@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/sdk",
   "description": "SDK - A high-performance, embeddable spreadsheet engine.",
-  "version": "0.7.28-beta.4",
+  "version": "0.8.0-beta.1",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -43,11 +43,11 @@
     "automation"
   ],
   "dependencies": {
-    "@sheetxl/formulas": "^0.7.28-beta.4",
-    "@sheetxl/formulas-extended": "^0.7.28-beta.4",
-    "@sheetxl/primitives": "^0.7.28-beta.4",
-    "@sheetxl/scripting": "^0.7.28-beta.4",
-    "@sheetxl/utils": "^0.7.28-beta.4",
+    "@sheetxl/formulas": "^0.8.0-beta.1",
+    "@sheetxl/formulas-extended": "^0.8.0-beta.1",
+    "@sheetxl/primitives": "^0.8.0-beta.1",
+    "@sheetxl/scripting": "^0.8.0-beta.1",
+    "@sheetxl/utils": "^0.8.0-beta.1",
     "bahttext": "^2.4.0",
     "bessel": "^1.0.2",
     "chalk": "^6.0.0",

package/types/scripting-enums.json

@@ -58,6 +58,10 @@
     "Column": "column",
     "Row": "row"
   },
+  "CompatFeatures": {
+    "noMemberFilter": "Members of a repeating scalar parameter are coerced rather than filtered; one that cannot be is #VALUE!.",
+    "noReferenceLift": "A multi-cell reference at a non-repeating scalar parameter is #VALUE! rather than a broadcast."
+  },
   "DateUnit": {
     "Day": "d",
     "Month": "m",

package/types/scripting.d.ts

@@ -639,6 +639,65 @@ declare global {
         }
     }
 
+    /**
+     * Family aliases: one name an author writes that expands to several {@link CompatFeatures}.
+     *
+     * @remarks
+     * Excel's Analysis-ToolPak heritage is ONE measured rule with two halves that act on disjoint
+     * parameter kinds — `noReferenceLift` at a non-repeating scalar slot, `noMemberFilter` at a
+     * repeating one — so every function in the family carries the same two bits and `@compat atp`
+     * says so in one word. The alias is expanded by the linter; only the atomic features are ever
+     * stored, so `@compat atp` and `@compat noReferenceLift noMemberFilter` emit the same declaration.
+     * The atomic names stay available for the day a function measures as disagreeing on one half.
+     */
+    export const CompatAliases: Readonly<Record<string, readonly CompatFeature[]>>;
+
+    /**
+     * One of the {@link CompatFeatures} names.
+     */
+    export type CompatFeature = keyof typeof CompatFeatures;
+
+    /**
+     * The behaviors `@compat` can turn on, and what each one does.
+     *
+     * @remarks
+     * A feature earns a place here only if the BODY cannot do it — the decision happens before the
+     * body runs, or instead of running it. Everything a body can decide for itself belongs in the
+     * body, where `FormulaContext.getArgs()` and `Omittable` already reach.
+     *
+     * Function-level until a measurement forces otherwise: `noReferenceLift` is per-function in
+     * Excel, and no function is known whose parameters disagree.
+     *
+     * @see {@link https://www.sheetxl.com/docs/guides/concepts/udf | UDF authoring guide}
+     */
+    export const CompatFeatures: {
+        /**
+         * A multi-cell REFERENCE at a non-repeating scalar parameter is `#VALUE!` rather than a
+         * broadcast.
+         *
+         * Excel's Analysis-ToolPak family answers `CUMIPMT(G1:G2,120,100000,13,24,0)` with `#VALUE!`
+         * where the native `ROUND(B1:B3,3)` spills three results. A multi-cell reference has no way to
+         * become a scalar there, because these functions never intersect. An ARRAY at the same slot
+         * still lifts (`MROUND({3,4,5},5)` spills), so the refusal is about references specifically,
+         * and a REPEATING slot absorbs a container as members either way (`GCD(C1:C3)` is 4) — so this
+         * never applies to one.
+         */
+        readonly noReferenceLift: "A multi-cell reference at a non-repeating scalar parameter is #VALUE! rather than a broadcast.";
+        /**
+         * Members of a REPEATING scalar parameter are coerced rather than filtered: numeric text
+         * parses, a blank inside a multi-cell range reads 0, and a boolean or non-numeric text member
+         * is `#VALUE!` for the whole call.
+         *
+         * The native family FILTERS — `SUM({1,"8",TRUE})` is 1, the text and the boolean skipped, and a
+         * blank cell contributes nothing. Excel's Analysis-ToolPak family coerces instead:
+         * `GCD({6,"8",12})` is 2, `GCD({6,TRUE,12})` is `#VALUE!`, `LCM(6,A1:A2)` over two blank cells
+         * is 0. A direct argument follows the same rule (`GCD(6,TRUE,12)` is `#VALUE!` where
+         * `SUM(6,TRUE,12)` is 19), and a one-cell blank reference or an omitted argument is still
+         * skipped — it never became a member.
+         */
+        readonly noMemberFilter: "Members of a repeating scalar parameter are coerced rather than filtered; one that cannot be is #VALUE!.";
+    };
+
     /**
      * A compiled collection of functions — the serialized form of one module.
      *
@@ -5770,6 +5829,22 @@ declare global {
          * Returns the absolute bounds for the range.
          */
         getBounds(): Bounds;
