@einfach-excel/excel-core-ts 0.0.0-stage → 0.2.0

package/@types/deps.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Workbook-level reverse dependency graph — the TS mirror of Rust's
+ * `cell_dependents` / `RangeDependentIndex` (see
+ * `excel/rust/excel-core/src/sheet.rs` and
+ * `docs/KEY_GRANULAR_INVALIDATION.md` for the design RFC).
+ *
+ * The graph answers ONE question fast: "which formulas may change when
+ * cell (sheetId, key) changes?" Mutations run a BFS over those edges so
+ * a write dirties O(true dependents), not O(cached formulas) — the
+ * audit C-2 fix.
+ *
+ * Three edge classes:
+ *  - **point** — `=A1+1` registers `A1 → formula`.
+ *  - **range** — `=SUM(A1:B10)` / `=SUM(A:A)` registers the range in a
+ *    column-bucketed index (Rust `RangeDependentIndex` shape: per-column
+ *    buckets plus a linear `wide` fallback for ranges spanning more than
+ *    `WIDE_COL_SPAN` columns, e.g. whole-row `1:1` ranges). Buckets are
+ *    keyed by COLUMN because rows are unbounded (whole-column aggregates
+ *    over sparse data are the hot case) while columns are capped at
+ *    16 384.
+ *  - **broad** — formulas whose reads cannot be statically bounded:
+ *    `INDIRECT` / `OFFSET` / dynamic-range endpoints, plus volatile
+ *    functions (NOW / TODAY / RAND / RANDBETWEEN / RANDARRAY). These are
+ *    dirtied by EVERY value write — which is both Excel's volatile
+ *    contract and exactly what the old whole-sheet flush did for them.
+ *
+ * Deps are extracted STATICALLY from the AST (`collectStaticDeps`),
+ * resolving names through the registry — so `=SUM(MYRANGE)` depends on
+ * the bound range, and a named LAMBDA's body contributes its refs (the
+ * TS twin of the Rust B-4 fix). Static extraction over-approximates
+ * (both IF branches register) which can only cause spurious re-evals,
+ * never stale values.
+ *
+ * Installation is lazy and replace-shaped: the workbook installs a
+ * formula's edges whenever the evaluator visits it (anchor derive runs
+ * AND transitive trampoline visits via `EvalContext.onFormulaEvaluated`)
+ * — the TS twin of Rust's hydrate-on-read dep install. Registry changes
+ * bump `namesRevision` so the next visit re-extracts.
+ */
+import type { CellKey, CellRange, Expr, NameBinding } from './types';
+/** Workbook-global formula identity: `${sheetId}<NUL>${key}`. */
+export type FormulaId = string;
+export declare function fidOf(sheetId: string, key: CellKey): FormulaId;
+export declare function fidLocation(fid: FormulaId): {
+    sheetId: string;
+    key: CellKey;
+};
+export interface CollectedDeps {
+    /** Point refs. `sheetName` undefined ⇒ the formula's own sheet. */
+    points: Array<{
+        sheetName?: string;
+        key: CellKey;
+    }>;
+    /** Range refs, normalized via `parseRange`. */
+    ranges: Array<{
+        sheetName?: string;
+        range: CellRange;
+    }>;
+    /** True when the formula must be dirtied on every value write. */
+    broad: boolean;
+}
+/**
+ * Walk `ast` and collect every statically-visible cell/range reference.
+ * `resolveName` threads the workbook names registry so named ranges and
+ * named-LAMBDA bodies contribute their refs. LET/LAMBDA parameter names
+ * that shadow workbook names may over-collect — harmless (spurious dep).
+ */
+export declare function collectStaticDeps(ast: Expr, resolveName: (name: string) => NameBinding | undefined): CollectedDeps;
+/** Deps resolved against workbook sheet ids, ready for installation. */
+export interface ResolvedDeps {
+    points: Array<{
+        sheetId: string;
+        key: CellKey;
+    }>;
+    ranges: Array<{
+        sheetId: string;
+        range: CellRange;
+    }>;
+    broad: boolean;
+}
+export declare class DepGraph {
+    private readonly cellDependents;
+    private readonly rangeIndexes;
+    /** Formulas dirtied by every value write. Read by the workbook BFS. */
+    readonly broadDependents: Set<string>;
+    private readonly installed;
+    /** Fast bail-out so dep-free bulk imports pay nothing per key. */
+    isEmpty(): boolean;
+    /** True when `fid` is already installed for this exact AST + registry rev. */
+    isCurrent(fid: FormulaId, ast: Expr, namesRevision: number, runtimeKey?: string): boolean;
+    /** Replace-install `fid`'s edges. */
+    install(fid: FormulaId, ast: Expr, namesRevision: number, deps: ResolvedDeps, runtimeKey?: string): void;
+    /** Remove every edge `fid` installed. Bounded maps under formula churn. */
+    uninstall(fid: FormulaId): void;
+    /**
+     * Size probe for the always-on scale suite (TS mirror of Rust's
+     * `debug_dep_graph_stats`). Pure observation — no graph mutation.
+     *
+     *  - `installed`: formulas with live edges (size of `installed`).
+     *  - `pointKeys`: distinct (sheet, key) coordinates with ≥1 point
+     *    dependent (Σ of per-sheet cellDependents map sizes).
+     *  - `rangeEntries`: distinct registered ranges across all sheets.
+     *  - `broad`: formulas in the dirty-on-every-write set.
+     *
+     * @internal
+     */
+    debugStats(): {
+        installed: number;
+        pointKeys: number;
+        rangeEntries: number;
+        broad: number;
+    };
+    /**
+     * Append every formula depending on (sheetId, key) — point edges plus
+     * range entries containing the coordinate (candidates narrowed via the
+     * column bucket; `wide` scanned linearly, expected tiny).
+     */
+    dependentsOfInto(sheetId: string, key: CellKey, out: FormulaId[]): void;
+}
+//# sourceMappingURL=deps.d.ts.map

