@platforma-sdk/model 1.79.24 → 1.80.0

package/src/columns/expand_by_partition.ts

@@ -2,20 +2,22 @@ import type {
   AxisFilterByIdx,
   AxisFilterValue,
   AxisId,
-  PartitionedDataInfoEntries,
-  PObjectId,
+  TraceEntry,
 } from "@milaboratories/pl-model-common";
 import {
+  Annotation,
   canonicalizeAxisId,
-  entriesToDataInfo,
   getAxisId,
-  isPartitionedDataInfoEntries,
+  isDataInfoEntries,
+  readAnnotation,
 } from "@milaboratories/pl-model-common";
-import type { TreeNodeAccessor } from "../render/accessor";
-import { filterDataInfoEntries } from "../render/util/axis_filtering";
-import { convertOrParsePColumnData, getUniquePartitionKeys } from "../render/util/pcolumn_data";
-import type { ColumnSnapshot } from "./column_snapshot";
-import { createReadyColumnData } from "./column_snapshot";
+import { TreeNodeAccessor } from "../render/accessor";
+import { getUniquePartitionKeys } from "../render/util/pcolumn_data";
+import type { ColumnRecipe } from "./column_recipes";
+import { ColumnFilteredRecipe } from "./column_recipes/column_filtered_recipe";
+import { ColumnOverriddenRecipe } from "./column_recipes/column_overrided_recipe";
+import { Column } from "./column";
+import { getLeafColumnData } from "./utils";
 
 // --- Types ---
 
