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

package/types/src/calculation/engine/CalcBackend.d.ts

@@ -0,0 +1,855 @@
+import { IRange, IFormulaContext, IRuntime, Scalar } from '@sheetxl/primitives';
+import { FunctionProvider } from '@sheetxl/scripting';
+import { AbstractModel, IModel } from '../../model';
+import { ITransaction } from '../../transaction';
+import { ISpatialMap, ISpatialQuery, ISpatialMap3D, ISparseGrid } from '../../collections';
+import { IExternalBookCollection } from '../../externalBook';
+import { ICalculation } from '../ICalculation';
+import { NamedNodeInfo } from '../Types';
+import { TableExtent } from '../_TableExtent';
+import { IFormulaCompiler } from '../compiler';
+import { FormulaBlockResolvers, IFormulaBlock, FormulaImager } from '../formula';
+import { CalculationContext } from '../state/CalculationContext';
+import { IContextContainer, CalcNode, CalcScope } from '../state';
+import { PrecedentSpatialValue, PrecedentKind } from '../spatial';
+import { FormulaSpatialValue } from '../spatial/FormulaSpatialValue';
+import { CalcExecutor } from '../executor/CalcExecutor';
+import { CalcGridBackend } from '../grid/CalcGridBackend';
+import { ICalcGrid, FormulaHost } from '../grid';
+import { CalcRequest, CalcResponse, CalcGridSpec, TableSymbols, NameSymbols } from '../grid/_CalcRequest';
+import { ExternalBookBindings, ExternalNamedItem } from '../ExternalBookBindings';
+import { ISymbolRegistry } from '../symbol';
+/**
+ * The calculation backend: the engine's store and everything kept in it, and the container its
+ * grids, formulas and executor work against (DESIGN-CALC-SERVICE §5).
+ *
+ * @remarks
+ * Made by the first `start()` from the loaded engine module, and kept across a stop and a restart.
+ * Its history is its own (§13.13): every model commit has a mirror here, a request lands under the
+ * model's operation or savepoint it was made in, and a revert names a model commit. The model's ids
+ * are known to it through one map, landing to engine commit.
+ *
+ * What it asks of the calculation that made it is {@link CalcBackend.Callbacks}, and nothing else.
+ */
+export declare class CalcBackend extends AbstractModel<CalcBackend.State> implements IContextContainer {
+    protected _callbacks: CalcBackend.Callbacks;
+    protected _runtime: IRuntime;
+    protected _symbols: ISymbolRegistry;
+    protected _resolvers: FormulaBlockResolvers;
+    protected _getSheetIndex: ((sheetName?: string) => number) | null;
+    protected _legacyIntersect: boolean;
+    protected _gridOptions: Partial<CalcGridBackend.ConstructorOptions>;
+    protected _calculation: ICalculation;
+    protected _context: CalculationContext & IFormulaContext;
+    protected _calcExecutor: CalcExecutor;
+    /** The cache as grids and the cached names as virtual grids — see {@link ExternalBookBindings}. */
+    protected _externalBindings: ExternalBookBindings;
+    protected _calcScope: CalcScope;
+    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;
+    protected _calculatedEngineId: string | null;
+    /** The engine holds grids: from a start's boot until a stop. */
+    protected _holdsGrids: boolean;
+    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 _symbolIndex: Map<string, IRange.Coords[]> | null;
+    protected _symbolIndexOf: ISpatialMap3D<FormulaSpatialValue> | null;
+    private _sheetsDerived;
+    private _tablesDerived;
+    private _namesDerived;
+    /**
+     * The grid registry and the grid maps as the batch {@link applyHeld} applies has written them,
+     * held here and written to the state once when the batch ends.
+     *
+     * @remarks
+     * Outside a batch each registration and each publish copies the whole map into a state of its
+     * own, so that every snapshot stays what it was. Inside the start batch that is one copy per
+     * grid over every grid, and a load whose defined names each compile into a grid of their own
+     * (thousands, in a legacy file) made the start quadratic in them - in time, and in the copies the
+     * batch's commit kept alive until it ended. `null` outside a batch.
+     */
+    private _collecting;
+    /**
+     * The names whose readers a drain recompiles ({@link recompileNamed}) or marks
+     * ({@link invalidateNamed}), gathered until that drain: each is one scan of every formula, and
+     * a load wires every name it holds in one batch.
+     */
+    private _recompileNamedPending;
+    private _invalidateNamedPending;
+    constructor(options: CalcBackend.ConstructorOptions);
+    /** Initializes the context: the function registry the backend calls through. */
+    initialize(): ReturnType<CalculationContext['_initialize']>;
+    /** The context every formula block evaluates in. */
+    getContext(): CalculationContext & IFormulaContext;
+    /** {@inheritDoc IContextContainer.getRuntime} */
+    getRuntime(): IRuntime;
+    /** {@inheritDoc IContextContainer.getScope} */
+    getScope(): CalcScope;
+    /** {@inheritDoc IContextContainer.createFormulaBlock} */
+    createFormulaBlock(gridId: string, context: IFormulaContext, expression: string, rowIndex: number, colIndex: number, editing?: ICalculation.FormulaTarget, legacyIntersect?: boolean): IFormulaBlock;
+    /** {@inheritDoc IContextContainer.getSymbols} */
+    getSymbols(): ISymbolRegistry;
+    /**
+     * {@inheritDoc IContextContainer.resolveScope}
+     *
+     * @remarks
+     * Bound: a reference range is handed it as a function of its own.
+     */
+    resolveScope: (scope: string) => string | undefined;
+    /** {@inheritDoc IContextContainer.getSheetIndex} */
+    getSheetIndex(sheetName?: string): number;
+    /** {@inheritDoc IContextContainer.getSheetCount} */
+    getSheetCount(): number;
+    /** {@inheritDoc IContextContainer.getSheetIds} */
+    getSheetIds(): readonly string[];
+    /** {@inheritDoc IContextContainer.getSheetSpanIds} */
+    getSheetSpanIds(scopeId: string): string[] | null;
+    /** {@inheritDoc IContextContainer.getFormulas} */
+    getFormulas(): ISpatialMap3D<FormulaSpatialValue>;
+    /** {@inheritDoc IContextContainer.setFormulas} */
+    setFormulas(spatial: ISpatialMap3D<FormulaSpatialValue>): void;
+    /** {@inheritDoc IContextContainer.getPrecedents} */
+    getPrecedents(): ISpatialMap3D<PrecedentSpatialValue>;
+    /** {@inheritDoc IContextContainer.setPrecedents} */
+    setPrecedents(spatial: ISpatialMap3D<PrecedentSpatialValue>): void;
+    /** {@inheritDoc IContextContainer.getDynamics} */
+    getDynamics(): Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>;
+    /** {@inheritDoc IContextContainer.setDynamics} */
+    setDynamics(map: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>): void;
+    /** {@inheritDoc IContextContainer.addDynamicPrecedent} */
+    addDynamicPrecedent(node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
+    /** {@inheritDoc IContextContainer.getVolatiles} */
+    getVolatiles(): Set<CalcNode>;
+    /** {@inheritDoc IContextContainer.isLegacyIntersect} */
+    isLegacyIntersect(): boolean;
+    /** {@inheritDoc IContextContainer.getGridValues} */
+    getGridValues(gridId: string): ISparseGrid<Scalar>;
+    /** {@inheritDoc IContextContainer.getIncrementalUpdates} */
+    getIncrementalUpdates(gridId: string): ICalcGrid.IncrementalUpdates | null;
+    /** {@inheritDoc IContextContainer.registerGrid} */
+    registerGrid(grid: CalcGridBackend): void;
+    /** {@inheritDoc IContextContainer.unregisterGrid} */
+    unregisterGrid(gridId: string): void;
+    /** The grids by id, as the open batch has them, else as the state does. */
+    protected _gridsAll(): Map<string, CalcGridBackend>;
+    /**
+     * Writes the grid registry: a copy of its own in the state, or the open batch's copy, which
+     * reaches the state when the batch ends. See {@link _collecting}.
+     */
+    private _writeGridsAll;
+    /** {@link _writeGridsAll}, for the grid maps. */
+    private _writeGridMaps;
+    /**
+     * Runs `batch` with the grid registry and maps collected, and writes them to the state once after;
+     * its requests share one clone key (see {@link getHeldCloneKey}) unless the caller set one.
+     *
+     * @remarks
+     * A held batch's, and a burst of defined-name compiles' (`NamedFormulaCollection._materializeMany`):
+     * both make many grids under one engine operation, and without this each grid's registration is
+     * a write that copies a registry holding an entry per sheet and per compiled name.
+     * @internal
+     */
+    _collectingGrids<R>(batch: () => R): R;
+    /** {@inheritDoc IContextContainer.getGrid} */
+    getGrid(gridId: string): CalcGridBackend | null;
+    /** {@inheritDoc IContextContainer.markDirty} */
+    markDirty(dirtyRegions: ISpatialMap.Entry[]): boolean;
+    /** {@inheritDoc IContextContainer.getDirtyGrid} */
+    getDirtyGrid(gridId: string): ISpatialQuery;
+    /** {@inheritDoc IContextContainer.calculateGrid} */
+    calculateGrid(gridId: string, options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /** {@inheritDoc IContextContainer.requestCalculateGrid} */
+    requestCalculateGrid(gridId: string): void;
+    /** {@inheritDoc IContextContainer.getCycleId} */
+    getCycleId(): number;
+    /** {@inheritDoc IContextContainer.getCalculatedCommitId} */
+    getCalculatedCommitId(): string | null;
+    /**
+     * {@inheritDoc IContextContainer.landRequest}
+     *
+     * @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.
+     */
+    landRequest<R>(landingId: string | undefined, action: () => R): R;
+    /** {@inheritDoc IContextContainer.sendRequest} */
+    sendRequest(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
+    /** {@inheritDoc IContextContainer.getImager} */
+    getImager(gridId: string): FormulaImager;
+    /** {@inheritDoc IContextContainer.setGridMaps} */
+    setGridMaps(gridId: string, maps: object): void;
+    /** {@inheritDoc IContextContainer.recordTouched} */
+    recordTouched(gridId: string, regions: readonly IRange.Coords[]): void;
+    private _recordTouchedNow;
+    /** {@inheritDoc IContextContainer.revertTo} */
+    revertTo(commitId: string, gridId: string): IRange.Coords[] | null;
+    /** {@inheritDoc IContextContainer.getCalcEpochs} */
+    getCalcEpochs(): {
+        staticEpoch: number;
+        precedentEpoch: number;
+    };
+    /** {@inheritDoc IContextContainer.bumpCalcEpochs} */
+    bumpCalcEpochs(includeStatic: boolean): void;
+    /** {@inheritDoc IContextContainer.getNow} */
+    getNow(): number;
+    /** {@inheritDoc IContextContainer.whenSafe} */
+    whenSafe(action: () => Promise<unknown>): void;
+    /** {@inheritDoc IContextContainer.isLoading} */
+    isLoading(): boolean;
+    /** {@inheritDoc IContextContainer.recompileNamed} */
+    recompileNamed(nameId: string): void;
+    /** {@inheritDoc IContextContainer.invalidateNamed} */
+    invalidateNamed(nameId: string): void;
+    /** {@inheritDoc IContextContainer.getNamedNodeInfo} */
+    getNamedNodeInfo(nameId: string, live?: boolean): NamedNodeInfo | null;
+    /**
+     * {@inheritDoc IContextContainer.getNamedDependents}
+     *
+     * @remarks
+     * The bucket for a NAME out of {@link getSymbolDependents}: one index for every symbol kind.
+     */
+    getNamedDependents(nameId: 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 the calculation 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.
+     */
+    getNamedDependentNames(nameId: string): ReadonlySet<string>;
+    /** A grid of the backend's, registered. */
+    createBackendGrid(options?: CalcGridBackend.ConstructorOptions): CalcGridBackend;
+    /**
+     * The engine's grid for a model grid, as a `create` describes it. What it pushes reaches the
+     * model grid under the same id.
+     */
+    createEngineGrid(spec: CalcGridSpec): CalcGridBackend;
+    /** The engine holds grids from here: an external book's cache is the engine's own content, made now. */
+    open(): void;
+    /**
+     * The engine's graph and every grid in it, gone: what a stop leaves, and what a rebuild starts
+     * from. The model's grids are untouched.
+     */
+    drop(): void;
+    /** Every grid the engine holds, by id. */
+    getGrids(): ReadonlyMap<string, CalcGridBackend>;
+    /**
+     * Brings the external books' grids and cached names into step with the collection.
+     *
+     * @remarks
+     * The first, `initial`, is made once the calculation holds this backend: binding a cached name
+     * looks the name up through the calculation's symbols, which ask the backend for it.
+     *
+     * @param initial The sync made when the backend is, before any formula has compiled.
+     * @returns The ids of the books whose grids or names changed.
+     */
+    syncExternalBooks(initial?: boolean): ReadonlySet<string>;
+    /** A cached name of an external book, by the id its virtual grid is registered under. */
+    getExternalName(id: string): ExternalNamedItem | null;
+    /** A cached name of an external book, by its spelling within a book's scope. */
+    getExternalNameByScope(name: string, scopeId: string): ExternalNamedItem | null;
+    /**
+     * Applies one request from the channel: the service's own (`sheets`, `tables`, `names`,
+     * `rollback`, `create`) here, a grid's on its grid. A request for a grid the engine does not hold
+     * is answered with nothing.
+     *
+     * @param held The request was held while the engine came up: it lands under the engine's
+     * current commit, whose snapshot it was made at has been mirrored already.
+     * @throws What the grid throws applying it.
+     */
+    apply(gridId: string, landingId: string | undefined, request: CalcRequest, held?: boolean): CalcResponse | PromiseLike<CalcResponse>;
+    /**
+     * Applies what the channel held while the engine came up (DESIGN-CALC-SERVICE §6.3): every
+     * grid made first, then a defined name's body, in its own order (`ICalcGrid.BodyOptions.priority`),
+     * then the rest in send order. A name must be bound before any formula that mentions it is
+     * examined, and each is held behind the create of its own grid.
+     *
+     * @remarks
+     * Every sheet a held `sheets` message adds enters the replica at its end first, 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. Every table a held `tables` message adds enters the same way, under the
+     * name and columns it was first told by: a seed sent ahead of a later sheet's tables compiles a
+     * reference to one, and a reference to a table the replica does not hold is refused. The messages
+     * themselves still apply in send order, so a seed sent before a rename binds the name it was sent
+     * under.
+     *
+     * A request whose snapshot the model has undone since (`dead`) is answered and not applied,
+     * except a grid's `create`.
+     *
+     * @param wroteWhileOff Something was written while the engine was `Off`: a seed asking for a
+     * full pass keeps it. Otherwise its values are the engine's own, or a file's.
+     * @returns What each request answered, in the order they were applied.
+     */
+    applyHeld(batch: readonly CalcBackend.Held[], wroteWhileOff: boolean): CalcBackend.Applied[];
+    /** {@inheritDoc IContextContainer.getHeldCloneKey} */
+    getHeldCloneKey(): string | null;
+    /** See {@link getHeldCloneKey}. */
+    private _heldCloneKey;
+    protected _applyHeldNow(batch: readonly CalcBackend.Held[], wroteWhileOff: boolean): CalcBackend.Applied[];
+    /**
+     * The model restored itself to `commitId`: the engine restores its own history there.
+     *
+     * @remarks
+     * An engine that is not up holds nothing to restore; it answers for the model's snapshot from
+     * here, and its start opens from it. One coming up holds the start's replicas, made after any
+     * commit it has no mirror of: restored where it has one, otherwise it answers for the
+     * snapshot. A `Running` one whose history does not reach the commit (one from before its
+     * start, or trimmed since) is rebuilt from the model as it is there.
+     *
+     * @param status The calculation's status now.
+     * @returns Whether a rebuild is owed.
+     */
+    followRestore(commitId: string, status: ICalculation.Status): boolean;
+    /**
+     * The engine made again from the model, as a start makes it: its graph dropped, its replicas as
+     * given, the external books' grids made. The model's grids are opened behind it, and its history
+     * starts there ({@link forgetEarlierLandings}).
+     */
+    rebuild(replica: CalcBackend.Replica): void;
+    /**
+     * Compiles an expression at a cell without writing it anywhere: what `ICalculation.createFormula`
+     * is built on.
+     *
+     * @remarks
+     * A `virtual` formula is held in a grid of its own (`temporary`), compiled as if written on
+     * `gridId`. It compiles with the `'editing'` profile, in `target`'s form: the text exactly as
+     * typed, and as much structure as a partial parse recovers (see FormulaCompilerProfile).
+     *
+     * @returns `null` when the grid the formula is anchored in does not exist.
+     */
+    compileTemporary(expression: string, at: CalcBackend.TemporaryAt): CalcBackend.Temporary | null;
+    /**
+     * Formula text as a cell of `gridId` at (`rowIndex`, `colIndex`) would store it, without writing
+     * it anywhere: compiled for storage, so `[#This Row]` becomes `@` and an unqualified structured
+     * reference is given the name of the table it binds to there.
+     */
+    toStoredText(gridId: string, expression: string, rowIndex: number, colIndex: number): string;
+    /**
+     * 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 {@link recompileReferencing} 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.
+     */
+    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[]>;
+    /**
+     * `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 {@link recompileReferencing} 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: ReadonlySet<string>): ReadonlySet<string>;
+    /**
+     * Reverse-invalidates only the formulas that reference any of `changedIds` — the stable name/table
+     * fake ids reported by `IndirectSymbolProvider.reconcile()` (add/heal, delete, rename).
+     *
+     * @remarks
+     * `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 {@link recompileReferencing}.
+     *
+     * @returns `true` if any formula was marked dirty.
+     */
+    markDirtyReferencing(changedIds: ReadonlySet<string>): boolean;
+    /**
+     * Recompiles every formula that references any of `changedIds` — a name or a table, directly or
+     * through a name — from its own text, so it re-derives its precedents.
+     *
+     * @remarks
+     * The re-wire half of {@link markDirtyReferencing}. A node stores the coords its references
+     * resolved to when it was wired, and `precedentSpatial` indexes those, so a symbol that now
+     * designates different cells (a name redefined, a table resized) leaves its readers evaluating
+     * against the old edges; a dirty mark does not reach them. Same `all3D` scan and the same
+     * {@link _namedTargets} expansion: a name whose body cites the symbol reaches its own readers.
+     *
+     * Run at a safe point only — it writes inputs.
+     */
+    recompileReferencing(changedIds: ReadonlySet<string>): void;
+    /**
+     * A table's body has changed rows: re-fit the A1 references that spanned it.
+     *
+     * @remarks
+     * Excel treats a reference whose ROWS are exactly a table's body - or run from its header to the
+     * body's end - as naming the body, whatever columns of the table it covers, and keeps it on the
+     * body however the body's rows change (probed, `probe-table-refit.ps1`): `SUM(B2:B5)` over body
+     * rows 2-5 reads `SUM(B2:B6)` after a row is appended, and `SUM(B2:B3)` after a resize gives two
+     * up. Relative, absolute or mixed alike, from any sheet, and in anything that holds a reference -
+     * a defined name, a table's held totals formula and a condition's formula are blocks too. A
+     * reference that only starts or only ends with the body is an ordinary one, and a change of
+     * COLUMNS re-fits nothing. A name's relative rows are read from its body's origin, A1, as Excel
+     * reads them (`probe-table-refit-relative.ps1`); a shift never moves them, so a row at the top
+     * leaves such a name alone.
+     *
+     * An insert or delete inside the body already leaves such a reference right, so this is asked
+     * only for what a shift gets wrong: rows taken or given up at the body's end, and a row inserted
+     * at its first row (which pushes the whole reference down).
+     *
+     * One search of the precedent index over the rows that match - an entry per (block, reference)
+     * that reads them - so the cost is the readers of the body, on a change of a table's rows. The
+     * text a cell shows catches up with the engine the way it does after any shift.
+     *
+     * A block is re-fitted cell by cell: only the cells whose reference spans the body are rewritten,
+     * which splits them out of the block. An array-entered block is one formula, read at its top-left,
+     * and is never split.
+     *
+     * **A DELIBERATE DIVERGENCE lives here** (Michael, 2026-09-22). Excel asks how the cell was
+     * authored, not what it reads: a fully relative reference is left where it is when the cell
+     * belongs to a shared-formula group, and re-fitted when it stands alone - so `SUM(B2:B5)` follows
+     * the body when it was typed and does not when the same three formulas were filled, and the file
+     * carries the difference as `<f t="shared">` (`probe-table-refit-fillhandle.ps1`,
+     * `probe-table-refit-roundtrip.ps1`). Here a run is a data-model fact, not an authoring one -
+     * cells holding the same formula are conflated whatever made them - so honoring that rule would
+     * make a formula follow the body or not depending on what a NEIGHBOR happens to hold, which a
+     * user cannot see. Every reference that spans the body is re-fitted, however it was written.
+     *
+     * @param sheet The sheet the table is on, by id or name.
+     * @param columns The table's columns. A reference reaching outside them is an ordinary one.
+     * @param match The rows a reference has to span to be one of the body's, as they read NOW.
+     * @param headerRow The header's row when a reference from it to `match.rowEnd` also counts.
+     * @param to The body's rows now.
+     */
+    refitTableRows(sheet: string, columns: {
+        colStart: number;
+        colEnd: number;
+    }, match: {
+        rowStart: number;
+        rowEnd: number;
+    }, headerRow: number | null, to: {
+        rowStart: number;
+        rowEnd: number;
+    }): void;
+    /**
+     * Replaces every structured reference to `tableId` on a sheet: by its address in `extent`, or by
+     * `#REF!` when there is none. A name's body or an external book's cached formula is left: not
+     * text a user wrote on a sheet.
+     */
+    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;
+    /** Whether any cell is out of date. */
+    hasDirty(): boolean;
+    /**
+     * Runs one pass over the dirty set (or all of it, or a range of it), and writes what it found
+     * into the state.
+     *
+     * @remarks
+     * One recalculation per COMMIT, not per notification of one.
+     *
+     * `gridId` marks the engine's own reactive pass — `ICalcGrid.calculate()`, which is what an
+     * edit schedules (`Sheet.onAfterStateChange`) and what `ready()` runs per dirty grid. An
+     * explicit `calculate()` from the API (F9, Shift+F9, a resolved async result) has no `gridId`
+     * and is always honored.
+     *
+     * The reactive pass is skipped only when BOTH halves say there is nothing to do:
+     *
+     * - the current commit has already had its recalculation. Commits notify their listeners on
+     *   `setTimeout(0)`, so a script that writes N cells without awaiting queues N dispatchers,
+     *   none of which run until it yields. By then the store is at the LAST commit and every one
+     *   of those dispatchers asks for a pass over the same final state — N-1 of them describing
+     *   work another pass has already done.
+     * - nothing is dirty. The dirty set is cumulative and whichever pass runs first consumes all
+     *   of it, but a seed (`CalcGridBackend._seedNow`) marks dirty without producing a commit of its
+     *   own, so the commit id alone would strand it.
+     *
+     * Neither half alone is enough, and the second is emphatically not sufficient: an edit that
+     * marks nothing dirty is still a recalculation in Excel, and it is the only thing that re-rolls
+     * `RAND`/`NOW` — see the "unrelated edit" case in `graph/volatile.test.ts`.
+     *
+     * Together they were the whole cost of the round-trip workbook build (`functions-to-xlsx.ts`):
+     * 2,594 redundant passes, each re-evaluating every volatile in the workbook and everything
+     * downstream of it, for 49,289 of 52,917 total evaluations — 93% of the engine's work, still
+     * running six seconds after `ready()` had resolved. See DESIGN-CALC-PASS-GATING.md.
+     */
+    runPass(options: ICalculation.CalculateOptions | undefined, pass: CalcBackend.PassOptions): void;
+    /** Each grid with cells out of date runs its pass - every grid, when `full`. */
+    calculateGrids(full: boolean): Promise<void>;
+    /** The cells of every cycle the last pass found. */
+    getCycleCells(): ReturnType<CalcExecutor['getCycleCells']>;
+    /** Demand and plan counters and timings since construction or the last {@link resetStats}. */
+    getDemandStats(): ReturnType<CalcExecutor['getDemandStats']>;
+    /** Zeroes every counter and timing. */
+    resetStats(): void;
+    /** The executor's plan-cache mode - see `CalcExecutor.planCacheMode`. */
+    getPlanCacheMode(): 'off' | 'assert' | 'on';
+    /** Sets the executor's plan-cache mode. */
+    setPlanCacheMode(mode: 'off' | 'assert' | 'on'): void;
+    /** The sheet replica: grid id to name, in tab order. */
+    getSheets(): ReadonlyMap<string, string | null>;
+    /** The table replica: table id to its name and columns. */
+    getTables(): ReadonlyMap<string, TableSymbols>;
+    /** The name replica: name id to its spelling and scope sheet. */
+    getNames(): ReadonlyMap<string, NameSymbols>;
+    /** Replaces the three replicas at once: what a start or a rebuild seeds them with. */
+    setReplica(replica: CalcBackend.Replica): void;
+    /**
+     * Replaces the sheet 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.
+     */
+    applySheets(sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[]): void;
+    /** Enters each sheet the replica does not hold yet at its end, under the name given. */
+    enterSheets(sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[]): void;
+    /** Enters each table the replica does not hold yet, as given; as {@link enterSheets} does. */
+    enterTables(tables: ReadonlyMap<string, TableSymbols>): void;
+    /**
+     * Applies what a `tables` message carries to the table replica. A reference bound by a name the
+     * replica did not have yet heals to it now, as one to a table added does.
+     */
+    applyTables(changes: readonly (readonly [id: string, table: TableSymbols | null])[]): void;
+    /** Applies what a `names` message carries to the name replica, as {@link applyTables} does. */
+    applyNames(changes: readonly (readonly [id: string, name: NameSymbols | null])[]): void;
+    /** The table replica and its name index. */
+    getReplicaTables(): {
+        of: ReadonlyMap<string, TableSymbols>;
+        idByName: Map<string, string>;
+    } | null;
+    /** The name replica and its spelling index, as {@link getReplicaTables}. */
+    getReplicaNames(): {
+        of: ReadonlyMap<string, NameSymbols>;
+        idsByName: Map<string, string[]>;
+    } | null;
+    /**
+     * The name a spelling resolves to from `scope`, by the replica: that sheet's own name first, then
+     * the global; asked from no sheet, the global, else any scoped one - the collection's rule
+     * (`NamedFormulaCollection.getByName`). `undefined` when the replica cannot answer.
+     */
+    getReplicaNameId(name: string, scope: string | null | undefined): string | undefined;
+    /** A sheet's grid id by its name, as Excel reads sheet names: case-insensitively. `null` when none. */
+    getSheetIdByName(name: string): string | null;
+    /** {@inheritDoc IContextContainer.isGridless} */
+    isGridless(sheetId: string): boolean;
+    /** A sheet's name by its grid id, or `null` for a grid that is no sheet. */
+    getSheetName(gridId: string): string | null;
+    private _sheetsCache;
+    /** When the engine's current commit was made: the clock a pass reads `NOW` from. */
+    getCommitTimestamp(): number;
+    /** The engine's current commit: where a held request the start batch applies lands. */
+    getCurrentCommitId(): string;
+    /**
+     * 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.
+     */
+    mirror(commitId: string): void;
+    /** What the engine answers for from here - the model's snapshot - without restoring anything. */
+    retarget(commitId: string): void;
+    /** Whether the engine can restore to a model commit: it has a landing for it and still holds that commit. */
+    holdsModelCommit(commitId: string): boolean;
+    /** Forgets a landing, and the engine commit it made if it made one. */
+    dropLanding(landingId: string): 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. The model's commit now
+     * is the boot's.
+     */
+    forgetEarlierLandings(): void;
+    /**
+     * 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.
+     */
+    foldPhantom(rootId: string): void;
+    /**
+     * 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).
+     */
+    restoreTo(commitId: string): Map<string, IRange.Coords[]> | null;
+    /**
+     * A nested savepoint of the model rolled back: what the engine landed under it goes with it.
+     * What a `rollback` message does.
+     *
+     * @remarks
+     * The savepoint is still open while it rolls back, so every engine commit made after its own,
+     * under the same root, was landed by a savepoint nested in it, and goes too.
+     */
+    rollbackSavepoint(savepointId: string): void;
+    /** Whether the engine still holds a commit: its own record is in every commit made since it was built. */
+    protected _holdsEngineCommit(engineId: string): boolean;
+    /** Drops the landings whose engine commit the store has trimmed or pruned. Rare: sized by the store's cap. */
+    protected _sweepLandings(): void;
+    /**
+     * The engine commit an engine write made during a model operation lands in: the operation's
+     * root (`<id>:0`) or the nested savepoint open now. `null` outside an operation, or while a
+     * landing is already open (the write joins it).
+     */
+    protected _modelLanding(): string | null;
+    /**
+     * Engine state is never a step of history on its own: a write is attributed to the model
+     * operation it is made in, or folded into the current snapshot (a pass's bookkeeping).
+     */
+    protected _updateState(updateState?: Partial<CalcBackend.State>, options?: ITransaction.StoreOperationOptions, events?: (keyof IModel.Events)[]): this;
+    protected _amendState(updateState?: Partial<CalcBackend.State>, options?: ITransaction.StoreOperationOptions, events?: (keyof IModel.Events)[]): this;
+    /**
+     * A restore moves every grid to another snapshot and reports nothing, so each grid adopts the
+     * maps the snapshot holds for it, and the calculation is told.
+     */
+    protected _processRestoreOrRevert(state: CalcBackend.State, commit: ITransaction.ICommit): void;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}
+/**
+ * Interfaces for creating a {@link CalcBackend}.
+ */
+export declare namespace CalcBackend {
+    /**
+     * What the backend asks of the calculation that made it: the in-process half of the backend's
+     * interface. Everything else it reads it was given at construction, as data.
+     */
+    interface Callbacks {
+        /** The compiler for stored text, or the editing one for `target`; `null` before a start has loaded one. */
+        getCompiler(target?: ICalculation.FormulaTarget): IFormulaCompiler | null;
+        /** The landing of the model operation open now - its root `<id>:0` or its nested savepoint - or `null` outside one. */
+        getModelLanding(): string | null;
+        /** Sends a grid's request through the calculation's channel. */
+        sendRequest(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
+        /** What images a grid's records for the model. */
+        getImager(gridId: string): FormulaImager;
+        /** A pass's or a seed's results for a model grid: pushed to the grid under the same id. */
+        onCalculated(gridId: string, results: ICalcGrid.Results): void;
+        /** The engine's store was restored: what the calculation's own listeners and its hosts are told. */
+        onRestored(): void;
+        /** Something was marked out of date: the calculation state may have changed. */
+        onDirty(): void;
+        /** A replica of tables or names changed: what its symbols resolve to now is reconciled. */
+        onSymbolsChanged(kind: 'tables' | 'names'): void;
+        /** Runs an action at the calculation's next safe point; a `priority` one ahead of the rest. */
+        whenSafe(action: () => Promise<unknown>, priority: boolean): void;
+        /** Whether the calculation is loading: draining, or starting. */
+        isLoading(): boolean;
+        /** Runs a pass: explicit without `gridId`, reactive for it with one. */
+        calculate(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
+        /** Owes a reactive pass for `gridId`, run once the current flush is over. */
+        owePass(gridId: string): void;
+        /** Whether a grid id is a defined name's: its virtual grid's id is the name's. */
+        isDefinedName(gridId: string): boolean;
+        /** A defined name as a node of the dependency graph, or `null` when there is no such name. */
+        getNameNodeInfo(nameId: string): NamedNodeInfo | null;
+        /** A table by its stable id, as it is now, or `null` when it is gone: what a structured reference resolves against. */
+        getTable(tableId: string): TableExtent | null;
+        /**
+         * Writes `text` over `coords` of a formula host's body, where the model holds it.
+         * @returns `false` when no host holds the grid.
+         */
+        rewriteHost(gridId: string, coords: IRange.Coords, text: string): boolean;
+        /** A virtual grid for an external book's cached name, as a host. */
+        createHost(id: string): FormulaHost;
+        /** The id the named-formula symbols give a name defined in `scopeId`. */
+        bindNameId(name: string, scopeId: string): string;
+    }
+    /** A request the channel held while the engine came up: see {@link CalcBackend.applyHeld}. */
+    interface Held {
+        gridId: string;
+        request: CalcRequest;
+        /** The model snapshot it was made at. */
+        commitId: string | undefined;
+        /** The model has undone the snapshot it was made at since. */
+        dead: boolean;
+    }
+    /** What one held request answered: its response, or what applying it threw. */
+    interface Applied {
+        /** Its position in the batch. */
+        index: number;
+        response?: CalcResponse | PromiseLike<CalcResponse>;
+        error?: unknown;
+        failed?: boolean;
+    }
+    /** Where a formula held apart from any grid is compiled: see {@link CalcBackend.compileTemporary}. */
+    interface TemporaryAt {
+        /** The sheet it is written on, or the one a virtual formula is compiled as if on. */
+        gridId: string | null;
+        /** Held in a grid of its own rather than on `gridId`. */
+        virtual: boolean;
+        rowIndex: number;
+        colIndex: number;
+        target: ICalculation.FormulaTarget;
+    }
+    /** A formula held apart from any grid: its block, the grid it is anchored in, and its evaluation. */
+    interface Temporary {
+        block: IFormulaBlock;
+        calcGrid: CalcGridBackend;
+        /** The grid it is anchored in: its sheet, or `temporary`. */
+        gridId: string;
+        /** Evaluates `block` - this one, or a repair of it - at the formula's cell. */
+        evaluate(block: IFormulaBlock, evalIndex: number | undefined, alwaysReturnRange: boolean): Scalar | IRange;
+    }
+    /** The three replicas, as a start seeds them. */
+    interface Replica {
+        sheets: ReadonlyMap<string, string | null>;
+        /** The sheets in {@link sheets} that have no grid: chart, macro and dialog sheets. */
+        gridless?: ReadonlySet<string>;
+        tables: ReadonlyMap<string, TableSymbols>;
+        names: ReadonlyMap<string, NameSymbols>;
+    }
+    /** What a pass is: see {@link CalcBackend.runPass}. */
+    interface PassOptions {
+        /** A full pass; when absent, whether one is owed. */
+        full?: boolean;
+        /** The cells to calculate, when only a range is. */
+        calcCoords?: IRange.Coords;
+        /** The grid whose reactive pass this is; absent for an explicit one. */
+        gridId?: string;
+        /** Iterative calculation's limits, or `null` when it is off. */
+        iterate: {
+            maxIteration: number;
+            maxChange: number;
+        } | null;
+        /** The model operation open now: what the pass's results are realized under. */
+        openOperationId: string | null;
+    }
+    interface ConstructorOptions {
+        callbacks: Callbacks;
+        /** The runtime formulas evaluate against. */
+        runtime: IRuntime;
+        /** The symbols formulas bind through. */
+        symbols: ISymbolRegistry;
+        /** What every formula block resolves structured references and names through. */
+        resolvers: FormulaBlockResolvers;
+        /** Function providers bound after the built-ins. */
+        functions?: readonly FunctionProvider[];
+        /** The owner's selected sheet, and a sheet position by a name the replica does not hold. */
+        getSheetIndex?: (sheetName?: string) => number;
+        /** The file asks for Excel's legacy implicit intersection. */
+        legacyIntersect?: boolean;
+        /** Options every grid of the backend's is made with. */
+        gridOptions?: Partial<CalcGridBackend.ConstructorOptions>;
+        /** The calculation the grids report their status and readiness through. */
+        calculation: ICalculation;
+        /** The external books the bindings mirror. */
+        books: IExternalBookCollection;
+        /** The replicas as the owner holds them when the start was asked for. */
+        replica?: Replica;
+        /** The model's current commit, mirrored first. */
+        modelCommitId?: string | null;
+        /** A plan-cache mode set before the backend existed. */
+        planCacheMode?: 'off' | 'assert' | 'on' | null;
+    }
+    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 sheets in {@link sheets} that have no grid: chart, macro and dialog sheets. They count in
+         * tab order (`SHEETS`, `SHEET`, a span's members) and hold no cells.
+         */
+        gridless: ReadonlySet<string>;
+        /**
+         * 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>;
+    }
+}
+//# sourceMappingURL=CalcBackend.d.ts.map