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

package/types/src/primitives/PrimitiveUtils.d.ts

@@ -150,7 +150,7 @@ isDirect: boolean, errors?: 'reject' | 'accept' | null): IRange | any[][] | Form
  * evaluated argument; see `isDirectArg` in `TypedFunction`.
  *
  * Two things it is NOT, both measured (`probe-direct-vs-literal.ps1`, pinned in
- * `functions2/coercion/DIRECT-VS-MEMBER.json`):
+ * `__tests__/functions/coercion/DIRECT-VS-MEMBER.json`):
  *
  * - **Not literalness.** `{1,TRUE}` and `A1:A2` behave IDENTICALLY (members of both are filtered),
  *   and the COMPUTED `A2>0` behaves like a typed `TRUE`. A container being a literal or a
@@ -171,28 +171,56 @@ export declare function addCoercedValue(context: IFormulaContext, coercedArr: Fi
 allowError: boolean, flatten: boolean, // indicates we should flatten
 errors?: 'reject' | 'accept' | null, // effective error policy (TypedFunction resolves the default)
 noMemberFilter?: boolean): FormulaError.Known | void;
+/**
+ * The depth-0 half of {@link addCoercedValue} for a SCALAR slot: `value` is already a single
+ * value — a typed or computed scalar, a blank, an error, rich data, or the member a one-cell
+ * reference was dereferenced to — never a container or coords. Same rules, same order, same
+ * verdicts as the general path, which still serves everything else; this exists so the common
+ * call (a number at a number slot) pays for no container questions.
+ *
+ * `isDirect` is the argument's own directness (a dereferenced cell is NOT direct): it gates the
+ * quoted-boolean parse, and nothing else — a scalar slot has no members, so the dereferenced
+ * value coerces with the direct rules exactly as it does in the general path (`ABS(A1)` is 1 for
+ * A1=TRUE).
+ */
+export declare function addCoercedScalar(context: IFormulaContext, coercedArr: FixedPackedArray, value: any, isDirect: boolean, scalarType: ScalarType | null, allowError: boolean, errors: 'reject' | 'accept' | null): FormulaError.Known | void;
 /**
  * Minimal validation used from the return value of functions.
  */
 /**
- * Makes a raw JS double look like an Excel one. Excel arithmetic has neither Infinity nor
- * subnormals, and this is the single rule that enforces both. Measured against Excel 16.0
- * (formula-tests: probe-num-overflow.ps1, probe-boundaries.ps1, probe-api-nonfinite.ps1):
- *
- * * ANY non-finite value is #NUM! — NaN and ±Infinity alike. `9E+307*2`, `9E+307+9E+307` and
- *   `9E+307/0.1` all report `ERROR.TYPE` 6, and a raw NaN or ±Infinity written through the
- *   Value2 API lands as #NUM! too. Infinity does NOT mean #DIV/0!: Excel never derives that
- *   error from a float, it raises it deliberately before dividing. Functions say so themselves
- *   by returning `FormulaError.BuiltIn.Div0`.
- * * a magnitude below the smallest NORMAL double flushes to ZERO, which also folds -0 to 0.
- *   `1E-300*2.224E-8` is 0 while `1E-300*2.226E-8` survives, and the flush lands before the next
- *   operator reads it — `=1/(1E-300*1E-100)` is #DIV/0!, not a huge number. The API agrees:
- *   writing `Double.Epsilon` reads back 0.
- *
- * Excel applies this at EVERY boundary, so SheetXL does too — `minCoerce` for a calculated
- * result, and the cell-write path for a value handed in through the API.
+ * Makes a raw JS double look like an Excel one: ANY non-finite value is #NUM! — NaN and
+ * ±Infinity alike. `9E+307*2`, `9E+307+9E+307` and `9E+307/0.1` all report `ERROR.TYPE` 6, and a
+ * raw NaN or ±Infinity written through the Value2 API lands as #NUM! too. Infinity does NOT mean
+ * #DIV/0!: Excel never derives that error from a float, it raises it deliberately before
+ * dividing. Functions say so themselves by returning `FormulaError.BuiltIn.Div0`.
+ *
+ * Measured against Excel 16.0 (formula-tests: probe-num-overflow.ps1, probe-boundaries.ps1,
+ * probe-api-nonfinite.ps1). This rule applies at every boundary; the SUBNORMAL rule does not —
+ * see {@link flushSubnormal}.
  */
 export declare function normalizeNumber(value: number): number | FormulaError.Known;
