react-semaphor 0.1.494 → 0.1.496

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

@@ -6646,6 +6646,15 @@ declare interface Field {
      * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
      */
     label: string;
+    /**
+     * Set only when `label` was synthesized from `name` because the source
+     * provided no authored label (raw database objects). Field pickers follow
+     * the naming rule in `@/lib/fields/field-display`: an authored semantic
+     * label is shown as is, otherwise the physical column name. A field whose
+     * `label` still equals `derivedLabel` has no authored label; any later
+     * edit to `label` makes it authored without touching this marker.
+     */
+    derivedLabel?: string;
     /**
      * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
      * If not provided, should be auto-generated from label or name.
@@ -32772,6 +32781,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[];
 };
@@ -32788,6 +32806,11 @@ export declare type SemaphorInputOptionSource = {
 
 export declare type SemaphorInputOptionsPayload = {
     options: SemaphorInputOption[];
+    /** Per-dependency classification for the option query; see
+     * `SemaphorOptionDependencyOutcome`. Absent when no dependencies applied. */
+    dependencyOutcomes?: SemaphorOptionDependencyOutcome[];
+    /** Authoritative exact-value relevance result when the request asked for it. */
+    match?: SemaphorOptionMatchResult;
     executionResult?: SemaphorAnalyticsExecutionResult;
 };
 
@@ -32820,6 +32843,9 @@ export declare type SemaphorInputOptionsQuerySpec = Omit<SemaphorQuerySourceSpec
 
 declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
     kind: 'inputOptions';
