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

package/types/src/{sheet → anomalies}/_Anomalies.d.ts

@@ -3,9 +3,9 @@ import { ICell } from '../cell';
 import { ISpatialMap, ISpatialQuery } from '../collections';
 import { ICellStyle, IStyleCollection } from '../style';
 import { IProperties } from '../type';
-import { IWorksheet } from './IWorksheet';
-import { IgnoredErrors } from './_IgnoredErrors';
-import { CellKind } from './_Kinds';
+import { IWorksheet } from '../sheet/IWorksheet';
+import { IgnoredErrors } from '../sheet/_IgnoredErrors';
+import { CellKind } from '../sheet/_Kinds';
 /**
  * The findings at a cell, interned per map: equal findings are one object, in rank order, so a
  * region's payload identity is its content and the fragments of one finding regroup.

package/types/src/anomalies/_FocusTable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Per focus, the share of a class of finding's regions that held a planted defect of that kind on the
+ * SpreadsheetBench v2 Debugging inputs, and `prior`, the kind's rate over every region. A class is
+ * `check/evidence key/repeats` (`ICellRange.AnomalyFocus`).
+ * @internal
+ */
+export declare const ANOMALY_FOCUS_TABLE: Readonly<Record<string, {
+    readonly prior: number;
+    readonly classes: Readonly<Record<string, number>>;
+}>>;
+//# sourceMappingURL=_FocusTable.d.ts.map

package/types/src/{sheet/_AnomalyFormulaChecks.d.ts → anomalies/_FormulaChecks.d.ts}

@@ -1,7 +1,7 @@
 import { IRange } from '@sheetxl/primitives';
 import { ICalculation } from '../calculation';
 import { SpatialMap } from '../collections';
-import { IWorksheet } from './IWorksheet';
+import { IWorksheet } from '../sheet/IWorksheet';
 import { AnomalySource, FormulaRegion, RoleSource, _Findings } from './_Anomalies';
 type Node = ICalculation.FormulaNode;
 type Rect = IRange.Coords;