+/**
+ * Zeroes a magnitude below the smallest NORMAL double, which also folds -0 to 0.
+ *
+ * "Excel has no subnormals" is true of its ARITHMETIC and of its write path, and false of its
+ * function results — so this is a rule three callers apply deliberately rather than one the
+ * boundary applies to everything (measured 2026-08-30,
+ * `fn-battery/mathTrig/adhoc-subnormal-store`):
+ *
+ * * MULTIPLICATION, DIVISION and EXPONENTIATION flush. `1E-300*2.224E-8` is 0 while
+ *   `1E-300*2.226E-8` survives, `2^-1022/2` is 0, and the flush lands before the next operator
+ *   reads it — `=1/(1E-300*1E-100)` is #DIV/0!, not a huge number.
+ * * ADDITION and SUBTRACTION do NOT. With `Z1` holding 5E-324, `Z1+0`, `-Z1` and `Z1+Z1` all
+ *   keep the value, and `Z1*1` is 0.
+ * * A FUNCTION RESULT does not either, and it survives the cell it is stored in: `EXP(-745)` is
+ *   5E-324 and `EXP(-745)*1E300` is 4.94E-24. SUM, MIN, ABS, IF, INDEX and ROUND all pass it
+ *   through. EXP reaches zero only below -745.1332, the true IEEE underflow.
+ * * The API WRITE path flushes: `Double.Epsilon` set through `Value2` reads back 0.
+ * * The BOOLEAN reading flushes, and so does `SWITCH`'s comparison — both are tests against zero
+ *   (`IF(EXP(-745),…)` takes the false branch and `SWITCH(EXP(-745),0,…)` matches), which the
+ *   comparison OPERATORS do not do: `EXP(-745)=0` is FALSE.
+ */
+export declare function flushSubnormal(value: number): number;
 export declare function minCoerce(value: any, context?: IFormulaContext | null, type?: string): any;
 /**
  * Loads a (possibly nested) array literal into a sparse grid and returns the pieces a `Range`
@@ -219,8 +247,12 @@ export interface FixedPackedArray<T = any> {
 /**
  * V8 Optimization
  *
- * Is seems the new Array(length) because it uses holey arrays.
- * Push causes reallocation a bunch times.
+ * Builds an array that V8 keeps in `PACKED_ELEMENTS`, every slot set to `value`.
+ *
+ * A bare `new Array(length)` is holey, and each read from a holey array pays a
+ * hole check (~35% on a linear scan). Both branches here produce the same map;
+ * they differ only in how fast they build, and the threshold is the point where
+ * the per-call cost of `fill` stops dominating the per-element cost of `push`.
  *
  * This should be only used for reusable arrays where they are long lived
  * and need to be fast (and not resized (much)).
@@ -229,6 +261,11 @@ export declare function createPackedArray<T = any>(length: number, value?: T): T
 /**
  * Create a packed array but with undefined values.
  *
+ * `undefined` here is a real element in every slot, not a hole; the array is
+ * packed exactly as {@link createPackedArray} is. Kept separate rather than
+ * delegating because passing `undefined` as an argument would take the
+ * `value=null` default.
+ *
  * @see createPackedArray
  */
 export declare function createEmptyPackedArray<T = any>(length: number): T[];

package/types/src/primitives/Range.d.ts

@@ -18,26 +18,46 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     protected _localRangeStats: IRangeStats | null;
     /** The `options` {@link _localRangeStats} was built for — the memo's key. See `getStats`. */
     protected _localRangeStatsOptions: IRange.IteratorOptions | undefined;
-    constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean);
+    /**
+     * What a cell the grid does not store reads as - `null` for an ordinary range.
+     *
+     * @remarks
+     * A grid can hold only part of its range's answer: a watch body's blank region shares one value
+     * that the engine keeps on the block rather than writing per cell (PLAN-WATCHES-BLANK-AWARE
+     * §4c), so within that body "absent" means "the shared answer", never "empty". A range with a
+     * non-null empty value is therefore DENSE: `getValueAt` answers it for every absent cell, and
+     * the iterators visit those cells whether or not `includeEmpty` was asked, since they are
+     * content. A STORED empty (`null`) is still empty.
+     *
+     * It is also how an elementwise operation carries its answer for the blank cells: `map`,
+     * `broadcast` and `zip` walk what their operands STORE, answer the absent region once, and
+     * hand that answer to the result here rather than writing it as a run per line — so the next
+     * operator finds the blank region again and a whole-column chain stays O(stored + runs)
+     * (CALC-PERFORMANCE §5). `fillEmpty` over the whole range sets it the same way.
+     *
+     * Every reader agrees on it: the iterators and `getValueAt` above; a transform over the same
+     * grid carries it (`slice`, `toType`, `clone`); one that derives a grid either writes every
+     * position or writes it out first (`_materializeEmpty` — `resize`, `tile`, a partial `fill`);
+     * and a reader that goes to the grid rather than through the range (the stats walk, the calc
+     * grid's write of a result, a sheet write) reads the written-out grid.
+     */
+    protected _absentValue: Scalar;
+    constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean, absentValue?: Scalar);
     /** @inheritdoc IRange.argsort */
     argsort(keyRanges?: IRange | IRange[], orders?: number | number[], axis?: IRange.Axis): number[];
     /** @inheritdoc IRange.uniqueIndices */
     uniqueIndices(axis?: IRange.Axis, exactlyOnce?: boolean): number[];
     /** @inheritdoc IRange.broadcast */
     broadcast<TS extends Scalar = T>(other: IRange | TS, callbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.BroadcastOptions): this;
