@milaboratories/pl-model-common 1.46.4 → 1.47.0

package/src/columns/types.ts

@@ -0,0 +1,116 @@
+import type { Branded } from "../branding";
+import type { PObjectId } from "../pool";
+
+/**
+ * Opaque sandbox/host accessor handle.
+ *
+ * Both the sandbox `TreeNodeAccessor.handle` and the host-issued accessor
+ * keys alias this brand — `sdk/model` re-exports the same type so the two
+ * sides stay structurally identical.
+ */
+export type AccessorHandle = Branded<string, "AccessorHandle">;
+
+/**
+ * Structural subset of {@link FieldTraversalStep} (from `@platforma-sdk/model`)
+ * needed by the host/sandbox column-providers traversal.
+ *
+ * Defined locally so this module does not depend on the sandbox `render`
+ * subtree. Both `TreeNodeAccessor.traverse` (sandbox) and
+ * `PlTreeNodeAccessor.traverse` (host) accept a superset of these fields, so
+ * structural compatibility is preserved.
+ */
+export interface FieldTraversalStepLike {
+  /** Field name */
+  readonly field: string;
+  /** Asserted field type — used by `accessor.traverse` to validate. */
+  readonly assertFieldType?: "Input" | "Output" | "Service" | "OTW" | "Dynamic" | "MTW";
+  /** Don't terminate chain if current resource or field has an error associated. */
+  readonly ignoreError?: true;
+}
+
+/**
+ * Raw entry returned by {@link GlobalCfgRenderCtxMethods.getUpstreamBlockCtx}
+ * on the sandbox side, or by `collectUpstreamBlockCtx` on the host side.
+ * Carries handle ids only — providers wrap them into accessor instances as
+ * needed.
+ *
+ * Generic over the handle type so the same shape backs both:
+ * - sandbox (`AHandle = AccessorHandle`, a `Branded<string, "AccessorHandle">`)
+ * - host (`AHandle = PlTreeNodeAccessor`, the resolved accessor instance)
+ *
+ * Default `AHandle = string` since `AccessorHandle` is a brand on `string` —
+ * the default is safe for the sandbox case.
+ */
+export interface UpstreamBlockCtx<AHandle = string> {
+  blockId: string;
+  prodCtx?: AHandle;
+  stagingCtx?: AHandle;
+  /** True when the `prodCtx` ctx-holder exists but `prodUiCtx` is still rendering. */
+  prodIncomplete?: boolean;
+  /** True when the `stagingCtx` ctx-holder exists but `stagingUiCtx` is still rendering. */
+  stagingIncomplete?: boolean;
+}
+
+/**
+ * Minimal accessor surface used by column-providers / column-registry
+ * traversal.
+ *
+ * Both sandbox `TreeNodeAccessor` and host `PlTreeNodeAccessor` satisfy this
+ * contract directly — `traverse(step)` is defined on both, and the other
+ * members already match by shape. No `resolvePath` member: when canonical
+ * `PObjectId`s are required (local-id construction inside the
+ * outputs/prerun branch), the traversal helpers thread the path explicitly.
+ */
+export interface AccessorLike<Self extends AccessorLike<Self>> {
+  /** Resource type carried by the underlying node (only `.name` is used). */
+  readonly resourceType: { readonly name: string };
+
+  /**
+   * Single-step field traversal. Returns `undefined` when the field is
+   * absent / unresolved (with `ignoreError`). Same shape on sandbox and host —
+   * sandbox `TreeNodeAccessor.traverse` is an alias for `resolveAny` and host
+   * `PlTreeNodeAccessor.traverse` is the canonical method.
+   */
+  traverse(step: FieldTraversalStepLike): Self | undefined;
+
+  /** List input-field names on this node. */
+  listInputFields(): string[];
+
+  /** Whether the input-field collection on this node is finalized. */
+  getInputsLocked(): boolean;
+
+  /** Whether this node has a data payload attached. */
+  hasData(): boolean;
+
+  /** Decode the data payload as JSON. Returns `undefined` if no data. */
+  getDataAsJson<T = unknown>(): T | undefined;
+}
+
+/**
+ * One indexed column — the canonical record produced by every traversal.
+ * Carries everything needed to read spec/data/status under a stable id.
+ *
+ * Generic over the accessor flavour so the same record shape works for both
+ * the sandbox `TreeNodeAccessor` and the host `PlTreeNodeAccessor`.
+ */
+export type LeafEntry<A extends AccessorLike<A>> = {
+  /** PFrame accessor that owns `<name>.spec` / `<name>.data` fields. */
+  accessor: A;
+  /** Field-name prefix inside the PFrame. */
+  name: string;
+  /** Canonical id under which this column is reachable. */
+  id: PObjectId;
+};
+
+/**
+ * Base interface for id-indexed column providers — the surface
+ * {@link ColumnRegistry} consumes. Generic over the concrete accessor flavour
+ * so it can back both sandbox (`TreeNodeAccessor`) and host
+ * (`PlTreeNodeAccessor` adapter) registries.
+ */
+export interface ColumnEntriesProvider<A extends AccessorLike<A>> {
+  /** Map of canonical {@link PObjectId} → {@link LeafEntry} for every column reachable from this source. */
+  getPObjectEntries(): ReadonlyMap<PObjectId, LeafEntry<A>>;
+  /** Whether enumeration of columns from this source has finalised. */
+  isFinal(): boolean;
+}

