@platforma-sdk/model 1.79.24 → 1.80.0

package/src/columns/column_providers/index.ts

@@ -0,0 +1,78 @@
+import { PColumn, type ColumnEntriesProvider } from "@milaboratories/pl-model-common";
+import type { GlobalCfgRenderCtx, PColumnDataUniversal } from "../../render/internal";
+import { getCfgRenderCtx } from "../../internal";
+import { MainAccessorName, StagingAccessorName } from "../../render/internal";
+import { TreeNodeAccessor } from "../../render/accessor";
+import { ColumnLazy } from "../column_lazy";
+import type { ColumnsSource } from "./types";
+import { ArrayColumnsProvider, ColumnsProvider } from "./providers";
+
+export * from "./types";
+export * from "./providers";
+
+/**
+ * Build the default set of ColumnsProviders for the ambient render ctx:
+ *  - `AccessorColumnsProvider` over `outputs` (if present)
+ *  - `AccessorColumnsProvider` over `prerun`  (if present)
+ *  - `ResultPoolColumnsProvider` over `rawResultPool`
+ *
+ * Pulls handles directly from the ambient `cfgRenderCtx`. Returns `[]` when
+ * called outside a render context.
+ *
+ * Result is memoised per-ctx (WeakMap → array). Repeated calls within the
+ * same render cycle return the same provider triplet — inner providers are
+ * also LRU-memoised by their content keys, so even a cache miss here doesn't
+ * re-walk the trees.
+ */
+export const _ctxProvidersCache = new WeakMap<
+  GlobalCfgRenderCtx,
+  (ColumnEntriesProvider<TreeNodeAccessor> & ColumnsProvider)[]
+>();
+
+export function getCtxProviders(deps?: {
+  ctx?: GlobalCfgRenderCtx;
+}): (ColumnEntriesProvider<TreeNodeAccessor> & ColumnsProvider)[] {
+  const ctx = deps?.ctx ?? getCfgRenderCtx();
+
+  const cached = _ctxProvidersCache.get(ctx);
+  if (cached !== undefined) return cached;
+
+  const providers: (ColumnEntriesProvider<TreeNodeAccessor> & ColumnsProvider)[] = [];
+
+  const outputs = ctx.getAccessorHandleByName(MainAccessorName);
+  if (outputs !== undefined) {
+    providers.push(ColumnsProvider(new TreeNodeAccessor(outputs, [MainAccessorName])));
+  }
+
+  const prerun = ctx.getAccessorHandleByName(StagingAccessorName);
+  if (prerun !== undefined) {
+    providers.push(ColumnsProvider(new TreeNodeAccessor(prerun, [StagingAccessorName])));
+  }
+
+  providers.push(ColumnsProvider(ctx.getUpstreamBlockCtx()));
+
+  _ctxProvidersCache.set(ctx, providers);
+  return providers;
+}
+
+export function isColumnProvider(source: unknown): source is ColumnsProvider {
+  if (typeof source !== "object" || source === null) return false;
+  const p = source as ColumnsProvider;
+  return typeof p.getColumns === "function" && typeof p.isFinal === "function";
+}
+
+export function toColumnProvider(source: ColumnsSource): ColumnsProvider {
+  if (isColumnArray(source)) return new ArrayColumnsProvider(source.columns, source.isFinal);
+  if (isColumnProvider(source)) return source;
+  if (source instanceof TreeNodeAccessor) return ColumnsProvider(source);
+  throw new Error("Unknown ColumnsSource type");
+}
+
+function isColumnArray(source: unknown): source is {
+  readonly columns: ReadonlyArray<PColumn<undefined | PColumnDataUniversal> | ColumnLazy>;
+  readonly isFinal: boolean;
+} {
+  if (typeof source !== "object" || source === null) return false;
+  const s = source as { columns?: unknown; isFinal?: unknown };
+  return Array.isArray(s.columns) && typeof s.isFinal === "boolean";
+}

