@milaboratories/pl-model-common 1.47.3 → 1.48.0

package/dist/template/template_relocate.js

@@ -0,0 +1,46 @@
+import { isColumnUniversalKey, remapColumnIdBlockIds } from "../drivers/pframe/spec/ids.js";
+import "../drivers/index.js";
+//#region src/template/template_relocate.ts
+/**
+* Point every column identifier in a block's params at the blocks of the project being built.
+*
+* The whole of what a template does about references, and it lives here — in the package the
+* block's own bundle imports — because knowing which values carry block ids is knowing the
+* reference system. The engine carrying the params neither marks them, reads them, nor
+* rewrites them: it hands the block its params and this map, and takes back what comes out.
+*
+* Params travel verbatim precisely so that this is possible. A file holds a `PlRef` as the
+* object the block stored and a column id as the canonical string the block stored, with no
+* marker of any kind, and the identifiers are found here by recognizing them — the same way
+* the project's own dependency detector finds them in live args.
+*
+* Rewriting is structural, never textual: an identifier is taken apart, its `blockId` fields
+* are replaced, and it is rebuilt canonically. That is what keeps a value that merely *looks*
+* like an id — a `domain` entry, an axis filter — from being rewritten along with it, and
+* what re-sorts a qualifications map whose keys are identifiers.
+*
+* An id the map does not mention is left as it is. That is the ordering rule doing its work:
+* a caller building the map as it creates blocks passes only the entries already created, so
+* a reference to an entry further down the file stays pointing at a block that does not
+* exist, and the applied block reports itself as missing references rather than being wired
+* to something below it.
+*
+* @param params Whatever the block projected, as the document stored it
+* @param blockIds template-local entry id → the block id that entry was given
+*/
+function relocateBlockIds(params, blockIds) {
+	if (blockIds.size === 0) return params;
+	const remapBlockId = (blockId) => blockIds.get(blockId) ?? blockId;
+	const walk = (node) => {
+		if (typeof node === "string") return remapColumnIdBlockIds(node, remapBlockId);
+		if (isColumnUniversalKey(node)) return remapColumnIdBlockIds(node, remapBlockId);
+		if (Array.isArray(node)) return node.map(walk);
+		if (typeof node === "object" && node !== null) return Object.fromEntries(Object.entries(node).map(([key, value]) => [remapColumnIdBlockIds(key, remapBlockId), walk(value)]));
+		return node;
+	};
+	return walk(params);
+}
+//#endregion
+export { relocateBlockIds };
+
+//# sourceMappingURL=template_relocate.js.map

