react-semaphor 0.1.449 → 0.1.453

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

@@ -54,6 +54,8 @@ export declare function arrayToCSV(rows: (string | number | null | undefined)[][
  */
 export declare function arrayToCSVRow(values: (string | number | null | undefined)[], delimiter?: string): string;
 
+export declare function assertRawTemporalChunkClassificationAgreement(inputs: readonly unknown[]): void;
+
 export declare function buildFlatTableExportTotalsFooter(params: {
     totalsByColumnId: FlatTableExportTotalsByColumnId;
     visibleColumns: readonly string[];
@@ -75,7 +77,7 @@ declare type CalendarContext = {
 
 export declare type CanonicalDurationUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
 
-export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | DurationCanonicalFormat | StringCanonicalFormat | TemporalBucketFormat;
+export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | RawTemporalFormat | DurationCanonicalFormat | StringCanonicalFormat | TemporalBucketFormat;
 
 declare type CanonicalPivotResultBase = {
     columns: SemaphorResultColumn[];
@@ -95,6 +97,11 @@ export declare type CanonicalPivotResultState = 'loaded_empty' | 'loaded_valid';
 
 export declare type CanonicalPivotResultTransport = LoadedEmptyPivotResult | LoadedValidPivotResult;
 
+export declare function classifyDeclaredSqlTemporalColumn(input: {
+    columnKey: string;
+    values: readonly (string | null)[];
+}): SqlTemporalColumnClassification;
+
 export declare interface ColorRange {
     min: number;
     max: number;
@@ -163,6 +170,13 @@ export declare function createCanonicalPivotResultTransport(input: {
     columnMetadata?: Readonly<Record<string, PivotResultColumnClassification | undefined>>;
 }): CanonicalPivotResultTransport;
 
+export declare function createPresentationExecutionSnapshot(input: {
+    reportContext: ReportRuntimeContext;
+    resolvedFormats: readonly ResolvedPresentationEntry[];
+}): PresentationExecutionSnapshot;
+
+export declare function createRawTemporalChunkClassificationEvidence(classifications: ReadonlyMap<string, SqlTemporalColumnClassification>): RawTemporalChunkClassificationEvidence;
+
 export declare interface CSVExportOptions {
     delimiter: ',' | ';' | '\t';
     includeHeaders: boolean;
@@ -197,6 +211,8 @@ export declare interface DateFormatOptions {
     locale?: string;
 }
 
+export declare const DEFAULT_RESOLVED_TEMPORAL_STYLE_SET: ResolvedTemporalStyleSet;
+
 /**
  * Derives the authored identity expectations stored in a canonical pivot
  * lifecycle contract. Producers and cache-compatibility consumers must use
@@ -278,6 +294,12 @@ export declare function findResolvedNumericFormat(input: {
     target: NumericPresentationTarget;
 }): NumericCanonicalFormat | undefined;
 
+export declare function findResolvedRawTemporalFormat(input: {
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    target: RawTemporalPresentationTarget;
+}): ResolvedRawTemporalFormat | undefined;
+
 export declare function findResolvedTemporalBucketFormat(input: {
     snapshot: PresentationExecutionSnapshot;
     scope: PresentationScope;
@@ -426,6 +448,13 @@ export declare function formatPivotDataRow(row: PivotRowData, pivotConfig: Pivot
  */
 export declare function formatPivotTableForCSV(data: PivotRowData[], pivotConfig: PivotExportConfig, formattingConfig: ExportFormattingConfig): string[];
 
+/** Strict one-off convenience; row loops should prepare once per column. */
+export declare function formatRawTemporalValue(input: {
+    value: string | null;
+    metadata: RawTemporalValueMetadata;
+    format: ResolvedRawTemporalFormat;
+}): RawTemporalFormatResult;
+
 /**
  * Format relative time using date-fns (e.g., "2 days ago")
  *
@@ -555,6 +584,12 @@ declare type MetricResultAliasInput = {
     expression?: string;
 };
 
+export declare class MissingResolvedRawTemporalFormatError extends Error {
+    readonly code = "missing_resolved_raw_temporal_format";
+    readonly deliveryBlocking = true;
+    constructor(columnKey: string);
+}
+
 declare type MonthAlignedFiscalCalendar = {
     kind: 'month_aligned';
     yearStartMonth: number;
@@ -650,10 +685,17 @@ export declare function parsePresentationExecutionSnapshot(input: unknown): Pres
 
 export declare function parsePresentationScope(input: unknown, path?: string): PresentationScope;
 
+export declare function parseRawTemporalChunkClassificationEvidence(input: unknown): RawTemporalChunkClassificationEvidence;
+
+/** Strictly parses one raw temporal descriptor at a result boundary. */
+export declare function parseRawTemporalValueMetadata(input: unknown): RawTemporalValueMetadata;
+
 export declare function parseResolvedNumericCanonicalFormat(input: unknown): NumericCanonicalFormatParseResult;
 
 export declare function parseResolvedPresentationEntries(input: unknown): ResolvedPresentationEntry[];
 
+export declare function parseResolvedRawTemporalFormat(input: unknown): ResolvedRawTemporalFormat;
+
 export declare function parseResolvedTemporalBucketFormat(input: unknown): ResolvedTemporalBucketFormatParseResult;
 
 export declare function parseTemporalBucketValue(value: TemporalBucketValue, metadata: TemporalBucketMetadata): TemporalBucketValueParseResult;
@@ -753,6 +795,14 @@ export declare interface PivotRowData {
     isGrandTotal?: boolean;
 }
 
+/** Strictly prepared per-column formatter for repeated cell rendering. */
+export declare type PreparedRawTemporalFormatter = (value: string | null) => RawTemporalFormatResult;
+
+export declare function prepareRawTemporalFormatter(input: {
+    metadata: RawTemporalValueMetadata;
+    format: ResolvedRawTemporalFormat;
+}): PreparedRawTemporalFormatter;
+
 /**
  * Formats one physical aggregate group cell. Row metadata alone determines
  * subtotal/grand-total ownership; null is always passed to the value formatter
@@ -766,10 +816,17 @@ export declare function presentAggregateGroupRow<T = string>(input: {
 }): AggregateGroupRowPresentation<T>;
 
 export declare type PresentationExecutionSnapshot = {
+    version: 1;
     reportContext: ReportRuntimeContext;
     resolvedFormats: ResolvedPresentationEntry[];
 };
 
+export declare class PresentationExecutionSnapshotError extends Error {
+    readonly code = "invalid_presentation_execution_snapshot";
+    readonly deliveryBlocking = true;
+    constructor(message: string);
+}
+
 export declare type PresentationScope = {
     dashboardId: string;
     cardId?: string;
@@ -804,6 +861,66 @@ export declare interface QueryColumnKeyMapEntry {
 
 export declare type QueryColumnKeyRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
 
+export declare type RawTemporalChunkClassificationEvidence = {
+    version: 1;
+    columns: Record<string, RawTemporalChunkClassificationStatus>;
+};
+
+export declare type RawTemporalChunkClassificationStatus = 'empty' | 'invalid_only' | RawTemporalValueKind;
+
+/** Normalized authored input for an ungrouped temporal result column. */
+export declare type RawTemporalFormat = {
+    type: 'raw_temporal';
+    /** Authored display timezone; `auto` uses the resolved calendar timezone. */
+    timezone?: string;
+    /** Authored source timezone; `auto` means UTC for timezone-less values. */
+    sourceTimezone?: string;
+    presentation: {
+        mode: 'auto';
+    } | {
+        mode: 'pattern';
+        dialect: RawTemporalPatternDialect;
+        pattern: string;
+    };
+};
+
+export declare class RawTemporalFormatContractError extends Error {
+    readonly code: 'invalid_raw_temporal_format' | 'mixed_sql_temporal_semantics';
+    constructor(code: RawTemporalFormatContractError['code'], message: string);
+}
+
+export declare type RawTemporalFormatResult = {
+    ok: true;
+    text: string;
+    status: 'formatted' | 'empty';
+} | {
+    ok: false;
+    text: string;
+    diagnostic: {
+        code: 'invalid_raw_temporal_value' | 'out_of_range_raw_temporal_value';
+        message: string;
+    };
+};
+
+export declare type RawTemporalPatternDialect = 'semaphor_tokens' | 'date_fns';
+
+export declare type RawTemporalPresentationTarget = {
+    kind: 'column';
+    columnKey: string;
+};
+
+/** Authoritative meaning of one ungrouped temporal result column. */
+export declare type RawTemporalValueKind = 'date' | 'wall_datetime' | 'instant';
+
+/**
+ * Result-column metadata for an ungrouped temporal value. This descriptor is
+ * mutually exclusive with grouped `temporalBucket` metadata.
+ */
+export declare type RawTemporalValueMetadata = {
+    kind: 'raw_temporal';
+    valueKind: RawTemporalValueKind;
+};
+
 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];
@@ -873,10 +990,47 @@ export declare type ResolvedNumericPresentationEntry = {
     format: NumericCanonicalFormat;
 };
 
-export declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry;
+export declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
 
-export declare type ResolvedTemporalBucketFormat = TemporalBucketFormat & {
+export declare type ResolvedRawTemporalFormat = {
+    type: 'raw_temporal';
     locale: string;
+    calendarTimezone: string;
+    /** Resolved source timezone for timezone-less wall datetimes, when authored. */
+    sourceTimezone?: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    } | {
+        mode: 'pattern';
+        dialect: RawTemporalPatternDialect;
+        pattern: string;
+    };
+};
+
+export declare type ResolvedRawTemporalPresentationEntry = {
+    scope: PresentationScope;
+    target: RawTemporalPresentationTarget;
+    format: ResolvedRawTemporalFormat;
+};
+
+export declare type ResolvedTemporalBucketFormat = {
+    type: 'temporal_bucket';
+    locale: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    };
+} | {
+    type: 'temporal_bucket';
+    locale: string;
+    presentation: {
+        mode: 'preset';
+        preset: TemporalBucketPreset;
+    } | {
+        mode: 'pattern';
+        pattern: string;
+    };
 };
 
 export declare type ResolvedTemporalBucketFormatParseResult = {
@@ -901,6 +1055,14 @@ export declare type ResolvedTemporalBucketPresentationEntry = {
     format: ResolvedTemporalBucketFormat;
 };
 
+export declare type ResolvedTemporalStyleSet = {
+    dateStyle: LocaleStyle;
+    dateTime: {
+        dateStyle: LocaleStyle;
+        timeStyle: LocaleStyle;
+    };
+};
+
 declare type ResolvedValueFormatPreferences = {
     locale: string;
     dateStyle: LocaleStyle;
@@ -928,6 +1090,12 @@ export declare function resolveNumericPresentation(authored: NumericCanonicalFor
 
 export declare function resolveQueryColumnKeyMapEntry(columnKeyMap: QueryColumnKeyMap | undefined, fieldId: string, role: QueryColumnKeyRole): QueryColumnKeyMapEntry | undefined;
 
+export declare function resolveRawTemporalFormat(input: {
+    format?: RawTemporalFormat;
+    preferences: ResolvedValueFormatPreferences;
+    calendar: Pick<CalendarContext, 'tz'>;
+}): ResolvedRawTemporalFormat;
+
 export declare function resolveTemporalBucketPresentation(input: ResolveTemporalBucketPresentationInput): ResolvedTemporalBucketPresentation;
 
 export declare type ResolveTemporalBucketPresentationInput = {
@@ -938,6 +1106,7 @@ export declare type ResolveTemporalBucketPresentationInput = {
     };
     cardFormat?: TemporalBucketFormat;
     locale: string;
+    styles?: ResolvedTemporalStyleSet;
 };
 
 /**
@@ -1054,6 +1223,7 @@ declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 
@@ -1119,6 +1289,15 @@ declare type SemaphorSourceRef = {
 
 declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
+export declare type SqlTemporalColumnClassification = {
+    status: 'empty';
+} | {
+    status: 'invalid_only';
+} | {
+    status: 'classified';
+    metadata: RawTemporalValueMetadata;
+};
+
 export declare type StringCanonicalFormat = {
     type: 'string';
     prefix?: string;
@@ -1240,6 +1419,14 @@ export declare function validateCardExportPresentationSnapshot(input: {
     useFormattedValues: boolean;
 }): void;
 
+/**
+ * Validates descriptor exclusivity and datatype compatibility without
+ * inferring temporal meaning from a value or display label.
+ */
+export declare function validateRawTemporalResultColumn(column: Pick<SemaphorResultColumn, 'dataType' | 'rawTemporal' | 'temporalBucket'>, options: {
+    metadataRequired: boolean;
+}): RawTemporalValueMetadata | undefined;
+
 export declare function validateTemporalBucketFormatApplicability(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketFormatApplicabilityResult;
 
 declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;

package/dist/types/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/common-types-CQ6SHfLk.cjs"),l=require("../chunks/token-types-BdQ8kHBm.cjs"),t=require("../chunks/pivot-result-identity-CDLRT-YG.cjs"),E=require("../chunks/report-runtime-context-C8LZFsqV.cjs");exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.CONTROL_CARD_DEFAULT_VALUE=e.CONTROL_CARD_DEFAULT_VALUE;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.EMPTY_SELECTION=e.EMPTY_SELECTION;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedField=e.isCalculatedField;exports.isCalculatedMetric=e.isCalculatedMetric;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=l.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=t.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=t.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=E.DEFAULT_CALENDAR_CONTEXT;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/common-types-Ci66eflG.cjs"),l=require("../chunks/token-types-D0i0IUX3.cjs"),t=require("../chunks/pivot-result-identity-CRUokNgm.cjs"),E=require("../chunks/report-runtime-context-DjYqLV-c.cjs");exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.CONTROL_CARD_DEFAULT_VALUE=e.CONTROL_CARD_DEFAULT_VALUE;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.EMPTY_SELECTION=e.EMPTY_SELECTION;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedField=e.isCalculatedField;exports.isCalculatedMetric=e.isCalculatedMetric;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=l.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=t.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=t.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=E.DEFAULT_CALENDAR_CONTEXT;

package/dist/types/index.js

@@ -1,7 +1,7 @@
-import { a as s, C as r, D as E, E as l, P as C, g as o, d as t, h as A, b as u, c as T, i as _ } from "../chunks/common-types-B7Jk3Rtj.js";
-import { D } from "../chunks/token-types-BHR58aTy.js";
-import { r as n, a as L } from "../chunks/pivot-result-identity-CwJWpKI7.js";
-import { D as d } from "../chunks/report-runtime-context-bCy3CVzK.js";
+import { a as s, C as r, D as E, E as l, P as C, g as o, d as t, h as A, b as u, c as T, i as _ } from "../chunks/common-types-F6qk6PPS.js";
+import { D } from "../chunks/token-types-CRpQJ4kv.js";
+import { r as n, a as L } from "../chunks/pivot-result-identity-C43Ai5Kr.js";
+import { D as d } from "../chunks/report-runtime-context-BJQDu2fV.js";
 export {
   s as CALCULATED_FIELD_ENTITY_MARKER,
   r as CONTROL_CARD_DEFAULT_VALUE,

package/dist/types/main.d.ts

@@ -471,7 +471,7 @@ declare type AsyncMutation<TInput, TOutput> = {
 
 export declare type AuthoritativeExportFormattingConfig = ExportFormattingConfig & {
     comparisonPresentation: ComparisonPresentationSpec;
-    resolvedFormats: ResolvedPresentationEntry[];
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
 };
 
 export declare type AuthToken = {
@@ -851,9 +851,9 @@ export declare type BriefingFormDraft = {
     limits: BriefingLimits;
 };
 
-export declare function briefingFormDraftToCreateRequest(draft: BriefingFormDraft, resolvedFormats?: ResolvedPresentationEntry[]): CreateBriefingRequest;
+export declare function briefingFormDraftToCreateRequest(draft: BriefingFormDraft): CreateBriefingRequest;
 
-export declare function briefingFormDraftToUpdateRequest(draft: BriefingFormDraft, resolvedFormats?: ResolvedPresentationEntry[]): UpdateBriefingRequest;
+export declare function briefingFormDraftToUpdateRequest(draft: BriefingFormDraft): UpdateBriefingRequest;
 
 export declare type BriefingFormOutputDraft = {
     artifactFormats: BriefingArtifactFormat[];
@@ -899,8 +899,7 @@ declare type BriefingFragments = {
 
 export declare type BriefingJobConfig = {
     kind: BriefingKind;
-    reportContext: ReportRuntimeContext;
-    resolvedFormats?: ResolvedPresentationEntry[];
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
     source: BriefingSource;
     body: BriefingBody;
     attachments: BriefingAttachment[];
@@ -1302,7 +1301,7 @@ 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 | TemporalBucketFormat;
+export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | RawTemporalFormat | DurationCanonicalFormat | StringCanonicalFormat | TemporalBucketFormat;
 
 declare type CanonicalPivotResultContract = {
     version: 1;
@@ -1845,7 +1844,6 @@ export declare type CreateBriefingRequest = {
     presentation: BriefingPresentation;
     limits?: BriefingLimits;
     deliveryConfig: BriefingDeliveryConfig | null;
-    resolvedFormats?: ResolvedPresentationEntry[];
 };
 
 /**
@@ -1881,7 +1879,6 @@ export declare interface CreateExportRequest {
     controlBindings?: ControlBinding[];
     resolvedPrimaryDateField?: ResolvedPrimaryDateField;
     globalDateComparison?: GlobalDateComparisonContext;
-    reportContext: ReportRuntimeContext;
     tableTotalsRequest?: TableTotalsRequest;
     totalRows: number;
     format: ExportFormat;
@@ -2379,6 +2376,8 @@ export declare type DashboardProps = {
      * points. Ordinary dashboard consumers should leave this unset.
      */
     interactionExecutionSnapshot?: Record<string, InteractionState>;
+    /** Server-resolved immutable presentation snapshot for internal print views. */
+    presentationExecutionSnapshot?: PresentationExecutionSnapshot;
     /**
      * Render target for print entry points. Generic dashboard PDF exports also
      * use cardDisplay.mode="print"; document-specific print handling must only
@@ -2634,6 +2633,11 @@ export declare type DeleteBriefingRunResponse = {
  */
 export declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     role: 'detail';
+    /**
+     * Query transport policy for ungrouped temporal values. This marker is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     dateFormat?: DateFormatValue;
     customFormat?: string;
     /**
@@ -2679,7 +2683,7 @@ export declare function DisplayFormatPreferencesFields({ value, inherited, inher
 export declare type DisplayFormatPreferencesFieldsProps = {
     value: ValueFormatPreferences;
     inherited: ResolvedValueFormatPreferences;
-    inheritedSources: Pick<ResolvedValueFormatPreferenceSources, 'locale' | 'defaultCurrency'>;
+    inheritedSources: Pick<ResolvedValueFormatPreferenceSources, 'locale' | 'dateStyle' | 'dateTime' | 'defaultCurrency'>;
     onChange: (value: ValueFormatPreferences) => void;
     disabled?: boolean;
 };
@@ -3381,7 +3385,7 @@ export declare interface ExportFormattingConfig {
     visibleColumns?: string[];
     columnLabels?: Record<string, string>;
     tableTotalsLabelColumnKey?: string;
-    resolvedFormats?: ResolvedPresentationEntry[];
+    presentationExecutionSnapshot?: PresentationExecutionSnapshot;
     comparisonPresentation?: ComparisonPresentationSpec;
 }
 
@@ -4927,6 +4931,12 @@ export declare type PluginType = 'custom' | 'standard';
 
 export declare function polishBriefingText(apiServiceUrl: string, token: string, text: string): Promise<string>;
 
+declare type PresentationExecutionSnapshot = {
+    version: 1;
+    reportContext: ReportRuntimeContext;
+    resolvedFormats: ResolvedPresentationEntry[];
+};
+
 declare type PresentationScope = {
     dashboardId: string;
     cardId?: string;
@@ -5015,6 +5025,41 @@ export declare type RangeValue = {
     gt?: string | number;
 };
 
+/** Normalized authored input for an ungrouped temporal result column. */
+declare type RawTemporalFormat = {
+    type: 'raw_temporal';
+    /** Authored display timezone; `auto` uses the resolved calendar timezone. */
+    timezone?: string;
+    /** Authored source timezone; `auto` means UTC for timezone-less values. */
+    sourceTimezone?: string;
+    presentation: {
+        mode: 'auto';
+    } | {
+        mode: 'pattern';
+        dialect: RawTemporalPatternDialect;
+        pattern: string;
+    };
+};
+
+declare type RawTemporalPatternDialect = 'semaphor_tokens' | 'date_fns';
+
+declare type RawTemporalPresentationTarget = {
+    kind: 'column';
+    columnKey: string;
+};
+
+/** Authoritative meaning of one ungrouped temporal result column. */
+declare type RawTemporalValueKind = 'date' | 'wall_datetime' | 'instant';
+
+/**
+ * Result-column metadata for an ungrouped temporal value. This descriptor is
+ * mutually exclusive with grouped `temporalBucket` metadata.
+ */
+declare type RawTemporalValueMetadata = {
+    kind: 'raw_temporal';
+    valueKind: RawTemporalValueKind;
+};
+
 declare type RelativeDateFilter = {
     mode: 'last';
     n: number;
@@ -5153,7 +5198,7 @@ declare type ResolvedNumericPresentationEntry = {
     format: NumericCanonicalFormat;
 };
 
-declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry;
+declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
 
 declare type ResolvedPrimaryDateField = (ResolvedPrimaryDateFieldBase & ({
     defaultGranularity?: SemaphorTimeGrain;
@@ -5178,8 +5223,45 @@ declare type ResolvedPrimaryDateFieldBase = {
     supportedGranularities?: SemaphorTimeGrain[];
 };
 
-declare type ResolvedTemporalBucketFormat = TemporalBucketFormat & {
+declare type ResolvedRawTemporalFormat = {
+    type: 'raw_temporal';
     locale: string;
+    calendarTimezone: string;
+    /** Resolved source timezone for timezone-less wall datetimes, when authored. */
+    sourceTimezone?: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    } | {
+        mode: 'pattern';
+        dialect: RawTemporalPatternDialect;
+        pattern: string;
+    };
+};
+
+declare type ResolvedRawTemporalPresentationEntry = {
+    scope: PresentationScope;
+    target: RawTemporalPresentationTarget;
+    format: ResolvedRawTemporalFormat;
+};
+
+declare type ResolvedTemporalBucketFormat = {
+    type: 'temporal_bucket';
+    locale: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    };
+} | {
+    type: 'temporal_bucket';
+    locale: string;
+    presentation: {
+        mode: 'preset';
+        preset: TemporalBucketPreset;
+    } | {
+        mode: 'pattern';
+        pattern: string;
+    };
 };
 
 declare type ResolvedTemporalBucketPresentationEntry = {
@@ -5188,6 +5270,14 @@ declare type ResolvedTemporalBucketPresentationEntry = {
     format: ResolvedTemporalBucketFormat;
 };
 
+declare type ResolvedTemporalStyleSet = {
+    dateStyle: LocaleStyle;
+    dateTime: {
+        dateStyle: LocaleStyle;
+        timeStyle: LocaleStyle;
+    };
+};
+
 declare type ResolvedValueFormatPreferences = {
     locale: string;
     dateStyle: LocaleStyle;
@@ -5805,6 +5895,7 @@ declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
     temporalBucket?: TemporalBucketMetadata;
+    rawTemporal?: RawTemporalValueMetadata;
     pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 

package/dist/types/shared.d.ts

@@ -736,6 +736,11 @@ declare type DefaultDateFilter = RelativeDateFilter | FixedMonthDefaultDateFilte
  */
 declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     role: 'detail';
+    /**
+     * Query transport policy for ungrouped temporal values. This marker is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     dateFormat?: DateFormatValue;
     customFormat?: string;
     /**