@milaboratories/pl-middle-layer 1.66.18 → 1.67.0

package/src/model/template_export.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, test } from "vitest";
+import canonicalize from "canonicalize";
+import { createPlRef } from "@milaboratories/pl-model-common";
+import type { ProjectStructure } from "./project_model";
+import type { TemplateParamsResult } from "./template_export";
+import { walkProjectForTemplateExport } from "./template_export";
+
+function simpleStructure(...ids: string[]): ProjectStructure {
+  return {
+    groups: [
+      {
+        id: "g1",
+        label: "G1",
+        blocks: ids.map((id) => ({ id, label: id, renderingMode: "Heavy" })),
+      },
+    ],
+  };
+}
+
+/** A provider backed by a plain map; blocks absent from it yield `undefined`. */
+function providerFrom(params: Record<string, TemplateParamsResult>) {
+  return (blockId: string): TemplateParamsResult | undefined => params[blockId];
+}
+
+const ok = (value: unknown): TemplateParamsResult => ({ value });
+
+describe("order", () => {
+  test("entries come out in structure order — no sort, none needed", () => {
+    // The structure IS the topological order: a block can only legally reference
+    // blocks above it, so emitting in this order gives a template file the ordering
+    // it needs — every block after the blocks it references — for free.
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("samples", "mixcr", "browser"),
+      providerFrom({
+        samples: ok({ dataset: "bulk-rna" }),
+        mixcr: ok({ input: { block: "samples", output: "reads" } }),
+        browser: ok({ clonotypes: { block: "mixcr", output: "clonotypes" } }),
+      }),
+    );
+
+    expect(walk.problems).toEqual([]);
+    expect(walk.entries.map((e) => e.blockId)).toEqual(["samples", "mixcr", "browser"]);
+  });
+
+  test("structure order wins over reference order", () => {
+    // Same three blocks, structure reordered. The walk reports what the project
+    // says, so a structure that violates the ordering rule produces a file that
+    // reference validation rejects — it is not silently fixed here, because
+    // reordering would change which references are even legal.
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("browser", "samples", "mixcr"),
+      providerFrom({ browser: ok({}), samples: ok({}), mixcr: ok({}) }),
+    );
+
+    expect(walk.entries.map((e) => e.blockId)).toEqual(["browser", "samples", "mixcr"]);
+  });
+
+  test("groups are flattened in order", () => {
+    const structure: ProjectStructure = {
+      groups: [
+        { id: "g1", label: "G1", blocks: [{ id: "a", label: "a", renderingMode: "Heavy" }] },
+        {
+          id: "g2",
+          label: "G2",
+          blocks: [
+            { id: "b", label: "b", renderingMode: "Heavy" },
+            { id: "c", label: "c", renderingMode: "Heavy" },
+          ],
+        },
+      ],
+    };
+
+    const walk = walkProjectForTemplateExport(
+      structure,
+      providerFrom({ a: ok({}), b: ok({}), c: ok({}) }),
+    );
+
+    expect(walk.entries.map((e) => e.blockId)).toEqual(["a", "b", "c"]);
+  });
+
+  test("an empty project walks to an empty template", () => {
+    expect(walkProjectForTemplateExport(simpleStructure(), providerFrom({}))).toEqual({
+      entries: [],
+      problems: [],
+    });
+  });
+});
+
+describe("collecting each block's descriptor output", () => {
+  test("params are carried through untouched", () => {
+    // The walk does not reshape params — references were already rewritten into
+    // template form on the SDK side, so there is nothing kind-specific to do here.
+    const params = {
+      species: "human",
+      input: { block: "samples", output: "reads" },
+      thresholds: [0.1, 0.2],
+    };
+
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("mixcr"),
+      providerFrom({ mixcr: ok(params) }),
+    );
+
+    expect(walk.entries).toEqual([{ blockId: "mixcr", params }]);
+  });
+
+  test("a block with nothing to project yields empty params", () => {
+    // Every block declares the lambda, so "no params at all" is not an outcome the walk
+    // can produce. A block whose state carries nothing worth restoring returns `{}`.
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("pool-explorer"),
+      providerFrom({ "pool-explorer": ok({}) }),
+    );
+
+    expect(walk.entries).toEqual([{ blockId: "pool-explorer", params: {} }]);
+    expect(walk.problems).toEqual([]);
+  });
+});
+
+describe("what the walk does with params", () => {
+  const UUID_A = "3f1b8c2e-5d4a-4c9f-8b17-2a6e0d9f4c31";
+  const UUID_B = "9c7e4d10-2b83-4f6a-91d5-7e0c3a8b5f42";
+
+  /** A canonical global-leaf identifier, i.e. a reference held as a string. */
+  const leafId = (blockId: string, name: string) => canonicalize({ __isRef: true, blockId, name })!;
+
+  test("params are written exactly as the block projected them", () => {
+    // The walk parses nothing and rewrites nothing: a template-local entry id IS the block's
+    // own id, so a wrapped reference already names the right entry.
+    const params = { input: createPlRef(UUID_A, "reads"), species: "hsa" };
+    const walk = walkProjectForTemplateExport(
+      simpleStructure(UUID_A, UUID_B),
+      providerFrom({ [UUID_A]: ok({}), [UUID_B]: ok(params) }),
+    );
+
+    expect(walk.problems).toEqual([]);
+    expect(walk.entries[1].params).toBe(params);
+  });
+
+  test("a non-UUID id passes through unchanged too", () => {
+    // `Project.addBlock` accepts an explicit id and only *defaults* it to a random UUID, so
+    // "UUID" describes the common case, not a constraint.
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("block1"),
+      providerFrom({ block1: ok({}) }),
+    );
+
+    expect(walk.entries).toEqual([{ blockId: "block1", params: {} }]);
+  });
+
+  test("a wrapper's contents are never inspected, whatever they are", () => {
+    // An identifier as a string, one under escape padding, a whole nested structure — all the
+    // same to the walk, which is the property the wrapper exists to buy.
+    const params = {
+      asObject: createPlRef("a", "reads"),
+      asString: leafId("a", "clones"),
+      stringified: JSON.stringify(leafId("a", "clones")),
+      nested: { deeper: [[createPlRef("a", "x")]] },
+    };
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("a", "b"),
+      providerFrom({ a: ok({}), b: ok(params) }),
+    );
+
+    expect(walk.problems).toEqual([]);
+    expect(walk.entries[1].params).toBe(params);
+  });
+
+  test("a reference the block did not wrap is written out as data, not refused", () => {
+    // The engine exposes the wrapper mechanic and models nothing else, so it has no opinion
+    // about an unwrapped `PlRef` — it is a value like any other. Wrapping the right things is
+    // the block's statement to make, and getting it wrong yields a template that does not
+    // work, the same way a wrong field name would. Pinned so the boundary stays deliberate.
+    const params = { input: createPlRef("a", "reads") };
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("a", "b"),
+      providerFrom({ a: ok({}), b: ok(params) }),
+    );
+
+    expect(walk.problems).toEqual([]);
+    expect(walk.entries[1].params).toBe(params);
+  });
+
+  test("a reference to a block outside the project is written out too", () => {
+    // Same boundary from the other side: telling this apart would mean recognizing which
+    // strings are identifiers, which is exactly the knowledge the engine does not hold. It
+    // surfaces on apply, as a block wired to nothing.
+    const params = { input: createPlRef("deleted", "reads") };
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("b"),
+      providerFrom({ b: ok(params) }),
+    );
+
+    expect(walk.problems).toEqual([]);
+    expect(walk.entries[0].params).toBe(params);
+  });
+});
+
+describe("problems", () => {
+  test("a failed derivation is reported against its block, and the walk continues", () => {
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("a", "b", "c"),
+      providerFrom({
+        a: ok({ x: 1 }),
+        b: { error: "templateParams() threw: not exportable yet" },
+        c: ok({ z: 3 }),
+      }),
+    );
+
+    // Every offending block is reported at once rather than aborting on the
+    // first, so the user fixes them in one pass.
+    expect(walk.problems).toEqual([
+      { blockId: "b", error: "templateParams() threw: not exportable yet" },
+    ]);
+    expect(walk.entries.map((e) => e.blockId)).toEqual(["a", "c"]);
+  });
+
+  test("a block with unreadable state is a problem, not a silent skip", () => {
+    // `productionGraph` skips blocks it has no args for; export must not, because
+    // a template that quietly omits a block does not describe the project — and
+    // the surviving entries may still reference the omitted one.
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("a", "ghost"),
+      providerFrom({ a: ok({}) }),
+    );
+
+    expect(walk.entries.map((e) => e.blockId)).toEqual(["a"]);
+    expect(walk.problems).toEqual([
+      {
+        blockId: "ghost",
+        error: "Block state is unavailable, so its template params could not be derived",
+      },
+    ]);
+  });
+
+  test.each([
+    { label: "a string", value: "not-params", expected: "a string" },
+    { label: "a number", value: 42, expected: "a number" },
+    { label: "null", value: null, expected: "null" },
+    { label: "an array", value: [1, 2], expected: "an array" },
+  ])("non-object params are rejected: $label", ({ value, expected }) => {
+    // An entry's `params` must be a mapping. A block kind carries its params type
+    // as a TypeScript type only, with no runtime schema, so nothing upstream
+    // enforces this — the walk is the only place that can catch it.
+    const walk = walkProjectForTemplateExport(
+      simpleStructure("odd"),
+      providerFrom({ odd: ok(value) }),
+    );
+
+    expect(walk.entries).toEqual([]);
+    expect(walk.problems).toEqual([
+      { blockId: "odd", error: `templateParams() must return an object, got ${expected}` },
+    ]);
+  });
+});

