@univerjs-pro/engine-formula-rust 1.0.0-insiders.20260725-1b9c8d8

package/lib/types/adapters/rust-projection-remote-instance.service.d.ts

@@ -0,0 +1,28 @@
+import type { IBaseSnapshot, IExecutionOptions, IMutationInfo, IWorkbookData } from '@univerjs/core';
+import type { IRemoteInstanceService } from '@univerjs/rpc';
+import { ICommandService, UniverInstanceType } from '@univerjs/core';
+import { RustEngineSyncController } from '../controllers/rust-engine-sync.controller.js';
+/**
+ * Optional worker-side adapter for the no-worker-Workbook runtime.
+ *
+ * Hosts can register this implementation for `IRemoteInstanceService` instead
+ * of `WebWorkerRemoteInstanceService` when Rust owns the formula projection.
+ */
+export declare class RustProjectionRemoteInstanceService implements IRemoteInstanceService {
+    private readonly _syncController;
+    private readonly _commandService;
+    constructor(_syncController: RustEngineSyncController, _commandService: ICommandService);
+    whenReady(): Promise<true>;
+    createInstance(params: {
+        unitID: string;
+        type: UniverInstanceType;
+        snapshot: IBaseSnapshot | IWorkbookData;
+    }): Promise<boolean>;
+    disposeInstance(params: {
+        unitID: string;
+    }): Promise<boolean>;
+    syncMutation(params: {
+        mutationInfo: IMutationInfo;
+    }, options?: IExecutionOptions): Promise<boolean>;
+    private _shouldExecuteOnWorkerFormulaRuntime;
+}