package/src/columns/column_providers/providers.ts

@@ -0,0 +1,193 @@
+import {
+  AccessorEntriesProvider,
+  ResultPoolEntriesProvider,
+  type PColumn,
+  type UpstreamBlockCtx,
+} from "@milaboratories/pl-model-common";
+import { AccessorHandle, PColumnDataUniversal, TreeNodeAccessor } from "../../render";
+import { ColumnLazy, ColumnLazyImpl } from "../column_lazy";
+import { getCfgRenderCtx } from "../../internal";
+import { isNil } from "es-toolkit";
+import { LRUCache } from "lru-cache";
+
+/**
+ * Data source for sandbox column-list builders. Has nothing to say about
+ * id-resolution — `ColumnRegistry` (in `@milaboratories/pl-model-common`)
+ * consumes the separate `ColumnEntriesProvider` interface for that.
+ *
+ * Same name as the factory function below — they merge into one TS
+ * declaration: `ColumnsProvider` is callable AND the interface type.
+ */
+export interface ColumnsProvider {
+  /** Returns all currently known PColumn columns as lazy views. */
+  getColumns(): ColumnLazy[];
+  /** Whether the provider has finished enumerating all its columns. */
+  isFinal(): boolean;
+}
+
+/**
+ * Unified memoised factory dispatching to the right provider flavour by the
+ * source shape:
+ * - `TreeNodeAccessor` → {@link AccessorColumnsProvider}
+ *   (indexed by `root.handle`, walks the accessor tree once per root).
+ * - `UpstreamBlockCtx<AccessorHandle>[]` (or omitted — pulled from the
+ *   ambient ctx) → {@link ResultPoolColumnsProvider}
+ *   (indexed by a content-hash of the block list).
+ *
+ * Both branches return cached instances within their LRU window, so repeated
+ * calls with the same source skip re-walking / re-hashing.
+ */
+export function ColumnsProvider(
+  source?: TreeNodeAccessor | ReadonlyArray<UpstreamBlockCtx<AccessorHandle>>,
+) {
+  if (isNil(source) || Array.isArray(source)) {
+    return ResultPoolColumnsProvider(source);
+  } else if (source instanceof TreeNodeAccessor) {
+    return AccessorColumnsProvider(source);
+  } else {
+    throw new Error("Unknown columns provider source");
+  }
+}
+
+/**
+ * Memoised constructor — same `root.handle` returns the same
+ * {@link AccessorColumnsProviderImpl}, so `indexAccessorRoot` runs once per
+ * accessor root (within the LRU window).
+ */
+const _accessorProviderCache = new LRUCache<AccessorHandle, AccessorColumnsProviderImpl>({
+  max: 64,
+});
+export function AccessorColumnsProvider(root: TreeNodeAccessor): AccessorColumnsProvider {
+  let provider = _accessorProviderCache.get(root.handle);
+  if (provider === undefined) {
+    provider = new AccessorColumnsProviderImpl(root);
+    _accessorProviderCache.set(root.handle, provider);
+  }
+  return provider;
+}
+
+/**
+ * Memoised constructor — same `rawPool` content returns the same
+ * {@link ResultPoolColumnsProviderImpl}, so `indexPoolBlock` runs once per
+ * pool snapshot (within the LRU window).
+ */
+const _resultPoolProviderCache = new LRUCache<string, ResultPoolColumnsProviderImpl>({ max: 4 });
+export function ResultPoolColumnsProvider(
+  rawPool: ReadonlyArray<
+    UpstreamBlockCtx<AccessorHandle>
+  > = getCfgRenderCtx().getUpstreamBlockCtx(),
+): ResultPoolColumnsProvider {
+  const key = hashRawPool(rawPool);
+  let provider = _resultPoolProviderCache.get(key);
+  if (provider === undefined) {
+    provider = new ResultPoolColumnsProviderImpl(rawPool);
+    _resultPoolProviderCache.set(key, provider);
+  }
+  return provider;
+}
+
+/**
+ * Simple provider wrapping an array of PColumns. Sandbox-only —
+ * implements {@link ColumnsProvider} (lazy-view enumeration). It is *not* an
+ * id-index source — `ColumnRegistry` does not consume it.
+ */
+export class ArrayColumnsProvider implements ColumnsProvider {
+  private readonly columns: ColumnLazy[];
+
+  constructor(
+    columns: ReadonlyArray<PColumn<undefined | PColumnDataUniversal> | ColumnLazy>,
+    private readonly _isFinal: boolean,
+  ) {
+    this.columns = columns.map((c) => ColumnLazyImpl.fromColumn(c));
+  }
+
+  getColumns(): ColumnLazy[] {
+    return this.columns;
+  }
+
+  isFinal(): boolean {
+    return this._isFinal;
+  }
+}
+
+/**
+ * Sandbox-specific provider over a {@link TreeNodeAccessor} root. Uses the
+ * accessor's own `resolvePath` as the canonical root path for id construction,
+ * and adds `getColumns()` returning {@link ColumnLazy}s on top of the generic
+ * entries index.
+ */
+export class AccessorColumnsProviderImpl
+  extends AccessorEntriesProvider<TreeNodeAccessor>
+  implements ColumnsProvider
+{
+  private cachedColumns?: ColumnLazy[];
+
+  constructor(root: TreeNodeAccessor) {
+    super(root, root.resolvePath);
+  }
+
+  getColumns(): ColumnLazy[] {
+    if (this.cachedColumns !== undefined) return this.cachedColumns;
+    return (this.cachedColumns = Array.from(this.entries.values())
+      .map((e) => ColumnLazyImpl.fromAccessor(e))
+      .filter((v): v is ColumnLazy => !isNil(v)));
+  }
+}
+
+/** Public type alias — value of the same name is the memoised factory above. */
+export type AccessorColumnsProvider = AccessorColumnsProviderImpl;
+
+/**
+ * Sandbox-specific result-pool provider. Accepts the raw handle-shaped blocks
+ * returned by {@link GlobalCfgRenderCtxMethods.getUpstreamBlockCtx} and
+ * wraps them into {@link TreeNodeAccessor}s, then adds `getColumns()`.
+ */
+export class ResultPoolColumnsProviderImpl
+  extends ResultPoolEntriesProvider<TreeNodeAccessor>
+  implements ColumnsProvider
+{
+  private cachedColumns?: ColumnLazy[];
+
+  constructor(
+    rawPool: ReadonlyArray<
+      UpstreamBlockCtx<AccessorHandle>
+    > = getCfgRenderCtx().getUpstreamBlockCtx(),
+  ) {
+    const blocks = rawPool.map((b) => ({
+      blockId: b.blockId,
+      prodCtx:
+        b.prodCtx !== undefined
+          ? new TreeNodeAccessor(b.prodCtx, [b.blockId, "prodCtx"])
+          : undefined,
+      stagingCtx:
+        b.stagingCtx !== undefined
+          ? new TreeNodeAccessor(b.stagingCtx, [b.blockId, "stagingCtx"])
+          : undefined,
+      prodIncomplete: b.prodIncomplete,
+      stagingIncomplete: b.stagingIncomplete,
+    }));
+
+    super(blocks);
+  }
+
+  getColumns(): ColumnLazy[] {
+    if (this.cachedColumns !== undefined) return this.cachedColumns;
+    return (this.cachedColumns = Array.from(this.getPObjectEntries().values())
+      .map((e) => ColumnLazyImpl.fromAccessor(e))
+      .filter((v): v is ColumnLazy => !isNil(v)));
+  }
+}
+
+/** Public type alias — value of the same name is the memoised factory above. */
+export type ResultPoolColumnsProvider = ResultPoolColumnsProviderImpl;
+
+function hashRawPool(rawPool: ReadonlyArray<UpstreamBlockCtx<AccessorHandle>>): string {
+  return rawPool
+    .map(
+      (b) =>
+        `${b.blockId}\x1f${b.prodCtx ?? ""}\x1f${b.stagingCtx ?? ""}\x1f${
+          b.prodIncomplete ? 1 : 0
+        }\x1f${b.stagingIncomplete ? 1 : 0}`,
+    )
+    .join("\x1e");
+}

