@platforma-sdk/model 1.69.0 → 1.70.0

package/src/columns/ctx_column_sources.ts

@@ -9,32 +9,26 @@ import { ResourceTypeName } from "@milaboratories/pl-model-common";
 import type { ValueOf } from "@milaboratories/helpers";
 
 /**
- * Collect ColumnSnapshotProviders from all render context sources:
- *
- * - **resultPool** — all upstream columns (always included)
- * - **outputs** — PFrame fields from block execution outputs
- * - **prerun** — PFrame fields from prerun/staging results
- *
- * Returns an array of providers suitable for `ColumnCollectionBuilder.addSource()`.
+ * Collect ColumnSnapshotProviders from `outputs`, `prerun`, and
+ * `resultPool` in that order. Dedup keeps the first occurrence per
+ * `NativePObjectId`, so a block re-publishing its own columns keeps
+ * the `outputs`-rooted canonical id instead of the result-pool variant.
  */
 export function collectCtxColumnSnapshotProviders(ctx: RenderCtxBase): ColumnSnapshotProvider[] {
   const providers: ColumnSnapshotProvider[] = [];
 
-  // ResultPool — all upstream columns
-  providers.push(new ResultPoolColumnSnapshotProvider(ctx.resultPool));
-
-  // Outputs — each PFrame-like output field becomes a provider
   const outputs = ctx.outputs;
   if (outputs) {
     providers.push(...collectPFrameProviders(outputs));
   }
 
-  // Prerun — same treatment as outputs
   const prerun = ctx.prerun;
   if (prerun) {
     providers.push(...collectPFrameProviders(prerun));
   }
 
+  providers.push(new ResultPoolColumnSnapshotProvider(ctx.resultPool));
+
   return providers;
 }
 

package/src/components/PlDataTable/createPlDataTable/createPlDataTableV3.ts

