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

package/types/src/calculation/INamedFormulasCollection.d.ts

@@ -6,6 +6,9 @@ import { INamed } from '../named';
 import { ICalculation } from './ICalculation';
 /**
  * Collection of named formulas available in the calculation engine.
+ *
+ * @remarks
+ * Keyed by the formula's id, not ordered: iteration order is unspecified.
  */
 export interface INamedFormulasCollection extends ICollection<ICalculation.INamedFormula> {
     /**
@@ -46,6 +49,8 @@ export interface INamedFormulasCollection extends ICollection<ICalculation.IName
      * registries — tables among them — and is not.
      */
     toJSON(): INamed.JSON[] | null;
+    /** For runtime type checking. */
+    readonly isINamedFormulasCollection: true;
 }
 /**
  * {@inheritDoc INamedFormulasCollection}
@@ -98,14 +103,6 @@ export declare namespace INamedFormulasCollection {
          * expression on the floor.
          */
         replaceExisting?: boolean;
-        /**
-         * A structural transform applied when this name's expression compiles — the READ half of the
-         * format-dialect hook, supplied by format loads (hydration) so a legacy on-disk spelling
-         * normalizes. Kept for the item's lifetime so an undo back to the loaded text re-applies it.
-         *
-         * @see {@link ICalculation.FormulaTransform}
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
     }
     /**
      * Options for getting items from the collection.

package/types/src/calculation/NamedFormulaCollection.d.ts

@@ -1,13 +1,13 @@
 import { IRange, Scalar, IFormulaContext } from '@sheetxl/primitives';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
-import { ListenerEmitter } from '../listener/ListenerEmitter';
 import { ICellRange, ICellRanges } from '../cellRange';
-import { _NamedGraphNode } from '../cellRange/_GraphNode';
+import { NamedNodeInfo, ReferenceCoords } from './Types';
 import { INamed } from '../named';
-import { ITypes } from '../type';
+import { ITypes, AbstractCollection } from '../type';
 import { IContextContainer } from './state';
-import { Formula, IFormulaBlock } from './formula';
+import { FormulaHost } from './grid';
+import { Formula, IFormulaBlockView } from './formula';
 import { ICalculation } from './ICalculation';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
 interface State {
@@ -28,20 +28,25 @@ interface State {
 /**
  * Implementation for {@link INamedFormulasCollection}.
  */