package/@types/deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps.d.ts","sourceRoot":"","sources":["../src/deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAEpE,iEAAiE;AACjE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAI9B,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,SAAS,CAE9D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAG7E;AAqBD,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IACnD,+CAA+C;IAC/C,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,CAAC,CAAA;IACvD,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,IAAI,EACT,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,GACrD,aAAa,CAIf;AAoID,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAChD,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,CAAC,CAAA;IACpD,KAAK,EAAE,OAAO,CAAA;CACf;AAmCD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkD;IAEjF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqC;IAElE,uEAAuE;IACvE,QAAQ,CAAC,eAAe,cAAuB;IAE/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAElE,kEAAkE;IAClE,OAAO,IAAI,OAAO;IAIlB,8EAA8E;IAC9E,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,SAAK,GAAG,OAAO;IAUrF,qCAAqC;IACrC,OAAO,CACL,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,IAAI,EACT,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,YAAY,EAClB,UAAU,SAAK,GACd,IAAI;IA4DP,2EAA2E;IAC3E,SAAS,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAiC/B;;;;;;;;;;;OAWG;IACH,UAAU,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAa3F;;;;OAIG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI;CA+BxE"}

package/@types/eval/array-selectors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 条件选择类函数在**数组**判定参数上的求值。
+ *
+ * 职责：当 `IF` / `IFERROR` / `IFNA` / `IFS` / `SWITCH` / `CHOOSE` 的判定参数是
+ * 一片数组时，逐格算出这一格该走哪一路分支，再把被选中的那几路广播回同一形状。
+ *
+ * 标量路径（短路、只算选中的那一支）留在 `evaluate.ts` —— 那是 `evaluate` 自己
+ * 的懒求值约定。「实参怎么求值」是**参数**传进来的，不是 import 的：反向 import
+ * `evaluate.ts` 会成环。
+ *
+ * 超过 300 行是刻意的：六个函数走的是同一套算法 —— 逐格定选路、只物化被选中的
+ * 那几路、按广播规则取格 —— 共用同一张 `ArraySelection` 选路矩阵。按函数名拆，
+ * 这张矩阵的协议就要在两个文件之间来回对，读者更难确认「某一格为什么取到这个
+ * 值」。
+ */
+import type { EvalContext, Expr, Value } from '../types';
+/**
+ * 求值器的「实参求值」（`evaluate.ts` 的 `evaluateFunctionArg`）。
+ *
+ * 传参而不是 import，是为了不与求值器成环 —— 参照 `spill-collision.ts` 的形状。
+ */
+export type EvaluateFunctionArg = (expr: Expr, ctx: EvalContext) => Value;
+export declare function evaluateArrayIf(cond: Value, args: ReadonlyArray<Expr>, ctx: EvalContext, evaluateFunctionArg: EvaluateFunctionArg): Value;
+export declare function evaluateArrayIfError(value: Value, fallback: Expr, ctx: EvalContext, catches: (error: Value & {
+    kind: 'error';
+}) => boolean, evaluateFunctionArg: EvaluateFunctionArg): Value;
+export declare function evaluateArrayChoose(indexValue: Value, args: ReadonlyArray<Expr>, ctx: EvalContext, evaluateFunctionArg: EvaluateFunctionArg): Value;
+export declare function evaluateArrayIfs(args: ReadonlyArray<Expr>, ctx: EvalContext, startPair: number, firstCond: Value, evaluateFunctionArg: EvaluateFunctionArg): Value;
+export declare function evaluateArraySwitch(exprValue: Value, args: ReadonlyArray<Expr>, ctx: EvalContext, evaluateFunctionArg: EvaluateFunctionArg): Value;
+//# sourceMappingURL=array-selectors.d.ts.map