@@ -405,7 +405,6 @@ function buildSecondaryGroups(
         entries: [
           ...lc.path.map((s) => ({
             column: resolveSnapshot(s.linker),
-            qualifications: s.qualifications,
           })),
           { column: resolveSnapshot(lc.column), qualifications: lc.qualifications.forHit },
         ],

package/src/components/PlDataTable/createPlDataTable/discoverColumns.ts

@@ -102,7 +102,6 @@ function mapToTableColumnVariants(
       path: variant.path.map((p) => ({
         type: "linker",
         column: p.linker.id,
-        qualifications: p.qualifications,
       })),
       columnQualifications: variant.qualifications.forHit,
       queriesQualifications: variant.qualifications.forQueries,

package/src/components/PlDataTable/createPlDataTable/utils.ts

@@ -241,7 +241,6 @@ export function deriveAllLabels(options: {
     spec: c.spec,
     linkerPath: c.linkerPath?.map((step) => ({
       spec: step.linker.spec,
-      qualifications: step.qualifications,
     })),
     qualifications: c.qualifications,
   }));

package/src/components/PlDatasetSelector/build_dataset_options.ts

@@ -1,20 +1,25 @@
-import type {
-  DatasetOption,
-  Option,
-  PColumnSelector,
-  PObjectSpec,
-} from "@milaboratories/pl-model-common";
+import type { MultiColumnSelector, Option, PObjectSpec } from "@milaboratories/pl-model-common";
+import { multiColumnSelectorsToPredicate } from "@milaboratories/pl-model-common";
 import type { DeriveLabelsOptions } from "../../labels/derive_distinct_labels";
 import type { RenderCtxBase } from "../../render";
 import { ColumnCollectionBuilder } from "../../columns/column_collection_builder";
 import { collectCtxColumnSnapshotProviders } from "../../columns/ctx_column_sources";
+import type { DatasetOption } from "./dataset_selection";
 import { buildRefMap, filterMatchesToOptions, findFilterColumns } from "./filter_discovery";
+import { enrichmentVariantsToRefs, findEnrichmentColumns } from "./enrichment_discovery";
 
 export type BuildDatasetOptions = {
   /** Which result pool columns qualify as datasets. Defaults to all. */
-  selector?: PColumnSelector | PColumnSelector[] | ((spec: PObjectSpec) => boolean);
+  primary?: MultiColumnSelector | MultiColumnSelector[] | ((spec: PObjectSpec) => boolean);
   /** Formatting options for filter labels. */
   labelOptions?: DeriveLabelsOptions;
+  /**
+   * Enables enrichment discovery and filters hits attached to
+   * `DatasetOption.enrichments`. Use `() => true` to accept all; omit to disable.
+   */
+  withEnrichments?: MultiColumnSelector | MultiColumnSelector[] | ((spec: PObjectSpec) => boolean);
+  /** Maximum linker hops considered. Only used when `withEnrichments` is set. */
+  enrichmentMaxHops?: number;
 };
 
 /**
@@ -27,28 +32,54 @@ export function buildDatasetOptions(
   ctx: RenderCtxBase,
   opts?: BuildDatasetOptions,
 ): DatasetOption[] | undefined {
-  const predicate = opts?.selector ?? (() => true);
-  const options = ctx.resultPool.getOptions(predicate, { refsWithEnrichments: true });
+  const primary = opts?.primary;
+  const primaryPredicate =
+    primary === undefined
+      ? () => true
+      : typeof primary === "function"
+        ? primary
+        : multiColumnSelectorsToPredicate(primary);
+  const options = ctx.resultPool.getOptions(primaryPredicate, { refsWithEnrichments: true });
   if (options.length === 0) return [];
 
   const columnSources = collectCtxColumnSnapshotProviders(ctx);
   const refMap = buildRefMap(ctx.resultPool.getSpecs().entries);
   const pframeSpec = ctx.getService("pframeSpec");
 
-  return options.map((o: Option): DatasetOption => {
-    const datasetSpec = ctx.resultPool.getPColumnSpecByRef(o.ref);
-    if (!datasetSpec) return o;
+  return options.map((primary: Option): DatasetOption => {
+    const datasetSpec = ctx.resultPool.getPColumnSpecByRef(primary.ref);
+    if (!datasetSpec) return { primary };
 
     const builder = new ColumnCollectionBuilder(pframeSpec);
     for (const src of columnSources) builder.addSource(src);
     const collection = builder.build({ anchors: { main: datasetSpec } });
-    if (!collection) return o;
+    if (!collection) return { primary };
 
     try {
-      const matches = findFilterColumns(collection);
-      if (matches.length === 0) return o;
-      const filters = filterMatchesToOptions(matches, refMap, opts?.labelOptions);
-      return { ...o, filters };
+      const filterMatches = findFilterColumns(collection);
+      const filters =
+        filterMatches.length === 0
+          ? undefined
+          : filterMatchesToOptions(filterMatches, refMap, opts?.labelOptions);
+
+      let enrichments;
+      if (opts?.withEnrichments !== undefined) {
+        const enrichmentVariants = findEnrichmentColumns(collection, {
+          maxHops: opts.enrichmentMaxHops,
+          ...(typeof opts.withEnrichments === "function"
+            ? { predicate: opts.withEnrichments }
+            : { include: opts.withEnrichments }),
+        });
+        if (enrichmentVariants.length > 0) {
+          enrichments = enrichmentVariantsToRefs(enrichmentVariants, opts.labelOptions);
+        }
+      }
+
+      return {
+        primary,
+        ...(filters !== undefined && filters.length > 0 ? { filters } : {}),
+        ...(enrichments !== undefined && enrichments.length > 0 ? { enrichments } : {}),
+      };
     } finally {
       collection.dispose();
     }

package/src/components/PlDatasetSelector/dataset_selection.ts

@@ -0,0 +1,37 @@
+import type { LabeledEnrichmentRefs, Option, PrimaryRef } from "@milaboratories/pl-model-common";
+
+/** Dataset picker entry: user picks {@link primary}, gets {@link enrichments} attached. */
+export type DatasetOption = {
+  readonly primary: Option;
+  readonly filters?: readonly Option[];
+  readonly enrichments?: LabeledEnrichmentRefs;
+};
+
+/**
+ * Picked dataset bundle emitted by `PlDatasetSelector`. Stored opaquely in
+ * block data; block authors unbundle inside their args resolver.
+ */
+export type DatasetSelection = {
+  readonly __isDatasetSelection: "v1";
+  readonly primary: PrimaryRef;
+  readonly enrichments?: LabeledEnrichmentRefs;
+};
+
+export function isDatasetSelection(value: unknown): value is DatasetSelection {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __isDatasetSelection?: unknown }).__isDatasetSelection === "v1" &&
+    "primary" in value
+  );
+}
+
+export function createDatasetSelection(
+  primary: PrimaryRef,
+  enrichments?: LabeledEnrichmentRefs,
+): DatasetSelection {
+  if (enrichments !== undefined && enrichments.length > 0) {
+    return { __isDatasetSelection: "v1", primary, enrichments };
+  }
+  return { __isDatasetSelection: "v1", primary };
+}

package/src/components/PlDatasetSelector/enrichment_discovery.ts

