@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/types/modules/formula/integration/workbook-snapshot.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Workbook Snapshot — Immutable data layer for the formula engine.
+ *
+ * The snapshot captures all workbook state needed for formula compilation
+ * and evaluation as plain, read-only data structures. Runtime/compile code
+ * must depend only on these types — never on live Workbook/Worksheet/Cell
+ * objects.
+ *
+ * ## Design Principles
+ *
+ * 1. **Immutable** — all interfaces use `readonly` modifiers. The engine
+ *    must never mutate snapshot data.
+ * 2. **Self-contained** — every piece of information the engine needs
+ *    (cell values, formula text, table metadata, defined names, calc
+ *    properties) is captured up front.
+ * 3. **No @excel/ imports** — this file defines pure data types. The
+ *    concrete builder that populates these structures lives in
+ *    `workbook-adapter.ts` and is the only file that touches live objects.
+ */
+/**
+ * Error codes recognized by the formula engine.
+ * This is an engine-internal type that avoids importing from `@excel/types`.
+ */
+export type ErrorCode = "#N/A" | "#REF!" | "#NAME?" | "#DIV/0!" | "#NULL!" | "#VALUE!" | "#NUM!" | "#SPILL!" | "#CALC!";
+export interface SnapshotErrorValue {
+    readonly error: ErrorCode;
+}
+/**
+ * A cell's raw value as captured in the snapshot.
+ *
+ * - `Date` is NOT included — dates are stored as their Excel serial number.
+ *   The snapshot builder converts Date objects to serial numbers at capture
+ *   time so the engine never needs to reason about Date objects.
+ * - Rich text is flattened to a plain string.
+ */
+export type SnapshotCellValue = number | string | boolean | SnapshotErrorValue | null;
+/**
+ * The kind of formula a cell contains.
+ *
+ * - `"none"` — not a formula cell (literal value)
+ * - `"normal"` — ordinary formula
+ * - `"shared-master"` — master cell of a shared formula group
+ * - `"shared-slave"` — slave cell that inherits from a shared master
+ * - `"cse"` — legacy CSE (Ctrl+Shift+Enter) array formula
+ * - `"dynamic-array"` — Excel 365 dynamic array formula
+ */
+export type FormulaCellKind = "none" | "normal" | "shared-master" | "shared-slave" | "cse" | "dynamic-array";
+/**
+ * Snapshot of a single cell.
+ *
+ * Only cells that contain data or formulas are captured — truly empty
+ * positions are represented by the absence of a CellSnapshot in the
+ * worksheet's cell map.
+ */
+export interface CellSnapshot {
+    /** 1-based row number. */
+    readonly row: number;
+    /** 1-based column number. */
+    readonly col: number;
+    /** The cell's raw value (for non-formula cells) or cached result (for formula cells). */
+    readonly value: SnapshotCellValue;
+    /** The formula classification. */
+    readonly formulaKind: FormulaCellKind;
+    /**
+     * The formula source text.
+     * - For normal / shared-master / CSE / dynamic-array: the actual formula.
+     * - For shared-slave: the *translated* formula (already offset from master).
+     * - For non-formula cells: `undefined`.
+     */
+    readonly formula?: string;
+    /**
+     * For CSE and shared-master formulas: the target range in "A1:B2" format.
+     * Used by the materialize layer to determine where results are written.
+     */
+    readonly ref?: string;
+    /**
+     * Whether this is a dynamic array formula (explicit `isDynamicArray` flag
+     * from the XLSX model, or inferred from the top-level function name).
+     */
+    readonly isDynamicArray?: boolean;
+    /**
+     * The cached result from the XLSX file (before engine evaluation).
+     * Used by `shouldPreserveCachedResult` to avoid overwriting usable data
+     * when the engine returns #NAME? for an unsupported function.
+     */
+    readonly cachedResult?: SnapshotCellValue;
+}
+/**
+ * Snapshot of a single worksheet.
+ */
+export interface WorksheetSnapshot {
+    /** Stable worksheet identifier (survives renames). */
+    readonly id: number;
+    /** Worksheet name (used as the key for cross-sheet references). */
+    readonly name: string;
+    /**
+     * The used range of the worksheet. `null` if the sheet has no data.
+     * All values are 1-based.
+     */
+    readonly dimensions: {
+        readonly top: number;
+        readonly left: number;
+        readonly bottom: number;
+        readonly right: number;
+    } | null;
+    /**
+     * All cells with data, keyed by `"row:col"` (e.g. `"1:1"` for A1).
+     * Only non-empty cells are present.
+     */
+    readonly cells: ReadonlyMap<string, CellSnapshot>;
+    /**
+     * Rows that are hidden. Used by SUBTOTAL's 1xx-variant codes
+     * (101-111) and AGGREGATE option 5/7 to skip hidden rows during
+     * aggregation. Excel distinguishes filter-hidden vs manually hidden,
+     * but our worksheet model carries a single `row.hidden` boolean for
+     * either case — SUBTOTAL 1xx/AGGREGATE treat them identically anyway,
+     * and SUBTOTAL 9 (plain) always skips filter-hidden rows (not
+     * distinguishable here, so we conservatively treat them as visible).
+     * 1-based row numbers.
+     */
+    readonly hiddenRows: ReadonlySet<number>;
+    /** Tables defined in this worksheet. */
+    readonly tables: readonly TableSnapshot[];
+}
+/**
+ * Column definition within a table.
+ */
+export interface TableColumnSnapshot {
+    readonly name: string;
+}
+/**
+ * Snapshot of a table (ListObject) within a worksheet.
+ */
+export interface TableSnapshot {
+    /** The table name (used in structured references). */
+    readonly name: string;
+    /** Column definitions — order matches physical column order. */
+    readonly columns: readonly TableColumnSnapshot[];
+    /** Top-left corner of the table (1-based). */
+    readonly topLeft: {
+        readonly row: number;
+        readonly col: number;
+    };
+    /** Number of data rows (excludes header and totals). */
+    readonly dataRowCount: number;
+    /** Whether the table has a header row (default true). */
+    readonly hasHeaderRow: boolean;
+    /** Whether the table has a totals row. */
+    readonly hasTotalsRow: boolean;
+}
+/**
+ * A single defined name in the workbook.
+ *
+ * Defined names can reference:
+ * - A cell or range: `"Sheet1!$A$1:$B$2"`
+ * - A formula expression: `"LAMBDA(x,y,x+y)"`
+ * - Multiple areas (currently unsupported by the engine)
+ */
+export interface DefinedNameSnapshot {
+    /** The defined name (case-insensitive). */
+    readonly name: string;
+    /**
+     * The range strings associated with this name.
+     * Usually a single entry. Multi-area names (length > 1) are not supported
+     * by the engine and will produce #VALUE!.
+     */
+    readonly ranges: readonly string[];
+    /**
+     * The scope of this defined name.
+     * - `undefined` or empty string means workbook-scoped (global).
+     * - A sheet name means this name is local to that worksheet.
+     *
+     * Excel allows the same name to exist both as a workbook-scoped name
+     * and as a sheet-scoped name on specific worksheets. When a formula on
+     * Sheet1 references the name "Total", the engine first looks for a
+     * sheet-scoped name on Sheet1, then falls back to the workbook-scoped name.
+     */
+    readonly scope?: string;
+}
+/**
+ * Calculation settings from the workbook.
+ */
+export interface CalcPropertiesSnapshot {
+    /** Whether to perform a full calculation on load. */
+    readonly fullCalcOnLoad?: boolean;
+    /** Whether iterative calculation is enabled (for circular references). */
+    readonly iterate?: boolean;
+    /** Maximum number of iterations (default 100). */
+    readonly iterateCount?: number;
+    /** Maximum change threshold for convergence (default 0.001). */
+    readonly iterateDelta?: number;
+}
+/**
+ * Global workbook properties relevant to the formula engine.
+ */
+export interface WorkbookPropertiesSnapshot {
+    /** Whether the workbook uses the 1904 date system. */
+    readonly date1904?: boolean;
+}
+/**
+ * A table resolved with its containing worksheet name.
+ * Used by the `tablesByName` index for O(1) table lookup.
+ */
+export interface ResolvedTable {
+    readonly table: TableSnapshot;
+    readonly sheetName: string;
+}
+/**
+ * Complete, immutable snapshot of all workbook state needed by the formula
+ * engine. This is the sole input to the compile → evaluate → materialize
+ * pipeline.
+ */
+export interface WorkbookSnapshot {
+    /** All worksheets in workbook order. */
+    readonly worksheets: readonly WorksheetSnapshot[];
+    /** Quick lookup: worksheet name (lowercase) → WorksheetSnapshot. */
+    readonly worksheetsByName: ReadonlyMap<string, WorksheetSnapshot>;
+    /** Quick lookup: worksheet id → WorksheetSnapshot. */
+    readonly worksheetsById: ReadonlyMap<number, WorksheetSnapshot>;
+    /** All defined names in the workbook. Keyed by uppercase name for global
+     *  names, or `"SHEETNAME\0NAME"` for sheet-scoped names. Use the
+     *  `resolveDefinedNameKey()` helper to find the correct entry. */
+    readonly definedNames: ReadonlyMap<string, DefinedNameSnapshot>;
+    /**
+     * Quick lookup: table name (lowercase) → table + sheet info.
+     * Built at snapshot creation time to avoid O(sheets × tables) scans
+     * in the binder and evaluator.
+     */
+    readonly tablesByName: ReadonlyMap<string, ResolvedTable>;
+    /** Calculation properties (iterative calc settings, etc.). */
+    readonly calcProperties: CalcPropertiesSnapshot;
+    /** Global workbook properties. */
+    readonly properties: WorkbookPropertiesSnapshot;
+}
+/**
+ * Build a snapshot cell key from row and column.
+ * This key format is used for the `WorksheetSnapshot.cells` map.
+ */
+export declare function snapshotCellKey(row: number, col: number): string;
+/**
+ * Build a formula cell key that includes the sheet name.
+ * Used by the dependency graph and eval session cache.
+ */
+export declare function formulaCellKey(sheet: string, row: number, col: number): string;
+/**
+ * Build a spill cell key using the worksheet id (stable across renames).
+ * Used by the spill engine for persistent tracking.
+ */
+export declare function spillCellKeyFromId(worksheetId: number, row: number, col: number): string;
+/**
+ * Build the key used to store a sheet-scoped defined name.
+ * Format: `"SHEETNAME\0NAME"` (null character separator ensures no collisions).
+ */
+export declare function scopedNameKey(sheetName: string, name: string): string;
+/**
+ * Resolve a defined name considering scope precedence.
+ *
+ * Excel name resolution order:
+ * 1. Sheet-scoped name on `currentSheet` (if any)
+ * 2. Workbook-scoped (global) name
+ *
+ * @param definedNames - The defined names map from the snapshot
+ * @param name - The name to resolve (case-insensitive)
+ * @param currentSheet - The sheet where the formula is located
+ * @returns The matching DefinedNameSnapshot, or undefined
+ */
+export declare function resolveDefinedName(definedNames: ReadonlyMap<string, DefinedNameSnapshot>, name: string, currentSheet?: string): DefinedNameSnapshot | undefined;

