@milaboratories/pl-model-common 1.47.3 → 1.49.0

package/dist/template/template_relocate.d.ts

@@ -0,0 +1,36 @@
+//#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 — an axis filter, a domain this package can see belongs to an identifier it
+ * knows — from being rewritten along with it, and what re-sorts a qualifications map whose
+ * keys are identifiers.
+ *
+ * A domain reached on its own is the exception, and `relocateDomain` below says why: an axis is
+ * qualified by the block that produced it. Only the domain keys known to name a block are
+ * repointed — matching an entry id is not on its own evidence of a reference.
+ *
+ * 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
+ */
+export declare function relocateBlockIds<T>(params: T, blockIds: ReadonlyMap<string, string>): T;
+//#endregion
+//# 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoCgB,iBAAiB,GAAG,QAAQ,GAAG,UAAU,8BAA8B"}

package/dist/template/template_relocate.js

@@ -0,0 +1,67 @@
+import { BlockScopedDomain } from "../drivers/pframe/spec/spec.js";
+import { isColumnUniversalKey, remapColumnIdBlockIds } from "../drivers/pframe/spec/ids.js";
+import "../drivers/index.js";
+import { isPlainObject } from "es-toolkit";
+//#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 — an axis filter, a domain this package can see belongs to an identifier it
+* knows — from being rewritten along with it, and what re-sorts a qualifications map whose
+* keys are identifiers.
+*
+* A domain reached on its own is the exception, and `relocateDomain` below says why: an axis is
+* qualified by the block that produced it. Only the domain keys known to name a block are
+* repointed — matching an entry id is not on its own evidence of a reference.
+*
+* 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), key === "domain" && isPlainObject(value) ? relocateDomain(value) : walk(value)]));
+		return node;
+	};
+	/**
+	* The block-naming entries of a domain, repointed at the project being built: an axis a block
+	* produced names that block in its domain, so those are references like any other.
+	*
+	* Only the keys {@link BlockScopedDomain} lists, because a template's entry ids are arbitrary
+	* non-empty strings — a hand-written template may name an entry `closest`, and a qualifier
+	* reading `closest` is not a reference to it. Matching the map is not on its own enough to
+	* tell one from the other; the key is.
+	*
+	* Reached only from the generic object case — inside an identifier this package recognizes a
+	* domain is spec data and stays as it is, which is what keeps an overridden column's
+	* `specOverrides.domain` untouched.
+	*/
+	const relocateDomain = (domain) => Object.fromEntries(Object.entries(domain).map(([key, value]) => [key, typeof value === "string" && BlockScopedDomain.has(key) ? remapBlockId(value) : walk(value)]));
+	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 { isPlainObject } from \"es-toolkit\";\n\nimport { BlockScopedDomain, 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 — an axis filter, a domain this package can see belongs to an identifier it\n * knows — from being rewritten along with it, and what re-sorts a qualifications map whose\n * keys are identifiers.\n *\n * A domain reached on its own is the exception, and `relocateDomain` below says why: an axis is\n * qualified by the block that produced it. Only the domain keys known to name a block are\n * repointed — matching an entry id is not on its own evidence of a reference.\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          key === \"domain\" && isPlainObject(value) ? relocateDomain(value) : walk(value),\n        ]),\n      );\n    }\n\n    return node;\n  };\n\n  /**\n   * The block-naming entries of a domain, repointed at the project being built: an axis a block\n   * produced names that block in its domain, so those are references like any other.\n   *\n   * Only the keys {@link BlockScopedDomain} lists, because a template's entry ids are arbitrary\n   * non-empty strings — a hand-written template may name an entry `closest`, and a qualifier\n   * reading `closest` is not a reference to it. Matching the map is not on its own enough to\n   * tell one from the other; the key is.\n   *\n   * Reached only from the generic object case — inside an identifier this package recognizes a\n   * domain is spec data and stays as it is, which is what keeps an overridden column's\n   * `specOverrides.domain` untouched.\n   */\n  const relocateDomain = (domain: Record<string, unknown>): Record<string, unknown> =>\n    Object.fromEntries(\n      Object.entries(domain).map(([key, value]) => [\n        key,\n        typeof value === \"string\" && BlockScopedDomain.has(key) ? remapBlockId(value) : walk(value),\n      ]),\n    );\n\n  return walk(params) as T;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,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,QAAQ,YAAY,cAAc,KAAK,IAAI,eAAe,KAAK,IAAI,KAAK,KAAK,CAC/E,CAAC,CACH;EAGF,OAAO;CACT;;;;;;;;;;;;;;CAeA,MAAM,kBAAkB,WACtB,OAAO,YACL,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CAC3C,KACA,OAAO,UAAU,YAAY,kBAAkB,IAAI,GAAG,IAAI,aAAa,KAAK,IAAI,KAAK,KAAK,CAC5F,CAAC,CACH;CAEF,OAAO,KAAK,MAAM;AACpB"}

package/dist/utag.d.ts

