@platforma-sdk/model 1.81.0 → 1.82.0

package/src/block_storage_callbacks.ts

@@ -25,7 +25,12 @@ import {
 } from "./block_storage";
 import type { PluginHandle } from "./plugin_handle";
 
-import { stringifyJson, type StringifiedJson } from "@milaboratories/pl-model-common";
+import {
+  stringifyJson,
+  expandTemplateRefs,
+  relocateBlockIds,
+  type StringifiedJson,
+} from "@milaboratories/pl-model-common";
 import type { DataVersioned, TransferRecord } from "./block_migrations";
 import type { StorageDebugView } from "@milaboratories/pl-model-middle-layer";
 
@@ -237,7 +242,20 @@ export function migrateStorage(
  * @throws If initialDataFn or createPluginData throws
  */
 export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {
-  const blockDefault = hooks.getDefaultBlockData();
+  return assembleStorage(hooks.getDefaultBlockData(), hooks);
+}
+
+/**
+ * Wraps freshly created block data and freshly created plugin data into storage.
+ *
+ * Shared by the two ways a block's first storage comes into being — from defaults
+ * and from template params. Only the block's own data differs between them:
+ * plugins have no params channel, so they are always created at their defaults.
+ */
+function assembleStorage(
+  blockData: DataVersioned<unknown>,
+  hooks: Omit<InitialStorageHooks, "getDefaultBlockData">,
+): StringifiedJson<BlockStorage> {
   const pluginRegistry = hooks.getPluginRegistry();
 
   const plugins: Record<PluginHandle, VersionedData<unknown>> = {};
@@ -248,14 +266,238 @@ export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJso
 
   const storage: BlockStorage = {
     [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
-    __dataVersion: blockDefault.version,
-    __data: blockDefault.data,
+    __dataVersion: blockData.version,
+    __data: blockData.data,
     __pluginRegistry: pluginRegistry,
     __plugins: plugins,
   };
   return stringifyJson(storage);
 }
 
+/** Dependencies for creating storage from a template entry's params. */
+export interface ParamsStorageHooks extends Omit<InitialStorageHooks, "getDefaultBlockData"> {
+  /** The block's init factory, called with the entry's params. */
+  getBlockDataFromParams: (params: unknown) => DataVersioned<unknown>;
+  /**
+   * The kind's runtime params check. Applied before the factory sees anything, and its
+   * output is what the factory gets.
+   */
+  parseInitializationParams: (value: unknown) => unknown;
+}
+
+/** Result of checking params against their kind: the params to use, or why they lost. */
+export type TemplateParamsValidationResult =
+  | { error: string }
+  | { error?: undefined; value: unknown };
+
+/**
+ * Check params against their kind's declared shape.
+ *
+ * The kind owns this rather than the block because the params contract belongs to the
+ * kind: many block versions implement one kind, and a per-block check would let them
+ * drift from each other and from the type.
+ *
+ * A parser rejects by throwing and accepts by returning the params to use, so its
+ * output — not the input — is what flows onward. That is what lets a kind strip keys
+ * it does not declare, which is the difference between a typo being ignored and a typo
+ * being reported.
+ *
+ * Every kind declares a parser, so every set of params that reaches here is checked;
+ * there is no pass-through path.
+ *
+ * @param value The params to check, references already in live form
+ * @param parseInitializationParams The kind's parser
+ */
+export function validateTemplateParams(
+  value: unknown,
+  parseInitializationParams: (value: unknown) => unknown,
+): TemplateParamsValidationResult {
+  try {
+    return { value: parseInitializationParams(value) };
+  } catch (e) {
+    // A rejection is an expected outcome for a hand-written file, so it is reported,
+    // not thrown.
+    return { error: `params do not match this block's kind: ${describeRejection(e)}` };
+  }
+}
+
+/** One `{ path, message }` entry of a schema library's error. */
+type IssueLike = { path?: unknown; message?: unknown };
+
+/**
+ * Render whatever a parser threw as one readable line.
+ *
+ * An error carrying an `issues` array is unpacked rather than printed: that is the
+ * shape zod (and several others) use, and its `message` is the whole issue list as
+ * JSON — technically complete and unreadable in a dialog. Duck-typed on purpose, since
+ * this package prescribes no schema library and takes no dependency on one; anything
+ * else falls back to its own message.
+ */
+function describeRejection(e: unknown): string {
+  const issues = (e as { issues?: unknown }).issues;
+  if (!Array.isArray(issues) || issues.length === 0) return messageOf(e);
+
+  return issues
+    .map((issue) => {
+      const { path, message } = issue as IssueLike;
+      const what = typeof message === "string" ? message : "is invalid";
+      const where = Array.isArray(path) ? formatPath(path) : "";
+      return where === "" ? what : `${where}: ${what}`;
+    })
+    .join("; ");
+}
+
+/** `["numbers", 0]` → `numbers[0]` — how the params are written, not how they parse. */
+function formatPath(path: readonly unknown[]): string {
+  return path.reduce<string>((acc, segment) => {
+    if (typeof segment === "number") return `${acc}[${segment}]`;
+    return acc === "" ? String(segment) : `${acc}.${String(segment)}`;
+  }, "");
+}
+
+/**
+ * Result of the `__pl_params_validate` callback.
+ *
+ * Carries no params back. The check is a pre-flight — its answer is "may this entry be
+ * applied", and the params that actually reach the block are produced by
+ * {@link createInitialStorageFromParams}, which parses again. One authoritative
+ * producer, rather than two values that could differ.
+ */
+export type InitializationParamsValidateCallbackResult = { error: string } | { error?: undefined };
+
+/**
+ * Check params that crossed into the model VM as text.
+ *
+ * The pre-flight entry point: a caller asks this before creating anything, once per
+ * template entry, so params a kind rejects are reported while there is still no
+ * project to half-build.
+ *
+ * The readable reference spelling is expanded here too, so what the kind checks is the shape it
+ * declared. The ids it sees are the file's own — no block exists yet — which is why a kind must
+ * not read meaning into a specific id.
+ *
+ * @param paramsJson The entry's params as JSON string
+ * @param parseInitializationParams The kind's parser
+ */
+export function validateTemplateParamsJson(
+  paramsJson: string,
+  parseInitializationParams: (value: unknown) => unknown,
+): InitializationParamsValidateCallbackResult {
+  let params: unknown;
+  try {
+    params = JSON.parse(paramsJson);
+  } catch (e) {
+    return { error: `params are not valid JSON: ${messageOf(e)}` };
+  }
+
+  // Expanded before the kind sees anything, or a hand-written file would be rejected by every
+  // kind that declares a reference: `{ block, name }` is not a `PlRef` and no contract accepts
+  // one. Expansion needs nothing but the params, so this stays a two-argument check — the ids
+  // are not known yet and are not needed to answer the question this asks.
+  const result = validateTemplateParams(expandTemplateRefs(params), parseInitializationParams);
+  if (result.error !== undefined) return { error: result.error };
+  return {};
+}
+
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/**
+ * Result of building initial storage from params.
+ * Returned by the `__pl_storage_initialFromParams` callback.
+ */
+export type ParamsStorageResult =
+  | { error: string }
+  | { error?: undefined; storageJson: StringifiedJson<BlockStorage> };
+
+/**
+ * Creates complete initial storage for a block being created from template params.
+ *
+ * The inverse of {@link deriveTemplateParamsFromStorage}: that projects storage
+ * into params, this builds storage from them. The params are handed to the block's
+ * init factory, whose output is versioned and wrapped exactly as
+ * {@link createInitialStorage} wraps the defaults — so a block created from a
+ * template is indistinguishable from one created in the UI and then edited.
+ *
+ * **This is where a template's references become the block's own**, and it is the only place in
+ * a template's life where a reference is recognized at all. Params travel from the file
+ * untouched — the engine carrying them neither marks a reference nor reads one, because
+ * recognizing one means knowing the reference system, and that knowledge is here.
+ *
+ * Two things happen, in this order. The readable spelling a person may have written
+ * (`{ block, name }`) is expanded into the `PlRef` it stands for. Then every reference naming
+ * an entry that has a block is repointed at it: `blockIds` maps each template-local entry id to
+ * the block id it was given, and an id it does not name is left alone, which is how a reference
+ * to an entry created later ends up naming nothing rather than naming the wrong block.
+ *
+ * Relocation happens before the kind's parser and before the factory, so both see the ids the
+ * block will actually hold. It is one step of this function rather than a callback of its own
+ * precisely because nothing else wants its result: every VM call re-instantiates the runtime
+ * and re-evaluates the whole model bundle, so a separate call would parse the block twice per
+ * entry to produce a value only the next line reads.
+ *
+ * Params arrive as JSON text because this runs across the model-VM boundary, where
+ * only strings pass. Anything the factory rejects is returned as an error rather
+ * than thrown: applying a hand-written template is expected to surface bad params,
+ * and the applier reports every entry's problem in one pass.
+ *
+ * @param paramsJson - The entry's params as JSON string, exactly as the file held them
+ * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object
+ * @param hooks - The block's init factory plus plugin creation
+ * @returns The storage to write, or why the params could not produce any
+ */
+export function createInitialStorageFromParams(
+  paramsJson: string,
+  blockIdsJson: string,
+  hooks: ParamsStorageHooks,
+): ParamsStorageResult {
+  let params: unknown;
+  try {
+    params = JSON.parse(paramsJson);
+  } catch (e) {
+    return { error: `params are not valid JSON: ${messageOf(e)}` };
+  }
+
+  // Read separately from the params, and reported separately, because the two fail for
+  // completely different reasons. Params are the file's and a bad one is the author's mistake;
+  // this argument is the caller's, so the only way it arrives unreadable is a caller that does
+  // not send it — a middle layer older than this block, which is a build to refresh rather than
+  // anything to fix in the template. Folding both into one message sent the reader to the file.
+  let blockIds: Map<string, string>;
+  try {
+    blockIds = new Map(Object.entries(JSON.parse(blockIdsJson) as Record<string, string>));
+  } catch (e) {
+    return {
+      error:
+        `this block was not told which blocks the template's references should point at ` +
+        `(${messageOf(e)}). The application applying the template is older than the block; ` +
+        `rebuild or update it.`,
+    };
+  }
+
+  try {
+    // Spelling first, ids second. Expansion turns `{ block, name }` into a `PlRef` naming an
+    // ENTRY, which is exactly what relocation then repoints — so both spellings reach the
+    // block through the same step and cannot diverge in how they behave.
+    params = relocateBlockIds(expandTemplateRefs(params), blockIds);
+  } catch (e) {
+    return { error: `this entry's references could not be relocated: ${messageOf(e)}` };
+  }
+
+  // Checked here too, not only in the caller's pre-flight pass. The pre-flight is
+  // about reporting every bad entry before anything is created; this is about the
+  // factory never being handed a value the kind rejects, whichever path got here.
+  const checked = validateTemplateParams(params, hooks.parseInitializationParams);
+  if (checked.error !== undefined) return { error: checked.error };
+
+  try {
+    return { storageJson: assembleStorage(hooks.getBlockDataFromParams(checked.value), hooks) };
+  } catch (e) {
+    return { error: `init() threw on the given params: ${messageOf(e)}` };
+  }
+}
+
 // =============================================================================
 // Args Derivation from Storage
 // =============================================================================
@@ -271,19 +513,19 @@ export type ArgsDeriveResult = { error: string } | { error?: undefined; value: u
  * This extracts data from storage and passes it to the block's args() function.
  *
  * @param storageJson - Storage as JSON string
- * @param argsFunction - The block's args derivation function
+ * @param deriveArgs - The block's args derivation function
  * @returns ArgsDeriveResult with derived args or error
  */
 export function deriveArgsFromStorage(
   storageJson: string,
-  argsFunction: (data: unknown) => unknown,
+  deriveArgs: (data: unknown) => unknown,
 ): ArgsDeriveResult {
   // Extract data from storage
   const { data } = normalizeStorage(storageJson);
 
   // Call the args function with extracted data
   try {
-    const result = argsFunction(data);
+    const result = deriveArgs(data);
     return { value: result };
   } catch (e) {
     const errorMsg = e instanceof Error ? e.message : String(e);
@@ -293,25 +535,25 @@ export function deriveArgsFromStorage(
 
 /**
  * Derives prerunArgs from storage.
- * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.
+ * Uses derivePrerunArgs if provided, otherwise falls back to deriveArgs.
  *
  * @param storageJson - Storage as JSON string
- * @param argsFunction - The block's args derivation function (fallback)
- * @param prerunArgsFunction - Optional prerun args derivation function
+ * @param deriveArgs - The block's args derivation function (fallback)
+ * @param derivePrerunArgs - Optional prerun args derivation function
  * @returns ArgsDeriveResult with derived prerunArgs or error
  */
 export function derivePrerunArgsFromStorage(
   storageJson: string,
-  argsFunction: (data: unknown) => unknown,
-  prerunArgsFunction?: (data: unknown) => unknown,
+  deriveArgs: (data: unknown) => unknown,
+  derivePrerunArgs?: (data: unknown) => unknown,
 ): ArgsDeriveResult {
   // Extract data from storage
   const { data } = normalizeStorage(storageJson);
 
   // Try prerunArgs function first if available
-  if (prerunArgsFunction) {
+  if (derivePrerunArgs) {
     try {
-      const result = prerunArgsFunction(data);
+      const result = derivePrerunArgs(data);
       return { value: result };
     } catch (e) {
       const errorMsg = e instanceof Error ? e.message : String(e);
@@ -321,7 +563,7 @@ export function derivePrerunArgsFromStorage(
 
   // Fall back to args function
   try {
-    const result = argsFunction(data);
+    const result = deriveArgs(data);
     return { value: result };
   } catch (e) {
     const errorMsg = e instanceof Error ? e.message : String(e);
@@ -329,5 +571,42 @@ export function derivePrerunArgsFromStorage(
   }
 }
 
+// =============================================================================
+// Template Entry Derivation from Storage
+// =============================================================================
+
+/**
+ * Derives this block's template-entry params from storage.
+ *
+ * The inverse of the data model's `init`: `init` turns `params` into data, this
+ * turns data back into the params that would recreate it.
+ *
+ * The lambda returns ordinary live params — references as `PlRef`s, column identifiers as they
+ * are stored — and that is exactly what gets written. Nothing is marked, normalized or
+ * rewritten on the way out: a template holds what the block holds. Repointing those references
+ * at another project is the business of {@link createInitialStorageFromParams}, on the way back
+ * in, where the ids to point at are known.
+ *
+ * Every block declares the lambda, so every export produces params; a block with
+ * nothing worth restoring returns `{}` rather than declining.
+ *
+ * @param storageJson - Storage as JSON string
+ * @param deriveTemplateParams - The block's templateParams lambda
+ * @returns ArgsDeriveResult holding the params exactly as the block projected them
+ */
+export function deriveTemplateParamsFromStorage<TP extends (data: unknown) => unknown>(
+  storageJson: string,
+  deriveTemplateParams: TP,
+): ArgsDeriveResult {
+  const { data } = normalizeStorage(storageJson);
+
+  try {
+    return { value: deriveTemplateParams(data) };
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    return { error: `templateParams() threw: ${errorMsg}` };
+  }
+}
+
 // Export discriminator key and schema version for external checks
 export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };

package/src/block_storage_facade.ts

@@ -82,6 +82,9 @@ export const BlockStorageFacadeCallbacks = {
   ArgsDerive: "__pl_args_derive",
   PrerunArgsDerive: "__pl_prerunArgs_derive",
   StorageInitial: "__pl_storage_initial",
+  InitializationParamsDerive: "__pl_initializationParams_derive",
+  StorageInitialFromParams: "__pl_storage_initialFromParams",
+  InitializationParamsValidate: "__pl_initializationParams_validate",
 } as const;
 
 /**
@@ -189,6 +192,98 @@ export interface BlockStorageFacade {
    * @returns Initial storage as JSON string
    */
   [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;
+
+  /**
+   * Derive this block's template entry params from storage.
+   * Called when exporting the project as a template.
+   *
+   * Every V3 block declares `.templateParams()` — the model does not build without
+   * it — so every export produces params. A block whose state carries nothing worth
+   * restoring returns `{}`, which is written out and used as-is by init.
+   *
+   * The returned params are written out exactly as they come back, references included: the
+   * template engine carrying them recognizes nothing in there, and the block that receives
+   * them on the way back in is what repoints them. The caller supplies everything else in the
+   * entry — `id`, `kind` — so the lambda cannot set them.
+   *
+   * @param storageJson - Storage as JSON string
+   * @returns Either an error, or the params to write
+   */
+  [BlockStorageFacadeCallbacks.InitializationParamsDerive]: (
+    storageJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; value: unknown };
+
+  /**
+   * Get initial storage JSON for a block created from params.
+   * Called when applying a template, once per entry that carries `params`.
+   *
+   * The mirror image of {@link BlockStorageFacadeCallbacks.InitializationParamsDerive}:
+   * that one turns storage into params, this one turns params into storage. Every
+   * applied entry comes through here, including one whose file omitted `params` —
+   * an omitted key is read as `{}` and checked like any other value, so no entry
+   * reaches a block without passing its kind's contract.
+   * {@link BlockStorageFacadeCallbacks.StorageInitial} stays the UI-creation path,
+   * where there are genuinely no params.
+   *
+   * Separate from `StorageInitial` rather than an optional argument to it,
+   * deliberately: a block bundled with an older SDK does not register this
+   * callback at all, so the caller sees it missing and can say so. Widening
+   * `StorageInitial` would instead have that block silently ignore the params and
+   * produce a default-initialized block that looks successfully applied.
+   *
+   * The params arrive as ordinary live params — references are `PlRef`s, already
+   * pointing at the ids the target project just assigned. Resolution happens in
+   * the engine, before this call, so a block's init factory never handles a
+   * template-local reference.
+   *
+   * Errors are returned, not thrown: a factory rejecting params it cannot use is
+   * an expected outcome for a hand-written template file, and every entry's
+   * problem is reported together.
+   *
+   * **Also where the entry's references are pointed at this project.** Params reach here
+   * exactly as the file held them: nothing between the block that exported them and this call
+   * marks a reference, reads one, or rewrites one, because recognizing one means knowing the
+   * reference system and this bundle is where that knowledge lives. `blockIdsJson` maps each
+   * template-local entry id to the block id it was given, holding the entries created so far —
+   * so an id it does not name is left alone, and a reference to an entry created later names
+   * nothing rather than naming the wrong block.
+   *
+   * Relocating and initializing are one call rather than two because every call
+   * re-instantiates the runtime and re-evaluates the whole model bundle: splitting them would
+   * parse the block twice per entry to produce an intermediate only the second half reads.
+   *
+   * @param paramsJson - The entry's params as JSON string, as the file held them
+   * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object
+   * @returns Either an error, or the initial storage as JSON string
+   */
+  [BlockStorageFacadeCallbacks.StorageInitialFromParams]: (
+    paramsJson: StringifiedJson,
+    blockIdsJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; storageJson: StringifiedJson };
+
+  /**
+   * Check params against this block's kind, creating nothing.
+   *
+   * Called once per entry before a template is applied, so params a kind rejects are
+   * reported against the entry that carries them while there is still no project — the
+   * same reason references and ids are checked before construction starts. Applying
+   * without this call is safe but worse: `StorageInitialFromParams` runs the same check
+   * and refuses, by which point earlier entries have already been created.
+   *
+   * A pass carries nothing back but its own absence of error: every kind declares a
+   * parser, so a pass means the params were checked against the contract, not merely
+   * that they were valid JSON.
+   *
+   * Reference ids inside the params may be placeholders at this point: the check runs
+   * before blocks exist, so what is verified is the shape of the params, not what they
+   * point at.
+   *
+   * @param paramsJson The entry's params as JSON string
+   * @returns Why the params were rejected, or nothing
+   */
+  [BlockStorageFacadeCallbacks.InitializationParamsValidate]: (
+    paramsJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined };
 }
 
 /** Register all facade callbacks at once. Ensures all required callbacks are provided. */

package/src/components/PlDataTable/createPlDataTable/utils.test.ts

@@ -207,6 +207,37 @@ describe("evaluateRules", () => {
     expect(result.get(gid("b"))?.priority).toBe(50);
   });
 
+  test("a rule matching zero columns does not suppress the other rules", () => {
+    const rules: ColumnOrderRule[] = [
+      { match: { name: "^nothing-matches-this$" }, priority: 999 },
+      { match: { name: "^alpha$" }, priority: 100 },
+      { match: { name: "^beta$" }, priority: 50 },
+    ];
+    const columns = [makeLazyColumn("a", { name: "alpha" }), makeLazyColumn("b", { name: "beta" })];
+
+    const result = evaluateRules(rules, columns);
+
+    expect(result.get(gid("a"))?.priority).toBe(100);
+    expect(result.get(gid("b"))?.priority).toBe(50);
+    expect(result.size).toBe(2);
+  });
+
+  test("rules matching zero columns are skipped regardless of their position", () => {
+    const rules: ColumnVisibilityRule[] = [
+      { match: { name: "^ghost-a$" }, visibility: "hidden" },
+      { match: { name: "^note$" }, visibility: "hidden" },
+      { match: { name: "^ghost-b$" }, visibility: "hidden" },
+      { match: { name: "^score$" }, visibility: "optional" },
+      { match: { name: "^ghost-c$" }, visibility: "hidden" },
+    ];
+    const columns = [makeLazyColumn("n", { name: "note" }), makeLazyColumn("s", { name: "score" })];
+
+    const result = evaluateRules(rules, columns);
+
+    expect(result.get(gid("n"))?.visibility).toBe("hidden");
+    expect(result.get(gid("s"))?.visibility).toBe("optional");
+  });
+
   test("dedupes columns by id before building spec frame (no duplicate-key crash)", () => {
     const rules: ColumnVisibilityRule[] = [{ match: { name: "^dup$" }, visibility: "hidden" }];
     const dup = makeLazyColumn("d", { name: "dup" });

package/src/components/PlDataTable/createPlDataTable/utils.ts

@@ -88,7 +88,10 @@ export function evaluateRules<R extends { match: ColumnSelector }>(
     const baseCollection = ColumnsCollection([{ columns: baseColumns, isFinal: true }]);
     for (const rule of selectorRules) {
       const hitIds = baseCollection.filter({ include: rule.match }).getColumnIds();
-      if (hitIds.length === 0) return result;
+      // A rule matching nothing simply contributes no entries — it must not
+      // discard the rules evaluated alongside it. The lookup below is
+      // null-safe, so leaving this rule out of the map is enough.
+      if (hitIds.length === 0) continue;
       selectorHitsByRule.set(rule, new Set(hitIds.map((id) => extractPObjectId(id))));
     }
   }

package/src/kind_reference.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, expectTypeOf, test } from "vitest";
+import type { BlockConfigContainer, BlockKindReference } from "@milaboratories/pl-model-common";
+import {
+  PROJECT_TEMPLATE_SCHEMA_V1,
+  parseProjectTemplateV1,
+  kindReferenceToSelectorReference,
+} from "@milaboratories/pl-model-common";
+import { extractConfig } from "./bconfig/normalization";
+import { BlockModelV3 } from "./block_model";
+import { DataModelBuilder } from "./block_migrations";
+import { defineBlockKind } from "@platforma-sdk/block-kind";
+
+// Template export needs one fact to hold at runtime: the kind reference a block
+// declared at build time is still readable from its config, and reaches a
+// template entry unchanged.
+//
+// No new code is needed for that read — `BlockConfigContainer.kind` is already
+// typed `BlockKindReference | undefined`, so the middle layer's read is the
+// property access `bp.info.config.kind`, and the widen to an entry's selector
+// form already exists. What did not exist is proof that the path holds end to
+// end, which is what this suite is: bake -> read -> widen -> entry, inside one
+// package, with no backend.
+
+type Params = { label: string };
+type BlockData = { label: string };
+
+const KIND_NAME = "@platforma-open/milaboratories.demo.kind";
+const KIND_VERSION = "1.4.2";
+const KIND_REF = `${KIND_NAME}@${KIND_VERSION}`;
+
+const kind = defineBlockKind<Params>({
+  name: KIND_NAME,
+  version: KIND_VERSION,
+  parseInitializationParams: (value) => value as Params,
+});
+
+const dataModel = new DataModelBuilder({ kind })
+  .from<BlockData>("v1")
+  .init(({ params }) => ({ label: params?.label ?? "" }));
+
+/**
+ * The config container `build-model` serializes into model.json.
+ *
+ * `done()` returns it whenever the model is not running in a UI — `isInUI()`
+ * checks for a `platforma` global, absent under vitest — which is exactly the
+ * path the build takes.
+ */
+function containerOf(model: unknown): BlockConfigContainer {
+  return (model as { config: BlockConfigContainer }).config;
+}
+
+const kindfulContainer = () =>
+  containerOf(
+    BlockModelV3.create({ dataModel, kind })
+      .args((data) => ({ label: data.label }))
+      .templateParams((data) => ({ label: data.label }))
+      .done(),
+  );
+
+describe("reading the kind reference back at runtime", () => {
+  test("done() bakes the declared kind at the container level", () => {
+    // Beside `code`, orthogonal to the render envelope — a future v5 envelope
+    // would not move it.
+    expect(kindfulContainer().kind).toBe(KIND_REF);
+  });
+
+  test("the NORMALIZED config does not carry it — the container is the read point", () => {
+    // extractConfig normalizes the render envelope and returns only envelope
+    // fields, so the `cfg` every getBlockPackInfo caller holds is kind-blind by
+    // construction (lib/node/pl-middle-layer/src/middle_layer/util.ts). An
+    // exporter that goes looking there finds nothing and must read
+    // `info.config.kind` instead. Pinned so that stays true, or fails loudly.
+    expect("kind" in extractConfig(kindfulContainer())).toBe(false);
+  });
+
+  test("the authoring API can no longer produce a kind-less block", () => {
+    const kindlessDataModel = new DataModelBuilder().from<BlockData>("v1").init(() => ({
+      label: "",
+    }));
+
+    // The kind-less `create(dataModel)` overload is gone: a kind is mandatory, so there
+    // is no longer a way to author a block whose container carries no kind reference.
+    // @ts-expect-error - create takes { dataModel, kind }; a bare DataModel is not it
+    expect(() => BlockModelV3.create(kindlessDataModel)).toThrow();
+  });
+
+  test("the READ side stays optional — already-published blocks carry no kind", () => {
+    // `BlockConfigContainer.kind` is `BlockKindReference | undefined` and must stay that
+    // way: every block published before kinds existed is in that state, and the middle
+    // layer reads those configs. What the exporter should DO with such a block is
+    // decided — a template entry's `kind` is required, so there is no legal entry to
+    // write and the export fails naming the block (`template_serializer.ts`).
+    const container = kindfulContainer();
+
+    expect(container.kind).toBe(KIND_REF);
+    expectTypeOf(container.kind).toEqualTypeOf<BlockKindReference | undefined>();
+  });
+});
+
+describe("the reference as a template entry's kind", () => {
+  test("it widens to the exact tier, string unchanged", () => {
+    // An entry's kind is the exact version the block implements, `{name}@X.Y.Z`,
+    // read from the model's embedded kind reference. Widening changes the brand,
+    // not the string — export never loosens to a `~` or `^` tier.
+    expect(kindReferenceToSelectorReference(kindfulContainer().kind!)).toBe(KIND_REF);
+  });
+
+  test("the org-scoped name survives the split", () => {
+    // The kind name itself starts with `@`, so splitting on the FIRST `@` would
+    // truncate it to the empty name. block_kind_ref.ts owns that rule by
+    // splitting on the last `@`; this pins that a reference a real block
+    // declares round-trips through it intact.
+    const widened = kindReferenceToSelectorReference(kindfulContainer().kind!);
+    expect(widened.startsWith("@platforma-open/")).toBe(true);
+  });
+
+  test("the widened reference is accepted as a template-v1 entry's kind", () => {
+    const blockId = "3f1c2b7a-0000-4000-8000-000000000001";
+
+    const [entry] = parseProjectTemplateV1({
+      schema: PROJECT_TEMPLATE_SCHEMA_V1,
+      blocks: [{ id: blockId, kind: kindReferenceToSelectorReference(kindfulContainer().kind!) }],
+    }).blocks;
+
+    // The whole path, end to end: what the block declared is what the file
+    // carries. `id` is the block's project-local UUID, reused verbatim, and `params` is the
+    // empty mapping the parser settles an omitted key to.
+    expect(entry).toEqual({ id: blockId, kind: KIND_REF, params: {} });
+
+    // No `block` override: a block implements exactly one kind version, so
+    // export has nothing to pin.
+    expect(entry.block).toBeUndefined();
+  });
+});