react-semaphor 0.1.544 → 0.1.546

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

@@ -0,0 +1,43 @@
+/**
+ * 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'
+/** 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,89 @@
+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 { 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;
+};
+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/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';
@@ -193,8 +203,8 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     defaultValue?: unknown;
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
 }, {
@@ -236,8 +246,8 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     defaultValue?: unknown;
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
 }>, {
@@ -279,8 +289,8 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     defaultValue?: unknown;
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
 }, {
@@ -322,8 +332,8 @@ export declare const controlDefinitionExecutionSchema: z.ZodEffects<z.ZodObject<
     defaultValue?: unknown;
     showLabel?: boolean | undefined;
     toolbarWidth?: number | undefined;
-    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     hidden?: boolean | undefined;
+    placement?: "toolbar" | "card_header" | "advanced" | undefined;
     locked?: boolean | undefined;
     helpText?: string | undefined;
 }>;
@@ -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">;

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-mapping-contract.d.ts

@@ -21,6 +21,13 @@ export type NormalizeDashboardInputsResult = {
     inputs: NormalizedDashboardInput[];
     issues: DashboardFilterMappingContractIssue[];
 };
+/**
+ * The one table of allowed scope and runtime-scope combinations (one filter
+ * model SPEC 4.2). A per-tab value lives on every tab the input is shown on
+ * (`isDashboardInputOnTab`), so a `cards` scope may keep per-tab values.
+ */
+export declare const DASHBOARD_INPUT_RUNTIME_SCOPE_KINDS: Readonly<Record<DashboardInput['runtimeScope'], ReadonlyArray<DashboardInput['scope']['kind']>>>;
+export declare function isAllowedDashboardInputScopeCombination(runtimeScope: DashboardInput['runtimeScope'], scopeKind: DashboardInput['scope']['kind']): boolean;
 export declare function normalizeDashboardInputs({ inputs, dashboardFilters, cards, validateCardTargets, }: {
     inputs: DashboardInput[] | unknown;
     dashboardFilters: TFilter[] | undefined;

package/dist/types/shared/dashboard-authoring/dashboard-input-scope.d.ts

@@ -0,0 +1,118 @@
+import { DashboardInputBase, DashboardInputScope, NormalizedDashboardInput, TDashboard } from '../../lib/types/common-types.js';
+import { DashboardInputRuntimeTarget } from '../../lib/dashboard-inputs/dashboard-input-values.js';
+/**
+ * The scope rule (one filter model M2): the one interpreter of
+ * `DashboardInputScope`. Filters, controls, click-to-filter targets and
+ * carried contexts all decide "does this reach that card" here, on the client
+ * and on the server.
+ */
+export type ScopedDashboardInputTarget = DashboardInputRuntimeTarget & {
+    sheetKind?: 'dashboard' | 'document';
+};
+/** One tab, for "is this input shown in this tab's filter bar". */
+export type DashboardTabTarget = {
+    sheetId: string;
+    sheetKind: 'dashboard' | 'document';
+    /** Every card on the tab: sheet cards, frame cards, section cards. */
+    cardIds: ReadonlySet<string>;
+};
+/** Does the input apply to this card, section or tab? */
+export declare function doesDashboardInputApplyToTarget(input: Pick<DashboardInputBase, 'scope' | 'compatibility'>, target: ScopedDashboardInputTarget): boolean;
+/**
+ * Is the input shown in this tab's filter bar? True when it applies to the
+ * tab itself, or to any card on it (a `cards` scope), or, for a
+ * `documentSections` scope, when the tab is that Document tab. "The tabs of
+ * a per-tab input" always means the tabs where this holds.
+ */
+export declare function isDashboardInputOnTab(input: Pick<DashboardInputBase, 'scope' | 'compatibility'>, tab: DashboardTabTarget): boolean;
+/** The tab targets of a dashboard, by sheet id, memoized per dashboard object. */
+export declare function listDashboardTabTargets(dashboard: Pick<TDashboard, 'sheets'>): ReadonlyMap<string, DashboardTabTarget>;
+/**
+ * Every tab, card and Document section an input reaches, as keys
+ * (`sheet:<id>`, `card:<id>`, `section:<id>`). A section card is evaluated
+ * with its section, as the runtime resolves it. Two inputs overlap when their
+ * keys intersect: the one reach behind the overlap rules of filter settings
+ * and of the app's save validation (aliases, backing control ids).
+ */
+export declare function listDashboardInputReachKeys(dashboard: Pick<TDashboard, 'sheets'>, input: Pick<DashboardInputBase, 'scope' | 'compatibility'>): Set<string>;
+/**
+ * Whether a filter input still applies when a carried context turns the
+ * dashboard's own filters off (`resolveContextAwareFilterPolicy`): a filter
+ * scoped to specific cards does, a toolbar filter included, and so do the
+ * cards' inline filters, which are scoped to their card (SP-12). A mapping
+ * never changes the scope, so attaching one never changes survival. The one
+ * rule for the compiler, the mapping resolver, the required check and any
+ * reader that says which filters a view applies.
+ */
+export declare function doesDashboardInputSurviveCarriedContext(input: Pick<NormalizedDashboardInput, 'kind' | 'scope'>): boolean;
+export type DashboardInputScopeIdChange = {
+    removedSheetIds?: ReadonlySet<string>;
+    removedCardIds?: ReadonlySet<string>;
+    /**
+     * Ids given new ids: a card renamed in place, a library visual's ids on its
+     * dashboard instance, an authoring plan's ids on the cards it produced. An
+     * id the map does not list stays.
+     */
+    renamedSheetIds?: ReadonlyMap<string, string>;
+    renamedCardIds?: ReadonlyMap<string, string>;
+    renamedSectionIds?: ReadonlyMap<string, string>;
+    /**
+     * `renamedCardIds` lists every card that is kept: a card id it does not
+     * list is removed (an authoring plan compiled into cards, some skipped).
+     */
+    keepOnlyRenamedCardIds?: boolean;
+    copiedTab?: {
+        /**
+         * 'replace': a filter copied with the tab; every listed id of the copied
+         * tab and its cards becomes its copy's id. 'extend': a filter shared with
+         * the copy; every listed id stays and its copy's id is added next to it.
+         */
+        mode: 'replace' | 'extend';
+        sheetIds: ReadonlyMap<string, string>;
+        cardIds: ReadonlyMap<string, string>;
+        sectionIds: ReadonlyMap<string, string>;
+    };
+};
+/**
+ * Rewrites the ids a scope names, in the positive lists and both except
+ * lists: after tabs or cards are removed, ids are renamed, or a tab is
+ * duplicated. The one rewrite of a scope's ids, for inputs and for click to
+ * filter targets alike. Lists may become empty; whether an input with an
+ * empty scope is kept is the caller's existing rule. Returns the same scope
+ * object when nothing changed.
+ */
+export declare function rewriteDashboardInputScopeIds(scope: DashboardInputScope, change: DashboardInputScopeIdChange): DashboardInputScope;
+/**
+ * Whether a tab owns an input, so deleting the tab deletes it: its scope
+ * names only that tab, only cards on it, or its Document sections. Scope
+ * owns an input's lifetime; runtimeScope only owns its value slots.
+ */
+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;

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

@@ -0,0 +1,75 @@
+import { SemaphorSkippedConstraintReason } from '../analytics-protocol/index.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { TCard } from '../../lib/types/common-types.js';
+import { CardConfig, DataSource } from '../../lib/types/explorer-types.js';
+/**
+ * Whether a dashboard filter's value applies to a card: the one rule (MCP
+ * dashboard editing ledger V-44). The query builder runs it on every filter
+ * value a card receives (semaphor-app build-query); the dashboard's filter
+ * mapping decision (`decideDashboardFilterCardTarget`) and every description
+ * of reach (the outline, reach warnings, the change resolver's effect check)
+ * read it too, so a filter reaches the same cards whether or not it has card
+ * mappings. Moved unchanged from semaphor-app
+ * `src/lib/analytics/query/filter-applicability.ts`, which re-exports it.
+ */
+/** The protocol's skip reasons: evidence reports them as they are (D3b-4). */
+export type FilterSkipReason = SemaphorSkippedConstraintReason;
+export type SkippedFilter = {
+    filterId?: string;
+    name?: string;
+    reason: FilterSkipReason;
+    details?: string;
+};
+export declare function formatSkippedFilterWarnings(skipped: ReadonlyArray<{
+    filterId?: string;
+    name?: string;
+    reason: string;
+}>): string[];
+export type FilterApplicabilityResult = {
+    applicableFilters: TFilterValue[];
+    skippedFilters: SkippedFilter[];
+};
+export type FilterApplicabilityPhase = 'pre_join' | 'post_join';
+export type FilterApplicabilityContext = {
+    cardDataSource?: DataSource | null;
+    targetQualifiedTableName?: string;
+    allowCalculated?: boolean;
+    additionalAllowedIdentifiers?: string[];
+    phase?: FilterApplicabilityPhase;
+};
+/** The same explicit join sources participate in early and final applicability. */
+export declare function collectJoinPlanIdentifiers(joinPlan: CardConfig['joinPlan'] | null): string[];
+/** Only for physical cards after structural completeness validation. Semantic
+ * cards need current catalog dependencies before deciding applicability. Keep
+ * unknown or partially overlapping predicates for the authoritative path. */
+export declare function pruneUnrelatedCalculatedFilters(filters: TFilterValue[], context: FilterApplicabilityContext): FilterApplicabilityResult;
+/**
+ * How the rule decides one filter value: applied with dataset proof, applied
+ * without it (no datasets to check against, a legacy unqualified name, a
+ * calculation with unknown dependencies), or skipped with a reason.
+ */
+export type FilterApplicabilityDecision = {
+    kind: 'apply';
+    proven: boolean;
+} | {
+    kind: 'skip';
+    reason: FilterSkipReason;
+    details?: string;
+};
+export declare function applyFilterApplicability(activeFilters: TFilterValue[] | undefined, context: FilterApplicabilityContext): FilterApplicabilityResult;
+/**
+ * The applicability context of a card as the query builder runs it: the
+ * card's data source, its join plan's entities, and the join phase.
+ */
+export declare function filterApplicabilityContextForCard(card: {
+    dataSource?: DataSource | null;
+    joinPlan?: CardConfig['joinPlan'] | null;
+}): FilterApplicabilityContext;
+/**
+ * Whether a filter value reaches a saved card, by the one rule: `reachable`
+ * when the card's data (the datasets it selects or joins) proves it takes the
+ * value's field, `unreachable` when the rule skips it, `unknown` when the rule
+ * keeps it without proof (nothing to check against, a legacy unqualified
+ * name, a calculation with unknown dependencies).
+ */
+export declare function filterValueReachForCard(filterValue: TFilterValue, card: Pick<TCard, 'dataSource' | 'config'>): 'reachable' | 'unreachable' | 'unknown';

package/dist/types/shared/dashboard-authoring/filter-model/ad-hoc-filter-values.d.ts

@@ -0,0 +1,10 @@
+import { TFilterValue } from '../../../components/surfboard/filter/types.js';
+/**
+ * Whether an ad-hoc value belongs to a tab: its id ends with the tab id. With
+ * no current tab, no ad-hoc value applies. The one owner of this rule (one
+ * filter model SPEC 5.8, P4a-02): the compile, the filter option lists, the
+ * summary request and the filter value list call it.
+ */
+export declare function isAdHocFilterValueOnTab(filterId: string, sheetId: string | null | undefined): boolean;
+/** The ad-hoc values of one tab, in list order. */
+export declare function listAdHocFilterValuesOnTab(adHocFilterValues: readonly TFilterValue[] | undefined, sheetId: string | null | undefined): TFilterValue[];

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

@@ -0,0 +1,29 @@
+import { TFilter } from '../../../components/surfboard/filter/types.js';
+import { NormalizedFilterDashboardInput, TDashboard } from '../../../lib/types/common-types.js';
+import { FilterInputEntry } from './read-dashboard-filter-model.js';
+/** One definition per filter input, in model order. The same array for the same dashboard object. */
+export declare function listDashboardFilterDefinitions(dashboard: TDashboard): readonly TFilter[];
+/** The dashboard's Global Date filter, whichever input holds it. */
+export declare function getDashboardGlobalDateFilter(dashboard: TDashboard): TFilter | undefined;
+/**
+ * The filter inputs the tab-presence rule places on a tab (M2), in model
+ * order: what the tab's filter bar shows. `sheetKind` overrides the tab's
+ * own kind. None for an unknown tab.
+ */
+export declare function listDashboardFilterInputsOnTab(dashboard: TDashboard, sheetId: string | null | undefined, sheetKind?: 'dashboard' | 'document'): readonly FilterInputEntry[];
+/**
+ * A filter hidden from the toolbar and not attached to a visual: a toolbar
+ * filter's `hide`, or an input placed `hidden` (OF-D14). The edit-mode strip
+ * of hidden filters lists these.
+ */
+export declare function isHiddenFilterInput(input: NormalizedFilterDashboardInput): boolean;
+/**
+ * Every filter definition the stored template holds, as stored: toolbar
+ * filters, stored inputs' filters and prototype Document inputs' filters,
+ * rejected inputs included (the model leaves those out). The objects
+ * themselves, so a writer of the stored shape (a migration's remap, a demo
+ * copy) rewrites them in place on its own copy, and a reader that must see
+ * every stored definition (the connections a migration maps) sees what the
+ * remap writes (one filter model P4b-02 (f)).
+ */
+export declare function listStoredFilterDefinitions(dashboard: TDashboard): TFilter[];