@platforma-sdk/model 1.63.1 → 1.64.0

package/src/labels/derive_distinct_labels.test.ts

@@ -117,17 +117,14 @@ test.each<{ name: string; traces: Trace[]; labels: string[] }>([
     labels: ["Unique entry 1", "Unique entry 2"],
   },
 ])("test label derivation: $name", ({ traces, labels }) => {
-  expect(deriveDistinctLabels(tracesToSpecs(traces)).map((r) => r.label)).toEqual(labels);
-  expect(
-    deriveDistinctLabels(tracesToSpecs(traces), { includeNativeLabel: true }).map((r) => r.label),
-  ).toEqual(labels.map((l) => "Label / " + l));
+  expect(deriveDistinctLabels(tracesToSpecs(traces))).toEqual(labels);
+  expect(deriveDistinctLabels(tracesToSpecs(traces), { includeNativeLabel: true })).toEqual(
+    labels.map((l) => "Label / " + l),
+  );
 });
 
 test("test fallback to native labels in label derivation", () => {
-  expect(deriveDistinctLabels(tracesToSpecs([[], []])).map((r) => r.label)).toEqual([
-    "Label",
-    "Label",
-  ]);
+  expect(deriveDistinctLabels(tracesToSpecs([[], []]))).toEqual(["Label", "Label"]);
 });
 
 test.each<{ name: string; traces: Trace[]; labels: string[] }>([
@@ -208,7 +205,7 @@ test.each<{ name: string; traces: Trace[]; labels: string[] }>([
     labels: ["A", "A", "B"],
   },
 ])("test label minimization: $name", ({ traces, labels }) => {
-  expect(deriveDistinctLabels(tracesToSpecs(traces)).map((r) => r.label)).toEqual(labels);
+  expect(deriveDistinctLabels(tracesToSpecs(traces))).toEqual(labels);
 });
 
 test.each<{ name: string; traces: Trace[]; labels: string[]; forceTraceElements: string[] }>([
@@ -274,72 +271,173 @@ test.each<{ name: string; traces: Trace[]; labels: string[]; forceTraceElements:
 ])(
   "test label derivation with forceTraceElements: $name",
   ({ name, traces, labels, forceTraceElements }) => {
-    expect(
-      deriveDistinctLabels(tracesToSpecs(traces), { forceTraceElements }).map((r) => r.label),
-    ).toEqual(labels);
+    expect(deriveDistinctLabels(tracesToSpecs(traces), { forceTraceElements })).toEqual(labels);
 
     if (name === "force element with includeNativeLabel") {
       expect(
         deriveDistinctLabels(tracesToSpecs(traces), {
           forceTraceElements,
           includeNativeLabel: true,
-        }).map((r) => r.label),
+        }),
       ).toEqual(labels.map((l) => "Label / " + l));
     }
   },
 );
 
-// --- Entry with { spec, prefixTrace, suffixTrace } ---
+// --- Entry with { spec, extraTrace } ---
 