-    /**
-     * {@link broadcast} against a scalar operand: this range's OWN entries, with every empty position
-     * written as a run of one computed value. See the call site for why the general path cannot.
-     *
-     * @remarks
-     * Reached only for a coord-blind callback, so the single empty call carries the origin coords.
-     */
-    private _broadcastScalar;
     /** @inheritdoc IRange.choose */
     choose<TS extends Scalar = T>(from: (IRange<TS> | TS)[], selectFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => MaybeError<number>, options?: IRange.ValuesOptions): this;
     /** @inheritdoc IRange.clear */
     clear(): this;
-    /** @inheritdoc IRange.clone */
+    /**
+     * @inheritdoc IRange.clone
+     * @param options Read options for the clone, over this range's own: a `processRowSkip` here is
+     * a clone that reads without those rows.
+     */
     clone(options?: IRange.IteratorOptions, isLiteral?: boolean, isDirectScalar?: boolean): this;
     /** @inheritdoc IRange.compute */
     compute(fn: (range: IRange) => IRange): this;
@@ -55,12 +75,34 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     fill(value: Scalar, coords?: Partial<IRange.Coords>): this;
     /** @inheritdoc IRange.fillEmpty */
     fillEmpty(value: Scalar, coords?: Partial<IRange.Coords>): this;
+    /**
+     * Writes `value` at every absent position of `absCoords` as runs — the stored form of
+     * {@link fillEmpty}, for the case the absent value cannot express (a partial fill), and of
+     * {@link _materializeEmpty}.
+     * The result reads its grid alone (no empty value).
+     */
+    protected _fillAbsent(value: Scalar, absCoords: IRange.Coords): this;
+    /**
+     * This range with its empty value WRITTEN — every absent cell stored as runs of it — for a
+     * reader that goes to the grid rather than through the range: the stats walk, the calc grid's
+     * write of a result, a sheet write. `this` when there is nothing to write.
+     * @internal
+     */
+    _materializeEmpty(): this;
     /** @inheritdoc IRange.filter */
     filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): this;
+    /** @inheritdoc IRange.firstError */
+    firstError(): FormulaError.Known | null;
     /** @inheritdoc IRange.flatten */
     flatten(options?: IRange.IteratorOptions): this;
     /** @inheritdoc IRange.getValuesFlat */
     getValuesFlat<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+    /** @inheritdoc IRange.indexOf */
+    indexOf(value: Scalar, options?: IRange.IndexOfOptions): number;
+    /**
+     * The row-major walk behind {@link indexOf}, for the reads the run index cannot answer.
+     */
+    protected _indexOfScan(value: Scalar, reverse: boolean): number;
     /** @inheritdoc IRange.forEach */
     forEach<TS extends Scalar = T, B = any>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => {
         break: B;
@@ -76,6 +118,8 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     };
     /** @inheritdoc IRange.getStats */
     getStats(options?: IRange.IteratorOptions): IRangeStats;
+    /** The stats without the typed-read fault — what `hasError()` and the fault itself read. */
+    protected _getStats(options?: IRange.IteratorOptions): IRangeStats;
     /** @inheritdoc IRange.hasError */
     hasError(): boolean;
     /** {@inheritDoc IRange.getType} */
@@ -85,7 +129,15 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     /** @inheritdoc IRange.getValues */
     getValues<TS extends Scalar = T>(options?: IRange.GetValuesOptions): TS[][];
     /** @inheritdoc IRange.map */
