@milaboratories/pl-model-common 1.47.2 → 1.48.0

package/dist/template/template_ref_form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_ref_form.d.ts","names":[],"sources":["../../src/template/template_ref_form.ts"],"mappings":";;AA6BA;;;;AAIe;AAUf;;;;;;;;AAAuE;AAsCvE;;;;;;;;;AAAmD;;;KApDvC,aAAA;oEAED,KAAA;WAEA,IAAI;AAAA;;;;;;;;iBAUC,eAAA,CAAgB,KAAA,YAAiB,KAAA,IAAS,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCvD,kBAAA,IAAsB,MAAA,EAAQ,CAAA,GAAI,CAAC"}

package/dist/template/template_ref_form.js

@@ -0,0 +1,72 @@
+//#region src/template/template_ref_form.ts
+/**
+* Whether `value` is a reference in the readable spelling.
+*
+* Exact about its keys, because the shape lives inside params a kind owns: `{ block, name }`
+* and nothing else. A value carrying `__isRef` is a `PlRef` already and is not this — the two
+* are told apart by shape and never overlap.
+*/
+function isTemplatePlRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length !== 2 || !keys.includes("block") || !keys.includes("name")) return false;
+	const { block, name } = value;
+	return typeof block === "string" && typeof name === "string";
+}
+/**
+* Expand every readable reference form in `params` into the form the system stores.
+*
+* Named for the job and not for today's only case. One readable form exists so far —
+* {@link TemplatePlRef}, the leaf reference — and the rest of the identifier system is meant to
+* follow: `TemplateCUId` / `TemplateCUKey`, readable spellings of the filtered, discovered and
+* overridden column keys, whose long forms are far worse to type than a `PlRef`'s.
+*
+* **Adding one is a recognizer plus an expander**, checked before the generic object case, the
+* way `isTemplatePlRef` / `expandTemplatePlRef` are below. Two rules a nesting form has to
+* respect, both consequences of how the stored forms are built:
+*
+* - **Expand bottom-up.** A wrapper key holds its source as a canonical *string*, not as an
+*   object, so the inner reference must be expanded and serialized before the outer key can be
+*   assembled. Descending after building the outer form would leave the inner spelling inside a
+*   string nothing looks at again.
+* - **Canonicalize what you build.** An identifier IS its canonical string; a key assembled
+*   with keys in another order is a different identifier for the same column.
+*
+* What comes out names its upstreams by template-local entry id — the same thing a `PlRef` in a
+* template file means. Turning those into the ids of real blocks is {@link relocateBlockIds},
+* which runs right after and treats an expanded reference exactly like one the file spelled out
+* in full.
+*
+* Needs nothing but the params. That is a property of the forms, not a coincidence: a readable
+* spelling carries the same information as the form it stands for, so expansion is a rewrite and
+* never a lookup. A form that needed the document to expand — a reference by position, say —
+* would have to be resolved somewhere that knows the document, and would drag that knowledge
+* into every caller of this. Keep them information-preserving.
+*/
+function expandTemplateRefs(params) {
+	const walk = (node) => {
+		if (isTemplatePlRef(node)) return expandTemplatePlRef(node);
+		if (Array.isArray(node)) return node.map(walk);
+		if (typeof node === "object" && node !== null) return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));
+		return node;
+	};
+	return walk(params);
+}
+/**
+* The leaf form's expander: `{ block, name }` becomes the `PlRef` it stands for.
+*
+* An id naming no entry is passed through, like a hand-written `PlRef` would be: an id naming
+* nothing and an id naming an entry created later are indistinguishable, and both are meant to
+* arrive at a block that reports itself as missing references.
+*/
+function expandTemplatePlRef(ref) {
+	return {
+		__isRef: true,
+		blockId: ref.block,
+		name: ref.name
+	};
+}
+//#endregion
+export { expandTemplateRefs, isTemplatePlRef };
+
+//# sourceMappingURL=template_ref_form.js.map

