@platforma-sdk/model 1.80.17 → 1.81.0

package/src/columns/column_recipes/index.ts

@@ -8,7 +8,7 @@ import {
   isColumnFilteredKey,
 } from "@milaboratories/pl-model-common";
 import type { GlobalCfgRenderCtx } from "../../render/internal";
-import { ColumnLazyImpl } from "../column_lazy";
+import { DataColumn } from "../data_column";
 import { ColumnDiscoveredRecipe } from "./column_discovered_recipe";
 import { ColumnFilteredRecipe } from "./column_filtered_recipe";
 import { ColumnOverriddenRecipe } from "./column_overrided_recipe";
@@ -19,7 +19,7 @@ import type {
 } from "./types";
 
 export type { ColumnFieldStatus, ColumnRecipeId, ColumnResolutionStatus, SpecQuery } from "./types";
-export { ColumnAbsentError } from "../column_lazy";
+export { ColumnAbsentError } from "../data_column";
 export { ColumnDiscoveredRecipe } from "./column_discovered_recipe";
 export { ColumnFilteredRecipe } from "./column_filtered_recipe";
 export { ColumnOverriddenRecipe } from "./column_overrided_recipe";
@@ -38,7 +38,7 @@ export interface ColumnRecipe<
  * concrete recipe variant based on the id's encoding and recurses on
  * wrappers' inner `source`:
  *
- *   - bare {@link PObjectId} (non-JSON)               → `ColumnLazy.fromId`
+ *   - bare {@link PObjectId} (non-JSON)               → `DataColumnRecipe.fromId`
  *   - `ColumnDiscoveredKey`                          → {@link ColumnDiscoveredRecipe}
  *   - `ColumnOverriddenKey { source, specOverrides }` → recurse on `source`,
  *                                                       then {@link ColumnOverriddenRecipe.wrap}
