@platforma-sdk/model 1.79.27 → 1.80.0

package/src/columns/utils.ts

@@ -0,0 +1,226 @@
+import {
+  collectSpecQueryColumns,
+  extractPObjectId,
+  isDataInfo,
+  visitDataInfo,
+  type AxisQualification,
+  type ColumnUniversalId,
+  type PObjectId,
+} from "@milaboratories/pl-model-common";
+import { throwError } from "@milaboratories/helpers";
+import type { GlobalCfgRenderCtx } from "../render/internal";
+import { TreeNodeAccessor } from "../render";
+import { deriveDistinctLabels, type DeriveLabelsOptions } from "../labels/derive_distinct_labels";
+import { ColumnLazy, ColumnLazyImpl, type ColumnLazyData } from "./column_lazy";
+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 { ColumnRecipe } from "./column_recipes/types";
+import { ColumnsCollection, isColumnsCollection } from "./columns_collection";
+import type { ColumnsSource } from "./column_providers/types";
+
+/**
+ * PObjectIds of every non-hit column referenced by `recipe.getQuery()`,
+ * deduped in traversal order. The hit column is
+ * `extractPObjectId(recipe.id)`; anything else in the query is a linker or
+ * other engine-consumed column.
+ *
+ * Pure query walk — no registry access. Use {@link collectLinkerColumns} for
+ * the resolved {@link ColumnLazy} variant.
+ */
+export function collectLinkerIds(recipe: ColumnRecipe): PObjectId[] {
+  const hit = extractPObjectId(recipe.id);
+  const seen = new Set<PObjectId>();
+  const out: PObjectId[] = [];
+  for (const id of collectSpecQueryColumns(recipe.getQuery())) {
+    // Leaf ids in SpecQuery may be rich (e.g. ColumnDiscoveredId) — drop to
+    // bare PObjectId before comparing/registering so we hand the ambient
+    // ColumnRegistry physical ids it can resolve.
+    const bare = extractPObjectId(id);
+    if (bare === hit) continue;
+    if (seen.has(bare)) continue;
+    seen.add(bare);
+    out.push(bare);
+  }
+  return out;
+}
+
+/**
+ * {@link collectLinkerIds} resolved against the ambient context as
+ * {@link ColumnLazy} instances. Throws if any id fails to resolve —
+ * matches the contract of the legacy `resolveLinkers` it replaces.
+ */
+export function collectLinkerColumns(
+  recipe: ColumnRecipe,
+  opts: { ctx?: GlobalCfgRenderCtx } = {},
+): ColumnLazy[] {
+  return collectLinkerIds(recipe).map(
+    (id) =>
+      ColumnLazyImpl.fromId(id, opts) ??
+      throwError(`materializeLinkers: linker ${id} not resolvable`),
+  );
+}
+
+/**
+ * Hit-side axis qualifications for the recipe — the ones that should land on
+ * the outer-join entry wrapping this column at the consumer boundary.
+ *
+ * Descends {@link ColumnOverriddenRecipe} / {@link ColumnFilteredRecipe} via
+ * `getInner()` until it finds a {@link ColumnDiscoveredRecipe}; otherwise
+ * returns `[]`. Pure recipe walk — no query-tree introspection.
+ */
+export function hitQualifications(recipe: ColumnRecipe): readonly AxisQualification[] {
+  const discovered = findDiscovered(recipe);
+  return discovered?.getColumnQualifications() ?? [];
+}
+
+/**
+ * Per-primary-column axis qualifications for the recipe — applied to the
+ * outer primary anchors on this recipe's group side. Keyed by the external
+ * primary column id (NOT by columns inside this recipe's own query).
+ *
+ * Same walk strategy as {@link hitQualifications}.
+ */
+export function queriesQualifications(
+  recipe: ColumnRecipe,
+): Readonly<Record<PObjectId, AxisQualification[]>> {
+  const discovered = findDiscovered(recipe);
+  return discovered?.getQueriesQualifications() ?? {};
+}
+
+/**
+ * Whether the recipe's underlying data resources actually carry bytes —
+ * strictly stronger than `getDataStatus() === "present"`, which only tells
+ * that the `.data` field is wired onto the accessor.
+ *
+ * Walks every physical leaf the recipe depends on via
+ * {@link ColumnRecipe.getReferencedIds} (resolves each id back to a
+ * {@link ColumnLazy} through the ambient ctx) and ANDs `hasData()` across
+ * all of them. Inline {@link PColumnValues} payloads count as present.
+ *
+ * Returns `false` if any leaf cannot be re-resolved in `opts.ctx` (treat as
+ * "not yet ready") rather than throwing — this is a UI-facing predicate, not
+ * a contract assertion.
+ */
+export function hasColumnData(
+  recipe: ColumnRecipe,
+  opts: { ctx?: GlobalCfgRenderCtx } = {},
+): boolean {
+  for (const id of recipe.getReferencedIds()) {
+    const lazy = ColumnLazyImpl.fromId(id, opts);
+    if (lazy === undefined) return false;
+    if (lazy.getDataStatus() !== "present") return false;
+    if (!isLazyDataPresent(lazy.getData())) return false;
+  }
+  return true;
+}
+
+function isLazyDataPresent(data: ColumnLazyData): boolean {
+  if (data === undefined) return false;
+  if (Array.isArray(data)) return true;
+  if (data instanceof TreeNodeAccessor) return data.hasData();
+  if (isDataInfo(data)) {
+    let ok = true;
+    visitDataInfo(data, (blob) => {
+      ok &&= blob.hasData();
+    });
+    return ok;
+  }
+  return false;
+}
+
+/**
+ * Walk wrapper layers (Overridden, Filtered) until a {@link
+ * ColumnDiscoveredRecipe} is found. Returns `undefined` if the recipe chain
+ * has no Discovered layer (bare leaves and Overridden-over-leaf cases).
+ *
+ * Invariant from the wrapper classes themselves: there is at most one
+ * Discovered layer in any recipe chain — Discovered is constructed only via
+ * its own factory and is never re-wrapped by Discovered.
+ */
+function findDiscovered(recipe: ColumnRecipe): undefined | ColumnDiscoveredRecipe {
+  let current: ColumnRecipe = recipe;
+  while (true) {
+    if (current instanceof ColumnDiscoveredRecipe) return current;
+    if (current instanceof ColumnOverriddenRecipe || current instanceof ColumnFilteredRecipe) {
+      current = current.getInner();
+      continue;
+    }
+    return undefined;
+  }
+}
+
+/**
+ * A recipe is a "leaf" (directly co-indexed on the anchor, reached without a
+ * linker chain) iff its wrapper chain contains no {@link ColumnDiscoveredRecipe}.
+ *
+ * `Filtered` / `Overridden` over a bare leaf stay leaves; anything wrapping a
+ * `Discovered` (e.g. `Overridden(Discovered(...))`) is linked. Use this — not an
+ * `instanceof ColumnLazyImpl` check — to split direct vs. linker-joined columns,
+ * since projections over a plain leaf are still direct.
+ */
+export function isLeafColumn(recipe: ColumnRecipe): boolean {
+  return findDiscovered(recipe) === undefined;
+}
+
+/**
+ * Data of the bare leaf a "leaf" recipe bottoms out at — reads the leaf-only
+ * {@link ColumnLazy.getData} after walking the wrapper chain down via
+ * {@link extractLeafColumn}. Returns `undefined` when the recipe is not a leaf (its
+ * chain reaches a {@link ColumnDiscoveredRecipe}); the symmetric counterpart
+ * of {@link isLeafColumn} returning `false`.
+ */
+export function getLeafColumnData(recipe: ColumnRecipe): ColumnLazyData {
+  if (!isLeafColumn(recipe)) {
+    throw new Error(`getLeafColumnData: recipe ${recipe.id} is not a leaf column`);
+  }
+  return extractLeafColumn(recipe)?.getData();
+}
+
+/**
+ * Walk wrapper layers (Overridden, Filtered) down to the bare {@link ColumnLazy}
+ * leaf the chain bottoms out at. Returns `undefined` if the chain reaches a
+ * {@link ColumnDiscoveredRecipe} instead — i.e. the recipe is not a leaf
+ * ({@link isLeafColumn} would return `false`). Mirror of {@link findDiscovered}.
+ */
+function extractLeafColumn(recipe: ColumnRecipe): undefined | ColumnLazy {
+  let current: ColumnRecipe = recipe;
+  while (true) {
+    if (current instanceof ColumnLazyImpl) return current;
+    if (current instanceof ColumnOverriddenRecipe || current instanceof ColumnFilteredRecipe) {
+      current = current.getInner();
+      continue;
+    }
+    if (current instanceof ColumnDiscoveredRecipe) {
+      throw new Error(`extractLeafColumn: recipe ${recipe.id} is not a leaf column`);
+    }
+    throw new Error(`extractLeafColumn: unrecognized recipe layer for ${recipe.id}`);
+  }
+}
+
+/** Drop-down option built over a {@link ColumnsCollection} — universal-id valued. */
+export type ColumnOption = {
+  readonly id: ColumnUniversalId;
+  readonly label: string;
+};
+
+/**
+ * Enumerates every column already in `source` and renders distinct labels
+ * from each recipe's spec. Filtering is the caller's job — pass a
+ * {@link ColumnsCollection} that was already narrowed via `.filter(...)` /
+ * `.discover(...)`, or hand over a raw {@link ColumnsSource} (provider,
+ * accessor, column array, or `"result_pool"` / `"current_block"` shorthand)
+ * to be wrapped on the fly.
+ */
+export function deriveColumnOptions(
+  source: ColumnsCollection | ColumnsSource[],
+  labelOptions: DeriveLabelsOptions = {},
+): ColumnOption[] {
+  const collection = isColumnsCollection(source) ? source : ColumnsCollection(source);
+  const recipes = collection.getColumns();
+  const labels = deriveDistinctLabels(
+    recipes.map((r) => r.getSpec()),
+    labelOptions,
+  );
+  return recipes.map((r, i) => ({ id: r.id, label: labels[i] }));
+}

