@univerjs-pro/engine-formula 1.0.0-alpha.7 → 1.0.0-beta.0

package/lib/types/commands/commands/host-external-reference.command.d.ts

@@ -0,0 +1,43 @@
+import type { ICommand, IMutationInfo } from '@univerjs/core';
+import type { FormulaUnitType } from '@univerjs/engine-formula';
+import type { IHostExternalReference } from '../../models/host-external-reference.model';
+import type { ISetHostExternalReferenceMutationParams } from '../mutations/set-host-external-reference.mutation';
+export interface IUpsertHostExternalReferenceCommandParams {
+    /** Stable ID of the Host Unit that owns the formula and persisted mapping. */
+    unitId: string;
+    /**
+     * Public Source name used in formula text, without brackets or quotes.
+     * Positive integers are invalid because Excel reserves them as external-link slots.
+     */
+    qualifier: string;
+    /** Stable Source Unit ID used for Formula Reference Data requests. */
+    sourceUnitId: string;
+    /** Source business type; product External References support Sheet and Base. */
+    sourceUnitType: FormulaUnitType;
+    /** Existing Host-local reference ID when the caller needs to update that exact entry. */
+    referenceId?: string;
+}
+export interface IRemoveHostExternalReferenceCommandParams {
+    /** Stable ID of the Host Unit that owns the mapping. */
+    unitId: string;
+    /** Host-local reference ID to remove. Supply this or `qualifier`. */
+    referenceId?: string;
+    /** Public Source qualifier to remove. Supply this or `referenceId`. */
+    qualifier?: string;
+}
+export interface IUpsertHostExternalReferencesCommandParams {
+    /** Stable ID of the Host Unit that owns the formula and persisted mappings. */
+    unitId: string;
+    /** Complete set of Source bindings required by one authoring operation. */
+    references: readonly IHostExternalReference[];
+}
+export interface IHostExternalReferenceMutationPair {
+    redoMutation?: IMutationInfo<ISetHostExternalReferenceMutationParams>;
+    undoMutation?: IMutationInfo<ISetHostExternalReferenceMutationParams>;
+}
+export declare const UpsertHostExternalReferenceCommand: ICommand<IUpsertHostExternalReferenceCommandParams>;
+export declare const UpsertHostExternalReferencesCommand: ICommand<IUpsertHostExternalReferencesCommandParams>;
+export declare const RemoveHostExternalReferenceCommand: ICommand<IRemoveHostExternalReferenceCommandParams>;
+export declare function buildUpsertHostExternalReferenceMutations(accessor: Parameters<ICommand['handler']>[0], unitId: string | undefined, references: ReadonlyArray<IHostExternalReference & {
+    referenceId?: string;
+}>): IHostExternalReferenceMutationPair | null;

package/lib/types/commands/commands/persist-formula-last-values.command.d.ts

@@ -0,0 +1,6 @@
+import type { ICommand } from '@univerjs/core';
+export interface IPersistFormulaLastValuesCommandParams {
+    sessionId: number;
+}
+/** Internal derived-state command. It intentionally does not create an undo entry. */
+export declare const PersistFormulaLastValuesCommand: ICommand<IPersistFormulaLastValuesCommandParams>;

package/lib/types/commands/mutations/set-host-external-reference.mutation.d.ts

@@ -0,0 +1,7 @@
+import type { IMutation } from '@univerjs/core';
+import type { IHostExternalReferenceResource } from '../../models/host-external-reference.model';
+export interface ISetHostExternalReferenceMutationParams {
+    unitId: string;
+    resource: IHostExternalReferenceResource;
+}
+export declare const SetHostExternalReferenceMutation: IMutation<ISetHostExternalReferenceMutationParams>;

package/lib/types/controllers/formula-last-value-persistence.controller.d.ts

@@ -0,0 +1,9 @@
+import { Disposable, ICommandService } from '@univerjs/core';
+import { FormulaCalculationSessionService } from '@univerjs/engine-formula';
+import { FormulaLastValuePersistenceService } from '../services/formula-last-value-persistence.service';
+export declare class FormulaLastValuePersistenceController extends Disposable {
+    private readonly _commandService;
+    private readonly _sessionService;
+    private _lastPersistedSessionId;
+    constructor(_commandService: ICommandService, _sessionService: FormulaCalculationSessionService, _persistenceService: FormulaLastValuePersistenceService);
+}

package/lib/types/controllers/host-external-reference-active-dirty.controller.d.ts

