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

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

@@ -23,18 +23,6 @@ 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;
@@ -46,6 +34,8 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     protected _gridOptions: Partial<CalcGridBackend.ConstructorOptions>;
     protected _calculation: ICalculation;
     protected _context: CalculationContext & IFormulaContext;
+    /** {@link _context} with no cell, for executors (`IDeferContext.getFormulaContext`); made on first ask. */
+    protected _cellFreeContext: (CalculationContext & IFormulaContext) | null;
     protected _calcExecutor: CalcExecutor;
     /** The cache as grids and the cached names as virtual grids — see {@link ExternalBookBindings}. */
     protected _externalBindings: ExternalBookBindings;
@@ -92,6 +82,8 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
      * a load wires every name it holds in one batch.
      */
     private _recompileNamedPending;
+    /** {@link _recompileNamedPending} for a name whose definition has not changed. */
+    private _recompileLoadedPending;
     private _invalidateNamedPending;
     constructor(options: CalcBackend.ConstructorOptions);
     /** Initializes the context: the function registry the backend calls through. */
@@ -106,34 +98,13 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     getScope(): CalcScope;
     /** {@inheritDoc IContextContainer.getDeferred} */
     getDeferred(): DeferredCalls;
-    /**
-     * The settle pass (DESIGN-ASYNC §4.5): a change with no write, for every call whose latest
-     * moved since the last one.
-     *
-     * @remarks
-     * A cell whose formula is its one call reads the latest through its holder: the model is told
-     * the cell's value as it reads now, its pending status clears, and its dependents are marked
-     * dirty — never the cell itself. A cell whose formula is more than its call is marked dirty
-     * itself, and its next evaluation serves each site its call. One settle pass follows, seeded from
-     * what was marked and nothing else, and vends the repaints with its results.
-     *
-     * A call whose owner's cell no longer names it — the cell was edited, or its version is not the
-     * current one — settles into that version's holder and nothing here.
-     */
     protected _settle(): void;
-    /**
-     * Cancels every call `cover` covers (`ICalculation.cancelAsync`, DESIGN-ASYNC §4.6): each is
-     * closed and its `onCancel` runs. Each owner whose cell still names its call re-evaluates in a
-     * settle pass: served the closed call, it shows what it did and is no longer pending.
-     *
-     * @returns The settle pass, or `null` when nothing was cancelled.
-     */
     cancelAsync(cover: true | string | IRange.Coords): Promise<ICalculation.Status> | null;
     /**
      * A call's result as a cell can hold it (`DeferredCalls.Normalize`): an array becomes a range
      * as a body's array return does, a one-cell range its scalar, a jagged array `#VALUE!`.
      */
-    protected _normalizeResult(value: unknown): unknown;
+    protected _normalizeResult(value: unknown, options?: IFormulaContext.DeferredCall.ResolveOptions): unknown;
     /**
      * The holder at a cell: the engine grid's value there, else the entry of the spill anchored
      * there (an anchor cell holds its first element; the spill's entry carries the holder). `null`
@@ -256,7 +227,7 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     /** {@inheritDoc IContextContainer.isLoading} */
     isLoading(): boolean;
     /** {@inheritDoc IContextContainer.recompileNamed} */
-    recompileNamed(nameId: string): void;
+    recompileNamed(nameId: string, loaded?: boolean): void;
     /** {@inheritDoc IContextContainer.invalidateNamed} */
     invalidateNamed(nameId: string): void;
     /** {@inheritDoc IContextContainer.getNamedNodeInfo} */
@@ -349,28 +320,6 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
      * @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;
