@platforma-sdk/model 1.60.0 → 1.61.0

package/src/columns/column_collection_builder.test.ts

@@ -5,44 +5,26 @@ import type {
   SUniversalPColumnId,
 } from "@milaboratories/pl-model-common";
 import { AnchoredIdDeriver } from "@milaboratories/pl-model-common";
+import { SpecDriver } from "@milaboratories/pf-spec-driver";
 
-import { describe, expect, test } from "vitest";
+import { afterEach, describe, expect, test } from "vitest";
 import type { ColumnSnapshotProvider } from "./column_snapshot_provider";
 import type { ColumnSnapshot } from "./column_snapshot";
 import { ColumnCollectionBuilder } from "./column_collection_builder";
 
-// --- Mock SpecFrameCtx ---
+const drivers: SpecDriver[] = [];
 
 function createSpecFrameCtx() {
-  const frames = new Map<string, Record<string, PColumnSpec>>();
-  let nextId = 0;
-
-  return {
-    createSpecFrame: (specs: Record<string, PColumnSpec>) => {
-      const handle = `frame-${nextId++}`;
-      frames.set(handle, specs);
-      return handle;
-    },
-    specFrameDiscoverColumns: (handle: string, _request: any) => {
-      const specs = frames.get(handle)!;
-      return {
-        hits: Object.entries(specs).map(([columnId, spec]) => ({
-          hit: { columnId: columnId as PObjectId, spec },
-          mappingVariants: [
-            {
-              qualifications: { forQueries: [], forHit: [] },
-              distinctiveQualifications: { forQueries: [], forHit: [] },
-            },
-          ],
-        })),
-      };
-    },
-    specFrameDispose: (handle: string) => {
-      frames.delete(handle);
-    },
-  };
+  const driver = new SpecDriver();
+  drivers.push(driver);
+  return driver;
 }
 
+afterEach(() => {
+  for (const driver of drivers) driver.dispose();
+  drivers.length = 0;
+});
+
 // --- Helpers ---
 
 /** Default axis used when none specified — WASM requires at least one axis. */
@@ -173,15 +155,16 @@ describe("ColumnCollection.findColumns", () => {
     expect(collection.findColumns()).toHaveLength(2);
   });
 
-  test("exclude throws not implemented", () => {
+  test("exclude filters out matching columns", () => {
     const s1 = createSnapshot("id1", createSpec("col1"));
+    const s2 = createSnapshot("id2", createSpec("col2"));
     const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([s1]);
+    builder.addSource([s1, s2]);
 
     const collection = builder.build()!;
-    expect(() => collection.findColumns({ exclude: { name: "col1" } })).toThrow(
-      /not yet implemented/i,
-    );
+    const results = collection.findColumns({ exclude: { name: "col1" } });
+    expect(results).toHaveLength(1);
+    expect(results[0].spec.name).toBe("col2");
   });
 });
 
@@ -377,15 +360,16 @@ describe("AnchoredColumnCollection", () => {
     expect(matches[0].variants).toBeDefined();
   });
 