package/src/model/template_export.ts

@@ -0,0 +1,136 @@
+import type { ProjectStructure } from "./project_model";
+import { allBlocks } from "./project_model_util";
+
+/**
+ * One block's template-descriptor output as the walk receives it.
+ *
+ * Deliberately the same shape the `__pl_initializationParams_derive` facade callback
+ * returns, so a provider can hand the VM's result straight through without
+ * reshaping it.
+ */
+export type TemplateParamsResult =
+  | { readonly error: string }
+  | { readonly error?: undefined; readonly value: unknown };
+
+/** One block's contribution to the template being exported. */
+export type TemplateExportEntry = {
+  /**
+   * The block's project-local id, which is also its template-local id: a template
+   * has no id namespace of its own, so the id is reused verbatim and references
+   * already stored in params need no translation.
+   */
+  readonly blockId: string;
+  /**
+   * The block's params exactly as it projected them.
+   *
+   * Always a mapping: a block that declared no `templateParams`, or whose lambda returned
+   * something else, is reported as a problem rather than carried here — see the object check
+   * in the walk. So nothing downstream has an absent case to decide.
+   */
+  readonly params: Record<string, unknown>;
+};
+
+/** Why one block could not be exported. */
+export type TemplateExportProblem = {
+  readonly blockId: string;
+  readonly error: string;
+};
+
+/**
+ * Outcome of the walk: the blocks that can be written, and the ones that cannot.
+ *
+ * Both lists are returned rather than throwing on the first failure, so the
+ * caller can report every offending block at once instead of making the user fix
+ * them one export at a time. Whether a non-empty `problems` aborts the export is
+ * the caller's policy, not the walk's — but note that emitting `entries` while
+ * ignoring `problems` can produce a file whose surviving entries reference a
+ * dropped block, which is an unusable template.
+ */
+export type TemplateExportWalk = {
+  readonly entries: readonly TemplateExportEntry[];
+  readonly problems: readonly TemplateExportProblem[];
+};
+
+/**
+ * Walk a project's blocks in dependency order, collecting each one's
+ * template-descriptor output.
+ *
+ * **No topological sort is performed, because none is needed.** The project
+ * structure is already stored in topological order, and that is enforced rather
+ * than assumed: `productionGraph` traverses `allBlocks(structure)` and passes the
+ * set of blocks seen *so far* as the allowed set to `inferAllReferencedBlocks`, so
+ * a reference to a block that is not already above is recorded as a missing
+ * reference instead of an upstream. A block can therefore only legally reference
+ * blocks earlier in this sequence — which is exactly what a template file needs,
+ * since its block order is the instantiation order and the engine creates blocks
+ * upstream-first. Emitting entries in structure order satisfies that for free.
+ *
+ * Groups are flattened in order, so cross-group ordering is the structure's too.
+ *
+ * A structure that violates the ordering rule is reported as-is, not repaired:
+ * reordering would change which references are legal in the first place.
+ *
+ * Params are written exactly as the block projected them. The walk parses nothing, rewrites
+ * nothing and inspects nothing inside them, and neither does anything else between here and the
+ * file — which values carry block ids is knowledge of the reference system, and a template
+ * engine holds none of it. The block that receives these params on the way back in is what
+ * recognizes them; a block that projects the wrong fields produces a template that does not
+ * work, the same way one whose `templateParams` returns the wrong shape does.
+ *
+ * @param structure The project structure — the source of both membership and order
+ * @param paramsProvider Yields a block's derived template params. Return
+ *   `undefined` for a block whose state cannot be read at all; such a block is
+ *   recorded as a problem rather than skipped, because a template that quietly
+ *   omits a block does not describe the project it was exported from, and the
+ *   surviving entries may still reference the omitted one.
+ */
+export function walkProjectForTemplateExport(
+  structure: ProjectStructure,
+  paramsProvider: (blockId: string) => TemplateParamsResult | undefined,
+): TemplateExportWalk {
+  const entries: TemplateExportEntry[] = [];
+  const problems: TemplateExportProblem[] = [];
+
+  for (const { id } of allBlocks(structure)) {
+    const derived = paramsProvider(id);
+
+    if (derived === undefined) {
+      problems.push({
+        blockId: id,
+        error: "Block state is unavailable, so its template params could not be derived",
+      });
+      continue;
+    }
+
+    if (derived.error !== undefined) {
+      problems.push({ blockId: id, error: derived.error });
+      continue;
+    }
+
+    const params = derived.value;
+
+    // An entry's `params` must be a mapping. The lambda's declared return type is the
+    // block kind's params type, and the kind's parser checks values coming IN, but
+    // nothing checks what the lambda hands back on the way out — so a block whose
+    // params type is a primitive or a tuple compiles fine and would produce an
+    // unwritable entry. This is the only place that can catch it.
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+      problems.push({
+        blockId: id,
+        error: `templateParams() must return an object, got ${typeName(params)}`,
+      });
+      continue;
+    }
+
+    entries.push({ blockId: id, params: params as Record<string, unknown> });
+  }
+
+  return { entries, problems };
+}
+
+/** Name the offending value's type for an error message, without printing the value. */
+function typeName(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
+}

