react-semaphor 0.1.545 → 0.1.547

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

@@ -0,0 +1,45 @@
+/**
+ * Problems and warnings for dashboard changes (MCP dashboard editing SPEC
+ * 3.2). One shape for both: a refusal lists problems, a proposal carries
+ * warnings. Messages are one sentence a person can read and never name the
+ * product; `fix` tells the agent what to do next.
+ */
+export type ChangeProblemCode = 'invalid_change' | 'invalid_change_target' | 'copy_required' | 'not_permitted' | 'change_not_allowed_for_credential' | 'dashboard_not_found' | 'card_not_found' | 'filter_not_found' | 'sheet_not_found' | 'sheet_required' | 'sheet_not_a_grid' | 'field_not_found' | 'card_not_editable' | 'type_not_supported' | 'query_form_mismatch' | 'capability_required' | 'handle_unknown' | 'too_many_changes'
+/** filter.update or filter.bind on a filter the outline marks read only. */
+ | 'filter_not_editable'
+/** The changed dashboard fails the save's own validation (propose or apply). */
+ | 'document_invalid';
+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. */
+ | 'type_change_drops'
+/** A column's aggregate or time grain changed and its custom label was kept. */
+ | 'label_kept_after_change'
+/** The change makes a library visual's card local to this dashboard. */
+ | 'detaches_linked_visual'
+/** The change removes a level or measure a control is bound to: that control stops changing the card. */
+ | 'control_binding_dropped'
+/** Apply only: saved, but the version control commit failed. */
+ | 'commit_failed'
+/**
+ * Propose from the dashboard on screen (analytics agent Plan 1, D7-13): that
+ * dashboard already fails the save's own check, so the change wasn't
+ * checked against it; the person's Save reports what it finds.
+ */
+ | 'document_not_checked';
+export type ChangeDiagnostic = {
+    code: ChangeProblemCode | ChangeWarningCode;
+    /** One sentence, safe to show an end user. */
+    message: string;
+    /** Where in the request, e.g. `changes[2].query.measures[0]`. */
+    path?: string;
+    /** What the agent should do next; may name tools. */
+    fix?: string;
+    /** E.g. `{ sheets }`, `{ available }`, `{ suggestedFields }`. */
+    details?: Record<string, unknown>;
+};

package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts

@@ -0,0 +1,54 @@
+import { TCard } from '../../../lib/types/common-types.js';
+import { RelativeDateFilter } from '../../analytics-protocol/relative-date-filter.js';
+import { CardType } from './card-types.js';
+import { CardQuery, MatrixColumns, TimeWindow } from './dashboard-change.js';
+/**
+ * A card's query in the public forms (MCP dashboard editing SPEC 3.5), or why
+ * it can't be changed through `card.update`. Conservative: anything the
+ * public query can't state, or that compiling the read query wouldn't
+ * reproduce, is `not_expressible`, with a short `detail`. `editable` answers
+ * only whether the card can be changed; whether it can be analyzed is
+ * `semaphor_analyze` `fromCard`'s question (DE-D29).
+ */
+export type NotEditableReason = 'text' | 'document_section' | 'custom' | 'needs_sql_access'
+/** A chart type outside the eight. */
+ | 'type_not_supported'
+/** The card uses something the public query can't say; `detail` names it. */
+ | 'not_expressible';
+export type OutlineCardSource = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+} | {
+    kind: 'sql';
+    connectionId: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    tableName: string;
+};
+export type CardQueryRead = {
+    editable: true;
+    type: CardType;
+    query: CardQuery;
+    matrix?: MatrixColumns;
+    source: OutlineCardSource;
+} | {
+    editable: false;
+    type: string;
+    reason: NotEditableReason;
+    message: string;
+    detail?: string;
+    source?: OutlineCardSource;
+};
+export declare function readCardQuery(card: TCard, viewer: {
+    sql: boolean;
+}): CardQueryRead;
+/**
+ * Where a card's data comes from, as the outline names it. SQL owns the result
+ * whenever the card has it, even beside config left from another mode: the
+ * execution owner's rule (`resolveDashboardCardResultOwner`).
+ */
+export declare function readCardSource(card: TCard): OutlineCardSource | undefined;
+/** A saved relative date as the public time window it was compiled from, or null when there isn't one. */
+export declare function relativeToTimeWindow(meta: RelativeDateFilter): TimeWindow | null;

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

