@platforma-sdk/model 1.79.27 → 1.80.0

package/src/components/PlDatasetSelector/enrichment_discovery.ts

@@ -1,41 +1,41 @@
-import { Annotation, createEnrichmentRef } from "@milaboratories/pl-model-common";
+import {
+  Annotation,
+  createEnrichmentRef,
+  extractPObjectId,
+  isGlobalPObjectId,
+} from "@milaboratories/pl-model-common";
 import type {
+  ColumnsCollectionDriverModel,
   EnrichmentStep,
   LabeledEnrichmentRef,
   LabeledEnrichmentRefs,
   MultiColumnSelector,
-  PObjectId,
+  PColumnSpec,
   PObjectSpec,
 } from "@milaboratories/pl-model-common";
-import type {
-  AnchoredColumnCollection,
-  ColumnVariant,
-} from "../../columns/column_collection_builder";
+import type { ColumnRecipe, ColumnsSource } from "../../columns";
+import {
+  isLeafColumn,
+  ColumnsCollection,
+  collectLinkerIds,
+  hitQualifications,
+  collectLinkerColumns,
+  queriesQualifications,
+} from "../../columns";
 import {
   deriveDistinctLabels,
   type DeriveLabelsOptions,
   type Entry,
 } from "../../labels/derive_distinct_labels";
 
