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

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

@@ -1,13 +1,12 @@
-import { IRange, Scalar, IFormulaContext } from '@sheetxl/primitives';
+import { IRange, Scalar } 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 { IContextContainer } from './state';
-import { Formula, IFormulaBlock } from './formula';
+import { ITypes, AbstractCollection } from '../type';
+import { FormulaHost } from './grid';
+import { Formula, IFormulaBlockView } from './formula';
 import { ICalculation } from './ICalculation';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
 interface State {
@@ -28,20 +27,24 @@ 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;
-    protected _container: IContextContainer | null;
-    protected _context: IFormulaContext | null;
+    /**
+     * `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 _engine: NamedFormulaCollection.Engine | null;
+    protected _bindSheet: ((scope: string) => string | null) | 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 +56,24 @@ 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;
+    /**
+     * The items by their upper-cased name: what {@link getByName} and {@link _findSameIdentity}
+     * read instead of scanning the set.
+     *
+     * @remarks
+     * A derived cache, not state - the set stays keyed by id (see `State`). It answers for one
+     * store position: the commit, the operation open on it, and the set's own map. Anything that
+     * moves one of those without passing through {@link _indexItem} (a restore, a rollback, a
+     * commit closing) rebuilds it on the next read, once over the set; a write made here keeps it
+     * current in place, so a load of thousands of names costs each one a map lookup rather than a
+     * scan - which, over the names a legacy file carries, was the larger part of opening it.
+     */
+    private _nameIndex;
     constructor(options?: NamedFormulaCollection.ConstructorOptions);
     /**
      * Hydrates from `IWorkbook.JSON.names`. A malformed entry is warned and skipped rather than
@@ -65,8 +86,20 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
      * be listed, and still evaluate to `#NAME?`.
      *
      * Not on `INamedFormulasCollection`: hydration belongs to whoever constructs the engine.
+     *
+     * A loaded name BINDS now and COMPILES on first use (see {@link NamedFormula._materialize}). A
+     * legacy file carries thousands of names nothing reads, and compiling one costs a grid of its own
+     * in the model's store, which every later commit copies. Until a reader binds the name, or the
+     * item is asked something only a compiled body answers, it answers from its state - and a loaded
+     * expression is already the file's sheet-qualified form, so the text is what a save writes back
+     * either way. A lambda-valued name is the exception: it is reached as a FUNCTION, by name, not
+     * through a symbol bind, so nothing would compile it ahead of the call.
      */
-    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;
+    /** The set's map as the running {@link hydrate} made it - see `add`. */
+    private _hydratingItems;
     /**
      * Serializes to `IWorkbook.JSON.names` form, sorted by scope+name so output is stable across
      * saves.
@@ -87,9 +120,57 @@ 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;
+    /**
+     * {@link add}, with the choice of WHEN the name compiles.
+     *
+     * @param lazy `true` for a loaded name: the item is recorded, indexed and announced, and its body
+     * compiles on first use (see {@link hydrate}). A name authored through the API compiles at once -
+     * the author expects `getRanges()` after `ready()`, and the wire is what qualifies a bare reference.
+     */
+    protected _add(options: INamedFormulasCollection.AddOptions, lazy: boolean): ICalculation.INamedFormula;
+    /**
+     * Compiles every loaded name whose text mentions the sheet, and has not compiled yet.
+     *
+     * @internal
+     *
+     * @remarks
+     * A compiled body follows the sheets it reads: a shift of their cells moves its references, and
+     * a rename re-images it from the sheet's id. Text follows nothing. So before a change of that kind
+     * lands, every name still answering from its text that could be reading the sheet is compiled,
+     * and the change reaches a body. A name that mentions no sheet at all - an error, an array
+     * constant, a number - is left as it is. The test is a spelling in the text, which is wider than
+     * a reference (a sheet called `A` is mentioned by nearly everything): a wide net compiles more
+     * than it needs to, a narrow one would leave a name pointing at the wrong cells.
+     */
+    _materializeMentioning(sheetName: string): void;
+    /**
+     * {@inheritDoc NamedCollection.Source.prepareRanges}
+     *
+     * @remarks
+     * Compiles, as one batch, the loaded names among `items` whose `getRanges()` would otherwise
+     * compile them one at a time: a name whose text is a literal or a plain address answers from its
+     * text and is left alone. Items of another source are not this collection's and are skipped.
+     */
+    prepareRanges(items: readonly INamed[]): void;
+    /**
+     * Compiles the loaded names among `items` that have not compiled, as ONE operation.
+     *
+     * @remarks
+     * Compiled one by one outside an operation, each name opens a commit of its own on the model
+     * store, so its grid lands under its own engine commit - and every engine commit copies the
+     * engine's registries, which hold an entry per sheet and per compiled name. A loop over the names
+     * of a legacy file (ten thousand of them) is then quadratic, in time and in memory held until the
+     * loop yields. Under one operation the names share one landing, one engine commit and one clone
+     * key, and the engine collects the grids they make into one write ({@link Engine.collectGrids}).
+     *
+     * @internal
+     */
+    _materializeMany(items: readonly NamedFormula[]): void;
     /**
      * A name has just been bound to the region it designates.
      *
@@ -110,21 +191,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 +228,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 +251,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`.
      *
@@ -203,6 +271,14 @@ export declare class NamedFormulaCollection implements INamedFormulasCollection
      * Backs both the duplicate check in {@link add} and the collision check on rename.
      */
     protected _findSameIdentity(name: string, scopeId: string | null): NamedFormula | null;
+    /** The items named `upper` (already upper-cased), through {@link _nameIndex}. */
+    protected _itemsNamed(upper: string, state: State): readonly NamedFormula[];
+    /**
+     * A write made here - an item added, renamed or removed - keeps {@link _nameIndex} current
+     * rather than costing the next read a rebuild. The set's map is read again, as the write has
+     * just replaced it.
+     */
+    protected _indexItem(item: NamedFormula, removed: boolean): void;
     /**
      * Resolves a caller's `scope` input to the sheet's stableId.
      *
@@ -215,18 +291,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
@@ -238,8 +344,8 @@ export declare namespace NamedFormulaCollection {
          */
         json?: INamed.JSON[];
         transactions?: ITransaction.IStore;
-        container?: IContextContainer;
-        context?: IFormulaContext;
+        /** What a name tells the engine it compiles into, and reads back from it. */
+        engine?: NamedFormulaCollection.Engine;
         ready?: () => Promise<ICalculation.Status>;
         getRange: (address: ICellRange.Address) => ICellRange;
         /** Resolves an address to ranges. Backs {@link ICalculation.INamedFormula.getReferences}. */
@@ -250,14 +356,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. Without it, a scope binds to nothing.
+         */
+        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;
         /**
@@ -270,10 +385,34 @@ export declare namespace NamedFormulaCollection {
          */
         isEngineReady?: () => boolean;
     }
