react-semaphor 0.1.444 → 0.1.445

package/dist/types/format-utils.d.ts

@@ -1,19 +1,47 @@
-export declare interface AggregateExportConfig {
-    groupByColumns: GroupByField[];
-    pivotSchema: PivotColumnSchema[];
-    rowAggregates?: RowAggregate[];
-    includeSubtotals: boolean;
-    includeGrandTotal: boolean;
+export declare const AGGREGATE_TOTAL_MEMBER_MARKER: "__TOTAL__";
+
+export declare type AggregateGroupCellPlacement = 'value' | 'label' | 'empty';
+
+export declare interface AggregateGroupCellPresentation<T = string> {
+    columnKey: string;
+    text: T | string;
+    placement: AggregateGroupCellPlacement;
+    colSpan: number;
 }
 
-export declare interface AggregateRowData extends Record<string, unknown> {
-    isSubtotal?: boolean;
-    isGrandTotal?: boolean;
-    subtotalLevel?: string;
-    subtotalContext?: {
-        groupByValues?: Record<string, unknown>;
-    };
-    aggregate?: string;
+export declare interface AggregateGroupRowPresentation<T = string> {
+    kind: 'data' | 'subtotal' | 'grand-total';
+    cells: AggregateGroupCellPresentation<T>[];
+}
+
+/**
+ * React-free aggregate-table row presentation policy shared by browser and
+ * delivery adapters. Canonical tuple values and row metadata remain identity;
+ * this module owns authoritative group keys and group-cell placement.
+ */
+export declare interface AggregateSubtotalLabelInput {
+    aggregateFunction: string;
+    customLabel?: string;
+    levelValue: unknown;
+    formatValue?: (value: unknown) => string;
+}
+
+export declare interface AggregateTablePresentationColumnKeyMap {
+    byRole: Readonly<{
+        groupby?: Readonly<Record<string, {
+            rawKey: string;
+            outputKey?: string;
+        }>>;
+    }>;
+}
+
+export declare interface AggregateTablePresentationContext {
+    groupColumnKeys: string[];
+    rowAggregates: Array<{
+        function: string;
+        groupLevel: string;
+        label?: string;
+    }>;
 }
 
 /**
@@ -30,7 +58,8 @@ export declare function buildFlatTableExportTotalsFooter(params: {
     totalsByColumnId: FlatTableExportTotalsByColumnId;
     visibleColumns: readonly string[];
     labelColumnKey?: string;
-    resolvedNumericFormats: readonly NumericPresentationSnapshotEntry[];
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
     useFormattedValues: boolean;
     delimiter: string;
 }): string;
@@ -46,7 +75,25 @@ declare type CalendarContext = {
 
 export 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 CanonicalPivotResultBase = {
+    columns: SemaphorResultColumn[];
+    columnKeyMap: QueryColumnKeyMap;
+    pivotResultContract: CanonicalPivotResultContract;
+};
+
+export declare type CanonicalPivotResultContract = {
+    version: 1;
+    expectedRoleFieldIds: PivotResultExpectedRoleFieldIds;
+    expectedMetricAliases: readonly string[];
+    columnKinds: Readonly<Record<string, PivotResultColumnKind>>;
+    columnClassifications: Readonly<Record<string, PivotResultColumnClassification | undefined>>;
+};
+
+export declare type CanonicalPivotResultState = 'loaded_empty' | 'loaded_valid';
+
+export declare type CanonicalPivotResultTransport = LoadedEmptyPivotResult | LoadedValidPivotResult;
 
 export declare interface ColorRange {
     min: number;
@@ -106,6 +153,16 @@ export declare interface ColumnSubtotalMeta {
     level: number;
 }
 
+export declare function createCanonicalPivotResultTransport(input: {
+    records: Record<string, unknown>[];
+    columns: SemaphorResultColumn[];
+    columnKeyMap: QueryColumnKeyMap;
+    expectedRoleFieldIds: PivotResultExpectedRoleFieldIds;
+    expectedMetricAliases?: readonly string[];
+    physicalPivotColumnKeys: readonly string[];
+    columnMetadata?: Readonly<Record<string, PivotResultColumnClassification | undefined>>;
+}): CanonicalPivotResultTransport;
+
 export declare interface CSVExportOptions {
     delimiter: ',' | ';' | '\t';
     includeHeaders: boolean;
@@ -140,6 +197,19 @@ export declare interface DateFormatOptions {
     locale?: string;
 }
 
+/**
+ * Derives the authored identity expectations stored in a canonical pivot
+ * lifecycle contract. Producers and cache-compatibility consumers must use
+ * this same projection so generated Count and repeated metric instances cannot
+ * drift across the transport seam.
+ */
+export declare function derivePivotResultContractExpectations(input: {
+    groupByFields?: readonly IdentifiedField[];
+    metricFields?: readonly IdentifiedMetricField[];
+    pivotByFields?: readonly IdentifiedField[];
+    detailFields?: readonly IdentifiedField[];
+}): PivotResultContractExpectations;
+
 export declare type DurationCanonicalFormat = {
     type: 'duration';
     inputUnit?: CanonicalDurationUnit;
@@ -202,6 +272,18 @@ export declare interface ExportFormattingConfig {
     visibleColumns: string[];
 }
 
+export declare function findResolvedNumericFormat(input: {
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    target: NumericPresentationTarget;
+}): NumericCanonicalFormat | undefined;
+
+export declare function findResolvedTemporalBucketFormat(input: {
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    target: TemporalBucketPresentationTarget;
+}): ResolvedTemporalBucketFormat | undefined;
+
 export declare type FlatTableExportTotalsBehavior = 'sum' | 'avg' | 'count' | 'label';
 
 export declare type FlatTableExportTotalsByColumnId = Record<string, string | number | null>;
@@ -216,15 +298,22 @@ export declare type FlatTableExportTotalsRequest = {
     }>;
 };
 
-/**
- * Format an aggregate table row for CSV export
- */
-export declare function formatAggregateRow(row: AggregateRowData, aggregateConfig: AggregateExportConfig, formattingConfig: ExportFormattingConfig): string[];
+export declare function formatAggregateGrandTotalLabel(aggregateFunction: string, customLabel?: string): string;
 
-/**
- * Format aggregate table data for CSV export
- */
-export declare function formatAggregateTableForCSV(data: AggregateRowData[], aggregateConfig: AggregateExportConfig, formattingConfig: ExportFormattingConfig): string[];
+export declare function formatAggregateGroupCell(input: {
+    row: Record<string, unknown>;
+    context: AggregateTablePresentationContext;
+    columnKey: string;
+    formatValue: (value: unknown, columnKey: string) => string;
+}): string;
+
+export declare function formatAggregateGroupRow(input: {
+    row: Record<string, unknown>;
+    context: AggregateTablePresentationContext;
+    formatValue: (value: unknown, columnKey: string) => string;
+}): string[];
+
+export declare function formatAggregateSubtotalLabel(input: AggregateSubtotalLabelInput): string;
 
 /**
  * Format a cell value for export based on column settings
@@ -375,10 +464,11 @@ export declare type FormattedMetricComparisonPart = {
     text: string | null;
 };
 
-/**
- * Generate headers for aggregate table export
- */
-export declare function generateAggregateHeaders(aggregateConfig: AggregateExportConfig): string[];
+export declare function formatTemporalBucket(input: {
+    value: TemporalBucketValue;
+    metadata: TemporalBucketMetadata;
+    format: ResolvedTemporalBucketFormat;
+}): string;
 
 /**
  * Generate multi-level headers for pivot table
@@ -406,6 +496,35 @@ export declare interface GroupByField {
     label?: string;
 }
 
+declare type IdentifiedField = {
+    id?: string;
+};
+
+declare type IdentifiedMetricField = IdentifiedField & MetricResultAliasInput;
+
+export declare function isAggregateTotalMemberMarker(value: unknown): value is typeof AGGREGATE_TOTAL_MEMBER_MARKER;
+
+export declare function isNumericCanonicalFormat(format: unknown): format is NumericCanonicalFormat;
+
+export declare function isPivotEmptyTupleAllowed(input: {
+    expectedPivotFieldIds: readonly string[];
+    classification?: PivotResultColumnClassification;
+}): boolean;
+
+export declare function isPivotSubtotalPrefix(classification: PivotResultColumnClassification | undefined): boolean;
+
+export declare function isTemporalBucketPreset(value: unknown): value is TemporalBucketPreset;
+
+export declare type LoadedEmptyPivotResult = CanonicalPivotResultBase & {
+    pivotResultState: 'loaded_empty';
+    records: [];
+};
+
+export declare type LoadedValidPivotResult = CanonicalPivotResultBase & {
+    pivotResultState: 'loaded_valid';
+    records: [Record<string, unknown>, ...Record<string, unknown>[]];
+};
+
 declare type LocaleStyle = 'short' | 'medium' | 'long';
 
 declare type MetricComparisonDirection = 'increase' | 'decrease' | 'no_change' | 'unknown';
@@ -425,6 +544,15 @@ declare type MetricComparisonEvaluation = {
 
 declare type MetricComparisonSentiment = 'favorable' | 'unfavorable' | 'neutral';
 
+declare type MetricResultAliasInput = {
+    alias?: string;
+    name: string;
+    entityName?: string;
+    role?: string;
+    aggregate?: string;
+    expression?: string;
+};
+
 declare type MonthAlignedFiscalCalendar = {
     kind: 'month_aligned';
     yearStartMonth: number;
@@ -450,15 +578,6 @@ export declare interface NumberFormatOptions {
     useSuffix?: boolean;
 }
 
-/**
- * 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
- */
 export declare type NumericCanonicalFormat = {
     type: 'number' | 'currency' | 'percent' | 'scientific';
     locale?: string;
@@ -485,21 +604,6 @@ export declare type NumericCanonicalFormatParseResult = {
     }>;
 };
 
-export declare type NumericPresentationExecutionSnapshot = {
-    reportContext: ReportRuntimeContext;
-    resolvedNumericFormats: NumericPresentationSnapshotEntry[];
-};
-
-export declare type NumericPresentationSnapshotEntry = {
-    scope: {
-        dashboardId: string;
-        cardId?: string;
-        attachmentIndex?: number;
-    };
-    target: NumericPresentationTarget;
-    format: NumericCanonicalFormat;
-};
-
 export declare type NumericPresentationTarget = {
     kind: 'metric';
     metricId: string;
@@ -518,18 +622,40 @@ export declare function objectsToCSV(data: Record<string, unknown>[], options?:
     columns?: string[];
 }): string;
 
+/**
+ * Parses the canonical pivot wire shape once. Downstream presentation and
+ * delivery consumers receive this discriminated result and do not infer
+ * lifecycle or repeat physical-member validation.
+ */
+export declare function parseCanonicalPivotResultTransport(input: PivotResultLifecycleInput): CanonicalPivotResultTransport;
+
+export declare type ParsedTemporalBucketValue = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+};
+
 export declare function parseFlatTableExportTotalsByColumnId(input: unknown, path?: string): FlatTableExportTotalsByColumnId;
 
 export declare function parseFlatTableExportTotalsRequest(input: unknown, path?: string): FlatTableExportTotalsRequest;
 
 export declare function parseNumericCanonicalFormat(input: unknown): NumericCanonicalFormatParseResult;
 
-export declare function parseNumericPresentationExecutionSnapshot(input: unknown): NumericPresentationExecutionSnapshot;
+export declare function parsePresentationExecutionSnapshot(input: unknown): PresentationExecutionSnapshot;
 
-export declare function parseNumericPresentationSnapshotEntries(input: unknown): NumericPresentationSnapshotEntry[];
+export declare function parsePresentationScope(input: unknown, path?: string): PresentationScope;
 
 export declare function parseResolvedNumericCanonicalFormat(input: unknown): NumericCanonicalFormatParseResult;
 
+export declare function parseResolvedPresentationEntries(input: unknown): ResolvedPresentationEntry[];
+
+export declare function parseResolvedTemporalBucketFormat(input: unknown): ResolvedTemporalBucketFormatParseResult;
+
+export declare function parseTemporalBucketValue(value: TemporalBucketValue, metadata: TemporalBucketMetadata): TemporalBucketValueParseResult;
+
 /**
  * Parse a date string with source timezone interpretation
  *
@@ -552,14 +678,6 @@ export declare interface PivotCellData {
     formatted?: string;
 }
 
-export declare interface PivotColumnSchema {
-    alias: string;
-    displayLabel?: string;
-    metricLabel?: string;
-    metricName?: string;
-    isMetricColumn: boolean;
-}
-
 export declare interface PivotExportConfig {
     groupByColumns: GroupByField[];
     pivotByColumns: PivotByColumn[];
@@ -571,6 +689,61 @@ export declare interface PivotExportConfig {
     showRowTotals: boolean;
 }
 
+export declare type PivotHeaderPresentation = {
+    memberLabels: string[];
+    metricLabel?: string;
+    flattenedLabel: string;
+};
+
+export declare class PivotHeaderPresentationError extends Error {
+    readonly code: 'missing_resolved_temporal_format';
+    readonly deliveryBlocking = true;
+    constructor(code: 'missing_resolved_temporal_format', message: string);
+}
+
+export declare type PivotHeaderPresentationMember = {
+    fieldId: string;
+    value: string | null;
+    temporalBucket?: TemporalBucketMetadata;
+};
+
+export declare type PivotHeaderPresentationMode = 'formatted' | 'canonical';
+
+export declare type PivotResultColumnClassification = {
+    isSubtotal?: boolean;
+    subtotalScope?: 'base' | 'pivot-value' | 'grand-total';
+};
+
+export declare type PivotResultColumnKind = 'row' | 'pivot_metric' | 'value';
+
+export declare type PivotResultContractExpectations = {
+    expectedRoleFieldIds: PivotResultExpectedRoleFieldIds;
+    expectedMetricAliases: string[];
+};
+
+export declare type PivotResultExpectedRoleFieldIds = Readonly<Partial<Record<QueryColumnKeyRole, readonly string[]>>>;
+
+export declare class PivotResultIdentityError extends Error {
+    readonly deliveryBlocking = true;
+    readonly code: "missing_pivot_member_identity";
+    constructor(message: string);
+}
+
+export declare class PivotResultLifecycleError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly code: "invalid_pivot_result_lifecycle";
+    readonly deliveryBlocking = true;
+    constructor(message: string, cause?: unknown | undefined);
+}
+
+declare type PivotResultLifecycleInput = {
+    pivotResultState?: unknown;
+    pivotResultContract?: unknown;
+    records?: unknown;
+    columns?: unknown;
+    columnKeyMap?: unknown;
+};
+
 export declare interface PivotRowData {
     fieldValues: string[];
     cells: Record<string, PivotCellData>;
@@ -578,6 +751,57 @@ export declare interface PivotRowData {
     isGrandTotal?: boolean;
 }
 
+/**
+ * Formats one physical aggregate group cell. Row metadata alone determines
+ * subtotal/grand-total ownership; null is always passed to the value formatter
+ * as a genuine blank member.
+ */
+export declare function presentAggregateGroupRow<T = string>(input: {
+    row: Record<string, unknown>;
+    context: AggregateTablePresentationContext;
+    formatValue: (value: unknown, columnKey: string) => T;
+    formatLabelValue?: (value: unknown, columnKey: string) => string;
+}): AggregateGroupRowPresentation<T>;
+
+export declare type PresentationExecutionSnapshot = {
+    reportContext: ReportRuntimeContext;
+    resolvedFormats: ResolvedPresentationEntry[];
+};
+
+export declare type PresentationScope = {
+    dashboardId: string;
+    cardId?: string;
+    attachmentIndex?: number;
+};
+
+/**
+ * React-free pivot header policy shared by interactive and delivery adapters.
+ * Canonical member values remain identity; this helper produces labels only.
+ */
+export declare function presentPivotHeader(input: {
+    members: readonly PivotHeaderPresentationMember[];
+    metricLabel?: string;
+    mode?: PivotHeaderPresentationMode;
+    resolveTemporalFormat?: (fieldId: string) => ResolvedTemporalBucketFormat | undefined;
+}): PivotHeaderPresentation;
+
+export declare interface QueryColumnKeyMap {
+    version: 1;
+    source: 'explorer';
+    byRole: QueryColumnKeyMapByRole;
+    byMetricAlias?: Record<string, QueryColumnKeyMapEntry>;
+}
+
+export declare type QueryColumnKeyMapByRole = Partial<Record<QueryColumnKeyRole, Record<string, QueryColumnKeyMapEntry>>>;
+
+export declare interface QueryColumnKeyMapEntry {
+    role: QueryColumnKeyRole;
+    rawKey: string;
+    outputKey?: string;
+}
+
+export declare type QueryColumnKeyRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
+
 declare const REPORT_PREFERENCE_SOURCES: readonly ["viewer_user", "viewer_tenant_user", "session_initial", "viewer_tenant", "viewer_organization", "system_default"];
 
 declare type ReportPreferenceSource = (typeof REPORT_PREFERENCE_SOURCES)[number];
@@ -593,6 +817,47 @@ declare type ReportRuntimeContext = {
     preferenceSources: ReportPreferenceSources;
 };
 
+export declare function requirePivotHeaderMembers(input: {
+    identity: SemaphorPivotResultColumnIdentity;
+    columnKey: string;
+    expectedPivotFieldIds?: readonly string[];
+    allowPrefix?: boolean;
+    allowEmpty?: boolean;
+}): readonly SemaphorPivotResultMember[];
+
+export declare function requirePivotResultColumnIdentities(columns: readonly {
+    key: string;
+    pivotIdentity?: SemaphorPivotResultColumnIdentity;
+}[], options: {
+    expectedPivotFieldIds: readonly string[];
+    columnClassifications?: Readonly<Record<string, PivotResultColumnClassification | undefined>>;
+    allowPrefixForColumn?: (column: {
+        key: string;
+        pivotIdentity?: SemaphorPivotResultColumnIdentity;
+    }) => boolean;
+    allowEmptyForColumn?: (column: {
+        key: string;
+        pivotIdentity?: SemaphorPivotResultColumnIdentity;
+    }) => boolean;
+}): void;
+
+/**
+ * Resolves saved field identity into the physical result keys used by rows.
+ * Missing groupByColumns is a valid metric-only aggregate-table shape.
+ */
+export declare function resolveAggregateTablePresentationContext(input: {
+    groupByColumns?: readonly unknown[];
+    rowAggregates?: readonly unknown[];
+    columnKeyMap?: AggregateTablePresentationColumnKeyMap;
+}): AggregateTablePresentationContext;
+
+/**
+ * Retains authored temporal presentation only when its grain is present and
+ * compatible. Boundary adapters decide whether an omitted result means
+ * rejecting the entire pair or preserving grain with automatic presentation.
+ */
+export declare function resolveApplicableTemporalBucketFormat(format: TemporalBucketFormat | undefined, granularity: SemaphorTimeGrain | undefined): TemporalBucketFormat | undefined;
+
 export declare function resolveCurrencyFractionDigits(locale: string, currency: string): Pick<NumericCanonicalFormat, 'minimumFractionDigits' | 'maximumFractionDigits'>;
 
 declare type ResolvedCalendarPreferenceSources = {
@@ -600,6 +865,40 @@ declare type ResolvedCalendarPreferenceSources = {
     weekStart: ReportPreferenceSource;
 };
 
+export declare type ResolvedNumericPresentationEntry = {
+    scope: PresentationScope;
+    target: NumericPresentationTarget;
+    format: NumericCanonicalFormat;
+};
+
+export declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry;
+
+export declare type ResolvedTemporalBucketFormat = TemporalBucketFormat & {
+    locale: string;
+};
+
+export declare type ResolvedTemporalBucketFormatParseResult = {
+    ok: true;
+    value: ResolvedTemporalBucketFormat;
+} | {
+    ok: false;
+    issues: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+
+export declare type ResolvedTemporalBucketPresentation = {
+    format: ResolvedTemporalBucketFormat;
+    source: 'card' | 'semantic' | 'automatic';
+};
+
+export declare type ResolvedTemporalBucketPresentationEntry = {
+    scope: PresentationScope;
+    target: TemporalBucketPresentationTarget;
+    format: ResolvedTemporalBucketFormat;
+};
+
 declare type ResolvedValueFormatPreferences = {
     locale: string;
     dateStyle: LocaleStyle;
@@ -620,8 +919,25 @@ declare type ResolvedValueFormatPreferenceSources = {
     defaultCurrency: ReportPreferenceSource;
 };
 
+/** Stable result-instance identity shared by query producers and consumers. */
+export declare function resolveMetricResultAlias(metric: MetricResultAliasInput): string;
+
 export declare function resolveNumericPresentation(authored: NumericCanonicalFormat, preferences: ResolvedValueFormatPreferences, boundCurrency?: string): NumericCanonicalFormat;
 
+export declare function resolveQueryColumnKeyMapEntry(columnKeyMap: QueryColumnKeyMap | undefined, fieldId: string, role: QueryColumnKeyRole): QueryColumnKeyMapEntry | undefined;
+
+export declare function resolveTemporalBucketPresentation(input: ResolveTemporalBucketPresentationInput): ResolvedTemporalBucketPresentation;
+
+export declare type ResolveTemporalBucketPresentationInput = {
+    metadata: TemporalBucketMetadata;
+    semanticFormat?: {
+        granularity: SemaphorTimeGrain;
+        format: TemporalBucketFormat;
+    };
+    cardFormat?: TemporalBucketFormat;
+    locale: string;
+};
+
 /**
  * Date formatting utilities with timezone support
  * IMPORTANT: No React imports allowed in this file
@@ -640,11 +956,166 @@ export declare function resolveNumericPresentation(authored: NumericCanonicalFor
  */
 export declare function resolveTimezone(columnTimezone: string | undefined, contextTimezone: string): string;
 
-export declare interface RowAggregate {
-    function: 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX';
-    groupLevel?: string;
+export declare function resolveUniqueQueryColumnKeyMapEntry(columnKeyMap: QueryColumnKeyMap | undefined, fieldId: string): QueryColumnKeyMapEntry | undefined;
+
+/** Stable field identity for the query builder's generated Count measure. */
+export declare const SEMAPHOR_GENERATED_COUNT_METRIC_ID: "__auto_count__";
+
+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 SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: SemaphorScalarValueFormat;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
+
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+declare type SemaphorFieldRef = {
+    name: string;
     label?: string;
-}
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+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 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 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 type StringCanonicalFormat = {
     type: 'string';
@@ -652,8 +1123,103 @@ export declare type StringCanonicalFormat = {
     suffix?: string;
 };
 
+export declare const TEMPORAL_BUCKET_PATTERN_TOKENS: readonly ["YYYY", "MMMM", "MMM", "YY", "MM", "DD", "HH", "mm", "ss"];
+
+declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
+export declare class TemporalBucketContractError extends Error {
+    readonly code: 'invalid_temporal_bucket_format' | 'invalid_temporal_bucket_value';
+    constructor(code: TemporalBucketContractError['code'], message: string);
+}
+
+declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
+export declare type TemporalBucketFormatApplicabilityErrorCode = 'invalid_temporal_bucket_pattern' | 'incompatible_temporal_bucket_pattern' | 'incompatible_temporal_bucket_preset';
+
+export declare type TemporalBucketFormatApplicabilityResult = {
+    ok: true;
+    segments?: TemporalBucketPatternSegment[];
+} | {
+    ok: false;
+    code: TemporalBucketFormatApplicabilityErrorCode;
+    message: string;
+};
+
+export declare type TemporalBucketMetadata = {
+    kind: 'temporal_bucket';
+    granularity: SemaphorTimeGrain;
+    calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
+};
+
+export declare type TemporalBucketPatternSegment = {
+    kind: 'token';
+    value: TemporalBucketPatternToken;
+} | {
+    kind: 'literal';
+    value: string;
+};
+
+export declare type TemporalBucketPatternToken = (typeof TEMPORAL_BUCKET_PATTERN_TOKENS)[number];
+
+export declare type TemporalBucketPatternTokenizationResult = {
+    ok: true;
+    segments: TemporalBucketPatternSegment[];
+} | {
+    ok: false;
+    code: 'invalid_temporal_bucket_pattern';
+    message: string;
+};
+
+declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+export 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];
+
+export declare type TemporalBucketValue = string | null;
+
+export declare type TemporalBucketValueParseResult = {
+    ok: true;
+    value: ParsedTemporalBucketValue | null;
+} | {
+    ok: false;
+    error: {
+        code: 'invalid_temporal_bucket_value';
+        message: string;
+    };
+};
+
+/**
+ * Tokenizes the finite grouped-temporal pattern vocabulary from Plan 04.
+ * It intentionally performs a deterministic left-to-right scan instead of
+ * regex replacement or date-library token inference.
+ */
+export declare function tokenizeTemporalBucketPattern(pattern: string): TemporalBucketPatternTokenizationResult;
+
 export declare function validateCardExportNumericPresentationSnapshot(input: {
-    entries: NumericPresentationSnapshotEntry[];
+    snapshot: PresentationExecutionSnapshot;
     expectedScope: {
         dashboardId: string;
         cardId: string;
@@ -662,6 +1228,18 @@ export declare function validateCardExportNumericPresentationSnapshot(input: {
     useFormattedValues: boolean;
 }): void;
 
+export declare function validateCardExportPresentationSnapshot(input: {
+    snapshot: PresentationExecutionSnapshot;
+    expectedScope: {
+        dashboardId: string;
+        cardId: string;
+    };
+    visibleColumns?: string[];
+    useFormattedValues: boolean;
+}): void;
+
+export declare function validateTemporalBucketFormatApplicability(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketFormatApplicabilityResult;
+
 declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 
 export { }