react-semaphor 0.1.537 → 0.1.539

package/dist/types/lib/dashboard-viewer/compatibility-input-storage.d.ts

@@ -0,0 +1,79 @@
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { DashboardInputCompatibilityMetadata, DashboardInputValues, TDashboard } from '../types/common-types.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+/**
+ * The bridge between bookmark slots and the storage compatibility inputs
+ * still use (TECH-SPEC 12, ledger P2-08). Legacy dashboard filters, controls
+ * and card inline filters keep their values in `filterValues`, control values
+ * and inline filter values, where the filter bar, controls and queries read
+ * them. Reading turns that storage into slots; writing turns a bookmark's
+ * slots back into it. When those inputs keep their values in slots, this
+ * file is deleted.
+ */
+export type ViewerRuntimeInputs = {
+    readonly filterValues: readonly TFilterValue[];
+    readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
+    readonly dashboardInputValues: DashboardInputValues;
+    /** Absent: the cards' inline filter defaults. */
+    readonly inlineFilterValuesMap?: Readonly<Record<string, readonly TFilterValue[]>>;
+};
+/** The input values the dashboard store holds, which cards run with. */
+export type ViewerStoreInputValues = {
+    filterValues: TFilterValue[];
+    controlValues: Record<string, unknown>;
+    cardControlValuesMap: Record<string, Record<string, unknown>>;
+    dashboardInputValues: DashboardInputValues;
+    inlineFilterValuesMap: Record<string, TFilterValue[]>;
+};
+/**
+ * The store's input values for these runtime values: the authored control
+ * defaults (dashboard and card) with the overrides on them, and the cards'
+ * inline filter defaults unless the values include their own. The one place
+ * runtime values become the values cards run with: the store applies it when
+ * a dashboard loads or refetches (`setDashboardWithFilterValues`), when it is
+ * replaced in place (`setDashboard`, keeping live control values), when a
+ * sheet is copied (the copy's defaults) and on every viewer event; the
+ * snapshot capture materializes it, and the analytics agent's regression set
+ * opens a saved dashboard with it. A host's control change alone goes through
+ * `computeRuntimeControlHydration`, the control half it is built on.
+ */
+export declare function resolveViewerStoreInputValues(dashboard: TDashboard, runtime: ViewerRuntimeInputs, calendar: CalendarContext | undefined): ViewerStoreInputValues;
+/**
+ * Every applicable input's slot on every dashboard sheet and card, as the
+ * snapshot capture materializes them, including click selection slots.
+ */
+export declare function materializeViewerInputs(dashboard: TDashboard, runtime: ViewerRuntimeInputs, calendar: CalendarContext | undefined): DashboardInputValues;
+/**
+ * Every applicable input's current slot from the store's runtime values,
+ * materialized like the baseline. `readViewerSnapshot` uses it.
+ */
+export declare function materializeViewerRuntimeInputs(dashboard: TDashboard, runtimeValues: Parameters<typeof materializeRuntimeInputs>[1], calendar: CalendarContext | undefined): DashboardInputValues;
+declare function materializeRuntimeInputs(dashboard: TDashboard, runtimeValues: {
+    filterValues?: TFilterValue[];
+    controlValues?: Record<string, unknown>;
+    cardControlValuesMap?: Record<string, Record<string, unknown>>;
+    dashboardInputValues?: DashboardInputValues;
+    inlineFilterValuesMap?: Record<string, TFilterValue[] | undefined>;
+}, calendar: CalendarContext | undefined): DashboardInputValues;
+/**
+ * A bookmark's slots, split by where each value lives. Authored inputs and
+ * click selections are runtime slots. Inputs synthesized from legacy dashboard
+ * filters, controls and card inline filters keep their values where the
+ * filter bar, controls and queries read them: `filterValues`, control values
+ * and inline filter values. A comparison choice stays a runtime aspect slot.
+ */
+export type BookmarkInputs = {
+    readonly runtime: DashboardInputValues;
+    /** filterId -> value, or `null` for a default the viewer removed. */
+    readonly filterValues: ReadonlyMap<string, TFilterValue | null>;
+    readonly controlValues: Readonly<Record<string, unknown>>;
+    /** cardId -> filterId -> value, or `null` for a removed default. */
+    readonly inlineFilterValues: ReadonlyMap<string, ReadonlyMap<string, TFilterValue | null>>;
+};
+export declare function splitBookmarkInputs(compatibilityByInputId: ReadonlyMap<string, DashboardInputCompatibilityMetadata>, values: DashboardInputValues): BookmarkInputs;
+export declare function overlayFilterValues(base: readonly TFilterValue[], overrides: ReadonlyMap<string, TFilterValue | null>): TFilterValue[];
+export declare function overlayControlValues(dashboard: TDashboard, base: Readonly<Record<string, unknown>> | undefined, overrides: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> | undefined;
+export declare function overlayInlineFilterValues(defaults: Readonly<Record<string, readonly TFilterValue[]>>, overrides: ReadonlyMap<string, ReadonlyMap<string, TFilterValue | null>>): Record<string, TFilterValue[]> | undefined;
+/** Live inline filter values for inline filters the cards still define, over the defaults. */
+export declare function keepLiveInlineFilterValues(dashboard: TDashboard, defaults: Readonly<Record<string, readonly TFilterValue[]>>, live: Readonly<Record<string, readonly TFilterValue[] | undefined>>): Record<string, TFilterValue[]> | undefined;
+export {};

package/dist/types/lib/dashboard-viewer/viewer-state.d.ts

@@ -1,10 +1,11 @@
 import { DashboardInputValues, TDashboard } from '../types/common-types.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
-import { DefaultsCalendar } from '../utils/filter-default-value-utils.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
 import { ViewerTableSettings } from '../../shared/dashboard-viewer/table-settings.js';
 import { Bookmark, BookmarkState } from '../../shared/dashboard-viewer/viewer-contract.js';
 /** The report runtime's calendar, as filter defaults read it. */
-export type ViewerCalendar = DefaultsCalendar;
+/** The viewer's report calendar, from report preferences (card query assembly CQ-D8). */
+export type ViewerCalendar = CalendarContext;
 /** A host filter default: a full filter value, or the short `{ filterId, values }` embed form. */
 export type HostFilterValue = TFilterValue | {
     readonly filterId: string;

package/dist/types/lib/document/document-table-data-policy.d.ts

@@ -0,0 +1,15 @@
+import { TCard } from '../types/common-types.js';
+export type DocumentTableDataPolicy = 'preview-window' | 'export-full-with-cap';
+export declare const DOCUMENT_TABLE_EXPORT_MAX_ROWS = 10000;
+export declare const DOCUMENT_TABLE_EXPORT_QUERY_CHUNK_SIZE = 500;
+export declare const DOCUMENT_TABLE_PREVIEW_QUERY_CHUNK_SIZE = 250;
+export declare function isDocumentFlatTableAcquisitionCard(card: TCard): boolean;
+export declare function isDocumentSqlTablePaginationEnabled(card: TCard): boolean;
+export declare function getDocumentTableQueryPageSize(policy: DocumentTableDataPolicy): 500 | 250;
+export declare function shouldUseServerPaginationForDashboardCardQuery({ card, isTablePrintMode, isPrintDisplayMode, isDocumentSectionRuntime, documentTableDataPolicy, }: {
+    card: TCard;
+    isTablePrintMode: boolean;
+    isPrintDisplayMode: boolean;
+    isDocumentSectionRuntime: boolean;
+    documentTableDataPolicy?: DocumentTableDataPolicy;
+}): boolean;

package/dist/types/lib/filter-values/filter-mode.d.ts

@@ -0,0 +1,22 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+/**
+ * Include or Exclude: how a multi-select filter applies its selected values.
+ * The mode is stored as an operation (`in` / `not in`). A definition's
+ * operation is the authored mode; the viewer's mode lives on the live value
+ * (see `resolveLiveFilterMode`).
+ */
+export type FilterMode = 'include' | 'exclude';
+export declare function isInclusionFilterOperation(operation: TFilterValue['operation'] | undefined): operation is 'in' | 'not in';
+export declare function getFilterModeFromOperation(operation: TFilterValue['operation'] | undefined): FilterMode;
+export declare function getFilterOperationFromMode(filterMode: FilterMode): 'in' | 'not in';
+/**
+ * The mode every viewer surface shows (FM-D2): the live value's when it is an
+ * inclusion value, else the mode the viewer picked before selecting anything
+ * (held by the dropdown, never a store), else the target's authored default
+ * mode (`resolveAuthoredFilterDefault`).
+ */
+export declare function resolveLiveFilterMode(params: {
+    authoredMode: FilterMode;
+    liveValue: Pick<TFilterValue, 'operation'> | undefined;
+    pendingMode?: FilterMode;
+}): FilterMode;

package/dist/types/lib/hooks/use-calendar-context.d.ts

@@ -1,5 +1,10 @@
 import { CalendarContext, ReportPreferenceSources, WeekStart } from '../../shared/report-runtime-context/index.js';
 import { ResolvedTemporalValueFormatPreferences, ResolvedValueFormatPreferences } from '../../shared/value-format-preferences/index.js';
+/**
+ * The viewer's report calendar (report preferences). It keeps its identity
+ * until its content changes, so a report context replaced for a formatting
+ * preference never re-resolves what reads the calendar.
+ */
 export declare function useCalendarContext(): CalendarContext | null;
 export declare function useTimezone(): string | null;
 export declare function useWeekStart(): WeekStart | null;

package/dist/types/lib/hooks/use-filter-option-browse.d.ts

@@ -59,6 +59,11 @@ export type FilterOptionBrowseState = {
     resultSource: 'local' | 'server' | 'both';
     hasNextPage: boolean;
     hasLoadedMoreOptions: boolean;
+    /**
+     * More options exist than the list holds and none load on scroll (an
+     * engine whose filter options don't page): only search reaches the rest.
+     */
+    isFirstPageOnly: boolean;
     isFetchingNextPage: boolean;
     isNextPageError: boolean;
     loadNextPage: () => void;

package/dist/types/lib/hooks/use-text-filter.d.ts

@@ -1,4 +1,5 @@
 import { TFilter, TFilterValue, TSelectedRecord, FilterStorageOptions } from '../../components/surfboard/filter/types.js';
+import { FilterMode } from '../filter-values/filter-mode.js';
 export declare function useTextFilterHook(filterId: string): {
     isLoading: boolean;
     isFetching: boolean;
@@ -8,6 +9,7 @@ export declare function useTextFilterHook(filterId: string): {
     retry: () => void;
     hasNextPage: boolean;
     hasLoadedMoreOptions: boolean;
+    isFirstPageOnly: boolean;
     isFetchingNextPage: boolean;
     isNextPageError: boolean;
     loadNextPage: () => void;
@@ -21,6 +23,9 @@ export declare function useTextFilterHook(filterId: string): {
     isSingleSelect: boolean;
     allSelected: boolean;
     activeFilterValue: TFilterValue | undefined;
+    filterMode: FilterMode;
+    changeFilterMode: (mode: FilterMode) => void;
+    discardPendingFilterMode: () => void;
     isSearching: boolean;
     searchError: boolean;
     resultSource: "server" | "both" | "local";
@@ -42,6 +47,7 @@ export declare function useTextFilter(filter: TFilter, options?: UseTextFilterOp
     retry: () => void;
     hasNextPage: boolean;
     hasLoadedMoreOptions: boolean;
+    isFirstPageOnly: boolean;
     isFetchingNextPage: boolean;
     isNextPageError: boolean;
     loadNextPage: () => void;
@@ -57,6 +63,9 @@ export declare function useTextFilter(filter: TFilter, options?: UseTextFilterOp
     isSingleSelect: boolean;
     allSelected: boolean;
     activeFilterValue: TFilterValue | undefined;
+    filterMode: FilterMode;
+    changeFilterMode: (mode: FilterMode) => void;
+    discardPendingFilterMode: () => void;
     isSearching: boolean;
     searchError: boolean;
     resultSource: "server" | "both" | "local";

package/dist/types/lib/print/print-inputs.d.ts

@@ -1,3 +1,4 @@
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
 import { DashboardInputExecutionSnapshot, TDashboard } from '../types/common-types.js';
 import { DashboardInputRuntimeValues } from '../dashboard-inputs/resolve-dashboard-input-context.js';
 import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
@@ -92,12 +93,13 @@ export declare function buildMissingPrintInputs({ sheetId, sheetTitle, inputLabe
  * for drill state). Carried state follows the caller: a schedule passes no
  * transient contexts or card view state, a download passes the viewer's.
  */
-export declare function capturePrintInputs({ dashboard, sheets, runtimeValues, transientContexts, timezone, generatedAt, }: {
+export declare function capturePrintInputs({ dashboard, sheets, runtimeValues, transientContexts, calendar, generatedAt, }: {
     dashboard: TDashboard;
     sheets: readonly PrintSheetRef[];
     runtimeValues: DashboardInputRuntimeValues;
     transientContexts: readonly TransientInputContext[] | undefined;
-    timezone?: string;
+    /** The report calendar the capture resolves input defaults in (CQ-D8); the capture keeps its zone. */
+    calendar: CalendarContext | null;
     generatedAt?: string;
 }): PrintInputCapture;
 /** Reads an untrusted value. Returns undefined for anything that is not a valid version-1 capture. */

package/dist/types/lib/query-context/build-card-query-context.d.ts

@@ -2,9 +2,9 @@ import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.j
 import { ControlBinding, ControlDefinition, ResolvedDashboardDateComparisonInput, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
 import { GlobalDateComparisonContext, GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
 import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
-import { CardConfig } from '../types/explorer-types.js';
-import { resolveRuntimeCardFilters } from './resolve-runtime-card-filters.js';
-import { CardViewState } from '../dashboard-view-state/index.js';
+import { CardConfig, FilterGroup } from '../types/explorer-types.js';
+import { RuntimeCardFilterParts } from './resolve-runtime-card-filters.js';
+import { CardViewState, DrillStep } from '../dashboard-view-state/index.js';
 import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
 import { DashboardCardFilterCompilationInput } from './compile-dashboard-card-filters.js';
 import { ResolvedCardDateFields } from './resolve-card-primary-date-field.js';
@@ -51,7 +51,15 @@ export type CardQueryContext = {
     controlDefinitions: ControlDefinition[];
     cardControlDefinitions: ControlDefinition[];
     controlBindings: ControlBinding[];
-    resolvedFilters: ReturnType<typeof resolveRuntimeCardFilters>;
+    resolvedFilters: FilterGroup | undefined;
+    /**
+     * The groups `resolvedFilters` merges, by origin (authored, drill,
+     * selections). Readers that keep where a condition came from read these;
+     * never part of the query identity.
+     */
+    resolvedFilterParts: RuntimeCardFilterParts;
+    /** The drill path the card runs at: `finalConfig` is grouped at its last step. */
+    drillSteps: readonly DrillStep[];
     finalConfig: CardConfig;
     queryRelevantConfig: CardConfig;
     finalFiltersKey: string;

package/dist/types/lib/query-context/build-dashboard-execution-snapshot.d.ts

@@ -0,0 +1,93 @@
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { CardViewStateMap } from '../dashboard-view-state/index.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardInputValues, TCard, TDashboard } from '../types/common-types.js';
+import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
+import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
+import { CompiledCardQueryContext } from './build-card-query-context.js';
+import { CompiledDashboardCardFilters } from './compile-dashboard-card-filters.js';
+import { CardRequestPayload } from './card-server-request.js';
+import { DocumentSectionCardRuntime } from './document-section-card-query.js';
+import { MatrixCardCatalog, prepareMatrixCard } from '../matrix-table/matrix-card-adapter.js';
+export type DashboardExecutionSnapshot = {
+    selectedSheetId: string | null;
+    filterValues: TFilterValue[];
+    controlValues: Record<string, unknown>;
+};
+type BuildDashboardExecutionSnapshotParams = {
+    dashboard: Pick<TDashboard, 'filters' | 'sheets'> | undefined;
+    filterValues: TFilterValue[] | undefined;
+    selectedSheetId: string | null | undefined;
+    sheetSelection?: 'current' | 'all';
+    dashboardControlValues?: Record<string, unknown>;
+    cardControlValuesMap?: Record<string, Record<string, unknown> | undefined> | undefined;
+    semanticExecutionPayload?: SemanticExecutionPayload;
+    timezone?: string;
+};
+export declare function buildDashboardExecutionSnapshot({ dashboard, filterValues, selectedSheetId, sheetSelection, dashboardControlValues, cardControlValuesMap, semanticExecutionPayload, timezone, }: BuildDashboardExecutionSnapshotParams): DashboardExecutionSnapshot;
+export type BuildDashboardCardExecutionSnapshotParams = {
+    dashboard: TDashboard | undefined;
+    cardId: string;
+    /**
+     * Carried contexts in effect on the dashboard. Required so that every
+     * caller decides; see `buildCardQueryContext`.
+     */
+    transientContexts: readonly TransientInputContext[] | undefined;
+    /** Drill paths by card. Required so that every caller decides; see `buildCardQueryContext`. */
+    cardViewStates: CardViewStateMap | undefined;
+    /**
+     * Viewer table settings by card: the export re-fetch carries the viewer's
+     * sort. Required so that every caller decides; see `buildCardQueryContext`.
+     */
+    viewerTableSettings: Readonly<Record<string, ViewerTableSettings>> | undefined;
+    filterValues: TFilterValue[] | undefined;
+    inlineFilterValuesMap: Record<string, TFilterValue[] | undefined> | undefined;
+    dashboardControlValues?: Record<string, unknown> | undefined;
+    cardControlValuesMap?: Record<string, Record<string, unknown> | undefined> | undefined;
+    dashboardInputValues?: DashboardInputValues;
+    semanticExecutionPayload?: SemanticExecutionPayload;
+    /**
+     * The viewer's report calendar (report preferences): input defaults resolve
+     * in it and the card compiles in its zone (CQ-D8). Null only before the
+     * report context loads.
+     */
+    calendar: CalendarContext | null;
+    /** Current columns metadata for all Matrix targets participating in coverage. */
+    matrixCatalog?: MatrixCardCatalog;
+    /** Editor drafts replace their persisted card only for this computation. */
+    cardOverride?: TCard;
+    sheetId?: string | null;
+    /**
+     * Runs the target card as a Document section (tech spec G3), with the same
+     * rules as every section card's frame query. Other cards keep the dashboard
+     * runtime.
+     */
+    documentSection?: DocumentSectionCardRuntime;
+    /** The editor's preview: its card filter values win, and it previews the authored table. */
+    editor?: {
+        inlineFilterValuesMap: Record<string, TFilterValue[] | undefined>;
+    };
+    /** Also carry the card's request, built from the same assembled inputs (D3b-2). */
+    withRequest?: boolean;
+};
+export type DashboardCardExecutionSnapshot = {
+    status: 'ready';
+    card: TCard;
+    sheetId: string;
+    queryContext: CompiledCardQueryContext;
+    matrix?: ReturnType<typeof prepareMatrixCard>;
+    /** The request the card posts to /api/v1/query (`withRequest`; never for Matrix). */
+    request?: CardRequestPayload;
+};
+export type DashboardCardExecutionSnapshotResult = DashboardCardExecutionSnapshot | {
+    status: 'blocked';
+    cardId: string;
+    mappingDispositions: CompiledDashboardCardFilters['mappingDispositions'];
+    reason?: 'metadata' | 'configuration' | 'coverage';
+    message?: string;
+} | null;
+export declare function requireReadyDashboardCardExecutionSnapshot(result: DashboardCardExecutionSnapshotResult): DashboardCardExecutionSnapshot | null;
+/** One card's compiled query from captured or current values, through the card query assembly. */
+export declare function buildDashboardCardExecutionSnapshot({ dashboard, cardId, transientContexts, cardViewStates, viewerTableSettings, semanticExecutionPayload, filterValues, inlineFilterValuesMap, dashboardControlValues, cardControlValuesMap, dashboardInputValues, calendar, matrixCatalog, cardOverride, sheetId, documentSection, editor, withRequest, }: BuildDashboardCardExecutionSnapshotParams): DashboardCardExecutionSnapshotResult;
+export {};

package/dist/types/lib/query-context/card-server-request.d.ts

@@ -0,0 +1,72 @@
+import { TCard } from '../types/common-types.js';
+import { CardConfig, DataSource, PaginationConfig, TableTotalsRequest } from '../types/explorer-types.js';
+import { CardQueryRequestExtras, DashboardCardQueryRequestPayloadBase } from '../../shared/dashboard-authoring/card-query-request.js';
+import { DocumentTableDataPolicy } from '../document/document-table-data-policy.js';
+/**
+ * A card's request as the server runs it: the card query assembly's request
+ * payload with the card's connection and data source. One owner for the live
+ * card query, CSV export and the analytics agent's replay of a card (Plan 1,
+ * Phase 3b, D3b-2, ledger P3-72, P3-78). Pure and React-free, so the Node
+ * entry can build a saved card's request too.
+ */
+export type CardServerRequestOptions = {
+    /** The editor in dev mode runs a card on the card's own connection. */
+    editorDevMode?: boolean;
+};
+/** The assembly's request with its extras: the whole request a card's query runs with. */
+export type CardRequestPayload = DashboardCardQueryRequestPayloadBase & CardQueryRequestExtras;
+export type CardServerRequest = {
+    connectionId: string;
+    requestPayloadBase: CardRequestPayload & {
+        cardDataSource: DataSource;
+    };
+};
+/** The live card query sends the card's own data source, which may be absent. */
+export type LiveCardServerRequest = {
+    connectionId: string;
+    requestPayloadBase: CardRequestPayload;
+};
+/** The page a new viewer opens a server-paginated card on. */
+export declare function firstCardPage(card: TCard): PaginationConfig;
+/**
+ * A card's request extras: the page a server-paginated table runs (the card,
+ * the display and a Document table policy decide whether it paginates) and a
+ * flat table's totals request. The live query passes the viewer's page; a
+ * captured request (the analytics agent's replay) passes `firstCardPage`,
+ * the page a new viewer opens on.
+ */
+export declare function resolveCardRequestExtras(input: {
+    card: TCard;
+    /** The config the card runs with (drilled, sorted): its totals are taken from it. */
+    finalConfig: CardConfig | undefined;
+    /** A printed table runs whole. Default: on screen. */
+    display?: {
+        isTablePrintMode: boolean;
+        isPrintDisplayMode: boolean;
+    };
+    /** Present for a card in a Document section, with the section's table policy. */
+    documentSection?: {
+        documentTableDataPolicy?: DocumentTableDataPolicy;
+    };
+    /** The page the viewer is on. */
+    page?: PaginationConfig;
+    /** A caller's own totals request (a Document table's). */
+    tableTotalsRequest?: TableTotalsRequest;
+}): CardQueryRequestExtras;
+/**
+ * The connection a card runs on: a SQL card's own connection first, any other
+ * card's data source first; the editor in dev mode only the card's own.
+ * Undefined when the card names none.
+ */
+export declare function resolveCardConnectionId(card: TCard, options?: CardServerRequestOptions): string | undefined;
+/**
+ * Throws when the card names no connection. A server replay or an export
+ * needs a data source and gets one built from the connection when the card
+ * has none; the live query passes `liveDataSource` and sends the card's own.
+ */
+export declare function buildCardServerRequest(card: TCard, requestPayloadBase: CardRequestPayload, options?: CardServerRequestOptions & {
+    liveDataSource?: false;
+}): CardServerRequest;
+export declare function buildCardServerRequest(card: TCard, requestPayloadBase: CardRequestPayload, options: CardServerRequestOptions & {
+    liveDataSource: true;
+}): LiveCardServerRequest;

package/dist/types/lib/query-context/compile-dashboard-card-filters.d.ts

@@ -55,6 +55,13 @@ export type DashboardCardFilterCompilationResult = (CompiledDashboardCardFilters
 export declare function requireReadyDashboardCardFilters(result: DashboardCardFilterCompilationResult): CompiledDashboardCardFilters & {
     status: 'ready';
 };
+/**
+ * Whether a filter input still applies when a carried context turns the
+ * dashboard's own filters off (`resolveContextAwareFilterPolicy`): only inputs
+ * authored for specific cards and the cards' inline filters do. The one rule
+ * for the compiler and for any reader that says which filters a view applies.
+ */
+export declare function filterInputSurvivesCarriedContext(input: Pick<NormalizedDashboardInput, 'kind' | 'scope' | 'compatibility'>): boolean;
 export declare function composeCardFilterValues(card: TCard, input: DashboardCardFilterCompilationInput): {
     status: 'ready';
     filterValues: TFilterValue[];

package/dist/types/lib/query-context/describe-card-execution-snapshot.d.ts

@@ -0,0 +1,56 @@
+import { TCard } from '../types/common-types.js';
+import { AssistantCardDescription } from '../../shared/assistant-protocol/context.js';
+import { DashboardCardExecutionSnapshotResult } from './build-dashboard-execution-snapshot.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+/**
+ * What a card runs, for the assistant (analytics agent Plan 1, ledger D3a-4,
+ * D3a-5, D3a-8): a formatting of the compiled execution snapshot, never a
+ * second resolution of inputs, fields, dates or labels.
+ *
+ * Kept: fields by role at the level the card runs (details included), every
+ * filter by origin with its and/or grouping (dashboard inputs as compiled for
+ * this card, the card's own inputs and saved filters, drill, selections), the
+ * drill path, the controls the card binds or its SQL references with their
+ * values, and the SQL with its parameters, every condition through the one
+ * full-detail renderer.
+ * Past a cap an entry is counted in `omitted`; the fingerprint is the card's
+ * query identity, so it covers all.
+ *
+ * Not described, by capability: Matrix, custom visuals, Python, and a
+ * snapshot that is blocked or still loading. Never a guess.
+ */
+/** A card's snapshot as its store adapter has it: `'pending'` while it loads. */
+export type CardExecutionSnapshotState = DashboardCardExecutionSnapshotResult | 'pending';
+export type DescribedCardExecution = {
+    fingerprint: string;
+    description: AssistantCardDescription;
+};
+export type DescribeCardExecutionOptions = {
+    /** The report calendar the card runs in; instants spanning whole days in its zone read as dates. */
+    calendar: CalendarContext;
+};
+/**
+ * How the description treats every fact the compiled context carries. A field
+ * added to the compiled context fails the type-check until it is classified
+ * here, so nothing a card runs goes unmentioned by accident (ledger P3-66).
+ */
+export declare const COMPILED_FACT_TREATMENT: {
+    readonly finalConfig: "described";
+    readonly cardFilterValues: "described";
+    readonly queryFilterDefinitions: "described";
+    readonly resolvedFilterParts: "described";
+    readonly resolvedFilters: "described";
+    readonly drillSteps: "described";
+    readonly controlValues: "described";
+    readonly controlDefinitions: "described";
+    readonly cardControlDefinitions: "described";
+    readonly controlBindings: "described";
+    readonly queryRelevantConfig: "named_not_described";
+    readonly finalFiltersKey: "identity";
+    readonly resolvedPrimaryDateField: "identity";
+    readonly resolvedDateFields: "identity";
+    readonly globalDateComparison: "described";
+    readonly globalDateComparisonSelection: "described";
+    readonly dateComparisonInputs: "identity";
+};
+export declare function describeCardExecutionSnapshot(card: TCard, snapshot: CardExecutionSnapshotState, options: DescribeCardExecutionOptions): DescribedCardExecution;

package/dist/types/lib/query-context/document-section-card-query.d.ts

@@ -0,0 +1,45 @@
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardInputRuntimeValues } from '../dashboard-inputs/resolve-dashboard-input-context.js';
+import { ControlDefinition, DashboardInputValues, TCard, TDashboard } from '../types/common-types.js';
+import { BuildCardQueryContextParams } from './build-card-query-context.js';
+import { EditorContext } from '../stores/editor-store.js';
+/** What a Document sheet resolved for one section, as one card's query sees it. */
+export type DocumentSectionCardRuntime = {
+    sheetId: string | undefined;
+    sectionId: string | undefined;
+    documentFilterValues: TFilterValue[];
+    documentControlDefinitions: ControlDefinition[];
+    documentControlValues: Record<string, unknown>;
+    /** The page's own input values; the editor's query uses the dashboard's. */
+    documentDashboardInputValues?: DashboardInputValues;
+    /** The editor's card filters, for the editor's query of the card it edits. */
+    editorFilterValues?: TFilterValue[];
+};
+/**
+ * The section an open editor edits, as the editor's own query runs it: the
+ * editor's snapshot of the document inputs and its card filter values.
+ */
+export declare function buildEditedDocumentSectionRuntime(editorContext: Extract<EditorContext, {
+    type: 'documentSection';
+}>, editorFilterValues: TFilterValue[] | undefined): DocumentSectionCardRuntime;
+/**
+ * The `buildCardQueryContext` inputs for a card that runs as a Document
+ * section. A section is its own runtime:
+ * - nothing is carried in (no transient contexts, no drill state);
+ * - the dashboard's toolbar filters and controls do not apply;
+ * - the section's scoped dashboard inputs apply when the dashboard has any,
+ *   otherwise the document's filter and control values do.
+ *
+ * The one owner of these rules, for frame queries and the Matrix execution
+ * snapshot alike.
+ */
+export declare function buildDocumentSectionCardQueryParams({ card, dashboard, runtime, dashboardRuntimeValues, calendar, }: {
+    card: TCard;
+    dashboard: TDashboard;
+    runtime: DocumentSectionCardRuntime;
+    /** The dashboard's runtime values, which scoped input resolution reads. */
+    dashboardRuntimeValues: Omit<DashboardInputRuntimeValues, 'cardViewState'>;
+    /** The report calendar the section's input defaults resolve in (CQ-D8); null only before the report context loads. */
+    calendar: CalendarContext | null;
+}): Omit<BuildCardQueryContextParams, 'selectedSheetId' | 'includeAuthoredFilters'>;

package/dist/types/lib/query-context/resolve-runtime-card-filters.d.ts

@@ -14,16 +14,31 @@ import { SelectionFilterSource } from './compile-selection-filters.js';
  * - Within a selection: AND inside a tuple, OR across tuples, AND across source cards
  * - Between authored filters, the drill path, and selections: AND
  */
-export declare function resolveRuntimeCardFilters(card: TCard, options?: {
+export declare function resolveRuntimeCardFilters(card: TCard, options?: RuntimeCardFilterOptions): FilterGroup | undefined;
+/** Authored filters, then the drill path, then selections; all AND-ed. */
+export declare function mergeRuntimeCardFilterParts(parts: RuntimeCardFilterParts): FilterGroup | undefined;
+type RuntimeCardFilterOptions = {
     includeAuthoredFilters?: boolean;
     /** Other cards' selections, already resolved for this card. */
     selections?: SelectionFilterSource[];
     /** This card's drill path, from card view state. */
     drill?: CardDrillPath;
-}): FilterGroup | undefined;
+};
+/**
+ * The groups `resolveRuntimeCardFilters` merges, by origin, for readers that
+ * keep where each condition came from (the assistant's card description,
+ * analytics agent Plan 1, D3a-4).
+ */
+export type RuntimeCardFilterParts = {
+    authored?: FilterGroup;
+    drill?: FilterGroup;
+    selections?: FilterGroup;
+};
+export declare function resolveRuntimeCardFilterParts(card: TCard, options?: RuntimeCardFilterOptions): RuntimeCardFilterParts;
 /**
  * The configuration a card runs with: grouped at its current drill level, with
  * the resolved runtime filters. Validated here so every consumer (queries,
  * exports, and so on) gets a valid comparison configuration.
  */
 export declare function resolveRuntimeCardConfig(card: TCard, drill: CardDrillPath | undefined, resolvedFilters: FilterGroup | undefined): CardConfig;
+export {};