package/dist/types/modules/formula/materialize/build-writeback-plan.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Build Writeback Plan — Convert evaluation results into a WritebackPlan.
+ *
+ * This module takes the evaluation results from the evaluator and
+ * produces a declarative `WritebackPlan` that describes all cell mutations.
+ * The plan is then applied by `apply-writeback-plan.ts`.
+ *
+ * ## Responsibilities
+ *
+ * 1. Classify each formula's result as scalar, CSE, or dynamic-array.
+ * 2. Check spill availability and detect #SPILL! conflicts.
+ * 3. Generate cleanup operations for stale ghost cells.
+ * 4. Track spill regions and ghost snapshots for persistence.
+ *
+ * ## Key Principle
+ *
+ * This module does NOT touch any live workbook objects. It reads only
+ * from the `WorkbookSnapshot` and the evaluation results.
+ */
+import type { CompiledFormula } from "../compile/compiled-formula.js";
+import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { RuntimeValue } from "../runtime/values.js";
+import type { SpillRegion } from "./types.js";
+import type { WritebackPlan } from "./writeback-plan.js";
+/**
+ * Build a complete `WritebackPlan` from evaluation results.
+ *
+ * @param snapshot - The workbook snapshot
+ * @param compiled - All compiled formulas in evaluation order
+ * @param results - Raw evaluation results, keyed by formula cell key
+ * @param previousSpills - Persistent spill regions from previous calculation
+ * @param previousGhosts - Persistent ghost snapshots from previous calculation
+ */
+export declare function buildWritebackPlan(snapshot: WorkbookSnapshot, compiled: readonly CompiledFormula[], results: ReadonlyMap<string, RuntimeValue>, previousSpills: ReadonlyMap<string, SpillRegion>, previousGhosts: ReadonlyMap<string, unknown>): WritebackPlan;