package/@types/eval/array-selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-selectors.d.ts","sourceRoot":"","sources":["../../src/eval/array-selectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAaxD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,KAAK,KAAK,CAAA;AAEzE,wBAAgB,eAAe,CAC7B,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EACzB,GAAG,EAAE,WAAW,EAChB,mBAAmB,EAAE,mBAAmB,GACvC,KAAK,CA0DP;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,IAAI,EACd,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,EACtD,mBAAmB,EAAE,mBAAmB,GACvC,KAAK,CAyBP;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,KAAK,EACjB,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EACzB,GAAG,EAAE,WAAW,EAChB,mBAAmB,EAAE,mBAAmB,GACvC,KAAK,CAoCP;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EACzB,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,KAAK,EAChB,mBAAmB,EAAE,mBAAmB,GACvC,KAAK,CAsCP;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,KAAK,EAChB,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EACzB,GAAG,EAAE,WAAW,EAChB,mBAAmB,EAAE,mBAAmB,GACvC,KAAK,CAiEP"}

package/@types/eval/array-shape.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 数组结果的形状闸门。
+ *
+ * 职责：判定一个二维 `Value` 矩阵能不能作为数组结果落地 —— 行必须等长、格数
+ * 不超过软上限、行列不超过 Excel 网格、格子里不能再嵌一片没摊开的数组 ——
+ * 不合格就给出对应的错误值。
+ */
+import type { Value } from '../types';
+/** 数组结果的软上限（格数）。`spill-collision.ts` 用它砍「够不着」的候选锚点。 */
+export declare const ARRAY_CELL_CAP = 1048576;
+export declare function arrayShapeError(rows: number, cols: number, label: string, capMessage?: string): Value | undefined;
+export declare function scalarCellError(value: Value): Value | undefined;
+export declare function matrixScalarCellError(matrix: Value[][]): Value | undefined;
+export declare function arrayResult(matrix: Value[][], label?: string): Value;
+//# sourceMappingURL=array-shape.d.ts.map

package/@types/eval/array-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-shape.d.ts","sourceRoot":"","sources":["../../src/eval/array-shape.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAIrC,uDAAuD;AACvD,eAAO,MAAM,cAAc,UAAY,CAAA;AAIvC,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,UAAU,SAAoC,GAC7C,KAAK,GAAG,SAAS,CAanB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAE/D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,GAAG,SAAS,CAQ1E;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,SAAiB,GAAG,KAAK,CAQ5E"}

package/@types/eval/binary-ops.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 二元运算符的求值。
+ *
+ * 职责：给定一个运算符与两个已经求好的 `Value`，算出结果值 —— 数组广播、错误
+ * 传播、Excel 的比较语义都在这里收口。
+ */
+import type { BinaryOp, Value } from '../types';
+/**
+ * Apply a binary operator. Errors propagate (left-first per Excel).
+ * Comparisons return `boolean` Value. Concat returns `string`. Numeric
+ * ops return `number`.
+ */
+export declare function applyBinary(op: BinaryOp, left: Value, right: Value): Value;
+//# sourceMappingURL=binary-ops.d.ts.map

package/@types/eval/binary-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-ops.d.ts","sourceRoot":"","sources":["../../src/eval/binary-ops.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAO/C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAK1E"}

package/@types/eval/canonical-name.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 名字的规范化。
+ *
+ * 职责：把工作簿里的一个名字（定义名 / LAMBDA 参数 / LET 绑定）折成查表用的键
+ * —— Excel 的名字大小写不敏感。
+ */
+export declare function canonicalName(name: string): string;
+//# sourceMappingURL=canonical-name.d.ts.map

package/@types/eval/canonical-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-name.d.ts","sourceRoot":"","sources":["../../src/eval/canonical-name.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/@types/eval/cell-address.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 地址表示之间的转换。
+ *
+ * 职责：在 A1 文本、`CellKey`、`CellCoord` 这三种地址表示之间互转。
+ */
+import type { CellCoord, CellKey } from '../types';
+export declare function parseRefToCoord(a1: string): {
+    row: number;
+    col: number;
+} | null;
+export declare function cellCoordFromKey(key: CellKey): CellCoord | undefined;
+export declare function parseRefToKey(a1: string): CellKey | null;
+//# sourceMappingURL=cell-address.d.ts.map