-test("Entry with prefixTrace prepends to labels", () => {
+test("Entry with extraTrace (suffix, default) appends to labels", () => {
   const spec = createSpec({
     annotations: {
       [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Base" }]),
     },
   });
   const entries: Entry[] = [
-    { spec, prefixTrace: [{ type: "prefix", label: "P1" }] },
-    { spec, prefixTrace: [{ type: "prefix", label: "P2" }] },
+    { spec, extraTrace: [{ type: "suffix", label: "S1" }] },
+    { spec, extraTrace: [{ type: "suffix", label: "S2" }] },
   ];
-  const labels = deriveDistinctLabels(entries).map((r) => r.label);
-  expect(labels).toEqual(["P1", "P2"]);
+  const labels = deriveDistinctLabels(entries);
+  expect(labels).toEqual(["S1", "S2"]);
 });
 
-test("Entry with suffixTrace appends to labels", () => {
+test("Entry with extraTrace position prefix prepends to labels", () => {
   const spec = createSpec({
     annotations: {
       [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Base" }]),
     },
   });
   const entries: Entry[] = [
-    { spec, suffixTrace: [{ type: "suffix", label: "S1" }] },
-    { spec, suffixTrace: [{ type: "suffix", label: "S2" }] },
+    { spec, extraTrace: [{ type: "prefix", label: "P1", position: "prefix" }] },
+    { spec, extraTrace: [{ type: "prefix", label: "P2", position: "prefix" }] },
   ];
-  const labels = deriveDistinctLabels(entries).map((r) => r.label);
-  expect(labels).toEqual(["S1", "S2"]);
+  const labels = deriveDistinctLabels(entries);
+  expect(labels).toEqual(["P1", "P2"]);
 });
 
-test("Entry with both prefixTrace and suffixTrace", () => {
-  const spec1 = createSpec({
-    annotations: {
-      [Annotation.Trace]: JSON.stringify([{ type: "base", label: "Same" }]),
+// --- linkerPath ---
+
+test("linkerPath appends default 'via' suffix", () => {
+  const entries: Entry[] = [
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+      }),
+      linkerPath: [
+        {
+          spec: createSpec({
+            annotations: { [Annotation.LinkLabel]: "MyLinker" },
+          }),
+        },
+      ],
+    },
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+      }),
     },
+  ];
+  const labels = deriveDistinctLabels(entries);
+  expect(labels).toEqual(["Col1 via MyLinker", "Col2"]);
+});
+
+test("linkerPath with multiple steps joins with ' > '", () => {
+  const entries: Entry[] = [
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+      }),
+      linkerPath: [
+        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L1" } }) },
+        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L2" } }) },
+      ],
+    },
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+      }),
+    },
+  ];
+  const labels = deriveDistinctLabels(entries);
+  expect(labels).toEqual(["Col1 via L1 > L2", "Col2"]);
+});
+
+test("linkerPath skips steps without labels", () => {
+  const entries: Entry[] = [
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+      }),
+      linkerPath: [
+        { spec: createSpec() },
+        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L2" } }) },
+      ],
+    },
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+      }),
+    },
+  ];
+  const labels = deriveDistinctLabels(entries);
+  expect(labels).toEqual(["Col1 via L2", "Col2"]);
+});
+
+test("linkerPath with custom linkerLabelFormatter", () => {
+  const entries: Entry[] = [
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+      }),
+      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L1" } }) }],
+    },
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+      }),
+    },
+  ];
+  const labels = deriveDistinctLabels(entries, {
+    linkerLabelFormatter: (linkerLabels) => `[${linkerLabels.join(", ")}]`,
   });
+  expect(labels).toEqual(["Col1 [L1]", "Col2"]);
+});
+
+test("linkerPath with linkerLabelFormatter returning undefined suppresses suffix", () => {
   const entries: Entry[] = [
     {
-      spec: spec1,
-      prefixTrace: [{ type: "pfx", label: "Pre1" }],
-      suffixTrace: [{ type: "sfx", label: "Suf1" }],
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+      }),
+      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L1" } }) }],
     },
     {
-      spec: spec1,
-      prefixTrace: [{ type: "pfx", label: "Pre2" }],
-      suffixTrace: [{ type: "sfx", label: "Suf2" }],
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+      }),
     },
   ];
-  const labels = deriveDistinctLabels(entries).map((r) => r.label);
-  // suffix is later in the trace (higher positional importance), so it wins over prefix
-  expect(labels).toEqual(["Suf1", "Suf2"]);
+  const labels = deriveDistinctLabels(entries, {
+    linkerLabelFormatter: () => undefined,
+  });
+  expect(labels).toEqual(["Col1", "Col2"]);
+});
+
+test("linkerPath falls back to Label when LinkLabel is absent", () => {
+  const entries: Entry[] = [
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+      }),
+      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.Label]: "FallbackLabel" } }) }],
+    },
+    {
+      spec: createSpec({
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+      }),
+    },
+  ];
+  const labels = deriveDistinctLabels(entries);
+  expect(labels).toEqual(["Col1 via FallbackLabel", "Col2"]);
 });
 
 // --- addLabelAsSuffix ---