package/dist/types/modules/formula/materialize/spill-engine.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Spill Engine — Persistent state management for dynamic array formulas.
+ *
+ * Manages persistent spill metadata that survives across
+ * `calculateFormulas()` invocations.
+ */
+import type { SpillRegion, WorkbookLike } from "./types.js";
+export declare function getPersistentSpillMap(workbook: WorkbookLike): Map<string, SpillRegion>;
+export declare function getGhostSnapshots(workbook: WorkbookLike): Map<string, unknown>;

package/dist/types/modules/formula/materialize/types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Structural interfaces the formula engine consumes.
+ *
+ * The engine talks to these interfaces only — never to the concrete
+ * `Workbook` / `Worksheet` / `Cell` classes from the `excel` module. Any
+ * host that wants to drive the engine (including the Node/browser
+ * Workbook in `@excel/*`) must implement these shapes.
+ *
+ * This is what keeps the Layer 3 ↔ Layer 4 dependency one-way: the
+ * `excel` module imports from `formula`, never the reverse.
+ */
+/**
+ * Excel-style error value carried inside a cell.
+ *
+ * Mirrors `CellErrorValue` in `@excel/types` so hosts can pass their
+ * concrete error objects straight through.
+ */
+export interface CellErrorValueLike {
+    error: string;
+}
+/**
+ * The value the engine writes back as `cell.result` for formula cells.
+ */
+export type FormulaResultLike = number | string | boolean | Date | CellErrorValueLike | undefined;
+/**
+ * Numeric cell-type tag exposed by host cells. The engine only compares
+ * against `Null` and `Formula`; any other value is treated as a scalar
+ * literal.
+ *
+ * Kept as inline numeric literals (not an enum) so this file stays free
+ * of runtime dependencies. The `const` object and `type` alias share a
+ * name via TypeScript's declaration merging — the value form
+ * (`CellValueTypeLike.Null`, `CellValueTypeLike.Formula`) is used at
+ * comparison sites, the type form annotates `CellLike.type`.
+ */
+export declare const CellValueTypeLike: {
+    readonly Null: 0;
+    readonly Formula: 6;
+};
+export type CellValueTypeLike = number;
+/**
+ * The portion of a cell's persisted `model` the engine inspects for
+ * classifying a formula (shared / CSE / dynamic array, etc.).
+ */
+export interface CellModelLike {
+    readonly shareType?: string;
+    readonly ref?: string;
+    readonly formula?: string;
+    readonly sharedFormula?: string;
+    readonly isDynamicArray?: boolean;
+}
+/**
+ * Minimal cell surface consumed by the engine. A host cell must allow
+ * both reading (for snapshot) and mutation (for writeback).
+ */
+export interface CellLike {
+    readonly row: number;
+    readonly col: number;
+    readonly type: CellValueTypeLike;
+    readonly formula?: string;
+    readonly model: CellModelLike;
+    /**
+     * Host cells can carry any representation (hyperlinks, rich text,
+     * checkboxes, dates, scalars, errors, …). The engine narrows to plain
+     * scalars internally during snapshot construction, so this is typed
+     * as `unknown` to stay structurally compatible with any host shape.
+     */
+    value: unknown;
+    result: FormulaResultLike;
+}
+export interface RowLike {
+    readonly hidden?: boolean;
+    /**
+     * Excel's `eachCell` accepts either a bare callback or options + callback.
+     */
+    eachCell(callback: (cell: CellLike, colNumber: number) => void): void;
+    eachCell(opts: {
+        includeEmpty?: boolean;
+    }, callback: (cell: CellLike, colNumber: number) => void): void;
+}
+export interface DimensionsLike {
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+export interface TableColumnLike {
+    readonly name: string;
+}
+export interface TableDefinitionLike {
+    readonly name?: string;
+    readonly displayName?: string;
+    readonly tl?: {
+        readonly row: number;
+        readonly col: number;
+    };
+    readonly columns?: readonly TableColumnLike[];
+    readonly rows?: readonly unknown[];
+    readonly headerRow?: boolean;
+    readonly totalsRow?: boolean;
+}
+export interface TableRefLike {
+    readonly table?: TableDefinitionLike;
+}
+export interface WorksheetLike {
+    readonly id: number;
+    readonly name: string;
+    readonly dimensions: DimensionsLike | null;
+    /**
+     * Excel's `eachRow` accepts either a bare callback or an options bag
+     * followed by a callback. Mirror both signatures so concrete
+     * `Worksheet` classes remain structurally assignable.
+     */
+    eachRow(callback: (row: RowLike, rowNumber: number) => void): void;
+    eachRow(opts: {
+        includeEmpty?: boolean;
+    }, callback: (row: RowLike, rowNumber: number) => void): void;
+    findCell(row: number, col: number): CellLike | undefined;
+    getCell(row: number, col: number): CellLike;
+    getTables?(): TableRefLike[];
+}
+/**
+ * A complete defined name entry with all details.
+ */
+export interface DefinedNameEntry {
+    name: string;
+    ranges: string[];
+    localSheetId?: number;
+    formulaExpression?: string;
+}
+export interface DefinedNamesLike {
+    /**
+     * Return all defined name entries with full details.
+     * Each entry is self-contained — no second lookup needed.
+     * Same bare name may appear multiple times with different scopes.
+     */
+    getAllEntries(): DefinedNameEntry[];
+    /** Enumerate name+scope pairs (lightweight). */
+    getAllNames(): {
+        name: string;
+        localSheetId?: number;
+    }[];
+}
+export interface WorkbookLike {
+    worksheets: WorksheetLike[];
+    getWorksheet(id?: number | string): WorksheetLike | undefined;
+    definedNames?: DefinedNamesLike;
+    /** Calculation properties — used for iterative calculation settings. */
+    calcProperties?: {
+        fullCalcOnLoad?: boolean;
+        /** Enable iterative calculation for circular references. */
+        iterate?: boolean;
+        /** Maximum number of iterations (default 100). */
+        iterateCount?: number;
+        /** Maximum change threshold for convergence (default 0.001). */
+        iterateDelta?: number;
+    };
+    /** Workbook properties including date system. */
+    properties?: {
+        date1904?: boolean;
+    };
+}
+/**
+ * Tracks a spill region: the source formula cell and the range of cells it
+ * has spilled into. Used for cleanup when a formula is re-evaluated with
+ * different-sized results.
+ */
+export interface SpillRegion {
+    /** The worksheet id — stable across renames */
+    readonly worksheetId: number;
+    /** The source formula cell's row */
+    readonly sourceRow: number;
+    /** The source formula cell's col */
+    readonly sourceCol: number;
+    /** Number of rows in the spill (including source) */
+    readonly rows: number;
+    /** Number of cols in the spill (including source) */
+    readonly cols: number;
+}

package/dist/types/modules/formula/materialize/writeback-plan.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Writeback Plan — Declarative description of formula calculation results.
+ *
+ * The engine never directly mutates workbook cells. Instead, it produces a
+ * `WritebackPlan` — a list of write operations that describe what values
+ * should be written where. A thin adapter layer then applies the plan to
+ * the live workbook.
+ *
+ * ## Design Principles
+ *
+ * 1. **Declarative** — the plan describes *what* to write, not *how*.
+ * 2. **Deterministic** — #SPILL! conflicts are detected during plan
+ *    construction, not during application.
+ * 3. **Ordered** — operations are applied in the order they appear.
+ * 4. **Independent** — each operation stands alone; the adapter does not
+ *    need engine internals to apply the plan.
+ *
+ * ## Operation Types
+ *
+ * - `ScalarWrite` — write a single value to a formula cell's result.
+ * - `CSEWrite` — distribute an array across a CSE formula's target range.
+ * - `SpillWrite` — write a dynamic array result to adjacent cells (spill).
+ * - `SpillErrorWrite` — write #SPILL! to the source cell (conflict detected).
+ * - `CleanupWrite` — clear stale ghost cells from a previous spill.
+ * - `PreserveWrite` — keep the cell's existing cached result (unsupported fn).
+ */
+import type { SnapshotCellValue } from "../integration/workbook-snapshot.js";
+import type { SpillRegion } from "./types.js";
+/**
+ * Write a scalar value to a formula cell's result.
+ */
+export interface ScalarWrite {
+    readonly type: "scalar";
+    readonly sheetName: string;
+    readonly row: number;
+    readonly col: number;
+    /** The computed result value. */
+    readonly value: SnapshotCellValue;
+}
+/**
+ * Distribute an array result across a CSE (Ctrl+Shift+Enter) formula's
+ * target range. Each cell in the range gets the corresponding element.
+ * If the result is smaller than the target range, excess cells receive
+ * the scalar value (or `null` for missing elements).
+ */
+export interface CSEWrite {
+    readonly type: "cse";
+    readonly sheetName: string;
+    /** Top-left corner of the target range. */
+    readonly top: number;
+    readonly left: number;
+    /** Bottom-right corner of the target range. */
+    readonly bottom: number;
+    readonly right: number;
+    /**
+     * The result array. `results[r][c]` is the value for row `top + r`,
+     * col `left + c`. May be smaller than the target range.
+     */
+    readonly results: readonly (readonly SnapshotCellValue[])[];
+    /**
+     * For scalar CSE results: the single value to fill the entire range.
+     * When set, `results` is ignored.
+     */
+    readonly scalarFill?: SnapshotCellValue;
+}
+/**
+ * Write a dynamic array result to the source cell and adjacent ghost cells.
+ * The spill region starts at (row, col) and extends downward/rightward.
+ */
+export interface SpillWrite {
+    readonly type: "spill";
+    readonly sheetName: string;
+    readonly sheetId: number;
+    /** Source formula cell position. */
+    readonly row: number;
+    readonly col: number;
+    /**
+     * The result array. `results[r][c]` is the value for row `row + r`,
+     * col `col + c`. The source cell gets `results[0][0]`.
+     */
+    readonly results: readonly (readonly SnapshotCellValue[])[];
+}
+/**
+ * Write #SPILL! to the source cell because the target range is occupied.
+ */
+export interface SpillErrorWrite {
+    readonly type: "spill-error";
+    readonly sheetName: string;
+    readonly sheetId: number;
+    readonly row: number;
+    readonly col: number;
+}
+/**
+ * Clear ghost cells from a previous spill that is no longer valid.
+ * Each entry in `cells` is a (row, col) pair to clear.
+ */
+export interface CleanupWrite {
+    readonly type: "cleanup";
+    readonly sheetName: string;
+    readonly sheetId: number;
+    /**
+     * Cells to clear. Each is `{ row, col }`.
+     * Only cells that haven't been modified by the user should be cleared —
+     * the plan builder checks this against the snapshot.
+     */
+    readonly cells: readonly {
+        readonly row: number;
+        readonly col: number;
+    }[];
+}
+/**
+ * Keep the cell's existing cached result.
+ * Used when the engine returns #NAME? (unsupported function) but the cell
+ * has a usable cached result from the XLSX file.
+ */
+export interface PreserveWrite {
+    readonly type: "preserve";
+    readonly sheetName: string;
+    readonly row: number;
+    readonly col: number;
+}
+/**
+ * A single write operation in the plan.
+ */
+export type WriteOperation = ScalarWrite | CSEWrite | SpillWrite | SpillErrorWrite | CleanupWrite | PreserveWrite;
+/**
+ * The complete writeback plan produced by the engine.
+ *
+ * Operations are ordered: cleanups first, then writes, to ensure stale
+ * data is removed before new data is written.
+ */
+export interface WritebackPlan {
+    /**
+     * All write operations in application order.
+     * The adapter should apply them sequentially.
+     */
+    readonly operations: readonly WriteOperation[];
+    /**
+     * Spill persistent state changes — spill regions and ghost cell snapshots
+     * that the adapter must update in the persistent tracking maps.
+     */
+    readonly spillState: SpillStateDelta;
+}
+/**
+ * Describes changes to the persistent spill tracking state.
+ * The adapter updates the persistent maps accordingly.
+ */
+export interface SpillStateDelta {
+    /**
+     * New or updated spill region metadata.
+     * Key: `"ws:<id>!row:col"` of the source formula cell.
+     * Value: the spill region dimensions.
+     */
+    readonly spillRegions: ReadonlyMap<string, SpillRegion>;
+    /**
+     * Ghost cell value snapshots for modification detection.
+     * Key: ghost cell key `"ws:<id>!row:col"`.
+     * Value: the raw value written to that ghost cell.
+     */
+    readonly ghostSnapshots: ReadonlyMap<string, SnapshotCellValue>;
+    /**
+     * Spill region entries to remove from the persistent map.
+     * These are source cell keys whose formulas no longer exist or whose
+     * spill was replaced.
+     */
+    readonly removedSpillKeys: readonly string[];
+}