@@ -481,51 +430,12 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
      * {@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.
+     * @param loaded The definitions have not changed (see {@link recompileNamed}). What was loaded
+     * with them, and the bodies of other names, only re-derive their precedents: opening a file
+     * evaluates what the file marks dirty, and mentioning a name is not a mark.
      */
+    recompileReferencing(changedIds: ReadonlySet<string>, loaded?: boolean): void;
     refitTableRows(sheet: string, columns: {
         colStart: number;
         colEnd: number;
@@ -549,38 +459,6 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     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>;
@@ -751,10 +629,6 @@ export declare namespace CalcBackend {
         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; a settle pass with
-         * `settle`, seeded from what the settle marked only (DESIGN-ASYNC §4.5).
-         */
         calculate(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): Promise<ICalculation.Status>;
         /** Owes a reactive pass for `gridId`, run once the current flush is over. */
         owePass(gridId: string): void;
@@ -828,17 +702,14 @@ export declare namespace CalcBackend {
         calcCoords?: IRange.Coords;
         /** The grid whose reactive pass this is; absent for an explicit one. */
         gridId?: string;
-        /**
-         * The settle pass (DESIGN-ASYNC §4.5, §4.8): seeded from the regions the settle marked only.
-         * Volatiles are not collected and the dirty set is left for the pass that owes it, so a
-         * landing result neither re-rolls `RAND` nor runs the recalculation manual mode withholds.
-         */
         settle?: boolean;
         /**
          * `ICalculation.CalculateOptions.external`: the calls the pass makes fetch past the workbook's
          * cache, to the source.
          */
         external?: boolean;
+        /** The pass a load owes: see `CalcExecutor.ExecuteOptions.load`. */
+        load?: boolean;
         /** Iterative calculation's limits, or `null` when it is off. */
         iterate: {
             maxIteration: number;
@@ -846,10 +717,6 @@ export declare namespace CalcBackend {
         } | null;
         /** The model operation open now: what the pass's results are realized under. */
         openOperationId: string | null;
-        /**
-         * A reactive pass under `AutomaticExceptTables`: the what-if data tables (`TABLE` nodes) are
-         * skipped and stay out of date (DESIGN-DATA-TABLES §4.4). Ignored by a full pass.
-         */
         exceptTables?: boolean;
     }
     interface ConstructorOptions {
@@ -874,8 +741,10 @@ export declare namespace CalcBackend {
         books: IExternalBookCollection;
         /** What rich values a formula makes are made for; omitted, made outside any workbook. */
         richData?: IRichDataKind.Context;
-        /** What async functions fetch through (`IBatchContext.fetch`); omitted, the global `fetch`. */
+        /** What async functions fetch through (`IDeferContext.fetch`); omitted, the global `fetch`. */
         fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+        /** How async functions read delimited text (`IDeferContext.parseText`); omitted, it rejects. */
+        parseText?: (text: string, options?: IFormulaContext.IDeferContext.ParseTextOptions) => Promise<Scalar[][]>;
         /** The replicas as the owner holds them when the start was asked for. */
         replica?: Replica;
         /** The model's current commit, mirrored first. */
@@ -920,23 +789,12 @@ export declare namespace CalcBackend {
          * 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

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

@@ -1,10 +1,2 @@
-/**
- * The calculation backend's code: what a started engine builds and runs.
- *
- * @remarks
- * `Calculation` reaches every value here through this one module and nothing else, so the facade a
- * workbook constructs carries none of it (DESIGN-CALC-SERVICE §5, §13.25). Types are imported
- * directly; only values belong on this list.
- */
 export { CalcBackend } from './CalcBackend';
 //# sourceMappingURL=index.d.ts.map

package/types/src/calculation/executor/CalcExecutor.d.ts

@@ -92,6 +92,8 @@ export declare class CalcExecutor {
     protected _passActive: boolean;
     /** The pass in progress is a settle pass (`ExecuteOptions.settle`): its seeds are the settles' alone. */
     protected _settlePass: boolean;
+    /** The pass a load owes: see {@link _savedAnswer}. */
+    protected _loadPass: boolean;
     /**
      * The holder {@link _takeDeferred} made for an evaluation whose value is a range: the value keeps
      * its shape for the spill layout, which puts the holder on the spill's entry. Taken at once.
@@ -111,11 +113,6 @@ export declare class CalcExecutor {
      * while a pass evaluates. Released with {@link _flush}.
      */
     _overlays: Map<string, PendingOverlayGrid> | null;
-    /**
-     * The what-if layers of the data table being evaluated, per grid id (DESIGN-DATA-TABLES §4.3):
-     * what `getGridValues` hands every read while a `TABLE` node runs its substitutions. `null`
-     * otherwise.
-     */
     _whatIf: Map<string, WhatIfLayer> | null;
     /**
      * A reactive pass under `AutomaticExceptTables`: a `TABLE` node is not evaluated, and is left
@@ -124,13 +121,6 @@ export declare class CalcExecutor {
     protected _exceptTables: boolean;
     /** The `TABLE` nodes the pass in progress skipped, for `ExecuteResult.skippedTables`. */
     protected _skippedTables: Set<CalcNode>;
-    /**
-     * The blank regions of the blocks whose representative could not stand for them this plan
-     * (PLAN-WATCHES-BLANK-AWARE §4), and the cells of the regions that WERE shared whose value the
-     * share moved under a reader ({@link _dirtyBlankReaders}) — handed to `doEvaluate`'s incremental
-     * dirty set at the end of the plan, so the next iteration of the pass collects the first cell
-     * by cell and the readers of the second.
-     */
     protected _fallbackDirty: ISpatialMap | null;
     /**
      * The cycle table (design §7.3): per cycle id, one live {@link CircularReference} holding the
@@ -225,31 +215,15 @@ export declare class CalcExecutor {
      */
     execute(cycleId: number, options: CalcExecutor.ExecuteOptions, state: CalcExecutor.ExecuteState): CalcExecutor.ExecuteResult | null;
     /**
-     * Takes the calls an evaluation of `node` deferred (DESIGN-ASYNC §4.4): the cell's value is an
-     * `AsyncValue` over them and what the formula calculated from their initials, and the node is
-     * pending with it while any is open.
+     * What a cell answers with instead of the calls its evaluation just made, on the pass a load owes:
+     * the value it was saved with, which is the cached answer until something asks the source. `undefined`
+     * when it should ask: the file marks it to calculate on load, nothing was saved, what was saved is
+     * not an answer (`#BUSY!`, a blocked spill), or the function is volatile.
      */
+    protected _savedAnswer(node: CalcNode): Scalar | IRange | undefined;
     protected _takeDeferred(node: CalcNode, value: any): any;
     /** The cells of the `TABLE` nodes the pass skipped, scoped; `undefined` for none. */
     private _takeSkippedTables;
-    /**
-     * The read hook of a pass (DESIGN-CIRCULAR-CALC.md §4.3, §5), shared by both paths: armed for
-     * every reference while a node is evaluated by demand, and for dynamic-branch references
-     * (`OFFSET`/`INDIRECT`/`INDEX` results) on the ordinary path. A read that lands on a node of
-     * THIS pass decides: `Waiting` (on the in-progress stack — transitively waiting on the reader)
-     * is a cycle; `Unevaluated` suspends the reader until it is done; `Evaluated` (in the pending
-     * batch) is committed on the spot and read; `Done` with a cycle role makes the reader
-     * downstream. Any other cell is a value. Inert outside a pass, so a reference built during one
-     * and read later (a spill committed afterwards) is plain values.
-     *
-     * `prefetch` is the rectangle an ITERATION was asked for, announced before its first read. Only
-     * the `Unevaluated` decision belongs to it — bringing what the sweep may need forward is free,
-     * and over-eager is harmless (design §4.3) — while `Waiting` and a finished cycle role are left
-     * to the per-position reports the sweep makes, which is what stops an early-exit lookup from
-     * reporting the tail it never opened (plan item 1). It answers whether those reports can say
-     * anything at all: a rectangle holding no node of this pass and nothing the sheet shows in a
-     * cycle is swept unobserved.
-     */
     private _onPassRead;
     /**
      * A read of a `Done` cycle node by the node being evaluated: the reader is downstream of that
@@ -314,27 +288,6 @@ export declare class CalcExecutor {
      * slot `length` on; returns the new length.
      */
     private _collectUnevaluated;
-    /**
-     * Evaluates `worklist` by demand (DESIGN-CIRCULAR-CALC.md §4.3): each node is evaluated with the
-     * read hook armed; a read that lands on one not yet evaluated suspends the reader and evaluates
-     * that one first (`NeedsFirst`); a read that lands on one already suspended — waiting,
-     * transitively, on the reader — is a cycle (`Circular`), and the in-progress stack from it up
-     * to the reader are the members, written `0`. A node that reads a member is downstream and
-     * writes `0` too. Everything else simply computes: an unorderable static edge that is never
-     * read (`OFFSET`'s anchor, `ROW`'s argument, an untaken `IF` branch) makes no cycle.
-     *
-     * @remarks
-     * Two callers: `doEvaluate` when the plan reaches the nodes `doMarkAndPlan` could not order
-     * (the batch, after everything ordered is committed), and `doEvaluate` again for a single
-     * ordered node whose dynamic read landed on a node not yet evaluated — the same suspension,
-     * on the ordinary path (§5). Every node evaluated here is flagged `circular`, so the plan
-     * takes its `demandValue` when it reaches it, and its finalized scalar is already in the
-     * overlay's demand layer for later lazy reads (`_pushDemand`); `flush` commits the ordered
-     * path's pending batch when a read needs a value still sitting in it. Flat: the stack is an
-     * array, so a 1,560-row chain is 1,560 evaluations, not 1,560 JS frames. A node is retried at
-     * most once per `NeedsFirst` it raises, and with the prefetch of its static precedents that is
-     * normally once.
-     */
     protected doDemandEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, worklist: readonly CalcNode[], flush: () => void): void;
     /**
      * The finalized scalar goes into the overlay's demand layer now, so a later lazy read sees it;
@@ -348,23 +301,7 @@ export declare class CalcExecutor {
      * `flush` of the `doEvaluate` that made it, and only that one.
      */
     private _overlayFor;
-    /**
-     * The results of a what-if data table, for the `TABLE` node being evaluated
-     * (DESIGN-DATA-TABLES §4.3): the affected nodes re-evaluated under each substitution of §2.2,
-     * through layers over what the grids read as now, the pass's uncommitted results included.
-     *
-     * @remarks
-     * The read hooks and the dynamic-edge accumulator are set aside while it runs: every member
-     * read is a plain read through the layers and registers no edge. The table's own reads of its
-     * edge, which order it and register its edges, are made before (`_DataTableFunction`). The calc
-     * scope is the table's again on return.
-     */
     evaluateWhatIf(table: WhatIfTable): Scalar[][];
-    /**
-     * One node evaluated where it sits, under the what-if layers (DESIGN-DATA-TABLES §4.3): its
-     * input slots are cleared so every read falls through to the funnel, as a demand evaluation's
-     * do. An async result stands as the cell's last value; so does a read that raised a signal.
-     */
     private _evaluateWhatIf;
     /**
      * A finalized result fitted to its cell when the block makes every cell its own 1x1
@@ -383,30 +320,6 @@ export declare class CalcExecutor {
      * arm it skipped), all of it final by now, so it is evaluated without the pass's read hook.
      */
     private _isPositionFree;
-    /**
-     * The representative of a gated block has finalized (PLAN-WATCHES-BLANK-AWARE §4): its scalar is
-     * shared with the block's blank region, or the gate is closed and the region is re-collected
-     * cell by cell.
-     *
-     * @remarks
-     * Shared only when nothing the evaluation read was per cell (`CalcScope.perCellRead`: a draw, a
-     * computed reference; a position unless {@link _isPositionFree} rules it out), the result is a
-     * scalar, and the node ran on its own - not a promise, not pending on one, not in a cycle. A
-     * per-cell read is a fact of the formula and
-     * closes the gate for good ({@link FormulaSpatialValue.blankRefused}); the rest may not recur
-     * and close it for this pass ({@link _fallbackBlank}).
-     *
-     * How the region is shared depends on who can read it (§4c). A block in a SHEET grid is read
-     * by other formulas, the sheet and the error index, all through the grid's values, so the
-     * scalar is written as runs - one per column of each blank rectangle, which for a column block
-     * is one run. A block in a grid that SHADOWS a sheet (a watch body, a one-shot evaluation) has
-     * exactly one reader, the range its owner holds, and that range answers the region as its empty
-     * value from the block (`FormulaSpatialValue.getBlankValueWithin`): nothing is written, whatever
-     * the region's size, and what an earlier pass stored there is removed so the block's answer is
-     * the one read.
-     *
-     * @param refuse The caller's own reasons the result cannot stand for the region.
-     */
     private _finalizeRepresentative;
     /**
      * Marks dirty the cells of a shared blank region whose value the share just moved, wherever a
@@ -494,29 +407,6 @@ export declare class CalcExecutor {
      * them run on (iteration on). Returns the stack index of `read`.
      */
     private _markCycleSlice;
-    /**
-     * Iterative calculation (design §6.3) over the members {@link _demandRun} marked. Each sweep
-     * evaluates them in ADDRESS order, each read seeing the latest value (Gauss–Seidel in row-major
-     * order, as Excel: `probe-iterative.ps1`), until no member moved by `maxChange` or
-     * `maxIteration` sweeps ran.
-     * The limits are global, as in Excel — one unsettled member keeps every cycle of the pass
-     * sweeping. Downstream nodes read the members once more afterwards; one that feeds a swept node
-     * is swept with them instead (`_onMemberRead`), so the rest feed no cycle and need no sweeping.
-     * Converged means a sweep over a list that did not grow moved nothing by `maxChange`: every
-     * node a swept node reads is then swept itself or does not move in this pass, so the state is a
-     * fixed point and not a fragment's. The members are then registered as volatile so the next
-     * recalculation re-runs them, which is how `=A1+1` advances per recalc (Excel re-iterates every
-     * cycle on every `Calculate()`).
-     *
-     * @remarks
-     * The evaluation that FOUND the members ran in dependency order — `B1 = B2+1` needs `B2` first,
-     * whichever of the two the plan reached first — so its results are not a sweep of this order,
-     * and counting them as one costs a step. The members go back to the values the pass found them
-     * at; a member that had none is then evaluated once, in address order, for the entry evaluation
-     * Excel gave it when it was written (§2.4), and every one of the `maxIteration` sweeps runs on
-     * top of that. Discovery's results are never read: a node that read a member is downstream, and
-     * evaluates again below.
-     */
     private _demandSweep;
     /** Clears the `IterHit` flags of the hits not consumed by {@link _demandRun}'s loop and empties the list. */
     private _drainIterHits;
@@ -599,6 +489,8 @@ export declare class CalcExecutor {
      * Uses Kahn's algorithm.
      */
     doMarkAndPlan(cycleId: number, markId: number, initial: FixedPackedArray<CalcNode>, plan: FixedPackedArray<CalcNode>, forceDemand?: boolean): boolean;
+    /** Stamps a plan as the order later passes may take a subset of (§1.2); `orderedLength` is where its demand appendix starts. */
+    private _stampPlan;
     /**
      * The remembered plan whose seed set is exactly this pass's, at this epoch — or `null`. The
      * length check first: it is what rejects the common miss (a single-cell pass against a bulk
@@ -637,24 +529,18 @@ export declare namespace CalcExecutor {
          * The grid to seed the pass FROM — `ICalculation.CalculateOptions.scope`, i.e. "Calculate Sheet".
          */
         scopeGridId?: string;
-        /**
-         * The settle pass (DESIGN-ASYNC §4.5): seeded from what the settles marked only; the volatiles
-         * and the dirty set are left for the pass that owes them.
-         */
         settle?: boolean;
         /**
          * `ICalculation.CalculateOptions.external`: the calls the pass makes fetch past the workbook's
          * cache, to the source.
          */
         external?: boolean;
+        /** The pass a load owes: a cell with a saved value answers with it rather than asking the source. */
+        load?: boolean;
         /**
          * Iterative calculation (design §6.3) for the pass; `null`/absent with it off.
          */
         iterate?: IterateOptions | null;
-        /**
-         * A reactive pass under `AutomaticExceptTables`: `TABLE` nodes are skipped and left dirty
-         * (DESIGN-DATA-TABLES §4.4); they come back in {@link ExecuteResult.skippedTables}.
-         */
         exceptTables?: boolean;
     }
     /** The two limits of `ICalculation.IterativeCalculation`. */
@@ -741,12 +627,9 @@ export declare namespace CalcExecutor {
         /** Discovery searches skipped (or verified) because `dependentsEpoch` was current. */
         dependentsCacheHits: number;
         dependentsCacheMisses: number;
-        /**
-         * Nodes evaluated on the ORDERED path (`evaluateAt` from `doEvaluate`); `evaluations` counts
-         * the demand path. Their sum is every formula run — what blank-aware evaluation
-         * (PLAN-WATCHES-BLANK-AWARE §4) reduces to the touched cells plus one.
-         */
         evaluated: number;
+        /** Plans ordered by formula block, with no cell-level walk (`orderByBlocks`). */
+        blockOrdered: number;
         discoveryMs: number;
         inDegreeMs: number;
         kahnMs: number;

package/types/src/calculation/executor/CalcExecutorUtils.d.ts

@@ -45,17 +45,6 @@ export declare function rangeToTuples(range: IRange, offsetMajor?: number, offse
  * is the packing, and the result reads its grid alone. Anything else is returned as it is.
  */
 export declare function packForReturn<T>(finalized: T): T;
-/**
- * Fits a result to a fixed (array-entered) extent, per dimension: a dimension of 1 broadcasts, a
- * longer one is clipped, a shorter one is padded with `#N/A`. Measured against Excel
- * (`probe-cse.ps1`): `=SEQUENCE(5)` into 3 rows is `1,2,3`; `=SEQUENCE(2)` into 5 rows is
- * `1,2,#N/A,#N/A,#N/A`; `=SUM(H1:H5)` into 3x3 is the sum nine times; a 1x3 into 3x3 repeats the
- * row; a 3x1 into 3x3 repeats the column.
- *
- * @returns The fitted values, row-major, exactly `rowCount` x `colCount`. A blank source cell stays
- * blank (`null`), as it does when a dynamic array spills. The fit is a fixed point - fitting the
- * result again yields the same shape - so nothing downstream needs a "do not resize" guard.
- */
 export declare function fitToExtent(value: Scalar | IRange, rowCount: number, colCount: number): Scalar[][];
 /**
  * {@link fitToExtent} as grid tuples over `coords`, in the orientation of the grid they are written
@@ -78,10 +67,40 @@ export declare function fitToTuples(value: Scalar | IRange, coords: IRange.Coord
  * @param scratch An array the search fills; the caller's, reused across calls.
  */
 export declare function visitReaderWindows(precedentSpatial: ISpatialQuery<PrecedentSpatialValue>, region: IRange.Coords, scratch: ISpatialMap.Entry<PrecedentSpatialValue>[], visitWindow: (block: FormulaSpatialValue, rowFrom: number, rowTo: number, colFrom: number, colTo: number) => void, visitDynamic: (entry: ISpatialMap.Entry<PrecedentSpatialValue>, block: FormulaSpatialValue) => void): void;
+/**
+ * Whether every cell of a static entry's block reads exactly one cell through it.
+ *
+ * @remarks
+ * Only such a reader looks at what a precedent pushes. A range reader builds its range when it
+ * evaluates, over that same slot. A reader this answers `false` for and that does read one cell (the
+ * first of `$A$1:A1`, whose range grows from there) has an empty slot, and reads the cell itself.
+ */
+export declare function readsOneCell(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>): boolean;
 /**
  * TODO - document and/or rationalize with visitPrecedentBlock
  */
 export declare function visitDependencyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, rowIndex: number, colIndex: number, callbackFn: (calc: CalcNode) => void, mint?: MintWindow | null): void;
+/** The part of a reader block an entry has reached so far in one discovery, absolute and closed. */
+export interface ReachedWindow {
+    rowFrom: number;
+    rowTo: number;
+    colFrom: number;
+    colTo: number;
+}
+/**
+ * {@link visitDependencyBlock} for discovery, which only has to reach each reader once.
+ *
+ * @remarks
+ * Every cell of a range reports to the same readers, so a running total reached from each of its n
+ * inputs would walk n²/2 readers to find one input's worth. What an entry has reached is kept in
+ * `reached` for the discovery, and each visit walks only what it adds: nothing for a running total
+ * after its first input, one reader per input for a sliding window. A window that does not meet what
+ * is held is walked whole, and the larger of the two is kept; that only costs a repeat, since
+ * reaching a reader twice changes nothing.
+ *
+ * An entry whose readers read one cell has one reader per input, and nothing to save.
+ */
+export declare function discoverDependencyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, rowIndex: number, colIndex: number, callbackFn: (calc: CalcNode) => void, mint: MintWindow, reached: Map<PrecedentSpatialValue, ReachedWindow>): void;
 /**
  * Visit the cells of a dependent block that read a spill's BODY — the extent an anchor at
  * (`anchorRow`, `anchorCol`) occupies, MINUS the anchor cell itself.

package/types/src/calculation/executor/CircularReference.d.ts

@@ -13,23 +13,6 @@ export interface CycleHost {
     /** The sheet name for a grid id, or `undefined` for a virtual grid (a named formula's body). */
     resolveScope(gridId: string): string | undefined;
 }
-/**
- * One reference cycle (DESIGN-CIRCULAR-CALC.md §7.3): the executor's record of it and its public
- * face in one — the object a `Feature.Circular` region carries as its payload and
- * `ICell.getCircularReference()` answers. It holds the nodes the sheet index currently shows as
- * its members and as downstream of it, the interned index payloads, and how the sweep that
- * settled it ended. It persists across passes — a node moves between cycles when a commit writes
- * its delta (`_trackCircular`) — and is dropped when its last node leaves.
- *
- * @remarks
- * Every read filters through {@link CycleHost.isLiveNode}: a pass that deletes the offending
- * formula never plans, so the sets cannot clear themselves, and a member is counted only while
- * its cell still holds the block the cycle was found in (design §7.3, trap 5).
- *
- * The iteration answers come from the sweep that settled the cycle (design §6.3). A cycle id is
- * minted by the pass that finds it, so a cycle evaluated with iteration off is a different object
- * with no record — `isIterative()` is exactly "a sweep settled this one".
- */
 export declare class CircularReference implements ICalculation.ICircularReference {
     protected readonly _host: CycleHost;
     protected readonly _cycleId: number;

package/types/src/calculation/executor/_BlockOrder.d.ts

@@ -0,0 +1,29 @@
+import { ISpatialMap3D } from '../../collections';
+import { FormulaSpatialValue } from '../spatial';
+import { CalcNode } from '../state';
+/**
+ * Orders a pass by formula block rather than by cell.
+ *
+ * @remarks
+ * A range reader adds an edge per cell it reads, so ordering a running total cell by cell visits
+ * n²/2 edges to learn that one column goes before another. A block's references are the same at
+ * every cell at that cell's offset, so its reads are known from its corners, and the block graph is
+ * as many vertices as the sheet has distinct fills.
+ *
+ * Every edge between cells lies inside an edge between their blocks, so a block order that exists
+ * is a valid cell order. Within a block the cells go in row order or column order, whichever puts
+ * everything the block reads of itself first. The block graph can refuse an order the cells have
+ * (`A1=B1`, `B1=A2`, filled down: each column reads the other); that answer is `false`, and is not
+ * a statement about cycles. Cell-level ordering decides those.
+ *
+ * Inputs and spills are the caller's: a spill's body edges are not in a block's references, and a
+ * reader of a cycle shown elsewhere is found by the cell-level walk.
+ *
+ * @param nodes The affected nodes.
+ * @param length The number of affected nodes.
+ * @param formulas The formula map the references resolve against.
+ * @param out Receives the nodes in order. Written over on `false` as well.
+ * @returns Whether `out` is a valid order.
+ */
+export declare function orderByBlocks(nodes: CalcNode[], length: number, formulas: ISpatialMap3D<FormulaSpatialValue>, out: CalcNode[]): boolean;
+//# sourceMappingURL=_BlockOrder.d.ts.map