@platforma-sdk/model 1.68.5 → 1.68.7

package/dist/labels/derive_distinct_labels.cjs

@@ -6,64 +6,84 @@ let es_toolkit = require("es-toolkit");
 const DISTANCE_PENALTY = .001;
 const LABEL_TYPE = "__LABEL__";
 const LABEL_TYPE_FULL = "__LABEL__@1";
+const LINKER_TYPE = "__LINKER__";
+const LINKER_TYPE_FULL = "__LINKER__@1";
+const HIT_QUAL_TYPE = "__HIT_QUAL__";
+const ANCHOR_QUAL_TYPE_PREFIX = "__ANCHOR_QUAL__:";
+function isAnchorQualType(t) {
+	return t.startsWith(ANCHOR_QUAL_TYPE_PREFIX);
+}
+function isSyntheticType(t) {
+	return t === LINKER_TYPE || t === HIT_QUAL_TYPE || isAnchorQualType(t);
+}
 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 records = values.map((v, i) => enrichRecord(v, i, options));
 	const stats = collectTypeStats(records);
+	const hasAnySynthetic = records.some((r) => r.fullTrace.some((ft) => isSyntheticType(ft.type)));
+	const labelForced = (options.includeNativeLabel === true || hasAnySynthetic) && stats.countByType.has(LABEL_TYPE_FULL);
+	const linkerForced = stats.countByType.get(LINKER_TYPE_FULL) === values.length;
+	const forcedSet = /* @__PURE__ */ new Set();
+	if (labelForced) forcedSet.add(LABEL_TYPE_FULL);
+	if (linkerForced) forcedSet.add(LINKER_TYPE_FULL);
 	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 applyLinkerSuffixes(build(new Set(LABEL_TYPE_FULL), true) ?? (0, _milaboratories_helpers.throwError)("Failed to derive labels using native column labels"), linkerSuffixes);
+		return build(new Set([LABEL_TYPE_FULL]), true) ?? (0, _milaboratories_helpers.throwError)("Failed to derive labels using native column labels");
 	}
 	let includedCount = 0;
 	let additionalType = -1;
 	while (includedCount < mainTypes.length) {
-		const currentSet = /* @__PURE__ */ new Set();
-		if (options.includeNativeLabel) currentSet.add(LABEL_TYPE_FULL);
+		const currentSet = new Set(forcedSet);
 		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 applyLinkerSuffixes(build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, options, separator), false) ?? (0, _milaboratories_helpers.throwError)("Failed to derive unique labels"), linkerSuffixes);
+		if (candidateResult !== void 0 && countUniqueLabels(candidateResult) === values.length) return build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, forcedSet, separator), false) ?? (0, _milaboratories_helpers.throwError)("Failed to derive unique labels");
 		additionalType++;
 		if (additionalType >= mainTypes.length) {
 			includedCount++;
 			additionalType = includedCount;
 		}
 	}
-	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;
+	return build(minimizeTypeSet(new Set([
+		...forcedSet,
+		...mainTypes,
+		...secondaryTypes
+	]), records, stats, forceTraceElements, forcedSet, separator), true) ?? (0, _milaboratories_helpers.throwError)("Failed to derive unique labels");
 }