package/@types/eval/cell-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-address.d.ts","sourceRoot":"","sources":["../../src/eval/cell-address.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAUlD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI/E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAOpE;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAIxD"}

package/@types/eval/cell-info.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `CELL` 函数。
+ *
+ * 职责：按第一个实参的 info_type，报出目标格的一项元信息 —— 地址、行列号、
+ * 内容、类型、前缀、宽度、保护、颜色、括号、格式、文件名。
+ *
+ * 与 `reference-info.ts` 里那一族的差别：那些函数各自只答一件事，`CELL` 一个
+ * 函数就要答十二件，它自己的 switch 值得单开一个文件。
+ */
+import type { EvalContext, Expr, Value } from '../types';
+import type { RefInfoDeps } from './reference-info';
+export declare function evaluateCellInfo(args: ReadonlyArray<Expr>, ctx: EvalContext, deps: RefInfoDeps): Value;
+//# sourceMappingURL=cell-info.d.ts.map

package/@types/eval/cell-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-info.d.ts","sourceRoot":"","sources":["../../src/eval/cell-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAIxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EACzB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,WAAW,GAChB,KAAK,CA+DP"}

package/@types/eval/cell-read.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 递归路径下「把一个地址读成值」。
+ *
+ * 职责：在一份 `cells` 快照里解析一个地址（或一片区域），公式格就地递归求值，
+ * 用 `ctx.currentlyEvaluating` 挡住环。
+ *
+ * 这是**递归**那条路 —— 宿主自造 `EvalContext` 的直测、跨表 shim 的嵌套读走
+ * 它。逐格入口（`sheet.ts`）走的是 `trampoline.ts` 的显式工作栈，两条路各自
+ * 保留，原因见 `resolveCell` 的 Recursion note。
+ *
+ * 求值器是**参数**传进来的，不是 import 的：反向 import `evaluate.ts` 会成环。
+ */
+import type { Cell, CellKey, EvalContext, Value } from '../types';
+import { type SpillProjectionRun } from './spill-projection-run';
+import type { EvaluateExpr } from './trampoline';
+/**
+ * Generic ref-lookup shared between the per-sheet ctx (workbook wires it)
+ * and the cross-sheet shim. Pulled into evaluator-internal scope so cycle
+ * detection lives in exactly one place.
+ *
+ * Returns `BLANK` when the cell does not exist (Excel behavior — an
+ * unwritten cell reads as blank, not as `#REF!`).
+ */
+export declare function refLookupGeneric(a1: string, cells: ReadonlyMap<CellKey, Cell>, ctx: EvalContext, evaluate: EvaluateExpr): Value;
+/**
+ * Generic range lookup. Returns a row-major 2-D `Value[][]`. Blank cells
+ * stay blank rather than being omitted.
+ *
+ * For whole-row / whole-col ranges (`A:A`, `1:1`) the range expands to
+ * the Excel max bounds via `parseRange`; `clampWholeAxisRange` pulls the
+ * tail back to the used region first, and anything still over
+ * `MATERIALIZE_REFUSE_CELL_CAP` is refused — 拒绝值带外带标记，见
+ * `range-gate.ts`。SUM / COUNTIF 一族另有稀疏孪生，根本不到这里。
+ */
+export declare function rangeLookupGeneric(start: string, end: string, cells: ReadonlyMap<CellKey, Cell>, ctx: EvalContext, evaluate: EvaluateExpr): Value[][];
+/**
+ * 递归路径的投影账本。每次查找现建一个（`unstable` 关掉备忘录），因为 `cells`
+ * 与求值栈都由调用方的 `currentlyEvaluating` 决定，跨调用复用会读到过期形状。
+ */
+export declare function outOfBandSpillRun(cells: ReadonlyMap<CellKey, Cell>, ctx: EvalContext, evaluateAnchor: (key: CellKey, target: ReadonlyMap<CellKey, Cell>) => Value): SpillProjectionRun;
+//# sourceMappingURL=cell-read.d.ts.map

package/@types/eval/cell-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-read.d.ts","sourceRoot":"","sources":["../../src/eval/cell-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAKjE,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAO1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EACjC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,YAAY,GACrB,KAAK,CAIP;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EACjC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,YAAY,GACrB,KAAK,EAAE,EAAE,CAmCX;AA0CD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EACjC,GAAG,EAAE,WAAW,EAChB,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,GAC1E,kBAAkB,CAgBpB"}