@@ -26,128 +28,114 @@ export interface SplitAxis {
 
 export interface ExpandByPartitionOpts {
   /** Resolve axis values to human-readable labels. */
-  axisLabels?: (axisId: AxisId) => undefined | Record<string | number, string>;
-}
-
-export interface ExpandByPartitionResult {
-  /** Expanded snapshots (one per key combination per original snapshot). */
-  readonly items: ColumnSnapshot<PObjectId>[];
-  /** False if any column's data was not ready for splitting. */
-  readonly complete: boolean;
+  axisValuesLabels?: (axisId: AxisId) => undefined | Record<string | number, string>;
 }
 
 // --- Implementation ---
 
+const MAX_KEY_COMBINATIONS = 10_000;
+
 /**
- * Expand snapshots by splitting along partition axes.
+ * Expand each input column along the requested partition axes into one
+ * {@link ColumnRecipe} per Cartesian combination of unique partition values.
+ *
+ * Each split is produced as `ColumnOverriddenRecipe.wrap(ColumnFilteredRecipe.wrap(inner, axisFilters), { domain, annotations })`:
+ *   - `ColumnFilteredRecipe` pins all split axes at once (one wrap call with
+ *     every `[idx, value]` pair) and removes them from `axesSpec`. The
+ *     engine performs the data slicing via the `sliceAxes` query node.
+ *   - `ColumnOverriddenRecipe` overlays a `domain[axisName] = String(value)`
+ *     entry per split axis and appends a `split:<canonicalAxisId>` trace
+ *     entry per split axis to the existing `pl7.app/trace` annotation.
  *
- * For each snapshot, reads partition data, enumerates unique keys on the
- * split axes, and produces one output snapshot per key combination —
- * with the split axes removed from `axesSpec` and a `pl7.app/trace`
- * annotation recording the split origin.
+ * The recipe id is a canonical
+ * `ColumnOverriddenId(source: ColumnFilteredId(source: inner.id, axisFilters), specOverrides)`
+ * — distinct per split combination, parseable by `extractPObjectId`, and
+ * traversable by recipe walkers.
  *
- * Returns `{ items: [], complete: false }` when any snapshot's data
- * is not ready (status !== 'ready' or partition data unavailable).
+ * Returns `undefined` when any input's `getData()` is not a
+ * {@link TreeNodeAccessor} — partition inspection is not yet possible.
  */
 export function expandByPartition(
-  snapshots: ColumnSnapshot<PObjectId>[],
+  inputs: Column[],
   splitAxes: SplitAxis[],
   opts?: ExpandByPartitionOpts,
-): ExpandByPartitionResult {
+): ColumnRecipe[] | undefined {
   if (splitAxes.length === 0) {
-    return { items: snapshots, complete: true };
+    return [...inputs];
   }
 
   const splitAxisIdxs = splitAxes.map((a) => a.idx).sort((a, b) => a - b);
-  const result: ColumnSnapshot<PObjectId>[] = [];
+  const maxSplitIdx = splitAxisIdxs[splitAxisIdxs.length - 1];
 
-  for (const snapshot of snapshots) {
-    if (snapshot.dataStatus !== "ready" || snapshot.data === undefined) {
-      return { items: [], complete: false };
-    }
+  const result: ColumnRecipe[] = [];
 
-    const rawData = snapshot.data.get();
-    const dataEntries = convertOrParsePColumnData(rawData as TreeNodeAccessor | undefined);
-
-    if (dataEntries === undefined) {
-      return { items: [], complete: false };
-    }
-
-    if (!isPartitionedDataInfoEntries(dataEntries)) {
-      throw new Error(
-        `Splitting requires Partitioned DataInfoEntries, but got ${dataEntries.type} for column ${String(snapshot.id)}`,
-      );
+  for (const inner of inputs) {
+    const data = getLeafColumnData(inner);
+    // Partition inspection requires either a live tree-accessor or already
+    // parsed DataInfoEntries. Anything else means the input is not yet ready.
+    if (!(data instanceof TreeNodeAccessor) && !isDataInfoEntries(data)) {
+      return undefined;
     }
 
-    const uniqueKeys = getUniquePartitionKeys(dataEntries);
+    const uniqueKeys = getUniquePartitionKeys(data);
+    if (uniqueKeys === undefined) return undefined;
 
-    const maxSplitIdx = splitAxisIdxs[splitAxisIdxs.length - 1];
-    if (maxSplitIdx >= dataEntries.partitionKeyLength) {
+    if (maxSplitIdx >= uniqueKeys.length) {
       throw new Error(
-        `Not enough partition keys (${dataEntries.partitionKeyLength}) for requested split axes (max index ${maxSplitIdx}) in column ${snapshot.spec.name}`,
+        `Not enough partition keys (${uniqueKeys.length}) for requested split axes (max index ${maxSplitIdx}) in column ${inner.getSpec().name}`,
       );
     }
 
-    // Resolve labels for each split axis
-    const axesLabels: (undefined | Record<string | number, string>)[] = splitAxisIdxs.map((idx) =>
-      opts?.axisLabels?.(getAxisId(snapshot.spec.axesSpec[idx])),
-    );
+    const spec = inner.getSpec();
+    const axesSpec = spec.axesSpec;
+    const splitAxisSpecs = splitAxisIdxs.map((idx) => axesSpec[idx]);
+    const splitAxisIds = splitAxisSpecs.map((axisSpec) => getAxisId(axisSpec));
+    const axesLabels = splitAxisIds.map((axisId) => opts?.axisValuesLabels?.(axisId));
+
+    const existingTraceRaw = readAnnotation(spec, Annotation.Trace);
+    const baseTrace: TraceEntry[] = existingTraceRaw
+      ? ((JSON.parse(existingTraceRaw) as TraceEntry[]) ?? [])
+      : [];
 
-    // Generate all key combinations across split axes
     const keyCombinations = generateKeyCombinations(uniqueKeys, splitAxisIdxs);
     if (keyCombinations.length === 0) continue;
 
-    // Build adjusted axesSpec (remove split axes in reverse order)
-    const newAxesSpec = [...snapshot.spec.axesSpec];
-    for (let i = splitAxisIdxs.length - 1; i >= 0; i--) {
-      newAxesSpec.splice(splitAxisIdxs[i], 1);
-    }
-
     for (const keyCombo of keyCombinations) {
       const axisFilters: AxisFilterByIdx[] = keyCombo.map(
         (value, sAxisIdx): AxisFilterByIdx => [splitAxisIdxs[sAxisIdx], value as AxisFilterValue],
       );
 
-      const traceEntries = keyCombo.map((value, sAxisIdx) => {
-        const axisIdx = splitAxisIdxs[sAxisIdx];
-        const axisId = getAxisId(snapshot.spec.axesSpec[axisIdx]);
+      const domain: Record<string, string> = {};
+      const traceEntries: TraceEntry[] = [];
+      for (let sAxisIdx = 0; sAxisIdx < keyCombo.length; sAxisIdx++) {
+        const value = keyCombo[sAxisIdx];
+        const axisSpec = splitAxisSpecs[sAxisIdx];
+        const axisId = splitAxisIds[sAxisIdx];
         const labelMap = axesLabels[sAxisIdx];
         const label = labelMap?.[value] ?? String(value);
-        return {
+        domain[axisSpec.name] = String(value);
+        traceEntries.push({
           type: `split:${canonicalizeAxisId(axisId)}`,
           label,
           importance: 1_000_000,
-        };
-      });
-
-      const filteredData = filterDataInfoEntries(
-        dataEntries as PartitionedDataInfoEntries<TreeNodeAccessor>,
-        axisFilters,
-      );
+        });
+      }
 
-      const adjustedSpec = {
-        ...snapshot.spec,
-        axesSpec: newAxesSpec,
+      const filtered = ColumnFilteredRecipe.wrap(inner, axisFilters);
+      const overrided = ColumnOverriddenRecipe.wrap(filtered, {
+        domain,
         annotations: {
-          ...snapshot.spec.annotations,
-          "pl7.app/trace": JSON.stringify(traceEntries),
+          [Annotation.Trace]: JSON.stringify([...baseTrace, ...traceEntries]),
         },
-      };
-
-      result.push({
-        id: snapshot.id,
-        spec: adjustedSpec,
-        dataStatus: "ready",
-        data: createReadyColumnData(() => entriesToDataInfo(filteredData)),
       });
+
+      result.push(overrided);
     }
   }
 
-  return { items: result, complete: true };
+  return result;
 }
 
-const MAX_KEY_COMBINATIONS = 10_000;
-
 function generateKeyCombinations(
   uniqueKeys: (string | number)[][],
   splitAxisIdxs: number[],

package/src/columns/index.ts

@@ -1,6 +1,8 @@
-export * from "./column_snapshot";
-export * from "./column_snapshot_provider";
-export * from "./column_selector";
-export * from "./column_collection_builder";
-export * from "./ctx_column_sources";
+export * from "./column_providers";
 export * from "./expand_by_partition";
+export * from "./derive_axis_values_labels";
+export * from "./columns_collection";
+export * from "./column_lazy";
+export * from "./column_recipes";
+export * from "./column";
+export * from "./utils";

package/src/columns/utils.test.ts

@@ -0,0 +1,249 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import {
+  createColumnDiscoveredKey,
+  createGlobalPObjectId,
+  createLocalPObjectId,
+  stringifyColumnDiscoveredId,
+  type AxisQualification,
+  type PColumnSpec,
+  type PObjectId,
+  type SpecOverrides,
+  type SpecQuery,
+  type ColumnUniversalId,
+} from "@milaboratories/pl-model-common";
+import { collectLinkerIds, hitQualifications, queriesQualifications } from "./utils";
+import { ColumnDiscoveredRecipe } from "./column_recipes/column_discovered_recipe";
+import { ColumnFilteredRecipe } from "./column_recipes/column_filtered_recipe";
+import { ColumnOverriddenRecipe } from "./column_recipes/column_overrided_recipe";
+import type { ColumnFieldStatus, ColumnRecipe } from "./column_recipes/types";
+import { installStubRegistry } from "./__test_helpers__/stub_registry";
+
+// ── ctx mock ────────────────────────────────────────────────────────────────
+// ColumnDiscoveredRecipe pulls `getCfgRenderCtx()` for `pframeSpec`. Minimal
+// no-op stub keeps the constructor happy.
+
+function makeCtx() {
+  // Minimal pframeSpec mock — `ColumnFilteredRecipe.wrap` validates axis
+  // indices against `inner.getSpec()`, which for a real `ColumnDiscoveredRecipe`
+  // runs `createSpecFrame` + `evaluateQuery` through this service. The mock
+  // echoes the registered specs as `tableSpec` entries so `getSpec()` returns
+  // the spec planted by the discovered fixture.
+  const services: Record<string, (...args: unknown[]) => unknown> = {
+    // Wrap whatever specs map the caller passes; we don't inspect its shape.
+    createSpecFrame: (...args: unknown[]) => ({ key: { specs: args[0] }, unref: () => {} }),
+    // Echo the registered specs as `tableSpec` entries — `getSpec` looks up
+    // the entry by id, so we need the shape we planted in `createSpecFrame`.
+    evaluateQuery: (...args: unknown[]) => {
+      const frameKey = args[0] as { specs: Record<string, PColumnSpec> };
+      return {
+        tableSpec: Object.entries(frameKey.specs).map(([id, spec]) => ({
+          type: "column" as const,
+          id,
+          spec,
+        })),
+      };
+    },
+  };
+  return {
+    getAccessorHandleByName: () => undefined,
+    getUpstreamBlockCtx: () => [],
+    getServiceNames: () => ["pframeSpec"],
+    getServiceMethods: () => Object.keys(services),
+    callServiceMethod: (_id: string, method: string, ...args: unknown[]) =>
+      services[method]?.(...args),
+  } as unknown as never;
+}
+
+let activeCtx: ReturnType<typeof makeCtx>;
+beforeEach(() => {
+  activeCtx = makeCtx();
+  (globalThis as { cfgRenderCtx?: unknown }).cfgRenderCtx = activeCtx;
+});
+
+afterEach(() => {
+  delete (globalThis as { cfgRenderCtx?: unknown }).cfgRenderCtx;
+});
+
+// ── fixtures ────────────────────────────────────────────────────────────────
+
+const hit = createLocalPObjectId(["main", "out"], "hit");
+const linker1 = createLocalPObjectId(["main"], "L1");
+const linker2 = createLocalPObjectId(["main"], "L2");
+const otherCol = createGlobalPObjectId("block-x", "extra");
+
+const colNode = (c: PObjectId): SpecQuery => ({ type: "column", column: c });
+
+const axisQual = (name: string): AxisQualification => ({ axis: { name }, contextDomain: {} });
+
+const overrides = (patch: Partial<SpecOverrides> = {}): SpecOverrides => ({
+  annotations: patch.annotations ?? {},
+  domain: patch.domain ?? {},
+  contextDomain: patch.contextDomain ?? {},
+  axesSpec: patch.axesSpec ?? {},
+});
+
+class StubRecipe implements ColumnRecipe<ColumnUniversalId> {
+  constructor(
+    readonly id: ColumnUniversalId,
+    private readonly query: SpecQuery,
+  ) {}
+  getReferencedIds(): PObjectId[] {
+    return [];
+  }
+  getDataStatus(): ColumnFieldStatus {
+    return "present";
+  }
+  getSpec(): PColumnSpec {
+    return { kind: "PColumn", valueType: "String", name: "stub", axesSpec: [] };
+  }
+  getQuery(): SpecQuery {
+    return this.query;
+  }
+  withSpecs(o: SpecOverrides): ColumnRecipe {
+    return ColumnOverriddenRecipe.wrap(this, o);
+  }
+}
+
+const recipe = (id: PObjectId, query: SpecQuery): ColumnRecipe => new StubRecipe(id, query);
+
+/**
+ * Build a real ColumnDiscoveredRecipe from a manually-crafted key. Plants a
+ * stub registry that resolves the hit column so {@link
+ * ColumnDiscoveredRecipe.fromKey} succeeds without a real ctx.
+ */
+function discovered(opts: {
+  column: PObjectId;
+  columnQualifications?: AxisQualification[];
+  queriesQualifications?: Record<PObjectId, AxisQualification[]>;
+}): ColumnDiscoveredRecipe {
+  const distilled = createColumnDiscoveredKey({
+    column: opts.column,
+    columnQualifications: opts.columnQualifications,
+    queriesQualifications: opts.queriesQualifications,
+  });
+  // Spec with two axes — leaves room for `ColumnFilteredRecipe.wrap` callers
+  // in dependent tests (need ≥1 filter and ≥1 remaining axis).
+  const stubSpec: PColumnSpec = {
+    kind: "PColumn",
+    name: "stub",
+    valueType: "String",
+    axesSpec: [
+      { name: "donor", type: "String" },
+      { name: "sample", type: "String" },
+    ],
+    annotations: {},
+  };
+  installStubRegistry(activeCtx, { [opts.column]: stubSpec });
+  const rec = ColumnDiscoveredRecipe.fromKey(distilled);
+  if (rec === undefined) throw new Error("discovered fixture: fromKey returned undefined");
+  expect(rec.id).toBe(stringifyColumnDiscoveredId(distilled));
+  return rec;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// collectLinkerIds
+// ════════════════════════════════════════════════════════════════════════════
+
+describe("collectLinkerIds", () => {
+  test("leaf recipe → empty", () => {
+    expect(collectLinkerIds(recipe(hit, colNode(hit)))).toEqual([]);
+  });
+
+  test("linkerJoin chain → linker ids in outer-to-inner order, hit excluded", () => {
+    const q: SpecQuery = {
+      type: "linkerJoin",
+      linker: colNode(linker1),
+      secondary: [
+        {
+          entry: {
+            type: "linkerJoin",
+            linker: colNode(linker2),
+            secondary: [{ entry: colNode(hit) }],
+          },
+        },
+      ],
+    };
+    expect(collectLinkerIds(recipe(hit, q))).toEqual([linker1, linker2]);
+  });
+
+  test("dedupes repeated references", () => {
+    const q: SpecQuery = {
+      type: "linkerJoin",
+      linker: colNode(linker1),
+      secondary: [
+        {
+          entry: {
+            type: "linkerJoin",
+            linker: colNode(linker1),
+            secondary: [{ entry: colNode(hit) }],
+          },
+        },
+      ],
+    };
+    expect(collectLinkerIds(recipe(hit, q))).toEqual([linker1]);
+  });
+
+  test("ignores the hit even when it appears multiple times", () => {
+    const q: SpecQuery = {
+      type: "innerJoin",
+      entries: [{ entry: colNode(hit) }, { entry: colNode(hit) }, { entry: colNode(otherCol) }],
+    };
+    expect(collectLinkerIds(recipe(hit, q))).toEqual([otherCol]);
+  });
+});
+
+// ════════════════════════════════════════════════════════════════════════════
+// hitQualifications / queriesQualifications — recipe-structure walk
+// ════════════════════════════════════════════════════════════════════════════
+
+describe("hitQualifications", () => {
+  test("leaf recipe → empty list", () => {
+    expect(hitQualifications(recipe(hit, colNode(hit)))).toEqual([]);
+  });
+
+  test("reads ColumnDiscoveredRecipe.columnQualifications", () => {
+    const d = discovered({ column: hit, columnQualifications: [axisQual("sample")] });
+    expect(hitQualifications(d)).toEqual([axisQual("sample")]);
+  });
+
+  test("descends through Overridden wrapper", () => {
+    const d = discovered({ column: hit, columnQualifications: [axisQual("donor")] });
+    const wrapped = ColumnOverriddenRecipe.wrap(d, overrides({ annotations: { x: "1" } }));
+    expect(hitQualifications(wrapped)).toEqual([axisQual("donor")]);
+  });
+
+  test("descends through Filtered wrapper", () => {
+    // Filter axis 0 — axis 1 remains, satisfying the wrap invariant.
+    const d = discovered({ column: hit, columnQualifications: [axisQual("donor")] });
+    const wrapped = ColumnFilteredRecipe.wrap(d, [[0, "v"]]);
+    expect(hitQualifications(wrapped)).toEqual([axisQual("donor")]);
+  });
+
+  test("descends through stacked Overridden<Filtered<Discovered>>", () => {
+    const d = discovered({ column: hit, columnQualifications: [axisQual("donor")] });
+    const stacked = ColumnOverriddenRecipe.wrap(
+      ColumnFilteredRecipe.wrap(d, [[0, "v"]]),
+      overrides({ annotations: { x: "1" } }),
+    );
+    expect(hitQualifications(stacked)).toEqual([axisQual("donor")]);
+  });
+});
+
+describe("queriesQualifications", () => {
+  test("leaf recipe → empty record", () => {
+    expect(queriesQualifications(recipe(hit, colNode(hit)))).toEqual({});
+  });
+
+  test("reads ColumnDiscoveredRecipe.queriesQualifications", () => {
+    const quals = { [otherCol]: [axisQual("primary-side")] };
+    const d = discovered({ column: hit, queriesQualifications: quals });
+    expect(queriesQualifications(d)).toEqual(quals);
+  });
+
+  test("descends through wrappers", () => {
+    const quals = { [otherCol]: [axisQual("primary-side")] };
+    const d = discovered({ column: hit, queriesQualifications: quals });
+    const wrapped = ColumnOverriddenRecipe.wrap(d, overrides());
+    expect(queriesQualifications(wrapped)).toEqual(quals);
+  });
+});