package/src/components/PFrameForGraphs.ts

@@ -27,8 +27,10 @@ export function isHiddenFromUIColumn(column: PColumnSpec): boolean {
  */
 export function createPFrameForGraphs<A, U>(
   ctx: RenderCtxBase<A, U>,
-  blockColumns?: PColumn<PColumnDataUniversal>[],
+  blockColumns?: PColumn<undefined | PColumnDataUniversal>[],
 ): PFrameHandle | undefined {
+  if (blockColumns?.some((v) => v.data === undefined)) return undefined;
+
   const suitableSpec = (spec: PColumnSpec) =>
     !isHiddenFromUIColumn(spec) && !isHiddenFromGraphColumn(spec);
   // if current block doesn't produce own columns then use all columns from result pool

package/src/components/PlAnnotations/filters_ui.test.ts

@@ -1,5 +1,4 @@
 // @DEPRECATED - use sdk/model/src/filters + sdk/model/src/annotations
-import type { SUniversalPColumnId } from "@milaboratories/pl-model-common";
 import { describe, expect, it, test } from "vitest";
 import type {
   AnnotationFilter,
@@ -37,10 +36,10 @@ describe("compileAnnotationScript", () => {
           filter: {
             type: "and",
             filters: [
-              { type: "isNA", column: "colA" as unknown as SUniversalPColumnId },
+              { type: "isNA", column: "colA" },
               {
                 type: "patternEquals",
-                column: "colB" as unknown as SUniversalPColumnId,
+                column: "colB",
                 value: "abc",
               },
             ],
@@ -57,10 +56,10 @@ describe("compileAnnotationScript", () => {
           filter: {
             type: "and",
             filters: [
-              { type: "isNA", column: "colA" as unknown as SUniversalPColumnId },
+              { type: "isNA", column: "colA" },
               {
                 type: "pattern",
-                column: "colB" as unknown as SUniversalPColumnId,
+                column: "colB",
                 predicate: { type: "equals", value: "abc" },
               },
             ],
@@ -77,11 +76,11 @@ describe("compileFilter", () => {
   it('should compile "or" filter', () => {
     const uiFilter: FilterUi = {
       type: "or",
-      filters: [{ type: "isNA", column: "colA" as unknown as SUniversalPColumnId }],
+      filters: [{ type: "isNA", column: "colA" }],
     };
     const expectedFilter: AnnotationFilter = {
       type: "or",
-      filters: [{ type: "isNA", column: "colA" as unknown as SUniversalPColumnId }],
+      filters: [{ type: "isNA", column: "colA" }],
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
   });
@@ -89,11 +88,11 @@ describe("compileFilter", () => {
   it('should compile "and" filter', () => {
     const uiFilter: FilterUi = {
       type: "and",
-      filters: [{ type: "isNA", column: "colA" as unknown as SUniversalPColumnId }],
+      filters: [{ type: "isNA", column: "colA" }],
     };
     const expectedFilter: AnnotationFilter = {
       type: "and",
-      filters: [{ type: "isNA", column: "colA" as unknown as SUniversalPColumnId }],
+      filters: [{ type: "isNA", column: "colA" }],
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
   });
@@ -102,13 +101,13 @@ describe("compileFilter", () => {
     const uiFilter: FilterUi = {
       type: "and",
       filters: [
-        { type: "isNA", column: "colA" as unknown as SUniversalPColumnId },
+        { type: "isNA", column: "colA" },
         {
           type: "or",
           filters: [
             {
               type: "patternEquals",
-              column: "colB" as unknown as SUniversalPColumnId,
+              column: "colB",
               value: "test",
             },
           ],
@@ -118,13 +117,13 @@ describe("compileFilter", () => {
     const expectedFilter: AnnotationFilter = {
       type: "and",
       filters: [
-        { type: "isNA", column: "colA" as unknown as SUniversalPColumnId },
+        { type: "isNA", column: "colA" },
         {
           type: "or",
           filters: [
             {
               type: "pattern",
-              column: "colB" as unknown as SUniversalPColumnId,
+              column: "colB",
               predicate: { type: "equals", value: "test" },
             },
           ],
@@ -137,20 +136,20 @@ describe("compileFilter", () => {
   it('should compile "not" filter', () => {
     const uiFilter: FilterUi = {
       type: "not",
-      filter: { type: "isNA", column: "colA" as unknown as SUniversalPColumnId },
+      filter: { type: "isNA", column: "colA" },
     };
     const expectedFilter: AnnotationFilter = {
       type: "not",
-      filter: { type: "isNA", column: "colA" as unknown as SUniversalPColumnId },
+      filter: { type: "isNA", column: "colA" },
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
   });
 
   it('should compile "isNA" filter', () => {
-    const uiFilter: FilterUi = { type: "isNA", column: "colA" as unknown as SUniversalPColumnId };
+    const uiFilter: FilterUi = { type: "isNA", column: "colA" };
     const expectedFilter: AnnotationFilter = {
       type: "isNA",
-      column: "colA" as unknown as SUniversalPColumnId,
+      column: "colA",
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
   });
@@ -158,9 +157,9 @@ describe("compileFilter", () => {
   it('should compile "isNotNA" filter', () => {
     const uiFilter: FilterUi = {
       type: "isNotNA",
-      column: "colA" as unknown as SUniversalPColumnId,
+      column: "colA",
     };
-    const expectedIsNA: IsNA = { type: "isNA", column: "colA" as unknown as SUniversalPColumnId };
+    const expectedIsNA: IsNA = { type: "isNA", column: "colA" };
     const expectedFilter: NotFilter = { type: "not", filter: expectedIsNA };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
   });
@@ -168,12 +167,12 @@ describe("compileFilter", () => {
   it('should compile "patternEquals" filter', () => {
     const uiFilter: FilterUi = {
       type: "patternEquals",
-      column: "colB" as unknown as SUniversalPColumnId,
+      column: "colB",
       value: "abc",
     };
     const expectedFilter: AnnotationFilter = {
       type: "pattern",
-      column: "colB" as unknown as SUniversalPColumnId,
+      column: "colB",
       predicate: { type: "equals", value: "abc" },
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
@@ -182,12 +181,12 @@ describe("compileFilter", () => {
   it('should compile "patternNotEquals" filter', () => {
     const uiFilter: FilterUi = {
       type: "patternNotEquals",
-      column: "colB" as unknown as SUniversalPColumnId,
+      column: "colB",
       value: "abc",
     };
     const expectedPatternFilter: PatternFilter = {
       type: "pattern",
-      column: "colB" as unknown as SUniversalPColumnId,
+      column: "colB",
       predicate: { type: "equals", value: "abc" },
     };
     const expectedFilter: NotFilter = { type: "not", filter: expectedPatternFilter };
@@ -197,12 +196,12 @@ describe("compileFilter", () => {
   it('should compile "patternContainSubsequence" filter', () => {
     const uiFilter: FilterUi = {
       type: "patternContainSubsequence",
-      column: "colC" as unknown as SUniversalPColumnId,
+      column: "colC",
       value: "sub",
     };
     const expectedFilter: AnnotationFilter = {
       type: "pattern",
-      column: "colC" as unknown as SUniversalPColumnId,
+      column: "colC",
       predicate: { type: "containSubsequence", value: "sub" },
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
@@ -211,12 +210,12 @@ describe("compileFilter", () => {
   it('should compile "patternNotContainSubsequence" filter', () => {
     const uiFilter: FilterUi = {
       type: "patternNotContainSubsequence",
-      column: "colC" as unknown as SUniversalPColumnId,
+      column: "colC",
       value: "sub",
     };
     const expectedPatternFilter: PatternFilter = {
       type: "pattern",
-      column: "colC" as unknown as SUniversalPColumnId,
+      column: "colC",
       predicate: { type: "containSubsequence", value: "sub" },
     };
     const expectedFilter: NotFilter = { type: "not", filter: expectedPatternFilter };
@@ -226,12 +225,12 @@ describe("compileFilter", () => {
   it('should compile "topN" filter (Top 5)', () => {
     const uiFilter: FilterUi = {
       type: "topN",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
       n: 5,
     };
     const expectedRank: ValueRank = {
       transformer: "rank",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
       descending: true,
     };
     const expectedFilter: NumericalComparisonFilter = {
@@ -246,12 +245,12 @@ describe("compileFilter", () => {
   it('should compile "topN" filter (Bottom 3)', () => {
     const uiFilter: FilterUi = {
       type: "bottomN",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
       n: 3,
     };
     const expectedRank: ValueRank = {
       transformer: "rank",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
     };
     const expectedFilter: NumericalComparisonFilter = {
       type: "numericalComparison",
@@ -265,12 +264,12 @@ describe("compileFilter", () => {
   it('should compile "lessThan" filter', () => {
     const uiFilter: FilterUi = {
       type: "lessThan",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
       x: 10,
     };
     const expectedFilter: AnnotationFilter = {
       type: "numericalComparison",
-      lhs: "colNum" as unknown as SUniversalPColumnId,
+      lhs: "colNum",
       rhs: 10,
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
@@ -279,12 +278,12 @@ describe("compileFilter", () => {
   it('should compile "greaterThan" filter', () => {
     const uiFilter: FilterUi = {
       type: "greaterThan",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
       x: 5,
     };
     const expectedFilter: AnnotationFilter = {
       type: "numericalComparison",
-      rhs: "colNum" as unknown as SUniversalPColumnId,
+      rhs: "colNum",
       lhs: 5,
     };
     expect(compileFilter(uiFilter)).toEqual(expectedFilter);
@@ -293,12 +292,12 @@ describe("compileFilter", () => {
   it('should compile "lessThanOrEqual" filter', () => {
     const uiFilter: FilterUi = {
       type: "lessThanOrEqual",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
       x: 20,
     };
     const expectedFilter: AnnotationFilter = {
       type: "numericalComparison",
-      lhs: "colNum" as unknown as SUniversalPColumnId,
+      lhs: "colNum",
       rhs: 20,
       allowEqual: true,
     };
@@ -308,12 +307,12 @@ describe("compileFilter", () => {
   it('should compile "greaterThanOrEqual" filter', () => {
     const uiFilter: FilterUi = {
       type: "greaterThanOrEqual",
-      column: "colNum" as unknown as SUniversalPColumnId,
+      column: "colNum",
       x: 0,
     };
     const expectedFilter: AnnotationFilter = {
       type: "numericalComparison",
-      rhs: "colNum" as unknown as SUniversalPColumnId,
+      rhs: "colNum",
       lhs: 0,
       allowEqual: true,
     };
@@ -323,14 +322,14 @@ describe("compileFilter", () => {
   it('should compile "lessThanColumn" filter', () => {
     const uiFilter: FilterUi = {
       type: "lessThanColumn",
-      column: "colNum1" as unknown as SUniversalPColumnId,
-      rhs: "colNum2" as unknown as SUniversalPColumnId,
+      column: "colNum1",
+      rhs: "colNum2",
       minDiff: 5,
     };
     const expectedFilter: AnnotationFilter = {
       type: "numericalComparison",
-      lhs: "colNum1" as unknown as SUniversalPColumnId,
-      rhs: "colNum2" as unknown as SUniversalPColumnId,
+      lhs: "colNum1",
+      rhs: "colNum2",
       minDiff: 5,
       allowEqual: undefined,
     };
@@ -340,14 +339,14 @@ describe("compileFilter", () => {
   it('should compile "lessThanColumnOrEqual" filter', () => {
     const uiFilter: FilterUi = {
       type: "lessThanColumnOrEqual",
-      column: "colNum1" as unknown as SUniversalPColumnId,
-      rhs: "colNum2" as unknown as SUniversalPColumnId,
+      column: "colNum1",
+      rhs: "colNum2",
       minDiff: 6,
     };
     const expectedFilter: AnnotationFilter = {
       type: "numericalComparison",
-      lhs: "colNum1" as unknown as SUniversalPColumnId,
-      rhs: "colNum2" as unknown as SUniversalPColumnId,
+      lhs: "colNum1",
+      rhs: "colNum2",
       minDiff: 6,
       allowEqual: true,
     };

package/src/components/PlDataTable/columnResolver.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import {
+  createLocalPObjectId,
+  createColumnOverriddenId,
+  type AxisId,
+  type AxisSpec,
+  type PColumnSpec,
+  type PObjectId,
+  type PTableColumnId,
+  type SUniversalPColumnId,
+} from "@milaboratories/pl-model-common";
+import { ColumnLazyImpl } from "../../columns";
+import type { ColumnRecipe } from "../../columns";
+import { createColumnResolver } from "./columnResolver";
+
+function wrap(id: PObjectId | SUniversalPColumnId, tag: string): SUniversalPColumnId {
+  return createColumnOverriddenId({
+    source: id,
+    specOverrides: { annotations: { tag }, domain: {}, contextDomain: {}, axesSpec: {} },
+  });
+}
+
+// ColumnLazy constructor pulls `getCfgRenderCtx()` from globalThis on some
+// paths — keep a minimal mock the same way p_column_lazy.test.ts does.
+const mockCtx = {
+  getAccessorHandleByName: () => undefined,
+  getUpstreamBlockCtx: () => [],
+} as unknown as never;
+
+beforeEach(() => {
+  (globalThis as { cfgRenderCtx?: unknown }).cfgRenderCtx = mockCtx;
+});
+afterEach(() => {
+  delete (globalThis as { cfgRenderCtx?: unknown }).cfgRenderCtx;
+});
+
+function lazyOf(id: PObjectId, axes: AxisSpec[] = []) {
+  const spec = { kind: "PColumn", name: "stub", axesSpec: axes } as unknown as PColumnSpec;
+  return ColumnLazyImpl.fromColumn({
+    id,
+    spec,
+    data: undefined,
+  });
+}
+
+function axisSpec(name: string): AxisSpec {
+  return { type: "String", name } as unknown as AxisSpec;
+}
+
+describe("createColumnResolver", () => {
+  test("exact lazy id match returns the same id (column)", () => {
+    const id = createLocalPObjectId(["main", "out"], "col-1");
+    const r = createColumnResolver([lazyOf(id)]);
+    const ref: PTableColumnId = { type: "column", id };
+    expect(r(ref)).toEqual({ type: "column", id });
+  });
+
+  test("bare PObjectId resolves to the recipe's full id", () => {
+    const pid = createLocalPObjectId(["main", "out"], "col-1");
+    const wrapped = wrap(pid, "A");
+    const fake: ColumnRecipe = {
+      id: wrapped,
+      getReferencedIds: () => [pid],
+      getSpec: () => ({ kind: "PColumn", name: "stub", axesSpec: [] }) as unknown as PColumnSpec,
+      getQuery: () => ({ type: "column", column: pid }) as never,
+      getDataStatus: () => "present",
+      withSpecs: () => fake,
+    };
+
+    const r = createColumnResolver([fake]);
+    const out = r({ type: "column", id: pid });
+    expect(out).toEqual({ type: "column", id: wrapped });
+  });
+
+  test("axis hit passes through unchanged", () => {
+    const ax = axisSpec("sampleId");
+    const id = createLocalPObjectId(["main", "out"], "col-1");
+    const r = createColumnResolver([lazyOf(id, [ax])]);
+    const ref: PTableColumnId = {
+      type: "axis",
+      id: { type: "String", name: "sampleId" } as AxisId,
+    };
+    expect(r(ref)).toEqual(ref);
+  });
+
+  test("axis miss → undefined", () => {
+    const id = createLocalPObjectId(["main", "out"], "col-1");
+    const r = createColumnResolver([lazyOf(id, [axisSpec("sampleId")])]);
+    const ref: PTableColumnId = { type: "axis", id: { type: "String", name: "missing" } as AxisId };
+    expect(r(ref)).toBeUndefined();
+  });
+
+  test("column miss → undefined", () => {
+    const id = createLocalPObjectId(["main", "out"], "col-1");
+    const other = createLocalPObjectId(["main", "out"], "col-2");
+    const r = createColumnResolver([lazyOf(id)]);
+    expect(r({ type: "column", id: other })).toBeUndefined();
+  });
+
+  test("collision warns once and keeps first", () => {
+    const pid = createLocalPObjectId(["main", "out"], "col-1");
+    const wrappedA = wrap(pid, "A");
+    const wrappedB = wrap(pid, "B");
+    const makeFake = (wrapped: SUniversalPColumnId): ColumnRecipe => {
+      const r: ColumnRecipe = {
+        id: wrapped,
+        getReferencedIds: () => [pid],
+        getSpec: () => ({ kind: "PColumn", name: "stub", axesSpec: [] }) as unknown as PColumnSpec,
+        getQuery: () => ({ type: "column", column: pid }) as never,
+        getDataStatus: () => "present",
+        withSpecs: () => r,
+      };
+      return r;
+    };
+
+    const warn = vi.fn();
+    const r = createColumnResolver([makeFake(wrappedA), makeFake(wrappedB)], { warn });
+    expect(warn).toHaveBeenCalledTimes(1);
+    const out = r({ type: "column", id: pid });
+    expect(out).toEqual({ type: "column", id: wrappedA });
+  });
+});