package/@types/eval/coerce.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Value ↔ scalar coercion helpers.
+ *
+ * Excel coercion rules (the subset we need for Wave B/B2 arithmetic +
+ * comparison + concat):
+ *
+ *  - `blank`   → `0` in arithmetic, `""` in concat, `false` in boolean.
+ *  - `number`  → itself.
+ *  - `string`  → parsed as number when it looks numeric; otherwise
+ *                `#VALUE!`. Special-case `"TRUE"` / `"FALSE"` for boolean.
+ *  - `boolean` → `1` / `0` in arithmetic, `"TRUE"` / `"FALSE"` in concat.
+ *  - `error`   → propagates; callers should use `propagateError` before
+ *                attempting coercion.
+ *  - `array`   → not coerced here; binary ops on arrays will be handled in
+ *                Wave E (spill / range broadcast). Returning a `#VALUE!`
+ *                envelope is correct for v1.
+ *
+ * Every helper is total — returns either the desired primitive (wrapped
+ * in `{ ok: true, value }`) or a `Value` error envelope. Callers thread
+ * the error verbatim, preserving the Excel "first-error-wins" rule.
+ */
+import type { Value } from '../types';
+export interface CoerceOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface CoerceErr {
+    readonly ok: false;
+    readonly error: Value & {
+        kind: 'error';
+    };
+}
+export type CoerceResult<T> = CoerceOk<T> | CoerceErr;
+/**
+ * Returns the first `kind: 'error'` value in `args`, or `undefined` if
+ * none. Used by the evaluator's binary/unary ops and by function impls
+ * that opt into the default error-short-circuit behavior.
+ */
+export declare function propagateError(args: ReadonlyArray<Value>): (Value & {
+    kind: 'error';
+}) | undefined;
+/**
+ * Coerce a `Value` to a JS `number` using Excel arithmetic rules.
+ *
+ * - `blank` → 0
+ * - `number` → itself
+ * - `boolean` → 1 / 0
+ * - `string` → `Number(trimmed)` if finite; else `#VALUE!`
+ * - `error` → propagated (caller should have short-circuited already)
+ * - `array` → top-left scalar coerced recursively; empty array → `#VALUE!`
+ */
+export declare function toNumber(v: Value): CoerceResult<number>;
+/**
+ * Coerce a `Value` to a JS `string` for concat / TEXT-like contexts.
+ *
+ * - `blank` → ""
+ * - `string` → itself
+ * - `number` → Excel 的「General」转文本规格（`excelGeneralToText`），不是 JS
+ *   `String(n)`：15 位有效数字、大写带符号至少两位的指数、两侧各自的科学计数
+ *   门槛。`String(n)` 会给出 `'1e+21'` / `'1e-7'` 这种 Excel 不存在的写法。
+ *   `TEXT()` 的显式 number-format 是另一条路，不走这里。
+ * - `boolean` → "TRUE" / "FALSE"
+ * - `error` → propagates
+ * - `array` → top-left scalar
+ */
+export declare function toString(v: Value): CoerceResult<string>;
+/**
+ * Coerce a `Value` to a JS `boolean` for IF / AND / OR contexts.
+ *
+ * - `blank` → false
+ * - `boolean` → itself
+ * - `number` → `n !== 0`
+ * - `string` → "TRUE" / "FALSE" case-insensitive; else `#VALUE!`
+ * - `error` → propagates
+ * - `array` → top-left scalar
+ */
+export declare function toBoolean(v: Value): CoerceResult<boolean>;
+//# sourceMappingURL=coerce.d.ts.map

package/@types/eval/coerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../src/eval/coerce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAGrC,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAA;CAC1C;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAKrD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,SAAS,CAKlG;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAuBvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAkBvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAsBzD"}

package/@types/eval/criteria-grammar.d.ts

