@platforma-sdk/model 1.80.17 → 1.81.1

package/src/columns/predicates.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from "vitest";
+import type {
+  AxisSpec,
+  PColumnSpec,
+  PObjectId,
+  SpecOverrides,
+} from "@milaboratories/pl-model-common";
+import type { PColumnDataUniversal } from "../render/internal";
+import { DataColumnImpl, type DataColumnRecipe } from "./data_column";
+import { ColumnFilteredRecipe } from "./column_recipes/column_filtered_recipe";
+import { ColumnOverriddenRecipe } from "./column_recipes/column_overrided_recipe";
+import { hasReachableData, hasSingleDataColumn } from "./utils";
+
+// --- Helpers ---
+
+const axis = (name: string): AxisSpec => ({ name, type: "String" }) as AxisSpec;
+
+const twoAxisSpec: PColumnSpec = {
+  kind: "PColumn",
+  name: "count",
+  valueType: "Int",
+  axesSpec: [axis("sampleId"), axis("clonotypeKey")],
+  annotations: {},
+} as PColumnSpec;
+
+const overrides = (patch: Partial<SpecOverrides>): SpecOverrides => ({
+  annotations: patch.annotations ?? {},
+  domain: patch.domain ?? {},
+  contextDomain: patch.contextDomain ?? {},
+  axesSpec: patch.axesSpec ?? {},
+});
+
+const DATA = { marker: "leaf-data" } as unknown as PColumnDataUniversal;
+
+const leaf = () =>
+  DataColumnImpl.fromColumn({
+    id: "leafId" as PObjectId,
+    spec: twoAxisSpec,
+    data: DATA,
+  });
+
+// ════════════════════════════════════════════════════════════════════════════
+// hasReachableData — "can I read this column's data, consistent with its spec?"
+// ════════════════════════════════════════════════════════════════════════════
+
+describe("hasReachableData", () => {
+  test("bare leaf: true, and getData returns the leaf payload", () => {
+    const col = leaf();
+    expect(hasReachableData(col)).toBe(true);
+    if (!hasReachableData(col)) throw new Error("unreachable");
+    expect(col.getData()).toBe(DATA);
+  });
+
+  test("override over a leaf: true — a spec patch never reshapes data", () => {
+    const col = ColumnOverriddenRecipe.wrap(leaf(), overrides({ annotations: { tag: "1" } }));
+    expect(hasReachableData(col)).toBe(true);
+    if (!hasReachableData(col)) throw new Error("unreachable");
+    expect(col.getData()).toBe(DATA);
+    // The patch landed on the spec while the data stayed the leaf's.
+    expect(col.getSpec().annotations?.tag).toBe("1");
+    expect(col.getSpec().axesSpec).toHaveLength(2);
+  });
+
+  test("axis-filtered leaf: false — spec drops an axis the data still carries", () => {
+    const filtered = ColumnFilteredRecipe.wrap(leaf(), [[0, "s1"]]);
+    // The mismatch this guards against: one axis in the spec, two in the data.
+    expect(filtered.getSpec().axesSpec).toHaveLength(1);
+    expect(hasReachableData(filtered)).toBe(false);
+  });
+
+  test("override over an axis-filtered leaf: false", () => {
+    const filtered = ColumnFilteredRecipe.wrap(leaf(), [[0, "s1"]]);
+    const col = ColumnOverriddenRecipe.wrap(filtered, overrides({ annotations: { tag: "1" } }));
+    expect(hasReachableData(col)).toBe(false);
+  });
+
+  test("an unreadable override has no getData at all — nothing to call, nothing to throw", () => {
+    const filtered = ColumnFilteredRecipe.wrap(leaf(), [[0, "s1"]]);
+    const col = ColumnOverriddenRecipe.wrap(filtered, overrides({ annotations: { tag: "1" } }));
+    expect((col as Partial<DataColumnRecipe>).getData).toBeUndefined();
+  });
+
+  test("merging overrides keeps the readable variant", () => {
+    const once = leaf().withSpecs(overrides({ annotations: { a: "1" } }));
+    const twice = once.withSpecs(overrides({ annotations: { b: "2" } }));
+    expect(hasReachableData(twice)).toBe(true);
+    if (!hasReachableData(twice)) throw new Error("unreachable");
+    expect(twice.getData()).toBe(DATA);
+    expect(twice.getSpec().annotations).toMatchObject({ a: "1", b: "2" });
+  });
+
+  test("merging overrides does not resurrect readability over a filtered leaf", () => {
+    const filtered = ColumnFilteredRecipe.wrap(leaf(), [[0, "s1"]]);
+    const twice = filtered
+      .withSpecs(overrides({ annotations: { a: "1" } }))
+      .withSpecs(overrides({ annotations: { b: "2" } }));
+    expect(hasReachableData(twice)).toBe(false);
+  });
+});
+
+// ════════════════════════════════════════════════════════════════════════════
+// hasSingleDataColumn — "does this column read one data column, or several?"
+// ════════════════════════════════════════════════════════════════════════════
+
+describe("hasSingleDataColumn", () => {
+  test("bare leaf, override and axis filter all read a single data column", () => {
+    const bare = leaf();
+    const filtered = ColumnFilteredRecipe.wrap(leaf(), [[0, "s1"]]);
+    const overridden = ColumnOverriddenRecipe.wrap(filtered, overrides({ domain: { d: "1" } }));
+
+    expect(hasSingleDataColumn(bare)).toBe(true);
+    expect(hasSingleDataColumn(filtered)).toBe(true);
+    expect(hasSingleDataColumn(overridden)).toBe(true);
+  });
+
+  test("is a different question from hasReachableData", () => {
+    const filtered = ColumnFilteredRecipe.wrap(leaf(), [[0, "s1"]]);
+    // Reads a single data column, yet its data is not reachable here (the
+    // slice happens engine-side). Conflating the two is the bug this pair of
+    // predicates replaced.
+    expect(hasSingleDataColumn(filtered)).toBe(true);
+    expect(hasReachableData(filtered)).toBe(false);
+  });
+});