-export declare class NamedFormulaCollection implements INamedFormulasCollection {
-    protected _emitter: ListenerEmitter<this, INamedFormulasCollection.IListeners>;
-    private _transactions;
+export declare class NamedFormulaCollection extends AbstractCollection<ICalculation.INamedFormula, INamedFormulasCollection.GetItemsOptions> implements INamedFormulasCollection {
+    protected _transactions: ITransaction.IStore;
     private _stateId;
     private _transactionsRemoveListener;
-    private _closed;
+    /**
+     * `json.names` held until {@link hydrate}, and answered by {@link toJSON} meanwhile — so a save
+     * before the engine starts (`ICellContainerOptions.calcOnLoad` `'none'`) writes the names
+     * exactly as they were read.
+     */
+    private _pendingJSON;
     protected _container: IContextContainer | null;
+    protected _bindSheet: ((scope: string) => string | null) | null;
     protected _context: IFormulaContext | null;
     protected _ready: (() => Promise<ICalculation.Status>) | null;
     protected _getActiveCell: () => IRange.CellCoords | null;
-    protected _createVirtualGrid: ((gridId: string) => void) | null;
+    protected _createHost: ((gridId: string) => FormulaHost) | null;
     protected _getRange: ((address: ICellRange.Address) => ICellRange) | undefined;
     protected _getRanges: ((address: ICellRanges.Address) => ICellRanges) | undefined;
-    protected _createGraphRanges: ((cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null) | undefined;
+    protected _createGraphRanges: ((cells: readonly IRange.Coords[], names: readonly NamedNodeInfo[]) => ICellRanges | null) | undefined;
     protected _resolveSheetScope: ((stableId: string) => string | null) | null;
     protected _isReadOnly: (() => boolean) | null;
     protected _getOrBindProxyFakeId: ((name: string, scope: string | null) => string | null) | null;
@@ -53,6 +58,11 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
     private _wiringDirty;
     /** Nesting depth of {@link _beginWiringBatch}; the flush happens on the way out of the last one. */
     private _wiringBatchDepth;
+    /**
+     * The names written, told as each is written - see {@link _addNamesWrittenListener}. Its own
+     * store, never open, so nothing waits for the operation to land.
+     */
+    private _namesEmitter;
     constructor(options?: NamedFormulaCollection.ConstructorOptions);
     /**
      * Hydrates from `IWorkbook.JSON.names`. A malformed entry is warned and skipped rather than
@@ -66,7 +76,9 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
      *
      * Not on `INamedFormulasCollection`: hydration belongs to whoever constructs the engine.
      */
-    hydrate(json: INamed.JSON[] | undefined, formulaTransform?: ICalculation.FormulaTransform): void;
+    hydrate(json: INamed.JSON[] | undefined): void;
+    /** Set while {@link hydrate} runs, so the read-only refusal in {@link add} stands down. */
+    private _hydrating;
     /**
      * Serializes to `IWorkbook.JSON.names` form, sorted by scope+name so output is stable across
      * saves.
@@ -87,6 +99,8 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
      * against), so serializing it would lose the sheet. An unwired item falls back to its raw
      * expression — it has nothing better to offer.
      */
+    /** Retains names not yet hydrated for {@link toJSON}; see `Calculation.hydrateNames`. */
+    setPendingJSON(json: INamed.JSON[] | null | undefined): void;
     toJSON(): INamed.JSON[] | null;
     /** {@inheritDoc INamedFormulasCollection.add} */
     add(options: INamedFormulasCollection.AddOptions): ICalculation.INamedFormula;
@@ -110,21 +124,6 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
      * and a listener that re-reads the collection would otherwise do it once per name.
      */
     protected _markWired(): void;
-    /**
-     * The graph node for a name id, or `null` — the sheet layer's door for minting name nodes into
-     * a CELL's graph answers.
-     *
-     * @internal
-     *
-     * @remarks
-     * `live` applies the phase-5 liveness rule (TODO-RENDER-DEPENDENCIES.md): a name is reported as
-     * a cell's DEPENDENT only when it has a dependent of its own — `_xlnm.Print_Area` reads every
-     * cell in the area and nothing reads it, so it is dead by construction and minting it would put
-     * a phantom on every cell it covers. No prefix special-casing: `=SUM(_xlnm.Print_Area)` makes
-     * it genuinely live and it SHOULD show. The PRECEDENT direction never gates: a name the cell's
-     * own formula mentions is in use by that very fact.
-     */
-    _graphNode(id: string, live?: boolean): _NamedGraphNode | null;
     /**
      * Announces that what this collection PRESENTS has changed, without its own state having moved.
      *
@@ -162,10 +161,8 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
      */
     private _endWiringBatch;
     protected _flushWired(): void;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<ICalculation.INamedFormula>;
-    /** {@inheritDoc INamedFormulasCollection.getItems} */
-    getItems(options?: INamedFormulasCollection.GetItemsOptions): ICalculation.INamedFormula[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: INamedFormulasCollection.GetItemsOptions): ICalculation.INamedFormula[];
     /**
      * {@inheritDoc INamedFormulasCollection.getByName}
      *
@@ -187,8 +184,12 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
     addListeners(listeners: INamedFormulasCollection.IListeners, options?: IListener.Options): IListener.Remove;
     /**
      * Look up a named formula by its stable id.
+     *
+     * @remarks
+     * Narrower than {@link INamedFormulasCollection.getById} declares, because the store holds the
+     * concrete item. Callers inside the calculation get the internals without a cast.
      */
-    getById(id: string): ICalculation.INamedFormula | null;
+    getById(id: string): NamedFormula | null;
     /**
      * The item holding this exact identity — the (name, sheet) pair — or `null`.
      *
@@ -215,18 +216,48 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
      * so a name loaded from a file that references a sheet the file does not contain still reports
      * the scope it was written with instead of silently becoming global.
      */
+    /** A sheet's name or id to its stable id: see {@link NamedFormulaCollection.ConstructorOptions.bindSheet}. */
+    protected _bindSheetScope(scope: string): string | null;
     protected _resolveScopeInput(scope: string | null): string | null;
     /** A scope id as the sheet's current display name — see {@link NamedFormula.getScope}. */
     protected _resolveScopeName(scopeId: string | null): string | null;
     protected _remove(id: string): void;
-    isClosed(): boolean;
+    /**
+     * Hears every name added, renamed or removed, as it is written: inside the operation, in the
+     * order the writes are made. A restore writes nothing here; what it brings back is whatever the
+     * store held.
+     *
+     * @internal The calculation's: what its engine is told of the names.
+     */
+    _addNamesWrittenListener(listeners: IListener.Callbacks<NamedFormulaCollection, NamedFormulaCollection.NamesWrittenEvents>): IListener.Remove;
+    protected _notifyNamesWritten(item: NamedFormula, removed: boolean): void;
+    /**
+     * Every name as {@link _addNamesWrittenListener} tells one: what a listener starts from.
+     * @internal
+     */
+    _namesAsWritten(): NamedFormulaCollection.NamesWritten[];
     close(): void;
     protected _getState(): State | null;
     protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
-    protected _updateState(state: Partial<State> | ((prevState: State) => State), description?: string, options?: ITransaction.StoreOperationOptions<unknown, Partial<State>>): void;
+    protected _updateState(state: Partial<State> | ((prevState: State) => State), description?: string, options?: ITransaction.StoreOperationOptions<Partial<State>>): void;
     protected _initState(): void;
+    /** {@inheritDoc INamedFormulasCollection.isINamedFormulasCollection} */
+    get isINamedFormulasCollection(): true;
 }
 export declare namespace NamedFormulaCollection {
+    /** What {@link NamesWrittenEvents.onNamesWritten} tells of one name, as it is now. */
+    interface NamesWritten {
+        id: string;
+        name: string;
+        /** The sheet the name is private to, as the sheet's id; `null` for a global name. */
+        scopeId: string | null;
+        /** The name has left the collection. */
+        removed: boolean;
+    }
+    /** See {@link NamedFormulaCollection._addNamesWrittenListener}. */
+    interface NamesWrittenEvents {
+        onNamesWritten?(source: NamedFormulaCollection, written: NamesWritten): void;
+    }
     interface ConstructorOptions {
         /**
          * Named items to hydrate at construction, in `IWorkbook.JSON.names` form — `ref` carries the
@@ -250,14 +281,23 @@ export declare namespace NamedFormulaCollection {
          * ({@link ICalculation.INamedFormula.getDirectDependents} and friends) whenever a defined name
          * belongs in one; without it those answers fall back to cells only.
          */
-        createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null;
+        createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly NamedNodeInfo[]) => ICellRanges | null;
         /** Resolves a sheet stableId to its display name — calc refs carry stableId scopes. */
         resolveSheetScope?: (stableId: string) => string | null;
+        /**
+         * A sheet's name or stable id to its stable id, as the model holds its sheets now - not as the
+         * engine's replica has been told. Falls back to the container's symbols when absent.
+         */
+        bindSheet?: (scope: string) => string | null;
         /** Backs {@link INamed.isReadOnly} on each item. Defaults to not read-only. */
         isReadOnly?: () => boolean;
         getActiveCell?: () => IRange.CellCoords | null;
-        createVirtualGrid?: (gridId: string) => void;
-        /** The virtual grid a name compiles into. Keyed by name AND scope — see `add`. */
+        /**
+         * The host a name compiles its body into, created on first ask and answered again for the same
+         * id thereafter (a redefine rebinds to the same id; a deleted name keeps its grid).
+         */
+        createHost?: (gridId: string) => FormulaHost;
+        /** The grid a name compiles into. Keyed by name AND scope — see `add`. */
         getOrBindProxyFakeId?: (name: string, scope: string | null) => string | null;
         queuePendingAction?: (action: () => Promise<void>) => void;
         /**
@@ -274,6 +314,8 @@ export declare namespace NamedFormulaCollection {
 interface NamedFormulaWireOptions {
     container: IContextContainer;
     context: IFormulaContext;
+    /** Holds the body. `null` for a name that has no grid (no proxy id was bound for it). */
+    host: FormulaHost | null;
     ready: () => Promise<ICalculation.Status>;
     /** Returns the scope's sheet gridId (for reference resolution). Resolved after ready(). */
     getScopeGridId: () => string | null;
@@ -295,7 +337,7 @@ interface NamedFormulaWireOptions {
     getRanges?: (address: ICellRanges.Address) => ICellRanges;
     getRange?: (address: ICellRange.Address) => ICellRange;
     /** Mixed graph answers (cells + name nodes) — see the collection option of the same name. */
-    createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null;
+    createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly NamedNodeInfo[]) => ICellRanges | null;
     /** Resolves a sheet stableId to its display name — calc refs carry stableId scopes. */
     resolveSheetScope?: (stableId: string) => string | null;
     /**
@@ -343,17 +385,31 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * rendering `getItems()`.
      */
     private readonly _notifyCollection;
-    /** Load-time dialect unwrap — see the constructor; applied by {@link _doWireCore}'s compile. */
-    private readonly _formulaTransform;
+    /** The collection's {@link NamedFormulaCollection._addNamesWrittenListener}, for a rename. */
+    private readonly _notifyNameWritten;
     private _emitter;
     private _transactionsRemoveListener;
     private _closed;
     /**
-     * The compiled body, read LIVE from this name's virtual grid on every access.
+     * What this name resolved to the last time its readers were reconciled with it: the body block
+     * (identity — the store keeps the compiled block object, so a version that did not touch the
+     * body hands back the same one) and the state that decides whether there is a body to read.
+     * Recorded after wiring and after every revert; `onRestoreOrRevert` invalidates readers only
+     * when the restored version differs. The restore event is dispatched to EVERY state of a
+     * commit, not only the ones that changed, so without this an undo of any cell value re-marked
+     * every reader of every name — on a template, the whole workbook, in a pass of its own.
+     */
+    private _seenBlock;
+    private _seenDeleted;
+    private _seenExpression;
+    /** Holds the body; `null` for a name without a grid. See {@link _block}. */
+    private readonly _host;
+    /**
+     * The compiled body, read LIVE from this name's host on every access.
      *
      * @remarks
      * Deliberately not a captured instance. A name's body is versioned state like any other formula —
-     * it lives at (0,0) of the virtual grid in the ONE shared `formulaSpatial` that also holds every
+     * it lives at (0,0) of the host's grid in the ONE shared `formulaSpatial` that also holds every
      * cell formula, inside `Calculation`'s transactional state. So the store already tracks it, and
      * anything holding a second copy is holding a snapshot:
      *
@@ -368,19 +424,21 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * `undefined` (no grid, or nothing compiled at its origin) is the pre-wire state, which every
      * accessor below already has a fallback for.
      */
-    protected get _block(): IFormulaBlock;
-    constructor(coords: IRange.CellCoords | null, options: INamedFormulasCollection.AddOptions, deleteFromCollection: () => void, wire: NamedFormulaWireOptions | null, gridId?: string | null, checkRename?: (nextName: string) => void, transactions?: ITransaction.IStore, isReadOnly?: (() => boolean) | null, resolveSheetScope?: (stableId: string) => string | null, notifyCollection?: () => void);
+    protected get _block(): IFormulaBlockView;
+    constructor(coords: IRange.CellCoords | null, options: INamedFormulasCollection.AddOptions, deleteFromCollection: () => void, wire: NamedFormulaWireOptions | null, gridId?: string | null, checkRename?: (nextName: string) => void, transactions?: ITransaction.IStore, isReadOnly?: (() => boolean) | null, resolveSheetScope?: (stableId: string) => string | null, notifyCollection?: () => void, notifyNameWritten?: () => void);
     /**
-     * Binds this name to the region its expression designates, now.
+     * Writes this name's body, which binds it to the region its expression designates once the
+     * engine answers.
      *
      * @internal
      *
      * @remarks
-     * Called by the collection once the item is IN the collection, so the notification `_doWireCore`
-     * ends with describes a set that already contains it. `_doWireCore` has no awaits, so this
-     * completes before it returns and `getRanges()` answers immediately afterwards.
+     * Called by the collection once the item is IN the collection, so the notification the answer
+     * brings describes a set that already contains it. `getRanges()` answers once the engine has.
      */
     _wireNow(): void;
+    /** Records what the readers have been reconciled with — see `_seenBlock`. */
+    private _recordSeen;
     /**
      * {@inheritDoc INamed.getId}
      *
@@ -560,9 +618,9 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      */
     getRanges(): ICellRanges | null;
     /** {@inheritDoc ICalculation.INamedFormula.getDirectDependents} */
-    getDirectDependents(): ICellRanges | null;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICalculation.INamedFormula.getDependents} */
-    getDependents(): ICellRanges | null;
+    getDependents(): Promise<ICellRanges | null>;
     /**
      * This name as a graph NODE — the backing a {@link NamedCellRange} delegates to.
      *
@@ -574,57 +632,24 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * falls to the name's scope sheet and finally to `null` (the consumer defaults it) — the same
      * "self-consistent but arbitrary" anchor the body was compiled against (design doc §7).
      */
-    _asGraphNode(): _NamedGraphNode;
+    _asNodeInfo(): NamedNodeInfo;
     /** {@inheritDoc ICalculation.INamedFormula.getDirectPrecedents} */
-    getDirectPrecedents(): ICellRanges | null;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICalculation.INamedFormula.getPrecedents} */
-    getPrecedents(): ICellRanges | null;
-    /**
-     * The precedents of this NAME — cells and names, ONE answer; the mirror of
-     * {@link _dependentRanges}.
-     *
-     * @remarks
-     * The cell half is the ordinary precedent graph: a body is a real formula on its virtual grid,
-     * and its references registered precedent ranges like any cell's — so the grid answers, one hop
-     * or deep, and only scope translation is needed. The name half is the body's `getNamedIds`:
-     * apply-at-eval means a name the body reads has no precedent edge, so the symbol list is the
-     * only carrier — one hop for `direct`, the downward closure (cycle-guarded) for the deep form,
-     * each closure member contributing its own grid's cell walk.
-     *
-     * The deep form does not take the symbol hop from UPSTREAM CELLS: with `X = A1*2` and
-     * `A1 = SomeName`, `A1` is listed and `SomeName`'s inputs are not — that hop belongs to `A1`,
-     * whose own `getDirectPrecedents` reports the `SomeName` node, which is how a TREE walk crosses
-     * it. Flattening it here would mean scanning every landed region's blocks; the tree gets it for
-     * free, one hop at a time.
-     *
-     * Everything resolves at the DEFINING anchor (the body's own compilation site) — the same
-     * answer the Name Manager gives, and the §4.1 rule for a name that is not in use.
-     */
-    private _precedentRanges;
+    getPrecedents(): Promise<ICellRanges | null>;
     /**
-     * The dependents of this NAME — cells and names, ONE answer.
+     * The precedents or dependents of this NAME — cells and names, ONE answer — as the engine walks
+     * them over its body's grid (see `CalcGridBackend._nameGraphNow` for the walk: the symbol edges
+     * names ride on, and the cell graph between them).
      *
      * @remarks
-     * Two graphs meet here, and the walk has to change vehicles between them.
-     *
-     * The **symbol** edge — which formulas mention this name — is not in the precedent spatial at
-     * all. Names apply at EVAL rather than being inlined at compile, so a reference to one registers
-     * no precedent range; the edge is the nameId list each compiled block carries, read back through
-     * `container.getNamedDependents` (bucketed and memoized there — see its docs).
-     *
-     * The **cell** edge is the ordinary precedent graph, and it already carries everything downstream
-     * of those blocks. So `direct` is one hop of the first graph; the transitive form takes that hop,
-     * then hands each landing block to the grid it lives on.
-     *
-     * A block on a VIRTUAL grid is another NAME reading this one. It is not a cell — it is a NODE,
-     * and it rides in the same answer as an anchored `INamedRange` (design doc §4): one node per
-     * name, whatever the walk direction found it by, since dependents are anchor-independent. The
-     * transitive walk still passes THROUGH it on the symbol closure (`getNamedDependentNames`, the
-     * same closure the engine invalidates against), or `Base`'s dependents would stop at `Plus1`
-     * and miss every cell reading `Plus1`. This name itself is listed only when a true cycle leads
-     * back to it.
+     * What is left here is the translation out of calc currency: a cell on no addressable sheet
+     * drops, and the rest are reduced to regions, not a list of blocks - two formulas naming this
+     * name in adjacent cells are one range, and the deep walk can reach one block down two paths.
+     * Everything resolves at the DEFINING anchor (the body's own compilation site): the answer the
+     * Name Manager gives. Name nodes lead, cells follow.
      */
-    private _dependentRanges;
+    private _graphRanges;
     /**
      * {@inheritDoc IModel.delete}
      *
@@ -645,25 +670,32 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * the {@link getReferences} override.
      */
     getExpression(options?: ICalculation.FormulaTextOptions): string;
+    /**
+     * The root of the compiled body, for the engine's own side: what a formula dialect reads a name
+     * through ({@link ICalculation.FormulaDialectContext.getNamedRoot}).
+     * @internal
+     */
+    _getBodyNode(): ICalculation.FormulaNode | null;
     /** Pre-wire fallback: return empty array before block is compiled. */
     getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[];
     /** Pre-wire fallback: return false before block is compiled. */
     isReferenceOnly(): boolean;
     /**
-     * {@inheritDoc ICalculation.IFormula.getReferences}
-     *
-     * @remarks
-     * Overridden to anchor at the virtual grid's origin. The inherited implementation reads
-     * `this._coords`, which for a named formula is the *defining* cell (the active cell when the
-     * name was added) — it exists only so relative refs encode their R1C1 offsets from there. The
-     * compiled block lives at (0,0) of the name's own virtual grid, so the base version would query
-     * a cell that holds nothing.
-     */
-    getReferences(): ICellRanges | null;
-    setReferenceAt(_index: number, _reference: any, _options?: any): this;
-    setReferenceModeAt(_index: number, _side?: ICalculation.ReferenceSide, _mode?: number, _options?: any): this;
-    private _wireAsync;
+     * Anchored at the virtual grid's origin. `this._coords` is the *defining* cell (the active cell
+     * when the name was added), which exists only so relative refs encode their R1C1 offsets from
+     * there; the compiled block lives at (0,0) of the name's own grid.
+     */
+    protected _referencesAt(): ReferenceCoords[] | null;
+    setReferenceAt(_index: number, _reference: any, _options?: any): Promise<this>;
+    setReferenceModeAt(_index: number, _side?: ICalculation.ReferenceSide, _mode?: number, _options?: any): Promise<this>;
+    /** Writes the body as authored, inside the operation that asked (the host amends the current commit when none is open). */
     private _doWireCore;