-/**
- * True for global-form ids — `canonicalize({__isRef: true, blockId, name})` —
- * which the workflow can resolve via bquery. Local-form ids (`resolvePath`)
- * fail this check and are excluded from auto-discovery; prerun/outputs hops
- * must be supplied as resolved `{spec, data}` instead.
- */
-function isGloballyAddressable(id: PObjectId): boolean {
-  try {
-    const decoded = JSON.parse(id);
-    return (
-      typeof decoded === "object" &&
-      decoded !== null &&
-      decoded.__isRef === true &&
-      typeof decoded.blockId === "string" &&
-      typeof decoded.name === "string"
-    );
-  } catch {
-    return false;
-  }
+export interface FindEnrichmentColumnsOptions {
+  sources: ReadonlyArray<ColumnsSource>;
+  anchorSpec: PColumnSpec;
+  maxHops?: number;
+  include?: MultiColumnSelector | MultiColumnSelector[];
+  predicate?: (spec: PObjectSpec) => boolean;
+  /** Override the resolved `columnsCollection` service (primarily for tests). */
+  driver?: ColumnsCollectionDriverModel;
 }
 
 /**
@@ -43,36 +43,34 @@ function isGloballyAddressable(id: PObjectId): boolean {
  * (filters / the primary itself) and structural hits (subset, linker, label
  * columns). Narrow further with `include` selectors or a `predicate`.
  */
-export function findEnrichmentColumns(
-  collection: AnchoredColumnCollection,
-  options?: {
-    maxHops?: number;
-    include?: MultiColumnSelector | MultiColumnSelector[];
-    predicate?: (spec: PObjectSpec) => boolean;
-  },
-): ColumnVariant[] {
+export function findEnrichmentColumns(options: FindEnrichmentColumnsOptions): ColumnRecipe[] {
   const include =
-    options?.include === undefined
+    options.include === undefined
       ? undefined
       : Array.isArray(options.include)
         ? options.include
         : [options.include];
-  const variants = collection.findColumnVariants({
-    mode: "enrichment",
-    maxHops: options?.maxHops ?? 4,
-    include,
-    exclude: [
-      { annotations: { [Annotation.IsSubset]: "true" } },
-      { annotations: { [Annotation.IsLinkerColumn]: "true" } },
-      { name: Annotation.Label },
-    ],
-  });
-  const predicate = options?.predicate;
-  return variants.filter((v) => {
-    if ((v.path?.length ?? 0) === 0) return false;
-    if (predicate !== undefined && !predicate(v.column.spec)) return false;
-    if (!isGloballyAddressable(v.column.id)) return false;
-    if (v.path?.some((p) => !isGloballyAddressable(p.linker.id))) return false;
+
+  const columns = ColumnsCollection([...options.sources], { driver: options.driver })
+    .discover({
+      anchors: { main: options.anchorSpec },
+      mode: "enrichment",
+      maxHops: options.maxHops ?? 4,
+      include,
+      exclude: [
+        { annotations: { [Annotation.IsSubset]: "true" } },
+        { annotations: { [Annotation.IsLinkerColumn]: "true" } },
+        { name: Annotation.Label },
+      ],
+    })
+    .getColumns();
+
+  const predicate = options.predicate;
+  return columns.filter((v) => {
+    if (isLeafColumn(v)) return false;
+    if (predicate !== undefined && !predicate(v.getSpec())) return false;
+    if (!isGlobalPObjectId(extractPObjectId(v.id))) return false;
+    if (collectLinkerIds(v).some((id) => !isGlobalPObjectId(id))) return false;
     return true;
   });
 }
@@ -83,27 +81,33 @@ export function findEnrichmentColumns(
  * `qualifications.forHit`; `forQueries` is re-derived by the table builder.
  */
 export function enrichmentVariantsToRefs(
-  variants: ColumnVariant[],
+  variants: ColumnRecipe[],
   labelOptions?: DeriveLabelsOptions,
 ): LabeledEnrichmentRefs {
   if (variants.length === 0) return [];
 
-  const entries: Entry[] = variants.map((variant) => ({
-    spec: variant.column.spec,
-    linkerPath: variant.path?.map((p) => ({ spec: p.linker.spec })),
-    qualifications: variant.qualifications,
+  const linkerIdsByVariant = variants.map((v) => collectLinkerIds(v));
+  const hitQualsByVariant = variants.map((v) => [...hitQualifications(v)]);
+
+  const entries: Entry[] = variants.map((variant, i) => ({
+    spec: variant.getSpec(),
+    linkerPath: collectLinkerColumns(variant).map((linker) => ({ spec: linker.getSpec() })),
+    qualifications: {
+      forHit: hitQualsByVariant[i],
+      forQueries: queriesQualifications(variant),
+    },
   }));
   const labels = deriveDistinctLabels(entries, labelOptions);
 
   return variants.map((variant, i): LabeledEnrichmentRef => {
-    const path: undefined | EnrichmentStep[] = variant.path?.map((step) => ({
-      type: "linker",
-      linker: step.linker.id,
-    }));
+    const path: undefined | EnrichmentStep[] =
+      linkerIdsByVariant[i].length === 0
+        ? undefined
+        : linkerIdsByVariant[i].map((id) => ({ type: "linker", linker: id }));
     return {
-      ref: createEnrichmentRef(variant.column.id, {
+      ref: createEnrichmentRef(extractPObjectId(variant.id), {
         path,
-        qualifications: variant.qualifications?.forHit,
+        qualifications: hitQualsByVariant[i],
       }),
       label: labels[i],
     };

package/src/components/PlDatasetSelector/filter_discovery.test.ts

@@ -1,25 +1,36 @@
-import { Annotation, createPlRef } from "@milaboratories/pl-model-common";
-import type { AxisSpec, PColumnSpec, PObjectId } from "@milaboratories/pl-model-common";
-import { SpecDriver } from "@milaboratories/pf-spec-driver";
+import { Annotation, createGlobalPObjectId, createPlRef } from "@milaboratories/pl-model-common";
+import type {
+  AxisSpec,
+  PColumn,
+  PColumnSpec,
+  PlRef,
+  PObjectId,
+} from "@milaboratories/pl-model-common";
 import canonicalize from "canonicalize";
-import { afterEach, describe, expect, test } from "vitest";
-import type { ColumnSnapshot } from "../../columns/column_snapshot";
-import { ColumnCollectionBuilder } from "../../columns/column_collection_builder";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import type { PColumnDataUniversal } from "../../render/internal";
 import { buildRefMap, filterMatchesToOptions, findFilterColumns } from "./filter_discovery";
+import {
+  createTestCollectionDriver,
+  type TestCollectionDriverHandle,
+} from "../../columns/__test_helpers__/collection_driver";
 
-const drivers: SpecDriver[] = [];
+let driverHandle: TestCollectionDriverHandle;
 
-function createSpecFrameCtx() {
-  const driver = new SpecDriver();
-  drivers.push(driver);
-  return driver;
-}
+beforeEach(() => {
+  driverHandle = createTestCollectionDriver();
+  driverHandle.installAmbientCtx();
+});
 
 afterEach(async () => {
-  for (const driver of drivers) await driver.dispose();
-  drivers.length = 0;
+  driverHandle.uninstallAmbientCtx();
+  await driverHandle.dispose();
 });
 
+function registerCols(cols: PColumn<PColumnDataUniversal | undefined>[]): void {
+  driverHandle.register(cols.map((c) => ({ id: c.id, spec: c.spec })));
+}
+
 function axis(name: string): AxisSpec {
   return { name, type: "String" } as AxisSpec;
 }
@@ -32,52 +43,68 @@ function spec(
   return { kind: "PColumn", name, valueType: "Int", axesSpec, annotations } as PColumnSpec;
 }
 
-function snap(id: string, s: PColumnSpec): ColumnSnapshot<PObjectId> {
-  return { id: id as PObjectId, spec: s, dataStatus: "ready", data: { get: () => ({}) as never } };
+function col(id: PObjectId, s: PColumnSpec): PColumn<PColumnDataUniversal | undefined> {
+  return {
+    id,
+    spec: s,
+    data: {} as never,
+  };
+}
+
+/** Canonical global PObjectId — required so downstream `extractPObjectId` accepts it. */
+function gid(name: string): PObjectId {
+  return createGlobalPObjectId("test-block", name);
 }
 
 // anchor defines the key space: [sample, gene]
 const anchorAxes = [axis("sample"), axis("gene")];
 const anchorSpec = spec("anchor", anchorAxes);
-const anchorSnap = snap("anchor-id", anchorSpec);
+const anchorSnap = col(gid("anchor"), anchorSpec);
 
 describe("findFilterColumns", () => {
   test("returns columns with pl7.app/isSubset annotation", () => {
-    const filter = snap("f1", spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" }));
-    const regular = snap("r1", spec("regular1", [axis("sample")]));
-
-    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([filter, regular, anchorSnap]);
-    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+    const filter = col(
+      gid("f1"),
+      spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" }),
+    );
+    const regular = col(gid("r1"), spec("regular1", [axis("sample")]));
+    registerCols([filter, regular, anchorSnap]);
 
-    const results = findFilterColumns(collection);
-    expect(results.every((m) => m.column.spec.name !== "regular1")).toBe(true);
-    expect(results.some((m) => m.column.spec.name === "filter1")).toBe(true);
+    const results = findFilterColumns({
+      sources: [{ columns: [filter, regular, anchorSnap], isFinal: true }],
+      anchorSpec,
+      driver: driverHandle.driver,
+    });
+    expect(results.every((m) => m.getSpec().name !== "regular1")).toBe(true);
+    expect(results.some((m) => m.getSpec().name === "filter1")).toBe(true);
   });
 
   test("axes subset: excludes filter whose axes are not a subset of anchor axes", () => {
     // filter with axis "other" — not a subset of anchor axes [sample, gene]
-    const badFilter = snap(
-      "f2",
+    const badFilter = col(
+      gid("f2"),
       spec("bad-filter", [axis("other")], { [Annotation.IsSubset]: "true" }),
     );
+    registerCols([badFilter, anchorSnap]);
 
-    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([badFilter, anchorSnap]);
-    const collection = builder.build({ anchors: { main: anchorSpec } })!;
-
-    const results = findFilterColumns(collection);
-    expect(results.every((m) => m.column.spec.name !== "bad-filter")).toBe(true);
+    const results = findFilterColumns({
+      sources: [{ columns: [badFilter, anchorSnap], isFinal: true }],
+      anchorSpec,
+      driver: driverHandle.driver,
+    });
+    expect(results.every((m) => m.getSpec().name !== "bad-filter")).toBe(true);
   });
 
   test("empty result when no filters exist", () => {
-    const regular = snap("r1", spec("regular1", [axis("sample")]));
-
-    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([regular, anchorSnap]);
-    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+    const regular = col(gid("r1"), spec("regular1", [axis("sample")]));
+    registerCols([regular, anchorSnap]);
 
-    expect(findFilterColumns(collection)).toHaveLength(0);
+    const results = findFilterColumns({
+      sources: [{ columns: [regular, anchorSnap], isFinal: true }],
+      anchorSpec,
+      driver: driverHandle.driver,
+    });
+    expect(results).toHaveLength(0);
   });
 });
 
@@ -101,18 +128,25 @@ describe("filterMatchesToOptions", () => {
     const filterRef1 = createPlRef("b1", "filter-top1000");
     const filterRef2 = createPlRef("b1", "filter-highconf");
 
-    const refMap = buildRefMap([{ ref: filterRef1 }, { ref: filterRef2 }]);
+    // Build ref map from entries (simulating result pool)
+    const refMap = buildRefMap([
+      { ref: anchorSnap.id as unknown as PlRef },
+      { ref: filterRef1 },
+      { ref: filterRef2 },
+    ]);
+
     const filterSpec1 = spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" });
     const filterSpec2 = spec("filter2", [axis("sample")], { [Annotation.IsSubset]: "true" });
 
-    const f1Snap = snap(canonicalize(filterRef1)! as string, filterSpec1);
-    const f2Snap = snap(canonicalize(filterRef2)! as string, filterSpec2);
-
-    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([f1Snap, f2Snap, anchorSnap]);
-    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+    const f1Snap = col(canonicalize(filterRef1)! as PObjectId, filterSpec1);
+    const f2Snap = col(canonicalize(filterRef2)! as PObjectId, filterSpec2);
+    registerCols([f1Snap, f2Snap, anchorSnap]);
 
-    const matches = findFilterColumns(collection);
+    const matches = findFilterColumns({
+      sources: [{ columns: [f1Snap, f2Snap, anchorSnap], isFinal: true }],
+      anchorSpec,
+      driver: driverHandle.driver,
+    });
     expect(matches.length).toBe(2);
 
     const options = filterMatchesToOptions(matches, {
@@ -120,7 +154,6 @@ describe("filterMatchesToOptions", () => {
       datasetSpec: anchorSpec,
     });
     expect(options).toHaveLength(2);
-    // Each option has a ref and label
     for (const opt of options) {
       expect(opt.ref).toBeDefined();
       expect(opt.label).toBeDefined();
@@ -153,13 +186,15 @@ describe("filterMatchesToOptions", () => {
         { type: "milaboratories.antibody-tcr-lead-selection", label: "Top 10", importance: 30 },
       ]),
     });
-    const fSnap = snap(canonicalize(filterRef)! as string, filterSpec);
-
-    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([fSnap, anchorSnap]);
-    const collection = builder.build({ anchors: { main: anchorSpec } })!;
-
-    const matches = findFilterColumns(collection);
+    const fSnap = col(canonicalize(filterRef)! as PObjectId, filterSpec);
+    const dsSnap = col(gid("dataset"), datasetSpec);
+    registerCols([fSnap, dsSnap]);
+
+    const matches = findFilterColumns({
+      sources: [{ columns: [fSnap, dsSnap], isFinal: true }],
+      anchorSpec: datasetSpec,
+      driver: driverHandle.driver,
+    });
     expect(matches).toHaveLength(1);
 
     const options = filterMatchesToOptions(matches, { refsByObjectId: refMap, datasetSpec });
@@ -215,14 +250,16 @@ describe("filterMatchesToOptions", () => {
         { type: "milaboratories.antibody-tcr-lead-selection", label: "Top 11", importance: 30 },
       ]),
     });
-    const f1Snap = snap(canonicalize(ref1)! as string, filterSpec1);
-    const f2Snap = snap(canonicalize(ref2)! as string, filterSpec2);
-
-    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([f1Snap, f2Snap, anchorSnap]);
-    const collection = builder.build({ anchors: { main: anchorSpec } })!;
-
-    const matches = findFilterColumns(collection);
+    const f1Snap = col(canonicalize(ref1)! as PObjectId, filterSpec1);
+    const f2Snap = col(canonicalize(ref2)! as PObjectId, filterSpec2);
+    const dsSnap = col(gid("dataset"), datasetSpec);
+    registerCols([f1Snap, f2Snap, dsSnap]);
+
+    const matches = findFilterColumns({
+      sources: [{ columns: [f1Snap, f2Snap, dsSnap], isFinal: true }],
+      anchorSpec: datasetSpec,
+      driver: driverHandle.driver,
+    });
     expect(matches).toHaveLength(2);
 
     const options = filterMatchesToOptions(matches, { refsByObjectId: refMap, datasetSpec });
@@ -239,14 +276,15 @@ describe("filterMatchesToOptions", () => {
     const knownRef = createPlRef("b1", "known");
     const knownSpec = spec("known", [axis("sample")], { [Annotation.IsSubset]: "true" });
     const orphanSpec = spec("orphan", [axis("sample")], { [Annotation.IsSubset]: "true" });
-    const knownSnap = snap(canonicalize(knownRef)! as string, knownSpec);
-    const orphanSnap = snap("orphan-id", orphanSpec);
-
-    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([knownSnap, orphanSnap, anchorSnap]);
-    const collection = builder.build({ anchors: { main: anchorSpec } })!;
-
-    const matches = findFilterColumns(collection);
+    const knownSnap = col(canonicalize(knownRef)! as PObjectId, knownSpec);
+    const orphanSnap = col(gid("orphan"), orphanSpec);
+    registerCols([knownSnap, orphanSnap, anchorSnap]);
+
+    const matches = findFilterColumns({
+      sources: [{ columns: [knownSnap, orphanSnap, anchorSnap], isFinal: true }],
+      anchorSpec,
+      driver: driverHandle.driver,
+    });
     expect(matches.length).toBe(2);
     const refMap = buildRefMap([{ ref: knownRef }]);
     const options = filterMatchesToOptions(matches, {

package/src/components/PlDatasetSelector/filter_discovery.ts

@@ -1,27 +1,45 @@
-import { Annotation } from "@milaboratories/pl-model-common";
-import type { Option, PlRef, PObjectId, PObjectSpec } from "@milaboratories/pl-model-common";
-import canonicalize from "canonicalize";
+import { Annotation, extractPObjectId } from "@milaboratories/pl-model-common";
 import type {
-  AnchoredColumnCollection,
-  ColumnMatch,
-} from "../../columns/column_collection_builder";
+  ColumnsCollectionDriverModel,
+  Option,
+  PColumnSpec,
+  PlRef,
+  PObjectId,
+  PObjectSpec,
+} from "@milaboratories/pl-model-common";
+import canonicalize from "canonicalize";
+import type { ColumnRecipe, ColumnsSource } from "../../columns";
+import { ColumnsCollection, collectLinkerColumns } from "../../columns";
 import {
   deriveDistinctLabels,
   type DeriveLabelsOptions,
   type Entry,
 } from "../../labels/derive_distinct_labels";
 
+export interface FindFilterColumnsOptions {
+  sources: ReadonlyArray<ColumnsSource>;
+  anchorSpec: PColumnSpec;
+  /** Override the resolved `columnsCollection` service (primarily for tests). */
+  driver?: ColumnsCollectionDriverModel;
+}
+
 /**
- * Columns annotated `pl7.app/isSubset: "true"` whose axes ⊆ anchor axes.
- * The axes-subset constraint comes from `mode: "enrichment"`.
+ * Matches columns annotated `pl7.app/isSubset: "true"` whose axes ⊆ anchor axes.
+ *
+ * Filter-intent: only the dataset's own direct subset columns, no linker
+ * traversal — so this uses `.filter()` (pins `maxHops: 0`), not `.discover()`
+ * (which would default to 4 hops and surface subset columns from other,
+ * linker-reachable datasets). `.filter()` still applies the default
+ * `enrichment` matching mode (`allowFloatingHitAxes: false`), which enforces
+ * the axes-subset constraint. See `matchingModeToConstraints()`.
  */
-export function findFilterColumns(collection: AnchoredColumnCollection): ColumnMatch[] {
-  return collection.findColumns({
-    mode: "enrichment",
-    include: {
-      annotations: { [Annotation.IsSubset]: "true" },
-    },
-  });
+export function findFilterColumns(options: FindFilterColumnsOptions): ColumnRecipe[] {
+  return ColumnsCollection([...options.sources], { driver: options.driver })
+    .filter({
+      anchors: { main: options.anchorSpec },
+      include: { annotations: { [Annotation.IsSubset]: "true" } },
+    })
+    .getColumns();
 }
 
 export type FilterMatchOptions = {
@@ -39,30 +57,32 @@ export type FilterMatchOptions = {
 };
 
 /**
- * Derive labels for filter column matches (for `DatasetOption.filters`).
- * Matches whose column id is missing from `refsByObjectId` are silently
- * dropped — they cannot be exposed as selectable options.
+ * Derive labeled options from filter column variants, for use in DatasetOption.filters.
+ *
+ * Entries whose column id has no PlRef in `refsByObjectId` are silently
+ * skipped — they cannot be exposed as user-selectable options.
  */
 export function filterMatchesToOptions(
-  matches: ColumnMatch[],
+  variants: ColumnRecipe[],
   options: FilterMatchOptions,
 ): Option[] {
-  if (matches.length === 0) return [];
+  if (variants.length === 0) return [];
 
   const { refsByObjectId, datasetSpec, labelOptions } = options;
 
-  // One entry per match-variant (different paths to the same column are
-  // exposed as separate Options). The `ref` field rides along on the
-  // Entry-shaped objects via structural typing; `deriveDistinctLabels`
-  // ignores extra fields.
-  const entries = matches.flatMap((match): (Entry & { ref: PlRef })[] => {
-    const ref = refsByObjectId.get(match.column.id);
+  // One Option per variant — `deriveDistinctLabels` disambiguates labels by
+  // path. All variants of the same column share a terminal PObjectId, so the
+  // ref lookup happens once per variant.
+  const entries: (Entry & { ref: PlRef })[] = variants.flatMap((variant) => {
+    const ref = refsByObjectId.get(extractPObjectId(variant.id));
     if (ref === undefined) return [];
-    return match.variants.map((variant) => ({
-      ref,
-      spec: match.column.spec,
-      linkerPath: variant.path.map((p) => ({ spec: p.linker.spec })),
-    }));
+    return [
+      {
+        ref,
+        spec: variant.getSpec(),
+        linkerPath: collectLinkerColumns(variant).map((linker) => ({ spec: linker.getSpec() })),
+      },
+    ];
   });
 
   // Appending the dataset forces a discriminating trace step into every

package/src/filters/converters/filterToQuery.test.ts

@@ -1,17 +1,24 @@
 import { describe, expect, it } from "vitest";
-import type { FilterSpec, FilterSpecLeaf } from "@milaboratories/pl-model-common";
+import type {
+  AxisId,
+  FilterSpec,
+  FilterSpecLeaf,
+  PObjectId,
+  PTableColumnId,
+} from "@milaboratories/pl-model-common";
 import { filterSpecToSpecQueryExpr } from "./filterToQuery";
 
-type QFilterSpec = FilterSpec<FilterSpecLeaf<string>>;
+type QFilterSpec = FilterSpec<FilterSpecLeaf<PTableColumnId>>;
 
-/** Helper: creates a CanonicalizedJson<PTableColumnId> for a regular column. */
-function colRef(id: string): string {
-  return JSON.stringify({ type: "column", id });
+/** Helper: creates a PTableColumnId for a regular column. */
+function colRef(id: string): PTableColumnId {
+  return { type: "column", id: id as PObjectId };
 }
 
-/** Helper: creates a CanonicalizedJson<PTableColumnId> for an axis. */
-function axisRef(id: string): string {
-  return JSON.stringify({ type: "axis", id });
+/** Helper: creates a PTableColumnId for an axis. AxisId stays as a string-shaped
+ *  value here because the converter passes `id` through to SingleAxisSelector. */
+function axisRef(id: string): PTableColumnId {
+  return { type: "axis", id: id as unknown as AxisId };
 }
 
 describe("filterSpecToSpecQueryExpr", () => {

package/src/filters/converters/filterToQuery.ts

@@ -1,23 +1,36 @@
 import { assertNever } from "@milaboratories/pl-model-common";
 import type {
+  AxisId,
+  ColumnUniversalId,
   FilterSpec,
   FilterSpecLeaf,
-  PTableColumnId,
   SingleAxisSelector,
   SpecQueryExpression,
 } from "@milaboratories/pl-model-common";
 import { traverseFilterSpec } from "../traverse";
 
-/** Parses a CanonicalizedJson<PTableColumnId> string into a SpecQueryExpression reference. */
-function resolveColumnRef(columnStr: string): SpecQueryExpression {
-  const parsed = JSON.parse(columnStr) as PTableColumnId;
-  return parsed.type === "axis"
-    ? { type: "axisRef", value: parsed.id as SingleAxisSelector }
-    : { type: "columnRef", value: parsed.id };
+export type QueryColumnIdAxis = {
+  type: "axis";
+  id: AxisId;
+};
+
+export type QueryColumnIdColumn = {
+  type: "column";
+  /** May be a rich {@link ColumnUniversalId} (Discovered / Overridden / Filtered) or bare PObjectId. */
+  id: ColumnUniversalId;
+};
+
+export type QueryColumnId = QueryColumnIdAxis | QueryColumnIdColumn;
+
+/** Converts a QueryColumnId object into a SpecQueryExpression reference. */
+function resolveColumnRef(col: QueryColumnId): SpecQueryExpression {
+  return col.type === "axis"
+    ? { type: "axisRef", value: col.id as SingleAxisSelector }
+    : { type: "columnRef", value: col.id };
 }
 
 /** Converts a FilterSpec tree into a SpecQueryExpression. */
-export function filterSpecToSpecQueryExpr<Leaf extends FilterSpecLeaf<string>>(
+export function filterSpecToSpecQueryExpr<Leaf extends FilterSpecLeaf<QueryColumnId>>(
   filter: FilterSpec<Leaf>,
 ): SpecQueryExpression {
   return traverseFilterSpec(filter, {
@@ -38,7 +51,7 @@ export function filterSpecToSpecQueryExpr<Leaf extends FilterSpecLeaf<string>>(
   });
 }
 
-function leafToSpecQueryExpr<Leaf extends FilterSpecLeaf<string>>(
+function leafToSpecQueryExpr<Leaf extends FilterSpecLeaf<QueryColumnId>>(
   filter: Leaf,
 ): SpecQueryExpression {
   switch (filter.type) {