-    map<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.IteratorOptions): this;
+    map<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.MapOptions): this;
+    /**
+     * {@link map} over what the grid stores: one call per stored member, one per run holding one
+     * value, and under `once` one for the absent region — whose answer is the result's empty value,
+     * so the next consumer finds the blank region again (CALC-PERFORMANCE §5). A member the
+     * callback empties (`null`) and a blank region it answers cannot share the one absent state,
+     * so in that one case the region's answer is written out as runs.
+     */
+    private _mapRuns;
     /** @inheritdoc IRange.mask */
     mask<TS extends Scalar = T>(conditions: IRange | TS, isTrues?: IRange | TS, options?: IRange.MaskOptions): this;
     /** @inheritdoc IRange.alignValues */
@@ -135,17 +187,25 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     /** @inheritdoc IRange.values */
     values<T extends Scalar = Scalar>(options?: IRange.IteratorOptions): IterableIterator<T>;
     /** @inheritdoc IRange.zip */
-    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.IteratorOptions): this;
-    /** {@inheritDoc IRange.isLiteral} */
-    isLiteral(): boolean;
-    /** Not on IRange — the boxed-bare-scalar flag; see `_isDirectScalar`. */
-    isDirectScalar(): boolean;
-    /** {@inheritDoc IRange.isScalar} */
-    isScalar(): boolean;
+    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.ZipOptions): this;
+    /**
+     * The array-constant flag (`_isLiteral`), for the ENGINE only — the coercion alias that makes
+     * a typed `{…}` direct for a slot's coercion. Excel's runtime has no literal kind (a typed and
+     * a computed array are both `Array`), so a function body never reads it: bodies ask
+     * `FormulaContext.getArgs().getKindAt`, and the reference-vs-array question is
+     * `isIReferenceRange`.
+     * @internal
+     */
+    _isLiteralArray(): boolean;
+    /**
+     * The boxed-bare-scalar flag (`_isDirectScalar`), for the ENGINE only — the box is call-local
+     * plumbing (born at a slot, unboxed at the call exit) and a function body never reads it:
+     * bodies ask `FormulaContext.getArgs().getKindAt`.
+     * @internal
+     */
+    _isDirectScalarBox(): boolean;
     /** {@inheritDoc IRange.isEmpty} */
     isEmpty(): boolean;
-    /** {@inheritDoc IRange.isVector} */
-    isVector(): boolean;
     /** @inheritdoc IRange.size */
     get size(): number;
     /** {@inheritDoc IRange[Symbol.iterator]} */
@@ -159,6 +219,17 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     protected _entries(options?: IRange.IteratorOptions & {
         reuseResult?: boolean;
     }): IGrid.EntryIterator<Scalar>;
+    /**
+     * The read `_entries` applies to one member under `options` - the typed coercion, its error
+     * policy, what an absent cell reads as - as a function, so a walk over runs (`RunHead`) reads a
+     * member exactly as the entry iterator would. Only a TYPED read (`options.type`) coerces; a raw
+     * read hands the member back, and an absent one (`undefined` in) as the empty value.
+     *
+     * @returns The value the member reads as, or `undefined` when the read DROPS it: a typed read
+     * filters what it cannot coerce - the declaration that the type is strict, so an aggregate
+     * ignores stray text the way Excel does - unless `includeEmpty` keeps it as an empty.
+     */
+    protected _memberReader(options: IRange.IteratorOptions | undefined, includeEmpty: boolean): (fromValue: Scalar | undefined) => Scalar | undefined;
     /**
      * Finds an absolute intersection given a relative coord.
      */
@@ -191,12 +262,49 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
      * (`SUMPRODUCT(--ISNUMBER(SEARCH(...)))` → 0).
      */
     protected _untyped(): this;
+    /** This range's options without its skips: for a result whose cells are laid out anew. */
+    protected _optionsFresh(): Omit<IRange.IteratorOptions, 'axis'> & {
+        axis?: IRange.Axis;
+    };
+    /**
+     * This range's options for a result over the same grid at `coords`: its skips count from this
+     * range's origin and cover its shape, so a result whose origin moved (a slice) asks them with
+     * the difference, and one that grew (a resize) asks them for the cells it had and leaves the
+     * rest alone. `null` coords - a result laid out anew - carry no skip.
+     *
+     * @remarks
+     * The rule the skips follow: a result whose cells sit where this range's do (a slice, a fill, a
+     * resize, a map) keeps them, since it is written over a copy of this grid and the cells the skip
+     * left alone still hold what the source does; one laid out anew (`empty()`, a compaction, a
+     * reflow) drops them ({@link _optionsFresh}).
+     */
+    protected _optionsAt(coords: IRange.Coords | null): Omit<IRange.IteratorOptions, 'axis'> & {
+        axis?: IRange.Axis;
+    };
+    /** Whether this range's own options skip anything. */
+    protected _hasSkips(): boolean;
+    /**
+     * Iterator options with their skips asked in the GRID's indexes rather than this range's: what
+     * the grid's own iterators take. The options themselves when they skip nothing.
+     */
+    protected _skipsOnGrid<O extends IRange.IteratorOptions>(options: O): O;
     protected _createBuilder(axis?: IRange.Axis): Tuple.IBuilder;
