react-semaphor 0.1.495 → 0.1.496

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

@@ -13898,10 +13898,17 @@ export declare function isExactNumericValue(value: unknown): value is ExactNumer
 /** Null expansion means all detail, not the browser's default depth. */
 export declare function isMatrixPathExpanded(path: MatrixPath, expansion: MatrixExpansion | null): boolean;
 
+/** Null checks carry no values but still constrain the option list. */
+export declare function isNullCheckPredicate(predicate: Pick<NativePredicateSemantics, 'operation'>): boolean;
+
+export declare function isOverridableOptionDependencyReason(reason: unknown): reason is (typeof OVERRIDABLE_OPTION_DEPENDENCY_REASONS)[number];
+
 export declare function isSemaphorAnalyzeResultFieldName(value: string): value is SemaphorAnalyzeResultFieldName;
 
 export declare function isSemaphorDataAppCodegenSummary(value: unknown): value is SemaphorDataAppCodegenSummary;
 
+export declare function isSemaphorOptionMatchValue(value: unknown): value is SemaphorOptionMatchValue;
+
 /**
  * Classifies persisted selected-entity metadata. This is structural metadata
  * handling; it does not inspect or parse authored SQL.
@@ -60110,6 +60117,10 @@ export declare const matrixWindowSchema: z.ZodEffects<z.ZodObject<{
     }[];
 }>;
 
+/** 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 declare function mergeSemaphorSourcesByIdentity<TSource extends SemaphorSourceRef>(sources: readonly TSource[]): TSource[];
 
 export declare type MetricComparisonConfig = {
@@ -60269,6 +60280,34 @@ declare type MonthAlignedFiscalCalendar = {
     yearStartMonth: number;
 };
 
+export declare const NATIVE_PREDICATE_OPERATIONS: readonly ["=", "!=", ">", "<", ">=", "<=", "like", "not like", "between", "not between", "in", "not in", "is null", "is not null"];
+
+export declare type NativePredicateOperation = (typeof NATIVE_PREDICATE_OPERATIONS)[number];
+
+/**
+ * Predicate semantics a dashboard transport wants executed verbatim. This is
+ * a closed contract: only the keys below survive, so a native filter value
+ * crossing a JSON boundary can never carry identity (field name, qualified
+ * name, owning entity, datatype, source context, calculated expression). The
+ * server rebuilds identity from grounding and re-applies the same contract.
+ */
+export declare type NativePredicateSemantics = {
+    operation: NativePredicateOperation;
+    values: unknown[];
+    valueType?: 'string' | 'number' | 'date' | 'boolean';
+    temporalBucket?: unknown;
+    relativeMeta?: unknown;
+    temporalPrecision?: unknown;
+};
+
+/**
+ * The allowlisted keys of a native filter value, unvalidated. This is what a
+ * client transport sends: it never decides whether a predicate is executable,
+ * so nothing is dropped on the way to the server, and it never carries a key
+ * outside the contract. Returns undefined only for a non-object value.
+ */
+export declare type NativePredicateSemanticsCandidate = Partial<Record<keyof NativePredicateSemantics, unknown>>;
+
 export declare function normalizeAnalyticsCatalogDataType(value: unknown): AnalyticsCatalogDataType;
 
 export declare function normalizeAnalyticsCatalogName(value: unknown): string;