package/src/columns/{expand_by_partition.test.ts → split_by_axes.test.ts}

@@ -13,9 +13,10 @@ import {
 } from "@milaboratories/pl-model-common";
 import { describe, expect, test } from "vitest";
 import type { PColumnDataUniversal } from "../render/internal";
-import type { ColumnLazy } from "./column_lazy";
-import { ColumnLazyImpl } from "./column_lazy";
-import { expandByPartition } from "./expand_by_partition";
+import type { DataColumnRecipe } from "./data_column";
+import { DataColumnImpl } from "./data_column";
+import type { SplitByAxesOpts } from "./split_by_axes";
+import { splitByAxes } from "./split_by_axes";
 
 // --- Helpers ---
 
@@ -33,13 +34,13 @@ function createSpec(name: string, axes: AxisSpec[]): PColumnSpec {
   } as PColumnSpec;
 }
 
-/** Build a synthetic ColumnLazy whose data is a JsonPartitioned DataInfoEntries. */
+/** Build a synthetic DataColumnRecipe whose data is a JsonPartitioned DataInfoEntries. */
 function createReadyLazy(
   id: string,
   spec: PColumnSpec,
   partitionKeyLength: number,
   parts: { key: (string | number)[]; value: unknown }[],
-): ColumnLazy {
+): DataColumnRecipe {
   const dataEntries: JsonPartitionedDataInfoEntries<unknown> = {
     type: "JsonPartitioned",
     partitionKeyLength,
@@ -48,15 +49,15 @@ function createReadyLazy(
   // `data` is typed `PColumnDataUniversal` but `getUniquePartitionKeys`
   // duck-types DataInfoEntries via `isDataInfoEntries`, so the JsonPartitioned
   // payload works at runtime.
-  return ColumnLazyImpl.fromColumn({
+  return DataColumnImpl.fromColumn({
     id: id as PObjectId,
     spec,
     data: dataEntries as unknown as PColumnDataUniversal,
   });
 }
 
-function createComputingLazy(id: string, spec: PColumnSpec): ColumnLazy {
-  return ColumnLazyImpl.fromColumn({
+function createComputingLazy(id: string, spec: PColumnSpec): DataColumnRecipe {
+  return DataColumnImpl.fromColumn({
     id: id as PObjectId,
     spec,
     data: undefined,
@@ -74,14 +75,21 @@ function extractTrace(recipe: { getSpec(): PColumnSpec }): Trace[] {
   return raw ? (JSON.parse(raw) as Trace[]) : [];
 }
 
+/**
+ * `axisValuesLabels` defaults to `deriveAxisValuesLabels()`, which needs the
+ * ambient render ctx these unit tests deliberately run without. Every case
+ * below is about the split itself, so opt out of label resolution explicitly.
+ */
+const NO_LABELS: SplitByAxesOpts = { axisValuesLabels: () => undefined };
+
 // --- Tests ---
 
-describe("expandByPartition", () => {
+describe("splitByAxes", () => {
   test("no split axes returns inputs unchanged", () => {
     const s = createReadyLazy("col1", createSpec("c", [createAxis("a")]), 1, [
       { key: ["x"], value: {} },
     ]);
-    const result = expandByPartition([s], []);
+    const result = splitByAxes([s], []);
     expect(result).toBeDefined();
     expect(result).toHaveLength(1);
     expect(result![0]).toBe(s); // same reference
@@ -99,7 +107,7 @@ describe("expandByPartition", () => {
       ],
     );
 
-    const result = expandByPartition([s], [{ idx: 0 }]);
+    const result = splitByAxes([s], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeDefined();
     // unique values on axis 0: s1, s2 → 2 recipes
     expect(result).toHaveLength(2);
@@ -124,7 +132,7 @@ describe("expandByPartition", () => {
       ],
     );
 
-    const result = expandByPartition([s], [{ idx: 0 }, { idx: 1 }]);
+    const result = splitByAxes([s], [{ idx: 0 }, { idx: 1 }], NO_LABELS);
     expect(result).toBeDefined();
     // a: a1, a2 (2) × b: b1, b2 (2) = 4
     expect(result).toHaveLength(4);
@@ -148,7 +156,7 @@ describe("expandByPartition", () => {
       ],
     );
 
-    const result = expandByPartition([s], [{ idx: 0 }]);
+    const result = splitByAxes([s], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeDefined();
     expect(result).toHaveLength(2);
 
@@ -183,7 +191,7 @@ describe("expandByPartition", () => {
     };
     const s = createReadyLazy("col1", spec, 1, [{ key: ["s1"], value: {} }]);
 
-    const result = expandByPartition([s], [{ idx: 0 }]);
+    const result = splitByAxes([s], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeDefined();
     expect(result).toHaveLength(1);
 
@@ -205,7 +213,7 @@ describe("expandByPartition", () => {
       s2: "Sample Two",
     };
 
-    const result = expandByPartition([s], [{ idx: 0 }], {
+    const result = splitByAxes([s], [{ idx: 0 }], {
       axisValuesLabels: () => labels,
     });
 
@@ -216,7 +224,7 @@ describe("expandByPartition", () => {
 
   test("computing input (data undefined) returns undefined", () => {
     const s = createComputingLazy("col1", createSpec("c", [createAxis("a")]));
-    const result = expandByPartition([s], [{ idx: 0 }]);
+    const result = splitByAxes([s], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeUndefined();
   });
 
@@ -228,7 +236,7 @@ describe("expandByPartition", () => {
       [], // no parts → no unique keys
     );
 
-    const result = expandByPartition([s], [{ idx: 0 }]);
+    const result = splitByAxes([s], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeDefined();
     expect(result).toHaveLength(0);
   });
@@ -244,7 +252,7 @@ describe("expandByPartition", () => {
       ],
     );
 
-    const result = expandByPartition([s], [{ idx: 0 }]);
+    const result = splitByAxes([s], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeDefined();
     expect(result).toHaveLength(2);
 
@@ -274,7 +282,7 @@ describe("expandByPartition", () => {
       ],
     );
 
-    const result = expandByPartition([s], [{ idx: 0 }]);
+    const result = splitByAxes([s], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeDefined();
     expect(result).toHaveLength(2);
 
@@ -306,7 +314,7 @@ describe("expandByPartition", () => {
       ],
     );
 
-    const result = expandByPartition([s1, s2], [{ idx: 0 }]);
+    const result = splitByAxes([s1, s2], [{ idx: 0 }], NO_LABELS);
     expect(result).toBeDefined();
     // s1: 2 unique + s2: 3 unique = 5 total
     expect(result).toHaveLength(5);
@@ -320,6 +328,6 @@ describe("expandByPartition", () => {
       [{ key: ["x"], value: {} }],
     );
 
-    expect(() => expandByPartition([s], [{ idx: 1 }])).toThrow(/Not enough partition keys/);
+    expect(() => splitByAxes([s], [{ idx: 1 }], NO_LABELS)).toThrow(/Not enough partition keys/);
   });
 });

package/src/columns/{expand_by_partition.ts → split_by_axes.ts}

@@ -13,11 +13,12 @@ import {
 } from "@milaboratories/pl-model-common";
 import { TreeNodeAccessor } from "../render/accessor";
 import { getUniquePartitionKeys } from "../render/util/pcolumn_data";
+import { deriveAxisValuesLabels } from "./derive_axis_values_labels";
 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";
+import { hasReachableData } from "./utils";
 
 // --- Types ---
 
@@ -26,8 +27,15 @@ export interface SplitAxis {
   readonly idx: number;
 }
 
-export interface ExpandByPartitionOpts {
-  /** Resolve axis values to human-readable labels. */
+export interface SplitByAxesOpts {
+  /**
+   * Resolve axis values to human-readable labels.
+   *
+   * Defaults to {@link deriveAxisValuesLabels} over the ambient render ctx
+   * (current block outputs + result pool), resolved lazily on the first
+   * lookup. Pass an explicit callback to narrow the label source, or
+   * `() => undefined` to keep raw axis values.
+   */
   axisValuesLabels?: (axisId: AxisId) => undefined | Record<string | number, string>;
 }
 
@@ -36,8 +44,11 @@ export interface ExpandByPartitionOpts {
 const MAX_KEY_COMBINATIONS = 10_000;
 
 /**
- * Expand each input column along the requested partition axes into one
- * {@link ColumnRecipe} per Cartesian combination of unique partition values.
+ * Split each input column along the requested axes into one
+ * {@link ColumnRecipe} per Cartesian combination of the axes' distinct values.
+ *
+ * The split axes must be partition-key axes of the input's data — the distinct
+ * values are read off the partition keys.
  *
  * Each split is produced as `ColumnOverriddenRecipe.wrap(ColumnFilteredRecipe.wrap(inner, axisFilters), { domain, annotations })`:
  *   - `ColumnFilteredRecipe` pins all split axes at once (one wrap call with
@@ -55,22 +66,24 @@ const MAX_KEY_COMBINATIONS = 10_000;
  * Returns `undefined` when any input's `getData()` is not a
  * {@link TreeNodeAccessor} — partition inspection is not yet possible.
  */
-export function expandByPartition(
+export function splitByAxes(
   inputs: Column[],
   splitAxes: SplitAxis[],
-  opts?: ExpandByPartitionOpts,
+  opts?: SplitByAxesOpts,
 ): ColumnRecipe[] | undefined {
   if (splitAxes.length === 0) {
     return [...inputs];
   }
 
+  const axisValuesLabels = opts?.axisValuesLabels ?? deriveAxisValuesLabels();
+
   const splitAxisIdxs = splitAxes.map((a) => a.idx).sort((a, b) => a - b);
   const maxSplitIdx = splitAxisIdxs[splitAxisIdxs.length - 1];
 
   const result: ColumnRecipe[] = [];
 
   for (const inner of inputs) {
-    const data = getLeafColumnData(inner);
+    const data = hasReachableData(inner) ? inner.getData() : undefined;
     // 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)) {
@@ -90,7 +103,7 @@ export function expandByPartition(
     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 axesLabels = splitAxisIds.map((axisId) => axisValuesLabels(axisId));
 
     const existingTraceRaw = readAnnotation(spec, Annotation.Trace);
     const baseTrace: TraceEntry[] = existingTraceRaw

package/src/columns/utils.ts

@@ -11,10 +11,13 @@ 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 { DataColumnRecipe, DataColumnImpl, type ColumnData } from "./data_column";
 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 {
+  ColumnOverriddenRecipe,
+  DataColumnOverriddenRecipe,
+} 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";
@@ -26,7 +29,7 @@ import type { ColumnsSource } from "./column_providers/types";
  * other engine-consumed column.
  *
  * Pure query walk — no registry access. Use {@link collectLinkerColumns} for
- * the resolved {@link ColumnLazy} variant.
+ * the resolved {@link DataColumnRecipe} variant.
  */
 export function collectLinkerIds(recipe: ColumnRecipe): PObjectId[] {
   const hit = extractPObjectId(recipe.id);
@@ -47,16 +50,16 @@ export function collectLinkerIds(recipe: ColumnRecipe): PObjectId[] {
 
 /**
  * {@link collectLinkerIds} resolved against the ambient context as
- * {@link ColumnLazy} instances. Throws if any id fails to resolve —
+ * {@link DataColumnRecipe} leaves. 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[] {
+): DataColumnRecipe<PObjectId>[] {
   return collectLinkerIds(recipe).map(
     (id) =>
-      ColumnLazyImpl.fromId(id, opts) ??
+      DataColumnImpl.fromId(id, opts) ??
       throwError(`materializeLinkers: linker ${id} not resolvable`),
   );
 }
@@ -95,7 +98,7 @@ export function queriesQualifications(
  *
  * 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
+ * {@link DataColumnRecipe} 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
@@ -107,15 +110,15 @@ export function hasColumnData(
   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;
+    const leaf = DataColumnImpl.fromId(id, opts);
+    if (leaf === undefined) return false;
+    if (leaf.getDataStatus() !== "present") return false;
+    if (!isLeafDataPresent(leaf.getData())) return false;
   }
   return true;
 }
 
-function isLazyDataPresent(data: ColumnLazyData): boolean {
+function isLeafDataPresent(data: ColumnData): boolean {
   if (data === undefined) return false;
   if (Array.isArray(data)) return true;
   if (data instanceof TreeNodeAccessor) return data.hasData();
@@ -151,51 +154,53 @@ function findDiscovered(recipe: ColumnRecipe): undefined | ColumnDiscoveredRecip
 }
 
 /**
- * A recipe is a "leaf" (directly co-indexed on the anchor, reached without a
- * linker chain) iff its wrapper chain contains no {@link ColumnDiscoveredRecipe}.
+ * Whether the recipe reads exactly one data column — its own — rather than
+ * reaching through others.
+ *
+ * True for a bare leaf and for projections over one (spec overrides, axis
+ * slicing): those add layers but no new columns. False when the recipe gets at
+ * its data through further columns, which happens when discovery reached it via
+ * a linker chain.
  *
- * `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.
+ * **Why callers care.** A recipe over a single data column is co-indexed by its
+ * own axes, so its spec is the whole truth about them. One that needs other
+ * columns only lines up after they are joined in, and therefore drags axes into
+ * the join that its own spec never mentions — which is why it cannot serve as a
+ * primary column, and why `createPlDataTableV3` splits on this.
+ *
+ * The count comes from {@link ColumnRecipe.getReferencedIds}, which resolves
+ * through the whole wrapper chain, so no class walk is involved and foreign
+ * `ColumnRecipe` implementations are handled too.
  */
-export function isLeafColumn(recipe: ColumnRecipe): boolean {
-  return findDiscovered(recipe) === undefined;
+export function hasSingleDataColumn(recipe: ColumnRecipe): boolean {
+  return recipe.getReferencedIds().length === 1;
 }
 
 /**
- * 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`.
+ * @deprecated Renamed to {@link hasSingleDataColumn} — "leaf" read as "you can
+ * get data out of it", which is a different question (see
+ * {@link hasReachableData}). Same semantics.
  */
-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();
-}
+export const isLeafColumn = hasSingleDataColumn;
 
 /**
- * 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}.
+ * Whether the column's data can be read here and now, consistent with its
+ * spec — narrows to {@link DataColumnRecipe}, which exposes `getData()`.
+ *
+ * True for a bare leaf and for a spec-override over a bare leaf. False for an
+ * axis-filtered recipe (its spec has dropped axes the underlying data still
+ * carries, so the two no longer line up) and for anything reached through
+ * other columns (nothing to read until the engine joins them). In both of
+ * those cases the data exists only engine-side: pass `recipe.id` to
+ * `createPFrame` / `createPTable` instead of trying to read it.
+ *
+ * The distinction is settled when the recipe is built, not here — recipes that
+ * carry data are instances of a class that declares `getData`. So a `true`
+ * result narrows to a value that really has the method, and there is no
+ * throwing path behind the guard.
  */
-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}`);
-  }
+export function hasReachableData(recipe: ColumnRecipe): recipe is DataColumnRecipe {
+  return recipe instanceof DataColumnImpl || recipe instanceof DataColumnOverriddenRecipe;
 }
 
 /** Drop-down option built over a {@link ColumnsCollection} — universal-id valued. */

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

@@ -9,7 +9,7 @@ import {
   type PTableColumnId,
   type SUniversalPColumnId,
 } from "@milaboratories/pl-model-common";
-import { ColumnLazyImpl } from "../../columns";
+import { DataColumnImpl } from "../../columns";
 import type { ColumnRecipe } from "../../columns";
 import { createColumnResolver } from "./columnResolver";
 
@@ -20,7 +20,7 @@ function wrap(id: PObjectId | SUniversalPColumnId, tag: string): SUniversalPColu
   });
 }
 
-// ColumnLazy constructor pulls `getCfgRenderCtx()` from globalThis on some
+// DataColumnRecipe 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,
@@ -36,7 +36,7 @@ afterEach(() => {
 
 function lazyOf(id: PObjectId, axes: AxisSpec[] = []) {
   const spec = { kind: "PColumn", name: "stub", axesSpec: axes } as unknown as PColumnSpec;
-  return ColumnLazyImpl.fromColumn({
+  return DataColumnImpl.fromColumn({
     id,
     spec,
     data: undefined,

package/src/components/PlDataTable/createPlDataTable/createPTableDefV2.ts

@@ -10,7 +10,7 @@ import type { PColumnDataUniversal } from "../../../render";
 import { isFunction } from "es-toolkit";
 import type { PlDataTableFilters } from "../typesV8";
 import { createPTableDefV3 } from "./createPTableDefV3";
-import { ColumnLazyImpl } from "../../../columns";
+import { DataColumn } from "../../../columns";
 
 export function createPTableDefV2(params: {
   columns: PColumn<undefined | PColumnDataUniversal>[];
@@ -33,8 +33,8 @@ export function createPTableDefV2(params: {
   secondaryColumns.push(...params.labelColumns);
 
   return createPTableDefV3({
-    primary: coreColumns.map((column) => ColumnLazyImpl.fromColumn(column)),
-    secondary: secondaryColumns.map((column) => ColumnLazyImpl.fromColumn(column)),
+    primary: coreColumns.map((column) => DataColumn.fromColumn(column)),
+    secondary: secondaryColumns.map((column) => DataColumn.fromColumn(column)),
     primaryJoinType: params.coreJoinType,
     filters: params.filters,
     sorting: params.sorting,

package/src/components/PlDataTable/createPlDataTable/createPlDataTableV2.ts

@@ -31,7 +31,7 @@ import { getMatchingLabelColumns } from "../labels";
 import { collectFilterSpecColumns, traverseFilterSpec } from "../../../filters/traverse";
 import { createPTableDefV2 } from "./createPTableDefV2";
 import { isColumnOptional } from "./utils";
-import { ColumnLazyImpl } from "../../../columns";
+import { DataColumn } from "../../../columns";
 import { createColumnResolver, type ColumnResolver } from "../columnResolver";
 import { isNil, type Nil } from "@milaboratories/helpers";
 
@@ -83,7 +83,7 @@ export function createPlDataTableV2<A, U>(
   const fullColumns = [...columns, ...fullLabelColumns];
 
   const resolver = createColumnResolver(
-    fullColumns.map((c) => ColumnLazyImpl.fromColumn(c)),
+    fullColumns.map((c) => DataColumn.fromColumn(c)),
     { warn: ctx.logWarn.bind(ctx) },
   );
 

package/src/components/PlDataTable/createPlDataTable/createPlDataTableV3.ts

@@ -27,7 +27,7 @@ import { upgradePlDataTableStateV2 } from "../state-migration";
 import type { PlDataTableStateV2 } from "../state-migration";
 import type { MatchingMode } from "@milaboratories/pl-model-common";
 import {
-  isLeafColumn,
+  hasSingleDataColumn,
   hitQualifications,
   collectLinkerColumns,
   queriesQualifications,
@@ -261,7 +261,7 @@ function splitByTopology(columns: ColumnRecipe[]): {
   const direct: ColumnRecipe[] = [];
   const linked: ColumnRecipe[] = [];
   for (const c of columns) {
-    if (isLeafColumn(c)) direct.push(c);
+    if (hasSingleDataColumn(c)) direct.push(c);
     else linked.push(c);
   }
   return { direct, linked };

package/src/components/PlDataTable/createPlDataTable/discoverColumns.ts

@@ -7,7 +7,7 @@ import type {
 import { PColumnName } from "@milaboratories/pl-model-common";
 import type { RenderCtxBase } from "../../../render";
 import type { ColumnRecipe, ColumnsSource } from "../../../columns";
-import { ColumnsCollection, isLeafColumn } from "../../../columns";
+import { ColumnsCollection, hasSingleDataColumn } from "../../../columns";
 import type { ColumnsSelectorConfig } from "./createPlDataTableV3";
 
 export type DiscoverTableColumnOptions = {
@@ -38,7 +38,7 @@ export function discoverTableColumns(
   const primary: ColumnRecipe[] = [];
   const secondary: ColumnRecipe[] = [];
   for (const col of discoveredColumns) {
-    if (isLeafColumn(col)) primary.push(col);
+    if (hasSingleDataColumn(col)) primary.push(col);
     else secondary.push(col);
   }
   return { primary, secondary };