@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.12

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

@@ -1,69 +1,40 @@
-import { IRange, IFormulaContext, IRuntime, Scalar } from '@sheetxl/primitives';
+import { IRange, IFunction, 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 { IResourceCollection } from '../resource';
 import { IFunctionCollection } from '../scripting';
-import { ISpatialMap, ISpatialMap3D } from '../collections';
 import { INamed, INamedCollection } from '../named';
 import { ICellRange, ICellRanges } from '../cellRange';
 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 { CalcGridBackend, CalcGrid, FormulaHost, ICalcGrid } from './grid';
+import { CalcGrid, FormulaHost, ICalcGrid } from './grid';
 import { CalcRequest, CalcResponse, CalcGridSpec, TableSymbols, NameSymbols } from './grid/_CalcRequest';
-import { CalcExecutor } from './executor';
+import { CalcBackend } from './engine/CalcBackend';
 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, 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;
-    /** 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;
@@ -71,28 +42,19 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     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 _startFunctions: (() => Promise<readonly IFunction[]>) | 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>;
     /** 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, CalcGridSpec>;
-    /** 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;
@@ -100,13 +62,7 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     protected _ownerStore: ITransaction.IStore;
     /** The record holding the owner's sheet list, in {@link _ownerStore}. */
     protected _sheetListId: string;
-    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 _landedCommits: Set<string> | null;
     protected _outstanding: Set<Promise<ICalcGrid.Results>> | null;
     protected _pendingActions: (() => Promise<unknown>)[] | null;
     protected _pendingPriority: (() => Promise<unknown>)[] | null;
@@ -126,6 +82,8 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     /** `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;
@@ -138,8 +96,8 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     /** 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`.
@@ -151,40 +109,27 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     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;
     /**
-     * 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.
+     * What the backend asks of this calculation (see {@link CalcBackend.Callbacks}): the in-process
+     * half of the backend's interface.
      */
-    protected _recompileReferencing(changedIds: Set<string>): void;
+    protected _backendCallbacks(): CalcBackend.Callbacks;
+    /**
+     * 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
@@ -199,41 +144,8 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     _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.
+     * A table's body has changed rows: re-fit the A1 references that spanned it (see
+     * {@link CalcBackend.refitTableRows}).
      *
      * @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.
@@ -255,16 +167,6 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
         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
@@ -272,66 +174,12 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * 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 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 _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}
-     *
-     * @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.
-     */
-    protected _getNamedDependentNames(nameId: string): ReadonlySet<string>;
-    /**
-     * `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.
-     *
-     * @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.
-     */
-    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']>;
+    _stats(): ReturnType<CalcBackend['getDemandStats']>;
     /** @internal Zeroes every counter/timing so a measurement window starts clean. */
     _resetStats(): void;
     /**
@@ -381,15 +229,36 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      */
     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`; after the start it makes when `Off`.
+     * 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>;
     /**
@@ -496,6 +365,14 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * read returns the raw text instead (`use-signs.test.ts`).
      */
     protected _drainPending(priorityOnly?: boolean): Promise<void>;
+    /** @inheritdoc ICalculation.getPendingCount */
+    getPendingCount(): number;
+    /** @inheritdoc ICalculation.whenPendingDone */
+    whenPendingDone(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /** @inheritdoc ICalculation.cancelAsync */
+    cancelAsync(options?: ICalculation.CancelOptions): Promise<ICalculation.Status>;
     /** @inheritdoc ICalculation.calculate */
     calculate(options?: ICalculation.CalculateOptions | boolean): Promise<ICalculation.Status>;
     /**
@@ -505,16 +382,22 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      *          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 _calculate(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): Promise<ICalculation.Status>;
     /** 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>;
+    protected _calculateNow(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): 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.
+     * @param settle The settle pass (DESIGN-ASYNC §4.5): seeded from what a settle marked only;
+     * volatiles and the dirty set are left for the pass that owes them.
+     */
+    protected _runCalculation(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): 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
      */
-    protected _processRestoreOrRevert(state: State, commit: ITransaction.ICommit): void;
+    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.
      *
@@ -576,11 +459,6 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     _createCalcGrid(options: Calculation.CalcGridOptions): CalcGrid;
     /** What a `create` for a model grid carries: its description. */
     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
@@ -596,12 +474,6 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * 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
@@ -618,9 +490,6 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * @internal
      */
     _reportError(error: unknown): void;
-    protected _createBackendGrid(options?: CalcGridBackend.ConstructorOptions): CalcGridBackend;
-    protected _registerGrid(grid: CalcGridBackend): void;
-    protected _unregisterGrid(gridId: string): 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. */
@@ -639,25 +508,14 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * 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])[]): 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;
+    _setSheets(sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[]): void;
     /**
-     * Before a start applies what it held: every sheet a held \`sheets\` message adds enters the
-     * replica at the end, under the name it was first listed by. A defined name's body is applied
-     * ahead of the seeds and may name a sheet listed while starting; the messages themselves still
-     * apply in send order, so a seed sent before a rename binds the name it was sent under.
+     * 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 _enterHeldSheets(held: readonly HeldRequest[]): void;
+    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. */
@@ -676,30 +534,33 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * @internal
      */
     _tableChanged(table: ITable, removed: boolean): void;
-    /** A name written, as {@link _tableChanged} tells a table. */
-    protected _nameWritten(written: NamedFormulaCollection.NamesWritten): void;
+    /** Names written, as {@link _tableChanged} tells a table: one message for a batch. */
+    protected _nameWritten(written: readonly NamedFormulaCollection.NamesWritten[]): void;
+    /** {@link _sendSymbolChanges} for one change. */
+    protected _sendSymbolChange<T>(kind: 'tables' | 'names', id: string, entry: T | null, same: (a: T | null | undefined, b: T | null) => boolean): 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.
+     * Changes to a replica, as messages: sent to a `Starting` engine as they are (the channel holds
+     * them in order), and to a `Running` one only where the replica does not already say so, as ONE
+     * message - the replica is rebuilt and reconciled once per message, over every symbol, so a batch
+     * told a symbol at a time costs the square of its size.
      */
-    protected _sendSymbolChange<T>(kind: 'tables' | 'names', id: string, entry: T | null, same: (a: T | null | undefined, b: T | null) => boolean): void;
+    protected _sendSymbolChanges<T>(kind: 'tables' | 'names', changes: readonly (readonly [string, 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.
+     * 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 _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;
+    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;
-    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.
+     * 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>;
@@ -710,9 +571,8 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
         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
+     * 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
      */
@@ -732,8 +592,6 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      * @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. */
@@ -759,66 +617,18 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     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.
+     * 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 _foldPhantom(rootId: string): void;
+    protected _hasLanded(commitId: string): boolean;
     /**
-     * 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).
+     * 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;
-    /**
-     * 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
@@ -828,11 +638,6 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
      */
     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;
     /**
@@ -855,13 +660,17 @@ 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. What `ready()` waits out.
+     * 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;
     /**
@@ -938,6 +747,8 @@ export declare namespace Calculation {
         authoredAt: IRange.CellCoords;
         /** Each cell of the block is its own 1x1 array-entered formula. See {@link ICalculation.EvaluateOptions.arrayFirstCell}. */
         arrayFirstCell?: boolean;
+        /** How long to wait for the cells' async calls. See {@link ICalculation.EvaluateOptions.timeout}. */
+        timeout?: number;
     }
     /** See {@link Calculation._createFormulaHost}. */
     interface FormulaHostOptions {
@@ -949,6 +760,8 @@ export declare namespace Calculation {
         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. */
@@ -960,8 +773,8 @@ export declare namespace Calculation {
     }
     /** The owner's sheet list as {@link Calculation._setSheets} holds it. */
     interface SheetList {
-        /** Every sheet's grid id and name, in tab order. */
-        readonly sheets: readonly (readonly [id: string, name: string | null])[];
+        /** 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'> {
@@ -973,6 +786,8 @@ export declare namespace Calculation {
         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}. */
@@ -994,6 +809,15 @@ export declare namespace Calculation {
          * @see {@link FunctionProvider}
          */
         functions?: readonly FunctionProvider[];
+        /**
+         * Custom functions to register at every start, ahead of the first pass: a workbook's script
+         * functions, so a formula calling one calculates on load rather than answering `#NAME?`.
+         *
+         * @remarks
+         * Asked once per start, alongside loading the engine. A function the registry refuses (a
+         * built-in's name) is reported and skipped; the start goes on with the rest.
+         */
+        startFunctions?: () => Promise<readonly IFunction[]>;
         /**
          * Returns the active cell — the current selection anchor — with its sheet id as `scope`.
          * Supplies the default scope for temporary / named-formula resolution, and the default
@@ -1051,6 +875,15 @@ export declare namespace Calculation {
         getSheetIndex?: (sheetName?: string) => number;
         getSheetCount?: () => number;
         strings?: IStringCollection;
+        /**
+         * The workbook's binary resources (image bytes), for rich values a formula makes.
+         */
+        resources?: IResourceCollection;
+        /**
+         * The workbook's fetch, for async functions (`IFormulaContext.IBatchContext.fetch`). Omitted,
+         * the global `fetch`.
+         */
+        fetch?: (input: string, init?: RequestInit) => Promise<Response>;
         /**
          * Whether to perform iterative calculations when there are circular dependencies.
          *
@@ -1090,70 +923,5 @@ interface HeldRequest {
     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.
-     *
-     * @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, 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)[];
-}
 export {};
 //# sourceMappingURL=Calculation.d.ts.map