@milaboratories/pl-model-common 1.36.1 → 1.37.0

package/src/ref.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { createPlRef, isPlRef, isPrimaryRef } from "./ref";
+import type { PObjectId } from "./pool/spec";
+import { createEnrichmentRef, createPlRef, isEnrichmentRef, isPlRef, isPrimaryRef } from "./ref";
 
 const sampleRef = createPlRef("block1", "output1", true);
+const sampleHit = "hit-1" as PObjectId;
+const sampleLinker = "linker-1" as PObjectId;
 
 describe("isPrimaryRef", () => {
   it("returns true for a valid PrimaryRef", () => {
@@ -31,7 +34,76 @@ describe("isPlRef", () => {
     expect(isPlRef({ __isPrimaryRef: "v1", column: sampleRef })).toBe(false);
   });
 
+  it("returns false for an EnrichmentRef", () => {
+    expect(isPlRef({ __isEnrichment: "v1", hit: sampleHit, path: [] })).toBe(false);
+  });
+
   it("returns true for a PlRef", () => {
     expect(isPlRef(sampleRef)).toBe(true);
   });
 });
+
+describe("isEnrichmentRef", () => {
+  it("returns true for an EnrichmentRef with empty path", () => {
+    expect(isEnrichmentRef({ __isEnrichment: "v1", hit: sampleHit, path: [] })).toBe(true);
+  });
+
+  it("returns true for an EnrichmentRef with linker steps", () => {
+    expect(
+      isEnrichmentRef({
+        __isEnrichment: "v1",
+        hit: sampleHit,
+        path: [{ type: "linker", linker: sampleLinker }],
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false for a PrimaryRef", () => {
+    expect(isEnrichmentRef({ __isPrimaryRef: "v1", column: sampleRef })).toBe(false);
+  });
+
+  it("returns false for a PlRef", () => {
+    expect(isEnrichmentRef(sampleRef)).toBe(false);
+  });
+
+  it("returns false for null", () => {
+    expect(isEnrichmentRef(null)).toBe(false);
+  });
+});
+
+describe("createEnrichmentRef", () => {
+  const sampleQual = { axis: { name: "a" }, contextDomain: { d: "1" } };
+
+  it("creates an EnrichmentRef with a non-empty linker path", () => {
+    const ref = createEnrichmentRef(sampleHit, {
+      path: [{ type: "linker", linker: sampleLinker }],
+    });
+    expect(ref).toEqual({
+      __isEnrichment: "v1",
+      hit: sampleHit,
+      path: [{ type: "linker", linker: sampleLinker }],
+    });
+    expect("qualifications" in ref).toBe(false);
+  });
+
+  it("omits path when none given", () => {
+    const ref = createEnrichmentRef(sampleHit);
+    expect(ref).toEqual({ __isEnrichment: "v1", hit: sampleHit });
+    expect("path" in ref).toBe(false);
+  });
+
+  it("omits empty path", () => {
+    const ref = createEnrichmentRef(sampleHit, { path: [] });
+    expect("path" in ref).toBe(false);
+  });
+
+  it("attaches non-empty qualifications", () => {
+    const ref = createEnrichmentRef(sampleHit, { qualifications: [sampleQual] });
+    expect(ref.qualifications).toEqual([sampleQual]);
+  });
+
+  it("omits empty qualifications array", () => {
+    const ref = createEnrichmentRef(sampleHit, { qualifications: [] });
+    expect("qualifications" in ref).toBe(false);
+  });
+});

package/src/ref.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import type { AxisQualification } from "./drivers/pframe/spec/selectors";
+import type { PObjectId } from "./pool/spec";
 
 export const PlRef = z
   .object({
@@ -125,11 +127,65 @@ export function createPrimaryRef(column: PlRef, filter?: PlRef): PrimaryRef {
 /** Block args accept either form — backward compatible. */
 export type DatasetInput = PlRef | PrimaryRef;
 
-/** Dataset option with optional filter choices. */
-export type DatasetOption = Option & {
-  readonly filters?: readonly Option[];
+/** Many-to-one linker hop. */
+export type EnrichmentLinkerStep = {
+  readonly type: "linker";
+  readonly linker: PObjectId;
 };
 
+/** Step from primary to hit. `path[0]` applied first. */
+export type EnrichmentStep = EnrichmentLinkerStep;
+
+/**
+ * Enrichment column reached via {@link path} linker hops; omitted means zero-hop.
+ * `hit` and `path[].linker` are global-form {@link PObjectId}s
+ * (`canonicalize({ __isRef: true, blockId, name })`) which the workflow decodes
+ * to a PlRef before resolving. For a prerun-sourced hop, supply a resolved
+ * `{spec, data}` map in place of the id — `tableBuilder` accepts both.
+ */
+export type EnrichmentRef = {
+  readonly __isEnrichment: "v1";
+  readonly hit: PObjectId;
+  readonly path?: readonly EnrichmentStep[];
+  readonly qualifications?: readonly AxisQualification[];
+};
+
+export function isEnrichmentRef(value: unknown): value is EnrichmentRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __isEnrichment?: unknown }).__isEnrichment === "v1" &&
+    "hit" in value
+  );
+}
+
+export type CreateEnrichmentRefOptions = {
+  readonly path?: readonly EnrichmentStep[];
+  readonly qualifications?: readonly AxisQualification[];
+};
+
+export function createEnrichmentRef(
+  hit: PObjectId,
+  options: CreateEnrichmentRefOptions = {},
+): EnrichmentRef {
+  const { path, qualifications } = options;
+  return {
+    __isEnrichment: "v1",
+    hit,
+    ...(path !== undefined && path.length > 0 ? { path } : {}),
+    ...(qualifications !== undefined && qualifications.length > 0 ? { qualifications } : {}),
+  };
+}
+
+/** {@link EnrichmentRef} plus the export header label. */
+export type LabeledEnrichmentRef = {
+  readonly ref: EnrichmentRef;
+  readonly label: string;
+};
+
+/** Auto-attached enrichment payload; not user-picked. */
+export type LabeledEnrichmentRefs = readonly LabeledEnrichmentRef[];
+
 /** Compare two PlRefs and returns true if they are qual */
 export function plRefsEqual(ref1: PlRef, ref2: PlRef, ignoreEnrichments: boolean = false) {
   return (