@sheetxl/sdk 0.7.28-beta.2 → 0.7.28-beta.4

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

@@ -0,0 +1,81 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { CalcNode } from '../state';
+import { CircularEntry } from '../spatial';
+import { CalcExecutor } from './CalcExecutor';
+/**
+ * The two graph questions a {@link CircularReference} cannot answer on its own; built once by
+ * the executor, shared by every cycle.
+ */
+export interface CycleHost {
+    /** Whether `node` is still the node registered for its own cell (a deleted formula's is not). */
+    isLiveNode(node: CalcNode): boolean;
+    /** The sheet name for a grid id, or `undefined` for a virtual grid (a named formula's body). */
+    resolveScope(gridId: string): string | undefined;
+}
+/**
+ * One reference cycle (DESIGN-CIRCULAR-CALC.md §7.3): the executor's record of it and its public
+ * face in one — the object a `Feature.Circular` region carries as its payload and
+ * `ICell.getCircularReference()` answers. It holds the nodes the sheet index currently shows as
+ * its members and as downstream of it, the interned index payloads, and how the sweep that
+ * settled it ended. It persists across passes — a node moves between cycles when a commit writes
+ * its delta (`_trackCircular`) — and is dropped when its last node leaves.
+ *
+ * @remarks
+ * Every read filters through {@link CycleHost.isLiveNode}: a pass that deletes the offending
+ * formula never plans, so the sets cannot clear themselves, and a member is counted only while
+ * its cell still holds the block the cycle was found in (design §7.3, trap 5).
+ *
+ * The iteration answers come from the sweep that settled the cycle (design §6.3). A cycle id is
+ * minted by the pass that finds it, so a cycle evaluated with iteration off is a different object
+ * with no record — `isIterative()` is exactly "a sweep settled this one".
+ */
+export declare class CircularReference implements ICalculation.ICircularReference {
+    protected readonly _host: CycleHost;
+    protected readonly _cycleId: number;
+    /** @internal The nodes the sheet index shows in the cycle; maintained by the executor. */
+    readonly members: Set<CalcNode>;
+    /** @internal The nodes the sheet index shows downstream of the cycle; maintained by the executor. */
+    readonly downstream: Set<CalcNode>;
+    /** One payload per kind, so equal payloads are one object and adjacent cells one region. */
+    protected _memberEntry: CircularEntry | null;
+    protected _downstreamEntry: CircularEntry | null;
+    protected _iteration: CalcExecutor.IterationResult | null;
+    constructor(host: CycleHost, cycleId: number);
+    /** @internal The executor's key for this cycle. */
+    getCycleId(): number;
+    /** @internal Whether the sheet index shows no cell in or downstream of the cycle any more. */
+    isEmpty(): boolean;
+    /** @internal The index payload for the cycle's members or for its downstream cells. */
+    getEntry(isMember: boolean): CircularEntry;
+    /** @internal How the sweep that settled this cycle ended; written by the executor. */
+    setIteration(result: CalcExecutor.IterationResult): void;
+    /** @inheritdoc ICalculation.ICircularReference.getRepresentative */
+    getRepresentative(): IRange.CellCoords | null;
+    /** @inheritdoc ICalculation.ICircularReference.getMembers */
+    getMembers(): readonly IRange.CellCoords[];
+    /** @inheritdoc ICalculation.ICircularReference.getMemberCount */
+    getMemberCount(): number;
+    /** @inheritdoc ICalculation.ICircularReference.getDownstreamCount */
+    getDownstreamCount(): number;
+    /** @inheritdoc ICalculation.ICircularReference.isMember */
+    isMember(coords: IRange.CellCoords): boolean;
+    /** @inheritdoc ICalculation.ICircularReference.getPath */
+    getPath(from: IRange.CellCoords): readonly IRange.CellCoords[];
+    /** The live member at `coords`, or `null`. */
+    protected _memberAt(coords: IRange.CellCoords): CalcNode | null;
+    /** @inheritdoc ICalculation.ICircularReference.isIterative */
+    isIterative(): boolean;
+    /** @inheritdoc ICalculation.ICircularReference.isConverged */
+    isConverged(): boolean;
+    /** @inheritdoc ICalculation.ICircularReference.getIterationCount */
+    getIterationCount(): number;
+    /** @inheritdoc ICalculation.ICircularReference.getLastChange */
+    getLastChange(): number;
+    /** The members still on the graph, in row-major order (virtual grids first, then by sheet). */
+    protected _liveMembers(): CalcNode[];
+    protected _countLive(nodes: Set<CalcNode>): number;
+    protected _scopeOf(node: CalcNode): string | null;
+    protected _toCoords(node: CalcNode): IRange.CellCoords;
+}
+//# sourceMappingURL=CircularReference.d.ts.map