+    /**
+     * The engine answered with the body: only now does the name designate anything - `getRanges()`
+     * was null up to here. Both the item and the collection announce it; a spatial consumer listens
+     * to the collection, which is the only place it can hear about a name it does not already hold.
+     */
+    private _bodyAnswered;
     toString(): string;
     get [Symbol.toStringTag](): string;
 }

package/types/src/calculation/NamedLambdaFunction.d.ts

@@ -0,0 +1,28 @@
+import { TypedFunction } from '../scripting/TypedFunction';
+import { ICalculation } from './ICalculation';
+/**
+ * A defined name whose body is `LAMBDA(…)`, answered by `IFunctionCollection.getByName` as a function
+ * so that a signature or help lookup can describe it.
+ *
+ * @remarks
+ * Not registered and never executed. The engine's own function lookups skip `isLambda()`, so a call to
+ * the name still compiles as an application of the NAME — its dependency edge, `#NAME?` healing,
+ * recursion and `LET` shadowing are all the name's. `execute` answers `#CALC!`, a lambda's verdict
+ * wherever it is not applied.
+ */
+export declare class NamedLambdaFunction extends TypedFunction {
+    /** @inheritdoc IFunction.isLambda */
+    isLambda(): boolean;
+}
+/** The category a named lambda is listed under — beside the built-in categories, in search and pickers. */
+export declare const LAMBDA_CATEGORY = "Lambda";
+/**
+ * The function a lambda-valued defined name exports, or `null` when its body is not a `LAMBDA`.
+ *
+ * @remarks
+ * The parameters are the ROOT lambda's declarations — `LAMBDA(n,LAMBDA(x,x+n))` takes `n` — with
+ * optional ones flagged, and the summary is the name's comment, or its formula when it has none. One
+ * instance per name while those stay the same.
+ */
+export declare const namedLambdaFunction: (item: ICalculation.INamedFormula) => NamedLambdaFunction | null;
+//# sourceMappingURL=NamedLambdaFunction.d.ts.map