@@ -0,0 +1,91 @@
+import type { Value } from '../types';
+/** Shared Excel criteria parsing and scalar matching. */
+export type Comparator = '=' | '<>' | '<' | '<=' | '>' | '>=';
+export interface ParsedCriterion {
+    readonly op: Comparator;
+    /** Comparand as a Value — number / string / boolean / blank. */
+    readonly target: Value;
+    /** Set when the criterion is a string whose body contains `*` or `?`. */
+    readonly wildcard: boolean;
+}
+/** Split a string criterion into (comparator, rest). Defaults to `=`. */
+export declare function parseStringCriterion(raw: string): {
+    op: Comparator;
+    rest: string;
+};
+export declare function parseNumericString(raw: string): number | undefined;
+/**
+ * Convert a Value-shaped criterion into the parsed form. Numeric / boolean
+ * / blank criteria become `op:'='` against the original Value. String
+ * criteria run through the comparator prefix check; the remainder is
+ * coerced to number when possible so `">5"` compares numerically.
+ */
+export declare function parseCriterion(criterion: Value): ParsedCriterion | {
+    error: Value;
+};
+/**
+ * Excel wildcard match:
+ *   `*` → any run of characters (including empty)
+ *   `?` → exactly one character
+ *   `~*` / `~?` / `~~` → literal `*` / `?` / `~`
+ *
+ * Case-insensitive — Excel string comparison is.
+ */
+export declare function wildcardMatch(text: string, pattern: string): boolean;
+export declare function escapeRegex(s: string): string;
+/**
+ * Test whether `value` satisfies `parsed`. Excel rules:
+ *
+ *  - Blank cells match `=""`, do **not** match other numeric/string criteria.
+ *  - Type mismatches under `=` / `<>` are false / true respectively (a
+ *    number cell never equals a string criterion).
+ *  - Comparison operators (`<`, `<=`, `>`, `>=`) only work between
+ *    numerically-coercible values; otherwise no match.
+ *  - String equality is case-insensitive (Excel-compat).
+ *
+ * 错误格分两档，**取决于判据带不带通配符**，别把两档合并：
+ *
+ *  - **不带**通配符（`"#N/A"` / `"<>#N/A"`）→ 按**显示文本**参与比较，于是
+ *    `"#N/A"` 命中错误格，Excel 的标准错误过滤配方靠的就是这个。
+ *  - **带**通配符（`"*"` / `"*N*"`）→ 错误格是**非文本格**，完全不参与匹配，
+ *    因此 `"*"` 不命中它、`"<>*"` 命中它。
+ *
+ * 再往外还有第三档：criteria 实参**本身**求值成错误值 → 在 `parseCriterion`
+ * 里原样传播，根本走不到这里。
+ */
+export declare function matchesCriterion(cell: Value, parsed: ParsedCriterion): boolean;
+export declare function makeCriterionMatcher(criterion: Value): {
+    readonly ok: true;
+    readonly matches: (value: Value) => boolean;
+    readonly matchesBlank: boolean;
+} | {
+    readonly ok: false;
+    readonly error: Value;
+};
+/**
+ * AVERAGEIF / AVERAGEIFS 的**值区取数口径**：只认真正的数字。
+ *
+ * 与 SUMIF 的 `toNumber` 是两档，别合并 —— 求和把空格当 0 加进去无害，平均
+ * 却要靠它决定**分母**。Excel 的措辞是 "If a cell in average_range is an
+ * empty cell, AVERAGEIF ignores it" 与 "Cells in range that contain TRUE or
+ * FALSE are ignored"，等价于「只有 number 格进分子分母」，与裸 `AVERAGE`
+ * （`forEachNumericArg`，见 `functions/math.ts`）同一条规则。
+ *
+ * 事故留痕：这里曾经是 `toNumber`，于是空格 → 0、`TRUE` → 1、文本 `"5"` → 5
+ * 全都进了分母。`AVERAGEIF(A1:A3,"")` 因此在 A2 空、B2 空时答 **0**
+ * （命中一格、值 0），而 Excel 与本仓 Rust 引擎都是 `#DIV/0!` —— 这两条
+ * 看着是两个 bug，其实是同一处口径错误的两个症状。
+ *
+ * Rust 孪生：`excel/rust/excel-core/src/eval_criteria_blank.rs::number_only`。
+ * 稀疏孪生：`sparse-single-criterion.ts` / `sparse-multi-criterion.ts` 的
+ * AVERAGEIF(S) 分支 —— 三处必须同改。
+ */
+export declare function averageTierNumber(v: Value): number | undefined;
+/** Coerce to a number for ordered comparison; return undefined if no clean coercion. */
+export declare function numericComparable(v: Value): number | undefined;
+/**
+ * Scalar equality used by `=` / `<>`. Numeric criteria coerce numeric
+ * strings from cells, matching Excel/Rust COUNTIF-family behavior.
+ */
+export declare function scalarEquals(a: Value, b: Value): boolean;
+//# sourceMappingURL=criteria-grammar.d.ts.map

package/@types/eval/criteria-grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-grammar.d.ts","sourceRoot":"","sources":["../../src/eval/criteria-grammar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAErC,yDAAyD;AAEzD,MAAM,MAAM,UAAU,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAA;AAE7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAA;IACvB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;IACtB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CASlF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKlE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,KAAK,GAAG,eAAe,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAqCnF;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CA0BpE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAkD9E;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,KAAK,GAEd;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;IAC3C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAC/B,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACtB,CAUJ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAE9D;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAO9D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAexD"}