@@ -56,7 +56,7 @@ function ColumnRecipeBuild(
   const parsed = parseColumnIdSafely(id);
 
   if (isPObjectKey(parsed)) {
-    return ColumnLazyImpl.fromId(id as PObjectId, opts);
+    return DataColumn.fromId(id as PObjectId, opts);
   }
 
   if (isColumnDiscoveredKey(parsed)) {
@@ -98,7 +98,7 @@ function ColumnRecipeGetStatus(
   opts: { ctx?: GlobalCfgRenderCtx } = {},
 ): ColumnResolutionStatus {
   const parsed = parseColumnIdSafely(id);
-  if (isPObjectKey(parsed)) return ColumnLazyImpl.getStatusById(id as PObjectId, opts);
+  if (isPObjectKey(parsed)) return DataColumn.getStatusById(id as PObjectId, opts);
   if (isColumnDiscoveredKey(parsed)) return ColumnDiscoveredRecipe.getStatusByKey(parsed, opts);
   if (isColumnOverriddenKey(parsed)) return ColumnOverriddenRecipe.getStatusByKey(parsed, opts);
   if (isColumnFilteredKey(parsed)) return ColumnFilteredRecipe.getStatusByKey(parsed, opts);
@@ -110,18 +110,3 @@ export const ColumnRecipe: typeof ColumnRecipeBuild & {
 } = Object.assign(ColumnRecipeBuild, {
   getStatus: ColumnRecipeGetStatus,
 });
-
-/**
- * Type-guard for any recipe class — leaf {@link ColumnLazyImpl} or any of the
- * wrapper recipes ({@link ColumnDiscoveredRecipe}, {@link ColumnFilteredRecipe},
- * {@link ColumnOverriddenRecipe}). Use when a value may be a raw id, a `PColumn`,
- * or a recipe and you want to branch on the recipe case.
- */
-export function isColumnRecipe(value: unknown): value is ColumnRecipe {
-  return (
-    value instanceof ColumnLazyImpl ||
-    value instanceof ColumnDiscoveredRecipe ||
-    value instanceof ColumnFilteredRecipe ||
-    value instanceof ColumnOverriddenRecipe
-  );
-}

package/src/columns/{column_lazy.test.ts → data_column.test.ts}

@@ -6,12 +6,12 @@ import {
   type PColumnSpec,
   type PObjectId,
 } from "@milaboratories/pl-model-common";
-import { ColumnAbsentError, ColumnLazy, ColumnLazyImpl } from "./column_lazy";
+import { ColumnAbsentError, DataColumnImpl } from "./data_column";
 import { _ctxProvidersCache } from "./column_providers";
 import { installStubRegistry } from "./__test_helpers__/stub_registry";
 
 // --- Ambient ctx mock ------------------------------------------------------
-// ColumnLazy constructor pulls `getCfgRenderCtx()` from globalThis. A minimal
+// DataColumnImpl constructor pulls `getCfgRenderCtx()` from globalThis. A minimal
 // mock with empty index is enough — these tests don't exercise resolve paths.
 
 const mockCtx = {
@@ -34,12 +34,12 @@ const baseLeaf = createLocalPObjectId(["main", "out"], "col-1");
 const stubSpec = { kind: "PColumn", name: "stub" } as unknown as PColumnSpec;
 
 function lazyOf(id: PObjectId, spec: PColumnSpec = stubSpec) {
-  return ColumnLazyImpl.fromColumn({ id, spec, data: undefined });
+  return DataColumnImpl.fromColumn({ id, spec, data: undefined });
 }
 
 // --- clone flattening -------------------------------------------------------
 
-describe("ColumnLazy.clone", () => {
+describe("DataColumnImpl.clone", () => {
   test("two successive clones produce flat wrap (no nesting)", () => {
     const c0 = lazyOf(baseLeaf);
     const c1 = c0.withSpecs({
@@ -77,7 +77,7 @@ describe("ColumnLazy.clone", () => {
 
 // --- spec() override application -------------------------------------------
 
-describe("ColumnLazy.spec — applySpecOverrides", () => {
+describe("DataColumnImpl.spec — applySpecOverrides", () => {
   test("base spec with no overrides returns readers.spec verbatim", () => {
     const c = lazyOf(baseLeaf);
     expect(c.getSpec()).toBe(stubSpec);
@@ -86,7 +86,7 @@ describe("ColumnLazy.spec — applySpecOverrides", () => {
   test("fromId throws ColumnAbsentError when ctx has no handles", () => {
     // Empty registry — `isFinal()` returns true vacuously, so the leaf is
     // provably absent (no provider will ever supply it).
-    expect(() => ColumnLazyImpl.fromId(baseLeaf)).toThrow(ColumnAbsentError);
+    expect(() => DataColumnImpl.fromId(baseLeaf)).toThrow(ColumnAbsentError);
   });
 
   test("appends axes at indices past base.axesSpec.length", () => {
@@ -129,67 +129,67 @@ describe("ColumnLazy.spec — applySpecOverrides", () => {
 
 // --- resolution status / absent throw --------------------------------------
 
-describe("ColumnLazy resolution: fromId / fromAccessor / getStatus", () => {
+describe("DataColumnImpl resolution: fromId / fromAccessor / getStatus", () => {
   test("fromId returns undefined when registry is unfinalized and id not found", () => {
     // `isFinal: false` → resolver can't tell yet → resolving → undefined.
     installStubRegistry(mockCtx, {}, { isFinal: false });
-    expect(ColumnLazyImpl.fromId(baseLeaf)).toBeUndefined();
+    expect(DataColumnImpl.fromId(baseLeaf)).toBeUndefined();
   });
 
   test("fromId throws ColumnAbsentError when leaf has no spec field on locked accessor", () => {
     // Leaf entry present, no spec field, accessor locked → absent forever.
     installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: true } });
-    expect(() => ColumnLazyImpl.fromId(baseLeaf)).toThrow(ColumnAbsentError);
+    expect(() => DataColumnImpl.fromId(baseLeaf)).toThrow(ColumnAbsentError);
   });
 
   test("fromId returns undefined when leaf has no spec field on unlocked accessor", () => {
     // Leaf entry present, no spec field, accessor unlocked → spec may still arrive.
     installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: false } });
-    expect(ColumnLazyImpl.fromId(baseLeaf)).toBeUndefined();
+    expect(DataColumnImpl.fromId(baseLeaf)).toBeUndefined();
   });
 
   test("fromId returns undefined when spec accessor exists but hasData is false", () => {
     // Spec resource present, bytes not yet written — transient resolving.
     installStubRegistry(mockCtx, { [baseLeaf]: { spec: stubSpec, specHasData: false } });
-    expect(ColumnLazyImpl.fromId(baseLeaf)).toBeUndefined();
+    expect(DataColumnImpl.fromId(baseLeaf)).toBeUndefined();
   });
 
   test("fromAccessor throws ColumnAbsentError when accessor is locked without spec", () => {
     installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: true } });
     const entry = pluckLeafEntry(baseLeaf);
-    expect(() => ColumnLazyImpl.fromAccessor(entry)).toThrow(ColumnAbsentError);
+    expect(() => DataColumnImpl.fromAccessor(entry)).toThrow(ColumnAbsentError);
   });
 
   test("fromAccessor returns undefined when accessor is unlocked without spec", () => {
     installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: false } });
     const entry = pluckLeafEntry(baseLeaf);
-    expect(ColumnLazyImpl.fromAccessor(entry)).toBeUndefined();
+    expect(DataColumnImpl.fromAccessor(entry)).toBeUndefined();
   });
 
   test("getStatusById returns 'absent' / 'resolving' / 'present' across configurations", () => {
     // present — spec with data on a locked, populated leaf.
     installStubRegistry(mockCtx, { [baseLeaf]: stubSpec });
-    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("present");
+    expect(DataColumnImpl.getStatusById(baseLeaf)).toBe("present");
 
     // resolving — same leaf id, spec bytes not yet written.
     installStubRegistry(mockCtx, { [baseLeaf]: { spec: stubSpec, specHasData: false } });
-    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("resolving");
+    expect(DataColumnImpl.getStatusById(baseLeaf)).toBe("resolving");
 
     // resolving — leaf entry exists but spec field missing on an unlocked accessor.
     installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: false } });
-    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("resolving");
+    expect(DataColumnImpl.getStatusById(baseLeaf)).toBe("resolving");
 
     // absent — leaf entry exists with no spec field on a locked accessor.
     installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: true } });
-    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("absent");
+    expect(DataColumnImpl.getStatusById(baseLeaf)).toBe("absent");
 
     // absent — id not in any provider and registry is final.
     installStubRegistry(mockCtx, {}, { isFinal: true });
-    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("absent");
+    expect(DataColumnImpl.getStatusById(baseLeaf)).toBe("absent");
 
     // resolving — id not in any provider but registry still enumerating.
     installStubRegistry(mockCtx, {}, { isFinal: false });
-    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("resolving");
+    expect(DataColumnImpl.getStatusById(baseLeaf)).toBe("resolving");
   });
 });
 

package/src/columns/{column_lazy.ts → data_column.ts}

@@ -20,14 +20,37 @@ import { TreeNodeAccessor } from "../render";
 import type {
   ColumnFieldStatus,
   ColumnRecipe,
+  ColumnRecipeId,
   ColumnResolutionStatus,
 } from "./column_recipes/types";
 import { ColumnOverriddenRecipe } from "./column_recipes/column_overrided_recipe";
 
-export type ColumnLazyId = PObjectId;
-export type ColumnLazyData = undefined | PColumnDataUniversal;
+export type DataColumnId = PObjectId;
+export type ColumnData = undefined | PColumnDataUniversal;
 export type { ColumnFieldStatus, ColumnResolutionStatus } from "./column_recipes/types";
 
+/**
+ * A {@link ColumnRecipe} that can be read directly in the sandbox: its
+ * {@link getData} is guaranteed to be consistent with {@link getSpec}.
+ *
+ * This is a *capability*, not a class. Only two recipe shapes carry it — a
+ * bare leaf and a spec-override over a bare leaf — because those are the only
+ * ones whose data still matches their spec. An axis-filtered recipe drops axes
+ * from its spec while the underlying data keeps them, and a discovered recipe
+ * only materialises after a join; neither can be read here, so neither
+ * implements this interface.
+ *
+ * Narrow to it with `hasReachableData(recipe)` rather than testing for a concrete
+ * class — which recipe classes exist is an implementation detail behind
+ * `recipe.id`.
+ */
+export interface DataColumnRecipe<
+  ID extends ColumnRecipeId = ColumnRecipeId,
+> extends ColumnRecipe<ID> {
+  /** Column data, consistent with {@link ColumnRecipe.getSpec}. */
+  getData(): ColumnData;
+}
+
 /**
  * Thrown by leaf-recipe factories when the requested column is provably
  * absent in the active render ctx — i.e. every relevant accessor reports
@@ -47,22 +70,24 @@ export class ColumnAbsentError extends Error {
 }
 
 /**
- * ColumnLazy is the leaf-recipe building block: a {@link ColumnRecipe} whose
- * `id` is a bare {@link PObjectId} and whose readers are bound to a single
- * tree-accessor leaf. Layered encodings (Overridden / Discovered / Filtered)
- * are reified through their dedicated recipe classes and reference leaf
- * columns by id.
+ * The leaf-recipe building block: a {@link DataColumnRecipe} whose `id` is a bare
+ * {@link PObjectId} and whose readers are bound to a single tree-accessor
+ * leaf. Layered encodings (Overridden / Discovered / Filtered) are reified
+ * through their dedicated recipe classes and reference leaf columns by id.
+ *
+ * Internal — consumers hold the {@link DataColumnRecipe} interface and construct
+ * through the {@link DataColumnRecipe} dispatcher.
  */
-export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
+export class DataColumnImpl implements DataColumnRecipe<PObjectId> {
   private specCache?: { readonly value: PColumnSpec };
-  private dataCache?: { readonly value: ColumnLazyData };
+  private dataCache?: { readonly value: ColumnData };
   private dataStatusCache?: { readonly value: ColumnFieldStatus };
 
   private constructor(
     public readonly id: PObjectId,
     private readonly options: {
       getSpec: () => PColumnSpec;
-      getData: () => ColumnLazyData;
+      getData: () => ColumnData;
       getDataStatus: () => ColumnFieldStatus;
     },
   ) {}
@@ -84,8 +109,7 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
     return { type: "column", column: this.id } as SpecQuery;
   }
 
-  /** Leaf-only: not on the recipe interface — only the leaf can read data directly. */
-  getData(): ColumnLazyData {
+  getData(): ColumnData {
     if (this.dataCache === undefined) this.dataCache = { value: this.options.getData() };
     return this.dataCache.value;
   }
@@ -99,7 +123,7 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
 
   /**
    * Overlay overrides → produces a {@link ColumnOverriddenRecipe} wrapping
-   * this leaf. ColumnLazy itself stays bare (id remains a plain PObjectId);
+   * this leaf. The leaf itself stays bare (id remains a plain PObjectId);
    * layering lives entirely in the recipe wrappers.
    */
   withSpecs(overrides: SpecOverrides): ColumnRecipe {
@@ -113,7 +137,10 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
    * and the column did not appear — the column will not exist in this ctx.
    * Data and dataStatus stay lazy.
    */
-  static fromId(id: PObjectId, { ctx }: { ctx?: GlobalCfgRenderCtx } = {}): undefined | ColumnLazy {
+  static fromId(
+    id: PObjectId,
+    { ctx }: { ctx?: GlobalCfgRenderCtx } = {},
+  ): undefined | DataColumnRecipe<PObjectId> {
     const registry = new ColumnRegistry(getCtxProviders({ ctx }));
     const leaf = registry.resolve(id);
     if (isNil(leaf)) {
@@ -126,7 +153,7 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
       return undefined;
     }
     if (!spec.hasData()) return undefined;
-    return new ColumnLazyImpl(id, {
+    return new DataColumnImpl(id, {
       getSpec: () => spec.getDataAsJson<PColumnSpec>(),
       getData: () => readDataAccessor(leaf),
       getDataStatus: () => readDataStatus(leaf),
@@ -134,8 +161,8 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
   }
 
   /** {@link PlRef} wrapper over {@link fromId}. */
-  static fromPlRef(ref: PlRef): undefined | ColumnLazy {
-    return ColumnLazyImpl.fromId(createGlobalPObjectId(ref.blockId, ref.name));
+  static fromPlRef(ref: PlRef): undefined | DataColumnRecipe<PObjectId> {
+    return DataColumnImpl.fromId(createGlobalPObjectId(ref.blockId, ref.name));
   }
 
   /**
@@ -143,14 +170,14 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
    * Throws {@link ColumnAbsentError} if the leaf has no spec field and its
    * accessor is `inputsLocked`. Returns `undefined` while still resolving.
    */
-  static fromAccessor(entry: LeafEntry<TreeNodeAccessor>): undefined | ColumnLazy {
+  static fromAccessor(entry: LeafEntry<TreeNodeAccessor>): undefined | DataColumnRecipe<PObjectId> {
     const spec = readSpecAccessor(entry);
     if (isNil(spec)) {
       if (entry.accessor.getInputsLocked()) throw new ColumnAbsentError(entry.id);
       return undefined;
     }
     if (!spec.hasData()) return undefined;
-    return new ColumnLazyImpl(entry.id, {
+    return new DataColumnImpl(entry.id, {
       getSpec: () => spec.getDataAsJson<PColumnSpec>(),
       getData: () => readDataAccessor(entry),
       getDataStatus: () => readDataStatus(entry),
@@ -159,13 +186,20 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
 
   /**
    * Wrap a materialised {@link PColumn}. If the input is already a
-   * {@link ColumnLazy} it is returned as-is.
+   * {@link DataColumnRecipe} leaf it is returned as-is.
    */
-  static fromColumn(column: PColumn<ColumnLazyData> | ColumnLazy): ColumnLazy {
-    if (column instanceof ColumnLazyImpl) return column;
-    return new ColumnLazyImpl(column.id, {
-      getSpec: () => column.spec,
-      getData: () => column.data,
+  static fromColumn(
+    column: PColumn<ColumnData> | DataColumnRecipe<PObjectId>,
+  ): DataColumnRecipe<PObjectId> {
+    if (column instanceof DataColumnImpl) return column;
+    // `DataColumnRecipe` is an interface, so `instanceof` above does not remove it
+    // from the union. The only implementation carrying a bare `PObjectId` is
+    // `DataColumnImpl` (wrappers expose `ColumnUniversalId`), so anything
+    // reaching here is a materialised `PColumn`.
+    const pColumn = column as PColumn<ColumnData>;
+    return new DataColumnImpl(pColumn.id, {
+      getSpec: () => pColumn.spec,
+      getData: () => pColumn.data,
       getDataStatus: () => "present",
     });
   }
@@ -191,7 +225,7 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
     ref: PlRef,
     opts: { ctx?: GlobalCfgRenderCtx } = {},
   ): ColumnResolutionStatus {
-    return ColumnLazyImpl.getStatusById(createGlobalPObjectId(ref.blockId, ref.name), opts);
+    return DataColumnImpl.getStatusById(createGlobalPObjectId(ref.blockId, ref.name), opts);
   }
 
   /** No registry — reads straight off the entry's accessor. */
@@ -200,67 +234,71 @@ export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
   }
 }
 
-/**
- * Public type alias — `ColumnLazy` (the type) refers to the underlying
- * {@link ColumnLazyImpl} class instance. `ColumnLazy` (the value) is the
- * callable below with the static factories attached.
- */
-export type ColumnLazy = ColumnLazyImpl;
+/** Anything the {@link DataColumnRecipe} dispatcher can build a leaf from. */
+export type DataColumnSource =
+  | PObjectId
+  | PlRef
+  | LeafEntry<TreeNodeAccessor>
+  | PColumn<ColumnData>
+  | DataColumnRecipe<PObjectId>;
 
 /**
- * Unified dispatcher — picks the right `ColumnLazyImpl.fromX` by source
+ * Unified dispatcher — picks the right `DataColumnImpl.fromX` by source
  * shape. For ambiguous inputs callers can still use the explicit factories
- * (also attached as properties: `ColumnLazy.fromId`, `.fromPlRef`,
+ * (also attached as properties: `DataColumn.fromId`, `.fromPlRef`,
  * `.fromAccessor`, `.fromColumn`).
  */
-function ColumnLazyDispatch(
-  source: PObjectId | PlRef | LeafEntry<TreeNodeAccessor> | PColumn<ColumnLazyData> | ColumnLazy,
+function DataColumnDispatch(
+  source: DataColumnSource,
   opts: { ctx?: GlobalCfgRenderCtx } = {},
-): undefined | ColumnLazy {
-  if (typeof source === "string") return ColumnLazyImpl.fromId(source, opts);
-  if (source instanceof ColumnLazyImpl) return source;
-  if ("accessor" in source) return ColumnLazyImpl.fromAccessor(source);
-  if (isPlRef(source)) return ColumnLazyImpl.fromPlRef(source);
-  if (isPColumn(source)) return ColumnLazyImpl.fromColumn(source);
-  throw new Error("ColumnLazy: unknown source shape");
+): undefined | DataColumnRecipe<PObjectId> {
+  if (typeof source === "string") return DataColumnImpl.fromId(source, opts);
+  if (source instanceof DataColumnImpl) return source;
+  // `DataColumnRecipe` is an interface — `instanceof` above cannot remove it from
+  // the union, and only `DataColumnImpl` implements it with a bare id.
+  const rest = source as LeafEntry<TreeNodeAccessor> | PlRef | PColumn<ColumnData>;
+  if ("accessor" in rest) return DataColumnImpl.fromAccessor(rest);
+  if (isPlRef(rest)) return DataColumnImpl.fromPlRef(rest);
+  if (isPColumn(rest)) return DataColumnImpl.fromColumn(rest);
+  throw new Error("DataColumn: unknown source shape");
 }
 
 /**
- * Polymorphic counterpart to {@link ColumnLazyDispatch}: returns the
+ * Polymorphic counterpart to {@link DataColumnDispatch}: returns the
  * {@link ColumnResolutionStatus} for any factory input without constructing
  * the recipe. For already-materialised sources ({@link PColumn} value,
- * existing {@link ColumnLazy}) status is `present` by construction.
+ * existing {@link DataColumnRecipe}) status is `present` by construction.
  */
-function ColumnLazyGetStatus(
-  source: PObjectId | PlRef | LeafEntry<TreeNodeAccessor> | PColumn<ColumnLazyData> | ColumnLazy,
+function DataColumnGetStatus(
+  source: DataColumnSource,
   opts: { ctx?: GlobalCfgRenderCtx } = {},
 ): ColumnResolutionStatus {
-  if (typeof source === "string") return ColumnLazyImpl.getStatusById(source, opts);
-  if (source instanceof ColumnLazyImpl) return "present";
-  if ("accessor" in source) return ColumnLazyImpl.getStatusByAccessor(source);
-  if (isPlRef(source)) return ColumnLazyImpl.getStatusByPlRef(source, opts);
-  if (isPColumn(source)) return "present";
-  throw new Error("ColumnLazy.getStatus: unknown source shape");
+  if (typeof source === "string") return DataColumnImpl.getStatusById(source, opts);
+  if (source instanceof DataColumnImpl) return "present";
+  const rest = source as LeafEntry<TreeNodeAccessor> | PlRef | PColumn<ColumnData>;
+  if ("accessor" in rest) return DataColumnImpl.getStatusByAccessor(rest);
+  if (isPlRef(rest)) return DataColumnImpl.getStatusByPlRef(rest, opts);
+  if (isPColumn(rest)) return "present";
+  throw new Error("DataColumn.getStatus: unknown source shape");
 }
 
-export const ColumnLazy = Object.assign(ColumnLazyDispatch, {
-  fromId: ColumnLazyImpl.fromId,
-  fromPlRef: ColumnLazyImpl.fromPlRef,
-  fromAccessor: ColumnLazyImpl.fromAccessor,
-  fromColumn: ColumnLazyImpl.fromColumn,
-  getStatus: ColumnLazyGetStatus,
-  getStatusById: ColumnLazyImpl.getStatusById,
-  getStatusByPlRef: ColumnLazyImpl.getStatusByPlRef,
-  getStatusByAccessor: ColumnLazyImpl.getStatusByAccessor,
+export const DataColumn = Object.assign(DataColumnDispatch, {
+  fromId: DataColumnImpl.fromId,
+  fromPlRef: DataColumnImpl.fromPlRef,
+  fromAccessor: DataColumnImpl.fromAccessor,
+  fromColumn: DataColumnImpl.fromColumn,
+  getStatus: DataColumnGetStatus,
+  getStatusById: DataColumnImpl.getStatusById,
+  getStatusByPlRef: DataColumnImpl.getStatusByPlRef,
+  getStatusByAccessor: DataColumnImpl.getStatusByAccessor,
 });
 
 /**
- * Type-guard narrowing to the leaf recipe. Prefer this over
- * `instanceof ColumnLazyImpl` — `ColumnLazy` (the value) is the dispatcher
- * with statics, not the class, so `instanceof` requires the impl symbol.
+ * Type-guard narrowing to a bare leaf — a {@link DataColumnRecipe} whose `id` is a
+ * plain {@link PObjectId}.
  */
-export function isColumnLazy(value: unknown): value is ColumnLazy {
-  return value instanceof ColumnLazyImpl;
+export function isDataColumn(value: unknown): value is DataColumnRecipe<PObjectId> {
+  return value instanceof DataColumnImpl;
 }
 
 const readSpecAccessor = memoizeByEntry(

package/src/columns/derive_axis_values_labels.ts

@@ -4,7 +4,7 @@ import type { ColumnsSource } from "./column_providers";
 import { ColumnsCollection, isColumnsCollection } from "./columns_collection";
 import type { GlobalCfgRenderCtx } from "../render/internal";
 import { TreeNodeAccessor } from "../render";
-import { isColumnLazy } from "./column_lazy";
+import { hasReachableData } from "./utils";
 
 const RT_JSON = "PColumnData/Json";
 const RT_JSON_PARTITIONED = "PColumnData/JsonPartitioned";
@@ -18,11 +18,11 @@ const RT_JSON_PARTITIONED = "PColumnData/JsonPartitioned";
  * column-access mechanism (filtered {@link ColumnsCollection}) instead of
  * walking the raw result pool.
  *
- * Pair with {@link expandByPartition} (or any consumer expecting the
+ * Pair with {@link splitByAxes} (or any consumer expecting the
  * `(axisId) => Record<axisValue, label>` shape).
  *
  * Skips:
- *  - non-leaf recipes (only direct `ColumnLazy` data is read);
+ *  - recipes whose data is not directly readable (see `hasReachableData`);
  *  - label columns whose `axesSpec.length !== 1`;
  *  - label columns whose data resource type isn't `PColumnData/Json` /
  *    `PColumnData/JsonPartitioned`.
@@ -43,7 +43,7 @@ export function deriveAxisValuesLabels(
     .getColumns();
 
   const byAxis = labelCols.reduce<Map<string, Record<string | number, string>>>((map, col) => {
-    if (!isColumnLazy(col)) return map;
+    if (!hasReachableData(col)) return map;
     const spec = col.getSpec();
     if (spec.axesSpec.length !== 1) return map;
 

package/src/columns/index.ts

@@ -1,8 +1,8 @@
 export * from "./column_providers";
-export * from "./expand_by_partition";
+export * from "./split_by_axes";
 export * from "./derive_axis_values_labels";
 export * from "./columns_collection";
-export * from "./column_lazy";
+export * from "./data_column";
 export * from "./column_recipes";
 export * from "./column";
 export * from "./utils";

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);
+  });
+});