react-semaphor 0.1.504 → 0.1.505

package/dist/types/shared/analytics-protocol/contracts.d.ts

@@ -0,0 +1,845 @@
+import { z } from 'zod';
+import { matrixAnalyticalIntentSchema } from './matrix-definition-contract.js';
+import { matrixResultSchema } from './matrix-window-contract.js';
+import { CalendarContext } from '../report-runtime-context/index.js';
+export type SemaphorProtocolVersion = 1;
+export type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+export type SemaphorSourceLevel = 'database' | 'schema' | 'table';
+export type SemaphorConnectionCapabilities = {
+    connectionId?: string;
+    connectionType?: string;
+    dialect: SemaphorDialect;
+    path: SemaphorSourceLevel[];
+    labels: Partial<Record<SemaphorSourceLevel, string>>;
+    prefixLevels: SemaphorSourceLevel[];
+    supportsFilterClause: boolean;
+};
+export 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;
+};
+export type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+export type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+export type SemaphorExecutionFieldRef = SemaphorFieldRef & {
+    derivedField?: SemaphorDerivedFieldDefinition;
+};
+export type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
+export type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+export type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+export type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+export 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;
+};
+export type SemaphorValueFormat = SemaphorScalarValueFormat | TemporalBucketFormat;
+export type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+export 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[];
+};
+export type SemaphorResultColumnRef = {
+    columnKey: string;
+} | {
+    field: SemaphorFieldRef;
+};
+export type SemaphorResultCalculationOutput = {
+    key: string;
+    label?: string;
+    dataType?: SemaphorFieldRef['dataType'];
+    format?: SemaphorScalarValueFormat;
+};
+export type SemaphorResultCalculationDenominator = {
+    scope: 'returned_result';
+} | {
+    scope: 'population';
+    metric: SemaphorFieldRef;
+    filters?: SemaphorAnalyticsFilter[];
+};
+export type SemaphorResultCalculation = {
+    id: string;
+    label: string;
+    kind: 'percent_of_total';
+    input: SemaphorResultColumnRef;
+    denominator?: SemaphorResultCalculationDenominator;
+    output: SemaphorResultCalculationOutput;
+} | {
+    id: string;
+    label: string;
+    kind: 'rank';
+    input: SemaphorResultColumnRef;
+    order?: 'asc' | 'desc';
+    output: SemaphorResultCalculationOutput;
+} | {
+    id: string;
+    label: string;
+    kind: 'running_total' | 'previous_row_delta';
+    input: SemaphorResultColumnRef;
+    orderBy?: SemaphorResultColumnRef;
+    output: SemaphorResultCalculationOutput;
+};
+export type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
+export type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
+export type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+export type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+export type SemaphorAnalyticsFilterBase = {
+    id?: string;
+    field: SemaphorFieldRef;
+    /**
+     * Controls where the filter is applied in an aggregate query.
+     *
+     * `row` means pre-aggregation filtering (`WHERE`).
+     * `aggregate` means post-aggregation filtering (`HAVING`) and is valid only
+     * for measure fields the execution engine can aggregate safely.
+     */
+    scope?: 'row' | 'aggregate';
+};
+export type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+export type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+export type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+export type SemaphorInputScope = {
+    level: 'dashboard';
+    excludeViewIds?: string[];
+} | {
+    level: 'section';
+    sectionId: string;
+    excludeViewIds?: string[];
+} | {
+    level: 'view';
+    viewIds: string[];
+};
+export type SemaphorInputSpec = {
+    id: string;
+    kind: 'filter' | 'control';
+    label: string;
+    field: SemaphorFieldRef;
+    operator?: SemaphorInputOperator;
+    multi?: boolean;
+    defaultValue?: unknown;
+    scope?: SemaphorInputScope;
+};
+export type SemaphorInputBinding = {
+    inputId: string;
+    kind?: 'filter' | 'control';
+    controlRole?: 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
+    operator?: SemaphorInputOperator;
+    field?: SemaphorFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+export type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+export type SemaphorOptionDependencyMode = 'independent' | 'explicit' | 'all_applicable';
+export type SemaphorOptionDependencies = {
+    /** Omitted mode means independent for protocol callers. Dashboard authoring
+     * normalizes omission separately through `resolveDashboardOptionDependencies`. */
+    mode?: SemaphorOptionDependencyMode;
+    includeInputIds?: string[];
+    excludeInputIds?: string[];
+    /**
+     * Ephemeral browse override: explicit dependencies the viewer asked to
+     * browse without. Only valid in explicit mode, only for ids in
+     * `includeInputIds`, and only honored by the server when that dependency
+     * would otherwise fail with an overridable reason (see
+     * `OVERRIDABLE_OPTION_DEPENDENCY_REASONS`). Never persisted, never applied
+     * to card predicates; it lives in one browse request and its cache identity.
+     */
+    omitInputIds?: string[];
+};
+/**
+ * Reasons a viewer may browse around with a labeled override. Everything
+ * else (auth, execution, malformed metadata, unsupported semantics) stays an
+ * error that an override cannot bypass.
+ */
+export declare const OVERRIDABLE_OPTION_DEPENDENCY_REASONS: readonly ["missing_dependency", "missing_relationship", "population_required", "ambiguous_relationship"];
+export declare function isOverridableOptionDependencyReason(reason: unknown): reason is (typeof OVERRIDABLE_OPTION_DEPENDENCY_REASONS)[number];
+/** Upper bound on exact values one relevance check may submit. Values beyond
+ * it stay `unknown`; a truncated list is never evidence of absence. */
+export declare const MAX_OPTION_MATCH_VALUES = 200;
+export type SemaphorOptionDependencyOutcomeStatus = 'applied' | 'inactive' | 'skipped' | 'overridden' | 'error';
+export type SemaphorOptionDependencyOutcomeReason = 'unrelated' | 'population_required' | 'missing_dependency' | 'missing_relationship' | 'ambiguous_relationship' | 'invalid_metadata' | 'unsupported_dependency' | 'override_not_eligible';
+/** Per-candidate classification of an option query's dependencies. Describes
+ * which viewer selections constrained the option list; it never substitutes
+ * for execution success or failure. */
+export type SemaphorOptionDependencyOutcome = {
+    inputId: string;
+    status: SemaphorOptionDependencyOutcomeStatus;
+    reason?: SemaphorOptionDependencyOutcomeReason;
+};
+export type SemaphorOptionPopulation = {
+    kind: 'option_source';
+    baseSource?: never;
+} | {
+    kind: 'related_population';
+    baseSource: SemaphorSourceRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+export declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+export type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
+export declare function isSemaphorTimeGrain(value: unknown): value is SemaphorTimeGrain;
+export declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+export type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+export type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+export type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+/**
+ * Authoring boundary for a dashboard field that is known to be grouped by a
+ * temporal grain. The broad persisted field types remain intentionally
+ * compatible with unmigrated/non-temporal fields; new temporal writers use
+ * this boundary instead.
+ */
+export type GroupedTemporalAuthoringInput<TBase extends object> = Omit<TBase, 'granularity' | 'format'> & {
+    granularity: SemaphorTimeGrain;
+    format?: TemporalBucketFormat;
+};
+/**
+ * Semantic temporal input permits total omission, but a format can only exist
+ * in the branch that declares its grain.
+ */
+export type SemanticGroupedTemporalInput<TBase extends object> = (Omit<TBase, 'granularity' | 'format'> & {
+    granularity?: undefined;
+    format?: undefined;
+}) | GroupedTemporalAuthoringInput<TBase>;
+/**
+ * Downstream normalized grouped fields always carry explicit presentation;
+ * an omitted authored format is materialized as `auto` by the Phase B adapter.
+ */
+export type NormalizedGroupedTemporalField<TBase extends object> = Omit<TBase, 'granularity' | 'format'> & {
+    granularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+};
+export type TemporalBucketMetadata = {
+    kind: 'temporal_bucket';
+    granularity: SemaphorTimeGrain;
+    calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
+};
+/** Authoritative meaning of one ungrouped temporal result column. */
+export type RawTemporalValueKind = 'date' | 'wall_datetime' | 'instant';
+/**
+ * Result-column metadata for an ungrouped temporal value. This descriptor is
+ * mutually exclusive with grouped `temporalBucket` metadata.
+ */
+export type RawTemporalValueMetadata = {
+    kind: 'raw_temporal';
+    valueKind: RawTemporalValueKind;
+};
+export declare const RAW_TEMPORAL_CONTRACT_ERROR_CODES: {
+    readonly invalidMetadata: "invalid_raw_temporal_metadata";
+};
+export type RawTemporalContractErrorCode = (typeof RAW_TEMPORAL_CONTRACT_ERROR_CODES)[keyof typeof RAW_TEMPORAL_CONTRACT_ERROR_CODES];
+type ResolvedPrimaryDateFieldBase = {
+    sourceDataset: string;
+    sourceField: string;
+    name: string;
+    qualifiedFieldName: string;
+    qualifiedEntityName?: string;
+    entityId: string;
+    entityName: string;
+    entityType: string;
+    dataType: string;
+    /** Canonical dataset coordinates stamped by the semantic grounding boundary. */
+    source?: SemaphorSourceRef;
+    supportedGranularities?: SemaphorTimeGrain[];
+};
+export type ResolvedPrimaryDateField = (ResolvedPrimaryDateFieldBase & ({
+    defaultGranularity?: SemaphorTimeGrain;
+    format?: undefined;
+} | {
+    defaultGranularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+})) | null;
+export declare function temporalBucketDataTypeForGrain(granularity: SemaphorTimeGrain): 'date' | 'datetime';
+export declare const TEMPORAL_BUCKET_CONTRACT_ERROR_CODES: {
+    readonly missingMetadata: "missing_temporal_bucket_metadata";
+    readonly invalidMetadata: "invalid_temporal_bucket_metadata";
+    readonly invalidValue: "invalid_temporal_bucket_value";
+};
+export type TemporalBucketContractErrorCode = (typeof TEMPORAL_BUCKET_CONTRACT_ERROR_CODES)[keyof typeof TEMPORAL_BUCKET_CONTRACT_ERROR_CODES];
+export type SemaphorRelativeTimeWindow = {
+    kind?: 'relative';
+    unit: SemaphorTimeGrain;
+    value: number;
+    anchor?: 'now' | 'latest_available';
+    completeness?: 'include_partial' | 'complete_periods';
+};
+export type SemaphorAbsoluteTimeWindow = {
+    kind: 'absolute';
+    start: string;
+    end: string;
+};
+export type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
+export type SemaphorPaginationRequest = {
+    page: number;
+    pageSize: number;
+};
+export type SemaphorPaginationMetadata = {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    totalCount: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+};
+export type SemaphorMetricAnalysis = {
+    kind: 'period_change';
+    orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
+    direction?: 'increase' | 'decrease' | 'both';
+    timeWindow?: SemaphorTimeWindow;
+};
+export type SemaphorMetricIntent = {
+    kind: 'metric';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    source: SemaphorSourceRef;
+    measures: SemaphorFieldRef[];
+    primaryMeasure?: SemaphorFieldRef;
+    label?: string;
+    dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    timeWindow?: SemaphorTimeWindow;
+    dimensions?: SemaphorFieldRef[];
+    filters?: SemaphorAnalyticsFilter[];
+    comparison?: {
+        kind: 'previous_period' | 'previous_year' | 'target';
+        targetValue?: number;
+    };
+    analysis?: SemaphorMetricAnalysis;
+    orderBy?: {
+        field: SemaphorFieldRef;
+        direction: 'asc' | 'desc';
+    };
+    inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
+    limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+export type SemaphorRecordsIntent = {
+    kind: 'records';
+    version?: SemaphorProtocolVersion;
+    source: SemaphorSourceRef;
+    id?: string;
+    label?: string;
+    fields: SemaphorFieldRef[];
+    dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    timeWindow?: SemaphorTimeWindow;
+    filters?: SemaphorAnalyticsFilter[];
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+    orderBy?: {
+        field: SemaphorFieldRef;
+        direction: 'asc' | 'desc';
+    };
+    inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+    totals?: SemaphorRecordsServerTotalsRequest;
+};
+export type SemaphorRecordsServerTotalsRequest = {
+    mode: 'server';
+    measures: SemaphorFieldRef[];
+};
+export type SemaphorInputOptionSource = {
+    source: Extract<SemaphorSourceRef, {
+        kind: 'semantic' | 'physical';
+    }>;
+    labelField: SemaphorFieldRef;
+    valueField: SemaphorFieldRef;
+    searchField?: SemaphorFieldRef;
+    disambiguationFields?: SemaphorFieldRef[];
+};
+export type SemaphorInputOptionsIntent = SemaphorInputOptionSource & {
+    kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    inputId: string;
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
+    search?: string;
+    limit?: number;
+    /**
+     * Authoritative selected-value relevance check: return only options whose
+     * value is one of these exact raw values, under the same dependency and
+     * population context, with no search or paging. Bounded by
+     * `MAX_OPTION_MATCH_VALUES`. The result's `match.complete` says whether
+     * absence from the returned options proves no match. Scalars only; see
+     * `parseOptionMatchValues`.
+     */
+    matchValues?: Array<string | number | boolean>;
+    inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+export type SemaphorSqlIntent = {
+    kind: 'sql';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+    sql: string;
+    defaultParameters?: Record<string, unknown>;
+    pythonCode?: string;
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+    rationale?: string;
+    fields?: SemaphorFieldRef[];
+    inputs?: SemaphorInputBinding[];
+};
+export type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+export type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+export type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+export type SemaphorMatrixIntent = z.infer<typeof matrixAnalyticalIntentSchema>;
+export type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
+export type SemaphorViewPresentation = {
+    kind: 'kpi';
+    format?: 'number' | 'currency' | 'percent' | 'duration';
+} | {
+    kind: 'lineChart' | 'barChart' | 'areaChart';
+    x?: string;
+    y?: string[];
+} | {
+    kind: 'table';
+    columns?: string[];
+} | {
+    kind: 'matrixTable';
+    mode?: 'auto' | 'pivot' | 'hierarchical';
+} | {
+    kind: 'text';
+};
+export type SemaphorDashboardViewIntent = {
+    id?: string;
+    title: string;
+    description?: string;
+    presentation: SemaphorViewPresentation;
+    analytics?: SemaphorAnalyticsIntent;
+    text?: string;
+};
+export type SemaphorDashboardSectionIntent = {
+    id?: string;
+    title: string;
+    description?: string;
+    views: SemaphorDashboardViewIntent[];
+};
+export type SemaphorDashboardIntent = {
+    version: SemaphorProtocolVersion;
+    kind: 'dashboard';
+    title: string;
+    description?: string;
+    inputs?: SemaphorInputSpec[];
+    sections: SemaphorDashboardSectionIntent[];
+};
+export type SemaphorExperienceIntent = SemaphorDashboardIntent;
+export type SemaphorProtocolIssue = {
+    code: string;
+    message: string;
+    path?: string;
+};
+export type SemaphorAnalyticsFieldRole = 'measure' | 'date' | 'dimension' | 'input' | 'source' | 'sql';
+export type SemaphorAnalyticsValidationCode = 'missing_source' | 'invalid_source_kind' | 'missing_semantic_domain' | 'missing_dataset_name' | 'missing_connection_id' | 'missing_table_name' | 'missing_sql' | 'missing_measure' | 'missing_record_fields' | 'missing_input_options_input_id' | 'missing_input_options_label_field' | 'missing_input_options_value_field' | 'invalid_input_options_dependencies' | 'invalid_input_options_population' | 'invalid_measure' | 'invalid_measure_list' | 'invalid_date_field' | 'invalid_dimension' | 'invalid_measure_dimensions' | 'conflicting_sql' | 'sql_policy_violation' | 'unsupported_intent_for_adapter' | 'invalid_analytics_kind' | 'invalid_analytics_intent';
+export type SemaphorAnalyticsRepairHint = {
+    code: SemaphorAnalyticsValidationCode | string;
+    message?: string;
+    invalidField?: string;
+    fieldRole?: SemaphorAnalyticsFieldRole;
+    validMeasureCandidates?: string[];
+    validDateCandidates?: string[];
+    validDimensionCandidates?: string[];
+    recommendedNextStep: string;
+};
+export type SemaphorAnalyticsValidationIssue = SemaphorProtocolIssue & {
+    code: SemaphorAnalyticsValidationCode | string;
+    fieldRole?: SemaphorAnalyticsFieldRole;
+    repairHint?: SemaphorAnalyticsRepairHint;
+};
+export type SemaphorAnalyticsValidationResult = {
+    ok: boolean;
+    errors: SemaphorAnalyticsValidationIssue[];
+    warnings: SemaphorAnalyticsValidationIssue[];
+    repairHints: SemaphorAnalyticsRepairHint[];
+};
+export type SemaphorValidationResult = {
+    ok: boolean;
+    errors: SemaphorProtocolIssue[];
+    warnings: SemaphorProtocolIssue[];
+};
+export type SemaphorQueryPath = 'query_spec' | 'sql' | 'sql_python';
+export type SemaphorCompiledQuery = {
+    kind: 'config';
+    queryId: string;
+    source: SemaphorSourceRef;
+    cardType: string;
+    connectionId: string;
+    cardConfig: unknown;
+    cardDataSource: unknown;
+    activeFilters?: SemaphorAnalyticsFilter[];
+    rowLimit: number;
+    analyticsIntent?: SemaphorAnalyticsIntent;
+} | {
+    kind: 'sql';
+    queryId: string;
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+    connectionId: string;
+    dialect: SemaphorDialect;
+    sql: string;
+    parameters?: Record<string, unknown>;
+    pythonCode?: string;
+    activeFilters?: SemaphorAnalyticsFilter[];
+    rowLimit: number;
+    analyticsIntent?: SemaphorAnalyticsIntent;
+};
+export type SemaphorAnalyticsResultBase = {
+    intentId?: string;
+    queryPath: SemaphorQueryPath;
+    warnings?: string[];
+    rowCount?: number;
+    rowLimitExceeded?: boolean;
+    limit?: number;
+    pagination?: SemaphorPaginationMetadata;
+};
+export type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
+    kind: 'metric';
+    primaryValue: number | string | null;
+    missingMeasures?: string[];
+    comparison?: {
+        kind: NonNullable<SemaphorMetricIntent['comparison']>['kind'];
+        value?: number | string | null;
+        delta?: number | null;
+        deltaPercent?: number | null;
+    };
+};
+/** Stable field identity for the query builder's generated Count measure. */
+export declare const SEMAPHOR_GENERATED_COUNT_METRIC_ID: "__auto_count__";
+/** Stable canonical scalar transported for one physical pivot member. */
+export type SemaphorPivotValue = string | null;
+export 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;
+};
+export 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[];
+};
+export 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;
+    rawTemporal?: RawTemporalValueMetadata;
+    pivotIdentity?: SemaphorPivotResultColumnIdentity;
+};
+export type DashboardRecordsPayload = {
+    records: Array<Record<string, unknown>>;
+    columns?: SemaphorResultColumn[];
+    [key: string]: unknown;
+};
+export type CanonicalDashboardRecordsPayload = DashboardRecordsPayload & {
+    columns: SemaphorResultColumn[];
+};
+export type SemaphorRecordsResult = SemaphorAnalyticsResultBase & {
+    kind: 'records';
+    columns: SemaphorResultColumn[];
+    records: Array<Record<string, unknown>>;
+    totals?: SemaphorRecordsServerTotalsResult;
+};
+export type SemaphorRecordsServerTotalsResult = {
+    mode: 'server';
+    scope: 'filtered_result';
+    row: Record<string, unknown>;
+    columns?: SemaphorResultColumn[];
+};
+export type SemaphorOptionMatchResult = {
+    /** True only when every submitted value was evaluated by a complete exact
+     * check; only then may absence be read as `no_match`. */
+    complete: boolean;
+    reason?: 'unsupported' | 'truncated';
+};
+export type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
+    kind: 'inputOptions';
+    dependencyOutcomes?: SemaphorOptionDependencyOutcome[];
+    /** Present when the intent carried `matchValues`. */
+    match?: SemaphorOptionMatchResult;
+    options: Array<{
+        label: string;
+        value: unknown;
+        count?: number;
+        disambiguation?: string[];
+    }>;
+};
+export type SemaphorSqlResult = SemaphorAnalyticsResultBase & {
+    kind: 'sql';
+    columns: SemaphorRecordsResult['columns'];
+    records: SemaphorRecordsResult['records'];
+    sqlShape?: {
+        statementType?: string;
+        explicitLimit?: number;
+        hasPythonCode?: boolean;
+    };
+};
+export type SemaphorMatrixResult = z.infer<typeof matrixResultSchema>;
+export type SemaphorAnalyticsResult = SemaphorMetricResult | SemaphorRecordsResult | SemaphorInputOptionsResult | SemaphorSqlResult | SemaphorMatrixResult;
+export type SemaphorAnalyticsExecutionStatus = 'answered' | 'partial' | 'failed';
+export type SemaphorAnalyticsExecutionResultShape = SemaphorAnalyticsResult['kind'] | 'period_change' | 'analysis';
+export type SemaphorRelationshipDiagnosticStatus = 'not_required' | 'resolved' | 'missing' | 'ambiguous' | 'fanout_risk' | 'unknown';
+export type SemaphorRelationshipDiagnostics = {
+    status: SemaphorRelationshipDiagnosticStatus;
+    requiredSources?: SemaphorSourceRef[];
+    relationshipsUsed?: string[];
+    missingSources?: string[];
+    warnings?: string[];
+    message?: string;
+    recommendedNextStep?: string;
+    joinPlanSummary?: {
+        baseSource?: SemaphorSourceRef;
+        joinedSources?: SemaphorSourceRef[];
+        joinCount?: number;
+    };
+    fanoutRisk?: {
+        status: 'none' | 'warning' | 'error' | 'unknown';
+        message?: string;
+    };
+};
+export type SemaphorAnalyticsPopulation = {
+    scope: 'filtered_query';
+    measures: Record<string, number | string | null>;
+};
+export type SemaphorAnalyticsExecutionResult = {
+    intentId?: string;
+    queryId?: string;
+    status: SemaphorAnalyticsExecutionStatus;
+    resultShape?: SemaphorAnalyticsExecutionResultShape;
+    intent?: SemaphorAnalyticsIntent;
+    compiledQuery?: SemaphorCompiledQuery;
+    fieldsUsed?: SemaphorExecutionFieldRef[];
+    result?: SemaphorAnalyticsResult;
+    validation: SemaphorAnalyticsValidationResult;
+    coverage?: {
+        answeredObligations: string[];
+        missingObligations: string[];
+        warnings?: SemaphorAnalyticsValidationIssue[];
+    };
+    missingFields?: string[];
+    warnings?: string[];
+    relationshipDiagnostics?: SemaphorRelationshipDiagnostics;
+    diagnosticFeedback?: SemaphorAnalyticsDiagnosticFeedback;
+    population?: SemaphorAnalyticsPopulation;
+    metadata?: Record<string, unknown>;
+};
+export type SemaphorAnalyticsDiagnosticReasonCode = 'ambiguous_fields' | 'empty_result' | 'missing_grounded_fields' | 'missing_relationship' | 'no_grounded_query' | 'partial_result' | 'presentation_incomplete' | 'query_validation_failed' | 'unsafe_join';
+export type SemaphorAnalyticsDiagnosticStatus = 'answered' | 'partial' | 'blocked';
+export type SemaphorAnalyticsDiagnosticAnsweredItem = {
+    slotId?: string;
+    queryId?: string;
+    summary: string;
+    evidenceIds?: string[];
+    fieldsUsed?: SemaphorExecutionFieldRef[];
+};
+export type SemaphorAnalyticsDiagnosticBlockedItem = {
+    slotId?: string;
+    queryId?: string;
+    reasonCode: SemaphorAnalyticsDiagnosticReasonCode;
+    message: string;
+    missingFields?: string[];
+    availableFields?: string[];
+    ambiguousFields?: string[];
+    missingRelationships?: string[];
+    evidenceIds?: string[];
+    neededFromUser?: string[];
+    recommendedNextStep?: string;
+};
+export type SemaphorAnalyticsDiagnosticRecommendation = {
+    reasonCode: SemaphorAnalyticsDiagnosticReasonCode;
+    message: string;
+    recommendedNextStep?: string;
+};
+export type SemaphorAnalyticsDiagnosticFeedback = {
+    version: 1;
+    status: SemaphorAnalyticsDiagnosticStatus;
+    summary: string;
+    answered: SemaphorAnalyticsDiagnosticAnsweredItem[];
+    blocked: SemaphorAnalyticsDiagnosticBlockedItem[];
+    semanticModelRecommendations?: SemaphorAnalyticsDiagnosticRecommendation[];
+};
+export type SemaphorAnalyticsObligationType = 'record_list' | 'count' | 'trend' | 'comparison' | 'driver_analysis' | 'metric_summary' | 'analysis_table' | 'lookup' | 'unknown';
+export type SemaphorAnalyticsObligation = {
+    id: string;
+    type: SemaphorAnalyticsObligationType;
+    subject: string;
+    prompt: string;
+    measureCandidates?: string[];
+    entityCandidates?: string[];
+    dateCandidates?: string[];
+    dimensionCandidates?: string[];
+    displayFieldCandidates?: string[];
+    requiredFieldCandidates?: string[];
+    limit?: number;
+    timeWindow?: SemaphorTimeWindow;
+    comparison?: 'previous_year' | 'previous_period';
+    required?: boolean;
+};
+export type SemaphorOperationIntent = {
+    version: SemaphorProtocolVersion;
+    kind: 'answer_obligations';
+    obligations: SemaphorAnalyticsObligation[];
+    source?: SemaphorSourceRef;
+    context?: Record<string, unknown>;
+} | {
+    version: SemaphorProtocolVersion;
+    kind: 'dashboard_change';
+    instruction: string;
+    targetDashboardId?: string;
+    analyticsIntent?: SemaphorAnalyticsIntent;
+    context?: Record<string, unknown>;
+} | {
+    version: SemaphorProtocolVersion;
+    kind: 'data_app_change';
+    instruction: string;
+    analyticsIntent?: SemaphorAnalyticsIntent;
+    context?: Record<string, unknown>;
+};
+export type SemaphorRecoveryToolCall = {
+    name: 'semaphor_get_dataset_schema' | 'semaphor_analyze' | 'semaphor_query_sql_advanced' | string;
+    arguments: Record<string, unknown>;
+    purpose: string;
+    obligationId?: string;
+    recoveryKind?: 'schema_discovery' | 'query_spec' | 'sql' | 'unsupported';
+};
+export type SemaphorAnalyticsRecoveryPlan = {
+    version: SemaphorProtocolVersion;
+    kind: 'analytics_recovery_plan';
+    operationIntent: SemaphorOperationIntent;
+    plannedToolCalls: SemaphorRecoveryToolCall[];
+    diagnostics: Array<{
+        code: string;
+        message: string;
+        obligationId?: string;
+        recommendedNextStep?: string;
+    }>;
+};
+export {};