+        /**
+         * The size this range's content needs — what {@link getBounds} would report if the range had
+         * been {@link autoFit}. A pure query: nothing is measured onto the model and nothing is committed.
+         *
+         * @param options Measurement options. Default `{ axes: IRange.AxisSelection.Both }`.
+         *
+         * @remarks
+         * - The width is the sum of the per-column best fits and the height the sum of the per-row best
+         *   fits, so a single-column range answers "how wide must this list be" directly.
+         * - An axis left out of {@link BestFitOptions.axes} reports its current size.
+         * - Only the range's own content is measured, so the answer never depends on cells outside it.
+         *   (`autoFit` also scans outside the range, to prove a shrink is safe.)
+         * - Sheet protection is not consulted: reading a size cannot violate it, and a protected sheet
+         *   answers the same as an unprotected one.
+         */
+        getBestFit(options?: ICellRange.BestFitOptions): Size;
         /**
          * Indicates if the range is readonly only.
          *
@@ -6256,9 +6331,9 @@ declare global {
             includeMergeOverflow?: boolean;
         }
         /**
-         * Options for {@link ICellRange.autoFit}.
+         * Options for {@link ICellRange.getBestFit} — measurement only.
          */
-        interface AutoFitOptions extends ITransaction.OperationOptions {
+        interface BestFitOptions {
             /**
              * Best fit using the minimum amount of space required.
              *
@@ -6269,21 +6344,6 @@ declare global {
              * For example allowing numbers to round or use scientific notation.
              */
             minContent?: boolean;
-            /**
-             * Restricts autoFit to only grow, never shrink.
-             *
-             * @defaultValue false - adjust in both directions.
-             *
-             * @remarks
-             * This is useful when adjusting fonts and wan the columns to resize but not the rows.
-             */
-            expandOnly?: boolean | IRange.Axis;
-            /**
-             * If this is set to `true` then any headers that have custom sizes will be ignored.
-             *
-             * @defaultValue false
-             */
-            skipCustomSize?: boolean;
             /**
              * The axes to autoFit.
              *
@@ -6305,6 +6365,26 @@ declare global {
              */
             formulaView?: boolean;
         }
+        /**
+         * Options for {@link ICellRange.autoFit}.
+         */
+        interface AutoFitOptions extends BestFitOptions, ITransaction.OperationOptions {
+            /**
+             * Restricts autoFit to only grow, never shrink.
+             *
+             * @defaultValue false - adjust in both directions.
+             *
+             * @remarks
+             * This is useful when adjusting fonts and wan the columns to resize but not the rows.
+             */
+            expandOnly?: boolean | IRange.Axis;
+            /**
+             * If this is set to `true` then any headers that have custom sizes will be ignored.
+             *
+             * @defaultValue false
+             */
+            skipCustomSize?: boolean;
+        }
         /**
          * Options for {@link ICellRanges.getFlattened}.
          */
@@ -12500,6 +12580,7 @@ declare global {
      * | Category | Key methods |
      * |---|---|
      * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords` |
+     * | Argument reflection | `getArgs` |
      * | Output hints | `formatResults` |
      * | Range construction | `createRange`, `filterHidden` |
      * | Dynamic references | `getReference`, `getValueAt`, `getFormulaAt`, `getSpillAt` |
@@ -12954,6 +13035,22 @@ declare global {
          * Mostly for diagnostics; the built-in `INFO` function is built on it.
          */
         getRuntime(): IRuntime;
+        /**
+         * The current call's arguments — how many the caller supplied, in which positions, of what kind,
+         * and what each value was BEFORE coercion.
+         *
+         * @remarks
+         * Argument REFLECTION, for the one thing a declaration cannot say: what happened at *this* call.
+         * It exists to serve Excel's declared `any`, which means "no contract, the body decides" — every
+         * other Excel type maps onto a type we already have and the marshaller handles it.
+         *
+         * The returned view is valid ONLY while the body that asked for it is running. Views are pooled
+         * by dispatch depth, so retaining one across an `await`, a callback, or a nested evaluation hands
+         * you another call's arguments.
+         *
+         * @throws If called outside a function dispatch — there are no arguments to reflect on.
+         */
+        getArgs(): IFunctionArguments;
     }
 
     /**
@@ -13615,9 +13712,164 @@ declare global {
              * @defaultValue false
              */
             cancelable?: boolean;
+            /**
+             * Named engine behaviors this function opts into, from the `@compat` doc tag.
+             *
+             * @remarks
+             * Canonical spellings, deduplicated and in declaration order; a family alias the author wrote
+             * (`@compat atp`) has already been expanded to its atomic features. An unknown name never
+             * reaches here — the linter fails the build on one, deliberately: a compatibility rule that
+             * silently no-ops is the worst failure available, because the fixtures keep passing and the
+             * behavior is simply absent.
+             *
+             * @see {@link CompatFeatures}
+             * @see {@link CompatAliases}
+             */
+            compat?: CompatFeature[];
         }
     }
 
+    /**
+     * The current call's arguments, as the body sees them — argument **reflection**.
+     *
+     * @remarks
+     * A declaration answers "what does this parameter mean?", and the marshaller coerces every
+     * argument to it. That is right for the overwhelming majority of parameters. What it cannot answer
+     * is anything about *this particular call*:
+     *
+     * - What did the caller write there — a value, a cell, an array, nothing at all?
+     * - What was the value BEFORE the parameter's type coerced it?
+     * - Was that empty slot an omission, or a blank cell the caller pointed at?
+     *
+     * Excel has measured behaviors that turn on exactly those questions, and they cluster at the
+     * parameters Excel declares `any` — where there is nothing to express as a type, because Excel
+     * declined to express one. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
+     * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
+     * body decides.
+     *
+     * It is REFLECTION and nothing else — two questions, and no third:
+     *
+     * | question | answers |
+     * | --- | --- |
+     * | *what was supplied* | {@link getLength}, {@link isOmittedAt} |
+     * | *what it is* | {@link getRawAt} |
+     *
+     * Coercion is deliberately absent. A body that wants a number calls
+     * {@link IFormulaContext.parseAsNumber} on the value this hands it — that already takes a value,
+     * already propagates an incoming error with its identity, and already answers `#VALUE!` for a
+     * boolean, which IS the rule an `any` slot needs. There is no coercion an index can do that a
+     * value cannot.
+     *
+     * Obtained from `FormulaContext.getArgs()`, and valid ONLY while the body that asked for it is
+     * running. A body must not retain it across an `await`, a callback, or a nested evaluation — the
+     * views are pooled by dispatch depth, so the one at your depth is handed to the next call at that
+     * depth.
+     *
+     * ```typescript
+     * export function CUMIPMT(rate: Scalar, nper: Scalar): number {
+     *   const args = FormulaContext.getArgs();
+     *   if (args.isOmittedAt(0)) return FormulaError.BuiltIn.NA;     // `CUMIPMT(,120,…)` is #N/A
+     *   const asNumber = FormulaContext.parseAsNumber(args.getRawAt(0) as Scalar);  // TRUE is #VALUE!
+     *   // …
+     * }
+     * ```
+     *
+     * @see {@link IFormulaContext.getArgs}
+     */
+    export interface IFunctionArguments {
+        /**
+         * How many PARAMETERS the caller supplied.
+         *
+         * @remarks
+         * Indexing throughout matches the BODY's own signature, never the raw call positions
+         * (see {@link getRawAt}). `index >= getLength()` is an ABSENT argument — one the caller never
+         * wrote, whose own JS initializer supplied the value. That is a different thing from an OMITTED
+         * one; see {@link isOmittedAt}.
+         */
+        getLength(): number;
+        /**
+         * This invocation's value at `index`, uncoerced.
+         *
+         * @param index The PARAMETER index — the position in the body's own signature.
+         *
+         * @remarks
+         * A `Scalar` means the argument IS a value; an {@link IRange} means a container whose members
+         * the body reads itself (a reference materializes on demand); a {@link Lambda} means a callable.
+         *
+         * At a REPEATING parameter (`Repeating<T>`, or a rest parameter) this is the ARRAY of that
+         * group's values — one entry per argument the caller wrote — and {@link getRepeatingArgsAt} is the
+         * per-argument view of the same thing. Indexing by parameter rather than by call position is
+         * what lets a body ask its questions in the vocabulary it declared:
+         *
+         * ```typescript
+         * // IFS(condition: Repeating<[logicalTest: boolean, logicalTrue: AcceptError<any>]>)
+         * args.getRawAt(0);                       // [test1, value1, test2, value2, …]
+         * args.getRepeatingArgsAt(0).getRawAt(0);     // test1
+         * ```
+         *
+         * **Under a lift** the call broadcasts and the body runs once per output cell; this reports the
+         * value for THIS invocation — the member at the current broadcast position for a lifted argument,
+         * the whole argument for one that is not lifting. That is what every identified caller wants: a
+         * body checking for a boolean must see the member, not the array around it.
+         *
+         * One boundary is worth knowing: under a lift at a parameter that declares a CONCRETE scalar
+         * type, the member has already been converted by that declaration, so the raw and coerced answers
+         * coincide there. At the `Scalar` slots this interface exists for, nothing coerces and the value
+         * is the member exactly as the caller's range holds it.
+         */
+        getRawAt(index: number): IFunctionArguments.RawArg | IFunctionArguments.RawArg[];
+        /**
+         * A nested view over one REPEATING parameter's arguments, so a body can ask the same questions
+         * one level down — `getRepeatingArgsAt(0).isOmittedAt(1)`.
+         *
+         * @param index The PARAMETER index of the repeating group (or rest parameter).
+         *
+         * @remarks
+         * The nested view is FLAT over the group's arguments: a period-2 group repeated three times reads
+         * as six, in call order. That is where "which one was omitted" has an answer at all — the group
+         * as a whole cannot be omitted, only one of its arguments can.
+         *
+         * At a non-repeating parameter this returns an EMPTY view (`getLength()` of 0) rather than
+         * throwing, so a body that folds over its groups needs no special case.
+         */
+        getRepeatingArgsAt(index: number): IFunctionArguments;
+        /**
+         * True for an OMITTED argument — one the caller supplied EMPTY, as the trailing comma of
+         * `CUMIPMT(,120,100000,13,24,0)`.
+         *
+         * @remarks
+         * There are THREE positions, not two, and Excel answers each differently:
+         *
+         * | form | position | Excel |
+         * | --- | --- | --- |
+         * | `CUMIPMT(0.01,120,100000,13,24)` | ABSENT | refused at entry |
+         * | `CUMIPMT(,120,100000,13,24,0)` | **OMITTED** | `#N/A` |
+         * | `CUMIPMT(0.01,120,100000,13,24,E1)`, E1 blank | a blank CELL | the ordinary answer |
+         *
+         * This separates the middle row from the other two. ABSENT is `index >= getLength()`; a blank
+         * cell is an ordinary value the caller pointed at and is not omitted.
+         */
+        isOmittedAt(index: number): boolean;
+    }
+
+    /**
+     * {@inheritDoc IFunctionArguments}
+     *
+     * @see
+     * ### **Interface**
+     *
+     * {@link IFunctionArguments}
+     */
+    export namespace IFunctionArguments {
+        /**
+         * One argument as the caller wrote it — a value, a container, a callable, or nothing.
+         *
+         * @remarks
+         * `undefined` is an OMITTED or ABSENT argument; `null` is a blank, which is a value.
+         */
+        type RawArg = Scalar | IRange | Lambda | undefined;
+    }
+
     /**
      * Collections of {@link IFunction}.
      */
@@ -17052,11 +17304,28 @@ declare global {
          */
         filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => MaybeError<boolean>, options?: IRange.TraversalAxis | IRange.IteratorOptions): this;
         /**
-         * Returns the values as an array of values.
+         * Linearizes the range into a single column by flattened ordinal — the member at ordinal `i`
+         * lands at row `i`, column 0.
          *
          * @param options {@link IRange.IteratorOptions}
+         *
+         * @remarks
+         * `options.axis` is the TRAVERSAL order feeding the ordinal, not the orientation of the result:
+         * the result is always Nx1, and a row is `flatten().transpose()`. The default is row-major,
+         * which is the order Excel pairs two range operands in.
+         *
+         * `options.type` carries a read type onto the result, so a member the type filters out becomes
+         * a HOLE at its ordinal rather than compacting the column. That is what lets two operands be
+         * paired position by position — see {@link alignValues}.
+         *
+         * `options.includeEmpty` has no meaning here and is ignored: a range is inherently sparse, so
+         * an empty position is simply absent. Sparsity is preserved and nothing is materialized.
+         *
+         * Equivalent to `reshape(rows * columns, 1)`, which is where the ordinal rule is stated.
+         *
+         * @see {@link getValuesFlat} for the same linearization as a JS array.
          */
-        flatten<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+        flatten(options?: IRange.IteratorOptions): this;
         /**
          * Iterates over the cells within the range, applying the provided callback function to each cell.
          *
@@ -17134,6 +17403,16 @@ declare global {
          * @param options {@link IRange.ValueOptions}
          */
         getValueAt<TS extends Scalar = T>(rowIndex: number, colIndex: number, options?: IRange.ValueOptions): TS;
+        /**
+         * Returns the members as a flat JS array.
+         *
+         * @param options {@link IRange.IteratorOptions}
+         *
+         * @remarks
+         * The array form of {@link flatten}. Skips empty members unless `includeEmpty` is set, where
+         * `flatten` keeps them as holes in a range.
+         */
+        getValuesFlat<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
         /**
          * Returns the number of columns of the range.
          */
@@ -28563,6 +28842,7 @@ declare global {
         c?: boolean;
         p?: MinifiedParameter[];
         r?: MinifiedValue;
+        x?: CompatFeature[];
     }
 
     export type MinifiedDeclarations = {
@@ -29473,6 +29753,28 @@ declare global {
      */
     export type Repeating<T> = T[];
 
+    /**
+     * Resolves a `@compat` feature name, CASE-INSENSITIVELY, to its canonical spelling.
+     *
+     * @param name The name as the author wrote it.
+     * @returns The canonical name, or `null` when no feature goes by it.
+     *
+     * @remarks
+     * Authors write `@compat noReferenceLift`; `@Compat NOREFERENCELIFT` means the same thing. Only
+     * the canonical spelling is ever stored, so the declaration a build emits does not depend on how
+     * the tag was typed.
+     */
+    export function resolveCompatFeature(name: string): CompatFeature | null;
+
+    /**
+     * Resolves a `@compat` name — a feature or a family alias — CASE-INSENSITIVELY, to the canonical
+     * features it turns on.
+     *
+     * @param name The name as the author wrote it.
+     * @returns The canonical features, or `null` when no feature or alias goes by that name.
+     */
+    export function resolveCompatFeatures(name: string): readonly CompatFeature[] | null;
+
     /**
      * Flatten a locale's declared `inherit` into a concrete lookup order, most-specific first.
      *

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

@@ -38,6 +38,11 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     protected _getRanges: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
     protected _calcExecutor: CalcExecutor;
     protected _cycleId: number;
+    protected _staticEpoch: number;
+    protected _precedentEpoch: number;
+    protected _epochSeenFormulas: ISpatialMap3D<FormulaSpatialValue> | null;
+    protected _epochSeenPrecedents: ISpatialMap3D<PrecedentSpatialValue> | null;
+    protected _epochSeenDynamics: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]> | null;
     protected _volatiles: Set<CalcNode>;
     protected _calculatedCommitId: string | null;
     protected _pendingActions: (() => Promise<unknown>)[] | null;

package/types/src/calculation/executor/CalcExecutor.d.ts

@@ -17,7 +17,9 @@ export declare class CalcExecutor {
     protected _container: IContextContainer;
     protected _context: IFormulaContext;
     private readonly _requestCalculate;
-    protected _pendingCalcs: Set<CalcNode>;
+    protected _pendingCalcs: Map<CalcNode, number>;
+    /** Debounced drain of {@link _pendingCalcs} into the volatile set; one instance for the executor's lifetime. */
+    private readonly _flushPendingCalcs;
     /**
      * The last pass's circular roster: every node it evaluated by demand (a `doMarkAndPlan` that
      * could not order, or the iteration guard's hand-over) plus every node whose dynamic read
@@ -90,6 +92,54 @@ export declare class CalcExecutor {
         evaluations: number;
         retries: number;
     };
+    /**
+     * Counters and per-phase timings over every plan since construction — the measurement rig the
+     * performance plan's §1.6 rollout asks for, and what validates the §1.2/§1.3 caches while
+     * {@link planCacheMode} is `'assert'`.
+     */
+    protected _planStats: CalcExecutor.PlanStats;
+    /**
+     * The plan caches of CALC-PERFORMANCE-PLAN.md §1.2/§1.3.
+     *
+     * - `'on'` (default): an eligible pass skips the in-degree + Kahn phases (plan = affected set
+     *   sorted by order stamp) and discovery reuses cached `dependents`.
+     * - `'assert'` (the §1.6 rollout mode; the diagnostic to flip back to if values ever look
+     *   stale — `__sxlCalc.mode('assert')`): stamps are written and eligibility computed, but every
+     *   pass still runs the full search + Kahn phases; the fast path's order and the cached
+     *   `dependents` are VERIFIED against them, mismatches counted in
+     *   `planAssertFailures`/`dependentsAssertFailures` and logged. Costs the old planning price
+     *   plus epsilon.
+     * - `'off'`: stamps are neither written nor consulted.
+     */
+    planCacheMode: 'off' | 'assert' | 'on';
+    /** Next order-stamp plan id to hand out; ids are unique across passes. */
+    protected _planIdNext: number;
+    /** Id of the last fully-ordered plan that stamped (§1.2); `0` = none yet. */
+    protected _lastPlanId: number;
+    /** Length of the last stamped plan — the `orderIndex` range the fast path's bucket order spans. */
+    protected _lastStampedLength: number;
+    /**
+     * Whole-closure reuse (§1.4): remembered fully-ordered passes — seeds, plan, and the
+     * `precedentEpoch` each was planned at (`-1` = empty). A pass with the identical seed set at
+     * the same epoch has the identical affected closure and the same valid order, so discovery and
+     * the sort are skipped outright: the plan is reused verbatim and each node gets only its
+     * per-pass reset. TWO slots, because one was not enough for the common workflow — "type a value,
+     * then fill it down": the single-cell pass overwrote the remembered bulk plan every time. Slots
+     * are recycled least-recently-USED (a hit refreshes a memo's clock), so the two plans in play
+     * both stay resident: bulk → small edits → same bulk hits, and two alternating bulk edits both
+     * hit. NOT "keep the largest": a full calc's plan is the same size as a bulk edit's over the
+     * same sheet, and that tie evicted the bulk memo on the very next small edit. Per executor, not
+     * module scope (§1.5).
+     */
+    protected _planMemos: [CalcExecutor.PlanMemo, CalcExecutor.PlanMemo];
+    /** The memos' LRU clock. Its own counter, NOT `PlanStats.passes`: a stats reset must not reorder the slots. */
+    protected _planMemoClock: number;
+    /**
+     * Nodes with an async promise in flight. Per executor, NOT module scope — module scope would
+     * cross-pollute workbook instances (undo to 0 formulas needs to clear these; TODO - revisit
+     * how we manage promises).
+     */
+    protected _pendingPromises: Set<CalcNode>;
     _gridUpdates: Map<string, ICalcGrid.IncrementalUpdates> | null;
     _addDynamicPrecedent: ((node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind) => void) | null;
     constructor(container: IContextContainer, context: IFormulaContext, requestCalculate: () => void);
@@ -221,11 +271,17 @@ export declare class CalcExecutor {
      * carrying the {@link CycleRole} its reads gave it. Describes the last pass only.
      */
     getCircularNodes(): readonly CalcNode[];
-    /** @internal Demand-pass counters since construction: evaluations and `NeedsFirst` retries. */
+    /**
+     * @internal
+     * Demand-pass counters since construction — evaluations and `NeedsFirst` retries — plus the
+     * plan-phase counters and timings (see {@link _planStats}).
+     */
     getDemandStats(): {
         evaluations: number;
         retries: number;
-    };
+    } & CalcExecutor.PlanStats;
+    /** @internal Zeroes every counter/timing so a measurement window starts clean (`__sxlCalc.reset()`). */
+    resetStats(): void;
     /**
      * Collects and marks all volatile CalcNodes.
      *
@@ -253,6 +309,17 @@ export declare class CalcExecutor {
      * Uses Kahn's algorithm.
      */
     doMarkAndPlan(cycleId: number, markId: number, initial: FixedPackedArray<CalcNode>, plan: FixedPackedArray<CalcNode>, forceDemand?: boolean): boolean;
+    /**
+     * The remembered plan whose seed set is exactly this pass's, at this epoch — or `null`. The
+     * length check first: it is what rejects the common miss (a single-cell pass against a bulk
+     * memo) before any node is touched.
+     */
+    private _matchPlanMemo;
+    /**
+     * Records this pass's seeds and plan for whole-closure reuse (§1.4). The victim slot is a stale
+     * one if there is one, else the least recently used.
+     */
+    private _rememberPlan;
     doEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, scheduleRecalculation: (cycleId: number, calcNode?: CalcNode) => void, commit: (calcNodes: CalcNode[], calcNodesLength: number) => void, forceFull: boolean, plan: FixedPackedArray<CalcNode>): ISpatialMap | undefined;
 }
 export declare namespace CalcExecutor {
@@ -296,6 +363,48 @@ export declare namespace CalcExecutor {
         /** Volatiles accumulated before this cycle — drained and cleared by execute() */
         oldVolatiles: Set<CalcNode>;
     }
+    /** A remembered fully-ordered pass for whole-closure reuse (§1.4) — see `CalcExecutor._planMemos`. */
+    interface PlanMemo {
+        seeds: CalcNode[];
+        seedsLength: number;
+        plan: CalcNode[];
+        planLength: number;
+        /** The `precedentEpoch` the plan was made at; `-1` = empty. */
+        epoch: number;
+        /** `CalcExecutor._planMemoClock` when last written or matched — the LRU key for slot recycling. */
+        used: number;
+    }
+    /** Plan-phase counters and timings — see `CalcExecutor.planCacheMode` and performance plan §1.6. */
+    interface PlanStats {
+        /** In-degree formula lookups answered by the single-entry block cache. */
+        formulaCacheHits: number;
+        formulaCacheMisses: number;
+        /** doMarkAndPlan invocations. */
+        passes: number;
+        /** Passes whose whole affected set carried valid order stamps (fast-path candidates). */
+        fastEligible: number;
+        /** Eligible passes that actually skipped in-degree + Kahn (`'on'` mode only). */
+        fastHits: number;
+        /** Passes whose seed set and precedent epoch matched the last plan (§1.4 candidates). */
+        closureEligible: number;
+        /** Closure-eligible passes that reused the last plan verbatim, skipping discovery too (`'on'` only). */
+        closureHits: number;
+        /** `'assert'` mode: closure-eligible passes whose fresh affected set differed from the last plan. */
+        closureAssertFailures: number;
+        /** Fully-ordered plans that wrote order stamps. */
+        stampedPlans: number;
+        /** `'assert'` mode: eligible passes whose stamp order contradicted a real static edge. */
+        planAssertFailures: number;
+        /** `'assert'` mode: cached `dependents` that did not match a fresh search. */
+        dependentsAssertFailures: number;
+        /** Discovery searches skipped (or verified) because `dependentsEpoch` was current. */
+        dependentsCacheHits: number;
+        dependentsCacheMisses: number;
+        discoveryMs: number;
+        inDegreeMs: number;
+        kahnMs: number;
+        evaluateMs: number;
+    }
     /** Updated spatial maps and committed grid batches returned to Calculation */
     interface ExecuteResult {
         precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;

package/types/src/calculation/state/CalcNode.d.ts

@@ -63,6 +63,26 @@ export interface CalcNode {
      * {@link cycleGroup}; the role it shows is the `CalcState.ShownRoleMask` field of {@link state}.
      */
     shownGroup: number;
+    /**
+     * Position of this node in the last FULLY-ORDERED plan that stamped it (CALC-PERFORMANCE-PLAN.md
+     * §1.2). Meaningful only when {@link planId} and {@link planEpoch} match the executor's current
+     * plan id and the container's static epoch; `-1` until first stamped.
+     */
+    orderIndex: number;
+    /**
+     * Id of the Kahn pass that stamped {@link orderIndex}; `0` = never stamped. Stamps from
+     * different passes are NOT mutually comparable — the fast path requires every affected node to
+     * carry the executor's `_lastPlanId`.
+     */
+    planId: number;
+    /** The container's `staticEpoch` when {@link orderIndex} was stamped; stale under a newer epoch. */
+    planEpoch: number;
+    /**
+     * The container's `precedentEpoch` when {@link dependents} was last computed
+     * (CALC-PERFORMANCE-PLAN.md §1.3). Discovery reuses the cached array while this matches;
+     * `0` = never computed.
+     */
+    dependentsEpoch: number;
     /**
      * Bit mask, laid out by `CalcState`: the pending flags, `Skip`, `Circular`, and the
      * `DemandState`/`CycleRole` fields of the current pass.