@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.2

package/types/src/calculation/Calculation.d.ts

@@ -1,25 +1,59 @@
 import { IRange, IFormulaContext, IRuntime, Scalar } from '@sheetxl/primitives';
+import { IListener } from '../listener';
 import { FunctionProvider } from '@sheetxl/scripting';
 import { AbstractModel, IModel } from '../model';
+import { ITransaction } from '../transaction';
 import { IStringCollection } from '../string';
 import { IFunctionCollection } from '../scripting';
 import { ISpatialMap, ISpatialMap3D } from '../collections';
 import { INamed, INamedCollection } from '../named';
 import { ICellRange, ICellRanges } from '../cellRange';
-import { _NamedGraphNode } from '../cellRange/_GraphNode';
-import { FormulaBlockResolvers } from './formula';
+import { NamedNodeInfo } from './Types';
+import { ITable } from '../table';
+import { IExternalBook, IExternalBookCollection } from '../externalBook';
+import { ExternalBookCollection } from '../externalBook/ExternalBookCollection';
+import { ExternalBookBindings } from './ExternalBookBindings';
+import { FormulaBlockResolvers, FormulaImager } from './formula';
 import { IFormulaCompiler } from './compiler';
 import { CalculationContext, IContextContainer, CalcNode } from './state';
 import { FormulaSpatialValue, PrecedentSpatialValue } from './spatial';
-import { CalcGrid, ICalcGrid } from './grid';
+import { CalcGridBackend, CalcGrid, FormulaHost, ICalcGrid } from './grid';
+import { CalcRequest, CalcResponse, CalcGridSpec, TableSymbols, NameSymbols } from './grid/_CalcRequest';
 import { CalcExecutor } from './executor';
+import { IndirectSymbolProvider, ISymbolRegistry } from './symbol';
 import { ICalculation } from './ICalculation';
 import { NamedFormulaCollection } from './NamedFormulaCollection';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
+/**
+ * What a structured reference resolves against: a live table, or a snapshot of one taken before it
+ * was removed ({@link snapshotTableExtent}).
+ */
+interface TableExtent {
+    getRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getDataRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getHeaderRowRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getTotalRowRange(): {
+        getCoords(): IRange.Coords;
+    };
+    isShowHeaders(): boolean;
+    isShowTotals(): boolean;
+    getColumnById(id: string): {
+        getIndex(): number;
+    } | null;
+    getSheet(): {
+        getId(): string;
+    } | null | undefined;
+}
 /**
  * Implementation for {@link ICalculation}.
  */
