@platforma-sdk/model 1.63.12 → 1.64.0

package/dist/labels/derive_distinct_labels.cjs

@@ -1,6 +1,7 @@
 require("../_virtual/_rolldown/runtime.cjs");
 let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
 let _milaboratories_helpers = require("@milaboratories/helpers");
+let es_toolkit = require("es-toolkit");
 //#region src/labels/derive_distinct_labels.ts
 const DISTANCE_PENALTY = .001;
 const LABEL_TYPE = "__LABEL__";
@@ -8,13 +9,19 @@ const LABEL_TYPE_FULL = "__LABEL__@1";
 function deriveDistinctLabels(values, options = {}) {
 	const forceTraceElements = options.forceTraceElements !== void 0 && options.forceTraceElements.length > 0 ? new Set(options.forceTraceElements) : void 0;
 	const separator = options.separator ?? " / ";
+	const linkerSuffixes = values.map((v, i) => {
+		const spec = "spec" in v && typeof v.spec === "object" ? v.spec : v;
+		const linkerLabels = extractLinkerLabels(v);
+		if (linkerLabels.length === 0) return void 0;
+		return (0, es_toolkit.isFunction)(options.linkerLabelFormatter) ? options.linkerLabelFormatter(linkerLabels, spec, i) : `via ${linkerLabels.join(" > ")}`;
+	});
 	const records = values.map((v) => enrichRecord(v, options));
 	const stats = collectTypeStats(records);
 	const { mainTypes, secondaryTypes } = classifyTypes(stats, values.length);
 	const build = (typeSet, force) => buildLabels(records, typeSet, forceTraceElements, separator, force);
 	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) ?? (0, _milaboratories_helpers.throwError)("Failed to derive labels using native column labels"), linkerSuffixes);
 	}
 	let includedCount = 0;
 	let additionalType = -1;
@@ -24,25 +31,37 @@ function deriveDistinctLabels(values, options = {}) {
 		for (let i = 0; i < includedCount; ++i) currentSet.add(mainTypes[i]);
 		if (additionalType >= 0) currentSet.add(mainTypes[additionalType]);
 		const candidateResult = build(currentSet, false);
-		if (candidateResult !== void 0 && countUniqueLabels(candidateResult) === values.length) return build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, options, separator), false) ?? (0, _milaboratories_helpers.throwError)("Failed to derive unique labels");
+		if (candidateResult !== void 0 && countUniqueLabels(candidateResult) === values.length) return applyLinkerSuffixes(build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, options, separator), false) ?? (0, _milaboratories_helpers.throwError)("Failed to derive unique labels"), linkerSuffixes);
 		additionalType++;
 		if (additionalType >= mainTypes.length) {
 			includedCount++;
 			additionalType = includedCount;
 		}
 	}
