react-semaphor 0.1.398 → 0.1.400

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

@@ -0,0 +1,1137 @@
+export declare function assertValidCodegenSummary(value: unknown): void;
+
+export declare function buildSemaphorGeneratedActiveInput({ input, filterContract, binding, option, codegenSummary, }: {
+    input: unknown;
+    filterContract: unknown;
+    binding: unknown;
+    option: {
+        value?: SemaphorInputValue;
+    };
+    codegenSummary: unknown;
+}): SemaphorActiveInput;
+
+export declare function buildSemaphorGeneratedInputOptionIntent({ input, filterContract, codegenSummary, }: {
+    input: unknown;
+    filterContract: unknown;
+    codegenSummary: unknown;
+}): Extract<SemaphorAnalyticsIntent, {
+    kind: 'inputOptions';
+}> | null;
+
+export declare function buildSemaphorGeneratedViewExecutionRequest(view: unknown, contextOrSummary: GeneratedRefContext | unknown): Omit<SemaphorGeneratedViewExecutionRequest, 'viewId'> | null;
+
+export declare function buildSemaphorGeneratedViewExecutionRequests(codegenSummary: unknown): SemaphorGeneratedViewExecutionRequestsResult;
+
+/**
+ * Calendar context for timezone-aware date operations.
+ * Controls how dates are interpreted, grouped, and displayed.
+ */
+declare type CalendarContext = {
+    /**
+     * IANA timezone identifier.
+     * @example 'America/Chicago', 'Europe/London', 'Asia/Tokyo', 'UTC'
+     * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    tz: string;
+    /**
+     * Day the week starts on.
+     * 0 = Sunday (US, Canada, Japan)
+     * 1 = Monday (ISO standard, most of Europe)
+     * 6 = Saturday (Middle East)
+     * @default 1 (Monday) for backward compatibility
+     */
+    weekStart: WeekStart;
+    /**
+     * Date anchor for relative date calculations.
+     * - 'now': Use current time (default, live dashboards)
+     * - { iso: string }: Fixed ISO 8601 date for reproducible views
+     */
+    anchor: 'now' | {
+        iso: string;
+    };
+};
+
+export declare const CODEGEN_SUMMARY_SCHEMA_VERSION: "semaphor-data-app-codegen-summary/v1";
+
+export declare const CODEGEN_SUMMARY_VALIDATOR_VERSION: "semaphor-data-app-codegen-summary-validator/v2";
+
+export declare const CONTRACT_MANIFEST_SCHEMA_VERSION = "semaphor-generated-data-app-contract-manifest/v1";
+
+export declare function evaluateSemaphorDataAppContractUpdatePolicy({ beforeSummary, afterSummary, migrationReport, operationIntent, preferences, }: SemaphorDataAppContractUpdatePolicyInput): SemaphorDataAppContractUpdatePolicyResult;
+
+export declare const GENERATED_CONTRACT_SCHEMA_VERSION = "semaphor-generated-data-app-contract/v1";
+
+export declare const GENERATED_CONTRACT_TYPESCRIPT_FILES: readonly ["sources.ts", "fields.ts", "inputs.ts", "queries.ts", "bindings.ts", "accessors.ts", "metadata.ts", "index.ts"];
+
+declare type GeneratedRefContext = {
+    sourcesByKey: Map<string, JsonRecord>;
+};
+
+export declare function isSemaphorDataAppCodegenSummary(value: unknown): value is SemaphorDataAppCodegenSummary;
+
+declare type JsonRecord = Record<string, unknown>;
+
+export declare const REQUIRED_GENERATED_CONTRACT_FILES: readonly ["sources.ts", "fields.ts", "inputs.ts", "queries.ts", "bindings.ts", "accessors.ts", "metadata.ts", "index.ts", "contract.manifest.json"];
+
+export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_SCHEMA_VERSION: "semaphor-data-app-codegen-summary/v1";
+
+export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_VALIDATOR_VERSION: "semaphor-data-app-codegen-summary-validator/v2";
+
+declare type SemaphorAbsoluteTimeWindow = {
+    kind: 'absolute';
+    start: string;
+    end: string;
+};
+
+declare type SemaphorActiveInput<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBinding & {
+    kind: 'filter' | 'control';
+    label?: string;
+    value?: TValue;
+    isActive: boolean;
+    operator?: SemaphorInputOperator;
+    controlRole?: SemaphorControlRole;
+};
+
+declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type SemaphorAnalysisDriverMode = 'absolute_delta' | 'largest_negative' | 'largest_positive' | 'positive_and_negative' | 'all';
+
+declare type SemaphorAnalysisQueryOptions = {
+    chartTitle?: string;
+    chartType?: string;
+    driverMode?: SemaphorAnalysisDriverMode;
+    includePopulation?: boolean;
+    calendarContext?: CalendarContext;
+};
+
+declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+
+declare 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';
+};
+
+declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
+
+declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+
+declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+
+declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+
+declare type SemaphorControlRole = 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
+
+declare type SemaphorDataAppChecklistBinding = {
+    inputId?: string;
+    inputLabel?: string;
+    fieldRef?: SemaphorDataAppCodegenFieldRef;
+    optionValueField?: SemaphorDataAppCodegenFieldRef;
+    optionLabelField?: SemaphorDataAppCodegenFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+    relationshipsUsed?: SemaphorDataAppCodegenRelationshipUse[];
+};
+
+declare type SemaphorDataAppCodegenAnalysisIntent = SemaphorDataAppCodegenMetricIntent & {
+    analysis?: SemaphorMetricIntent['analysis'];
+    timeWindow?: SemaphorTimeWindow;
+    filters?: SemaphorDataAppCodegenAnalyticsFilter[];
+    driverMode?: 'absolute_delta' | 'largest_negative' | 'largest_positive' | 'positive_and_negative' | 'all';
+    includePopulation?: boolean;
+    calendarContext?: {
+        tz?: string;
+        weekStart?: number;
+        anchor?: 'now' | {
+            iso: string;
+        };
+    };
+};
+
+declare type SemaphorDataAppCodegenAnalyticsFilter = SemaphorAnalyticsFilter & {
+    field: SemaphorDataAppCodegenFieldRef;
+};
+
+declare type SemaphorDataAppCodegenComputation = {
+    kind: 'server_query';
+    queryKind: SemaphorDataAppCodegenQueryKind;
+    queryOwnership?: 'view_owned' | 'shared_query';
+    sourceKeys?: string[];
+    fieldNames?: string[];
+    inputIds?: string[];
+    tableExecution?: {
+        mode?: 'bounded' | 'server_paginated' | 'server_windowed';
+        initialLimit?: number;
+        sort?: 'server' | 'client_for_bounded_rows';
+        pagination?: 'offset' | 'cursor' | 'window' | 'not_needed';
+    };
+    reason?: string;
+} | {
+    kind: 'derived';
+    upstreamViewId: string;
+    derivation: string;
+    caveat?: string;
+} | {
+    kind: 'presentation_only';
+    reason?: string;
+} | {
+    kind: 'unsupported';
+    reason: string;
+    suggestedModelingFix: string;
+};
+
+declare type SemaphorDataAppCodegenExecutableView = {
+    id: string;
+    title?: string;
+    purpose?: string;
+    sourcePresentation?: SemaphorDataAppCodegenSourcePresentation;
+    visual?: string;
+    visualSpec?: SemaphorDataAppCodegenVisualSpec;
+    queryKind: SemaphorDataAppCodegenQueryKind;
+    sdkBuilder?: SemaphorDataAppCodegenSdkBuilder;
+    sdkSpec: SemaphorDataAppCodegenSdkSpec;
+    fields: SemaphorDataAppCodegenFieldRef[];
+    computation?: SemaphorDataAppCodegenComputation;
+    uxExpectations?: string[];
+    validation?: SemaphorDataAppCodegenViewValidation;
+};
+
+declare type SemaphorDataAppCodegenFallbackReason = {
+    code?: string;
+    message?: string;
+    governedAlternativesTried?: string[];
+    requiredModelingFix?: string;
+    acceptedByUser?: boolean;
+};
+
+declare type SemaphorDataAppCodegenFieldRef = SemaphorFieldRef & {
+    sourceKey?: string;
+};
+
+declare type SemaphorDataAppCodegenInput = {
+    id: string;
+    label?: string;
+    type?: string;
+    serverSide?: boolean;
+    fieldRef?: SemaphorDataAppCodegenFieldRef;
+    optionQuery?: SemaphorDataAppCodegenInputOptionQuery;
+    bindings?: SemaphorDataAppCodegenInputBinding[];
+    appliesToViewIds: string[];
+    relationshipHint?: SemaphorRelationshipHint;
+    relationshipsUsed?: SemaphorDataAppCodegenRelationshipUse[];
+};
+
+declare type SemaphorDataAppCodegenInputBinding = {
+    appliesToViewIds: string[];
+    fieldRef: SemaphorDataAppCodegenFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+    relationshipsUsed?: SemaphorDataAppCodegenRelationshipUse[];
+};
+
+declare type SemaphorDataAppCodegenInputOptionQuery = {
+    id?: string;
+    builder: 'semaphor.inputOptions';
+    source?: SemaphorSourceRef;
+    sourceKey?: string;
+    valueFieldRef: SemaphorDataAppCodegenFieldRef;
+    labelFieldRef: SemaphorDataAppCodegenFieldRef;
+    filterFieldRef?: SemaphorDataAppCodegenFieldRef;
+    population?: SemaphorInputOptionsIntent['population'];
+    dependencies?: SemaphorInputOptionsIntent['dependencies'];
+    limit?: number;
+    spec?: SemaphorDataAppCodegenInputOptionsIntent;
+};
+
+declare type SemaphorDataAppCodegenInputOptionsIntent = Omit<SemaphorInputOptionsIntent, 'kind' | 'labelField' | 'valueField' | 'searchField' | 'disambiguationFields'> & {
+    labelField: SemaphorDataAppCodegenFieldRef;
+    valueField: SemaphorDataAppCodegenFieldRef;
+    searchField?: SemaphorDataAppCodegenFieldRef;
+    disambiguationFields?: SemaphorDataAppCodegenFieldRef[];
+};
+
+declare type SemaphorDataAppCodegenMatrixIntent = {
+    source: Extract<SemaphorDataAppCodegenSource, {
+        kind: 'semantic' | 'physical';
+    }>;
+    id?: string;
+    label?: string;
+    filters?: SemaphorDataAppCodegenAnalyticsFilter[];
+    relationshipHint?: SemaphorRelationshipHint;
+    rows: Array<{
+        id?: string;
+        field?: SemaphorDataAppCodegenFieldRef;
+        grain?: SemaphorTimeGrain;
+        label?: string;
+        subtotal?: boolean | {
+            enabled?: boolean;
+            label?: string;
+        };
+    }>;
+    columns?: Array<{
+        id?: string;
+        field?: SemaphorDataAppCodegenFieldRef;
+        grain?: SemaphorTimeGrain;
+        label?: string;
+        subtotal?: boolean | {
+            enabled?: boolean;
+            label?: string;
+        };
+    }>;
+    values: Array<{
+        id?: string;
+        field?: SemaphorDataAppCodegenFieldRef;
+        aggregate?: SemaphorFieldRef['aggregate'];
+        label?: string;
+    }>;
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorDataAppCodegenMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: {
+        hierarchy?: 'compact' | 'tabular' | 'outline';
+        valuesPlacement?: 'columns' | 'rows';
+        stickyRowHeaders?: boolean;
+        stickyColumnHeaders?: boolean;
+    };
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorDataAppCodegenMatrixSortRule = Omit<SemaphorMatrixSortRule, 'by'> & {
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorDataAppCodegenFieldRef;
+        aggregate?: SemaphorFieldRef['aggregate'];
+    } | {
+        kind: 'value';
+        valueId: string;
+        rowPath?: SemaphorMatrixSortRule['by'] extends infer T ? T extends {
+            kind: 'value';
+            rowPath?: infer R;
+        } ? R : never : never;
+        columnPath?: SemaphorMatrixSortRule['by'] extends infer T ? T extends {
+            kind: 'value';
+            columnPath?: infer C;
+        } ? C : never : never;
+    };
+};
+
+declare type SemaphorDataAppCodegenMetricIntent = {
+    source: SemaphorDataAppCodegenSource;
+    id?: string;
+    label?: string;
+    measures: SemaphorDataAppCodegenFieldRef[];
+    primaryMeasure?: SemaphorDataAppCodegenFieldRef;
+    dateField?: SemaphorDataAppCodegenFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    dimensions?: SemaphorDataAppCodegenFieldRef[];
+    comparison?: SemaphorMetricIntent['comparison'];
+    orderBy?: {
+        field: SemaphorDataAppCodegenFieldRef;
+        direction: 'asc' | 'desc';
+    };
+    filters?: SemaphorDataAppCodegenAnalyticsFilter[];
+    relationshipHint?: SemaphorRelationshipHint;
+    limit?: number;
+    derivedFields?: SemaphorMetricIntent['derivedFields'];
+};
+
+declare type SemaphorDataAppCodegenPresentationView = {
+    id: string;
+    title?: string;
+    purpose?: string;
+    sourcePresentation?: SemaphorDataAppCodegenSourcePresentation;
+    visual?: 'text_block' | 'narrative' | string;
+    visualSpec?: SemaphorDataAppCodegenVisualSpec;
+    queryKind?: never;
+    sdkBuilder?: never;
+    sdkSpec?: never;
+    fields?: SemaphorDataAppCodegenFieldRef[];
+    computation: Extract<SemaphorDataAppCodegenComputation, {
+        kind: 'presentation_only' | 'unsupported' | 'derived';
+    }>;
+    uxExpectations?: string[];
+    validation?: SemaphorDataAppCodegenViewValidation;
+};
+
+declare type SemaphorDataAppCodegenQueryKind = 'metric' | 'records' | 'matrix' | 'analysis' | 'sql_fallback';
+
+declare type SemaphorDataAppCodegenRecordsIntent = {
+    source: SemaphorDataAppCodegenSource;
+    id?: string;
+    label?: string;
+    fields: SemaphorDataAppCodegenFieldRef[];
+    dateField?: SemaphorDataAppCodegenFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    timeWindow?: SemaphorTimeWindow;
+    filters?: SemaphorDataAppCodegenAnalyticsFilter[];
+    orderBy?: {
+        field: SemaphorDataAppCodegenFieldRef;
+        direction: 'asc' | 'desc';
+    };
+    relationshipHint?: SemaphorRelationshipHint;
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+    totals?: SemaphorDataAppCodegenRecordsServerTotalsRequest;
+    derivedFields?: SemaphorMetricIntent['derivedFields'];
+};
+
+declare type SemaphorDataAppCodegenRecordsServerTotalsRequest = {
+    mode: 'server';
+    measures: SemaphorDataAppCodegenSourceBearingFieldRef[];
+};
+
+declare type SemaphorDataAppCodegenRelationshipUse = {
+    id?: string;
+    fromSourceKey?: string;
+    toSourceKey?: string;
+    fields?: SemaphorDataAppCodegenFieldRef[];
+};
+
+declare type SemaphorDataAppCodegenSdkBuilder = 'semaphor.metric' | 'semaphor.records' | 'semaphor.matrix' | 'semaphor.analysis' | 'semaphor.sql';
+
+declare type SemaphorDataAppCodegenSdkSpec = {
+    builder: 'semaphor.metric';
+    spec: SemaphorDataAppCodegenMetricIntent;
+} | {
+    builder: 'semaphor.records';
+    spec: SemaphorDataAppCodegenRecordsIntent;
+} | {
+    builder: 'semaphor.matrix';
+    spec: SemaphorDataAppCodegenMatrixIntent;
+} | {
+    builder: 'semaphor.analysis';
+    spec: SemaphorDataAppCodegenAnalysisIntent;
+} | {
+    builder: 'semaphor.sql';
+    spec: SemaphorDataAppCodegenSqlIntent;
+    fallbackReason?: SemaphorDataAppCodegenFallbackReason;
+};
+
+declare type SemaphorDataAppCodegenSource = SemaphorSourceRef & {
+    sourceKey?: string;
+    datasetRole?: string;
+    relationshipCount?: number;
+    datasetShape?: 'event' | 'daily_snapshot' | 'latest_snapshot' | 'entity_state' | 'dimension' | 'bridge' | 'unknown';
+    dateSemantics?: {
+        primaryDateField?: SemaphorDataAppCodegenFieldRef;
+        primaryDateFieldSource?: 'authored' | 'single_candidate' | 'missing' | 'ambiguous' | 'authored_missing';
+        defaultTimeGrain?: SemaphorMetricIntent['timeGrain'];
+        defaultTimeWindow?: SemaphorMetricIntent['timeWindow'];
+        snapshot?: {
+            kind?: 'not_snapshot' | 'daily_snapshot' | 'latest_snapshot';
+            selector?: 'not_needed' | 'latest_available';
+            selectorSupported?: boolean;
+            dateField?: SemaphorDataAppCodegenFieldRef;
+            unsupportedReason?: string;
+        };
+    };
+};
+
+declare type SemaphorDataAppCodegenSourceBearingFieldRef = SemaphorDataAppCodegenFieldRef & ({
+    sourceKey: string;
+} | {
+    source: SemaphorSourceRef;
+});
+
+declare type SemaphorDataAppCodegenSourcePresentation = {
+    sourceKeys?: string[];
+    sourceLabels?: string[];
+};
+
+declare type SemaphorDataAppCodegenSqlIntent = Omit<SemaphorSqlIntent, 'kind' | 'fields'> & {
+    fields?: SemaphorDataAppCodegenFieldRef[];
+};
+
+export declare type SemaphorDataAppCodegenSummary = {
+    schemaVersion: SemaphorDataAppCodegenSummarySchemaVersion;
+    title: string;
+    purpose?: string;
+    userGoal?: string;
+    nextStep?: string;
+    sources: SemaphorDataAppCodegenSource[];
+    inputs: SemaphorDataAppCodegenInput[];
+    views: SemaphorDataAppCodegenView[];
+    filterContracts: SemaphorDataAppFilterContract[];
+    implementationChecklist: SemaphorDataAppImplementationChecklist;
+    nextRequiredTool?: {
+        name: string;
+        reason?: string;
+    };
+    unsupportedInsights?: SemaphorDataAppUnsupportedInsight[];
+    assumptions?: string[];
+    validation?: {
+        status?: 'ready' | 'partial' | 'blocked';
+        warnings?: string[];
+    };
+};
+
+export declare type SemaphorDataAppCodegenSummarySchemaVersion = typeof SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_SCHEMA_VERSION;
+
+export declare type SemaphorDataAppCodegenSummaryValidatorVersion = typeof SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_VALIDATOR_VERSION;
+
+declare type SemaphorDataAppCodegenTableBehavior = {
+    tableMode: 'bounded' | 'server_paginated' | 'server_windowed';
+    height: {
+        maxPx: number;
+        scroll: 'vertical' | 'both';
+        stickyHeader: boolean;
+    };
+    pagination: {
+        mode: 'none' | 'server' | 'client_for_bounded_rows';
+        pageSize?: number;
+        readsFrom?: 'result.pagination';
+    };
+    sorting: {
+        mode: 'server' | 'client_for_bounded_rows';
+        defaultField?: string;
+        defaultDirection?: 'asc' | 'desc';
+        resetPageOnChange?: boolean;
+    };
+    totals: {
+        mode: 'none';
+    } | SemaphorDataAppCodegenRecordsServerTotalsRequest | {
+        mode: 'local';
+        label: 'Displayed rows' | 'Current page';
+    };
+    serverSideRequired: boolean;
+};
+
+declare type SemaphorDataAppCodegenView = SemaphorDataAppCodegenExecutableView | SemaphorDataAppCodegenPresentationView;
+
+declare type SemaphorDataAppCodegenViewValidation = {
+    status?: 'ready' | 'partial' | 'blocked' | 'unsupported';
+    evidence?: string[];
+    warnings?: string[];
+};
+
+declare type SemaphorDataAppCodegenVisualSpec = {
+    visualType: 'kpi' | 'line_chart' | 'bar_chart' | 'stacked_bar_chart' | 'pie_chart' | 'donut_chart' | 'area_chart' | 'table' | 'matrix' | 'narrative' | 'text_block' | 'custom';
+    title?: string;
+    subtitle?: string;
+    encoding?: {
+        x?: string;
+        y?: string;
+        color?: string;
+        size?: string;
+        columns?: string[];
+        value?: string;
+    };
+    text?: {
+        body?: string;
+        variant?: 'plain' | 'parameterized';
+    };
+    sort?: {
+        field?: string;
+        direction?: 'asc' | 'desc';
+        execution?: 'server' | 'client_for_bounded_rows';
+    };
+    limit?: number;
+    interactions?: string[];
+    states?: string[];
+    tableBehavior?: SemaphorDataAppCodegenTableBehavior;
+};
+
+export declare type SemaphorDataAppContractUpdatePolicy = {
+    kind: string;
+    mode: 'invalid_update_preferences' | 'diagnostic_warning_fix' | 'metric_aggregate_override_edit' | 'general_iterative_update';
+    reason: string;
+    allowedViewChangeReasons?: string[];
+    targetViewIds?: string[];
+};
+
+export declare type SemaphorDataAppContractUpdatePolicyInput = {
+    beforeSummary?: unknown;
+    afterSummary?: unknown;
+    migrationReport?: unknown;
+    operationIntent?: unknown;
+    preferences?: unknown;
+};
+
+export declare type SemaphorDataAppContractUpdatePolicyResult = {
+    ok: boolean;
+    policy: SemaphorDataAppContractUpdatePolicy;
+    violations: SemaphorDataAppContractUpdatePolicyViolation[];
+};
+
+export declare type SemaphorDataAppContractUpdatePolicyViolation = {
+    path: string;
+    reason: string;
+};
+
+declare type SemaphorDataAppFilterContract = {
+    inputId: string;
+    label?: string;
+    type?: string;
+    serverSide?: boolean;
+    fieldRef?: SemaphorDataAppCodegenFieldRef;
+    optionQuery?: SemaphorDataAppCodegenInputOptionQuery;
+    bindings: SemaphorDataAppFilterContractBinding[];
+    appliesToViewIds: string[];
+    notAppliedToViewIds: string[];
+};
+
+declare type SemaphorDataAppFilterContractBinding = {
+    viewId: string;
+    fieldRef: SemaphorDataAppCodegenFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+    relationshipsUsed?: SemaphorDataAppCodegenRelationshipUse[];
+};
+
+declare type SemaphorDataAppFilterScope = {
+    inputId?: string;
+    label?: string;
+    type?: string;
+    scope?: 'dashboard' | 'section' | 'card';
+    appliesToViewIds?: string[];
+    notAppliedToViewIds?: string[];
+    cardAffordanceRequired?: boolean;
+};
+
+declare type SemaphorDataAppImplementationChecklist = {
+    schemaVersion?: string;
+    requiredDevtools: {
+        mountRootDevtools: boolean;
+        providerDebugBridge?: string;
+        panelPosition?: string;
+        forbidden?: string[];
+    };
+    requiredInputOptions: SemaphorDataAppRequiredInputOption[];
+    filterScopeByInput: SemaphorDataAppFilterScope[];
+    bindingsByView: Record<string, SemaphorDataAppChecklistBinding[]>;
+    validationCommands: string[];
+    browserSmokeChecks: string[];
+};
+
+declare type SemaphorDataAppRelationshipCandidate = {
+    source: SemaphorDataAppRelationshipCandidateSource;
+    sourceFields: SemaphorDataAppRelationshipCandidateField[];
+    target: SemaphorDataAppRelationshipCandidateSource;
+    targetFields: SemaphorDataAppRelationshipCandidateField[];
+};
+
+declare type SemaphorDataAppRelationshipCandidateField = Pick<SemaphorDataAppCodegenFieldRef, 'name' | 'label' | 'role' | 'dataType'>;
+
+declare type SemaphorDataAppRelationshipCandidateSource = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    sourceKey?: string;
+};
+
+declare type SemaphorDataAppRequiredInputOption = {
+    inputId?: string;
+    label?: string;
+    builder?: 'semaphor.inputOptions';
+    appliesToViewIds?: string[];
+    optionSourceKey?: string;
+    visibleLabelField?: SemaphorDataAppCodegenFieldRef;
+    optionValueField?: SemaphorDataAppCodegenFieldRef;
+    runtimeFilterField?: SemaphorDataAppCodegenFieldRef;
+    population?: SemaphorInputOptionsIntent['population'];
+    dependencies?: SemaphorInputOptionsIntent['dependencies'];
+};
+
+declare type SemaphorDataAppUnsupportedInsight = {
+    title: string;
+    requestedQuestion: string;
+    reason: 'missing_measure' | 'missing_dimension' | 'missing_date' | 'missing_relationship' | 'missing_semantic_role' | 'missing_current_app_state' | 'unsupported_change_intent' | 'ambiguous_field_grounding' | 'invalid_ranker_output' | 'latest_snapshot_selector_not_modeled' | 'unsupported_grain' | 'requires_sql_escape_hatch' | 'unsupported_sdk_capability';
+    suggestedModelingFix: string;
+    relationshipCandidate?: SemaphorDataAppRelationshipCandidate;
+    nextRepairAction?: {
+        tool: 'semaphor_propose_semantic_model_change';
+        reason: 'missing_relationship';
+    };
+};
+
+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?: SemaphorValueFormat;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
+
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+/**
+ * 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;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+export declare type SemaphorGeneratedContractFileName = (typeof REQUIRED_GENERATED_CONTRACT_FILES)[number];
+
+export declare type SemaphorGeneratedContractFiles = Record<SemaphorGeneratedContractFileName, string>;
+
+export declare type SemaphorGeneratedContractTypescriptFileName = (typeof GENERATED_CONTRACT_TYPESCRIPT_FILES)[number];
+
+export declare type SemaphorGeneratedContractValidationInput = {
+    manifest: unknown;
+    generatedFiles?: Record<string, string>;
+};
+
+export declare type SemaphorGeneratedContractValidationIssue = {
+    path?: string;
+    message: string;
+    repairHint?: string;
+};
+
+export declare type SemaphorGeneratedContractValidationResult = {
+    issues: SemaphorGeneratedContractValidationIssue[];
+};
+
+declare type SemaphorGeneratedQueryResultShape = 'metric' | 'records' | 'analysis' | 'matrix' | 'sql' | 'inputOptions';
+
+export declare type SemaphorGeneratedViewExecutionRequest = {
+    viewId: string;
+    intent: SemaphorAnalyticsIntent;
+    resultShape: SemaphorGeneratedQueryResultShape;
+    analysisOptions?: SemaphorAnalysisQueryOptions;
+};
+
+export declare type SemaphorGeneratedViewExecutionRequestIssue = {
+    viewId?: string;
+    path?: string;
+    message: string;
+};
+
+export declare type SemaphorGeneratedViewExecutionRequestsResult = {
+    requests: SemaphorGeneratedViewExecutionRequest[];
+    issues: SemaphorGeneratedViewExecutionRequestIssue[];
+};
+
+declare type SemaphorInputBinding = {
+    inputId: string;
+    kind?: 'filter' | 'control';
+    controlRole?: 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
+    operator?: SemaphorInputOperator;
+    field?: SemaphorFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
+
+declare type SemaphorInputOptionsIntent = {
+    kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    inputId: string;
+    source: SemaphorSourceRef;
+    labelField: SemaphorFieldRef;
+    valueField: SemaphorFieldRef;
+    searchField?: SemaphorFieldRef;
+    disambiguationFields?: SemaphorFieldRef[];
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
+    search?: string;
+    limit?: number;
+    inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
+declare type SemaphorInputValue = SemaphorScalar | SemaphorScalar[];
+
+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[];
+    relationshipHint?: SemaphorRelationshipHint;
+    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;
+    format?: SemaphorValueFormat;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
+declare type SemaphorMetricAnalysis = {
+    kind: 'period_change';
+    orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
+    direction?: 'increase' | 'decrease' | 'both';
+    timeWindow?: SemaphorTimeWindow;
+};
+
+declare 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[];
+};
+
+declare type SemaphorOptionDependencies = {
+    mode?: 'auto' | 'independent' | 'explicit';
+    includeInputIds?: string[];
+    excludeInputIds?: string[];
+};
+
+declare type SemaphorOptionPopulation = {
+    kind: 'option_source';
+    baseSource?: never;
+} | {
+    kind: 'related_population';
+    baseSource: SemaphorSourceRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
+declare type SemaphorPaginationRequest = {
+    page: number;
+    pageSize: number;
+};
+
+declare type SemaphorProtocolVersion = 1;
+
+declare 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;
+};
+
+declare type SemaphorRecordsServerTotalsRequest = {
+    mode: 'server';
+    measures: SemaphorFieldRef[];
+};
+
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
+declare type SemaphorRelativeTimeWindow = {
+    kind?: 'relative';
+    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    value: number;
+    anchor?: 'now' | 'latest_available';
+    completeness?: 'include_partial' | 'complete_periods';
+};
+
+declare type SemaphorScalar = string | number | boolean | null;
+
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+declare type 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[];
+};
+
+declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
+
+declare type SemaphorValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    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): {
+    ok: boolean;
+    issues: string[];
+};
+
+export declare function validateSemaphorGeneratedContract({ manifest, generatedFiles, }: SemaphorGeneratedContractValidationInput): Promise<SemaphorGeneratedContractValidationResult>;
+
+/**
+ * Week start day type.
+ * 0 = Sunday (US, Canada, Japan)
+ * 1 = Monday (ISO standard, most of Europe)
+ * 6 = Saturday (Middle East)
+ */
+declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+export { }