package/dist/template/template_relocate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_relocate.js","names":[],"sources":["../../src/template/template_relocate.ts"],"sourcesContent":["import { isColumnUniversalKey, remapColumnIdBlockIds } from \"../drivers\";\n\n/**\n * Point every column identifier in a block's params at the blocks of the project being built.\n *\n * The whole of what a template does about references, and it lives here — in the package the\n * block's own bundle imports — because knowing which values carry block ids is knowing the\n * reference system. The engine carrying the params neither marks them, reads them, nor\n * rewrites them: it hands the block its params and this map, and takes back what comes out.\n *\n * Params travel verbatim precisely so that this is possible. A file holds a `PlRef` as the\n * object the block stored and a column id as the canonical string the block stored, with no\n * marker of any kind, and the identifiers are found here by recognizing them — the same way\n * the project's own dependency detector finds them in live args.\n *\n * Rewriting is structural, never textual: an identifier is taken apart, its `blockId` fields\n * are replaced, and it is rebuilt canonically. That is what keeps a value that merely *looks*\n * like an id — a `domain` entry, an axis filter — from being rewritten along with it, and\n * what re-sorts a qualifications map whose keys are identifiers.\n *\n * An id the map does not mention is left as it is. That is the ordering rule doing its work:\n * a caller building the map as it creates blocks passes only the entries already created, so\n * a reference to an entry further down the file stays pointing at a block that does not\n * exist, and the applied block reports itself as missing references rather than being wired\n * to something below it.\n *\n * @param params Whatever the block projected, as the document stored it\n * @param blockIds template-local entry id → the block id that entry was given\n */\nexport function relocateBlockIds<T>(params: T, blockIds: ReadonlyMap<string, string>): T {\n  if (blockIds.size === 0) return params;\n  const remapBlockId = (blockId: string) => blockIds.get(blockId) ?? blockId;\n\n  const walk = (node: unknown): unknown => {\n    // Any string may be an identifier under any amount of escaping; one that is not comes\n    // back as the very same string, so this needs no test of its own here.\n    if (typeof node === \"string\") return remapColumnIdBlockIds(node, remapBlockId);\n\n    // Before the generic object case: an identifier IS an object, and descending into one\n    // would rewrite the strings nested in it piecemeal instead of rebuilding the whole id —\n    // losing the bottom-up canonicalization that keeps the result a valid identifier.\n    if (isColumnUniversalKey(node)) return remapColumnIdBlockIds(node, remapBlockId);\n\n    if (Array.isArray(node)) return node.map(walk);\n\n    if (typeof node === \"object\" && node !== null) {\n      // Keys as well as values: params may be keyed by column id — per-column settings, say\n      // — and a key is exactly as much of a reference as a value is.\n      return Object.fromEntries(\n        Object.entries(node).map(([key, value]) => [\n          remapColumnIdBlockIds(key, remapBlockId),\n          walk(value),\n        ]),\n      );\n    }\n\n    return node;\n  };\n\n  return walk(params) as T;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,iBAAoB,QAAW,UAA0C;CACvF,IAAI,SAAS,SAAS,GAAG,OAAO;CAChC,MAAM,gBAAgB,YAAoB,SAAS,IAAI,OAAO,KAAK;CAEnE,MAAM,QAAQ,SAA2B;EAGvC,IAAI,OAAO,SAAS,UAAU,OAAO,sBAAsB,MAAM,YAAY;EAK7E,IAAI,qBAAqB,IAAI,GAAG,OAAO,sBAAsB,MAAM,YAAY;EAE/E,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO,KAAK,IAAI,IAAI;EAE7C,IAAI,OAAO,SAAS,YAAY,SAAS,MAGvC,OAAO,OAAO,YACZ,OAAO,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CACzC,sBAAsB,KAAK,YAAY,GACvC,KAAK,KAAK,CACZ,CAAC,CACH;EAGF,OAAO;CACT;CAEA,OAAO,KAAK,MAAM;AACpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-common",
-  "version": "1.47.3",
+  "version": "1.48.0",
   "description": "Platforma SDK Model",
   "files": [
     "./dist/**/*",
@@ -20,16 +20,16 @@
     "canonicalize": "~2.1.0",
     "es-toolkit": "^1.39.10",
     "zod": "~3.25.76",
-    "@milaboratories/helpers": "1.14.5",
-    "@milaboratories/pl-error-like": "1.12.10"
+    "@milaboratories/pl-error-like": "1.12.10",
+    "@milaboratories/helpers": "1.14.5"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.1.3",
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
+    "@milaboratories/ts-configs": "1.4.0",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-builder": "1.6.1",
-    "@milaboratories/ts-configs": "1.3.1"
+    "@milaboratories/ts-builder": "1.7.0"
   },
   "scripts": {
     "build": "ts-builder build --target node",

package/src/bmodel/block_kind_ref.ts

@@ -0,0 +1,59 @@
+import type { Branded } from "@milaboratories/helpers";
+
+/**
+ * On-wire reference to a block kind, canonically the string `{name}@{version}`.
+ *
+ * A branded string: readers overwhelmingly need identity equality ("does block
+ * X implement kind Y?"), for which an opaque canonical string is ideal. Any
+ * reader that needs the parts calls {@link parseKindRef}; any writer composes
+ * the reference through {@link formatKindRef}. Keeping composition in a single
+ * function localizes the one open decision — whether the name segment has to be
+ * org-qualified for global uniqueness — to one place.
+ */
+export type BlockKindReference = Branded<string, "BlockKindReference">;
+
+/**
+ * Compose a {@link BlockKindReference} from a kind's `name`/`version`.
+ *
+ * The single place that decides how the reference is assembled. If global
+ * uniqueness later requires the name segment to be org-qualified, this is the
+ * one line that changes.
+ */
+export const formatKindRef = (k: { name: string; version: string }): BlockKindReference =>
+  `${k.name}@${k.version}` as BlockKindReference;
+
+/**
+ * Split a `{name}@{version}` string on its version separator.
+ *
+ * The one place that decides where the name ends. Uses the LAST `@` so an
+ * org-qualified npm name that itself starts with `@` (e.g.
+ * `@platforma-open/pkg.kind`) keeps its whole name. A leading/absent separator
+ * (`lastIndexOf("@") <= 0`) means the string carries no version segment —
+ * malformed — so this throws rather than returning a silently version-less
+ * result.
+ *
+ * Shared with the template layer, whose `{name}@{selector}` references use the
+ * same split and differ only in how the right half is interpreted (see
+ * `parseKindSelectorReference`). `what` names the thing being parsed so the
+ * error message stays specific to the caller's reference type.
+ */
+export const splitVersionedName = (
+  ref: string,
+  what = "block kind reference",
+  expected = "{name}@{version}",
+): { name: string; version: string } => {
+  const at = ref.lastIndexOf("@");
+  if (at <= 0) {
+    throw new Error(`Malformed ${what} (expected '${expected}'): ${ref}`);
+  }
+  return { name: ref.slice(0, at), version: ref.slice(at + 1) };
+};
+
+/**
+ * Split a {@link BlockKindReference} back into `{ name, version }`.
+ *
+ * Throws on a reference with no version segment — see
+ * {@link splitVersionedName}, which owns the split rule.
+ */
+export const parseKindRef = (ref: BlockKindReference): { name: string; version: string } =>
+  splitVersionedName(ref);

package/src/bmodel/container.ts

@@ -1,4 +1,5 @@
 import type { BlockConfigV3Generic, BlockConfigV4Generic } from "./block_config";
+import type { BlockKindReference } from "./block_kind_ref";
 import type { Code } from "./code";
 import type { BlockRenderingMode } from "./types";
 
@@ -11,6 +12,14 @@ export type BlockConfigContainer = {
   /** Config code bundle. Actually is required, but we keep it optional for backward compatibility */
   readonly code?: Code;
 
+  /**
+   * Reference to the block kind this config implements, in `{name}@{version}`
+   * form. Version-independent block identity — lives at the container level
+   * beside {@link code}, orthogonal to which render envelope (`v3`/`v4`)
+   * applies. Optional for backward compatibility with kind-less blocks.
+   */
+  readonly kind?: BlockKindReference;
+
   //
   // Fields below are used to read previous config versions
   //

package/src/bmodel/index.ts

@@ -2,4 +2,5 @@ export * from "./block_config";
 export * from "./code";
 export * from "./types";
 export * from "./container";
+export * from "./block_kind_ref";
 export * from "./normalization";

package/src/columns/dedup.ts

@@ -20,7 +20,7 @@ import { isPObjectId } from "../pool";
  *
  * Shared by sandbox-side `extractColumns` (column_providers) and host-side
  * `ColumnsCollectionDriverImpl.getColumns` — both layers need identical
- * dedup semantics, but operate on different concrete item types (ColumnLazy
+ * dedup semantics, but operate on different concrete item types (DataColumnRecipe
  * vs. raw ColumnUniversalId).
  */
 export function dedupColumns<T>(

package/src/columns/providers.ts

@@ -8,7 +8,7 @@ import type { AccessorLike, ColumnEntriesProvider, LeafEntry, UpstreamBlockCtx }
  * exposes `isFinal()` via the root's `getInputsLocked()`.
  *
  * Used directly on the host side; sandbox extends it with `getColumns()`
- * returning {@link ColumnLazy}s — see `AccessorColumnsProvider` in
+ * returning {@link DataColumnRecipe}s — see `AccessorColumnsProvider` in
  * `@platforma-sdk/model`.
  */
 export class AccessorEntriesProvider<

package/src/drivers/pframe/spec/ids.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "vitest";
+import { createGlobalPObjectId, createLocalPObjectId } from "../../../pool";
+import { createColumnDiscoveredId } from "./discovered_column";
+import { createColumnFilteredId } from "./filtered_column";
+import { peelJsonLayers, type ColumnUniversalId } from "./ids";
+
+/**
+ * The escape-layer peeler.
+ *
+ * It is the one definition of "how a value can be hiding inside a string", and the reference
+ * detector in `pl-middle-layer` (`inferAllReferencedBlocks`) is built on it — a block id can
+ * sit under any number of `JSON.stringify` passes, and a walk over object properties reaches
+ * none of them. It deliberately says nothing about which values count as identifiers; the
+ * cases below are identifiers only because that is what the callers care about.
+ */
+
+const leaf = (blockId: string, name: string) =>
+  createGlobalPObjectId(blockId, name) as ColumnUniversalId;
+
+describe("peelJsonLayers", () => {
+  test("a canonical id is layer zero — encoded once, and that once is the id itself", () => {
+    const id = leaf("samples", "reads");
+
+    expect(peelJsonLayers(id)).toEqual({
+      value: { __isRef: true, blockId: "samples", name: "reads" },
+      layers: 0,
+    });
+  });
+
+  test("each extra stringify pass is one more layer", () => {
+    const id = leaf("samples", "reads");
+
+    expect(peelJsonLayers(JSON.stringify(id))?.layers).toBe(1);
+    expect(peelJsonLayers(JSON.stringify(JSON.stringify(id)))?.layers).toBe(2);
+  });
+
+  test("the value at the bottom is the same however deep it was", () => {
+    const id = leaf("samples", "reads");
+    const bottom = { __isRef: true, blockId: "samples", name: "reads" };
+
+    expect(peelJsonLayers(JSON.stringify(JSON.stringify(id)))?.value).toEqual(bottom);
+  });
+
+  test("a nested identifier peels to its own outer key, not to the leaf", () => {
+    // Wrapper forms nest by *string*, so peeling reaches the outermost key and stops. Walking
+    // further in is the caller's business, and no caller does — which is the point.
+    const filtered = createColumnFilteredId({
+      source: createColumnDiscoveredId({ column: leaf("samples", "clonotypes") }),
+      axisFilters: [[0, "IGH"]],
+    });
+
+    const peeled = peelJsonLayers(filtered);
+
+    expect(peeled?.layers).toBe(0);
+    expect(peeled?.value).toMatchObject({ __isFiltered: true });
+  });
+
+  test("a local leaf peels too, though it carries no marker at all", () => {
+    // The gate must not demand `__isRef`: a filtered id whose innermost leaf is local has
+    // none, and a peeler that required one would miss the whole chain.
+    const id = createLocalPObjectId(["pf", "byChain"], "abundance");
+
+    expect(peelJsonLayers(id)?.value).toEqual({
+      resolvePath: ["pf", "byChain"],
+      name: "abundance",
+    });
+  });
+
+  test("an ordinary string is not JSON and stops at the first character", () => {
+    for (const value of ["samples", "", "not json", "1.0", "yes"]) {
+      expect(peelJsonLayers(value)).toBeUndefined();
+    }
+  });
+
+  test("a quoted string that only ever yields strings is refused", () => {
+    // `"\"abc\""` peels to `abc`, which is not JSON — there is no encoded value in there, so
+    // there is nothing for a caller to look at.
+    expect(peelJsonLayers(JSON.stringify("abc"))).toBeUndefined();
+  });
+
+  test("malformed JSON is refused rather than thrown", () => {
+    expect(peelJsonLayers('{"__isRef": true')).toBeUndefined();
+  });
+
+  test("a JSON array or scalar is a value like any other", () => {
+    // Nothing here is identifier-specific: the peeler answers "what was encoded", full stop.
+    expect(peelJsonLayers("[1,2]")).toBeUndefined();
+    expect(peelJsonLayers('{"a":1}')).toEqual({ value: { a: 1 }, layers: 0 });
+  });
+});

package/src/drivers/pframe/spec/ids.ts

@@ -8,6 +8,8 @@ import {
 } from "./filtered_column";
 import {
   createPObjectId,
+  isGlobalPObjectKey,
+  isLocalPObjectKey,
   isPObjectId,
   isPObjectKey,
   LocalPObjectKey,
@@ -28,7 +30,7 @@ import {
   type ColumnOverriddenId,
   type ColumnOverriddenKey,
 } from "./overridden";
-import { canonicalizeJson } from "../../../json";
+import { canonicalizeJson, parseJsonSafely } from "../../../json";
 import { AxisSpec, PColumnSpec } from "./spec";
 import { isString } from "es-toolkit";
 
@@ -97,6 +99,194 @@ export function parseColumnIdSafely(
   }
 }
 
+/** Whether `value` is any of the five key forms a {@link ColumnUniversalId} serializes. */
+export function isColumnUniversalKey(value: unknown): value is ColumnUniversalKey {
+  return (
+    isPObjectKey(value) ||
+    isColumnFilteredKey(value) ||
+    isColumnDiscoveredKey(value) ||
+    isColumnOverriddenKey(value)
+  );
+}
+
+export function isColumnUniversalId(value: unknown): value is ColumnUniversalId {
+  const key = isString(value) ? parseJsonSafely(value, false) : false;
+  return key === false ? false : isColumnUniversalKey(key);
+}
+
+/**
+ * A JSON string with its escape padding taken off, and how many passes that took.
+ *
+ * `layers` counts the `JSON.stringify` passes *above* the encoded value: a canonical id
+ * is `layers: 0`, the same id run through `JSON.stringify` once more is `layers: 1`. Keep
+ * it to put the value back the way it was found.
+ */
+export type PeeledJsonLayers = {
+  readonly value: unknown;
+  readonly layers: number;
+};
+
+/**
+ * Take a value out of however many `JSON.stringify` passes wrapped it, or `undefined`
+ * when `s` is not JSON at all.
+ *
+ * The one definition of "how a value can be hiding inside a string" — a block id can sit
+ * under several layers of escaping, and a walk over object properties reaches none of
+ * them. Callers differ in what they do at the bottom (this deliberately says nothing
+ * about which values count as identifiers), but they must agree on the mechanics, or
+ * "what carries a block id" ends up with two answers that drift.
+ *
+ * The gate is cheap and does NOT require any marker in the body: a filtered id whose
+ * innermost leaf is a {@link LocalPObjectKey} carries no `__isRef`, so demanding one
+ * would miss it.
+ */
+export function peelJsonLayers(s: string): PeeledJsonLayers | undefined {
+  let current = s;
+  let layers = 0;
+  for (;;) {
+    const c0 = current.charCodeAt(0);
+    if (c0 !== 0x7b /* { */ && c0 !== 0x22 /* " */) return undefined;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(current);
+    } catch {
+      return undefined;
+    }
+    // A pass that yielded another string was escape padding, so peel again. The string
+    // is strictly shorter each time, which is what bounds the loop.
+    if (isString(parsed)) {
+      if (parsed.length >= current.length) return undefined;
+      current = parsed;
+      layers++;
+      continue;
+    }
+    return { value: parsed, layers };
+  }
+}
+
+/**
+ * Rewrite every block id buried inside a column id.
+ *
+ * A {@link GlobalPObjectKey} leaf names its upstream by block id, and the wrapper key forms
+ * nest by *string* id rather than by object — so a block id can sit under several layers of
+ * JSON escaping, and `queriesQualifications` carries one in a map *key*. A caller that only
+ * walks object properties never reaches any of them, which is why moving a column id between
+ * projects needs this rather than a generic walk.
+ *
+ * Recursion re-canonicalizes bottom-up, so every level is canonical afterwards — including
+ * the rebuilt `queriesQualifications`, whose keys the canonical form sorts. That is the
+ * property a textual rewrite cannot have: redirecting an id that is a map key changes what
+ * the sorted order should be, and only rebuilding restores it.
+ *
+ * Returns the input itself when no block id changed, so a caller mapping ids to themselves
+ * gets its value back byte-for-byte and never re-serializes a stored id. Any `string` is
+ * accepted for the same reason: a caller sweeping a params object cannot know which of its
+ * strings are ids, and one that is not is returned as-is.
+ *
+ * @param remapBlockId old block id → new block id. Throw from it to reject an id that cannot
+ *   be mapped.
+ */
+export function remapColumnIdBlockIds<T extends string | ColumnUniversalKey>(
+  id: T,
+  remapBlockId: (blockId: string) => string,
+): T {
+  const remapped = isString(id) ? remapIdString(id, remapBlockId) : remapKey(id, remapBlockId);
+  return (remapped ?? id) as T;
+}
+
+/**
+ * The string half of {@link remapColumnIdBlockIds}. `undefined` means "nothing to change",
+ * which is what keeps an unaffected id from being re-serialized.
+ *
+ * Escape padding is peeled and put back, so an id that reached params through an extra
+ * `JSON.stringify` is rewritten in place and comes back wrapped as it was found. A string
+ * that does not peel to a column key is left alone: params hold ordinary strings too.
+ */
+function remapIdString(id: string, remapBlockId: (blockId: string) => string): string | undefined {
+  const peeled = peelJsonLayers(id);
+  if (peeled === undefined || !isColumnUniversalKey(peeled.value)) return undefined;
+
+  const remappedKey = remapKey(peeled.value, remapBlockId);
+  if (remappedKey === undefined) return undefined;
+
+  let rebuilt: string = stringifyColumnId(remappedKey);
+  for (let layer = 0; layer < peeled.layers; layer++) rebuilt = JSON.stringify(rebuilt);
+  return rebuilt;
+}
+
+/** The key half of {@link remapColumnIdBlockIds}. `undefined` means "nothing to change". */
+function remapKey(
+  key: ColumnUniversalKey,
+  remapBlockId: (blockId: string) => string,
+): ColumnUniversalKey | undefined {
+  if (isGlobalPObjectKey(key)) {
+    const blockId = remapBlockId(key.blockId);
+    return blockId === key.blockId ? undefined : { ...key, blockId };
+  }
+
+  // A local leaf names its column by a path inside its own block — no block id.
+  if (isLocalPObjectKey(key)) return undefined;
+
+  if (isColumnFilteredKey(key)) {
+    const source = remapIdString(key.source, remapBlockId);
+    return source === undefined ? undefined : { ...key, source: source as ColumnUniversalId };
+  }
+
+  if (isColumnOverriddenKey(key)) {
+    const source = remapIdString(key.source, remapBlockId);
+    // Remapping preserves the id's shape, so `source` is still not an Overridden id.
+    return source === undefined
+      ? undefined
+      : { ...key, source: source as ColumnOverriddenKey["source"] };
+  }
+
+  if (isColumnDiscoveredKey(key)) return remapDiscoveredKey(key, remapBlockId);
+
+  throw new Error(
+    `remapColumnIdBlockIds: unrecognized column id structure: ${JSON.stringify(key)}`,
+  );
+}
+
+/**
+ * Discovered is the only key form carrying more than one nested id: the column it
+ * discovered, one per linker hop, and one per entry in `queriesQualifications` — where the
+ * id is the map key, not the value.
+ */
+function remapDiscoveredKey(
+  key: ColumnDiscoveredKey,
+  remapBlockId: (blockId: string) => string,
+): ColumnDiscoveredKey | undefined {
+  const column = remapIdString(key.column, remapBlockId);
+
+  let pathChanged = false;
+  const path = key.path?.map((item) => {
+    const itemColumn = remapIdString(item.column, remapBlockId);
+    if (itemColumn === undefined) return item;
+    pathChanged = true;
+    return { ...item, column: itemColumn as ColumnUniversalId };
+  });
+
+  let queriesChanged = false;
+  const queriesQualifications =
+    key.queriesQualifications &&
+    (Object.fromEntries(
+      Object.entries(key.queriesQualifications).map(([queryId, qualifications]) => {
+        const remappedId = remapIdString(queryId, remapBlockId);
+        if (remappedId === undefined) return [queryId, qualifications];
+        queriesChanged = true;
+        return [remappedId, qualifications];
+      }),
+    ) as ColumnDiscoveredKey["queriesQualifications"]);
+
+  if (column === undefined && !pathChanged && !queriesChanged) return undefined;
+  return {
+    ...key,
+    ...(column !== undefined ? { column: column as ColumnUniversalId } : {}),
+    ...(pathChanged ? { path } : {}),
+    ...(queriesChanged ? { queriesQualifications } : {}),
+  };
+}
+
 /**
  * Walk a rich column id down to its terminal leaf {@link PObjectId}.
  */

package/src/index.ts

@@ -23,3 +23,4 @@ export * from "./services";
 export * from "./pool_entry";
 export * from "./project_id";
 export * from "./columns";
+export * from "./template";

package/src/plid.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { base32Encode } from "./base32_encode";
+import { Branded } from "@milaboratories/helpers";
 
 /** Number of raw bytes in the PlId. */
 export const PlIdBytes = 15;
@@ -9,19 +10,18 @@ export const PlIdLength = 24; // = 15 bytes * 8 bits / 5 bits per char in base32
 export const PlId = z
   .string()
   .length(PlIdLength)
-  .regex(/[ABCDEFGHIJKLMNOPQRSTUVWXYZ234567]/) // RFC4648
-  .brand("PlId");
-export type PlId = z.infer<typeof PlId>;
+  .regex(/[ABCDEFGHIJKLMNOPQRSTUVWXYZ234567]/); // RFC4648
+export type PlId = Branded<z.infer<typeof PlId>, "PlId">;
 
 export function uniquePlId(): PlId {
   const data = new Uint8Array(PlIdBytes);
   crypto.getRandomValues(data);
-  return PlId.parse(base32Encode(data, "RFC4648"));
+  return PlId.parse(base32Encode(data, "RFC4648")) as PlId;
 }
 
 export function plId(bytes: Uint8Array): PlId {
   if (bytes.length !== PlIdBytes) throw new Error(`Wrong number of bytes: ${bytes.length}`);
-  return PlId.parse(base32Encode(bytes, "RFC4648"));
+  return PlId.parse(base32Encode(bytes, "RFC4648")) as PlId;
 }
 
 export async function digestPlId(data: string): Promise<PlId> {

package/src/template/index.ts

@@ -0,0 +1,4 @@
+export * from "./kind_selector";
+export * from "./project_template_v1";
+export * from "./template_ref_form";
+export * from "./template_relocate";

package/src/template/kind_selector.ts

@@ -0,0 +1,126 @@
+import type { Branded } from "@milaboratories/helpers";
+import type { BlockKindReference } from "../bmodel/block_kind_ref";
+import { parseKindRef, splitVersionedName } from "../bmodel/block_kind_ref";
+
+/**
+ * Version-selection tier of a template entry's `kind` field.
+ *
+ * - `exact` — `X.Y.Z`: this version and no other.
+ * - `patch` — `~X.Y.Z`: patch floor, behavior frozen.
+ * - `minor` — `^X.Y.Z`: minor floor, behavior floats.
+ */
+export type KindSelectorOp = "exact" | "patch" | "minor";
+
+/** The version half of a `{name}@{selector}` kind reference, split into parts. */
+export type KindSelector = {
+  readonly op: KindSelectorOp;
+  readonly version: string;
+};
+
+/**
+ * On-wire reference to a *set* of block kind versions: `{name}@{selector}`, e.g.
+ * `@platforma-open/milaboratories.mixcr-clonotyping.kind@~1.2.0`.
+ *
+ * The template-file form of a kind reference, and the only form the
+ * `template-v1` schema accepts in an entry's `kind` field. It is the same string
+ * shape as {@link BlockKindReference} widened by the `~`/`^` tiers, but branded
+ * separately so a *resolved* kind reference is never silently passed where a
+ * selector is expected, or vice versa. Widen an exact reference explicitly with
+ * {@link kindReferenceToSelectorReference}.
+ */
+export type BlockKindSelectorReference = Branded<string, "BlockKindSelectorReference">;
+
+/** `X.Y.Z` with optional semver prerelease and build metadata. */
+const semVerRegex =
+  /^\d+\.\d+\.\d+(?:-[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?(?:\+[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?$/;
+
+/**
+ * Split a raw selector string (`1.2.0`, `~1.2.0`, `^1.2.0`) into its parts.
+ *
+ * The version is validated as `X.Y.Z`, so a range that is legal npm but not part
+ * of the kind grammar (`>=1.0.0`, `1.x`, `latest`) is rejected here rather than
+ * reaching resolution. Note the deliberate divergence from
+ * `tools/block-tools`'s `parseSelector`, which additionally tolerates a leading
+ * `@` as `exact`: after the `{name}@{selector}` split a leading `@` can only
+ * come from a doubled separator, which is malformed.
+ *
+ * Mapping a selector onto a concrete version is resolution, not parsing, and
+ * lives with the resolver (`kind_resolver.selectorToRange`).
+ *
+ * @throws if the version part is not `X.Y.Z`
+ */
+export function parseKindSelector(raw: string): KindSelector {
+  const s = raw.trim();
+  const op: KindSelectorOp = s.startsWith("~") ? "patch" : s.startsWith("^") ? "minor" : "exact";
+  const version = op === "exact" ? s : s.slice(1);
+  if (!semVerRegex.test(version)) {
+    throw new Error(
+      `Malformed kind version selector (expected 'X.Y.Z', '~X.Y.Z' or '^X.Y.Z'): ${raw}`,
+    );
+  }
+  return { op, version };
+}
+
+/** Render a {@link KindSelector} back to its on-wire string. */
+export function formatKindSelector(sel: KindSelector): string {
+  switch (sel.op) {
+    case "exact":
+      return sel.version;
+    case "patch":
+      return `~${sel.version}`;
+    case "minor":
+      return `^${sel.version}`;
+  }
+}
+
+/**
+ * Split a {@link BlockKindSelectorReference} into `{ name, selector }`.
+ *
+ * @throws if the reference carries no version segment, or the selector is
+ *   outside the `X.Y.Z` / `~X.Y.Z` / `^X.Y.Z` grammar
+ */
+export function parseKindSelectorReference(ref: BlockKindSelectorReference): {
+  name: string;
+  selector: KindSelector;
+} {
+  const { name, version } = splitVersionedName(ref, "kind selector reference", "{name}@{selector}");
+  return { name, selector: parseKindSelector(version) };
+}
+
+/**
+ * Compose a {@link BlockKindSelectorReference} from a name and selector.
+ *
+ * A formatter, not a validator — pass a selector that came from
+ * {@link parseKindSelector} or that you constructed from a known-good version.
+ */
+export function formatKindSelectorReference(k: {
+  name: string;
+  selector: KindSelector;
+}): BlockKindSelectorReference {
+  return `${k.name}@${formatKindSelector(k.selector)}` as BlockKindSelectorReference;
+}
+
+/**
+ * Widen a resolved {@link BlockKindReference} to its `exact`-tier selector form.
+ *
+ * The export direction: a block implements exactly one kind version, so export
+ * always emits `{name}@X.Y.Z`. Validates on the way through, so a
+ * malformed stored reference fails at the boundary rather than in the file.
+ */
+export function kindReferenceToSelectorReference(
+  ref: BlockKindReference,
+): BlockKindSelectorReference {
+  const { name, version } = parseKindRef(ref);
+  return formatKindSelectorReference({ name, selector: parseKindSelector(version) });
+}
+
+/** Whether `value` is a well-formed `{name}@{selector}` string. */
+export function isBlockKindSelectorReference(value: unknown): value is BlockKindSelectorReference {
+  if (typeof value !== "string") return false;
+  try {
+    parseKindSelectorReference(value as BlockKindSelectorReference);
+    return true;
+  } catch {
+    return false;
+  }
+}