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

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

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

@@ -10,6 +10,29 @@ export declare const SymbolType: {
 };
 export type SymbolType = typeof SymbolType[keyof typeof SymbolType];
 export interface SheetCtx {
+    /**
+     * Resolve to the form a READER sees rather than the form a formula is stored as.
+     *
+     * @remarks
+     * The two differ only for an external book: stored is `[n]Sheet1`, where `n` is a position
+     * projected from the book's place in the collection, and display is the book's own spelling
+     * (`'C:\dir\[Book.xlsx]Sheet1'`). A local sheet has one name and ignores this.
+     */
+    display?: boolean;
+    /**
+     * Bind is AUTHORING: a scope that names an external book this workbook has none of may create
+     * one (`'C:\dir\[Book.xlsx]Sheet1'` typed into a cell is how a link is made — DESIGN-EXTERNAL-LINKS
+     * §5 step 13). Off by default, and off for an editing compile, so a keystroke mints nothing; a
+     * local sheet is never minted.
+     */
+    mint?: boolean;
+    /**
+     * The formula being linked belongs to an external BOOK — a cached defined name's body — so a
+     * plain sheet name (`Alpha`) is that book's sheet, never one of this workbook's, and a `[n]`
+     * position cites the source's own links, which this workbook cannot see (`null`). Nothing is
+     * minted inside a book.
+     */
+    book?: string;
 }
 export interface NamedFormulaCtx {
     /** The stableId of the sheet that owns the formula scope, if any. */

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

@@ -57,6 +57,11 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      */
     private readonly _getByName;
     private readonly _getById;
+    /**
+     * The name an item goes by for this provider's reader - what a bind matches and a resolve
+     * displays. The item's own name unless the reader holds a copy of the names of its own.
+     */
+    private readonly _nameOf;
     private _byName;
     private _byId;
     /**
@@ -79,7 +84,12 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      * shadowing (a name scoped to that sheet beats a global of the same name). Providers with no
      * scoped items — tables — may ignore it.
      */
-    _getByName: (name: string, scope?: string | null) => T | null, _getById: (id: string) => T | null);
+    _getByName: (name: string, scope?: string | null) => T | null, _getById: (id: string) => T | null, 
+    /**
+     * The name an item goes by for this provider's reader - what a bind matches and a resolve
+     * displays. The item's own name unless the reader holds a copy of the names of its own.
+     */
+    _nameOf?: (item: T) => string);
     /**
      * @inheritdoc ISymbolProvider.bind
      *
@@ -98,8 +108,12 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      * it heals to turns out to be scoped.
      *
      * A miss on `_byName` is not proof the item has no proxy — see {@link _byRealId}.
+     *
+     * `ctx.existing: true` asks only whether the name is an item NOW: it answers `null` rather than
+     * minting a proxy for a name nothing holds. For a caller deciding what a spelling IS (a bare name
+     * that may be a table) — a proxy minted for every other name would never heal into anything.
      */
-    bind(displayName: string, ctx?: Record<string, unknown>): string;
+    bind(displayName: string, ctx?: Record<string, unknown>): string | null;
     /** Points a proxy at its real item, keeping {@link _byRealId} in step. */
     private _adopt;
     /** Moves a proxy to the `_byName` key its current name/scope spell. */

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