@@ -53,6 +53,14 @@ export declare function checkLookupShape(source: AnomalySource, regions: readonl
  * a converter wrapped as unknown (`_XLUDF.`, `'udf'`).
  */
 export declare function checkExternalReference(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `errorConstant`: a formula that is only an error value — `=#DIV/0!`, `=#REF!`. Nobody types
+ * one; it is what a converter leaves when it drops the formula that computed the error. When the
+ * block sits against a data table (`=TABLE(…)`) that spills less than the block covers,
+ * `dataTable` names the table's anchor and `extent` the rectangle the two cover together: the
+ * table's results were replaced by constants.
+ */
+export declare function checkErrorConstant(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
 /** One term of a sum: a reference, added (`1`) or taken away (`-1`). */
 export interface Leaf {
     readonly node: Node;
@@ -122,4 +130,4 @@ export interface Resolved {
 /** Where a cell or range reference lands when its formula sits at `at`; `null` for anything else. @internal */
 export declare function resolve(node: Node, at: At, own: string): Resolved | null;
 export {};
-//# sourceMappingURL=_AnomalyFormulaChecks.d.ts.map
+//# sourceMappingURL=_FormulaChecks.d.ts.map

package/types/src/{sheet/_AnomalyLabelChecks.d.ts → anomalies/_LabelChecks.d.ts}

@@ -18,4 +18,4 @@ export declare function checkKeyLabelMismatch(source: AnomalySource, regions: re
  * other sign — `=-'Debt'!C20` where two other links read `='Debt'!D20`, `='Debt'!E20`.
  */
 export declare function checkSignVsSiblings(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
-//# sourceMappingURL=_AnomalyLabelChecks.d.ts.map
+//# sourceMappingURL=_LabelChecks.d.ts.map

package/types/src/anomalies/_LiteralChecks.d.ts

@@ -0,0 +1,35 @@
+import { AnomalySource, FormulaRegion, _Findings } from './_Anomalies';
+/**
+ * `literalMatchesInput`: a number typed into a formula that equals a typed number on the sheet no
+ * formula reads — `=(-0.595*J19)` with `0.595` in J52, which nothing reads. The reference the
+ * literal replaced is what left the input unread, so an unread input is the signal; a literal
+ * matching an input something still reads is the formula's own constant.
+ *
+ * Small counts, calendar periods and powers of ten never fire (`isConventional`). The nearest
+ * occurrence is the evidence, with its label when it has one, and `matches`, the places the value
+ * is typed, scales the rank down: a value typed all over a data block is a weak witness.
+ */
+export declare function checkLiteralMatchesInput(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `constantFrequency`: every constant a formula types — a number, a string, a boolean — as a
+ * finding of its own, with how often the workbook types it. A model's conventions are typed many
+ * times (`/365` in every days line, `"Total"` in every lookup); a value typed once, or a unit typed
+ * in two rows where the workbook types another in twenty, is the exception to read first. The
+ * count is the second pass's: it adds `uses` and `of` and divides the rank by `uses`, so nothing is
+ * cut and a convention lists last. A number keys without its sign, so `-0.595` and `0.595` are one
+ * constant.
+ */
+export declare function checkConstantFrequency(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `twinBlockDivergence`: twin formulas that differ in a typed number — the formulas on the sheet
+ * with the same shape once references, literals and signs are set aside. `($D136/100)` in one
+ * tranche where the next has `($D145/10000)`; `*(1/360)` beside `*(1/365)`. Every side of a
+ * divergence fires, naming the other side's value and a twin that carries it: two planted rows can
+ * outvote the one that is right, and which literal the business meant is the reader's call. The
+ * side fewer twins carry ranks higher, by `twins / (twins + its own count)`.
+ *
+ * Only a unit pair compares (`isUnitPair`). A position whose values are spread with no plurality
+ * carries no convention and says nothing.
+ */
+export declare function checkTwinBlockDivergence(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+//# sourceMappingURL=_LiteralChecks.d.ts.map

package/types/src/anomalies/_SeriesChecks.d.ts

@@ -0,0 +1,13 @@
+import { AnomalySource, _Findings } from './_Anomalies';
+/**
+ * `scaleOutlier`: a typed percent a hundred times or more off the typical value of the sheet's
+ * typed percents — `30` in a percent cell where the others are around `0.4`: a 30% rate typed as a
+ * whole number, which shows as 3000%. The typical value is the median of the sheet's typed
+ * percents; `times`, the power of ten the value is off by, is the evidence, with the median and
+ * how many numbers it is taken over.
+ *
+ * Read for percents only today: a percent has a scale the format states, so a value off it is a
+ * unit fact rather than a large line item.
+ */
+export declare function checkScaleOutlier(source: AnomalySource, findings: _Findings): void;
+//# sourceMappingURL=_SeriesChecks.d.ts.map

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

@@ -1,9 +1,10 @@
-import { IRange, IRuntime, Scalar } from '@sheetxl/primitives';
+import { IRange, IFunction, IRuntime, Scalar } from '@sheetxl/primitives';
 import { IListener } from '../listener';
 import { FunctionProvider } from '@sheetxl/scripting';
 import { AbstractModel, IModel } from '../model';
 import { ITransaction } from '../transaction';
 import { IStringCollection } from '../string';
+import { IResourceCollection } from '../resource';
 import { IFunctionCollection } from '../scripting';
 import { INamed, INamedCollection } from '../named';
 import { ICellRange, ICellRanges } from '../cellRange';
@@ -44,6 +45,7 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
     protected _engineModule: typeof import('./engine') | null;
     protected _planCache: 'off' | 'assert' | 'on' | null;
     protected _getActiveCell: () => IRange.CellCoords | null;
+    protected _startFunctions: (() => Promise<readonly IFunction[]>) | null;
     protected _getRange: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
     protected _getRanges: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
     /** The current handle of every formula host's grid, by grid id. */
@@ -363,6 +365,14 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
      * read returns the raw text instead (`use-signs.test.ts`).
      */
     protected _drainPending(priorityOnly?: boolean): Promise<void>;
+    /** @inheritdoc ICalculation.getPendingCount */
+    getPendingCount(): number;
+    /** @inheritdoc ICalculation.whenPendingDone */
+    whenPendingDone(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /** @inheritdoc ICalculation.cancelAsync */
+    cancelAsync(options?: ICalculation.CancelOptions): Promise<ICalculation.Status>;
     /** @inheritdoc ICalculation.calculate */
     calculate(options?: ICalculation.CalculateOptions | boolean): Promise<ICalculation.Status>;
     /**
@@ -372,10 +382,14 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
      *          successful one (the tail simply fell off the end), and two call sites cast the result
      *          to `Status` to satisfy {@link ICalculation.calculate}.
      */
-    protected _calculate(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
+    protected _calculate(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): Promise<ICalculation.Status>;
     /** A pass, counted while it runs: what the calculation state reads as a pass in flight. */
-    protected _calculateNow(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
-    protected _runCalculation(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
+    protected _calculateNow(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): Promise<ICalculation.Status>;
+    /**
+     * @param settle The settle pass (DESIGN-ASYNC §4.5): seeded from what a settle marked only;
+     * volatiles and the dirty set are left for the pass that owes them.
+     */
+    protected _runCalculation(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): Promise<ICalculation.Status>;
     /**
      * The model commit the last pass recalculated for, `null` before the first: what a sheet
      * realizing the pass's results amends them into.
@@ -520,13 +534,17 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
      * @internal
      */
     _tableChanged(table: ITable, removed: boolean): void;
-    /** A name written, as {@link _tableChanged} tells a table. */
-    protected _nameWritten(written: NamedFormulaCollection.NamesWritten): void;
+    /** Names written, as {@link _tableChanged} tells a table: one message for a batch. */
+    protected _nameWritten(written: readonly NamedFormulaCollection.NamesWritten[]): void;
+    /** {@link _sendSymbolChanges} for one change. */
+    protected _sendSymbolChange<T>(kind: 'tables' | 'names', id: string, entry: T | null, same: (a: T | null | undefined, b: T | null) => boolean): void;
     /**
-     * One change to a replica, as a message: sent to a `Starting` engine as it is (the channel holds
-     * it in order), and to a `Running` one only when the replica does not already say so.
+     * Changes to a replica, as messages: sent to a `Starting` engine as they are (the channel holds
+     * them in order), and to a `Running` one only where the replica does not already say so, as ONE
+     * message - the replica is rebuilt and reconciled once per message, over every symbol, so a batch
+     * told a symbol at a time costs the square of its size.
      */
-    protected _sendSymbolChange<T>(kind: 'tables' | 'names', id: string, entry: T | null, same: (a: T | null | undefined, b: T | null) => boolean): void;
+    protected _sendSymbolChanges<T>(kind: 'tables' | 'names', changes: readonly (readonly [string, T | null])[], same: (a: T | null | undefined, b: T | null) => boolean): void;
     /**
      * While `Starting`: per kind, the held symbol message a new symbol of that kind joins, and the
      * ids every message of the start has told. Dropped with the channel - see {@link _sendSymbolChange}.
@@ -729,6 +747,8 @@ export declare namespace Calculation {
         authoredAt: IRange.CellCoords;
         /** Each cell of the block is its own 1x1 array-entered formula. See {@link ICalculation.EvaluateOptions.arrayFirstCell}. */
         arrayFirstCell?: boolean;
+        /** How long to wait for the cells' async calls. See {@link ICalculation.EvaluateOptions.timeout}. */
+        timeout?: number;
     }
     /** See {@link Calculation._createFormulaHost}. */
     interface FormulaHostOptions {
@@ -789,6 +809,15 @@ export declare namespace Calculation {
          * @see {@link FunctionProvider}
          */
         functions?: readonly FunctionProvider[];
+        /**
+         * Custom functions to register at every start, ahead of the first pass: a workbook's script
+         * functions, so a formula calling one calculates on load rather than answering `#NAME?`.
+         *
+         * @remarks
+         * Asked once per start, alongside loading the engine. A function the registry refuses (a
+         * built-in's name) is reported and skipped; the start goes on with the rest.
+         */
+        startFunctions?: () => Promise<readonly IFunction[]>;
         /**
          * Returns the active cell — the current selection anchor — with its sheet id as `scope`.
          * Supplies the default scope for temporary / named-formula resolution, and the default
@@ -846,6 +875,15 @@ export declare namespace Calculation {
         getSheetIndex?: (sheetName?: string) => number;
         getSheetCount?: () => number;
         strings?: IStringCollection;
+        /**
+         * The workbook's binary resources (image bytes), for rich values a formula makes.
+         */
+        resources?: IResourceCollection;
+        /**
+         * The workbook's fetch, for async functions (`IFormulaContext.IBatchContext.fetch`). Omitted,
+         * the global `fetch`.
+         */
+        fetch?: (input: string, init?: RequestInit) => Promise<Response>;
         /**
          * Whether to perform iterative calculations when there are circular dependencies.
          *

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

@@ -1,5 +1,4 @@
 import { Scalar } from '@sheetxl/primitives';
-import { ICell } from '../cell';
 import { Tuple } from '../collections';
 import { IExternalBookCollection } from '../externalBook';
 import { CalcGridBackend, FormulaHost } from './grid';
@@ -87,11 +86,11 @@ export declare class ExternalBookBindings {
  * column-major scalar tuples a `CalcGridBackend` loads.
  *
  * @remarks
- * `ICell.JSON`'s untyped arm is a bare primitive, and the cache's strings are LITERAL (never a
+ * `Scalar.JSON`'s untyped arm is a bare primitive, and the cache's strings are LITERAL (never a
  * string-table index — the part inlines them, design doc §1). The typed arm carries an error by
  * code. `null` when the cache holds nothing.
  */
-export declare function cacheToGridTuples(data: Tuple.GridTuple<ICell.JSON> | null | undefined): Tuple.GridTuple<Scalar> | null;
+export declare function cacheToGridTuples(data: Tuple.GridTuple<Scalar.JSON> | null | undefined): Tuple.GridTuple<Scalar> | null;
 export declare namespace ExternalBookBindings {
     interface ConstructorOptions {
         /** The collection to mirror — read fresh on every {@link ExternalBookBindings.sync}. */

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

@@ -19,7 +19,9 @@ export interface ICalculation extends IModel {
      * @returns A promise that will be resolved when the calculation is completed.
      *
      * @remarks
-     * For async functions this will return before they are completed.
+     * For async functions this will return before they are completed. An async function is called
+     * again unless its call is still running; what it fetches is answered
+     * from the workbook's cache unless {@link ICalculation.CalculateOptions.external} is set.
      */
     calculate(options?: boolean | ICalculation.CalculateOptions): Promise<ICalculation.Status>;
     /**
@@ -38,7 +40,7 @@ export interface ICalculation extends IModel {
     /**
      * Resolves once the engine is running and idle: its calculation state is
      * {@link ICalculation.CalculationState.Done}, or {@link ICalculation.CalculationState.Pending} in
-     * manual mode.
+     * manual mode (and, under `AutomaticExceptTables`, with only data tables out of date).
      *
      * @remarks
      * * After it, every answer the engine owes has landed: a formula written before it reads as
@@ -46,14 +48,46 @@ export interface ICalculation extends IModel {
      * * Manual mode does not wait for a recalculation nobody has asked for; call {@link calculate}.
      * * Waits for what consumers derive from the results too ({@link waitUntil}): a conditional
      *   format reads as painted after it, including one a read just asked to evaluate.
-     * * A streaming or async function's result in flight is not waited for: its cell reads as the
-     *   current value until the result arrives.
+     * * An async function's result in flight is not waited for: its cell reads as what the
+     *   function returned until the result arrives.
      * * Starts the engine if it is {@link ICalculation.Status.Off}. An engine in
      *   {@link ICalculation.Status.Error} is not started; {@link start} tries again.
      *
      * @param options Pass `{ full: true }` to recalculate every grid rather than only the dirty ones.
      */
     ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * How many async function calls are waiting for an answer.
+     */
+    getPendingCount(): number;
+    /**
+     * Resolves once no async function call is pending ({@link getPendingCount} is `0`) and every
+     * answer has been calculated into the workbook — Excel's `CalculateUntilAsyncQueriesDone`.
+     *
+     * @param options `timeout` in milliseconds; 30 seconds when absent.
+     * @returns `true` when nothing is pending; `false` when the timeout came first.
+     *
+     * @remarks
+     * * An answer that makes a formula ask a new question (one call's answer is another's input)
+     *   is waited for too.
+     * * {@link ready} is the engine's own readiness and does not wait for answers.
+     */
+    whenPendingDone(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
+     * Stops waiting for async function calls — Excel's *Cancel Refresh*: each pending
+     * call the options cover is closed, and the function is told (its `onCancel`).
+     *
+     * @param options Which calls; every call when absent.
+     * @returns A promise that resolves once the cells have been recalculated.
+     *
+     * @remarks
+     * * A cell keeps what it showed — its last answer, or the value its function returned while it
+     *   waited — and is no longer pending. An answer that arrives later is dropped.
+     * * A recalculation of a cancelled cell calls its function again.
+     */
+    cancelAsync(options?: ICalculation.CancelOptions): Promise<ICalculation.Status>;
     /**
      * Counts `work` that a consumer derives from the engine's results as calculation in flight
      * until it settles: {@link ready} waits for it, and {@link getCalculationState} reads
@@ -1042,6 +1076,14 @@ export declare namespace ICalculation {
          * Use {@link ICalculation.FormulaToken.evalIndex} to discover valid indices.
          */
         evalIndex?: number;
+        /**
+         * How long to wait, in milliseconds, for the answers of async functions the formula calls:
+         * the evaluation resolves once each has answered, and
+         * answers a `#TIMEOUT!` error naming the call it waited on when the time runs out.
+         *
+         * @defaultValue `30000`
+         */
+        timeout?: number;
         /**
          * Temporary range of values to use for this evaluation.
          *
@@ -1174,6 +1216,15 @@ export declare namespace ICalculation {
          * Called when the calculation state has changed - see {@link ICalculation.getCalculationState}.
          */
         onCalculationStateChange?(source: ICalculation): void;
+        /**
+         * Called when the number of async function calls waiting for an answer may have changed — see
+         * {@link ICalculation.getPendingCount}.
+         *
+         * @remarks
+         * Called when calls are made, when answers are applied, and on a cancel or a stop: answers
+         * arriving together are one call.
+         */
+        onPendingChange?(source: ICalculation): void;
         /**
          * Called when a calculation is completed.
          */
@@ -1242,7 +1293,8 @@ export declare namespace ICalculation {
         readonly Calculating: "calculating";
         /**
          * Changes have been made that need a recalculation, and none will run until one is asked for:
-         * manual mode between an edit and {@link ICalculation.calculate}.
+         * manual mode between an edit and {@link ICalculation.calculate}, or the `TABLE` data tables an
+         * edit left out of date under `AutomaticExceptTables`.
          */
         readonly Pending: "pending";
     };
@@ -1313,14 +1365,16 @@ export declare namespace ICalculation {
          */
         readonly Stale: "stale";
         /**
-         * The value is being calculated asynchronously, typically because the function used returned a Promise.
-         * All dependent values will also be in the Pending state. If the promise returns an error or times out, the value will be an error value.
+         * The cell's own function asked for its result later (`FormulaContext.defer`) and it has not
+         * arrived: the cell shows what the function returned meanwhile, and its dependents calculate
+         * from that and read as {@link Waiting}. A failed call answers an error value.
          */
         readonly Pending: "pending";
         /**
-         * The value is up-to-date, but the underlying data source is streaming live updates.
+         * The value was calculated from a pending value — a precedent whose function has not answered —
+         * and will be calculated again when it does.
          */
-        readonly Streaming: "streaming";
+        readonly Waiting: "waiting";
     };
     type ResultStatus = typeof ResultStatus[keyof typeof ResultStatus];
     /**
@@ -1358,6 +1412,39 @@ export declare namespace ICalculation {
          * live in other sheets, and a named formula's body lives in a virtual grid of its own.
          */
         scope?: string;
+        /**
+         * If `true`, what the calculation reads from outside the workbook is read from the source
+         * again rather than from the workbook's cache — Excel's *Data › Refresh All*: what the async
+         * functions it calls fetch, and, for a calculation that is neither {@link range} nor
+         * {@link scope}, every external book (`IExternalBookCollection.refreshAll`).
+         *
+         * @remarks
+         * * Which functions are called is the calculation's own choice, as without it: pass
+         *   {@link full} for every formula. A call still running is left be.
+         * * The calculation resolves without waiting for the new answers or the external books.
+         *
+         * @example Refresh All
+         * ```ts
+         * await workbook.getCalculation().calculate({ full: true, external: true });
+         * ```
+         *
+         * @defaultValue `false`
+         */
+        external?: boolean;
+    }
+    /**
+     * Options for {@link ICalculation.cancelAsync}.
+     */
+    interface CancelOptions {
+        /**
+         * Only the calls of the formulas in this range are cancelled.
+         */
+        range?: ICellRange.Address;
+        /**
+         * Only the calls of the formulas on this sheet, by name, are cancelled. Ignored when
+         * {@link range} is set.
+         */
+        scope?: string;
     }
     interface JSON {
         /**

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

@@ -3,9 +3,9 @@ import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { NamedNodeInfo, ReferenceCoords } from './Types';
-import { INamed } from '../named';
+import { INamed, INamedCollection } from '../named';
 import { ITypes, AbstractCollection } from '../type';
-import { FormulaHost } from './grid';
+import { FormulaHost, ICalcGrid } from './grid';
 import { Formula, IFormulaBlockView } from './formula';
 import { ICalculation } from './ICalculation';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
@@ -75,6 +75,8 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      */
     private _nameIndex;
     constructor(options?: NamedFormulaCollection.ConstructorOptions);
+    /** Loaded names some write has given a state of their own - see {@link NamedFormula._writeNamedState}. */
+    private _written;
     /**
      * Hydrates from `IWorkbook.JSON.names`. A malformed entry is warned and skipped rather than
      * failing the whole load — one bad name must not cost the workbook every other name.
@@ -157,6 +159,27 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      * text and is left alone. Items of another source are not this collection's and are skipped.
      */
     prepareRanges(items: readonly INamed[]): void;
+    /**
+     * {@inheritDoc NamedCollection.Source.removeUnused}
+     *
+     * @remarks
+     * A name that has not compiled has no compiled reader - a formula that reads a name binds it - so
+     * only the compiled ones are asked of the engine. What the engine cannot see is a reader that has
+     * not compiled either: a kept name whose definition spells a candidate keeps it, and whatever that
+     * one spells in turn. By spelling, so lenient - a name wrongly kept costs nothing, one wrongly
+     * removed breaks the name that read it.
+     *
+     * A LAMBDA is called, not bound, so it is never removed; nor is a built-in name (`_xlnm.`),
+     * which the sheet reads rather than any formula.
+     */
+    removeUnused(options: INamedCollection.RemoveUnusedOptions & {
+        scope?: string;
+    }): Promise<number>;
+    /**
+     * Deletes `items` as ONE operation: each item's own writes, then a single rewrite of the set.
+     * Deleted one at a time, each removal copies the set, and a legacy file's names are thousands.
+     */
+    protected _removeMany(items: readonly NamedFormula[]): void;
     /**
      * Compiles the loaded names among `items` that have not compiled, as ONE operation.
      *
@@ -306,6 +329,8 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      */
     _addNamesWrittenListener(listeners: IListener.Callbacks<NamedFormulaCollection, NamedFormulaCollection.NamesWrittenEvents>): IListener.Remove;
     protected _notifyNamesWritten(item: NamedFormula, removed: boolean): void;
+    /** {@link _notifyNamesWritten} for a batch, told as one. */
+    protected _notifyManyWritten(items: readonly NamedFormula[], removed: boolean): void;
     /**
      * Every name as {@link _addNamesWrittenListener} tells one: what a listener starts from.
      * @internal
@@ -331,7 +356,7 @@ export declare namespace NamedFormulaCollection {
     }
     /** See {@link NamedFormulaCollection._addNamesWrittenListener}. */
     interface NamesWrittenEvents {
-        onNamesWritten?(source: NamedFormulaCollection, written: NamesWritten): void;
+        onNamesWritten?(source: NamedFormulaCollection, written: readonly NamesWritten[]): void;
     }
     interface ConstructorOptions {
         /**
@@ -396,6 +421,12 @@ export declare namespace NamedFormulaCollection {
         recompileNamed(nameId: string): void;
         /** The root of the name's compiled body, or `null` while it has none. */
         getBodyNode(nameId: string): ICalculation.FormulaNode | null;
+        /**
+         * The name's precedents or dependents, cells in calc currency and names, as the engine walks
+         * them - asked by the name's id, so a name that has not compiled is asked without compiling it.
+         * Nothing while the engine is `Off`.
+         */
+        getNameGraph(nameId: string, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
         /**
          * 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,
@@ -457,7 +488,10 @@ interface NamedFormulaWireOptions {
  * supplied is implemented here against the transaction store the item already holds.
  */
 declare class NamedFormula extends Formula implements ICalculation.INamedFormula, INamed<string> {
-    /** Transactional state — see the field docs on `_transactions`. */
+    /**
+     * Transactional state — see the field docs on `_transactions`. A loaded name nothing has written
+     * reads what the file said, as does one an undo took back past its first write.
+     */
     private _getNamedState;
     private readonly _id;
     /**
@@ -465,7 +499,19 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * mutation is undoable.
      */
     private readonly _transactions;
-    private readonly _stateId;
+    /**
+     * `null` for a loaded name until its first write: every commit copies the store's snapshot, and a
+     * legacy file's tens of thousands of names were nearly all of it. See {@link _writeNamedState}.
+     */
+    private _stateId;
+    /** What a loaded name's file said: its state until written, and again when undone past that write. */
+    private readonly _loaded;
+    /** Tells the collection a loaded name has a state now, so it hears an undo that removes it. */
+    private readonly _noteWritten;
+    /** Whether the collection lists this item now — a loaded name's deletion when it has no state. */
+    private readonly _isListed;
+    /** {@link _loaded}, deleted. */
+    private _loadedDeleted;
     private readonly _deleteFromCollection;
     private readonly _wire;
     /** Refuses a rename that would collide with a sibling — see {@link setName}. */
@@ -484,6 +530,11 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     private readonly _notifyCollection;
     /** The collection's {@link NamedFormulaCollection._addNamesWrittenListener}, for a rename. */
     private readonly _notifyNameWritten;
+    /**
+     * Made on the first `addListeners`. Every emitter on the shared store is told of every commit, and
+     * a legacy file's tens of thousands of names nothing listens to made each commit pay for all of
+     * them. Until it exists there is nobody to notify.
+     */
     private _emitter;
     private _transactionsRemoveListener;
     private _closed;
@@ -528,8 +579,48 @@ 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.
      */
+    /** Hears this name's own state: made with the item, or by a loaded name's first write. */
+    private _listenToState;
+    /**
+     * Whether an undo has taken this loaded name back past its first write: it has a state id, and
+     * the snapshot the store is at does not hold it.
+     * @internal
+     */
+    _isStateAbsent(): boolean;
+    /**
+     * An undo/redo repointed the store.
+     * @internal
+     */
+    _onRestoreOrRevert(): void;
+    /**
+     * {@link delete}'s own writes, inside an operation the collection holds — its removal from the
+     * set is the caller's, made once for many.
+     *
+     * @remarks
+     * A loaded name nothing has written writes no state: not being listed is its deletion (see
+     * {@link _getNamedState}), so deleting a legacy file's thousands of names adds nothing to every
+     * later commit's snapshot.
+     * @internal
+     */
+    _deleteWithin(trans: ITransaction): void;
+    /**
+     * Adds every identifier this name's definition spells, lowercased, to `into` — nothing for a
+     * literal, which reads no name.
+     * @internal
+     */
+    _addSpelledNames(into: Set<string>): void;
+    /**
+     * Writes this item's state in `trans`.
+     *
+     * @remarks
+     * A loaded name has no state until this runs: it is made here, inside the write, so the commit
+     * before the write has none and an undo past it reads {@link _loaded} again. Whenever the
+     * snapshot holds no state - the first write, or one after such an undo - the write carries the
+     * whole of it, since an update merges onto what the store holds.
+     */
+    private _writeNamedState;
     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);
+    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, noteWritten?: () => void, isListed?: () => boolean);
     /**
      * Writes this name's body, which binds it to the region its expression designates once the
      * engine answers.
@@ -811,10 +902,15 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     getPrecedents(): Promise<ICellRanges | null>;
     /**
      * 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).
+     * them (see `CalcBackend._nameGraphNow` for the walk: the symbol edges names ride on, and the
+     * cell graph between them).
      *
      * @remarks
+     * Only the precedents read the body, so only they compile it, and a literal has none. The
+     * dependents are asked by id and never compile: a formula that reads this name bound it when it
+     * compiled, so a name still waiting for its first use has no compiled reader to find — and a
+     * report asking every name of a legacy file must not compile thousands of them to learn that.
+     *
      * 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.

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

@@ -1,6 +1,6 @@
 /**
  * The clone boundary: a test mode that treats the model/engine crossing as if it were a wire
- * (DESIGN-CALC-SERVICE §11, goal G1, plan step 6).
+ * (DESIGN-CALC-SERVICE §11, goal G1).
  *
  * @remarks
  * Every request into a grid and every {@link ICalcGrid.Results} out of one passes through here.

package/types/src/calculation/compiler/ASTTypes.d.ts

@@ -235,10 +235,14 @@ export interface NamedNode extends ASTNode<typeof TokenType.Named, NamedReferenc
 }
 export interface FunctionNode extends ASTNode<typeof TokenType.Function, any> {
     /**
-     * Re use this as a cache for built-in static functions.
-     *
+     * The function this call resolved to.
      */
     cacheFn?: IFunction;
+    /**
+     * The registry stamp `cacheFn` resolved under, for a custom function; `undefined` for a built-in,
+     * which never changes.
+     */
+    cacheFnStamp?: number;
 }
 export type ParenNode = ASTNode<typeof TokenType.Paren>;
 /**