@platforma-sdk/model 1.63.12 → 1.65.0

package/dist/index.d.ts

@@ -24,7 +24,7 @@ import { CommonFieldTraverseOps, CommonTraversalOps, FieldTraversalStep, FieldTy
 import { PColumnDataUniversal, internal_d_exports } from "./render/internal.js";
 import { ExtractFutureRefType, FutureRef } from "./render/future.js";
 import { TreeNodeAccessor, ifDef } from "./render/accessor.js";
-import { DeriveLabelsOptions, Entry, Trace, WithLabel, deriveDistinctLabels } from "./labels/derive_distinct_labels.js";
+import { DeriveLabelsOptions, Entry, Trace, TraceEntry, deriveDistinctLabels } from "./labels/derive_distinct_labels.js";
 import { deriveLabels } from "./render/util/label.js";
 import { AxisLabelProvider, ColumnProvider, PColumnCollection, PColumnEntryUniversal, PColumnEntryWithLabel, PColumnLazyUniversal, PColumnLazyWithLabel } from "./render/util/column_collection.js";
 import { BlockRenderCtx, InferRenderFunctionReturn, PluginRenderCtx, RenderCtx, RenderCtxBase, RenderCtxLegacy, RenderFunction, RenderFunctionLegacy, ResultPool, UniversalColumnOption, UnwrapFutureRef } from "./render/api.js";
@@ -44,21 +44,23 @@ import { distillFilterSpec } from "./filters/distill.js";
 import { AnnotationSpec, AnnotationSpecUi, ExpressionSpec, FilterSpecUi } from "./annotations/types.js";
 import { convertFilterSpecsToExpressionSpecs } from "./annotations/converter.js";
 import { AnnotationScriptUi, AnnotationStepUi, AnyForm, FilterUi, FilterUiOfType, FilterUiType, FormField, TypeField, TypeFieldRecord, TypeForm, TypeToLiteral, compileAnnotationScript, compileFilter, compileFilters, unreachable } from "./components/PlAnnotations/filters_ui.js";
-import { PTableParamsV2, PlDataTableFilters, PlDataTableFiltersWithMeta, PlDataTableGridStateCore, PlDataTableModel, PlDataTableSheet, PlDataTableSheetState, PlDataTableStateV2CacheEntry, PlDataTableStateV2Normalized, PlTableColumnId, PlTableColumnIdJson } from "./components/PlDataTable/typesV5.js";
+import { PTableParamsV2, PlDataTableFilterMeta, PlDataTableFilterSpecLeaf, PlDataTableFilters, PlDataTableFiltersWithMeta, PlDataTableGridStateCore, PlDataTableModel, PlDataTableSheet, PlDataTableSheetState, PlDataTableStateV2CacheEntry, PlDataTableStateV2Normalized, PlTableColumnId, PlTableColumnIdJson } from "./components/PlDataTable/typesV5.js";
 import { PlDataTableStateV2, createDefaultPTableParams, createPlDataTableStateV2, upgradePlDataTableStateV2 } from "./components/PlDataTable/state-migration.js";
 import { createPlDataTableSheet } from "./components/PlDataTable/createPlDataTableSheet.js";
 import { createPlDataTableV2 } from "./components/PlDataTable/createPlDataTable/createPlDataTableV2.js";
 import { ColumnData, ColumnDataStatus, ColumnSnapshot, createColumnSnapshot, createReadyColumnData } from "./columns/column_snapshot.js";
 import { ArrayColumnProvider, ColumnSnapshotProvider, ColumnSource, OutputColumnProvider, OutputColumnProviderOpts, SnapshotColumnProvider, isColumnSnapshotProvider, toColumnSnapshotProvider } from "./columns/column_snapshot_provider.js";
-import { ColumnSelectorInput, RelaxedAxisSelector, RelaxedColumnSelector, RelaxedRecord, RelaxedStringMatchers, StringMatcher, columnSelectorsToPredicate, matchColumn, matchColumnSelectors, normalizeSelectors } from "./columns/column_selector.js";
-import { AnchoredBuildOptions, AnchoredColumnCollection, AnchoredFindColumnsOptions, BuildOptions, ColumnCollection, ColumnCollectionBuilder, ColumnMatch, FindColumnsOptions, MatchQualifications, MatchVariant, MatchingMode } from "./columns/column_collection_builder.js";
+import { ColumnSelector, RelaxedAxisSelector, RelaxedColumnSelector, RelaxedRecord, RelaxedStringMatchers, StringMatcher, convertColumnSelectorToMultiColumnSelector, convertRelaxedAxisSelectorToMultiAxisSelector, convertRelaxedColumnSelectorToMultiColumnSelector } from "./columns/column_selector.js";
+import { AnchorEntry, AnchoredBuildOptions, AnchoredColumnCollection, AnchoredFindColumnsOptions, BuildOptions, ColumnCollection, ColumnCollectionBuilder, ColumnMatch, FindColumnsOptions, MatchQualifications, MatchVariant, MatchingMode } from "./columns/column_collection_builder.js";
 import { ResultPoolColumnSnapshotProvider, collectCtxColumnSnapshotProviders } from "./columns/ctx_column_sources.js";
-import { createPlDataTableV3, isColumnHidden, isColumnOptional } from "./components/PlDataTable/createPlDataTable/createPlDataTableV3.js";
+import { ExpandByPartitionOpts, ExpandByPartitionResult, SplitAxis, expandByPartition } from "./columns/expand_by_partition.js";
+import { discoverTableColumnSnaphots } from "./components/PlDataTable/createPlDataTable/discoverColumns.js";
+import { ColumnMatcher, ColumnOrderRule, ColumnVisibilityRule, ColumnsDisplayOptions, ColumnsSelectorConfig, createPlDataTableOptionsV3, createPlDataTableV3 } from "./components/PlDataTable/createPlDataTable/createPlDataTableV3.js";
 import { createPlDataTable } from "./components/PlDataTable/createPlDataTable/index.js";
+import { getEffectiveVisibility, getOrderPriority, isColumnHidden, isColumnOptional } from "./components/PlDataTable/createPlDataTable/utils.js";
 import { PTableKey, PlSelectionModel, createPlSelectionModel } from "./components/PlSelectionModel.js";
 import { PColumnPredicate, PlMultiSequenceAlignmentColorSchemeOption, PlMultiSequenceAlignmentModel, PlMultiSequenceAlignmentSettings, PlMultiSequenceAlignmentWidget, createRowSelectionColumn } from "./components/PlMultiSequenceAlignment.js";
 import { PFrameImpl } from "./pframe.js";
-import { writeLabelsToSpecs } from "./labels/write_labels_to_specs.js";
 import { fromPlOption, fromPlRef } from "./ref_util.js";
 import { getPlatformaApiVersion, getRawPlatformaInstance } from "./raw_globals.js";
 import { getAllRelatedColumns, getRelatedColumns } from "./pframe_utils/columns.js";
@@ -67,4 +69,4 @@ import { NodeServiceProxy, buildServices, createNodeServiceProxy } from "./servi
 import { getEnvironmentValue } from "./env_value.js";
 export * from "@milaboratories/pl-model-common";
 export * from "@milaboratories/pl-error-like";
-export { ActAnd, ActExtractArchiveAndGetURL, ActFlatten, ActGetBlobContent, ActGetBlobContentAsJson, ActGetBlobContentAsString, ActGetDownloadedBlobContent, ActGetField, ActGetFromCtx, ActGetImmediate, ActGetLastLogs, ActGetLogHandle, ActGetOnDemandBlobContent, ActGetProgressLog, ActGetProgressLogWithInfo, ActGetResourceField, ActGetResourceValueAsJson, ActImportProgress, ActIsEmpty, ActIsolate, ActMakeArray, ActMakeObject, ActMapArrayValues, ActMapRecordValues, ActMapResourceFields, ActNot, ActOr, ActionResult, AnchoredBuildOptions, AnchoredColumnCollection, AnchoredFindColumnsOptions, AndFilter, AnnotationFilter, AnnotationMode, AnnotationScript, AnnotationScript2, AnnotationScriptUi, AnnotationSpec, AnnotationSpecUi, AnnotationStep, AnnotationStepUi, AnyForm, Args, ArrayColumnProvider, AxesVault, AxisLabelProvider, BLOCK_SERVICE_FLAGS, BLOCK_STORAGE_FACADE_VERSION, BlockApiV1, BlockApiV2, BlockConfig, BlockConfigV3, BlockConfigV4, BlockDefaultModelServices, BlockDefaultUiServices, BlockModel, BlockModelInfo, BlockModelV3, BlockRenderCtx, BlockServiceFlags, BlockStatePatch, type BlockStorage, BlockStorageFacade, BlockStorageFacadeCallbacks, BlockStorageFacadeHandles, type BlockStorageSchemaVersion, BuildOptions, CancelSubscription, Cfg, CfgAnd, CfgBlobContent, CfgBlobContentAsJson, CfgBlobContentAsString, CfgDownloadedBlobContent, CfgExtractArchiveAndGetURL, CfgFlatten, CfgGetFromCtx, CfgGetJsonField, CfgGetResourceField, CfgImmediate, CfgImportProgress, CfgIsEmpty, CfgIsolate, CfgLastLogs, CfgLogHandle, CfgMakeArray, CfgMakeObject, CfgMapArrayValues, CfgMapRecordValues, CfgMapResourceFields, CfgNot, CfgOnDemandBlobContent, CfgOr, CfgProgressLog, CfgProgressLogWithInfo, CfgRenderingMode, CfgResourceValueAsJson, Checked, ColumnCollection, ColumnCollectionBuilder, ColumnData, ColumnDataStatus, ColumnMatch, ColumnProvider, ColumnSelectorInput, ColumnSnapshot, ColumnSnapshotProvider, ColumnSource, CommonFieldTraverseOps, CommonTraversalOps, ConfAction, ConfigRenderLambda, ConfigRenderLambdaFlags, ConfigResult, CurrentSdkInfo, DataModel, DataModelBuilder, DeriveHref, DeriveLabelsOptions, Entry, ExpressionSpec, ExtractAction, ExtractFunctionHandleReturn, ExtractFutureRefType, FieldTraversalStep, FieldType, FilterSpec, FilterSpecLeaf, FilterSpecNode, FilterSpecOfType, FilterSpecType, FilterSpecUi, FilterUi, FilterUiOfType, FilterUiType, FindColumnsOptions, FormField, FutureRef, GetFieldStep, InferArgsType, InferBlockState, InferBlockStatePatch, InferDataType, InferFactoryData, InferFactoryModelServices, InferFactoryOutputs, InferFactoryParams, InferFactoryUiServices, InferHrefType, InferOutputType, InferOutputsFromConfigs, InferOutputsFromLambdas, InferOutputsType, InferPluginData, InferPluginHandle, InferPluginHandles, InferPluginNames, InferRenderFunctionReturn, InferUiState, InferVarTypeSafe, IsNA, It, internal_d_exports as JsRenderInternal, DeriveLabelsOptions as LabelDerivationOps, Log10, MainOutputs, MatchQualifications, MatchVariant, MatchingMode, type MigrateBlockStorageConfig, type MigrationFailure, type MigrationResult, type MigrationSuccess, ModelServices, type MutateStoragePayload, NodeServiceProxy, NotFilter, NumericalComparisonFilter, OptionalPlResourceEntry, OrFilter, OutputColumnProvider, OutputColumnProviderOpts, OutputError, PColumnCollection, PColumnDataUniversal, PColumnEntryUniversal, PColumnEntryWithLabel, PColumnKeyList, PColumnLazyUniversal, PColumnLazyWithLabel, PColumnPredicate, PColumnResourceMapData, PColumnResourceMapEntry, PFrameImpl, POCExtractAction, PTableKey, PTableParamsV2, type ParamsInput, Patch, PatternFilter, PatternPredicate, PatternPredicateContainSubsequence, PatternPredicateEquals, PlDataTableFilters, PlDataTableFiltersWithMeta, PlDataTableGridStateCore, PlDataTableModel, PlDataTableSheet, PlDataTableSheetState, PlDataTableStateV2, PlDataTableStateV2CacheEntry, PlDataTableStateV2Normalized, PlMultiSequenceAlignmentColorSchemeOption, PlMultiSequenceAlignmentModel, PlMultiSequenceAlignmentSettings, PlMultiSequenceAlignmentWidget, PlResourceEntry, PlSelectionModel, PlTableColumnId, PlTableColumnIdJson, Platforma, PlatformaApiVersion, PlatformaExtended, PlatformaFactory, PlatformaSDKVersion, PlatformaV1, PlatformaV2, PlatformaV3, type PluginConfig, type PluginData, PluginDataModel, PluginDataModelBuilder, type PluginDataModelVersions, type PluginFactory, PluginFactoryLike, PluginHandle, PluginInstance, PluginModel, type PluginName, type PluginOutputs, type PluginParams, type PluginRecord, type PluginRegistry, PluginRenderCtx, PrimitiveOrConfig, PrimitiveToCfg, RT_BINARY_PARTITIONED, RT_BINARY_SUPER_PARTITIONED, RT_JSON_PARTITIONED, RT_JSON_SUPER_PARTITIONED, RT_PARQUET_PARTITIONED, RT_PARQUET_SUPER_PARTITIONED, RT_RESOURCE_MAP, RT_RESOURCE_MAP_PARTITIONED, RelaxedAxisSelector, RelaxedColumnSelector, RelaxedRecord, RelaxedStringMatchers, RenderCtx, RenderCtxBase, RenderCtxLegacy, RenderFunction, RenderFunctionLegacy, ResolveCfgType, ResolveModelServices, ResolveUiServices, ResourceTraversalOps, ResourceType, ResultPool, ResultPoolColumnSnapshotProvider, SdkInfo, SimplifiedPColumnSpec, SimplifiedUniversalPColumnEntry, SnapshotColumnProvider, SortedCumulativeSum, Entry as SpecExtractorResult, StagingOutputs, StdCtx, StdCtxArgsOnly, StringMatcher, Trace, TransformedColumn, TreeNodeAccessor, TypeField, TypeFieldRecord, TypeForm, TypeToLiteral, TypedConfig, TypedConfigOrConfigLambda, TypedConfigOrString, UiServices, UiState, Unionize, UniversalColumnOption, UnwrapFutureRef, ValueRank, type VersionedData, WithLabel, allPColumnsReady, and, blockServiceNames, buildServices, collectCtxColumnSnapshotProviders, columnSelectorsToPredicate, compileAnnotationScript, compileFilter, compileFilters, convertFilterSpecsToExpressionSpecs, convertFilterUiToExpressionImpl, convertFilterUiToExpressions, convertOrParsePColumnData, createBlockStorage, createColumnSnapshot, createDefaultPTableParams, createNodeServiceProxy, createPFrameForGraphs, createPlDataTable, createPlDataTableSheet, createPlDataTableStateV2, createPlDataTableV2, createPlDataTableV3, createPlSelectionModel, createReadyColumnData, createRowSelectionColumn, deriveDataFromStorage, deriveDistinctLabels, deriveLabels, distillFilterSpec, downgradeCfgOrLambda, enrichCompatible, extractArchiveAndGetURL, extractConfig, filterDataInfoEntries, filterSpecToSpecQueryExpr, flatten, fromPlOption, fromPlRef, getAllRelatedColumns, getAvailableWithLinkersAxes, getAxisUniqueValues, getBlobContent, getBlobContentAsJson, getBlobContentAsString, getColumnOrAxisValueLabelsId, getColumnSpecById, getColumnUniqueValues, getColumnsFull, getDownloadedBlobContent, getEnvironmentValue, getFromCfg, getImmediate, getImportProgress, getJsonField, getLastLogs, getLogHandle, getOnDemandBlobContent, getPartitionKeysList, getPlatformaApiVersion, getPluginData, getProgressLog, getProgressLogWithInfo, getRawPlatformaInstance, getRelatedColumns, getRequestColumnsFromSelectedSources, getResourceField, getResourceValueAsJson, getSingleColumnData, getStorageData, getUniquePartitionKeys, getUniqueSourceValuesWithLabels, ifDef, isBlockStorage, isColumnHidden, isColumnOptional, isColumnSnapshotProvider, isConfigLambda, isEmpty, isHiddenFromGraphColumn, isHiddenFromUIColumn, isPColumnReady, isPluginOutputKey, isolate, makeArray, makeObject, mapArrayValues, mapRecordValues, mapResourceFields, matchColumn, matchColumnSelectors, migrateBlockStorage, normalizeBlockStorage, normalizeSelectors, not, or, parsePColumnData, parseResourceMap, pluginOutputKey, pluginOutputPrefix, readOutput, registerFacadeCallbacks, toColumnSnapshotProvider, unreachable, updateStorageData, upgradePlDataTableStateV2, wrapOutputs, writeLabelsToSpecs };
+export { ActAnd, ActExtractArchiveAndGetURL, ActFlatten, ActGetBlobContent, ActGetBlobContentAsJson, ActGetBlobContentAsString, ActGetDownloadedBlobContent, ActGetField, ActGetFromCtx, ActGetImmediate, ActGetLastLogs, ActGetLogHandle, ActGetOnDemandBlobContent, ActGetProgressLog, ActGetProgressLogWithInfo, ActGetResourceField, ActGetResourceValueAsJson, ActImportProgress, ActIsEmpty, ActIsolate, ActMakeArray, ActMakeObject, ActMapArrayValues, ActMapRecordValues, ActMapResourceFields, ActNot, ActOr, ActionResult, AnchorEntry, AnchoredBuildOptions, AnchoredColumnCollection, AnchoredFindColumnsOptions, AndFilter, AnnotationFilter, AnnotationMode, AnnotationScript, AnnotationScript2, AnnotationScriptUi, AnnotationSpec, AnnotationSpecUi, AnnotationStep, AnnotationStepUi, AnyForm, Args, ArrayColumnProvider, AxesVault, AxisLabelProvider, BLOCK_SERVICE_FLAGS, BLOCK_STORAGE_FACADE_VERSION, BlockApiV1, BlockApiV2, BlockConfig, BlockConfigV3, BlockConfigV4, BlockDefaultModelServices, BlockDefaultUiServices, BlockModel, BlockModelInfo, BlockModelV3, BlockRenderCtx, BlockServiceFlags, BlockStatePatch, type BlockStorage, BlockStorageFacade, BlockStorageFacadeCallbacks, BlockStorageFacadeHandles, type BlockStorageSchemaVersion, BuildOptions, CancelSubscription, Cfg, CfgAnd, CfgBlobContent, CfgBlobContentAsJson, CfgBlobContentAsString, CfgDownloadedBlobContent, CfgExtractArchiveAndGetURL, CfgFlatten, CfgGetFromCtx, CfgGetJsonField, CfgGetResourceField, CfgImmediate, CfgImportProgress, CfgIsEmpty, CfgIsolate, CfgLastLogs, CfgLogHandle, CfgMakeArray, CfgMakeObject, CfgMapArrayValues, CfgMapRecordValues, CfgMapResourceFields, CfgNot, CfgOnDemandBlobContent, CfgOr, CfgProgressLog, CfgProgressLogWithInfo, CfgRenderingMode, CfgResourceValueAsJson, Checked, ColumnCollection, ColumnCollectionBuilder, ColumnData, ColumnDataStatus, ColumnMatch, ColumnMatcher, ColumnOrderRule, ColumnProvider, ColumnSelector, ColumnSnapshot, ColumnSnapshotProvider, ColumnSource, ColumnVisibilityRule, ColumnsDisplayOptions, ColumnsSelectorConfig, CommonFieldTraverseOps, CommonTraversalOps, ConfAction, ConfigRenderLambda, ConfigRenderLambdaFlags, ConfigResult, CurrentSdkInfo, DataModel, DataModelBuilder, DeriveHref, DeriveLabelsOptions, Entry, ExpandByPartitionOpts, ExpandByPartitionResult, ExpressionSpec, ExtractAction, ExtractFunctionHandleReturn, ExtractFutureRefType, FieldTraversalStep, FieldType, FilterSpec, FilterSpecLeaf, FilterSpecNode, FilterSpecOfType, FilterSpecType, FilterSpecUi, FilterUi, FilterUiOfType, FilterUiType, FindColumnsOptions, FormField, FutureRef, GetFieldStep, InferArgsType, InferBlockState, InferBlockStatePatch, InferDataType, InferFactoryData, InferFactoryModelServices, InferFactoryOutputs, InferFactoryParams, InferFactoryUiServices, InferHrefType, InferOutputType, InferOutputsFromConfigs, InferOutputsFromLambdas, InferOutputsType, InferPluginData, InferPluginHandle, InferPluginHandles, InferPluginNames, InferRenderFunctionReturn, InferUiState, InferVarTypeSafe, IsNA, It, internal_d_exports as JsRenderInternal, DeriveLabelsOptions as LabelDerivationOps, Log10, MainOutputs, MatchQualifications, MatchVariant, MatchingMode, type MigrateBlockStorageConfig, type MigrationFailure, type MigrationResult, type MigrationSuccess, ModelServices, type MutateStoragePayload, NodeServiceProxy, NotFilter, NumericalComparisonFilter, OptionalPlResourceEntry, OrFilter, OutputColumnProvider, OutputColumnProviderOpts, OutputError, PColumnCollection, PColumnDataUniversal, PColumnEntryUniversal, PColumnEntryWithLabel, PColumnKeyList, PColumnLazyUniversal, PColumnLazyWithLabel, PColumnPredicate, PColumnResourceMapData, PColumnResourceMapEntry, PFrameImpl, POCExtractAction, PTableKey, PTableParamsV2, type ParamsInput, Patch, PatternFilter, PatternPredicate, PatternPredicateContainSubsequence, PatternPredicateEquals, PlDataTableFilterMeta, PlDataTableFilterSpecLeaf, PlDataTableFilters, PlDataTableFiltersWithMeta, PlDataTableGridStateCore, PlDataTableModel, PlDataTableSheet, PlDataTableSheetState, PlDataTableStateV2, PlDataTableStateV2CacheEntry, PlDataTableStateV2Normalized, PlMultiSequenceAlignmentColorSchemeOption, PlMultiSequenceAlignmentModel, PlMultiSequenceAlignmentSettings, PlMultiSequenceAlignmentWidget, PlResourceEntry, PlSelectionModel, PlTableColumnId, PlTableColumnIdJson, Platforma, PlatformaApiVersion, PlatformaExtended, PlatformaFactory, PlatformaSDKVersion, PlatformaV1, PlatformaV2, PlatformaV3, type PluginConfig, type PluginData, PluginDataModel, PluginDataModelBuilder, type PluginDataModelVersions, type PluginFactory, PluginFactoryLike, PluginHandle, PluginInstance, PluginModel, type PluginName, type PluginOutputs, type PluginParams, type PluginRecord, type PluginRegistry, PluginRenderCtx, PrimitiveOrConfig, PrimitiveToCfg, RT_BINARY_PARTITIONED, RT_BINARY_SUPER_PARTITIONED, RT_JSON_PARTITIONED, RT_JSON_SUPER_PARTITIONED, RT_PARQUET_PARTITIONED, RT_PARQUET_SUPER_PARTITIONED, RT_RESOURCE_MAP, RT_RESOURCE_MAP_PARTITIONED, RelaxedAxisSelector, RelaxedColumnSelector, RelaxedRecord, RelaxedStringMatchers, RenderCtx, RenderCtxBase, RenderCtxLegacy, RenderFunction, RenderFunctionLegacy, ResolveCfgType, ResolveModelServices, ResolveUiServices, ResourceTraversalOps, ResourceType, ResultPool, ResultPoolColumnSnapshotProvider, SdkInfo, SimplifiedPColumnSpec, SimplifiedUniversalPColumnEntry, SnapshotColumnProvider, SortedCumulativeSum, Entry as SpecExtractorResult, SplitAxis, StagingOutputs, StdCtx, StdCtxArgsOnly, StringMatcher, Trace, TraceEntry, TransformedColumn, TreeNodeAccessor, TypeField, TypeFieldRecord, TypeForm, TypeToLiteral, TypedConfig, TypedConfigOrConfigLambda, TypedConfigOrString, UiServices, UiState, Unionize, UniversalColumnOption, UnwrapFutureRef, ValueRank, type VersionedData, allPColumnsReady, and, blockServiceNames, buildServices, collectCtxColumnSnapshotProviders, compileAnnotationScript, compileFilter, compileFilters, convertColumnSelectorToMultiColumnSelector, convertFilterSpecsToExpressionSpecs, convertFilterUiToExpressionImpl, convertFilterUiToExpressions, convertOrParsePColumnData, convertRelaxedAxisSelectorToMultiAxisSelector, convertRelaxedColumnSelectorToMultiColumnSelector, createBlockStorage, createColumnSnapshot, createDefaultPTableParams, createNodeServiceProxy, createPFrameForGraphs, createPlDataTable, createPlDataTableOptionsV3, createPlDataTableSheet, createPlDataTableStateV2, createPlDataTableV2, createPlDataTableV3, createPlSelectionModel, createReadyColumnData, createRowSelectionColumn, deriveDataFromStorage, deriveDistinctLabels, deriveLabels, discoverTableColumnSnaphots, distillFilterSpec, downgradeCfgOrLambda, enrichCompatible, expandByPartition, extractArchiveAndGetURL, extractConfig, filterDataInfoEntries, filterSpecToSpecQueryExpr, flatten, fromPlOption, fromPlRef, getAllRelatedColumns, getAvailableWithLinkersAxes, getAxisUniqueValues, getBlobContent, getBlobContentAsJson, getBlobContentAsString, getColumnOrAxisValueLabelsId, getColumnSpecById, getColumnUniqueValues, getColumnsFull, getDownloadedBlobContent, getEffectiveVisibility, getEnvironmentValue, getFromCfg, getImmediate, getImportProgress, getJsonField, getLastLogs, getLogHandle, getOnDemandBlobContent, getOrderPriority, getPartitionKeysList, getPlatformaApiVersion, getPluginData, getProgressLog, getProgressLogWithInfo, getRawPlatformaInstance, getRelatedColumns, getRequestColumnsFromSelectedSources, getResourceField, getResourceValueAsJson, getSingleColumnData, getStorageData, getUniquePartitionKeys, getUniqueSourceValuesWithLabels, ifDef, isBlockStorage, isColumnHidden, isColumnOptional, isColumnSnapshotProvider, isConfigLambda, isEmpty, isHiddenFromGraphColumn, isHiddenFromUIColumn, isPColumnReady, isPluginOutputKey, isolate, makeArray, makeObject, mapArrayValues, mapRecordValues, mapResourceFields, migrateBlockStorage, normalizeBlockStorage, not, or, parsePColumnData, parseResourceMap, pluginOutputKey, pluginOutputPrefix, readOutput, registerFacadeCallbacks, toColumnSnapshotProvider, unreachable, updateStorageData, upgradePlDataTableStateV2, wrapOutputs };

package/dist/index.js

@@ -35,18 +35,20 @@ import { createDefaultPTableParams, createPlDataTableStateV2, upgradePlDataTable
 import { createPlDataTableSheet } from "./components/PlDataTable/createPlDataTableSheet.js";
 import { createColumnSnapshot, createReadyColumnData } from "./columns/column_snapshot.js";
 import { ArrayColumnProvider, OutputColumnProvider, SnapshotColumnProvider, isColumnSnapshotProvider, toColumnSnapshotProvider } from "./columns/column_snapshot_provider.js";
-import { columnSelectorsToPredicate, matchColumn, matchColumnSelectors, normalizeSelectors } from "./columns/column_selector.js";
+import { convertColumnSelectorToMultiColumnSelector, convertRelaxedAxisSelectorToMultiAxisSelector, convertRelaxedColumnSelectorToMultiColumnSelector } from "./columns/column_selector.js";
 import { ColumnCollectionBuilder } from "./columns/column_collection_builder.js";
 import { ResultPoolColumnSnapshotProvider, collectCtxColumnSnapshotProviders } from "./columns/ctx_column_sources.js";
+import { expandByPartition } from "./columns/expand_by_partition.js";
 import "./columns/index.js";
-import { createPlDataTableV3, isColumnHidden, isColumnOptional } from "./components/PlDataTable/createPlDataTable/createPlDataTableV3.js";
+import { getEffectiveVisibility, getOrderPriority, isColumnHidden, isColumnOptional } from "./components/PlDataTable/createPlDataTable/utils.js";
 import { createPlDataTableV2 } from "./components/PlDataTable/createPlDataTable/createPlDataTableV2.js";
+import { discoverTableColumnSnaphots } from "./components/PlDataTable/createPlDataTable/discoverColumns.js";
+import { createPlDataTableV3 } from "./components/PlDataTable/createPlDataTable/createPlDataTableV3.js";
 import { createPlDataTable } from "./components/PlDataTable/createPlDataTable/index.js";
 import { createRowSelectionColumn } from "./components/PlMultiSequenceAlignment.js";
 import { createPlSelectionModel } from "./components/PlSelectionModel.js";
 import "./components/index.js";
 import { PFrameImpl } from "./pframe.js";
-import { writeLabelsToSpecs } from "./labels/write_labels_to_specs.js";
 import "./labels/index.js";
 import { fromPlOption, fromPlRef } from "./ref_util.js";
 import { getPlatformaApiVersion, getRawPlatformaInstance } from "./raw_globals.js";
@@ -58,4 +60,4 @@ import "./services/index.js";
 import { getEnvironmentValue } from "./env_value.js";
 export * from "@milaboratories/pl-model-common";
 export * from "@milaboratories/pl-error-like";
-export { Args, ArrayColumnProvider, BLOCK_SERVICE_FLAGS, BLOCK_STORAGE_FACADE_VERSION, BlockModel, BlockModelV3, BlockRenderCtx, BlockStorageFacadeCallbacks, BlockStorageFacadeHandles, ColumnCollectionBuilder, CurrentSdkInfo, DataModel, DataModelBuilder, FutureRef, It, internal_exports as JsRenderInternal, MainOutputs, OutputColumnProvider, OutputError, PColumnCollection, PFrameImpl, PlatformaSDKVersion, PluginDataModel, PluginDataModelBuilder, PluginInstance, PluginModel, PluginRenderCtx, RT_BINARY_PARTITIONED, RT_BINARY_SUPER_PARTITIONED, RT_JSON_PARTITIONED, RT_JSON_SUPER_PARTITIONED, RT_PARQUET_PARTITIONED, RT_PARQUET_SUPER_PARTITIONED, RT_RESOURCE_MAP, RT_RESOURCE_MAP_PARTITIONED, RenderCtxBase, RenderCtxLegacy, ResultPool, ResultPoolColumnSnapshotProvider, SnapshotColumnProvider, StagingOutputs, TreeNodeAccessor, UiState, allPColumnsReady, and, blockServiceNames, buildServices, collectCtxColumnSnapshotProviders, columnSelectorsToPredicate, compileAnnotationScript, compileFilter, compileFilters, convertFilterSpecsToExpressionSpecs, convertFilterUiToExpressionImpl, convertFilterUiToExpressions, convertOrParsePColumnData, createBlockStorage, createColumnSnapshot, createDefaultPTableParams, createNodeServiceProxy, createPFrameForGraphs, createPlDataTable, createPlDataTableSheet, createPlDataTableStateV2, createPlDataTableV2, createPlDataTableV3, createPlSelectionModel, createReadyColumnData, createRowSelectionColumn, deriveDataFromStorage, deriveDistinctLabels, deriveLabels, distillFilterSpec, downgradeCfgOrLambda, enrichCompatible, extractArchiveAndGetURL, extractConfig, filterDataInfoEntries, filterSpecToSpecQueryExpr, flatten, fromPlOption, fromPlRef, getAllRelatedColumns, getAvailableWithLinkersAxes, getAxisUniqueValues, getBlobContent, getBlobContentAsJson, getBlobContentAsString, getColumnOrAxisValueLabelsId, getColumnSpecById, getColumnUniqueValues, getColumnsFull, getDownloadedBlobContent, getEnvironmentValue, getFromCfg, getImmediate, getImportProgress, getJsonField, getLastLogs, getLogHandle, getOnDemandBlobContent, getPartitionKeysList, getPlatformaApiVersion, getPluginData, getProgressLog, getProgressLogWithInfo, getRawPlatformaInstance, getRelatedColumns, getRequestColumnsFromSelectedSources, getResourceField, getResourceValueAsJson, getSingleColumnData, getStorageData, getUniquePartitionKeys, getUniqueSourceValuesWithLabels, ifDef, isBlockStorage, isColumnHidden, isColumnOptional, isColumnSnapshotProvider, isConfigLambda, isEmpty, isHiddenFromGraphColumn, isHiddenFromUIColumn, isPColumnReady, isPluginOutputKey, isolate, makeArray, makeObject, mapArrayValues, mapRecordValues, mapResourceFields, matchColumn, matchColumnSelectors, migrateBlockStorage, normalizeBlockStorage, normalizeSelectors, not, or, parsePColumnData, parseResourceMap, pluginOutputKey, pluginOutputPrefix, readOutput, registerFacadeCallbacks, toColumnSnapshotProvider, unreachable, updateStorageData, upgradePlDataTableStateV2, wrapOutputs, writeLabelsToSpecs };
+export { Args, ArrayColumnProvider, BLOCK_SERVICE_FLAGS, BLOCK_STORAGE_FACADE_VERSION, BlockModel, BlockModelV3, BlockRenderCtx, BlockStorageFacadeCallbacks, BlockStorageFacadeHandles, ColumnCollectionBuilder, CurrentSdkInfo, DataModel, DataModelBuilder, FutureRef, It, internal_exports as JsRenderInternal, MainOutputs, OutputColumnProvider, OutputError, PColumnCollection, PFrameImpl, PlatformaSDKVersion, PluginDataModel, PluginDataModelBuilder, PluginInstance, PluginModel, PluginRenderCtx, RT_BINARY_PARTITIONED, RT_BINARY_SUPER_PARTITIONED, RT_JSON_PARTITIONED, RT_JSON_SUPER_PARTITIONED, RT_PARQUET_PARTITIONED, RT_PARQUET_SUPER_PARTITIONED, RT_RESOURCE_MAP, RT_RESOURCE_MAP_PARTITIONED, RenderCtxBase, RenderCtxLegacy, ResultPool, ResultPoolColumnSnapshotProvider, SnapshotColumnProvider, StagingOutputs, TreeNodeAccessor, UiState, allPColumnsReady, and, blockServiceNames, buildServices, collectCtxColumnSnapshotProviders, compileAnnotationScript, compileFilter, compileFilters, convertColumnSelectorToMultiColumnSelector, convertFilterSpecsToExpressionSpecs, convertFilterUiToExpressionImpl, convertFilterUiToExpressions, convertOrParsePColumnData, convertRelaxedAxisSelectorToMultiAxisSelector, convertRelaxedColumnSelectorToMultiColumnSelector, createBlockStorage, createColumnSnapshot, createDefaultPTableParams, createNodeServiceProxy, createPFrameForGraphs, createPlDataTable, createPlDataTableSheet, createPlDataTableStateV2, createPlDataTableV2, createPlDataTableV3, createPlSelectionModel, createReadyColumnData, createRowSelectionColumn, deriveDataFromStorage, deriveDistinctLabels, deriveLabels, discoverTableColumnSnaphots, distillFilterSpec, downgradeCfgOrLambda, enrichCompatible, expandByPartition, extractArchiveAndGetURL, extractConfig, filterDataInfoEntries, filterSpecToSpecQueryExpr, flatten, fromPlOption, fromPlRef, getAllRelatedColumns, getAvailableWithLinkersAxes, getAxisUniqueValues, getBlobContent, getBlobContentAsJson, getBlobContentAsString, getColumnOrAxisValueLabelsId, getColumnSpecById, getColumnUniqueValues, getColumnsFull, getDownloadedBlobContent, getEffectiveVisibility, getEnvironmentValue, getFromCfg, getImmediate, getImportProgress, getJsonField, getLastLogs, getLogHandle, getOnDemandBlobContent, getOrderPriority, getPartitionKeysList, getPlatformaApiVersion, getPluginData, getProgressLog, getProgressLogWithInfo, getRawPlatformaInstance, getRelatedColumns, getRequestColumnsFromSelectedSources, getResourceField, getResourceValueAsJson, getSingleColumnData, getStorageData, getUniquePartitionKeys, getUniqueSourceValuesWithLabels, ifDef, isBlockStorage, isColumnHidden, isColumnOptional, isColumnSnapshotProvider, isConfigLambda, isEmpty, isHiddenFromGraphColumn, isHiddenFromUIColumn, isPColumnReady, isPluginOutputKey, isolate, makeArray, makeObject, mapArrayValues, mapRecordValues, mapResourceFields, migrateBlockStorage, normalizeBlockStorage, not, or, parsePColumnData, parseResourceMap, pluginOutputKey, pluginOutputPrefix, readOutput, registerFacadeCallbacks, toColumnSnapshotProvider, unreachable, updateStorageData, upgradePlDataTableStateV2, wrapOutputs };

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.65.0";
 //#endregion
 Object.defineProperty(exports, "version", {
 	enumerable: true,