@@ -60299,8 +60338,36 @@ export declare const nullableScalarSchema: z.ZodUnion<[z.ZodNumber, z.ZodString,
 
 declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
 
+/**
+ * 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 parseMatrixRuntimeInputs(input: unknown): MatrixRuntimeInputs;
 
+/**
+ * Builds validated predicate semantics from a native filter value or a
+ * transported candidate. Returns undefined when the operation or cardinality
+ * is not executable; the server reports that as a typed outcome rather than
+ * dropping the candidate.
+ */
+export declare function parseNativePredicateSemantics(value: unknown): NativePredicateSemantics | undefined;
+
+/**
+ * The one structural rule for `matchValues` on every transport: a non-empty
+ * list of scalar values within the bound. Both the intent validator and the
+ * standard body parser use it, so the two transports cannot drift.
+ */
+export declare function parseOptionMatchValues(raw: unknown): {
+    ok: true;
+    values: SemaphorOptionMatchValue[];
+} | {
+    ok: false;
+    error: string;
+};
+
 /** Strictly parses one raw temporal descriptor at a result boundary. */
 export declare function parseRawTemporalValueMetadata(input: unknown): RawTemporalValueMetadata;
 
@@ -60315,6 +60382,14 @@ export declare function parseSemaphorQualifiedSourcePath(input: {
     capabilities: Pick<SemaphorConnectionCapabilities, 'prefixLevels'>;
 }): SemaphorSourceCoordinateInput;
 
+/**
+ * The unqualified, unquoted leaf of a persisted identifier path such as
+ * `schema.table.column`, `"Column Name"`, `` `col` `` or `[col]`. Persisted
+ * filter names and columns carry dialect quoting; consumers that need the
+ * bare column name use this instead of hand-rolled string surgery.
+ */
+export declare function persistedIdentifierLeafName(value: string | null | undefined): string;
+
 declare type PhysicalResolutionCapabilities = Pick<SemaphorConnectionCapabilities, 'dialect' | 'prefixLevels'>;
 
 export declare function preferSemaphorFieldRefMetadata(current: SemaphorFieldRef, next: SemaphorFieldRef): SemaphorFieldRef;
@@ -61917,6 +61992,8 @@ declare const presentationFields: {
     }>>;
 };
 
+export declare function projectNativePredicateSemantics(value: unknown): NativePredicateSemanticsCandidate | undefined;
+
 export declare const RAW_TEMPORAL_CONTRACT_ERROR_CODES: {
     readonly invalidMetadata: "invalid_raw_temporal_metadata";
 };
@@ -65081,6 +65158,15 @@ export declare type SemaphorInputOptionsIntent = SemaphorInputOptionSource & {
     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[];
 };
