react-semaphor 0.1.546 → 0.1.548

package/dist/types/lib/dashboard-inputs/dashboard-filter-value-identity.d.ts

@@ -0,0 +1,65 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { NormalizedFilterDashboardInput } from '../types/common-types.js';
+import { DashboardFilterLogicalValueField, DashboardFilterOptionSource, DashboardFilterRelationshipTarget, DashboardFilterTargetField, DashboardFilterTargetSource } from '../../shared/dashboard-authoring/index.js';
+import { SemaphorConnectionCapabilities } from '../../shared/analytics-protocol/index.js';
+export type DashboardFilterSourceResolutionContext = {
+    connectionType?: string;
+    capabilities?: Pick<SemaphorConnectionCapabilities, 'dialect' | 'prefixLevels'>;
+};
+/**
+ * Resolves the concrete source carried by an Option Source field, falling
+ * back to the Option Source declaration for older field refs that omit it.
+ */
+export declare function resolveDashboardFilterOptionFieldSource(field: DashboardFilterOptionSource['valueField'], fallbackSource: DashboardFilterOptionSource['source']): DashboardFilterTargetSource;
+export declare function resolveDashboardFilterBackingSourceResolution(filter: TFilter, context?: DashboardFilterSourceResolutionContext): import('../../shared/analytics-protocol/index.js').SemaphorSourceEntityResolution<Record<string, unknown>>;
+/** Resolves the one source that owns an ordinary dashboard filter field. */
+export declare function resolveDashboardFilterBackingSource(filter: TFilter, context?: DashboardFilterSourceResolutionContext): DashboardFilterTargetSource | undefined;
+/**
+ * Metadata authoring may inspect a complete persisted qualified source even
+ * when stale selected-entity inventory no longer contains it. Runtime source
+ * resolution remains fail-closed through resolveDashboardFilterBackingSource.
+ */
+export declare function resolveDashboardFilterMappingCandidateSource(filter: TFilter, context?: DashboardFilterSourceResolutionContext): DashboardFilterTargetSource | undefined;
+/**
+ * Resolves every proven identity by which the selected filter field may map.
+ * A physical dataset selected within a semantic domain legitimately has both
+ * a physical backing identity and a semantic projection; the consuming card
+ * chooses the identity present in its own executable-source inventory.
+ */
+export declare function resolveDashboardFilterMappingSources(filter: TFilter): DashboardFilterTargetSource[];
+/**
+ * Authoring counterpart to resolveDashboardFilterMappingSources. It may carry
+ * a complete qualified backing candidate when persisted entity inventory is
+ * stale, while the semantic projection still requires a resolved entity.
+ */
+export declare function resolveDashboardFilterMappingCandidateSources(filter: TFilter, context?: DashboardFilterSourceResolutionContext): DashboardFilterTargetSource[];
+/** Resolves the ordinary filter field used as the pre-Option-Source value key. */
+export declare function deriveDashboardFilterLogicalSelectionField(filter: TFilter): Pick<DashboardFilterTargetField, 'name'> | undefined;
+/** The filter's logical value field: its Option Source's value field, else its own field. */
+export declare function filterInputLogicalValueField(input: NormalizedFilterDashboardInput, filterValue?: TFilterValue): DashboardFilterLogicalValueField | undefined;
+/** The sources a filter's values belong to: its Option Source's, else its own field's. */
+export declare function filterInputValueSources(input: NormalizedFilterDashboardInput): DashboardFilterTargetSource[];
+/**
+ * The source-qualified fields whose values a toolbar filter holds. A filter
+ * with an option source has exactly one; an ordinary filter has one per
+ * source it is proven to address.
+ */
+export declare function dashboardFilterInputValueFields(input: NormalizedFilterDashboardInput): DashboardFilterTargetField[];
+/**
+ * Whether an author-chosen relationship route (RF-D10) still ends at the
+ * filter's value field: the field the filter's values belong to (its Option
+ * Source's value field when it has one). A route chosen for another field,
+ * as after the Option Source moves to another dataset, can't run and is stale
+ * until chosen again. The card target decision, the Cards tab draft and save
+ * validation all ask here (relationship filter reach ledger R-12).
+ */
+export declare function relationshipTargetFollowsValueField(input: NormalizedFilterDashboardInput, target: DashboardFilterRelationshipTarget): boolean;
+/**
+ * The target that saves an author's choice of a relationship route (RF-D10):
+ * the route's ids and the filter's value field as its semantic dataset in the
+ * card's domain, the field `relationshipTargetFollowsValueField` checks. A
+ * value field can also have a physical identity (a physical dataset in a
+ * semantic domain); the route ends at the semantic one. The server preview
+ * builds the Cards tab's choices here (ledger R-16).
+ */
+export declare function relationshipRouteTarget(input: NormalizedFilterDashboardInput, domainId: string, relationshipIds: readonly string[]): DashboardFilterRelationshipTarget | undefined;

