@platforma-sdk/model 1.79.27 → 1.80.2

package/src/columns/__test_helpers__/stub_registry.ts

@@ -0,0 +1,134 @@
+/**
+ * Test-only: plant a stub provider into `_ctxProvidersCache` so that
+ * `ColumnRegistry.resolve(id)` returns a `LeafEntry` whose spec accessor
+ * reports `hasData() === true` and `getDataAsJson()` returns the supplied
+ * spec. Sufficient for code that goes through
+ * `getCtxProviders` / `readLeafSpecAccessor` (e.g. `ColumnLazy.fromId`,
+ * `ColumnDiscoveredRecipe.fromKey`).
+ *
+ * Two leaf shapes:
+ *  - `PColumnSpec` (shorthand) — spec present, accessor locked, `hasData`
+ *    true. Discriminated at runtime by the presence of a `kind` field.
+ *  - {@link StubLeafConfig} — fine-grained control: omit `spec` to simulate
+ *    "no spec field reachable from this leaf"; set `accessorLocked: false`
+ *    to simulate a still-resolving leaf accessor; set `specHasData: false`
+ *    to simulate "spec resource exists but bytes not yet written".
+ *
+ * Registry-wide `isFinal` is also configurable — pass `{ isFinal: false }`
+ * to simulate a still-enumerating registry where missing ids should report
+ * `resolving` rather than `absent`.
+ */
+import type {
+  ColumnEntriesProvider,
+  LeafEntry,
+  PColumnSpec,
+  PObjectId,
+} from "@milaboratories/pl-model-common";
+import type { GlobalCfgRenderCtx } from "../../render/internal";
+import type { TreeNodeAccessor } from "../../render/accessor";
+import { _ctxProvidersCache } from "../column_providers";
+import type { ColumnsProvider } from "../column_providers";
+import { ColumnLazy, ColumnLazyImpl } from "../column_lazy";
+
+/** Fine-grained per-leaf stub config. Defaults match the shorthand form. */
+export type StubLeafConfig = {
+  /** Spec returned by `${id}.spec` traverse. Omit to simulate a missing field. */
+  spec?: PColumnSpec;
+  /** Drives `leaf.accessor.getInputsLocked()`. Default `true`. */
+  accessorLocked?: boolean;
+  /** Drives `spec.hasData()` (ignored when `spec` is omitted). Default `true`. */
+  specHasData?: boolean;
+};
+
+/** Either the shorthand `PColumnSpec` or a {@link StubLeafConfig}. */
+export type StubLeafInput = PColumnSpec | StubLeafConfig;
+
+export function installStubRegistry(
+  ctx: GlobalCfgRenderCtx,
+  leaves: ReadonlyMap<PObjectId, StubLeafInput> | Record<PObjectId, StubLeafInput>,
+  { isFinal = true }: { isFinal?: boolean } = {},
+): void {
+  const map =
+    leaves instanceof Map
+      ? leaves
+      : new Map(Object.entries(leaves) as [PObjectId, StubLeafInput][]);
+  _ctxProvidersCache.set(ctx, [buildStubProvider(map, isFinal)]);
+}
+
+function buildStubProvider(
+  leaves: ReadonlyMap<PObjectId, StubLeafInput>,
+  isFinal: boolean,
+): ColumnEntriesProvider<TreeNodeAccessor> & ColumnsProvider {
+  const { entries, columns } = [...leaves].reduce(
+    (acc, [id, raw]) => {
+      const cfg = normalizeLeafInput(raw);
+      acc.entries.set(id, { accessor: stubAccessorFor(id, cfg), name: id, id });
+      if (cfg.spec !== undefined && cfg.specHasData) {
+        acc.columns.push(
+          ColumnLazyImpl.fromColumn({ id, spec: cfg.spec, data: undefined as never }),
+        );
+      }
+      return acc;
+    },
+    {
+      entries: new Map<PObjectId, LeafEntry<TreeNodeAccessor>>(),
+      columns: [] as ColumnLazy[],
+    },
+  );
+  return {
+    getPObjectEntries: () => entries,
+    isFinal: () => isFinal,
+    getColumns: () => columns,
+  };
+}
+
+type NormalizedLeafConfig = {
+  spec?: PColumnSpec;
+  accessorLocked: boolean;
+  specHasData: boolean;
+};
+
+function normalizeLeafInput(raw: StubLeafInput): NormalizedLeafConfig {
+  if (isPColumnSpec(raw)) {
+    return { spec: raw, accessorLocked: true, specHasData: true };
+  }
+  return {
+    spec: raw.spec,
+    accessorLocked: raw.accessorLocked ?? true,
+    specHasData: raw.specHasData ?? true,
+  };
+}
+
+function isPColumnSpec(v: StubLeafInput): v is PColumnSpec {
+  return typeof v === "object" && v !== null && "kind" in v;
+}
+
+let stubAccessorSeq = 0;
+
+function stubAccessorFor(id: PObjectId, cfg: NormalizedLeafConfig): TreeNodeAccessor {
+  const specField = `${id}.spec`;
+  const specHolder =
+    cfg.spec === undefined
+      ? undefined
+      : {
+          getDataAsJson: <T>() => cfg.spec as unknown as T,
+          hasData: () => cfg.specHasData,
+        };
+  // Per-installation unique handle. The module-level `readSpecAccessor` LRU
+  // cache keys by `${accessor.handle}:${name}`, and reinstalling the stub
+  // for the same id should produce a fresh cache lookup (otherwise tests
+  // that vary leaf state for the same id see stale spec accessors).
+  const handle = `${id}#${++stubAccessorSeq}`;
+  const stub = {
+    handle,
+    resolvePath: [],
+    traverse: (step: { field?: string } | string) => {
+      const field = typeof step === "string" ? step : step?.field;
+      return field === specField ? specHolder : undefined;
+    },
+    getDataAsJson: <T>() => cfg.spec as unknown as T,
+    listInputFields: () => (cfg.spec !== undefined ? [specField] : []),
+    getInputsLocked: () => cfg.accessorLocked,
+  };
+  return stub as unknown as TreeNodeAccessor;
+}

package/src/columns/column.ts

@@ -0,0 +1,46 @@
+import type {
+  ColumnUniversalId,
+  LeafEntry,
+  PColumn,
+  PlRef,
+  PObjectId,
+} from "@milaboratories/pl-model-common";
+import type { GlobalCfgRenderCtx } from "../render/internal";
+import type { TreeNodeAccessor } from "../render";
+import { ColumnLazy, ColumnLazyImpl, type ColumnLazyData } from "./column_lazy";
+import { ColumnRecipe, ColumnRecipeId, isColumnRecipe } from "./column_recipes";
+
+export type ColumnSource =
+  | PObjectId
+  | ColumnUniversalId
+  | PlRef
+  | LeafEntry<TreeNodeAccessor>
+  | PColumn<ColumnLazyData>
+  | ColumnLazyImpl;
+
+/**
+ * Unified entry point — routes between the two top-level dispatchers:
+ *   - string id (`PObjectId` / `ColumnUniversalId`) → {@link ColumnRecipe}
+ *   - object source (`PlRef` / `LeafEntry` / `PColumn` / `ColumnLazy`) → {@link ColumnLazy}
+ *
+ * `ColumnLazy` is itself a `ColumnRecipe<PObjectId>`, so the return type is
+ * the common `ColumnRecipe`.
+ */
+export function Column(
+  source: ColumnSource,
+  opts?: { ctx?: GlobalCfgRenderCtx },
+): undefined | ColumnRecipe {
+  if (typeof source === "string") return ColumnRecipe(source, opts);
+  return ColumnLazy(source, opts);
+}
+
+export type Column<ID extends ColumnRecipeId = ColumnRecipeId> = ColumnRecipe<ID>;
+
+/**
+ * Type-guard for the `Column` type — currently aliased to `ColumnRecipe`, so
+ * this is equivalent to {@link isColumnRecipe}. Kept as a separate export to
+ * mirror the `Column` / `ColumnRecipe` / `ColumnLazy` factory triple.
+ */
+export function isColumn(value: unknown): value is Column {
+  return isColumnRecipe(value);
+}

package/src/columns/column_lazy.test.ts

@@ -0,0 +1,201 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import {
+  createLocalPObjectId,
+  parseColumnOverriddenId,
+  SpecOverrides,
+  type PColumnSpec,
+  type PObjectId,
+} from "@milaboratories/pl-model-common";
+import { ColumnAbsentError, ColumnLazy, ColumnLazyImpl } from "./column_lazy";
+import { _ctxProvidersCache } from "./column_providers";
+import { installStubRegistry } from "./__test_helpers__/stub_registry";
+
+// --- Ambient ctx mock ------------------------------------------------------
+// ColumnLazy constructor pulls `getCfgRenderCtx()` from globalThis. A minimal
+// mock with empty index is enough — these tests don't exercise resolve paths.
+
+const mockCtx = {
+  getAccessorHandleByName: () => undefined,
+  getUpstreamBlockCtx: () => [],
+} as unknown as never;
+
+beforeEach(() => {
+  (globalThis as { cfgRenderCtx?: unknown }).cfgRenderCtx = mockCtx;
+});
+
+afterEach(() => {
+  delete (globalThis as { cfgRenderCtx?: unknown }).cfgRenderCtx;
+});
+
+// --- Helpers ----------------------------------------------------------------
+
+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 });
+}
+
+// --- clone flattening -------------------------------------------------------
+
+describe("ColumnLazy.clone", () => {
+  test("two successive clones produce flat wrap (no nesting)", () => {
+    const c0 = lazyOf(baseLeaf);
+    const c1 = c0.withSpecs({
+      annotations: { a: "1" },
+      domain: {},
+      contextDomain: {},
+      axesSpec: {},
+    });
+    const c2 = c1.withSpecs({
+      annotations: { b: "2" },
+      domain: {},
+      contextDomain: {},
+      axesSpec: {},
+    });
+
+    const parsed = parseColumnOverriddenId(c2.id);
+    // source must be the canonical leaf — not a nested wrap
+    expect(parsed.source).toBe(baseLeaf);
+    expect(parsed.specOverrides.annotations).toEqual({ a: "1", b: "2" });
+  });
+
+  test("idempotent: clone with same overrides twice → same id", () => {
+    const c0 = lazyOf(baseLeaf);
+    const patch: SpecOverrides = {
+      annotations: { x: "1" },
+      domain: {},
+      contextDomain: {},
+      axesSpec: {},
+    };
+    const a = c0.withSpecs(patch);
+    const b = c0.withSpecs(patch);
+    expect(a.id).toBe(b.id);
+  });
+});
+
+// --- spec() override application -------------------------------------------
+
+describe("ColumnLazy.spec — applySpecOverrides", () => {
+  test("base spec with no overrides returns readers.spec verbatim", () => {
+    const c = lazyOf(baseLeaf);
+    expect(c.getSpec()).toBe(stubSpec);
+  });
+
+  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);
+  });
+
+  test("appends axes at indices past base.axesSpec.length", () => {
+    const base = {
+      kind: "PColumn",
+      name: "col",
+      valueType: "String",
+      axesSpec: [{ name: "group", type: "String" }],
+      annotations: {},
+    } as unknown as PColumnSpec;
+    const c = lazyOf(baseLeaf, base).withSpecs({
+      annotations: {},
+      domain: {},
+      contextDomain: {},
+      axesSpec: { 1: { name: "name", type: "String" } },
+    });
+    expect(c.getSpec().axesSpec).toEqual([
+      { name: "group", type: "String" },
+      { name: "name", type: "String" },
+    ]);
+  });
+
+  test("patch on existing axis merges annotations/domain (does not replace whole object)", () => {
+    const base = {
+      kind: "PColumn",
+      name: "col",
+      valueType: "String",
+      axesSpec: [{ name: "group", type: "String", annotations: { k1: "v1" } }],
+      annotations: {},
+    } as unknown as PColumnSpec;
+    const c = lazyOf(baseLeaf, base).withSpecs({
+      annotations: {},
+      domain: {},
+      contextDomain: {},
+      axesSpec: { 0: { annotations: { k2: "v2" } } },
+    });
+    expect(c.getSpec().axesSpec[0].annotations).toEqual({ k1: "v1", k2: "v2" });
+  });
+});
+
+// --- resolution status / absent throw --------------------------------------
+
+describe("ColumnLazy 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();
+  });
+
+  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);
+  });
+
+  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();
+  });
+
+  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();
+  });
+
+  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);
+  });
+
+  test("fromAccessor returns undefined when accessor is unlocked without spec", () => {
+    installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: false } });
+    const entry = pluckLeafEntry(baseLeaf);
+    expect(ColumnLazyImpl.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");
+
+    // resolving — same leaf id, spec bytes not yet written.
+    installStubRegistry(mockCtx, { [baseLeaf]: { spec: stubSpec, specHasData: false } });
+    expect(ColumnLazy.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");
+
+    // absent — leaf entry exists with no spec field on a locked accessor.
+    installStubRegistry(mockCtx, { [baseLeaf]: { accessorLocked: true } });
+    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("absent");
+
+    // absent — id not in any provider and registry is final.
+    installStubRegistry(mockCtx, {}, { isFinal: true });
+    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("absent");
+
+    // resolving — id not in any provider but registry still enumerating.
+    installStubRegistry(mockCtx, {}, { isFinal: false });
+    expect(ColumnLazy.getStatusById(baseLeaf)).toBe("resolving");
+  });
+});
+
+/** Pull the `LeafEntry` planted by the stub registry for a given id. */
+function pluckLeafEntry(id: PObjectId) {
+  const entry = _ctxProvidersCache.get(mockCtx)?.[0]?.getPObjectEntries().get(id);
+  if (entry === undefined) throw new Error(`pluckLeafEntry: no entry for ${id}`);
+  return entry;
+}

package/src/columns/column_lazy.ts

@@ -0,0 +1,311 @@
+import {
+  ColumnRegistry,
+  createGlobalPObjectId,
+  isPColumn,
+  isPlRef,
+  PlRef,
+  PObjectId,
+  type ColumnUniversalId,
+  type LeafEntry,
+  type PColumn,
+  type PColumnSpec,
+  type SpecOverrides,
+  type SpecQuery,
+} from "@milaboratories/pl-model-common";
+import type { GlobalCfgRenderCtx, PColumnDataUniversal } from "../render/internal";
+import { getCtxProviders } from "./column_providers";
+import { isNil } from "es-toolkit";
+import { LRUCache } from "lru-cache";
+import { TreeNodeAccessor } from "../render";
+import type {
+  ColumnFieldStatus,
+  ColumnRecipe,
+  ColumnResolutionStatus,
+} from "./column_recipes/types";
+import { ColumnOverriddenRecipe } from "./column_recipes/column_overrided_recipe";
+
+export type ColumnLazyId = PObjectId;
+export type ColumnLazyData = undefined | PColumnDataUniversal;
+export type { ColumnFieldStatus, ColumnResolutionStatus } from "./column_recipes/types";
+
+/**
+ * Thrown by leaf-recipe factories when the requested column is provably
+ * absent in the active render ctx — i.e. every relevant accessor reports
+ * `inputsLocked` and the column did not appear. Distinct from the
+ * `undefined` return that the factories still use for the "resolving" case
+ * (the column may still appear later).
+ *
+ * Catch at the boundary (resolver / filter+sort wiring / data-table assembly)
+ * when partial absence should be surfaced to the user rather than silently
+ * producing an empty result.
+ */
+export class ColumnAbsentError extends Error {
+  constructor(public readonly id: ColumnUniversalId) {
+    super(`Column is absent in the active render ctx and will not appear: ${id}`);
+    this.name = "ColumnAbsentError";
+  }
+}
+
+/**
+ * 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.
+ */
+export class ColumnLazyImpl implements ColumnRecipe<PObjectId> {
+  private specCache?: { readonly value: PColumnSpec };
+  private dataCache?: { readonly value: ColumnLazyData };
+  private dataStatusCache?: { readonly value: ColumnFieldStatus };
+
+  private constructor(
+    public readonly id: PObjectId,
+    private readonly options: {
+      getSpec: () => PColumnSpec;
+      getData: () => ColumnLazyData;
+      getDataStatus: () => ColumnFieldStatus;
+    },
+  ) {}
+
+  /** A leaf-recipe references exactly one column — its own id. */
+  getReferencedIds(): PObjectId[] {
+    return [this.id];
+  }
+
+  getSpec(): PColumnSpec {
+    if (this.specCache === undefined) {
+      this.specCache = { value: this.options.getSpec() };
+    }
+    return this.specCache.value;
+  }
+
+  /** Leaf-shaped — points straight at `this.id`. */
+  getQuery(): SpecQuery {
+    return { type: "column", column: this.id } as SpecQuery;
+  }
+
+  /** Leaf-only: not on the recipe interface — only the leaf can read data directly. */
+  getData(): ColumnLazyData {
+    if (this.dataCache === undefined) this.dataCache = { value: this.options.getData() };
+    return this.dataCache.value;
+  }
+
+  getDataStatus(): ColumnFieldStatus {
+    if (this.dataStatusCache === undefined) {
+      this.dataStatusCache = { value: this.options.getDataStatus() };
+    }
+    return this.dataStatusCache.value;
+  }
+
+  /**
+   * Overlay overrides → produces a {@link ColumnOverriddenRecipe} wrapping
+   * this leaf. ColumnLazy itself stays bare (id remains a plain PObjectId);
+   * layering lives entirely in the recipe wrappers.
+   */
+  withSpecs(overrides: SpecOverrides): ColumnRecipe {
+    return ColumnOverriddenRecipe.wrap(this, overrides);
+  }
+
+  /**
+   * Resolve via the ambient {@link ColumnRegistry}. Spec is resolved eagerly:
+   * returns `undefined` if the leaf isn't reachable yet (resolving). Throws
+   * {@link ColumnAbsentError} when every relevant accessor is `inputsLocked`
+   * 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 {
+    const registry = new ColumnRegistry(getCtxProviders({ ctx }));
+    const leaf = registry.resolve(id);
+    if (isNil(leaf)) {
+      if (registry.isFinal()) throw new ColumnAbsentError(id);
+      return undefined;
+    }
+    const spec = readSpecAccessor(leaf);
+    if (isNil(spec)) {
+      if (leaf.accessor.getInputsLocked()) throw new ColumnAbsentError(id);
+      return undefined;
+    }
+    if (!spec.hasData()) return undefined;
+    return new ColumnLazyImpl(id, {
+      getSpec: () => spec.getDataAsJson<PColumnSpec>(),
+      getData: () => readDataAccessor(leaf),
+      getDataStatus: () => readDataStatus(leaf),
+    });
+  }
+
+  /** {@link PlRef} wrapper over {@link fromId}. */
+  static fromPlRef(ref: PlRef): undefined | ColumnLazy {
+    return ColumnLazyImpl.fromId(createGlobalPObjectId(ref.blockId, ref.name));
+  }
+
+  /**
+   * Bind directly to an accessor-backed {@link LeafEntry} — no registry.
+   * 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 {
+    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, {
+      getSpec: () => spec.getDataAsJson<PColumnSpec>(),
+      getData: () => readDataAccessor(entry),
+      getDataStatus: () => readDataStatus(entry),
+    });
+  }
+
+  /**
+   * Wrap a materialised {@link PColumn}. If the input is already a
+   * {@link ColumnLazy} 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,
+      getDataStatus: () => "present",
+    });
+  }
+
+  /**
+   * Distinguishes `present` / `resolving` / `absent` for a {@link PObjectId}
+   * in the active render ctx. Falls back to the registry's `isFinal()`
+   * when the id has no entry — only then we can say `absent` instead of
+   * `resolving`.
+   */
+  static getStatusById(
+    id: PObjectId,
+    { ctx }: { ctx?: GlobalCfgRenderCtx } = {},
+  ): ColumnResolutionStatus {
+    const registry = new ColumnRegistry(getCtxProviders({ ctx }));
+    const leaf = registry.resolve(id);
+    if (isNil(leaf)) return registry.isFinal() ? "absent" : "resolving";
+    return getLeafEntryStatus(leaf);
+  }
+
+  /** {@link PlRef} wrapper over {@link getStatusById}. */
+  static getStatusByPlRef(
+    ref: PlRef,
+    opts: { ctx?: GlobalCfgRenderCtx } = {},
+  ): ColumnResolutionStatus {
+    return ColumnLazyImpl.getStatusById(createGlobalPObjectId(ref.blockId, ref.name), opts);
+  }
+
+  /** No registry — reads straight off the entry's accessor. */
+  static getStatusByAccessor(entry: LeafEntry<TreeNodeAccessor>): ColumnResolutionStatus {
+    return getLeafEntryStatus(entry);
+  }
+}
+
+/**
+ * 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;
+
+/**
+ * Unified dispatcher — picks the right `ColumnLazyImpl.fromX` by source
+ * shape. For ambiguous inputs callers can still use the explicit factories
+ * (also attached as properties: `ColumnLazy.fromId`, `.fromPlRef`,
+ * `.fromAccessor`, `.fromColumn`).
+ */
+function ColumnLazyDispatch(
+  source: PObjectId | PlRef | LeafEntry<TreeNodeAccessor> | PColumn<ColumnLazyData> | ColumnLazy,
+  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");
+}
+
+/**
+ * Polymorphic counterpart to {@link ColumnLazyDispatch}: 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.
+ */
+function ColumnLazyGetStatus(
+  source: PObjectId | PlRef | LeafEntry<TreeNodeAccessor> | PColumn<ColumnLazyData> | ColumnLazy,
+  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");
+}
+
+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,
+});
+
+/**
+ * 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.
+ */
+export function isColumnLazy(value: unknown): value is ColumnLazy {
+  return value instanceof ColumnLazyImpl;
+}
+
+const readSpecAccessor = memoizeByEntry(
+  ({ accessor, name }: LeafEntry<TreeNodeAccessor>): undefined | TreeNodeAccessor =>
+    accessor.traverse({ field: `${name}.spec`, assertFieldType: "Input", ignoreError: true }),
+);
+
+/**
+ * Per-entry counterpart to {@link readDataStatus}: tells whether the leaf's
+ * **spec** can be read in this ctx, and — for the negative cases —
+ * distinguishes `resolving` from `absent` via `getInputsLocked()`.
+ *
+ *  - spec field not yet on the entry's accessor + inputs locked → `absent`
+ *  - spec field not yet on the entry's accessor + still resolving → `resolving`
+ *  - spec resource present but bytes not yet written → `resolving`
+ *    (transient — the spec resource is connected, just unfilled)
+ *  - spec resource present and `hasData()` → `present`
+ */
+function getLeafEntryStatus(entry: LeafEntry<TreeNodeAccessor>): ColumnResolutionStatus {
+  const spec = readSpecAccessor(entry);
+  if (isNil(spec)) return entry.accessor.getInputsLocked() ? "absent" : "resolving";
+  if (!spec.hasData()) return "resolving";
+  return "present";
+}
+
+const readDataAccessor = memoizeByEntry(
+  ({ accessor, name }: LeafEntry<TreeNodeAccessor>): undefined | TreeNodeAccessor =>
+    accessor.traverse({ field: `${name}.data`, assertFieldType: "Input", ignoreError: true }),
+);
+
+const readDataStatus = memoizeByEntry(
+  ({ accessor, name }: LeafEntry<TreeNodeAccessor>): ColumnFieldStatus => {
+    if (accessor.listInputFields().includes(`${name}.data`)) return "present";
+    return accessor.getInputsLocked() ? "absent" : "resolving";
+  },
+);
+
+function memoizeByEntry<R>(
+  fn: (entry: LeafEntry<TreeNodeAccessor>) => R,
+): (entry: LeafEntry<TreeNodeAccessor>) => R {
+  const cache = new LRUCache<string, { value: R }>({ max: 1000 });
+  return (entry) => {
+    const key = `${entry.accessor.handle}:${entry.name}`;
+    let hit = cache.get(key);
+    if (!hit) cache.set(key, (hit = { value: fn(entry) }));
+    return hit.value;
+  };
+}