+    dependencyOutcomes?: SemaphorOptionDependencyOutcome[];
+    /** Present when the intent carried `matchValues`. */
+    match?: SemaphorOptionMatchResult;
     options: Array<{
         label: string;
         value: unknown;
@@ -32956,9 +32982,42 @@ declare type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
 export declare type SemaphorNonEmptyArray<T> = [T, ...T[]];
 
 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[];
+};
+
+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';
 };
 
 export declare type SemaphorOptionPopulation = {

package/dist/types/format-utils.d.ts

@@ -5633,6 +5633,15 @@ declare interface Field {
      * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
      */
     label: string;
+    /**
+     * Set only when `label` was synthesized from `name` because the source
+     * provided no authored label (raw database objects). Field pickers follow
+     * the naming rule in `@/lib/fields/field-display`: an authored semantic
+     * label is shown as is, otherwise the physical column name. A field whose
+     * `label` still equals `derivedLabel` has no authored label; any later
+     * edit to `label` makes it authored without touching this marker.
+     */
+    derivedLabel?: string;
     /**
      * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
      * If not provided, should be auto-generated from label or name.

package/dist/types/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("../chunks/common-types-nBuCd3u2.cjs"),e=require("../chunks/validators-4dRtYUI1.cjs"),l=require("../chunks/token-types-hl08eNuY.cjs"),E=require("../chunks/pivot-result-identity-CmvwpG4K.cjs"),a=require("../chunks/report-runtime-context-Bb0ejvVq.cjs");exports.CONTROL_CARD_DEFAULT_VALUE=t.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=t.EMPTY_SELECTION;exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.LEGACY_CALCULATED_FIELD_ENTITY_MARKER=e.LEGACY_CALCULATED_FIELD_ENTITY_MARKER;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.hasSyntheticCalculatedFieldOwner=e.hasSyntheticCalculatedFieldOwner;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedField=e.isCalculatedField;exports.isCalculatedMetric=e.isCalculatedMetric;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=l.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=E.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=E.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=a.DEFAULT_CALENDAR_CONTEXT;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("../chunks/common-types-nBuCd3u2.cjs"),e=require("../chunks/validators-ux2obZB9.cjs"),l=require("../chunks/token-types-CkAGFhiW.cjs"),E=require("../chunks/pivot-result-identity-DEenUrMj.cjs"),a=require("../chunks/report-runtime-context-lSIvyKm2.cjs");exports.CONTROL_CARD_DEFAULT_VALUE=t.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=t.EMPTY_SELECTION;exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.LEGACY_CALCULATED_FIELD_ENTITY_MARKER=e.LEGACY_CALCULATED_FIELD_ENTITY_MARKER;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.hasSyntheticCalculatedFieldOwner=e.hasSyntheticCalculatedFieldOwner;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedField=e.isCalculatedField;exports.isCalculatedMetric=e.isCalculatedMetric;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=l.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=E.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=E.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=a.DEFAULT_CALENDAR_CONTEXT;

package/dist/types/index.js

@@ -1,8 +1,8 @@
 import { C as s, E } from "../chunks/common-types-C6cAQgyh.js";
-import { C, D as l, L as t, P as A, g as o, c as _, h as T, d as u, a as L, b as i, i as D } from "../chunks/validators-BpJDwDnG.js";
-import { D as n } from "../chunks/token-types-5buW2I6f.js";
-import { r as F, a as M } from "../chunks/pivot-result-identity-CMz27nri.js";
-import { D as N } from "../chunks/report-runtime-context-nCHl3uHC.js";
+import { C, D as l, L as t, P as A, g as o, c as _, h as T, d as u, a as L, b as i, i as D } from "../chunks/validators-D-_IT-Xw.js";
+import { D as n } from "../chunks/token-types-BIYFAsGq.js";
+import { r as F, a as M } from "../chunks/pivot-result-identity-sZc1RaIz.js";
+import { D as N } from "../chunks/report-runtime-context-BlDpc-F-.js";
 export {
   C as CALCULATED_FIELD_ENTITY_MARKER,
   s as CONTROL_CARD_DEFAULT_VALUE,

package/dist/types/main.d.ts

@@ -8704,6 +8704,12 @@ declare type DashboardFilterAuthoringSettingsUpdate = {
     target?: DashboardInputRuntimeTarget;
     optionSourceChanged?: boolean;
     optionSource?: DashboardFilterOptionSource;
+    /** Authored option dependency policy edit; undefined value restores the
+     * dashboard default (omitted, meaning All applicable). */
+    optionDependenciesChanged?: boolean;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulationChanged?: boolean;
+    optionPopulation?: DashboardFilterOptionPopulation;
     /** Raw selection identity changed; the previous runtime value is invalid. */
     selectionIdentityChanged?: boolean;
 };
@@ -8890,6 +8896,16 @@ declare type DashboardFilterMappingDraftRow = {
 
 declare type DashboardFilterMappingDraftStatus = 'pendingSource' | 'automatic' | 'suggested' | 'needsMapping' | 'mapped' | 'notApplicable' | 'excluded' | 'invalidMapping' | 'metadataUnavailable';
 
+/**
+ * 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. */
 export declare type DashboardFilterOptionSource = SemaphorInputOptionSource;
 
@@ -10117,6 +10133,8 @@ export declare type EmbeddedFilterDashboardInput = FilterDashboardInputBase & {
     filter: TFilter;
     filterReference?: never;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -10514,6 +10532,15 @@ export declare interface Field {
      * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
      */
     label: string;
+    /**
+     * Set only when `label` was synthesized from `name` because the source
+     * provided no authored label (raw database objects). Field pickers follow
+     * the naming rule in `@/lib/fields/field-display`: an authored semantic
+     * label is shown as is, otherwise the physical column name. A field whose
+     * `label` still equals `derivedLabel` has no authored label; any later
+     * edit to `label` makes it authored without touching this marker.
+     */
+    derivedLabel?: string;
     /**
      * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
      * If not provided, should be auto-generated from label or name.
@@ -10711,6 +10738,53 @@ declare type FilterOnClick = {
     columnIndex: number;
 };
 
+declare type FilterOptionDependencyFailure = {
+    peer: FilterOptionDependencyPeer;
+    reason?: SemaphorOptionDependencyOutcomeReason;
+    /** Viewer-safe explanation built from the reason, never raw server text. */
+    message: string;
+    /** Explicit mode and an overridable, classified reason. */
+    canOverride: boolean;
+};
+
+declare type FilterOptionDependencyFeedback = {
+    applied: FilterOptionDependencyPeer[];
+    skipped: Array<FilterOptionDependencyPeer & {
+        reason?: SemaphorOptionDependencyOutcomeReason;
+    }>;
+    overridden: Array<FilterOptionDependencyPeer & {
+        reason?: SemaphorOptionDependencyOutcomeReason;
+    }>;
+    failure?: FilterOptionDependencyFailure;
+};
+
+/**
+ * Viewer-facing reading of the server's dependency outcomes for one option
+ * list. Pure: outcomes and the request error come from the response, labels
+ * come from the dashboard. Nothing here decides applicability; the server
+ * already did. It only says what was applied, what was skipped and why, what
+ * the viewer is browsing around, and whether a classified failure may be
+ * browsed around at all.
+ */
+declare type FilterOptionDependencyPeer = {
+    inputId: string;
+    label: string;
+};
+
+/**
+ * Dependency state a list renders: what narrowed it, what was skipped, the
+ * active browse override, and the one classified failure a viewer may
+ * browse around. Overrides live here, in browse state, and nowhere else.
+ */
+declare type FilterOptionDependencyState = FilterOptionDependencyFeedback & {
+    /** Explicit dependency ids currently browsed without. */
+    override: readonly string[];
+    showDiagnostics: boolean;
+    /** Browse without one classified dependency; the server re-validates. */
+    overrideDependency: (inputId: string) => void;
+    clearOverride: () => void;
+};
+
 declare type FilterOptionValue = string | number | boolean;
 
 declare type FilterSemanticContext = {
@@ -19927,6 +20001,8 @@ export declare type NormalizedFilterDashboardInput = FilterDashboardInputBase &
     kind: 'filter';
     filter: TFilter;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
     definitionOrigin: 'embedded' | 'dashboardFilter';
 };
@@ -19994,6 +20070,21 @@ declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in'
 
 export declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
 
+declare type OptionSelectionRelevance = {
+    byIdentity: ReadonlyMap<string, OptionSelectionRelevanceStatus>;
+    noMatchIdentities: ReadonlySet<string>;
+    isPending: boolean;
+};
+
+/**
+ * Per-value relevance of a retained selection under the authored dependency
+ * context. Only a successful, complete exact-value check may say
+ * `no_match`; everything else (pending, failed, unsupported, truncated,
+ * beyond the bounded batch) stays `unknown`, so a stale or partial answer can
+ * never mark a current selection wrong.
+ */
+declare type OptionSelectionRelevanceStatus = 'matches' | 'no_match' | 'unknown';
+
 declare type OptionsMap = {
     number: NumberOptions;
     string: StringOptions;
@@ -21872,6 +21963,8 @@ export declare type ReferencedFilterDashboardInput = FilterDashboardInputBase &
         filterId: string;
     };
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -22379,6 +22472,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[];
 };
@@ -22431,11 +22533,26 @@ declare type SemaphorMetricIntent = {
 };
 
 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';
+
+declare type SemaphorOptionDependencyOutcomeReason = 'unrelated' | 'population_required' | 'missing_dependency' | 'missing_relationship' | 'ambiguous_relationship' | 'invalid_metadata' | 'unsupported_dependency' | 'override_not_eligible';
+
 declare type SemaphorOptionPopulation = {
     kind: 'option_source';
     baseSource?: never;
@@ -26155,7 +26272,9 @@ export declare function useTextFilterHook(filterId: string): {
     isLoading: boolean;
     isFetching: boolean;
     isPlaceholderData: boolean;
+    isLoadingOptions: boolean;
     isError: boolean;
+    retry: () => void;
     hasNextPage: boolean;
     hasLoadedMoreOptions: boolean;
     isFetchingNextPage: boolean;
@@ -26174,6 +26293,8 @@ export declare function useTextFilterHook(filterId: string): {
     isSearching: boolean;
     searchError: boolean;
     resultSource: "server" | "both" | "local";
+    dependency: FilterOptionDependencyState;
+    selectionRelevance: OptionSelectionRelevance;
 };
 
 export declare function validateBriefingFormDraft(draft: BriefingFormDraft): BriefingFormValidationResult;

package/dist/types/shared.d.ts

@@ -4004,6 +4004,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;
 
@@ -4575,6 +4585,8 @@ declare type EmbeddedFilterDashboardInput = FilterDashboardInputBase & {
     filter: TFilter;
     filterReference?: never;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -4776,6 +4788,15 @@ declare interface Field {
      * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
      */
     label: string;
+    /**
+     * Set only when `label` was synthesized from `name` because the source
+     * provided no authored label (raw database objects). Field pickers follow
+     * the naming rule in `@/lib/fields/field-display`: an authored semantic
+     * label is shown as is, otherwise the physical column name. A field whose
+     * `label` still equals `derivedLabel` has no authored label; any later
+     * edit to `label` makes it authored without touching this marker.
+     */
+    derivedLabel?: string;
     /**
      * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
      * If not provided, should be auto-generated from label or name.
@@ -7130,6 +7151,8 @@ declare type ReferencedFilterDashboardInput = FilterDashboardInputBase & {
         filterId: string;
     };
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -7225,6 +7248,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/surfboard.d.ts

@@ -4149,6 +4149,16 @@ export 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. */
 export declare type DashboardFilterOptionSource = SemaphorInputOptionSource;
 
@@ -4936,6 +4946,8 @@ export declare type EmbeddedFilterDashboardInput = FilterDashboardInputBase & {
     filter: TFilter;
     filterReference?: never;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -5150,6 +5162,15 @@ declare interface Field {
      * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
      */
     label: string;
+    /**
+     * Set only when `label` was synthesized from `name` because the source
+     * provided no authored label (raw database objects). Field pickers follow
+     * the naming rule in `@/lib/fields/field-display`: an authored semantic
+     * label is shown as is, otherwise the physical column name. A field whose
+     * `label` still equals `derivedLabel` has no authored label; any later
+     * edit to `label` makes it authored without touching this marker.
+     */
+    derivedLabel?: string;
     /**
      * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
      * If not provided, should be auto-generated from label or name.
@@ -5913,6 +5934,8 @@ export declare type NormalizedFilterDashboardInput = FilterDashboardInputBase &
     kind: 'filter';
     filter: TFilter;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
     definitionOrigin: 'embedded' | 'dashboardFilter';
 };
@@ -7680,6 +7703,8 @@ export declare type ReferencedFilterDashboardInput = FilterDashboardInputBase &
         filterId: string;
     };
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -7977,6 +8002,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/types.d.ts

@@ -4664,6 +4664,16 @@ export 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. */
 export declare type DashboardFilterOptionSource = SemaphorInputOptionSource;
 
@@ -5513,6 +5523,8 @@ export declare type EmbeddedFilterDashboardInput = FilterDashboardInputBase & {
     filter: TFilter;
     filterReference?: never;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -5737,6 +5749,15 @@ export declare interface Field {
      * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
      */
     label: string;
+    /**
+     * Set only when `label` was synthesized from `name` because the source
+     * provided no authored label (raw database objects). Field pickers follow
+     * the naming rule in `@/lib/fields/field-display`: an authored semantic
+     * label is shown as is, otherwise the physical column name. A field whose
+     * `label` still equals `derivedLabel` has no authored label; any later
+     * edit to `label` makes it authored without touching this marker.
+     */
+    derivedLabel?: string;
     /**
      * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
      * If not provided, should be auto-generated from label or name.
@@ -6583,6 +6604,8 @@ export declare type NormalizedFilterDashboardInput = FilterDashboardInputBase &
     kind: 'filter';
     filter: TFilter;
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
     definitionOrigin: 'embedded' | 'dashboardFilter';
 };
@@ -8488,6 +8511,8 @@ export declare type ReferencedFilterDashboardInput = FilterDashboardInputBase &
         filterId: string;
     };
     optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
     application?: DashboardFilterApplication;
 };
 
@@ -8838,6 +8863,34 @@ 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 SemaphorPivotResultColumnIdentity = {
     metricId: string;
     /** Collision-safe identity for this configured metric instance. */
@@ -8862,6 +8915,10 @@ declare type SemaphorPivotResultMember = {
 /** Stable canonical scalar transported for one physical pivot member. */
 declare type SemaphorPivotValue = string | null;
 
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
 declare type SemaphorResultColumn = {
     /**
      * Stable row accessor for this result. Consumers should read values with

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.494",
+  "version": "0.1.496",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",