package/src/columns/column_providers/types.ts

@@ -0,0 +1,24 @@
+import type { PColumn } from "@milaboratories/pl-model-common";
+import { TreeNodeAccessor } from "../../render";
+import type { PColumnDataUniversal } from "../../render/internal";
+import type { ColumnLazy } from "../column_lazy";
+import type { ColumnRecipe } from "../column_recipes";
+import type { ColumnsProvider } from "./providers";
+
+/**
+ * Union of types that can serve as column sources for helpers and builders.
+ * Includes TreeNodeAccessor, ColumnsProvider, and arrays of columns.
+ *
+ * The array form accepts plain {@link PColumn}s (materialized snapshots),
+ * {@link ColumnLazy} leaves, or any {@link ColumnRecipe} — builders only
+ * need each entry's `id` for serialization.
+ */
+export type ColumnsSource =
+  | ColumnsProvider
+  | TreeNodeAccessor
+  | {
+      readonly columns: ReadonlyArray<
+        PColumn<undefined | PColumnDataUniversal> | ColumnLazy | ColumnRecipe
+      >;
+      readonly isFinal: boolean;
+    };

package/src/columns/column_recipes/column_discovered_recipe.ts

@@ -0,0 +1,231 @@
+import {
+  distillColumnDiscoveredKey,
+  extractPObjectId,
+  stringifyColumnDiscoveredId,
+  type AxisQualification,
+  type ColumnDiscoveredId,
+  type ColumnDiscoveredKey,
+  type ColumnUniversalId,
+  type PColumnSpec,
+  type PObjectId,
+  type SpecOverrides,
+  type SpecQuery,
+} from "@milaboratories/pl-model-common";
+import type { GlobalCfgRenderCtx } from "../../render/internal";
+import type { ColumnFieldStatus, ColumnResolutionStatus } from "./types";
+import { ColumnRecipe } from "./index";
+import { ColumnOverriddenRecipe } from "./column_overrided_recipe";
+import { Column } from "../column";
+import { rebrandLeafId } from "./leaf_rebrand";
+import { throwError } from "@milaboratories/helpers";
+
+/**
+ * Recipe for columns identified by a {@link ColumnDiscoveredKey}: a base
+ * column + a `path` of linkers + qualifications.
+ *
+ * Specifics:
+ *  - References more than one column (`column` + each `path[i].column`);
+ *    {@link getDataStatus} aggregates across the whole set.
+ *  - {@link getQuery} assembles the {@link SpecQuery} locally
+ *    ({@link buildSpecQuery}) — the hit is inlined as its own recipe's query
+ *    tree, linkers fold inside-out into nested `linkerJoin` nodes.
+ *  - {@link getSpec} passes through to the hit column's own spec: the linker
+ *    chain only enables co-indexing and does not remap the hit's `axesSpec`, so
+ *    no engine round-trip is needed (mirrors the Discovered branch of
+ *    `reconstructSpecFromId` on the host side).
+ */
+export class ColumnDiscoveredRecipe implements ColumnRecipe<ColumnDiscoveredId> {
+  /**
+   * Validate the key + resolve every referenced column via
+   * {@link ColumnLazy.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.
+   *
+   * Spec JSON is deserialized lazily on first {@link getSpec}/{@link getQuery}.
+   */
+  static fromKey(
+    key: ColumnDiscoveredKey,
+    opts: { ctx?: GlobalCfgRenderCtx } = {},
+  ): undefined | ColumnDiscoveredRecipe {
+    const distilled = distillColumnDiscoveredKey(key);
+    const columns: Record<ColumnUniversalId, Column> = {};
+    for (const uniId of referencedUniIdsOf(distilled)) {
+      const recipe = Column(uniId, opts);
+      if (recipe === undefined) return undefined;
+      columns[uniId] = recipe;
+    }
+    return new ColumnDiscoveredRecipe(distilled, columns);
+  }
+
+  /**
+   * Static counterpart to {@link fromKey}: returns the resolution status of
+   * a {@link ColumnDiscoveredKey} without constructing the recipe. Worst-wins
+   * across every referenced {@link ColumnUniversalId} (hit + path linkers),
+   * each resolved via the top-level {@link ColumnRecipe.getStatus} dispatcher.
+   */
+  static getStatusByKey(
+    key: ColumnDiscoveredKey,
+    opts: { ctx?: GlobalCfgRenderCtx } = {},
+  ): ColumnResolutionStatus {
+    const distilled = distillColumnDiscoveredKey(key);
+    let worst: ColumnResolutionStatus = "present";
+    for (const uniId of referencedUniIdsOf(distilled)) {
+      const s = ColumnRecipe.getStatus(uniId, opts);
+      if (s === "absent") return "absent";
+      if (s === "resolving") worst = "resolving";
+    }
+    return worst;
+  }
+
+  readonly id: ColumnDiscoveredId;
+  private specCache?: { readonly value: PColumnSpec };
+  private queryCache?: { readonly value: SpecQuery };
+  private dataStatusCache?: { readonly value: ColumnFieldStatus };
+
+  private constructor(
+    private readonly key: ColumnDiscoveredKey,
+    private readonly columns: Record<ColumnUniversalId, ColumnRecipe>,
+  ) {
+    this.id = stringifyColumnDiscoveredId(this.key);
+  }
+
+  /**
+   * Universal id of the hit column (excluding path/qualifications on top).
+   * May itself be a wrapped id (Overridden / Filtered / nested Discovered) —
+   * preserves projections applied to the underlying column.
+   */
+  getHitId(): ColumnUniversalId {
+    return this.key.column;
+  }
+
+  /**
+   * Axis qualifications attached to the hit column itself — applied to the
+   * outer-join entry that wraps this column at the consumer boundary.
+   */
+  getColumnQualifications(): readonly AxisQualification[] {
+    return this.key.columnQualifications ?? [];
+  }
+
+  /**
+   * Per-primary-column qualifications applied to the primary anchors on
+   * this group's side. Keyed by the external primary column id.
+   */
+  getQueriesQualifications(): Readonly<Record<PObjectId, AxisQualification[]>> {
+    return this.key.queriesQualifications ?? {};
+  }
+
+  /**
+   * Leaf {@link PObjectId}s the recipe physically depends on: hit column +
+   * each linker in `path`, with any projection wrappers unwrapped down to
+   * their underlying storage column. Used to track real-data dependencies
+   * (e.g. {@link getDataStatus}), not projected identities.
+   */
+  getReferencedIds(): PObjectId[] {
+    return [...new Set([...referencedUniIdsOf(this.key)].map((uniId) => extractPObjectId(uniId)))];
+  }
+
+  /**
+   * Final spec of a discovered hit is just the hit column's own spec: the
+   * linker chain only enables co-indexing, it does not remap the hit's
+   * `axesSpec`, and axis qualifications live on the outer join entry (see
+   * {@link buildSpecQuery}), not in the spec. So pass through to the hit
+   * recipe's `getSpec()` — no engine round-trip needed. This mirrors the
+   * Discovered branch of `reconstructSpecFromId` on the host side.
+   */
+  getSpec(): PColumnSpec {
+    if (this.specCache === undefined) {
+      const hit =
+        this.columns[this.key.column] ??
+        throwError(`ColumnDiscoveredRecipe.getSpec: missing column ${this.key.column}`);
+      this.specCache = { value: hit.getSpec() };
+    }
+    return this.specCache.value;
+  }
+
+  /** IR for building the final spec — see {@link buildSpecQuery}. */
+  getQuery(): SpecQuery {
+    if (this.queryCache === undefined) {
+      this.queryCache = { value: this.buildSpecQuery() };
+    }
+    return this.queryCache.value;
+  }
+
+  getDataStatus(): ColumnFieldStatus {
+    if (this.dataStatusCache === undefined) {
+      this.dataStatusCache = {
+        value: Object.values(this.columns).reduce<ColumnFieldStatus>((worst, lazy) => {
+          const s = lazy.getDataStatus();
+          if (s === "absent" || worst === "absent") return "absent";
+          if (s === "resolving") return "resolving";
+          return worst;
+        }, "present"),
+      };
+    }
+    return this.dataStatusCache.value;
+  }
+
+  /**
+   * Discovered + overrides → Overridden<Discovered>. Delegates to the
+   * flat-merge factory of ColumnOverriddenRecipe; subsequent `withSpecs`
+   * calls merge at the Overridden level (one wrapper, no nesting).
+   */
+  withSpecs(overrides: SpecOverrides): ColumnRecipe {
+    return ColumnOverriddenRecipe.wrap(this, overrides);
+  }
+
+  /**
+   * Assembles the SpecQuery for this discovered hit by folding `key.path`
+   * around the hit column.
+   *
+   * The hit (innermost) is built by inlining `columns[key.column].getQuery()`
+   * — recursing into the hit's own recipe — so wrapping layers on the hit
+   * (Overridden / Filtered / nested Discovered) appear in the produced tree.
+   * The previous `pframeSpec.buildQuery` path was a flat
+   * {@link PObjectId}-only call and could not express that.
+   *
+   * Linkers stay as plain column references on the linker side of
+   * `linkerJoin` (the spec node has no slot for a query-side linker); the
+   * linker's recipe id is used directly. The frame registered in
+   * {@link getSpec} carries each recipe's final spec under that same id, so
+   * the engine resolves linker axes from the post-projection spec.
+   *
+   * Path ordering matches {@link ColumnDiscoveredKey.path}: `path[0]` is
+   * outermost, `path[N-1]` is closest to the hit. We fold from the inside
+   * out — innermost wrap first — so the result lines up with that convention.
+   *
+   * `columnQualifications` / `queriesQualifications` are not emitted here —
+   * qualifications live on a {@link SpecQueryJoinEntry} wrapper (lost on
+   * unwrapping to {@link SpecQuery}). External consumers apply them at the
+   * outer join via {@link getColumnQualifications} / {@link getQueriesQualifications}.
+   */
+  private buildSpecQuery(): SpecQuery {
+    // Preserve the inner hit recipe's full query tree — it may carry
+    // wrappers (specOverride / sliceAxes / nested linkerJoin) that the
+    // host needs to apply correctly. We only rebrand the terminal column
+    // leaf to this.id so two variants of the same physical hit reached via
+    // different linker chains stay distinct columns in the engine output.
+    const hitRecipe =
+      this.columns[this.key.column] ??
+      throwError(`ColumnDiscoveredRecipe.buildSpecQuery: missing column ${this.key.column}`);
+    let query: SpecQuery = rebrandLeafId(hitRecipe.getQuery(), hitRecipe.id, this.id);
+    const path = this.key.path ?? [];
+
+    for (let i = path.length - 1; i >= 0; i--) {
+      const linker =
+        this.columns[path[i].column] ??
+        throwError(
+          `ColumnDiscoveredRecipe.buildSpecQuery: missing linker column ${path[i].column}`,
+        );
+      query = {
+        type: "linkerJoin",
+        linker: linker.getQuery(),
+        secondary: [{ entry: query }],
+      };
+    }
+    return query;
+  }
+}
+
+function referencedUniIdsOf(key: ColumnDiscoveredKey): Set<ColumnUniversalId> {
+  return new Set<ColumnUniversalId>([key.column, ...(key.path ?? []).map((item) => item.column)]);
+}