Skip to content

Add the mandatory block kind and its params contract - #43

Merged
AStaroverov merged 8 commits into
mainfrom
feat/project-template-migration
Aug 19, 2026
Merged

Add the mandatory block kind and its params contract#43
AStaroverov merged 8 commits into
mainfrom
feat/project-template-migration

Conversation

@AStaroverov

@AStaroverov AStaroverov commented Aug 10, 2026

Copy link
Copy Markdown
Collaborator

Scaffold kind/ and let structure refresh wire it: the facade gains a direct kind devDep, the model a kind dependency. BlockParams is inputAnchor plus annotationSpecUi, both optional — a block created from the UI has neither, and export has to describe that state rather than fail on it.

Both fields are stored exactly as they arrive, so init and templateParams are identities. inputAnchor stays the ColumnUniversalId the block already holds; its block id, and every block id inside the annotation filters' column ids, is rewritten by the SDK codec on export and resolved again on apply.

parseTemplateParams checks the envelope and the anchor and stops at the shape of a filter step: a step the user has not finished filling in is ordinary live state, and the projection hands live state back untouched, so anything stricter would make a block export a file its own kind refuses to apply.

Greptile Summary

The PR introduces a mandatory block kind and connects its initialization contract to model initialization and template export, while updating SDK dependencies and column APIs.

  • BlockParams — the block initialization contract containing optional inputAnchor and annotationSpecUi; newly defined by the kind package.
  • parseInitializationParams — validates the initialization envelope, column anchor, annotation metadata, and step-level shape; now rejects non-string defaultValue values.
  • kind — the block identity and parameter contract produced by defineBlockKind; now supplied to both DataModelBuilder and BlockModelV3.
  • annotationSpecUi — editable annotation configuration stored in block state; now accepted during initialization and returned during template export.
  • templateParams — the template projection for reconstructing a block; now exports inputAnchor and annotationSpecUi.
  • splitByAxes — the current column-splitting API; replaces expandByPartition for overlap and sample tables.
  • hasReachableData and getData() — the current reachability guard and data accessor; replace getLeafColumnData.
  • Package and workflow configuration now includes the kind workspace, updated Platforma SDK versions, clean-install-safe dependency resolution, and mandatory block-package changeset enforcement.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the parser now rejects invalid non-string default values, and the unavailable local dependency overrides have been removed without leaving external file references.

Important Files Changed

Filename Overview
kind/src/index.ts Defines the block kind, initialization parameter types, and runtime validation; the previously reported defaultValue contract gap is fixed.
model/src/dataModel.ts Registers the kind with the data model and initializes state from optional template parameters.
model/src/index.ts Registers the kind with the block model, adds template parameter projection, and migrates column operations to current SDK APIs.
model/src/types.ts Re-exports annotation parameter types from the kind package so persisted state and initialization share one contract.
package.json Removes external local-tarball overrides, resolving the previously reported standalone-install failure.
pnpm-workspace.yaml Adds the kind workspace and updates the shared dependency catalog required by the new contract.
.github/workflows/build.yaml Requires pull requests to include a changeset bump for the published block package.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  T[Template parameters] --> P[parseInitializationParams]
  P --> K[Block kind contract]
  K --> I[Data model init]
  I --> S[Live block state]
  S --> E[templateParams projection]
  E --> T
Loading

Reviews (2): Last reviewed commit: "fix: validate defaultValue in annotation..." | Re-trigger Greptile

Context used:

  • Context used - Terms is a types in codebase. Provide the list of ... (source)

Scaffold kind/ and let structure refresh wire it: the facade gains a direct
kind devDep, the model a kind dependency. BlockParams is inputAnchor plus
annotationSpecUi, both optional — a block created from the UI has neither,
and export has to describe that state rather than fail on it.

Both fields are stored exactly as they arrive, so init and templateParams
are identities. inputAnchor stays the ColumnUniversalId the block already
holds; its block id, and every block id inside the annotation filters'
column ids, is rewritten by the SDK codec on export and resolved again on
apply.

parseTemplateParams checks the envelope and the anchor and stops at the
shape of a filter step: a step the user has not finished filling in is
ordinary live state, and the projection hands live state back untouched,
so anything stricter would make a block export a file its own kind refuses
to apply.

Restore the Ver_2026_05_28 migration's plRefToUniversalId conversion, which
had been reduced to a no-op — without it a project stored at Ver_2026_04_14
migrates to a BlockData holding a PlRef where a ColumnUniversalId is
expected, and every anchor lookup fails.

Not mergeable as-is: pnpm.overrides points the SDK at local tarballs
because @platforma-sdk/block-kind and a kind-aware block-tools are not
published yet.
@AStaroverov
AStaroverov marked this pull request as draft August 10, 2026 11:52
Comment thread package.json Outdated
Comment thread kind/src/index.ts Outdated
Adds the changeset gate on the published `block` package. Tool output from
`block-tools structure refresh`; `structure check` is a fixpoint afterwards.
The kind's params slot is now `parseInitializationParams`, and the envelope
check it starts from ships as `assertParamsObject` — which also names what a
non-object was, so a quoting mistake in a template file reads as one.

Two deliberate loosenings on the params contract, both so that a parser is not
stricter than the states the block itself reaches:

- The key-set check is gone. A parser returns the params to use, so a field it
  never read is already dropped; refusing unknown keys meant the kind keeping a
  list of its own field names as strings, which nothing holds in step with the
  type. A contract from another version of the kind is guarded by the version in
  the entry's kind reference instead.
- The parser returns the two fields it read rather than the value it was handed.
  Returning the whole object type-checked only because the shape guard widens
  every field to `any`, which is the cast it replaced wearing a guard.

Model side, following the column API: `expandByPartition` is `splitByAxes` and
defaults its label resolver, and `getLeafColumnData` is gone in favour of the
`hasReachableData` guard, which narrows to the recipe that exposes `getData()`.
@AStaroverov
AStaroverov marked this pull request as ready for review August 19, 2026 09:27
@AStaroverov
AStaroverov merged commit e8f3480 into main Aug 19, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant