@platforma-sdk/model 1.76.4 → 1.77.0

package/src/components/PlDataTable/typesV6.ts

@@ -1,152 +1,30 @@
-import type {
-  AxisId,
-  AxisSpec,
-  CanonicalizedJson,
-  ListOptionBase,
-  PTableColumnSpec,
-  PTableSorting,
-  PColumnIdAndSpec,
-  PTableHandle,
-  RootFilterSpec,
-  PTableColumnId,
-  PFrameHandle,
-} from "@milaboratories/pl-model-common";
-import type { FilterSpecLeaf } from "../../filters";
-import { Nil } from "@milaboratories/helpers";
+import type { CanonicalizedJson, PTableColumnSpec } from "@milaboratories/pl-model-common";
+import type { PlDataTableFiltersWithMeta, PlDataTableSheetState, PTableParamsV2 } from "./typesV7";
 
-export type PlTableColumnIdJson = CanonicalizedJson<PTableColumnSpec>;
+/**
+ * v6 colId scheme: bare canonicalized `PTableColumnSpec` (full spec including
+ * all annotations and `pl7.app/trace`). v7 dropped the spec body and now uses
+ * `CanonicalizedJson<PTableColumnId>` — orders of magnitude smaller.
+ */
+export type PlDataTableV6ColIdJson = CanonicalizedJson<PTableColumnSpec>;
 
