react-semaphor 0.1.444 → 0.1.446

package/dist/types/main.d.ts

@@ -1,5 +1,4 @@
 import { Chart as Chart_2 } from 'chart.js';
-import { ChartConfiguration } from 'chart.js';
 import { ColumnSizingState } from '@tanstack/react-table';
 import { DateRange } from 'react-day-picker';
 import { default as default_2 } from 'react';
@@ -349,9 +348,13 @@ declare type AddFrameOptions = {
 
 /**
  * Single-button mode toggle (action pattern). The label reflects where
- * a click will take you, not where you currently are — e.g. while in
- * drag-and-drop mode the button shows `</> SQL`. Compact, matches the
+ * a click will take you, not where you currently are — e.g. while in the
+ * visual editor the button shows `</> SQL editor`. Compact, matches the
  * "Edit / Done" toggle convention.
+ *
+ * Both labels name a destination surface, in parallel. The old pair mixed
+ * categories — "SQL" named a language, "Drag & drop" named a gesture — so
+ * neither read as the place the click would take you.
  */
 export declare function AdvancedModeToggle({ className }: AdvancedModeToggleProps): JSX.Element | null;
 
@@ -468,7 +471,7 @@ declare type AsyncMutation<TInput, TOutput> = {
 
 export declare type AuthoritativeExportFormattingConfig = ExportFormattingConfig & {
     comparisonPresentation: ComparisonPresentationSpec;
-    resolvedNumericFormats: NumericPresentationSnapshotEntry[];
+    resolvedFormats: ResolvedPresentationEntry[];
 };
 
 export declare type AuthToken = {
@@ -537,6 +540,8 @@ declare type BaseFilter = {
     dataType?: string;
     fieldMeta?: FilterFieldMeta;
     semanticContext?: FilterSemanticContext;
+    /** Governed meaning for canonical grouped-temporal filter values. */
+    temporalBucket?: TemporalBucketMetadata;
 };
 
 export declare interface BaseInteractionEvent {
@@ -846,9 +851,9 @@ export declare type BriefingFormDraft = {
     limits: BriefingLimits;
 };
 
-export declare function briefingFormDraftToCreateRequest(draft: BriefingFormDraft): CreateBriefingRequest;
+export declare function briefingFormDraftToCreateRequest(draft: BriefingFormDraft, resolvedFormats?: ResolvedPresentationEntry[]): CreateBriefingRequest;
 
-export declare function briefingFormDraftToUpdateRequest(draft: BriefingFormDraft): UpdateBriefingRequest;
+export declare function briefingFormDraftToUpdateRequest(draft: BriefingFormDraft, resolvedFormats?: ResolvedPresentationEntry[]): UpdateBriefingRequest;
 
 export declare type BriefingFormOutputDraft = {
     artifactFormats: BriefingArtifactFormat[];
@@ -895,6 +900,7 @@ declare type BriefingFragments = {
 export declare type BriefingJobConfig = {
     kind: BriefingKind;
     reportContext: ReportRuntimeContext;
+    resolvedFormats?: ResolvedPresentationEntry[];
     source: BriefingSource;
     body: BriefingBody;
     attachments: BriefingAttachment[];
@@ -1296,7 +1302,17 @@ export declare function cancelExport(apiServiceUrl: string, token: string, expor
 
 declare type CanonicalDurationUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
 
-export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | DurationCanonicalFormat | StringCanonicalFormat;
+export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | DurationCanonicalFormat | StringCanonicalFormat | TemporalBucketFormat;
+
+declare type CanonicalPivotResultContract = {
+    version: 1;
+    expectedRoleFieldIds: PivotResultExpectedRoleFieldIds;
+    expectedMetricAliases: readonly string[];
+    columnKinds: Readonly<Record<string, PivotResultColumnKind>>;
+    columnClassifications: Readonly<Record<string, PivotResultColumnClassification | undefined>>;
+};
+
+declare type CanonicalPivotResultState = 'loaded_empty' | 'loaded_valid';
 
 export declare interface CardConfig {
     /**
@@ -1359,9 +1375,6 @@ export declare interface CardConfig {
      * Configuration for on-click dashboard filters triggered by this card.
      */
     clickFilterInteractions?: ClickFilterInteraction[];
-    showTrendline?: boolean;
-    trendlineWindow?: number;
-    trendlineGranularity?: 'day' | 'week' | 'month';
     summary?: {
         enabled?: boolean;
         showOnCard?: boolean;
@@ -1437,8 +1450,10 @@ export declare interface ClickedMetricValue {
 export declare interface ClickFilterCondition {
     field: Field;
     operator: Operator;
-    value: string | number;
+    value: string | number | null;
     label?: string;
+    /** Governed meaning for a canonical grouped-temporal scalar. */
+    temporalBucket?: TemporalBucketMetadata;
 }
 
 export declare interface ClickFilterConditionGroup {
@@ -1785,7 +1800,10 @@ export declare type ControlOption = {
     label: string;
     presentation?: {
         granularity?: TimeGranularity;
+        format?: TemporalBucketFormat;
+        /** Saved-dashboard compatibility only. New authoring writes `format`. */
         dateFormat?: DateFormatValue;
+        /** Saved-dashboard compatibility only. New authoring writes `format`. */
         customFormat?: string;
     };
 };
@@ -1827,6 +1845,7 @@ export declare type CreateBriefingRequest = {
     presentation: BriefingPresentation;
     limits?: BriefingLimits;
     deliveryConfig: BriefingDeliveryConfig | null;
+    resolvedFormats?: ResolvedPresentationEntry[];
 };
 
 /**
@@ -1850,6 +1869,9 @@ export declare interface CreateExportRequest {
     title?: string;
     connection_id: string;
     cardType: string;
+    sql: string;
+    python: string;
+    resultOwner: TemporalResultOwner;
     cardConfig: CardConfig;
     cardDataSource: DataSource;
     active_filters: TFilterValue[];
@@ -2352,6 +2374,11 @@ export declare type DashboardProps = {
      * inputs instead of documentInputValues.
      */
     dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
+    /**
+     * Runtime interaction state captured for deterministic print/replay entry
+     * points. Ordinary dashboard consumers should leave this unset.
+     */
+    interactionExecutionSnapshot?: Record<string, InteractionState>;
     /**
      * Render target for print entry points. Generic dashboard PDF exports also
      * use cardDisplay.mode="print"; document-specific print handling must only
@@ -2867,7 +2894,9 @@ export declare type DocumentVariableRef = {
     key: 'generatedAt' | 'pageNumber' | 'pageCount';
 };
 
-export declare interface DomainCalculatedDimension {
+export declare type DomainCalculatedDimension = SemanticGroupedTemporalInput<DomainCalculatedDimensionBase>;
+
+declare type DomainCalculatedDimensionBase = {
     name: string;
     label: string;
     description?: string;
@@ -2875,7 +2904,7 @@ export declare interface DomainCalculatedDimension {
     inputs: Record<string, DimensionInputReference>;
     dataType?: DataType;
     tags?: string[];
-}
+};
 
 export declare interface DomainCalculatedMetric {
     name: string;
@@ -2884,7 +2913,7 @@ export declare interface DomainCalculatedMetric {
     expression: string;
     inputs: Record<string, InputReference>;
     metricType?: 'base' | 'derived' | 'calculated';
-    format?: FormatSpec;
+    format?: ScalarFormatSpec;
     tags?: string[];
     isCertified?: boolean;
     aggregationStrategy?: AggregationStrategy;
@@ -3352,7 +3381,7 @@ export declare interface ExportFormattingConfig {
     visibleColumns?: string[];
     columnLabels?: Record<string, string>;
     tableTotalsLabelColumnKey?: string;
-    resolvedNumericFormats?: NumericPresentationSnapshotEntry[];
+    resolvedFormats?: ResolvedPresentationEntry[];
     comparisonPresentation?: ComparisonPresentationSpec;
 }
 
@@ -3444,8 +3473,9 @@ declare type ExportStoreState = {
 
 export declare interface Field {
     /**
-     * Unique identifier for this field instance (for joins, UI state, etc.).
-     * Should be unique within the context of the query or data model.
+     * Stable authored/semantic field identifier (for joins, UI state, etc.).
+     * It is normally unique within a role, but one saved query may reuse it in
+     * different roles; result bindings must therefore include the role.
      * Example: 'orders.customer_id', 'expr_12345', etc.
      */
     id: string;
@@ -3487,6 +3517,12 @@ export declare interface Field {
      */
     derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
+    /**
+     * Source-level temporal presentation keeps the semantic grain that authored
+     * the format. The card's mutable `granularity` remains the active query
+     * grain, so changing it cannot accidentally retarget a semantic default.
+     */
+    semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
 }
@@ -3530,6 +3566,10 @@ export declare interface FilterCondition {
     field: Field;
     operator: Operator;
     value: FilterValue;
+    /** Display-only label for canonical grouped-temporal values. */
+    label?: string;
+    /** Governed meaning for a canonical grouped-temporal scalar. */
+    temporalBucket?: TemporalBucketMetadata;
 }
 
 export declare type FilterDashboardInput = DashboardInputBase & {
@@ -3711,7 +3751,7 @@ export declare type FormatSpec = {
     type: 'string';
     prefix?: string;
     suffix?: string;
-};
+} | TemporalBucketFormat;
 
 export declare function getBriefing(apiServiceUrl: string, token: string, briefingId: string): Promise<{
     briefing: BriefingDetail;
@@ -3763,7 +3803,7 @@ export declare function getExportStatus(apiServiceUrl: string, token: string, ex
 
 export declare function getFieldRuntimeColumnName(field: Pick<Field, 'name' | 'sourceField'> | null | undefined): string;
 
-export declare function getFilterValueType(filter: TFilter): "date" | "string" | "number" | "boolean";
+export declare function getFilterValueType(filter: TFilter): "string" | "boolean" | "number" | "date";
 
 export declare function getFormattedTableNameForQuery({ schemaName, tableName, modelName, databaseName, capabilities, connectionType, }: {
     schemaName: string;
@@ -3806,7 +3846,7 @@ declare type GlobalDateComparisonSelection = {
     spec: ViewerPeriodComparisonSpec;
 };
 
-export declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+export declare type Granularity = SemaphorTimeGrain;
 
 export declare interface GroupByColumn extends BaseColumn {
     role: 'groupby';
@@ -3817,6 +3857,11 @@ export declare interface GroupByColumn extends BaseColumn {
 export declare interface GroupByField extends Field {
     role: 'groupby';
     granularity?: TimeGranularity;
+    /**
+     * Query transport policy for grouped temporal values. This is projected
+     * into executable card config and is not persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     /**
      * Optional SQL expression for grouping (e.g., DATE_TRUNC('month', order_date)).
      * If present, used in SELECT and GROUP BY instead of just the column name.
@@ -3826,6 +3871,17 @@ export declare interface GroupByField extends Field {
     calculatedFormula?: CalculatedFieldFormula;
 }
 
+/**
+ * Authoring boundary for a dashboard field that is known to be grouped by a
+ * temporal grain. The broad persisted field types remain intentionally
+ * compatible with unmigrated/non-temporal fields; new temporal writers use
+ * this boundary instead.
+ */
+declare type GroupedTemporalAuthoringInput<TBase extends object> = Omit<TBase, 'granularity' | 'format'> & {
+    granularity: SemaphorTimeGrain;
+    format?: TemporalBucketFormat;
+};
+
 export declare function hasCalculatedFieldMarker(field: Pick<Field, 'entityName' | 'entityId'> | null | undefined): boolean;
 
 export declare function hasCalculatedFormulaInputs(field: Field | null | undefined): boolean;
@@ -4139,7 +4195,7 @@ declare type MatrixAxisLevelDescriptor = {
     fieldKey: string;
     label: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -4351,7 +4407,7 @@ declare type MatrixMeasureDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -4365,7 +4421,7 @@ declare type MatrixMeasureSemantics = {
 } | {
     kind: 'semiAdditive';
     aggregate?: SemaphorAggregateFunction;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
 } | {
     kind: 'nonAdditive';
     aggregate?: SemaphorAggregateFunction;
@@ -4573,7 +4629,7 @@ declare type MetricComparisonSpec = {
     targetValue: number;
 };
 
-declare type MetricComparisonWindowGrain = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type MetricComparisonWindowGrain = SemaphorTimeGrain;
 
 export declare interface MetricField extends Field {
     role: 'metric';
@@ -4698,15 +4754,6 @@ export declare type NumberOptions = {
     colorRanges?: ColorRange[];
 };
 
-/**
- * Shared format types for export system
- * IMPORTANT: No React imports allowed in this file
- *
- * These types are used by:
- * - react-semaphor (browser) for client-side exports
- * - semaphor-app (Next.js) for API routes
- * - Lambda (Node.js) for async export processing
- */
 declare type NumericCanonicalFormat = {
     type: 'number' | 'currency' | 'percent' | 'scientific';
     locale?: string;
@@ -4722,16 +4769,6 @@ declare type NumericCanonicalFormat = {
     percentValueMode?: 'fraction' | 'whole';
 };
 
-declare type NumericPresentationSnapshotEntry = {
-    scope: {
-        dashboardId: string;
-        cardId?: string;
-        attachmentIndex?: number;
-    };
-    target: NumericPresentationTarget;
-    format: NumericCanonicalFormat;
-};
-
 declare type NumericPresentationTarget = {
     kind: 'metric';
     metricId: string;
@@ -4802,6 +4839,11 @@ export declare type PersistedInteraction = Interaction & {
 
 export declare interface PivotByField extends Field {
     role: 'pivotby';
+    /**
+     * Query transport policy for grouped temporal pivot members. This is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
 }
 
 export declare interface PivotColumnSchema {
@@ -4810,7 +4852,8 @@ export declare interface PivotColumnSchema {
     metricId: string;
     metricName: string;
     metricLabel?: string;
-    pivotValues: string[];
+    pivotValues: SemaphorPivotValue[];
+    pivotFieldIds?: string[];
     pivotFields?: string[];
     displayLabel?: string;
     isPivotColumn?: boolean;
@@ -4844,6 +4887,15 @@ export declare enum PivotMarkerEnum {
     ALL = "__ALL__"
 }
 
+declare type PivotResultColumnClassification = {
+    isSubtotal?: boolean;
+    subtotalScope?: 'base' | 'pivot-value' | 'grand-total';
+};
+
+declare type PivotResultColumnKind = 'row' | 'pivot_metric' | 'value';
+
+declare type PivotResultExpectedRoleFieldIds = Readonly<Partial<Record<QueryColumnKeyRole, readonly string[]>>>;
+
 export declare type Placeholders = {
     /**
      * Placeholder for the card when there are no records to display.
@@ -4859,6 +4911,12 @@ export declare type PluginType = 'custom' | 'standard';
 
 export declare function polishBriefingText(apiServiceUrl: string, token: string, text: string): Promise<string>;
 
+declare type PresentationScope = {
+    dashboardId: string;
+    cardId?: string;
+    attachmentIndex?: number;
+};
+
 export declare function previewBriefingPlan(apiServiceUrl: string, token: string, payload: CreateBriefingRequest): Promise<PreviewBriefingPlanResponse>;
 
 export declare type PreviewBriefingPlanResponse = {
@@ -4874,12 +4932,17 @@ export declare type PrintState = {
 
 export declare type QueryColumn = GroupByColumn | MetricColumn | FilterByColumn;
 
-export declare interface QueryColumnKeyMap {
+export declare type QueryColumnKeyMap = QueryColumnKeyMap_2;
+
+declare interface QueryColumnKeyMap_2 {
     version: 1;
     source: 'explorer';
-    byFieldId: Record<string, QueryColumnKeyMapEntry>;
+    byRole: QueryColumnKeyMapByRole;
+    byMetricAlias?: Record<string, QueryColumnKeyMapEntry>;
 }
 
+export declare type QueryColumnKeyMapByRole = Partial<Record<QueryColumnKeyRole, Record<string, QueryColumnKeyMapEntry>>>;
+
 export declare interface QueryColumnKeyMapEntry {
     role: QueryColumnKeyRole;
     rawKey: string;
@@ -4903,6 +4966,11 @@ export declare interface QueryConfig {
  */
 export declare interface QueryExecutionResponse {
     records: any[];
+    /** Execution owner captured with these exact result rows. */
+    resultOwner?: TemporalResultOwner;
+    pivotResultState?: CanonicalPivotResultState;
+    pivotResultContract?: CanonicalPivotResultContract;
+    columns?: SemaphorResultColumn[];
     output: string;
     rowLimitExceeded: boolean;
     sql?: string;
@@ -5063,7 +5131,23 @@ declare type ResolvedMetricComparisonRequest = {
     owner?: DashboardDateComparisonOwner;
 };
 
-declare type ResolvedPrimaryDateField = {
+declare type ResolvedNumericPresentationEntry = {
+    scope: PresentationScope;
+    target: NumericPresentationTarget;
+    format: NumericCanonicalFormat;
+};
+
+declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry;
+
+declare type ResolvedPrimaryDateField = (ResolvedPrimaryDateFieldBase & ({
+    defaultGranularity?: SemaphorTimeGrain;
+    format?: undefined;
+} | {
+    defaultGranularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+})) | null;
+
+declare type ResolvedPrimaryDateFieldBase = {
     sourceDataset: string;
     sourceField: string;
     name: string;
@@ -5073,13 +5157,20 @@ declare type ResolvedPrimaryDateField = {
     entityName: string;
     entityType: string;
     dataType: string;
-    /** Canonical dataset coordinates stamped by the temporal grounding boundary. */
+    /** Canonical dataset coordinates stamped by the semantic grounding boundary. */
     source?: SemaphorSourceRef;
-    dateFormat?: string;
-    customFormat?: string;
-    defaultGranularity?: TimeGranularity;
-    supportedGranularities?: TimeGranularity[];
-} | null;
+    supportedGranularities?: SemaphorTimeGrain[];
+};
+
+declare type ResolvedTemporalBucketFormat = TemporalBucketFormat & {
+    locale: string;
+};
+
+declare type ResolvedTemporalBucketPresentationEntry = {
+    scope: PresentationScope;
+    target: TemporalBucketPresentationTarget;
+    format: ResolvedTemporalBucketFormat;
+};
 
 declare type ResolvedValueFormatPreferences = {
     locale: string;
@@ -5101,6 +5192,10 @@ declare type ResolvedValueFormatPreferenceSources = {
     defaultCurrency: ReportPreferenceSource;
 };
 
+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;
+
 export declare interface ResourceListItem {
     id: string;
     title: string;
@@ -5177,6 +5272,8 @@ export declare type RunBriefingPreviewResponse = {
     dispatch: BriefingDispatchResult | null;
 };
 
+export declare type ScalarFormatSpec = Exclude<FormatSpec, TemporalBucketFormat>;
+
 export declare type SchemaItem = DropdownItem;
 
 export declare type SelectedEntities = SelectedEntity[];
@@ -5213,6 +5310,24 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+/**
+ * Semantic temporal input permits total omission, but a format can only exist
+ * in the branch that declares its grain.
+ */
+declare type SemanticGroupedTemporalInput<TBase extends object> = (Omit<TBase, 'granularity' | 'format'> & {
+    granularity?: undefined;
+    format?: undefined;
+}) | GroupedTemporalAuthoringInput<TBase>;
+
+export declare type SemanticTemporalPresentation = {
+    granularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+};
+
+declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -5289,7 +5404,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -5359,7 +5474,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -5475,6 +5590,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -5510,7 +5627,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -5578,6 +5695,30 @@ declare type SemaphorPaginationRequest = {
     pageSize: number;
 };
 
+declare type SemaphorPivotResultColumnIdentity = {
+    metricId: string;
+    /** Collision-safe identity for this configured metric instance. */
+    metricAlias: string;
+    /**
+     * Sole transported tuple identity in configured pivot-axis order. A leaf
+     * carries the complete tuple, a subtotal carries its explicit prefix, and a
+     * metric-only or grand-total column carries an empty tuple.
+     */
+    members: SemaphorPivotResultMember[];
+};
+
+declare type SemaphorPivotResultMember = {
+    /** Stable identity of the configured pivot field. */
+    fieldId: string;
+    /** Canonical pivot member value; labels are resolved only at presentation. */
+    value: SemaphorPivotValue;
+    /** Present when this member is an activated governed temporal bucket. */
+    temporalBucket?: TemporalBucketMetadata;
+};
+
+/** Stable canonical scalar transported for one physical pivot member. */
+declare type SemaphorPivotValue = string | null;
+
 declare type SemaphorProtocolVersion = 1;
 
 declare function SemaphorQueryClient({ children, }: {
@@ -5622,12 +5763,72 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+declare type SemaphorResultColumn = {
+    /**
+     * Stable row accessor for this result. Consumers should read values with
+     * `row[column.key]`; labels are display-only and may change.
+     */
+    key: string;
+    /**
+     * Semantic/source field name before result-key disambiguation.
+     */
+    name: string;
+    /**
+     * Human-facing display label.
+     */
+    label: string;
+    role?: SemaphorFieldRef['role'];
+    dataType?: SemaphorFieldRef['dataType'];
+    aggregate?: SemaphorFieldRef['aggregate'];
+    source?: SemaphorFieldRef['source'];
+    derivedField?: SemaphorDerivedFieldDefinition;
+    temporalBucket?: TemporalBucketMetadata;
+    pivotIdentity?: SemaphorPivotResultColumnIdentity;
+};
+
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -5673,47 +5874,10 @@ declare type SemaphorSqlIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    minimumFractionDigits?: number;
-    maximumFractionDigits?: number;
-    useGrouping?: boolean;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-    compact?: boolean;
-    scale?: number;
-    currency?: string;
-    percentValueMode?: 'fraction' | 'whole';
-} | {
-    type: 'date' | 'datetime';
-    locale?: string;
-    pattern?: string;
-    relative?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-    prefix?: string;
-    suffix?: string;
-} | {
-    type: 'duration';
-    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    maxUnits?: number;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-} | {
-    type: 'string';
-    prefix?: string;
-    suffix?: string;
-};
-
 /**
  * Stable serializer for dashboard dirty checks.
  * This consolidates normalization + serialization into one call site, so
@@ -6356,8 +6520,6 @@ export declare type TCardPreferences = {
     };
 };
 
-declare type TChartConfiguration = ChartConfiguration;
-
 export declare type TChartOptions = {
     type?: TChartType;
     scales?: {
@@ -6477,6 +6639,7 @@ export declare type TDataColumn = {
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
+    granularity?: TimeGranularity;
     sourceField?: string;
     aggregate?: AggregateFunction;
 };
@@ -6579,8 +6742,48 @@ export declare type TDynamicVisualIntent = {
     includesKpis: boolean;
 };
 
+declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
+declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
+declare type TemporalBucketMetadata = {
+    kind: 'temporal_bucket';
+    granularity: SemaphorTimeGrain;
+    calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
+};
+
+declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+declare type TemporalBucketPresentationTarget = {
+    kind: 'field';
+    fieldId: string;
+    /** Distinguishes one semantic field used on both pivot axes. */
+    role?: 'groupby' | 'pivotby';
+} | {
+    kind: 'column';
+    columnKey: string;
+} | {
+    kind: 'matrix_axis';
+    axisInstanceId: string;
+};
+
+declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
 declare type TemporalPrecision = 'minute';
 
+declare type TemporalResultOwner = 'config' | 'freeform' | 'none';
+
 export declare type TEvent = {
     type: 'success' | 'error' | 'info' | 'warning';
     message: any;
@@ -6779,7 +6982,7 @@ export declare interface TimeDrillStep {
     rollingWindow?: number;
 }
 
-export declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+export declare type TimeGranularity = SemaphorTimeGrain;
 
 /**
  * Inline filter definition stored on a card.
@@ -7262,12 +7465,14 @@ export declare function useCard(cardId: string): {
     fetchStatus: FetchStatus;
     visualKey: number;
     handleDatapointClick: (chart: Chart_2, datasetIndex: number, clickIndex: number, value: number) => void;
-    cfg: TChartConfiguration | undefined;
+    cfg: any;
     queryKey: string[];
     queryRequestPayload: Record<string, unknown> | undefined;
     pagination: PaginationMetadata | undefined;
     comparisonMetadata: MetricComparisonMetadataMap | undefined;
     resolvedPrimaryDateField: ResolvedPrimaryDateField | undefined;
+    effectiveCardConfig: CardConfig | undefined;
+    isCurrentQueryResult: boolean;
 };
 
 export declare function useCardSummary(card: TCard, options?: UseCardSummaryOptions): {
@@ -7583,7 +7788,7 @@ export declare function useTextFilterHook(filterId: string): {
     activeFilterValue: TFilterValue | undefined;
     isSearching: boolean;
     searchError: boolean;
-    resultSource: "both" | "server" | "local";
+    resultSource: "server" | "both" | "local";
 };
 
 export declare function validateBriefingFormDraft(draft: BriefingFormDraft): BriefingFormValidationResult;