package/src/drivers/columns/columns_collection_driver.ts

@@ -0,0 +1,146 @@
+import type { Branded } from "../../branding";
+import type { PoolEntry } from "../../pool_entry";
+import type { AccessorHandle, AccessorLike, UpstreamBlockCtx } from "../../columns/types";
+import type { ColumnUniversalId } from "../pframe/spec/ids";
+import type { ColumnsDiscoverOptions, ColumnsFilterOptions } from "./discover_columns_options";
+import type { PFrameSpecDriver } from "../pframe/spec_driver";
+import type { PColumnSpec } from "../pframe/spec/spec";
+import type { PObjectId } from "../../pool";
+
+/**
+ * Opaque host-owned handle for a `ColumnsCollection` instance. Issued by
+ * {@link ColumnsCollectionDriver.create}, refcounted by the driver, and
+ * pinned to the active render ctx via the VM injector — sandbox never
+ * sees raw refcounting.
+ */
+export type CollectionHandle = Branded<string, "CollectionHandle">;
+
+/**
+ * JSON descriptor crossing the VM bridge in place of a sandbox
+ * `ColumnsSource`. Always plain data — no closures, no class instances.
+ *
+ * - `"collection"`  – reference another driver-managed collection by handle
+ *   (chaining, splicing).
+ * - `"result_pool"` – fan-out into the host's current render ctx upstream
+ *   block ctxes. Carries no payload — the host always uses its own pool.
+ * - `"accessor"`    – walk the host tree starting at the given accessor
+ *   handle from a `path` prefix.
+ * - `"ids"`         – pre-resolved id list (sandbox-materialised provider).
+ */
+export type SerializedColumnsSource =
+  | { readonly kind: "collection"; readonly handle: CollectionHandle }
+  | { readonly kind: "result_pool" }
+  | { readonly kind: "accessor"; readonly accessor: AccessorHandle; readonly path: string[] }
+  | { readonly kind: "ids"; readonly ids: ColumnUniversalId[]; readonly isFinal: boolean };
+
+/**
+ * Per-call host bindings the driver needs to resolve sources whose
+ * shape references render-ctx state (`"accessor"`, `"result_pool"`).
+ *
+ * The VM injector inside `pl-middle-layer` supplies these on every call;
+ * UI-side direct callers that only build collections out of `"ids"` /
+ * `"collection"` sources may omit the bindings entirely.
+ *
+ * Parameterised on the concrete accessor flavour so host implementations
+ * keep their static types (e.g. `PlTreeNodeAccessor`) without leaking that
+ * dependency into `@milaboratories/pl-model-common`.
+ */
+export interface ColumnsCollectionDriverHost<A extends AccessorLike<A> = AccessorLike<any>> {
+  /** Resolve an {@link AccessorHandle} to the host's concrete accessor. */
+  resolveAccessor(handle: AccessorHandle): A;
+
+  /** Snapshot of upstream-block ctx pairs from the current render ctx. */
+  getUpstreamBlockCtxes(): ReadonlyArray<UpstreamBlockCtx<A>>;
+
+  /**
+   * Per-call spec driver. The injector supplies the active render ctx's
+   * `PFrameSpec` service; `discover` / `filter` use it to build a spec
+   * frame and run a single discovery query.
+   */
+  getSpecDriver(): PFrameSpecDriver;
+
+  /**
+   * Resolve the canonical {@link PColumnSpec} for a leaf {@link PObjectId}.
+   * Returns `undefined` when the id is not present in the active registry
+   * (e.g. handed to the driver via a `{kind:"ids"}` source whose underlying
+   * column has since left the visible scope). Override-wrapped ids are
+   * unwrapped by the caller — this method only resolves the underlying leaf.
+   */
+  resolveSpec(id: PObjectId): PColumnSpec | undefined;
+}
+
+/**
+ * Sandbox / UI view of the `ColumnsCollection` driver. Same methods as
+ * {@link ColumnsCollectionDriver}, but the `host` parameters are dropped —
+ * the VM bridge / UI wrapper supplies them on every call so callers only
+ * pass plain data (handles + source descriptors + option objects).
+ *
+ * `getService("columnsCollection")` returns a value of this shape on both
+ * sandbox and UI sides.
+ */
+export interface ColumnsCollectionDriverModel {
+  /** Build a fresh collection from the supplied source descriptors. */
+  create(sources: ReadonlyArray<SerializedColumnsSource>): CollectionHandle;
+
+  /** Whether the collection currently exposes zero columns. */
+  isEmpty(handle: CollectionHandle): boolean;
+
+  /** Whether enumeration is finalised across every contributing source. */
+  isFinal(handle: CollectionHandle): boolean;
+
+  /** Canonical id list for the columns visible through this collection. */
+  getColumns(handle: CollectionHandle): ColumnUniversalId[];
+
+  /** Append one or more sources and return a fresh collection handle. */
+  addSource(
+    handle: CollectionHandle,
+    sources: ReadonlyArray<SerializedColumnsSource>,
+  ): CollectionHandle;
+
+  /** Anchored/selector-driven discovery. Returns a fresh handle. */
+  discover(handle: CollectionHandle, options: ColumnsDiscoverOptions): CollectionHandle;
+
+  /** Selector-only filter (no anchor traversal). Returns a fresh handle. */
+  filter(handle: CollectionHandle, options: ColumnsFilterOptions): CollectionHandle;
+}
+
+/**
+ * Synchronous host-side driver for `ColumnsCollection` operations. All
+ * collection state lives on the host side, addressable through opaque
+ * {@link CollectionHandle}s. Every handle-minting method returns a
+ * {@link PoolEntry} so callers can wire the refcount into their own
+ * lifecycle; the VM bridge pins each entry to the active render ctx and
+ * forwards only the handle string to sandbox.
+ *
+ * Sandbox / UI callers consume {@link ColumnsCollectionDriverModel}
+ * instead; the bridge maps that surface onto this one by injecting
+ * {@link ColumnsCollectionDriverHost} bindings.
+ */
+export interface ColumnsCollectionDriver {
+  create(
+    sources: ReadonlyArray<SerializedColumnsSource>,
+    host: ColumnsCollectionDriverHost,
+  ): PoolEntry<CollectionHandle>;
+
+  isEmpty(handle: CollectionHandle): boolean;
+  isFinal(handle: CollectionHandle): boolean;
+  getColumns(handle: CollectionHandle, host: ColumnsCollectionDriverHost): ColumnUniversalId[];
+
+  addSource(
+    handle: CollectionHandle,
+    sources: ReadonlyArray<SerializedColumnsSource>,
+    host: ColumnsCollectionDriverHost,
+  ): PoolEntry<CollectionHandle>;
+
+  discover(
+    handle: CollectionHandle,
+    options: ColumnsDiscoverOptions,
+    host: ColumnsCollectionDriverHost,
+  ): PoolEntry<CollectionHandle>;
+
+  filter(
+    handle: CollectionHandle,
+    options: ColumnsFilterOptions,
+    host: ColumnsCollectionDriverHost,
+  ): PoolEntry<CollectionHandle>;
+}

