react-semaphor 0.1.443 → 0.1.445

package/dist/types/types.d.ts

@@ -147,8 +147,16 @@ declare type BaseFilter = {
     dataType?: string;
     fieldMeta?: FilterFieldMeta;
     semanticContext?: FilterSemanticContext;
+    /** Governed meaning for canonical grouped-temporal filter values. */
+    temporalBucket?: TemporalBucketMetadata;
 };
 
+declare interface BaseInteractionEvent {
+    sourceCardId: string;
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+}
+
 declare type BaseSurfaceAppearance = {
     background?: string;
     foreground?: string;
@@ -339,6 +347,7 @@ declare type BriefingFragments = {
 export declare type BriefingJobConfig = {
     kind: BriefingKind;
     reportContext: ReportRuntimeContext;
+    resolvedFormats?: ResolvedPresentationEntry[];
     source: BriefingSource;
     body: BriefingBody;
     attachments: BriefingAttachment[];
@@ -693,7 +702,17 @@ export declare type CancelBriefingRunResponse = {
 
 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 {
     /**
@@ -756,9 +775,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;
@@ -815,6 +831,38 @@ declare type ChartAppearance = {
     axisColor?: string;
 };
 
+declare interface ClickedMetricValue {
+    field: Field;
+    value: number;
+    formattedValue?: string;
+}
+
+declare interface ClickFilterCondition {
+    field: Field;
+    operator: Operator;
+    value: string | number | null;
+    label?: string;
+    /** Governed meaning for a canonical grouped-temporal scalar. */
+    temporalBucket?: TemporalBucketMetadata;
+}
+
+declare interface ClickFilterConditionGroup {
+    filters: ClickFilterCondition[];
+}
+
+declare interface ClickFilterEvent extends BaseInteractionEvent {
+    interactionMode: 'clickFilter';
+    applyToCardIds?: string[];
+    excludeCardIds?: string[];
+    /**
+     * Whether the source card should receive its own filter.
+     * When true, the source card will be filtered (not just blurred).
+     * Used when user selects from multiple interactions popup.
+     * @default false
+     */
+    filterSourceCard?: boolean;
+}
+
 declare interface ClickFilterInteraction {
     mode: 'clickFilter';
     /**
@@ -1095,7 +1143,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;
     };
 };
@@ -1131,6 +1182,7 @@ export declare type CreateBriefingRequest = {
     presentation: BriefingPresentation;
     limits?: BriefingLimits;
     deliveryConfig: BriefingDeliveryConfig | null;
+    resolvedFormats?: ResolvedPresentationEntry[];
 };
 
 export declare type CurrencyPresentationBinding = {
@@ -1351,6 +1403,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
@@ -1719,7 +1776,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;
@@ -1727,7 +1786,7 @@ export declare interface DomainCalculatedDimension {
     inputs: Record<string, DimensionInputReference>;
     dataType?: DataType;
     tags?: string[];
-}
+};
 
 export declare interface DomainCalculatedMetric {
     name: string;
@@ -1736,12 +1795,49 @@ export declare interface DomainCalculatedMetric {
     expression: string;
     inputs: Record<string, InputReference>;
     metricType?: 'base' | 'derived' | 'calculated';
-    format?: FormatSpec;
+    format?: ScalarFormatSpec;
     tags?: string[];
     isCertified?: boolean;
     aggregationStrategy?: AggregationStrategy;
 }
 
+declare interface DrillBreadcrumb {
+    /**
+     * The user clicked one or more segments. Each group of filters represents
+     * a single segment (i.e., a single click interaction).
+     *
+     * - Filters within a group are AND-ed (e.g., state = 'NY' AND ship_mode = 'Standard').
+     * - Across groups, they are OR-ed (e.g., ... OR state = 'CA' AND ship_mode = 'First Class').
+     */
+    sourceFilterGroups: ClickFilterConditionGroup[];
+    /**
+     * The next (group by) field the user is drilling into (e.g., 'city' after 'state').
+     */
+    toField?: Field;
+    /**
+     * Optional: If the drill target is a time field, this describes the granularity (e.g., month, year).
+     */
+    granularity?: TimeGranularity;
+    /**
+     * Optional: Indicates whether the drill is for time comparison (e.g., YoY).
+     */
+    timeComparison?: TimeComparison;
+    /**
+     * Optional: The metric the user clicked (e.g., '123 Orders'), used for display only.
+     */
+    metric?: ClickedMetricValue;
+}
+
+declare interface DrillDownEvent extends BaseInteractionEvent {
+    interactionMode: 'drillDown';
+    hierarchyId: string;
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+    toField: Field;
+    granularity?: TimeGranularity;
+    timeComparison?: TimeComparison;
+}
+
 declare interface DrillDownInteraction {
     mode: 'drillDown';
     /**
@@ -1773,6 +1869,12 @@ declare interface DrillHierarchyStep {
     linkedInsightId?: string;
 }
 
+declare interface DrillThroughEvent extends BaseInteractionEvent {
+    interactionMode: 'drillThrough';
+    targetDashboardId: string;
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+}
+
 declare interface DrillThroughInteraction {
     mode: 'drillThrough';
     /**
@@ -1790,6 +1892,17 @@ declare interface DrillThroughInteraction {
     label?: string;
 }
 
+declare interface DrillToDetailEvent extends BaseInteractionEvent {
+    interactionMode: 'drillToDetail';
+    detailFields: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    targetInsightId?: string;
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    displayMode?: 'modal' | 'replace-card';
+}
+
 declare interface DrillToDetailInteraction {
     mode: 'drillToDetail';
     /**
@@ -1819,6 +1932,11 @@ declare interface DrillToDetailInteraction {
     label?: string;
 }
 
+declare interface DrillToURLEvent extends BaseInteractionEvent {
+    interactionMode: 'drillToURL';
+    url: string;
+}
+
 declare interface DrillToURLInteraction {
     mode: 'drillToURL';
     /**
@@ -1874,6 +1992,15 @@ declare type DurationCanonicalFormat = {
     negativeStyle?: 'minus' | 'parentheses';
 };
 
+declare interface DynamicDrillEvent extends BaseInteractionEvent {
+    interactionMode: 'dynamicDrill';
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+    toField: Field;
+    granularity?: TimeGranularity;
+    timeComparison?: TimeComparison;
+}
+
 declare interface DynamicDrillInteraction {
     mode: 'dynamicDrill';
     /**
@@ -1929,8 +2056,9 @@ export declare type ExportDataPayload = {
 
 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;
@@ -1972,6 +2100,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;
 }
@@ -2015,6 +2149,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 & {
@@ -2189,7 +2327,7 @@ export declare type FormatSpec = {
     type: 'string';
     prefix?: string;
     suffix?: string;
-};
+} | TemporalBucketFormat;
 
 export declare type GetDashboardResponse = {
     dashboard: TDashboard;
@@ -2220,7 +2358,7 @@ declare type GlobalDateComparisonSelection = {
     spec: ViewerPeriodComparisonSpec;
 };
 
-declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+declare type Granularity = SemaphorTimeGrain;
 
 declare interface GroupByColumn extends BaseColumn {
     role: 'groupby';
@@ -2231,6 +2369,11 @@ 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.
@@ -2240,6 +2383,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;
@@ -2248,6 +2402,12 @@ export declare type HtmlOptions = {
     html: string;
 };
 
+declare interface InlineDrillEvent extends BaseInteractionEvent {
+    interactionMode: 'inlineDrill';
+    fetchMode?: 'lazy' | 'preloaded';
+    inlineLimit?: number;
+}
+
 declare interface InlineDrillInteraction {
     mode: 'inlineDrill';
     /**
@@ -2300,6 +2460,60 @@ export declare type InputReference = {
  */
 declare type Interaction = ClickFilterInteraction | DrillDownInteraction | DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction | DrillUpInteraction | DynamicDrillInteraction;
 
+declare type InteractionEvent = DrillDownEvent | DynamicDrillEvent | DrillToURLEvent | DrillThroughEvent | DrillToDetailEvent | InlineDrillEvent | ClickFilterEvent;
+
+declare interface InteractionState {
+    /**
+     * If user is in a drill hierarchy (static or dynamic), this tracks which one.
+     * Undefined if not currently in a drill path.
+     */
+    hierarchyId?: string;
+    /**
+     * Breadcrumb trail representing the user's drill path.
+     * Empty if no drill-down steps have occurred.
+     */
+    breadcrumbs: DrillBreadcrumb[];
+    /**
+     * All click filters applied from this card
+     */
+    appliedClickFilters?: ClickFilterEvent[];
+    /**
+     * (Optional) Track last one-off interaction (e.g., drillToDetail, drillToURL).
+     * Useful for things like modals or redirection handling.
+     */
+    lastInteractionEvent?: InteractionEvent;
+    /**
+     * Context mode for drill-to-insight filtering.
+     * Controls whether dashboard filters are applied alongside interaction filters.
+     *
+     * - 'interactionFilters': Only filters from the interaction event (no dashboard filters)
+     * - 'full': Dashboard filters + interaction filters
+     * - 'none': No filters applied
+     *
+     * Undefined for regular cards (not insights).
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    /**
+     * Source dashboard ID for drill-through navigation.
+     * Used for "Back" button navigation.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    sourceDashboardId?: string;
+    /**
+     * Source dashboard title for drill-through navigation.
+     * Used for "Back to [X]" UI display.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    sourceDashboardTitle?: string;
+    /**
+     * Target dashboard ID for drill-through navigation.
+     * Filters only apply when current dashboard matches this ID.
+     * Prevents filters from applying to source dashboard during navigation.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    targetDashboardId?: string;
+}
+
 declare interface InteractionTargetOverride {
     applyToCardIds?: string[] | null;
     excludeCardIds?: string[] | null;
@@ -2439,7 +2653,7 @@ declare type MatrixAxisLevelDescriptor = {
     fieldKey: string;
     label: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -2554,7 +2768,7 @@ declare type MatrixMeasureDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -2568,7 +2782,7 @@ declare type MatrixMeasureSemantics = {
 } | {
     kind: 'semiAdditive';
     aggregate?: SemaphorAggregateFunction;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
 } | {
     kind: 'nonAdditive';
     aggregate?: SemaphorAggregateFunction;
@@ -2762,15 +2976,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;
@@ -2786,6 +2991,17 @@ declare type NumericCanonicalFormat = {
     percentValueMode?: 'fraction' | 'whole';
 };
 
+declare type NumericPresentationTarget = {
+    kind: 'metric';
+    metricId: string;
+} | {
+    kind: 'column';
+    columnKey: string;
+} | {
+    kind: 'matrix_measure';
+    measureId: string;
+};
+
 declare type OldFilterValue = string | number | null | (string | number)[] | RangeValue;
 
 export declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
@@ -2841,6 +3057,11 @@ 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 {
@@ -2849,7 +3070,8 @@ export declare interface PivotColumnSchema {
     metricId: string;
     metricName: string;
     metricLabel?: string;
-    pivotValues: string[];
+    pivotValues: SemaphorPivotValue[];
+    pivotFieldIds?: string[];
     pivotFields?: string[];
     displayLabel?: string;
     isPivotColumn?: boolean;
@@ -2883,6 +3105,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.
@@ -2896,16 +3127,27 @@ export declare type Placeholders = {
 
 export declare type PluginType = 'custom' | 'standard';
 
+declare type PresentationScope = {
+    dashboardId: string;
+    cardId?: string;
+    attachmentIndex?: number;
+};
+
 export declare type PreviewBriefingPlanResponse = {
     plan: BriefingPreviewPlan;
 };
 
-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;
@@ -2929,6 +3171,11 @@ 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;
@@ -3060,7 +3307,23 @@ export declare type ResolvedDocumentInput = {
     exports: Record<string, string | number | boolean | null>;
 };
 
-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;
@@ -3070,13 +3333,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;
@@ -3098,6 +3368,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 type RunBriefingNowRequest = {
     requestId: string;
 };
@@ -3121,6 +3395,8 @@ export declare type RunBriefingPreviewResponse = {
     dispatch: BriefingDispatchResult | null;
 };
 
+export declare type ScalarFormatSpec = Exclude<FormatSpec, TemporalBucketFormat>;
+
 export declare type SelectedEntities = SelectedEntity[];
 
 export declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
@@ -3155,6 +3431,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 SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
 
 declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
@@ -3218,7 +3512,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -3269,7 +3563,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -3385,6 +3679,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -3420,7 +3716,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -3433,6 +3729,30 @@ declare type SemaphorPaginationMetadata = {
     hasPrevPage: boolean;
 };
 
+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 type SemaphorQueryPath = 'query_spec' | 'sql' | 'sql_python';
@@ -3441,36 +3761,30 @@ declare type SemaphorRelationshipHint = {
     relationshipIds?: string[];
 };
 
-declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
-    kind: 'semantic';
-}>;
-
-declare type SemaphorSourceRef = {
-    kind: 'semantic';
-    domainId: string;
-    datasetName: string;
-    datasetId?: string;
-    label?: string;
-    connectionId?: string;
-} | {
-    kind: 'physical';
-    connectionId: string;
-    connectionType?: string;
-    tableName: string;
-    databaseName?: string;
-    schemaName?: string;
-    label?: string;
-    dialect?: SemaphorDialect;
-} | {
-    kind: 'sql';
-    connectionId: string;
-    dialect?: SemaphorDialect;
-    label?: string;
+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 SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
-
-declare type SemaphorValueFormat = {
+declare type SemaphorScalarValueFormat = {
     type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
     minimumFractionDigits?: number;
     maximumFractionDigits?: number;
@@ -3507,6 +3821,35 @@ declare type SemaphorValueFormat = {
     suffix?: string;
 };
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
+
 export declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
@@ -4139,6 +4482,7 @@ export declare type TDataColumn = {
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
+    granularity?: TimeGranularity;
     sourceField?: string;
     aggregate?: AggregateFunction;
 };
@@ -4241,8 +4585,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;
@@ -4428,6 +4812,12 @@ export declare type THeatmapConfig = {
 
 export declare type Theme = 'dark' | 'light' | 'system';
 
+declare interface TimeComparison {
+    type: 'previous_year' | 'previous_period';
+    offset: number;
+    granularity: TimeGranularity;
+}
+
 declare interface TimeDrillStep {
     granularity: TimeGranularity;
     next?: TimeGranularity;
@@ -4435,7 +4825,7 @@ 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.