+    /**
+     * What a name asks of the engine it compiles into. Held from before the engine starts: each call
+     * reaches the engine once there is one, and waits for it until then.
+     */
+    interface Engine {
+        /** The name's resolution moved: the formulas that read it are out of date. */
+        invalidateNamed(nameId: string): void;
+        /** The name's body changed or went: the formulas that read it compile again. */
+        recompileNamed(nameId: string): void;
+        /** The root of the name's compiled body, or `null` while it has none. */
+        getBodyNode(nameId: string): ICalculation.FormulaNode | null;
+        /**
+         * Runs `batch` with the grids it makes collected into one write of the engine's registry, under
+         * one clone key - see `CalcBackend._collectingGrids`. Without it each grid is its own write,
+         * each copying the registry: a burst of a thousand compiles costs a thousand copies of a
+         * thousand entries, all of them reachable until the burst yields.
+         */
+        collectGrids?<R>(batch: () => R): R;
+    }
 }
 interface NamedFormulaWireOptions {
-    container: IContextContainer;
-    context: IFormulaContext;
+    engine: NamedFormulaCollection.Engine;
+    /**
+     * Makes the host that holds the body - the same one again for the same name, see
+     * `NamedFormulaCollection.ConstructorOptions.createHost`. `null` for a name that has no grid (no
+     * proxy id was bound for it).
+     */
+    createHost: (() => FormulaHost) | null;
     ready: () => Promise<ICalculation.Status>;
     /** Returns the scope's sheet gridId (for reference resolution). Resolved after ready(). */
     getScopeGridId: () => string | null;
@@ -295,7 +434,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 +482,38 @@ 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, and for a loaded name nothing has read yet.
+     * See {@link _block} and {@link _materialize}.
+     */
+    private _host;
+    /** A loaded name, compiled on first use - see `NamedFormulaCollection.hydrate`. */
+    private readonly _lazy;
+    /** A {@link _materializeLater} is queued and has not run. */
+    private _materializeQueued;
+    /**
+     * 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 +528,81 @@ 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, lazy?: boolean);
     /**
-     * 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;
+    /**
+     * A loaded name that answers from its text: no host, or one whose grid a restore has left
+     * without state (see `CalcGrid._revive`), so no compiled body.
+     * @internal
+     */
+    _isUnmaterialized(): boolean;
+    /**
+     * Gives a loaded name what a name authored through the API has from the start: a host, and the
+     * body compiled into it. The first use of the name calls this - a reader binding it, or an ask
+     * only the compiled body answers (`getRanges`, the graph, `evaluate`, a redefinition). Nothing
+     * more than bookkeeping for a name that has it already.
+     *
+     * @internal
+     *
+     * @remarks
+     * Folded into the current commit: the host writes as `FormulaHost._amendCurrent` does. So an undo
+     * past the edit whose reader compiled the name leaves the item without a body in its grid - the
+     * unmaterialized state again, with the host object still held - and the next use writes the body
+     * once more rather than assuming it is there.
+     */
+    _materialize(): void;
+    /**
+     * {@link _materialize} at the next safe point: for a caller inside the engine's own work (the
+     * compile of a formula that mentions this name), where a body cannot be written.
+     * @internal
+     */
+    _materializeLater(): void;
+    /**
+     * For a loaded name that has not compiled: its text as a list of sheet-qualified addresses
+     * (`Sheet1!$A$1:$B$2`, `'Q1'!$A:$A,'Q2'!$A:$A`), or `null` when the text is anything else.
+     *
+     * @remarks
+     * Read with the address grammar the API's `getRanges(address)` reads - a cell, a range, an entire
+     * row or column, a comma list of those - and nothing wider. A text that is a function, a name, an
+     * error, an array constant, an intersection or a bare reference does not parse, and only the
+     * compiler can say what it designates; the caller compiles then. What does parse is what the
+     * compiler would have called reference-only and resolved to these same cells, so the name can
+     * answer {@link getRanges} without a grid of its own - the Name Box asks every name what it
+     * designates, and a file's thousands of names must not all compile for the question.
+     */
+    private _parseAddressText;
+    /**
+     * For a loaded name that has not compiled: whether its text is a literal - a number, a string, a
+     * boolean, an error or an array constant - and so designates no cells whatever the compiler would
+     * make of it.
+     *
+     * @remarks
+     * The names a decades-old model carries by the thousand are exactly these (macro-sheet
+     * constants, dead `#REF!`s), and a report that asks every name what it covers must not compile
+     * them for an answer that is `null` by the shape of the text. Strict on purpose: `#REF!$A$1` or
+     * `{1,2}+A1` is not matched and compiles, where the compiler's answer is the only correct one.
+     */
+    private _isLiteralText;
+    /**
+     * Whether `getRanges()` on this name would compile it: a loaded name that has not compiled and
+     * whose text is neither a literal nor a plain address list. What a batch compiles ahead of a loop
+     * that asks each name in turn ({@link NamedFormulaCollection.prepareRanges}).
+     * @internal
+     */
+    _compilesForRanges(): boolean;
+    /** Records what the readers have been reconciled with — see `_seenBlock`. */
+    private _recordSeen;
     /**
      * {@inheritDoc INamed.getId}
      *
@@ -465,6 +687,8 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     setExpression(expression: string, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc INamed.getComment} */
     getComment(): string | null;
+    /** {@inheritDoc ICalculation.INamedFormula.getFileAttributes} */
+    getFileAttributes(): Readonly<INamed.FileAttributes> | null;
     /** {@inheritDoc INamed.setComment} */
     setComment(comment: string | null, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc INamed.isHidden} */
@@ -557,12 +781,18 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      *    Consumers requery once the engine has started.
      * 3. **Wiring bailed.** `_doWireCore` returns early when the scope sheet cannot be resolved,
      *    which leaves the item permanently unwired rather than transiently.
+     *
+     * A loaded name that has not compiled answers from its text when the text is a plain address
+     * list (see {@link _parseAddressText}) or a literal (see {@link _isLiteralText}, case 1 without
+     * the compile); any other text compiles it, and the answer is case 2.
      */
     getRanges(): ICellRanges | null;
+    /** {@inheritDoc ICalculation.IFormula.getReferences} */
+    getReferences(): 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 +804,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 +842,35 @@ 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. */
+    /**
+     * Pre-wire fallback: return false before block is compiled. A loaded name that has not compiled
+     * answers as {@link getRanges} does, from its text.
+     */
     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.
+     * 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.
      */
-    getReferences(): ICellRanges | null;
-    setReferenceAt(_index: number, _reference: any, _options?: any): this;
-    setReferenceModeAt(_index: number, _side?: ICalculation.ReferenceSide, _mode?: number, _options?: any): this;
-    private _wireAsync;
+    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;
 }