package/src/drivers/columns/discover_columns_options.ts

@@ -0,0 +1,91 @@
+import type { ColumnSelector, RelaxedColumnSelector } from "../../columns/column_selector";
+import type { PlRef } from "../../ref";
+import type { PObjectId } from "../../pool";
+import type { PColumnSpec, AxisQualification } from "../pframe/spec";
+import type { DiscoverColumnsConstraints } from "../pframe/spec_driver";
+
+/**
+ * Axis matching behaviour applied to `discover` requests.
+ *
+ * - `enrichment` (default) — anchor axes may float over un-mapped hit axes;
+ *   used by tooling that "extends" a query.
+ * - `related` — both source and hit axes may float; widest match.
+ * - `exact` — no floating, no qualifications; strict equality.
+ */
+export type MatchingMode = "enrichment" | "related" | "exact";
+
+/**
+ * Single entry accepted by `DiscoverColumnsOptions.anchors`. All variants are
+ * trivially JSON-serialisable so the option carrier crosses the
+ * sandbox/host VM bridge unchanged.
+ */
+export type AnchorEntry = PlRef | PObjectId | PColumnSpec | RelaxedColumnSelector;
+
+/** Qualifications needed for both already-integrated anchor columns and the hit column. */
+export interface MatchQualifications {
+  /** Qualifications for already-integrated anchor columns */
+  readonly forQueries?: Record<PObjectId, AxisQualification[]>;
+  /** Qualifications for the hit column. */
+  readonly forHit?: AxisQualification[];
+}
+
+/**
+ * Options object accepted by sandbox `discoverColumns()` and by the host
+ * `ColumnsCollectionDriver.discover` / `.filter` methods. Pure JSON shape —
+ * no class instances, no closures.
+ */
+export interface DiscoverColumnsOptions {
+  /** Include columns matching these selectors. If omitted, includes all. */
+  include?: ColumnSelector;
+  /** Exclude columns matching these selectors. */
+  exclude?: ColumnSelector;
+  /** Axis matching behavior. Default: 'enrichment'. Ignored if no anchors. */
+  mode?: MatchingMode;
+  /** Anchors enable axis-aware discovery + linker traversal. */
+  // @todo: migrate to array<AnchorEntry>
+  anchors?: Record<string, AnchorEntry>;
+  /** Maximum linker hops. Default: 4 when anchors present, 0 otherwise. */
+  maxHops?: number;
+}
+
+/**
+ * Options accepted by `ColumnsCollection.discover` / driver `.discover`.
+ * Traversal scope (`mode`, `maxHops`) must be specified explicitly — the
+ * defaults from {@link DiscoverColumnsOptions} are intentionally surfaced as
+ * required choices at the discovery entrypoint.
+ */
+export type ColumnsDiscoverOptions = DiscoverColumnsOptions;
+
+/**
+ * Options accepted by `ColumnsCollection.filter` / driver `.filter`. Traversal
+ * scope is fixed by the source collection, so `mode` / `maxHops` are not part
+ * of the filter surface — only `include` / `exclude` / `anchors`.
+ */
+export type ColumnsFilterOptions = Omit<DiscoverColumnsOptions, "mode" | "maxHops">;
+
+/** Translate a {@link MatchingMode} into the boolean-flag form the spec driver consumes. */
+export function matchingModeToConstraints(mode: MatchingMode): DiscoverColumnsConstraints {
+  switch (mode) {
+    case "enrichment":
+      return {
+        allowFloatingSourceAxes: true,
+        allowFloatingHitAxes: false,
+        allowSourceQualifications: true,
+        allowHitQualifications: true,
+      };
+    case "related":
+      return {
+        allowFloatingSourceAxes: true,
+        allowFloatingHitAxes: true,
+        allowSourceQualifications: true,
+        allowHitQualifications: true,
+      };
+    case "exact":
+      return {
+        allowFloatingSourceAxes: false,
+        allowFloatingHitAxes: false,
+        allowSourceQualifications: false,
+        allowHitQualifications: false,
+      };
+  }
+}