package/src/model/template_parser.test.ts

@@ -0,0 +1,264 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { PROJECT_TEMPLATE_SCHEMA_V1 } from "@milaboratories/pl-model-common";
+import { parseProjectTemplateV1Yaml } from "./template_parser";
+import { stringifyProjectTemplateV1 } from "./template_serializer";
+
+const FIXTURE_DIR = join(import.meta.dirname, "..", "..", "test_fixtures", "template-v1");
+
+const KIND = "@platforma-open/milaboratories.demo.kind@^1.0.0";
+
+/** The document, or a test failure naming what went wrong instead. */
+function documentOf(text: string) {
+  const outcome = parseProjectTemplateV1Yaml(text);
+  if (!outcome.ok) throw new Error(`expected a document, got: ${outcome.error}`);
+  return outcome.document;
+}
+
+/** The error message, or a test failure if the text parsed after all. */
+function errorOf(text: string): string {
+  const outcome = parseProjectTemplateV1Yaml(text);
+  if (outcome.ok) throw new Error("expected a failure, but the text parsed");
+  return outcome.error;
+}
+
+describe("parseProjectTemplateV1Yaml", () => {
+  test("reads a file into the document import applies", () => {
+    const document = documentOf(
+      [
+        `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}`,
+        "blocks:",
+        "  - id: first",
+        `    kind: "${KIND}"`,
+        "    params:",
+        "      dataset: bulk-rna",
+        "  - id: second",
+        `    kind: "${KIND}"`,
+        "    params:",
+        "      input:",
+        "        __isRef: true",
+        "        blockId: first",
+        "        name: reads",
+        "      readable:",
+        "        block: first",
+        "        name: reads",
+        "",
+      ].join("\n"),
+    );
+
+    expect(document.blocks).toEqual([
+      { id: "first", kind: KIND, params: { dataset: "bulk-rna" } },
+      {
+        id: "second",
+        kind: KIND,
+        // Carried verbatim, both spellings alike: the parser recognizes neither as a
+        // reference, because recognizing one is the receiving block's business.
+        params: {
+          input: { __isRef: true, blockId: "first", name: "reads" },
+          readable: { block: "first", name: "reads" },
+        },
+      },
+    ]);
+  });
+
+  test("an entry without params reads as empty params", () => {
+    // The one thing the parser fills in. Leaving the key absent would make every reader
+    // downstream normalize it, and one of them would eventually forget.
+    const [entry] = documentOf(
+      `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}\nblocks:\n  - id: a\n    kind: "${KIND}"\n`,
+    ).blocks;
+
+    expect(entry.params).toEqual({});
+  });
+
+  test("JSON is accepted, being valid YAML", () => {
+    // Not a feature to advertise, but a file someone hand-wrote as JSON should not be
+    // rejected for a reason that has nothing to do with its contents.
+    const document = documentOf(
+      JSON.stringify({
+        schema: PROJECT_TEMPLATE_SCHEMA_V1,
+        blocks: [{ id: "a", kind: KIND }],
+      }),
+    );
+
+    expect(document.blocks).toHaveLength(1);
+  });
+
+  test("every golden export file reads back", () => {
+    // The other side of the round trip, checked against the files the export tests
+    // pin: whatever export writes, this reads. A fixture that stopped parsing here
+    // would mean the two halves had drifted apart.
+    const files = readdirSync(FIXTURE_DIR).filter((f) => f.endsWith(".yaml"));
+
+    expect(files.length).toBeGreaterThan(0);
+    for (const file of files) {
+      const text = readFileSync(join(FIXTURE_DIR, file), "utf-8");
+      const outcome = parseProjectTemplateV1Yaml(text);
+
+      expect(outcome.ok, `${file}: ${outcome.ok ? "" : outcome.error}`).toBe(true);
+    }
+  });
+
+  test("a document survives being written and read again", () => {
+    // Text → document → text → document. Pins the two text layers against each other
+    // rather than against a fixture, so a change to either shows up here.
+    const original = documentOf(
+      `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}\nblocks:\n  - id: a\n    kind: "${KIND}"\n    params:\n      n: 1\n`,
+    );
+
+    expect(documentOf(stringifyProjectTemplateV1(original))).toEqual(original);
+  });
+});
+
+describe("what a broken file says", () => {
+  test("an empty file is called empty", () => {
+    // Blank input, whitespace and comment-only files all parse to null, where the
+    // schema would report a type mismatch instead of the actual mistake.
+    expect(errorOf("")).toBe("The file is empty.");
+    expect(errorOf("   \n\n")).toBe("The file is empty.");
+    expect(errorOf("# just a comment\n")).toBe("The file is empty.");
+  });
+
+  test("a YAML syntax error is located, without a code frame", () => {
+    // The position is what a person needs; the frame duplicates the editor they are
+    // already looking at.
+    const error = errorOf(
+      `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}\nblocks:\n  - id: a\n   kind: x\n`,
+    );
+
+    expect(error).toContain("not valid YAML");
+    expect(error).toContain("line 4");
+    expect(error).not.toContain("\n");
+  });
+
+  test("a repeated key is reported rather than silently dropped", () => {
+    // A realistic hand-editing mistake: copy an entry, forget to change a field. YAML
+    // would otherwise keep one of the two and the file would apply, wrongly.
+    const error = errorOf(
+      `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}\nblocks:\n  - id: a\n    id: b\n    kind: "${KIND}"\n`,
+    );
+
+    expect(error).toContain("not valid YAML");
+    expect(error).toMatch(/keys must be unique/i);
+  });
+
+  test("tabs are reported as such", () => {
+    // Tab indentation is invalid YAML and the failure is otherwise baffling.
+    expect(errorOf("schema: x\n\tblocks: []\n")).toMatch(/tabs/i);
+  });
+
+  test("something that is not a mapping says what was expected", () => {
+    expect(errorOf("a plain string\n")).toContain("expected a mapping");
+    expect(errorOf("- a\n- b\n")).toContain("expected a mapping");
+  });
+
+  test("the wrong kind of file is named as such, not as a type error", () => {
+    // The likeliest mistake of all — a file picker was pointed at the wrong file — so
+    // it gets its own message rather than the schema's literal-mismatch wording.
+    expect(errorOf("schema: template-v2\nblocks: []\n")).toBe(
+      `This file says it is 'template-v2', not ${PROJECT_TEMPLATE_SCHEMA_V1}.`,
+    );
+    expect(errorOf("blocks: []\n")).toBe(
+      `This file has no 'schema' field, so it is not a ${PROJECT_TEMPLATE_SCHEMA_V1} template.`,
+    );
+  });
+
+  test("a schema problem is located the way the file is written", () => {
+    // `blocks[0].kind`, not the parser's `blocks.0.kind`: the reader finds it by
+    // reading, not by counting.
+    const error = errorOf(`schema: ${PROJECT_TEMPLATE_SCHEMA_V1}\nblocks:\n  - id: a\n`);
+
+    expect(error).toContain("- blocks[0].kind:");
+  });
+
+  test("every schema problem is listed, and counted", () => {
+    // One pass to fix the file, not one pass per problem.
+    const error = errorOf(
+      [`schema: ${PROJECT_TEMPLATE_SCHEMA_V1}`, "blocks:", "  - id: a", "  - id: b", ""].join("\n"),
+    );
+
+    expect(error).toContain("2 problems:");
+    expect(error).toContain("- blocks[0].kind:");
+    expect(error).toContain("- blocks[1].kind:");
+  });
+
+  test("a malformed kind reference explains the grammar", () => {
+    const error = errorOf(
+      `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}\nblocks:\n  - id: a\n    kind: no-version\n`,
+    );
+
+    expect(error).toContain("blocks[0].kind:");
+    expect(error).toContain("{name}@{selector}");
+  });
+
+  test("two entries with the same id are rejected", () => {
+    // Template-local ids are what references name, so a duplicate makes a reference
+    // ambiguous — and the apply would map one id to two blocks.
+    const error = errorOf(
+      [
+        `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}`,
+        "blocks:",
+        "  - id: a",
+        `    kind: "${KIND}"`,
+        "  - id: a",
+        `    kind: "${KIND}"`,
+        "",
+      ].join("\n"),
+    );
+
+    expect(error).toContain("Duplicate template-local id: a");
+  });
+
+  test("an unknown field is refused, not ignored", () => {
+    // A misspelled key that was silently dropped would apply a file that does not say
+    // what the author meant.
+    const error = errorOf(
+      `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}\nblocks:\n  - id: a\n    kind: "${KIND}"\n    parms: {}\n`,
+    );
+
+    expect(error).toMatch(/Unrecognized key/);
+  });
+});
+
+describe("scalars in params", () => {
+  test("what looks like a string stays a string", () => {
+    // Read as YAML 1.2 on purpose. Under 1.1 — PyYAML's default — a bare `yes` is
+    // `true` and `1:30` is `90`, so a hand-written file would silently change meaning
+    // depending on who wrote it. The export side quotes these anyway, which is the
+    // other half of the same decision.
+    const [entry] = documentOf(
+      [
+        `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}`,
+        "blocks:",
+        "  - id: a",
+        `    kind: "${KIND}"`,
+        "    params:",
+        "      answer: yes",
+        "      duration: 1:30",
+        "",
+      ].join("\n"),
+    ).blocks;
+
+    expect(entry.params).toEqual({ answer: "yes", duration: "1:30" });
+  });
+
+  test("numbers and booleans written as such stay themselves", () => {
+    const [entry] = documentOf(
+      [
+        `schema: ${PROJECT_TEMPLATE_SCHEMA_V1}`,
+        "blocks:",
+        "  - id: a",
+        `    kind: "${KIND}"`,
+        "    params:",
+        "      count: 42",
+        "      ratio: 0.5",
+        "      enabled: true",
+        "      missing: null",
+        "",
+      ].join("\n"),
+    ).blocks;
+
+    expect(entry.params).toEqual({ count: 42, ratio: 0.5, enabled: true, missing: null });
+  });
+});