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

package/types/src/.generated/wasm/sdk.d.ts

@@ -23,11 +23,6 @@ export class MetricsTable {
      * characters measured on demand after [`Self::fill`].
      */
     fill_per_em(codepoints: Uint32Array, per_em: Float32Array): void;
-    /**
-     * Records Excel's row pitch at every integer ppem from `first_ppem`, from a `.rows.json`;
-     * `line_pitch` and `wrap` size lines by it from then on. `false` with fewer than two sizes.
-     */
-    fill_rows(first_ppem: number, pitches: Uint16Array): boolean;
     /**
      * Whether nothing has been recorded.
      */
@@ -36,10 +31,6 @@ export class MetricsTable {
      * The number of characters recorded.
      */
     len(): number;
-    /**
-     * Excel's row height for this face at `px` pixels per em.
-     */
-    line_pitch(px: number): number;
     /**
      * An empty table for a face with these vertical metrics per em (`usWinAscent / unitsPerEm`,
      * `usWinDescent / unitsPerEm`): what the host's own table keeps, whether it came from a
@@ -51,48 +42,35 @@ export class MetricsTable {
      */
     text_width(text: string, px: number, letter_spacing: number, super_sub: boolean): number;
     /**
-     * Wraps `text`; `max_width` and `max_height` of zero or less mean none. Returns the lines
-     * flat, eight numbers each (`sheetxl_text::wrap::Wrapped::flatten`).
+     * Wraps `text` in lines `line_height` px tall, the font's box centered in each; `max_width`
+     * and `max_height` of zero or less mean none. Returns the lines flat, eight numbers each
+     * (`sheetxl_text::wrap::Wrapped::flatten`).
      *
      * Scalars rather than an options object, deliberately: each crosses for free, an object
      * would be marshalled.
      */
-    wrap(text: string, px: number, max_width: number, max_height: number, indent: number, letter_spacing: number, super_sub: boolean): Float32Array;
+    wrap(text: string, px: number, line_height: number, max_width: number, max_height: number, indent: number, letter_spacing: number, super_sub: boolean): Float32Array;
 }
 
-/**
- * The alphabetic baseline's offset from the top of a line box of [`line_pitch`] height.
- */
-export function baseline(ascent: number, descent: number): number;
-
 /**
  * The number of Unicode scalar values in `text` (not `text.length`, which counts UTF-16 units).
  */
 export function char_count(text: string): number;
 
-/**
- * Excel's line pitch for a font: `ascent + descent + 2`, in whole pixels.
- */
-export function line_pitch(ascent: number, descent: number): number;
-
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_metricstable_free: (a: number, b: number) => void;
-    readonly baseline: (a: number, b: number) => number;
     readonly char_count: (a: number, b: number) => number;
-    readonly line_pitch: (a: number, b: number) => number;
     readonly metricstable_fill: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly metricstable_fill_hinting: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly metricstable_fill_per_em: (a: number, b: number, c: number, d: number, e: number) => void;
-    readonly metricstable_fill_rows: (a: number, b: number, c: number, d: number) => number;
     readonly metricstable_is_empty: (a: number) => number;
     readonly metricstable_len: (a: number) => number;
-    readonly metricstable_line_pitch: (a: number, b: number) => number;
     readonly metricstable_new: (a: number, b: number) => number;
     readonly metricstable_text_width: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
-    readonly metricstable_wrap: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+    readonly metricstable_wrap: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;

package/types/src/address/AddressUtils.d.ts

@@ -94,6 +94,14 @@ export declare function stringToCoordsArray(str: string, defaultRange: Readonly<
 export declare function coordsArrayToStringArray(coords: readonly (Partial<IRange.Coords | IRange.CellCoords> | string)[], defaultRange?: Readonly<IRange.Coords>, toStringRange?: RangeToString, //fixableRangeToString,
 toStringCell?: CellToString, r1c1?: boolean): string[] | null;
 export declare function coordsArrayToString(coords: readonly (Partial<IRange.Coords | IRange.CellCoords> | string)[], defaultRange?: Readonly<IRange.Coords>, toStringRange?: RangeToString, toStringCell?: CellToString, r1c1?: boolean): string;
+/**
+ * Reads the arguments of `getRange(rowStart, colStart, rowEnd, colEnd)`: zero-based, ends inclusive.
+ *
+ * @remarks
+ * Left out of the declarations on purpose. There is one documented way to say this, the coords
+ * object; this is for scripts that guess, which should get the range they meant, or an error.
+ */
+export declare function indexesToCoords(args: ArrayLike<unknown>): IRange.Coords;
 export declare function rangesAddressToRangesCoords<R extends IRange.Coords = IRange.Coords, C extends IRange.CellCoords = IRange.CellCoords>(address: ICellRanges.Address | ICell.Address, defaultRange: Readonly<R>, toRange?: StringToRange, onNoParse?: (coord: Partial<C | R> | string) => readonly R[], allowR1C1?: boolean): R[];
 /** `Fast` just scans through each character. */
 export declare function fastStringToCell(address: string, reuse?: IRange.CellCoords): IRange.CellCoords | undefined;

package/types/src/address/_SheetNameQuoteChars.d.ts

@@ -0,0 +1,3 @@
+/** Whether Excel quotes a sheet name for containing this UTF-16 code unit. Only meaningful above U+007F. */
+export declare function isQuotedSheetNameChar(code: number): boolean;
+//# sourceMappingURL=_SheetNameQuoteChars.d.ts.map

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,5 @@
+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, IFormulaContext, 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';
@@ -26,7 +27,6 @@ import { INamedFormulasCollection } from './INamedFormulasCollection';
 export declare class Calculation extends AbstractModel<AbstractModel.State, ICalculation.JSON, ICalculation.IListeners> implements ICalculation {
     protected _backend: CalcBackend | null;
     protected _startReplica: CalcBackend.Replica | null;
-    /** The symbols formulas bind through (DESIGN-CALC-SERVICE §8): the model's, handed to the backend. */
     protected _symbols: ISymbolRegistry;
     protected _status: ICalculation.Status;
     protected _statusTransition: Promise<void> | null;
@@ -44,12 +44,12 @@ 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. */
     protected _formulaHosts: Map<string, FormulaHost>;
     protected _modelStore: ITransaction.IStore | null;
-    /** The model-side grids, by grid id (DESIGN-CALC-SERVICE §13.23): what a copy lands on, what a start seeds from. */
     protected readonly _fronts: Map<string, CalcGrid>;
     /** What each model grid is, for the `create` a start sends for it (its size is read then). */
     protected readonly _gridSpecs: Map<string, CalcGridSpec>;
@@ -80,6 +80,12 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
     /** `ready()` calls waiting for work in flight to end: woken on every check. */
     protected _calculationStateWaiters: (() => void)[] | null;
     protected _bootFull: boolean;
+    /** The full boot pass is the load's own, not one a caller asked for: see {@link _calculateForLoad}. */
+    protected _bootFullForLoad: boolean;
+    /** Something was edited ahead of the boot pass, so what a cell was saved with may be out of date. */
+    protected _bootEdited: boolean;
+    /** The next pass is the one a load owes: see `CalcExecutor.ExecuteOptions.load`. */
+    protected _passForLoad: boolean;
     /** Consumer work not yet settled: see {@link waitUntil}. */
     protected _consumerWork: number;
     protected _bootExplicit: boolean;
@@ -211,11 +217,6 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
      * only inside a calculation. The drain is a safe point, not a synchronization point.
      */
     _whenSafe(action: () => Promise<unknown>, priority?: boolean): void;
-    /**
-     * Sends a grid request through the channel (DESIGN-CALC-SERVICE §4): applied now on a `Running`
-     * engine, held in send order while `Starting`, and neither recorded nor sent on an `Off` one -
-     * the caller's own view is the truth there, and a start is seeded from it.
-     */
     protected _sendRequest(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
     protected _sendRequestNow(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<CalcResponse>;
     /** Re-judges every held request: `dead` is what `isDead` answers for it now. */
@@ -241,41 +242,7 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
      * batch is the engine's answer to what the model already holds.
      */
     protected _underOneModelOperation<R>(batch: () => R): R;
-    /**
-     * @internal
-     * Resolves once the engine can compile: at once when `Running`; when the batch has applied the
-     * seeds, ahead of the boot pass, while `Starting`; and, when `Off`, once something else starts
-     * it. It never starts the engine itself.
-     *
-     * @remarks
-     * What an owner that registers a formula asynchronously waits on (a condition formula's
-     * evaluation). Waiting on {@link ready} instead resolves after the boot pass, and the
-     * registration then costs a pass of its own (design §6.5: a boot owes one).
-     *
-     * An `Off` engine stays off (DESIGN-CALC-ON-LOAD: under `calcOnLoad: 'none'` a read starts
-     * nothing, and a conditional format or data validation evaluating on load is a read). Starting it
-     * here ran the boot pass, and the pass moved cached values — every volatile, every iterating
-     * cycle — in a workbook that was only being opened and saved. The waiter is released by the
-     * start the first mutation (or an explicit calculation) makes, and by {@link close}.
-     */
     _whenCanCompile(): Promise<void>;
-    /**
-     * The start batch (DESIGN-CALC-SERVICE §6.3), in the order the service owns: service-level
-     * content first (the names, wired from the priority queue), then the channel in send order
-     * (every seed and every request made while the engine was coming up), then the owners that
-     * hold a formula of their own (a host whose grid lost its body writes it again; a watch held for
-     * the engine registers inside `onReady`), then the one pass the boot owes.
-     *
-     * @remarks
-     * `isLoading()` holds for the whole batch, so a grid seeded here owes its pass rather than
-     * running one against siblings not yet seeded. The pass itself runs on a task of its own
-     * ({@link _runBoot}): a consumer whose registration chains through promises resolved here (a
-     * data validation's, a conditional format's) lands ahead of it, and N of them cost one pass.
-     *
-     * A held request lands under the engine's current commit: the snapshot it named has been
-     * mirrored already, so its writes belong to the tip, and the maps are versioned under that key.
-     * One whose snapshot the model has undone since is skipped.
-     */
     protected _boot(): Promise<void>;
     /**
      * Posts the boot pass on a task of its own, and answers the promise `start()`, `ready()` and a
@@ -284,6 +251,13 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
     protected _scheduleBoot(): Promise<void>;
     /** The boot pass: what the batch, and the consumers that registered since, owe - once. */
     protected _runBoot(): Promise<void>;
+    /**
+     * The full pass a load owes: a file that asks for one, or one whose `calcId` says it needs one.
+     * It evaluates what the file holds without reaching for anything outside the workbook, where a
+     * full calculation a caller asks for does.
+     * @internal
+     */
+    _calculateForLoad(): Promise<ICalculation.Status>;
     /**
      * Posts a microtask drain, if one is not already coming.
      *
@@ -363,6 +337,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 +354,10 @@ 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>;
+    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.
@@ -434,14 +416,6 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
      * @internal
      */
     protected _evaluateOver(options: Calculation.EvaluateOverOptions): Promise<IRange>;
-    /**
-     * A grid for a model to hold (DESIGN-CALC-SERVICE §13.23): the synchronous half, versioned in
-     * the model's store, forwarding every verb as a request. The engine's grid is made by the
-     * grid's first request, `create`, which an `Off` engine drops: a start makes it then, from this
-     * one. What the engine pushes reaches the owner through the grid's events. It opens empty: the
-     * owner attaches its listeners, then seeds it.
-     * @internal
-     */
     _createCalcGrid(options: Calculation.CalcGridOptions): CalcGrid;
     /** What a `create` for a model grid carries: its description. */
     protected _specOf(front: CalcGrid): CalcGridSpec;
@@ -480,20 +454,6 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
     protected _heldSheets(): Calculation.SheetList['sheets'];
     /** One sheet of {@link _heldSheets} by its grid id, or `undefined` for a grid that is no sheet. */
     protected _heldSheetAt(id: string): Calculation.SheetList['sheets'][number] | undefined;
-    /**
-     * The owner's sheet list as it is now: every sheet's grid id and name, in tab order, hidden ones
-     * included (DESIGN-CALC-SERVICE §8). The owner calls this whenever its list changes - a sheet
-     * added, deleted, moved, copied or renamed - and before any grid that names a sheet in it
-     * seeds. Not on a restore: this record is restored with the owner's own, and the engine's
-     * replica with the engine's store.
-     *
-     * @remarks
-     * Held in the caller's operation (folded into the current commit when none is open) and sent
-     * to the engine as one `sheets` message: applied at once on a `Running` engine, held in order
-     * while `Starting`. An `Off` engine is told nothing; its next start seeds the replica from this
-     * record, and owes a full pass only when a sheet already listed was renamed, moved or removed.
-     * @internal
-     */
     _setSheets(sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[]): void;
     /**
      * Compiles every loaded name whose text mentions the sheet, ahead of a change a compiled body
@@ -520,13 +480,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}.
@@ -561,18 +525,7 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
     _replicaNameId(name: string, scope: string | null | undefined): string | undefined;
     /** See {@link _modelSymbols}. */
     protected _modelSymbolRegistry: ISymbolRegistry;
-    /**
-     * The model's symbol map (DESIGN-CALC-SERVICE §8): what the facade images the engine's records
-     * against. Sheets answer from the model's live list; the rest from the engine's providers.
-     * @internal
-     */
     _modelSymbols(): ISymbolRegistry;
-    /**
-     * What images a grid's records for the model (DESIGN-CALC-SERVICE §8): the model's symbol map,
-     * the grid as home scope, its bounds and the reader's locale, both read live so a rename or a
-     * locale switch shows without a recompile.
-     * @internal
-     */
     _imagerFor(gridId: string): FormulaImager;
     /** Every sheet's grid id in tab order, from the replica. */
     protected _sheetIds(): readonly string[];
@@ -729,6 +682,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 +744,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
@@ -831,21 +795,24 @@ export declare namespace Calculation {
         names?: INamed.JSON[];
         getRanges?: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
         getRange?: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
-        /**
-         * Builds ONE `ICellRanges` graph answer out of cell coords plus defined-name nodes.
-         *
-         * @internal
-         *
-         * @remarks
-         * The seam that keeps the layers apart: the calculation layer knows WHICH names belong in a
-         * precedents/dependents answer, the range layer knows how a name rides in one (an anchored
-         * `INamedRange` — see DESIGN-NAMED-FORMULAS.md §4). Structural like `getRange`/`getRanges`,
-         * and like them supplied by the workbook. Without it, graph answers fall back to cells only.
-         */
         createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly NamedNodeInfo[]) => ICellRanges | null;
         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.IDeferContext.fetch`). Omitted,
+         * the global `fetch`.
+         */
+        fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+        /**
+         * How async functions read delimited text (`IFormulaContext.IDeferContext.parseText`), as the
+         * workbook reads typed entry. Omitted, it rejects.
+         */
+        parseText?: (text: string, options?: IFormulaContext.IDeferContext.ParseTextOptions) => Promise<Scalar[][]>;
         /**
          * Whether to perform iterative calculations when there are circular dependencies.
          *
@@ -869,10 +836,6 @@ export declare namespace Calculation {
 /**
  * Transaction State for Calculation
  */
-/**
- * A grid request the channel holds while the engine is `Starting` (DESIGN-CALC-SERVICE §4): the
- * request as data, the snapshot it names, and the caller's continuation.
- */
 interface HeldRequest {
     gridId: string;
     request: CalcRequest;

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';
@@ -20,32 +19,6 @@ export interface ExternalNamedItem {
     /** The cached body as written; replaced in place when a refresh changes it. */
     refersTo: string;
 }
-/**
- * What an external book's cache is to the engine: one read-only grid per sheet, and one virtual
- * grid per cached defined name — reconciled against the collection on every change.
- *
- * @remarks
- * DESIGN-EXTERNAL-LINKS §5 steps 15 and 16. The measured rule (§6 items 1 and 2) is that an
- * external cell the cache does not hold is a BLANK CELL, so a sheet's grid is simply the sparse
- * cache loaded at its real coordinates with the ordinary sheet extent: every cell it does not hold
- * is already empty, and a whole-column citation walks the cache's used cells like any sheet's.
- * A sheet with no cache at all gets an empty grid for the same reason — Excel answers blank there
- * too, and the alternative (`#REF!`) is the value damage this phase exists to remove.
- *
- * Grids are keyed by the `ext:` stable id the sheet symbol binds to, so `container.getGrid(scope)`
- * finds them with no change to the executor. A book's removal unregisters its grids WITHOUT the
- * `delete()` a dropped sheet gets: a citation keeps the slot's id and computes `#REF!`, and an undo,
- * which restores the slot with its id, rebuilds the grids and heals it (see
- * `IExternalBook.delete`).
- *
- * A cached name's body is compiled INSIDE the book (`SheetCtx.book`), so `'Alpha'!$A$1` names the
- * book's sheet; a bare reference anchors to the scoping sheet, else the book's first. A name is
- * found under exactly the scope it was cached with — Excel flattens a sheet-scoped source name
- * into the book's namespace on caching and then answers `#NAME?` to the sheet-qualified citation
- * of it (measured 2026-09-11, `externalLinksNames.xlsx` + `probe-external-names-recalc.ps1`:
- * `'Data Sheet'!Local` is cached with no `sheetId`, and `'[1]Data Sheet'!Local` rebuilds to
- * `#NAME?` with the source absent), so there is no sheet-to-book fallback here.
- */
 export declare class ExternalBookBindings {
     private readonly _options;
     /** Every registered name, by the provider's key: `<scopeId>::<lowercase name>`. */
@@ -87,11 +60,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}. */