@milaboratories/pl-model-common 1.48.0 → 1.49.0

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.48.0",
+  "version": "1.49.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/pl-error-like": "1.12.10",
-    "@milaboratories/helpers": "1.14.5"
+    "@milaboratories/helpers": "1.14.5",
+    "@milaboratories/pl-error-like": "1.12.10"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.1.3",
-    "typescript": "~5.9.3",
+    "typescript": "7.0.2",
     "vitest": "^4.1.3",
-    "@milaboratories/ts-configs": "1.4.0",
-    "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-builder": "1.7.0"
+    "@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/drivers/pframe/spec/spec.ts

@@ -83,6 +83,37 @@ export const Domain = {
   },
 } as const;
 
+/**
+ * Domain keys whose value is the id of a block, rather than a qualifier of the data.
+ *
+ * Applying a template repoints these at the blocks of the project being built: an axis a block
+ * produced names that block in its domain, so an axis left naming the exported-from project
+ * resolves to nothing. Listing the keys is what makes that safe — a template's entry ids are
+ * arbitrary non-empty strings, so a hand-written template may name an entry `closest`, and a
+ * qualifier that happens to read `closest` must not be mistaken for a reference to it.
+ *
+ * A key absent from here is simply left alone, which is the behaviour from before relocation
+ * reached domains at all. Adding one is therefore safe; omitting one costs only that a template
+ * carrying it applies still pointing at the project it came from.
+ */
+export const BlockScopedDomain: ReadonlySet<string> = new Set<string>([
+  "pl7.app/blockId",
+  "pl7.app/block",
+  "pl7.app/redefined-by",
+  "pl7.app/annotationRunId",
+  "pl7.app/clonotypeAnnotationRunId",
+  "pl7.app/clustering/blockId",
+  "pl7.app/umap/blockId",
+  "pl7.app/peptide/extractionRunId",
+  "pl7.app/repertoire/extractionRunId",
+  "pl7.app/antibodyVariantDesigner/designRunId",
+  "pl7.app/vdj/clonotypingRunId",
+  "pl7.app/vdj/clustering/blockId",
+  "pl7.app/vdj/integration/blockId",
+  "pl7.app/vdj/spatiotemporalAnalysis/blockId",
+  "pl7.app/vdj/libraryId",
+]);
+
 export type Domain = Metadata &
   Partial<{
     [Domain.Alphabet]: "nucleotide" | "aminoacid" | (string & {});

package/src/flags/block_flags.ts

@@ -13,7 +13,7 @@ export type BlockCodeFeatureFlags = Record<`supports${string}`, boolean | number
   Record<`requires${string}`, boolean | number | undefined>;
 
 /**
- * Known block flags. Flags are set during model compilation, see `BlockModel.create` for more details and for initial values.
+ * Known block flags. Flags are set during model compilation, see `BlockModelV3` feature flags for more details and for initial values.
  */
 export type BlockCodeKnownFeatureFlags = {
   readonly supportsLazyState?: boolean;

package/src/template/template_relocate.test.ts

@@ -109,6 +109,63 @@ describe("relocateBlockIds", () => {
     });
   });
 
+  describe("a domain that qualifies an axis", () => {
+    // An axis a block produced names that block in its domain — `pl7.app/sampleId` is
+    // qualified by the block that defined the samples, a clonotype key by the run that called
+    // the clonotypes. A chart bound to such an axis is bound to a reference.
+    const axis = (runId: string) => ({
+      kind: "axis",
+      name: "pl7.app/vdj/clonotypeKey",
+      type: "String",
+      domain: { "pl7.app/vdj/chain": "IGHeavy", "pl7.app/vdj/clonotypingRunId": runId },
+    });
+
+    test("an entry naming one of this template's entries is repointed", () => {
+      expect(relocateBlockIds({ x: axis("old") }, to("old", "new"))).toEqual({ x: axis("new") });
+    });
+
+    test("an entry that is not an entry id is left alone", () => {
+      // The map is the whole test of what is a reference: nothing reads a value's shape, so an
+      // ordinary qualifier cannot be caught by it.
+      const moved = relocateBlockIds({ x: axis("old") }, to("old", "new")) as {
+        x: { domain: Record<string, string> };
+      };
+
+      expect(moved.x.domain["pl7.app/vdj/chain"]).toBe("IGHeavy");
+    });
+
+    test("a domain naming a block this template does not carry keeps it", () => {
+      // The ordering rule again: an entry created later is not in the map yet, and the applied
+      // block reports itself as missing references rather than pointing at the wrong block.
+      expect(relocateBlockIds({ x: axis("later") }, to("earlier", "new"))).toEqual({
+        x: axis("later"),
+      });
+    });
+
+    test("a qualifier that merely collides with an entry id is NOT a reference", () => {
+      // Entry ids are validated only as non-empty strings, so a hand-written template names its
+      // entries readably. `algo` is a qualifier of the data, and an entry called `closest` does
+      // not make it one: matching the map is not evidence, the key is.
+      const params = { method: { domain: { algo: "closest", chain: "IGHeavy" } } };
+
+      expect(relocateBlockIds(params, to("closest", "new"))).toEqual(params);
+    });
+
+    test("a domain INSIDE a recognized identifier is still spec data, and stays", () => {
+      // The boundary of the rule above. This id is taken apart by the structural remapper,
+      // which never descends to the generic object case, so its overrides are untouched.
+      const id = createColumnOverriddenId({
+        source: leafId("old", "clonotypes"),
+        specOverrides: { domain: { producedBy: "old" } },
+      });
+
+      const moved = relocateBlockIds({ a: id }, to("old", "new")) as { a: string };
+      const key = JSON.parse(moved.a) as { specOverrides: { domain: unknown } };
+
+      expect(key.specOverrides.domain).toEqual({ producedBy: "old" });
+    });
+  });
+
   describe("depth", () => {
     test("three nested forms are repointed at the bottom and rebuilt on the way up", () => {
       const deep = (block: string) =>

package/src/template/template_relocate.ts

@@ -1,4 +1,6 @@
-import { isColumnUniversalKey, remapColumnIdBlockIds } from "../drivers";
+import { isPlainObject } from "es-toolkit";
+
+import { BlockScopedDomain, isColumnUniversalKey, remapColumnIdBlockIds } from "../drivers";
 
 /**
  * Point every column identifier in a block's params at the blocks of the project being built.
@@ -15,8 +17,13 @@ import { isColumnUniversalKey, remapColumnIdBlockIds } from "../drivers";
  *
  * 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.
+ * 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
@@ -49,7 +56,7 @@ export function relocateBlockIds<T>(params: T, blockIds: ReadonlyMap<string, str
       return Object.fromEntries(
         Object.entries(node).map(([key, value]) => [
           remapColumnIdBlockIds(key, remapBlockId),
-          walk(value),
+          key === "domain" && isPlainObject(value) ? relocateDomain(value) : walk(value),
         ]),
       );
     }
@@ -57,5 +64,26 @@ export function relocateBlockIds<T>(params: T, blockIds: ReadonlyMap<string, str
     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: Record<string, unknown>): Record<string, unknown> =>
+    Object.fromEntries(
+      Object.entries(domain).map(([key, value]) => [
+        key,
+        typeof value === "string" && BlockScopedDomain.has(key) ? remapBlockId(value) : walk(value),
+      ]),
+    );
+
   return walk(params) as T;
 }