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

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,22 @@ 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[];
+    /**
+     * Whether a sheet in the tab order has no grid: a chart, macro or dialog sheet. Such a sheet counts
+     * in a span's members and gives no values; it cannot be a span's endpoint.
+     */
+    isGridless?: (sheetId: string) => boolean;
     getScope(): CalcScope;
     getRuntime(): IRuntime;
     /**
@@ -51,6 +74,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 +105,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 +124,78 @@ 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 clone key the requests of the batch being applied share (`ISpatialMap.clone`'s), while a
+     * held batch or a collecting batch of grids applies; `null` otherwise. The batch is one engine
+     * operation, so a map one of its requests cloned is the one the next writes into, rather than a
+     * copy per request.
+     */
+    getHeldCloneKey?(): string | null;
+    /**
+     * 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 +227,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 +255,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 +273,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 +356,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 +427,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.

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

@@ -0,0 +1,163 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGrid, ISparseGrid, Tuple, IListLike } from '../../collections';
+import { ReferenceErrorIndex } from '../../primitives/ReferenceRange';
+/**
+ * The calc grid's committed values with the pass's UNCOMMITTED results laid over them.
+ *
+ * @remarks
+ * The executor batches results and commits them in one write (`writeCalcs`); a reference built
+ * during the pass used to force that commit whenever it could see a batched cell. On a row-chained
+ * sheet (`SUM($K$51:K#)` on every row) that was a commit per row — thousands of small persistent
+ * writes into the same long runs. This grid serves those reads from the batch instead, so the
+ * executor commits every N results and the writes are few and contiguous.
+ *
+ * It is a SUBSTITUTION view: iteration walks the committed runs and swaps in the pending value
+ * where one exists. That only describes a cell the committed grid already holds; a result for a
+ * cell with no committed run under it (a formula's first result — new after load, entry, paste)
+ * cannot be shown this way, so such a push marks the overlay `uncovered` and the next ITERATION
+ * over the pending box commits first (`_coverFor`), which is exactly the old behavior; a point
+ * read is answered by the map and never commits. A steady-state recalc never trips it. Reads
+ * outside the batch's bounding box never touch the map.
+ *
+ * Operations that materialize or write go through a commit first and then the committed grid —
+ * the safe fallback for anything a substitution cannot answer (`getValues`, `copyTo`, `clone`,
+ * every write). `cloneEmpty` needs no values.
+ *
+ * It is also the error index of references built over it ({@link ReferenceErrorIndex}): the
+ * committed index plus a scan of the pending map, taken only while the batch holds an error.
+ *
+ * A second layer holds DEMAND results (DESIGN-CIRCULAR-CALC.md §4.6): what demand evaluation and
+ * the iteration sweeps compute ahead of the plan. It is not part of the batch — a commit leaves it
+ * alone — and an entry lives until the plan takes its node ({@link takeDemand}), which then pushes
+ * the same value to the batch. A sweep rewrites its members many times, and every rewrite is a map
+ * write, not a persistent one. Substitution still needs a committed run under the cell, so the
+ * first result for a cell with nothing under it is written through as well; every later one is
+ * substituted.
+ */
+export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, ReferenceErrorIndex {
+    protected readonly _inner: ISparseGrid<Scalar>;
+    protected readonly _committed: ReferenceErrorIndex;
+    protected readonly _flush: () => void;
+    protected readonly _isColumn: boolean;
+    protected _pending: Map<number, Scalar>;
+    /** Pending values that are errors — the pending scan in {@link hasErrorIn} runs only while > 0. */
+    protected _errors: number;
+    /** A pending cell has no committed run under it; substitution cannot show it. */
+    protected _uncovered: boolean;
+    protected _rowStart: number;
+    protected _rowEnd: number;
+    protected _colStart: number;
+    protected _colEnd: number;
+    /** Demand results the plan has not taken yet; a commit leaves them. */
+    protected _demand: Map<number, Scalar>;
+    /** Demand values that are errors, as {@link _errors} is for the batch. */
+    protected _demandErrors: number;
+    protected _demandRowStart: number;
+    protected _demandRowEnd: number;
+    protected _demandColStart: number;
+    protected _demandColEnd: number;
+    protected _anyRowStart: number;
+    protected _anyRowEnd: number;
+    protected _anyColStart: number;
+    protected _anyColEnd: number;
+    constructor(inner: ISparseGrid<Scalar>, committed: ReferenceErrorIndex, flush: () => void);
+    get isPendingOverlay(): true;
+    /** The committed grid. */
+    getInner(): ISparseGrid<Scalar>;
+    /** Pending results. */
+    get size(): number;
+    /** Demand results the plan has not taken yet. */
+    get demandSize(): number;
+    /** Records one result. The executor's batch and this map are emptied together by a commit. */
+    push(row: number, col: number, value: Scalar): void;
+    /**
+     * Records one demand result, replacing the cell's last. A cell with nothing committed under it
+     * gets the value written through as well, so its later results can be substituted.
+     */
+    pushDemand(row: number, col: number, value: Scalar): void;
+    /** The plan has taken the cell's node: its result goes on as an ordinary one, or is written already. */
+    takeDemand(row: number, col: number): void;
+    /**
+     * Writes every demand result the plan did not take into the committed grid and empties the
+     * layer, so nothing computed is lost with the overlay.
+     */
+    commitDemand(): void;
+    /** After a commit: the committed grid now holds everything that was pending. Demand results stay. */
+    reset(): void;
+    protected _resetDemand(): void;
+    protected _growAny(row: number, col: number): void;
+    /** Rebuilds the union box from the two layers' own. */
+    protected _resetAny(): void;
+    /** Does a rectangle overlap the bounding box of the cells either layer holds? */
+    intersects(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
+    /** Does a rectangle overlap the pending (batch) cells' bounding box? */
+    protected _pendingIntersects(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
+    /** {@inheritDoc ReferenceErrorIndex.hasErrorIn} */
+    hasErrorIn(coords: IRange.Coords): boolean;
+    /** Does a (possibly partial) bounds box overlap the pending cells' box? Missing sides are open. */
+    protected _boundsIntersect(bounds: Partial<RangeCoords> | null | undefined): boolean;
+    /**
+     * Writes the demand results inside `bounds` (every one for `null`) into the committed grid, for
+     * a path that reads it without substituting. They stay in the layer — the grid now agrees with
+     * it, and the plan still takes each one.
+     */
+    protected _writeDemandIn(bounds: Partial<RangeCoords> | null | undefined): void;
+    /** The cell's value in either layer (they never share a cell), or `undefined`. */
+    protected _layered(key: number): Scalar | undefined;
+    /**
+     * Before an ITERATION over `bounds`: commits when a pending cell substitution cannot show
+     * (`uncovered`) lies inside them. A point read never needs this — the map answers it — and
+     * on a first calc, where every result is uncovered, a commit per read would be a commit per
+     * node. Nothing happens for reads outside the pending box.
+     */
+    protected _coverFor(bounds: Partial<RangeCoords> | null | undefined): void;
+    /** Before a MATERIALIZATION of `bounds` (no substitution on that path): commits what it would miss. */
+    protected _flushIfPendingIn(bounds: Partial<RangeCoords> | null | undefined): void;
+    /** Is the cell inside the box of either layer? */
+    protected _inBounds(row: number, col: number): boolean;
+    /** Nothing in either layer: every read is the committed grid's. */
+    protected _isEmpty(): boolean;
+    /** The run with pending values swapped in, or the run itself when none fall inside it. */
+    protected _substituteRun(major: number, minorFrom: number, run: IListLike<Scalar>): IListLike<Scalar>;
+    /** {@inheritDoc IGrid.getValueAt} */
+    getValueAt(row: number, column: number): Scalar;
+    /** {@inheritDoc ISparseGrid.getRuns} */
+    getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<Scalar>;
+    /** {@inheritDoc IGrid.entries} */
+    entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator<Scalar>;
+    /** {@inheritDoc IGrid.values} */
+    values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
+    /** {@inheritDoc IGrid.keys} */
+    keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    /** {@inheritDoc IGrid.getValues} */
+    getValues(coords?: RangeCoords): Tuple.Region<Scalar> | null;
+    /** {@inheritDoc IGrid.copyTo} */
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+    /** {@inheritDoc IGrid.getAxis} */
+    getAxis(): RangeAxis;
+    /** {@inheritDoc IGrid.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IGrid.getCoords} */
+    getCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.getMaxCoords} */
+    getMaxCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.clone} */
+    clone(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.cloneEmpty} */
+    cloneEmpty(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.setValues} */
+    setValues(values: Tuple.GridTuple<Scalar>): this;
+    /** {@inheritDoc IGrid.setValueAt} */
+    setValueAt(row: number, column: number, value: Scalar): void;
+    /** {@inheritDoc IGrid.delete} */
+    delete(coords: RangeCoords | null): boolean;
+    /** {@inheritDoc IGrid.clear} */
+    clear(): void;
+    /** {@inheritDoc IGrid.shift} */
+    shift(coords: RangeCoords, direction: Direction): boolean;
+    /** Both layers into the committed grid, so neither can shadow a write that follows. */
+    protected _commitAll(): void;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=_PendingOverlayGrid.d.ts.map

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

@@ -5,16 +5,61 @@ import { IGrid, ISparseGrid, Tuple } from '../../collections';
  * Receives every value read a formula makes while a read hook is armed.
  *
  * @remarks
- * A single-cell read reports a 1x1 rectangle; a block read (iteration, runs, bounded tuples)
- * reports the rectangle it was asked for — the cells it *may* open — because a sparse iterator
- * cannot tell an empty cell from a formula cell whose value is not there yet, and the second is
- * exactly the read a cycle check must see. Coordinates are absolute and closed.
+ * A single-cell read reports a 1x1 rectangle. A block read reports the span the consumer actually
+ * SWEPT: the iterator is wrapped and each position reported as it is reached, so a function that
+ * stops early (`VLOOKUP` at its hit) never reports the tail it did not look at, while positions
+ * the iterator skipped over — an `includeEmpty: false` sweep past a formula cell whose value is
+ * not there yet — are reported, because a sparse iterator cannot tell such a cell from an empty
+ * one and that is exactly the read a cycle check must see. Coordinates are absolute and closed.
+ *
+ * `prefetch` marks the ONE call such a sweep makes up front, naming the rectangle it was asked
+ * for. It is not a claim that those cells were opened — only the decisions that must be made
+ * ahead of the first read belong to it (bringing unevaluated precedents forward); whether any
+ * cell in the rectangle was opened is answered by the per-position reports that follow. Its
+ * RETURN says whether those reports can tell the caller anything: `false` means nothing in the
+ * rectangle could ever produce an answer, and the sweep is left unobserved.
  *
  * The hook may throw; the throw propagates through the reading function up to the evaluation
  * that armed it. Nothing is reported for constructing a reference, for its coords or size, or for
  * a copy made to hold derived values.
  */
-export type ReadHook = (gridId: string, rowStart: number, colStart: number, rowEnd: number, colEnd: number) => void;
+export type ReadHook = (gridId: string, rowStart: number, colStart: number, rowEnd: number, colEnd: number, prefetch?: boolean) => boolean;
+/**
+ * Turns the positions an iterator reaches into rectangles, in iteration order.
+ *
+ * @remarks
+ * Positions are numbered along the iteration's own axis and direction, so the cells between the
+ * last one reported and the one just reached are always a contiguous run of that numbering — at
+ * most three rectangles: the tail of the first major line, the whole lines between, and the head
+ * of the last.
+ */
+declare class SweptSpan {
+    private readonly _onRead;
+    private readonly _gridId;
+    private readonly _rowStart;
+    private readonly _colStart;
+    private readonly _rowEnd;
+    private readonly _colEnd;
+    /** The major axis is the column: positions run down a column, then on to the next. */
+    private readonly _byColumn;
+    private readonly _reverse;
+    /** Positions per major line — the height for a column sweep, the width for a row sweep. */
+    private readonly _minorCount;
+    private readonly _total;
+    /** The last position reported, in iteration order; `-1` before the first. */
+    private _cursor;
+    constructor(onRead: ReadHook, gridId: string, rowStart: number, colStart: number, rowEnd: number, colEnd: number, byColumn: boolean, reverse: boolean);
+    /** Reports everything from the last reported position up to and including this cell. */
+    reach(row: number, col: number): void;
+    /** A minor index (the row of a column sweep, the column of a row sweep) held inside the span. */
+    clampMinor(minor: number): number;
+    /** Reports the tail: an iterator run to exhaustion looked at everything it could yield. */
+    finish(): void;
+    /** Reports iteration positions `(cursor, to]`, then moves the cursor to `to`. */
+    private _advance;
+    /** One rectangle, in major/minor offsets from the sweep's origin. */
+    private _report;
+}
 /**
  * An `ISparseGrid` that reports every value access on an inner grid to a {@link ReadHook}.
  *
@@ -23,6 +68,13 @@ export type ReadHook = (gridId: string, rowStart: number, colStart: number, rowE
  * and never touches the sheet directly, so wrapping that grid observes every value read the
  * reference makes — through any `Range` view derived from it, since views share the grid.
  *
+ * A block read is wrapped rather than reported whole: the iterator reports each position as it is
+ * reached, so a consumer that stops early — every exact-match lookup — never reports the tail it
+ * did not look at, and one run to exhaustion reports everything. Positions the iterator skipped
+ * over are reported with the one that follows them, because skipping is what a sparse iterator
+ * does to a formula cell whose value is not there yet. A materialization (`getValues`, `copyTo`)
+ * has no span and reports its rectangle whole.
+ *
  * `clone`/`cloneEmpty` hand back the inner grid's copy UNWRAPPED. A `Range` operation clones
  * its grid only as scratch space for a derived result (`fill`, `map`, a scalar broadcast) and
  * overwrites what it later reads back; the coordinates in such a copy no longer name sheet
@@ -38,6 +90,8 @@ export declare class ReadObservedGrid implements ISparseGrid<Scalar> {
      * A pass that Kahn orders builds none; tests pin that the ordinary path stays unwrapped.
      */
     static created: number;
+    /** {@inheritDoc ISparseGrid.observesReads} */
+    readonly observesReads: true;
     protected readonly _inner: ISparseGrid<Scalar>;
     protected readonly _gridId: string;
     protected readonly _onRead: ReadHook;
@@ -45,10 +99,21 @@ export declare class ReadObservedGrid implements ISparseGrid<Scalar> {
     /** The grid being observed. */
     getInner(): ISparseGrid<Scalar>;
     /**
-     * Reports a block read. Missing sides of a partial bound are taken from the grid's maximum
-     * extent, then from its data extent; a grid with neither has nothing to read.
+     * The rectangle a block read names, absolute and closed. Missing sides of a partial bound are
+     * taken from the grid's maximum extent, then from its data extent; a grid with neither has
+     * nothing to read, and answers `null`.
+     */
+    protected _resolveBounds(bounds: Partial<RangeCoords> | null | undefined): RangeCoords | null;
+    /**
+     * Reports a rectangle whose every cell the caller does open.
      */
     protected _reportBounds(bounds: Partial<RangeCoords> | null | undefined): void;
+    /**
+     * Announces the rectangle an iteration was asked for and opens a {@link SweptSpan} over it, or
+     * answers `null` when the sweep need not be observed at all — either the rectangle could not be
+     * resolved, or the hook says nothing in it can produce an answer.
+     */
+    protected _openSweep(bounds: Partial<RangeCoords> | null | undefined, axis: RangeAxis | undefined, reverse: boolean | undefined): SweptSpan | null;
     /** {@inheritDoc IGrid.getValueAt} */
     getValueAt(row: number, column: number): Scalar;
     /** {@inheritDoc ISparseGrid.getRuns} */
@@ -60,7 +125,7 @@ export declare class ReadObservedGrid implements ISparseGrid<Scalar> {
     /** {@inheritDoc IGrid.keys} */
     keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
     /** {@inheritDoc IGrid.getValues} */
-    getValues(coords?: RangeCoords): Tuple.BoundedTuples<Scalar> | null;
+    getValues(coords?: RangeCoords): Tuple.Region<Scalar> | null;
     /** {@inheritDoc IGrid.copyTo} */
     copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
     /** {@inheritDoc IGrid.getAxis} */
@@ -87,4 +152,5 @@ export declare class ReadObservedGrid implements ISparseGrid<Scalar> {
     shift(coords: RangeCoords, direction: Direction): boolean;
     get [Symbol.toStringTag](): string;
 }
+export {};
 //# sourceMappingURL=_ReadObservedGrid.d.ts.map

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

@@ -1,4 +1,5 @@
 export * from './CalcNode';
+export * from './CalcInputs';
 export * from './CalcScope';
 export * from './CalcState';
 export * from './IContextContainer';

package/types/src/calculation/symbol/ExternalSheetSymbols.d.ts

@@ -0,0 +1,80 @@
+import { IExternalBookCollection, ExternalScopeParts } from '../../externalBook';
+import { ExternalBookCollection } from '../../externalBook/ExternalBookCollection';
+import { SheetSymbolHandle } from './SheetSymbolProvider';
+/**
+ * The stable-id prefix that marks a sheet symbol as living in an external book.
+ *
+ * @remarks
+ * `ext:<bookId>` is the book-scoped form (`[1]!Name`); `ext:<bookId>:<sheetIndex>` adds a sheet, and
+ * `ext:<bookId>:<first>:<last>` is a 3-D span across the book's sheets (`[1]Alpha:Data Sheet`). The
+ * prefix is the test every consumer uses — "is this scope external" is a `startsWith`, which is why
+ * external books needed no new {@link SymbolType} and no new branch in the twenty-odd places that
+ * ask the Sheet provider (DESIGN-EXTERNAL-LINKS §4B).
+ */
+export declare const EXTERNAL_ID_PREFIX = "ext:";
+/** Is this stable id an external sheet or book? */
+export declare const isExternalSymbolId: (stableId: string | null | undefined) => boolean;
+/**
+ * The book id and sheet positions inside an `ext:` stable id, or `null` if it is not one.
+ *
+ * @remarks
+ * A book is `sheetIndex` and `sheetEnd` of `-1`; a sheet has both equal; a 3-D span has the first and
+ * last sheet. A uuid carries no `:`, so every `:` after the book id is a separator.
+ */
+export declare function splitExternalSymbolId(stableId: string): {
+    bookId: string;
+    sheetIndex: number;
+    sheetEnd: number;
+} | null;
+/**
+ * The stable id of a book (`sheetIndex < 0`), of one of its sheets, or of a 3-D span from
+ * `sheetIndex` to `sheetEnd` — the inverse of {@link splitExternalSymbolId}.
+ */
+export declare const externalSymbolId: (bookId: string, sheetIndex: number, sheetEnd?: number) => string;
+/**
+ * The authoring half of {@link bindExternalScope}: how a scope that names no existing book, or a
+ * sheet no book lists, becomes one. Supplied by the engine from the collection it owns.
+ */
+export interface ExternalBookMinter {
+    /** A new book for a typed `<dir>[<file>]` — answers its id. */
+    addBook(parts: ExternalScopeParts): string;
+    /** Records `sheetName` on an existing book — answers the sheet's index. */
+    addSheet(bookId: string, sheetName: string): number;
+}
+/**
+ * Binds a sheet scope that names an external book, or `null` if it names none of this workbook's.
+ *
+ * @remarks
+ * Every spelling a book answers to binds to the SAME id, so the storage form (`[1]Sheet1`), the
+ * closed display form (`C:\dir\[Book.xlsx]Sheet1`) and the open one (`[Book.xlsx]Sheet1`) are three
+ * ways of writing one symbol — which is the invariant that lets a handle's `toString()` be fed
+ * straight back to `bind` (see {@link SheetSymbolProvider}).
+ *
+ * A position that does not exist (`[7]` of three books) answers `null`: the typed image is kept
+ * verbatim, the reference is `#REF!`, and the writer warns. A file name matching more than one book
+ * answers `null` too — the citation is genuinely ambiguous and `[n]` is the only spelling that is
+ * not — unless the typed directory picks one of them out.
+ *
+ * A 3-D span (`[1]Alpha:Data Sheet`) binds to one id with its sheets in the book's own order, so
+ * `[1]Data Sheet:Alpha` is the same symbol; both sheets must be listed.
+ *
+ * With a `minter`, a file name no book carries MINTS one (DESIGN-EXTERNAL-LINKS §4C): typing
+ * `'C:\dir\[Book.xlsx]Sheet1'!A1` creates the link, cache empty, exactly as Excel does when it cannot
+ * see the source. A sheet a known book does not list is recorded on it the same way. A `[n]` is never
+ * minted — a position is a citation of something that exists, and a directory that differs from a
+ * same-named book's is a different book, not a respelling of it. A span never mints either.
+ */
+export declare function bindExternalScope(books: ExternalBookCollection | null | undefined, displayName: string, minter?: ExternalBookMinter | null, withinBook?: string | null): string | null;
+/**
+ * Resolves an `ext:` stable id to a sheet handle, or `null` if the book has since been removed.
+ *
+ * @remarks
+ * `toString()` is the projection DESIGN-EXTERNAL-LINKS §4B describes: `[n]Sheet1` by default — the
+ * form a formula is STORED as, read off the book's current position — and the book's display name
+ * when the caller asks for one. Both bind back. A span spells both sheets after one book prefix
+ * (`[1]Alpha:Data Sheet`), as Excel writes it.
+ */
+export declare function resolveExternalSymbol(books: ExternalBookCollection | null | undefined, stableId: string, display: boolean): SheetSymbolHandle | null;
+/** The `AddOptions` a minted book starts from: the typed directory and file, the typed sheet. */
+export declare function mintedBookOptions(parts: ExternalScopeParts): IExternalBookCollection.AddOptions;
+//# sourceMappingURL=ExternalSheetSymbols.d.ts.map