package/@types/eval/criteria-value-range.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 一件事：**物化路径上，把 SUMIF / AVERAGEIF 的值区实参按「左上角 + 条件区形状」
+ * 重新读一遍**，再交给 `FUNCTIONS` 注册表里的实现。
+ *
+ * 为什么必须在求值器这一层做：`FUNCTIONS.SUMIF` 只拿得到 `Value[]`，值区被压成
+ * 一个数组之后就再也不知道它落在网格的哪里 —— 而 Excel 的规则要求越过值区自身
+ * 的边界继续往下读（`SUMIF(A1:A3,">1",B1)` 要读到 B3）。只有还握着 `Expr` 的
+ * 求值器能把这片格子重新解析出来。
+ *
+ * 事故留痕：修之前这条路用 `n = min(len(range), len(sum_range))` 截断，于是
+ * `SUMIF(A1:A3,">1",B1)` 给 0、`SUMIF(A1:A3,">1",B1:B2)` 给 200（Excel 都是
+ * 500）；而同一个函数的稀疏孪生 `evaluateSparseSumIf` 用 `relativeCoord` 走的
+ * 正是对的规则 —— 同一组输入，两条路两个答案，且没有任何测试把它们对起来。
+ * 现在两条路共用 `criteria-value-rect.ts` 的同一条几何规则，配对断言在
+ * `test/criteria-value-range.test.ts`。
+ */
+import type { CellCoord, EvalContext, Expr, Value } from '../types';
+import type { RuntimeRefResult } from './runtime-ref-resolve';
+/**
+ * 求值器按回调传进来的两件事。**不回头 import `evaluate.ts`** —— 本文件被
+ * 求值器直接依赖，反向 import 会成环，而循环依赖在本仓是硬门禁
+ * （`rollup.config.mjs` 的 `INTENTIONAL_CYCLE` 白名单不为新代码开口）。
+ * 形状照抄同目录的 `RefResolveDeps` / `RefInfoDeps`。
+ */
+export interface CriteriaValueDeps {
+    /** 表达式 → 运行期引用矩形（`evaluate.ts` 的 `runtimeRefFromExpr`）。 */
+    readonly resolveRef: (expr: Expr, ctx: EvalContext) => RuntimeRefResult;
+    /** 单格读，折叠成标量（`evaluate.ts` 的 `valueAtRuntimeCoord`）。 */
+    readonly valueAt: (sheetName: string | undefined, coord: CellCoord, ctx: EvalContext) => Value;
+}
+export interface AlignedCriteriaValueArg {
+    readonly index: number;
+    readonly value: Value;
+}
+/**
+ * 值区实参要不要重读？要就返回替换值，不要就返回 `undefined`（调用方照常求值）。
+ *
+ * 返回 `undefined` 的几种情形，都是刻意保持原行为：
+ *  - 不是 SUMIF / AVERAGEIF，或没写第三个实参；
+ *  - 条件区或值区不是引用（数组字面量、函数结果……）—— Excel 这条规则讲的是
+ *    引用的几何，非引用没有「左上角」可言；
+ *  - 两边形状本来就一样 —— 重读会得到同一片格子，白花开销。
+ */
+export declare function alignCriteriaValueArg(upperName: string, args: ReadonlyArray<Expr>, ctx: EvalContext, deps: CriteriaValueDeps): AlignedCriteriaValueArg | undefined;
+//# sourceMappingURL=criteria-value-range.d.ts.map

package/@types/eval/criteria-value-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-value-range.d.ts","sourceRoot":"","sources":["../../src/eval/criteria-value-range.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAO7D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,KAAK,gBAAgB,CAAA;IACvE,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,CAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,WAAW,KACb,KAAK,CAAA;CACX;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EACzB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,iBAAiB,GACtB,uBAAuB,GAAG,SAAS,CA0BrC"}

