@platforma-sdk/model 1.81.1 → 1.83.0

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();
+  });
+});

package/src/render/api.ts

@@ -728,34 +728,6 @@ export class BlockRenderCtx<Args = unknown, Data = unknown> extends RenderCtxBas
   }
 }
 
-/** Render context for legacy v1/v2 blocks - provides backward compatibility */
-export class RenderCtxLegacy<Args = unknown, UiState = unknown> extends RenderCtxBase<
-  Args,
-  UiState
-> {
-  private argsCache?: { v: Args };
-
-  public get args(): Args {
-    if (this.argsCache === undefined) {
-      const raw = this.ctx.args;
-      const value = typeof raw === "function" ? raw() : raw;
-      this.argsCache = { v: JSON.parse(value) };
-    }
-    return this.argsCache.v;
-  }
-
-  private uiStateCache?: { v: UiState };
-
-  public get uiState(): UiState {
-    if (this.uiStateCache === undefined) {
-      const raw = this.ctx.uiState!;
-      const value = typeof raw === "function" ? raw() : raw;
-      this.uiStateCache = { v: value ? JSON.parse(value) : ({} as UiState) };
-    }
-    return this.uiStateCache.v;
-  }
-}
-
 /**
  * Render context for plugin output functions.
  * Reads plugin data from blockStorage and derives params from pre-wrapped input callbacks.
@@ -811,10 +783,6 @@ export type RenderFunction<Args = unknown, State = unknown, Ret = unknown> = (
   rCtx: BlockRenderCtx<Args, State>,
 ) => Ret;
 
-export type RenderFunctionLegacy<Args = unknown, State = unknown, Ret = unknown> = (
-  rCtx: RenderCtxLegacy<Args, State>,
-) => Ret;
-
 export type UnwrapFutureRef<K> =
   K extends FutureRef<infer T>
     ? T

package/src/template_init.test.ts

@@ -0,0 +1,413 @@
+import { describe, expect, test } from "vitest";
+import type { PlRef } from "@milaboratories/pl-model-common";
+import { createPlRef, stringifyJson } from "@milaboratories/pl-model-common";
+import type { PluginHandle } from "./plugin_handle";
+import type { PluginName } from "./block_storage";
+import { BLOCK_STORAGE_KEY, createBlockStorage, isBlockStorage } from "./block_storage";
+import {
+  createInitialStorage,
+  createInitialStorageFromParams,
+  deriveTemplateParamsFromStorage,
+  validateTemplateParams,
+  validateTemplateParamsJson,
+} from "./block_storage_callbacks";
+import { DataModelBuilder } from "./block_migrations";
+import { defineBlockKind } from "@platforma-sdk/block-kind";
+
+/**
+ * The apply half of the template contract: params in, storage out.
+ *
+ * `template_params.test.ts` covers the export direction. These cover the inverse,
+ * plus the one property that ties the two together — params that survive a round
+ * trip through storage.
+ */
+
+type Params = { sources?: PlRef[]; label: string };
+
+/**
+ * Deliberately permissive: these tests are about what the apply path does with params
+ * the kind already accepted, so the parser here only carries the shape through. The
+ * rejection behaviour is covered by the `validateTemplateParams` cases below, which
+ * supply their own strict parsers.
+ */
+const passThrough = (value: unknown) => value as Params;
+
+/**
+ * No entries created yet, so nothing to repoint.
+ *
+ * Relocation is the callback's other half and is covered where it lives — `relocateBlockIds`
+ * in `pl-model-common`. What these tests drive is the factory and the shape of the storage it
+ * produces, and an empty map keeps the params arriving exactly as written.
+ */
+const NO_IDS = JSON.stringify({});
+
+const kind = defineBlockKind<Params>({
+  name: "@platforma-open/milaboratories.demo.kind",
+  version: "1.0.0",
+  parseInitializationParams: passThrough,
+});
+
+type BlockData = { sources: PlRef[]; label: string; scratch: number };
+
+const dataModel = new DataModelBuilder({ kind }).from<BlockData>("v1").init(({ params }) => ({
+  sources: params?.sources ?? [],
+  label: params?.label ?? "",
+  scratch: 0,
+}));
+
+const upstream = "3f1c2b7a-0000-4000-8000-000000000001";
+
+/** Hooks for a block with no plugins — the common case. */
+const noPlugins = {
+  getPluginRegistry: () => ({}),
+  createPluginData: () => {
+    throw new Error("no plugins registered");
+  },
+};
+
+const fromParams = (params: unknown) =>
+  createInitialStorageFromParams(JSON.stringify(params), NO_IDS, {
+    getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+    parseInitializationParams: passThrough,
+    ...noPlugins,
+  });
+
+/** Storage the callback produced, parsed back. Fails the test if it errored. */
+function storageOf(result: ReturnType<typeof fromParams>) {
+  if (result.error !== undefined) throw new Error(`expected storage, got: ${result.error}`);
+  return JSON.parse(result.storageJson) as Record<string, unknown>;
+}
+
+describe("createInitialStorageFromParams", () => {
+  test("the block's init factory receives the entry's params", () => {
+    const storage = storageOf(fromParams({ label: "run 1" }));
+
+    expect(storage.__data).toEqual({ sources: [], label: "run 1", scratch: 0 });
+  });
+
+  test("references arrive as PlRefs and land in data untouched", () => {
+    // The engine resolves template-local references before this point, so what the
+    // factory sees is an ordinary live reference to a block that already exists.
+    const ref = createPlRef(upstream, "reads");
+    const storage = storageOf(fromParams({ label: "wired", sources: [ref] }));
+
+    expect((storage.__data as BlockData).sources).toEqual([ref]);
+  });
+
+  test("the result is well-formed storage at the current data version", () => {
+    const storage = storageOf(fromParams({ label: "x" }));
+
+    expect(isBlockStorage(storage)).toBe(true);
+    expect(storage[BLOCK_STORAGE_KEY]).toBeDefined();
+    expect(storage.__dataVersion).toBe(dataModel.version);
+  });
+
+  test("a block created from params is shaped exactly like one created from defaults", () => {
+    // Same envelope, only `__data` differs — which is what lets an applied block be
+    // read, migrated and edited by every path that never heard of templates.
+    const fromDefaults = JSON.parse(
+      createInitialStorage({
+        getDefaultBlockData: () => dataModel.getDefaultData(),
+        getPluginRegistry: noPlugins.getPluginRegistry,
+        createPluginData: noPlugins.createPluginData,
+      }),
+    ) as Record<string, unknown>;
+    const applied = storageOf(fromParams({ label: "x" }));
+
+    expect(Object.keys(applied).sort()).toEqual(Object.keys(fromDefaults).sort());
+    expect({ ...applied, __data: null }).toEqual({ ...fromDefaults, __data: null });
+  });
+
+  test("empty params are used as-is, not treated as absent", () => {
+    // An entry with `params: {}` says "initialize from nothing in particular";
+    // the factory's own fallbacks fill in, and the applier never substitutes
+    // defaults on the block's behalf.
+    expect(storageOf(fromParams({})).__data).toEqual({ sources: [], label: "", scratch: 0 });
+  });
+
+  test("params that are not valid JSON are reported", () => {
+    const result = createInitialStorageFromParams("{not json", NO_IDS, {
+      getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+      parseInitializationParams: passThrough,
+      ...noPlugins,
+    });
+
+    expect(result.error).toMatch(/params are not valid JSON/);
+  });
+
+  test("a factory that rejects the params is reported, not propagated", () => {
+    // The expected failure mode for a hand-written template file: params the block
+    // cannot make sense of. It must come back as a problem the applier can attach
+    // to an entry, not as a throw that aborts the whole apply.
+    const result = createInitialStorageFromParams(JSON.stringify({ label: "" }), NO_IDS, {
+      getBlockDataFromParams: () => {
+        throw new Error("label must not be empty");
+      },
+      parseInitializationParams: passThrough,
+      ...noPlugins,
+    });
+
+    expect(result).toEqual({ error: "init() threw on the given params: label must not be empty" });
+  });
+
+  test("plugins are created at their defaults, never from params", () => {
+    // Params belong to the block's kind; a plugin has no params channel, so it is
+    // initialized the same way whether the block came from a template or the UI.
+    const handle = "p1" as PluginHandle;
+    const result = createInitialStorageFromParams(JSON.stringify({ label: "x" }), NO_IDS, {
+      getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+      parseInitializationParams: passThrough,
+      getPluginRegistry: () => ({ [handle]: "demoPlugin" as PluginName }),
+      createPluginData: (h) => {
+        expect(h).toBe(handle);
+        return { version: "v1", data: { items: [] } };
+      },
+    });
+
+    expect(storageOf(result).__plugins).toEqual({
+      [handle]: { __dataVersion: "v1", __data: { items: [] } },
+    });
+  });
+});
+
+describe("DataModel.getDataFromParams", () => {
+  test("a factory that ignores params matches getDefaultData", () => {
+    const paramless = new DataModelBuilder().from<{ n: number }>("v1").init(() => ({ n: 7 }));
+
+    expect(paramless.getDataFromParams({ n: 99 })).toEqual(paramless.getDefaultData());
+  });
+
+  test("undefined params are what a factory sees from getDefaultData", () => {
+    // The two entry points must not diverge on the "no params" case: an entry
+    // without params goes through StorageInitial, and a factory written against
+    // `params?.x ?? default` has to behave identically either way.
+    expect(dataModel.getDataFromParams(undefined)).toEqual(dataModel.getDefaultData());
+  });
+});
+
+describe("params round trip", () => {
+  test("init then templateParams returns the params it started from", () => {
+    // The closest thing to an export→import round trip available without the engine: params
+    // → storage → params. It comes back byte-identical, references included — a template
+    // holds what the block holds, so the two ends of the trip have nothing to convert.
+    const params = { label: "run 1", sources: [createPlRef(upstream, "reads")] };
+
+    const storageJson = stringifyJson(
+      createBlockStorage(storageOf(fromParams(params)).__data as BlockData),
+    );
+    const derived = deriveTemplateParamsFromStorage(storageJson, (data) => {
+      const d = data as BlockData;
+      return { sources: d.sources, label: d.label };
+    });
+
+    expect(derived).toEqual({ value: params });
+  });
+});
+
+describe("validateTemplateParams", () => {
+  test("the parser's output is what flows on, not its input", () => {
+    // This is what makes a schema able to strip keys the kind does not declare, which
+    // is the difference between a typo being ignored and a typo being caught.
+    const result = validateTemplateParams({ label: "x", stray: 1 }, () => ({ label: "x" }));
+
+    expect(result).toEqual({ value: { label: "x" } });
+  });
+
+  test("there is no unchecked pass", () => {
+    // Every kind declares a parser, so the result carries no "was this checked" flag:
+    // a pass means the params were held to the contract. A parser is the only way a
+    // value gets through, and one that rejects everything is still a parser.
+    expect(
+      validateTemplateParams({ anything: true }, () => {
+        throw new Error("this kind takes no params");
+      }).error,
+    ).toMatch(/do not match this block's kind/);
+  });
+});
+
+describe("params reaching init", () => {
+  test("init sees what the parser returned", () => {
+    const storage = storageOf(
+      createInitialStorageFromParams(JSON.stringify({ label: "raw", stray: 1 }), NO_IDS, {
+        getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+        parseInitializationParams: () => ({ label: "parsed" }),
+        ...noPlugins,
+      }),
+    );
+
+    expect((storage.__data as BlockData).label).toBe("parsed");
+  });
+
+  test("params the kind rejects never reach init", () => {
+    // Checked here as well as in the caller's pre-flight: the pre-flight exists to
+    // report every bad entry before anything is created, this exists so the factory is
+    // never handed a value the kind refused, whichever path got here.
+    let reached = false;
+    const result = createInitialStorageFromParams(JSON.stringify({ label: "" }), NO_IDS, {
+      getBlockDataFromParams: (p) => {
+        reached = true;
+        return dataModel.getDataFromParams(p);
+      },
+      parseInitializationParams: () => {
+        throw new Error("label must not be empty");
+      },
+      ...noPlugins,
+    });
+
+    expect(reached).toBe(false);
+    expect(result.error).toMatch(/do not match this block's kind/);
+  });
+});
+
+describe("validateTemplateParamsJson", () => {
+  test("valid params against a real schema", () => {
+    expect(validateTemplateParamsJson(JSON.stringify({ n: 1 }), (v) => v)).toEqual({});
+  });
+
+  test("a rejection comes back as a message, not a throw", () => {
+    const result = validateTemplateParamsJson(JSON.stringify({}), () => {
+      throw new Error("n: Required");
+    });
+
+    expect(result.error).toContain("n: Required");
+  });
+
+  test("params that are not JSON are reported", () => {
+    expect(validateTemplateParamsJson("{oops", (v) => v).error).toMatch(/not valid JSON/);
+  });
+});
+
+describe("the kind carries the check", () => {
+  test("a kind's parser reaches the data model that declared it", () => {
+    // The threading that makes any of this work: the kind object is not kept, but the
+    // parser is lifted off it beside the kind reference, so `done()` can register it.
+    const parse = (v: unknown) => v as Params;
+    const checkedKind = defineBlockKind<Params>({
+      name: "@platforma-open/milaboratories.checked.kind",
+      version: "1.0.0",
+      parseInitializationParams: parse,
+    });
+    const model = new DataModelBuilder({ kind: checkedKind })
+      .from<BlockData>("v1")
+      .init(() => ({ sources: [], label: "", scratch: 0 }));
+
+    expect(model.templateParamsParser).toBe(parse);
+  });
+
+  test("a kind-less data model carries no parser — the plugin case", () => {
+    // The only remaining way this slot is empty. A BLOCK data model always has a kind,
+    // and a kind always supplies a parser; a PLUGIN data model is built with no kind at
+    // all, because a plugin has no params channel of its own. Such a model can no longer
+    // reach `BlockModelV3.create`, so nothing reads this as a block's parser.
+    const pluginDataModel = new DataModelBuilder()
+      .from<BlockData>("v1")
+      .init(() => ({ sources: [], label: "", scratch: 0 }));
+
+    expect(pluginDataModel.templateParamsParser).toBeUndefined();
+  });
+});
+
+describe("how a rejection reads", () => {
+  test("a schema library's issue list is unpacked, not dumped as JSON", () => {
+    // A zod error's own `message` is the entire issue array as JSON. Complete, and
+    // unreadable in the dialog this ends up in. The shape is duck-typed because this
+    // package prescribes no schema library.
+    const zodLike = Object.assign(new Error("[{...}]"), {
+      issues: [
+        { code: "invalid_type", path: ["numbers", 0], message: "Expected number, received string" },
+        { code: "unrecognized_keys", path: [], message: "Unrecognized key(s) in object: 'colour'" },
+      ],
+    });
+
+    const result = validateTemplateParams({}, () => {
+      throw zodLike;
+    });
+
+    expect(result.error).toBe(
+      "params do not match this block's kind: numbers[0]: Expected number, received string; " +
+        "Unrecognized key(s) in object: 'colour'",
+    );
+  });
+
+  test("a path is written the way the params are written", () => {
+    const result = validateTemplateParams({}, () => {
+      throw Object.assign(new Error("x"), {
+        issues: [{ path: ["steps", 2, "name"], message: "Required" }],
+      });
+    });
+
+    expect(result.error).toContain("steps[2].name: Required");
+  });
+
+  test("a plain error keeps its own words", () => {
+    const result = validateTemplateParams({}, () => {
+      throw new Error("numbers must not be empty");
+    });
+
+    expect(result.error).toBe("params do not match this block's kind: numbers must not be empty");
+  });
+});
+
+describe("a caller that predates this callback", () => {
+  test("is named as the cause, instead of blaming the template's params", () => {
+    // A middle layer older than the block calls this with one argument, so the id map arrives
+    // as `undefined`. It happened for real: an entry with no references at all failed with
+    // "params are not valid JSON", sending the reader to a file that was perfectly fine.
+    const result = createInitialStorageFromParams(
+      JSON.stringify({ label: "x" }),
+      undefined as unknown as string,
+      {
+        getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+        parseInitializationParams: passThrough,
+        ...noPlugins,
+      },
+    );
+
+    expect(result.error).toMatch(/not told which blocks/);
+    expect(result.error).toMatch(/older than the block; rebuild or update it/);
+  });
+});
+
+describe("the readable reference spelling", () => {
+  const hooks = () => ({
+    getBlockDataFromParams: (p: unknown) => dataModel.getDataFromParams(p),
+    parseInitializationParams: passThrough,
+    ...noPlugins,
+  });
+
+  test("becomes a PlRef, and is repointed like a long-form one", () => {
+    // What a hand-written file gets to say: `{ block, name }`, no `__isRef`. It arrives at the
+    // block as the reference it stands for, pointing at the block the entry was given.
+    const result = createInitialStorageFromParams(
+      JSON.stringify({ label: "x", sources: [{ block: "samples", name: "reads" }] }),
+      JSON.stringify({ samples: "block-1" }),
+      hooks(),
+    );
+
+    expect(JSON.parse(result.storageJson!).__data).toEqual({
+      label: "x",
+      sources: [createPlRef("block-1", "reads")],
+      scratch: 0,
+    });
+  });
+
+  test("the kind's parser is the check, and it sees the expanded form", () => {
+    // The whole reason expansion happens before the parser: a contract declared against `PlRef`
+    // would reject `{ block, name }` outright, so the readable spelling would be unusable.
+    const rejectsShorthand = (value: unknown) => {
+      const { sources } = value as { sources: unknown };
+      if (!Array.isArray(sources) || sources.some((s) => (s as PlRef).__isRef !== true)) {
+        throw new Error("'sources' must be an array of references");
+      }
+      return value as Params;
+    };
+
+    const result = createInitialStorageFromParams(
+      JSON.stringify({ label: "x", sources: [{ block: "samples", name: "reads" }] }),
+      JSON.stringify({}),
+      { ...hooks(), parseInitializationParams: rejectsShorthand },
+    );
+
+    expect(result.error).toBeUndefined();
+  });
+});