@platforma-sdk/model 1.80.17 → 1.81.1

package/src/columns/column_recipes/column_discovered_recipe.ts

@@ -37,7 +37,7 @@ import { throwError } from "@milaboratories/helpers";
 export class ColumnDiscoveredRecipe implements ColumnRecipe<ColumnDiscoveredId> {
   /**
    * Validate the key + resolve every referenced column via
-   * {@link ColumnLazy.fromId} (which itself checks the leaf accessor reports
+   * {@link DataColumnRecipe.fromId} (which itself checks the leaf accessor reports
    * `hasData()`). Returns `undefined` if the key is malformed or any
    * referenced column is not yet spec-resolvable.
    *

package/src/columns/column_recipes/column_overrided_recipe.ts

@@ -11,6 +11,7 @@ import {
   type SpecQuery,
 } from "@milaboratories/pl-model-common";
 import type { GlobalCfgRenderCtx } from "../../render/internal";
+import { type DataColumnRecipe, type ColumnData, isDataColumn } from "../data_column";
 import type { ColumnFieldStatus, ColumnResolutionStatus } from "./types";
 import { ColumnRecipe } from "./index";
 import { Column } from "../column";
@@ -33,7 +34,7 @@ type NonOverriddenColumn = Column<Exclude<ColumnUniversalId, ColumnOverriddenId>
  * This invariant matches the one enforced inside `unwrapOverrides` from
  * pl-model-common: it explicitly throws on a nested override-wrap.
  */
-export class ColumnOverriddenRecipe implements Column<ColumnOverriddenId> {
+export class ColumnOverriddenRecipe implements ColumnRecipe<ColumnOverriddenId> {
   /**
    * Wrap any recipe with overrides. If `inner` is already a
    * {@link ColumnOverriddenRecipe}, merges `overrides` into the existing ones
@@ -42,12 +43,41 @@ export class ColumnOverriddenRecipe implements Column<ColumnOverriddenId> {
    */
   static wrap(col: Column, overrides: SpecOverrides): ColumnOverriddenRecipe {
     if (col instanceof ColumnOverriddenRecipe) {
-      return new ColumnOverriddenRecipe(col.inner, mergeSpecOverrides(col.overrides, overrides));
+      return ColumnOverriddenRecipe.build(col.inner, mergeSpecOverrides(col.overrides, overrides));
     }
     // `inner` is not an Overridden wrap (the `instanceof` branch above handles
     // that). Narrow the id union here so the constructor parameter stays
     // honest with `ColumnOverriddenKey.source`.
-    return new ColumnOverriddenRecipe(col as NonOverriddenColumn, overrides);
+    return ColumnOverriddenRecipe.build(col as NonOverriddenColumn, overrides);
+  }
+
+  /**
+   * Pick the variant from the inner recipe: data-bearing inner →
+   * {@link DataColumnOverriddenRecipe}, otherwise the plain wrapper.
+   *
+   * The choice is **structural**, not a readiness check — it follows from
+   * which kind of recipe `inner` is, which in turn follows from the id alone
+   * (a bare `PObjectId` source is a leaf, anything else is not). So the same
+   * id always yields the same class, whether it was built via `withSpecs` or
+   * parsed from a string, and recipes stay value-objects that are equal iff
+   * their ids match.
+   *
+   * Re-deriving from `inner` on every build is also what keeps the merge path
+   * honest: `overridden.withSpecs(a).withSpecs(b)` cannot silently drop the
+   * data-bearing variant.
+   *
+   * Discriminated by method presence rather than `instanceof DataColumnImpl`
+   * to keep this module free of a runtime import cycle with `../data_column`.
+   * By the flat-merge invariant `inner` is never an Overridden, so the only
+   * recipe kind reaching here that carries `getData` is the leaf.
+   */
+  private static build(
+    inner: NonOverriddenColumn,
+    overrides: SpecOverrides,
+  ): ColumnOverriddenRecipe {
+    return isDataColumn(inner)
+      ? new DataColumnOverriddenRecipe(inner, overrides)
+      : new ColumnOverriddenRecipe(inner, overrides);
   }
 
   /**
@@ -67,7 +97,7 @@ export class ColumnOverriddenRecipe implements Column<ColumnOverriddenId> {
   private queryCache?: { readonly value: SpecQuery };
   private dataStatusCache?: { readonly value: ColumnFieldStatus };
 
-  private constructor(
+  protected constructor(
     private readonly inner: NonOverriddenColumn,
     private readonly overrides: SpecOverrides,
   ) {
@@ -144,3 +174,27 @@ export class ColumnOverriddenRecipe implements Column<ColumnOverriddenId> {
     return ColumnOverriddenRecipe.wrap(this, overrides);
   }
 }
+
+/**
+ * The variant produced when the wrapped recipe is itself data-bearing.
+ *
+ * Overrides are a pure spec patch — they never reshape the data — so the inner
+ * column's data stays consistent with this recipe's spec and is passed
+ * straight through. Which variant you get is decided once, at construction:
+ * see {@link build}.
+ *
+ * Not something callers name. Narrow with `hasReachableData(recipe)`, which
+ * yields the {@link DataColumnRecipe} interface.
+ */
+export class DataColumnOverriddenRecipe
+  extends ColumnOverriddenRecipe
+  implements DataColumnRecipe<ColumnOverriddenId>
+{
+  /**
+   * Safe by construction: {@link build} only picks this class when the inner
+   * recipe exposes `getData`.
+   */
+  getData(): ColumnData {
+    return (this.getInner() as DataColumnRecipe).getData();
+  }
+}

package/src/columns/column_recipes/column_recipes.test.ts

@@ -24,7 +24,7 @@ import { ColumnDiscoveredRecipe } from "./column_discovered_recipe";
 import { ColumnOverriddenRecipe } from "./column_overrided_recipe";
 import { ColumnFilteredRecipe } from "./column_filtered_recipe";
 import { ColumnRecipe } from "./index";
-import { ColumnAbsentError } from "../column_lazy";
+import { ColumnAbsentError } from "../data_column";
 import type { ColumnFieldStatus } from "./types";
 import { installStubRegistry } from "../__test_helpers__/stub_registry";
 import { throwError } from "@milaboratories/helpers";
@@ -581,7 +581,7 @@ describe("Wrapper getStatusByKey delegates to source", () => {
 });
 
 describe("ColumnRecipe.getStatus (top-level dispatcher)", () => {
-  test("routes bare PObjectId to ColumnLazyImpl.getStatusById", () => {
+  test("routes bare PObjectId to DataColumnImpl.getStatusById", () => {
     setupCtx({ [baseLeaf]: stubSpec() });
     expect(ColumnRecipe.getStatus(baseLeaf)).toBe("present");
   });

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";