package/dist/template/template_ref_form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_ref_form.js","names":[],"sources":["../../src/template/template_ref_form.ts"],"sourcesContent":["import type { PlRef } from \"../ref\";\n\n/**\n * A reference as a person writes it: the entry it points at, and the output name.\n *\n * The readable spelling of a {@link PlRef}, and input only. The two say the same thing, and\n * differ only in what a reader has to carry:\n *\n * ```yaml\n * # what an export writes, and what a block holds\n * sources:\n *   - __isRef: true\n *     blockId: samples\n *     name: numbers\n *\n * # the same reference, written by hand\n * sources:\n *   - { block: samples, name: numbers }\n * ```\n *\n * `block` is a template-local entry id — the same thing a `PlRef`'s `blockId` holds inside a\n * template file. Nothing else: this form exists to drop the `__isRef` marker and the word\n * `blockId`, not to introduce a second way of naming an entry.\n *\n * Export never emits it — a block holds live `PlRef`s and a template holds what the block\n * holds. It is expanded on the way in, inside the block's own bundle and before the kind's\n * parser runs, so a kind's params contract is written against `PlRef` alone and never learns\n * this type exists.\n */\nexport type TemplatePlRef = {\n  /** The template-local id of the entry this points at. */\n  readonly block: string;\n  /** The upstream output's name, exactly as a `PlRef` spells it. */\n  readonly name: string;\n};\n\n/**\n * Whether `value` is a reference in the readable spelling.\n *\n * Exact about its keys, because the shape lives inside params a kind owns: `{ block, name }`\n * and nothing else. A value carrying `__isRef` is a `PlRef` already and is not this — the two\n * are told apart by shape and never overlap.\n */\nexport function isTemplatePlRef(value: unknown): value is TemplatePlRef {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n  const keys = Object.keys(value);\n  if (keys.length !== 2 || !keys.includes(\"block\") || !keys.includes(\"name\")) return false;\n  const { block, name } = value as { block: unknown; name: unknown };\n  return typeof block === \"string\" && typeof name === \"string\";\n}\n\n/**\n * Expand every readable reference form in `params` into the form the system stores.\n *\n * Named for the job and not for today's only case. One readable form exists so far —\n * {@link TemplatePlRef}, the leaf reference — and the rest of the identifier system is meant to\n * follow: `TemplateCUId` / `TemplateCUKey`, readable spellings of the filtered, discovered and\n * overridden column keys, whose long forms are far worse to type than a `PlRef`'s.\n *\n * **Adding one is a recognizer plus an expander**, checked before the generic object case, the\n * way `isTemplatePlRef` / `expandTemplatePlRef` are below. Two rules a nesting form has to\n * respect, both consequences of how the stored forms are built:\n *\n * - **Expand bottom-up.** A wrapper key holds its source as a canonical *string*, not as an\n *   object, so the inner reference must be expanded and serialized before the outer key can be\n *   assembled. Descending after building the outer form would leave the inner spelling inside a\n *   string nothing looks at again.\n * - **Canonicalize what you build.** An identifier IS its canonical string; a key assembled\n *   with keys in another order is a different identifier for the same column.\n *\n * What comes out names its upstreams by template-local entry id — the same thing a `PlRef` in a\n * template file means. Turning those into the ids of real blocks is {@link relocateBlockIds},\n * which runs right after and treats an expanded reference exactly like one the file spelled out\n * in full.\n *\n * Needs nothing but the params. That is a property of the forms, not a coincidence: a readable\n * spelling carries the same information as the form it stands for, so expansion is a rewrite and\n * never a lookup. A form that needed the document to expand — a reference by position, say —\n * would have to be resolved somewhere that knows the document, and would drag that knowledge\n * into every caller of this. Keep them information-preserving.\n */\nexport function expandTemplateRefs<T>(params: T): T {\n  const walk = (node: unknown): unknown => {\n    // One line per readable form, before the generic object case: a form IS an object, and\n    // descending into one would rewrite its parts instead of expanding it as a whole.\n    if (isTemplatePlRef(node)) return expandTemplatePlRef(node);\n\n    if (Array.isArray(node)) return node.map(walk);\n\n    if (typeof node === \"object\" && node !== null) {\n      return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));\n    }\n\n    return node;\n  };\n  return walk(params) as T;\n}\n\n/**\n * The leaf form's expander: `{ block, name }` becomes the `PlRef` it stands for.\n *\n * An id naming no entry is passed through, like a hand-written `PlRef` would be: an id naming\n * nothing and an id naming an entry created later are indistinguishable, and both are meant to\n * arrive at a block that reports itself as missing references.\n */\nfunction expandTemplatePlRef(ref: TemplatePlRef): PlRef {\n  return { __isRef: true, blockId: ref.block, name: ref.name };\n}\n"],"mappings":";;;;;;;;AA2CA,SAAgB,gBAAgB,OAAwC;CACtE,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG,OAAO;CAChF,MAAM,OAAO,OAAO,KAAK,KAAK;CAC9B,IAAI,KAAK,WAAW,KAAK,CAAC,KAAK,SAAS,OAAO,KAAK,CAAC,KAAK,SAAS,MAAM,GAAG,OAAO;CACnF,MAAM,EAAE,OAAO,SAAS;CACxB,OAAO,OAAO,UAAU,YAAY,OAAO,SAAS;AACtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,mBAAsB,QAAc;CAClD,MAAM,QAAQ,SAA2B;EAGvC,IAAI,gBAAgB,IAAI,GAAG,OAAO,oBAAoB,IAAI;EAE1D,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO,KAAK,IAAI,IAAI;EAE7C,IAAI,OAAO,SAAS,YAAY,SAAS,MACvC,OAAO,OAAO,YAAY,OAAO,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;EAG9E,OAAO;CACT;CACA,OAAO,KAAK,MAAM;AACpB;;;;;;;;AASA,SAAS,oBAAoB,KAA2B;CACtD,OAAO;EAAE,SAAS;EAAM,SAAS,IAAI;EAAO,MAAM,IAAI;CAAK;AAC7D"}