-  test("findColumns exclude throws not implemented", () => {
-    const snap = createSnapshot("id1", createSpec("col1", { axesSpec: [sampleAxis("sample")] }));
+  test("findColumns exclude filters out matching columns", () => {
+    const snap1 = createSnapshot("id1", createSpec("col1", { axesSpec: [sampleAxis("sample")] }));
+    const snap2 = createSnapshot("id2", createSpec("col2", { axesSpec: [sampleAxis("sample")] }));
     const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
-    builder.addSource([snap]);
+    builder.addSource([snap1, snap2]);
 
     const collection = builder.build({ anchors: { main: anchorSpec } })!;
-    expect(() => collection.findColumns({ exclude: { name: "col1" } })).toThrow(
-      /not yet implemented/i,
-    );
+    const results = collection.findColumns({ exclude: { name: "col1" } });
+    expect(results).toHaveLength(1);
+    expect(results[0].column.spec.name).toBe("col2");
   });
 
   test("allowPartialColumnList with anchors tracks completeness", () => {

package/src/columns/column_collection_builder.ts

@@ -2,6 +2,7 @@ import type {
   AxisQualification,
   ColumnAxesWithQualifications,
   DiscoverColumnsConstraints,
+  DiscoverColumnsStepInfo,
   MultiColumnSelector,
   NativePObjectId,
   PColumnSpec,
@@ -23,7 +24,7 @@ import type { GlobalCfgRenderCtxMethods } from "../render/internal";
 /** Subset of render context methods needed for spec frame operations. */
 type SpecFrameCtx = Pick<
   GlobalCfgRenderCtxMethods,
-  "createSpecFrame" | "specFrameDiscoverColumns" | "specFrameDispose"
+  "createSpecFrame" | "specFrameDiscoverColumns" | "disposeSpecFrame"
 >;
 
 // --- FindColumnsOptions ---
@@ -79,6 +80,8 @@ export interface ColumnMatch {
   readonly originalId: PObjectId;
   /** Match variants — different paths/qualifications that reach this column. */
   readonly variants: MatchVariant[];
+  /** Linker steps traversed to reach this hit; empty for direct matches. */
+  readonly path: DiscoverColumnsStepInfo[];
 }
 
 /** Qualifications needed for both query (already-integrated) columns and the hit column. */
@@ -253,24 +256,23 @@ class ColumnCollectionImpl implements ColumnCollection {
   }
 
   findColumns(options?: FindColumnsOptions): ColumnSnapshot<PObjectId>[] {
-    const columnFilter = options?.include ? toMultiColumnSelectors(options.include) : [];
+    const includeColumns = options?.include ? toMultiColumnSelectors(options.include) : undefined;
+    const excludeColumns = options?.exclude ? toMultiColumnSelectors(options.exclude) : undefined;
 
     const response = this.ctx.specFrameDiscoverColumns(this.specFrameHandle, {
-      columnFilter,
+      includeColumns,
+      excludeColumns,
       axes: [],
+      maxHops: 0,
       constraints: PLAIN_CONSTRAINTS,
     });
 
     // Map hits back to snapshots
-    let results = response.hits
+    const results = response.hits
       .map((hit) => this.columns.get(hit.hit.columnId as PObjectId))
       .filter((col): col is ColumnSnapshot<PObjectId> => col !== undefined)
       .map((col) => this.toSnapshot(col));
 
-    if (options?.exclude) {
-      throw new Error("Exclude filter is not yet implemented for plain ColumnCollection");
-    }
-
     return results;
   }
 
@@ -336,16 +338,19 @@ class AnchoredColumnCollectionImpl implements AnchoredColumnCollection {
   findColumns(options?: AnchoredFindColumnsOptions): ColumnMatch[] {
     const mode = options?.mode ?? "enrichment";
     const constraints = matchingModeToConstraints(mode);
-    const columnFilter = options?.include ? toMultiColumnSelectors(options.include) : [];
+    const includeColumns = options?.include ? toMultiColumnSelectors(options.include) : undefined;
+    const excludeColumns = options?.exclude ? toMultiColumnSelectors(options.exclude) : undefined;
 
     const response = this.ctx.specFrameDiscoverColumns(this.specFrameHandle, {
-      columnFilter,
+      includeColumns,
+      excludeColumns,
       constraints,
       axes: this.anchorAxes,
+      maxHops: options?.maxHops ?? 4,
     });
 
     // Map hits back to ColumnMatch entries
-    let results = response.hits
+    const results = response.hits
       .map((hit) => {
         const origId = hit.hit.columnId as PObjectId;
         const col = this.columns.get(origId);
@@ -360,14 +365,11 @@ class AnchoredColumnCollectionImpl implements AnchoredColumnCollection {
               distinctiveQualifications: v.distinctiveQualifications,
             }),
           ),
+          path: hit.path,
         } satisfies ColumnMatch;
       })
       .filter((m): m is ColumnMatch => m !== undefined);
 
-    if (options?.exclude) {
-      throw new Error("Exclude filter is not yet implemented for AnchoredColumnCollection");
-    }
-
     return results;
   }
 

package/src/columns/column_selector.ts

@@ -1,9 +1,10 @@
 import type {
+  AxisValueType,
+  ColumnValueType,
   MultiAxisSelector,
   MultiColumnSelector,
   PColumnSpec,
   StringMatcher,
-  ValueType,
 } from "@milaboratories/pl-model-common";
 
 export type { StringMatcher } from "@milaboratories/pl-model-common";
@@ -19,7 +20,7 @@ export type RelaxedRecord = Record<string, RelaxedStringMatchers>;
 /** Relaxed axis selector — accepts plain strings where strict requires StringMatcher[]. */
 export interface RelaxedAxisSelector {
   name?: RelaxedStringMatchers;
-  type?: ValueType | ValueType[];
+  type?: AxisValueType | AxisValueType[];
   domain?: RelaxedRecord;
   contextDomain?: RelaxedRecord;
   annotations?: RelaxedRecord;
@@ -28,7 +29,7 @@ export interface RelaxedAxisSelector {
 /** Relaxed column selector — convenient hand-written form. */
 export interface RelaxedColumnSelector {
   name?: RelaxedStringMatchers;
-  type?: ValueType | ValueType[];
+  type?: ColumnValueType | ColumnValueType[];
   domain?: RelaxedRecord;
   contextDomain?: RelaxedRecord;
   annotations?: RelaxedRecord;
@@ -57,7 +58,7 @@ function normalizeRecord(input: RelaxedRecord): Record<string, StringMatcher[]>
   return result;
 }
 
-function normalizeTypes(input: ValueType | ValueType[]): ValueType[] {
+function normalizeTypes<T>(input: T | T[]): T[] {
   return Array.isArray(input) ? input : [input];
 }
 
@@ -140,7 +141,7 @@ function matchAxisSelector(
   selector: MultiAxisSelector,
 ): boolean {
   if (selector.name !== undefined && !matchStringValue(axis.name, selector.name)) return false;
-  if (selector.type !== undefined && !selector.type.includes(axis.type as ValueType)) return false;
+  if (selector.type !== undefined && !selector.type.includes(axis.type)) return false;
   if (selector.domain !== undefined && !matchRecordField(axis.domain, selector.domain))
     return false;
   if (

package/src/render/api.ts

@@ -1,6 +1,8 @@
 import type {
   AnchoredPColumnSelector,
   AnyFunction,
+  AxesId,
+  AxesSpec,
   AxisId,
   DataInfo,
   DiscoverColumnsRequest,
@@ -17,6 +19,8 @@ import type {
   PObjectId,
   PObjectSpec,
   PSpecPredicate,
+  PTableColumnId,
+  PTableColumnSpec,
   PTableDef,
   PTableDefV2,
   PTableHandle,
@@ -25,6 +29,7 @@ import type {
   PlRef,
   ResolveAnchorsOptions,
   ResultCollection,
+  SingleAxisSelector,
   SUniversalPColumnId,
   ValueOrError,
 } from "@milaboratories/pl-model-common";
@@ -727,8 +732,24 @@ export abstract class RenderCtxBase<Args = unknown, Data = unknown> {
     return this.ctx.specFrameDiscoverColumns(handle, request);
   }
 
-  public specFrameDispose(handle: string): void {
-    this.ctx.specFrameDispose(handle);
+  public disposeSpecFrame(handle: string): void {
+    this.ctx.disposeSpecFrame(handle);
+  }
+
+  public expandAxes(spec: AxesSpec): AxesId {
+    return this.ctx.expandAxes(spec);
+  }
+
+  public collapseAxes(ids: AxesId): AxesSpec {
+    return this.ctx.collapseAxes(ids);
+  }
+
+  public findAxis(spec: AxesSpec, selector: SingleAxisSelector): number {
+    return this.ctx.findAxis(spec, selector);
+  }
+
+  public findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number {
+    return this.ctx.findTableColumn(tableSpec, selector);
   }
 
   public getCurrentUnstableMarker(): string | undefined {

package/src/render/internal.ts

@@ -1,8 +1,13 @@
 import type { Optional } from "utility-types";
 import type {
+  AxesId,
+  AxesSpec,
   Branded,
   DiscoverColumnsRequest,
   DiscoverColumnsResponse,
+  PTableColumnId,
+  PTableColumnSpec,
+  SingleAxisSelector,
   StringifiedJson,
 } from "@milaboratories/pl-model-common";
 import type { CommonFieldTraverseOps, FieldTraversalStep, ResourceType } from "./traversal_ops";
@@ -174,7 +179,19 @@ export interface GlobalCfgRenderCtxMethods<AHandle = AccessorHandle, FHandle = F
     request: DiscoverColumnsRequest,
   ): DiscoverColumnsResponse;
 
-  specFrameDispose(handle: string): void;
+  disposeSpecFrame(handle: string): void;
+
+  /** Expand index-based parentAxes in AxesSpec to resolved AxisId parents in AxesId. */
+  expandAxes(spec: AxesSpec): AxesId;
+
+  /** Collapse resolved AxisId parents back to index-based parentAxes in AxesSpec. */
+  collapseAxes(ids: AxesId): AxesSpec;
+
+  /** Find the index of an axis matching the given selector. Returns -1 if not found. */
+  findAxis(spec: AxesSpec, selector: SingleAxisSelector): number;
+
+  /** Find the flat index of a table column matching the given selector. Returns -1 if not found. */
+  findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number;
 
   //
   // Computable