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

package/types/src/calculation/state/CalcNode.d.ts

@@ -1,43 +1,56 @@
 import { Scalar, FormulaError, IRange } from '@sheetxl/primitives';
 import { ISpatialMap } from '../../collections';
 import { PrecedentSpatialValue, FormulaSpatialValue } from '../spatial';
-export interface CalcNode {
-    block: FormulaSpatialValue;
-    gridId: string | null;
-    colIndex: number;
-    rowIndex: number;
-    cycleId: number;
-    markId: number;
-    inDegree: number;
-    /**
-     * Cached result of a spatial search: all ISpatialMap.Entry<PrecedentSpatialValue> blocks whose formula ranges
-     * overlap this cell.
-     * Populated once during the mark phase (the BFS upward-walk), then reused by the topological sort to decrement.
-     */
-    dependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
+/**
+ * The fields of a node that only a MINORITY of nodes ever need: the ones a spill anchor, a cycle
+ * node, an async formula or an array-entered block carries. Allocated on first write
+ * ({@link calcNodeExt}) and `null` on every node that is none of those — which, in a real
+ * workbook, is nearly all of them.
+ *
+ * @remarks
+ * One object rather than one per feature. Three nullable pointers (spill, cycle, async) would
+ * cost three slots on every node to save nine, and would put three shapes behind the reads;
+ * one costs a single slot and leaves each `ext.*` site monomorphic, because a site is only
+ * reached once `ext !== null`.
+ *
+ * Every field here keeps the meaning it had on the node, so a reader that has an ext in hand
+ * reads it exactly as before. A reader that does NOT is reading a node with none of these
+ * features, and the defaults in {@link calcNodeExt} are what it would have found.
+ */
+export interface CalcNodeExt {
     /**
-     * Parallel to `precedents`. One slot per static precedent, in formula order.
-     * Populated by the push model: after CalcNode N evaluates, N writes cachedValue into
-     * each dependent D's inputs[entry.value.index]. Range-typed slots are filled by a
-     * mid-cycle ReferenceRange (see doEvaluate range branch). Read by CalculationContext
-     * during evaluateAt() to resolve formula argument values.
-     * Undefined slots mean the precedent is a constant cell — CalculationContext falls back to the grid.
+     * The precedent entries that read this node's spill BODY — its extent minus the anchor cell.
+     * Recomputed by the mark phase, and never cached across passes: it is keyed by an extent the
+     * pass can change.
+     *
+     * @remarks
+     * Body cells hold the anchor's output but no formula of their own, so neither `dependents`
+     * (searched at the anchor cell) nor `formulaSpatial` (which has no body entry) knows their
+     * readers. These entries make the anchor stand in for its whole extent — both for discovery and
+     * for the in-degree/decrement pair, so a reader whose reference never touches the anchor is
+     * still ordered after it. Walked with `visitSpillBodyBlock`, which excludes the anchor cell's
+     * own readers so each edge is counted exactly once. See {@link spillRowEnd}.
      */
-    inputs: (Scalar | IRange | IRange.Coords | undefined)[];
+    spillDependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
     /**
-     * Coordinate ranges for every static precedent in formula order, parallel to `inputs`.
-     * Pre-filled at CalcNode construction from resolvedPrecedentsAt(cellRow, cellCol).
-     * Errors (FormulaError.Known) appear where the reference resolves to an invalid range (#REF! etc.).
-     * Read by CalculationContext for runtime value lookups and by the mark phase for inDegree computation.
+     * The bottom-right of the spill extent {@link spillDependents} was searched over; the top-left
+     * is the node's own position. `-1` whenever that list is empty — a node that does not spill, and
+     * equally one whose body nothing reads.
      */
-    precedents: (IRange.Coords | FormulaError.Known)[];
+    spillRowEnd: number;
+    spillColEnd: number;
     /**
-     * The cached value of the cell after evaluation.
+     * The extent of the array-entered (Ctrl+Shift+Enter) block this node anchors, or `null` for an
+     * ordinary formula. Absolute, unscoped.
      *
      * @remarks
-     * This is `undefined` if not calculated.
+     * Carried on the node, not inferred from the cached value or the spill map: a fixed block's
+     * result is fitted to this extent — 1x1 for the overwhelming majority — so the cached value is a
+     * scalar and never says "spill". The executor's fixed branch selects on this alone; the
+     * `SpillEntry` it writes is the persisted image. Set at load from a `fixed` `formulaArray` entry
+     * and by `setInputs` with a `arrayFixed`; translated with the node when its block moves.
      */
-    cachedValue: Scalar | IRange | undefined;
+    fixedRef: IRange.Coords | null;
     pendingPromise: Promise<any> | null;
     /**
      * The demand evaluation's result — finalized for the cell, or a pending promise — which
@@ -60,9 +73,102 @@ export interface CalcNode {
     /**
      * The cycle the sheet's circular index currently shows this cell in (`0` none) — what the last
      * commit wrote, so the next can write the delta. Persists across passes, unlike
-     * {@link cycleGroup}; the role it shows is the `CalcState.ShownRoleMask` field of {@link state}.
+     * {@link cycleGroup}; the role it shows is the `CalcState.ShownRoleMask` field of
+     * `CalcNode.state`.
      */
     shownGroup: number;
+}
+/**
+ * The node's {@link CalcNodeExt}, created on first ask.
+ *
+ * @remarks
+ * Only ever called from a write path — a node acquiring one of the features the ext carries.
+ * A READ must go through `node.ext` and treat `null` as the defaults set here, so that reading a
+ * node never gives it an ext it does not need.
+ */
+export declare const calcNodeExt: (node: CalcNode) => CalcNodeExt;
+/**
+ * The node's static precedent edges, absolute — its own stored list, or the block's template
+ * materialized for its cell.
+ *
+ * @remarks
+ * A templated answer is the BLOCK's buffer and is valid only until the next ask (see
+ * `FormulaSpatialValue.getPrecedentsAt`): read it inside the loop that asked for it, and copy
+ * anything you intend to keep. Every consumer in the engine already does.
+ */
+export declare const nodePrecedents: (node: CalcNode) => (IRange.Coords | FormulaError.Known)[];
+/**
+ * How many input slots the node needs — one per static precedent.
+ *
+ * @remarks
+ * Read off the stored list where there is one, and off the block's template where there is not,
+ * so the count never has to materialize a cell's edges. The two agree: a template contributes one
+ * edge per root reference at every cell.
+ */
+export declare const nodeParamLength: (node: CalcNode) => number;
+export interface CalcNode {
+    block: FormulaSpatialValue;
+    gridId: string | null;
+    colIndex: number;
+    rowIndex: number;
+    cycleId: number;
+    markId: number;
+    inDegree: number;
+    /**
+     * Cached result of a spatial search: all ISpatialMap.Entry<PrecedentSpatialValue> blocks whose formula ranges
+     * overlap this cell.
+     * Populated once during the mark phase (the BFS upward-walk), then reused by the topological sort to decrement.
+     */
+    dependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
+    /**
+     * Where this node's input slots start in the pass's shared arena (`CalcInputs`), or `-1` for a
+     * node with no precedents — and for one no mark phase has reached, whose slots would be read as
+     * empty and fall through to the grid.
+     *
+     * @remarks
+     * One slot per static precedent, in formula order — `precedents.length` of them, the same
+     * parallel the per-node array had. Populated by the push model: after CalcNode N evaluates, N
+     * writes its cached value into each dependent D's slot `entry.value.index`. Range-typed slots
+     * are filled by a mid-cycle ReferenceRange (see doEvaluate range branch). Read by
+     * CalculationContext during evaluateAt() to resolve formula argument values. An empty slot means
+     * the precedent is a constant cell — CalculationContext falls back to the grid.
+     *
+     * The slots live in the arena rather than in an array per node because they are pass scratch:
+     * cleared by the mark phase, written and read within the one pass, and never read between
+     * passes. A million nodes holding a two-element array each is a million allocations, and none
+     * of them survives the pass that fills it.
+     */
+    inputsAt: number;
+    /**
+     * Coordinate ranges for every static precedent in formula order, parallel to the node's arena
+     * slots — or `null` when the block carries a precedent TEMPLATE and the edges are materialized
+     * on demand instead. Read through {@link nodePrecedents}, never directly.
+     *
+     * @remarks
+     * Where it is set, it is pre-filled at CalcNode construction from
+     * `resolvedPrecedentsAt(cellRow, cellCol)`, and errors (FormulaError.Known) appear where the
+     * reference resolves to an invalid range (#REF! etc.). Read by CalculationContext for runtime
+     * value lookups and by the mark phase for inDegree computation.
+     *
+     * `null` is the common case: a formula whose references are plain A1 refs has the same edges at
+     * every cell of its block, at that cell's own offset, so the block keeps ONE relative template
+     * and one buffer rather than an array of fresh coord objects per cell. See
+     * `IFormulaBlock.getPrecedentTemplate`.
+     */
+    precedents: (IRange.Coords | FormulaError.Known)[] | null;
+    /**
+     * The cached value of the cell after evaluation.
+     *
+     * @remarks
+     * This is `undefined` if not calculated.
+     */
+    cachedValue: Scalar | IRange | undefined;
+    /**
+     * The number format a function supplied for this cell's result during its evaluation
+     * (`IFormulaContext.formatResults`), held until the results are written and reported
+     * (`ICalcGrid.Results.formatInserts`); `null` when none did. Cleared by the write.
+     */
+    numFmt: string | null;
     /**
      * Position of this node in the last FULLY-ORDERED plan that stamped it (CALC-PERFORMANCE-PLAN.md
      * §1.2). Meaningful only when {@link planId} and {@link planEpoch} match the executor's current
@@ -94,5 +200,10 @@ export interface CalcNode {
      * pass on purpose.
      */
     state: number;
+    /**
+     * The spill / cycle / async / array-entered fields, or `null` on a node that is none of those.
+     * See {@link CalcNodeExt}; write through {@link calcNodeExt}, read defensively.
+     */
+    ext: CalcNodeExt | null;
 }
 //# sourceMappingURL=CalcNode.d.ts.map

package/types/src/calculation/state/CalcScope.d.ts

@@ -24,6 +24,43 @@ export interface CalcScope {
      * 0 for an ordinary cell. Enforces the LAMBDA recursion limit (Step 14).
      */
     depth: number;
+    /**
+     * The implicit-intersection mode of the call being dispatched — `true` is Excel's VALUE mode,
+     * `false` ARRAY mode. Copied from the call node's compile-time annotation
+     * (`ASTNode.implicitIntersect`) around each dispatch by `FormulaBlock._callFunction`, read
+     * through `IFormulaContext.isImplicitIntersect`.
+     */
+    implicitIntersect: boolean;
+    /**
+     * Whether the call being dispatched is under a first-cell demand: only element `[0,0]` of its
+     * result is read, so a lift builds that one element. `true` only inside a block whose cells are
+     * each their own 1x1 array-entered extent (`FormulaSpatialValue.arrayFirstCell`), for a call the
+     * compiler annotated (`ASTNode.firstCell`). Set around each dispatch by
+     * `FormulaBlock._callFunction` and taken by the typed dispatch on entry
+     * (`CalculationContext._takeFirstCell`), so a body that calls another function directly never
+     * inherits it.
+     */
+    firstCell: boolean;
+    /**
+     * Set when the evaluation read something that is PER CELL rather than a property of its inputs
+     * — a random draw (`IFormulaContext.getRandom`), a position (`getRow`, `getColumn`, `getFormulaAt`,
+     * `getSheetIndex`, a reference's `getCoords`), or a reference it computed (a dynamic precedent)
+     * — so its answer cannot stand in for another cell's even when the two cells' inputs are
+     * identical. Cleared by whoever evaluates a cell as the representative of a block's blank
+     * region and read at its finalize (PLAN-WATCHES-BLANK-AWARE §4); a cell evaluated on its own
+     * behalf never reads it.
+     */
+    perCellRead: boolean;
+    /**
+     * How many draws (`IFormulaContext.getRandom`) this evaluation has taken, from `0`.
+     *
+     * @remarks
+     * A seeded draw is keyed by the cell and the pass, so a cell taking two of them — `RAND()+RAND()`,
+     * or one per element of a `RANDARRAY` — needs something to tell them apart. Reset wherever an
+     * evaluation begins, alongside `rowIndex`/`colIndex`, so a retried cell draws what it drew
+     * before. Ignored when no seed is set.
+     */
+    drawIndex: number;
     /**
      * Stable nameIds currently on the resolution stack — the cycle guard for named
      * formulas. A plain name re-entering itself (`X = X + 1`) is a circular reference.

package/types/src/calculation/state/CalcState.d.ts

@@ -34,7 +34,8 @@ export declare const CalcState: {
      */
     readonly Circular: number;
     /**
-     * A `Waiting` node the evaluation in progress has read under iterative calculation — it is in
+     * A `Waiting` node — or a finished member of a cycle that is still open — the evaluation in
+     * progress has read under iterative calculation: it is in
      * the executor's hit list already, so a second read of it in the same evaluation adds nothing.
      * Cleared when the list is consumed.
      */
@@ -51,6 +52,26 @@ export declare const CalcState: {
      * clears this when it empties the roster.
      */
     readonly Rostered: number;
+    /**
+     * A `CycleRole.Downstream` node that iterative calculation sweeps with the members, because a
+     * swept node reads it: it lies between two cycles, so it is in neither and still has to move
+     * with them. In the executor's sweep list already.
+     */
+    readonly Swept: number;
+    /**
+     * Pushed onto the demand stack by the PREFETCH of a `NeedsFirst` rather than by a read: the
+     * reader may never read it (an untaken `IF` arm names a cell without reading it), so its own
+     * reads may not decide anything about the reader. A node the prefetch pushes and a read then
+     * asks for loses the flag. Cleared when the node finishes, or when it is put back unevaluated.
+     */
+    readonly Prefetched: number;
+    /**
+     * `Unevaluated` and on the demand stack already, below the node being evaluated: it will be
+     * reached, so a prefetch does not push it again. Cleared when its evaluation starts. May outlive
+     * its entry (a cycle unwinds the stack past queued nodes); that only skips a prefetch, which is
+     * never needed for a right answer.
+     */
+    readonly Queued: number;
     /** What the mark phase resets: everything a single pass decides. `Skip` and the shown role survive. */
     readonly PassMask: number;
 };

package/types/src/calculation/state/CalculationContext.d.ts

@@ -12,6 +12,11 @@ export declare class CalculationContext implements IFormulaContext {
     protected _calcScope: CalcScope;
     protected _functions: IFunctionCollection;
     protected _container: IContextContainer;
+    /** The key parts of a draw that are not the cell itself — see {@link getRandom}. */
+    protected _passSeed: number;
+    protected _passCycleId: number;
+    protected _gridKey: number;
+    protected _gridKeyId: string | null;
     protected _axis: IRange.Axis;
     protected _coerceToNumber: (value: Scalar, fromType: ScalarType, options?: IFormulaContext.ParseNumberOptions) => Scalar;
     protected _functionProviders?: readonly FunctionProvider[];
@@ -31,6 +36,13 @@ export declare class CalculationContext implements IFormulaContext {
      * is seen (DESIGN-CIRCULAR-CALC.md §5); `null` outside a pass.
      */
     protected _dynamicRead: ReadHook | null;
+    /**
+     * Marks the evaluation in progress as having read something PER CELL — a position — so its
+     * answer cannot stand in for another cell's (`CalcScope.perCellRead`). One closure for the
+     * context's lifetime: every reference it builds is handed this for its `getCoords`, and the
+     * context's own position accessors call it directly.
+     */
+    protected readonly _positionRead: () => void;
     constructor(container: IContextContainer, axis?: IRange.Axis, functionProviders?: readonly FunctionProvider[]);
     /** @hidden */
     _setInstanceScope(instanceScope: any): void;
@@ -99,22 +111,44 @@ export declare class CalculationContext implements IFormulaContext {
     getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
     /** @inheritdoc IFormulaContext.getNow */
     getNow(): number;
+    /** @inheritdoc IFormulaContext.getRandom */
+    getRandom(): number;
     /** @inheritdoc IFormulaContext.compare */
     compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
-    protected _fromTuples(boundedTuples: Tuple.BoundedTuples<Scalar>, type?: ScalarType | null, isLiteral?: boolean, isDirectScalar?: boolean): IRange | null;
+    protected _fromTuples(boundedTuples: Tuple.Region<Scalar>, type?: ScalarType | null, isLiteral?: boolean, isDirectScalar?: boolean): IRange | null;
     /** @inheritdoc IFormulaContext.getValueAt */
     getValueAt(rowIndex: number, colIndex: number, sheetName?: string | null, options?: IRange.ValueOptions): Scalar | null;
     /** @inheritdoc IFormulaContext.getSpillAt */
     getSpillAt(rowIndex: number, colIndex: number, sheetName?: string): IReferenceRange | null;
     /** @inheritdoc IFormulaContext.createRange */
     createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /** @inheritdoc IFormulaContext.flattenAreas */
+    flattenAreas(value: IRange | IRange[]): IRange;
     getRange(value: Scalar | Scalar[][], type?: ScalarType | null, isLiteral?: boolean): IRange;
     /** @inheritdoc IFormulaContext.getRow */
     getRow(): number;
     /** @inheritdoc IFormulaContext.getColumn */
     getColumn(): number;
+    /** @inheritdoc IFormulaContext.isImplicitIntersect */
+    isImplicitIntersect(): boolean;
+    /**
+     * Whether the call being dispatched is under a first-cell demand (`CalcScope.firstCell`), and
+     * clears it: the demand is the dispatched call's own, and a body that calls another function
+     * directly must not inherit it. Engine-internal; no body reads it.
+     */
+    _takeFirstCell(): boolean;
     /** @inheritdoc IFormulaContext.getReference */
     getReference(coords: IRange.Coords | string, r1c1?: boolean): IReferenceRange;
+    /**
+     * @internal
+     * A reference whose scope is a 3-D span, as its member areas — one coords per sheet it covers, in
+     * tab order, marked `isSheetSpan` — or `null` for any other value.
+     *
+     * @remarks
+     * The marshaller asks this before its union rules, so a span is flattened, handed whole or refused
+     * exactly where a union would be, and a body that reads the mark (`SHEETS`) still can.
+     */
+    _expandSheetSpan(value: any): IRange.Coords[] | null;
     /** @inheritdoc IFormulaContext.getResizedReference */
     getResizedReference(anchor: Readonly<IRange.Coords>, rowCount: number, colCount: number): IReferenceRange;
     /**
@@ -151,7 +185,7 @@ export declare class CalculationContext implements IFormulaContext {
     parseAsNumber(textOrNumber: Scalar, options?: IFormulaContext.ParseNumberOptions): number;
     parseAsNumber(textOrNumber: Scalar | undefined, options?: IFormulaContext.ParseNumberOptions): number | undefined;
     /** @inheritdoc IFormulaContext.createCriteria */
-    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
     /** @inheritdoc IFormulaContext.parseAsLiteral */
     parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
     /** @inheritdoc IFormulaContext.toText */

package/types/src/calculation/state/IContextContainer.d.ts

@@ -1,10 +1,12 @@
 import { Scalar, IRange, IRuntime, IFormulaContext } from '@sheetxl/primitives';
 import { ISparseGrid, ISpatialMap, ISpatialMap3D, ISpatialQuery } from '../../collections';
 import { ISymbolRegistry } from '../symbol';
-import { IFormulaBlock } from '../formula';
+import { IFormulaBlock, FormulaImager } from '../formula';
 import { PrecedentSpatialValue, PrecedentKind, FormulaSpatialValue } from '../spatial';
-import { ICalcGrid } from '../grid';
+import { ICalcGrid, CalcGridBackend } from '../grid';
+import { CalcRequest } from '../grid/_CalcRequest';
 import { ICalculation } from '../ICalculation';
+import { NamedNodeInfo } from '../Types';
 import { CalcNode } from './CalcNode';
 import { CalcScope } from './CalcScope';
 /**
@@ -17,14 +19,19 @@ export interface IContextContainer {
      * @remarks
      * This is passed in so that the Calculation engine can lazy load
      *
-     * @param editing If `true` the block is compiled with the `'editing'` compiler profile — the
+     * @param editing When set, the block is compiled with the `'editing'` compiler profile — the
      * expression is preserved exactly as typed and a parse failure gets maximum recovery (see
-     * `FormulaCompilerProfile`). Used by `createFormula` (the formula editor); the default
-     * (`'calc'`) profile normalizes and spends nothing on recovery.
-     * @param formulaTransform A structural transform applied to the parsed tree (pre-link) — the
-     * READ half of the dialect hook, supplied only by format loads (see `ICalcGrid.fromJSON`).
+     * `FormulaCompilerProfile`) — reading `'storage'` or `'display'` text. Used by `createFormula`;
+     * absent, the (`'calc'`) profile reads storage text, normalizes and spends nothing on recovery.
      */
-    createFormulaBlock(gridId: string, context: IFormulaContext, expression: string, rowIndex: number, colIndex: number, editing?: boolean, formulaTransform?: ICalculation.FormulaTransform): IFormulaBlock;
+    /**
+     * Compiles a formula for a grid.
+     *
+     * @param legacyIntersect Compile in the legacy entry era: every call intersects
+     * ({@link ICalculation.JSON.legacyIntersect}). What a loaded block that is not an array anchor
+     * gets when the calculation is in that era.
+     */
+    createFormulaBlock(gridId: string, context: IFormulaContext, expression: string, rowIndex: number, colIndex: number, editing?: ICalculation.FormulaTarget, legacyIntersect?: boolean): IFormulaBlock;
     /**
      * Returns the symbol registry for name → stableId resolution.
      */
@@ -38,6 +45,17 @@ export interface IContextContainer {
     resolveScope(scope: string): string | undefined;
     getSheetIndex?: (sheetName?: string) => number;
     getSheetCount?: () => number;
+    /**
+     * The grid ids a 3-D span covers — every sheet from its first endpoint to its last in current tab
+     * order, hidden sheets included — or `null` when `scopeId` is not a span or an endpoint is gone.
+     *
+     * @remarks
+     * Asked at read time rather than stored: inserting, moving or deleting a sheet changes the members
+     * without changing the span.
+     */
+    getSheetSpanIds?: (scopeId: string) => string[] | null;
+    /** Every sheet's grid id in tab order, hidden sheets included. */
+    getSheetIds?: () => readonly string[];
     getScope(): CalcScope;
     getRuntime(): IRuntime;
     /**
@@ -51,6 +69,11 @@ export interface IContextContainer {
      * Returns `null` if the container does not track volatiles.
      */
     getVolatiles(): Set<CalcNode> | null;
+    /**
+     * Whether the calculation's unmarked formulas are in the legacy entry era
+     * ({@link ICalculation.JSON.legacyIntersect}).
+     */
+    isLegacyIntersect(): boolean;
     /**
      * Returns a 3D formulas.
      */
@@ -77,10 +100,11 @@ export interface IContextContainer {
      * Returns the current block-level dynamic precedent map, keyed by FormulaSpatialValue.
      *
      * @remarks
-     * At most one entry per (block, {@link PrecedentKind}) — so at most two, because one block can be
-     * BOTH kinds at once: `=INDIRECT("A1:A3")` reads a range it discovers at runtime AND spills over
-     * one it writes. Those two rectangles have nothing to do with each other, and the single slot this
-     * map used to hold forced them into a bounding box that described neither.
+     * At most one entry per (block, {@link PrecedentKind}, grid). One block can be BOTH kinds at once:
+     * `=INDIRECT("A1:A3")` reads a range it discovers at runtime AND spills over one it writes. Those
+     * two rectangles have nothing to do with each other, and the single slot this map used to hold
+     * forced them into a bounding box that described neither. And one block can read on several
+     * grids — a 3-D reference reads every sheet it covers — which a bounding box cannot express at all.
      *
      * Every path that replaces a block evicts through this map, so it must list ALL of the block's
      * entries: one left behind points at a dead block, whose CalcNodes the dirty walk then collects
@@ -95,20 +119,71 @@ export interface IContextContainer {
     /**
      * Returns the grid for a given gridId. This is used to get other grids when calculating.
      */
-    getGrid(gridId: string): ICalcGrid | null;
+    getGrid(gridId: string): CalcGridBackend | null;
+    /**
+     * Runs a request against the engine's state, landing what it writes under the snapshot it
+     * names (DESIGN-CALC-SERVICE §13.13: the engine keeps its own history keyed by the model's
+     * ids).
+     *
+     * @param landingId The engine commit the request lands in: the model's commit for a root
+     * transaction, its savepoint for a nested one, or `undefined` for a request naming no snapshot
+     * (a caller with no model), which is applied as it is.
+     * @param action The request; its writes land together.
+     */
+    landRequest<R>(landingId: string | undefined, action: () => R): R;
+    /**
+     * Sends a grid request through the service's channel (DESIGN-CALC-SERVICE §4, §7.2).
+     *
+     * @param gridId The grid the request is for.
+     * @param landingId The engine commit a request applied now lands in - see {@link landRequest}.
+     * @param request The request, as data.
+     *
+     * @remarks
+     * On a `Running` engine the request is applied at once and lands under `landingId`. While the
+     * engine is `Starting` it is held, in send order, and applied once the engine is up, behind the
+     * seeds; one whose snapshot the model has undone by then is dropped. On an `Off` engine nothing
+     * is recorded and the request resolves with nothing: a later start is seeded from the model.
+     */
+    sendRequest(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
+    /**
+     * What images a grid's records for the model (DESIGN-CALC-SERVICE §8): the model's symbol
+     * map, the grid as home scope, its bounds, the reader's locale. The facade's, read where a
+     * response crosses to the model.
+     */
+    getImager(gridId: string): FormulaImager;
+    /**
+     * Records the regions a request touched on the commit it is landing in, so a revert knows what
+     * to re-vend. A no-op outside a landing request.
+     */
+    recordTouched(gridId: string, regions: readonly IRange.Coords[]): void;
+    /**
+     * Records a grid's per-grid maps (values, spills, ...) in the engine's history, under the
+     * commit landing now: a restore hands them back to the grid. The maps are the grid's own
+     * objects, copy-on-write per request.
+     */
+    setGridMaps(gridId: string, maps: object): void;
+    /**
+     * The model has restored itself to `commitId` (an undo, a redo): restore the engine's history
+     * to it, once, and answer the regions of `gridId` that changed between the two snapshots. A
+     * grid asking after the engine is already there gets the regions of that same restore.
+     *
+     * @returns The changed regions of the grid, or `null` when the engine holds no history for the
+     * id (it restarts from a seed) or nothing changed on that grid.
+     */
+    revertTo(commitId: string, gridId: string): IRange.Coords[] | null;
     /**
      * Upserts a grid into the container's registry (create or replace), keyed by its `gridId`.
      *
      * @remarks
      * Called in two situations:
-     * 1. **Construction** — a newly created `CalcGrid` self-registers so it is reachable via
+     * 1. **Construction** — a newly created `CalcGridBackend` self-registers so it is reachable via
      *    {@link getGrid} / {@link getGridValues}.
      * 2. **Clone** — the cloned grid re-registers under the same `gridId`, atomically replacing
      *    the previous iteration in the registry and enabling swap-in-place semantics.
      *
      * @param calcGrid The grid instance to register.
      */
-    registerGrid(calcGrid: ICalcGrid): void;
+    registerGrid(calcGrid: CalcGridBackend): void;
     /**
      * Removes the grid with the given `gridId` from the container's registry.
      *
@@ -140,6 +215,18 @@ export interface IContextContainer {
      * @param options Optional calculation options.
      */
     calculateGrid(gridId: string, options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * Ask for the reactive pass that evaluates what `gridId` has dirty, once the current flush is
+     * over.
+     *
+     * @remarks
+     * Unlike {@link calculateGrid}, which runs the pass now, this posts it: every grid that asks
+     * during one synchronous flush is answered by ONE pass, at the flush's end. A watch registering
+     * asks this way, so a paint's worth of rules registering together costs one pass, not one each.
+     *
+     * @param gridId The grid whose dirty body the pass is owed for.
+     */
+    requestCalculateGrid(gridId: string): void;
     /**
      * Returns the monotonically incrementing generation counter for the calculation engine.
      *
@@ -156,6 +243,11 @@ export interface IContextContainer {
      * still carry, and the "already visited this cycle" guards would skip their re-evaluation.
      */
     getCycleId(): number;
+    /**
+     * The id of the last transaction commit a calculation pass was run for, or `null` before the
+     * first pass. What a record the engine pushes answers for (`ICalcGrid.Results.commitId`).
+     */
+    getCalculatedCommitId(): string | null;
     /**
      * The graph-version counters the executor's plan caches key on (CALC-PERFORMANCE-PLAN.md §1.1).
      *
@@ -169,7 +261,7 @@ export interface IContextContainer {
      * READING is what synchronizes: the implementation compares the identities of the spatial maps
      * it last saw and advances the counters when a clone-then-swap happened (edits, shifts, undo/
      * redo, pass-end dynamic commits all publish fresh maps). Sites that mutate the CURRENT maps in
-     * place — `CalcGrid.fromJSON` loads, an un-cloned `shift` — must call {@link bumpCalcEpochs}
+     * place — a seed (`CalcGridBackend._seedNow`), an un-cloned `shift` — must call {@link bumpCalcEpochs}
      * explicitly, because no identity changes there.
      *
      * Both counters are monotonic and deliberately NOT transactional, for the same reason as
@@ -252,30 +344,27 @@ export interface IContextContainer {
      * What a caller does owe: the action must be safe to run at an arbitrary microtask boundary, not
      * only from inside a calculation.
      *
-     * Used by surfaces (e.g. `CalcGrid`) to defer writes that arrive while the engine is still
-     * populating. That drain happens inline at the tail of `Calculation.start()`, so `await start()`
-     * still resolves only after queued work completes.
+     * For the engine's own deferrals (wiring a name, recompiling its dependents), which stay
+     * backend-side. A grid request is never queued here: it goes through {@link sendRequest}, as
+     * data, so the channel can hold it (DESIGN-CALC-SERVICE §6.2).
      */
     whenSafe(action: () => Promise<unknown>): void;
     /**
      * `true` while the engine is either `Starting` or inside a pending-action drain — at any drain
-     * site, not only the load drain in `Calculation.start()`.
+     * site, the start batch included.
      *
      * @remarks
      * A grid must NOT trigger a calc while this is `true`: a formula could evaluate against a sibling
-     * sheet whose values have not been drained yet (e.g. a volatile/cross-sheet formula reading an
-     * empty cell). Defer such calcs via {@link whenSafe} so they run after the full drain.
-     *
-     * This used to be set by the load drain alone, so during a drain ahead of a calculation it read
-     * `false` and a grid populating there took the inline branch — a calc re-entered from inside a
-     * drain, the exact shape the deferral exists to avoid.
+     * sheet whose seed has not been applied yet (e.g. a volatile/cross-sheet formula reading an
+     * empty cell). Owe the pass instead ({@link requestCalculateGrid}); the batch runs one once
+     * every seed is in.
      */
     isLoading(): boolean;
     /**
      * Recompiles every formula that references `nameId`, directly or through another name.
      *
      * @remarks
-     * Brute-force all3D scan over `formulaSpatial`, matched via `IFormulaBlock.getNamedIds` against
+     * Brute-force all3D scan over `formulaSpatial`, matched via `IFormulaBlock.getReferencedSymbolIds` against
      * `nameId` and {@link getNamedDependentNames}. Called after a named formula is wired or deleted
      * so dependents pick up the change. A recompile, not a dirty-mark, on purpose: a definition
      * change requires dependents to re-derive their precedents (`setInputs`), which `markDirty` does
@@ -326,6 +415,19 @@ export interface IContextContainer {
      * resolve the scope and drop what is not a sheet.
      */
     getNamedDependents(nameId: string): readonly IRange.Coords[];
+    /**
+     * A name's identity and anchor as plain data, or `null` when `nameId` names nothing.
+     *
+     * @param nameId The name's stable id.
+     * @param live When `true`, answers `null` for a name nothing currently references - the
+     *   dependents rule, where a name no formula reads is a definition rather than a dependent.
+     *
+     * @remarks
+     * Sits beside {@link getNamedDependents}: both are facts about a name, by id, asked from inside
+     * the calculation. This is what lets a grid answer a graph question with a name in it without
+     * handing out an engine-bound object.
+     */
+    getNamedNodeInfo(nameId: string, live?: boolean): NamedNodeInfo | null;
     /**
      * The ids of every NAME that references `nameId`, transitively. Excludes `nameId` itself unless
      * a cycle genuinely leads back to it.