package/lib/types/binding.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Loads the native Rust binding (NAPI on Node.js, WASM in browser).
+ */
+import type { Buffer } from 'node:buffer';
+export interface INativeBinding {
+    formulaEngineExecute(inputJson: string): string;
+    formulaLexerTreeBuild(formula: string, transformSuffix?: boolean): string;
+    formulaSequenceNodesBuild(formula: string): string;
+    formulaCheckIfAddBracket(formula: string): number;
+    rustNumfmtFormat(inputJson: string): string;
+    rustNumfmtFormatBatch(inputJson: string): string;
+    rustNumfmtParse(inputJson: string): string;
+    rustNumfmtParseBatch(inputJson: string): string;
+    rustNumfmtParseMatrixBatch(inputJson: string): string;
+    rustNumfmtParseValue(inputJson: string): string;
+    rustNumfmtAnalyzeFormat(inputJson: string): string;
+    rustNumfmtAnalyzeBatch(inputJson: string): string;
+    rustNumfmtFormatInfo(inputJson: string): string;
+    rustNumfmtFormatDateInfo(inputJson: string): string;
+    rustNumfmtFormatColor(inputJson: string): string;
+    rustNumfmtDateToSerial(inputJson: string): string;
+    rustNumfmtDateFromSerial(inputJson: string): string;
+    rustNumfmtValidate(inputJson: string): string;
+    rustEngineLoadSnapshot(snapshotJson: string): string;
+    rustEngineLoadSnapshotBinary(snapshotBytes: Buffer): string;
+    rustEngineLoadSingleSheetColumnarSnapshot(unitId: string, workbookName: string | undefined | null, sheetId: string, sheetName: string | undefined | null, rowCount: number, columnCount: number, rows: Buffer, cols: Buffer, valueTags: Buffer, numbers: Buffer, valueStringOffsets: Buffer, valueStringBytes: Buffer, formulaOffsets: Buffer, formulaBytes: Buffer): string;
+    rustEngineApplyMutation(mutationJson: string): string;
+    rustEngineApplyMutationBinary(mutationBytes: Buffer): string;
+    rustEngineApplyNumberCellsColumnar(unitId: string, sheetId: string, rows: Buffer, cols: Buffer, values: Buffer): string;
+    rustEngineDisposeWorkbook(unitId: string): string;
+    rustEngineDisposeAllWorkbooks(): string;
+    rustEngineGetModelStats(): string;
+    rustEngineGetCell(unitId: string, sheetId: string, row: number, col: number): string;
+    rustEngineGetSheetState(unitId: string, sheetId: string): string;
+    rustEngineGetFormulaData(unitId?: string): string;
+    rustEngineBuildDependencyGraph(unitId?: string): string;
+    rustEngineGetDirtyDependencies(dirtyRangesJson: string, unitId?: string): string;
+    rustEngineSyncFormulaDependencies(inputJson: string): string;
+    rustEngineInspectFormulaDependencyGraph(): string;
+    rustEngineMarkFormulaDirty(inputJson: string): string;
+    rustEngineClearFormulaDependencies(inputJson: string): string;
+    rustEngineClearFormulaDirty(): string;
+    rustEngineExecuteDirtyFormulas(maxIteration?: number, includeCalculatedNodes?: boolean, includeRuntimeData?: boolean, includeResultBatches?: boolean): string;
+    rustEngineGetFormulaNumberResultsColumnar(unitId: string, sheetId: string, startColumn?: number, endColumn?: number): Buffer;
+    rustMaterializeWorkbookSnapshot(workbookJson: Buffer, unitId: string, rev: number, dirtyInputJson?: string): Promise<INativeMaterializedWorkbook>;
+}
+export interface INativeMaterializedBlock {
+    id: string;
+    startRow: number;
+    endRow: number;
+    data: Buffer;
+}
+export interface INativeMaterializedSheetBlocks {
+    sheetId: string;
+    blocks: INativeMaterializedBlock[];
+}
+export interface INativeMaterializedWorkbook {
+    snapshotDraftJson: Buffer;
+    sheetBlocks: INativeMaterializedSheetBlocks[];
+    warningsJson: Buffer;
+    calculationStatsJson: Buffer;
+}
+export type NativeBindingSource = '../native/index.js' | '../../../crates/univer-formula/index.js' | '@univerjs-pro/engine-formula-rust-binding';
+export declare function getNativeBindingSource(): NativeBindingSource | null;
+export declare function loadNativeBinding(): Promise<INativeBinding>;
+export declare function executeOnRust(inputJson: string): string;
+export declare function buildLexerTreeOnRust(formula: string, transformSuffix?: boolean): string;
+export declare function buildSequenceNodesOnRust(formula: string): string;
+export declare function checkIfAddBracketOnRust(formula: string): number;
+export declare function formatNumberOnRust(inputJson: string): string;
+export declare function formatNumberBatchOnRust(inputJson: string): string;
+export declare function parseNumberFormatInputOnRust(inputJson: string): string;
+export declare function parseNumberFormatInputBatchOnRust(inputJson: string): string;
+export declare function parseNumberFormatMatrixBatchOnRust(inputJson: string): string;
+export declare function parseNumberFormatValueOnRust(inputJson: string): string;
+export declare function analyzeNumberFormatOnRust(inputJson: string): string;
+export declare function analyzeNumberFormatBatchOnRust(inputJson: string): string;
+export declare function getNumberFormatInfoOnRust(inputJson: string): string;
+export declare function getNumberFormatDateInfoOnRust(inputJson: string): string;
+export declare function getNumberFormatColorOnRust(inputJson: string): string;
+export declare function dateToSerialOnRust(inputJson: string): string;
+export declare function dateFromSerialOnRust(inputJson: string): string;
+export declare function validateNumberFormatInputOnRust(inputJson: string): string;
+export declare function loadSnapshotOnRust(snapshotJson: string): string;
+export declare function loadSnapshotBinaryOnRust(snapshotBytes: Buffer): string;
+export declare function loadSingleSheetColumnarSnapshotOnRust(unitId: string, workbookName: string | undefined | null, sheetId: string, sheetName: string | undefined | null, rowCount: number, columnCount: number, rows: Buffer, cols: Buffer, valueTags: Buffer, numbers: Buffer, valueStringOffsets: Buffer, valueStringBytes: Buffer, formulaOffsets: Buffer, formulaBytes: Buffer): string;
+export declare function applyMutationOnRust(mutationJson: string): string;
+export declare function applyMutationBinaryOnRust(mutationBytes: Buffer): string;
+export declare function applyNumberCellsColumnarOnRust(unitId: string, sheetId: string, rows: Buffer, cols: Buffer, values: Buffer): string;
+export declare function disposeWorkbookOnRust(unitId: string): string;
+export declare function disposeAllWorkbooksOnRust(): string;
+export declare function getRustModelStats(): string;
+export declare function getRustCellOnRust(unitId: string, sheetId: string, row: number, col: number): string;
+export declare function getRustSheetStateOnRust(unitId: string, sheetId: string): string;
+export declare function getRustFormulaDataOnRust(unitId?: string): string;
+export declare function buildRustDependencyGraphOnRust(unitId?: string): string;
+export declare function getRustDirtyDependenciesOnRust(dirtyRangesJson: string, unitId?: string): string;
+export declare function syncRustFormulaDependenciesOnRust(inputJson: string): string;
+export declare function inspectRustFormulaDependencyGraphOnRust(): string;
+export declare function markRustFormulaDirtyOnRust(inputJson: string): string;
+export declare function clearRustFormulaDependenciesOnRust(inputJson: string): string;
+export declare function clearRustFormulaDirtyOnRust(): string;
+export declare function executeDirtyFormulasOnRust(maxIteration?: number, includeCalculatedNodes?: boolean, includeRuntimeData?: boolean, includeResultBatches?: boolean): string;
+export declare function getFormulaNumberResultsColumnarOnRust(unitId: string, sheetId: string, startColumn?: number, endColumn?: number): Buffer;
+export declare function materializeWorkbookSnapshotOnRust(workbookJson: Buffer, unitId: string, rev: number, dirtyInputJson?: string): Promise<INativeMaterializedWorkbook>;