@@ -0,0 +1,111 @@
+import { Annotation, createEnrichmentRef } from "@milaboratories/pl-model-common";
+import type {
+  EnrichmentStep,
+  LabeledEnrichmentRef,
+  LabeledEnrichmentRefs,
+  MultiColumnSelector,
+  PObjectId,
+  PObjectSpec,
+} from "@milaboratories/pl-model-common";
+import type {
+  AnchoredColumnCollection,
+  ColumnVariant,
+} from "../../columns/column_collection_builder";
+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;
+  }
+}
+
+/**
+ * Linker-reached hits attached to the anchor primary. Drops zero-hop variants
+ * (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[] {
+  const include =
+    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) 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;
+    return true;
+  });
+}
+
+/**
+ * Pair each variant with a path-disambiguated label (so export headers stay
+ * unique) and carry hit/linker `PObjectId`s through verbatim. Propagates
+ * `qualifications.forHit`; `forQueries` is re-derived by the table builder.
+ */
+export function enrichmentVariantsToRefs(
+  variants: ColumnVariant[],
+  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 labels = deriveDistinctLabels(entries, labelOptions);
+
+  return variants.map((variant, i): LabeledEnrichmentRef => {
+    const path: EnrichmentStep[] = variant.path.map((step) => ({
+      type: "linker",
+      linker: step.linker.id,
+    }));
+    return {
+      ref: createEnrichmentRef(variant.column.id, {
+        path,
+        qualifications: variant.qualifications.forHit,
+      }),
+      label: labels[i],
+    };
+  });
+}

package/src/components/PlDatasetSelector/index.ts

@@ -1,2 +1,3 @@
+export * from "./dataset_selection";
 export * from "./filter_discovery";
 export * from "./build_dataset_options";

package/src/labels/derive_distinct_tooltips.test.ts

@@ -34,12 +34,8 @@ function linkerSnapshot(name: string, label?: string): ColumnSnapshot<PObjectId>
   };
 }
 
-function pathStep(
-  linkerName: string,
-  qualifications: AxisQualification[],
-  label?: string,
-): MatchVariant["path"][number] {
-  return { linker: linkerSnapshot(linkerName, label), qualifications };
+function pathStep(linkerName: string, label?: string): MatchVariant["path"][number] {
+  return { linker: linkerSnapshot(linkerName, label) };
 }
 
 describe("deriveDistinctTooltips", () => {
@@ -63,16 +59,13 @@ describe("deriveDistinctTooltips", () => {
     const entries: TooltipEntry[] = [
       {
         spec: createSpec("hit_col", "Hit Col"),
-        linkerPath: [
-          pathStep("linker_a", [axisQualification("sample", { batch: "A" })], "Linker A"),
-        ],
+        linkerPath: [pathStep("linker_a", "Linker A")],
       },
     ];
     const [tooltip] = deriveDistinctTooltips(entries);
     expect(tooltip).toBeDefined();
     expect(tooltip).toContain("Origin path");
     expect(tooltip).toContain("linker 1: Linker A");
-    expect(tooltip).toContain("qualifies: sample context: batch=A");
     expect(tooltip).toContain("hit column: Hit Col");
   });
 
@@ -146,7 +139,7 @@ describe("deriveDistinctTooltips", () => {
       {
         spec: createSpec("col1", "Col 1"),
         qualifications: { forQueries: {}, forHit: [] },
-        linkerPath: [pathStep("linker_a", [], "Linker A")],
+        linkerPath: [pathStep("linker_a", "Linker A")],
       },
     ];
     const [tooltip] = deriveDistinctTooltips(entries);
@@ -157,10 +150,7 @@ describe("deriveDistinctTooltips", () => {
     const entries: TooltipEntry[] = [
       {
         spec: createSpec("hit_col", "Hit Col"),
-        linkerPath: [
-          pathStep("linker_a", [], "Linker A"),
-          pathStep("linker_b", [axisQualification("sample", { batch: "B" })], "Linker B"),
-        ],
+        linkerPath: [pathStep("linker_a", "Linker A"), pathStep("linker_b", "Linker B")],
       },
     ];
     const [tooltip] = deriveDistinctTooltips(entries);
@@ -174,7 +164,7 @@ describe("deriveDistinctTooltips", () => {
         spec: createSpec("hit_col", "Hit"),
         variantIndex: 2,
         variantCount: 2,
-        linkerPath: [pathStep("linker_a", [axisQualification("sample", { batch: "B" })], "LA")],
+        linkerPath: [pathStep("linker_a", "LA")],
         qualifications: {
           forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "B" })] },
           forHit: [axisQualification("sample", { batch: "B" })],

package/src/labels/derive_distinct_tooltips.ts

@@ -46,7 +46,6 @@ function formatTooltip(entry: TooltipEntry): undefined | string {
 }
 
 const BULLET_1 = "  • ";
-const SUB_BULLET = "      ";
 
 function formatHeader(entry: TooltipEntry): undefined | string {
   const lines: string[] = [];
@@ -67,8 +66,6 @@ function formatOriginPath(entry: TooltipEntry): undefined | string {
       readAnnotation(step.linker.spec, Annotation.Label) ??
       step.linker.spec.name;
     lines.push(`${BULLET_1}linker ${i + 1}: ${label}`);
-    const qs = formatAxisQualifications(step.qualifications);
-    if (qs !== undefined) lines.push(`${SUB_BULLET}qualifies: ${qs}`);
   });
   const hitName = readAnnotation(entry.spec, Annotation.Label) ?? entry.spec.name;
   lines.push(`${BULLET_1}hit column: ${hitName}`);