@milaboratories/pl-model-common 1.31.2 → 1.32.0

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

@@ -74,6 +74,20 @@ describe("traverseQuerySpec", () => {
     });
   });
 
+  it("transforms columns inside linkerJoin", () => {
+    const q: Q = {
+      type: "linkerJoin",
+      linker: { column: "l" },
+      secondary: [entry(col("a")), entry(col("b"))],
+    };
+    const result = traverseQuerySpec(q, { column: (c) => c.toUpperCase() });
+    expect(result).toEqual({
+      type: "linkerJoin",
+      linker: { column: "L" },
+      secondary: [entry({ type: "column", column: "A" }), entry({ type: "column", column: "B" })],
+    });
+  });
+
   it("transforms columns inside filter", () => {
     const q: Q = {
       type: "filter",
@@ -195,6 +209,15 @@ describe("collectSpecQueryColumns", () => {
     } as unknown as Q;
     expect(collectSpecQueryColumns(q)).toEqual([]);
   });
+
+  it("collects linker and secondary columns from linkerJoin", () => {
+    const q: Q = {
+      type: "linkerJoin",
+      linker: { column: "l" },
+      secondary: [entry(col("a")), entry(col("b"))],
+    };
+    expect(collectSpecQueryColumns(q)).toEqual(["l", "a", "b"]);
+  });
 });
 
 describe("sortSpecQuery", () => {
@@ -221,6 +244,20 @@ describe("sortSpecQuery", () => {
     });
   });
 