package/lib/types/controllers/rust-engine-sync.controller.d.ts

@@ -0,0 +1,40 @@
+import type { IFormulaDatasetConfig } from '@univerjs/engine-formula';
+import type { IRustEngineMutation, IRustFormulaDependencyExecutionOutput } from '../types.js';
+import { Disposable, ICommandService } from '@univerjs/core';
+import { type IRustProjectionWorkbookInput } from '../services/rust-formula-projection.service.js';
+interface IRustEngineSyncState {
+    snapshotEpoch: number;
+    dependencyInvalidationEpoch: number;
+}
+export declare function getRustEngineSyncState(): IRustEngineSyncState;
+/**
+ * Keeps Rust's in-memory formula workbook projection aligned with Univer.
+ *
+ * Rust projection loading is host-driven: the main/runtime adapter provides the
+ * initial workbook snapshot and subsequent formula-relevant mutations. This
+ * controller intentionally does not create or read worker-side Workbook units.
+ */
+export declare class RustEngineSyncController extends Disposable {
+    private readonly _commandService;
+    private _nativeReady;
+    private _snapshotLoaded;
+    private _projectionLoadPromise;
+    private readonly _pendingMutations;
+    constructor(_commandService: ICommandService);
+    private _initialize;
+    loadProjection(workbooks: readonly IRustProjectionWorkbookInput[]): Promise<void>;
+    waitForProjectionLoad(): Promise<void>;
+    private _loadProjection;
+    applyProjectionMutation(mutation: IRustEngineMutation): void;
+    upsertReferenceData(config: IFormulaDatasetConfig, needs: NonNullable<IRustFormulaDependencyExecutionOutput['needsData']>): number;
+    disposeProjectionWorkbook(unitId: string): void;
+    dispose(): void;
+    private _loadSerializedSnapshot;
+    private _queueOrSyncMutation;
+    private _flushPendingMutations;
+    private _syncMutation;
+    private _markProjectionDesynced;
+    private _shouldSyncMutation;
+    private _serializeMutation;
+}
+export {};

package/lib/types/controllers/rust-same-runtime-projection.controller.d.ts

