react-semaphor 0.1.497 → 0.1.499

package/dist/types/main.d.ts

@@ -4621,6 +4621,8 @@ export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD"
  */
 export declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -4648,6 +4650,32 @@ export declare interface CalculatedFieldFormula {
     constant?: number;
 }
 
+/** Metadata surface needed to classify a field without requiring shelf UI fields. */
+export declare type CalculatedFieldInspectable = {
+    calculationRepresentation?: Field['calculationRepresentation'];
+    name?: string;
+    sourceField?: string;
+    role?: Field['role'];
+    entityName?: string;
+    entityId?: string;
+    qualifiedEntityName?: string;
+    fieldScope?: FieldScope;
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    derivedField?: SemaphorDerivedFieldDefinition;
+};
+
+export declare type CalculatedFieldInspection = {
+    representation: 'physical' | 'inline-expression' | 'manual' | 'typed-derived';
+    ownership: 'local' | 'domain';
+    completeness: 'not-calculated' | 'complete' | 'incomplete';
+    computeStage?: 'row' | 'aggregate';
+    runtimeExecutable: boolean;
+    /** Compatibility mode for local runtime fields created before stage metadata. */
+    legacyManual: boolean;
+};
+
 /**
  * Operations supported for calculated fields
  */
@@ -10578,6 +10606,19 @@ export declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
@@ -10664,7 +10705,7 @@ export declare type FilterDashboardInputDefinitionUpdateResult = {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */
@@ -10908,6 +10949,8 @@ export declare function getBriefingPreviewRun(apiServiceUrl: string, token: stri
 
 export declare function getBriefingRun(apiServiceUrl: string, token: string, briefingId: string, runId: string): Promise<BriefingRun>;
 
+export declare function getCalculatedFieldComputeStage(field: CalculatedFieldInspectable | null | undefined): 'row' | 'aggregate' | undefined;
+
 export declare function getColumnDataType(column: TDataColumn): string;
 
 export declare type GetDashboardResponse = {
@@ -11087,6 +11130,13 @@ export declare type InputReference = {
     dimension: string;
 };
 
+/**
+ * Inspect a runtime field without conflating public typed-derived metadata with
+ * the dashboard-local expression/formula representation. Consumers use this
+ * result for classification and stage; each compiler still owns execution.
+ */
+export declare function inspectCalculatedField(field: CalculatedFieldInspectable | null | undefined): CalculatedFieldInspection;
+
 /**
  * Unified Interaction type (V2)
  * Combines all interaction types into a single union for the new interactions array.
@@ -11220,11 +11270,6 @@ export declare function isCalculatedDimension(field: GroupByField): field is Gro
     expression: string;
 };
 
-/**
- * Generic type guard for any calculated field
- */
-export declare function isCalculatedField(field: Field): boolean;
-
 /**
  * IMPORTANT: Why we store qualifiedFieldNames as strings instead of Field objects
  *
@@ -11248,6 +11293,15 @@ export declare function isColumnInSqlGen(column: TDataColumn, sqlGen: SqlGen): b
 
 export declare function isDateDataType(dataType: string): boolean;
 
+/**
+ * True for every representation of a derived (calculated) field:
+ * an expression, formula inputs, the shared-contract `derivedField`
+ * (the only shape Matrix-authored calculations may carry), or a synthetic
+ * calculated-field owner. Use this wherever the
+ * question is "is this computed rather than stored".
+ */
+export declare function isDerivedField(field: CalculatedFieldInspectable | null | undefined): boolean;
+
 /**
  * Check if an export has completed (successfully or with failure)
  */
@@ -20003,6 +20057,10 @@ declare type MonthAlignedFiscalCalendar = {
 
 declare type NoneOptions = {};
 
+/** Normalize unannotated saved shapes once, before attaching placement/scope
+ * metadata. Never replaces an explicit tag, even if invalid: validation owns it. */
+export declare function normalizeCalculatedFieldRepresentation<T extends CalculatedFieldInspectable>(field: T): T;
+
 /**
  * Normalizes dashboard layout objects into a canonical structure:
  * - strips transient react-grid-layout runtime fields
@@ -22827,6 +22885,9 @@ declare type ShareRole = 'VIEWER' | 'EDITOR' | 'CONTRIBUTOR';
 
 declare type ShareScope = 'specific_tenant_user' | 'all_tenant_users' | 'specific_org_user' | 'all_org_users' | 'org_users_only' | 'all_tenants_only';
 
+/** Only a proven inherited default may be removed for an aggregate-stage definition. */
+export declare function shouldDropInheritedCalculationAggregate(computeStage: 'row' | 'aggregate' | undefined, aggregateOrigin: MetricField['aggregateOrigin']): boolean;
+
 export declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
@@ -25144,6 +25205,13 @@ export declare type TDataColumn = {
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
+    fieldScope?: FieldScope;
+    source?: Field['source'];
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    calculationRepresentation?: Field['calculationRepresentation'];
+    aggregateOrigin?: Field['aggregateOrigin'];
+    labelOrigin?: Field['labelOrigin'];
+    formatOrigin?: Field['formatOrigin'];
     format?: FormatSpec;
     granularity?: TimeGranularity;
     sourceField?: string;

package/dist/types/shared.d.ts

@@ -311,6 +311,8 @@ declare type CacheConfig = {
  */
 declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -4839,6 +4841,19 @@ declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
@@ -4903,7 +4918,7 @@ declare type FilterDashboardInputBase = DashboardInputBase & {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */

package/dist/types/surfboard.d.ts

@@ -403,6 +403,8 @@ export declare type CacheConfig = {
  */
 declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -5213,6 +5215,19 @@ declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
@@ -5277,7 +5292,7 @@ declare type FilterDashboardInputBase = DashboardInputBase & {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */
@@ -10306,6 +10321,13 @@ export declare type TDataColumn = {
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
+    fieldScope?: FieldScope;
+    source?: Field['source'];
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    calculationRepresentation?: Field['calculationRepresentation'];
+    aggregateOrigin?: Field['aggregateOrigin'];
+    labelOrigin?: Field['labelOrigin'];
+    formatOrigin?: Field['formatOrigin'];
     format?: FormatSpec;
     granularity?: TimeGranularity;
     sourceField?: string;

package/dist/types/types.d.ts

@@ -877,6 +877,8 @@ export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD"
  */
 export declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
      *
@@ -904,6 +906,32 @@ export declare interface CalculatedFieldFormula {
     constant?: number;
 }
 
+/** Metadata surface needed to classify a field without requiring shelf UI fields. */
+export declare type CalculatedFieldInspectable = {
+    calculationRepresentation?: Field['calculationRepresentation'];
+    name?: string;
+    sourceField?: string;
+    role?: Field['role'];
+    entityName?: string;
+    entityId?: string;
+    qualifiedEntityName?: string;
+    fieldScope?: FieldScope;
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    derivedField?: SemaphorDerivedFieldDefinition;
+};
+
+export declare type CalculatedFieldInspection = {
+    representation: 'physical' | 'inline-expression' | 'manual' | 'typed-derived';
+    ownership: 'local' | 'domain';
+    completeness: 'not-calculated' | 'complete' | 'incomplete';
+    computeStage?: 'row' | 'aggregate';
+    runtimeExecutable: boolean;
+    /** Compatibility mode for local runtime fields created before stage metadata. */
+    legacyManual: boolean;
+};
+
 /**
  * Operations supported for calculated fields
  */
@@ -1897,6 +1925,16 @@ declare interface ClickFilterInteraction {
     label?: string;
 }
 
+export declare function collectDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>, options?: DatasetCollectionOptions): void;
+
+export declare function collectDatasetNamesFromFilterGroup(filters: FilterGroup | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>, options?: DatasetCollectionOptions): void;
+
+export declare function collectExecutionDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>): void;
+
+export declare function collectPreferredDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>): void;
+
+export declare function collectQualifiedDatasetNamesFromExplorerField(field: ExplorerField | null | undefined, datasets: Set<string>, visitedFields?: Set<string>, visitedGroups?: Set<string>): void;
+
 export declare type ColorConfig = {
     segments: Record<string, string>;
 };
@@ -4946,6 +4984,13 @@ export declare interface DataModelEntityReference extends DatabaseEntityReferenc
     description: string;
 }
 
+export declare type DatasetCollectionOptions = {
+    /** Include datasets referenced by metric filter conditions. Default true. */
+    includeMetricFilterDatasets?: boolean;
+    /** Emit `qualifiedEntityName` when it is dotted, otherwise `entityName`. Default false. */
+    preferQualifiedIdentity?: boolean;
+};
+
 export declare interface DatasetEntityReference extends DatabaseEntityReference {
     type: 'dataset';
     datasetType: 'physical' | 'virtual';
@@ -4959,6 +5004,14 @@ export declare interface DatasetEntityReference extends DatabaseEntityReference
     description?: string;
 }
 
+/**
+ * The dataset a shared analytics `source` ref names. Semantic sources are
+ * the dataset name; physical sources keep database/schema/table so distinct
+ * tables stay distinct. The single mapping for both the walker and the
+ * calculator's identity resolver.
+ */
+export declare function datasetRefFromSource(source: Field['source'] | undefined): FieldDatasetDependency | undefined;
+
 export declare interface DataSource {
     connectionId: string;
     semanticDomainId?: string;
@@ -5026,6 +5079,9 @@ export declare type DeleteBriefingRunResponse = {
     deletedRunId: string;
 };
 
+/** Best available identity for a dependency: name, else qualified name. */
+export declare function dependencyDisplayIdentity(dep: FieldDatasetDependency): string;
+
 /**
  * Field configuration for detail table columns.
  * Unlike GroupByField, DetailField does not support aggregation or granularity.
@@ -5725,6 +5781,41 @@ declare const expansionShape: z.ZodObject<{
     }[];
 }>;
 
+/**
+ * Field dependency resolution (shared by server planning and client UX)
+ * =====================================================================
+ *
+ * One question, answered in one place for every field representation:
+ *
+ *   "Which datasets does this field read from?"
+ *
+ * Consumers:
+ *   - semaphor-app query planning (join resolution, filter applicability,
+ *     fan-out analysis) via the `collect*` functions, which keep the
+ *     original server API and semantics.
+ *   - react-semaphor field availability ("usable in this chart") via
+ *     `resolveFieldDatasetDependencies`, which returns full dependency
+ *     objects with qualified identity.
+ *
+ * Representations handled, in order, by ONE walker:
+ *   1. A field owned by a real dataset is a leaf on that dataset, even when
+ *      it carries an expression (inline domain expressions, query-local
+ *      aliases). Synthetic owners (the calculated-field markers, the
+ *      `calculated_fields` group, or no owner) are never leaves.
+ *   2. `calculatedFormula.inputFields`: full Field objects, walked
+ *      recursively.
+ *   3. `derivedField.inputs[*].field.source`: the shared analytics contract,
+ *      used only when there are no formula inputs (both encode the same
+ *      inputs). Semantic sources resolve to the dataset name; physical
+ *      sources keep database/schema/table so `public.orders` and
+ *      `archive.orders` stay distinct. This is the only representation
+ *      Matrix-authored calculations may carry.
+ *   4. Metric filter conditions (`parameters.filters`), when requested.
+ *
+ * Adding a representation means adding it here, once.
+ */
+declare type ExplorerField = Field | GroupByField | MetricField;
+
 export declare type ExportDataPayload = {
     cardId: string;
     title: string;
@@ -5800,9 +5891,46 @@ export declare interface Field {
      */
     semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
     fieldScope?: FieldScope;
 }
 
+export declare type FieldDatasetDependency = {
+    /**
+     * Dataset name as the catalog knows it (entityName / datasetName / table).
+     * Empty string when the source carried only a qualified name.
+     */
+    entityName: string;
+    entityId?: string;
+    /** Qualified identity when known (`schema.table`, `db.schema.table`, or the field's qualifiedEntityName). */
+    qualifiedEntityName?: string;
+    /** Human label when the source carried one. */
+    label?: string;
+};
+
+export declare type FieldDependencyResolution = {
+    /** Unique datasets, in first-seen order. */
+    datasets: FieldDatasetDependency[];
+    /**
+     * False when at least one input could not be traced to a dataset (for
+     * example a metric-to-metric reference that was not expanded into input
+     * fields). Callers must not claim the field is available in that case.
+     */
+    complete: boolean;
+};
+
 export declare type FieldScope = 'card' | 'sheet' | 'dashboard' | 'domain';
 
 declare type FileAttachment = {
@@ -5864,7 +5992,7 @@ declare type FilterDashboardInputBase = DashboardInputBase & {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-export declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+export declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope' | 'calculationRepresentation' | 'calculatedFieldOrigin' | 'derivedField'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     /** Exact database type used by server-side predicate formatting. */
@@ -6042,6 +6170,8 @@ export declare type FormatSpec = {
     suffix?: string;
 } | TemporalBucketFormat;
 
+export declare function getCalculatedFieldComputeStage(field: CalculatedFieldInspectable | null | undefined): 'row' | 'aggregate' | undefined;
+
 export declare type GetDashboardResponse = {
     dashboard: TDashboard;
     initialReportContext: ReportRuntimeContext;
@@ -6117,6 +6247,9 @@ export declare type HtmlOptions = {
     html: string;
 };
 
+/** Humanize a catalog dataset name for customer-facing copy. */
+export declare function humanizeDatasetName(name: string, labels?: Record<string, string>): string;
+
 declare interface InlineDrillEvent extends BaseInteractionEvent {
     interactionMode: 'inlineDrill';
     fetchMode?: 'lazy' | 'preloaded';
@@ -6169,6 +6302,13 @@ export declare type InputReference = {
     dimension: string;
 };
 
+/**
+ * Inspect a runtime field without conflating public typed-derived metadata with
+ * the dashboard-local expression/formula representation. Consumers use this
+ * result for classification and stage; each compiler still owns execution.
+ */
+export declare function inspectCalculatedField(field: CalculatedFieldInspectable | null | undefined): CalculatedFieldInspection;
+
 /**
  * Unified Interaction type (V2)
  * Combines all interaction types into a single union for the new interactions array.
@@ -6271,11 +6411,6 @@ export declare function isCalculatedDimension(field: GroupByField): field is Gro
     expression: string;
 };
 
-/**
- * Generic type guard for any calculated field
- */
-export declare function isCalculatedField(field: Field): boolean;
-
 /**
  * IMPORTANT: Why we store qualifiedFieldNames as strings instead of Field objects
  *
@@ -6295,6 +6430,15 @@ export declare function isCalculatedMetric(field: Field): field is MetricField &
     expression: string;
 };
 
+/**
+ * True for every representation of a derived (calculated) field:
+ * an expression, formula inputs, the shared-contract `derivedField`
+ * (the only shape Matrix-authored calculations may carry), or a synthetic
+ * calculated-field owner. Use this wherever the
+ * question is "is this computed rather than stored".
+ */
+export declare function isDerivedField(field: CalculatedFieldInspectable | null | undefined): boolean;
+
 export declare interface Join {
     id: string;
     source: DatabaseEntityReference;
@@ -6597,6 +6741,10 @@ declare type MonthAlignedFiscalCalendar = {
 
 declare type NoneOptions = {};
 
+/** Normalize unannotated saved shapes once, before attaching placement/scope
+ * metadata. Never replaces an explicit tag, even if invalid: validation owns it. */
+export declare function normalizeCalculatedFieldRepresentation<T extends CalculatedFieldInspectable>(field: T): T;
+
 export declare type NormalizedDashboardInput = NormalizedFilterDashboardInput | ControlDashboardInput;
 
 /** Runtime form after dashboard-filter references are resolved once. */
@@ -8729,6 +8877,14 @@ declare type ResolvedValueFormatPreferenceSources = {
     defaultCurrency: ReportPreferenceSource;
 };
 
+/**
+ * Resolve the datasets a field reads from, with qualified identity.
+ * Base fields resolve to their own dataset; calculated fields resolve
+ * through their inputs. Metric filter datasets are not included: they do
+ * not affect whether the field itself can be added.
+ */
+export declare function resolveFieldDatasetDependencies(field: Field): FieldDependencyResolution;
+
 export declare function resolveQueryColumnKeyMapEntry(columnKeyMap: QueryColumnKeyMap_2 | undefined, fieldId: string, role: QueryColumnKeyRole): QueryColumnKeyMapEntry | undefined;
 
 export declare function resolveUniqueQueryColumnKeyMapEntry(columnKeyMap: QueryColumnKeyMap_2 | undefined, fieldId: string): QueryColumnKeyMapEntry | undefined;
@@ -9005,6 +9161,9 @@ declare type SemaphorSourceRef = {
 
 declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
+/** Only a proven inherited default may be removed for an aggregate-stage definition. */
+export declare function shouldDropInheritedCalculationAggregate(computeStage: 'row' | 'aggregate' | undefined, aggregateOrigin: MetricField['aggregateOrigin']): boolean;
+
 export declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
@@ -11231,6 +11390,13 @@ export declare type TDataColumn = {
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
+    fieldScope?: FieldScope;
+    source?: Field['source'];
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    calculationRepresentation?: Field['calculationRepresentation'];
+    aggregateOrigin?: Field['aggregateOrigin'];
+    labelOrigin?: Field['labelOrigin'];
+    formatOrigin?: Field['formatOrigin'];
     format?: FormatSpec;
     granularity?: TimeGranularity;
     sourceField?: string;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.497",
+  "version": "0.1.499",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",