package/types/src/calculation/TokenType.d.ts

@@ -86,6 +86,15 @@ export declare const TokenType: {
      * A named formula reference, e.g. `TotalRevenue`.
      */
     readonly Named: "named";
+    /**
+     * A `LET` / `LAMBDA` name — its declaration (`x` in `LET(x,1,x+1)`) or a use bound to it. `value` is
+     * a {@link ICalculation.NamedRef} whose `declaration` flag marks the declaration.
+     *
+     * @remarks
+     * Token-only: in a formula tree these remain `named` nodes. Unlike a `named` token it never resolves
+     * against the workbook — its scope is the formula itself.
+     */
+    readonly Parameter: "parameter";
     /**
      * Tokens related to structured reference parsing. (e.g. Table[])
      *

package/types/src/calculation/Types.d.ts

@@ -30,6 +30,20 @@ export interface NamedReference {
      */
     readonly optional?: boolean;
 }
+/**
+ * An error reference — the `value` of an error REFERENCE AST node (`#REF!`, `#NAME?`): the error
+ * itself, and the sheet the dead reference named. INTERNAL, as {@link NamedReference} is.
+ *
+ * @remarks
+ * `scope` is the sheet's stableId once linked, the raw sheet name before. The public counterpart is
+ * {@link ICalculation.ErrorRef}, the `value` of an `error` {@link ICalculation.FormulaToken}, which
+ * carries the error as its label so that the token is plain data; `generateFormulaTokens` projects
+ * this onto that.
+ */
+export interface ErrorReference {
+    readonly error: FormulaError.Known;
+    readonly scope?: string | null;
+}
 /**
  * Pre-computed structured reference (table) query.
  *
@@ -84,11 +98,51 @@ export interface StructuredReference {
  * - `IRange.FixableCellCoords` — a single *cell* reference (`colIndex`/`rowIndex`). Passing this REPLACES
  *   the reference's shape: an existing range collapses to a lone cell (`A1:B2` → `A1`). This is how a
  *   caller says "I mean a cell" without a side-channel flag — the type carries the intent.
+ * - `TableReferenceCoords` — a structured reference, resolved (distinguish via `'tableId' in ref`)
  * - `NamedReference` — a named formula reference (distinguish via `'nameId' in ref`)
  * - `FormulaError.Ref` — a broken reference (`#REF!`)
  * - `null` — no reference at this slot
  */