-    protected _applyBuilder(values: ISparseGrid<Scalar>, builder: Tuple.IBuilder, clone?: boolean): ISparseGrid<Scalar>;
-    protected _cloneFromBuilder(builder: Tuple.IBuilder | undefined, deletes?: ISpatialMap.IConflatingEntries | null): this;
+    /**
+     * Writes `region` into `values`: its clears first, unless `fresh` (a grid that stores nothing
+     * there), then its tuples.
+     */
+    protected _applyRegion(values: ISparseGrid<Scalar>, region: Tuple.Region | null, fresh: boolean): void;
+    /**
+     * @param absentValue What the result's absent cells read as. Defaults to this range's own: the
+     * result is this grid written into, so what it lacked it still lacks. A caller whose writes
+     * changed that says so (`map`; `_fillAbsent`, which wrote it out).
+     */
+    protected _cloneFromBuilder(builder: Tuple.IBuilder | undefined, deletes?: ISpatialMap.IConflatingEntries | null, fresh?: boolean, absentValue?: Scalar): this;
+    /** {@link _cloneFromBuilder} from a built region, whose clears are applied with the deletes. */
+    protected _cloneFromRegion(region: Tuple.Region | null, deletes?: ISpatialMap.IConflatingEntries | null, fresh?: boolean, absentValue?: Scalar): this;
     protected _coerceValue<TS extends Scalar>(fromValue: Scalar, toType: ScalarType, options?: IRange.ValueOptions, fromType?: ScalarType): TS;
     protected _mergeIterators<T = Scalar>(that: Range, callbackFn?: (a: T, b: T, coords: IRange.CellCoords, range: IRange) => T, options?: IRange.IteratorOptions): Tuple.IBuilder;
-    protected _newRange(values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean): this;
+    protected _newRange(values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean, absentValue?: Scalar): this;
     /** @inheritdoc IRange.isIRange */
     get isIRange(): true;
 }
@@ -217,7 +325,7 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
 export declare class _VisibleScopedRange extends Range {
     protected _visibleCoords: readonly IRange.Coords[];
     constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords, visibleCoords: readonly IRange.Coords[]);
-    /** {@inheritDoc IRange.getStats} */
-    getStats(options?: IRange.IteratorOptions): IRangeStats;
+    /** The rescoped stats; `getStats` (the typed-read fault) is inherited and reads through here. */
+    protected _getStats(options?: IRange.IteratorOptions): IRangeStats;
 }
 //# sourceMappingURL=Range.d.ts.map

package/types/src/primitives/RangeStats.d.ts

@@ -1,6 +1,6 @@
 import { ScalarType, IRange, IRuntime, IRangeStats, Scalar } from '@sheetxl/primitives';
 import { ISparseGrid } from '../collections';