@@ -0,0 +1,96 @@
+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';
+import { ChangeDiagnostic } from './diagnostics.js';
+/**
+ * Public dashboard changes to resolved operations (MCP dashboard editing SPEC
+ * 3.7, DE-D48). Every rule the schema can't state lives here; everything that
+ * needs app state comes through `services` (S-INV-10). The result carries
+ * every id it assigned (DE-D39), proven by a dry run of the reducer
+ * (S-INV-11), with each added or changed card checked as saved (DE-D56).
+ */
+export type CardSource = {
+    /** The catalog `changeCardType` and `buildFilterInputFromField` take. */
+    fields: readonly Field[];
+    dataSource?: DataSource;
+    connectionId: string;
+    connectionType?: string;
+};
+export type ChangeServices = {
+    /** The caller's capabilities; read only through `need`, which records each one relied on (DE-D60). */
+    capabilities: {
+        sql: boolean;
+    };
+    /**
+     * The report calendar filter defaults resolve in, with a fixed anchor: the
+     * propose instant (DE-D59). The app sets it, so the resolver never reads a
+     * clock (S-INV-10).
+     */
+    calendar: CalendarContext;
+    /** A measures or records query compiled into a card's query part (the app wraps `prepareGovernedCard`). */
+    compileCardQuery(request: {
+        query: MetricCardQuery | RecordsCardQuery;
+        chartType: TChartType;
+    }): Promise<{
+        ok: true;
+        part: CardQueryPart;
+        warnings: ChangeDiagnostic[];
+    } | {
+        ok: false;
+        problems: ChangeDiagnostic[];
+    }>;
+    /** A dataset's or connection's fields in the editor's catalog shape, or null when the caller can't use it. */
+    loadCardSource(ref: {
+        domainId: string;
+        datasetName: string;
+    } | {
+        connectionId: string;
+    }): Promise<CardSource | null>;
+    /** Fields on `toDataset` that the domain's relationships join to `field` on `fromDataset`. Never guessed from names. */
+    findRelationshipFields(input: {
+        domainId: string;
+        fromDataset: string;
+        field: string;
+        toDataset: string;
+    }): 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;
+    kind: 'card' | 'filter';
+    id: string;
+    title: string;
+    changeIndex: number;
+};
+export type ChangeResolution = {
+    ok: true;
+    operations: DashboardOperation[];
+    /** The reducer context the operations were resolved with; stored with the proposal and reused at apply. */
+    context: OperationContext;
+    /** The dashboard after the operations, from a dry run of `applyDashboardOperations`. */
+    dashboard: TDashboard;
+    /** Handle or existing id to final id, in change order; a handle-less card.add gets $card_1, $card_2... */
+    refs: ChangeRef[];
+    descriptions: OperationDescription[];
+    /** Cards whose query part or type changed, and added cards, in change order: the preview runs the first five. */
+    changedCardIds: string[];
+    /** Every capability the resolution relied on (DE-D60). */
+    requires: Array<'sql'>;
+    warnings: ChangeDiagnostic[];
+} | {
+    ok: false;
+    problems: ChangeDiagnostic[];
+};
+export declare function resolveDashboardChanges(dashboard: TDashboard, changes: readonly unknown[], services: ChangeServices): Promise<ChangeResolution>;

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/column-catalog.d.ts

@@ -0,0 +1,32 @@
+import { TDataColumn } from '../../lib/types/common-types.js';
+import { DatabaseEntityReference, DataModelEntityReference, EntityColumnGroup, Field } from '../../lib/types/explorer-types.js';
+/**
+ * The card editor's field catalog, built from the columns API's response
+ * (`/api/v1/columns`): one group per source, domain calculated fields first,
+ * flattened to `Field[]`. The editor's columns hook, the Matrix card catalog
+ * and the server's dashboard change services (MCP dashboard editing SPEC 6.2,
+ * `loadCardSource`) all build it here, so a field has the same id, label and
+ * metadata wherever it is read.
+ */
+export type ColumnCatalogTarget = Pick<DatabaseEntityReference, 'name' | 'type' | 'database' | 'schema'> & Partial<Pick<DataModelEntityReference, 'id' | 'label' | 'description'>>;
+/** One source's columns as `Field`s, in a group named for the source. */
+export declare function buildEntityColumnGroup(target: ColumnCatalogTarget, responseColumns: TDataColumn[]): EntityColumnGroup;
+/** A domain's calculated fields as catalog fields: the stable domain id, domain scope. */
+export declare function domainCalculatedFields(fields: readonly Field[]): Field[];
+/** Groups flattened to the editor's field list, every field labeled and placed in its group. */
+export declare function flattenEntityColumns(entityGroups: EntityColumnGroup[]): Field[];
+/** One columns API response for one source. */
+export type ColumnCatalogEntry = {
+    target: ColumnCatalogTarget;
+    columns?: TDataColumn[];
+    calculatedFields?: Field[];
+};
+/**
+ * The editor's whole catalog for a card's sources: a group per source with
+ * columns, domain calculated fields (deduplicated by their stable id) in a
+ * group of their own first, then every field flattened.
+ */
+export declare function buildColumnCatalog(entries: readonly ColumnCatalogEntry[]): {
+    columnGroups: EntityColumnGroup[];
+    columns: Field[];
+};