@@ -65097,6 +65183,9 @@ export declare type SemaphorInputOptionSource = {
 
 export declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
     kind: 'inputOptions';
+    dependencyOutcomes?: SemaphorOptionDependencyOutcome[];
+    /** Present when the intent carried `matchValues`. */
+    match?: SemaphorOptionMatchResult;
     options: Array<{
         label: string;
         value: unknown;
@@ -65107,6 +65196,29 @@ export declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
 
 export declare const semaphorInputOptionsResultSchema: z.ZodObject<{
     kind: z.ZodLiteral<"inputOptions">;
+    dependencyOutcomes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        inputId: z.ZodString;
+        status: z.ZodEnum<["applied", "inactive", "skipped", "overridden", "error"]>;
+        reason: z.ZodOptional<z.ZodEnum<["unrelated", "population_required", "missing_dependency", "missing_relationship", "ambiguous_relationship", "invalid_metadata", "unsupported_dependency", "override_not_eligible"]>>;
+    }, "strip", z.ZodTypeAny, {
+        status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+        inputId: string;
+        reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+    }, {
+        status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+        inputId: string;
+        reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+    }>, "many">>;
+    match: z.ZodOptional<z.ZodObject<{
+        complete: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodEnum<["unsupported", "truncated"]>>;
+    }, "strip", z.ZodTypeAny, {
+        complete: boolean;
+        reason?: "unsupported" | "truncated" | undefined;
+    }, {
+        complete: boolean;
+        reason?: "unsupported" | "truncated" | undefined;
+    }>>;
     options: z.ZodArray<z.ZodEffects<z.ZodObject<z.ZodRawShape, "passthrough", z.ZodTypeAny, z.objectOutputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">, z.objectInputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">>, z.objectOutputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">, z.objectInputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">>, "many">;
     intentId: z.ZodOptional<z.ZodString>;
     queryPath: z.ZodEnum<["query_spec", "sql", "sql_python"]>;
@@ -65138,6 +65250,29 @@ export declare const semaphorInputOptionsResultSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     kind: z.ZodLiteral<"inputOptions">;
+    dependencyOutcomes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        inputId: z.ZodString;
+        status: z.ZodEnum<["applied", "inactive", "skipped", "overridden", "error"]>;
+        reason: z.ZodOptional<z.ZodEnum<["unrelated", "population_required", "missing_dependency", "missing_relationship", "ambiguous_relationship", "invalid_metadata", "unsupported_dependency", "override_not_eligible"]>>;
+    }, "strip", z.ZodTypeAny, {
+        status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+        inputId: string;
+        reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+    }, {
+        status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+        inputId: string;
+        reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+    }>, "many">>;
+    match: z.ZodOptional<z.ZodObject<{
+        complete: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodEnum<["unsupported", "truncated"]>>;
+    }, "strip", z.ZodTypeAny, {
+        complete: boolean;
+        reason?: "unsupported" | "truncated" | undefined;
+    }, {
+        complete: boolean;
+        reason?: "unsupported" | "truncated" | undefined;
+    }>>;
     options: z.ZodArray<z.ZodEffects<z.ZodObject<z.ZodRawShape, "passthrough", z.ZodTypeAny, z.objectOutputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">, z.objectInputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">>, z.objectOutputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">, z.objectInputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">>, "many">;
     intentId: z.ZodOptional<z.ZodString>;
     queryPath: z.ZodEnum<["query_spec", "sql", "sql_python"]>;
@@ -65169,6 +65304,29 @@ export declare const semaphorInputOptionsResultSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     kind: z.ZodLiteral<"inputOptions">;
+    dependencyOutcomes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        inputId: z.ZodString;
+        status: z.ZodEnum<["applied", "inactive", "skipped", "overridden", "error"]>;
+        reason: z.ZodOptional<z.ZodEnum<["unrelated", "population_required", "missing_dependency", "missing_relationship", "ambiguous_relationship", "invalid_metadata", "unsupported_dependency", "override_not_eligible"]>>;
+    }, "strip", z.ZodTypeAny, {
+        status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+        inputId: string;
+        reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+    }, {
+        status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+        inputId: string;
+        reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+    }>, "many">>;
+    match: z.ZodOptional<z.ZodObject<{
+        complete: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodEnum<["unsupported", "truncated"]>>;
+    }, "strip", z.ZodTypeAny, {
+        complete: boolean;
+        reason?: "unsupported" | "truncated" | undefined;
+    }, {
+        complete: boolean;
+        reason?: "unsupported" | "truncated" | undefined;
+    }>>;
     options: z.ZodArray<z.ZodEffects<z.ZodObject<z.ZodRawShape, "passthrough", z.ZodTypeAny, z.objectOutputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">, z.objectInputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">>, z.objectOutputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">, z.objectInputType<z.ZodRawShape, z.ZodTypeAny, "passthrough">>, "many">;
     intentId: z.ZodOptional<z.ZodString>;
     queryPath: z.ZodEnum<["query_spec", "sql", "sql_python"]>;