-export type ReferenceCoords = IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | FormulaError.Ref | null;
+export type ReferenceCoords = IRange.FixableCoords | IRange.FixableCellCoords | TableReferenceCoords | NamedReference | FormulaError.Ref | null;
+/**
+ * The cells a structured reference designates, marked with the table that designates them.
+ *
+ * @remarks
+ * A structured reference names a table, not cells: the table re-resolves it after every structural
+ * change, so a shift that moves cells must leave the reference alone. Without the mark the resolved
+ * coordinates are indistinguishable from an absolute range (every axis is `$`) and the shift paths
+ * rewrote the reference into one. Distinguish via `'tableId' in ref`, as `'nameId' in ref` does for
+ * a name.
+ */
+export interface TableReferenceCoords extends IRange.FixableCoords {
+    /** The stable id of the table. */
+    tableId: string;
+}
+/**
+ * A named formula as a NODE in a graph answer - everything needed to build the range object
+ * that carries it, and nothing that needs the engine.
+ *
+ * @remarks
+ * The calculation layer knows the graph; the model layer knows how to be a range. This struct is
+ * the seam, and it is deliberately plain data: a name crossing into the model used to arrive as an
+ * object carrying lazy graph queries as closures, which meant the model reached into the
+ * calculation to get one and could not have received it over a wire at all. The queries are
+ * public on {@link ICalculation.INamedFormula}, resolved from {@link id} when asked.
+ */
+export interface NamedNodeInfo {
+    /** The name's stable id - also the id of the virtual grid its body compiles into. */
+    id: string;
+    /** The name as authored, unqualified. Scope qualification is the view's job, led by the id. */
+    name: string;
+    /**
+     * The anchor sheet's display NAME, or `null` when it cannot be resolved (a file-loaded name
+     * whose defining sheet is unknowable) - the consumer picks a default sheet then.
+     */
+    sheetName: string | null;
+    /** The anchor cell - the name's defining cell (the active cell at authoring time). */
+    rowIndex: number;
+    colIndex: number;
+}
 /**
  * Options for `IFormulaBlock.setReferenceAt`.
  */
