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

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

@@ -1,131 +1,191 @@
-import { IRange, IFormulaContext, IRuntime, Scalar } from '@sheetxl/primitives';
+import { IRange, 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 { 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 { CalcExecutor } from './executor';
+import { CalcGrid, FormulaHost, ICalcGrid } from './grid';
+import { CalcRequest, CalcResponse, CalcGridSpec, TableSymbols, NameSymbols } from './grid/_CalcRequest';
+import { CalcBackend } from './engine/CalcBackend';
+import { IndirectSymbolProvider, ISymbolRegistry } from './symbol';
 import { ICalculation } from './ICalculation';
 import { NamedFormulaCollection } from './NamedFormulaCollection';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
 /**
  * Implementation for {@link ICalculation}.
  */
-export declare class Calculation extends AbstractModel<State, ICalculation.JSON, CommitView, ICalculation.IListeners> implements ICalculation {
-    protected _container: IContextContainer;
-    protected _context: CalculationContext & IFormulaContext;
+export declare class Calculation extends AbstractModel<AbstractModel.State, ICalculation.JSON, ICalculation.IListeners> implements ICalculation {
+    protected _backend: CalcBackend | null;
+    protected _startReplica: CalcBackend.Replica | null;
+    /** The symbols formulas bind through (DESIGN-CALC-SERVICE §8): the model's, handed to the backend. */
+    protected _symbols: ISymbolRegistry;
     protected _status: ICalculation.Status;
     protected _statusTransition: Promise<void> | null;
     protected _runtime: IRuntime;
     protected _functions: IFunctionCollection;
     protected _namedFormulas: NamedFormulaCollection;
+    protected _externalBooks: ExternalBookCollection;
     /** `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 _engineModule: typeof import('./engine') | null;
+    protected _planCache: 'off' | 'assert' | 'on' | null;
     protected _getActiveCell: () => IRange.CellCoords | null;
     protected _getRange: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
     protected _getRanges: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
-    protected _calcExecutor: CalcExecutor;
-    protected _cycleId: number;
-    protected _staticEpoch: number;
-    protected _precedentEpoch: number;
-    protected _epochSeenFormulas: ISpatialMap3D<FormulaSpatialValue> | null;
-    protected _epochSeenPrecedents: ISpatialMap3D<PrecedentSpatialValue> | null;
-    protected _epochSeenDynamics: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]> | null;
-    protected _volatiles: Set<CalcNode>;
-    protected _calculatedCommitId: string | null;
+    /** The current handle of every formula host's grid, by grid id. */
+    protected _formulaHosts: Map<string, FormulaHost>;
+    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, CalcGridSpec>;
+    protected _modelStoreRemoveListener: IListener.Remove | null;
+    protected _mirrorRemoveListener: IListener.Remove | null;
+    _modelMirrorId: string | null;
+    /** Where the owner's sheet list is held ({@link _setSheets}): the model's store, or a transient one with no model. */
+    protected _ownerStore: ITransaction.IStore;
+    /** The record holding the owner's sheet list, in {@link _ownerStore}. */
+    protected _sheetListId: string;
+    protected _landedCommits: Set<string> | 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;
+    /** Consumer work not yet settled: see {@link waitUntil}. */
+    protected _consumerWork: number;
+    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;
     protected _removeNamedItemsListeners: (() => void) | null;
-    protected _namedDependents: Map<string, IRange.Coords[]> | null;
-    protected _namedDependentsOf: ISpatialMap3D<FormulaSpatialValue> | null;
+    /** The listeners on each table's extent, registered again whenever the named collection changes. */
+    protected _tableListenerRemovers: (() => void)[];
     /**
      * Resolver callbacks passed to every {@link FormulaBlock} at creation time.
      * 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;
     /**
-     * Reverse-invalidates only the formulas that reference any of `changedIds` — the stable name/table
-     * fake ids reported by `IndirectSymbolProvider.reconcile()` (add/heal, delete, rename).
+     * Makes the backend from its loaded module. Once per calculation; a restart reuses it, as
+     * `_dropEngine` leaves it.
      *
      * @remarks
-     * Replaces the old `isFullCalcRequired` blanket. `bind()` assigns a stable fake id at compile time
-     * regardless of whether the symbol resolves, and reconcile() reports that same id — so matching a
-     * formula's `getReferencedSymbolIds()` catches the "heal" case (`#NAME?`/`#REF!` → valid) that a
-     * precedent-range markDirty can't, because an unresolved reference has no precedent range.
-     *
-     * Marking the direct referencers is not enough where the referencer is another NAME. Downstream
-     * of a cell, the dependency graph carries transitivity for free; downstream of a name it carries
-     * nothing, because a name registers no precedent range for the formulas that mention it. So the
-     * ids are first expanded over the symbol graph ({@link _namedTargets}), and only from the cells
-     * that land in are the ordinary edges left to do the rest.
-     *
-     * O(formulas) all3D scan — same cost/scale as `recompileNamed`.
-     *
-     * @returns `true` if any formula was marked dirty.
+     * Its history starts here, at the model's current commit: nothing before a start writes to it.
+     * Its replicas start as the owner held them when the start was asked for.
      */
-    protected _markDirtyReferencing(changedIds: Set<string>): boolean;
+    protected _attachEngine(engine: typeof import('./engine')): void;
     /**
-     * {@inheritDoc IContextContainer.getNamedDependents}
-     *
-     * @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.
+     * What the backend asks of this calculation (see {@link CalcBackend.Callbacks}): the in-process
+     * half of the backend's interface.
      */
-    protected _getNamedDependents(nameId: string): readonly IRange.Coords[];
+    protected _backendCallbacks(): CalcBackend.Callbacks;
     /**
-     * {@inheritDoc IContextContainer.getNamedDependentNames}
+     * Recompiles, at the next safe point, the formulas that reference a name - or reference a name
+     * that does: a name's link to the engine, held from before there is one. See
+     * {@link IContextContainer.recompileNamed}.
+     */
+    protected _recompileNamed(nameId: string): void;
+    /** Marks, at the next safe point, the formulas that reference a name out of date. See {@link IContextContainer.invalidateNamed}. */
+    protected _invalidateNamed(nameId: 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
-     * A block that depends on a name and lives on a VIRTUAL grid is another name's BODY, and that
-     * grid's id is that name's id — `add` binds the two together and `delete` keeps the grid rather
-     * than dropping it. So the hop is a bucket lookup on the id itself; a sheet grid id is never a
-     * name id, which is what {@link NamedFormulaCollection.getById} is asked to confirm before the
-     * walk continues through one.
-     *
-     * Expands each id once. That is the cycle guard (`A = B+1`, `B = A+1` reaches `A` again on its
-     * second hop) and the diamond guard both.
+     * 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.
      */
-    protected _getNamedDependentNames(nameId: string): ReadonlySet<string>;
+    _releaseTableReferences(table: ITable, release: 'error' | 'address'): void;
     /**
-     * `changedIds` widened to everything a change to them reaches through the SYMBOL graph: each id
-     * plus, for the names among them, every name transitively referencing it.
+     * @internal
+     * A table's body has changed rows: re-fit the A1 references that spanned it (see
+     * {@link CalcBackend.refitTableRows}).
      *
-     * @remarks
-     * The one expansion both `recompileNamed` and {@link _markDirtyReferencing} apply before their
-     * all3D scan, so a formula naming an intermediate name is matched by the same pass that matches
-     * one naming the changed name directly. Ids that are not names (a table's) expand to themselves.
+     * @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;
+    /**
+     * @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;
+    /**
+     * @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<CalcBackend['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`.
      */
-    protected _namedTargets(changedIds: Set<string>): ReadonlySet<string>;
+    _planCacheMode(mode?: 'off' | 'assert' | 'on'): 'off' | 'assert' | 'on';
     /** @inheritdoc ICalculation.start */
     start(): Promise<void>;
     /**
@@ -137,7 +197,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 +211,86 @@ 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;
+    /**
+     * Runs the start batch under one operation on the model's store, folded into the commit the
+     * batch happens during.
+     *
+     * @remarks
+     * What the batch vends - a seed's record, a name body's answer - the model adopts as it is
+     * applied, and each adoption is a write to the model's store. Made as its own root commit, each
+     * write copies the store's whole state map into the record it keeps (a state per sheet model, and
+     * one per defined name's host), so a start that answers thousands of bodies cost thousands of
+     * such copies - the larger part of opening a legacy file. Under one open operation the writes
+     * join it, and the store copies once when it closes. Nothing of the model's changes here: the
+     * batch is the engine's answer to what the model already holds.
+     */
+    protected _underOneModelOperation<R>(batch: () => R): R;
+    /**
+     * @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`; and, when `Off`, once something else starts
+     * it. It never starts the engine itself.
+     *
+     * @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).
+     *
+     * An `Off` engine stays off (DESIGN-CALC-ON-LOAD: under `calcOnLoad: 'none'` a read starts
+     * nothing, and a conditional format or data validation evaluating on load is a read). Starting it
+     * here ran the boot pass, and the pass moved cached values — every volatile, every iterating
+     * cycle — in a workbook that was only being opened and saved. The waiter is released by the
+     * start the first mutation (or an explicit calculation) makes, and by {@link close}.
+     */
+    _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 +319,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 +352,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 +362,272 @@ 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;
-    protected _unregisterGrid(gridId: string): 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>;
+    /**
+     * The model commit the last pass recalculated for, `null` before the first: what a sheet
+     * realizing the pass's results amends them into.
+     * @internal
+     */
+    get _calculatedCommitId(): string | null;
+    /** A response's cycle: the engine's last pass, or none before there is an engine. */
+    protected get _cycleId(): number;
+    /**
+     * 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;
+    /**
+     * Whether a grid under `id` is in the model as the store is now: a held formula's grid that came
+     * back with an undone delete is attached to rather than written again.
+     * @internal
+     */
+    /**
+     * 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
+     */
+    _hasLiveGrid(id: string): boolean;
+    _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. */
+    protected _specOf(front: CalcGrid): CalcGridSpec;
+    /**
+     * 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 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;
+    /** The owner's sheet list as it last said ({@link _setSheets}): what a start seeds the replica from. */
+    protected _heldSheets(): Calculation.SheetList['sheets'];
+    /** One sheet of {@link _heldSheets} by its grid id, or `undefined` for a grid that is no sheet. */
+    protected _heldSheetAt(id: string): Calculation.SheetList['sheets'][number] | undefined;
+    /**
+     * The owner's sheet list as it is now: every sheet's grid id and name, in tab order, hidden ones
+     * included (DESIGN-CALC-SERVICE §8). The owner calls this whenever its list changes - a sheet
+     * added, deleted, moved, copied or renamed - and before any grid that names a sheet in it
+     * seeds. Not on a restore: this record is restored with the owner's own, and the engine's
+     * replica with the engine's store.
+     *
+     * @remarks
+     * Held in the caller's operation (folded into the current commit when none is open) and sent
+     * to the engine as one `sheets` message: applied at once on a `Running` engine, held in order
+     * while `Starting`. An `Off` engine is told nothing; its next start seeds the replica from this
+     * record, and owes a full pass only when a sheet already listed was renamed, moved or removed.
+     * @internal
+     */
+    _setSheets(sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[]): void;
+    /**
+     * Compiles every loaded name whose text mentions the sheet, ahead of a change a compiled body
+     * follows and text cannot: a shift of the sheet's cells, its rename, its removal. See
+     * {@link NamedFormulaCollection._materializeMentioning}. Nothing while `Off`: a body written
+     * then is sent at the next start, against the sheets as they are by then, as the text would be.
+     */
+    protected _materializeNamesMentioning(sheetId: 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;
+    /**
+     * While `Starting`: per kind, the held symbol message a new symbol of that kind joins, and the
+     * ids every message of the start has told. Dropped with the channel - see {@link _sendSymbolChange}.
+     */
+    protected _openSymbolMessages: Map<'tables' | 'names', HeldRequest> | null;
+    protected _symbolsTold: Map<'tables' | 'names', Set<string>> | null;
+    /** What a replica's change re-resolved - healed, renamed, gone - is marked for the next pass. */
+    protected _markDirtyReconciled(provider: {
+        reconcile(): string[];
+    } | null): void;
+    /**
+     * Whether the engine's replicas answer: not while `Off`, nor before the start has made the
+     * engine. An engine that has been told nothing reads the model.
+     */
+    protected _hasReplicas(): boolean;
+    /** The table replica and its name index, or `null` when there is none (see {@link _hasReplicas}). */
+    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 (see
+     * {@link CalcBackend.getReplicaNameId}). `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;
+    /** 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;
+    /** The model commits on the live history: the current one and its ancestors. */
+    protected _modelHistory(): Set<string>;
+    /**
+     * Whether a model commit landed: the model holds it, or did when a held request was judged
+     * against it. A snapshot that never landed (an amended root's) is not one a restore can undo.
+     */
+    protected _hasLanded(commitId: string): boolean;
+    /**
+     * The landing of the model operation open now, which an engine write made during it lands in:
+     * the operation's root (`<id>:0`) or the nested savepoint open now. `null` outside an operation.
+     */
+    protected _modelLanding(): string | 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;
     /** @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 +642,40 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     toJSON(): ICalculation.JSON;
     /** @inheritdoc ICalculation.ready */
     ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /** {@inheritDoc ICalculation.waitUntil} */
+    waitUntil<T>(work: Promise<T>): Promise<T>;
+    /** 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, and what consumers derive from the results ({@link waitUntil}) -
+     * except in manual mode, where the pass that work waits for runs only when asked. 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 +705,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 +717,62 @@ 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;
+        /** `true` for a body whose blank region may be evaluated a tile at a time. See {@link FormulaHost.request}. */
+        paged?: 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;
+        /** Told after a restore or revert has replaced the body under the host. */
+        onResync?: () => void;
+    }
+    /** The owner's sheet list as {@link Calculation._setSheets} holds it. */
+    interface SheetList {
+        /** Every sheet's grid id and name, in tab order, and `true` third for a sheet with no grid. */
+        readonly sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[];
+    }
+    /** 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.shadowOf}. */
+        shadowOf?: string;
+        /** See {@link CalcGridSpec.unanchored}. */
+        unanchored?: boolean;
+        /** See {@link CalcGridSpec.arrayFirstCell}. */
+        arrayFirstCell?: boolean;
+        /** See {@link CalcGridSpec.paged}. */
+        paged?: boolean;
+        /** See {@link CalcGridSpec.entireCoords}. */
+        entireCoords?: IRange.Coords;
+        /** See {@link CalcGridSpec.sizeOf}. */
+        sizeOf?: string;
+    }
     /**
      * Options available when creating a Calculation Service.
      */
@@ -321,29 +796,21 @@ export declare namespace Calculation {
          */
         getActiveCell?: () => IRange.CellCoords | null;
         /**
-         * Returns a sheet handle given an id.
+         * Whether defined names refuse edits, on top of the calculation's own read-only state. A
+         * workbook answers with its structure protection.
          */
+        isNamesReadOnly?: () => boolean;
         /**
-         * `getRange`/`getRanges` are OPTIONAL and structural on purpose — this keeps `Calculation` decoupled
-         * from `ISheet` while letting a real sheet hand over its own address resolvers. A temporary formula
-         * anchored to that sheet uses them so an unscoped (same-sheet) reference resolves THERE rather than
-         * against the workbook's active sheet. See `createFormula`.
-         */
-        getSheetById?: (sheetId: string) => {
-            getId(): string;
-            getName(): string;
-            getEntireCoords: () => IRange.Coords | null;
-            getRange?: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
-            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 +829,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,7 +842,7 @@ 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;
         strings?: IStringCollection;
@@ -396,7 +857,7 @@ export declare namespace Calculation {
          *
          * @defaultValue 100
          */
-        maxIterations?: number;
+        maxIteration?: number;
         /**
          * The maximum change allowed between iterations when performing iterative calculations.
          *
@@ -408,47 +869,21 @@ export declare namespace Calculation {
 /**
  * Transaction State for Calculation
  */
-interface State extends AbstractModel.State {
-    /**
-     * Top down evaluation and marking dirty.
-     * This is the only spatial map that is completely updated via api.
-     *
-     * @remarks
-     * For top down evaluation and marking formulas dirty.
-     */
-    formulaSpatial: ISpatialMap3D<FormulaSpatialValue>;
-    /**
-     * Tracks the inputs to formulas.
-     *
-     * @remarks
-     * * For bottom up marking dirty.
-     * * Contains a back-pointer to the formula.
-     *
-     */
-    precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;
-    /**
-     * Tracks dynamic precedents by block.
-     * Used to remove old dynamic precedents when a block is re-evaluated and to add new ones after evaluation.
-     */
-    dynamicByBlock: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>;
-    /**
-     * Dirty regions
-     */
-    dirtySpatial: ISpatialMap3D;
-    /**
-     * If true, the next calculation will be a full calc regardless of dirty state. Used for example when the engine detects a circular dependency and needs to fallback to iterative calculation or when the user explicitly requests a full calc.
-     */
-    isFullCalcRequired: boolean;
-    /**
-     * All registered grids.
-     */
-    gridsAll: Map<string, ICalcGrid>;
-    /**
-     * Listeners to individual named items
-     */
-    itemRemoveListeners: (() => void)[];
-}
-interface CommitView extends AbstractModel.CommitView {
+/**
+ * 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;
 }
 export {};
 //# sourceMappingURL=Calculation.d.ts.map