package/@types/eval/criteria-value-rect.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 一件事：**SUMIF / AVERAGEIF 第三个实参（值区）实际覆盖哪个矩形**。
+ *
+ * Excel 对这两个函数的值区只取**左上角**，行列数由**条件区**决定 —— 值区自己
+ * 写成一格、写短、写长、甚至写成整列，都不参与形状：
+ *
+ * > "The sum_range argument does not have to be the same size and shape as the
+ * >  range argument. The actual cells that are added are determined by using
+ * >  the upper leftmost cell in the sum_range argument as the beginning cell,
+ * >  and then including cells that correspond in size and shape to the range
+ * >  argument."  —— Microsoft, SUMIF（AVERAGEIF 的 average_range 同款措辞）
+ *
+ * 这条规则在本仓有三个消费者，都必须走这里：
+ *  1. 稀疏路径 `sparse-single-criterion.ts` —— 它靠 `relativeCoord` 逐格换算，
+ *     等价于本矩形，是历史上唯一做对的一条；
+ *  2. 物化路径 `criteria-value-range.ts` —— 把值区按本矩形重新读一遍再交给
+ *     `FUNCTIONS.SUMIF` / `FUNCTIONS.AVERAGEIF`；
+ *  3. 依赖图 `deps.ts` —— 公式读了哪片格子就得依赖哪片，否则 `B1` 之外的格子
+ *     变了不会触发重算。
+ *
+ * 本文件**不 import 求值器**，`deps.ts` 才能安全地用它（那边在 import 图上位于
+ * 求值器之外）。
+ *
+ * ⚠️ 只管 SUMIF / AVERAGEIF 这一档「传统 IF 家族」。`SUMIFS` / `AVERAGEIFS` /
+ * `MAXIFS` / `MINIFS` / `COUNTIFS` 是另一条规则：Excel 要求各区形状严格相同，
+ * 否则 `#VALUE!` —— 别把这里的宽容套过去。
+ */
+import type { CellRange, Expr } from '../types';
+/** 走这条规则的函数名（大写）。 */
+export declare function usesCriteriaValueRect(upperName: string): boolean;
+/**
+ * 值区实际矩形 = `anchor` 的左上角 + `criteria` 的行列数。
+ *
+ * 越过网格边界返回 `undefined`（调用方给 `#REF!`）—— 与稀疏路径
+ * `relativeCoord` 的越界判定同一口径。
+ */
+export declare function criteriaValueRect(criteria: CellRange, anchor: CellRange): CellRange | undefined;
+/** 两个矩形行列数是否相同 —— 相同就不必重新读值区。 */
+export declare function sameRectShape(a: CellRange, b: CellRange): boolean;
+/**
+ * 依赖图要登记的值区矩形 —— `deps.ts` 的入口。
+ *
+ * `=SUMIF(A1:A3,">1",B1)` 静态上只看得见 `B1` 一个点，实际读到 B1:B3。不把
+ * 真实矩形登记进去，B2 / B3 改了不会触发重算 —— 值是对的但会变陈。
+ *
+ * 返回 `undefined` 时调用方照常按普通实参收集依赖（形状本来就一样、实参不是
+ * 静态引用、或矩形越界）。
+ */
+export declare function criteriaValueDepRect(upperName: string, args: ReadonlyArray<Expr>, sheetName: string | undefined): {
+    readonly sheetName?: string;
+    readonly range: CellRange;
+} | undefined;
+//# sourceMappingURL=criteria-value-rect.d.ts.map

package/@types/eval/criteria-value-rect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-value-rect.d.ts","sourceRoot":"","sources":["../../src/eval/criteria-value-rect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAG/C,qBAAqB;AACrB,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,SAAS,GAChB,SAAS,GAAG,SAAS,CAKvB;AAED,iCAAiC;AACjC,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAKjE;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EACzB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAQxE"}

package/@types/eval/cycle-guard.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 环检测键。
+ *
+ * 职责：给「某个 `cells` 快照里的某个 `CellKey`」造一个跨表不会撞车的键。
+ */
+import type { Cell, CellKey } from '../types';
+export declare function tagFor(cells: ReadonlyMap<CellKey, Cell>): string;
+/**
+ * Build the composite cycle-set key for `(cells, cellKey)`. Exported so
+ * `sheet.ts` can seed the set with the entry-point cell before invoking
+ * `evaluate` directly (the entry doesn't flow through `resolveCell` and
+ * would otherwise re-enter unguarded).
+ */
+export declare function cycleGuardKey(cells: ReadonlyMap<CellKey, Cell>, key: CellKey): CellKey;
+//# sourceMappingURL=cycle-guard.d.ts.map

package/@types/eval/cycle-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-guard.d.ts","sourceRoot":"","sources":["../../src/eval/cycle-guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAU7C,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,MAAM,CAOhE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EACjC,GAAG,EAAE,OAAO,GACX,OAAO,CAET"}

package/@types/eval/error-value.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 求值器的错误值构造器。
+ *
+ * 职责：把一个 `ErrorCode`（可选附言）包成 `Value` 的 `error` 变体。
+ *
+ * 单列一个文件，是为了让求值器的那些叶子模块（`array-shape` / `grid` /
+ * `binary-ops` / `runtime-ref` …）都能用上它，而不必反过来 import
+ * `evaluate.ts` —— 那会把它们一并拖进求值器的循环导入。
+ */
+import type { ErrorCode, Value } from '../types';
+export declare const ERR: (code: ErrorCode, message?: string) => Value;
+//# sourceMappingURL=error-value.d.ts.map

package/@types/eval/error-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-value.d.ts","sourceRoot":"","sources":["../../src/eval/error-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAEhD,eAAO,MAAM,GAAG,GAAI,MAAM,SAAS,EAAE,UAAU,MAAM,KAAG,KAC4B,CAAA"}