@@ -0,0 +1,5 @@
+import { Disposable, IUniverInstanceService } from '@univerjs/core';
+import { IActiveDirtyManagerService, RegisterOtherFormulaService } from '@univerjs/engine-formula';
+export declare class HostExternalReferenceActiveDirtyController extends Disposable {
+    constructor(activeDirtyManagerService: IActiveDirtyManagerService, univerInstanceService: IUniverInstanceService, registerOtherFormulaService: RegisterOtherFormulaService);
+}

package/lib/types/controllers/host-external-reference-calculation.controller.d.ts

@@ -0,0 +1,9 @@
+import { Disposable, ICommandService } from '@univerjs/core';
+import { HostExternalReferenceModel } from '../models/host-external-reference.model';
+/**
+ * External Reference resources travel with each calculation payload, just like dirty data.
+ * They are not synchronized to the Worker through resource mutations.
+ */
+export declare class HostExternalReferenceCalculationController extends Disposable {
+    constructor(commandService: ICommandService, model: HostExternalReferenceModel);
+}

package/lib/types/controllers/host-external-reference.controller.d.ts

@@ -0,0 +1,5 @@
+import { Disposable, ICommandService, IResourceManagerService } from '@univerjs/core';
+import { HostExternalReferenceModel } from '../models/host-external-reference.model';
+export declare class HostExternalReferenceController extends Disposable {
+    constructor(commandService: ICommandService, resourceManagerService: IResourceManagerService, model: HostExternalReferenceModel);
+}

package/lib/types/engine/dependency-engine/dependency-engine.d.ts

@@ -1,4 +1,5 @@
-import type { CalcNodeIndex, CellId, DepList, ExternalNodeId, ICalcNodeDeps, ICalcNodeRef, ICalculationOrderResult, ICompressedSharedFormulaGroup, IDecodedCell, IDecodedFeatureCalculationId, IDecodedOtherFormulaId, IDependencyEngineOptions, IDynamicResolver, IRefRange, ISetNodeResult } from './types';
+import type { IUnitRange } from '@univerjs/core';
+import type { CalcNodeIndex, CellId, DepList, ExternalNodeId, ICalcNodeDeps, ICalcNodeRef, ICalculationOrderResult, ICompressedSharedFormulaGroup, IDecodedCell, IDecodedFeatureCalculationId, IDecodedOtherFormulaId, IDependencyEngineOptions, IDynamicResolver, ISetNodeResult } from './types';
 import { CellCodec } from './cell-codec';
 import { RangeIndex } from './range-index';
 /**
@@ -98,7 +99,7 @@ export declare class DependencyEngine {
     }): ISetNodeResult;
     setNewCellFormulaDeps(cell: CellId, deps: ICalcNodeDeps): ISetNodeResult;
     setNewCellFormulaNodeOnly(cell: CellId): ISetNodeResult;
-    setNewCellFormulaNodeOnlyRange(unitId: string, sheetId: string, range: IRefRange['range'], skip?: {
+    setNewCellFormulaNodeOnlyRange(unitId: string, sheetId: string, range: IUnitRange['range'], skip?: {
         row: number;
         col: number;
     }): CalcNodeIndex[];
@@ -210,14 +211,14 @@ export declare class DependencyEngine {
     /**
      * Marks dependents of a changed range dirty without expanding all cells.
      */
