react-semaphor 0.1.443 → 0.1.445

package/dist/types/data-app-codegen-node.d.ts

@@ -66,6 +66,10 @@ export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_SCHEMA_VERSION: "semaphor
 
 export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_VALIDATOR_VERSION: "semaphor-data-app-codegen-summary-validator/v2";
 
+declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -266,7 +270,7 @@ declare type SemaphorDataAppCodegenMatrixIntent = {
     rows: Array<{
         id?: string;
         field?: SemaphorDataAppCodegenFieldRef;
-        grain?: SemaphorTimeGrain;
+        grain?: SemaphorMatrixTimeGrain;
         label?: string;
         subtotal?: boolean | {
             enabled?: boolean;
@@ -276,7 +280,7 @@ declare type SemaphorDataAppCodegenMatrixIntent = {
     columns?: Array<{
         id?: string;
         field?: SemaphorDataAppCodegenFieldRef;
-        grain?: SemaphorTimeGrain;
+        grain?: SemaphorMatrixTimeGrain;
         label?: string;
         subtotal?: boolean | {
             enabled?: boolean;
@@ -689,7 +693,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -820,7 +824,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -912,6 +916,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -947,7 +953,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -1042,7 +1048,7 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
@@ -1050,6 +1056,43 @@ declare type SemaphorRelativeTimeWindow = {
 
 declare type SemaphorScalar = string | number | boolean | null;
 
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -1095,47 +1138,10 @@ declare type SemaphorSqlIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    minimumFractionDigits?: number;
-    maximumFractionDigits?: number;
-    useGrouping?: boolean;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-    compact?: boolean;
-    scale?: number;
-    currency?: string;
-    percentValueMode?: 'fraction' | 'whole';
-} | {
-    type: 'date' | 'datetime';
-    locale?: string;
-    pattern?: string;
-    relative?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-    prefix?: string;
-    suffix?: string;
-} | {
-    type: 'duration';
-    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    maxUnits?: number;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-} | {
-    type: 'string';
-    prefix?: string;
-    suffix?: string;
-};
-
 export declare function validateCodegenSummary(value: unknown): string[];
 
 export declare function validateSemaphorDataAppCodegenSummary(value: unknown): {

package/dist/types/data-app-codegen.d.ts

@@ -62,6 +62,10 @@ export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_SCHEMA_VERSION: "semaphor
 
 export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_VALIDATOR_VERSION: "semaphor-data-app-codegen-summary-validator/v2";
 
+declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -262,7 +266,7 @@ declare type SemaphorDataAppCodegenMatrixIntent = {
     rows: Array<{
         id?: string;
         field?: SemaphorDataAppCodegenFieldRef;
-        grain?: SemaphorTimeGrain;
+        grain?: SemaphorMatrixTimeGrain;
         label?: string;
         subtotal?: boolean | {
             enabled?: boolean;
@@ -272,7 +276,7 @@ declare type SemaphorDataAppCodegenMatrixIntent = {
     columns?: Array<{
         id?: string;
         field?: SemaphorDataAppCodegenFieldRef;
-        grain?: SemaphorTimeGrain;
+        grain?: SemaphorMatrixTimeGrain;
         label?: string;
         subtotal?: boolean | {
             enabled?: boolean;
@@ -679,7 +683,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -792,7 +796,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -884,6 +888,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -919,7 +925,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -1014,7 +1020,7 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
@@ -1022,6 +1028,43 @@ declare type SemaphorRelativeTimeWindow = {
 
 declare type SemaphorScalar = string | number | boolean | null;
 
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -1067,47 +1110,10 @@ declare type SemaphorSqlIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    minimumFractionDigits?: number;
-    maximumFractionDigits?: number;
-    useGrouping?: boolean;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-    compact?: boolean;
-    scale?: number;
-    currency?: string;
-    percentValueMode?: 'fraction' | 'whole';
-} | {
-    type: 'date' | 'datetime';
-    locale?: string;
-    pattern?: string;
-    relative?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-    prefix?: string;
-    suffix?: string;
-} | {
-    type: 'duration';
-    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    maxUnits?: number;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-} | {
-    type: 'string';
-    prefix?: string;
-    suffix?: string;
-};
-
 export declare function validateCodegenSummary(value: unknown): string[];
 
 export declare function validateSemaphorDataAppCodegenSummary(value: unknown): {

package/dist/types/data-app-sdk-adapters.d.ts

@@ -26,6 +26,10 @@ export declare function normalizeSemaphorInputOptions(options?: Array<{
     disambiguation?: string[];
 }[];
 
+declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -122,7 +126,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -259,7 +263,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -366,6 +370,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -401,7 +407,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -561,7 +567,7 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
@@ -569,6 +575,43 @@ declare type SemaphorRelativeTimeWindow = {
 
 declare type SemaphorScalar = string | number | boolean | null;
 
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -635,47 +678,10 @@ declare type SemaphorSqlSourceSpec = {
     }>;
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    minimumFractionDigits?: number;
-    maximumFractionDigits?: number;
-    useGrouping?: boolean;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-    compact?: boolean;
-    scale?: number;
-    currency?: string;
-    percentValueMode?: 'fraction' | 'whole';
-} | {
-    type: 'date' | 'datetime';
-    locale?: string;
-    pattern?: string;
-    relative?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-    prefix?: string;
-    suffix?: string;
-} | {
-    type: 'duration';
-    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    maxUnits?: number;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-} | {
-    type: 'string';
-    prefix?: string;
-    suffix?: string;
-};
-
 export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
 
 export declare function toSemaphorAnalysisIntent(spec: SemaphorAnalysisQuerySpec): SemaphorMetricIntent;

package/dist/types/data-app-sdk-validation.d.ts

@@ -20,7 +20,7 @@ declare type MatrixAxisLevelDescriptor = {
     fieldKey: string;
     label: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -135,7 +135,7 @@ declare type MatrixMeasureDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -149,7 +149,7 @@ declare type MatrixMeasureSemantics = {
 } | {
     kind: 'semiAdditive';
     aggregate?: SemaphorAggregateFunction;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
 } | {
     kind: 'nonAdditive';
     aggregate?: SemaphorAggregateFunction;
@@ -250,6 +250,10 @@ export declare function relatedProjectionFieldCandidatesForIntent(intent: Relati
 
 declare type RelationshipAwareProjectionIntent = SemaphorRecordsIntent | SemaphorMetricIntent | SemaphorMatrixIntent;
 
+declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -545,7 +549,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -700,7 +704,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -835,6 +839,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -870,7 +876,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -981,6 +987,30 @@ declare type SemaphorPaginationRequest = {
     pageSize: number;
 };
 
+declare type SemaphorPivotResultColumnIdentity = {
+    metricId: string;
+    /** Collision-safe identity for this configured metric instance. */
+    metricAlias: string;
+    /**
+     * Sole transported tuple identity in configured pivot-axis order. A leaf
+     * carries the complete tuple, a subtotal carries its explicit prefix, and a
+     * metric-only or grand-total column carries an empty tuple.
+     */
+    members: SemaphorPivotResultMember[];
+};
+
+declare type SemaphorPivotResultMember = {
+    /** Stable identity of the configured pivot field. */
+    fieldId: string;
+    /** Canonical pivot member value; labels are resolved only at presentation. */
+    value: SemaphorPivotValue;
+    /** Present when this member is an activated governed temporal bucket. */
+    temporalBucket?: TemporalBucketMetadata;
+};
+
+/** Stable canonical scalar transported for one physical pivot member. */
+declare type SemaphorPivotValue = string | null;
+
 declare type SemaphorProtocolIssue = {
     code: string;
     message: string;
@@ -1113,7 +1143,7 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
@@ -1138,10 +1168,49 @@ declare type SemaphorResultColumn = {
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
+    temporalBucket?: TemporalBucketMetadata;
+    pivotIdentity?: SemaphorPivotResultColumnIdentity;
 };
 
 declare type SemaphorScalar = string | number | boolean | null;
 
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -1223,45 +1292,14 @@ declare type SemaphorSqlSourceSpec = {
     }>;
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    minimumFractionDigits?: number;
-    maximumFractionDigits?: number;
-    useGrouping?: boolean;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-    compact?: boolean;
-    scale?: number;
-    currency?: string;
-    percentValueMode?: 'fraction' | 'whole';
-} | {
-    type: 'date' | 'datetime';
-    locale?: string;
-    pattern?: string;
-    relative?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-    prefix?: string;
-    suffix?: string;
-} | {
-    type: 'duration';
-    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    maxUnits?: number;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-} | {
-    type: 'string';
-    prefix?: string;
-    suffix?: string;
+declare type TemporalBucketMetadata = {
+    kind: 'temporal_bucket';
+    granularity: SemaphorTimeGrain;
+    calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
 };
 
 export declare function validateSemaphorDataAppQuerySpecs(input: {