@@ -349,7 +447,7 @@ test("addLabelAsSuffix places native label at the end", () => {
   const labels = deriveDistinctLabels(specs, {
     includeNativeLabel: true,
     addLabelAsSuffix: true,
-  }).map((r) => r.label);
+  });
   expect(labels).toEqual(["L1 / Label", "L2 / Label"]);
 });
 
@@ -370,7 +468,7 @@ test("custom separator is used between label parts", () => {
       { type: "t2", label: "Y" },
     ],
   ]);
-  const labels = deriveDistinctLabels(specs, { separator: " - " }).map((r) => r.label);
+  const labels = deriveDistinctLabels(specs, { separator: " - " });
   expect(labels).toEqual(["A - X", "A - Y", "B - Y"]);
 });
 
@@ -378,7 +476,7 @@ test("custom separator is used between label parts", () => {
 
 test("single value gets its trace label", () => {
   const specs = tracesToSpecs([[{ type: "t1", label: "Only" }]]);
-  const labels = deriveDistinctLabels(specs).map((r) => r.label);
+  const labels = deriveDistinctLabels(specs);
   expect(labels).toEqual(["Only"]);
 });
 
@@ -395,13 +493,13 @@ test("Unlabeled fallback when no trace entries match", () => {
   delete spec.annotations![Annotation.Label];
 
   const result = deriveDistinctLabels([spec, spec]);
-  expect(result.every((r) => r.label === "Same")).toBe(true);
+  expect(result.every((r) => r === "Same")).toBe(true);
 });
 
 test("Unlabeled when no traces and no label", () => {
   const spec = createSpec();
   const result = deriveDistinctLabels([spec, spec]);
-  expect(result.every((r) => r.label === "Unlabeled")).toBe(true);
+  expect(result.every((r) => r === "Unlabeled")).toBe(true);
 });
 
 // --- repeated type occurrences (secondaryTypes path) ---
@@ -418,7 +516,7 @@ test("repeated type occurrences are used as secondary types", () => {
       { type: "t1", label: "B" },
     ],
   ]);
-  const labels = deriveDistinctLabels(specs).map((r) => r.label);
+  const labels = deriveDistinctLabels(specs);
   // t1@1 has label "First" for both (same), t1@2 has "A" vs "B" (distinguishing)
   // t1@2 is secondary since it only appears when there are 2 occurrences
   expect(labels).toEqual(["A", "B"]);
@@ -439,7 +537,7 @@ test("spec without native label uses only trace entries", () => {
       },
     }),
   ];
-  const labels = deriveDistinctLabels(specs).map((r) => r.label);
+  const labels = deriveDistinctLabels(specs);
   expect(labels).toEqual(["X", "Y"]);
 });
 
@@ -456,6 +554,6 @@ test("includeNativeLabel with no native label does not break", () => {
       },
     }),
   ];
-  const labels = deriveDistinctLabels(specs, { includeNativeLabel: true }).map((r) => r.label);
+  const labels = deriveDistinctLabels(specs, { includeNativeLabel: true });
   expect(labels).toEqual(["X", "Y"]);
 });

package/src/labels/derive_distinct_labels.ts

@@ -2,32 +2,34 @@ import {
   Annotation,
   parseJson,
   readAnnotation,
-  type CanonicalizedJson,
   type PObjectSpec,
+  type StringifiedJson,
+  type Trace,
 } from "@milaboratories/pl-model-common";
 import { throwError } from "@milaboratories/helpers";
+import { isFunction, isNil } from "es-toolkit";
+
+export type { Trace, TraceEntry } from "@milaboratories/pl-model-common";
 
 const DISTANCE_PENALTY = 0.001;
 const LABEL_TYPE = "__LABEL__";
 const LABEL_TYPE_FULL = "__LABEL__@1";
 