package/dist/types/lib/dashboard-inputs/resolve-selection-input.d.ts

@@ -1,5 +1,5 @@
 import { SelectionField, SelectionInputValue } from '../../shared/analytics-protocol/selection-contract.js';
-import { DashboardFilterTarget } from '../../shared/dashboard-authoring/index.js';
+import { DashboardFilterFieldTarget } from '../../shared/dashboard-authoring/index.js';
 import { ScopedDashboardInputTarget } from '../../shared/dashboard-authoring/dashboard-input-scope.js';
 import { NormalizedFilterDashboardInput, SelectionDashboardInput, TCard } from '../types/common-types.js';
 import { FilterCondition } from '../types/explorer-types.js';
@@ -19,7 +19,7 @@ export type SelectionBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' |
 export type SelectionConditionDisposition = {
     status: 'apply';
     clickedFieldKey: string;
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
     provenance: 'automatic' | 'bound' | 'borrowedFromFilter';
     /** Set when provenance is 'borrowedFromFilter'. */
     borrowedFromInputId?: string;
@@ -57,7 +57,7 @@ export declare function findBorrowedSelectionBinding(params: {
     filterInputs: NormalizedFilterDashboardInput[];
 }): {
     inputId: string;
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
 } | undefined;
 /**
  * Decides what one source card's selection does on one target card. A viewer's

package/dist/types/lib/hooks/use-dashboard-card.d.ts

@@ -21,6 +21,7 @@ export declare function useCard(cardId: string): {
     resolvedPrimaryDateField: import('../types/semantic-runtime-types.js').ResolvedPrimaryDateField | undefined;
     effectiveCardConfig: import('../types/index.js').CardConfig | undefined;
     isCurrentQueryResult: boolean;
+    filterReach: import('../../shared/analytics-protocol/index.js').SemaphorFilterReachEntry[];
 };
 export declare function useDashboardCard(card: TCard): {
     isPending: boolean;
@@ -42,4 +43,5 @@ export declare function useDashboardCard(card: TCard): {
     resolvedPrimaryDateField: import('../types/semantic-runtime-types.js').ResolvedPrimaryDateField | undefined;
     effectiveCardConfig: import('../types/index.js').CardConfig | undefined;
     isCurrentQueryResult: boolean;
+    filterReach: import('../../shared/analytics-protocol/index.js').SemaphorFilterReachEntry[];
 };

package/dist/types/lib/matrix-table/matrix-delivery-policy.d.ts

@@ -31,4 +31,4 @@ export declare function matrixDeliveryOptions(allowDownload?: boolean, content?:
     formats: ("csv" | "xlsx" | "pdf" | "png")[];
 };
 /** Matrix delivery requires an effective capture, never resident cells. */
-export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "window" | "unavailable" | "ordinary";
+export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "unavailable" | "window" | "ordinary";

package/dist/types/lib/matrix-table/matrix-runtime-types.d.ts

@@ -1,4 +1,4 @@
-import { MatrixAxis, MatrixAxisPage, MatrixCellBlock, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixIndexedWindowOutcome, MatrixWindowRequest, OperationTemporalState, SemaphorScalarValue } from '../../shared/analytics-protocol/index.js';
+import { MatrixAxis, MatrixAxisPage, MatrixCellBlock, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixIndexedWindowOutcome, MatrixWindowRequest, OperationTemporalState, SemaphorScalarValue, SemaphorFilterReachEntry } from '../../shared/analytics-protocol/index.js';
 export type MatrixRuntimeError = {
     failure: MatrixFailure;
     retryKey: string | null;
@@ -124,6 +124,12 @@ export type MatrixDataset = {
      * or seeded dataset continues on the same instant.
      */
     temporalState?: OperationTemporalState;
+    /**
+     * The per-filter report its latest window returned (relationship filter
+     * reach RF-D13): a restored dataset shows rows without running a window, so
+     * its filter info reads the report saved with them (ledger R-03).
+     */
+    filterReach?: readonly SemaphorFilterReachEntry[];
 };
 /** What a mounted runtime exposes to History. */
 export type MatrixLiveView = {
@@ -208,6 +214,8 @@ export type MatrixWindowExecutor = (input: {
 /** A window outcome and the operation state the server ran it on. */
 export type MatrixWindowExecution = MatrixIndexedWindowOutcome & {
     temporalState?: OperationTemporalState;
+    /** The per-filter report for this window, as `/api/v1/query` returns it for other cards. */
+    filterReach?: SemaphorFilterReachEntry[];
 };
 export type MatrixRuntimeInput = {
     spec: MatrixSpec;

package/dist/types/lib/matrix-table/matrix-runtime.d.ts

@@ -1,5 +1,5 @@
+import { SemaphorFilterReachEntry, MatrixAxis, MatrixCoordinate, MatrixPath, MatrixSort, MatrixViewState } from '../../shared/analytics-protocol/index.js';
 import { QueryClient } from '@tanstack/react-query';
-import { MatrixAxis, MatrixCoordinate, MatrixPath, MatrixSort, MatrixViewState } from '../../shared/analytics-protocol/index.js';
 import { MatrixCellAddress, MatrixCellState, MatrixDatasetRetention, MatrixRuntimeInput, MatrixRuntimeSnapshot, MatrixViewport, MatrixVisibleCoverage, MatrixWindowExecutor } from './matrix-runtime-types.js';
 /** Owns acquisition, errors, generation fencing and retention for exactly one card. */
 export declare class MatrixRuntimeController {
@@ -26,6 +26,8 @@ export declare class MatrixRuntimeController {
      * every page and expansion sends it, so they all run on one instant.
      */
     private temporalState?;
+    /** The latest window's per-filter report (relationship filter reach RF-D13). */
+    private filterReach;
     private error?;
     private notice?;
     private blockingFailures;
@@ -73,6 +75,8 @@ export declare class MatrixRuntimeController {
      * Value, null and empty cells are complete; unloaded and loading cells, axis
      * pages still loading, and queued or active work are not.
      */
+    /** Which filters the latest window's source applied, and why not, as the server reported it. */
+    readFilterReach: () => SemaphorFilterReachEntry[];
     readVisibleCoverage: () => MatrixVisibleCoverage;
     /** Used by explicit refresh/retry integrations; latest-issued response wins. */
     refetchCell: (coordinate: MatrixCoordinate) => void;

package/dist/types/lib/query-context/dashboard-filter-mapping-resolution.d.ts

@@ -1,6 +1,7 @@
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { NormalizedFilterDashboardInput, ResolvedDashboardInput, TCard } from '../types/common-types.js';
-import { DashboardFilterLogicalValueField, DashboardFilterTarget, DashboardFilterTargetField, DashboardFilterTargetSource, buildDashboardCardSourceIndex } from '../../shared/dashboard-authoring/index.js';
+import { DashboardFilterLogicalValueField, DashboardFilterFieldTarget, DashboardFilterTargetField, DashboardFilterTargetSource, buildDashboardCardSourceIndex } from '../../shared/dashboard-authoring/index.js';
+import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../../shared/analytics-protocol/index.js';
 import { Field } from '../types/explorer-types.js';
 export type DashboardFilterMappingSkipReason = 'outsideScope' | 'noSelection' | 'explicitlyExcluded' | 'notApplicable';
 export type DashboardFilterMappingBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' | 'invalidSelection' | 'incompatibleValueType' | 'unsupportedTarget';
@@ -35,7 +36,7 @@ export type DashboardFilterMappingResolution = {
  * use, so the server resolves both to the same table alias. Pass the card's
  * grounded executable source when validation returned one.
  */
-export declare function explorerFieldFromMappingTarget(target: DashboardFilterTarget, source?: DashboardFilterTargetField['source']): Field;
+export declare function explorerFieldFromMappingTarget(target: DashboardFilterFieldTarget, source?: DashboardFilterTargetField['source']): Field;
 /** Date and datetime are interchangeable; every other type must match exactly. */
 export declare function dashboardFilterDataTypesAreCompatible(sourceType: string, targetType: DashboardFilterTargetField['dataType']): boolean;
 /**
@@ -47,13 +48,7 @@ export declare function automaticTargetCandidates(params: {
     valueField: DashboardFilterLogicalValueField;
     valueSources: DashboardFilterTargetSource[];
     sourceIndex: ReturnType<typeof buildDashboardCardSourceIndex>;
-}): DashboardFilterTarget[];
-/**
- * The source-qualified fields whose values a toolbar filter holds. A filter
- * with an option source has exactly one; an ordinary filter has one per
- * source it is proven to address.
- */
-export declare function dashboardFilterInputValueFields(input: NormalizedFilterDashboardInput): DashboardFilterTargetField[];
+}): DashboardFilterFieldTarget[];
 export type DashboardFilterTargetValidation = {
     status: 'valid';
     /** The card's own copy of the source the target addresses. */
@@ -71,7 +66,7 @@ export type DashboardFilterTargetValidation = {
  */
 export declare function validateDashboardFilterTargetForCard(params: {
     sourceIndex: ReturnType<typeof buildDashboardCardSourceIndex>;
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
 }): DashboardFilterTargetValidation;
 /**
  * Where a filter input lands on a card: the one decision execution
@@ -87,7 +82,7 @@ export type DashboardFilterCardTarget = {
 } | {
     status: 'bound';
     bindingId: string;
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
     validation: Extract<DashboardFilterTargetValidation, {
         status: 'valid';
     }>;
@@ -103,7 +98,7 @@ export type DashboardFilterCardTarget = {
     status: 'sql';
 } | {
     status: 'automatic';
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
 }
 /**
  * The card's data takes the filter's field (the one applicability rule) but
@@ -113,6 +108,22 @@ export type DashboardFilterCardTarget = {
  */
  | {
     status: 'passthrough';
+}
+/**
+ * The value's dataset is one the card's query doesn't use, in the card's
+ * semantic domain: the value is sent as it is and the server decides,
+ * through the domain's relationships, whether and how it reaches the card
+ * (relationship filter reach row 7r). The browser loads no relationships.
+ * With `route`, the author chose the relationships (a mapping `relationship`
+ * target, RF-D10): the value carries their ids and the server resolves
+ * exactly them or blocks the card.
+ */
+ | {
+    status: 'relationship';
+    route?: {
+        bindingId: string;
+        relationshipIds: string[];
+    };
 } | {
     status: 'ambiguous';
 } | {
@@ -134,7 +145,56 @@ export type DashboardFilterCardReach =
 /** More than one field of the card could take it: the card blocks until it is mapped. */
  | 'ambiguous'
 /** The mapping binds a target the card can't run or no longer has: the card blocks until it is mapped again. */
- | 'blocked' | 'notApplicable';
+ | 'blocked'
+/**
+ * The server decides when the card runs, through the domain's
+ * relationships: it may apply the value or skip it with a reason. A reader
+ * never counts it as reached.
+ */
+ | 'relationship'
+/** A server-side resolver confirmed the route the card will apply (RF-D15). */
+ | 'relationshipApplied' | 'notApplicable';
+/** How a filter reaches a card, with the route or the reason a resolver gave (RF-D15). */
+export type DashboardFilterCardReachDetail = {
+    reach: DashboardFilterCardReach;
+    /** With 'relationshipApplied'. */
+    route?: SemaphorRelationshipRoute;
+    /** With 'notApplicable' from a resolver. */
+    reason?: SemaphorSkippedConstraintReason;
+    /** With reason 'relationship_ambiguous'. */
+    candidates?: SemaphorRelationshipRoute[];
+    /** With 'blocked' from a resolver. */
+    message?: string;
+    /**
+     * With 'automatic' from a resolver: a card the target decision sends to the
+     * server to place applies the value on data its query already uses, so no
+     * route is needed (ledger R-05).
+     */
+    kept?: true;
+};
+/**
+ * Supplied by semaphor-app to server-side readers (RF-D15). Synchronous: the
+ * app preloads each card's domain. In the browser readers have none and
+ * report `relationship` unresolved.
+ */
+export type DashboardRelationshipReachResolver = (query: {
+    card: TCard;
+    value: TFilterValue;
+}) => {
+    status: 'applied';
+    route: SemaphorRelationshipRoute;
+}
+/** The card's query already uses the value's dataset: it applies as any filter. */
+ | {
+    status: 'kept';
+} | {
+    status: 'skipped';
+    reason: SemaphorSkippedConstraintReason;
+    candidates?: SemaphorRelationshipRoute[];
+} | {
+    status: 'blocked';
+    message: string;
+};
 /**
  * Whether a filter in scope reaches a card, read without a value, from the
  * decision execution makes (`decideDashboardFilterCardTarget`). The dashboard
@@ -142,6 +202,16 @@ export type DashboardFilterCardReach =
  * (MCP dashboard editing SPEC 3.6, 5.4).
  */
 export declare function describeDashboardFilterCardReach(input: NormalizedFilterDashboardInput, card: TCard): DashboardFilterCardReach;
+/**
+ * `describeDashboardFilterCardReach` with the route or reason. With a
+ * resolver (server-side readers, RF-D15) a `relationship` card is resolved
+ * the way the card query resolves it: applied with its route, not applicable
+ * with the reason, or blocked. The value is the filter's own field, as the
+ * card would send it; no policy step depends on the operator.
+ */
+export declare function describeDashboardFilterCardReachDetail(input: NormalizedFilterDashboardInput, card: TCard, options?: {
+    relationshipReach?: DashboardRelationshipReachResolver;
+}): DashboardFilterCardReachDetail;
 export declare function resolveDashboardFilterMappings({ card, inputs, resolvedInputs, activeFilterValues, shouldApplyDashboardFilters, }: {
     card: TCard;
     inputs: NormalizedFilterDashboardInput[];

package/dist/types/lib/stores/dashboard-store.d.ts

@@ -107,6 +107,12 @@ export type DashboardStore = {
      * on load, on entering or leaving edit mode, and when an editable size is chosen.
      */
     layoutPreviewBreakpoint: Breakpoint | null;
+    /**
+     * Whether the screen-size bar is open (responsive layouts RL-D21). Closed by
+     * default: the editor edits Desktop and the bar appears only when someone
+     * opens it. Closed on load and on entering or leaving edit mode.
+     */
+    screenSizesOpen: boolean;
     theme?: 'light' | 'dark' | 'system';
     themeStyle?: StyleProps;
     filteringCards?: TCard[];
@@ -357,6 +363,12 @@ type Actions = {
     editSheetLayout: (sheetId: string, breakpoint: GridEditBreakpoint, items: LayoutItem[]) => void;
     /** Shows a screen size look-only, or ends the preview with null (RL-D19). */
     setLayoutPreviewBreakpoint: (breakpoint: Breakpoint | null) => void;
+    /**
+     * Opens or closes the screen-size bar (RL-D21). Opening in view mode starts a
+     * look-only preview at the size shown now; closing ends any preview and
+     * returns the editor to Desktop.
+     */
+    setScreenSizesOpen: (open: boolean) => void;
     /** The screen size the editor edits: Desktop, Tablet or Phone (RL-D11). */
     setLayoutEditBreakpoint: (breakpoint: EditableBreakpoint) => void;
     /** "Back to automatic" for a customized Tablet or Phone layout, through the layout engine (`reset_to_automatic`). */

package/dist/types/shared/analytics-protocol/applied-constraints.d.ts

@@ -17,6 +17,33 @@ export type AppliedConstraintField = {
     label?: string;
     qualifiedName?: string;
 };
+/** To-one only with key proof (relationship filter reach RF-D12); anything else is to-many. */
+export type SemaphorRelationshipDirection = 'to_one' | 'to_many';
+/**
+ * The route a filter value took to a card through the domain's modeled
+ * relationships (relationship filter reach). Applied as "keep the card's rows
+ * that have at least one matching related row", so no row repeats.
+ */
+export type SemaphorRelationshipRoute = {
+    /** Ordered from the base dataset to the value's dataset; non-empty, no repeats. */
+    relationshipIds: string[];
+    /** The card's dataset the route starts from, for wording ("Projects with ..."). */
+    base?: {
+        name: string;
+        label?: string;
+    };
+    /** The datasets after the base, in order, for wording ("through Project"). */
+    datasets: Array<{
+        name: string;
+        label?: string;
+    }>;
+    direction: SemaphorRelationshipDirection;
+    /** For a to-many route: the dataset its first to-many step reaches (the copy's "matching {D}"). */
+    matchingDataset?: {
+        name: string;
+        label?: string;
+    };
+};
 export type AppliedFilterCondition = {
     /** The filter the condition came from: a dashboard input, a request filter, a time window. */
     filterId: string;
@@ -41,6 +68,8 @@ export type AppliedFilterCondition = {
      * Absent when it applied to the whole answer.
      */
     measures?: string[];
+    /** The condition reached the card through these relationships. */
+    through?: SemaphorRelationshipRoute;
 };
 export type SemaphorAppliedConstraint = ({
     kind: 'filter';
@@ -61,7 +90,13 @@ export type SemaphorAppliedConstraint = ({
     grain?: MetricComparisonWindowGrain;
 };
 /** Why a condition was left out of the executed query. */
-export type SemaphorSkippedConstraintReason = 'dataset_not_reachable' | 'field_not_resolvable' | 'missing_metadata' | 'unsupported_calculated_filter';
+export type SemaphorSkippedConstraintReason = 'dataset_not_reachable' | 'field_not_resolvable' | 'missing_metadata' | 'unsupported_calculated_filter'
+/** The relationships connect, but this card can't take the value through them. */
+ | 'relationship_unsupported'
+/** No active modeled relationship connects the value's dataset to the card. */
+ | 'relationship_missing'
+/** More than one equally preferred route connects them; the author chooses one. */
+ | 'relationship_ambiguous';
 export type SemaphorSkippedConstraint = {
     filterId?: string;
     field?: AppliedConstraintField;
@@ -72,3 +107,24 @@ export type SemaphorQueryConstraints = {
     applied: SemaphorAppliedConstraint[];
     skipped: SemaphorSkippedConstraint[];
 };
+/**
+ * Per filter, whether a card query applied it and why not (relationship
+ * filter reach RF-D22): built by the server from its one per-card
+ * resolution, keyed by the filter's id, never from the deduped evidence.
+ */
+export type SemaphorFilterReachEntry = {
+    filterId: string;
+    status: 'applied';
+    through?: SemaphorRelationshipRoute;
+} | {
+    filterId: string;
+    status: 'skipped';
+    reason: SemaphorSkippedConstraintReason;
+} | {
+    filterId: string;
+    status: 'blocked';
+    message: string;
+};
+export declare function readRelationshipRoute(value: unknown): SemaphorRelationshipRoute | undefined;
+/** Reads `filterReach` from a raw `/api/v1/query` response body; [] when absent or malformed. */
+export declare function readFilterReach(responseBody: unknown): SemaphorFilterReachEntry[];

package/dist/types/shared/assistant-protocol/context.d.ts

@@ -247,14 +247,14 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         }, {
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         }>, z.ZodObject<{
             kind: z.ZodLiteral<"varies">;
         }, "strict", z.ZodTypeAny, {
@@ -268,8 +268,8 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         } | {
             kind: "varies";
         };
@@ -281,8 +281,8 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         } | {
             kind: "varies";
         };
@@ -610,8 +610,8 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         } | {
             kind: "varies";
         };
@@ -702,8 +702,8 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         } | {
             kind: "varies";
         };
@@ -794,8 +794,8 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         } | {
             kind: "varies";
         };
@@ -886,8 +886,8 @@ export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
             kind: "set";
             text: string;
             fingerprint: string;
-            omittedValues?: number | undefined;
             notApplied?: "opened_from_another_dashboard" | undefined;
+            omittedValues?: number | undefined;
         } | {
             kind: "varies";
         };

package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts

@@ -12,6 +12,8 @@ export type ChangeProblemCode = 'invalid_change' | 'invalid_change_target' | 'co
 export type ChangeWarningCode = 
 /** In-scope cards the filter doesn't reach. */
 'filter_not_reaching_cards'
+/** In-scope cards on another dataset of the filter's domain: decided when each card runs, through the relationships. */
+ | 'filter_reach_through_relationships'
 /** The compiled card stores the window as fixed dates. */
  | 'window_saved_as_fixed_dates'
 /** A type change leaves out fields or preferences. */

package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts

@@ -2,6 +2,7 @@ import { TDashboard } from '../../../lib/types/common-types.js';
 import { DataSource, Field } from '../../../lib/types/explorer-types.js';
 import { TChartType } from '../../../lib/charts/types.js';
 import { CalendarContext } from '../../report-runtime-context/index.js';
+import { DashboardRelationshipReachResolver } from '../../../lib/query-context/dashboard-filter-mapping-resolution.js';
 import { DashboardOperation, OperationContext, OperationDescription } from '../operations/apply-dashboard-operations.js';
 import { CardQueryPart } from './card-query-part.js';
 import { FieldRef, MetricCardQuery, RecordsCardQuery } from './dashboard-change.js';
@@ -59,6 +60,12 @@ export type ChangeServices = {
     }): Promise<FieldRef[]>;
     /** A new unique id (a UUID: Matrix ids must be UUIDs, ledger P1-04). */
     newId(): string;
+    /**
+     * Server side only: resolves relationship reach the way the card query
+     * does, with each card's domain preloaded (relationship filter reach
+     * RF-D15). Without one, those cards read as decided when they run.
+     */
+    relationshipReach?: DashboardRelationshipReachResolver;
 };
 export type ChangeRef = {
     ref: string;

package/dist/types/shared/dashboard-authoring/click-to-filter-settings.d.ts

@@ -3,7 +3,7 @@ import { SelectionField } from '../analytics-protocol/selection-contract.js';
 import { DashboardInputScope, TCard } from '../../lib/types/common-types.js';
 import { Field } from '../../lib/types/explorer-types.js';
 import { buildDashboardCardSourceIndex, DashboardCardFilterSourceInventory } from './dashboard-card-source-index.js';
-import { DashboardFilterTarget } from './dashboard-filter-mapping-types.js';
+import { DashboardFilterFieldTarget } from './dashboard-filter-mapping-types.js';
 /** Which fields a click on this card carries. */
 export type ClickToFilterFieldsRule = 
 /** Table: every dimension column on the row. Matrix: the full path. Chart: every dimension of the clicked mark. */
@@ -31,8 +31,8 @@ export type ClickToFilterCardMapping = {
     /** Target card. */
     cardId: string;
     clickedFieldKey: string;
-    /** Same target shape toolbar filter mappings persist. */
-    target: DashboardFilterTarget;
+    /** A field of the target card: a click applies its value to a field the card executes (ledger R-11). */
+    target: DashboardFilterFieldTarget;
 }
 /** "Not applied": this target never receives this source's clicks. */
  | {

package/dist/types/shared/dashboard-authoring/dashboard-filter-automatic-target.d.ts

@@ -1,10 +1,10 @@
-import { DashboardFilterTarget, DashboardFilterTargetField } from './dashboard-filter-mapping-types.js';
+import { DashboardFilterFieldTarget, DashboardFilterTarget, DashboardFilterTargetField } from './dashboard-filter-mapping-types.js';
 export type DashboardFilterLogicalValueField = Pick<DashboardFilterTargetField, 'name' | 'sourceField'> & {
     dataType: DashboardFilterTargetField['dataType'];
 };
 export type DashboardFilterAutomaticTargetResolution = {
     status: 'matched';
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
 } | {
     status: 'ambiguous';
 } | {
@@ -22,7 +22,7 @@ export declare function dashboardFilterTargetMatchesLogicalValue(target: Dashboa
  */
 export declare function resolveDashboardFilterAutomaticTarget(params: {
     logicalValueField: DashboardFilterLogicalValueField;
-    candidates: DashboardFilterTarget[];
+    candidates: DashboardFilterFieldTarget[];
 }): DashboardFilterAutomaticTargetResolution;
 /**
  * Reuses an accepted, source-qualified target as the default for later config
@@ -33,5 +33,5 @@ export declare function resolveDashboardFilterAutomaticTarget(params: {
  */
 export declare function resolveDashboardFilterInheritedTarget(params: {
     logicalValueField: DashboardFilterLogicalValueField;
-    acceptedTargets: DashboardFilterTarget[];
+    acceptedTargets: DashboardFilterFieldTarget[];
 }): DashboardFilterAutomaticTargetResolution;

package/dist/types/shared/dashboard-authoring/dashboard-filter-mapping-contract.d.ts

@@ -1,6 +1,8 @@
 import { DashboardInput, NormalizedDashboardInput, TCard } from '../../lib/types/common-types.js';
 import { TFilter } from '../../components/surfboard/filter/types.js';
-export type DashboardFilterMappingContractIssueCode = 'invalid_input' | 'both_filter_definitions' | 'missing_filter_definition' | 'orphaned_filter_reference' | 'invalid_filter_reference' | 'duplicate_filter_reference' | 'global_date_reference' | 'unsupported_mapped_scope' | 'invalid_application' | 'duplicate_card_application' | 'unknown_card' | 'invalid_binding_id' | 'unsupported_target' | 'invalid_target_field' | 'unknown_target_data_type' | 'unavailable_card_source' | 'invalid_option_source' | 'invalid_option_dependencies' | 'invalid_option_population';
+export type DashboardFilterMappingContractIssueCode = 'invalid_input' | 'both_filter_definitions' | 'missing_filter_definition' | 'orphaned_filter_reference' | 'invalid_filter_reference' | 'duplicate_filter_reference' | 'global_date_reference' | 'unsupported_mapped_scope' | 'invalid_application' | 'duplicate_card_application' | 'unknown_card' | 'invalid_binding_id' | 'unsupported_target' | 'invalid_target_field' | 'unknown_target_data_type' | 'unavailable_card_source'
+/** A relationship target's ids are empty, not strings, or repeat (RF-D10). */
+ | 'invalid_relationship_route' | 'invalid_option_source' | 'invalid_option_dependencies' | 'invalid_option_population';
 export type DashboardFilterMappingContractIssue = {
     code: DashboardFilterMappingContractIssueCode;
     path: string;

package/dist/types/shared/dashboard-authoring/dashboard-filter-mapping-types.d.ts

@@ -20,10 +20,36 @@ export type DashboardFilterTargetField = {
     /** Catalog-grounded physical column used when it differs from the semantic name. */
     sourceField?: string;
 };
-export type DashboardFilterTarget = {
+/**
+ * An author-chosen route to a card through the domain's relationships
+ * (relationship filter reach RF-D10), for a filter whose value's dataset the
+ * card doesn't use and reaches by more than one equally preferred path. The
+ * card sends the value as it is with these ids; the server resolves exactly
+ * them, or blocks the card while the value is set (P-1).
+ */
+export type DashboardFilterRelationshipTarget = {
+    kind: 'relationship';
+    /** The value's field on its own dataset (the filter's own field). */
+    field: DashboardFilterTargetField;
+    /** Ordered from the card's base dataset to `field.source`'s dataset; non-empty, no repeats. */
+    relationshipIds: string[];
+};
+/**
+ * A field of the card the filter's value applies to directly. Field-only
+ * code (card field catalogs, automatic targeting, click-to-filter, compiling
+ * a card condition) takes this type, so a new target kind never reaches it
+ * unchecked (relationship filter reach hotspot H-05).
+ */
+export type DashboardFilterFieldTarget = {
     kind: 'field';
     field: DashboardFilterTargetField;
 };
+/**
+ * Every target a filter mapping persists. Code that takes both kinds handles
+ * each one explicitly (an exhaustive `switch`), so the compiler names it when
+ * a kind is added; both kinds carry `field`, so reading it never proves which.
+ */
+export type DashboardFilterTarget = DashboardFilterFieldTarget | DashboardFilterRelationshipTarget;
 export type DashboardFilterBoundCardApplication = {
     kind: 'bound';
     cardId: string;