react-semaphor 0.1.381 → 0.1.383

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

@@ -1,5 +1,6 @@
-import { Context } from 'react';
+import { CSSProperties } from 'react';
 import { JSX } from 'react/jsx-runtime';
+import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 
 /**
@@ -37,7 +38,7 @@ export declare function defineSemaphorDataApp<TDefinition extends SemaphorDataAp
 
 export declare function defineSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputSpec<TValue>;
 
-export declare function hasSemaphorInputValue(value: unknown): boolean;
+export declare function isSemaphorInputValueValidForOptions(value: SemaphorInputValue | undefined, options: SemaphorInputOption[] | undefined): boolean;
 
 declare type MatrixAxisLevelDescriptor = {
     instanceId: string;
@@ -358,25 +359,19 @@ declare type MatrixWarning = {
     severity?: 'info' | 'warning' | 'error';
 };
 
-export declare function normalizeSemaphorAnalysisPayload(payload: SemaphorAnalysisPayload | undefined | null): SemaphorAnalysisPayload;
-
-export declare function normalizeSemaphorAnalysisQueryOptions(value: unknown, options?: {
-    pathPrefix?: string;
-    validateTimezone?: SemaphorAnalysisTimezoneValidator;
-}): SemaphorAnalysisQueryOptionsValidationResult;
-
-export declare function normalizeSemaphorInputOptions(options?: Array<{
-    label: string;
-    value: SemaphorOptionValue;
-} | SemaphorOptionValue>): {
-    label: string;
-    value: SemaphorOptionValue;
-}[];
-
-export declare function readWindowRuntime(): SemaphorDataAppWindowRuntime | undefined;
-
 export declare const semaphor: {
+    source: {
+        semantic(spec: SemaphorSemanticSourceBuilderSpec): SemaphorSourceRef;
+        sql(spec: Omit<SemaphorSqlSourceBuilderSpec, "kind">): SemaphorSqlSourceBuilderSpec;
+    };
+    field: {
+        measure(name: string, spec?: SemaphorFieldBuilderSpec): SemaphorFieldWithRole<"measure">;
+        dimension(name: string, spec?: SemaphorFieldBuilderSpec): SemaphorFieldWithRole<"dimension">;
+        date(name: string, spec?: SemaphorFieldBuilderSpec): SemaphorFieldWithRole<"date">;
+        id(name: string, spec?: SemaphorFieldBuilderSpec): SemaphorFieldWithRole<"id">;
+    };
     filter<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: Omit<SemaphorFilterInputSpec<TValue>, "kind">): SemaphorFilterInputSpec<TValue>;
+    bindInput(input: SemaphorInputReference, binding: SemaphorBindInputSpec): SemaphorInputBindingReference;
     control<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorControlBuilderSpec<TValue>): SemaphorControlInputSpec<TValue>;
     sqlParam<TValue extends SemaphorSqlParameterValue = SemaphorSqlParameterValue>(spec: SemaphorSqlParamInputSpec<TValue>): SemaphorControlInputSpec<TValue>;
     derivedField(spec: Omit<SemaphorDerivedFieldDefinition, "kind"> & {
@@ -444,20 +439,6 @@ export declare type SemaphorAnalysisQueryOptions = {
     calendarContext?: CalendarContext;
 };
 
-export declare type SemaphorAnalysisQueryOptionsValidationIssue = {
-    code: 'invalid_analysis_option';
-    message: string;
-    path: string;
-};
-
-export declare type SemaphorAnalysisQueryOptionsValidationResult = {
-    ok: true;
-    analysisOptions?: SemaphorAnalysisQueryOptions;
-} | {
-    ok: false;
-    issues: SemaphorAnalysisQueryOptionsValidationIssue[];
-};
-
 export declare type SemaphorAnalysisQueryResult = SemaphorQueryState & SemaphorAnalysisPayload & {
     id?: string;
     intent?: SemaphorMetricIntent;
@@ -475,8 +456,6 @@ export declare type SemaphorAnalysisResultSet = {
     rowCount?: number;
 };
 
-export declare type SemaphorAnalysisTimezoneValidator = (tz: string) => string | null;
-
 declare type SemaphorAnalyticsDiagnosticAnsweredItem = {
     slotId?: string;
     queryId?: string;
@@ -543,7 +522,7 @@ declare type SemaphorAnalyticsExecutionResult = {
 
 declare type SemaphorAnalyticsExecutionStatus = 'answered' | 'partial' | 'failed';
 
-declare type SemaphorAnalyticsFieldRole = 'metric' | 'dateField' | 'dimension' | 'input' | 'source' | 'sql';
+declare type SemaphorAnalyticsFieldRole = 'measure' | 'date' | 'dimension' | 'input' | 'source' | 'sql';
 
 export declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
 
@@ -573,7 +552,7 @@ declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
 
 declare type SemaphorAnalyticsPopulation = {
     scope: 'filtered_query';
-    metrics: Record<string, number | string | null>;
+    measures: Record<string, number | string | null>;
 };
 
 declare type SemaphorAnalyticsRepairHint = {
@@ -581,7 +560,7 @@ declare type SemaphorAnalyticsRepairHint = {
     message?: string;
     invalidField?: string;
     fieldRole?: SemaphorAnalyticsFieldRole;
-    validMetricCandidates?: string[];
+    validMeasureCandidates?: string[];
     validDateCandidates?: string[];
     validDimensionCandidates?: string[];
     recommendedNextStep: string;
@@ -599,7 +578,7 @@ declare type SemaphorAnalyticsResultBase = {
     pagination?: SemaphorPaginationMetadata;
 };
 
-declare type SemaphorAnalyticsValidationCode = 'missing_source' | 'invalid_source_kind' | 'missing_semantic_domain' | 'missing_dataset_name' | 'missing_connection_id' | 'missing_table_name' | 'missing_sql' | 'missing_metric' | 'missing_record_fields' | 'missing_input_options_field' | 'invalid_metric' | 'invalid_metric_list' | 'invalid_date_field' | 'invalid_dimension' | 'invalid_metric_dimensions' | 'conflicting_sql' | 'sql_policy_violation' | 'unsupported_intent_for_adapter' | 'invalid_analytics_kind' | 'invalid_analytics_intent';
+declare 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';
 
 declare type SemaphorAnalyticsValidationIssue = SemaphorProtocolIssue & {
     code: SemaphorAnalyticsValidationCode | string;
@@ -627,6 +606,10 @@ export declare type SemaphorAppDerivedFieldsSpec = {
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
+export declare type SemaphorBindInputSpec = Omit<SemaphorInputBinding, 'inputId'> & {
+    inputId?: string;
+};
+
 declare type SemaphorCompiledQuery = {
     kind: 'config';
     queryId: string;
@@ -663,9 +646,14 @@ export declare type SemaphorControlInputSpec<TValue extends SemaphorInputValue =
     role: SemaphorControlRole;
 };
 
-export declare type SemaphorControlRole = 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+export declare type SemaphorControlRole = 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
 
-export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
+export declare type SemaphorDataAppDebugConfig = boolean | {
+    enabled?: boolean;
+    exposeWindowBridge?: boolean;
+    maxQueries?: number;
+    maxEventsPerQuery?: number;
+};
 
 export declare type SemaphorDataAppDefinition = {
     id?: string;
@@ -676,54 +664,93 @@ export declare type SemaphorDataAppDefinition = {
     views: SemaphorDataAppViewDefinition[];
 };
 
-export declare type SemaphorDataAppFieldCatalog = {
-    source: SemaphorSourceRef;
-    sourceAliases?: SemaphorSourceRef[];
-    fields: SemaphorFieldRef[];
-};
-
-export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
-
-export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext & {
-    executor?: SemaphorQueryExecutor;
-    children: ReactNode;
+export declare type SemaphorDataAppDevtoolsState = {
+    enabled: boolean;
+    queries: SemaphorDataAppTrace[];
+    getQuery(queryId: string): SemaphorDataAppTrace | undefined;
+    getQueries(queryId: string): SemaphorDataAppTrace[];
 };
 
-export declare type SemaphorDataAppQuerySpecEnvelope = {
-    queryHook: 'useSemaphorQuery';
-    spec: SemaphorQueryDefinition;
+export declare type SemaphorDataAppDevtoolsWindowBridge = {
+    snapshot(): SemaphorDataAppDevtoolsState;
+    getQuery(queryId: string): SemaphorDataAppTrace | undefined;
+    getQueries(queryId: string): SemaphorDataAppTrace[];
 };
 
-export declare type SemaphorDataAppQueryValidation = {
-    queryHook: SemaphorDataAppQuerySpecEnvelope['queryHook'];
-    queryId?: string;
-    intent?: SemaphorAnalyticsIntent;
-    diagnostics: SemaphorDataAppValidationDiagnostic[];
-    executionResult: SemaphorAnalyticsExecutionResult;
-};
+export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, debug, children, }: SemaphorDataAppProviderProps): JSX.Element;
 
-export declare type SemaphorDataAppRuntime = SemaphorQueryExecutorContext & {
+export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext & {
     executor?: SemaphorQueryExecutor;
+    debug?: SemaphorDataAppDebugConfig;
+    children: ReactNode;
 };
 
-export declare type SemaphorDataAppValidationDiagnostic = {
-    severity: 'error' | 'warning';
-    code: 'invalid_query_spec' | 'invalid_analytics_intent' | 'invalid_source_ref' | 'missing_field' | 'unsupported_input_filter_composition' | string;
-    message: string;
-    path?: string;
-    queryHook?: SemaphorDataAppQuerySpecEnvelope['queryHook'];
-    queryId?: string;
-    intentId?: string;
-    source?: SemaphorSourceRef;
-    field?: SemaphorFieldRef;
+export declare type SemaphorDataAppTrace = {
+    traceId: string;
+    viewId?: string;
+    queryId: string;
+    queryLabel?: string;
+    queryKind: SemaphorQueryDefinition['queryKind'];
+    builder: 'semaphor.metric' | 'semaphor.records' | 'semaphor.matrix' | 'semaphor.analysis' | 'semaphor.inputOptions' | 'semaphor.sql';
+    sourceRefs: SemaphorSourceRef[];
+    projectionFieldRefs?: SemaphorFieldRef[];
+    inputFieldRefs?: SemaphorFieldRef[];
+    fieldRefs: SemaphorFieldRef[];
+    inputsApplied: Array<{
+        inputId: string;
+        fieldRef?: SemaphorFieldRef;
+        operator?: string;
+        valuePreview?: string;
+    }>;
+    latestAttempt?: {
+        requestId?: string;
+        status: SemaphorQueryStatus;
+        durationMs?: number;
+        rowCount?: number;
+        columnCount?: number;
+        cacheStatus?: 'hit' | 'miss' | 'unknown';
+        executionResult?: SemaphorAnalyticsExecutionResult;
+        errorMessage?: string;
+    };
+    recentEvents: SemaphorDataAppTraceEvent[];
+    server?: {
+        compiledSql?: string;
+        dialect?: string;
+        sqlHash?: string;
+        executionPlanSummary?: string;
+    };
+    clientWarnings: string[];
 };
 
-export declare type SemaphorDataAppValidationResult = {
-    ok: boolean;
-    diagnostics: SemaphorDataAppValidationDiagnostic[];
-    queries: SemaphorDataAppQueryValidation[];
-    intents: SemaphorAnalyticsIntent[];
-    executionResults: SemaphorAnalyticsExecutionResult[];
+export declare type SemaphorDataAppTraceEvent = {
+    type: 'query_started';
+    queryId: string;
+    requestId?: string;
+    at: string;
+} | {
+    type: 'query_succeeded';
+    queryId: string;
+    requestId?: string;
+    at: string;
+    rowCount?: number;
+    durationMs?: number;
+} | {
+    type: 'query_failed';
+    queryId: string;
+    requestId?: string;
+    at: string;
+    errorMessage: string;
+} | {
+    type: 'query_ignored_stale';
+    queryId: string;
+    requestId?: string;
+    at: string;
+    reason: 'newer_inputs' | 'unmounted' | 'superseded';
+} | {
+    type: 'input_changed';
+    inputId: string;
+    at: string;
+    valuePreview?: string;
 };
 
 export declare type SemaphorDataAppViewDefinition<TQuery extends SemaphorQueryDefinition = SemaphorQueryDefinition> = {
@@ -734,14 +761,6 @@ export declare type SemaphorDataAppViewDefinition<TQuery extends SemaphorQueryDe
     inputs?: SemaphorInputReference[];
 };
 
-declare type SemaphorDataAppWindowRuntime = {
-    apiBaseUrl?: string;
-    dataApiBaseUrl?: string;
-    authToken?: null | {
-        accessToken?: string;
-    };
-};
-
 declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
 
 declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
@@ -770,15 +789,29 @@ 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 SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
+
+export declare function SemaphorDevtools({ buttonPosition, initialIsOpen, panelPosition, className, style, }?: SemaphorDevtoolsProps): ReactElement | null;
+
+export declare function SemaphorDevtoolsInspectButton({ queryId, viewId, label, className, style, }?: SemaphorDevtoolsInspectButtonProps): ReactElement | null;
+
+export declare type SemaphorDevtoolsInspectButtonProps = {
+    queryId?: string;
+    viewId?: string;
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+};
+
+export declare type SemaphorDevtoolsProps = {
+    buttonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'relative';
+    initialIsOpen?: boolean;
+    panelPosition?: 'bottom' | 'right';
+    className?: string;
+    style?: CSSProperties;
+};
 
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
@@ -797,6 +830,8 @@ declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
     kind: 'physical';
 }>;
 
+export declare type SemaphorFieldBuilderSpec = Omit<SemaphorFieldRef, 'name' | 'role'>;
+
 export declare type SemaphorFieldRef = {
     name: string;
     label?: string;
@@ -806,10 +841,15 @@ export declare type SemaphorFieldRef = {
     aggregate?: SemaphorAggregateFunction;
 };
 
+declare type SemaphorFieldWithRole<TRole extends NonNullable<SemaphorFieldRef['role']>> = SemaphorFieldRef & {
+    role: TRole;
+};
+
 export declare type SemaphorFilterInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'filter';
     field: SemaphorQueryField;
-    operator?: SemaphorInputOperatorInput;
+    operator?: SemaphorInputOperator;
+    relationshipHint?: SemaphorInputBinding['relationshipHint'];
     multi?: boolean;
 };
 
@@ -824,12 +864,17 @@ declare type SemaphorInputBase<TValue extends SemaphorInputValue> = {
     options?: Array<SemaphorInputOption | SemaphorOptionValue>;
 };
 
-declare type SemaphorInputBinding = {
+export declare type SemaphorInputBinding = {
     inputId: string;
     kind?: 'filter' | 'control';
-    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    controlRole?: 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
     operator?: SemaphorInputOperator;
     field?: SemaphorFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
+export declare type SemaphorInputBindingReference<TValue extends SemaphorInputValue = SemaphorInputValue> = {
+    toAnalyticsInput(): SemaphorActiveInput<TValue>;
 };
 
 export declare type SemaphorInputHandle<TValue extends SemaphorInputValue = SemaphorInputValue> = {
@@ -838,6 +883,7 @@ export declare type SemaphorInputHandle<TValue extends SemaphorInputValue = Sema
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
+    relationshipHint?: SemaphorInputBinding['relationshipHint'];
     controlRole?: SemaphorControlRole;
     value: TValue | undefined;
     options: SemaphorInputOption[];
@@ -849,14 +895,11 @@ export declare type SemaphorInputHandle<TValue extends SemaphorInputValue = Sema
 
 export declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
 
-declare type SemaphorInputOperatorAlias = 'eq' | 'equals' | 'not_equals' | 'neq' | 'not equal' | 'not equals' | 'not in' | 'like' | 'not_contains' | 'not contains' | 'not_like' | 'not like' | 'not_between' | 'not between';
-
-export declare type SemaphorInputOperatorInput = SemaphorInputOperator | SemaphorInputOperatorAlias;
-
 export declare type SemaphorInputOption = {
     label: string;
     value: SemaphorOptionValue;
     count?: number;
+    disambiguation?: string[];
 };
 
 declare type SemaphorInputOptionsIntent = {
@@ -864,10 +907,17 @@ declare type SemaphorInputOptionsIntent = {
     version?: SemaphorProtocolVersion;
     id?: string;
     label?: string;
+    inputId: string;
     source: SemaphorSourceRef;
-    field: SemaphorFieldRef;
+    labelField: SemaphorFieldRef;
+    valueField: SemaphorFieldRef;
+    searchField?: SemaphorFieldRef;
+    disambiguationFields?: SemaphorFieldRef[];
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
     search?: string;
     limit?: number;
+    inputs?: SemaphorInputBinding[];
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
@@ -890,7 +940,14 @@ export declare type SemaphorInputOptionsQueryResult = SemaphorQueryState & Semap
 export declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
-    field: SemaphorQueryField;
+    inputId: string;
+    labelField: SemaphorQueryField;
+    valueField: SemaphorQueryField;
+    searchField?: SemaphorQueryField;
+    disambiguationFields?: SemaphorQueryField[];
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
+    inputs?: SemaphorInputReference[];
     search?: string;
     limit?: number;
 };
@@ -901,10 +958,11 @@ declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
         label: string;
         value: unknown;
         count?: number;
+        disambiguation?: string[];
     }>;
 };
 
-export declare type SemaphorInputReference = SemaphorInputSpec | SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle;
+export declare type SemaphorInputReference = SemaphorInputSpec | SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle | SemaphorInputBindingReference;
 
 export declare type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
 
@@ -970,6 +1028,7 @@ export declare type SemaphorMatrixIntent = {
     values: SemaphorMatrixValueField[];
     filters?: SemaphorAnalyticsFilter[];
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     totals?: SemaphorMatrixTotalOptions;
     sort?: SemaphorMatrixSortRule[];
     expansion?: SemaphorMatrixExpansionOptions;
@@ -1134,8 +1193,8 @@ declare type SemaphorMetricIntent = {
     version?: SemaphorProtocolVersion;
     id?: string;
     source: SemaphorSourceRef;
-    metrics: SemaphorFieldRef[];
-    primaryMetric?: SemaphorFieldRef;
+    measures: SemaphorFieldRef[];
+    primaryMeasure?: SemaphorFieldRef;
     label?: string;
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
@@ -1152,13 +1211,14 @@ declare type SemaphorMetricIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     limit?: number;
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 export declare type SemaphorMetricPayload = {
     value: number | string | null;
-    metrics?: Record<string, number | string | null>;
+    measures?: Record<string, number | string | null>;
     comparisonValue?: number | string | null;
     delta?: number | null;
     deltaPercent?: number | null;
@@ -1178,14 +1238,15 @@ export declare type SemaphorMetricQueryResult = SemaphorQueryState & SemaphorMet
 export declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
-    metrics: SemaphorNonEmptyArray<SemaphorQueryField>;
-    primaryMetric?: SemaphorQueryField;
+    measures: SemaphorNonEmptyArray<SemaphorQueryField>;
+    primaryMeasure?: SemaphorQueryField;
     dateField?: SemaphorQueryField;
     timeGrain?: SemaphorTimeGrain;
     dimensions?: SemaphorQueryField[];
     comparison?: SemaphorMetricComparison;
     orderBy?: SemaphorQueryOrderBy;
     inputs?: SemaphorInputReference[];
+    relationshipHint?: SemaphorRelationshipHint;
     limit?: number;
 };
 
@@ -1202,6 +1263,21 @@ declare type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
 
 export declare type SemaphorNonEmptyArray<T> = [T, ...T[]];
 
+export declare type SemaphorOptionDependencies = {
+    mode?: 'auto' | 'independent' | 'explicit';
+    includeInputIds?: string[];
+    excludeInputIds?: string[];
+};
+
+export declare type SemaphorOptionPopulation = {
+    kind: 'option_source';
+    baseSource?: never;
+} | {
+    kind: 'related_population';
+    baseSource: SemaphorSourceRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
 export declare type SemaphorOptionValue = string | number | boolean;
 
 export declare type SemaphorPaginationMetadata = {
@@ -1226,6 +1302,11 @@ declare type SemaphorProtocolIssue = {
 
 declare type SemaphorProtocolVersion = 1;
 
+export declare type SemaphorQueryDebugOptions = {
+    viewId?: string;
+    title?: string;
+};
+
 export declare type SemaphorQueryDefinition = SemaphorMetricQueryDefinition | SemaphorAnalysisQueryDefinition | SemaphorRecordsQueryDefinition | SemaphorInputOptionsQueryDefinition | SemaphorSqlQueryDefinition | SemaphorMatrixQueryDefinition;
 
 export declare type SemaphorQueryExecutor = {
@@ -1260,6 +1341,7 @@ export declare type SemaphorQueryResultFor<TQuery extends SemaphorQueryDefinitio
 
 export declare type SemaphorQueryRuntimeOptions = {
     inputs?: SemaphorInputReference[];
+    debug?: SemaphorQueryDebugOptions;
 };
 
 export declare type SemaphorQuerySourceSpec = {
@@ -1270,6 +1352,7 @@ export declare type SemaphorQueryState = {
     status: SemaphorQueryStatus;
     isLoading: boolean;
     error: Error | null;
+    trace?: SemaphorDataAppTrace;
 };
 
 export declare type SemaphorQueryStatus = 'idle' | 'loading' | 'success' | 'error';
@@ -1283,6 +1366,7 @@ declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & SemaphorAp
     filters?: SemaphorAnalyticsFilter[];
     orderBy?: SemaphorRecordsOrderBy;
     inputs?: SemaphorInputReference[];
+    relationshipHint?: SemaphorRelationshipHint;
     limit?: number;
     pagination?: SemaphorPaginationRequest;
 };
@@ -1309,6 +1393,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
@@ -1364,6 +1449,10 @@ declare type SemaphorRelationshipDiagnostics = {
 
 declare type SemaphorRelationshipDiagnosticStatus = 'not_required' | 'resolved' | 'missing' | 'ambiguous' | 'fanout_risk' | 'unknown';
 
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
     unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
@@ -1397,6 +1486,14 @@ export declare type SemaphorRowsQueryResult<TRecord extends Record<string, unkno
 
 export declare type SemaphorScalar = string | number | boolean | null;
 
+export declare type SemaphorSemanticSourceBuilderSpec = {
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    connectionId?: string;
+    label?: string;
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -1491,6 +1588,10 @@ declare type SemaphorSqlResult = SemaphorAnalyticsResultBase & {
     };
 };
 
+export declare type SemaphorSqlSourceBuilderSpec = Extract<SemaphorSourceRef, {
+    kind: 'sql';
+}>;
+
 export declare type SemaphorSqlSourceSpec = {
     source: Extract<SemaphorSourceRef, {
         kind: 'sql';
@@ -1539,39 +1640,15 @@ declare type SemaphorValueFormat = {
     suffix?: string;
 };
 
-export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
-
-export declare function toSemaphorAnalysisIntent(spec: SemaphorAnalysisQuerySpec): SemaphorMetricIntent;
-
-export declare function toSemaphorAnalysisQueryOptions(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryOptions;
-
-export declare function toSemaphorInputBinding(input: SemaphorInputReference): SemaphorInputBinding;
-
-export declare function toSemaphorInputBindings(inputs: SemaphorInputReference[] | undefined): SemaphorInputBinding[] | undefined;
-
-export declare function toSemaphorInputOptionsIntent(spec: SemaphorInputOptionsQuerySpec): Extract<SemaphorAnalyticsIntent, {
-    kind: 'inputOptions';
-}>;
-
-export declare function toSemaphorInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
-
-export declare function toSemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputBinding & {
-    kind: SemaphorInputSpec['kind'];
-    label?: string;
-    field?: SemaphorFieldRef;
-    operator?: SemaphorInputOperator;
-    controlRole?: SemaphorControlRole;
-};
-
-export declare function toSemaphorMatrixIntent(spec: SemaphorMatrixQuerySpec): SemaphorMatrixIntent;
-
-export declare function toSemaphorMetricIntent(spec: SemaphorMetricQuerySpec): SemaphorMetricIntent;
-
-export declare function toSemaphorRecordsIntent(spec: SemaphorRecordsQuerySpec): SemaphorRecordsIntent;
+export declare function SemaphorViewBoundary({ id, title, children, }: {
+    id: string;
+    title?: string;
+    children: ReactNode;
+}): ReactElement;
 
-export declare function toSemaphorSqlIntent(spec: SemaphorSqlQuerySpec): SemaphorSqlIntent;
+export declare function useClearInvalidSemaphorInputValue(input: SemaphorInputHandle, optionsResult: Pick<SemaphorInputOptionsQueryResult, 'options' | 'status'> | undefined): void;
 
-export declare function useSemaphorDataAppRuntime(): SemaphorDataAppRuntime;
+export declare function useSemaphorDevtools(): SemaphorDataAppDevtoolsState;
 
 export declare function useSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputHandle;
 
@@ -1589,13 +1666,6 @@ export declare function useSemaphorQuery<TRecord extends Record<string, unknown>
 
 export declare function useSemaphorQuery(spec: SemaphorMatrixQueryDefinition, options?: SemaphorQueryRuntimeOptions): SemaphorMatrixQueryResult;
 
-export declare function validateSemaphorDataAppQuerySpecs(input: {
-    queries: SemaphorDataAppQuerySpecEnvelope[];
-    fieldCatalogs?: SemaphorDataAppFieldCatalog[];
-    requireFieldCatalog?: boolean;
-    validateTimezone?: SemaphorAnalysisTimezoneValidator;
-}): SemaphorDataAppValidationResult;
-
 /**
  * Week start day type.
  * 0 = Sunday (US, Canada, Japan)