-export type WithLabel<T> = {
-  value: T;
-  label: string;
-};
-
-type TraceEntry = {
-  id?: string;
-  type: string;
-  label: string;
+/** SDK-internal trace shape — adds fields used by this algorithm only, not part of the on-disk contract. */
+type ExtendedTraceEntry = Trace[number] & {
   importance?: number;
+  position?: "prefix" | "suffix";
 };
 
-export type Trace = TraceEntry[];
-
 export type Entry =
   | PObjectSpec
-  | { spec: PObjectSpec; prefixTrace?: TraceEntry[]; suffixTrace?: TraceEntry[] };
+  | {
+      spec: PObjectSpec;
+      /** Extra trace entries merged with the base trace from annotations. */
+      extraTrace?: ExtendedTraceEntry[];
+      /** Linker steps traversed to discover this column; used to append "via $linkLabel" to derived labels. */
+      linkerPath?: { spec: PObjectSpec }[];
+    };
 
 export type DeriveLabelsOptions = {
   /** Separator to use between label parts (" / " by default) */
@@ -38,18 +40,33 @@ export type DeriveLabelsOptions = {
   includeNativeLabel?: boolean;
   /** Trace elements list that will be forced to be included in the label. */
   forceTraceElements?: string[];
+  /** Custom formatter for linker path suffix. Receives the array of linker labels from the full traversal chain,
+   *  the column spec, and the column index.
+   *  If returns undefined, no linker suffix is appended. By default labels are joined with " > " and prefixed with "via ". */
+  linkerLabelFormatter?: (
+    linkerLabels: string[],
+    spec: PObjectSpec,
+    index: number,
+  ) => string | undefined;
 };
 
-export function deriveDistinctLabels<T extends Entry>(
-  values: T[],
-  options: DeriveLabelsOptions = {},
-): WithLabel<T>[] {
+export function deriveDistinctLabels(values: Entry[], options: DeriveLabelsOptions = {}): string[] {
   const forceTraceElements =
     options.forceTraceElements !== undefined && options.forceTraceElements.length > 0
       ? new Set(options.forceTraceElements)
       : undefined;
   const separator = options.separator ?? " / ";
 
+  // Collect per-entry linker suffixes before disambiguation
+  const linkerSuffixes = values.map((v, i) => {
+    const spec = "spec" in v && typeof v.spec === "object" ? v.spec : (v as PObjectSpec);
+    const linkerLabels = extractLinkerLabels(v);
+    if (linkerLabels.length === 0) return undefined;
+    return isFunction(options.linkerLabelFormatter)
+      ? options.linkerLabelFormatter(linkerLabels, spec, i)
+      : `via ${linkerLabels.join(" > ")}`;
+  });
+
   // Phase 1: enrich each value with parsed trace
   const records = values.map((v) => enrichRecord(v, options));
 
@@ -65,7 +82,12 @@ export function deriveDistinctLabels<T extends Entry>(
   if (mainTypes.length === 0) {
     if (secondaryTypes.length !== 0)
       throw new Error("Non-empty secondary types list while main types list is empty.");
-    return build(new Set(LABEL_TYPE_FULL), true)!;
+
+    return applyLinkerSuffixes(
+      build(new Set(LABEL_TYPE_FULL), true) ??
+        throwError("Failed to derive labels using native column labels"),
+      linkerSuffixes,
+    );
   }
 
   // Phase 4: search for minimal type set that produces unique labels
@@ -96,7 +118,10 @@ export function deriveDistinctLabels<T extends Entry>(
         options,
         separator,
       );
-      return build(minimized, false) ?? throwError("Failed to derive unique labels");
+      return applyLinkerSuffixes(
+        build(minimized, false) ?? throwError("Failed to derive unique labels"),
+        linkerSuffixes,
+      );
     }
 
     additionalType++;
@@ -116,29 +141,55 @@ export function deriveDistinctLabels<T extends Entry>(
     options,
     separator,
   );
-  return build(minimized, true) ?? throwError("Failed to derive unique labels");
+  return applyLinkerSuffixes(
+    build(minimized, true) ?? throwError("Failed to derive unique labels"),
+    linkerSuffixes,
+  );
+}
+
+/** Apply pre-formatted linker suffixes to labels that have them. */
+function applyLinkerSuffixes(labels: string[], suffixes: (string | undefined)[]): string[] {
+  return labels.map((label, i) => (isNil(suffixes[i]) ? label : `${label} ${suffixes[i]}`));
+}
+
+/** Extract linker labels from every step of the linkers path. */
+function extractLinkerLabels(entry: Entry): string[] {
+  if (!("spec" in entry) || typeof entry.spec !== "object") return [];
+  const path = entry.linkerPath;
+  if (path === undefined || path.length === 0) return [];
+  const labels: string[] = [];
+  for (const step of path) {
+    const label = (
+      readAnnotation(step.spec, Annotation.LinkLabel) ?? readAnnotation(step.spec, Annotation.Label)
+    )?.trim();
+    if (label !== undefined && label.length > 0) {
+      labels.push(label);
+    }
+  }
+  return labels;
 }
 
 // --- Pure helpers ---
-type FullTraceEntry = TraceEntry & { fullType: string; occurrenceIndex: number };
+type FullTraceEntry = ExtendedTraceEntry & { fullType: string; occurrenceIndex: number };
 
-type EnrichedRecord<T> = {
-  value: T;
+type EnrichedRecord = {
   fullTrace: FullTraceEntry[];
 };
 
 function extractSpecAndTrace(entry: Entry): {
   spec: PObjectSpec;
-  prefixTrace: TraceEntry[] | undefined;
-  suffixTrace: TraceEntry[] | undefined;
+  extraTrace: ExtendedTraceEntry[] | undefined;
+  linkerPath: { spec: PObjectSpec }[] | undefined;
 } {
-  if ("spec" in entry && typeof entry.spec === "object") {
-    return { spec: entry.spec, prefixTrace: entry.prefixTrace, suffixTrace: entry.suffixTrace };
-  }
-  return { spec: entry as PObjectSpec, prefixTrace: undefined, suffixTrace: undefined };
+  const isEnriched = "spec" in entry && typeof entry.spec === "object";
+  return {
+    spec: isEnriched ? entry.spec : (entry as PObjectSpec),
+    extraTrace: isEnriched ? entry.extraTrace : undefined,
+    linkerPath: isEnriched ? entry.linkerPath : undefined,
+  };
 }
 
-function buildFullTrace(trace: TraceEntry[]): FullTraceEntry[] {
+function buildFullTrace(trace: ExtendedTraceEntry[]): FullTraceEntry[] {
   const result: FullTraceEntry[] = [];
   const occurrences = new Map<string, number>();
 
@@ -157,15 +208,17 @@ function buildFullTrace(trace: TraceEntry[]): FullTraceEntry[] {
   return result;
 }
 
-function enrichRecord<T extends Entry>(value: T, options: DeriveLabelsOptions): EnrichedRecord<T> {
-  const { spec, prefixTrace, suffixTrace } = extractSpecAndTrace(value);
+function enrichRecord(value: Entry, options: DeriveLabelsOptions): EnrichedRecord {
+  const { spec, extraTrace } = extractSpecAndTrace(value);
 
   const label = readAnnotation(spec, Annotation.Label);
-  const traceStr = readAnnotation(spec, Annotation.Trace) as
-    | CanonicalizedJson<TraceEntry[]>
-    | undefined;
-  const baseTrace: Trace = traceStr ? (parseJson<Trace>(traceStr) ?? []) : [];
-  const trace = [...(prefixTrace ?? []), ...baseTrace, ...(suffixTrace ?? [])];
+  const traceStr = readAnnotation(spec, Annotation.Trace);
+  const baseTrace = traceStr
+    ? (parseJson(traceStr as StringifiedJson<ExtendedTraceEntry[]>) ?? [])
+    : [];
+  const prefixExtra = extraTrace?.filter((e) => e.position === "prefix") ?? [];
+  const suffixExtra = extraTrace?.filter((e) => e.position !== "prefix") ?? [];
+  const trace = [...prefixExtra, ...baseTrace, ...suffixExtra];
 
   if (label !== undefined) {
     const labelEntry = { label, type: LABEL_TYPE, importance: -2 };
@@ -173,7 +226,7 @@ function enrichRecord<T extends Entry>(value: T, options: DeriveLabelsOptions):
     else trace.splice(0, 0, labelEntry);
   }
 
-  return { value, fullTrace: buildFullTrace(trace) };
+  return { fullTrace: buildFullTrace(trace) };
 }
 
 type TypeStats = {
@@ -181,7 +234,7 @@ type TypeStats = {
   countByType: Map<string, number>;
 };
 
-function collectTypeStats<T>(records: EnrichedRecord<T>[]): TypeStats {
+function collectTypeStats(records: EnrichedRecord[]): TypeStats {
   const importances = new Map<string, number>();
   const countByType = new Map<string, number>();
 
@@ -220,14 +273,14 @@ function classifyTypes(
   return { mainTypes, secondaryTypes };
 }
 
-function buildLabels<T>(
-  records: EnrichedRecord<T>[],
+function buildLabels(
+  records: EnrichedRecord[],
   includedTypes: Set<string>,
   forceTraceElements: Set<string> | undefined,
   separator: string,
   force: boolean,
-): WithLabel<T>[] | undefined {
-  const result: WithLabel<T>[] = [];
+): string[] | undefined {
+  const result: string[] = [];
 
   for (const r of records) {
     const parts: string[] = [];
@@ -239,24 +292,24 @@ function buildLabels<T>(
 
     if (parts.length === 0) {
       if (!force) return undefined;
-      result.push({ label: "Unlabeled", value: r.value });
+      result.push("Unlabeled");
       continue;
     }
 
-    result.push({ label: parts.join(separator), value: r.value });
+    result.push(parts.join(separator));
   }
 
   return result;
 }
 
-function countUniqueLabels<T>(result: WithLabel<T>[] | undefined): number {
+function countUniqueLabels(result: string[] | undefined): number {
   if (result === undefined) return 0;
-  return new Set(result.map((c) => c.label)).size;
+  return new Set(result).size;
 }
 
-function minimizeTypeSet<T>(
+function minimizeTypeSet(
   typeSet: Set<string>,
-  records: EnrichedRecord<T>[],
+  records: EnrichedRecord[],
   stats: TypeStats,
   forceTraceElements: Set<string> | undefined,
   options: DeriveLabelsOptions,

package/src/labels/index.ts

@@ -1,2 +1 @@
 export * from "./derive_distinct_labels";
-export * from "./write_labels_to_specs";

package/src/render/api.ts

@@ -686,10 +686,12 @@ export abstract class RenderCtxBase<
 
   // TODO remove all non-PColumn fields
   public createPFrame(
-    def: PFrameDef<PColumn<PColumnDataUniversal> | PColumnLazy<undefined | PColumnDataUniversal>>,
+    def: PFrameDef<
+      PColumn<undefined | PColumnDataUniversal> | PColumnLazy<undefined | PColumnDataUniversal>
+    >,
   ): PFrameHandle | undefined {
-    this.verifyInlineAndExplicitColumnsSupport(def);
     if (!allPColumnsReady(def)) return undefined;
+    this.verifyInlineAndExplicitColumnsSupport(def);
     return this.ctx.createPFrame(def.map((c) => transformPColumnData(c)));
   }
 
@@ -731,11 +733,19 @@ export abstract class RenderCtxBase<
     return this.ctx.createPTable(mapPTableDef(rawDef, (po) => transformPColumnData(po)));
   }
 
-  public createPTableV2(def: PTableDefV2<PColumn<PColumnDataUniversal>>): PTableHandle | undefined {
+  public createPTableV2(
+    def: PTableDefV2<PColumn<undefined | PColumnDataUniversal>>,
+  ): PTableHandle | undefined {
     const columns = collectSpecQueryColumns(def.query);
-    this.verifyInlineAndExplicitColumnsSupport(columns);
     if (!allPColumnsReady(columns)) return undefined;
-    return this.ctx.createPTableV2(mapPTableDefV2(def, (po) => transformPColumnData(po)));
+    this.verifyInlineAndExplicitColumnsSupport(columns);
+    return this.ctx.createPTableV2(
+      mapPTableDefV2(def, (po) => {
+        if (po.data === undefined)
+          throw new Error("unreachable: column data undefined after readiness check");
+        return transformPColumnData({ id: po.id, spec: po.spec, data: po.data });
+      }),
+    );
   }
 
   /** @deprecated scheduled for removal from SDK */

package/src/render/util/column_collection.ts

@@ -126,8 +126,8 @@ type IntermediateDirectEntry = {
 // Union type for intermediate processing
 type IntermediateColumnEntry = IntermediateSplitEntry | IntermediateDirectEntry;
 
-function splitFiltersToTrace(splitFilters?: AxisFilterInfo[]) {
-  if (!splitFilters) return undefined;
+function splitFiltersToExtraTrace(splitFilters?: AxisFilterInfo[]) {
+  if (splitFilters === undefined) return undefined;
   return splitFilters.map((filter) => ({
     type: `split:${canonicalizeAxisId(filter.axisId)}`,
     label: filter.label,
@@ -467,7 +467,8 @@ export class PColumnCollection {
       intermediateResults,
       (entry) => ({
         spec: entry.spec,
-        suffixTrace: entry.type === "split" ? splitFiltersToTrace(entry.axisFilters) : undefined,
+        extraTrace:
+          entry.type === "split" ? splitFiltersToExtraTrace(entry.axisFilters) : undefined,
       }),
       labelOps,
     );

package/src/render/util/label.ts

@@ -20,6 +20,6 @@ export function deriveLabels<T>(
   options: DeriveLabelsOptions = {},
 ): WithLabel<T>[] {
   const specs = values.map(getSpec);
-  const labeled = deriveDistinctLabels(specs, options);
-  return labeled.map((l, i) => ({ value: values[i], label: l.label }));
+  const labels = deriveDistinctLabels(specs, options);
+  return labels.map((label, i) => ({ value: values[i], label }));
 }

package/src/render/util/pcolumn_data.ts

@@ -546,7 +546,7 @@ export function convertOrParsePColumnData(
 }
 
 export function isPColumnReady(
-  c: PColumn<PColumnDataUniversal> | PColumnLazy<undefined | PColumnDataUniversal>,
+  c: PColumn<undefined | PColumnDataUniversal> | PColumnLazy<undefined | PColumnDataUniversal>,
 ): c is PColumn<PColumnDataUniversal> | PColumnLazy<PColumnDataUniversal> {
   const isValues = (d: PColumnDataUniversal): d is PColumnValues => Array.isArray(d);
   const isAccessor = (d: PColumnDataUniversal): d is TreeNodeAccessor =>
@@ -561,14 +561,16 @@ export function isPColumnReady(
   } else if (isDataInfo(data)) {
     visitDataInfo(data, (v) => (ready &&= v.getIsReadyOrError()));
   } else if (!isValues(data)) {
-    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
     throw Error(`unsupported column data type: ${data satisfies never}`);
   }
   return ready;
 }
 
 export function allPColumnsReady(
-  columns: (PColumn<PColumnDataUniversal> | PColumnLazy<undefined | PColumnDataUniversal>)[],
+  columns: (
+    | PColumn<undefined | PColumnDataUniversal>
+    | PColumnLazy<undefined | PColumnDataUniversal>
+  )[],
 ): columns is (PColumn<PColumnDataUniversal> | PColumnLazy<PColumnDataUniversal>)[] {
   return columns.every(isPColumnReady);
 }