package/types/src/calculation/functions/Operators.d.ts

@@ -25,6 +25,6 @@ export declare const Prefix: {
 };
 export declare const Postfix: {
     '%': (context: IFormulaContext, value: any) => any;
-    '#': (context: IFormulaContext, value: any) => IReferenceRange;
+    '#': (context: IFormulaContext, value: any) => IReferenceRange | FormulaError.Known;
 };
 //# sourceMappingURL=Operators.d.ts.map

package/types/src/calculation/grid/CalcGrid.d.ts

@@ -3,7 +3,7 @@ import { IListener } from '../../listener';
 import { ListenerEmitter } from '../../listener/ListenerEmitter';
 import { Tuple, ISpatialQuery, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
 import { IContextContainer, CalcNode } from '../state';
-import { SpillEntry, FormulaSpatialValue, ContentfulSpatialValue, PrecedentSpatialValue } from '../spatial';
+import { SpillEntry, FormulaSpatialValue, ContentfulSpatialValue, PrecedentSpatialValue, CircularEntry } from '../spatial';
 import { IFormulaBlock } from '../formula';
 import { ReferenceCoords } from '../Types';
 import { ICalculation } from '../ICalculation';
@@ -20,12 +20,14 @@ export declare class CalcGrid implements ICalcGrid {
     _spillSpatial: ISpatialMap<SpillEntry>;
     _errorSpatial: ISpatialMap<string>;
     _pendingSpatial: ISpatialMap<boolean>;
+    _circularSpatial: ISpatialMap<CircularEntry>;
     _contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
     _notifyValues: ISpatialMap;
     _notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
     _notifySpillsRemove: IRange.Coords[];
     _notifyFormats: ISpatialMap;
     _notifyPending: ISpatialMap<boolean>;
+    _notifyCircular: ISpatialMap<CircularEntry | false>;
     _cloneKey?: CalcGrid;
     _version: number;
     _iterationId: number;
@@ -75,6 +77,8 @@ export declare class CalcGrid implements ICalcGrid {
     getDirtyRegions(): ISpatialQuery;
     /** {@inheritDoc ICalcGrid.getFormulas} */
     getFormulas(): ISpatialQuery<IFormulaBlock>;
+    /** {@inheritDoc ICalcGrid.getSpills} */
+    getSpills(): ISpatialQuery<SpillEntry>;
     /** {@inheritDoc ICalcGrid.getSnapshot} */
     getSnapshot(options?: ICalcGrid.GetSnapshotOptions): ICalcGrid.ISnapshot;
     /** {@inheritDoc ICalcGrid.getDirectDependentsAt} */

package/types/src/calculation/grid/CalcGridUtils.d.ts

@@ -1,7 +1,7 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
 import { Tuple, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
 import { CalcNode } from '../state';
-import { ContentfulSpatialValue, FormulaSpatialValue, SpillEntry, PrecedentSpatialValue, PrecedentKind } from '../spatial';
+import { ContentfulSpatialValue, FormulaSpatialValue, SpillEntry, PrecedentSpatialValue, CircularEntry, PrecedentKind } from '../spatial';
 import { ReferenceCoords } from '../Types';
 export declare function anchorCompareValues(a: ISpatialMap.Entry<FormulaSpatialValue>, removing: ISpatialMap.Entry<FormulaSpatialValue>): boolean;
 /**
@@ -19,7 +19,8 @@ export declare function isTopLeft(rowIndex: number, colIndex: number, range: IRa
  * This code will inline spill errors but spill results are handled in calculations.
  */
 export declare function applyContentful(cycleId: number, removes: readonly IRange.Coords[] | null | undefined, inserts: ISpatialMap.Entry[] | null | undefined, contentfulSpatial: ISpatialMap<ContentfulSpatialValue>, spillSpatial: ISpatialMap<SpillEntry>, values: ISparseGrid<Scalar>, addDirty?: (colStart: number, rowStart: number, colEnd: number, rowEnd: number) => void, notifyValuesSpatial?: ISpatialMap, notifySpills?: (insert: ISpatialMap.Entry<SpillEntry>, remove: ISpatialMap.Entry<SpillEntry>) => void, notifyPending?: ISpatialMap<boolean>, errorSpatial?: ISpatialMap<string>, // notifyErrorSpatial,
-isColumn?: boolean, notifyCalc?: boolean): IRange.Coords | null;
+isColumn?: boolean, notifyCalc?: boolean, // should notify. this is to differentiate between user set values and calc set values
+circularSpatial?: ISpatialMap<CircularEntry>): IRange.Coords | null;
 /**
  * Creates a map from tuples
  *

package/types/src/calculation/grid/ICalcGrid.d.ts

@@ -5,7 +5,7 @@ import { IListener } from '../../listener';
 import { IHistory } from '../../history';
 import { ISpatialQuery, ISpatialMap, ISparseGrid, Tuple } from '../../collections';
 import { IFormulaBlock } from '../formula';
-import { ContentfulSpatialValue, SpillEntry } from '../spatial';
+import { ContentfulSpatialValue, SpillEntry, CircularEntry } from '../spatial';
 import { ReferenceCoords, NamedReference } from '../Types';
 import { ICalculation } from '../ICalculation';
 /**
@@ -66,6 +66,17 @@ export interface ICalcGrid {
      * Used by sheet
      */
     getFormulas(): ISpatialQuery<IFormulaBlock>;
+    /**
+     * Returns a queryable spatial index of the ARRAY EXTENTS on this grid — one entry per array
+     * formula, keyed by the cells it occupies: a dynamic array's spill, a legacy CSE block, or the
+     * single cell a blocked spill collapses to.
+     *
+     * @remark
+     * The same index a calculation pass writes through {@link ICalcGrid.IncrementalUpdates.spillSpatial}
+     * (`beginUpdates` hands out this very map), so a read answers identically inside and outside a
+     * pass — which is what lets a formula evaluated OUTSIDE one resolve a spill anchor.
+     */
+    getSpills(): ISpatialQuery<SpillEntry>;
     /**
      * Returns the current values on the grid.
      */
@@ -300,6 +311,14 @@ export declare namespace ICalcGrid {
          * These are guaranteed to not overlap.
          */
         pendingUpdates?: ISpatialMap.Entry<boolean>[];
+        /**
+         * Cells that entered or left a reference cycle (or the set downstream of one). A `null`
+         * value is a removal.
+         *
+         * @remarks
+         * These are guaranteed to not overlap.
+         */
+        circularUpdates?: ISpatialMap.Entry<CircularEntry | null>[];
     }
     /**
      * Returns from `ICalcGrid.beginUpdates()`.
@@ -313,13 +332,16 @@ export declare namespace ICalcGrid {
         spillSpatial: ISpatialMap<SpillEntry>;
         errorSpatial: ISpatialMap<string>;
         pendingSpatial: ISpatialMap<boolean>;
+        circularSpatial: ISpatialMap<CircularEntry>;
         contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
         notifyValues: ISpatialMap;
         notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
         notifySpillsRemove: IRange.Coords[];
         notifyFormats: ISpatialMap;
         notifyPending: ISpatialMap<boolean>;
+        notifyCircular: ISpatialMap<CircularEntry | false>;
         pendingConflating: ISpatialMap.IConflatingEntries<boolean> | null;
+        circularConflating: ISpatialMap.IConflatingEntries<CircularEntry | false> | null;
         errorRemovesConflating: ISpatialMap.IConflatingEntries<null> | null;
         errorInsertsConflating: ISpatialMap.IConflatingEntries<string> | null;
         formatsConflating: ISpatialMap.IConflatingEntries | null;

package/types/src/calculation/spatial/CircularEntry.d.ts

@@ -0,0 +1,18 @@
+import { ICalculation } from '../ICalculation';
+/**
+ * What a sheet's circular index says about a cell (DESIGN-CIRCULAR-CALC.md §7.2): which
+ * reference cycle it belongs to, and whether it is in the cycle or merely downstream of it.
+ *
+ * @remarks
+ * The value stays what it is (`0`, Excel's answer with iterative calculation off); this is
+ * metadata beside it, the way `SpillEntry` marks a spill zone. Entries are interned per
+ * `(cycle, kind)` by the executor, so equal payloads are the same object and adjacent cells of
+ * one cycle coalesce into one region — and a region's payload IS the cycle, no id to look up.
+ */
+export interface CircularEntry {
+    /** The cycle; one live object per cycle, shared by every cell in it or downstream of it. */
+    readonly cycle: ICalculation.ICircularReference;
+    /** In the cycle, or a reader of it (transitively). Both evaluate to `0`. */
+    readonly kind: 'member' | 'downstream';
+}
+//# sourceMappingURL=CircularEntry.d.ts.map

package/types/src/calculation/spatial/index.d.ts

@@ -1,4 +1,5 @@
 export * from './SpillEntry';
+export * from './CircularEntry';
 export * from './ContentfulSpatialValue';
 export * from './FormulaSpatialValue';
 export * from './PrecedentSpatialValue';

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

@@ -40,31 +40,38 @@ export interface CalcNode {
     cachedValue: Scalar | IRange | undefined;
     pendingPromise: Promise<any> | null;
     /**
-     * Indicates if the pending is in the pending spatial (to avoid lookup)
+     * The demand evaluation's result — finalized for the cell, or a pending promise — which
+     * `doEvaluate` consumes in place of an `evaluateAt` of its own. Cleared once consumed.
+     * Meaningful only while `CalcState.Circular` is set.
      */
-    pending: boolean;
+    demandValue: any;
     /**
-     * Indicates the pending is waiting on a precedent to resolve.
+     * Identifies the cycle a `CycleRole.Member` belongs to (and the one a `CycleRole.Downstream`
+     * node read). `0` for none. Slices that share a node share an id. Reset every mark phase.
      */
-    pendingPrecedents: boolean;
+    cycleGroup: number;
     /**
-     * Indicates the pending is full filled and waiting for the next cycle to resolve.
+     * For a `CycleRole.Member`: the member this one READ that continues the cycle — the next step
+     * of the walk `ICircularReference.getPath` answers. A cycle of one points at itself. Written
+     * from the `Circular` slice (whose stack order is the read order) and rewritten whenever the
+     * cycle is detected again; stale otherwise, so a walk checks each step is still a live member.
      */
-    pendingResolved: boolean;
+    cycleNext: CalcNode | null;
     /**
-     * Set when the topological sort could not order this node — it is part of a reference cycle, or
-     * downstream of one. Reset for every affected node at the start of each mark phase, so like
-     * `inDegree` it only describes the CURRENT cycle.
-     *
-     * @remarks
-     * Deliberately not folded into {@link state}: `state` carries the Skip/Pending transitions that
-     * `doEvaluate` reads and rewrites mid-pass, and this has to survive being set BEFORE that runs.
+     * The cycle the sheet's circular index currently shows this cell in (`0` none) — what the last
+     * commit wrote, so the next can write the delta. Persists across passes, unlike
+     * {@link cycleGroup}; the role it shows is the `CalcState.ShownRoleMask` field of {@link state}.
      */
-    circular: boolean;
+    shownGroup: number;
     /**
-     * The state is a bit mask with transient states.
-     * The CalcNode is reused across cycles and cloned records for performance.
-     * To ensure that it is correct the cycleId id must be consulted.
+     * Bit mask, laid out by `CalcState`: the pending flags, `Skip`, `Circular`, and the
+     * `DemandState`/`CycleRole` fields of the current pass.
+     *
+     * @remarks
+     * The node is reused across passes, so a per-pass bit is only meaningful when {@link cycleId}
+     * and {@link markId} say the node is in the current pass; the mark phase resets them
+     * (`CalcState.PassMask`) as it visits each affected node. `Skip` and the shown role outlive a
+     * pass on purpose.
      */
     state: number;
 }

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

@@ -1,28 +1,91 @@
+/**
+ * The bit layout of `CalcNode.state`: single-bit flags in the low byte, then three 2-bit fields.
+ *
+ * @remarks
+ * Every bit is independent, so a phase touches only its own: the mark phase clears
+ * {@link PassMask} (what the last pass decided), `doEvaluate` consumes {@link Skip}, and the
+ * promise path flips the pending bits — none of them assigns the whole word.
+ *
+ * The 2-bit fields hold a {@link DemandState} and two {@link CycleRole}s. Their values are
+ * pre-shifted into place, so a read is `(state & Mask) === Value` and a write is
+ * `state = (state & ~Mask) | Value`. The `ShownRole` field sits two bits above `CycleRole`, so
+ * copying the role the pass decided into what the sheet shows is `(state & CycleRoleMask) << 2`.
+ */
 export declare const CalcState: {
+    /** Nothing set. */
+    readonly Idle: 0;
     /**
-     * The default state.
+     * Evaluate-once guard for a dynamic dependency (a dynamic precedent or a spill output) that
+     * caused a recalc: the next pass skips the node instead of re-evaluating it.
      */
-    readonly Active: 0;
+    readonly Skip: number;
+    /** Reserved. */
+    readonly Removed: number;
+    /** The node is in the pending spatial (the user has been given a pending status). */
+    readonly Pending: number;
+    /** A precedent evaluated to a pending value this pass, so the node keeps its cached value. */
+    readonly PendingPrecedents: number;
+    /** The node's promise resolved; the result waits in `cachedValue` for the next pass. */
+    readonly PendingResolved: number;
     /**
-     * Causing a recalc due to a dynamic dependency. This is either a
-     * dynamic precedent or a spill output.
+     * The topological sort could not order the node this pass — it is in a reference cycle, or
+     * downstream of one — so it was (or will be) evaluated by demand and `doEvaluate` takes its
+     * `demandValue` in place of an `evaluateAt`.
      */
-    readonly Skip: 1;
-    readonly Removed: 2;
+    readonly Circular: number;
     /**
-     * The calc node is pending and waiting for a precedent to resolve.
-     * This is used to indicate that the user has been given a pending status.
+     * A `Waiting` node the evaluation in progress has read under iterative calculation — it is in
+     * the executor's hit list already, so a second read of it in the same evaluation adds nothing.
+     * Cleared when the list is consumed.
      */
-    readonly Pending: 3;
+    readonly IterHit: number;
+    /** Field: the {@link DemandState}. */
+    readonly DemandMask: number;
+    /** Field: the {@link CycleRole} this pass decided. */
+    readonly CycleRoleMask: number;
+    /** Field: the {@link CycleRole} the sheet's circular index currently shows (persists). */
+    readonly ShownRoleMask: number;
     /**
-     * The calc node is pending and waiting for a precedent to resolve.
-     * This is used for dynamic dependencies that are not yet resolved.
+     * In the executor's circular roster for the pass in progress. Outside {@link PassMask} on
+     * purpose: the roster outlives the re-marks a pass makes while it re-dirties, so the executor
+     * clears this when it empties the roster.
      */
-    readonly PendingPrecedents: 4;
+    readonly Rostered: number;
+    /** What the mark phase resets: everything a single pass decides. `Skip` and the shown role survive. */
+    readonly PassMask: number;
+};
+/**
+ * Where a node the topological sort could not order stands in the demand evaluation
+ * (DESIGN-CIRCULAR-CALC.md §4.3). Meaningful only while `CalcState.Circular` is set for the
+ * current pass. Values sit in the `CalcState.DemandMask` field.
+ */
+export declare const DemandState: {
+    /** Not yet evaluated; a read of it suspends the reader so it can go first. */
+    readonly Unevaluated: 0;
+    /** On the in-progress stack; a read of it is a reference cycle. */
+    readonly Waiting: number;
+    /** Evaluated (or written `0` as a cycle member); reads see its value. */
+    readonly Done: number;
+    /**
+     * Evaluated on the ordered path but not yet committed — its value is in the pending batch, so a
+     * lazy read of the grid would still see the previous one. Reads treat it as {@link Unevaluated}
+     * until the batch is flushed, which makes it {@link Done}.
+     */
+    readonly Evaluated: number;
+};
+/**
+ * How a node relates to a reference cycle, decided by the demand evaluation's reads. Values sit
+ * in the `CalcState.CycleRoleMask` field.
+ */
+export declare const CycleRole: {
+    /** Not in a cycle and reads none — an unorderable node that simply computed. */
+    readonly None: 0;
+    /** Named by a `Circular` read: its evaluation needed its own value. Writes `0`. */
+    readonly Member: number;
     /**
-     * The calc node is pending and waiting for a precedent to resolve.
-     * This is used for dynamic dependencies that are not yet resolved.
+     * Read a member (transitively). Writes `0` too — Excel gives every cell downstream of a cycle
+     * `0`, not a value computed from the members' `0` (design §2.1: `=A1+100` is `0`).
      */
-    readonly PendingResolved: 5;
+    readonly Downstream: number;
 };
 //# sourceMappingURL=CalcState.d.ts.map

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

@@ -5,6 +5,7 @@ import { IFunctionCollection } from '../../scripting';
 import { Tuple } from '../../collections';
 import { IContextContainer } from './IContextContainer';
 import { CalcScope } from './CalcScope';
+import { ReadHook } from './_ReadObservedGrid';
 export declare class CalculationContext implements IFormulaContext {
     protected _instanceScope: any;
     protected _runtime: IRuntime;
@@ -14,9 +15,39 @@ export declare class CalculationContext implements IFormulaContext {
     protected _axis: IRange.Axis;
     protected _coerceToNumber: (value: Scalar, fromType: ScalarType, options?: IFormulaContext.ParseNumberOptions) => Scalar;
     protected _functionProviders?: readonly FunctionProvider[];
+    /**
+     * Receives every value read while armed; `null` on the ordinary path.
+     *
+     * @remarks
+     * Two paths read the grid on a formula's behalf and both report here: a reference built by
+     * {@link _toReference} (its grid is wrapped in a {@link ReadObservedGrid}) and the direct
+     * single-cell read {@link getValueAt} falls back to. Constructing a reference is not a read.
+     */
+    protected _onRead: ReadHook | null;
+    /**
+     * Receives the reads of references built on the DYNAMIC branch of {@link getReference} — the
+     * result of `OFFSET`/`INDIRECT`/`INDEX` — when {@link _onRead} is not armed. The executor arms
+     * it for the length of an ordinary pass so that a dynamic read landing on the evaluating cell
+     * is seen (DESIGN-CIRCULAR-CALC.md §5); `null` outside a pass.
+     */
+    protected _dynamicRead: ReadHook | null;
     constructor(container: IContextContainer, axis?: IRange.Axis, functionProviders?: readonly FunctionProvider[]);
     /** @hidden */
     _setInstanceScope(instanceScope: any): void;
+    /**
+     * @hidden
+     * Arms (or, with `null`, disarms) the read hook. While armed, every reference this context
+     * builds observes its reads and every direct cell read is reported — the funnel a demand
+     * evaluation decides circularity through. The ordinary evaluation path leaves it `null` and
+     * builds references exactly as before.
+     */
+    _setReadHook(hook: ReadHook | null): void;
+    /**
+     * @hidden
+     * Arms (or, with `null`, disarms) the hook dynamic-branch references report to while no read
+     * hook is armed. See {@link _dynamicRead}.
+     */
+    _setDynamicReadHook(hook: ReadHook | null): void;
     /**
      * @hidden
      *
@@ -100,6 +131,14 @@ export declare class CalculationContext implements IFormulaContext {
      * A caller that reads a WINDOW rather than returning a reference - `SUMIF`'s `sum_range`,
      * `LOOKUP`'s `result_vector`, both anchor-plus-length - goes through
      * {@link getResizedReference} instead: Excel reads the part that fits rather than failing.
+     *
+     * This is the one place a reference is built on a formula's behalf, so it is where the read
+     * hook attaches: while {@link _onRead} is armed the reference is built over a
+     * {@link ReadObservedGrid} and every value it (or a view derived from it) opens is reported.
+     * Unarmed, a static reference's grid is used as is — the ordinary path pays nothing, not even a
+     * branch per read — while a `dynamic` one (the result of `OFFSET`/`INDIRECT`/`INDEX`, the rare
+     * path) reports to {@link _dynamicRead} when that is armed: a dynamic read that lands on the
+     * evaluating cell is a cycle on any path (design §5).
      */
     private _toReference;
     /** @inheritdoc IFormulaContext.getAddress */

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

@@ -0,0 +1,90 @@
+import { Scalar } from '@sheetxl/primitives';
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGrid, ISparseGrid, Tuple } from '../../collections';
+/**
+ * Receives every value read a formula makes while a read hook is armed.
+ *
+ * @remarks
+ * A single-cell read reports a 1x1 rectangle; a block read (iteration, runs, bounded tuples)
+ * reports the rectangle it was asked for — the cells it *may* open — because a sparse iterator
+ * cannot tell an empty cell from a formula cell whose value is not there yet, and the second is
+ * exactly the read a cycle check must see. Coordinates are absolute and closed.
+ *
+ * The hook may throw; the throw propagates through the reading function up to the evaluation
+ * that armed it. Nothing is reported for constructing a reference, for its coords or size, or for
+ * a copy made to hold derived values.
+ */
+export type ReadHook = (gridId: string, rowStart: number, colStart: number, rowEnd: number, colEnd: number) => void;
+/**
+ * An `ISparseGrid` that reports every value access on an inner grid to a {@link ReadHook}.
+ *
+ * @remarks
+ * Every `ReferenceRange` a formula receives reads its cells through the grid it was built over
+ * and never touches the sheet directly, so wrapping that grid observes every value read the
+ * reference makes — through any `Range` view derived from it, since views share the grid.
+ *
+ * `clone`/`cloneEmpty` hand back the inner grid's copy UNWRAPPED. A `Range` operation clones
+ * its grid only as scratch space for a derived result (`fill`, `map`, a scalar broadcast) and
+ * overwrites what it later reads back; the coordinates in such a copy no longer name sheet
+ * cells (a broadcast writes its scalar at (0,0)), so reporting them would invent reads of A1.
+ *
+ * Writes are delegated verbatim; nothing on a reference's path writes to its grid.
+ */
+export declare class ReadObservedGrid implements ISparseGrid<Scalar> {
+    /**
+     * Number of wrappers constructed since module load.
+     *
+     * @remarks
+     * A pass that Kahn orders builds none; tests pin that the ordinary path stays unwrapped.
+     */
+    static created: number;
+    protected readonly _inner: ISparseGrid<Scalar>;
+    protected readonly _gridId: string;
+    protected readonly _onRead: ReadHook;
+    constructor(inner: ISparseGrid<Scalar>, gridId: string, onRead: ReadHook);
+    /** The grid being observed. */
+    getInner(): ISparseGrid<Scalar>;
+    /**
+     * Reports a block read. Missing sides of a partial bound are taken from the grid's maximum
+     * extent, then from its data extent; a grid with neither has nothing to read.
+     */
+    protected _reportBounds(bounds: Partial<RangeCoords> | null | undefined): void;
+    /** {@inheritDoc IGrid.getValueAt} */
+    getValueAt(row: number, column: number): Scalar;
+    /** {@inheritDoc ISparseGrid.getRuns} */
+    getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<Scalar>;
+    /** {@inheritDoc IGrid.entries} */
+    entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator<Scalar>;
+    /** {@inheritDoc IGrid.values} */
+    values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
+    /** {@inheritDoc IGrid.keys} */
+    keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    /** {@inheritDoc IGrid.getValues} */
+    getValues(coords?: RangeCoords): Tuple.BoundedTuples<Scalar> | null;
+    /** {@inheritDoc IGrid.copyTo} */
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+    /** {@inheritDoc IGrid.getAxis} */
+    getAxis(): RangeAxis;
+    /** {@inheritDoc IGrid.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IGrid.getCoords} */
+    getCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.getMaxCoords} */
+    getMaxCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.clone} */
+    clone(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.cloneEmpty} */
+    cloneEmpty(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.setValues} */
+    setValues(values: Tuple.GridTuple<Scalar>): this;
+    /** {@inheritDoc IGrid.setValueAt} */
+    setValueAt(row: number, column: number, value: Scalar): void;
+    /** {@inheritDoc IGrid.delete} */
+    delete(coords: RangeCoords | null): boolean;
+    /** {@inheritDoc IGrid.clear} */
+    clear(): void;
+    /** {@inheritDoc IGrid.shift} */
+    shift(coords: RangeCoords, direction: Direction): boolean;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=_ReadObservedGrid.d.ts.map

package/types/src/cell/ICell.d.ts

@@ -124,12 +124,28 @@ export interface ICell {
      *
      * @remarks
      * Warnings differ from errors in that they may alter the display of the cell's value or type.
+     * A cell in a reference cycle, or downstream of one, carries one here — the text form of
+     * {@link getCircularReference}: the walk from this cell around the cycle and back
+     * ("Circular reference: A1 → B1 → A1"), or "Reads a circular reference at A1".
      */
     getWarnings(): readonly string[];
     /**
      * Retrieves any errors attached to the cell.
      */
     getErrors(): readonly string[];
+    /**
+     * The reference cycle this cell is in, or downstream of — or `null` when it is neither.
+     *
+     * @remarks
+     * Evaluated state, beside the value: a cell in a cycle, and every cell that reads one, is `0`
+     * (Excel, iterative calculation off), and this is the only thing that says why. Ask the cycle
+     * whether this cell is a member or a reader ({@link ICalculation.ICircularReference.isMember})
+     * and, under iterative calculation, whether it converged.
+     *
+     * The range-level view is `ICellRange.Feature.Circular` — `getCounts` for how many cells,
+     * `getRegions` for which, each region carrying this same object as its payload.
+     */
+    getCircularReference(): ICalculation.ICircularReference | null;
     /**
      * Returns the style information applied to the cell.
      *