@milaboratories/pl-model-common 1.46.4 → 1.47.0

package/src/drivers/pframe/spec/discovered_column.ts

@@ -1,35 +1,39 @@
-import { Branded, throwError } from "@milaboratories/helpers";
+import { type Branded, throwError } from "@milaboratories/helpers";
+import { type CanonicalizedJson, canonicalizeJson, parseJsonSafely } from "../../../json";
 import { PObjectId } from "../../../pool";
 import { AxisQualification } from "./selectors";
-import { canonicalizeJson } from "../../../json";
+import { ColumnUniversalId } from "./ids";
 
-export type DiscoveredPColumn = {
-  column: PObjectId;
+export interface ColumnDiscoveredKey {
+  __isDiscovered: true;
+  column: ColumnUniversalId;
   path?: PathItem[];
   columnQualifications?: AxisQualification[];
   queriesQualifications?: Record<PObjectId, AxisQualification[]>;
-};
+}
 
-export type DiscoveredPColumnId = Branded<PObjectId, "DiscoveredPColumnId">; // CanonicalizedJson<DiscoveredPColumn>;
+export type ColumnDiscoveredId = Branded<
+  CanonicalizedJson<ColumnDiscoveredKey>,
+  "ColumnDiscoveredId"
+>;
 
 type PathItem = {
   type: "linker";
-  column: PObjectId;
+  column: ColumnUniversalId;
 };
 