@@ -65454,11 +65612,78 @@ export declare type SemaphorOperationIntent = {
 };
 
 export declare type SemaphorOptionDependencies = {
-    mode?: 'independent' | 'explicit';
+    /** 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[];
+};
+
+export declare type SemaphorOptionDependencyMode = 'independent' | 'explicit' | 'all_applicable';
+
+/** 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 declare type SemaphorOptionDependencyOutcome = {
+    inputId: string;
+    status: SemaphorOptionDependencyOutcomeStatus;
+    reason?: SemaphorOptionDependencyOutcomeReason;
+};
+
+export declare type SemaphorOptionDependencyOutcomeReason = 'unrelated' | 'population_required' | 'missing_dependency' | 'missing_relationship' | 'ambiguous_relationship' | 'invalid_metadata' | 'unsupported_dependency' | 'override_not_eligible';
+
+export declare const semaphorOptionDependencyOutcomeSchema: z.ZodObject<{
+    inputId: z.ZodString;
+    status: z.ZodEnum<["applied", "inactive", "skipped", "overridden", "error"]>;
+    reason: z.ZodOptional<z.ZodEnum<["unrelated", "population_required", "missing_dependency", "missing_relationship", "ambiguous_relationship", "invalid_metadata", "unsupported_dependency", "override_not_eligible"]>>;
+}, "strip", z.ZodTypeAny, {
+    status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+    inputId: string;
+    reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+}, {
+    status: "applied" | "inactive" | "skipped" | "overridden" | "error";
+    inputId: string;
+    reason?: "unrelated" | "population_required" | "missing_dependency" | "missing_relationship" | "ambiguous_relationship" | "invalid_metadata" | "unsupported_dependency" | "override_not_eligible" | undefined;
+}>;
+
+export declare type SemaphorOptionDependencyOutcomeStatus = 'applied' | 'inactive' | 'skipped' | 'overridden' | 'error';
+
+export declare type SemaphorOptionDependencyValidationProfile = 'protocol' | 'dashboard';
+
+export declare 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 declare const semaphorOptionMatchResultSchema: z.ZodObject<{
+    complete: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodEnum<["unsupported", "truncated"]>>;
+}, "strip", z.ZodTypeAny, {
+    complete: boolean;
+    reason?: "unsupported" | "truncated" | undefined;
+}, {
+    complete: boolean;
+    reason?: "unsupported" | "truncated" | undefined;
+}>;
+
+/**
+ * A raw value a relevance check may submit. NULL is deliberately excluded:
+ * an `in` predicate cannot express "is null", so a null selection can never
+ * be proven present or absent by this check and stays unknown on the client.
+ */
+export declare type SemaphorOptionMatchValue = string | number | boolean;
+
 export declare type SemaphorOptionPopulation = {
     kind: 'option_source';
     baseSource?: never;
@@ -68181,6 +68406,24 @@ declare interface TimeDrillStep {
 
 declare type TimeGranularity = SemaphorTimeGrain;
 
+/**
+ * Semantics of a native filter value the caller already trusts structurally.
+ * Throws only for programming errors (an unknown operation on a typed filter
+ * value); JSON callers must use `parseNativePredicateSemantics`.
+ */
+export declare function toNativePredicateSemantics(filter: {
+    operation: string;
+    values: unknown[];
+} & Record<string, unknown>): NativePredicateSemantics;
+
+/**
+ * Maps a dashboard filter operation (the `TFilterValue.operation` vocabulary)
+ * to the shared input operator. Null checks have no input operator; callers
+ * that carry the native predicate keep the original operation and only use
+ * this mapping to describe the binding.
+ */
+export declare function toSemaphorInputOperatorFromFilterOperation(operation: string | null | undefined): SemaphorInputOperator | undefined;
+
 /**
  * Validates the atomic column boundary for an activated canonical producer.
  * Expected keys come from the producer's typed field/output mapping; this
@@ -68223,6 +68466,18 @@ export declare function validateSemaphorDerivedFieldDefinition(definition: Semap
 
 export declare function validateSemaphorOperationIntent(intent: SemaphorOperationIntent): SemaphorAnalyticsValidationResult;
 
+/**
+ * Validates an option dependency policy object. The `protocol` profile is the
+ * SDK contract: omitted mode stays independent and include/exclude lists are
+ * only checked for shape. The `dashboard` profile adds the authored-policy
+ * rules from the dashboard filter option dependencies plan: a mode is
+ * required, independent carries no ID lists, explicit needs at least one
+ * unique included ID and no exclusions, and all_applicable carries no include
+ * list. Dependency ID declarations against `inputs` are validated by the
+ * intent validator, not here.
+ */
+export declare function validateSemaphorOptionDependencies(value: unknown, profile?: SemaphorOptionDependencyValidationProfile): SemaphorValidationResult;
+
 export declare function validateSemaphorResultCalculation(calculation: SemaphorResultCalculation): SemaphorValidationResult;
 
 export declare function validateTemporalBucketMetadata(metadata: unknown): TemporalBucketMetadataValidationResult;

package/dist/types/briefings.d.ts

@@ -7491,6 +7491,16 @@ declare type DashboardFilterExcludedCardApplication = {
     cardId: string;
 };
 
+/**
+ * Persisted policy for which peer selections narrow a filter's option list.
+ * Omitted means All applicable for dashboards; see
+ * `resolveDashboardOptionDependencies`.
+ */
+declare type DashboardFilterOptionDependencies = SemaphorOptionDependencies;
+
+/** Persisted population that fixes relevance for fact-bridged cascades. */
+declare type DashboardFilterOptionPopulation = SemaphorOptionPopulation;
+
 /** Persisted label/value option definition for a mapped dashboard filter. */
 declare type DashboardFilterOptionSource = SemaphorInputOptionSource;
 
@@ -8075,6 +8085,8 @@ declare type EmbeddedFilterDashboardInput = FilterDashboardInputBase & {
     filter: TFilter;
     filterReference?: never;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -13918,6 +13930,8 @@ declare type ReferencedFilterDashboardInput = FilterDashboardInputBase & {
         filterId: string;
     };
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -14116,6 +14130,38 @@ declare type SemaphorInputOptionSource = {
     disambiguationFields?: SemaphorFieldRef[];
 };
 
+declare 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[];
+};
+
+declare type SemaphorOptionDependencyMode = 'independent' | 'explicit' | 'all_applicable';
+
+declare type SemaphorOptionPopulation = {
+    kind: 'option_source';
+    baseSource?: never;
+} | {
+    kind: 'related_population';
+    baseSource: SemaphorSourceRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
 declare type SemaphorScalarValueFormat = {
     type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
     minimumFractionDigits?: number;

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

@@ -10989,6 +10989,15 @@ declare type SemaphorInputOptionsIntent = SemaphorInputOptionSource & {
     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[];
 };
@@ -11005,6 +11014,9 @@ declare type SemaphorInputOptionSource = {
 
 declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
     kind: 'inputOptions';
+    dependencyOutcomes?: SemaphorOptionDependencyOutcome[];
+    /** Present when the intent carried `matchValues`. */
+    match?: SemaphorOptionMatchResult;
     options: Array<{
         label: string;
         value: unknown;
@@ -11065,9 +11077,42 @@ declare type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
 };
 
 declare type SemaphorOptionDependencies = {
-    mode?: 'independent' | 'explicit';
+    /** 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[];
+};
+
+declare type SemaphorOptionDependencyMode = 'independent' | 'explicit' | 'all_applicable';
+
+/** 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. */
+declare type SemaphorOptionDependencyOutcome = {
+    inputId: string;
+    status: SemaphorOptionDependencyOutcomeStatus;
+    reason?: SemaphorOptionDependencyOutcomeReason;
+};
+
+declare type SemaphorOptionDependencyOutcomeReason = 'unrelated' | 'population_required' | 'missing_dependency' | 'missing_relationship' | 'ambiguous_relationship' | 'invalid_metadata' | 'unsupported_dependency' | 'override_not_eligible';
+
+declare type SemaphorOptionDependencyOutcomeStatus = 'applied' | 'inactive' | 'skipped' | 'overridden' | 'error';
+
+declare 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';
 };
 
 declare type SemaphorOptionPopulation = {