-import { SortedNumbers, AggSegmentCache } from './stats';
+import { SortedNumbers, AggSegmentCache, AggResults } from './stats';
 export declare class RangeStats implements IRangeStats {
     protected _runtime: IRuntime;
     protected _grid: ISparseGrid<Scalar>;
@@ -9,20 +9,48 @@ export declare class RangeStats implements IRangeStats {
     protected _iteratorOptions?: IRange.IteratorOptions;
     protected _segmentCache: AggSegmentCache;
     protected _ZoneSizeMinor: number;
+    /**
+     * The first row and column of the range whose options these are, which its `processRowSkip` /
+     * `processColumnSkip` count from; `undefined` when the options skip nothing.
+     */
+    protected _skipOrigin: IRange.CellCoords | undefined;
     protected _sortedNumbers: SortedNumbers | undefined;
     protected _aggregates: IRangeStats.Aggregates | undefined;
     protected _typedCounts: Readonly<Record<ScalarType, number>> | undefined;
+    /**
+     * The raw results of the ONE walk this instance has done, whichever consumer asked first.
+     * `count`, `typed` and the numeric aggregates are all recorded by the same pass and none of
+     * them depends on `onError` (the segment cache's own contract — only `coerce` changes content),
+     * so the typed counts a reject scan asks for and the aggregates the body then asks for come
+     * from a single scan instead of two. A partial-zone range (a `SUM($K$51:K#)` running total)
+     * never caches at the segment level, so without this every such call scanned twice.
+     * Two-state: `undefined` = not walked yet, `null` = walked, the grid was empty.
+     */
+    protected _raw: AggResults | null | undefined;
     protected _frequencies: Readonly<IRangeStats.IFrequency> | undefined;
     protected _ranked: readonly Scalar[] | undefined;
     protected _lastNumber: number | null | undefined;
-    constructor(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords?: readonly (IRange.Coords | null)[], options?: IRange.IteratorOptions, segmentCache?: AggSegmentCache, zoneSizeMinor?: number);
+    constructor(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords?: readonly (IRange.Coords | null)[], options?: IRange.IteratorOptions, segmentCache?: AggSegmentCache, zoneSizeMinor?: number, skipOrigin?: IRange.CellCoords);
+    /**
+     * The values grid this instance measures. Its owner re-points the cache when the map is
+     * replaced, which a clone of the map is.
+     */
+    getGrid(): ISparseGrid<Scalar>;
     clone(grid?: ISparseGrid<Scalar>, localCoords?: readonly (IRange.Coords | null)[]): this;
     clear(): void;
     /** Lazily resolved, then held for this instance's lifetime like the other per-instance results. */
     protected _getLastNumber(): number | undefined;
     toLocalCoords(coords: IRange.Coords | readonly IRange.Coords[], iteratorOptions?: IRange.IteratorOptions): IRangeStats;
+    /** @inheritdoc IRangeStats.getCoords */
+    getCoords(): IRange.Coords | null;
     /** @inheritdoc IRangeStats.getSize */
     getSize(): number;
+    /**
+     * The instance's one walk (see `_raw`), taken with errors as population — the contract of
+     * every consumer that counts. Reused by the aggregate path when the instance's own error
+     * policy has no side effect to replay.
+     */
+    protected _walk(): AggResults | null;
     /** @inheritdoc IRangeStats.getCount */
     getCount(): number;
     /** @inheritdoc IRangeStats.getAggregates */

package/types/src/primitives/ReferenceRange.d.ts

@@ -1,14 +1,58 @@
 import { Scalar, ScalarType, IReferenceRange, IRange, IRuntime } from '@sheetxl/primitives';
 import { ISparseGrid } from '../collections';
 import { Range } from './Range';
+/**
+ * Answers "is there an error value within these coords" for the grid a reference reads, from an
+ * index rather than a scan. The calculation grid maintains one at every write; a reference built
+ * over any other grid has none and scans.
+ */
+export interface ReferenceErrorIndex {
+    hasErrorIn(coords: IRange.Coords): boolean;
+}
+/** @internal */
+export declare function _setReferenceErrorIndexAssert(enabled: boolean): void;
 export declare class ReferenceRange extends Range implements IReferenceRange {
     protected _getEntireCoords: () => IRange.Coords;
     protected _resolveScope: (scope: string) => string | undefined;
+    /** The grid's error index, when the reference reads a grid that keeps one. */
+    protected _errorIndex: ReferenceErrorIndex | null;
+    /**
+     * Told when a body reads this reference's POSITION (`getCoords`). A reference's values are a
+     * property of what it points at; its address is a property of which cell is asking, so a
+     * formula that reads it (`ROW(A13)`, `CELL("address",A13)`) shares its answer with another cell
+     * only where the position cannot matter — see `CalcScope.positionRead`. Set by the context that builds the reference; a view
+     * (`slice`, `toType`) carries it.
+     */
+    protected _onCoordsRead: (() => void) | null;
     constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords, options: IRange.ValueOptions | null | undefined, getEntireCoords: (() => IRange.Coords) | undefined, resolveScope: (scope: string) => string | undefined);
     /** @inheritdoc IReferenceRange.getCoords */
     getCoords(): Readonly<IRange.Coords>;
     /** @inheritdoc IReferenceRange.isIReferenceRange */
     get isIReferenceRange(): true;
+    /**
+     * @internal
+     * Attaches the error index of the grid this reference reads. Set by the context that builds
+     * the reference; a typed view (`toType`) carries it.
+     */
+    _setErrorIndex(index: ReferenceErrorIndex | null): void;
+    /**
+     * @internal
+     * Attaches the hook a position read reports to — see {@link _onCoordsRead}.
+     */
+    _setCoordsReadHook(hook: (() => void) | null): void;
+    /** @inheritdoc IRange.hasError */
+    hasError(): boolean;
+    /** @inheritdoc IRange.slice */
+    slice(coords: Partial<IRange.Coords>): this;
+    /** @inheritdoc Range.clone */
+    clone(options?: IRange.IteratorOptions, isLiteral?: boolean, isDirectScalar?: boolean): this;
+    /**
+     * @internal
+     * The reference DEMOTED to its values: a plain `Range` over the same grid and coords, with no
+     * reference identity. The call-exit applies this to a VALUE-declared function's reference
+     * result (IFERROR/IFNA's surviving branch — ISREF of it is FALSE, measured; TypedFunction §3.1).
+     */
+    _toValueRange(): IRange;
     /** @inheritdoc IRange.toType */
     toType(type: ScalarType | IRange.ValueOptions): this;
     protected _validateCoords(coords: Partial<IRange.Coords>): void;

package/types/src/primitives/Runtime.d.ts

@@ -17,12 +17,23 @@ export interface RuntimeOptions {
      */
     getLocaleOverrides?: () => LocaleProfileOverrides | null;
     /**
-     * Returns now as a long date time.
+     * The clock behind {@link IRuntime.getNow}, as epoch milliseconds — not a serial date.
      *
      * @remarks
-     * This is not a serial date here.
+     * Pinning it makes `NOW` and `TODAY` reproducible. A workbook that builds its own runtime pins
+     * this to the current commit's timestamp, so supplying a runtime without one hands those
+     * functions the wall clock instead.
      */
     getNow?: () => number;
+    /**
+     * The value behind {@link IRuntime.getRandom}, drawn once per calculation pass — `Math.random`
+     * unless a host pins it.
+     *
+     * @remarks
+     * Pinning it makes every draw in the workbook reproducible. Like a pinned clock it is a
+     * whole-run choice: collaborators who do not pin the same value do not draw the same values.
+     */
+    getRandom?: () => number;
 }
 export declare const defaultLocale: () => string;
 export declare const languageLocale: () => string | null;
@@ -37,6 +48,8 @@ export declare class Runtime implements IRuntime {
     getLocale(): string;
     /** @inheritdoc IRuntime.getNow */
     getNow(): number;
+    /** @inheritdoc IRuntime.getRandom */
+    getRandom(): number;
     /** @inheritdoc IRuntime.getLocaleProfile */
     getLocaleProfile(): LocaleProfile;
     /** @inheritdoc IRuntime.isDate1904 */

package/types/src/primitives/environment.browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The runtime location - the current page url in the browser.
+ */
+export declare function getLocation(): string;
+/**
+ * The OS platform, used by the `INFO("system")` formula.
+ */
+export declare function getOS(): string;
+//# sourceMappingURL=environment.browser.d.ts.map

package/types/src/primitives/environment.node.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The runtime location - the current working directory in node.
+ */
+export declare function getLocation(): string;
+/**
+ * The OS platform, used by the `INFO("system")` formula. `process.platform` is available
+ * synchronously without importing `os`.
+ */
+export declare function getOS(): string;
+//# sourceMappingURL=environment.node.d.ts.map

package/types/src/primitives/stats/AggregateStats.d.ts

@@ -37,8 +37,52 @@ export type AggResults = {
 export type AggSegmentCache = {
     coerce: unknown;
     byRun: WeakMap<IListLike<Scalar>, AggResults[]>;
+    /**
+     * The segments of a walk that SKIPS cells (`IRange.IteratorOptions.processRowSkip`), by the
+     * skip and the origin it counts from: a segment's content then depends on which cells the skip
+     * leaves out, and a caller that keeps one skip (the engine's, per hidden set) keeps its zones.
+     */
+    bySkip: WeakMap<SkipProcessor, Map<number, WeakMap<IListLike<Scalar>, AggResults[]>>>;
 };
 export declare const createAggSegmentCache: () => AggSegmentCache;
+/** A skip as `IRange.IteratorOptions.processRowSkip` gives one: the index to read at or past `index`. */
+export type SkipProcessor = (index: number, reverse?: boolean) => number;
+/**
+ * A skip a walk honors, on one axis of the grid: the range's callback, which counts from the
+ * range's origin on that axis, asked with a grid index less that origin.
+ */
+export interface WalkSkip {
+    readonly skip: SkipProcessor;
+    readonly origin: number;
+}
+/** The skips of a walk, by the grid's axes. */
+export interface WalkSkips {
+    /** The skip along the grid's major axis: a run it skips is left out whole. */
+    readonly major: WalkSkip | null;
+    /** The skip along the grid's minor axis: the cells of a run it skips. */
+    readonly minor: WalkSkip | null;
+}
+/**
+ * The skips `options` ask for, by the grid's axes; `null` when it asks for none.
+ *
+ * @param origin The range's first row and column on the grid, which its callbacks count from.
+ */
+export declare function resolveSkips(options: IRange.IteratorOptions | undefined, isColumn: boolean, origin: IRange.CellCoords | undefined): WalkSkips | null;
+/** Whether the skip leaves out the grid index. */
+export declare const isSkipped: (skip: WalkSkip, index: number) => boolean;
+/**
+ * The grid index to read at or past `index` (at or before, when `reverse`): `index` itself when
+ * the skip reads it. A walk moves straight to it, so a hidden block costs one call, not one per
+ * cell.
+ */
+export declare const nextRead: (skip: WalkSkip, index: number, reverse?: boolean) => number;
+/**
+ * How many cells of `coords` a read under `options` takes in: the population blanks are counted
+ * from. A skipped cell is outside it, so it is never a blank.
+ *
+ * @param origin As {@link resolveSkips}.
+ */
+export declare function countReadCells(options: IRange.IteratorOptions | undefined, coords: IRange.Coords, origin: IRange.CellCoords | undefined): number;
 export declare const resolveAggSegmentCache: (grid: ISparseGrid<Scalar>, inherit?: AggSegmentCache) => AggSegmentCache;
 /**
  * The default minor zone size for segment caching.
@@ -61,13 +105,13 @@ export declare const EmptyAggregates: Readonly<IRangeStats.Aggregates>;
  *
  * @remarks
  * Results are built using a segment cache keyed by run identity (`segmentsByRun`).
- * The cache is shared across all coord shapes that derive from the same root `RangeStats`
- * instance (via `toLocalCoords`), so segment aggregates computed for one shape are reused
- * by any other shape that overlaps the same run segments.
+ * The cache is grid-scoped (see `resolveAggSegmentCache`), so segment aggregates computed for
+ * one coord shape are reused by any other shape over the same grid lineage that overlaps the
+ * same run segments.
  *
  * Returns `null` when the grid is empty.
  */
-export declare function iterateAndCollectStats(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined, segmentCache: AggSegmentCache, zoneSizeMinor: number): AggResults | null;
+export declare function iterateAndCollectStats(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined, segmentCache: AggSegmentCache, zoneSizeMinor: number, skipOrigin?: IRange.CellCoords): AggResults | null;
 /**
  * The value Excel added LAST — the final numeric member in ROW-major order, which is the
  * traversal Excel's accumulators use (measured: `probe-sum-cancel-order.ps1`, two mirrored 2-D
@@ -87,7 +131,7 @@ export declare function iterateAndCollectStats(runtime: IRuntime, grid: ISparseG
  * `(row, col)` is used rather than reverse iteration because the grid's run iterator has no
  * reverse, and this way the result is independent of the grid's axis.
  */
-export declare function findLastNumber(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined): number | undefined;
+export declare function findLastNumber(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined, skipOrigin?: IRange.CellCoords): number | undefined;
 /**
  * Resolves an iterator's `coerce` option into the callable pair the scans use.
  *
@@ -106,14 +150,4 @@ export declare function resolveCoerce(runtime: IRuntime, optionsIterator: IRange
  * Computes derived fields (average, variance, stdDev) and normalizes missing-number fields to null.
  */
 export declare function buildAggregates(raw: AggResults | null): Readonly<IRangeStats.Aggregates>;
-/**
- * Calculates an optimal zone size for a given grid minor dimension.
- *
- * @remarks
- * Strategy: target ~128 segments per full column/row to balance cache granularity
- * (smaller = better reuse for small queries) vs. iteration overhead (fewer = faster
- * full-column scans). Result is rounded up to the nearest power of 2 and clamped to
- * [256, 16384].
- */
-export declare function calculateZoneSize(maxMinorDimension: number): number;
 //# sourceMappingURL=AggregateStats.d.ts.map

package/types/src/primitives/stats/Cancellation.d.ts

@@ -40,4 +40,17 @@ export declare const mayCancel: (sum: number, largestMag: number) => boolean;
  * `SUM(1E-20)` → `1E-20`.
  */
 export declare const snapCancelledSum: (sum: number, lastNumber: number | undefined) => number;
+/**
+ * The rule itself, for one addition whose left operand is known: `result` is `0` when it lands
+ * at least 50 binary exponents below `accBefore`.
+ *
+ * @param result The sum (or difference) just computed.
+ * @param accBefore What was already accumulated — the left operand of a root `+`/`-`.
+ *
+ * @remarks
+ * A binary `+`/`-` is the one-step case of the sum rule: `=H4+H9` (`1 + -(1-2^-50)`) is `0`
+ * while `=H9+H4` keeps `8.88178419700125E-16`, the same order dependence as `SUM`. A non-finite
+ * result is never a cancellation (see {@link mayCancel}).
+ */
+export declare const snapCancelled: (result: number, accBefore: number) => number;
 //# sourceMappingURL=Cancellation.d.ts.map