@@ -1,8 +1,7 @@
 import { AuthorMarker } from "./author_marker.js";
-
 //#region src/utag.d.ts
 /** Value returned for changing states supporting reactive listening for changes */
-interface ValueWithUTag<V> {
+export interface ValueWithUTag<V> {
   /** Value snapshot. */
   readonly value: V;
   /**
@@ -14,9 +13,8 @@ interface ValueWithUTag<V> {
    * */
   readonly uTag: string;
 }
-interface ValueWithUTagAndAuthor<V> extends ValueWithUTag<V> {
+export interface ValueWithUTagAndAuthor<V> extends ValueWithUTag<V> {
   readonly author?: AuthorMarker;
 }
 //#endregion
-export { ValueWithUTag, ValueWithUTagAndAuthor };
 //# sourceMappingURL=utag.d.ts.map

package/dist/utag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utag.d.ts","names":[],"sources":["../src/utag.ts"],"mappings":";;;;UAGiB,aAAA;EAAA;EAAA,SAEN,KAAA,EAAO,CAAC;EAFW;;;;;;;EAAA,SAWnB,IAAA;AAAA;AAAA,UAGM,sBAAA,YAAkC,aAAA,CAAc,CAAA;EAAA,SACtD,MAAA,GAAS,YAAA;AAAA"}
+{"version":3,"file":"utag.d.ts","names":[],"sources":["../src/utag.ts"],"mappings":";;;iBAGiB,cAAc;;WAEpB,OAAO;;;;;;;;WASP;;iBAGM,uBAAuB,WAAW,cAAc;WACtD,SAAS"}

package/dist/util.d.ts

@@ -1,10 +1,9 @@
 //#region src/util.d.ts
-declare function assertNever(x: never): never;
+export declare function assertNever(x: never): never;
 /**
  * Return unique entries of the array by the provided id
  * For each id, the last entry is kept
  */
-declare function uniqueBy<T>(array: T[], makeId: (entry: T) => string): T[];
+export declare function uniqueBy<T>(array: T[], makeId: (entry: T) => string): T[];
 //#endregion
-export { assertNever, uniqueBy };
 //# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","names":[],"sources":["../src/util.ts"],"mappings":";iBAAgB,WAAA,CAAY,CAAQ;AAApC;;;;AAAA,iBAQgB,QAAA,IAAY,KAAA,EAAO,CAAA,IAAK,MAAA,GAAS,KAAA,EAAO,CAAA,cAAe,CAAA"}
+{"version":3,"file":"util.d.ts","names":[],"sources":["../src/util.ts"],"mappings":";wBAAgB,YAAY;;;;;wBAQZ,SAAS,GAAG,OAAO,KAAK,SAAS,OAAO,eAAe"}

package/dist/value_or_error.d.ts

@@ -1,12 +1,11 @@
 //#region src/value_or_error.d.ts
-type ValueOrError<V, E> = {
+export type ValueOrError<V, E> = {
   ok: true;
   value: V;
 } | {
   ok: false;
   error: E;
 };
-declare function mapValueInVOE<V1, V2, E>(voe: ValueOrError<V1, E>, cb: (value: V1) => V2): ValueOrError<V2, E>;
+export declare function mapValueInVOE<V1, V2, E>(voe: ValueOrError<V1, E>, cb: (value: V1) => V2): ValueOrError<V2, E>;
 //#endregion
-export { ValueOrError, mapValueInVOE };
 //# sourceMappingURL=value_or_error.d.ts.map

package/dist/value_or_error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value_or_error.d.ts","names":[],"sources":["../src/value_or_error.ts"],"mappings":";KAAY,YAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,CAAC;AAAA;AAAA,iBAGE,aAAA,YACd,GAAA,EAAK,YAAA,CAAa,EAAA,EAAI,CAAA,GACtB,EAAA,GAAK,KAAA,EAAO,EAAA,KAAO,EAAA,GAClB,YAAA,CAAa,EAAA,EAAI,CAAA"}
+{"version":3,"file":"value_or_error.d.ts","names":[],"sources":["../src/value_or_error.ts"],"mappings":";YAAY,aAAa,GAAG;EAEtB;EACA,OAAO;;EAGP;EACA,OAAO;;wBAGG,cAAc,IAAI,IAAI,GACpC,KAAK,aAAa,IAAI,IACtB,KAAK,OAAO,OAAO,KAClB,aAAa,IAAI"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-common",
-  "version": "1.47.3",
+  "version": "1.49.0",
   "description": "Platforma SDK Model",
   "files": [
     "./dist/**/*",
@@ -25,11 +25,11 @@
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.1.3",
-    "typescript": "~5.9.3",
+    "typescript": "7.0.2",
     "vitest": "^4.1.3",
-    "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-builder": "1.6.1",
-    "@milaboratories/ts-configs": "1.3.1"
+    "@milaboratories/build-configs": "2.0.1",
+    "@milaboratories/ts-builder": "1.7.2",
+    "@milaboratories/ts-configs": "1.4.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}.
  */