package/dist/template/template_relocate.cjs

@@ -0,0 +1,46 @@
+const require_ids = require("../drivers/pframe/spec/ids.cjs");
+require("../drivers/index.cjs");
+//#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 require_ids.remapColumnIdBlockIds(node, remapBlockId);
+		if (require_ids.isColumnUniversalKey(node)) return require_ids.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]) => [require_ids.remapColumnIdBlockIds(key, remapBlockId), walk(value)]));
+		return node;
+	};
+	return walk(params);
+}
+//#endregion
+exports.relocateBlockIds = relocateBlockIds;
+
+//# sourceMappingURL=template_relocate.cjs.map

package/dist/template/template_relocate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_relocate.cjs","names":["remapColumnIdBlockIds","isColumnUniversalKey"],"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,OAAOA,YAAAA,sBAAsB,MAAM,YAAY;EAK7E,IAAIC,YAAAA,qBAAqB,IAAI,GAAG,OAAOD,YAAAA,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,CACzCA,YAAAA,sBAAsB,KAAK,YAAY,GACvC,KAAK,KAAK,CACZ,CAAC,CACH;EAGF,OAAO;CACT;CAEA,OAAO,KAAK,MAAM;AACpB"}

package/dist/template/template_relocate.d.ts

@@ -0,0 +1,32 @@
+//#region src/template/template_relocate.d.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
+ */
+declare function relocateBlockIds<T>(params: T, blockIds: ReadonlyMap<string, string>): T;
+//#endregion
+export { relocateBlockIds };
+//# sourceMappingURL=template_relocate.d.ts.map

package/dist/template/template_relocate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_relocate.d.ts","names":[],"sources":["../../src/template/template_relocate.ts"],"mappings":";;AA6BA;;;;;;;;;;;;;;;AAAwF;;;;;;;;;;;iBAAxE,gBAAA,IAAoB,MAAA,EAAQ,CAAA,EAAG,QAAA,EAAU,WAAA,mBAA8B,CAAA"}

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.2",
+  "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-configs": "1.3.1",
-    "@milaboratories/ts-builder": "1.6.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/data_types.ts

@@ -248,6 +248,18 @@ export interface WritePTableToFsOptions {
   path: string;
   format: PTableDownloadFormat;
   columnIndices: number[];
+  /**
+   * Optional header names aligned 1:1 with {@link columnIndices}. When provided,
+   * each is written verbatim — letting callers supply disambiguated labels the
+   * spec's intrinsic `pl7.app/label` may not carry. When omitted (or an
+   * individual entry is empty), the header falls back to the column's
+   * spec-derived label.
+   *
+   * Additive on purpose: the UI (ui-vue) and the desktop-app runtime version
+   * independently, so a newer UI must not send a shape an older runtime cannot
+   * read. Older runtimes ignore this field and use {@link columnIndices} alone.
+   */
+  headerNames?: string[];
   range?: TableRange;
   chunkSize?: number;
   includeHeader?: boolean;
@@ -281,4 +293,16 @@ export interface ExportPTableOptions {
   /** Unified indices of the columns to export, in output order
    * (axes first, then data columns). */
   columnIndices: number[];
+  /**
+   * Optional header names aligned 1:1 with {@link columnIndices}. When provided,
+   * each is written verbatim — letting callers supply disambiguated labels the
+   * spec's intrinsic `pl7.app/label` may not carry. When omitted (or an
+   * individual entry is empty), the header falls back to the column's
+   * spec-derived label.
+   *
+   * Additive on purpose: the UI (ui-vue) and the desktop-app runtime version
+   * independently, so a newer UI must not send a shape an older runtime cannot
+   * read. Older runtimes ignore this field and use {@link columnIndices} alone.
+   */
+  headerNames?: string[];
 }

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