react-semaphor 0.1.424 → 0.1.426

package/dist/types/main.d.ts

@@ -2,11 +2,11 @@ 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-grid-layout';
+import { default as default_2 } from 'react';
+import { default as default_3 } from 'react-grid-layout';
 import { FetchStatus } from '@tanstack/query-core';
 import { FontSpec } from 'chart.js';
-import { JSX } from 'react/jsx-runtime';
-import { JSX as JSX_2 } from 'react';
+import { JSX } from 'react';
 import { JSXElementConstructor } from 'react';
 import { QueryObserverResult } from '@tanstack/query-core';
 import * as React_2 from 'react';
@@ -45,8 +45,9 @@ declare type Actions_2 = {
     removeDashboardInput: (inputId: string) => void;
     setDefaultDashboardInputValues: (values: DashboardInputValues | undefined) => void;
     setDashboardInputValues: (values: DashboardInputValues) => void;
-    setDashboardInputValuesAreAuthoritative: (isAuthoritative: boolean) => void;
     setDashboardInputSlot: (input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget, slot: DashboardInputSlot) => void;
+    setDashboardInputComparisonSelection: (input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget, selection: GlobalDateComparisonSelection) => void;
+    resetDashboardInputComparisonSelection: (input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget) => void;
     clearDashboardInputSlot: (input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget) => void;
     removeDashboardInputSlot: (input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget) => void;
     setDashboardControlsModel: (controls: ControlDefinition[], defaultValues?: Record<string, unknown>, options?: DashboardControlsModelOptions) => void;
@@ -71,13 +72,13 @@ declare type Actions_2 = {
     setDashboard: (dashboard: TDashboard, options?: {
         semanticExecutionPayload?: SemanticExecutionPayload;
         dashboardInputValues?: DashboardInputValues;
-        dashboardInputValuesAreAuthoritative?: boolean;
+        dashboardInputReferenceTime?: string;
     }) => void;
     setDashboardWithFilterValues: (dashboard: TDashboard, filterValues: TFilterValue[], runtimeOverrides?: Record<string, unknown>, options?: {
         selectedSheetId?: string | null;
         semanticExecutionPayload?: SemanticExecutionPayload;
         dashboardInputValues?: DashboardInputValues;
-        dashboardInputValuesAreAuthoritative?: boolean;
+        dashboardInputReferenceTime?: string;
     }) => void;
     hydrateRuntimeControlValues: (dashboard: TDashboard, runtimeOverrides?: Record<string, unknown>) => void;
     mergeSemanticExecutionPayload: (semanticExecutionPayload: SemanticExecutionPayload) => void;
@@ -103,8 +104,8 @@ declare type Actions_2 = {
     setDocumentInputControlValue: (sheetId: string, inputId: string, value: unknown) => void;
     clearDocumentInputRuntime: (sheetId?: string) => void;
     setSelectedSheetId: (sheetId: string | null) => void;
-    setSheetLayout: (sheetId: string, layout: default_2.Layout[]) => void;
-    setSheetLayouts: (sheetId: string, layouts: default_2.Layouts) => void;
+    setSheetLayout: (sheetId: string, layout: default_3.Layout[]) => void;
+    setSheetLayouts: (sheetId: string, layouts: default_3.Layouts) => void;
     setSelectedCardId: (sheetId: string, cardId: string | null) => void;
     setSelectedFrameId: (frameId: string) => void;
     clearSelectedFrameId: () => void;
@@ -179,8 +180,8 @@ declare type Actions_2 = {
     getSelectedFrame: () => TFrame | undefined;
     getCardFrame: (cardId: string) => TFrame | undefined;
     getCardSheet: (cardId: string) => TSheet | undefined;
-    getSelectedSheetLayout: () => default_2.Layout[] | undefined;
-    getSelectedSheetLayouts: () => default_2.Layouts | undefined;
+    getSelectedSheetLayout: () => default_3.Layout[] | undefined;
+    getSelectedSheetLayouts: () => default_3.Layouts | undefined;
     handleDataPointClickAction: (card: TCard, dataPoint: any) => void;
     addBaseQuery: (baseQuery: TBaseQuery) => void;
     removeBaseQuery: (baseQueryId: string) => void;
@@ -199,7 +200,6 @@ declare type Actions_3 = TableActions & ExplorerActions & DrillActions & {
     /** Resets the editor store to its initial state. Called when loading a new dashboard. */
     resetEditorStore: () => void;
     setEditorFilterMode: (filterColumnName: string, filterMode: 'include' | 'exclude') => void;
-    setLowerIsBetter: (lowerIsBetter: boolean) => void;
     setValueAlignment: (valueAlignment: 'left' | 'center') => void;
     clearEditorFilter: (filterColumn: FilterByColumn) => void;
     removeEditorFilter: (filterColumn: FilterByColumn) => void;
@@ -460,6 +460,10 @@ declare type AsyncMutation<TInput, TOutput> = {
     mutateAsync: (input: TInput) => Promise<TOutput>;
 };
 
+export declare type AuthoritativeExportFormattingConfig = ExportFormattingConfig & {
+    comparisonPresentation: ComparisonPresentationSpec;
+};
+
 export declare type AuthToken = {
     accessToken: string;
     refreshToken?: string;
@@ -1212,7 +1216,7 @@ export declare type CalendarContext = {
     };
 };
 
-export declare function CalendarPreferencesDialog({ open, onOpenChange, }: CalendarPreferencesDialogProps): JSX.Element;
+export declare function CalendarPreferencesDialog({ open, onOpenChange, }: CalendarPreferencesDialogProps): default_2.JSX.Element;
 
 declare interface CalendarPreferencesDialogProps {
     open: boolean;
@@ -1237,6 +1241,8 @@ export declare type CancelBriefingRunResponse = {
  */
 export declare function cancelExport(apiServiceUrl: string, token: string, exportId: string): Promise<void>;
 
+declare type CanonicalDurationUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+
 export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | DurationCanonicalFormat | StringCanonicalFormat;
 
 export declare interface CardConfig {
@@ -1300,9 +1306,6 @@ export declare interface CardConfig {
      * Configuration for on-click dashboard filters triggered by this card.
      */
     clickFilterInteractions?: ClickFilterInteraction[];
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
-    targetValue?: number;
-    showComparisonInLegend?: boolean;
     showTrendline?: boolean;
     trendlineWindow?: number;
     trendlineGranularity?: 'day' | 'week' | 'month';
@@ -1522,7 +1525,7 @@ export declare function Combobox({ name, items, value, onChange, isLoading, isEr
     refetch: () => void;
     className?: string;
     showNone?: boolean;
-}): JSX.Element;
+}): React_2.JSX.Element;
 
 declare type ComboBoxOption = {
     id: number | string;
@@ -1530,33 +1533,50 @@ declare type ComboBoxOption = {
     [key: string]: number | string;
 };
 
-export declare interface ComparisonMetadataEntry {
-    /** Type of comparison being performed */
-    type: 'previous_period' | 'same_period_last_year' | 'start_vs_end' | 'target';
-    /** Display name for the metric (UI convenience) */
-    displayName?: string;
-    /** Human-readable comparison label (UI convenience) */
-    displayLabel?: string;
-    /** Current period date range */
-    currentPeriod?: {
-        /** ISO date string */
-        start: string;
-        /** ISO date string */
-        end: string;
-    };
-    /** Comparison period date range */
-    comparisonPeriod?: {
-        /** ISO date string */
-        start: string;
-        /** ISO date string */
-        end: string;
-    };
-}
+declare type ComparisonAvailability = {
+    status: 'available';
+} | {
+    status: 'unavailable';
+    reason: ComparisonUnavailableReason;
+    traceId?: string;
+};
 
-export declare type ComparisonMetadataMap = Record<string, ComparisonMetadataEntry>;
+export declare type ComparisonMetadataEntry = MetricComparisonMetadataEntry;
+
+/** Keyed by MetricComparisonOutput.outputId, never by a display label. */
+export declare type ComparisonMetadataMap = MetricComparisonMetadataMap;
 
 declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
 
+declare type ComparisonPresentationSpec = {
+    /** Defaults to difference. */
+    displayMode?: 'difference' | 'percent_change' | 'both' | 'ratio';
+    /** Defaults to true. This controls display, not baseline selection. */
+    showComparison?: boolean;
+    /** Percent/ratio precision. Defaults to the surface formatter; valid range is 0..6. */
+    precision?: number;
+    /** Defaults to arrow_badge. */
+    indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
+    /** Defaults to true. */
+    showColor?: boolean;
+    position?: 'left' | 'right' | 'top';
+    /** Defaults to false. */
+    conditionalLabel?: boolean;
+    labelName?: string;
+    conditionalLabels?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+    colors?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+};
+
+declare type ComparisonUnavailableReason = 'finite_current_window_required' | 'current_window_not_started' | 'temporal_binding_missing' | 'temporal_binding_ambiguous' | 'temporal_binding_invalid' | 'unsupported_output_shape' | 'unsupported_raw_sql' | 'insufficient_history' | 'invalid_comparison_spec' | 'comparison_execution_failed';
+
 declare type ConditionalFormatCondition = {
     kind: 'comparison';
     columnId: string;
@@ -1781,10 +1801,12 @@ export declare interface CreateExportRequest {
     cardControlDefinitions?: ControlDefinition[];
     controlBindings?: ControlBinding[];
     resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    globalDateComparison?: GlobalDateComparisonContext;
+    calendarContext?: CalendarContext;
     timezone?: string;
     totalRows: number;
     format: ExportFormat;
-    formatOptions?: ExportFormattingConfig;
+    formatOptions: AuthoritativeExportFormattingConfig;
 }
 
 /** Response from creating an export job */
@@ -1907,6 +1929,14 @@ export declare interface DashboardCreateDialogBaseProps {
     initialDomainId?: string;
 }
 
+declare type DashboardDateComparisonOwner = {
+    kind: 'global_date';
+} | {
+    kind: 'field_date';
+    filterId: string;
+    label: string;
+};
+
 export declare type DashboardEventHandlers = {
     onExportData?: (payload: ExportDataPayload) => void;
 };
@@ -2054,11 +2084,17 @@ export declare type DashboardInputScope = {
     sectionIds: string[];
 };
 
-export declare type DashboardInputSlot = {
+export declare type DashboardInputSlot = ({
     status: 'set';
     value: DashboardInputValue;
-} | {
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | ({
     status: 'cleared';
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | {
+    status?: never;
+    value?: never;
+    comparisonSelection: GlobalDateComparisonSelection;
 };
 
 export declare type DashboardInputTextContent = Array<{
@@ -2323,8 +2359,8 @@ export declare type DashboardStore = {
     cardControlValuesMap: Record<string, Record<string, unknown>>;
     /** Runtime-only dashboard input values keyed by input runtime scope. */
     dashboardInputValues: DashboardInputValues;
-    /** True when dashboardInputValues came from a strict execution snapshot. */
-    dashboardInputValuesAreAuthoritative: boolean;
+    /** Fixed execution clock from a strict dashboard input replay snapshot. */
+    dashboardInputReferenceTime?: string;
     semanticExecutionPayload: SemanticExecutionPayload;
     drillHistory: Array<{
         sourceDashboardId: string;
@@ -2520,7 +2556,6 @@ export declare interface DetailTableBackupConfig {
         function: AggregateFunction;
         pivotLevel: string | 'ALL';
     }>;
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
 }
 
 export declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
@@ -3029,18 +3064,16 @@ export declare type DroppableId = 'droppable-group-by' | 'droppable-metric';
 
 declare type DurationCanonicalFormat = {
     type: 'duration';
-    inputUnit?: DurationUnit;
+    inputUnit?: CanonicalDurationUnit;
     outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: DurationUnit;
-    smallestUnit?: DurationUnit;
+    largestUnit?: CanonicalDurationUnit;
+    smallestUnit?: CanonicalDurationUnit;
     maxUnits?: number;
     prefix?: string;
     suffix?: string;
     negativeStyle?: 'minus' | 'parentheses';
 };
 
-declare type DurationUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-
 export declare interface DynamicDrillEvent extends BaseInteractionEvent {
     interactionMode: 'dynamicDrill';
     filterGroups: ClickFilterConditionGroup[];
@@ -3230,6 +3263,8 @@ export declare interface ExportFormattingConfig {
     includeHeaders: boolean;
     columnSettings?: Record<string, unknown>;
     visibleColumns?: string[];
+    columnLabels?: Record<string, string>;
+    comparisonPresentation?: ComparisonPresentationSpec;
 }
 
 /** Export job from list endpoint */
@@ -3273,7 +3308,7 @@ export declare interface ExportJobStatus {
  * - Completed: Download button with file size
  * - Failed: Error message with dismiss option
  */
-export declare function ExportNotificationItem({ export: exp, onRemove, }: ExportNotificationItemProps): JSX.Element;
+export declare function ExportNotificationItem({ export: exp, onRemove, }: ExportNotificationItemProps): default_2.JSX.Element;
 
 declare interface ExportNotificationItemProps {
     /** The export data to display */
@@ -3288,7 +3323,7 @@ declare interface ExportNotificationItemProps {
  * Displays all active and recent exports with their status,
  * progress, and download options.
  */
-export declare function ExportNotificationList(): JSX.Element;
+export declare function ExportNotificationList(): default_2.JSX.Element;
 
 export declare type ExportStatus = 'pending' | 'processing' | 'chunking' | 'compacting' | 'completed' | 'failed' | 'cancelled';
 
@@ -3594,7 +3629,8 @@ export declare function getColumnDataType(column: TDataColumn): string;
 export declare type GetDashboardResponse = {
     dashboard: TDashboard;
     lenses: TLens[];
-    filterValues?: TFilterValue[];
+    filterValues?: TFilterValue[] | null;
+    inputValues?: LensInputValuesSnapshot | null;
     defaultLensId?: string;
     assistantProfileId?: string;
     semanticExecutionPayload: SemanticExecutionPayload;
@@ -3625,7 +3661,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): "string" | "number" | "date" | "boolean";
+export declare function getFilterValueType(filter: TFilter): "date" | "string" | "number" | "boolean";
 
 export declare function getFormattedTableNameForQuery({ schemaName, tableName, modelName, databaseName, capabilities, connectionType, }: {
     schemaName: string;
@@ -3653,6 +3689,21 @@ export declare function getQualifiedTableName({ schemaName, tableName, databaseN
 
 export declare function getSql(config: SqlGen, schemaName: string, tableName: string, modelName: string, databaseName: string, capabilities: TDbCapabilities, qualifiedEntityName?: string): string | undefined;
 
+declare type GlobalDateComparisonContext = {
+    selection: GlobalDateComparisonSelection;
+    inheritGlobalComparison?: false;
+    owner?: DashboardDateComparisonOwner;
+    /** Fixed execution clock carried by authoritative dashboard replay snapshots. */
+    referenceTime?: string;
+};
+
+declare type GlobalDateComparisonSelection = {
+    mode: 'off';
+} | {
+    mode: 'period';
+    spec: ViewerPeriodComparisonSpec;
+};
+
 export declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
 
 export declare interface GroupByColumn extends BaseColumn {
@@ -3915,7 +3966,12 @@ export declare interface JoinPlan {
 export declare type KPICardProps = {
     card: TCard;
     isLoading?: boolean;
-    renderFilterInfo?: () => JSX_2.Element | null;
+    renderFilterInfo?: () => JSX.Element | null;
+};
+
+export declare type LensInputValuesSnapshot = {
+    generatedAt: string;
+    dashboardInputValues: DashboardInputValues;
 };
 
 export declare type Level = 'database' | 'schema' | 'table';
@@ -3966,6 +4022,14 @@ declare type ManagementStore = {
     actions: Actions;
 };
 
+/**
+ * A comparison input proven to be present in the card's executed filter set.
+ * Ownership and UI coverage must consume this stage, never source inputs.
+ */
+export declare type MaterializedDashboardDateComparisonInput = ResolvedDashboardDateComparisonInput & {
+    effectiveFilterValue: TFilterValue;
+};
+
 declare type MatrixAxisLevelDescriptor = {
     instanceId: string;
     fieldKey: string;
@@ -4335,6 +4399,80 @@ export declare interface MetricColumn extends BaseColumn {
     aliasTemplate?: string;
 }
 
+declare type MetricComparisonConfig = {
+    mode: 'off';
+} | {
+    mode: 'explicit';
+    spec: MetricComparisonSpec;
+};
+
+declare type MetricComparisonMetadataEntry = {
+    type: MetricComparisonSpec['kind'];
+    displayName?: string;
+    displayLabel?: string;
+    output: MetricComparisonOutput;
+};
+
+/** Keyed by MetricComparisonOutput.outputId, never by source id or label. */
+declare type MetricComparisonMetadataMap = Record<MetricComparisonOutput['outputId'], MetricComparisonMetadataEntry>;
+
+declare type MetricComparisonOutput = MetricComparisonOutputBase & ({
+    request: ResolvedMetricComparisonRequest;
+    availability: {
+        status: 'available';
+    };
+    comparisonColumnKey: string;
+    deltaColumnKey: string;
+    percentChangeColumnKey: string;
+    ratioColumnKey: string;
+    rowStatusColumnKey?: string;
+    currentBucketColumnKey?: string;
+    comparisonSourceBucketColumnKey?: string;
+} | {
+    request?: ResolvedMetricComparisonRequest;
+    availability: Extract<ComparisonAvailability, {
+        status: 'unavailable';
+    }>;
+    comparisonColumnKey?: never;
+    deltaColumnKey?: never;
+    percentChangeColumnKey?: never;
+    ratioColumnKey?: never;
+    rowStatusColumnKey?: never;
+    currentBucketColumnKey?: never;
+    comparisonSourceBucketColumnKey?: never;
+});
+
+declare type MetricComparisonOutputBase = {
+    outputId: string;
+    metricId: string;
+    metricAlias: string;
+    currentColumnKey: string;
+    windowGrain?: MetricComparisonWindowGrain;
+    currentWindow?: ResolvedDateWindow;
+    comparisonWindow?: ResolvedDateWindow;
+    referenceTime?: string;
+    temporalField?: SemaphorFieldRef;
+};
+
+declare type MetricComparisonPolarity = 'higher_is_better' | 'lower_is_better' | 'neutral';
+
+declare type MetricComparisonSpec = {
+    kind: 'previous_period';
+    offsetPeriods?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'previous_year';
+    offsetYears?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'target';
+    targetValue: number;
+};
+
+declare type MetricComparisonWindowGrain = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
 export declare interface MetricField extends Field {
     role: 'metric';
     aggregate?: AggregateFunction;
@@ -4383,9 +4521,10 @@ export declare interface MetricField extends Field {
      * pre-aggregated metric input.
      */
     isPreAggregated?: boolean;
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'start_vs_end' | 'target';
-    comparisonDisplay?: 'column' | 'inline' | 'hover';
-    targetValue?: number;
+    comparison?: MetricComparisonConfig;
+    comparisonPolarity?: MetricComparisonPolarity;
+    /** Governed runtime annotation. When present, authoring polarity is read-only. */
+    semanticComparisonPolarity?: MetricComparisonPolarity;
 }
 
 declare interface MinimalResourceForSharing {
@@ -4432,7 +4571,7 @@ export declare function normalizeDashboardForDirtyCheck(dashboard: TDashboard |
  */
 export declare function NotificationBell({ variant, }: {
     variant?: 'outline' | 'ghost';
-}): JSX.Element;
+}): default_2.JSX.Element;
 
 export declare type NumberAxisFormat = {
     decimalPlaces?: number;
@@ -4452,6 +4591,15 @@ 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;
@@ -4524,6 +4672,7 @@ export declare interface PivotByField extends Field {
 
 export declare interface PivotColumnSchema {
     alias: string;
+    metricAlias?: string;
     metricId: string;
     metricName: string;
     metricLabel?: string;
@@ -4676,6 +4825,20 @@ export declare function resolveDatamodelName(datamodelName: string): string;
 
 export declare const resolveDataType: (value: any) => string;
 
+export declare type ResolvedDashboardDateComparisonInput = {
+    inputId: string;
+    filterId: string;
+    label: string;
+    filter: TFilter;
+    /**
+     * The active value before execution-only canonicalization. Comparison
+     * ownership uses this value as provenance evidence and must fail closed
+     * when its filter or field identity does not match the definition.
+     */
+    filterValue?: TFilterValue;
+    selection: GlobalDateComparisonSelection;
+};
+
 export declare type ResolvedDashboardInput = {
     id: string;
     kind: 'filter' | 'control';
@@ -4691,6 +4854,7 @@ export declare type ResolvedDashboardInput = {
     control?: ControlDefinition;
     controlValue?: unknown;
     missingRequiredValue?: boolean;
+    comparisonSelection?: GlobalDateComparisonSelection;
 };
 
 export declare type ResolvedDashboardInputContext = {
@@ -4702,10 +4866,18 @@ export declare type ResolvedDashboardInputContext = {
     controlBindings: ControlBinding[];
     controlValues: Record<string, unknown>;
     variablesByName: Record<string, ResolvedDashboardInput>;
+    globalDateComparisonSelection?: GlobalDateComparisonSelection;
+    dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
     variablesById: Record<string, ResolvedDashboardInput>;
     missingRequiredInputs: ResolvedDashboardInput[];
 };
 
+declare type ResolvedDateWindow = {
+    startInclusive: string;
+    endExclusive: string;
+    timezone: string;
+};
+
 export declare type ResolvedDocumentInput = {
     inputId: string;
     variableName: string;
@@ -4716,6 +4888,15 @@ export declare type ResolvedDocumentInput = {
     exports: Record<string, string | number | boolean | null>;
 };
 
+declare type ResolvedMetricComparisonRequest = {
+    source: 'explicit';
+    spec: MetricComparisonSpec;
+} | {
+    source: 'inherited';
+    spec: ViewerPeriodComparisonSpec;
+    owner?: DashboardDateComparisonOwner;
+};
+
 declare type ResolvedPrimaryDateField = {
     sourceDataset: string;
     sourceField: string;
@@ -4726,6 +4907,8 @@ declare type ResolvedPrimaryDateField = {
     entityName: string;
     entityType: string;
     dataType: string;
+    /** Canonical dataset coordinates stamped by the temporal grounding boundary. */
+    source?: SemaphorSourceRef;
     dateFormat?: string;
     customFormat?: string;
     defaultGranularity?: TimeGranularity;
@@ -5910,6 +6093,11 @@ export declare type TCardContext = {
 };
 
 export declare type TCardPreferences = {
+    comparisonPresentation?: ComparisonPresentationSpec;
+    /** Absence means eligible metrics inherit the Global Date comparison. */
+    inheritGlobalComparison?: false;
+    /** Separate two-metric KPI feature; defaults to false. */
+    metricPairComparisonEnabled?: boolean;
     onClickFilter?: FilterOnClick[];
     filterOnClick?: boolean;
     filterOnClickField?: string;
@@ -5982,43 +6170,14 @@ export declare type TCardPreferences = {
         colorScale?: string;
     };
     kpiVisualOptions?: {
-        lowerIsBetter?: boolean;
         countryLogoId?: string;
         valueAlignment?: 'left' | 'center';
         formatOptions?: TFormatOptions;
-        metricComparison?: {
-            enabled?: boolean;
-            calculationType?: 'difference' | 'change' | 'change_difference' | 'ratio';
-            formatOptions?: TFormatOptions;
-            showArrow?: boolean;
-            showColor?: boolean;
-            conditionalLabel?: boolean;
-            labelName?: string;
-            position?: 'left' | 'right' | 'top';
-            conditionalLabels?: {
-                increase?: string;
-                decrease?: string;
-                noChange?: string;
-            };
-            colorConfig?: {
-                increase?: 'green' | 'red' | 'neutral' | string;
-                decrease?: 'green' | 'red' | 'neutral' | string;
-                noChange?: 'green' | 'red' | 'neutral' | string;
-            };
-        };
-    };
-    tableVisualOptions?: {
-        metricComparison?: {
-            calculatedAs?: 'difference' | 'change' | 'change_difference' | 'ratio';
-            indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
-            formatOptions?: TFormatOptions;
-            colors?: {
-                increase?: 'green' | 'red' | 'neutral' | string;
-                decrease?: 'green' | 'red' | 'neutral' | string;
-                neutral?: 'green' | 'red' | 'neutral' | string;
-            };
-            lowerIsBetter?: boolean;
-        };
+        /**
+         * Presentation-only polarity for a query-backed KPI's manually returned
+         * current/prior value pair. Governed KPIs use per-metric polarity instead.
+         */
+        queryComparisonPolarity?: MetricComparisonPolarity;
     };
     pivotTableOptions?: {
         showRowTotals?: boolean;
@@ -6515,7 +6674,8 @@ export declare type TLens = {
     id: string;
     name: string;
     template?: string;
-    filterValues?: TFilterValue[];
+    filterValues?: TFilterValue[] | null;
+    inputValues?: LensInputValuesSnapshot | null;
     isDefault?: boolean;
     shared?: boolean;
 };
@@ -6940,12 +7100,12 @@ export declare function useCard(cardId: string): {
     queryKey: string[];
     queryRequestPayload: Record<string, unknown> | undefined;
     pagination: PaginationMetadata | undefined;
-    comparisonMetadata: ComparisonMetadataMap | undefined;
+    comparisonMetadata: MetricComparisonMetadataMap | undefined;
     resolvedPrimaryDateField: ResolvedPrimaryDateField | undefined;
 };
 
 export declare function useCardSummary(card: TCard, options?: UseCardSummaryOptions): {
-    data: SummaryResponse | undefined;
+    data: NoInfer<SummaryResponse> | undefined;
     isLoading: boolean;
     isFetching: boolean;
     isError: boolean;
@@ -6977,11 +7137,11 @@ export declare function useDashboardById(dashboardId: string, options?: {
 }): UseQueryResult<any, Error>;
 
 export declare function useDashboardQuery(): {
-    data: GetDashboardResponse | null | undefined;
+    data: NoInfer<GetDashboardResponse | null> | undefined;
     isLoading: boolean;
     isFetching: boolean;
     isError: boolean;
-    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<GetDashboardResponse | null, Error>>;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<NoInfer<GetDashboardResponse | null>, Error>>;
     dashboardIdToFetch: string | null;
 };
 
@@ -6991,12 +7151,12 @@ setState(nextStateOrUpdater: DashboardStore | ((state: WritableDraft<DashboardSt
 }>;
 
 export declare function useDashboardSummary(): {
-    data: SummaryResponse | undefined;
+    data: NoInfer<SummaryResponse> | undefined;
     isLoading: boolean;
     isFetching: boolean;
     isError: boolean;
     error: Error | null;
-    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<SummaryResponse, Error>>;
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<NoInfer<SummaryResponse>, Error>>;
     refresh: UseMutateAsyncFunction<SummaryResponse, Error, void, unknown>;
     isRefreshing: boolean;
     applyAction: (action: SummaryAction) => Promise<void>;
@@ -7242,6 +7402,10 @@ export declare function useTextFilterHook(filterId: string): {
 
 export declare function validateBriefingFormDraft(draft: BriefingFormDraft): BriefingFormValidationResult;
 
+declare type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
+    kind: 'previous_period' | 'previous_year';
+}>;
+
 export declare function Visual(props: VisualProps): JSX.Element;
 
 /**