@@ -2,17 +2,77 @@ import { IRange } from '@sheetxl/primitives';
 import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
 /**
  * Strict provider for sheet symbols.
+ *
+ * @remarks
+ * An EXTERNAL sheet is a sheet symbol too. A scope this workbook has no sheet for, and which names
+ * a book (`[1]Sheet1`, `C:\dir\[Book.xlsx]Sheet1`), falls through to `_getExternal` rather than to a
+ * `SymbolType` of its own — the twenty-odd consumers of a scope all ask this provider, and teaching
+ * one provider a second spelling touches none of them (DESIGN-EXTERNAL-LINKS §4B).
+ *
+ * So is a 3-D span (`Alpha:Gamma`, PLAN-3D-REFS §2.1): one symbol naming its two endpoint sheets,
+ * `<firstId>:<lastId>`, with the endpoints in tab order.
  */
 export declare class SheetSymbolProvider implements ISymbolProvider {
     private readonly _getId;
     private readonly _getById;
-    constructor(_getId: (displayName: string) => string | null, _getById: (sheetId: string) => SheetSymbolHandle | null);
+    private readonly _external?;
+    /** A sheet's position in tab order, hidden sheets included, or `-1`. */
+    private readonly _getIndexById?;
+    constructor(_getId: (displayName: string) => string | null, _getById: (sheetId: string) => SheetSymbolHandle | null, _external?: (ExternalSheetSymbols | null) | undefined, 
+    /** A sheet's position in tab order, hidden sheets included, or `-1`. */
+    _getIndexById?: ((sheetId: string) => number) | null | undefined);
     /** @inheritdoc ISymbolProvider.bind */
-    bind(displayName: string, _ctx: Record<string, unknown>): string | null;
+    bind(displayName: string, ctx?: Record<string, unknown>): string | null;
     /** @inheritdoc ISymbolProvider.resolve */
-    resolve(stableId: string, _ctx: Record<string, unknown>): SheetSymbolHandle | null;
+    resolve(stableId: string, ctx?: Record<string, unknown>): SheetSymbolHandle | null;
+    /**
+     * `First:Last` (names or ids) to a span id with the endpoints in tab order, the plain sheet id when
+     * both ends are one sheet (`Alpha:Alpha` is `Alpha`, as Excel normalizes it), or `null` when either
+     * end is not a sheet of this workbook.
+     */
+    private _bindSpan;
+    /** One end of a span: a sheet's id or name, never a virtual grid (which has no name). */
+    private _bindEndpoint;
+    private _resolveSpan;
+}
+/**
+ * The two endpoint sheet ids of a LOCAL span id (`<firstId>:<lastId>`), or `null` if it is not one.
+ *
+ * @remarks
+ * A sheet id is `<name>-<uuid>` and a sheet name cannot contain `:`, so a `:` in a non-external id is
+ * the separator. Both halves must end in a uuid: typed text that never bound (`Alpha:Nope`) reaches
+ * `resolve` too, and must not be mistaken for a span whose sheets are gone.
+ */
+export declare function splitSheetSpanSymbolId(stableId: string | null | undefined): [string, string] | null;
+/**
+ * What a local span id becomes when tab order changes from `before` to `after` — `undefined` when it
+ * stands.
+ *
+ * @remarks
+ * An endpoint that is gone, or that `movedId` carried across the other endpoint, is replaced by its
+ * inward neighbor in `before`: the nearest sheet between the endpoints that is still there. When both
+ * ends land on one sheet the answer is that sheet's plain id, as Excel collapses `Alpha:Beta` to
+ * `Beta!A1`. A span that lost every sheet stands too; it has nothing to shrink to.
+ */
+export declare function replaceSheetSpanEndpoints(spanId: string, before: readonly string[], after: readonly string[], movedId?: string): string | undefined;
+/** Whether a sheet stable id is a 3-D span — local `<firstId>:<lastId>` or external `ext:<bookId>:<i>:<j>`. */
+export declare function isSpanSymbolId(stableId: string | null | undefined): boolean;
+/** The external-book half of {@link SheetSymbolProvider}, supplied by `Calculation`. */
+export interface ExternalSheetSymbols {
+    /**
+     * `mint`: a scope naming a book this workbook has none of may CREATE one — see {@link SheetCtx.mint}.
+     * `withinBook`: the id of the book a plain sheet name belongs to — see {@link SheetCtx.book}.
+     */
+    bind(displayName: string, mint: boolean, withinBook?: string | null): string | null;
+    resolve(stableId: string, display: boolean): SheetSymbolHandle | null;
 }
 export interface SheetSymbolHandle extends SymbolHandle {
     getEntireCoords(): IRange.Coords | null;
+    /**
+     * The sheet's own name, `null` for a sheet that has none. `toString` is the DISPLAY form and
+     * substitutes a placeholder for a nameless sheet; a caller that means to bind or compare a
+     * name reads this instead. Absent on a handle that is not a sheet (a virtual grid).
+     */
+    getName?(): string | null;
 }
 //# sourceMappingURL=SheetSymbolProvider.d.ts.map

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

@@ -16,4 +16,24 @@ export declare class SymbolRegistry implements ISymbolRegistry {
     /** @inheritdoc ISymbolRegistry.resolve */
     resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
 }
+/**
+ * A registry that answers some symbol types from providers of its own and every other from a base.
+ *
+ * @remarks
+ * The model's symbol map (DESIGN-CALC-SERVICE §8) is this over the engine's: the types the engine
+ * keeps a copy of resolve through the model's live items here, while the rest resolve through the
+ * engine's providers. Registering a provider registers it on the base, so a provider that arrives
+ * late (the functions, once their module loads) is seen by both.
+ */
+export declare class OverlaidSymbolRegistry implements ISymbolRegistry {
+    private readonly _base;
+    private readonly _overrides;
+    constructor(_base: ISymbolRegistry, _overrides: ReadonlyMap<SymbolType, ISymbolProvider>);
+    /** @inheritdoc ISymbolRegistry.registerProvider */
+    registerProvider(type: SymbolType, provider: ISymbolProvider): void;
+    /** @inheritdoc ISymbolRegistry.bind */
+    bind(type: SymbolType, displayName: string, ctx?: Record<string, unknown>): string | null;
+    /** @inheritdoc ISymbolRegistry.resolve */
+    resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
+}
 //# sourceMappingURL=SymbolRegistry.d.ts.map

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

@@ -1,7 +1,8 @@
 export { type ISymbolRegistry, type ISymbolProvider, type SymbolHandle, SymbolType } from './ISymbolRegistry';
 export { type SheetCtx, type NamedFormulaCtx, type TableCtx, type ColumnCtx, type FunctionCtx } from './ISymbolRegistry';
-export { SymbolRegistry } from './SymbolRegistry';
-export { SheetSymbolProvider } from './SheetSymbolProvider';
+export { SymbolRegistry, OverlaidSymbolRegistry } from './SymbolRegistry';
+export { SheetSymbolProvider, isSpanSymbolId, splitSheetSpanSymbolId, replaceSheetSpanEndpoints, type SheetSymbolHandle, type ExternalSheetSymbols } from './SheetSymbolProvider';
+export { EXTERNAL_ID_PREFIX, isExternalSymbolId, splitExternalSymbolId, externalSymbolId, bindExternalScope, resolveExternalSymbol, mintedBookOptions, type ExternalBookMinter } from './ExternalSheetSymbols';
 export { TableSymbolProvider } from './TableSymbolProvider';
 export { IndirectSymbolProvider, IndirectProxy } from './IndirectSymbolProvider';
 export { TableColumnSymbolProvider } from './TableColumnSymbolProvider';