react-semaphor 0.1.369 → 0.1.371

package/dist/types/dashboard-authoring.d.ts

@@ -81,8 +81,14 @@ declare type CacheConfig = {
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -1251,6 +1257,15 @@ declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -1828,7 +1843,7 @@ declare type SemaphorAnalyticsFilterBase = {
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
-declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
 
 declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
     operator: SemaphorAnalyticsNullFilterOperator;
@@ -1869,8 +1884,54 @@ declare type SemaphorDashboardViewIntent = {
     text?: string;
 };
 
+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?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+
 declare type SemaphorFieldRef = {
     name: string;
     label?: string;
@@ -1903,6 +1964,7 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorInputScope = {
@@ -1928,6 +1990,149 @@ declare type SemaphorInputSpec = {
     scope?: SemaphorInputScope;
 };
 
+declare type SemaphorMatrixAxisExpansionOptions = {
+    defaultDepth?: number;
+    lazy?: boolean;
+    expandedPaths?: SemaphorMatrixMemberPathSegment[][];
+};
+
+declare type SemaphorMatrixAxisLevel = {
+    id?: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    label?: string;
+    subtotal?: boolean | SemaphorMatrixSubtotalOptions;
+    sortBy?: SemaphorMatrixAxisSortRule;
+};
+
+declare type SemaphorMatrixAxisSortRule = {
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixDisplayLimitOptions = {
+    rows?: SemaphorMatrixDisplayLimitRule;
+    columns?: SemaphorMatrixDisplayLimitRule;
+};
+
+declare type SemaphorMatrixDisplayLimitRule = {
+    limit: number;
+    by?: 'label' | 'value';
+    direction?: 'top' | 'bottom';
+    others?: boolean | {
+        label?: string;
+    };
+};
+
+declare type SemaphorMatrixExpansionOptions = {
+    rows?: SemaphorMatrixAxisExpansionOptions;
+    columns?: SemaphorMatrixAxisExpansionOptions;
+};
+
+declare type SemaphorMatrixIntent = {
+    kind: 'matrix';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorMatrixAxisLevel[];
+    columns?: SemaphorMatrixAxisLevel[];
+    values: SemaphorMatrixValueField[];
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputBinding[];
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixLayoutOptions;
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorMatrixLayoutOptions = {
+    hierarchy?: 'compact' | 'tabular' | 'outline';
+    valuesPlacement?: 'columns' | 'rows';
+    stickyRowHeaders?: boolean;
+    stickyColumnHeaders?: boolean;
+};
+
+declare type SemaphorMatrixMemberPathSegment = {
+    levelId: string;
+    value: unknown;
+};
+
+declare type SemaphorMatrixSortRule = {
+    axis: 'row' | 'column';
+    targetId?: string;
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    } | {
+        kind: 'value';
+        valueId: string;
+        rowPath?: SemaphorMatrixMemberPathSegment[];
+        columnPath?: SemaphorMatrixMemberPathSegment[];
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+
+declare type SemaphorMatrixSubtotalOptions = {
+    enabled?: boolean;
+    position?: 'before' | 'after';
+    label?: string;
+};
+
+declare type SemaphorMatrixTotalCalculation = {
+    kind: 'defaultAggregate';
+} | {
+    kind: 'blank';
+} | {
+    kind: 'labelOnly';
+    label?: string;
+} | {
+    kind: 'customAggregate';
+    aggregate: SemaphorAggregateFunction;
+} | {
+    kind: 'percentOfParent';
+} | {
+    kind: 'percentOfGrandTotal';
+} | {
+    kind: 'customExpression';
+    expressionId: string;
+};
+
+declare type SemaphorMatrixTotalOptions = {
+    rows?: boolean | 'perLevel';
+    columns?: boolean | 'perLevel';
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+    rowPosition?: 'top' | 'bottom';
+    columnPosition?: 'left' | 'right';
+};
+
+declare type SemaphorMatrixValueField = {
+    id?: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
 declare type SemaphorMetricAnalysis = {
     kind: 'period_change';
     orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
@@ -1959,6 +2164,7 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorPaginationRequest = {
@@ -1986,6 +2192,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorRelativeTimeWindow = {
@@ -1996,6 +2203,10 @@ declare type SemaphorRelativeTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -2051,6 +2262,9 @@ declare type SemaphorViewPresentation = {
 } | {
     kind: 'table';
     columns?: string[];
+} | {
+    kind: 'matrixTable';
+    mode?: 'auto' | 'pivot' | 'hierarchical';
 } | {
     kind: 'text';
 };

package/dist/types/dashboard.d.ts

@@ -158,8 +158,14 @@ export declare type CacheConfig = {
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -1288,6 +1294,15 @@ declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -1907,8 +1922,57 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+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?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 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 SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -2566,6 +2630,7 @@ export declare type TDataColumn = {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     sourceField?: string;
     aggregate?: AggregateFunction;

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

@@ -564,7 +564,7 @@ declare type SemaphorAnalyticsFilterBase = {
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
-declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
 
 declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
     operator: SemaphorAnalyticsNullFilterOperator;
@@ -580,8 +580,54 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
+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?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+
 declare type SemaphorFieldRef = {
     name: string;
     label?: string;
@@ -610,6 +656,150 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
+declare type SemaphorMatrixAxisExpansionOptions = {
+    defaultDepth?: number;
+    lazy?: boolean;
+    expandedPaths?: SemaphorMatrixMemberPathSegment[][];
+};
+
+declare type SemaphorMatrixAxisLevel = {
+    id?: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    label?: string;
+    subtotal?: boolean | SemaphorMatrixSubtotalOptions;
+    sortBy?: SemaphorMatrixAxisSortRule;
+};
+
+declare type SemaphorMatrixAxisSortRule = {
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixDisplayLimitOptions = {
+    rows?: SemaphorMatrixDisplayLimitRule;
+    columns?: SemaphorMatrixDisplayLimitRule;
+};
+
+declare type SemaphorMatrixDisplayLimitRule = {
+    limit: number;
+    by?: 'label' | 'value';
+    direction?: 'top' | 'bottom';
+    others?: boolean | {
+        label?: string;
+    };
+};
+
+declare type SemaphorMatrixExpansionOptions = {
+    rows?: SemaphorMatrixAxisExpansionOptions;
+    columns?: SemaphorMatrixAxisExpansionOptions;
+};
+
+declare type SemaphorMatrixIntent = {
+    kind: 'matrix';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorMatrixAxisLevel[];
+    columns?: SemaphorMatrixAxisLevel[];
+    values: SemaphorMatrixValueField[];
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputBinding[];
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixLayoutOptions;
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorMatrixLayoutOptions = {
+    hierarchy?: 'compact' | 'tabular' | 'outline';
+    valuesPlacement?: 'columns' | 'rows';
+    stickyRowHeaders?: boolean;
+    stickyColumnHeaders?: boolean;
+};
+
+declare type SemaphorMatrixMemberPathSegment = {
+    levelId: string;
+    value: unknown;
+};
+
+declare type SemaphorMatrixSortRule = {
+    axis: 'row' | 'column';
+    targetId?: string;
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    } | {
+        kind: 'value';
+        valueId: string;
+        rowPath?: SemaphorMatrixMemberPathSegment[];
+        columnPath?: SemaphorMatrixMemberPathSegment[];
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+
+declare type SemaphorMatrixSubtotalOptions = {
+    enabled?: boolean;
+    position?: 'before' | 'after';
+    label?: string;
+};
+
+declare type SemaphorMatrixTotalCalculation = {
+    kind: 'defaultAggregate';
+} | {
+    kind: 'blank';
+} | {
+    kind: 'labelOnly';
+    label?: string;
+} | {
+    kind: 'customAggregate';
+    aggregate: SemaphorAggregateFunction;
+} | {
+    kind: 'percentOfParent';
+} | {
+    kind: 'percentOfGrandTotal';
+} | {
+    kind: 'customExpression';
+    expressionId: string;
+};
+
+declare type SemaphorMatrixTotalOptions = {
+    rows?: boolean | 'perLevel';
+    columns?: boolean | 'perLevel';
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+    rowPosition?: 'top' | 'bottom';
+    columnPosition?: 'left' | 'right';
+};
+
+declare type SemaphorMatrixValueField = {
+    id?: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
 declare type SemaphorMetricAnalysis = {
@@ -643,6 +833,7 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorPaginationRequest = {
@@ -670,6 +861,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorRelativeTimeWindow = {
@@ -680,6 +872,10 @@ declare type SemaphorRelativeTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;