-	return build(minimizeTypeSet(new Set([...mainTypes, ...secondaryTypes]), records, stats, forceTraceElements, options, separator), true) ?? (0, _milaboratories_helpers.throwError)("Failed to derive unique labels");
+	return applyLinkerSuffixes(build(minimizeTypeSet(new Set([...mainTypes, ...secondaryTypes]), records, stats, forceTraceElements, options, separator), true) ?? (0, _milaboratories_helpers.throwError)("Failed to derive unique labels"), linkerSuffixes);
+}
+/** Apply pre-formatted linker suffixes to labels that have them. */
+function applyLinkerSuffixes(labels, suffixes) {
+	return labels.map((label, i) => (0, es_toolkit.isNil)(suffixes[i]) ? label : `${label} ${suffixes[i]}`);
+}
+/** Extract linker labels from every step of the linkers path. */
+function extractLinkerLabels(entry) {
+	if (!("spec" in entry) || typeof entry.spec !== "object") return [];
+	const path = entry.linkerPath;
+	if (path === void 0 || path.length === 0) return [];
+	const labels = [];
+	for (const step of path) {
+		const label = ((0, _milaboratories_pl_model_common.readAnnotation)(step.spec, _milaboratories_pl_model_common.Annotation.LinkLabel) ?? (0, _milaboratories_pl_model_common.readAnnotation)(step.spec, _milaboratories_pl_model_common.Annotation.Label))?.trim();
+		if (label !== void 0 && label.length > 0) labels.push(label);
+	}
+	return labels;
 }
 function extractSpecAndTrace(entry) {
-	if ("spec" in entry && typeof entry.spec === "object") return {
-		spec: entry.spec,
-		prefixTrace: entry.prefixTrace,
-		suffixTrace: entry.suffixTrace
-	};
+	const isEnriched = "spec" in entry && typeof entry.spec === "object";
 	return {
-		spec: entry,
-		prefixTrace: void 0,
-		suffixTrace: void 0
+		spec: isEnriched ? entry.spec : entry,
+		extraTrace: isEnriched ? entry.extraTrace : void 0,
+		linkerPath: isEnriched ? entry.linkerPath : void 0
 	};
 }
 function buildFullTrace(trace) {
@@ -62,14 +81,16 @@ function buildFullTrace(trace) {
 	return result;
 }
 function enrichRecord(value, options) {
-	const { spec, prefixTrace, suffixTrace } = extractSpecAndTrace(value);
+	const { spec, extraTrace } = extractSpecAndTrace(value);
 	const label = (0, _milaboratories_pl_model_common.readAnnotation)(spec, _milaboratories_pl_model_common.Annotation.Label);
 	const traceStr = (0, _milaboratories_pl_model_common.readAnnotation)(spec, _milaboratories_pl_model_common.Annotation.Trace);
 	const baseTrace = traceStr ? (0, _milaboratories_pl_model_common.parseJson)(traceStr) ?? [] : [];
+	const prefixExtra = extraTrace?.filter((e) => e.position === "prefix") ?? [];
+	const suffixExtra = extraTrace?.filter((e) => e.position !== "prefix") ?? [];
 	const trace = [
-		...prefixTrace ?? [],
+		...prefixExtra,
 		...baseTrace,
-		...suffixTrace ?? []
+		...suffixExtra
 	];
 	if (label !== void 0) {
 		const labelEntry = {
@@ -80,10 +101,7 @@ function enrichRecord(value, options) {
 		if (options.addLabelAsSuffix) trace.push(labelEntry);
 		else trace.splice(0, 0, labelEntry);
 	}
-	return {
-		value,
-		fullTrace: buildFullTrace(trace)
-	};
+	return { fullTrace: buildFullTrace(trace) };
 }
 function collectTypeStats(records) {
 	const importances = /* @__PURE__ */ new Map();
@@ -118,22 +136,16 @@ function buildLabels(records, includedTypes, forceTraceElements, separator, forc
 		for (const ft of r.fullTrace) if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) parts.push(ft.label);
 		if (parts.length === 0) {
 			if (!force) return void 0;
-			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(result) {
 	if (result === void 0) return 0;
-	return new Set(result.map((c) => c.label)).size;
+	return new Set(result).size;
 }
 function minimizeTypeSet(typeSet, records, stats, forceTraceElements, options, separator) {
 	const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);

package/dist/labels/derive_distinct_labels.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"derive_distinct_labels.cjs","names":["Annotation"],"sources":["../../src/labels/derive_distinct_labels.ts"],"sourcesContent":["import {\n  Annotation,\n  parseJson,\n  readAnnotation,\n  type CanonicalizedJson,\n  type PObjectSpec,\n} from \"@milaboratories/pl-model-common\";\nimport { throwError } from \"@milaboratories/helpers\";\n\nconst DISTANCE_PENALTY = 0.001;\nconst LABEL_TYPE = \"__LABEL__\";\nconst LABEL_TYPE_FULL = \"__LABEL__@1\";\n\nexport type WithLabel<T> = {\n  value: T;\n  label: string;\n};\n\ntype TraceEntry = {\n  id?: string;\n  type: string;\n  label: string;\n  importance?: number;\n};\n\nexport type Trace = TraceEntry[];\n\nexport type Entry =\n  | PObjectSpec\n  | { spec: PObjectSpec; prefixTrace?: TraceEntry[]; suffixTrace?: TraceEntry[] };\n\nexport type DeriveLabelsOptions = {\n  /** Separator to use between label parts (\" / \" by default) */\n  separator?: string;\n  /** If true, label will be added as suffix (at the end of the generated label). By default label added as a prefix. */\n  addLabelAsSuffix?: boolean;\n  /** Force inclusion of native column label */\n  includeNativeLabel?: boolean;\n  /** Trace elements list that will be forced to be included in the label. */\n  forceTraceElements?: string[];\n};\n\nexport function deriveDistinctLabels<T extends Entry>(\n  values: T[],\n  options: DeriveLabelsOptions = {},\n): WithLabel<T>[] {\n  const forceTraceElements =\n    options.forceTraceElements !== undefined && options.forceTraceElements.length > 0\n      ? new Set(options.forceTraceElements)\n      : undefined;\n  const separator = options.separator ?? \" / \";\n\n  // Phase 1: enrich each value with parsed trace\n  const records = values.map((v) => enrichRecord(v, options));\n\n  // Phase 2: collect global type statistics\n  const stats = collectTypeStats(records);\n\n  // Phase 3: classify types into main (present everywhere) and secondary\n  const { mainTypes, secondaryTypes } = classifyTypes(stats, values.length);\n\n  const build = (typeSet: Set<string>, force: boolean) =>\n    buildLabels(records, typeSet, forceTraceElements, separator, force);\n\n  if (mainTypes.length === 0) {\n    if (secondaryTypes.length !== 0)\n      throw new Error(\"Non-empty secondary types list while main types list is empty.\");\n    return build(new Set(LABEL_TYPE_FULL), true)!;\n  }\n\n  // Phase 4: search for minimal type set that produces unique labels\n  //\n  // includedCount = 2\n  // *  *\n  // T0 T1 T2 T3 T4 T5\n  //          *\n  // additionalType = 3\n  //\n  // Resulting set: T0, T1, T3\n  //\n  let includedCount = 0;\n  let additionalType = -1;\n  while (includedCount < mainTypes.length) {\n    const currentSet = new Set<string>();\n    if (options.includeNativeLabel) currentSet.add(LABEL_TYPE_FULL);\n    for (let i = 0; i < includedCount; ++i) currentSet.add(mainTypes[i]);\n    if (additionalType >= 0) currentSet.add(mainTypes[additionalType]);\n\n    const candidateResult = build(currentSet, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) === values.length) {\n      const minimized = minimizeTypeSet(\n        currentSet,\n        records,\n        stats,\n        forceTraceElements,\n        options,\n        separator,\n      );\n      return build(minimized, false) ?? throwError(\"Failed to derive unique labels\");\n    }\n\n    additionalType++;\n    if (additionalType >= mainTypes.length) {\n      includedCount++;\n      additionalType = includedCount;\n    }\n  }\n\n  // Fallback: include all types, then minimize\n  const fallbackSet = new Set([...mainTypes, ...secondaryTypes]);\n  const minimized = minimizeTypeSet(\n    fallbackSet,\n    records,\n    stats,\n    forceTraceElements,\n    options,\n    separator,\n  );\n  return build(minimized, true) ?? throwError(\"Failed to derive unique labels\");\n}\n\n// --- Pure helpers ---\ntype FullTraceEntry = TraceEntry & { fullType: string; occurrenceIndex: number };\n\ntype EnrichedRecord<T> = {\n  value: T;\n  fullTrace: FullTraceEntry[];\n};\n\nfunction extractSpecAndTrace(entry: Entry): {\n  spec: PObjectSpec;\n  prefixTrace: TraceEntry[] | undefined;\n  suffixTrace: TraceEntry[] | undefined;\n} {\n  if (\"spec\" in entry && typeof entry.spec === \"object\") {\n    return { spec: entry.spec, prefixTrace: entry.prefixTrace, suffixTrace: entry.suffixTrace };\n  }\n  return { spec: entry as PObjectSpec, prefixTrace: undefined, suffixTrace: undefined };\n}\n\nfunction buildFullTrace(trace: TraceEntry[]): FullTraceEntry[] {\n  const result: FullTraceEntry[] = [];\n  const occurrences = new Map<string, number>();\n\n  for (let i = trace.length - 1; i >= 0; --i) {\n    const entry = trace[i];\n    const occurrenceIndex = (occurrences.get(entry.type) ?? 0) + 1;\n    occurrences.set(entry.type, occurrenceIndex);\n    result.push({\n      ...entry,\n      fullType: `${entry.type}@${occurrenceIndex}`,\n      occurrenceIndex,\n    });\n  }\n\n  result.reverse();\n  return result;\n}\n\nfunction enrichRecord<T extends Entry>(value: T, options: DeriveLabelsOptions): EnrichedRecord<T> {\n  const { spec, prefixTrace, suffixTrace } = extractSpecAndTrace(value);\n\n  const label = readAnnotation(spec, Annotation.Label);\n  const traceStr = readAnnotation(spec, Annotation.Trace) as\n    | CanonicalizedJson<TraceEntry[]>\n    | undefined;\n  const baseTrace: Trace = traceStr ? (parseJson<Trace>(traceStr) ?? []) : [];\n  const trace = [...(prefixTrace ?? []), ...baseTrace, ...(suffixTrace ?? [])];\n\n  if (label !== undefined) {\n    const labelEntry = { label, type: LABEL_TYPE, importance: -2 };\n    if (options.addLabelAsSuffix) trace.push(labelEntry);\n    else trace.splice(0, 0, labelEntry);\n  }\n\n  return { value, fullTrace: buildFullTrace(trace) };\n}\n\ntype TypeStats = {\n  importances: Map<string, number>;\n  countByType: Map<string, number>;\n};\n\nfunction collectTypeStats<T>(records: EnrichedRecord<T>[]): TypeStats {\n  const importances = new Map<string, number>();\n  const countByType = new Map<string, number>();\n\n  for (const record of records) {\n    for (let i = 0; i < record.fullTrace.length; i++) {\n      const { fullType, importance: rawImportance } = record.fullTrace[i];\n      const importance = rawImportance ?? 0;\n      const distance = (record.fullTrace.length - i) * DISTANCE_PENALTY;\n\n      countByType.set(fullType, (countByType.get(fullType) ?? 0) + 1);\n      importances.set(\n        fullType,\n        Math.max(importances.get(fullType) ?? Number.NEGATIVE_INFINITY, importance - distance),\n      );\n    }\n  }\n\n  return { importances, countByType };\n}\n\nfunction classifyTypes(\n  stats: TypeStats,\n  totalRecords: number,\n): { mainTypes: string[]; secondaryTypes: string[] } {\n  const sorted = [...stats.importances].sort(([, i1], [, i2]) => i2 - i1);\n\n  const mainTypes: string[] = [];\n  const secondaryTypes: string[] = [];\n\n  for (const [typeName] of sorted) {\n    if (typeName.endsWith(\"@1\") || stats.countByType.get(typeName) === totalRecords)\n      mainTypes.push(typeName);\n    else secondaryTypes.push(typeName);\n  }\n\n  return { mainTypes, secondaryTypes };\n}\n\nfunction buildLabels<T>(\n  records: EnrichedRecord<T>[],\n  includedTypes: Set<string>,\n  forceTraceElements: Set<string> | undefined,\n  separator: string,\n  force: boolean,\n): WithLabel<T>[] | undefined {\n  const result: WithLabel<T>[] = [];\n\n  for (const r of records) {\n    const parts: string[] = [];\n    for (const ft of r.fullTrace) {\n      if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) {\n        parts.push(ft.label);\n      }\n    }\n\n    if (parts.length === 0) {\n      if (!force) return undefined;\n      result.push({ label: \"Unlabeled\", value: r.value });\n      continue;\n    }\n\n    result.push({ label: parts.join(separator), value: r.value });\n  }\n\n  return result;\n}\n\nfunction countUniqueLabels<T>(result: WithLabel<T>[] | undefined): number {\n  if (result === undefined) return 0;\n  return new Set(result.map((c) => c.label)).size;\n}\n\nfunction minimizeTypeSet<T>(\n  typeSet: Set<string>,\n  records: EnrichedRecord<T>[],\n  stats: TypeStats,\n  forceTraceElements: Set<string> | undefined,\n  options: DeriveLabelsOptions,\n  separator: string,\n): Set<string> {\n  const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);\n  if (initialResult === undefined) return typeSet;\n\n  const targetCardinality = countUniqueLabels(initialResult);\n  const result = new Set(typeSet);\n\n  const removable = [...result]\n    .filter(\n      (t) =>\n        !forceTraceElements?.has(t.split(\"@\")[0]) &&\n        !(options.includeNativeLabel && t === LABEL_TYPE_FULL),\n    )\n    .sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));\n\n  for (const typeToRemove of removable) {\n    const candidate = new Set(result);\n    candidate.delete(typeToRemove);\n    const candidateResult = buildLabels(records, candidate, forceTraceElements, separator, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) >= targetCardinality) {\n      result.delete(typeToRemove);\n    }\n  }\n\n  return result;\n}\n"],"mappings":"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"}
+{"version":3,"file":"derive_distinct_labels.cjs","names":["Annotation"],"sources":["../../src/labels/derive_distinct_labels.ts"],"sourcesContent":["import {\n  Annotation,\n  parseJson,\n  readAnnotation,\n  type PObjectSpec,\n  type StringifiedJson,\n  type Trace,\n} from \"@milaboratories/pl-model-common\";\nimport { throwError } from \"@milaboratories/helpers\";\nimport { isFunction, isNil } from \"es-toolkit\";\n\nexport type { Trace, TraceEntry } from \"@milaboratories/pl-model-common\";\n\nconst DISTANCE_PENALTY = 0.001;\nconst LABEL_TYPE = \"__LABEL__\";\nconst LABEL_TYPE_FULL = \"__LABEL__@1\";\n\n/** SDK-internal trace shape — adds fields used by this algorithm only, not part of the on-disk contract. */\ntype ExtendedTraceEntry = Trace[number] & {\n  importance?: number;\n  position?: \"prefix\" | \"suffix\";\n};\n\nexport type Entry =\n  | PObjectSpec\n  | {\n      spec: PObjectSpec;\n      /** Extra trace entries merged with the base trace from annotations. */\n      extraTrace?: ExtendedTraceEntry[];\n      /** Linker steps traversed to discover this column; used to append \"via $linkLabel\" to derived labels. */\n      linkerPath?: { spec: PObjectSpec }[];\n    };\n\nexport type DeriveLabelsOptions = {\n  /** Separator to use between label parts (\" / \" by default) */\n  separator?: string;\n  /** If true, label will be added as suffix (at the end of the generated label). By default label added as a prefix. */\n  addLabelAsSuffix?: boolean;\n  /** Force inclusion of native column label */\n  includeNativeLabel?: boolean;\n  /** Trace elements list that will be forced to be included in the label. */\n  forceTraceElements?: string[];\n  /** Custom formatter for linker path suffix. Receives the array of linker labels from the full traversal chain,\n   *  the column spec, and the column index.\n   *  If returns undefined, no linker suffix is appended. By default labels are joined with \" > \" and prefixed with \"via \". */\n  linkerLabelFormatter?: (\n    linkerLabels: string[],\n    spec: PObjectSpec,\n    index: number,\n  ) => string | undefined;\n};\n\nexport function deriveDistinctLabels(values: Entry[], options: DeriveLabelsOptions = {}): string[] {\n  const forceTraceElements =\n    options.forceTraceElements !== undefined && options.forceTraceElements.length > 0\n      ? new Set(options.forceTraceElements)\n      : undefined;\n  const separator = options.separator ?? \" / \";\n\n  // Collect per-entry linker suffixes before disambiguation\n  const linkerSuffixes = values.map((v, i) => {\n    const spec = \"spec\" in v && typeof v.spec === \"object\" ? v.spec : (v as PObjectSpec);\n    const linkerLabels = extractLinkerLabels(v);\n    if (linkerLabels.length === 0) return undefined;\n    return isFunction(options.linkerLabelFormatter)\n      ? options.linkerLabelFormatter(linkerLabels, spec, i)\n      : `via ${linkerLabels.join(\" > \")}`;\n  });\n\n  // Phase 1: enrich each value with parsed trace\n  const records = values.map((v) => enrichRecord(v, options));\n\n  // Phase 2: collect global type statistics\n  const stats = collectTypeStats(records);\n\n  // Phase 3: classify types into main (present everywhere) and secondary\n  const { mainTypes, secondaryTypes } = classifyTypes(stats, values.length);\n\n  const build = (typeSet: Set<string>, force: boolean) =>\n    buildLabels(records, typeSet, forceTraceElements, separator, force);\n\n  if (mainTypes.length === 0) {\n    if (secondaryTypes.length !== 0)\n      throw new Error(\"Non-empty secondary types list while main types list is empty.\");\n\n    return applyLinkerSuffixes(\n      build(new Set(LABEL_TYPE_FULL), true) ??\n        throwError(\"Failed to derive labels using native column labels\"),\n      linkerSuffixes,\n    );\n  }\n\n  // Phase 4: search for minimal type set that produces unique labels\n  //\n  // includedCount = 2\n  // *  *\n  // T0 T1 T2 T3 T4 T5\n  //          *\n  // additionalType = 3\n  //\n  // Resulting set: T0, T1, T3\n  //\n  let includedCount = 0;\n  let additionalType = -1;\n  while (includedCount < mainTypes.length) {\n    const currentSet = new Set<string>();\n    if (options.includeNativeLabel) currentSet.add(LABEL_TYPE_FULL);\n    for (let i = 0; i < includedCount; ++i) currentSet.add(mainTypes[i]);\n    if (additionalType >= 0) currentSet.add(mainTypes[additionalType]);\n\n    const candidateResult = build(currentSet, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) === values.length) {\n      const minimized = minimizeTypeSet(\n        currentSet,\n        records,\n        stats,\n        forceTraceElements,\n        options,\n        separator,\n      );\n      return applyLinkerSuffixes(\n        build(minimized, false) ?? throwError(\"Failed to derive unique labels\"),\n        linkerSuffixes,\n      );\n    }\n\n    additionalType++;\n    if (additionalType >= mainTypes.length) {\n      includedCount++;\n      additionalType = includedCount;\n    }\n  }\n\n  // Fallback: include all types, then minimize\n  const fallbackSet = new Set([...mainTypes, ...secondaryTypes]);\n  const minimized = minimizeTypeSet(\n    fallbackSet,\n    records,\n    stats,\n    forceTraceElements,\n    options,\n    separator,\n  );\n  return applyLinkerSuffixes(\n    build(minimized, true) ?? throwError(\"Failed to derive unique labels\"),\n    linkerSuffixes,\n  );\n}\n\n/** Apply pre-formatted linker suffixes to labels that have them. */\nfunction applyLinkerSuffixes(labels: string[], suffixes: (string | undefined)[]): string[] {\n  return labels.map((label, i) => (isNil(suffixes[i]) ? label : `${label} ${suffixes[i]}`));\n}\n\n/** Extract linker labels from every step of the linkers path. */\nfunction extractLinkerLabels(entry: Entry): string[] {\n  if (!(\"spec\" in entry) || typeof entry.spec !== \"object\") return [];\n  const path = entry.linkerPath;\n  if (path === undefined || path.length === 0) return [];\n  const labels: string[] = [];\n  for (const step of path) {\n    const label = (\n      readAnnotation(step.spec, Annotation.LinkLabel) ?? readAnnotation(step.spec, Annotation.Label)\n    )?.trim();\n    if (label !== undefined && label.length > 0) {\n      labels.push(label);\n    }\n  }\n  return labels;\n}\n\n// --- Pure helpers ---\ntype FullTraceEntry = ExtendedTraceEntry & { fullType: string; occurrenceIndex: number };\n\ntype EnrichedRecord = {\n  fullTrace: FullTraceEntry[];\n};\n\nfunction extractSpecAndTrace(entry: Entry): {\n  spec: PObjectSpec;\n  extraTrace: ExtendedTraceEntry[] | undefined;\n  linkerPath: { spec: PObjectSpec }[] | undefined;\n} {\n  const isEnriched = \"spec\" in entry && typeof entry.spec === \"object\";\n  return {\n    spec: isEnriched ? entry.spec : (entry as PObjectSpec),\n    extraTrace: isEnriched ? entry.extraTrace : undefined,\n    linkerPath: isEnriched ? entry.linkerPath : undefined,\n  };\n}\n\nfunction buildFullTrace(trace: ExtendedTraceEntry[]): FullTraceEntry[] {\n  const result: FullTraceEntry[] = [];\n  const occurrences = new Map<string, number>();\n\n  for (let i = trace.length - 1; i >= 0; --i) {\n    const entry = trace[i];\n    const occurrenceIndex = (occurrences.get(entry.type) ?? 0) + 1;\n    occurrences.set(entry.type, occurrenceIndex);\n    result.push({\n      ...entry,\n      fullType: `${entry.type}@${occurrenceIndex}`,\n      occurrenceIndex,\n    });\n  }\n\n  result.reverse();\n  return result;\n}\n\nfunction enrichRecord(value: Entry, options: DeriveLabelsOptions): EnrichedRecord {\n  const { spec, extraTrace } = extractSpecAndTrace(value);\n\n  const label = readAnnotation(spec, Annotation.Label);\n  const traceStr = readAnnotation(spec, Annotation.Trace);\n  const baseTrace = traceStr\n    ? (parseJson(traceStr as StringifiedJson<ExtendedTraceEntry[]>) ?? [])\n    : [];\n  const prefixExtra = extraTrace?.filter((e) => e.position === \"prefix\") ?? [];\n  const suffixExtra = extraTrace?.filter((e) => e.position !== \"prefix\") ?? [];\n  const trace = [...prefixExtra, ...baseTrace, ...suffixExtra];\n\n  if (label !== undefined) {\n    const labelEntry = { label, type: LABEL_TYPE, importance: -2 };\n    if (options.addLabelAsSuffix) trace.push(labelEntry);\n    else trace.splice(0, 0, labelEntry);\n  }\n\n  return { fullTrace: buildFullTrace(trace) };\n}\n\ntype TypeStats = {\n  importances: Map<string, number>;\n  countByType: Map<string, number>;\n};\n\nfunction collectTypeStats(records: EnrichedRecord[]): TypeStats {\n  const importances = new Map<string, number>();\n  const countByType = new Map<string, number>();\n\n  for (const record of records) {\n    for (let i = 0; i < record.fullTrace.length; i++) {\n      const { fullType, importance: rawImportance } = record.fullTrace[i];\n      const importance = rawImportance ?? 0;\n      const distance = (record.fullTrace.length - i) * DISTANCE_PENALTY;\n\n      countByType.set(fullType, (countByType.get(fullType) ?? 0) + 1);\n      importances.set(\n        fullType,\n        Math.max(importances.get(fullType) ?? Number.NEGATIVE_INFINITY, importance - distance),\n      );\n    }\n  }\n\n  return { importances, countByType };\n}\n\nfunction classifyTypes(\n  stats: TypeStats,\n  totalRecords: number,\n): { mainTypes: string[]; secondaryTypes: string[] } {\n  const sorted = [...stats.importances].sort(([, i1], [, i2]) => i2 - i1);\n\n  const mainTypes: string[] = [];\n  const secondaryTypes: string[] = [];\n\n  for (const [typeName] of sorted) {\n    if (typeName.endsWith(\"@1\") || stats.countByType.get(typeName) === totalRecords)\n      mainTypes.push(typeName);\n    else secondaryTypes.push(typeName);\n  }\n\n  return { mainTypes, secondaryTypes };\n}\n\nfunction buildLabels(\n  records: EnrichedRecord[],\n  includedTypes: Set<string>,\n  forceTraceElements: Set<string> | undefined,\n  separator: string,\n  force: boolean,\n): string[] | undefined {\n  const result: string[] = [];\n\n  for (const r of records) {\n    const parts: string[] = [];\n    for (const ft of r.fullTrace) {\n      if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) {\n        parts.push(ft.label);\n      }\n    }\n\n    if (parts.length === 0) {\n      if (!force) return undefined;\n      result.push(\"Unlabeled\");\n      continue;\n    }\n\n    result.push(parts.join(separator));\n  }\n\n  return result;\n}\n\nfunction countUniqueLabels(result: string[] | undefined): number {\n  if (result === undefined) return 0;\n  return new Set(result).size;\n}\n\nfunction minimizeTypeSet(\n  typeSet: Set<string>,\n  records: EnrichedRecord[],\n  stats: TypeStats,\n  forceTraceElements: Set<string> | undefined,\n  options: DeriveLabelsOptions,\n  separator: string,\n): Set<string> {\n  const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);\n  if (initialResult === undefined) return typeSet;\n\n  const targetCardinality = countUniqueLabels(initialResult);\n  const result = new Set(typeSet);\n\n  const removable = [...result]\n    .filter(\n      (t) =>\n        !forceTraceElements?.has(t.split(\"@\")[0]) &&\n        !(options.includeNativeLabel && t === LABEL_TYPE_FULL),\n    )\n    .sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));\n\n  for (const typeToRemove of removable) {\n    const candidate = new Set(result);\n    candidate.delete(typeToRemove);\n    const candidateResult = buildLabels(records, candidate, forceTraceElements, separator, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) >= targetCardinality) {\n      result.delete(typeToRemove);\n    }\n  }\n\n  return result;\n}\n"],"mappings":"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"}

package/dist/labels/derive_distinct_labels.d.ts

@@ -1,29 +1,29 @@
-import { PObjectSpec } from "@milaboratories/pl-model-common";
+import { PObjectSpec, Trace, Trace as Trace$1, TraceEntry } from "@milaboratories/pl-model-common";
 
 //#region src/labels/derive_distinct_labels.d.ts
-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";
 };
-type Trace = TraceEntry[];
 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;
+  }[];
 };
 type DeriveLabelsOptions = {
   /** Separator to use between label parts (" / " by default) */separator?: string; /** If true, label will be added as suffix (at the end of the generated label). By default label added as a prefix. */
   addLabelAsSuffix?: boolean; /** Force inclusion of native column label */
   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;
 };
-declare function deriveDistinctLabels<T extends Entry>(values: T[], options?: DeriveLabelsOptions): WithLabel<T>[];
+declare function deriveDistinctLabels(values: Entry[], options?: DeriveLabelsOptions): string[];
 //#endregion
-export { DeriveLabelsOptions, Entry, Trace, WithLabel, deriveDistinctLabels };
+export { DeriveLabelsOptions, Entry, type Trace$1 as Trace, type TraceEntry, deriveDistinctLabels };
 //# sourceMappingURL=derive_distinct_labels.d.ts.map

package/dist/labels/derive_distinct_labels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive_distinct_labels.d.ts","names":[],"sources":["../../src/labels/derive_distinct_labels.ts"],"mappings":";;;KAaY,SAAA;EACV,KAAA,EAAO,CAAA;EACP,KAAA;AAAA;AAAA,KAGG,UAAA;EACH,EAAA;EACA,IAAA;EACA,KAAA;EACA,UAAA;AAAA;AAAA,KAGU,KAAA,GAAQ,UAAA;AAAA,KAER,KAAA,GACR,WAAA;EACE,IAAA,EAAM,WAAA;EAAa,WAAA,GAAc,UAAA;EAAc,WAAA,GAAc,UAAA;AAAA;AAAA,KAEvD,mBAAA;EAXV,8DAaA,SAAA,WAXA;EAaA,gBAAA,YAbU;EAeV,kBAAA,YAZe;EAcf,kBAAA;AAAA;AAAA,iBAGc,oBAAA,WAA+B,KAAA,CAAA,CAC7C,MAAA,EAAQ,CAAA,IACR,OAAA,GAAS,mBAAA,GACR,SAAA,CAAU,CAAA"}
+{"version":3,"file":"derive_distinct_labels.d.ts","names":[],"sources":["../../src/labels/derive_distinct_labels.ts"],"mappings":";;;;KAkBK,kBAAA,GAAqB,KAAA;EACxB,UAAA;EACA,QAAA;AAAA;AAAA,KAGU,KAAA,GACR,WAAA;EAEE,IAAA,EAAM,WAAA,EANV;EAQI,UAAA,GAAa,kBAAA,IART;EAUJ,UAAA;IAAe,IAAA,EAAM,WAAA;EAAA;AAAA;AAAA,KAGf,mBAAA;EALO,8DAOjB,SAAA,WALoC;EAOpC,gBAAA,YAbE;EAeF,kBAAA,YAbU;EAeV,kBAAA;EAbiB;;;EAiBjB,oBAAA,IACE,YAAA,YACA,IAAA,EAAM,WAAA,EACN,KAAA;AAAA;AAAA,iBAIY,oBAAA,CAAqB,MAAA,EAAQ,KAAA,IAAS,OAAA,GAAS,mBAAA"}

package/dist/labels/derive_distinct_labels.js

@@ -1,5 +1,6 @@
 import { Annotation, parseJson, readAnnotation } from "@milaboratories/pl-model-common";
 import { throwError } from "@milaboratories/helpers";
+import { isFunction, isNil as isNil$1 } from "es-toolkit";
 //#region src/labels/derive_distinct_labels.ts
 const DISTANCE_PENALTY = .001;
 const LABEL_TYPE = "__LABEL__";
@@ -7,13 +8,19 @@ const LABEL_TYPE_FULL = "__LABEL__@1";
 function deriveDistinctLabels(values, options = {}) {
 	const forceTraceElements = options.forceTraceElements !== void 0 && options.forceTraceElements.length > 0 ? new Set(options.forceTraceElements) : void 0;
 	const separator = options.separator ?? " / ";
+	const linkerSuffixes = values.map((v, i) => {
+		const spec = "spec" in v && typeof v.spec === "object" ? v.spec : v;
+		const linkerLabels = extractLinkerLabels(v);
+		if (linkerLabels.length === 0) return void 0;
+		return isFunction(options.linkerLabelFormatter) ? options.linkerLabelFormatter(linkerLabels, spec, i) : `via ${linkerLabels.join(" > ")}`;
+	});
 	const records = values.map((v) => enrichRecord(v, options));
 	const stats = collectTypeStats(records);
 	const { mainTypes, secondaryTypes } = classifyTypes(stats, values.length);
 	const build = (typeSet, force) => buildLabels(records, typeSet, forceTraceElements, separator, force);
 	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);
 	}
 	let includedCount = 0;
 	let additionalType = -1;
