Migrate to structure v2 and declare a block kind

[AStaroverov]

What

Brings samples-and-data onto the current canonical block layout and gives it the now-mandatory kind, whose init-params contract is what a project template supplies to seed a new instance.

Structure v2 + SDK upgrade

block-tools structure refresh output: block-tools 2.14.0, model/ui-vue 1.82.x, workflow-tengo 6.8.2, tengo-builder 4.0.23. Software packages move from pl-pkg to block-tools software build; build scripts move to the PL_BUILD_* channel scheme; CI moves to the hz-ubuntu-dind runner.

The kind and its init-params contract

The contract is the study setup a template carries — the metadata columns the study collects, the name of the sample column, how its datasets are configured — plus whichever of its data can be resolved from where the block lands.

Either the whole study travels or none of its data does. Block state is one connected thing: datasets key their files by sample or by group, sample groups and multiplexing rules name those samples, metadata values are keyed by them, and args holds the pieces to each other. So:

• every file a storage reference (index:// names a {storageId, path}) → the state goes as it stands;
• any file a local upload (a machine-local path signed with the installation's own secret) → only the setup goes, and the new project imports its own data.

Carrying part of it would mean picking which invariant to break — in particular validateDatasets, which requires as many sample groups as file groups.

metadataUploadHandle is deliberately outside the contract: it is not a link to the metadata table but scaffolding for one import dialog, cleared as soon as the parsed values land in metadata.

The dataset and metadata types move into the kind package and are re-exported from the model, so every existing import keeps resolving. The projection lives in model/src/template_params.ts as the exported deriveTemplateParams.

Two fixes the upgrade forced

• TreeNodeAccessor.resolveAny was removed from the SDK; the metadataFile output now uses traverse, its alias.
• @platforma-sdk/model 1.82.0 depends on pl-model-common 1.48.0 while the catalog range resolved the kind's direct dependency to 1.47.3. PlId is branded there, so two copies gave the model two incompatible PlId types. The catalog is now pinned to the version the SDK uses.

Verification

• turbo run build — 13/13 green; pnpm install --frozen-lockfile clean.
• The projection checked against built output: storage-only project carries every field unchanged; one local file anywhere reduces every dataset to its setup and drops roster, values and preprocess queues; an unset file slot does not block the transfer; a project with no datasets travels. validateDatasets' invariant holds on every outcome, and the kind's parser accepts what the projection emits.
• The kind's parser rejects 13 classes of malformed input (non-object, array, unknown content.type, bad valueType, non-string roster entries, …).
• collectDatasetHandles is exhaustive over DSContent — verified by removing a case and getting TS2345 ... not assignable to parameter of type 'never'.

Not run: the block's integration tests, which need a live backend on PL_ADDRESS. BlockData's shape is unchanged, so test/src/wf.test.ts should pass as is — assumption, not a check.

Before merge

Commit 22891f1 ("pin SDK deps to local monorepo builds") was the temporary file: overrides needed while @platforma-sdk/block-kind was unpublished. It is published now (1.1.0) and 58d8a58 already removed the overrides — the earlier commit is left in history only as the record.

Greptile Summary

The PR migrates the block to structure v2, upgrades its SDK and software-build tooling, and introduces a block-kind contract used to initialize instances from project templates.

• Block kind — the versioned runtime identity and initialization contract for the block; added as a new kind package and connected to both the data model and block model.
• BlockParams — optional initialization fields used to seed a block; added with datasets, metadata, sample mappings, and preprocessing queues.
• DSAny / DSContent — the dataset envelope and discriminated union of supported dataset content; moved from the model into the kind package and re-exported for compatibility.
• MTColumn — a metadata-column definition and its sample-keyed values; moved into the kind package and included in template projection.
• ImportFileHandle — a reference to either portable indexed storage or an installation-local upload; now used by the kind parser and template-portability projection.
• deriveTemplateParams — the projection from current block state to template initialization parameters; added to preserve complete portable studies or strip data when a dataset contains a local upload.
• DataModelBuilder / BlockModelV3 — model construction APIs; upgraded to register the new kind and initialize block state from parsed parameters.
• PL_BUILD channel variables — build channel, variant, and location configuration; replace the former PL_PKG_DEV build flow for local and release builds.

Confidence Score: 4/5

The PR is not yet safe to merge because templates can still restore installation-local preprocessing handles on a destination where they cannot resolve.

The template projection checks portability only inside datasets, then copies both preprocessing queues unchanged; destination initialization feeds those handles into prerun imports, leaving the previously reported portability failure reachable.

Files Needing Attention: model/src/template_params.ts

Important Files Changed

Filename	Overview
kind/src/types.ts	Defines the new block initialization contract and relocates the shared dataset and metadata types into the kind package.
kind/src/params.ts	Adds field-level runtime validation for initialization parameters, including dataset discriminators and file-handle forms.
model/src/data_model.ts	Registers the block kind and initializes each persisted field from optional template parameters with existing defaults.
model/src/template_params.ts	Adds template-state projection, but its dataset-only portability gate still allows local preprocessing handles to reach destination blocks.
model/src/index.ts	Registers the kind and template projection, adopts the upgraded model API, and replaces the removed resource-resolution alias.
package.json	Replaces legacy package-development build variables with structure-v2 build channel, variant, and location scripts.
.github/workflows/build.yaml	Moves CI to Node 22 and the DinD runner while separating local development and release build scripts.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Current block state] --> B[deriveTemplateParams]
  B --> C{All dataset handles portable?}
  C -->|Yes| D[Copy datasets, metadata, samples, and preprocessing queues]
  C -->|No| E[Keep dataset setup and clear sample/group data]
  D --> F[Kind parser validates params]
  E --> F
  F --> G[Data model initializes destination block]
  G --> H[Prerun imports queued preprocessing handles]

Loading

_{Reviews (2): Last reviewed commit: "refactor: take the array guard from es-t..." | Re-trigger Greptile}

Context used:

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

[greptile-apps]

Preprocessing handles bypass portability check

When the datasets are portable or empty but either preprocessing queue still contains a local upload handle, deriveTemplateParams copies that handle into the template because its portability check examines only dataset contents. The destination block restores the queue and attempts to import the installation-local handle during prerun, preventing the corresponding preprocessing outputs from resolving.

Prompt To Fix With AI

This is a comment left during a code review.
Path: model/src/template_params.ts
Line: 27-28

Comment:
**Preprocessing handles bypass portability check**

When the datasets are portable or empty but either preprocessing queue still contains a local upload handle, `deriveTemplateParams` copies that handle into the template because its portability check examines only dataset contents. The destination block restores the queue and attempts to import the installation-local handle during prerun, preventing the corresponding preprocessing outputs from resolving.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.