-export function isDiscoveredPColumn(obj: unknown): obj is DiscoveredPColumn {
-  return (
-    typeof obj === "object" &&
-    obj !== null &&
-    "path" in obj &&
-    "column" in obj &&
-    "columnQualifications" in obj &&
-    "queriesQualifications" in obj
-  );
+export function isColumnDiscoveredKey(obj: unknown): obj is ColumnDiscoveredKey {
+  return typeof obj === "object" && obj !== null && "__isDiscovered" in obj;
 }
 
-export function distillDiscoveredPColumn(props: DiscoveredPColumn): DiscoveredPColumn {
+export function isColumnDiscoveredId(str: unknown): str is ColumnDiscoveredId {
+  if (typeof str !== "string") return false;
+  return isColumnDiscoveredKey(parseJsonSafely(str));
+}
+
+export function distillColumnDiscoveredKey(props: ColumnDiscoveredKey): ColumnDiscoveredKey {
   return {
+    __isDiscovered: true,
     column: props.column,
     path: Array.isArray(props.path) && props.path.length > 0 ? props.path : undefined,
     columnQualifications:
@@ -43,30 +47,41 @@ export function distillDiscoveredPColumn(props: DiscoveredPColumn): DiscoveredPC
   };
 }
 
-export function createDiscoveredPColumnId(props: {
-  column: PObjectId;
+export function createColumnDiscoveredId(props: {
+  column: ColumnUniversalId;
+  path?: PathItem[];
+  columnQualifications?: AxisQualification[];
+  queriesQualifications?: Record<PObjectId, AxisQualification[]>;
+}): ColumnDiscoveredId {
+  return stringifyColumnDiscoveredId(props);
+}
+
+export function createColumnDiscoveredKey(props: {
+  column: ColumnUniversalId;
   path?: PathItem[];
   columnQualifications?: AxisQualification[];
   queriesQualifications?: Record<PObjectId, AxisQualification[]>;
-}): DiscoveredPColumnId {
-  return stringifyDiscoveredPColumnId(props);
+}): ColumnDiscoveredKey {
+  return distillColumnDiscoveredKey({ __isDiscovered: true, ...props });
 }
 
-export function parseDiscoveredPColumnId(id: DiscoveredPColumnId): DiscoveredPColumn {
+export function parseColumnDiscoveredId(id: ColumnDiscoveredId): ColumnDiscoveredKey {
   try {
     const parsed = JSON.parse(id);
-    return isDiscoveredPColumn(parsed)
+    return isColumnDiscoveredKey(parsed)
       ? parsed
       : throwError("Parsed object is not a valid DiscoveredPColumn");
   } catch {
     throw new Error(
-      "Invalid DiscoveredPColumnId: not a valid JSON or does not conform to DiscoveredPColumn structure",
+      "Invalid ColumnDiscoveredId: not a valid JSON or does not conform to DiscoveredPColumn structure",
     );
   }
 }
 
-export function stringifyDiscoveredPColumnId(id: DiscoveredPColumn) {
-  return canonicalizeJson<DiscoveredPColumn>(
-    distillDiscoveredPColumn(id),
-  ) as string as DiscoveredPColumnId;
+export function stringifyColumnDiscoveredId(
+  id: Omit<ColumnDiscoveredKey, "__isDiscovered">,
+): ColumnDiscoveredId {
+  return canonicalizeJson<ColumnDiscoveredKey>(
+    distillColumnDiscoveredKey({ __isDiscovered: true, ...id }),
+  ) as ColumnDiscoveredId;
 }

package/src/drivers/pframe/spec/filtered_column.ts

@@ -1,4 +1,8 @@
+import { type Branded } from "@milaboratories/helpers";
+import { type CanonicalizedJson, canonicalizeJson, parseJsonSafely } from "../../../json";
 import type { AnchoredPColumnId } from "./selectors";
+import { ColumnUniversalId } from "./ids";
+import type { PColumnSpec } from "./spec";
 
 /** Value of an axis filter */
 export type AxisFilterValue = number | string;
@@ -29,13 +33,75 @@ export type FilteredPColumn<CID = AnchoredPColumnId, AFI = AxisFilter> = {
   axisFilters: AFI[];
 };
 
+/** @deprecated */
 export type FilteredPColumnId = FilteredPColumn<AnchoredPColumnId, AxisFilterByIdx>;
 
 /**
  * Checks if a given value is a FilteredPColumn
  * @param id - The value to check
  * @returns True if the value is a FilteredPColumn, false otherwise
+ * @deprecated use {@link isColumnFilteredKey} for the key form and `source` checks for the id form
  */
 export function isFilteredPColumn(id: unknown): id is FilteredPColumn {
   return typeof id === "object" && id !== null && "source" in id && "axisFilters" in id;
 }
+
+/**
+ * `source` is either a leaf {@link PObjectId} or a {@link ColumnDiscoveredId}.
+ * Filtered never nests inside Filtered (flat-merge invariant), and Filtered is
+ * never the outer wrapper around Overridden — Overridden is always outermost.
+ */
+export interface ColumnFilteredKey {
+  __isFiltered: true;
+  source: ColumnUniversalId;
+  axisFilters: AxisFilterByIdx[];
+}
+
+export type ColumnFilteredId = Branded<CanonicalizedJson<ColumnFilteredKey>, "ColumnFilteredId">;
+
+export function stringifyColumnFilteredId(
+  key: Omit<ColumnFilteredKey, "__isFiltered">,
+): ColumnFilteredId {
+  return canonicalizeJson<ColumnFilteredKey>(createColumnFilteredKey(key)) as ColumnFilteredId;
+}
+
+export function isColumnFilteredKey(obj: unknown): obj is ColumnFilteredKey {
+  return typeof obj === "object" && obj !== null && "__isFiltered" in obj;
+}
+
+export function isColumnFilteredId(id: unknown): id is ColumnFilteredId {
+  if (typeof id !== "string") return false;
+  return isColumnFilteredKey(parseJsonSafely(id));
+}
+
+export function createColumnFilteredId(props: {
+  source: ColumnUniversalId;
+  axisFilters: AxisFilterByIdx[];
+}): ColumnFilteredId {
+  return stringifyColumnFilteredId(props);
+}
+
+export function createColumnFilteredKey(props: {
+  source: ColumnUniversalId;
+  axisFilters: AxisFilterByIdx[];
+}): ColumnFilteredKey {
+  // `axisFilters` must be ordered by axis index so logically
+  // identical filtered columns produce one canonical id.
+  const axisFilters = props.axisFilters.toSorted((a, b) => a[0] - b[0]);
+  return { __isFiltered: true, source: props.source, axisFilters };
+}
+
+/**
+ * Drop the axes pinned by `axisFilters` from a {@link PColumnSpec}'s
+ * `axesSpec`. Indices are positional against `spec.axesSpec`. Returns `spec`
+ * unchanged when there are no filters.
+ *
+ * Single source of the Filtered-layer spec math — shared by
+ * `reconstructSpecFromId` (host, id-walking) and `ColumnFilteredRecipe.getSpec`
+ * (sandbox, recipe-graph walking).
+ */
+export function applyAxisFilters(spec: PColumnSpec, axisFilters: AxisFilterByIdx[]): PColumnSpec {
+  if (axisFilters.length === 0) return spec;
+  const fixed = new Set(axisFilters.map(([i]) => i));
+  return { ...spec, axesSpec: spec.axesSpec.filter((_, i) => !fixed.has(i)) };
+}

package/src/drivers/pframe/spec/ids.ts

@@ -1,34 +1,159 @@
-import type { Branded } from "../../../branding";
 import type { AnchoredPColumnId } from "./selectors";
-import type { FilteredPColumnId } from "./filtered_column";
-import canonicalize from "canonicalize";
-import type { PObjectId } from "../../../pool";
-import { DiscoveredPColumn } from "./discovered_column";
+import {
+  applyAxisFilters,
+  isColumnFilteredKey,
+  type ColumnFilteredId,
+  type ColumnFilteredKey,
+  type FilteredPColumnId,
+} from "./filtered_column";
+import {
+  createPObjectId,
+  isPObjectId,
+  isPObjectKey,
+  LocalPObjectKey,
+  type GlobalPObjectId,
+  type GlobalPObjectKey,
+  type LocalPObjectId,
+  type PObjectId,
+} from "../../../pool";
+import {
+  isColumnDiscoveredKey,
+  type ColumnDiscoveredId,
+  type ColumnDiscoveredKey,
+} from "./discovered_column";
+import { throwError } from "@milaboratories/helpers";
+import {
+  applySpecOverrides,
+  isColumnOverriddenKey,
+  type ColumnOverriddenId,
+  type ColumnOverriddenKey,
+} from "./overridden";
+import { canonicalizeJson } from "../../../json";
+import { AxisSpec, PColumnSpec } from "./spec";
+import { isString } from "es-toolkit";
+
+/**
+ * Per-axis patches keyed by positional index in the base spec's `axesSpec`.
+ *
+ * Using position rather than `name` lets us disambiguate linker-style specs
+ * that carry multiple axes with the same `name` differentiated by `domain` /
+ * `contextDomain` (e.g. a `group`, `group/primary`, `group/secondary` triple).
+ *
+ * A patch at index `>= base.axesSpec.length` appends a new axis at that slot.
+ */
+export type AxisPatches = Record<number, Partial<AxisSpec>>;
 
 /**
  * Universal column identifier optionally anchored and optionally filtered.
+ * @deprecated use {@link ColumnUniversalKey}
  */
-export type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId | DiscoveredPColumn;
+export type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId;
 
 /**
  * Canonically serialized {@link UniversalPColumnId}.
+ * @deprecated use {@link ColumnUniversalId}
  */
-export type SUniversalPColumnId = Branded<PObjectId, "SUniversalPColumnId", "__pl_model_brand_2__">;
+export type SUniversalPColumnId = ColumnUniversalId;
+// export type SUniversalPColumnId = Branded<PObjectId, "SUniversalPColumnId", "__pl_model_brand_2__">;
+
+export type ColumnUniversalKey =
+  | LocalPObjectKey
+  | GlobalPObjectKey
+  | ColumnFilteredKey
+  | ColumnDiscoveredKey
+  | ColumnOverriddenKey;
+
+export type ColumnUniversalId =
+  | LocalPObjectId
+  | GlobalPObjectId
+  | ColumnFilteredId
+  | ColumnDiscoveredId
+  | ColumnOverriddenId;
 
 /**
- * Canonically serializes a {@link UniversalPColumnId} to a string.
- * @param id - The column identifier to serialize
- * @returns The canonically serialized string
+ * Canonically serializes a column key to a branded string id. Accepts both
+ * the new {@link ColumnUniversalKey} and the deprecated {@link UniversalPColumnId}
+ * (anchored / old filtered object form).
  */
-export function stringifyColumnId(id: UniversalPColumnId): SUniversalPColumnId {
-  return canonicalize(id)! as SUniversalPColumnId;
+export function stringifyColumnId(id: ColumnUniversalKey | UniversalPColumnId): ColumnUniversalId {
+  return canonicalizeJson(id) as ColumnUniversalId;
+}
+
+/**
+ * Parses a canonically serialized column id back to its key form.
+ */
+export function parseColumnId(str: ColumnUniversalId): ColumnUniversalKey {
+  return JSON.parse(str) as ColumnUniversalKey;
+}
+
+export function parseColumnIdSafely(
+  str: ColumnUniversalId,
+  fallback = undefined,
+): ColumnUniversalKey | typeof fallback {
+  try {
+    return JSON.parse(str) as ColumnUniversalKey;
+  } catch {
+    return fallback;
+  }
 }
 
 /**
- * Parses a canonically serialized {@link UniversalPColumnId} from a string.
- * @param str - The string to parse
- * @returns The parsed column identifier
+ * Walk a rich column id down to its terminal leaf {@link PObjectId}.
  */
-export function parseColumnId(str: SUniversalPColumnId): UniversalPColumnId {
-  return JSON.parse(str) as UniversalPColumnId;
+export function extractPObjectId(id: ColumnUniversalId | ColumnUniversalKey): PObjectId {
+  if (isString(id)) {
+    if (isPObjectId(id)) return id;
+
+    const parsed =
+      parseColumnIdSafely(id) ??
+      throwError(`extractPObjectId: id "${id}" is not a valid canonical column id`);
+    return extractPObjectId(parsed);
+  }
+
+  if (isPObjectKey(id)) return createPObjectId(id);
+  if (isColumnFilteredKey(id)) return extractPObjectId(id.source);
+  if (isColumnOverriddenKey(id)) return extractPObjectId(id.source);
+  if (isColumnDiscoveredKey(id)) return extractPObjectId(id.column);
+
+  throw new Error(`extractPObjectId: unrecognized column id structure: ${JSON.stringify(id)}`);
+}
+
+/**
+ * Reconstruct the effective {@link PColumnSpec} for a rich column id by walking
+ * the id chain from leaf to outermost wrapper, applying each layer's spec
+ * transformation in the same order the corresponding recipe would.
+ *
+ * Layer semantics:
+ * - Leaf ({@link LocalPObjectKey} / {@link GlobalPObjectKey}): no transformation.
+ * - {@link ColumnDiscoveredKey}: pass-through, descends into `column`.
+ * - {@link ColumnFilteredKey}: drops the axes whose positional index appears in
+ *   `axisFilters[i][0]` from the inner spec's `axesSpec` — mirrors
+ *   `ColumnFilteredRecipe.getSpec()`.
+ * - {@link ColumnOverriddenKey}: applies `specOverrides` via
+ *   {@link applySpecOverrides} on top of the inner spec.
+ */
+export function reconstructSpecFromId(
+  baseSpec: PColumnSpec,
+  id: ColumnUniversalId | ColumnUniversalKey,
+): PColumnSpec {
+  if (isString(id)) {
+    if (isPObjectId(id)) return baseSpec;
+
+    const parsed =
+      parseColumnIdSafely(id) ??
+      throwError(`reconstructSpecFromId: id "${id}" is not a valid canonical column id`);
+    return reconstructSpecFromId(baseSpec, parsed);
+  }
+
+  if (isPObjectKey(id)) return baseSpec;
+  if (isColumnDiscoveredKey(id)) return reconstructSpecFromId(baseSpec, id.column);
+  if (isColumnFilteredKey(id)) {
+    return applyAxisFilters(reconstructSpecFromId(baseSpec, id.source), id.axisFilters);
+  }
+  if (isColumnOverriddenKey(id)) {
+    const inner = reconstructSpecFromId(baseSpec, id.source);
+    return applySpecOverrides(inner, id.specOverrides);
+  }
+
+  throw new Error(`reconstructSpecFromId: unrecognized column id structure: ${JSON.stringify(id)}`);
 }

package/src/drivers/pframe/spec/index.ts

@@ -5,3 +5,4 @@ export * from "./spec";
 export * from "./selectors";
 export * from "./native_id";
 export * from "./discovered_column";
+export * from "./overridden";

package/src/drivers/pframe/spec/overridden.ts

@@ -0,0 +1,285 @@
+import { type Branded, throwError, type Mutable, Nil } from "@milaboratories/helpers";
+import { type CanonicalizedJson, canonicalizeJson } from "../../../json";
+import { AxisPatches, type ColumnUniversalId, parseColumnIdSafely } from "./ids";
+import type { AxisSpec, PColumnSpec } from "./spec";
+import { isNil, isString } from "es-toolkit";
+
+export type SpecOverrides = Pick<PColumnSpec, "domain" | "contextDomain" | "annotations"> & {
+  axesSpec?: AxisPatches;
+};
+
+/**
+ * `source` can reference a leaf or a Filtered/Discovered id, but never another
+ * Overridden id — there is no `Overridden<Overridden<...>>`. Repeated overrides
+ * merge at the outer wrapper via {@link mergeSpecOverrides}.
+ */
+export interface ColumnOverriddenKey {
+  __isOverridden: true;
+  source: Exclude<ColumnUniversalId, ColumnOverriddenId>;
+  specOverrides: SpecOverrides;
+}
+
+export type ColumnOverriddenId = Branded<
+  CanonicalizedJson<ColumnOverriddenKey>,
+  "ColumnOverriddenId"
+>;
+
+export function isColumnOverriddenKey(obj: unknown): obj is ColumnOverriddenKey {
+  return typeof obj === "object" && obj !== null && "__isOverridden" in obj;
+}
+
+export function distillColumnOverriddenKey(props: ColumnOverriddenKey): ColumnOverriddenKey {
+  return {
+    __isOverridden: true,
+    source: props.source,
+    specOverrides: props.specOverrides,
+  };
+}
+
+export function createColumnOverriddenId(props: {
+  source: ColumnUniversalId;
+  specOverrides: SpecOverrides;
+}): ColumnOverriddenId {
+  return stringifyColumnOverriddenId(createColumnOverriddenKey(props));
+}
+
+export function createColumnOverriddenKey(props: {
+  source: ColumnUniversalId;
+  specOverrides: SpecOverrides;
+}): ColumnOverriddenKey {
+  const { source, specOverrides } = props;
+  const unwrapped = unwrapOverrides(source);
+  const baseSource = unwrapped
+    ? unwrapped.source
+    : (source as Exclude<ColumnUniversalId, ColumnOverriddenId>);
+  const mergedOverrides = unwrapped
+    ? mergeSpecOverrides(unwrapped.specOverrides, specOverrides)
+    : specOverrides;
+
+  return {
+    __isOverridden: true,
+    source: baseSource,
+    specOverrides: mergedOverrides,
+  };
+}
+
+export function parseColumnOverriddenId(id: ColumnUniversalId): ColumnOverriddenKey {
+  try {
+    const parsed = JSON.parse(id);
+    return isColumnOverriddenKey(parsed)
+      ? parsed
+      : throwError("Parsed object is not a valid OverriddenPColumn");
+  } catch {
+    throw new Error(
+      "Invalid ColumnOverriddenId: not a valid JSON or does not conform to OverriddenPColumn structure",
+    );
+  }
+}
+
+export function stringifyColumnOverriddenId(id: ColumnOverriddenKey): ColumnOverriddenId {
+  return canonicalizeJson<ColumnOverriddenKey>(
+    distillColumnOverriddenKey(id),
+  ) as ColumnOverriddenId;
+}
+
+/**
+ * Peel one override-wrap layer.
+ *
+ * Invariant: `{source, specOverrides}` can only appear at the top level —
+ * the inner `source` is never itself an override-wrap. Anything else throws.
+ */
+export function unwrapOverrides(id: ColumnUniversalId): ColumnOverriddenKey | undefined {
+  const parsed = parseColumnIdSafely(id);
+  if (parsed === undefined || !isColumnOverriddenKey(parsed)) return undefined;
+  const inner = parseColumnIdSafely(parsed.source);
+  if (inner !== undefined && isColumnOverriddenKey(inner)) {
+    throw new Error("nested override-wrap detected — invariant broken");
+  }
+  return parsed;
+}
+
+/**
+ * Diff two specs into a {@link SpecOverrides} patch that, when applied on top
+ * of `base`, reconstructs `next`.
+ *
+ * - For top-level `annotations` / `domain` / `contextDomain`: include keys
+ *   whose value in `next` differs from `base` (or is missing in `base`).
+ *   Keys present in `base` but missing in `next` are not emitted — overrides
+ *   merge, they cannot delete.
+ * - For `axesSpec`: matched by **positional index**. Each `next[i]` is diffed
+ *   against `base[i]`; only changed fields are emitted as a patch under key
+ *   `i`. Indices past `base.length` carry the full new axis (append).
+ */
+export function deriveSpecDelta(base: PColumnSpec, next: PColumnSpec): SpecOverrides {
+  const annotations = recordDelta(base.annotations, next.annotations);
+  const domain = recordDelta(base.domain, next.domain);
+  const contextDomain = recordDelta(base.contextDomain, next.contextDomain);
+  const axesSpec = deriveAxesDelta(base.axesSpec, next.axesSpec);
+  return {
+    ...(axesSpec && { axesSpec }),
+    ...(annotations && { annotations }),
+    ...(domain && { domain }),
+    ...(contextDomain && { contextDomain }),
+  };
+}
+
+export function isEmptySpecDelta(delta: SpecOverrides): boolean {
+  return (
+    (!delta.annotations || Object.keys(delta.annotations).length === 0) &&
+    (!delta.domain || Object.keys(delta.domain).length === 0) &&
+    (!delta.contextDomain || Object.keys(delta.contextDomain).length === 0) &&
+    (!delta.axesSpec || Object.keys(delta.axesSpec).length === 0)
+  );
+}
+
+function deriveAxesDelta(
+  base: readonly AxisSpec[],
+  next: readonly AxisSpec[],
+): AxisPatches | undefined {
+  const out: AxisPatches = {};
+  let any = false;
+  for (let i = 0; i < next.length; i++) {
+    const a = next[i];
+    const b = base[i];
+    if (b === undefined) {
+      out[i] = a;
+      any = true;
+      continue;
+    }
+    const nameChanged = a.name !== b.name;
+    const typeChanged = a.type !== b.type;
+    const annotations = recordDelta(b.annotations, a.annotations);
+    const domain = recordDelta(b.domain, a.domain);
+    const contextDomain = recordDelta(b.contextDomain, a.contextDomain);
+    if (!nameChanged && !typeChanged && !annotations && !domain && !contextDomain) continue;
+    out[i] = {
+      ...(nameChanged && { name: a.name }),
+      ...(typeChanged && { type: a.type }),
+      ...(annotations && { annotations }),
+      ...(domain && { domain }),
+      ...(contextDomain && { contextDomain }),
+    };
+    any = true;
+  }
+  return any ? out : undefined;
+}
+
+function recordDelta(
+  base: Record<string, string> | undefined,
+  next: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!next) return undefined;
+  let any = false;
+  const diff: Record<string, string> = {};
+  for (const [k, v] of Object.entries(next)) {
+    if (!base || base[k] !== v) {
+      diff[k] = v;
+      any = true;
+    }
+  }
+  return any ? diff : undefined;
+}
+
+/**
+ * Apply `specOverrides` from a rich id (`SUniversalPColumnId`) on top of a
+ * resolved {@link PColumnSpec}. Returns `base` unchanged when the id carries
+ * no overrides.
+ */
+export function applySpecOverrides(
+  base: PColumnSpec,
+  idOrOverride: Nil | SpecOverrides | ColumnUniversalId,
+): PColumnSpec {
+  if (isNil(idOrOverride)) {
+    return base;
+  }
+
+  const overrides = isString(idOrOverride)
+    ? unwrapOverrides(idOrOverride)?.specOverrides
+    : idOrOverride;
+
+  if (isNil(overrides)) {
+    return base;
+  }
+
+  const result = { ...base };
+  if (overrides.annotations)
+    result.annotations = mergeRecord(base.annotations, overrides.annotations);
+  if (overrides.domain) result.domain = mergeRecord(base.domain, overrides.domain);
+  if (overrides.contextDomain)
+    result.contextDomain = mergeRecord(base.contextDomain, overrides.contextDomain);
+  if (overrides.axesSpec) result.axesSpec = applyAxesPatches(base.axesSpec, overrides.axesSpec);
+  return result;
+}
+
+/**
+ * Compose two override patches: applying `mergeSpecOverrides(prior, next)` on
+ * top of a base spec produces the same result as applying `prior` then `next`.
+ */
+export function mergeSpecOverrides(prior: SpecOverrides, next: SpecOverrides): SpecOverrides {
+  const result: Mutable<SpecOverrides> = {};
+  const axesSpec = mergeAxesPatches(prior.axesSpec, next.axesSpec);
+  if (axesSpec !== undefined) result.axesSpec = axesSpec;
+  const annotations = mergeRecord(prior.annotations, next.annotations);
+  if (annotations !== undefined) result.annotations = annotations;
+  const domain = mergeRecord(prior.domain, next.domain);
+  if (domain !== undefined) result.domain = domain;
+  const contextDomain = mergeRecord(prior.contextDomain, next.contextDomain);
+  if (contextDomain !== undefined) result.contextDomain = contextDomain;
+  return result;
+}
+
+/**
+ * Apply positional `patches` onto `base.axesSpec`. Patches deep-merge
+ * `annotations` / `domain` / `contextDomain` and shallow-override `name` /
+ * `type` at their slot. Indices `>= base.length` append new axes; intermediate
+ * gaps (if any) are filled with the patch itself, so callers should not leave
+ * holes between base.length and the highest patched index.
+ */
+function applyAxesPatches(base: readonly AxisSpec[], patches: AxisPatches): AxisSpec[] {
+  const result: AxisSpec[] = base.slice();
+  for (const [k, p] of Object.entries(patches)) {
+    const i = Number(k);
+    const existing = result[i];
+    result[i] = (existing === undefined ? p : mergeAxisPatch(existing, p)) as AxisSpec;
+  }
+  return result;
+}
+
+/**
+ * Compose two positional patch maps: `mergeAxesPatches(prior, next)` applied to
+ * a base spec must equal applying `prior` then `next`. Patches sharing an
+ * index deep-merge field-by-field.
+ */
+function mergeAxesPatches(
+  prior: AxisPatches | undefined,
+  next: AxisPatches | undefined,
+): AxisPatches | undefined {
+  if (!prior || Object.keys(prior).length === 0) return next;
+  if (!next || Object.keys(next).length === 0) return prior;
+  const result: AxisPatches = { ...prior };
+  for (const [k, p] of Object.entries(next)) {
+    const i = Number(k);
+    const existing = result[i];
+    result[i] = existing === undefined ? p : mergeAxisPatch(existing, p);
+  }
+  return result;
+}
+
+function mergeAxisPatch<A extends Partial<AxisSpec>>(axis: A, patch: Partial<AxisSpec>): A {
+  const result: Mutable<A> = { ...axis, ...patch };
+  if (patch.annotations) result.annotations = mergeRecord(axis.annotations, patch.annotations);
+  if (patch.domain) result.domain = mergeRecord(axis.domain, patch.domain);
+  if (patch.contextDomain) {
+    result.contextDomain = mergeRecord(axis.contextDomain, patch.contextDomain);
+  }
+  return result;
+}
+
+function mergeRecord(
+  a: Record<string, string> | undefined,
+  b: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!b) return a;
+  if (!a) return b;
+  return { ...a, ...b };
+}

package/src/drivers/pframe/spec/selectors.ts

@@ -64,6 +64,8 @@ export interface SingleAxisSelector {
   type?: AxisValueType;
   /** Domain requirements (optional) */
   domain?: Domain;
+  /** Context-domain requirements (optional) */
+  contextDomain?: Domain;
   /** Parent axes requirements (optional) */
   parentAxes?: SingleAxisSelector[];
 }
@@ -170,6 +172,7 @@ export interface PColumnSelector extends AnchoredPColumnSelector {
 /**
  * Strict identifier for PColumns in an anchored context
  * Unlike APColumnMatcher, this requires exact matches on domain and axes
+ * @deprecated This is part of the legacy column matching API. The new Columns API (see sdk/model/src/columns/) now handles column and axis
  */
 export interface AnchoredPColumnId extends AnchoredPColumnSelector {
   /** Name is required for exact column identification */