@@ -23,25 +30,37 @@ function deriveDistinctLabels(values, options = {}) {
 		for (let i = 0; i < includedCount; ++i) currentSet.add(mainTypes[i]);
 		if (additionalType >= 0) currentSet.add(mainTypes[additionalType]);
 		const candidateResult = build(currentSet, false);
-		if (candidateResult !== void 0 && countUniqueLabels(candidateResult) === values.length) return build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, options, separator), false) ?? throwError("Failed to derive unique labels");
+		if (candidateResult !== void 0 && countUniqueLabels(candidateResult) === values.length) return applyLinkerSuffixes(build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, options, separator), false) ?? throwError("Failed to derive unique labels"), linkerSuffixes);
 		additionalType++;
 		if (additionalType >= mainTypes.length) {
 			includedCount++;
 			additionalType = includedCount;
 		}
 	}
-	return build(minimizeTypeSet(new Set([...mainTypes, ...secondaryTypes]), records, stats, forceTraceElements, options, separator), true) ?? throwError("Failed to derive unique labels");
+	return applyLinkerSuffixes(build(minimizeTypeSet(new Set([...mainTypes, ...secondaryTypes]), records, stats, forceTraceElements, options, separator), true) ?? throwError("Failed to derive unique labels"), linkerSuffixes);
+}
+/** Apply pre-formatted linker suffixes to labels that have them. */
+function applyLinkerSuffixes(labels, suffixes) {
+	return labels.map((label, i) => isNil$1(suffixes[i]) ? label : `${label} ${suffixes[i]}`);
+}
+/** Extract linker labels from every step of the linkers path. */
+function extractLinkerLabels(entry) {
+	if (!("spec" in entry) || typeof entry.spec !== "object") return [];
+	const path = entry.linkerPath;
+	if (path === void 0 || path.length === 0) return [];
+	const labels = [];
+	for (const step of path) {
+		const label = (readAnnotation(step.spec, Annotation.LinkLabel) ?? readAnnotation(step.spec, Annotation.Label))?.trim();
+		if (label !== void 0 && label.length > 0) labels.push(label);
+	}
+	return labels;
 }
 function extractSpecAndTrace(entry) {
-	if ("spec" in entry && typeof entry.spec === "object") return {
-		spec: entry.spec,
-		prefixTrace: entry.prefixTrace,
-		suffixTrace: entry.suffixTrace
-	};
+	const isEnriched = "spec" in entry && typeof entry.spec === "object";
 	return {
-		spec: entry,
-		prefixTrace: void 0,
-		suffixTrace: void 0
+		spec: isEnriched ? entry.spec : entry,
+		extraTrace: isEnriched ? entry.extraTrace : void 0,
+		linkerPath: isEnriched ? entry.linkerPath : void 0
 	};
 }
 function buildFullTrace(trace) {
@@ -61,14 +80,16 @@ function buildFullTrace(trace) {
 	return result;
 }
 function enrichRecord(value, options) {
-	const { spec, prefixTrace, suffixTrace } = extractSpecAndTrace(value);
+	const { spec, extraTrace } = extractSpecAndTrace(value);
 	const label = readAnnotation(spec, Annotation.Label);
 	const traceStr = readAnnotation(spec, Annotation.Trace);
 	const baseTrace = traceStr ? parseJson(traceStr) ?? [] : [];
+	const prefixExtra = extraTrace?.filter((e) => e.position === "prefix") ?? [];
+	const suffixExtra = extraTrace?.filter((e) => e.position !== "prefix") ?? [];
 	const trace = [
-		...prefixTrace ?? [],
+		...prefixExtra,
 		...baseTrace,
-		...suffixTrace ?? []
+		...suffixExtra
 	];
 	if (label !== void 0) {
 		const labelEntry = {
@@ -79,10 +100,7 @@ function enrichRecord(value, options) {
 		if (options.addLabelAsSuffix) trace.push(labelEntry);
 		else trace.splice(0, 0, labelEntry);
 	}
-	return {
-		value,
-		fullTrace: buildFullTrace(trace)
-	};
+	return { fullTrace: buildFullTrace(trace) };
 }
 function collectTypeStats(records) {
 	const importances = /* @__PURE__ */ new Map();
@@ -117,22 +135,16 @@ function buildLabels(records, includedTypes, forceTraceElements, separator, forc
 		for (const ft of r.fullTrace) if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) parts.push(ft.label);
 		if (parts.length === 0) {
 			if (!force) return void 0;
-			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(result) {
 	if (result === void 0) return 0;
-	return new Set(result.map((c) => c.label)).size;
+	return new Set(result).size;
 }
 function minimizeTypeSet(typeSet, records, stats, forceTraceElements, options, separator) {
 	const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);

package/dist/labels/derive_distinct_labels.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive_distinct_labels.js","names":[],"sources":["../../src/labels/derive_distinct_labels.ts"],"sourcesContent":["import {\n  Annotation,\n  parseJson,\n  readAnnotation,\n  type CanonicalizedJson,\n  type PObjectSpec,\n} from \"@milaboratories/pl-model-common\";\nimport { throwError } from \"@milaboratories/helpers\";\n\nconst DISTANCE_PENALTY = 0.001;\nconst LABEL_TYPE = \"__LABEL__\";\nconst LABEL_TYPE_FULL = \"__LABEL__@1\";\n\nexport type WithLabel<T> = {\n  value: T;\n  label: string;\n};\n\ntype TraceEntry = {\n  id?: string;\n  type: string;\n  label: string;\n  importance?: number;\n};\n\nexport type Trace = TraceEntry[];\n\nexport type Entry =\n  | PObjectSpec\n  | { spec: PObjectSpec; prefixTrace?: TraceEntry[]; suffixTrace?: TraceEntry[] };\n\nexport type DeriveLabelsOptions = {\n  /** Separator to use between label parts (\" / \" by default) */\n  separator?: string;\n  /** If true, label will be added as suffix (at the end of the generated label). By default label added as a prefix. */\n  addLabelAsSuffix?: boolean;\n  /** Force inclusion of native column label */\n  includeNativeLabel?: boolean;\n  /** Trace elements list that will be forced to be included in the label. */\n  forceTraceElements?: string[];\n};\n\nexport function deriveDistinctLabels<T extends Entry>(\n  values: T[],\n  options: DeriveLabelsOptions = {},\n): WithLabel<T>[] {\n  const forceTraceElements =\n    options.forceTraceElements !== undefined && options.forceTraceElements.length > 0\n      ? new Set(options.forceTraceElements)\n      : undefined;\n  const separator = options.separator ?? \" / \";\n\n  // Phase 1: enrich each value with parsed trace\n  const records = values.map((v) => enrichRecord(v, options));\n\n  // Phase 2: collect global type statistics\n  const stats = collectTypeStats(records);\n\n  // Phase 3: classify types into main (present everywhere) and secondary\n  const { mainTypes, secondaryTypes } = classifyTypes(stats, values.length);\n\n  const build = (typeSet: Set<string>, force: boolean) =>\n    buildLabels(records, typeSet, forceTraceElements, separator, force);\n\n  if (mainTypes.length === 0) {\n    if (secondaryTypes.length !== 0)\n      throw new Error(\"Non-empty secondary types list while main types list is empty.\");\n    return build(new Set(LABEL_TYPE_FULL), true)!;\n  }\n\n  // Phase 4: search for minimal type set that produces unique labels\n  //\n  // includedCount = 2\n  // *  *\n  // T0 T1 T2 T3 T4 T5\n  //          *\n  // additionalType = 3\n  //\n  // Resulting set: T0, T1, T3\n  //\n  let includedCount = 0;\n  let additionalType = -1;\n  while (includedCount < mainTypes.length) {\n    const currentSet = new Set<string>();\n    if (options.includeNativeLabel) currentSet.add(LABEL_TYPE_FULL);\n    for (let i = 0; i < includedCount; ++i) currentSet.add(mainTypes[i]);\n    if (additionalType >= 0) currentSet.add(mainTypes[additionalType]);\n\n    const candidateResult = build(currentSet, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) === values.length) {\n      const minimized = minimizeTypeSet(\n        currentSet,\n        records,\n        stats,\n        forceTraceElements,\n        options,\n        separator,\n      );\n      return build(minimized, false) ?? throwError(\"Failed to derive unique labels\");\n    }\n\n    additionalType++;\n    if (additionalType >= mainTypes.length) {\n      includedCount++;\n      additionalType = includedCount;\n    }\n  }\n\n  // Fallback: include all types, then minimize\n  const fallbackSet = new Set([...mainTypes, ...secondaryTypes]);\n  const minimized = minimizeTypeSet(\n    fallbackSet,\n    records,\n    stats,\n    forceTraceElements,\n    options,\n    separator,\n  );\n  return build(minimized, true) ?? throwError(\"Failed to derive unique labels\");\n}\n\n// --- Pure helpers ---\ntype FullTraceEntry = TraceEntry & { fullType: string; occurrenceIndex: number };\n\ntype EnrichedRecord<T> = {\n  value: T;\n  fullTrace: FullTraceEntry[];\n};\n\nfunction extractSpecAndTrace(entry: Entry): {\n  spec: PObjectSpec;\n  prefixTrace: TraceEntry[] | undefined;\n  suffixTrace: TraceEntry[] | undefined;\n} {\n  if (\"spec\" in entry && typeof entry.spec === \"object\") {\n    return { spec: entry.spec, prefixTrace: entry.prefixTrace, suffixTrace: entry.suffixTrace };\n  }\n  return { spec: entry as PObjectSpec, prefixTrace: undefined, suffixTrace: undefined };\n}\n\nfunction buildFullTrace(trace: TraceEntry[]): FullTraceEntry[] {\n  const result: FullTraceEntry[] = [];\n  const occurrences = new Map<string, number>();\n\n  for (let i = trace.length - 1; i >= 0; --i) {\n    const entry = trace[i];\n    const occurrenceIndex = (occurrences.get(entry.type) ?? 0) + 1;\n    occurrences.set(entry.type, occurrenceIndex);\n    result.push({\n      ...entry,\n      fullType: `${entry.type}@${occurrenceIndex}`,\n      occurrenceIndex,\n    });\n  }\n\n  result.reverse();\n  return result;\n}\n\nfunction enrichRecord<T extends Entry>(value: T, options: DeriveLabelsOptions): EnrichedRecord<T> {\n  const { spec, prefixTrace, suffixTrace } = extractSpecAndTrace(value);\n\n  const label = readAnnotation(spec, Annotation.Label);\n  const traceStr = readAnnotation(spec, Annotation.Trace) as\n    | CanonicalizedJson<TraceEntry[]>\n    | undefined;\n  const baseTrace: Trace = traceStr ? (parseJson<Trace>(traceStr) ?? []) : [];\n  const trace = [...(prefixTrace ?? []), ...baseTrace, ...(suffixTrace ?? [])];\n\n  if (label !== undefined) {\n    const labelEntry = { label, type: LABEL_TYPE, importance: -2 };\n    if (options.addLabelAsSuffix) trace.push(labelEntry);\n    else trace.splice(0, 0, labelEntry);\n  }\n\n  return { value, fullTrace: buildFullTrace(trace) };\n}\n\ntype TypeStats = {\n  importances: Map<string, number>;\n  countByType: Map<string, number>;\n};\n\nfunction collectTypeStats<T>(records: EnrichedRecord<T>[]): TypeStats {\n  const importances = new Map<string, number>();\n  const countByType = new Map<string, number>();\n\n  for (const record of records) {\n    for (let i = 0; i < record.fullTrace.length; i++) {\n      const { fullType, importance: rawImportance } = record.fullTrace[i];\n      const importance = rawImportance ?? 0;\n      const distance = (record.fullTrace.length - i) * DISTANCE_PENALTY;\n\n      countByType.set(fullType, (countByType.get(fullType) ?? 0) + 1);\n      importances.set(\n        fullType,\n        Math.max(importances.get(fullType) ?? Number.NEGATIVE_INFINITY, importance - distance),\n      );\n    }\n  }\n\n  return { importances, countByType };\n}\n\nfunction classifyTypes(\n  stats: TypeStats,\n  totalRecords: number,\n): { mainTypes: string[]; secondaryTypes: string[] } {\n  const sorted = [...stats.importances].sort(([, i1], [, i2]) => i2 - i1);\n\n  const mainTypes: string[] = [];\n  const secondaryTypes: string[] = [];\n\n  for (const [typeName] of sorted) {\n    if (typeName.endsWith(\"@1\") || stats.countByType.get(typeName) === totalRecords)\n      mainTypes.push(typeName);\n    else secondaryTypes.push(typeName);\n  }\n\n  return { mainTypes, secondaryTypes };\n}\n\nfunction buildLabels<T>(\n  records: EnrichedRecord<T>[],\n  includedTypes: Set<string>,\n  forceTraceElements: Set<string> | undefined,\n  separator: string,\n  force: boolean,\n): WithLabel<T>[] | undefined {\n  const result: WithLabel<T>[] = [];\n\n  for (const r of records) {\n    const parts: string[] = [];\n    for (const ft of r.fullTrace) {\n      if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) {\n        parts.push(ft.label);\n      }\n    }\n\n    if (parts.length === 0) {\n      if (!force) return undefined;\n      result.push({ label: \"Unlabeled\", value: r.value });\n      continue;\n    }\n\n    result.push({ label: parts.join(separator), value: r.value });\n  }\n\n  return result;\n}\n\nfunction countUniqueLabels<T>(result: WithLabel<T>[] | undefined): number {\n  if (result === undefined) return 0;\n  return new Set(result.map((c) => c.label)).size;\n}\n\nfunction minimizeTypeSet<T>(\n  typeSet: Set<string>,\n  records: EnrichedRecord<T>[],\n  stats: TypeStats,\n  forceTraceElements: Set<string> | undefined,\n  options: DeriveLabelsOptions,\n  separator: string,\n): Set<string> {\n  const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);\n  if (initialResult === undefined) return typeSet;\n\n  const targetCardinality = countUniqueLabels(initialResult);\n  const result = new Set(typeSet);\n\n  const removable = [...result]\n    .filter(\n      (t) =>\n        !forceTraceElements?.has(t.split(\"@\")[0]) &&\n        !(options.includeNativeLabel && t === LABEL_TYPE_FULL),\n    )\n    .sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));\n\n  for (const typeToRemove of removable) {\n    const candidate = new Set(result);\n    candidate.delete(typeToRemove);\n    const candidateResult = buildLabels(records, candidate, forceTraceElements, separator, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) >= targetCardinality) {\n      result.delete(typeToRemove);\n    }\n  }\n\n  return result;\n}\n"],"mappings":"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"}
+{"version":3,"file":"derive_distinct_labels.js","names":["isNil"],"sources":["../../src/labels/derive_distinct_labels.ts"],"sourcesContent":["import {\n  Annotation,\n  parseJson,\n  readAnnotation,\n  type PObjectSpec,\n  type StringifiedJson,\n  type Trace,\n} from \"@milaboratories/pl-model-common\";\nimport { throwError } from \"@milaboratories/helpers\";\nimport { isFunction, isNil } from \"es-toolkit\";\n\nexport type { Trace, TraceEntry } from \"@milaboratories/pl-model-common\";\n\nconst DISTANCE_PENALTY = 0.001;\nconst LABEL_TYPE = \"__LABEL__\";\nconst LABEL_TYPE_FULL = \"__LABEL__@1\";\n\n/** SDK-internal trace shape — adds fields used by this algorithm only, not part of the on-disk contract. */\ntype ExtendedTraceEntry = Trace[number] & {\n  importance?: number;\n  position?: \"prefix\" | \"suffix\";\n};\n\nexport type Entry =\n  | PObjectSpec\n  | {\n      spec: PObjectSpec;\n      /** Extra trace entries merged with the base trace from annotations. */\n      extraTrace?: ExtendedTraceEntry[];\n      /** Linker steps traversed to discover this column; used to append \"via $linkLabel\" to derived labels. */\n      linkerPath?: { spec: PObjectSpec }[];\n    };\n\nexport type DeriveLabelsOptions = {\n  /** Separator to use between label parts (\" / \" by default) */\n  separator?: string;\n  /** If true, label will be added as suffix (at the end of the generated label). By default label added as a prefix. */\n  addLabelAsSuffix?: boolean;\n  /** Force inclusion of native column label */\n  includeNativeLabel?: boolean;\n  /** Trace elements list that will be forced to be included in the label. */\n  forceTraceElements?: string[];\n  /** Custom formatter for linker path suffix. Receives the array of linker labels from the full traversal chain,\n   *  the column spec, and the column index.\n   *  If returns undefined, no linker suffix is appended. By default labels are joined with \" > \" and prefixed with \"via \". */\n  linkerLabelFormatter?: (\n    linkerLabels: string[],\n    spec: PObjectSpec,\n    index: number,\n  ) => string | undefined;\n};\n\nexport function deriveDistinctLabels(values: Entry[], options: DeriveLabelsOptions = {}): string[] {\n  const forceTraceElements =\n    options.forceTraceElements !== undefined && options.forceTraceElements.length > 0\n      ? new Set(options.forceTraceElements)\n      : undefined;\n  const separator = options.separator ?? \" / \";\n\n  // Collect per-entry linker suffixes before disambiguation\n  const linkerSuffixes = values.map((v, i) => {\n    const spec = \"spec\" in v && typeof v.spec === \"object\" ? v.spec : (v as PObjectSpec);\n    const linkerLabels = extractLinkerLabels(v);\n    if (linkerLabels.length === 0) return undefined;\n    return isFunction(options.linkerLabelFormatter)\n      ? options.linkerLabelFormatter(linkerLabels, spec, i)\n      : `via ${linkerLabels.join(\" > \")}`;\n  });\n\n  // Phase 1: enrich each value with parsed trace\n  const records = values.map((v) => enrichRecord(v, options));\n\n  // Phase 2: collect global type statistics\n  const stats = collectTypeStats(records);\n\n  // Phase 3: classify types into main (present everywhere) and secondary\n  const { mainTypes, secondaryTypes } = classifyTypes(stats, values.length);\n\n  const build = (typeSet: Set<string>, force: boolean) =>\n    buildLabels(records, typeSet, forceTraceElements, separator, force);\n\n  if (mainTypes.length === 0) {\n    if (secondaryTypes.length !== 0)\n      throw new Error(\"Non-empty secondary types list while main types list is empty.\");\n\n    return applyLinkerSuffixes(\n      build(new Set(LABEL_TYPE_FULL), true) ??\n        throwError(\"Failed to derive labels using native column labels\"),\n      linkerSuffixes,\n    );\n  }\n\n  // Phase 4: search for minimal type set that produces unique labels\n  //\n  // includedCount = 2\n  // *  *\n  // T0 T1 T2 T3 T4 T5\n  //          *\n  // additionalType = 3\n  //\n  // Resulting set: T0, T1, T3\n  //\n  let includedCount = 0;\n  let additionalType = -1;\n  while (includedCount < mainTypes.length) {\n    const currentSet = new Set<string>();\n    if (options.includeNativeLabel) currentSet.add(LABEL_TYPE_FULL);\n    for (let i = 0; i < includedCount; ++i) currentSet.add(mainTypes[i]);\n    if (additionalType >= 0) currentSet.add(mainTypes[additionalType]);\n\n    const candidateResult = build(currentSet, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) === values.length) {\n      const minimized = minimizeTypeSet(\n        currentSet,\n        records,\n        stats,\n        forceTraceElements,\n        options,\n        separator,\n      );\n      return applyLinkerSuffixes(\n        build(minimized, false) ?? throwError(\"Failed to derive unique labels\"),\n        linkerSuffixes,\n      );\n    }\n\n    additionalType++;\n    if (additionalType >= mainTypes.length) {\n      includedCount++;\n      additionalType = includedCount;\n    }\n  }\n\n  // Fallback: include all types, then minimize\n  const fallbackSet = new Set([...mainTypes, ...secondaryTypes]);\n  const minimized = minimizeTypeSet(\n    fallbackSet,\n    records,\n    stats,\n    forceTraceElements,\n    options,\n    separator,\n  );\n  return applyLinkerSuffixes(\n    build(minimized, true) ?? throwError(\"Failed to derive unique labels\"),\n    linkerSuffixes,\n  );\n}\n\n/** Apply pre-formatted linker suffixes to labels that have them. */\nfunction applyLinkerSuffixes(labels: string[], suffixes: (string | undefined)[]): string[] {\n  return labels.map((label, i) => (isNil(suffixes[i]) ? label : `${label} ${suffixes[i]}`));\n}\n\n/** Extract linker labels from every step of the linkers path. */\nfunction extractLinkerLabels(entry: Entry): string[] {\n  if (!(\"spec\" in entry) || typeof entry.spec !== \"object\") return [];\n  const path = entry.linkerPath;\n  if (path === undefined || path.length === 0) return [];\n  const labels: string[] = [];\n  for (const step of path) {\n    const label = (\n      readAnnotation(step.spec, Annotation.LinkLabel) ?? readAnnotation(step.spec, Annotation.Label)\n    )?.trim();\n    if (label !== undefined && label.length > 0) {\n      labels.push(label);\n    }\n  }\n  return labels;\n}\n\n// --- Pure helpers ---\ntype FullTraceEntry = ExtendedTraceEntry & { fullType: string; occurrenceIndex: number };\n\ntype EnrichedRecord = {\n  fullTrace: FullTraceEntry[];\n};\n\nfunction extractSpecAndTrace(entry: Entry): {\n  spec: PObjectSpec;\n  extraTrace: ExtendedTraceEntry[] | undefined;\n  linkerPath: { spec: PObjectSpec }[] | undefined;\n} {\n  const isEnriched = \"spec\" in entry && typeof entry.spec === \"object\";\n  return {\n    spec: isEnriched ? entry.spec : (entry as PObjectSpec),\n    extraTrace: isEnriched ? entry.extraTrace : undefined,\n    linkerPath: isEnriched ? entry.linkerPath : undefined,\n  };\n}\n\nfunction buildFullTrace(trace: ExtendedTraceEntry[]): FullTraceEntry[] {\n  const result: FullTraceEntry[] = [];\n  const occurrences = new Map<string, number>();\n\n  for (let i = trace.length - 1; i >= 0; --i) {\n    const entry = trace[i];\n    const occurrenceIndex = (occurrences.get(entry.type) ?? 0) + 1;\n    occurrences.set(entry.type, occurrenceIndex);\n    result.push({\n      ...entry,\n      fullType: `${entry.type}@${occurrenceIndex}`,\n      occurrenceIndex,\n    });\n  }\n\n  result.reverse();\n  return result;\n}\n\nfunction enrichRecord(value: Entry, options: DeriveLabelsOptions): EnrichedRecord {\n  const { spec, extraTrace } = extractSpecAndTrace(value);\n\n  const label = readAnnotation(spec, Annotation.Label);\n  const traceStr = readAnnotation(spec, Annotation.Trace);\n  const baseTrace = traceStr\n    ? (parseJson(traceStr as StringifiedJson<ExtendedTraceEntry[]>) ?? [])\n    : [];\n  const prefixExtra = extraTrace?.filter((e) => e.position === \"prefix\") ?? [];\n  const suffixExtra = extraTrace?.filter((e) => e.position !== \"prefix\") ?? [];\n  const trace = [...prefixExtra, ...baseTrace, ...suffixExtra];\n\n  if (label !== undefined) {\n    const labelEntry = { label, type: LABEL_TYPE, importance: -2 };\n    if (options.addLabelAsSuffix) trace.push(labelEntry);\n    else trace.splice(0, 0, labelEntry);\n  }\n\n  return { fullTrace: buildFullTrace(trace) };\n}\n\ntype TypeStats = {\n  importances: Map<string, number>;\n  countByType: Map<string, number>;\n};\n\nfunction collectTypeStats(records: EnrichedRecord[]): TypeStats {\n  const importances = new Map<string, number>();\n  const countByType = new Map<string, number>();\n\n  for (const record of records) {\n    for (let i = 0; i < record.fullTrace.length; i++) {\n      const { fullType, importance: rawImportance } = record.fullTrace[i];\n      const importance = rawImportance ?? 0;\n      const distance = (record.fullTrace.length - i) * DISTANCE_PENALTY;\n\n      countByType.set(fullType, (countByType.get(fullType) ?? 0) + 1);\n      importances.set(\n        fullType,\n        Math.max(importances.get(fullType) ?? Number.NEGATIVE_INFINITY, importance - distance),\n      );\n    }\n  }\n\n  return { importances, countByType };\n}\n\nfunction classifyTypes(\n  stats: TypeStats,\n  totalRecords: number,\n): { mainTypes: string[]; secondaryTypes: string[] } {\n  const sorted = [...stats.importances].sort(([, i1], [, i2]) => i2 - i1);\n\n  const mainTypes: string[] = [];\n  const secondaryTypes: string[] = [];\n\n  for (const [typeName] of sorted) {\n    if (typeName.endsWith(\"@1\") || stats.countByType.get(typeName) === totalRecords)\n      mainTypes.push(typeName);\n    else secondaryTypes.push(typeName);\n  }\n\n  return { mainTypes, secondaryTypes };\n}\n\nfunction buildLabels(\n  records: EnrichedRecord[],\n  includedTypes: Set<string>,\n  forceTraceElements: Set<string> | undefined,\n  separator: string,\n  force: boolean,\n): string[] | undefined {\n  const result: string[] = [];\n\n  for (const r of records) {\n    const parts: string[] = [];\n    for (const ft of r.fullTrace) {\n      if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) {\n        parts.push(ft.label);\n      }\n    }\n\n    if (parts.length === 0) {\n      if (!force) return undefined;\n      result.push(\"Unlabeled\");\n      continue;\n    }\n\n    result.push(parts.join(separator));\n  }\n\n  return result;\n}\n\nfunction countUniqueLabels(result: string[] | undefined): number {\n  if (result === undefined) return 0;\n  return new Set(result).size;\n}\n\nfunction minimizeTypeSet(\n  typeSet: Set<string>,\n  records: EnrichedRecord[],\n  stats: TypeStats,\n  forceTraceElements: Set<string> | undefined,\n  options: DeriveLabelsOptions,\n  separator: string,\n): Set<string> {\n  const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);\n  if (initialResult === undefined) return typeSet;\n\n  const targetCardinality = countUniqueLabels(initialResult);\n  const result = new Set(typeSet);\n\n  const removable = [...result]\n    .filter(\n      (t) =>\n        !forceTraceElements?.has(t.split(\"@\")[0]) &&\n        !(options.includeNativeLabel && t === LABEL_TYPE_FULL),\n    )\n    .sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));\n\n  for (const typeToRemove of removable) {\n    const candidate = new Set(result);\n    candidate.delete(typeToRemove);\n    const candidateResult = buildLabels(records, candidate, forceTraceElements, separator, false);\n    if (candidateResult !== undefined && countUniqueLabels(candidateResult) >= targetCardinality) {\n      result.delete(typeToRemove);\n    }\n  }\n\n  return result;\n}\n"],"mappings":"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"}

package/dist/labels/index.cjs

@@ -1,2 +1 @@
 require("./derive_distinct_labels.cjs");
-require("./write_labels_to_specs.cjs");

package/dist/labels/index.d.ts

@@ -1,2 +1 @@
-import { DeriveLabelsOptions, Entry, Trace, WithLabel, deriveDistinctLabels } from "./derive_distinct_labels.js";
-import { writeLabelsToSpecs } from "./write_labels_to_specs.js";
+import { DeriveLabelsOptions, Entry, Trace, TraceEntry, deriveDistinctLabels } from "./derive_distinct_labels.js";

package/dist/labels/index.js

@@ -1,2 +1 @@
 import "./derive_distinct_labels.js";
-import "./write_labels_to_specs.js";

package/dist/package.cjs

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "1.63.12";
+var version = "1.64.0";
 //#endregion
 Object.defineProperty(exports, "version", {
 	enumerable: true,

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "1.63.12";
+var version = "1.64.0";
 //#endregion
 export { version };
 

package/dist/render/api.cjs

@@ -379,8 +379,8 @@ var RenderCtxBase = class {
 		return def;
 	}
 	createPFrame(def) {
-		this.verifyInlineAndExplicitColumnsSupport(def);
 		if (!require_pcolumn_data.allPColumnsReady(def)) return void 0;
+		this.verifyInlineAndExplicitColumnsSupport(def);
 		return this.ctx.createPFrame(def.map((c) => transformPColumnData(c)));
 	}
 	createPTable(def) {
@@ -405,9 +405,16 @@ var RenderCtxBase = class {
 	}
 	createPTableV2(def) {
 		const columns = (0, _milaboratories_pl_model_common.collectSpecQueryColumns)(def.query);
-		this.verifyInlineAndExplicitColumnsSupport(columns);
 		if (!require_pcolumn_data.allPColumnsReady(columns)) return void 0;
-		return this.ctx.createPTableV2((0, _milaboratories_pl_model_common.mapPTableDefV2)(def, (po) => transformPColumnData(po)));
+		this.verifyInlineAndExplicitColumnsSupport(columns);
+		return this.ctx.createPTableV2((0, _milaboratories_pl_model_common.mapPTableDefV2)(def, (po) => {
+			if (po.data === void 0) 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 */
 	getBlockLabel(blockId) {