-    markRangeChanged(rangeInput: IRefRange, options?: {
+    markRangeChanged(rangeInput: IUnitRange, options?: {
         includeFormulaCells?: boolean;
         coalesce?: boolean;
     }): void;
     /**
      * Batch range-change entry point for paste, fill, clear, and import.
      */
-    markRangesChanged(rangeInputs: IRefRange[], options?: {
+    markRangesChanged(rangeInputs: IUnitRange[], options?: {
         includeFormulaCells?: boolean;
         coalesce?: boolean;
     }): void;
@@ -244,7 +245,7 @@ export declare class DependencyEngine {
     getDirtyNodeIndices(): CalcNodeIndex[];
     getDirtyNodes(): ICalcNodeRef[];
     forEachDependentByCell(cell: CellId, cb: (node: ICalcNodeRef, nodeIndex: CalcNodeIndex) => void): void;
-    forEachDependentByRange(range: IRefRange, cb: (node: ICalcNodeRef, nodeIndex: CalcNodeIndex) => void): void;
+    forEachDependentByRange(range: IUnitRange, cb: (node: ICalcNodeRef, nodeIndex: CalcNodeIndex) => void): void;
     forEachDependentByNode(node: ICalcNodeRef, cb: (dependentNode: ICalcNodeRef, dependentIndex: CalcNodeIndex) => void): void;
     forEachDependentByIndex(nodeIndex: CalcNodeIndex, cb: (dependentNode: ICalcNodeRef, dependentIndex: CalcNodeIndex) => void): void;
     /**

package/lib/types/engine/dependency-engine/formula-cell-index.d.ts

@@ -1,5 +1,6 @@
+import type { IUnitRange } from '@univerjs/core';
 import type { CellCodec } from './cell-codec';
-import type { CalcNodeIndex, ExternalNodeId, IRefRange } from './types';
+import type { CalcNodeIndex, ExternalNodeId } from './types';
 /**
  * Spatial index for active `CellFormula` nodes.
  *
@@ -16,7 +17,7 @@ export declare class FormulaCellIndex {
     addFormulaCell(formulaCell: number, nodeIndex: CalcNodeIndex): void;
     addFormulaCellByPosition(sheetKey: number, row: number, col: number, nodeIndex: CalcNodeIndex): void;
     removeFormulaCell(formulaCell: number, nodeIndex: CalcNodeIndex): void;
-    forEachFormulaInRange(rangeInput: IRefRange, cb: (nodeIndex: CalcNodeIndex) => boolean | void): boolean;
+    forEachFormulaInRange(rangeInput: IUnitRange, cb: (nodeIndex: CalcNodeIndex) => boolean | void): boolean;
     private _scanRows;
     private _scanCols;
     private _scanRowBucket;

package/lib/types/engine/dependency-engine/helpers.d.ts

@@ -1,4 +1,5 @@
-import type { CalcNodeIndex, DepList, ExternalNodeId, ICalcNodeRef, IDecodedCell, IRefRange } from './types';
+import type { IUnitRange } from '@univerjs/core';
+import type { CalcNodeIndex, DepList, ExternalNodeId, ICalcNodeRef, IDecodedCell } from './types';
 /**
  * Shared low-level helpers for dependency storage.
  *
@@ -7,10 +8,10 @@ import type { CalcNodeIndex, DepList, ExternalNodeId, ICalcNodeRef, IDecodedCell
  * propagation.
  */
 export declare function assertCellNodeId(id: ExternalNodeId): asserts id is number;
-export declare function normalizeRange(r: IRefRange): IRefRange;
-export declare function rangeRowCount(r: IRefRange): number;
-export declare function rangeColCount(r: IRefRange): number;
-export declare function rangeContainsCell(r: IRefRange, d: IDecodedCell): boolean;
+export declare function normalizeRange(r: IUnitRange): IUnitRange;
+export declare function rangeRowCount(r: IUnitRange): number;
+export declare function rangeColCount(r: IUnitRange): number;
+export declare function rangeContainsCell(r: IUnitRange, d: IDecodedCell): boolean;
 export declare function uniqueSortedNumbers(values: readonly number[] | undefined): number[];
 export declare function pushToArrayMap<K>(map: Map<K, number[]>, key: K, value: number): void;
 export declare function removeFromArraySwap(arr: number[], value: number): boolean;
@@ -29,4 +30,4 @@ export declare function uniqueNodeRefs(values: readonly ICalcNodeRef[] | undefin
  * We do not merge L-shaped areas into a larger rectangle because that would
  * create too many false-positive dependents.
  */
-export declare function coalesceAlignedRanges(rangeInputs: IRefRange[]): IRefRange[];
+export declare function coalesceAlignedRanges(rangeInputs: IUnitRange[]): IUnitRange[];

package/lib/types/engine/dependency-engine/point-subscription-index.d.ts

@@ -1,5 +1,6 @@
+import type { IUnitRange } from '@univerjs/core';
 import type { CellCodec } from './cell-codec';
-import type { CellId, IRefRange } from './types';
+import type { CellId } from './types';
 /**
  * Index of direct precedent cells subscribed by formula dependencies.
  *
@@ -15,7 +16,7 @@ export declare class PointSubscriptionIndex {
     constructor(_codec: CellCodec, _pointScanCellLimit: number);
     add(cell: CellId): void;
     remove(cell: CellId): void;
-    forEachCellInRange(rangeInput: IRefRange, cb: (cell: CellId) => void): void;
+    forEachCellInRange(rangeInput: IUnitRange, cb: (cell: CellId) => void): void;
     private _isSmallArea;
     private _scanRows;
     private _scanCols;

package/lib/types/engine/dependency-engine/range-index.d.ts

@@ -1,5 +1,6 @@
+import type { IUnitRange } from '@univerjs/core';
 import type { CellCodec } from './cell-codec';
-import type { CalcNodeIndex, IRefRange } from './types';
+import type { CalcNodeIndex } from './types';
 /**
  * Reverse index from precedent ranges to dependent calculation nodes.
  *
@@ -37,19 +38,19 @@ export declare class RangeIndex {
     private readonly _nodeToWholeRowKeys;
     constructor(_codec: CellCodec, initialCapacity: number, _maxIndexedSpan: number);
     reserveCapacity(minCapacity: number): void;
-    addRange(nodeIndex: CalcNodeIndex, rangeInput: IRefRange): void;
+    addRange(nodeIndex: CalcNodeIndex, rangeInput: IUnitRange): void;
     removeNode(nodeIndex: CalcNodeIndex): void;
     /**
      * Finds range-dependent nodes when one cell changes.
      */
     forEachPoint(unitId: string, sheetId: string, row: number, col: number, cb: (nodeIndex: CalcNodeIndex) => void): void;
-    forEachRangeIntersecting(changedInput: IRefRange, cb: (nodeIndex: CalcNodeIndex) => void): void;
+    forEachRangeIntersecting(changedInput: IUnitRange, cb: (nodeIndex: CalcNodeIndex) => void): void;
     /**
      * Finds range-dependent nodes intersecting a batch of changed ranges.
      *
      * A single range epoch deduplicates normal range IDs across the batch.
      */
-    forEachRangesIntersecting(changedInputs: IRefRange[], cb: (nodeIndex: CalcNodeIndex) => void): void;
+    forEachRangesIntersecting(changedInputs: IUnitRange[], cb: (nodeIndex: CalcNodeIndex) => void): void;
     private _allocRangeId;
     private _ensureRangeCapacity;
     private _setRangeMeta;

package/lib/types/engine/dependency-engine/types.d.ts

@@ -56,7 +56,6 @@ export interface IDecodedOtherFormulaId {
 /**
  * Unit-aware rectangular range.
  */
-export type IRefRange = IUnitRange;
 /**
  * Dependency declaration for a calculation node.
  */
@@ -73,7 +72,7 @@ export interface ICalcNodeDeps {
      *
      * Formula cells inside these ranges naturally become precedent nodes.
      */
-    ranges?: IRefRange[];
+    ranges?: IUnitRange[];
     /**
      * Explicit precedent calculation nodes.
      *
@@ -107,7 +106,7 @@ export type ICompressedSharedFormulaPattern = {
 };
 export interface ICompressedSharedFormulaGroup {
     groupId: string;
-    fillRange: IRefRange;
+    fillRange: IUnitRange;
     patterns: ICompressedSharedFormulaPattern[];
     memberNodeIndices?: CalcNodeIndex[];
 }
@@ -118,7 +117,7 @@ export interface IDynamicDependency {
 export interface IDynamicResolveResult {
     signature: string;
     cells?: CellId[];
-    ranges?: IRefRange[];
+    ranges?: IUnitRange[];
     nodes?: ICalcNodeRef[];
     traceCells?: CellId[];
     status?: DynamicResolveStatus;
@@ -203,19 +202,3 @@ export declare enum RangeKind {
 /**
  * Backward-compatible type aliases for older imports.
  */
-export type CalcNodeRef = ICalcNodeRef;
-export type DecodedCell = IDecodedCell;
-export type DecodedFeatureCalculationId = IDecodedFeatureCalculationId;
-export type DecodedOtherFormulaId = IDecodedOtherFormulaId;
-export type DynamicDependency = IDynamicDependency;
-export type DynamicResolver = IDynamicResolver;
-export type DynamicResolveResult = IDynamicResolveResult;
-export type CompressedSharedFormulaGroup = ICompressedSharedFormulaGroup;
-export type CompressedSharedFormulaPattern = ICompressedSharedFormulaPattern;
-export type RefRange = IRefRange;
-export type CalcNodeDeps = ICalcNodeDeps;
-export type DependencyEngineOptions = IDependencyEngineOptions;
-export type SetNodeResult = ISetNodeResult;
-export type CalculationOrderResult = ICalculationOrderResult;
-export type CalculationPlanItem = ICalculationPlanItem;
-export type CalculationOrderTree = ICalculationOrderTree;

package/lib/types/engine/formula-dependency.d.ts

@@ -1,6 +1,6 @@
 import type { IUnitRange, Nullable } from '@univerjs/core';
 import type { BaseAstNode, IFormulaDataItem, IFormulaDependencyTree, IFormulaDependencyTreeJson, IUnitData } from '@univerjs/engine-formula';
-import type { DynamicResolver } from './dependency-engine/types';
+import type { IDynamicResolver } from './dependency-engine/types';
 import type { ISharedFormulaCompressionMetrics } from './shared-formula-group-analyzer';
 import { FormulaDependencyGenerator, FormulaDependencyTree, FormulaDependencyTreeType } from '@univerjs/engine-formula';
 export interface IFormulaCalculationTree {
@@ -40,7 +40,7 @@ export declare class FormulaDependencyProGenerator extends FormulaDependencyGene
     getCalculationOrder(): import("./dependency-engine/types").ICalculationOrderResult;
     getSharedFormulaCompressionMetrics(): ISharedFormulaCompressionMetrics;
     hasDynamicDepsByIndex(nodeIndex: number): boolean;
-    refreshDynamicDepsByIndex(nodeIndex: number, resolver: DynamicResolver): boolean;
+    refreshDynamicDepsByIndex(nodeIndex: number, resolver: IDynamicResolver): boolean;
     hasUncalculatedDirtyPrecedentByIndex(nodeIndex: number, calculatedNodeIndices: ReadonlySet<number>): boolean;
     getAllDependencyJson(): Promise<IFormulaDependencyTreeJson[]>;
     generatePro(isCalculateTreeModel?: boolean): Promise<{

package/lib/types/facade/f-enum.d.ts

@@ -24,7 +24,10 @@ export interface IFFormulaReferenceEnumMixin {
      *         range: { startRow: 0, endRow: 9, startColumn: 0, endColumn: 1 },
      *     },
      * });
-     * shape.setFormula(`=SUM(${reference})`);
+     * shape.setFormula({
+     *     formula: `=SUM(${reference})`,
+     *     externalReferences: [], // Required; empty only because Source and Host are the same Unit.
+     * });
      * ```
      *
      * @example Select a Base table-column target
@@ -45,7 +48,14 @@ export interface IFFormulaReferenceEnumMixin {
      *             columnName: 'Amount',
      *         },
      *     });
-     *     shape.setFormula(`=SUM(${reference})`);
+     *     shape.setFormula({
+     *         formula: `=SUM(${reference})`,
+     *         externalReferences: [{
+     *             qualifier: baseUnit.formulaQualifier,
+     *             sourceUnitId: baseUnit.unitId,
+     *             sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_BASE,
+     *         }],
+     *     });
      * }
      *
      * setSalesBaseFormula({

package/lib/types/facade/f-formula.d.ts

@@ -1,87 +1,137 @@
-import type { IBuildFormulaReferenceOptions } from '@univerjs-pro/engine-formula';
+import type { IBuildFormulaReferenceOptions, IRemoveHostExternalReferenceCommandParams, IUpsertHostExternalReferenceCommandParams } from '@univerjs-pro/engine-formula';
 import { FFormula } from '@univerjs/engine-formula/facade';
 /** Formula-reference APIs contributed by Univer Pro. */
 export interface IFFormulaReferenceMixin {
     /**
-     * Builds a Sheet-range or structured-table reference fragment.
+     * Builds one Sheet-range or Base-table reference fragment for Facade authoring.
      *
-     * This is a pure text helper. It does not add a leading `=`, mutate a Shape,
-     * discover or bind external resources, load a Unit, or start formula calculation.
+     * Use this method when the caller knows both the Host Unit ID and the stable
+     * Source Unit ID. For a cross-Unit Source, it synchronously persists the
+     * Host-owned External Reference before returning. For a Host-local Source, it
+     * only returns local reference syntax. An unchanged binding is an idempotent
+     * no-op.
+     *
+     * The returned value is a reference fragment, not a complete formula: it has no
+     * leading `=` and does not start calculation. The method does not load the Source
+     * Unit. Formula calculation later reads the Source through its stable `unitId`.
+     *
+     * Authoring rule:
+     * - Cell formula: build the reference, then pass the returned fragment to
+     *   `range.setFormula(...)`; the binding has already been persisted.
+     * - Formula Shape: build the reference, then pass the same Source identity again
+     *   in `shape.setFormula({ formula, externalReferences })`. The duplicate binding
+     *   write is a no-op and the Shape setter remains the final consistency boundary.
+     * - Hand-written or imported formula text: call `upsertExternalReference()` before
+     *   writing the formula because the engine never guesses `unitId` from a name.
      *
      * @param {IBuildFormulaReferenceOptions} options Host, caller-provided source Unit, and reference target.
      * @returns {string} A formula reference fragment.
      *
-     * @example Build a cross-unit Sheet range from an externally supplied Unit
+     * @example Write a cross-Unit Sheet reference to a cell
      * ```ts
-     * import type { IFormulaReferenceUnit } from '@univerjs-pro/engine-formula';
-     *
-     * function setSalesFormula(salesUnit: IFormulaReferenceUnit) {
-     *     const board = univerAPI.getActiveBoard();
-     *     if (!board) {
-     *         throw new Error('No active board.');
-     *     }
-     *
-     *     const shape = board.getShape('formula-shape-1');
-     *     if (!shape?.isFormulaShape()) {
-     *         throw new Error('Formula Shape not found.');
-     *     }
-     *
-     *     const reference = univerAPI.getFormula().buildReference({
-     *         hostUnitId: board.getId(),
-     *         unit: salesUnit,
-     *         target: {
-     *             kind: univerAPI.Enum.FormulaReferenceType.SHEET_RANGE,
-     *             sheetName: 'Sales',
-     *             range: { startRow: 1, endRow: 9, startColumn: 1, endColumn: 1 },
-     *         },
-     *     });
-     *     shape.setFormula(`=SUM(${reference})`);
-     * }
-     *
-     * setSalesFormula({
+     * const workbook = univerAPI.getActiveWorkbook();
+     * if (!workbook) throw new Error('No active workbook.');
+     *
+     * const salesWorkbook = {
      *     unitId: 'sales-workbook',
      *     formulaQualifier: 'Sales Workbook',
+     * };
+     * const reference = univerAPI.getFormula().buildReference({
+     *     hostUnitId: workbook.getId(),
+     *     unit: salesWorkbook,
+     *     target: {
+     *         kind: univerAPI.Enum.FormulaReferenceType.SHEET_RANGE,
+     *         sheetName: 'Sales',
+     *         range: { startRow: 1, endRow: 9, startColumn: 1, endColumn: 1 },
+     *     },
      * });
+     * workbook.getActiveSheet().getRange('C1').setFormula(`=SUM(${reference})`);
      * ```
      *
-     * @example Build a cross-unit Base column from an externally supplied Unit
+     * @example Build a Host-local Sheet reference without creating a binding
      * ```ts
-     * import type { IFormulaReferenceUnit } from '@univerjs-pro/engine-formula';
-     *
-     * function setSalesFormula(salesUnit: IFormulaReferenceUnit) {
-     *     const document = univerAPI.getActiveDocument();
-     *     if (!document) {
-     *         throw new Error('No active document.');
-     *     }
-     *
-     *     const shape = document.getShape('formula-shape-1');
-     *     if (!shape?.isFormulaShape()) {
-     *         throw new Error('Formula Shape not found.');
-     *     }
-     *
-     *     const reference = univerAPI.getFormula().buildReference({
-     *         hostUnitId: document.getId(),
-     *         unit: salesUnit,
-     *         target: {
-     *             kind: univerAPI.Enum.FormulaReferenceType.TABLE_COLUMN,
-     *             tableName: 'SalesTable',
-     *             columnName: 'Amount',
-     *         },
-     *     });
-     *     shape.setFormula(`=SUM(${reference})`);
-     * }
-     *
-     * setSalesFormula({
-     *     unitId: 'sales-base',
-     *     formulaQualifier: 'Sales Base',
+     * const workbook = univerAPI.getActiveWorkbook();
+     * if (!workbook) throw new Error('No active workbook.');
+     *
+     * const reference = univerAPI.getFormula().buildReference({
+     *     hostUnitId: workbook.getId(),
+     *     unit: {
+     *         unitId: workbook.getId(),
+     *         formulaQualifier: workbook.getName(),
+     *     },
+     *     target: {
+     *         kind: univerAPI.Enum.FormulaReferenceType.SHEET_RANGE,
+     *         sheetName: 'Sales',
+     *         range: { startRow: 1, endRow: 9, startColumn: 1, endColumn: 1 },
+     *     },
      * });
+     * // reference contains local syntax such as Sales!B2:B10.
      * ```
      */
     buildReference(options: IBuildFormulaReferenceOptions): string;
+    /**
+     * Creates or rebinds one Host-owned External Reference.
+     *
+     * Use this explicit API when formula text is hand-written, imported, or generated
+     * in a batch without `buildReference()`. Call it before writing the formula.
+     * `qualifier` is the public name used inside the formula, without brackets or
+     * quotes; `sourceUnitId` is the stable identity used for data requests.
+     *
+     * Repeating the same mapping succeeds without mutation, dirty data, or undo.
+     *
+     * @param {IUpsertHostExternalReferenceCommandParams} options Host and stable Source binding.
+     * @returns {boolean} `true` when the binding already matches or was persisted.
+     *
+     * @example Bind a hand-written cross-workbook formula before writing it
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * if (!workbook) throw new Error('No active workbook.');
+     *
+     * const formula = univerAPI.getFormula();
+     * const bound = formula.upsertExternalReference({
+     *     unitId: workbook.getId(),
+     *     qualifier: 'Sales Workbook',
+     *     sourceUnitId: 'sales-workbook',
+     *     sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET,
+     * });
+     * if (!bound) throw new Error('Could not bind the Sales Workbook source.');
+     *
+     * workbook
+     *     .getActiveSheet()
+     *     .getRange('C1')
+     *     .setFormula("=SUM('[Sales Workbook]Sales'!B2:B10)");
+     * ```
+     */
+    upsertExternalReference(options: IUpsertHostExternalReferenceCommandParams): boolean;
+    /**
+     * Removes one Host-owned External Reference by `referenceId` or `qualifier`.
+     *
+     * Removing a binding does not rewrite or delete formulas. It marks only the Host
+     * dirty; the next Host calculation resolves the remaining formula under the
+     * normal External Reference rules.
+     *
+     * @param {IRemoveHostExternalReferenceCommandParams} options Host plus reference ID or qualifier.
+     * @returns {boolean} `true` when an existing binding was removed.
+     *
+     * @example Remove a Host binding by qualifier
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * if (!workbook) throw new Error('No active workbook.');
+     *
+     * const removed = univerAPI.getFormula().removeExternalReference({
+     *     unitId: workbook.getId(),
+     *     qualifier: 'Sales Workbook',
+     * });
+     * if (!removed) throw new Error('External Reference was not found.');
+     * ```
+     */
+    removeExternalReference(options: IRemoveHostExternalReferenceCommandParams): boolean;
 }
 /** @ignore */
 export declare class FFormulaReferenceMixin extends FFormula implements IFFormulaReferenceMixin {
     buildReference(options: IBuildFormulaReferenceOptions): string;
+    upsertExternalReference(options: IUpsertHostExternalReferenceCommandParams): boolean;
+    removeExternalReference(options: IRemoveHostExternalReferenceCommandParams): boolean;
 }
 declare module '@univerjs/engine-formula/facade' {
     interface FFormula extends IFFormulaReferenceMixin {

package/lib/types/index.d.ts

@@ -1,3 +1,7 @@
+export { buildUpsertHostExternalReferenceMutations, RemoveHostExternalReferenceCommand, UpsertHostExternalReferenceCommand, UpsertHostExternalReferencesCommand, } from './commands/commands/host-external-reference.command';
+export type { IHostExternalReferenceMutationPair, IRemoveHostExternalReferenceCommandParams, IUpsertHostExternalReferenceCommandParams, IUpsertHostExternalReferencesCommandParams, } from './commands/commands/host-external-reference.command';
+export { PersistFormulaLastValuesCommand } from './commands/commands/persist-formula-last-values.command';
+export type { IPersistFormulaLastValuesCommandParams } from './commands/commands/persist-formula-last-values.command';
 export { ExternalReferenceDataProvidersController } from './controllers/external-reference-data-providers.controller';
 export { ExternalReferenceRenameController } from './controllers/external-reference-rename.controller';
 export { ExternalReferenceResourceController } from './controllers/external-reference-resource.controller';
@@ -6,16 +10,27 @@ export { ExternalReferenceOverlayModel } from './models/external-reference-overl
 export type { IExternalOverlayCellState } from './models/external-reference-overlay.model';
 export { createEmptyExternalReferenceResource, createExternalSyntheticUnitId, EXTERNAL_REFERENCE_SCHEMA_VERSION, ExternalReferenceModel, SHEET_EXTERNAL_DATA_PLUGIN, } from './models/external-reference.model';
 export type { ExternalReferenceBindingResult, IExternalReferenceCachedCell, IExternalReferenceCachedSheet, IExternalReferenceCoverage, IExternalReferenceLink, IExternalReferenceResource, IExternalReferenceTable, IExternalReferenceTableColumn, } from './models/external-reference.model';
+export type { IFormulaLastValue } from './models/formula-last-value';
+export { HOST_EXTERNAL_REFERENCE_SCHEMA_VERSION, HostExternalReferenceModel, normalizeHostExternalReferenceQualifier, UNIVER_EXTERNAL_REFERENCE_PLUGIN, } from './models/host-external-reference.model';
+export type { HostExternalReferenceBindingResult, IHostExternalReference, IHostExternalReferenceResource, } from './models/host-external-reference.model';
 export { UniverProFormulaEnginePlugin } from './plugin';
 export { ExternalCacheReferenceDataProvider } from './services/external-cache-reference-data.provider';
 export { ExternalReferencePrefetchPlanner } from './services/external-reference-prefetch-planner';
 export { ExternalReferencePrefetchService } from './services/external-reference-prefetch.service';
 export type { IExternalReferencePrefetchLimits, IExternalReferencePrefetchResult, } from './services/external-reference-prefetch.service';
 export { ExternalFormulaUnitReferenceResolver } from './services/external-unit-reference-resolver.service';
+export { FormulaCacheEligibilityService } from './services/formula-cache-eligibility.service';
+export type { FormulaCacheIneligibleReason, IFormulaCacheEligibility, } from './services/formula-cache-eligibility.service';
+export { FormulaLastValuePersistenceService } from './services/formula-last-value-persistence.service';
+export type { IFormulaLastValuePersistenceProvider } from './services/formula-last-value-persistence.service';
 export { createUnavailableReferenceDataResponse, FormulaReferenceDataProviderRegistry, IFormulaReferenceDataProviderRegistry, IFormulaReferenceDataService, } from './services/formula-reference-data.service';
-export type { FormulaReferenceDataFreshness, FormulaReferenceDataSource, IFormulaReferenceDataCell, IFormulaReferenceDataProvider, IFormulaReferenceDataRangeRequest, IFormulaReferenceDataRequest, IFormulaReferenceDataResponse, IFormulaReferenceDataSheet, } from './services/formula-reference-data.service';
+export type { FormulaReferenceDataFreshness, FormulaReferenceDataSource, IFormulaReferenceDataCell, IFormulaReferenceDataProvider, IFormulaReferenceDataRangeRequest, IFormulaReferenceDataRequest, IFormulaReferenceDataResponse, IFormulaReferenceDataSheet, IFormulaReferenceDataTable, } from './services/formula-reference-data.service';
 export { buildFormulaReference, FormulaReferenceType, } from './services/formula-reference-unit.service';
 export type { FormulaReferenceTarget, IBuildFormulaReferenceOptions, IFormulaReferenceUnit, IFormulaSheetRangeReferenceTarget, IFormulaTableColumnReferenceTarget, } from './services/formula-reference-unit.service';
+export { getFormulaResultCell, getScalarFormulaResultCell, resolveFormulaResultPresentation, toFormulaLastValue, } from './services/formula-result-presentation';
+export type { IFormulaResultPresentation, IResolveFormulaResultPresentationOptions, } from './services/formula-result-presentation';
+export { collectFormulaExternalReferenceQualifiers, resolveHostFormulaExternalReferences, } from './services/host-formula-binding.service';
+export type { HostFormulaExternalReferenceResolution, } from './services/host-formula-binding.service';
 export { MainFormulaReferenceDataService } from './services/main-formula-reference-data.service';
 export { RemoveSuperTableMutation, SetFormulaCalculationResultMutation, SetFormulaCalculationStartMutation, SetSuperTableMutation, SetTriggerFormulaCalculationStartMutation, } from '@univerjs/engine-formula';
 export type { ISetFormulaCalculationResultMutation, ISetFormulaCalculationStartMutation, ISuperTable, } from '@univerjs/engine-formula';

package/lib/types/models/formula-last-value.d.ts

@@ -0,0 +1,14 @@
+import type { CellValueType } from '@univerjs/core';
+/**
+ * Minimal snapshot projection of the last successful scalar Formula result.
+ *
+ * This value is Host content. It intentionally excludes formula text, source bindings,
+ * display text, color, timestamps, calculation hashes, and all Source ACL metadata.
+ * It inherits only the Host object's persistence and read-permission boundary.
+ */
+export interface IFormulaLastValue {
+    v: string | number | boolean | null;
+    t?: CellValueType;
+    /** Number format inherited from the successful result cell. */
+    pattern?: string;
+}