package/src/drivers/columns/index.ts

@@ -0,0 +1,2 @@
+export * from "./columns_collection_driver";
+export * from "./discover_columns_options";

package/src/drivers/index.ts

@@ -7,4 +7,5 @@ export * from "./log";
 export * from "./ls";
 
 export * from "./pframe";
+export * from "./columns";
 export * from "./ChunkedStreamReader";

package/src/drivers/pframe/index.ts

@@ -4,7 +4,6 @@ export * from "./filter_spec";
 export * from "./data_types";
 export * from "./find_columns";
 export * from "./pframe";
-export * from "./spec/spec";
 export * from "./table";
 export * from "./table_calculate";
 export * from "./table_common";

package/src/drivers/pframe/query/query_common.ts

@@ -1169,3 +1169,27 @@ export interface QueryTransformColumns<Q, E, SO> {
   /** Derived columns to compute (at least one). */
   columns: [TransformColumnEntry<E, SO>, ...TransformColumnEntry<E, SO>[]];
 }
+
+/**
+ * Spec-override query operation — client-side-only structural node.
+ *
+ * Overlays a {@link SpecOverrides} patch on top of the inner query's spec.
+ * Carries no topological change — it is collapsed at the host boundary
+ * (`resolvePColumn`) before the query reaches pframe-engine. The engine
+ * never sees this node.
+ *
+ * Emitted by `ColumnOverriddenRecipe.getQuery()`; the only currently
+ * supported shape is `specOverride{ input: <plain column ref>, override }`
+ * (i.e. `Overridden<Lazy>`). More complex projections under Overridden are
+ * a future engine work item.
+ *
+ * @template Q - Input query type
+ * @template SO - Spec override type
+ */
+export interface QuerySpecOverride<Q, SO> {
+  type: "specOverride";
+  /** Input query whose spec is to be overridden. */
+  input: Q;
+  /** Spec override patch to overlay on the inner spec. */
+  override: SO;
+}

