react-semaphor 0.1.545 → 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';
@@ -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-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;

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

@@ -2,9 +2,7 @@ export * from './contracts.js';
 export * from './comparison-document-migration.js';
 export * from './source-matching.js';
 export * from './validators.js';
-export * from './layout-compiler.js';
 export * from './artifact-compiler.js';
-export * from './change-compiler.js';
 export * from './protocol-adapter.js';
 export * from './temporal-result-owner.js';
 export * from './temporal-bucket-authoring.js';
@@ -39,3 +37,21 @@ export { matrixCatalogSources, matrixExecutionSources } from './matrix-control-s
 export * from './dashboard-option-dependencies.js';
 export * from './new-card.js';
 export * from './operations/apply-dashboard-operations.js';
+export * from './changes/card-types.js';
+export * from './changes/diagnostics.js';
+export * from './changes/card-query-part.js';
+export * from './changes/read-card-query.js';
+export * from './changes/dashboard-change.js';
+export * from './changes/resolve-dashboard-changes.js';
+export * from './outline/outline-filters.js';
+export * from './outline/outline-dashboard.js';
+export * from './column-catalog.js';
+export { prepareLoadedDashboard } from '../../lib/dashboard-inputs/prepare-loaded-dashboard.js';
+export { buildFilterInputFromField, buildFilterInputFromDefinition, applyFilterSettingsChange } from '../../lib/dashboard-inputs/filter-settings.js';
+export type { FilterSettingsChange, FilterValueEffect } from '../../lib/dashboard-inputs/filter-settings.js';
+export { describeDashboardFilterCardReach, type DashboardFilterCardReach } from '../../lib/query-context/dashboard-filter-mapping-resolution.js';
+export { changeCardType, sharedCardPreferences, type CardTypeChange, type CardTypeChangeOptions, } from '../../lib/utils/card-type-change.js';
+export { buildSavedEditorCard } from '../../lib/utils/build-saved-editor-card.js';
+export { getCardDefinition, type AuthoredCardFields } from '../../lib/utils/card-definition.js';
+export { changeMatrixEditor, dropMatrixEditorField, matrixEditorCatalogFromFields, } from '../../lib/matrix-table/matrix-editor.js';
+export * from './filter-applicability.js';