-export declare class Calculation extends AbstractModel<State, ICalculation.JSON, CommitView, ICalculation.IListeners> implements ICalculation {
+export declare class Calculation extends AbstractModel<State, ICalculation.JSON, ICalculation.IListeners> implements ICalculation {
     protected _container: IContextContainer;
     protected _context: CalculationContext & IFormulaContext;
     protected _status: ICalculation.Status;
@@ -27,11 +61,15 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     protected _runtime: IRuntime;
     protected _functions: IFunctionCollection;
     protected _namedFormulas: NamedFormulaCollection;
+    protected _externalBooks: ExternalBookCollection;
+    /** The cache as grids and the cached names as virtual grids — see {@link ExternalBookBindings}. */
+    protected _externalBindings: ExternalBookBindings | null;
     /** `json.names` held from construction until {@link hydrateNames} — see it for why. */
     protected _pendingNames: INamed.JSON[] | null;
     protected _compiler: IFormulaCompiler;
     protected _compilerEditing: IFormulaCompiler;
     protected _compilerEditingSig: string;
+    protected _compilerEditingStorage: IFormulaCompiler | null;
     protected _compilerModule: typeof import('./compiler/FormulaCompiler');
     protected _getActiveCell: () => IRange.CellCoords | null;
     protected _getRange: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
@@ -44,17 +82,54 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     protected _epochSeenPrecedents: ISpatialMap3D<PrecedentSpatialValue> | null;
     protected _epochSeenDynamics: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]> | null;
     protected _volatiles: Set<CalcNode>;
+    /** The current handle of every formula host's grid, by grid id. */
+    protected _formulaHosts: Map<string, FormulaHost>;
     protected _calculatedCommitId: string | null;
+    protected _calculatedEngineId: string | null;
+    protected _modelStore: ITransaction.IStore | null;
+    /** The model-side grids, by grid id (DESIGN-CALC-SERVICE §13.23): what a copy lands on, what a start seeds from. */
+    protected readonly _fronts: Map<string, CalcGrid>;
+    /** What each model grid is, for the `create` a start sends for it (its size is read then). */
+    protected readonly _gridSpecs: Map<string, Omit<CalcGridSpec, 'name' | 'entireCoords'>>;
+    /** The engine holds grids: from a start's boot until a stop. */
+    protected _engineUp: boolean;
+    protected _modelStoreRemoveListener: IListener.Remove | null;
+    protected _mirrorRemoveListener: IListener.Remove | null;
+    _modelMirrorId: string | null;
+    protected _engineIds: Map<string, string>;
+    protected _landingOf: Map<string, string>;
+    protected _mirroredId: string | null;
+    protected _lastRevert: {
+        commitId: string;
+        regions: Map<string, IRange.Coords[]>;
+    } | null;
+    protected _outstanding: Set<Promise<ICalcGrid.Results>> | null;
     protected _pendingActions: (() => Promise<unknown>)[] | null;
     protected _pendingPriority: (() => Promise<unknown>)[] | null;
     protected _draining: boolean;
+    protected _drainDepth: number;
     protected _drainScheduled: boolean;
     protected _calcOwed: boolean;
+    protected _calcOwedBy: string | null;
+    protected _channel: HeldRequest[] | null;
+    protected _bootPending: Promise<void> | null;
+    /** Passes running now: see {@link _calculateNow}. */
+    protected _passesInFlight: number;
+    /** The calculation state last announced (`onCalculationStateChange`). */
+    protected _calculationState: ICalculation.CalculationState;
+    /** A check of the calculation state is posted: see {@link _noteCalculationState}. */
+    protected _calculationStatePosted: boolean;
+    /** `ready()` calls waiting for work in flight to end: woken on every check. */
+    protected _calculationStateWaiters: (() => void)[] | null;
+    protected _bootFull: boolean;
+    protected _bootExplicit: boolean;
+    protected _compilerWaiters: (() => void)[] | null;
+    protected _wroteWhileOff: boolean;
     /** {@link ICalculation.getCalculationMode} — gates the reactive pass in {@link _calculate}. */
     protected _calcMode: ICalculation.CalculationMode;
     /** {@link ICalculation.getIterativeCalculation} — handed to the executor per pass. */
     protected _iterate: boolean;
-    protected _maxIterations: number;
+    protected _maxIteration: number;
     protected _maxIterateChange: number;
     /** The `calcPr` the file carried, kept whole so settings this engine ignores still round-trip. */
     protected _calcJSON: ICalculation.JSON | null;
@@ -66,6 +141,9 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * Populated from {@link Calculation.ConstructorOptions} during `_initialize`.
      */
     protected _resolvers: FormulaBlockResolvers | null;
+    /** Tables as symbols: a table's stable id, which is what a structured reference stores. */
+    protected _tableSymbols: IndirectSymbolProvider<INamed<ITable>> | null;
+    protected _nameSymbols: IndirectSymbolProvider<ICalculation.INamedFormula> | null;
     constructor(options?: Calculation.ConstructorOptions);
     protected _initialize(options?: Calculation.ConstructorOptions): void;
     /**
@@ -89,19 +167,137 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * @returns `true` if any formula was marked dirty.
      */
     protected _markDirtyReferencing(changedIds: Set<string>): boolean;
+    /**
+     * Recompiles every formula that references any of `changedIds` — a name or a table, directly or
+     * through a name — from its own text, so it re-derives its precedents.
+     *
+     * @remarks
+     * The re-wire half of {@link _markDirtyReferencing}. A node stores the coords its references
+     * resolved to when it was wired, and `precedentSpatial` indexes those, so a symbol that now
+     * designates different cells (a name redefined, a table resized) leaves its readers evaluating
+     * against the old edges; a dirty mark does not reach them. Same `all3D` scan and the same
+     * {@link _namedTargets} expansion: a name whose body cites the symbol reaches its own readers.
+     *
+     * Run at a safe point only — it writes inputs.
+     */
+    protected _recompileReferencing(changedIds: Set<string>): void;
+    /**
+     * @internal
+     * Rewrites the formulas that reference `table`, which is about to be removed: `'error'` puts
+     * `#REF!` in place of each reference (a delete), `'address'` the absolute range it designated
+     * (a convert to range).
+     *
+     * @remarks
+     * Called while the table still exists: its id and its extent are read now, and the rewrite runs at
+     * the next safe point. A defined name whose body cites the table is not rewritten; it evaluates
+     * `#REF!` once the table is gone.
+     */
+    _releaseTableReferences(table: ITable, release: 'error' | 'address'): void;
+    /**
+     * @internal
+     * A table's body has changed rows: re-fit the A1 references that spanned it.
+     *
+     * @remarks
+     * Excel treats a reference whose ROWS are exactly a table's body - or run from its header to the
+     * body's end - as naming the body, whatever columns of the table it covers, and keeps it on the
+     * body however the body's rows change (probed, `probe-table-refit.ps1`): `SUM(B2:B5)` over body
+     * rows 2-5 reads `SUM(B2:B6)` after a row is appended, and `SUM(B2:B3)` after a resize gives two
+     * up. Relative, absolute or mixed alike, from any sheet, and in anything that holds a reference -
+     * a defined name, a table's held totals formula and a condition's formula are blocks too. A
+     * reference that only starts or only ends with the body is an ordinary one, and a change of
+     * COLUMNS re-fits nothing. A name's relative rows are read from its body's origin, A1, as Excel
+     * reads them (`probe-table-refit-relative.ps1`); a shift never moves them, so a row at the top
+     * leaves such a name alone.
+     *
+     * An insert or delete inside the body already leaves such a reference right, so this is asked
+     * only for what a shift gets wrong: rows taken or given up at the body's end, and a row inserted
+     * at its first row (which pushes the whole reference down).
+     *
+     * One search of the precedent index over the rows that match - an entry per (block, reference)
+     * that reads them - so the cost is the readers of the body, on a change of a table's rows. The
+     * text a cell shows catches up with the engine the way it does after any shift.
+     *
+     * A block is re-fitted cell by cell: only the cells whose reference spans the body are rewritten,
+     * which splits them out of the block. An array-entered block is one formula, read at its top-left,
+     * and is never split.
+     *
+     * **A DELIBERATE DIVERGENCE lives here** (Michael, 2026-09-22). Excel asks how the cell was
+     * authored, not what it reads: a fully relative reference is left where it is when the cell
+     * belongs to a shared-formula group, and re-fitted when it stands alone - so `SUM(B2:B5)` follows
+     * the body when it was typed and does not when the same three formulas were filled, and the file
+     * carries the difference as `<f t="shared">` (`probe-table-refit-fillhandle.ps1`,
+     * `probe-table-refit-roundtrip.ps1`). Here a run is a data-model fact, not an authoring one -
+     * cells holding the same formula are conflated whatever made them - so honoring that rule would
+     * make a formula follow the body or not depending on what a NEIGHBOR happens to hold, which a
+     * user cannot see. Every reference that spans the body is re-fitted, however it was written.
+     *
+     * @param sheet The sheet the table is on, by id or name.
+     * @param columns The table's columns. A reference reaching outside them is an ordinary one.
+     * @param match The rows a reference has to span to be one of the body's, as they read NOW.
+     * @param headerRow The header's row when a reference from it to `match.rowEnd` also counts.
+     * @param to The body's rows now.
+     * @param afterShift The rows to match are where a shift THIS edit makes will have put them - a
+     * row inserted at the body's first row. The table hears of a shift before the engine has made it,
+     * so this waits for the next safe point.
+     * @param isCurrent Whether the table is still as this change left it.
+     */
+    _refitTableRows(sheet: string, columns: {
+        colStart: number;
+        colEnd: number;
+    }, match: {
+        rowStart: number;
+        rowEnd: number;
+    }, headerRow: number | null, to: {
+        rowStart: number;
+        rowEnd: number;
+    }, afterShift: boolean, isCurrent: () => boolean): void;
+    /**
+     * Replaces every structured reference to `tableId` on a sheet: by its address in `extent`, or by
+     * `#REF!` when there is none.
+     */
+    protected _rewriteTableReferences(tableId: string, extent: TableExtent | null): void;
+    /**
+     * Writes `text` over `fsv`'s cells - or over `coords`, a part of them - as the engine's own input.
+     * Safe point only.
+     */
+    protected _writeBlockText(fsv: FormulaSpatialValue, text: string, coords?: IRange.Coords): void;
+    /**
+     * @internal
+     * Rewrites the 3-D spans that a tab-order change from `before` to `after` broke — an endpoint that
+     * `movedId` carried across the other — to their inward neighbor. Called inside the move's commit,
+     * so an undo of the move restores the text.
+     */
+    _replaceSheetSpans(before: readonly string[], after: readonly string[], movedId?: string): void;
     /**
      * {@inheritDoc IContextContainer.getNamedDependents}
      *
      * @remarks
+     * The bucket for a NAME out of {@link _getSymbolDependents}. Kept as the name-flavored spelling
+     * the callers read; the index underneath is one index for every symbol kind.
+     */
+    protected _getNamedDependents(nameId: string): readonly IRange.Coords[];
+    /**
+     * Every formula block that references a symbol — a defined name, a table, or an external BOOK —
+     * by its stable id, as `{ ...ref, scope: gridId }` coords.
+     *
+     * @remarks
      * The memo is keyed on the formula spatial's IDENTITY, which is the whole invalidation story:
      * the map is copy-on-write (`getFormulas().clone()` before any mutation, `setFormulas` to
      * publish), so a formula added, removed, shifted or recompiled necessarily replaces it — and an
      * undo, which restores an earlier map, replaces it too. Nothing has to remember to clear this.
      *
      * The sweep is the same `all3D` walk `recompileNamed` and {@link _markDirtyReferencing} already
-     * do, done once for every name instead of once per name.
+     * do, done once for every symbol instead of once per symbol. Bucketed off
+     * `getReferencedSymbolIds()` — names, tables and books alike — so a book's dependents
+     * (`IExternalBook.getDependents`) come out of the same walk as a name's, and a name's body that
+     * cites a book lands in the book's bucket with the name's id as its scope.
      */
-    protected _getNamedDependents(nameId: string): readonly IRange.Coords[];
+    protected _getSymbolDependents(symbolId: string): readonly IRange.Coords[];
+    /**
+     * Every symbol id a formula cites, to the blocks citing it — the index
+     * {@link _getSymbolDependents} answers from, memoized the same way.
+     */
+    protected _getSymbolIndex(): ReadonlyMap<string, readonly IRange.Coords[]>;
     /**
      * {@inheritDoc IContextContainer.getNamedDependentNames}
      *
@@ -126,6 +322,20 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * one naming the changed name directly. Ids that are not names (a table's) expand to themselves.
      */
     protected _namedTargets(changedIds: Set<string>): ReadonlySet<string>;
+    /**
+     * @internal
+     * Demand/plan counters and timings since construction (or the last {@link _resetStats}) — the
+     * plan-cache soak rig. From a console: `SheetXL.getSelectedWorkbook().getCalculation()._stats()`.
+     */
+    _stats(): ReturnType<CalcExecutor['getDemandStats']>;
+    /** @internal Zeroes every counter/timing so a measurement window starts clean. */
+    _resetStats(): void;
+    /**
+     * @internal
+     * Read (no argument) or set the plan-cache mode: `'on'` | `'assert'` | `'off'`. `'assert'` is the
+     * diagnostic to flip to if values ever look stale — see `CalcExecutor.planCacheMode`.
+     */
+    _planCacheMode(mode?: 'off' | 'assert' | 'on'): 'off' | 'assert' | 'on';
     /** @inheritdoc ICalculation.start */
     start(): Promise<void>;
     /**
@@ -137,7 +347,7 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      *
      * - `Starting` — held for `start()`'s drain, which always follows and loops until empty.
      * - Inside a drain — picked up by the loop already running.
-     * - `Ready` and settled — a microtask drain is posted (see {@link _scheduleDrain}).
+     * - `Running` and settled — a microtask drain is posted (see {@link _scheduleDrain}).
      *
      * That last case is why this is no longer called `whenStarting`. It only ever handled work that
      * arrived while starting: queuing scheduled nothing, and the array was pumped as a side effect of
@@ -151,13 +361,65 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * only inside a calculation. The drain is a safe point, not a synchronization point.
      */
     _whenSafe(action: () => Promise<unknown>, priority?: boolean): void;
+    /**
+     * Sends a grid request through the channel (DESIGN-CALC-SERVICE §4): applied now on a `Running`
+     * engine, held in send order while `Starting`, and neither recorded nor sent on an `Off` one -
+     * the caller's own view is the truth there, and a start is seeded from it.
+     */
+    protected _sendRequest(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
+    protected _sendRequestNow(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<CalcResponse>;
+    /** Re-judges every held request: `dead` is what `isDead` answers for it now. */
+    protected _markHeld(isDead: (held: HeldRequest) => boolean): void;
+    /**
+     * A start that did not complete: what the channel held is resolved with nothing (the model
+     * keeps every write, and the next start is seeded from it), and whoever waited for the
+     * compiler is released.
+     */
+    protected _abandonStart(): void;
+    protected _releaseCompilerWaiters(): void;
+    /**
+     * @internal
+     * Resolves once the engine can compile: at once when `Running`; when the batch has applied the
+     * seeds, ahead of the boot pass, while `Starting`; after the start it makes when `Off`.
+     *
+     * @remarks
+     * What an owner that registers a formula asynchronously waits on (a condition formula's
+     * evaluation). Waiting on {@link ready} instead resolves after the boot pass, and the
+     * registration then costs a pass of its own (design §6.5: a boot owes one).
+     */
+    _whenCanCompile(): Promise<void>;
+    /**
+     * The start batch (DESIGN-CALC-SERVICE §6.3), in the order the service owns: service-level
+     * content first (the names, wired from the priority queue), then the channel in send order
+     * (every seed and every request made while the engine was coming up), then the owners that
+     * hold a formula of their own (a host whose grid lost its body writes it again; a watch held for
+     * the engine registers inside `onReady`), then the one pass the boot owes.
+     *
+     * @remarks
+     * `isLoading()` holds for the whole batch, so a grid seeded here owes its pass rather than
+     * running one against siblings not yet seeded. The pass itself runs on a task of its own
+     * ({@link _runBoot}): a consumer whose registration chains through promises resolved here (a
+     * data validation's, a conditional format's) lands ahead of it, and N of them cost one pass.
+     *
+     * A held request lands under the engine's current commit: the snapshot it named has been
+     * mirrored already, so its writes belong to the tip, and the maps are versioned under that key.
+     * One whose snapshot the model has undone since is skipped.
+     */
+    protected _boot(): Promise<void>;
+    /**
+     * Posts the boot pass on a task of its own, and answers the promise `start()`, `ready()` and a
+     * `calculate()` made meanwhile wait on. One at a time.
+     */
+    protected _scheduleBoot(): Promise<void>;
+    /** The boot pass: what the batch, and the consumers that registered since, owe - once. */
+    protected _runBoot(): Promise<void>;
     /**
      * Posts a microtask drain, if one is not already coming.
      *
      * @remarks
      * A no-op in the two cases where a drain is already guaranteed to reach this action:
      *
-     * - not `Ready` — `start()` drains at the tail of its transition, and does so inline so
+     * - not `Running` — `start()` drains at the tail of its transition, and does so inline so
      *   `await start()` covers the queued work. Posting here would race that.
      * - already draining — `_drainPending` loops until the queue is empty, so an action appended
      *   during a drain is picked up by the pass in flight.
@@ -186,8 +448,23 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * This is deliberately not folded into {@link _drainPending}. The other three sites would then
      * calculate twice, and `start()` would calculate mid-load — which is the thing `isLoading()`
      * exists to prevent.
+     *
+     * The pass is reactive whether or not a grid owed it, so manual mode holds it for `calculate()`.
+     * That includes the load: a manual-mode file opens with no pass, as Excel's does — its `ca`
+     * cells and value-less formulas stay dirty (`isCalculationRequired()`) until asked. A file whose
+     * `calcId` says it needs recalculating still gets one; that is the explicit full pass of
+     * `calcOnLoad: 'full'`.
      */
     protected _drainStandalone(): Promise<void>;
+    /**
+     * Owe a reactive pass for `gridId`, to run once the current flush is over.
+     *
+     * @remarks
+     * The posted form of `calculateGrid`: the drain scheduler already coalesces everything owed at
+     * the end of a flush into one pass, and this is how a consumer asks for that pass without
+     * running one itself. See {@link IContextContainer.requestCalculateGrid}.
+     */
+    protected _owePass(gridId: string): void;
     /**
      * Runs queued actions until the queue is empty. The one drain, used by every site that drains.
      *
@@ -204,8 +481,8 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * shape, and got away with it only because it goes on to call `grid.calculate()` per dirty grid —
      * which loop-drains. It held if something was dirty and did not if nothing was.
      *
-     * `_draining` is restored rather than cleared, so a nested drain (an action that calculates)
-     * leaves the outer one's window intact.
+     * `_draining` stays set until the last run in flight finishes ({@link _drainDepth}), so a nested
+     * drain (an action that calculates) or an overlapping one leaves the other's window intact.
      *
      * **Call this under `if (this._pendingActions?.length)`, not unconditionally.** `await` on an
      * async call yields to the microtask queue even when the callee does nothing, and a calculation
@@ -214,24 +491,332 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * between. An unconditional drain here pushes the whole pass past a microtask boundary and that
      * read returns the raw text instead (`use-signs.test.ts`).
      */
-    protected _drainPending(): Promise<void>;
+    protected _drainPending(priorityOnly?: boolean): Promise<void>;
     /** @inheritdoc ICalculation.calculate */
     calculate(options?: ICalculation.CalculateOptions | boolean): Promise<ICalculation.Status>;
     /**
      * @returns The status the engine is in once the pass has run — `Starting` if the request was
-     *          deferred to the start-up drain, and whatever non-`Ready` status turned it away
+     *          deferred to the start-up drain, and whatever non-`Running` status turned it away
      *          otherwise. Never `undefined`: it used to resolve that on every path including the
      *          successful one (the tail simply fell off the end), and two call sites cast the result
      *          to `Status` to satisfy {@link ICalculation.calculate}.
      */
     protected _calculate(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
-    protected _createCalcGrid(options?: CalcGrid.ConstructorOptions): ICalcGrid;
-    protected _registerGrid(grid: ICalcGrid): void;
+    /** A pass, counted while it runs: what the calculation state reads as a pass in flight. */
+    protected _calculateNow(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
+    protected _runCalculation(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
+    /**
+     * A restore moves every grid to another snapshot and reports nothing, so each formula host is
+     * told here what its grid now holds.
+     * @internal
+     */
+    protected _processRestoreOrRevert(state: State, commit: ITransaction.ICommit): void;
+    /**
+     * Formula text as a cell at `coords` would STORE it, without writing it anywhere.
+     *
+     * @remarks
+     * {@link createFormula} compiles for editing, which keeps what was typed. A committed cell is
+     * compiled for storage: `[#This Row]` becomes `@`, and an unqualified structured reference is
+     * given the name of the table it binds to - the one at `coords`. An owner that holds formula text
+     * apart from any cell (a table column's totals formula while its row is hidden) stores it
+     * through this, so it holds what a cell would.
+     *
+     * @param coords The cell the text is authored at, on the sheet `scope` names (by id or name).
+     * @throws When the engine is not Ready, or `scope` names no sheet.
+     * @internal
+     */
+    _toStoredText(expression: string, coords: IRange.CellCoords & {
+        scope: string;
+    }): string;
+    /**
+     * A grid that holds exactly one formula block, as a handle - see {@link FormulaHost}.
+     *
+     * @remarks
+     * Creates the grid unless the container already has one under `id` (a name's grid outlives a
+     * redefine and a delete), then answers a handle over it. The handle resolves the grid by id on
+     * every use, so it is safe to hold across snapshots.
+     *
+     * @internal
+     */
+    _createFormulaHost(options: Calculation.FormulaHostOptions): FormulaHost;
+    /**
+     * Evaluate an expression once over a block, through the engine.
+     *
+     * @remarks
+     * The implementation of {@link ICalculation.EvaluateOptions.block}: a watch with no lifetime.
+     * The body is written over `coords` in a grid that shadows the sheet, exactly as a watch's is
+     * (see `WatchAnchor`), one pass evaluates it, and the grid is dropped. What comes back reads over
+     * a copy-on-write clone of the dropped grid's values, taken before the drop, so it outlives the
+     * grid as a plain object.
+     *
+     * The grid and its body amend the current commit, as a watch's do: never an undo step. The
+     * pass is explicit and seeded from the one grid, so it runs under manual calculation without
+     * recalculating what the user has deferred.
+     * @internal
+     */
+    protected _evaluateOver(options: Calculation.EvaluateOverOptions): Promise<IRange>;
+    /**
+     * A grid for a model to hold (DESIGN-CALC-SERVICE §13.23): the synchronous half, versioned in
+     * the model's store, forwarding every verb as a request. The engine's grid is made by the
+     * grid's first request, `create`, which an `Off` engine drops: a start makes it then, from this
+     * one. What the engine pushes reaches the owner through the grid's events. It opens empty: the
+     * owner attaches its listeners, then seeds it.
+     * @internal
+     */
+    _createCalcGrid(options: Calculation.CalcGridOptions): CalcGrid;
+    /** What a `create` for a model grid carries: its description, and its size as it is now. */
+    protected _specOf(front: CalcGrid): CalcGridSpec;
+    /**
+     * The engine's grid for a model grid, as a `create` describes it. What it pushes reaches the
+     * model grid under the same id.
+     */
+    protected _createEngineGrid(spec: CalcGridSpec): CalcGridBackend;
+    /**
+     * Make the engine's grids from the model's (design §6.3): each live model grid's `create`, the
+     * hosts' first (a name's grid before any sheet's); each host's body sent again; then every grid
+     * a sheet owns seeded from what it holds now. Requests like any other: held while `Starting`,
+     * applied at once on a `Running` engine that is rebuilt.
+     *
+     * @param full The seeds ask for a full pass - a start's, which the boot keeps only when
+     * something was written while `Off`.
+     */
+    protected _openEngineGrids(full: boolean): void;
+    /**
+     * The engine's graph and every grid in it, gone: what `stop()` leaves, and what a rebuild starts
+     * from. The model's grids are untouched.
+     */
+    protected _dropEngine(): void;
+    /**
+     * The engine's history starts at the boot: the commits mirrored before it hold none of the
+     * grids the boot made, so a restore to one is not followed but rebuilt ({@link _followRestore}).
+     * The model's commit now is the boot's.
+     */
+    protected _forgetEarlierLandings(modelCommitId?: string | null): void;
+    /**
+     * The model restored itself to `commitId`: the engine restores its own history there, or - on a
+     * `Running` engine whose history does not reach it (a commit from before its start, or one
+     * trimmed since) - is rebuilt from the model's grids as they are there, at the next safe point.
+     */
+    protected _followRestore(commitId: string): void;
+    /**
+     * Make the engine again from the model, as a start does: its replicas, its grids and their
+     * seeds, with the values the model holds trusted.
+     */
+    protected _rebuildEngine(): void;
+    /**
+     * Report a failure of a request no caller awaits - a grid's seed - as this calculation's error.
+     * @internal
+     */
+    _reportError(error: unknown): void;
+    protected _createBackendGrid(options?: CalcGridBackend.ConstructorOptions): CalcGridBackend;
+    protected _registerGrid(grid: CalcGridBackend): void;
     protected _unregisterGrid(gridId: string): void;
+    /**
+     * The sheet list as the model holds it now: what a `sheets` message carries, and what a start
+     * seeds the replica from. Read only at those two moments.
+     */
+    protected _liveSheets(): [id: string, name: string | null][];
+    /**
+     * Tells the engine the sheet list as the model holds it now (DESIGN-CALC-SERVICE §8): one
+     * message through the channel, applied at once on a `Running` engine, held in order while
+     * `Starting`, dropped by an `Off` one (whose next start seeds the replica afresh, and which
+     * reads the drop as a write made meanwhile, so that start's pass is full).
+     */
+    protected _sendSheets(): void;
+    /**
+     * Replaces the replica with the list a `sheets` message carries.
+     *
+     * @remarks
+     * A sheet that survived with a different name or at a different position changes what the
+     * functions reading names and positions answer (`INDIRECT`, `FORMULATEXT`, `CELL`, `SHEET`, a
+     * 3-D span's members), and none of that is a precedent: a full pass follows, which is what the
+     * model asked for on a rename or a move before the engine was told of either. A sheet
+     * appended moves nothing; one inserted or deleted ahead of a survivor moves it, and counts.
+     */
+    protected _applySheets(sheets: readonly (readonly [id: string, name: string | null])[]): void;
+    /** The model's tables as the replica holds them: by id, each table's name and columns. */
+    protected _liveTables(): Map<string, TableSymbols>;
+    /** The defined names as the replica holds them: by id, each name's spelling and scope sheet. */
+    protected _liveNames(): Map<string, NameSymbols>;
+    /**
+     * Tell the engine one table's name and columns as they are now, or that it is gone - from the
+     * model, at the moment it changes, inside the operation (the sheet's table callbacks). So the
+     * message is in the channel where the change happened, between the requests made before it and
+     * those made after, and a request held while `Starting` binds the names it was sent under. A
+     * restore changes nothing here: it reaches the engine as the revert of its own store. An `Off`
+     * engine is told nothing; a start seeds the replica from the model.
+     *
+     * @remarks
+     * Reads the table's own record only: a read of the sheet inside an open operation would make the
+     * writes a cell buffer holds.
+     * @internal
+     */
+    _tableChanged(table: ITable, removed: boolean): void;
+    /** A name written, as {@link _tableChanged} tells a table. */
+    protected _nameWritten(written: NamedFormulaCollection.NamesWritten): void;
+    /**
+     * One change to a replica, as a message: sent to a `Starting` engine as it is (the channel holds
+     * it in order), and to a `Running` one only when the replica does not already say so.
+     */
+    protected _sendSymbolChange<T>(kind: 'tables' | 'names', id: string, entry: T | null, same: (a: T | null | undefined, b: T | null) => boolean): void;
+    /**
+     * Applies what a `tables` message carries to the replica. A reference bound by a name the
+     * replica did not have yet heals to it now, as one to a table added does.
+     */
+    protected _applyTables(changes: readonly (readonly [id: string, table: TableSymbols | null])[]): void;
+    /** Applies what a `names` message carries, as {@link _applyTables} does. */
+    protected _applyNames(changes: readonly (readonly [id: string, name: NameSymbols | null])[]): void;
+    /** What a replica's change re-resolved - healed, renamed, gone - is marked for the next pass. */
+    protected _markDirtyReconciled(provider: {
+        reconcile(): string[];
+    } | null): void;
+    private _tablesDerived;
+    private _namesDerived;
+    /**
+     * The table replica and its name index, or `null` while `Off`: an engine that has been told
+     * nothing reads the model.
+     */
+    protected _replicaTables(): {
+        of: ReadonlyMap<string, TableSymbols>;
+        idByName: Map<string, string>;
+    } | null;
+    /** The name replica and its spelling index, as {@link _replicaTables}. @internal */
+    _replicaNames(): {
+        of: ReadonlyMap<string, NameSymbols>;
+        idsByName: Map<string, string[]>;
+    } | null;
+    /**
+     * The name a spelling resolves to from `scope`, by the replica: that sheet's own name first, then
+     * the global; asked from no sheet, the global, else any scoped one - the collection's rule
+     * (`NamedFormulaCollection.getByName`). `undefined` when the replica cannot answer, and the
+     * collection is asked instead.
+     * @internal
+     */
+    _replicaNameId(name: string, scope: string | null | undefined): string | undefined;
+    /** See {@link _modelSymbols}. */
+    protected _modelSymbolRegistry: ISymbolRegistry;
+    /**
+     * The model's symbol map (DESIGN-CALC-SERVICE §8): what the facade images the engine's records
+     * against. Sheets answer from the model's live list; the rest from the engine's providers.
+     * @internal
+     */
+    _modelSymbols(): ISymbolRegistry;
+    /**
+     * What images a grid's records for the model (DESIGN-CALC-SERVICE §8): the model's symbol map,
+     * the grid as home scope, its bounds and the reader's locale, both read live so a rename or a
+     * locale switch shows without a recompile.
+     * @internal
+     */
+    _imagerFor(gridId: string): FormulaImager;
+    private _sheetsDerived;
+    private _sheetsCache;
+    /** Every sheet's grid id in tab order, from the replica. */
+    protected _sheetIds(): readonly string[];
+    /** A sheet's grid id by its name, as Excel reads sheet names: case-insensitively. `null` when none. */
+    protected _sheetIdByName(name: string): string | null;
+    /** A sheet's name by its grid id, or `null` for a grid that is no sheet. */
+    protected _sheetName(gridId: string): string | null;
     /** @inheritdoc ICalculation.stop */
     stop(): Promise<void>;
+    /**
+     * {@inheritDoc ITransaction.ITransactional.close}
+     *
+     * @remarks
+     * Brings the ENGINE down before the model goes away. The inherited close is a model close — it
+     * flips the closed flag and detaches the transaction listener — which left a closed calculation
+     * still reporting {@link ICalculation.Status.Running}, with `onStopping`/`onStop` never sent to
+     * listeners that were about to be discarded.
+     *
+     * {@link stop} resolves synchronously (it awaits nothing), so the `void` here loses no ordering;
+     * it is `async` only because the interface says so. It is also a no-op unless the status is
+     * `Running`, which is what makes closing a still-STARTING engine safe — `start()` observes the close
+     * at its own await points instead.
+     */
+    close(): void;
+    /** A model holding writes for the engine makes them on this read (`ITransaction.Hooks.writes`). */
+    protected _flushModel(): void;
+    /**
+     * Runs `action` with its engine writes landing under `landingId`, or as they are when none.
+     *
+     * @remarks
+     * A root-level request after a nested savepoint of the same root has landed: the root's own
+     * commit is behind the tip, and the savepoint is part of the root for good, so the write joins
+     * the tip. The engine's live maps are always the tip's.
+     * @internal
+     */
+    _landUnder<R>(landingId: string | undefined, action: () => R): R;
+    /** Whether the engine still holds a commit: its own record is in every commit made since it was built. */
+    protected _holdsEngineCommit(engineId: string): boolean;
+    /**
+     * Records the model commit that just landed: its mirror, a commit of the engine's own that names
+     * it in the engine's record.
+     *
+     * @remarks
+     * A commit even when nothing landed under the model's: an engine write made after the close,
+     * outside any model operation (a deferred recompile), amends the engine's tip, and that tip has
+     * to be this model commit's, not the one before it, or a restore to the one before carries the
+     * write. The engine's record changes with every mirror, so the commit is never elided.
+     */
+    protected _mirror(commitId: string): void;
+    /** Forgets a landing, and the engine commit it made if it made one. */
+    protected _dropLanding(landingId: string): void;
+    /** Drops the landings whose engine commit the store has trimmed or pruned. Rare: sized by the store's cap. */
+    protected _sweepLandings(): void;
+    /** The model commits on the live history: the current one and its ancestors. */
+    protected _modelHistory(): Set<string>;
+    /**
+     * A model root closed without landing (an amend, or nothing written): the engine commits made
+     * under its id (`<id>:0`, `<id>:n`) fold into the mirror of the model's current commit.
+     */
+    protected _foldPhantom(rootId: string): void;
+    /**
+     * The engine commit an engine write made during a model operation lands in: the operation's
+     * root (`<id>:0`) or the nested savepoint open now. `null` outside an operation, or while a
+     * landing is already open (the write joins it).
+     */
+    protected _modelLanding(): string | null;
+    /**
+     * Engine state is never a step of history on its own: a write is attributed to the model
+     * operation it is made in, or folded into the current snapshot (a pass's bookkeeping).
+     * @internal
+     */
+    protected _updateState(updateState?: Partial<State>, options?: ITransaction.StoreOperationOptions, events?: (keyof ICalculation.IListeners)[]): this;
+    /** @internal */
+    protected _amendState(updateState?: Partial<State>, options?: ITransaction.StoreOperationOptions, events?: (keyof ICalculation.IListeners)[]): this;
+    /**
+     * Restore the engine's history to the model's `commitId`, once; answers what changed per grid.
+     *
+     * @remarks
+     * The changed regions are the union of what every engine commit between the two snapshots
+     * recorded as touched (`IntentTouched`), whichever direction the restore goes; they are marked
+     * dirty so the pass that follows recomputes them, and handed back so each grid can re-vend the
+     * blocks over them. An id the engine no longer holds is answered with `null`: the engine's
+     * history is shorter than the model's there, and a seed is what brings it back (step 3).
+     * @internal
+     */
+    _revertTo(commitId: string): Map<string, IRange.Coords[]> | null;
+    /**
+     * Hook the rollback of the savepoint a request goes out under, the first time one does: a
+     * `rollback` message follows, through the channel, if it rolls back. By a step that shares the
+     * savepoint and writes nothing - its outcome hooks pass to the savepoint when it closes. A
+     * request landing on the operation's own commit (`<id>:0`) needs none: a root rollback is seen by
+     * the engine's listener on the store.
+     */
+    protected _hookRollback(landingId: string): void;
+    private _rollbackHooked;
+    /**
+     * A nested savepoint of the model rolled back: what the engine landed under it goes with it.
+     * What a `rollback` message does.
+     */
+    protected _savepointRolledBack(savepointId: string): void;
     /** @inheritdoc ICalculation.getStatus */
     getStatus(): ICalculation.Status;
+    /**
+     * Resolves once every request sent to a grid has settled and its sender has handled the
+     * response. What a save waits for after `ready()`.
+     * @internal
+     */
+    _whenRequestsSettled(): Promise<void>;
     /** @inheritdoc ICalculation.getCalculationMode */
     getCalculationMode(): ICalculation.CalculationMode;
     /** @inheritdoc ICalculation.setCalculationMode */
@@ -246,19 +831,36 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     toJSON(): ICalculation.JSON;
     /** @inheritdoc ICalculation.ready */
     ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /** One round of `ready()`: up, drained, and the passes the dirty set owes (none in manual mode). */
+    protected _readyPass(full: boolean): Promise<void>;
+    /** @inheritdoc ICalculation.getCalculationState */
+    getCalculationState(): ICalculation.CalculationState;
+    /**
+     * Work in flight: answers owed to the model, a drain posted or running, deferred actions, a pass
+     * owed or running, the boot. What `ready()` waits out.
+     */
+    protected _isWorking(): boolean;
+    /**
+     * Checks the calculation state once the current flush is over: announces a change, and wakes
+     * every `ready()` waiting for work in flight to end. Called wherever that work starts or ends.
+     */
+    protected _noteCalculationState(): void;
     /**
      * The locale-aware editing compiler, (re)built when the workbook locale (separators, Plane 1) or
      * active spreadsheet-language pack (boolean literals, Plane 3) has changed since it was last built.
      * Only the editing path uses locale-specific separators; the calc path (`_compiler`) is always
      * canonical because it only ever parses stored/API text.
      */
-    protected _getEditingCompiler(): IFormulaCompiler;
+    protected _getEditingCompiler(target?: ICalculation.FormulaTarget): IFormulaCompiler;
     /** @inheritdoc ICalculation.createFormula */
-    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
+    protected _createFormula(expression: string, coords: Partial<IRange.CellCoords> | undefined, target: ICalculation.FormulaTarget): ICalculation.IFormula;
     /** {@inheritDoc ICalculation.evaluate} */
-    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /** @inheritdoc ICalculation.getFunctions */
     getFunctions(): IFunctionCollection;
+    /** @inheritdoc ICalculation.getExternalBooks */
+    getExternalBooks(): IExternalBookCollection;
     /** @inheritdoc ICalculation.getNamedFormulas */
     getNamedFormulas(): INamedFormulasCollection;
     /**
@@ -288,6 +890,8 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     protected _statusMessage(): string;
     get [Symbol.toStringTag](): string;
     toString(): string;
+    /** {@inheritDoc ICalculation.isICalculation} */
+    get isICalculation(): true;
 }
 /**
  * Interfaces for creating `Calculation` items.
@@ -298,6 +902,55 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
  * {@link Calculation}
  */
 export declare namespace Calculation {
+    /** See {@link Calculation._evaluateOver}. */
+    interface EvaluateOverOptions {
+        /** The sheet whose coordinate space the block is in. */
+        sheetGridId: string;
+        /** The block: the body is filled over it. */
+        coords: IRange.Coords;
+        /** The expression as authored, without a leading `=`. */
+        expression: string;
+        /** Where the expression is authored; `coords`' top-left for a plain fill. */
+        authoredAt: IRange.CellCoords;
+        /** Each cell of the block is its own 1x1 array-entered formula. See {@link ICalculation.EvaluateOptions.arrayFirstCell}. */
+        arrayFirstCell?: boolean;
+    }
+    /** See {@link Calculation._createFormulaHost}. */
+    interface FormulaHostOptions {
+        /** The grid's id; an existing grid under it is reused. */
+        id: string;
+        /** The sheet grid whose coordinate space the body lives in - a watch. See {@link ICalcGrid.getShadowOf}. */
+        shadowOf?: string;
+        /** `true` for a grid whose (0,0) is a synthetic anchor - a name. See {@link CalcGridBackend.ConstructorOptions.unanchored}. */
+        unanchored?: boolean;
+        /** `true` for a body whose every cell is its own 1x1 array-entered formula. See {@link ICalcGrid.isArrayFirstCell}. */
+        arrayFirstCell?: boolean;
+        /** The grid's size: fixed, a name's. */
+        entireCoords?: IRange.Coords;
+        /** The grid whose size the body has, whatever it is then: a sheet's, for a body on it. */
+        sizeOf?: string;
+        /** Told after every pass that wrote the grid. */
+        onCalculated?: (results: ICalcGrid.Results) => void;
+    }
+    /** See {@link Calculation._createCalcGrid}. */
+    interface CalcGridOptions extends CalcGrid.HostOptions, Pick<CalcGrid.ConstructorOptions, 'valuesAxis'> {
+        /** The grid's id; a new one is made when absent. */
+        uuid?: string;
+        /** See {@link CalcGridSpec.name}: a sheet's grid. */
+        name?: string | null;
+        /** See {@link CalcGridSpec.shadowOf}. */
+        shadowOf?: string;
+        /** See {@link CalcGridSpec.unanchored}. */
+        unanchored?: boolean;
+        /** See {@link CalcGridSpec.arrayFirstCell}. */
+        arrayFirstCell?: boolean;
+        /** The grid's size, as the model knows it: a sheet's, read when asked. */
+        getEntireCoords?: () => IRange.Coords;
+        /** The grid's size, fixed. */
+        entireCoords?: IRange.Coords;
+        /** See {@link CalcGridSpec.sizeOf}. */
+        sizeOf?: string;
+    }
     /**
      * Options available when creating a Calculation Service.
      */
@@ -320,6 +973,11 @@ export declare namespace Calculation {
          * defining cell when a named formula is added without an explicit `cell` (mirrors Excel).
          */
         getActiveCell?: () => IRange.CellCoords | null;
+        /**
+         * Whether defined names refuse edits, on top of the calculation's own read-only state. A
+         * workbook answers with its structure protection.
+         */
+        isNamesReadOnly?: () => boolean;
         /**
          * Returns a sheet handle given an id.
          */
@@ -337,13 +995,16 @@ export declare namespace Calculation {
             getRanges?: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
         } | null;
         /**
-         * Returns a sheet handle given a name.
+         * External books to hydrate at construction, in `IWorkbook.JSON.externalBooks` form — `[n]`
+         * order, `null` for a DDE/OLE gap.
+         *
+         * @remarks
+         * The engine owns the collection ({@link ICalculation.getExternalBooks}) for the reason it owns
+         * defined names: a book is a symbol formulas bind into, and its dependents are the engine's index.
          */
-        getSheetByName?: (sheetName: string) => {
-            getId(): string;
-            getName(): string;
-            getEntireCoords: () => IRange.Coords | null;
-        } | null;
+        externalBooks?: (IExternalBook.JSON | null)[];
+        /** See {@link ICellContainerOptions.externalBookResolver}; held by the collection for the engine's life. */
+        externalBookResolver?: IExternalBook.IResolver;
         /**
          * Named item collection shared with the workbook.
          *
@@ -362,12 +1023,6 @@ export declare namespace Calculation {
          * engine has no pre-load lifecycle state.
          */
         names?: INamed.JSON[];
-        /**
-         * A structural transform applied to each hydrated name's expression as it compiles — the READ
-         * half of the format-dialect hook (see `IWorkbook.ConstructorOptions.formulaTransform`).
-         * Applies only to {@link names}; formulas added later compile without it.
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
         getRanges?: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
         getRange?: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
         /**
@@ -381,9 +1036,20 @@ export declare namespace Calculation {
          * `INamedRange` — see DESIGN-NAMED-FORMULAS.md §4). Structural like `getRange`/`getRanges`,
          * and like them supplied by the workbook. Without it, graph answers fall back to cells only.
          */
-        createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null;
+        createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly NamedNodeInfo[]) => ICellRanges | null;
         getSheetIndex?: (sheetName?: string) => number;
         getSheetCount?: () => number;
+        /**
+         * Every sheet's stable id in tab order, hidden and very hidden included — the order a 3-D
+         * reference's members are read from.
+         */
+        getSheetIds?: () => string[];
+        /**
+         * Subscribes to the sheet list changing by an operation - a sheet added, deleted, moved,
+         * copied or renamed. Not a restore: an undo or a redo reaches the engine through its own
+         * store, which is restored with the model's (DESIGN-CALC-SERVICE §7.5, §8).
+         */
+        addSheetsListener?: (callback: () => void, options?: IListener.Options) => IListener.Remove;
         strings?: IStringCollection;
         /**
          * Whether to perform iterative calculations when there are circular dependencies.
@@ -396,7 +1062,7 @@ export declare namespace Calculation {
          *
          * @defaultValue 100
          */
-        maxIterations?: number;
+        maxIteration?: number;
         /**
          * The maximum change allowed between iterations when performing iterative calculations.
          *
@@ -408,7 +1074,25 @@ export declare namespace Calculation {
 /**
  * Transaction State for Calculation
  */
+/**
+ * A grid request the channel holds while the engine is `Starting` (DESIGN-CALC-SERVICE §4): the
+ * request as data, the snapshot it names, and the caller's continuation.
+ */
+interface HeldRequest {
+    gridId: string;
+    request: CalcRequest;
+    /** The engine commit it would have landed in; what a nested rollback names. */
+    landingId: string | undefined;
+    /** The model snapshot it was made at (`RequestOptions.commitId`); what a restore names. */
+    commitId: string | undefined;
+    /** The model has undone the snapshot it was made at: skipped when applied, unless a redo revives it. */
+    dead: boolean;
+    resolve: (response: CalcResponse | PromiseLike<CalcResponse>) => void;
+    reject: (error: unknown) => void;
+}
 interface State extends AbstractModel.State {
+    /** The model commit this engine commit mirrors; written by every mirror so the commit lands. */
+    mirrorOf?: string;
     /**
      * Top down evaluation and marking dirty.
      * This is the only spatial map that is completely updated via api.
@@ -442,13 +1126,34 @@ interface State extends AbstractModel.State {
     /**
      * All registered grids.
      */
-    gridsAll: Map<string, ICalcGrid>;
+    gridsAll: Map<string, CalcGridBackend>;
+    /**
+     * The engine's replica of the model's sheet list (DESIGN-CALC-SERVICE §8): grid id to name, in
+     * tab order. What every symbol lookup, span and sheet-position function reads. Fed by the
+     * `sheets` message and by grid registration; versioned here so a revert restores it with the
+     * formulas that bound through it.
+     */
+    sheets: ReadonlyMap<string, string | null>;
+    /**
+     * The engine's replica of the model's tables (DESIGN-CALC-SERVICE §8): table id to its name and
+     * its columns' ids and names. What a structured reference binds and images through. Fed by the
+     * `tables` message, seeded at a start, versioned here as {@link sheets} is.
+     */
+    tables: ReadonlyMap<string, TableSymbols>;
+    /**
+     * The engine's replica of the defined names: name id to its spelling and the sheet it is scoped
+     * to. What a name binds and images through. Fed by the `names` message, as {@link tables} is.
+     */
+    names: ReadonlyMap<string, NameSymbols>;
+    /**
+     * Each grid's per-grid maps as of this snapshot (`CalcGridMaps`): values, contentful, spills,
+     * errors, pending, circular. Copy-on-write per request; handed back to the grid on a restore.
+     */
+    gridMaps: Map<string, object>;
     /**
      * Listeners to individual named items
      */
     itemRemoveListeners: (() => void)[];
 }
-interface CommitView extends AbstractModel.CommitView {
-}
 export {};
 //# sourceMappingURL=Calculation.d.ts.map