package/dist/types/shared/dashboard-authoring/contracts.d.ts

@@ -1,11 +1,8 @@
 import { DashboardInput, DashboardInputScope, DashboardInputValues, TCard, TDashboard, TFilter } from '../../lib/types/index.js';
 import { TChartType } from '../../lib/charts/types.js';
 import { Field } from '../../lib/types/explorer-types.js';
-import { PersistedFrameLayouts } from '../layouts/create-frame-layouts.js';
 import { SemaphorAnalyticsIntent, SemaphorSourceRef } from '../analytics-protocol/index.js';
-export declare const DASHBOARD_AUTHORING_BREAKPOINTS: readonly ["lg", "md", "sm", "xs", "xxs"];
 export declare const DASHBOARD_AUTHORING_MAX_GENERATED_CARDS = 15;
-export type DashboardAuthoringBreakpoint = (typeof DASHBOARD_AUTHORING_BREAKPOINTS)[number];
 export type DashboardCardSizeIntent = 'kpi' | 'chart' | 'table' | 'text';
 export type DashboardPlanCard = {
     id: string;
@@ -103,59 +100,7 @@ export type DashboardAuthoringValidationResult = {
     errors: DashboardPlanWarning[];
     warnings: DashboardPlanWarning[];
 };
-export type DashboardChangeOperation = {
-    kind: 'addCard';
-    card: DashboardPlanCard;
-} | {
-    kind: 'addFilterInput';
-    input: DashboardPlanFilterInput;
-} | {
-    kind: 'addCalculatedField';
-    field: DashboardPlanCalculatedField;
-} | {
-    kind: 'reuseCalculatedField';
-    fieldId: string;
-    scope: 'sheet' | 'dashboard' | 'domain';
-} | {
-    kind: 'renameCard';
-    cardId: string;
-    title: string;
-    description?: string;
-} | {
-    kind: 'updateCardSelectionSettings';
-    cardId: string;
-    card: Pick<DashboardPlanCard, 'clickToFilter' | 'respondsToSelections'>;
-} | {
-    kind: 'reorderCards';
-    cardIds: string[];
-} | {
-    kind: 'unsupported';
-    requestedAction: string;
-    reason: string;
-};
-export type DashboardChangePlan = {
-    version: 1;
-    id: string;
-    dashboardId: string;
-    title?: string;
-    description?: string;
-    datasets: SemaphorSourceRef[];
-    operations: DashboardChangeOperation[];
-    warnings?: DashboardPlanWarning[];
-    unresolvedRequests?: string[];
-};
-export type DashboardChangeCompileResult = {
-    dashboard: TDashboard;
-    warnings: DashboardPlanWarning[];
-    skippedOperations: DashboardPlanWarning[];
-};
 export type CompiledDashboardInputDefaults = {
     inputs: DashboardInput[];
     defaultInputValues?: DashboardInputValues;
 };
-export type DashboardLayoutCompileInput = {
-    frameId: string;
-    role: DashboardCardSizeIntent;
-    priority: number;
-};
-export type DashboardLayoutCompileResult = PersistedFrameLayouts;

package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts

@@ -12,6 +12,16 @@ import { ControlBinding, ControlDefinition } from '../../lib/types/common-types.
 export declare function isPresentationCurrencyBinding(binding: ControlBinding): binding is Extract<ControlBinding, {
     target: 'presentation_currency';
 }>;
+/**
+ * What a structural control replaces when it runs (the control executor's
+ * contract; semaphor-app `config-control-resolution.ts` applies it and its
+ * parity test holds it to this): a metric selector the measures, an
+ * aggregation every measure's aggregate, a field selector the grouping
+ * fields, a grain the grouped date's grain. A change to that part of a card
+ * wouldn't take effect.
+ */
+export type StructuralControlOverride = 'measures' | 'measureAggregates' | 'groupingFields' | 'timeGrain';
+export declare function structuralControlOverride(binding: ControlBinding): StructuralControlOverride | undefined;
 /** A binding that changes the query's structure (fields, metrics, aggregation, grain). */
 export declare function isStructuralControlBinding(binding: ControlBinding): binding is Exclude<ControlBinding, {
     target: 'sql_param' | 'presentation_currency';
@@ -194,9 +204,9 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
 }, {
     type: "number" | "boolean" | "date" | "text" | "enum" | "multi_enum" | "field_selector" | "metric_selector" | "aggregation_selector" | "grain_selector";
     id: string;
@@ -237,9 +247,9 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
 }>, {
     type: "number" | "boolean" | "date" | "text" | "enum" | "multi_enum" | "field_selector" | "metric_selector" | "aggregation_selector" | "grain_selector";
     id: string;
@@ -280,9 +290,9 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
 }, {
     type: "number" | "boolean" | "date" | "text" | "enum" | "multi_enum" | "field_selector" | "metric_selector" | "aggregation_selector" | "grain_selector";
     id: string;
@@ -323,9 +333,9 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
 }>;
 export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"target", [z.ZodObject<{
     controlId: z.ZodString;
@@ -333,12 +343,12 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
     paramId: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     target: "sql_param";
-    paramId: string;
     controlId: string;
+    paramId: string;
 }, {
     target: "sql_param";
-    paramId: string;
     controlId: string;
+    paramId: string;
 }>, z.ZodObject<{
     controlId: z.ZodString;
     target: z.ZodLiteral<"config_metric_selector">;
@@ -858,6 +868,7 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
     }>>;
 }, "strict", z.ZodTypeAny, {
     target: "config_metric_selector";
+    controlId: string;
     mapping: Record<string, z.objectOutputType<{
         id: z.ZodString;
         name: z.ZodString;
@@ -933,10 +944,10 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
         id: string;
         kind: "matrix_instance";
     }>;
-    controlId: string;
     matrixTargetId?: string | undefined;
 }, {
     target: "config_metric_selector";
+    controlId: string;
     mapping: Record<string, z.objectInputType<{
         id: z.ZodString;
         name: z.ZodString;
@@ -1012,7 +1023,6 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
         id: string;
         kind: "matrix_instance";
     }>;
-    controlId: string;
     matrixTargetId?: string | undefined;
 }>, z.ZodObject<{
     controlId: z.ZodString;
@@ -1526,6 +1536,7 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
     }>>;
 }, "strict", z.ZodTypeAny, {
     target: "config_field_selector";
+    controlId: string;
     mapping: Record<string, z.objectOutputType<{
         id: z.ZodString;
         name: z.ZodString;
@@ -1600,10 +1611,10 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
         id: string;
         kind: "matrix_instance";
     }>;
-    controlId: string;
     matrixTargetId?: string | undefined;
 }, {
     target: "config_field_selector";
+    controlId: string;
     mapping: Record<string, z.objectInputType<{
         id: z.ZodString;
         name: z.ZodString;
@@ -1678,7 +1689,6 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
         id: string;
         kind: "matrix_instance";
     }>;
-    controlId: string;
     matrixTargetId?: string | undefined;
 }>, z.ZodObject<{
     controlId: z.ZodString;
@@ -1687,13 +1697,13 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
     mapping: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodString>, Record<string, string>, Record<string, string>>;
 }, "strict", z.ZodTypeAny, {
     target: "config_aggregation";
-    mapping: Record<string, string>;
     controlId: string;
+    mapping: Record<string, string>;
     matrixTargetId?: string | undefined;
 }, {
     target: "config_aggregation";
-    mapping: Record<string, string>;
     controlId: string;
+    mapping: Record<string, string>;
     matrixTargetId?: string | undefined;
 }>, z.ZodObject<{
     controlId: z.ZodString;
@@ -1702,13 +1712,13 @@ export declare const controlBindingExecutionSchema: z.ZodDiscriminatedUnion<"tar
     mapping: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodString>, Record<string, string>, Record<string, string>>;
 }, "strict", z.ZodTypeAny, {
     target: "config_grain";
-    mapping: Record<string, string>;
     controlId: string;
+    mapping: Record<string, string>;
     matrixTargetId?: string | undefined;
 }, {
     target: "config_grain";
-    mapping: Record<string, string>;
     controlId: string;
+    mapping: Record<string, string>;
     matrixTargetId?: string | undefined;
 }>, z.ZodObject<{
     controlId: z.ZodString;

package/dist/types/shared/dashboard-authoring/dashboard-card-source-index.d.ts

@@ -1,5 +1,5 @@
 import { TCard } from '../../lib/types/common-types.js';
-import { DataSource, DatabaseEntityReference } from '../../lib/types/explorer-types.js';
+import { DataSource, DatabaseEntityReference, Field } from '../../lib/types/explorer-types.js';
 import { DashboardFilterTargetSource } from './dashboard-filter-mapping-types.js';
 export type DashboardCardFilterSourceInventory = {
     cardId: string;
@@ -24,6 +24,14 @@ export type DashboardSqlPinnedCatalogSource = {
     /** Physical SQL coordinate declared by the pinned entity, when available. */
     executionTable?: DashboardSqlExecutionTable;
 };
+/**
+ * The one dataset of a card's data source a field reads, or undefined when it
+ * reads none or several: matched by the field's source, its dependencies'
+ * stable ids and names, and for physical tables the connection's own path
+ * levels. Every reader that places a field on a dataset asks here (the filter
+ * source index, the Matrix editor's catalog), whatever the connection.
+ */
+export declare function resolveFieldSelectedSource(field: Field, dataSource: DataSource | undefined): DashboardFilterTargetSource | undefined;
 export declare function resolveDashboardEntitySource(entity: DatabaseEntityReference, dataSource: DataSource | undefined): DashboardFilterTargetSource | undefined;
 /**
  * Inventories config sources proven executable by the card and SQL sources

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/dashboard-input-scope.d.ts

@@ -90,3 +90,29 @@ export declare function rewriteDashboardInputScopeIds(scope: DashboardInputScope
 export declare function isDashboardInputOwnedBySheet(scope: DashboardInputScope, sheetId: string, cardIds: ReadonlySet<string>): boolean;
 /** Whether a scope reaches nothing: an empty tab or card list (after ids are removed). */
 export declare function isDashboardInputScopeEmpty(scope: DashboardInputScope): boolean;
+/** The cards a scope leaves out explicitly ("every card except"), in the order they were left out. */
+export declare function listDashboardInputScopeExceptedCardIds(scope: DashboardInputScope): readonly string[];
+/** The sheets an every-sheet scope leaves out ("all sheets except"); none for any other scope. */
+export declare function listDashboardInputScopeExceptedSheetIds(scope: DashboardInputScope): readonly string[];
+/**
+ * The scope with one card taken back in: off the "every card except" list.
+ * Unchanged when the scope doesn't leave the card out that way (a card on a
+ * sheet the scope leaves out stays out: that is a change of sheets).
+ */
+export declare function withCardIncludedInScope(scope: DashboardInputScope, cardId: string): DashboardInputScope;
+/**
+ * A new sheet scope with what the stored scope says that a change of sheets
+ * doesn't: the cards it leaves out and its Document-sheet reach. The change
+ * names only grid sheets, so Document ids must come from the saved scope.
+ */
+export declare function withUnstatedScopeParts(stored: DashboardInputScope, next: DashboardInputScope, documentSheetIds: ReadonlySet<string>): DashboardInputScope;
+/** Whether an every-sheet scope also covers Document sheets (no kinds named means every kind). */
+export declare function dashboardInputScopeIncludesDocumentSheets(scope: DashboardInputScope): boolean;
+/**
+ * The scope with one card left out: every reached tab except that card (a
+ * card added later is still reached), or the card list without it. A
+ * Document-section scope names sections, not cards, so it can't leave one
+ * out (undefined). Inputs that can't carry card mappings (Global Date) are
+ * excluded this way.
+ */
+export declare function withCardExcludedFromScope(scope: DashboardInputScope, cardId: string): DashboardInputScope | undefined;