react-semaphor 0.1.525 → 0.1.527

package/dist/types/lib/export-utils.d.ts

@@ -1,6 +1,7 @@
 import { TablePreferences } from '../components/visual/data-table/types/data-table.js';
 import { TCard } from './types/common-types.js';
 import { SemaphorResultColumn } from '../shared/analytics-protocol/index.js';
+import { CsvDelimiter, CsvEncoding } from '../shared/format-utils/index.js';
 import { CardNumericPresentationContext } from './formatters/numeric-presentation.js';
 import { ComparisonMetadataMap } from './types/query-types.js';
 import { CardConfig, QueryColumnKeyMap } from './types/explorer-types.js';
@@ -8,7 +9,8 @@ import { FlatTableTotalsByColumnId } from './table-formatting/table-totals-setti
 import { RegularTableTemporalPresentation } from './formatters/regular-table-temporal-presentation.js';
 import { RawTemporalPresentation } from './formatters/raw-temporal-presentation.js';
 type ExportTableOptions = {
-    delimiter?: string;
+    delimiter?: CsvDelimiter;
+    encoding?: CsvEncoding;
     includeHeaders?: boolean;
     useFormattedValues?: boolean;
     comparisonMetadata?: ComparisonMetadataMap;
@@ -23,23 +25,23 @@ type ExportTableOptions = {
 /** Build a filesystem-safe CSV filename with the export time in UTC. */
 export declare function buildCsvExportFilename(title: string | null | undefined, generatedAt?: Date): string;
 /**
- * Export table data as CSV with column preferences
+ * The CSV file for plain records (charts and other non-table cards, and the
+ * editor's raw download). Columns are the union of record keys in first-seen
+ * order, so a record missing a key gets an empty cell.
  */
-export declare function exportTableAsCSV(data: any[], fileName: string, tablePreferences?: TablePreferences, card?: TCard, options?: ExportTableOptions): void;
+export declare function buildRecordsCsv({ records, includeHeaders, delimiter, encoding, }: {
+    records: readonly Record<string, unknown>[];
+    includeHeaders?: boolean;
+    delimiter?: CsvDelimiter;
+    encoding?: CsvEncoding;
+}): string;
 /**
- * Export table data with aggregations (for aggregated tables)
+ * Export table data as CSV with column preferences
  */
-export declare function exportAggregatedTableAsCSV(data: any[], fileName: string, groupByColumns?: string[], metricColumns?: string[], options?: {
-    delimiter?: string;
-    includeHeaders?: boolean;
-    includeSubtotals?: boolean;
-    includeGrandTotal?: boolean;
-}): void;
+export declare function exportTableAsCSV(data: any[], fileName: string, tablePreferences?: TablePreferences, card?: TCard, options?: ExportTableOptions): void;
 /**
- * Export pivot table as CSV
+ * The CSV file for a Table or Detail Table, or undefined when there is
+ * nothing exportable.
  */
-export declare function exportPivotTableAsCSV(data: any[], fileName: string, rowHeaders?: string[], columnHeaders?: string[], options?: {
-    delimiter?: string;
-    includeHeaders?: boolean;
-}): void;
+export declare function buildTableCsv(data: any[], tablePreferences?: TablePreferences, card?: TCard, options?: ExportTableOptions): string | undefined;
 export {};

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

@@ -1,4 +1,4 @@
-import { FilterGroup, FilterCondition, LogicalOperator, Field, FilterValue } from '../../types/explorer-types.js';
+import { FilterGroup, FilterCondition, LogicalOperator, Field } from '../../types/explorer-types.js';
 interface UseFilterBuilderProps {
     initialFilters?: FilterGroup | null;
     availableFields?: Field[];
@@ -12,8 +12,8 @@ export declare function useFilterBuilder({ initialFilters, availableFields: prop
     addGroup: (parentGroupId: string) => void;
     removeCondition: (groupId: string, conditionId: string) => void;
     removeGroup: (parentGroupId: string, groupId: string) => void;
-    updateCondition: (groupId: string, conditionId: string, field: keyof FilterCondition, value: FilterValue) => void;
     updateConditionFields: (groupId: string, conditionId: string, updates: Partial<FilterCondition>) => void;
+    replaceCondition: (groupId: string, conditionId: string, next: FilterCondition) => void;
     updateGroupOperator: (groupId: string, operator: LogicalOperator) => void;
     updateGroupNegate: (groupId: string, negate: boolean) => void;
     reorderConditions: (groupId: string, oldIndex: number, newIndex: number) => void;

package/dist/types/lib/hooks/explorer/use-schemas.d.ts

@@ -2,7 +2,7 @@ import { AuthToken } from '../../types/common-types.js';
 export declare function useSchemas(token?: AuthToken): {
     isPending: boolean;
     error: Error | null;
-    schemas: import('../../../components/index.js').DropdownItem[];
+    schemas: import('../../types/dropdown-types.js').DropdownItem[];
     refetch: (options?: import('@tanstack/query-core').RefetchOptions) => Promise<import('@tanstack/query-core').QueryObserverResult<any, Error>>;
     label: string;
 };

package/dist/types/lib/hooks/use-dashboard.d.ts

@@ -1,6 +1,6 @@
 import { AuthToken, ControlBinding, ControlDefinition, CustomCard, DashboardLifecycleEvent, DashboardInputExecutionSnapshot, TDashboard, TEvent, TStyle } from '../types/common-types.js';
 import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
-import { TFilterValue } from '../../components/index.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
 type UseDashboardProps = {
     id?: string;
     version?: string;
@@ -39,7 +39,7 @@ export declare function useDashboard({ customStyle, currentTheme, onSave, onEven
         dashboard: TDashboard;
         assistantProfileId?: string;
         semanticExecutionPayload: import('../types/semantic-runtime-types.js').SemanticExecutionPayload;
-        organizationAppearance?: import('../../components/index.js').AppearanceSpec | null;
+        organizationAppearance?: import('../appearance/types.js').AppearanceSpec | null;
     } | null, Error>>;
 };
 export {};

package/dist/types/lib/hooks/use-relative-date-summarizer.d.ts

@@ -0,0 +1,7 @@
+import { RelativeDateSummary } from '../utils/relative-date-description.js';
+import { RelativeDateFilter } from '../../shared/analytics-protocol/relative-date-filter.js';
+/**
+ * Summarizes relative dates in the dashboard calendar and the viewer's date
+ * preferences (plan D8).
+ */
+export declare function useRelativeDateSummarizer(): (relative: RelativeDateFilter) => RelativeDateSummary;

package/dist/types/lib/interactions/get-click-context-from-chartjs.d.ts

@@ -1,6 +1,5 @@
 import { TCard } from '../types/index.js';
-import { CardConfig, Field } from '../../components/index.js';
-import { QueryColumnKeyMap } from '../types/explorer-types.js';
+import { QueryColumnKeyMap, CardConfig, Field } from '../types/explorer-types.js';
 import { ClickedMetricValue, ClickFilterCondition } from '../types/interaction-types.js';
 import { Chart } from 'chart.js';
 import { SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';

package/dist/types/lib/matrix-table/matrix-application-adapter.d.ts

@@ -4,10 +4,11 @@ import { Field } from '../types/explorer-types.js';
 import { MatrixCardCatalog } from './matrix-card-adapter.js';
 /** Staged transport input. Auth and catalog grounding remain server-owned. */
 type ExecutionInput = Parameters<MatrixExecutionEnvironment['execute']>[0];
-export declare function buildMatrixCardQueryPayload(input: Pick<ExecutionInput, 'spec' | 'window' | 'cardId' | 'runtimeSorts'> & {
+export declare function buildMatrixCardQueryPayload(input: Pick<ExecutionInput, 'spec' | 'window' | 'cardId' | 'runtimeSorts' | 'temporalState'> & {
     queryContext: Pick<ExecutionInput['queryContext'], 'cardFilterValues' | 'controlDefinitions' | 'cardControlDefinitions' | 'controlBindings' | 'controlValues'> & Partial<Pick<ExecutionInput['queryContext'], 'resolvedFilters'>>;
     reportContext: Pick<ExecutionInput['reportContext'], 'calendar'>;
 }): {
+    temporalState?: import('../../shared/analytics-protocol/index.js').OperationTemporalState | undefined;
     active_filters: import('../types/index.js').TFilterValue[];
     calendarContext: import('../types/index.js').CalendarContext;
     controlDefinitions: import('../types/index.js').ControlDefinition[];
@@ -38,7 +39,7 @@ export declare function buildMatrixCardQueryPayload(input: Pick<ExecutionInput,
         levelId: string;
         axis: "columns" | "rows";
         direction: "asc" | "desc";
-        nulls: "first" | "last";
+        nulls: "last" | "first";
     }[] | undefined;
     runtimeFilters?: import('../types/explorer-types.js').FilterGroup | undefined;
     cardId: string;

package/dist/types/lib/matrix-table/matrix-card-adapter.d.ts

@@ -318,7 +318,7 @@ export declare function prepareMatrixCard(card: TCard, catalog: MatrixCardCatalo
                 levelId: string;
                 axis: "columns" | "rows";
                 direction: "asc" | "desc";
-                nulls: "first" | "last";
+                nulls: "last" | "first";
             }[];
             rankings: readonly import('../../shared/analytics-protocol/index.js').MatrixRanking[];
             filters?: import('../types/explorer-types.js').FilterGroup | undefined;

package/dist/types/lib/matrix-table/matrix-card-draft.d.ts

@@ -298,7 +298,7 @@ export declare function initializeMatrixCardDraft(card: Pick<TCard, 'config' | '
             levelId: string;
             axis: "columns" | "rows";
             direction: "asc" | "desc";
-            nulls: "first" | "last";
+            nulls: "last" | "first";
         }[];
         rankings: readonly import('../../shared/analytics-protocol/index.js').MatrixRanking[];
         filters?: import('../types/index.js').FilterGroup | undefined;

package/dist/types/lib/matrix-table/matrix-dataset-history.d.ts

@@ -0,0 +1,47 @@
+import { MatrixDatasetRetention } from './matrix-runtime-types.js';
+/** Matrix fetching plan MF-D3 and MF-D4. */
+export declare const MATRIX_HISTORY_LIMITS: Readonly<{
+    /** Restorable while the oldest piece is younger than this. */
+    freshMs: number;
+    entriesPerCard: 3;
+    entries: 12;
+    bytes: number;
+}>;
+/**
+ * Dashboard-scoped store of inactive Matrix datasets (plan INV-2 to INV-8).
+ *
+ * History holds only datasets no runtime is showing. A newly mounted runtime
+ * may also start from a copy of another runtime's live dataset (efficiency
+ * plan E-D1); the two then own their copies separately. History never limits
+ * or evicts live data: per card it holds at most what is left of the runtime
+ * allowance after the usage of the card's mounted runtimes, oldest saved first
+ * out. Entries are written only by `save` and never mutated afterwards.
+ */
+export declare class MatrixDatasetHistory {
+    private readonly now;
+    private entries;
+    private generations;
+    private live;
+    /** Copies of live datasets handed out by `peek`, so `adopt` can recognize them. */
+    private seeds;
+    private scope?;
+    constructor(now?: () => number);
+    /** A new auth or host scope drops everything saved under the previous one. */
+    setScope(scope: string): void;
+    /** The retention one runtime uses, bound to its card and query identity. */
+    port(binding: {
+        scope: string;
+        card: string;
+        dataset: string;
+    }): MatrixDatasetRetention;
+    private generation;
+    /**
+     * A copy of another mounted runtime's dataset for the same card, query
+     * identity and sorts, when it is current and fresh (plan E-D1). Reading it
+     * changes no runtime; History only remembers the copy it handed out.
+     */
+    private seed;
+    private usable;
+    /** Oldest saved first out: expired, then over the card's remainder, then over the dashboard ceilings. */
+    private fit;
+}

package/dist/types/lib/matrix-table/matrix-delivery.d.ts

@@ -1,4 +1,5 @@
 import { MatrixConfig, MatrixViewState } from '../../shared/analytics-protocol/index.js';
+import { CsvEncoding } from '../../shared/format-utils/exporters/csv-utils.js';
 import { MatrixExportContent } from '../../shared/dashboard-authoring/matrix-delivery.js';
 import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
 import { CompiledCardQueryContext } from '../query-context/build-card-query-context.js';
@@ -34,6 +35,8 @@ export declare function buildMatrixDeliveryPayload(input: {
     content: MatrixExportContent;
     format: 'csv' | 'pdf';
     delimiter: ',' | ';' | '\t';
+    /** CSV only; absent lets the app resolve the dashboard's setting. */
+    csvEncoding?: CsvEncoding;
     includeHeaders: boolean;
 }): {
     controlValues: Record<string, unknown>;
@@ -64,7 +67,7 @@ export declare function buildMatrixDeliveryPayload(input: {
         levelId: string;
         axis: "columns" | "rows";
         direction: "asc" | "desc";
-        nulls: "first" | "last";
+        nulls: "last" | "first";
     }[] | undefined;
     runtimeFilters?: import('../types/explorer-types.js').FilterGroup | undefined;
 } & {
@@ -381,7 +384,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                     levelId: string;
                     axis: "columns" | "rows";
                     direction: "asc" | "desc";
-                    nulls: "first" | "last";
+                    nulls: "last" | "first";
                 }[];
                 rankings: readonly import('../../shared/analytics-protocol/index.js').MatrixRanking[];
                 filters?: import('../types/explorer-types.js').FilterGroup | undefined;
@@ -733,7 +736,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                     levelId: string;
                     axis: "columns" | "rows";
                     direction: "asc" | "desc";
-                    nulls: "first" | "last";
+                    nulls: "last" | "first";
                 }[];
                 rankings: readonly import('../../shared/analytics-protocol/index.js').MatrixRanking[];
                 filters?: import('../types/explorer-types.js').FilterGroup | undefined;
@@ -747,6 +750,7 @@ export declare function buildMatrixDeliveryPayload(input: {
         includeHeaders: boolean;
         timezone: string;
         presentationExecutionSnapshot: import('../../shared/format-utils/index.js').PresentationExecutionSnapshot;
+        csvEncoding?: "utf-8-bom" | "utf-8" | undefined;
         acquisition?: "continuation" | undefined;
     };
 };

package/dist/types/lib/matrix-table/matrix-execution-context.d.ts

@@ -2,6 +2,7 @@ import { CompiledCardQueryContext } from '../query-context/build-card-query-cont
 import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
 import { MatrixWindowExecutor } from './matrix-runtime-types.js';
 import { MatrixOperationQueue } from './matrix-operation-queue.js';
+import { MatrixDatasetHistory } from './matrix-dataset-history.js';
 export type MatrixExecutionEnvironment = {
     ready: boolean;
     /** Existing auth/project scope identity, never a token in the query key. */
@@ -15,4 +16,5 @@ export type MatrixExecutionEnvironment = {
 };
 export declare const MatrixExecutionContext: import('react').Context<(MatrixExecutionEnvironment & {
     queue: MatrixOperationQueue;
+    history: MatrixDatasetHistory;
 }) | null>;

package/dist/types/lib/matrix-table/matrix-query-transport.d.ts

@@ -1,3 +1,6 @@
 import { MatrixExecutionEnvironment } from './matrix-execution-context.js';
-/** The dashboard endpoint owns auth and grounding; no data/SQL reconstruction here. */
+/**
+ * The dashboard endpoint owns auth and grounding; no data/SQL reconstruction
+ * here. Successful windows arrive indexed (efficiency plan E-D8).
+ */
 export declare function createMatrixQueryTransport(endpoint: string, token: string): MatrixExecutionEnvironment['execute'];

package/dist/types/lib/matrix-table/matrix-runtime-types.d.ts

@@ -1,4 +1,4 @@
-import { MatrixAxis, MatrixAxisPage, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixWindowOutcome, MatrixWindowRequest, SemaphorScalarValue } from '../../shared/analytics-protocol/index.js';
+import { MatrixAxis, MatrixAxisPage, MatrixCellBlock, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixIndexedWindowOutcome, MatrixWindowRequest, OperationTemporalState, SemaphorScalarValue } from '../../shared/analytics-protocol/index.js';
 export type MatrixRuntimeError = {
     failure: MatrixFailure;
     retryKey: string | null;
@@ -53,15 +53,110 @@ export type MatrixAxisItem = {
         error: MatrixRuntimeError;
     };
 };
+/**
+ * Slots are per runtime; a copied dataset duplicates them. The loaded data a
+ * slot points to (request, page, coverage, values) is replaced whole, never
+ * modified, so copies may share it (efficiency plan E-INV-6).
+ */
 export type MatrixPageSlot = {
     key: string;
-    request: MatrixPageRequest;
+    request: Readonly<MatrixPageRequest>;
     ordinal: number;
-    data?: MatrixAxisPage;
+    data?: Readonly<MatrixAxisPage>;
+    status: 'idle' | 'loading' | 'ready' | 'failed';
+    error?: MatrixRuntimeError;
+    touched: number;
+    bytes: number;
+};
+/** A loaded cell tile: one row owner (page or singleton path) by one column owner. */
+export type MatrixTileSlot = {
+    key: string;
+    rowOwner: string;
+    columnOwner: string;
+    rows: readonly MatrixPath[];
+    columns: readonly MatrixPath[];
     status: 'idle' | 'loading' | 'ready' | 'failed';
     error?: MatrixRuntimeError;
+    coverage?: Readonly<MatrixCellBlock['coverage']>;
+    /**
+     * Present values by position in `coverage`, keyed
+     * `(row * columns + column) * measures + measure`; absent means no data.
+     */
+    values: ReadonlyMap<number, Readonly<MatrixCellBlock['cells'][number]['value']>>;
+    /** Coverage positions by row key, column key and measure id, for `readCell`. */
+    positions?: MatrixTilePositions;
     touched: number;
     bytes: number;
+    cells: number;
+};
+export type MatrixTilePositions = {
+    rows: ReadonlyMap<string, number>;
+    columns: ReadonlyMap<string, number>;
+    measures: ReadonlyMap<string, number>;
+};
+/** Resident usage in every retention dimension. Bytes are serialized payload, never heap. */
+export type MatrixUsage = {
+    pages: number;
+    blocks: number;
+    cells: number;
+    bytes: number;
+};
+/**
+ * One card's loaded data for one query identity and sort order. It holds only
+ * ready pages and tiles, never failed or loading ones. It is in one runtime or
+ * in the dataset History, never both; a seeded runtime holds its own copy.
+ */
+export type MatrixDataset = {
+    /** The effective sort order it was acquired under. */
+    sorts: string;
+    /** The card generation it belongs to; a refresh makes it unusable. */
+    generation: number;
+    /** When its oldest piece was fetched; saving or restoring never resets it. */
+    fetchedAt: number;
+    queryIdentity: string;
+    descriptors: MatrixWindow['descriptors'];
+    pages: readonly MatrixPageSlot[];
+    tiles: readonly MatrixTileSlot[];
+    usage: MatrixUsage;
+    /**
+     * The operation state its first response reported (analytics kernel K14):
+     * every later page and expansion of this dataset runs on it, so a restored
+     * or seeded dataset continues on the same instant.
+     */
+    temporalState?: OperationTemporalState;
+};
+/** What a mounted runtime exposes to History. */
+export type MatrixLiveView = {
+    usage: () => MatrixUsage;
+    /** A copy of its ready pieces, or nothing while it has none or is in an error state. */
+    snapshot: () => MatrixDataset | undefined;
+};
+/** How one runtime keeps and restores its card's datasets for one query identity. */
+export type MatrixDatasetRetention = {
+    now(): number;
+    /** The card generation a dataset starting now belongs to. */
+    generation(): number;
+    /**
+     * A restorable dataset for these sorts: a saved one, else a copy of another
+     * live view's. A pure read, safe during render.
+     */
+    peek(sorts: string): MatrixDataset | undefined;
+    /**
+     * Takes ownership of a peeked dataset (a saved one leaves History; a live
+     * copy leaves its source untouched); false when it is gone, stale or expired.
+     */
+    adopt(dataset: MatrixDataset): boolean;
+    /** Moves a stopped dataset into History; a stale generation or scope is rejected. */
+    save(dataset: MatrixDataset): void;
+    /** Clears the card's History and returns the card's new generation. */
+    invalidate(): number;
+    /**
+     * Registers this runtime as a live view: its usage counts against the card's
+     * History allowance, and its snapshot may seed another view of the card.
+     */
+    register(view: MatrixLiveView): () => void;
+    /** Live usage grew; History re-fits the card's allowance. */
+    usageChanged(): void;
 };
 export type MatrixRuntimeSnapshot = {
     rows: readonly MatrixAxisItem[];
@@ -107,7 +202,13 @@ export type MatrixWindowExecutor = (input: {
     spec: MatrixSpec;
     window: MatrixWindowRequest;
     signal: AbortSignal;
-}) => Promise<MatrixWindowOutcome>;
+    /** The acquisition's state once its first response reported one. */
+    temporalState?: OperationTemporalState;
+}) => Promise<MatrixWindowExecution>;
+/** A window outcome and the operation state the server ran it on. */
+export type MatrixWindowExecution = MatrixIndexedWindowOutcome & {
+    temporalState?: OperationTemporalState;
+};
 export type MatrixRuntimeInput = {
     spec: MatrixSpec;
     presentation: MatrixPresentation;

package/dist/types/lib/matrix-table/matrix-runtime.d.ts

@@ -1,10 +1,11 @@
 import { QueryClient } from '@tanstack/react-query';
 import { MatrixAxis, MatrixCoordinate, MatrixPath, MatrixSort, MatrixViewState } from '../../shared/analytics-protocol/index.js';
-import { MatrixCellAddress, MatrixCellState, MatrixRuntimeInput, MatrixRuntimeSnapshot, MatrixViewport, MatrixVisibleCoverage, MatrixWindowExecutor } from './matrix-runtime-types.js';
+import { MatrixCellAddress, MatrixCellState, MatrixDatasetRetention, MatrixRuntimeInput, MatrixRuntimeSnapshot, MatrixViewport, MatrixVisibleCoverage, MatrixWindowExecutor } from './matrix-runtime-types.js';
 /** Owns acquisition, errors, generation fencing and retention for exactly one card. */
 export declare class MatrixRuntimeController {
     private query;
     private execute;
+    private retention;
     private readonly prefix;
     private listeners;
     private pages;
@@ -19,6 +20,12 @@ export declare class MatrixRuntimeController {
     private mounted;
     private scheduled;
     private queryIdentity?;
+    /**
+     * The acquisition's operation state (analytics kernel K14): until its first
+     * response reports one, the generation runs one request at a time; after,
+     * every page and expansion sends it, so they all run on one instant.
+     */
+    private temporalState?;
     private error?;
     private notice?;
     private blockingFailures;
@@ -28,12 +35,24 @@ export declare class MatrixRuntimeController {
     private view;
     private spec;
     private snapshot;
-    constructor(input: MatrixRuntimeInput, query: QueryClient, execute: MatrixWindowExecutor, session?: MatrixViewState);
+    /** Card generation of the current dataset; set when the dataset starts. */
+    private datasetGeneration;
+    /** Fetch time of the current dataset's oldest piece. */
+    private datasetFetchedAt?;
+    /** Installed at construction, adopted from History when the runtime starts. */
+    private restored?;
+    private unregister?;
+    constructor(input: MatrixRuntimeInput, query: QueryClient, execute: MatrixWindowExecutor, session?: MatrixViewState, retention?: MatrixDatasetRetention);
     subscribe: (listener: () => void) => () => boolean;
     getSnapshot: () => MatrixRuntimeSnapshot;
     start: () => void;
     stop: () => void;
     private clear;
+    /**
+     * "This card, as of now": every refresh, retry of a request-wide failure and
+     * server-forced reset invalidates the card's History (plan MF-D5), and the new
+     * dataset starts under the bumped generation.
+     */
     refresh: () => void;
     dismissNotice: () => void;
     /** Presentation updates never change the acquisition generation. */
@@ -66,6 +85,12 @@ export declare class MatrixRuntimeController {
     private loadTile;
     private enqueue;
     private pump;
+    /**
+     * Re-derived on every pump, never a flag cleared on success: a bootstrap that
+     * fails, is cancelled or is superseded ends its active work, and the next
+     * queued request becomes the bootstrap.
+     */
+    private awaitingTemporalState;
     private run;
     private current;
     private runtimeError;
@@ -74,6 +99,22 @@ export declare class MatrixRuntimeController {
     private removeTile;
     private removeResource;
     private trim;
+    /** One measure of resident usage for the runtime budget and History. */
+    private usage;
+    /** Order-insensitive, like the sort comparison that decides a reset. */
+    private sortsKey;
+    /** Page ownership for acquired and restored pages alike. */
+    private ownPage;
+    /**
+     * The ready pieces of the current dataset. Failed and loading pieces never
+     * leave (plan INV-7), and a view in a request-wide failure saves nothing.
+     * Copies are taken, so History entries are never mutated afterwards.
+     */
+    private exportDataset;
+    /** Installs copies, so a dataset peeked by two runtimes is never shared mutably. */
+    private install;
+    /** Adopts a fresh saved dataset for the current sorts, if History has one. */
+    private restore;
     private deferPlan;
     private publish;
 }

package/dist/types/lib/matrix-table/use-matrix.d.ts

@@ -9,6 +9,12 @@ type MatrixInput = MatrixRuntimeInput & {
     cardId?: string;
     /** Authored controls input; runtime spec is the resolved display definition. */
     authoredSpec?: MatrixSpec;
+    /**
+     * The shared card query identity (`createCompiledCardQueryIdentities`) of the
+     * same `queryContext` and calendar this card sends. It is the only source of
+     * query-context identity here; never hash query-context fields locally.
+     */
+    queryInputIdentity: string;
     queryContext: CompiledCardQueryContext;
     reportContext: ReportRuntimeContext;
     /** Milliseconds from the card refresh setting; absent while editing. */

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

@@ -1,6 +1,7 @@
 import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
 import { ControlBinding, ControlDefinition, ResolvedDashboardDateComparisonInput, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
-import { GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.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';
@@ -50,6 +51,9 @@ export type CardQueryContext = {
 export type CompiledCardQueryContext = Omit<CardQueryContext, 'filterCompilationInput'> & {
     cardFilterValues: TFilterValue[];
     queryFilterDefinitions: TFilter[];
+    /** Compiled outputs the shared card query identity reads; see `createCompiledCardQueryIdentities`. */
+    resolvedPrimaryDateField: ResolvedPrimaryDateField | null;
+    globalDateComparison: GlobalDateComparisonContext | undefined;
     globalDateComparisonSelection?: GlobalDateComparisonSelection;
     dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
 };

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

@@ -51,7 +51,6 @@ export type DashboardCardQueryExecutionOptions = {
     resolvedPrimaryDateField?: ResolvedPrimaryDateField;
     calendarContext: CalendarContext;
     allowGlobalDateMinutePrecision?: boolean;
-    globalDateComparisonReferenceTime?: string;
     resolvePaginationConfig?: (queryInputIdentity: string) => PaginationConfig | undefined;
 };
 /** One final compilation for interactive requests and immutable input captures. */

package/dist/types/lib/query-context/build-global-date-comparison-context.d.ts

@@ -1,9 +1,8 @@
 import { TCard } from '../types/common-types.js';
 import { DashboardDateComparisonOwner, GlobalDateComparisonContext, GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
 import { DashboardDateComparisonResolution } from '../dashboard-inputs/dashboard-date-comparison-plan.js';
-export declare function buildGlobalDateComparisonContext(card: Pick<TCard, 'preferences'>, selection: GlobalDateComparisonSelection | undefined, referenceTime?: string, owner?: DashboardDateComparisonOwner): GlobalDateComparisonContext | undefined;
+export declare function buildGlobalDateComparisonContext(card: Pick<TCard, 'preferences'>, selection: GlobalDateComparisonSelection | undefined, owner?: DashboardDateComparisonOwner): GlobalDateComparisonContext | undefined;
 export declare function buildDashboardDateComparisonContext(params: {
     card: TCard;
     resolution: DashboardDateComparisonResolution;
-    referenceTime?: string;
 }): GlobalDateComparisonContext | undefined;

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

@@ -35,7 +35,6 @@ export type CompileDashboardCardFiltersParams = {
     semanticExecutionPayload?: SemanticExecutionPayload;
     timezone?: string;
     allowMinutePrecision?: boolean;
-    comparisonReferenceTime?: string;
 };
 export type CompiledDashboardCardFilters = {
     cardFilterValues: TFilterValue[];
@@ -68,5 +67,5 @@ export declare function composeCardFilterValues(card: TCard, input: DashboardCar
  * The single final per-card filter compiler. Every card execution consumer
  * calls this once and treats its result as immutable query state.
  */
-export declare function compileDashboardCardFilters({ card, cardConfig, input, resolvedPrimaryDateField, resolvedFields, semanticExecutionPayload, timezone, allowMinutePrecision, comparisonReferenceTime, }: CompileDashboardCardFiltersParams): DashboardCardFilterCompilationResult;
+export declare function compileDashboardCardFilters({ card, cardConfig, input, resolvedPrimaryDateField, resolvedFields, semanticExecutionPayload, timezone, allowMinutePrecision, }: CompileDashboardCardFiltersParams): DashboardCardFilterCompilationResult;
 export {};

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

@@ -3,6 +3,7 @@ import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
 import { CardConfig, PaginationConfig } from '../types/explorer-types.js';
 import { GlobalDateComparisonContext } from '../../shared/analytics-protocol/index.js';
 import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { CompiledCardQueryContext } from './build-card-query-context.js';
 export declare const isPaginatedCardType: (card: TCard) => boolean;
 export type CreateDashboardCardQueryKeyOptions = {
     finalFiltersKey: string;
@@ -36,4 +37,13 @@ export declare function createDashboardCardQueryIdentities(card: TCard, options:
     queryInputIdentity: string;
     paginationConfig: PaginationConfig | undefined;
 };
+/**
+ * The one identity for a compiled card context. Regular cards and the Matrix
+ * both use it, so a card's identity always covers what its request sends.
+ */
+export declare function createCompiledCardQueryIdentities(card: TCard, context: CompiledCardQueryContext, calendarContext: CalendarContext, identityOptions?: Parameters<typeof createDashboardCardQueryIdentities>[2]): {
+    queryKey: string[];
+    queryInputIdentity: string;
+    paginationConfig: PaginationConfig | undefined;
+};
 export declare function createDashboardCardQueryKey(card: TCard, options: CreateDashboardCardQueryKeyOptions): string[];

package/dist/types/lib/query-context/query-auth-scope.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The auth scope every card puts in its query identity: a stable hash of the
+ * access token, never the token itself. A new token is a new scope.
+ */
+export declare function hashTokenForQueryKey(accessToken?: string): string;