react-semaphor 0.1.546 → 0.1.547

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;

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

@@ -10,9 +10,18 @@ export declare function isDashboardFilterOperationCompatible(dataType: unknown,
 export declare const DASHBOARD_FILTER_OPERATIONS: ReadonlySet<string>;
 export type DashboardFilterScalarType = keyof typeof OPERATIONS_BY_DATA_TYPE;
 /**
- * The values a filter operation takes: how many, and of which scalar type.
  * The one rule for stored filter values, in authored defaults and in saved
- * bookmarks. Appends a message naming `location` for the first problem.
+ * bookmarks: the values a filter operation takes (how many, and of which
+ * scalar type), and a date window that runs to now. A dashboard filter's
+ * dates never count back from the latest data (relationship filter reach
+ * RF-INV-13): the Cards tab previews reach without a value, and a route can't
+ * carry a data anchor (P-6, ledger R-15). MCP edits already refuse such a
+ * default. Appends a message naming `location` (the stored value) for the
+ * first problem.
  */
-export declare function validateDashboardFilterValues(operation: unknown, values: readonly unknown[], valueType: DashboardFilterScalarType | undefined, location: string, errors: string[]): void;
+export declare function validateDashboardFilterValues(value: {
+    operation: unknown;
+    values: readonly unknown[];
+    relativeMeta?: unknown;
+}, valueType: DashboardFilterScalarType | undefined, location: string, errors: string[]): void;
 export {};

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

@@ -0,0 +1,18 @@
+import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../analytics-protocol/index.js';
+/** "Project" to "Projects", "Category" to "Categories"; a label ending in "s" stays. */
+export declare function pluralDatasetLabel(label: string): string;
+/**
+ * P-8 and P-11: "through Project" for a to-one route; "Projects with at least
+ * one matching Dashboard" for a to-many route, where Dashboard is the dataset
+ * its first to-many step reaches. A route of more than one step names the
+ * datasets it passes through, not the filter's own, which it always ends at
+ * ("through Crew" for a Company filter; ledger R-21).
+ */
+export declare function describeRelationshipRoute(route: SemaphorRelationshipRoute): string;
+/** P-1: a persisted route the domain no longer has. */
+export declare const RELATIONSHIP_ROUTE_CHANGED_MESSAGE = "The relationship this card used changed; choose it again";
+/** P-2, P-3, P-6, P-7: why a value was not applied to a card. */
+export declare function describeRelationshipSkip(reason: SemaphorSkippedConstraintReason, cardDataset?: {
+    name: string;
+    label?: string;
+}): string;