@@ -0,0 +1,27 @@
+import type { ISuperTableService as ISuperTableServiceType } from '@univerjs/engine-formula';
+import { Disposable, ICommandService, IUniverInstanceService } from '@univerjs/core';
+import { FormulaDataModel } from '@univerjs/engine-formula';
+import { RustEngineSyncController } from './rust-engine-sync.controller.js';
+/**
+ * Loads Rust projection from the same Univer runtime that owns calculation.
+ *
+ * This is for headless/same-runtime hosts. It does not recover from worker
+ * Workbook snapshots and does not reload on mutation errors.
+ */
+export declare class RustSameRuntimeProjectionController extends Disposable {
+    private readonly _univerInstanceService;
+    private readonly _rustEngineSyncController;
+    private readonly _formulaDataModel;
+    private readonly _superTableService;
+    private readonly _commandService;
+    private _projectionReload;
+    private _projectionReloadRequested;
+    constructor(_univerInstanceService: IUniverInstanceService, _rustEngineSyncController: RustEngineSyncController, _formulaDataModel: FormulaDataModel, _superTableService: ISuperTableServiceType, _commandService: ICommandService);
+    private _initialize;
+    private _scheduleProjectionReload;
+    private _drainProjectionReloads;
+    private _loadAllWorkbookProjections;
+    private _createBaseWorkbookProjection;
+    private _createBaseTableResource;
+    private _rawCellData;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+export { applyMutationOnRust, buildRustDependencyGraphOnRust, buildLexerTreeOnRust, buildSequenceNodesOnRust, checkIfAddBracketOnRust, disposeAllWorkbooksOnRust, disposeWorkbookOnRust, executeOnRust, getRustCellOnRust, getRustFormulaDataOnRust, getRustDirtyDependenciesOnRust, getRustModelStats, getRustSheetStateOnRust, getNativeBindingSource, loadNativeBinding, loadSnapshotOnRust, materializeWorkbookSnapshotOnRust, syncRustFormulaDependenciesOnRust, markRustFormulaDirtyOnRust, clearRustFormulaDependenciesOnRust, clearRustFormulaDirtyOnRust, } from './binding.js';
+export { RustEngineSyncController } from './controllers/rust-engine-sync.controller.js';
+export { analyzeNumberFormatBatch, formatNumberBatch, parseNumberFormatBatch, parseNumberFormatMatrixBatch, } from './numfmt.js';
+export type { IAnalyzeNumberFormatBatchInput, IAnalyzeNumberFormatBatchOutput, IFormatNumberBatchInput, IFormatNumberBatchOutput, INumberFormatAnalysis, INumberFormatDiagnostic, INumberFormatOptions, IObjectArrayPrimitiveType, IObjectMatrixPrimitiveType, IParsedNumberFormatValue, IParsedNumberFormatMatrixValue, IParseNumberFormatBatchInput, IParseNumberFormatBatchOutput, IParseNumberFormatMatrixBatchInput, IParseNumberFormatMatrixBatchOutput, IParseNumberFormatMatrixCell, NumberFormatDateSystem, } from './numfmt.js';
+export { type IUniverRustFormulaEngineConfig, UniverRustFormulaEnginePlugin } from './plugin.js';
+export { IRustCalculateFormulaService, RustCalculateFormulaService } from './services/calculate-formula.service.js';
+export { materializeWorkbookSnapshot, type IMaterializationCalculationStats, type IMaterializedWorkbookSnapshot, } from './services/workbook-snapshot-materializer.js';
+export { createFormulaProjectionDesyncSignal, isRustFormulaRelevantMutation, isRustIncrementalDependencyMutation, RUST_FORMULA_RELEVANT_MUTATIONS, RUST_INCREMENTAL_DEPENDENCY_MUTATIONS, RUST_UPSERT_REFERENCE_DATA_MUTATION_ID, RustFormulaProjectionService, rustExecutionOutputToFormulaCalculationPatch, serializeRuntimeWorkbookSnapshot, serializeRuntimeWorkbookSnapshots, } from './services/rust-formula-projection.service.js';
+export * from './types.js';
+export type { IFormulaCalculationError, IFormulaCalculationPatch, IFormulaProjectionDesyncSignal, IRustFormulaProjectionLoadResult, IRustFormulaProjectionMutationResult, IRustProjectionWorkbookInput, } from './services/rust-formula-projection.service.js';

package/lib/types/numfmt.d.ts

@@ -0,0 +1,145 @@
+export type NumberFormatDateSystem = '1900' | '1904';
+export interface INumberFormatOptions {
+    locale?: string;
+    dateSystem?: NumberFormatDateSystem;
+    throws?: boolean;
+    invalid?: string;
+    overflow?: string;
+    dateErrorNumber?: boolean;
+    dateSpanLarge?: boolean;
+    leap1900?: boolean;
+    nbsp?: boolean;
+    skipChar?: string;
+    fillChar?: string;
+    bigintErrorNumber?: boolean;
+    ignoreTimezone?: boolean;
+    dateNf?: string;
+}
+export interface INumberFormatDiagnostic {
+    code: string;
+    message?: string;
+    [key: string]: unknown;
+}
+export interface IFormatNumberBatchInput {
+    formats: Array<{
+        id: number;
+        formatCode?: string;
+        numFmtId?: number;
+        options?: INumberFormatOptions;
+    }>;
+    values: Array<{
+        value: unknown;
+        valueType?: 'number' | 'text' | 'boolean' | 'date' | 'datetime' | 'bigint' | string;
+        formatId: number;
+    }>;
+}
+export interface IFormatNumberBatchOutput {
+    values: Array<{
+        text: string;
+        color?: string;
+        style?: unknown;
+        diagnostics: INumberFormatDiagnostic[];
+    }>;
+    timingsMs?: Record<string, number>;
+}
+export interface IParseNumberFormatBatchInput {
+    options: Array<INumberFormatOptions & {
+        id: number;
+    }>;
+    inputs: Array<{
+        input: string;
+        optionsId: number;
+    }>;
+}
+export interface IParsedNumberFormatValue {
+    number?: number;
+    text?: string;
+    boolean?: boolean;
+}
+export interface IParseNumberFormatBatchOutput {
+    values: Array<{
+        value: IParsedNumberFormatValue | null;
+        kind?: string;
+        inferredFormat?: string;
+        diagnostics: INumberFormatDiagnostic[];
+    }>;
+    timingsMs?: Record<string, number>;
+}
+export interface IObjectMatrixPrimitiveType<T> {
+    [key: number]: IObjectArrayPrimitiveType<T>;
+}
+export interface IObjectArrayPrimitiveType<T> {
+    [key: number]: T;
+}
+export interface IParseNumberFormatMatrixCell {
+    v?: unknown;
+}
+export interface IParseNumberFormatMatrixBatchInput {
+    option?: INumberFormatOptions;
+    matrix: IObjectMatrixPrimitiveType<IParseNumberFormatMatrixCell>;
+}
+export interface IParsedNumberFormatMatrixValue {
+    value: IParsedNumberFormatValue | null;
+    kind?: string;
+    inferredFormat?: string;
+    diagnostics: INumberFormatDiagnostic[];
+}
+export interface IParseNumberFormatMatrixBatchOutput {
+    values: IObjectMatrixPrimitiveType<IParsedNumberFormatMatrixValue>;
+    timingsMs?: Record<string, number>;
+}
+export interface IAnalyzeNumberFormatBatchInput {
+    formats: Array<{
+        id: number;
+        formatCode: string;
+    }>;
+}
+export interface INumberFormatAnalysis {
+    isDate?: boolean;
+    isTime?: boolean;
+    isPercent?: boolean;
+    isText?: boolean;
+    [key: string]: unknown;
+}
+export interface IAnalyzeNumberFormatBatchOutput {
+    values: Array<{
+        id: number;
+        analysis: INumberFormatAnalysis | null;
+        diagnostics: INumberFormatDiagnostic[];
+    }>;
+    timingsMs?: Record<string, number>;
+}
+/**
+ * Formats many values with the Rust number-format engine.
+ *
+ * The native binding is loaded lazily on the first call, so callers do not need
+ * to call `loadNativeBinding()` before using this API. Binding or transport
+ * failures reject the promise; per-item formatting issues are returned in each
+ * item's `diagnostics` array.
+ */
+export declare function formatNumberBatch(input: IFormatNumberBatchInput): Promise<IFormatNumberBatchOutput>;
+/**
+ * Parses many user-entered number-format strings with the Rust engine.
+ *
+ * This API is pure data-in/data-out and does not apply Univer mutations. The
+ * native binding is loaded lazily on the first call. Binding or transport
+ * failures reject the promise; per-item parse issues are returned in each
+ * item's `diagnostics` array.
+ */
+export declare function parseNumberFormatBatch(input: IParseNumberFormatBatchInput): Promise<IParseNumberFormatBatchOutput>;
+/**
+ * Parses string `v` values from a Univer-style sparse object matrix.
+ *
+ * Non-string values and empty strings are skipped and therefore omitted from
+ * the returned sparse matrix. Row and column coordinates are preserved.
+ */
+export declare function parseNumberFormatMatrixBatch(input: IParseNumberFormatMatrixBatchInput): Promise<IParseNumberFormatMatrixBatchOutput>;
+/**
+ * Analyzes many number-format patterns with the Rust engine.
+ *
+ * The native binding is loaded lazily on the first call, so callers can use the
+ * API directly as a Promise-returning utility. Binding or transport failures
+ * reject the promise; per-pattern analysis issues are returned in each item's
+ * `diagnostics` array.
+ */
+export declare function analyzeNumberFormatBatch(input: IAnalyzeNumberFormatBatchInput): Promise<IAnalyzeNumberFormatBatchOutput>;

package/lib/types/plugin.d.ts

@@ -0,0 +1,35 @@
+import type { Dependency } from '@univerjs/core';
+import type { IUniverEngineFormulaConfig } from '@univerjs/engine-formula';
+import { IConfigService, Injector } from '@univerjs/core';
+import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula';
+export interface IUniverRustFormulaEngineConfig extends IUniverEngineFormulaConfig {
+    /**
+     * Whether to use the Rust-backed formula engine.
+     * @default true
+     */
+    useRustEngine?: boolean;
+}
+/**
+ * Plugin that swaps the formula calculation core for a Rust implementation.
+ *
+ * Inherits from UniverFormulaEnginePlugin to keep all non-calculation services
+ * (FormulaDataModel, IFunctionService, controllers, etc.) intact.
+ *
+ * On the worker thread it overrides ICalculateFormulaService with
+ * RustCalculateFormulaService which delegates heavy computation to the Rust
+ * NAPI module.
+ */
+export declare class UniverRustFormulaEnginePlugin extends UniverProFormulaEnginePlugin {
+    protected readonly _config: Partial<IUniverRustFormulaEngineConfig>;
+    protected readonly _injector: Injector;
+    protected readonly _configService: IConfigService;
+    static packageName: string;
+    static version: string;
+    constructor(_config: Partial<IUniverRustFormulaEngineConfig> | undefined, _injector: Injector, _configService: IConfigService);
+    onReady(): void;
+    /**
+     * UniverProFormulaEnginePlugin invokes this hook before its single DI
+     * registration pass.
+     */
+    protected _extendFormulaExecutionDependencies(dependencies: Dependency[]): void;
+}

package/lib/types/regression/formula-array-followers.d.ts

@@ -0,0 +1,14 @@
+export interface FormulaArrayAnchor {
+    readonly endColumn: number;
+    readonly endRow: number;
+    readonly formula: string;
+    readonly startColumn: number;
+    readonly startRow: number;
+}
+export interface FormulaArrayFollowerComparable {
+    readonly syntheticArrayFollower?: boolean;
+}
+export declare function isIgnorableFormulaArrayFollowerExtra(value: FormulaArrayFollowerComparable | undefined): boolean;
+export declare function parseFormulaArrayAnchor(ref: string, formula: string): FormulaArrayAnchor | undefined;
+export declare function buildFormulaArrayAnchorRowIndex(anchors: readonly FormulaArrayAnchor[]): Map<number, readonly FormulaArrayAnchor[]>;
+export declare function findFormulaArrayFollower(anchors: readonly FormulaArrayAnchor[], row: number, column: number): FormulaArrayAnchor | undefined;

package/lib/types/regression/formula-value-normalization.d.ts

@@ -0,0 +1,2 @@
+import type { ICellData, Nullable } from '@univerjs/core';
+export declare function normalizeUniverFormulaValue(cell: Nullable<ICellData>): unknown;

package/lib/types/regression/formula-volatile-dependencies.d.ts

@@ -0,0 +1,7 @@
+export interface FormulaDependencyValue {
+    readonly sheetName: string;
+    readonly address: string;
+    readonly formula?: string;
+}
+export declare function buildVolatileRandomFormulaKeySet(values: readonly FormulaDependencyValue[]): Set<string>;
+export declare function formulaValueKey(value: FormulaDependencyValue): string;

package/lib/types/regression/real-univer-stage-timeouts.d.ts

@@ -0,0 +1,7 @@
+export interface CaseBoundedTimeoutInput {
+    readonly caseTimeoutMs: number;
+    readonly elapsedCaseMs: number;
+    readonly operationTimeoutMs: number;
+    readonly stageTimeoutMs?: number;
+}
+export declare function caseBoundedTimeoutMs(input: CaseBoundedTimeoutInput): number;

package/lib/types/regression/rust-only-artifact-cache.d.ts

@@ -0,0 +1,41 @@
+import type { RustOnlyExchangeBinaryProfile } from './rust-only-exchange-binary.js';
+import type { RustOnlyFormulaCalculationMode } from './rust-only-report.js';
+export type RustOnlyArtifactStaleReason = 'source-hash-changed' | 'rust-exchange-binary-path-changed' | 'rust-exchange-binary-profile-changed' | 'rust-exchange-binary-version-changed' | 'formula-mode-changed' | 'calc-chain-mode-changed' | 'runner-version-changed';
+export interface RustOnlyArtifactFingerprint {
+    readonly sourceSha256: string;
+    readonly rustExchangeBinaryPath: string;
+    readonly rustExchangeBinaryVersion: string;
+    readonly formulaCalculationMode: RustOnlyFormulaCalculationMode;
+    readonly calcChainMode?: 'off' | 'trusted';
+    readonly runnerVersion: string;
+}
+export interface EvaluateRustOnlyArtifactFreshnessOptions {
+    readonly expected: RustOnlyArtifactFingerprint;
+    readonly actual: RustOnlyArtifactFingerprint;
+}
+export interface RustOnlyArtifactFreshnessResult {
+    readonly fresh: boolean;
+    readonly staleReasons: readonly RustOnlyArtifactStaleReason[];
+}
+export interface ShouldReuseRustOnlyCaseReportOptions {
+    readonly report: {
+        readonly runnerVersion?: string;
+        readonly exchangeBinaryProfile?: RustOnlyExchangeBinaryProfile;
+        readonly formulaCalculationMode?: RustOnlyFormulaCalculationMode;
+        readonly calcChainMode?: 'off' | 'trusted';
+        readonly source?: {
+            readonly sha256?: string;
+        };
+    };
+    readonly expectedRunnerVersion: string;
+    readonly expectedExchangeBinaryProfile?: RustOnlyExchangeBinaryProfile;
+    readonly expectedFormulaCalculationMode: RustOnlyFormulaCalculationMode;
+    readonly expectedCalcChainMode?: 'off' | 'trusted';
+    readonly expectedSourceSha256: string;
+}
+export interface ShouldReuseRustOnlyCaseReportResult {
+    readonly reuse: boolean;
+    readonly staleReasons: readonly RustOnlyArtifactStaleReason[];
+}
+export declare function evaluateRustOnlyArtifactFreshness(options: EvaluateRustOnlyArtifactFreshnessOptions): RustOnlyArtifactFreshnessResult;
+export declare function shouldReuseRustOnlyCaseReport(options: ShouldReuseRustOnlyCaseReportOptions): ShouldReuseRustOnlyCaseReportResult;

package/lib/types/regression/rust-only-discovery.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_RUST_ONLY_SOURCE_DIRS: readonly ['C:\\Users\\wbfsa\\Downloads\\\u590D\u6742Excel\u6A21\u677F', 'C:\\Users\\wbfsa\\Downloads\\spreadsheetbench_verified_400\\spreadsheet'];
+export interface RustOnlyRegressionCase {
+    readonly caseId: string;
+    readonly sourcePath: string;
+    readonly sourceRoot: string;
+    readonly relativePath: string;
+    readonly reusedFromResume: boolean;
+}
+export interface DiscoverRustOnlyRegressionCasesOptions {
+    readonly sourceDirs?: readonly string[];
+    readonly explicitFiles?: readonly string[];
+    readonly only?: readonly string[];
+    readonly limit?: number;
+    readonly resumeCompletedCaseIds?: ReadonlySet<string>;
+    readonly listXlsxFiles?: (sourceRoot: string) => Promise<readonly string[]>;
+}
+export declare function discoverRustOnlyRegressionCases(options?: DiscoverRustOnlyRegressionCasesOptions): Promise<RustOnlyRegressionCase[]>;

package/lib/types/regression/rust-only-excel-com-oracle.d.ts

@@ -0,0 +1,57 @@
+import type { RustOnlyFormulaValueExtractorPort } from './rust-only-pipeline.js';
+export interface RustOnlyExcelComPort {
+    readonly openSaveWorkbook: (request: {
+        readonly inputPath: string;
+        readonly outputXlsxPath: string;
+        readonly forceFullRecalculation: boolean;
+    }) => Promise<void>;
+}
+export interface CreateRustOnlyExcelComOracleOptions {
+    readonly sourcePath: string;
+    readonly caseDir: string;
+    readonly excelCom: RustOnlyExcelComPort;
+    readonly formulaValueExtractor: RustOnlyFormulaValueExtractorPort;
+    readonly shortOutputDir?: string;
+    readonly now?: () => number;
+}
+export interface RustOnlyExcelComOracleSuccess {
+    readonly ok: true;
+    readonly excelComCalculatedXlsx: string;
+    readonly excelComFormulaValues: string;
+    readonly excelComOracleMs: number;
+    readonly formulaCacheExtractionMs: number;
+}
+export interface RustOnlyExcelComOracleFailure {
+    readonly ok: false;
+    readonly diagnostic: {
+        readonly classification: 'excel-com-unavailable';
+        readonly message: string;
+        readonly sourcePath: string;
+        readonly stage: 'excelComOracle';
+    };
+}
+export type RustOnlyExcelComOracleResult = RustOnlyExcelComOracleSuccess | RustOnlyExcelComOracleFailure;
+export interface ValidateRustOnlyExportedWorkbookOptions {
+    readonly exportedXlsxPath: string;
+    readonly caseDir: string;
+    readonly excelCom: RustOnlyExcelComPort;
+    readonly shortOutputDir?: string;
+    readonly now?: () => number;
+}
+export interface RustOnlyExportedWorkbookExcelComSuccess {
+    readonly ok: true;
+    readonly excelComOpenedXlsx: string;
+    readonly excelComOpenMs: number;
+}
+export interface RustOnlyExportedWorkbookExcelComFailure {
+    readonly ok: false;
+    readonly diagnostic: {
+        readonly classification: 'export' | 'excel-com-unavailable';
+        readonly message: string;
+        readonly exportedXlsxPath: string;
+        readonly stage: 'rustExportExcelComOpen';
+    };
+}
+export type RustOnlyExportedWorkbookExcelComResult = RustOnlyExportedWorkbookExcelComSuccess | RustOnlyExportedWorkbookExcelComFailure;
+export declare function createRustOnlyExcelComOracle(options: CreateRustOnlyExcelComOracleOptions): Promise<RustOnlyExcelComOracleResult>;
+export declare function validateRustOnlyExportedWorkbookWithExcelCom(options: ValidateRustOnlyExportedWorkbookOptions): Promise<RustOnlyExportedWorkbookExcelComResult>;

package/lib/types/regression/rust-only-excel-process-cleanup.d.ts

@@ -0,0 +1,3 @@
+export declare function listRustOnlyExcelAutomationProcessIds(): Promise<ReadonlySet<number>>;
+export declare function resolveNewRustOnlyExcelAutomationProcessIds(beforeIds: ReadonlySet<number>, afterIds: ReadonlySet<number>): number[];
+export declare function stopNewRustOnlyExcelAutomationProcesses(beforeIds: ReadonlySet<number>): Promise<void>;

package/lib/types/regression/rust-only-exchange-binary.d.ts

@@ -0,0 +1,15 @@
+export type RustOnlyExchangeBinaryProfile = 'release' | 'debug' | 'custom';
+export interface ResolveRustOnlyExchangeBinaryPathOptions {
+    readonly explicitPath?: string;
+    readonly envPath?: string;
+    readonly binaryProfile?: RustOnlyExchangeBinaryProfile;
+    readonly releasePath: string;
+    readonly debugPath: string;
+    readonly exists: (path: string) => boolean;
+}
+export interface RustOnlyExchangeBinarySelection {
+    readonly path: string;
+    readonly profile: RustOnlyExchangeBinaryProfile;
+}
+export declare function resolveRustOnlyExchangeBinaryPath(options: ResolveRustOnlyExchangeBinaryPathOptions): string;
+export declare function resolveRustOnlyExchangeBinarySelection(options: ResolveRustOnlyExchangeBinaryPathOptions): RustOnlyExchangeBinarySelection;

package/lib/types/regression/rust-only-failure-report.d.ts

@@ -0,0 +1,13 @@
+import type { RustOnlyMismatchClassification, RustOnlyMismatchGroup } from './rust-only-report.js';
+import type { RustOnlyActiveStage } from './rust-only-timeout.js';
+export interface CreateRustOnlyRunnerFailureMismatchGroupOptions {
+    readonly activeStage: RustOnlyActiveStage;
+    readonly message: string;
+}
+export declare function createRustOnlyRunnerFailureMismatchGroup(options: CreateRustOnlyRunnerFailureMismatchGroupOptions): RustOnlyMismatchGroup;
+export declare function isSkippableRustOnlyFailureClassification(classification: RustOnlyMismatchClassification): boolean;
+export declare function isRustOnlyRunnerTimeoutFailure(options: CreateRustOnlyRunnerFailureMismatchGroupOptions): boolean;
+export declare function createUnsupportedExcelSourceWorkbookMismatchGroup(reason: string): RustOnlyMismatchGroup;
+export declare function detectUnsupportedExcelGridLimits(parts: Record<string, string>): string | undefined;
+export declare function detectUnsupportedExcelSourceWorkbook(parts: Record<string, string>): string | undefined;
+export declare function detectUnsupportedExcelSourceOpenFailure(message: string): string | undefined;

package/lib/types/regression/rust-only-feature-extraction.d.ts

@@ -0,0 +1,19 @@
+import { type RustOnlyFeatureFamily } from './rust-only-report.js';
+type FeatureStatus = 'present' | 'not-present';
+export interface RustOnlyFeatureEvidence {
+    readonly status: FeatureStatus;
+    readonly count: number;
+    readonly modelPaths: readonly string[];
+}
+export type RustOnlyExtractedFeatureEvidence = Record<string, RustOnlyFeatureEvidence>;
+export interface RustOnlyNormalizedFeatureCoverage {
+    readonly status: FeatureStatus;
+    readonly evidenceArtifacts: readonly string[];
+    readonly comparisonArtifacts: readonly string[];
+    readonly comparisonRequired: boolean;
+    readonly failures: readonly string[];
+}
+export declare function extractRustOnlyWorkbookFeatureEvidence(workbook: unknown): RustOnlyExtractedFeatureEvidence;
+export declare function unwrapRustOnlyWorkbookSnapshot(workbook: unknown): Record<string, unknown>;
+export declare function normalizeRustOnlyFeatureCoverage(evidence: RustOnlyExtractedFeatureEvidence): Record<RustOnlyFeatureFamily, RustOnlyNormalizedFeatureCoverage>;
+export {};