-function extractSpecAndTrace(entry) {
-	const isEnriched = "spec" in entry && typeof entry.spec === "object";
+function extractEntryParts(entry) {
+	if (!("spec" in entry && typeof entry.spec === "object")) return {
+		spec: entry,
+		extraTrace: void 0,
+		linkerPath: void 0,
+		qualifications: void 0
+	};
 	return {
-		spec: isEnriched ? entry.spec : entry,
-		extraTrace: isEnriched ? entry.extraTrace : void 0,
-		linkerPath: isEnriched ? entry.linkerPath : void 0
+		spec: entry.spec,
+		extraTrace: entry.extraTrace,
+		linkerPath: entry.linkerPath,
+		qualifications: entry.qualifications
 	};
 }
+function formatQualification(q) {
+	const ctx = q.contextDomain ?? {};
+	const keys = Object.keys(ctx);
+	if (keys.length === 0) return q.axis.name;
+	const pairs = keys.map((k) => `${k}=${ctx[k]}`).join(", ");
+	return Object.prototype.hasOwnProperty.call(ctx, q.axis.name) ? pairs : `${q.axis.name} ${pairs}`;
+}
+function formatQualifications(qs) {
+	return qs.map(formatQualification).join("; ");
+}
+function computeStepLabel(step, stepIndex, formatters) {
+	const base = ((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 ((0, es_toolkit.isNil)(base) || base.length === 0) return void 0;
+	if (step.qualifications === void 0 || step.qualifications.length === 0) return base;
+	const qualText = (0, es_toolkit.isFunction)(formatters?.linkerStepQualification) ? formatters.linkerStepQualification(step.qualifications, stepIndex, step.spec) : `[${formatQualifications(step.qualifications)}]`;
+	return (0, es_toolkit.isNil)(qualText) ? base : `${base} ${qualText}`;
+}
 function buildFullTrace(trace) {
 	const result = [];
 	const occurrences = /* @__PURE__ */ new Map();
@@ -80,9 +100,10 @@ function buildFullTrace(trace) {
 	result.reverse();
 	return result;
 }
-function enrichRecord(value, options) {
-	const { spec, extraTrace } = extractSpecAndTrace(value);
-	const label = (0, _milaboratories_pl_model_common.readAnnotation)(spec, _milaboratories_pl_model_common.Annotation.Label);
+function enrichRecord(value, index, options) {
+	const { spec, extraTrace, linkerPath, qualifications } = extractEntryParts(value);
+	const formatters = options.formatters;
+	const rawLabel = (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") ?? [];
@@ -92,14 +113,48 @@ function enrichRecord(value, options) {
 		...baseTrace,
 		...suffixExtra
 	];
-	if (label !== void 0) {
-		const labelEntry = {
-			label,
-			type: LABEL_TYPE,
-			importance: -2
-		};
-		if (options.addLabelAsSuffix) trace.push(labelEntry);
-		else trace.splice(0, 0, labelEntry);
+	if (!(0, es_toolkit.isNil)(rawLabel)) {
+		const label = (0, es_toolkit.isFunction)(formatters?.native) ? formatters.native(rawLabel, spec, index) : rawLabel;
+		if (!(0, es_toolkit.isNil)(label)) {
+			const labelEntry = {
+				label,
+				type: LABEL_TYPE,
+				importance: -2
+			};
+			if (options.addLabelAsSuffix === true) trace.push(labelEntry);
+			else trace.splice(0, 0, labelEntry);
+		}
+	}
+	if (linkerPath !== void 0 && linkerPath.length > 0) {
+		const stepLabels = linkerPath.map((step, i) => computeStepLabel(step, i, formatters)).filter((s) => !(0, es_toolkit.isNil)(s));
+		if (stepLabels.length > 0) {
+			const linkerText = (0, es_toolkit.isFunction)(formatters?.linker) ? formatters.linker(stepLabels, spec, index) : `via ${stepLabels.join(" > ")}`;
+			if (!(0, es_toolkit.isNil)(linkerText)) trace.push({
+				type: LINKER_TYPE,
+				label: linkerText,
+				importance: -10
+			});
+		}
+	}
+	if (qualifications !== void 0) {
+		for (const [anchorId, qs] of Object.entries(qualifications.forQueries)) {
+			if (qs.length === 0) continue;
+			const anchorText = (0, es_toolkit.isFunction)(formatters?.anchorQualification) ? formatters.anchorQualification(anchorId, qs, spec, index) : `[${anchorId}: ${formatQualifications(qs)}]`;
+			if ((0, es_toolkit.isNil)(anchorText)) continue;
+			trace.push({
+				type: `${ANCHOR_QUAL_TYPE_PREFIX}${anchorId}`,
+				label: anchorText,
+				importance: -11
+			});
+		}
+		if (qualifications.forHit.length > 0) {
+			const hitText = (0, es_toolkit.isFunction)(formatters?.hitQualification) ? formatters.hitQualification(qualifications.forHit, spec, index) : `[${formatQualifications(qualifications.forHit)}]`;
+			if (!(0, es_toolkit.isNil)(hitText)) trace.push({
+				type: HIT_QUAL_TYPE,
+				label: hitText,
+				importance: -12
+			});
+		}
 	}
 	return { fullTrace: buildFullTrace(trace) };
 }
@@ -132,14 +187,30 @@ function classifyTypes(stats, totalRecords) {
 function buildLabels(records, includedTypes, forceTraceElements, separator, force) {
 	const result = [];
 	for (const r of records) {
-		const parts = [];
-		for (const ft of r.fullTrace) if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) parts.push(ft.label);
-		if (parts.length === 0) {
+		const traceParts = [];
+		const anchorParts = [];
+		let linkerLabel;
+		let hitLabel;
+		for (const ft of r.fullTrace) {
+			if (!(includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type))) continue;
+			if (ft.type === LINKER_TYPE) linkerLabel = ft.label;
+			else if (ft.type === HIT_QUAL_TYPE) hitLabel = ft.label;
+			else if (isAnchorQualType(ft.type)) anchorParts.push(ft.label);
+			else traceParts.push(ft.label);
+		}
+		if (traceParts.length === 0 && anchorParts.length === 0 && linkerLabel === void 0 && hitLabel === void 0) {
 			if (!force) return void 0;
 			result.push("Unlabeled");
 			continue;
 		}
-		result.push(parts.join(separator));
+		let label = traceParts.join(separator);
+		const append = (part) => {
+			label = label.length === 0 ? part : `${label} ${part}`;
+		};
+		if (linkerLabel !== void 0) append(linkerLabel);
+		for (const a of anchorParts) append(a);
+		if (hitLabel !== void 0) append(hitLabel);
+		result.push(label);
 	}
 	return result;
 }
@@ -147,12 +218,12 @@ function countUniqueLabels(result) {
 	if (result === void 0) return 0;
 	return new Set(result).size;
 }
-function minimizeTypeSet(typeSet, records, stats, forceTraceElements, options, separator) {
+function minimizeTypeSet(typeSet, records, stats, forceTraceElements, forcedSet, separator) {
 	const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);
 	if (initialResult === void 0) return typeSet;
 	const targetCardinality = countUniqueLabels(initialResult);
 	const result = new Set(typeSet);
-	const removable = [...result].filter((t) => !forceTraceElements?.has(t.split("@")[0]) && !(options.includeNativeLabel && t === LABEL_TYPE_FULL)).sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));
+	const removable = [...result].filter((t) => !forceTraceElements?.has(t.split("@")[0]) && !forcedSet.has(t)).sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));
 	for (const typeToRemove of removable) {
 		const candidate = new Set(result);
 		candidate.delete(typeToRemove);

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 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":";;;;;AAaA,MAAM,mBAAmB;AACzB,MAAM,aAAa;AACnB,MAAM,kBAAkB;AAqCxB,SAAgB,qBAAqB,QAAiB,UAA+B,EAAE,EAAY;CACjG,MAAM,qBACJ,QAAQ,uBAAuB,KAAA,KAAa,QAAQ,mBAAmB,SAAS,IAC5E,IAAI,IAAI,QAAQ,mBAAmB,GACnC,KAAA;CACN,MAAM,YAAY,QAAQ,aAAa;CAGvC,MAAM,iBAAiB,OAAO,KAAK,GAAG,MAAM;EAC1C,MAAM,OAAO,UAAU,KAAK,OAAO,EAAE,SAAS,WAAW,EAAE,OAAQ;EACnE,MAAM,eAAe,oBAAoB,EAAE;AAC3C,MAAI,aAAa,WAAW,EAAG,QAAO,KAAA;AACtC,UAAA,GAAA,WAAA,YAAkB,QAAQ,qBAAqB,GAC3C,QAAQ,qBAAqB,cAAc,MAAM,EAAE,GACnD,OAAO,aAAa,KAAK,MAAM;GACnC;CAGF,MAAM,UAAU,OAAO,KAAK,MAAM,aAAa,GAAG,QAAQ,CAAC;CAG3D,MAAM,QAAQ,iBAAiB,QAAQ;CAGvC,MAAM,EAAE,WAAW,mBAAmB,cAAc,OAAO,OAAO,OAAO;CAEzE,MAAM,SAAS,SAAsB,UACnC,YAAY,SAAS,SAAS,oBAAoB,WAAW,MAAM;AAErE,KAAI,UAAU,WAAW,GAAG;AAC1B,MAAI,eAAe,WAAW,EAC5B,OAAM,IAAI,MAAM,iEAAiE;AAEnF,SAAO,oBACL,MAAM,IAAI,IAAI,gBAAgB,EAAE,KAAK,KAAA,GAAA,wBAAA,YACxB,qDAAqD,EAClE,eACD;;CAaH,IAAI,gBAAgB;CACpB,IAAI,iBAAiB;AACrB,QAAO,gBAAgB,UAAU,QAAQ;EACvC,MAAM,6BAAa,IAAI,KAAa;AACpC,MAAI,QAAQ,mBAAoB,YAAW,IAAI,gBAAgB;AAC/D,OAAK,IAAI,IAAI,GAAG,IAAI,eAAe,EAAE,EAAG,YAAW,IAAI,UAAU,GAAG;AACpE,MAAI,kBAAkB,EAAG,YAAW,IAAI,UAAU,gBAAgB;EAElE,MAAM,kBAAkB,MAAM,YAAY,MAAM;AAChD,MAAI,oBAAoB,KAAA,KAAa,kBAAkB,gBAAgB,KAAK,OAAO,OASjF,QAAO,oBACL,MATgB,gBAChB,YACA,SACA,OACA,oBACA,SACA,UACD,EAEkB,MAAM,KAAA,GAAA,wBAAA,YAAe,iCAAiC,EACvE,eACD;AAGH;AACA,MAAI,kBAAkB,UAAU,QAAQ;AACtC;AACA,oBAAiB;;;AAcrB,QAAO,oBACL,MATgB,gBADE,IAAI,IAAI,CAAC,GAAG,WAAW,GAAG,eAAe,CAAC,EAG5D,SACA,OACA,oBACA,SACA,UACD,EAEkB,KAAK,KAAA,GAAA,wBAAA,YAAe,iCAAiC,EACtE,eACD;;;AAIH,SAAS,oBAAoB,QAAkB,UAA4C;AACzF,QAAO,OAAO,KAAK,OAAO,OAAA,GAAA,WAAA,OAAa,SAAS,GAAG,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,KAAM;;;AAI3F,SAAS,oBAAoB,OAAwB;AACnD,KAAI,EAAE,UAAU,UAAU,OAAO,MAAM,SAAS,SAAU,QAAO,EAAE;CACnE,MAAM,OAAO,MAAM;AACnB,KAAI,SAAS,KAAA,KAAa,KAAK,WAAW,EAAG,QAAO,EAAE;CACtD,MAAM,SAAmB,EAAE;AAC3B,MAAK,MAAM,QAAQ,MAAM;EACvB,MAAM,UAAA,GAAA,gCAAA,gBACW,KAAK,MAAMA,gCAAAA,WAAW,UAAU,KAAA,GAAA,gCAAA,gBAAmB,KAAK,MAAMA,gCAAAA,WAAW,MAAM,GAC7F,MAAM;AACT,MAAI,UAAU,KAAA,KAAa,MAAM,SAAS,EACxC,QAAO,KAAK,MAAM;;AAGtB,QAAO;;AAUT,SAAS,oBAAoB,OAI3B;CACA,MAAM,aAAa,UAAU,SAAS,OAAO,MAAM,SAAS;AAC5D,QAAO;EACL,MAAM,aAAa,MAAM,OAAQ;EACjC,YAAY,aAAa,MAAM,aAAa,KAAA;EAC5C,YAAY,aAAa,MAAM,aAAa,KAAA;EAC7C;;AAGH,SAAS,eAAe,OAA+C;CACrE,MAAM,SAA2B,EAAE;CACnC,MAAM,8BAAc,IAAI,KAAqB;AAE7C,MAAK,IAAI,IAAI,MAAM,SAAS,GAAG,KAAK,GAAG,EAAE,GAAG;EAC1C,MAAM,QAAQ,MAAM;EACpB,MAAM,mBAAmB,YAAY,IAAI,MAAM,KAAK,IAAI,KAAK;AAC7D,cAAY,IAAI,MAAM,MAAM,gBAAgB;AAC5C,SAAO,KAAK;GACV,GAAG;GACH,UAAU,GAAG,MAAM,KAAK,GAAG;GAC3B;GACD,CAAC;;AAGJ,QAAO,SAAS;AAChB,QAAO;;AAGT,SAAS,aAAa,OAAc,SAA8C;CAChF,MAAM,EAAE,MAAM,eAAe,oBAAoB,MAAM;CAEvD,MAAM,SAAA,GAAA,gCAAA,gBAAuB,MAAMA,gCAAAA,WAAW,MAAM;CACpD,MAAM,YAAA,GAAA,gCAAA,gBAA0B,MAAMA,gCAAAA,WAAW,MAAM;CACvD,MAAM,YAAY,YAAA,GAAA,gCAAA,WACH,SAAkD,IAAI,EAAE,GACnE,EAAE;CACN,MAAM,cAAc,YAAY,QAAQ,MAAM,EAAE,aAAa,SAAS,IAAI,EAAE;CAC5E,MAAM,cAAc,YAAY,QAAQ,MAAM,EAAE,aAAa,SAAS,IAAI,EAAE;CAC5E,MAAM,QAAQ;EAAC,GAAG;EAAa,GAAG;EAAW,GAAG;EAAY;AAE5D,KAAI,UAAU,KAAA,GAAW;EACvB,MAAM,aAAa;GAAE;GAAO,MAAM;GAAY,YAAY;GAAI;AAC9D,MAAI,QAAQ,iBAAkB,OAAM,KAAK,WAAW;MAC/C,OAAM,OAAO,GAAG,GAAG,WAAW;;AAGrC,QAAO,EAAE,WAAW,eAAe,MAAM,EAAE;;AAQ7C,SAAS,iBAAiB,SAAsC;CAC9D,MAAM,8BAAc,IAAI,KAAqB;CAC7C,MAAM,8BAAc,IAAI,KAAqB;AAE7C,MAAK,MAAM,UAAU,QACnB,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,UAAU,QAAQ,KAAK;EAChD,MAAM,EAAE,UAAU,YAAY,kBAAkB,OAAO,UAAU;EACjE,MAAM,aAAa,iBAAiB;EACpC,MAAM,YAAY,OAAO,UAAU,SAAS,KAAK;AAEjD,cAAY,IAAI,WAAW,YAAY,IAAI,SAAS,IAAI,KAAK,EAAE;AAC/D,cAAY,IACV,UACA,KAAK,IAAI,YAAY,IAAI,SAAS,IAAI,OAAO,mBAAmB,aAAa,SAAS,CACvF;;AAIL,QAAO;EAAE;EAAa;EAAa;;AAGrC,SAAS,cACP,OACA,cACmD;CACnD,MAAM,SAAS,CAAC,GAAG,MAAM,YAAY,CAAC,MAAM,GAAG,KAAK,GAAG,QAAQ,KAAK,GAAG;CAEvE,MAAM,YAAsB,EAAE;CAC9B,MAAM,iBAA2B,EAAE;AAEnC,MAAK,MAAM,CAAC,aAAa,OACvB,KAAI,SAAS,SAAS,KAAK,IAAI,MAAM,YAAY,IAAI,SAAS,KAAK,aACjE,WAAU,KAAK,SAAS;KACrB,gBAAe,KAAK,SAAS;AAGpC,QAAO;EAAE;EAAW;EAAgB;;AAGtC,SAAS,YACP,SACA,eACA,oBACA,WACA,OACsB;CACtB,MAAM,SAAmB,EAAE;AAE3B,MAAK,MAAM,KAAK,SAAS;EACvB,MAAM,QAAkB,EAAE;AAC1B,OAAK,MAAM,MAAM,EAAE,UACjB,KAAI,cAAc,IAAI,GAAG,SAAS,IAAI,oBAAoB,IAAI,GAAG,KAAK,CACpE,OAAM,KAAK,GAAG,MAAM;AAIxB,MAAI,MAAM,WAAW,GAAG;AACtB,OAAI,CAAC,MAAO,QAAO,KAAA;AACnB,UAAO,KAAK,YAAY;AACxB;;AAGF,SAAO,KAAK,MAAM,KAAK,UAAU,CAAC;;AAGpC,QAAO;;AAGT,SAAS,kBAAkB,QAAsC;AAC/D,KAAI,WAAW,KAAA,EAAW,QAAO;AACjC,QAAO,IAAI,IAAI,OAAO,CAAC;;AAGzB,SAAS,gBACP,SACA,SACA,OACA,oBACA,SACA,WACa;CACb,MAAM,gBAAgB,YAAY,SAAS,SAAS,oBAAoB,WAAW,MAAM;AACzF,KAAI,kBAAkB,KAAA,EAAW,QAAO;CAExC,MAAM,oBAAoB,kBAAkB,cAAc;CAC1D,MAAM,SAAS,IAAI,IAAI,QAAQ;CAE/B,MAAM,YAAY,CAAC,GAAG,OAAO,CAC1B,QACE,MACC,CAAC,oBAAoB,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,IACzC,EAAE,QAAQ,sBAAsB,MAAM,iBACzC,CACA,MAAM,GAAG,OAAO,MAAM,YAAY,IAAI,EAAE,IAAI,MAAM,MAAM,YAAY,IAAI,EAAE,IAAI,GAAG;AAEpF,MAAK,MAAM,gBAAgB,WAAW;EACpC,MAAM,YAAY,IAAI,IAAI,OAAO;AACjC,YAAU,OAAO,aAAa;EAC9B,MAAM,kBAAkB,YAAY,SAAS,WAAW,oBAAoB,WAAW,MAAM;AAC7F,MAAI,oBAAoB,KAAA,KAAa,kBAAkB,gBAAgB,IAAI,kBACzE,QAAO,OAAO,aAAa;;AAI/B,QAAO"}
+{"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 AxisQualification,\n  type PObjectId,\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\";\nimport type { MatchQualifications } from \"../columns/column_collection_builder\";\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\";\nconst LINKER_TYPE = \"__LINKER__\";\nconst LINKER_TYPE_FULL = \"__LINKER__@1\";\nconst HIT_QUAL_TYPE = \"__HIT_QUAL__\";\nconst ANCHOR_QUAL_TYPE_PREFIX = \"__ANCHOR_QUAL__:\";\n\nfunction isAnchorQualType(t: string): boolean {\n  return t.startsWith(ANCHOR_QUAL_TYPE_PREFIX);\n}\n\nfunction isSyntheticType(t: string): boolean {\n  return t === LINKER_TYPE || t === HIT_QUAL_TYPE || isAnchorQualType(t);\n}\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 LinkerStep = {\n  spec: PObjectSpec;\n  qualifications?: AxisQualification[];\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; rendered as \"via …\" only when needed for uniqueness. */\n      linkerPath?: LinkerStep[];\n      /** Axis qualifications applied to the hit column / already-bound anchors; rendered as \"[…]\" suffixes. */\n      qualifications?: MatchQualifications;\n    };\n\n/**\n * Per-zone formatters. Each one receives raw inputs and returns the rendered text for that zone,\n * or `undefined` to suppress the zone entirely (no synthetic injection → no minimization, no render).\n */\nexport type DeriveLabelsFormatters = {\n  /** Native column label. Default: identity. `undefined` → label entry not added (treated as if spec had no label). */\n  native?: (label: string, spec: PObjectSpec, index: number) => string | undefined;\n  /** Linker zone (whole \"via …\" piece). Receives step labels with step-quals already inlined.\n   *  Default: `via ${steps.join(\" > \")}`. */\n  linker?: (linkerLabels: string[], spec: PObjectSpec, index: number) => string | undefined;\n  /** Per-step linker qualifications inlined into the step base label.\n   *  Default: `[${formatQualifications(qs)}]`. `undefined` → step rendered without quals. */\n  linkerStepQualification?: (\n    qualifications: AxisQualification[],\n    stepIndex: number,\n    stepSpec: PObjectSpec,\n  ) => string | undefined;\n  /** Hit-axis qualifications block. Default: `[${formatQualifications(qs)}]`. */\n  hitQualification?: (\n    qualifications: AxisQualification[],\n    spec: PObjectSpec,\n    index: number,\n  ) => string | undefined;\n  /** Per-anchor qualifications block. Default: `[${anchorId}: ${formatQualifications(qs)}]`. */\n  anchorQualification?: (\n    anchorId: PObjectId,\n    qualifications: AxisQualification[],\n    spec: PObjectSpec,\n    index: number,\n  ) => string | undefined;\n};\n\nexport type DeriveLabelsOptions = {\n  /** Separator to use between label parts (\" / \" by default). */\n  separator?: string;\n  /** If true, native label is appended at the end of the trace zone. By default it is prepended (label is the most important name). */\n  addLabelAsSuffix?: boolean;\n  /** Force inclusion of native column label even when not needed for uniqueness. */\n  includeNativeLabel?: boolean;\n  /** Trace types that must be included in the label. */\n  forceTraceElements?: string[];\n  /** Per-zone custom formatters. Returning `undefined` from any formatter suppresses the corresponding zone. */\n  formatters?: DeriveLabelsFormatters;\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  const records = values.map((v, i) => enrichRecord(v, i, options));\n  const stats = collectTypeStats(records);\n\n  const hasAnySynthetic = records.some((r) => r.fullTrace.some((ft) => isSyntheticType(ft.type)));\n  const labelForced =\n    (options.includeNativeLabel === true || hasAnySynthetic) &&\n    stats.countByType.has(LABEL_TYPE_FULL);\n  // Tied to labeled-step presence, not path presence: entries with a non-empty linkerPath\n  // but no labeled steps contribute no LINKER_TYPE trace entry, so they do not count here.\n  const linkerForced = stats.countByType.get(LINKER_TYPE_FULL) === values.length;\n\n  const forcedSet = new Set<string>();\n  if (labelForced) forcedSet.add(LABEL_TYPE_FULL);\n  if (linkerForced) forcedSet.add(LINKER_TYPE_FULL);\n\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 (\n      build(new Set([LABEL_TYPE_FULL]), true) ??\n      throwError(\"Failed to derive labels using native column labels\")\n    );\n  }\n\n  let includedCount = 0;\n  let additionalType = -1;\n  while (includedCount < mainTypes.length) {\n    const currentSet = new Set<string>(forcedSet);\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        forcedSet,\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  const fallbackSet = new Set([...forcedSet, ...mainTypes, ...secondaryTypes]);\n  const minimized = minimizeTypeSet(\n    fallbackSet,\n    records,\n    stats,\n    forceTraceElements,\n    forcedSet,\n    separator,\n  );\n  return build(minimized, true) ?? throwError(\"Failed to derive unique labels\");\n}\n\n// --- Pure helpers ---\ntype FullTraceEntry = ExtendedTraceEntry & { fullType: string; occurrenceIndex: number };\n\ntype EnrichedRecord = {\n  fullTrace: FullTraceEntry[];\n};\n\nfunction extractEntryParts(entry: Entry): {\n  spec: PObjectSpec;\n  extraTrace: ExtendedTraceEntry[] | undefined;\n  linkerPath: LinkerStep[] | undefined;\n  qualifications: MatchQualifications | undefined;\n} {\n  const isEnriched = \"spec\" in entry && typeof entry.spec === \"object\";\n  if (!isEnriched) {\n    return {\n      spec: entry as PObjectSpec,\n      extraTrace: undefined,\n      linkerPath: undefined,\n      qualifications: undefined,\n    };\n  }\n  return {\n    spec: entry.spec,\n    extraTrace: entry.extraTrace,\n    linkerPath: entry.linkerPath,\n    qualifications: entry.qualifications,\n  };\n}\n\nfunction formatQualification(q: AxisQualification): string {\n  const ctx = q.contextDomain ?? {};\n  const keys = Object.keys(ctx);\n  if (keys.length === 0) return q.axis.name;\n  const pairs = keys.map((k) => `${k}=${ctx[k]}`).join(\", \");\n  return Object.prototype.hasOwnProperty.call(ctx, q.axis.name) ? pairs : `${q.axis.name} ${pairs}`;\n}\n\nfunction formatQualifications(qs: AxisQualification[]): string {\n  return qs.map(formatQualification).join(\"; \");\n}\n\nfunction computeStepLabel(\n  step: LinkerStep,\n  stepIndex: number,\n  formatters: DeriveLabelsFormatters | undefined,\n): string | undefined {\n  const base = (\n    readAnnotation(step.spec, Annotation.LinkLabel) ?? readAnnotation(step.spec, Annotation.Label)\n  )?.trim();\n  if (isNil(base) || base.length === 0) return undefined;\n  if (step.qualifications === undefined || step.qualifications.length === 0) return base;\n  const qualText = isFunction(formatters?.linkerStepQualification)\n    ? formatters.linkerStepQualification(step.qualifications, stepIndex, step.spec)\n    : `[${formatQualifications(step.qualifications)}]`;\n  return isNil(qualText) ? base : `${base} ${qualText}`;\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, index: number, options: DeriveLabelsOptions): EnrichedRecord {\n  const { spec, extraTrace, linkerPath, qualifications } = extractEntryParts(value);\n  const formatters = options.formatters;\n\n  const rawLabel = 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: ExtendedTraceEntry[] = [...prefixExtra, ...baseTrace, ...suffixExtra];\n\n  if (!isNil(rawLabel)) {\n    const label = isFunction(formatters?.native)\n      ? formatters.native(rawLabel, spec, index)\n      : rawLabel;\n    if (!isNil(label)) {\n      const labelEntry = { label, type: LABEL_TYPE, importance: -2 };\n      if (options.addLabelAsSuffix === true) trace.push(labelEntry);\n      else trace.splice(0, 0, labelEntry);\n    }\n  }\n\n  if (linkerPath !== undefined && linkerPath.length > 0) {\n    const stepLabels = linkerPath\n      .map((step, i) => computeStepLabel(step, i, formatters))\n      .filter((s): s is string => !isNil(s));\n    if (stepLabels.length > 0) {\n      const linkerText = isFunction(formatters?.linker)\n        ? formatters.linker(stepLabels, spec, index)\n        : `via ${stepLabels.join(\" > \")}`;\n      if (!isNil(linkerText)) {\n        trace.push({ type: LINKER_TYPE, label: linkerText, importance: -10 });\n      }\n    }\n  }\n\n  if (qualifications !== undefined) {\n    for (const [anchorId, qs] of Object.entries(qualifications.forQueries)) {\n      if (qs.length === 0) continue;\n      const anchorText = isFunction(formatters?.anchorQualification)\n        ? formatters.anchorQualification(anchorId as PObjectId, qs, spec, index)\n        : `[${anchorId}: ${formatQualifications(qs)}]`;\n      if (isNil(anchorText)) continue;\n      trace.push({\n        type: `${ANCHOR_QUAL_TYPE_PREFIX}${anchorId}`,\n        label: anchorText,\n        importance: -11,\n      });\n    }\n    if (qualifications.forHit.length > 0) {\n      const hitText = isFunction(formatters?.hitQualification)\n        ? formatters.hitQualification(qualifications.forHit, spec, index)\n        : `[${formatQualifications(qualifications.forHit)}]`;\n      if (!isNil(hitText)) {\n        trace.push({ type: HIT_QUAL_TYPE, label: hitText, importance: -12 });\n      }\n    }\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 traceParts: string[] = [];\n    const anchorParts: string[] = [];\n    let linkerLabel: string | undefined;\n    let hitLabel: string | undefined;\n\n    for (const ft of r.fullTrace) {\n      if (!(includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type))) continue;\n      if (ft.type === LINKER_TYPE) linkerLabel = ft.label;\n      else if (ft.type === HIT_QUAL_TYPE) hitLabel = ft.label;\n      else if (isAnchorQualType(ft.type)) anchorParts.push(ft.label);\n      else traceParts.push(ft.label);\n    }\n\n    const isEmpty =\n      traceParts.length === 0 &&\n      anchorParts.length === 0 &&\n      linkerLabel === undefined &&\n      hitLabel === undefined;\n\n    if (isEmpty) {\n      if (!force) return undefined;\n      result.push(\"Unlabeled\");\n      continue;\n    }\n\n    let label = traceParts.join(separator);\n    const append = (part: string) => {\n      label = label.length === 0 ? part : `${label} ${part}`;\n    };\n    if (linkerLabel !== undefined) append(linkerLabel);\n    for (const a of anchorParts) append(a);\n    if (hitLabel !== undefined) append(hitLabel);\n\n    result.push(label);\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  forcedSet: Set<string>,\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((t) => !forceTraceElements?.has(t.split(\"@\")[0]) && !forcedSet.has(t))\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,4 +1,5 @@
-import { PObjectSpec, Trace, Trace as Trace$1, TraceEntry } from "@milaboratories/pl-model-common";
+import { MatchQualifications } from "../columns/column_collection_builder.js";
+import { AxisQualification, PObjectId, PObjectSpec, Trace, Trace as Trace$1, TraceEntry } from "@milaboratories/pl-model-common";
 
 //#region src/labels/derive_distinct_labels.d.ts
 /** SDK-internal trace shape — adds fields used by this algorithm only, not part of the on-disk contract. */
@@ -6,24 +7,39 @@ type ExtendedTraceEntry = Trace[number] & {
   importance?: number;
   position?: "prefix" | "suffix";
 };
+type LinkerStep = {
+  spec: PObjectSpec;
+  qualifications?: AxisQualification[];
+};
 type Entry = PObjectSpec | {
   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;
-  }[];
+  extraTrace?: ExtendedTraceEntry[]; /** Linker steps traversed to discover this column; rendered as "via …" only when needed for uniqueness. */
+  linkerPath?: LinkerStep[]; /** Axis qualifications applied to the hit column / already-bound anchors; rendered as "[…]" suffixes. */
+  qualifications?: MatchQualifications;
+};
+/**
+ * Per-zone formatters. Each one receives raw inputs and returns the rendered text for that zone,
+ * or `undefined` to suppress the zone entirely (no synthetic injection → no minimization, no render).
+ */
+type DeriveLabelsFormatters = {
+  /** Native column label. Default: identity. `undefined` → label entry not added (treated as if spec had no label). */native?: (label: string, spec: PObjectSpec, index: number) => string | undefined;
+  /** Linker zone (whole "via …" piece). Receives step labels with step-quals already inlined.
+   *  Default: `via ${steps.join(" > ")}`. */
+  linker?: (linkerLabels: string[], spec: PObjectSpec, index: number) => string | undefined;
+  /** Per-step linker qualifications inlined into the step base label.
+   *  Default: `[${formatQualifications(qs)}]`. `undefined` → step rendered without quals. */
+  linkerStepQualification?: (qualifications: AxisQualification[], stepIndex: number, stepSpec: PObjectSpec) => string | undefined; /** Hit-axis qualifications block. Default: `[${formatQualifications(qs)}]`. */
+  hitQualification?: (qualifications: AxisQualification[], spec: PObjectSpec, index: number) => string | undefined; /** Per-anchor qualifications block. Default: `[${anchorId}: ${formatQualifications(qs)}]`. */
+  anchorQualification?: (anchorId: PObjectId, qualifications: AxisQualification[], spec: PObjectSpec, index: number) => string | undefined;
 };
 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;
+  /** Separator to use between label parts (" / " by default). */separator?: string; /** If true, native label is appended at the end of the trace zone. By default it is prepended (label is the most important name). */
+  addLabelAsSuffix?: boolean; /** Force inclusion of native column label even when not needed for uniqueness. */
+  includeNativeLabel?: boolean; /** Trace types that must be included in the label. */
+  forceTraceElements?: string[]; /** Per-zone custom formatters. Returning `undefined` from any formatter suppresses the corresponding zone. */
+  formatters?: DeriveLabelsFormatters;
 };
 declare function deriveDistinctLabels(values: Entry[], options?: DeriveLabelsOptions): string[];
 //#endregion
-export { DeriveLabelsOptions, Entry, type Trace$1 as Trace, type TraceEntry, deriveDistinctLabels };
+export { DeriveLabelsFormatters, DeriveLabelsOptions, Entry, LinkerStep, 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":";;;;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"}
+{"version":3,"file":"derive_distinct_labels.d.ts","names":[],"sources":["../../src/labels/derive_distinct_labels.ts"],"mappings":";;;;;KAiCK,kBAAA,GAAqB,KAAA;EACxB,UAAA;EACA,QAAA;AAAA;AAAA,KAGU,UAAA;EACV,IAAA,EAAM,WAAA;EACN,cAAA,GAAiB,iBAAA;AAAA;AAAA,KAGP,KAAA,GACR,WAAA;EAEE,IAAA,EAAM,WAAA,EARU;EAUhB,UAAA,GAAa,kBAAA,IARiB;EAU9B,UAAA,GAAa,UAAA,IAXX;EAaF,cAAA,GAAiB,mBAAA;AAAA;;;AATvB;;KAgBY,sBAAA;EAfR,qHAiBF,MAAA,IAAU,KAAA,UAAe,IAAA,EAAM,WAAA,EAAa,KAAA;EAb3B;;EAgBjB,MAAA,IAAU,YAAA,YAAwB,IAAA,EAAM,WAAA,EAAa,KAAA;EAZb;;EAexC,uBAAA,IACE,cAAA,EAAgB,iBAAA,IAChB,SAAA,UACA,QAAA,EAAU,WAAA,yBAxBR;EA2BJ,gBAAA,IACE,cAAA,EAAgB,iBAAA,IAChB,IAAA,EAAM,WAAA,EACN,KAAA,iCA5BE;EA+BJ,mBAAA,IACE,QAAA,EAAU,SAAA,EACV,cAAA,EAAgB,iBAAA,IAChB,IAAA,EAAM,WAAA,EACN,KAAA;AAAA;AAAA,KAIQ,mBAAA;EAnCN,+DAqCJ,SAAA,WArCwC;EAuCxC,gBAAA,YAhCU;EAkCV,kBAAA;EAEA,kBAAA,aA/BwC;EAiCxC,UAAA,GAAa,sBAAA;AAAA;AAAA,iBAGC,oBAAA,CAAqB,MAAA,EAAQ,KAAA,IAAS,OAAA,GAAS,mBAAA"}

package/dist/labels/derive_distinct_labels.js

@@ -5,64 +5,84 @@ import { isFunction, isNil as isNil$1 } from "es-toolkit";
 const DISTANCE_PENALTY = .001;
 const LABEL_TYPE = "__LABEL__";
 const LABEL_TYPE_FULL = "__LABEL__@1";
+const LINKER_TYPE = "__LINKER__";
+const LINKER_TYPE_FULL = "__LINKER__@1";
+const HIT_QUAL_TYPE = "__HIT_QUAL__";
+const ANCHOR_QUAL_TYPE_PREFIX = "__ANCHOR_QUAL__:";
+function isAnchorQualType(t) {
+	return t.startsWith(ANCHOR_QUAL_TYPE_PREFIX);
+}
+function isSyntheticType(t) {
+	return t === LINKER_TYPE || t === HIT_QUAL_TYPE || isAnchorQualType(t);
+}
 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 records = values.map((v, i) => enrichRecord(v, i, options));
 	const stats = collectTypeStats(records);
+	const hasAnySynthetic = records.some((r) => r.fullTrace.some((ft) => isSyntheticType(ft.type)));
+	const labelForced = (options.includeNativeLabel === true || hasAnySynthetic) && stats.countByType.has(LABEL_TYPE_FULL);
+	const linkerForced = stats.countByType.get(LINKER_TYPE_FULL) === values.length;
+	const forcedSet = /* @__PURE__ */ new Set();
+	if (labelForced) forcedSet.add(LABEL_TYPE_FULL);
+	if (linkerForced) forcedSet.add(LINKER_TYPE_FULL);
 	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 applyLinkerSuffixes(build(new Set(LABEL_TYPE_FULL), true) ?? throwError("Failed to derive labels using native column labels"), linkerSuffixes);
+		return build(new Set([LABEL_TYPE_FULL]), true) ?? throwError("Failed to derive labels using native column labels");
 	}
 	let includedCount = 0;
 	let additionalType = -1;
 	while (includedCount < mainTypes.length) {
-		const currentSet = /* @__PURE__ */ new Set();
-		if (options.includeNativeLabel) currentSet.add(LABEL_TYPE_FULL);
+		const currentSet = new Set(forcedSet);
 		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 applyLinkerSuffixes(build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, options, separator), false) ?? throwError("Failed to derive unique labels"), linkerSuffixes);
+		if (candidateResult !== void 0 && countUniqueLabels(candidateResult) === values.length) return build(minimizeTypeSet(currentSet, records, stats, forceTraceElements, forcedSet, separator), false) ?? throwError("Failed to derive unique labels");
 		additionalType++;
 		if (additionalType >= mainTypes.length) {
 			includedCount++;
 			additionalType = includedCount;
 		}
 	}
-	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;
+	return build(minimizeTypeSet(new Set([
+		...forcedSet,
+		...mainTypes,
+		...secondaryTypes
+	]), records, stats, forceTraceElements, forcedSet, separator), true) ?? throwError("Failed to derive unique labels");
 }
-function extractSpecAndTrace(entry) {
-	const isEnriched = "spec" in entry && typeof entry.spec === "object";
+function extractEntryParts(entry) {
+	if (!("spec" in entry && typeof entry.spec === "object")) return {
+		spec: entry,
+		extraTrace: void 0,
+		linkerPath: void 0,
+		qualifications: void 0
+	};
 	return {
-		spec: isEnriched ? entry.spec : entry,
-		extraTrace: isEnriched ? entry.extraTrace : void 0,
-		linkerPath: isEnriched ? entry.linkerPath : void 0
+		spec: entry.spec,
+		extraTrace: entry.extraTrace,
+		linkerPath: entry.linkerPath,
+		qualifications: entry.qualifications
 	};
 }
+function formatQualification(q) {
+	const ctx = q.contextDomain ?? {};
+	const keys = Object.keys(ctx);
+	if (keys.length === 0) return q.axis.name;
+	const pairs = keys.map((k) => `${k}=${ctx[k]}`).join(", ");
+	return Object.prototype.hasOwnProperty.call(ctx, q.axis.name) ? pairs : `${q.axis.name} ${pairs}`;
+}
+function formatQualifications(qs) {
+	return qs.map(formatQualification).join("; ");
+}
+function computeStepLabel(step, stepIndex, formatters) {
+	const base = (readAnnotation(step.spec, Annotation.LinkLabel) ?? readAnnotation(step.spec, Annotation.Label))?.trim();
+	if (isNil$1(base) || base.length === 0) return void 0;
+	if (step.qualifications === void 0 || step.qualifications.length === 0) return base;
+	const qualText = isFunction(formatters?.linkerStepQualification) ? formatters.linkerStepQualification(step.qualifications, stepIndex, step.spec) : `[${formatQualifications(step.qualifications)}]`;
+	return isNil$1(qualText) ? base : `${base} ${qualText}`;
+}
 function buildFullTrace(trace) {
 	const result = [];
 	const occurrences = /* @__PURE__ */ new Map();
@@ -79,9 +99,10 @@ function buildFullTrace(trace) {
 	result.reverse();
 	return result;
 }
-function enrichRecord(value, options) {
-	const { spec, extraTrace } = extractSpecAndTrace(value);
-	const label = readAnnotation(spec, Annotation.Label);
+function enrichRecord(value, index, options) {
+	const { spec, extraTrace, linkerPath, qualifications } = extractEntryParts(value);
+	const formatters = options.formatters;
+	const rawLabel = readAnnotation(spec, Annotation.Label);
 	const traceStr = readAnnotation(spec, Annotation.Trace);
 	const baseTrace = traceStr ? parseJson(traceStr) ?? [] : [];
 	const prefixExtra = extraTrace?.filter((e) => e.position === "prefix") ?? [];
@@ -91,14 +112,48 @@ function enrichRecord(value, options) {
 		...baseTrace,
 		...suffixExtra
 	];
-	if (label !== void 0) {
-		const labelEntry = {
-			label,
-			type: LABEL_TYPE,
-			importance: -2
-		};
-		if (options.addLabelAsSuffix) trace.push(labelEntry);
-		else trace.splice(0, 0, labelEntry);
+	if (!isNil$1(rawLabel)) {
+		const label = isFunction(formatters?.native) ? formatters.native(rawLabel, spec, index) : rawLabel;
+		if (!isNil$1(label)) {
+			const labelEntry = {
+				label,
+				type: LABEL_TYPE,
+				importance: -2
+			};
+			if (options.addLabelAsSuffix === true) trace.push(labelEntry);
+			else trace.splice(0, 0, labelEntry);
+		}
+	}
+	if (linkerPath !== void 0 && linkerPath.length > 0) {
+		const stepLabels = linkerPath.map((step, i) => computeStepLabel(step, i, formatters)).filter((s) => !isNil$1(s));
+		if (stepLabels.length > 0) {
+			const linkerText = isFunction(formatters?.linker) ? formatters.linker(stepLabels, spec, index) : `via ${stepLabels.join(" > ")}`;
+			if (!isNil$1(linkerText)) trace.push({
+				type: LINKER_TYPE,
+				label: linkerText,
+				importance: -10
+			});
+		}
+	}
+	if (qualifications !== void 0) {
+		for (const [anchorId, qs] of Object.entries(qualifications.forQueries)) {
+			if (qs.length === 0) continue;
+			const anchorText = isFunction(formatters?.anchorQualification) ? formatters.anchorQualification(anchorId, qs, spec, index) : `[${anchorId}: ${formatQualifications(qs)}]`;
+			if (isNil$1(anchorText)) continue;
+			trace.push({
+				type: `${ANCHOR_QUAL_TYPE_PREFIX}${anchorId}`,
+				label: anchorText,
+				importance: -11
+			});
+		}
+		if (qualifications.forHit.length > 0) {
+			const hitText = isFunction(formatters?.hitQualification) ? formatters.hitQualification(qualifications.forHit, spec, index) : `[${formatQualifications(qualifications.forHit)}]`;
+			if (!isNil$1(hitText)) trace.push({
+				type: HIT_QUAL_TYPE,
+				label: hitText,
+				importance: -12
+			});
+		}
 	}
 	return { fullTrace: buildFullTrace(trace) };
 }
@@ -131,14 +186,30 @@ function classifyTypes(stats, totalRecords) {
 function buildLabels(records, includedTypes, forceTraceElements, separator, force) {
 	const result = [];
 	for (const r of records) {
-		const parts = [];
-		for (const ft of r.fullTrace) if (includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type)) parts.push(ft.label);
-		if (parts.length === 0) {
+		const traceParts = [];
+		const anchorParts = [];
+		let linkerLabel;
+		let hitLabel;
+		for (const ft of r.fullTrace) {
+			if (!(includedTypes.has(ft.fullType) || forceTraceElements?.has(ft.type))) continue;
+			if (ft.type === LINKER_TYPE) linkerLabel = ft.label;
+			else if (ft.type === HIT_QUAL_TYPE) hitLabel = ft.label;
+			else if (isAnchorQualType(ft.type)) anchorParts.push(ft.label);
+			else traceParts.push(ft.label);
+		}
+		if (traceParts.length === 0 && anchorParts.length === 0 && linkerLabel === void 0 && hitLabel === void 0) {
 			if (!force) return void 0;
 			result.push("Unlabeled");
 			continue;
 		}
-		result.push(parts.join(separator));
+		let label = traceParts.join(separator);
+		const append = (part) => {
+			label = label.length === 0 ? part : `${label} ${part}`;
+		};
+		if (linkerLabel !== void 0) append(linkerLabel);
+		for (const a of anchorParts) append(a);
+		if (hitLabel !== void 0) append(hitLabel);
+		result.push(label);
 	}
 	return result;
 }
@@ -146,12 +217,12 @@ function countUniqueLabels(result) {
 	if (result === void 0) return 0;
 	return new Set(result).size;
 }
-function minimizeTypeSet(typeSet, records, stats, forceTraceElements, options, separator) {
+function minimizeTypeSet(typeSet, records, stats, forceTraceElements, forcedSet, separator) {
 	const initialResult = buildLabels(records, typeSet, forceTraceElements, separator, false);
 	if (initialResult === void 0) return typeSet;
 	const targetCardinality = countUniqueLabels(initialResult);
 	const result = new Set(typeSet);
-	const removable = [...result].filter((t) => !forceTraceElements?.has(t.split("@")[0]) && !(options.includeNativeLabel && t === LABEL_TYPE_FULL)).sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));
+	const removable = [...result].filter((t) => !forceTraceElements?.has(t.split("@")[0]) && !forcedSet.has(t)).sort((a, b) => (stats.importances.get(a) ?? 0) - (stats.importances.get(b) ?? 0));
 	for (const typeToRemove of removable) {
 		const candidate = new Set(result);
 		candidate.delete(typeToRemove);