@@ -101,10 +155,37 @@ export interface SetReferenceOptions {
      * Measured in Excel: a row/area delete leaves the qualified form (`Data!#REF!`), which is the
      * breadcrumb naming whose cells went; deleting the sheet itself leaves a bare `#REF!`, since
      * there is no longer a sheet to name. Only the caller knows which of the two it is performing —
-     * `CalcGrid.delete` is walking the precedents OF the grid it is about to drop, while every
+     * `CalcGridBackend.delete` is walking the precedents OF the grid it is about to drop, while every
      * shift path is deleting rows within a sheet that survives. It cannot be inferred here: the
      * sheet is still registered when this rewrite runs, so resolving the qualifier still succeeds.
      */
     scopeDeleted?: boolean;
 }
+/**
+ * A block's static precedent edges in RELATIVE form — one entry per edge, in the order
+ * `resolvedPrecedentsAt` returns them — for the blocks whose edges are the same rects at every
+ * cell's own offset. See {@link IFormulaBlock.getPrecedentTemplate}.
+ */
+export interface PrecedentTemplate {
+    /**
+     * The stored reference behind each edge, translated against the asking cell — or the error the
+     * edge IS (`#REF!`), which is the same at every cell and translates to nothing. The resolver
+     * answers the same error in that slot, so a block whose only reference is broken still has an
+     * edge list it can share, and the blank-aware predicate treats it as an input that does not vary.
+     */
+    readonly relative: readonly (IRange.FixableCoords | FormulaError.Known)[];
+    /**
+     * The SECOND endpoint of an edge written as a range (`A1:B4` — a `:` operator over two cell
+     * leaves, which is how the compiler stores every range); `null` where the edge is one
+     * reference. The edge is then the union of the two translated endpoints, exactly as
+     * `resolvedPrecedentsAt`'s range-operator branch forms it.
+     */
+    readonly second: readonly (IRange.FixableCoords | null)[];
+    /**
+     * Per edge, the compiler's per-axis anchoring — what `resolvedPrecedentsAt` stamps onto the
+     * coords it hands back. Constant for the block, so a materialized buffer is stamped once.
+     */
+    readonly verticalAbs: readonly boolean[];
+    readonly horizontalAbs: readonly boolean[];
+}
 //# sourceMappingURL=Types.d.ts.map