+  it("sorts linkerJoin secondary entries (linker column unchanged)", () => {
+    const q: SpecQuery = {
+      type: "linkerJoin",
+      linker: { column: pid("l") },
+      secondary: [pentry(pcol("c")), pentry(pcol("a")), pentry(pcol("b"))],
+    };
+    const result = sortSpecQuery(q);
+    expect(result).toEqual({
+      type: "linkerJoin",
+      linker: { column: "l" },
+      secondary: [pentry(pcol("a")), pentry(pcol("b")), pentry(pcol("c"))],
+    });
+  });
+
   it("sorts sparseToDenseColumn axesIndices", () => {
     const q: SpecQuery = {
       type: "sparseToDenseColumn",

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

@@ -78,6 +78,13 @@ export function traverseQuerySpec<C1, C2>(
         secondary: query.secondary.map(traverseEntry),
       };
       break;
+    case "linkerJoin":
+      result = {
+        ...query,
+        linker: { ...query.linker, column: visitor.column(query.linker.column) },
+        secondary: query.secondary.map(traverseEntry),
+      };
+      break;
     case "filter":
     case "sort":
     case "sliceAxes":
@@ -126,6 +133,10 @@ export function sortSpecQuery(query: SpecQuery): SpecQuery {
           const sorted = [...node.secondary].sort(cmpQueryJoinEntrySpec);
           return { ...node, secondary: sorted };
         }
+        case "linkerJoin": {
+          const sorted = [...node.secondary].sort(cmpQueryJoinEntrySpec);
+          return { ...node, secondary: sorted };
+        }
         case "sliceAxes":
           return {
             ...node,
@@ -198,6 +209,20 @@ function cmpQuerySpec(lhs: SpecQuery, rhs: SpecQuery): number {
       }
       return 0;
     }
+    case "linkerJoin": {
+      const rhsLinker = rhs as typeof lhs;
+      if (lhs.linker.column !== rhsLinker.linker.column) {
+        return lhs.linker.column < rhsLinker.linker.column ? -1 : 1;
+      }
+      if (lhs.secondary.length !== rhsLinker.secondary.length) {
+        return lhs.secondary.length - rhsLinker.secondary.length;
+      }
+      for (let i = 0; i < lhs.secondary.length; i++) {
+        const cmp = cmpQueryJoinEntrySpec(lhs.secondary[i], rhsLinker.secondary[i]);
+        if (cmp !== 0) return cmp;
+      }
+      return 0;
+    }
     case "sliceAxes":
       return cmpQuerySpec(lhs.input, (rhs as typeof lhs).input);
     case "sort":

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

@@ -50,7 +50,12 @@ export class AnchoredIdDeriver {
    * Creates a new anchor context from a set of anchor column specifications
    * @param anchors Record of anchor column specifications indexed by anchor ID
    */
-  constructor(public readonly anchors: Record<string, PColumnSpec>) {
+  constructor(
+    public readonly anchors: Record<
+      string,
+      Pick<PColumnSpec, "axesSpec" | "domain" | "contextDomain">
+    >,
+  ) {
     const anchorEntries = Object.entries(anchors);
     anchorEntries.sort((a, b) => a[0].localeCompare(b[0]));
     for (const [anchorId, spec] of anchorEntries) {
@@ -241,7 +246,7 @@ export type ResolveAnchorsOptions = {
  * @returns A non-anchored column matcher with all references resolved to actual values
  */
 export function resolveAnchors(
-  anchors: Record<string, PColumnSpec>,
+  anchors: Record<string, Pick<PColumnSpec, "axesSpec" | "domain" | "contextDomain">>,
   matcher: AnchoredPColumnSelector,
   options?: ResolveAnchorsOptions,
 ): PColumnSelector {
@@ -321,7 +326,7 @@ export function resolveAnchors(
  * Resolves an anchored axis reference to a concrete AxisId
  */
 function resolveAxisReference(
-  anchors: Record<string, PColumnSpec>,
+  anchors: Record<string, Pick<PColumnSpec, "axesSpec">>,
   axisRef: AAxisSelector,
 ): LegacyAxisSelector {
   if (!isAnchorAxisRef(axisRef)) return axisRef;

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

@@ -145,6 +145,7 @@ export const Annotation = {
   IsScore: "pl7.app/isScore",
   IsSubset: "pl7.app/isSubset",
   Label: "pl7.app/label",
+  LinkLabel: "pl7.app/linkLabel",
   Max: "pl7.app/max",
   Min: "pl7.app/min",
   MultipliesBy: "pl7.app/multipliesBy",
@@ -204,10 +205,24 @@ export type Annotation = Metadata &
     [Annotation.Table.FontFamily]: string;
     [Annotation.Table.OrderPriority]: StringifiedJson<number>;
     [Annotation.Table.Visibility]: "hidden" | "optional" | (string & {});
-    [Annotation.Trace]: StringifiedJson<Record<string, unknown>>;
+    [Annotation.Trace]: StringifiedJson<Trace>;
     [Annotation.VDJ.IsAssemblingFeature]: StringifiedJson<boolean>;
   }>;
 
+/// One step in a column's derivation lineage. Only `type` and `label` are part
+/// of the typed public surface; writers may add fields (e.g. `id`, `importance`)
+/// passed through opaquely as `unknown`, accessed via explicit narrowing.
+const TraceEntrySchema = z
+  .object({
+    type: z.string(),
+    label: z.string(),
+  })
+  .catchall(z.unknown());
+
+export type TraceEntry = z.infer<typeof TraceEntrySchema>;
+
+export type Trace = TraceEntry[];
+
 // export const AxisSpec = z.object({
 //   type: z.nativeEnum(ValueType),
 //   name: z.string(),
@@ -256,7 +271,7 @@ export const AnnotationJson: AnnotationJson = {
   [Annotation.Sequence.Annotation.Mapping]: z.record(z.string(), z.string()),
   [Annotation.Sequence.IsAnnotation]: z.boolean(),
   [Annotation.Table.OrderPriority]: z.number(),
-  [Annotation.Trace]: z.record(z.string(), z.unknown()),
+  [Annotation.Trace]: z.array(TraceEntrySchema),
   [Annotation.VDJ.IsAssemblingFeature]: z.boolean(),
 };
 
@@ -527,11 +542,9 @@ export function getNormalizedAxesList(axes: AxisSpec[]): AxisSpecNormalized[] {
 
 /** Create list of regular axisSpec from normalized (parents are indexes, inside of current axes list) */
 export function getDenormalizedAxesList(axesSpec: AxisSpecNormalized[]): AxisSpec[] {
-  const idsList = axesSpec.map((axisSpec) => canonicalizeJson(getAxisId(axisSpec)));
+  const idsList = axesSpec.map(canonicalizeAxisId);
   return axesSpec.map((axisSpec) => {
-    const parentsIds = axisSpec.parentAxesSpec.map((axisSpec) =>
-      canonicalizeJson(getAxisId(axisSpec)),
-    );
+    const parentsIds = axisSpec.parentAxesSpec.map(canonicalizeAxisId);
     const parentIdxs = parentsIds.map((id) => idsList.indexOf(id));
     const { parentAxesSpec: _, ...copiedRest } = axisSpec;
     if (parentIdxs.length) {

package/src/drivers/pframe/spec_driver.ts

@@ -1,5 +1,6 @@
 import type { Branded } from "@milaboratories/helpers";
 import type { PoolEntry } from "../../pool_entry";
+import type { PObjectId } from "../../pool";
 import type {
   AxisSpec,
   AxesSpec,
@@ -111,8 +112,48 @@ export interface DiscoverColumnsLinkerStep {
   qualifications: AxisQualification[];
 }
 
+/**
+ * Filter step: intersects the current subquery with a filter column on shared
+ * axes. Filter columns carry `pl7.app/isSubset: "true"` with axes ⊆ dataset
+ * axes, so the inner-join narrows the key space to rows where the filter is
+ * present.
+ */
+export interface DiscoverColumnsFilterStep {
+  type: "filter";
+  /** The filter column applied in this step */
+  filter: PColumnIdAndSpec;
+}
+
 /** A step traversed during path-based column discovery. Discriminated by `type`. */
-export type DiscoverColumnsStepInfo = DiscoverColumnsLinkerStep;
+export type DiscoverColumnsStepInfo = DiscoverColumnsLinkerStep | DiscoverColumnsFilterStep;
+
+/**
+ * Input to {@link PFrameWasmV4.buildQuery}: a terminal column plus an ordered
+ * path of wrapping steps (linker hops, filter joins). Produces a
+ * {@link SpecQueryJoinEntry} ready to be plugged into an
+ * `innerJoin`/`fullJoin`/`outerJoin` entry list.
+ *
+ * Path ordering: `path[0]` is outermost (first applied), `path[N-1]` is
+ * closest to `column`. Omit or pass `[]` for a direct column with no
+ * wrapping.
+ *
+ * Columns are referenced by id — specs are resolved later at
+ * {@link PFrameWasmV4.evaluateQuery} against the registered specs of the
+ * PFrame, so the caller cannot disagree with the frame about spec content.
+ *
+ * Qualifications annotate the resulting outermost entry; they do not
+ * propagate into the inner query.
+ */
+export type BuildQueryInput = {
+  /** Shape version marker — bumped only on breaking structural changes. */
+  readonly version: "v1";
+  /** Terminal column id — the column actually returning data. */
+  readonly column: PObjectId;
+  /** Ordered path from source integration to `column`. Outermost first. */
+  readonly path?: DiscoverColumnsStepInfo[];
+  /** Axis qualifications attached to the resulting join entry. */
+  readonly qualifications?: AxisQualification[];
+};
 
 /** Qualifications info for a discover columns response mapping variant */
 export interface DiscoverColumnsResponseQualifications {

package/src/services/service_types.ts

@@ -1,3 +1,4 @@
+import { UnionToIntersection } from "@milaboratories/helpers";
 import type { Branded } from "../branding";
 import { ServiceAlreadyRegisteredError, ServiceInvalidIdError } from "../errors";
 import type { Services } from "./service_declarations";
@@ -101,12 +102,6 @@ export type ServiceRequireFlags = {
   [K in keyof SMap as `requires${K & string}`]?: boolean;
 };
 
-type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
-  k: infer I,
-) => void
-  ? I
-  : never;
-
 export type RequireServices<T extends ServiceName> = UnionToIntersection<
   T extends Branded<infer N extends string, infer S extends ServiceTypesLike>
     ? Record<N, InferServiceModel<S>>