-export type PlDataTableGridStateCore = {
-  /** Includes column ordering */
-  columnOrder?: {
-    /** All colIds in order */
-    orderedColIds: PlTableColumnIdJson[];
-  };
-  /** Includes current sort columns and direction */
-  sort?: {
-    /** Sorted columns and directions in order */
-    sortModel: {
-      /** Column Id to apply the sort to. */
-      colId: PlTableColumnIdJson;
-      /** Sort direction */
-      sort: "asc" | "desc";
-    }[];
-  };
-  /** Includes column visibility */
-  columnVisibility?: {
-    /** All colIds which were hidden */
-    hiddenColIds: PlTableColumnIdJson[];
-  };
+export type PlDataTableGridStateV6 = {
+  columnOrder?: { orderedColIds: PlDataTableV6ColIdJson[] };
+  sort?: { sortModel: { colId: PlDataTableV6ColIdJson; sort: "asc" | "desc" }[] };
+  columnVisibility?: { hiddenColIds: PlDataTableV6ColIdJson[] };
 };
 
-export type PlDataTableSheet = {
-  /** spec of the axis to use */
-  axis: AxisSpec;
-  /** options to show in the filter dropdown */
-  options: ListOptionBase<string | number>[];
-  /** default (selected) value */
-  defaultValue?: string | number;
-};
-
-export type PlDataTableSheetState = {
-  /** id of the axis */
-  axisId: AxisId;
-  /** selected value */
-  value: string | number;
-};
-
-/** Tree-based filter state compatible with PlAdvancedFilter's RootFilter */
-export type PlDataTableFilterMeta = {
-  id: number;
-  source?: "table-filter" | "table-search";
-  isExpanded?: boolean;
-  isSuppressed?: boolean;
-};
-export type PlDataTableFilterSpecLeaf = FilterSpecLeaf<CanonicalizedJson<PTableColumnId>>;
-export type PlDataTableFilters = RootFilterSpec<PlDataTableFilterSpecLeaf>;
-export type PlDataTableFiltersWithMeta = RootFilterSpec<
-  PlDataTableFilterSpecLeaf,
-  PlDataTableFilterMeta
->;
-
-export type PlDataTableStateV2CacheEntry = {
-  /** DataSource identifier for state management */
+export type PlDataTableStateV2V6CacheEntry = {
   sourceId: string;
-  /** Internal ag-grid state */
-  gridState: PlDataTableGridStateCore;
-  /** Sheets state */
+  gridState: PlDataTableGridStateV6;
   sheetsState: PlDataTableSheetState[];
-  /** User filters state (tree-based, compatible with PlAdvancedFilter) */
   filtersState: null | PlDataTableFiltersWithMeta;
-  /** Default filters state from model (snapshot of defaults) */
   defaultFiltersState: null | PlDataTableFiltersWithMeta;
-  /** Fast search string */
   searchString?: string;
 };
 
-export type PTableParamsV2 =
-  | {
-      sourceId: null;
-      hiddenColIds: null;
-      sorting: [];
-      filters: null;
-      defaultFilters: null;
-    }
-  | {
-      sourceId: string;
-      hiddenColIds: null | PTableColumnId[];
-      sorting: PTableSorting[];
-      filters: null | PlDataTableFilters;
-      defaultFilters: null | PlDataTableFilters;
-    };
-
-export type PlDataTableStateV2Normalized = {
-  /** Version for upgrades */
+export type PlDataTableStateV2V6 = {
   version: 6;
-  /** Internal states, LRU cache for 5 sourceId-s */
-  stateCache: PlDataTableStateV2CacheEntry[];
-  /** PTable params derived from the cache state for the current sourceId */
+  stateCache: PlDataTableStateV2V6CacheEntry[];
   pTableParams: PTableParamsV2;
 };
-
-/** PlAgDataTable model */
-export type PlDataTableModel = {
-  /** DataSource identifier for state management */
-  sourceId: null | string;
-  /** p-table including all columns, used to show the full specification of the table */
-  fullTableHandle?: PTableHandle;
-  /** p-frame handle */
-  fullPframeHandle?: PFrameHandle;
-  /** p-table including only visible columns, used to get the data */
-  visibleTableHandle?: PTableHandle;
-  /** Default filters from model options, surfaced for UI display */
-  defaultFilters?: Nil | PlDataTableFilters;
-};
-
-export type CreatePlDataTableOps = {
-  /** Filters for columns and non-partitioned axes */
-  filters?: PlDataTableFilters;
-
-  /** Sorting to columns hidden from user */
-  sorting?: PTableSorting[];
-
-  /**
-   * Selects columns for which will be inner-joined to the table.
-   *
-   * Default behaviour: all columns are considered to be core
-   */
-  coreColumnPredicate?: (spec: PColumnIdAndSpec) => boolean;
-
-  /**
-   * Determines how core columns should be joined together:
-   *   inner - so user will only see records present in all core columns
-   *   full - so user will only see records present in any of the core columns
-   *
-   * All non-core columns will be left joined to the table produced by the core
-   * columns, in other words records form the pool of non-core columns will only
-   * make their way into the final table if core table contains corresponding key.
-   *
-   * Default: 'full'
-   */
-  coreJoinType?: "inner" | "full";
-};

package/src/components/PlDataTable/typesV7.ts

@@ -0,0 +1,151 @@
+import type {
+  AxisId,
+  AxisSpec,
+  CanonicalizedJson,
+  ListOptionBase,
+  PTableSorting,
+  PColumnIdAndSpec,
+  PTableHandle,
+  RootFilterSpec,
+  PTableColumnId,
+  PFrameHandle,
+} from "@milaboratories/pl-model-common";
+import type { FilterSpecLeaf } from "../../filters";
+import { Nil } from "@milaboratories/helpers";
+
+export type PlTableColumnIdJson = CanonicalizedJson<PTableColumnId>;
+
+export type PlDataTableGridStateCore = {
+  /** Includes column ordering */
+  columnOrder?: {
+    /** All colIds in order */
+    orderedColIds: PlTableColumnIdJson[];
+  };
+  /** Includes current sort columns and direction */
+  sort?: {
+    /** Sorted columns and directions in order */
+    sortModel: {
+      /** Column Id to apply the sort to. */
+      colId: PlTableColumnIdJson;
+      /** Sort direction */
+      sort: "asc" | "desc";
+    }[];
+  };
+  /** Includes column visibility */
+  columnVisibility?: {
+    /** All colIds which were hidden */
+    hiddenColIds: PlTableColumnIdJson[];
+  };
+};
+
+export type PlDataTableSheet = {
+  /** spec of the axis to use */
+  axis: AxisSpec;
+  /** options to show in the filter dropdown */
+  options: ListOptionBase<string | number>[];
+  /** default (selected) value */
+  defaultValue?: string | number;
+};
+
+export type PlDataTableSheetState = {
+  /** id of the axis */
+  axisId: AxisId;
+  /** selected value */
+  value: string | number;
+};
+
+/** Tree-based filter state compatible with PlAdvancedFilter's RootFilter */
+export type PlDataTableFilterMeta = {
+  id: number;
+  source?: "table-filter" | "table-search";
+  isExpanded?: boolean;
+  isSuppressed?: boolean;
+};
+export type PlDataTableFilterSpecLeaf = FilterSpecLeaf<CanonicalizedJson<PTableColumnId>>;
+export type PlDataTableFilters = RootFilterSpec<PlDataTableFilterSpecLeaf>;
+export type PlDataTableFiltersWithMeta = RootFilterSpec<
+  PlDataTableFilterSpecLeaf,
+  PlDataTableFilterMeta
+>;
+
+export type PlDataTableStateV2CacheEntry = {
+  /** DataSource identifier for state management */
+  sourceId: string;
+  /** Internal ag-grid state */
+  gridState: PlDataTableGridStateCore;
+  /** Sheets state */
+  sheetsState: PlDataTableSheetState[];
+  /** User filters state (tree-based, compatible with PlAdvancedFilter) */
+  filtersState: null | PlDataTableFiltersWithMeta;
+  /** Default filters state from model (snapshot of defaults) */
+  defaultFiltersState: null | PlDataTableFiltersWithMeta;
+  /** Fast search string */
+  searchString?: string;
+};
+
+export type PTableParamsV2 =
+  | {
+      sourceId: null;
+      hiddenColIds: null;
+      sorting: [];
+      filters: null;
+      defaultFilters: null;
+    }
+  | {
+      sourceId: string;
+      hiddenColIds: null | PTableColumnId[];
+      sorting: PTableSorting[];
+      filters: null | PlDataTableFilters;
+      defaultFilters: null | PlDataTableFilters;
+    };
+
+export type PlDataTableStateV2Normalized = {
+  /** Version for upgrades */
+  version: 7;
+  /** Internal states, LRU cache for 5 sourceId-s */
+  stateCache: PlDataTableStateV2CacheEntry[];
+  /** PTable params derived from the cache state for the current sourceId */
+  pTableParams: PTableParamsV2;
+};
+
+/** PlAgDataTable model */
+export type PlDataTableModel = {
+  /** DataSource identifier for state management */
+  sourceId: null | string;
+  /** p-table including all columns, used to show the full specification of the table */
+  fullTableHandle?: PTableHandle;
+  /** p-frame handle */
+  fullPframeHandle?: PFrameHandle;
+  /** p-table including only visible columns, used to get the data */
+  visibleTableHandle?: PTableHandle;
+  /** Default filters from model options, surfaced for UI display */
+  defaultFilters?: Nil | PlDataTableFilters;
+};
+
+export type CreatePlDataTableOps = {
+  /** Filters for columns and non-partitioned axes */
+  filters?: PlDataTableFilters;
+
+  /** Sorting to columns hidden from user */
+  sorting?: PTableSorting[];
+
+  /**
+   * Selects columns for which will be inner-joined to the table.
+   *
+   * Default behaviour: all columns are considered to be core
+   */
+  coreColumnPredicate?: (spec: PColumnIdAndSpec) => boolean;
+
+  /**
+   * Determines how core columns should be joined together:
+   *   inner - so user will only see records present in all core columns
+   *   full - so user will only see records present in any of the core columns
+   *
+   * All non-core columns will be left joined to the table produced by the core
+   * columns, in other words records form the pool of non-core columns will only
+   * make their way into the final table if core table contains corresponding key.
+   *
+   * Default: 'full'
+   */
+  coreJoinType?: "inner" | "full";
+};

package/src/components/PlDatasetSelector/build_dataset_options.ts

@@ -31,7 +31,11 @@ export type BuildDatasetOptions = {
    * accept-all.
    */
   filter?: SpecPredicateOption;
-  /** Formatting options for filter labels. */
+  /**
+   * Formatting options forwarded to label derivation for both filter and
+   * enrichment rows. `formatters.native` on the filter path is overridden
+   * — see `FilterMatchOptions.labelOptions`.
+   */
   labelOptions?: DeriveLabelsOptions;
   /**
    * Enables enrichment discovery and filters hits attached to
@@ -96,7 +100,11 @@ export function buildDatasetOptions(
       const filters =
         filterMatches.length === 0
           ? undefined
-          : filterMatchesToOptions(filterMatches, refMap, opts?.labelOptions);
+          : filterMatchesToOptions(filterMatches, {
+              refsByObjectId: refMap,
+              datasetSpec,
+              labelOptions: opts?.labelOptions,
+            });
 
       let enrichments;
       if (enrichmentCollection && withEnrichments) {

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

@@ -1,5 +1,5 @@
 import { Annotation, createPlRef } from "@milaboratories/pl-model-common";
-import type { AxisSpec, PColumnSpec, PlRef, PObjectId } from "@milaboratories/pl-model-common";
+import type { AxisSpec, PColumnSpec, PObjectId } from "@milaboratories/pl-model-common";
 import { SpecDriver } from "@milaboratories/pf-spec-driver";
 import canonicalize from "canonicalize";
 import { afterEach, describe, expect, test } from "vitest";
@@ -85,10 +85,7 @@ describe("buildRefMap", () => {
   test("maps canonicalized PlRef to original ref", () => {
     const ref1 = createPlRef("b1", "out1");
     const ref2 = createPlRef("b2", "out2", true);
-    const entries = [{ ref: ref1 }, { ref: ref2 }];
-
-    const map = buildRefMap(entries);
-
+    const map = buildRefMap([{ ref: ref1 }, { ref: ref2 }]);
     expect(map.get(canonicalize(ref1)! as PObjectId)).toBe(ref1);
     expect(map.get(canonicalize(ref2)! as PObjectId)).toBe(ref2);
     expect(map.size).toBe(2);
@@ -104,18 +101,10 @@ describe("filterMatchesToOptions", () => {
     const filterRef1 = createPlRef("b1", "filter-top1000");
     const filterRef2 = createPlRef("b1", "filter-highconf");
 
-    // Build ref map from entries (simulating result pool)
-    const refMap = buildRefMap([
-      { ref: anchorSnap.id as unknown as PlRef }, // anchor — won't be looked up
-      { ref: filterRef1 },
-      { ref: filterRef2 },
-    ]);
-
-    // Build filter specs with isSubset annotation
+    const refMap = buildRefMap([{ ref: filterRef1 }, { ref: filterRef2 }]);
     const filterSpec1 = spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" });
     const filterSpec2 = spec("filter2", [axis("sample")], { [Annotation.IsSubset]: "true" });
 
-    // Use the canonical PlRef as the PObjectId (matches how result pool works)
     const f1Snap = snap(canonicalize(filterRef1)! as string, filterSpec1);
     const f2Snap = snap(canonicalize(filterRef2)! as string, filterSpec2);
 
@@ -126,7 +115,10 @@ describe("filterMatchesToOptions", () => {
     const matches = findFilterColumns(collection);
     expect(matches.length).toBe(2);
 
-    const options = filterMatchesToOptions(matches, refMap);
+    const options = filterMatchesToOptions(matches, {
+      refsByObjectId: refMap,
+      datasetSpec: anchorSpec,
+    });
     expect(options).toHaveLength(2);
     // Each option has a ref and label
     for (const opt of options) {
@@ -136,11 +128,114 @@ describe("filterMatchesToOptions", () => {
     }
   });
 
+  test("single filter: dataset name prefixes the discriminating trace step", () => {
+    // Regression: without the dataset in the input, deriveDistinctLabels
+    // picks the highest-importance step it sees — the dataset's own
+    // `samples-and-data/dataset` step (importance 100) — and the filter
+    // shows "Bulk" instead of "Top 10". Appending the dataset forces the
+    // algorithm to include the lower-importance lead-selection step too.
+    const datasetSpec = spec("dataset", [axis("sample"), axis("gene")], {
+      [Annotation.Label]: "Bulk",
+      [Annotation.Trace]: JSON.stringify([
+        { type: "milaboratories.samples-and-data/dataset", label: "Bulk", importance: 100 },
+        { type: "milaboratories.mixcr-clonotyping", label: "MiXCR", importance: 20 },
+      ]),
+    });
+
+    const filterRef = createPlRef("b1", "filter");
+    const refMap = buildRefMap([{ ref: filterRef }]);
+    const filterSpec = spec("filter", [axis("sample")], {
+      [Annotation.IsSubset]: "true",
+      [Annotation.Label]: "Selected Leads",
+      [Annotation.Trace]: JSON.stringify([
+        { type: "milaboratories.samples-and-data/dataset", label: "Bulk", importance: 100 },
+        { type: "milaboratories.mixcr-clonotyping", label: "MiXCR", importance: 20 },
+        { 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);
+    expect(matches).toHaveLength(1);
+
+    const options = filterMatchesToOptions(matches, { refsByObjectId: refMap, datasetSpec });
+    expect(options).toHaveLength(1);
+    expect(options[0].label).toBe("Bulk / Top 10");
+
+    // Caller's `formatters.native` must NOT override the internal
+    // suppression — otherwise the algorithm short-circuits on the
+    // inherited "Selected Leads" label.
+    const withCustomNative = filterMatchesToOptions(matches, {
+      refsByObjectId: refMap,
+      datasetSpec,
+      labelOptions: { formatters: { native: (l) => `<<${l}>>` } },
+    });
+    expect(withCustomNative[0].label).toBe("Bulk / Top 10");
+
+    // Non-native label options (here `separator`) flow through.
+    const withSeparator = filterMatchesToOptions(matches, {
+      refsByObjectId: refMap,
+      datasetSpec,
+      labelOptions: { separator: " :: " },
+    });
+    expect(withSeparator[0].label).toBe("Bulk :: Top 10");
+  });
+
+  test("multiple filters with shared dataset trace disambiguate by filter-specific steps", () => {
+    const datasetSpec = spec("dataset", [axis("sample"), axis("gene")], {
+      [Annotation.Label]: "Bulk",
+      [Annotation.Trace]: JSON.stringify([
+        { type: "milaboratories.samples-and-data/dataset", label: "Bulk", importance: 100 },
+        { type: "milaboratories.mixcr-clonotyping", label: "MiXCR", importance: 20 },
+      ]),
+    });
+
+    const ref1 = createPlRef("b1", "f1");
+    const ref2 = createPlRef("b2", "f2");
+    const refMap = buildRefMap([{ ref: ref1 }, { ref: ref2 }]);
+    const filterSpec1 = spec("filter1", [axis("sample")], {
+      [Annotation.IsSubset]: "true",
+      [Annotation.Label]: "Selected Leads",
+      [Annotation.Trace]: JSON.stringify([
+        { type: "milaboratories.samples-and-data/dataset", label: "Bulk", importance: 100 },
+        { type: "milaboratories.mixcr-clonotyping", label: "MiXCR", importance: 20 },
+        { type: "milaboratories.antibody-tcr-lead-selection", label: "Top 10", importance: 30 },
+      ]),
+    });
+    const filterSpec2 = spec("filter2", [axis("sample")], {
+      [Annotation.IsSubset]: "true",
+      [Annotation.Label]: "Selected Leads",
+      [Annotation.Trace]: JSON.stringify([
+        { type: "milaboratories.samples-and-data/dataset", label: "Bulk", importance: 100 },
+        { type: "milaboratories.mixcr-clonotyping", label: "MiXCR", importance: 20 },
+        { 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);
+    expect(matches).toHaveLength(2);
+
+    const options = filterMatchesToOptions(matches, { refsByObjectId: refMap, datasetSpec });
+    expect(options.map((o) => o.label).sort()).toEqual(["Bulk / Top 10", "Bulk / Top 11"]);
+  });
+
   test("returns empty array for empty matches", () => {
-    expect(filterMatchesToOptions([], new Map())).toEqual([]);
+    expect(
+      filterMatchesToOptions([], { refsByObjectId: new Map(), datasetSpec: anchorSpec }),
+    ).toEqual([]);
   });
 
-  test("skips entries whose ref is not found in map", () => {
+  test("skips entries whose id is not in refsByObjectId", () => {
     const knownRef = createPlRef("b1", "known");
     const knownSpec = spec("known", [axis("sample")], { [Annotation.IsSubset]: "true" });
     const orphanSpec = spec("orphan", [axis("sample")], { [Annotation.IsSubset]: "true" });
@@ -153,9 +248,11 @@ describe("filterMatchesToOptions", () => {
 
     const matches = findFilterColumns(collection);
     expect(matches.length).toBe(2);
-
     const refMap = buildRefMap([{ ref: knownRef }]);
-    const options = filterMatchesToOptions(matches, refMap);
+    const options = filterMatchesToOptions(matches, {
+      refsByObjectId: refMap,
+      datasetSpec: anchorSpec,
+    });
     expect(options).toHaveLength(1);
     expect(options[0].ref).toBe(knownRef);
   });

package/src/components/PlDatasetSelector/filter_discovery.ts

@@ -1,5 +1,5 @@
 import { Annotation } from "@milaboratories/pl-model-common";
-import type { Option, PlRef, PObjectId } from "@milaboratories/pl-model-common";
+import type { Option, PlRef, PObjectId, PObjectSpec } from "@milaboratories/pl-model-common";
 import canonicalize from "canonicalize";
 import type {
   AnchoredColumnCollection,
@@ -12,12 +12,8 @@ import {
 } from "../../labels/derive_distinct_labels";
 
 /**
- * Matches columns annotated `pl7.app/isSubset: "true"` whose axes ⊆ anchor axes.
- *
- * The axes-subset constraint is enforced by `mode: "enrichment"`, which sets
- * `allowFloatingHitAxes: false` — every axis of the matched column must be
- * present in the anchor's axes. See `matchingModeToConstraints()` in
- * `column_collection_builder.ts`.
+ * Columns annotated `pl7.app/isSubset: "true"` whose axes ⊆ anchor axes.
+ * The axes-subset constraint comes from `mode: "enrichment"`.
  */
 export function findFilterColumns(collection: AnchoredColumnCollection): ColumnMatch[] {
   return collection.findColumns({
@@ -28,51 +24,62 @@ export function findFilterColumns(collection: AnchoredColumnCollection): ColumnM
   });
 }
 
+export type FilterMatchOptions = {
+  /** Maps result-pool column id back to its source PlRef (see {@link buildRefMap}). */
+  refsByObjectId: ReadonlyMap<PObjectId, PlRef>;
+  /** Spec of the dataset the filters are subsets of. */
+  datasetSpec: PObjectSpec;
+  /**
+   * Forwarded to `deriveDistinctLabels`. Any `formatters.native` caller
+   * sets is silently overridden — the function relies on a no-op native
+   * formatter to keep the algorithm from short-circuiting on filters'
+   * inherited `pl7.app/label`.
+   */
+  labelOptions?: DeriveLabelsOptions;
+};
+
 /**
- * Derive labeled options from filter column matches, 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.
- *
- * @param matches - from findFilterColumns()
- * @param refsByObjectId - from {@link buildRefMap}
- * @param labelOptions - forwarded to deriveDistinctLabels()
+ * 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.
  */
 export function filterMatchesToOptions(
   matches: ColumnMatch[],
-  refsByObjectId: ReadonlyMap<PObjectId, PlRef>,
-  labelOptions?: DeriveLabelsOptions,
+  options: FilterMatchOptions,
 ): Option[] {
   if (matches.length === 0) return [];
 
-  // Each ColumnMatch can be reached via multiple variants (different linker
-  // paths / qualifications). We emit one Option per variant so the user can
-  // pick a specific path — `deriveDistinctLabels` disambiguates labels by
-  // path. All variants of a match share a column id, so the ref lookup
-  // happens once per match.
-  const flattened = matches.flatMap((match) => {
+  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);
     if (ref === undefined) return [];
-    return match.variants.map((variant) => ({ match, variant, ref }));
+    return match.variants.map((variant) => ({
+      ref,
+      spec: match.column.spec,
+      linkerPath: variant.path.map((p) => ({ spec: p.linker.spec })),
+    }));
   });
 
-  const entries: Entry[] = flattened.map(({ match, variant }) => ({
-    spec: match.column.spec,
-    linkerPath: variant.path.map((p) => ({ spec: p.linker.spec })),
-  }));
-
-  const labels = deriveDistinctLabels(entries, labelOptions);
+  // Appending the dataset forces a discriminating trace step into every
+  // filter label (yielding e.g. "Bulk / Top 10"); the dataset's own label
+  // is dropped because we only zip `entries`. Native label is force-
+  // suppressed (the override sits after caller's spread) — filters
+  // inherit the dataset's `pl7.app/label` and would otherwise satisfy
+  // uniqueness before any trace step is consulted.
+  const labels = deriveDistinctLabels([...entries, { spec: datasetSpec }], {
+    ...labelOptions,
+    formatters: { ...labelOptions?.formatters, native: () => undefined },
+  });
 
-  return flattened.map(({ ref }, i) => ({ ref, label: labels[i] }));
+  return entries.map(({ ref }, i) => ({ ref, label: labels[i] }));
 }
 
-/**
- * Usage: `buildRefMap(ctx.resultPool.getSpecs().entries)`
- */
+/** Build the `refsByObjectId` map from `ctx.resultPool.getSpecs().entries`. */
 export function buildRefMap(entries: readonly { readonly ref: PlRef }[]): Map<PObjectId, PlRef> {
-  const map = new Map<PObjectId, PlRef>();
-  for (const entry of entries) {
-    map.set(canonicalize(entry.ref)! as PObjectId, entry.ref);
-  }
-  return map;
+  return new Map(entries.map((e) => [canonicalize(e.ref)! as PObjectId, e.ref]));
 }