package/src/drivers/pframe/query/query_spec.ts

@@ -1,4 +1,5 @@
 import type { PObjectId } from "../../../pool";
+import type { ColumnUniversalId } from "../spec/ids";
 import type {
   ExprAxisRef,
   ExprCast,
@@ -28,10 +29,12 @@ import type {
   QuerySliceAxes,
   QuerySort,
   QuerySparseToDenseColumn,
+  QuerySpecOverride,
   QuerySymmetricJoin,
   QueryTransformColumns,
 } from "./query_common";
 import type { Domain, PColumnIdAndSpec, SingleAxisSelector } from "../spec";
+import type { SpecOverrides } from "../spec/overridden";
 
 /**
  * Join entry for spec-layer queries — the base join entry extended with
@@ -43,8 +46,8 @@ import type { Domain, PColumnIdAndSpec, SingleAxisSelector } from "../spec";
  *   qualifications: [{ axis: { name: 'sample' }, contextDomain: { ... } }]
  * }
  */
-export type SpecQueryJoinEntry<C = PObjectId> = QueryJoinEntry<SpecQuery<C>> & {
-  qualifications?: {
+export type SpecQueryJoinEntry<C = ColumnUniversalId> = QueryJoinEntry<SpecQuery<C>> & {
+  qualifications?: readonly {
     /** Axis to qualify. */
     axis: SingleAxisSelector;
     /** Additional domain constraints for this axis. */
@@ -53,46 +56,54 @@ export type SpecQueryJoinEntry<C = PObjectId> = QueryJoinEntry<SpecQuery<C>> & {
 };
 
 /** @see QueryColumn */
-export type SpecQueryColumn<C = PObjectId> = QueryColumn<C>;
+export type SpecQueryColumn<C = ColumnUniversalId> = QueryColumn<C>;
 /** @see QueryInlineColumn */
 export type SpecQueryInlineColumn = QueryInlineColumn<PColumnIdAndSpec>;
 /** @see QuerySparseToDenseColumn */
-export type SpecQuerySparseToDenseColumn<C = PObjectId> = QuerySparseToDenseColumn<
+export type SpecQuerySparseToDenseColumn<C = ColumnUniversalId> = QuerySparseToDenseColumn<
   C,
   SingleAxisSelector,
   PColumnIdAndSpec
 >;
 /** @see QuerySymmetricJoin */
-export type SpecQuerySymmetricJoin<C = PObjectId> = QuerySymmetricJoin<SpecQueryJoinEntry<C>>;
+export type SpecQuerySymmetricJoin<C = ColumnUniversalId> = QuerySymmetricJoin<
+  SpecQueryJoinEntry<C>
+>;
 /** @see QueryOuterJoin */
-export type SpecQueryOuterJoin<C = PObjectId> = QueryOuterJoin<SpecQueryJoinEntry<C>>;
-/**
- * Linker side of a spec-layer linker-join.
- *
- * At the spec layer the linker is just a column reference — integration artifacts
- * (axes mapping, one-side indices) are derived during spec→data conversion.
- */
-export type SpecQueryLinkerJoinLinker<C = PObjectId> = {
-  /** Linker column reference. */
-  column: C;
-};
+export type SpecQueryOuterJoin<C = ColumnUniversalId> = QueryOuterJoin<SpecQueryJoinEntry<C>>;
 /** @see QueryLinkerJoin */
-export type SpecQueryLinkerJoin<C = PObjectId> = QueryLinkerJoin<
-  SpecQueryLinkerJoinLinker<C>,
+export type SpecQueryLinkerJoin<C = ColumnUniversalId> = QueryLinkerJoin<
+  SpecQuery<C>,
   SpecQueryJoinEntry<C>
 >;
 /** @see QuerySliceAxes */
-export type SpecQuerySliceAxes<C = PObjectId> = QuerySliceAxes<SpecQuery<C>, SingleAxisSelector>;
+export type SpecQuerySliceAxes<C = ColumnUniversalId> = QuerySliceAxes<
+  SpecQuery<C>,
+  SingleAxisSelector
+>;
 /** @see QuerySort */
-export type SpecQuerySort<C = PObjectId> = QuerySort<SpecQuery<C>, SpecQueryExpression>;
+export type SpecQuerySort<C = ColumnUniversalId> = QuerySort<SpecQuery<C>, SpecQueryExpression>;
 /** @see QueryFilter */
-export type SpecQueryFilter<C = PObjectId> = QueryFilter<SpecQuery<C>, SpecQueryBooleanExpression>;
+export type SpecQueryFilter<C = ColumnUniversalId> = QueryFilter<
+  SpecQuery<C>,
+  SpecQueryBooleanExpression
+>;
 /** @see QueryTransformColumns */
-export type SpecQueryTransformColumns<C = PObjectId> = QueryTransformColumns<
+export type SpecQueryTransformColumns<C = ColumnUniversalId> = QueryTransformColumns<
   SpecQuery<C>,
   SpecQueryExpression,
   PColumnIdAndSpec
 >;
+/**
+ * Client-side spec-override node — collapsed at the host boundary, never
+ * sent to pframe-engine.
+ *
+ * @see QuerySpecOverride
+ */
+export type SpecQuerySpecOverride<C = ColumnUniversalId> = QuerySpecOverride<
+  SpecQuery<C>,
+  SpecOverrides
+>;
 
 /**
  * Union of all spec layer query types.
@@ -108,8 +119,9 @@ export type SpecQueryTransformColumns<C = PObjectId> = QueryTransformColumns<
  * - Leaf nodes: column, inlineColumn, sparseToDenseColumn
  * - Join operations: innerJoin, fullJoin, outerJoin, linkerJoin
  * - Transformations: sliceAxes, sort, filter, transformColumns
+ * - Client-side overlays: specOverride (collapsed before reaching the engine)
  */
-export type SpecQuery<C = PObjectId> =
+export type SpecQuery<C = ColumnUniversalId> =
   | SpecQueryColumn<C>
   | SpecQueryInlineColumn
   | SpecQuerySparseToDenseColumn<C>
@@ -119,12 +131,13 @@ export type SpecQuery<C = PObjectId> =
   | SpecQuerySliceAxes<C>
   | SpecQuerySort<C>
   | SpecQueryFilter<C>
-  | SpecQueryTransformColumns<C>;
+  | SpecQueryTransformColumns<C>
+  | SpecQuerySpecOverride<C>;
 
 /** @see ExprAxisRef */
 export type SpecExprAxisRef = ExprAxisRef<SingleAxisSelector>;
 /** @see ExprColumnRef */
-export type SpecExprColumnRef = ExprColumnRef<PObjectId>;
+export type SpecExprColumnRef = ExprColumnRef<ColumnUniversalId>;
 
 export type SpecQueryExpression =
   | SpecExprColumnRef

package/src/drivers/pframe/query/utils.test.ts

@@ -85,13 +85,13 @@ describe("traverseQuerySpec", () => {
   it("transforms columns inside linkerJoin", () => {
     const q: Q = {
       type: "linkerJoin",
-      linker: { column: "l" },
+      linker: col("l"),
       secondary: [entry(col("a")), entry(col("b"))],
     };
     const result = traverseQuerySpec(q, { column: (c) => c.toUpperCase() });
     expect(result).toEqual({
       type: "linkerJoin",
-      linker: { column: "L" },
+      linker: { type: "column", column: "L" },
       secondary: [entry({ type: "column", column: "A" }), entry({ type: "column", column: "B" })],
     });
   });
@@ -180,7 +180,7 @@ describe("mapSpecQueryColumns", () => {
       primary: entry(col("a")),
       secondary: [entry(col("b"))],
     };
-    const result = mapSpecQueryColumns(q, (c) => c.toUpperCase());
+    const result = mapSpecQueryColumns(q, { column: (c) => c.toUpperCase() });
     expect(collectSpecQueryColumns(result)).toEqual(["A", "B"]);
   });
 });
@@ -229,7 +229,7 @@ describe("collectSpecQueryColumns", () => {
   it("collects linker and secondary columns from linkerJoin", () => {
     const q: Q = {
       type: "linkerJoin",
-      linker: { column: "l" },
+      linker: col("l"),
       secondary: [entry(col("a")), entry(col("b"))],
     };
     expect(collectSpecQueryColumns(q)).toEqual(["l", "a", "b"]);
@@ -263,13 +263,13 @@ describe("sortSpecQuery", () => {
   it("sorts linkerJoin secondary entries (linker column unchanged)", () => {
     const q: SpecQuery = {
       type: "linkerJoin",
-      linker: { column: pid("l") },
+      linker: pcol("l"),
       secondary: [pentry(pcol("c")), pentry(pcol("a")), pentry(pcol("b"))],
     };
     const result = sortSpecQuery(q);
     expect(result).toEqual({
       type: "linkerJoin",
-      linker: { column: "l" },
+      linker: pcol("l"),
       secondary: [pentry(pcol("a")), pentry(pcol("b")), pentry(pcol("c"))],
     });
   });

package/src/drivers/pframe/query/utils.ts

@@ -79,17 +79,25 @@ export function traverseQuerySpec<C1, C2>(
         secondary: query.secondary.map(traverseEntry),
       };
       break;
-    case "linkerJoin":
+    case "linkerJoin": {
+      // Back-compat: pre-#c7309fc8 blocks emit `linker` as `{ column }` without
+      // a `type` — tag it as a `column` node so recursion handles it normally.
+      const linker =
+        "type" in query.linker
+          ? query.linker
+          : ({ type: "column", column: (query.linker as { column: C1 }).column } as SpecQuery<C1>);
       result = {
         ...query,
-        linker: { ...query.linker, column: visitor.column(query.linker.column) },
+        linker: traverseQuerySpec(linker, visitor),
         secondary: query.secondary.map(traverseEntry),
       };
       break;
+    }
     case "filter":
     case "sort":
     case "sliceAxes":
     case "transformColumns":
+    case "specOverride":
       result = { ...query, input: traverseQuerySpec(query.input, visitor) };
       break;
     default:
@@ -102,9 +110,16 @@ export function traverseQuerySpec<C1, C2>(
 /** Recursively maps all column references in a SpecQuery tree. */
 export function mapSpecQueryColumns<C1, C2>(
   query: SpecQuery<C1>,
-  cb: (c: C1) => C2,
+  visitor: {
+    /** Transform column references in leaf nodes (column, sparseToDenseColumn). */
+    column: (c: C1) => C2;
+    /** Visit a node after its children have been traversed. */
+    node?: (node: SpecQuery<C2>) => SpecQuery<C2>;
+    /** Visit a join entry after its inner query has been traversed. */
+    joinEntry?: (entry: SpecQueryJoinEntry<C2>) => SpecQueryJoinEntry<C2>;
+  },
 ): SpecQuery<C2> {
-  return traverseQuerySpec(query, { column: cb });
+  return traverseQuerySpec(query, visitor);
 }
 
 /** Collects all column references from a SpecQuery tree. */
@@ -227,9 +242,8 @@ function cmpQuerySpec(lhs: SpecQuery, rhs: SpecQuery): number {
     }
     case "linkerJoin": {
       const rhsLinker = rhs as typeof lhs;
-      if (lhs.linker.column !== rhsLinker.linker.column) {
-        return lhs.linker.column < rhsLinker.linker.column ? -1 : 1;
-      }
+      const cmp = cmpQuerySpec(lhs.linker, rhsLinker.linker);
+      if (cmp !== 0) return cmp;
       if (lhs.secondary.length !== rhsLinker.secondary.length) {
         return lhs.secondary.length - rhsLinker.secondary.length;
       }
@@ -245,6 +259,12 @@ function cmpQuerySpec(lhs: SpecQuery, rhs: SpecQuery): number {
       return cmpQuerySpec(lhs.input, (rhs as typeof lhs).input);
     case "filter":
       return cmpQuerySpec(lhs.input, (rhs as typeof lhs).input);
+    case "specOverride": {
+      const rhsSo = rhs as typeof lhs;
+      const cmp = cmpQuerySpec(lhs.input, rhsSo.input);
+      if (cmp !== 0) return cmp;
+      return canonicalizeJson(lhs.override).localeCompare(canonicalizeJson(rhsSo.override));
+    }
     case "transformColumns": {
       const rhsTc = rhs as typeof lhs;
       const cmp = cmpQuerySpec(lhs.input, rhsTc.input);