bilig-workpaper 0.160.2 → 0.164.0

package/AGENTS.md

@@ -38,6 +38,7 @@ npm exec --yes --package bilig-workpaper@latest -- bilig-evaluate --door agent-m
 npm exec --package bilig-workpaper@latest -- bilig-mcp-challenge --json
 npm exec --package bilig-workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable
 npm exec --package bilig-workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx
+pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
 
 For Node or TypeScript, import bilig-workpaper directly. Check the edit by
 reading the relevant range, writing one small input or formula, reading the
@@ -94,6 +95,14 @@ WorkPaper. Without `--workpaper --writable`, edits stay in memory; add a
 WorkPaper JSON path only when the task needs persisted file state. It does not
 certify Excel compatibility.
 
+For a maintained transcript that starts from a real XLSX, call
+`analyze_workbook_risk`, then prove `Inputs!B3` -> `Summary!B3` readback
+and export with:
+
+```sh
+pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
+```
+
 Claude Desktop users can skip manual JSON config by installing the released
 MCPB bundle:
 
@@ -106,9 +115,9 @@ Use `bilig-workpaper` when the workbook logic belongs in a service, queue
 worker, test, or route:
 
 ```ts
-import { WorkPaper, exportWorkPaperDocument, serializeWorkPaperDocument } from 'bilig-workpaper'
+import { buildA1WorkPaper } from 'bilig-workpaper'
 
-const workbook = WorkPaper.buildFromSheets({
+const book = buildA1WorkPaper({
   Inputs: [
     ['Metric', 'Value'],
     ['Customers', 20],
@@ -120,18 +129,19 @@ const workbook = WorkPaper.buildFromSheets({
   ],
 })
 
-const inputs = workbook.getSheetId('Inputs')
-const summary = workbook.getSheetId('Summary')
-if (inputs === undefined || summary === undefined) {
-  throw new Error('Workbook is missing required sheets')
-}
-
-workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32)
+const proof = book.editAndReadback('Inputs!B2', 32, {
+  readbackRange: 'Summary!B2',
+})
 
-const revenue = workbook.getCellDisplayValue({ sheet: summary, row: 1, col: 1 })
-const saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }))
+console.log({
+  editedCell: proof.editedCell,
+  after: proof.afterReadback.displayValues,
+  afterRestore: proof.restoredReadback.displayValues,
+  persistedDocumentBytes: proof.persistedDocumentBytes,
+  verified: proof.verified,
+})
 
-console.log({ revenue, savedBytes: saved.length })
+book.dispose()
 ```
 
 ## Verification shortcuts
@@ -146,6 +156,7 @@ npm exec --yes --package bilig-workpaper@latest -- bilig-evaluate --door agent-m
 npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json
 npm exec --package bilig-workpaper@latest -- bilig-agent-challenge --json
 npm exec --package bilig-workpaper@latest -- bilig-mcp-challenge --json
+pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
 ```
 
 `bilig-agent-challenge` checks the direct WorkPaper API loop.

package/README.md

@@ -13,9 +13,9 @@ npm install bilig-workpaper
 ## Use A WorkPaper In Node
 
 ```ts
-import { WorkPaper } from 'bilig-workpaper'
+import { buildA1WorkPaper } from 'bilig-workpaper'
 
-const workbook = WorkPaper.buildFromSheets({
+const book = buildA1WorkPaper({
   Inputs: [
     ['Metric', 'Value'],
     ['Units', 40],
@@ -27,20 +27,19 @@ const workbook = WorkPaper.buildFromSheets({
   ],
 })
 
-const inputs = workbook.getSheetId('Inputs')
-const summary = workbook.getSheetId('Summary')
-
-if (inputs === undefined || summary === undefined) {
-  throw new Error('Expected sheets to exist')
-}
-
-workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 48)
-workbook.setCellContents({ sheet: inputs, row: 2, col: 1 }, 1500)
+const proof = book.editAndReadback('Inputs!B2', 48, {
+  readbackRange: 'Summary!B2',
+})
 
-console.log(workbook.getCellValue({ sheet: summary, row: 1, col: 1 }))
-console.log(workbook.exportSnapshot())
+console.log({
+  editedCell: proof.editedCell,
+  after: proof.afterReadback.displayValues,
+  afterRestore: proof.restoredReadback.displayValues,
+  persistedDocumentBytes: proof.persistedDocumentBytes,
+  verified: proof.verified,
+})
 
-workbook.dispose()
+book.dispose()
 ```
 
 ## XLSX Import And Export

package/SKILL.md

@@ -119,6 +119,12 @@ WorkPaper. Without `--workpaper --writable`, edits stay in memory; add a
 WorkPaper JSON path only when the task needs persisted file state. It does not
 certify Excel compatibility.
 
+For a maintained XLSX preflight transcript, run
+`pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight`.
+It requires `analyze_workbook_risk`, `set_cell_contents_and_readback`,
+`export_workpaper_document`, `Inputs!B3`, `Summary!B3`, `60000 -> 96000`,
+and `verified: true`.
+
 After a write, always read the dependent output cell and export the WorkPaper
 document. If the listed tool set includes `set_cell_contents_and_readback`,
 prefer it for stateless clients because the edit and dependent readback happen
@@ -142,9 +148,9 @@ stdio command when the workflow must persist a project WorkPaper JSON file.
 Use `bilig-workpaper` directly when workbook logic belongs in a service, queue worker, test, or route:
 
 ```ts
-import { WorkPaper, exportWorkPaperDocument, serializeWorkPaperDocument } from 'bilig-workpaper'
+import { buildA1WorkPaper } from 'bilig-workpaper'
 
-const workbook = WorkPaper.buildFromSheets({
+const book = buildA1WorkPaper({
   Inputs: [
     ['Metric', 'Value'],
     ['Customers', 20],
@@ -156,17 +162,19 @@ const workbook = WorkPaper.buildFromSheets({
   ],
 })
 
-const inputs = workbook.getSheetId('Inputs')
-const summary = workbook.getSheetId('Summary')
-if (inputs === undefined || summary === undefined) {
-  throw new Error('Workbook is missing required sheets')
-}
+const proof = book.editAndReadback('Inputs!B2', 32, {
+  readbackRange: 'Summary!B2',
+})
 
-workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32)
-const revenue = workbook.getCellDisplayValue({ sheet: summary, row: 1, col: 1 })
-const saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }))
+console.log({
+  editedCell: proof.editedCell,
+  after: proof.afterReadback.displayValues,
+  afterRestore: proof.restoredReadback.displayValues,
+  persistedDocumentBytes: proof.persistedDocumentBytes,
+  verified: proof.verified,
+})
 
-console.log({ revenue, savedBytes: saved.length })
+book.dispose()
 ```
 
 ## XLSX Formula Clinic
@@ -204,6 +212,7 @@ If any readback step fails, report the blocker instead of claiming the workbook
 - MCP server guide: https://proompteng.github.io/bilig/mcp-workpaper-tool-server.html
 - OpenHands MCP setup: https://proompteng.github.io/bilig/openhands-workpaper-mcp.html
 - OpenCode MCP setup: https://proompteng.github.io/bilig/opencode-workpaper-mcp.html
+- Goose MCP recipe: https://proompteng.github.io/bilig/goose-workpaper-mcp.html
 - Open WebUI tool setup: https://proompteng.github.io/bilig/open-webui-workpaper-mcp.html
 - LobeHub MCP setup: https://proompteng.github.io/bilig/lobehub-workpaper-mcp.html
 - AnythingLLM MCP setup: https://proompteng.github.io/bilig/anythingllm-workpaper-mcp.html

package/bin/bilig-evaluate.js

@@ -1,4 +1,2 @@
 #!/usr/bin/env node
-const { runBiligEvaluatorCli } = await import('@bilig/xlsx-formula-recalc/evaluator')
-
-process.exitCode = runBiligEvaluatorCli(process.argv.slice(2))
+await import('../dist/evaluator-bin.js')

package/dist/a1.d.ts

@@ -0,0 +1,118 @@
+import { WorkPaper } from '@bilig/headless';
+import type { PersistedWorkPaperDocument, RawCellContent, WorkPaperChange, WorkPaperConfig, WorkPaperFormulaDiagnostic, WorkPaperSheets } from '@bilig/headless';
+type WorkPaperInstance = ReturnType<typeof WorkPaper.buildFromSheets>;
+export type A1CellInput = RawCellContent;
+export type A1CellValue = ReturnType<WorkPaperInstance['getCellValue']>;
+export interface A1WorkPaperOptions {
+    readonly defaultSheetName?: string;
+    readonly writableSheets?: readonly string[];
+    readonly limitations?: readonly string[];
+}
+export interface A1CellRead {
+    readonly address: string;
+    readonly value: A1CellValue;
+    readonly serialized: RawCellContent;
+    readonly formula: string | null;
+    readonly displayValue: string;
+    readonly formulaDiagnostics: readonly WorkPaperFormulaDiagnostic[];
+}
+export interface A1RangeRead {
+    readonly range: string;
+    readonly values: A1CellValue[][];
+    readonly serialized: RawCellContent[][];
+    readonly displayValues: string[][];
+    readonly formulaDiagnostics: readonly WorkPaperFormulaDiagnostic[];
+    readonly cells: readonly (readonly A1CellRead[])[];
+}
+export interface A1SetCellAndReadbackOptions {
+    readonly readbackRange: string;
+    readonly requireReadbackChange?: boolean;
+    readonly includeConfig?: boolean;
+    readonly includeSerializedDocument?: boolean;
+    readonly limitations?: readonly string[];
+}
+export interface A1SetCellAndReadbackProof {
+    readonly editedCell: string;
+    readonly readbackRange: string;
+    readonly before: A1CellRead;
+    readonly after: A1CellRead;
+    readonly beforeReadback: A1RangeRead;
+    readonly afterReadback: A1RangeRead;
+    readonly restoredReadback: A1RangeRead;
+    readonly persistedDocumentBytes: number;
+    readonly checks: {
+        readonly readbackChanged: boolean;
+        readonly computedReadbackChanged: boolean;
+        readonly editedFormulaReadbackChanged: boolean;
+        readonly readbackIncludesEditedCell: boolean;
+        readonly readbackContainsOnlyEditedCell: boolean;
+        readonly restoredReadbackMatchesAfter: boolean;
+        readonly blockingFormulaDiagnosticCount: number;
+        readonly formulaDiagnostics: readonly WorkPaperFormulaDiagnostic[];
+        readonly previousSerialized: RawCellContent;
+        readonly newSerialized: RawCellContent;
+    };
+    readonly verified: boolean;
+    readonly limitations: readonly string[];
+    readonly changes: readonly WorkPaperChange[];
+    readonly serializedDocument?: string;
+}
+export interface A1EditManyAndReadbackProof {
+    readonly editedCells: readonly string[];
+    readonly readbackRange: string;
+    readonly before: Readonly<Record<string, A1CellRead>>;
+    readonly after: Readonly<Record<string, A1CellRead>>;
+    readonly beforeReadback: A1RangeRead;
+    readonly afterReadback: A1RangeRead;
+    readonly restoredReadback: A1RangeRead;
+    readonly persistedDocumentBytes: number;
+    readonly checks: {
+        readonly readbackChanged: boolean;
+        readonly computedReadbackChanged: boolean;
+        readonly editedFormulaReadbackChanged: boolean;
+        readonly readbackIncludesEditedCells: boolean;
+        readonly readbackContainsOnlyEditedCells: boolean;
+        readonly restoredReadbackMatchesAfter: boolean;
+        readonly blockingFormulaDiagnosticCount: number;
+        readonly formulaDiagnostics: readonly WorkPaperFormulaDiagnostic[];
+        readonly previousSerialized: Readonly<Record<string, RawCellContent>>;
+        readonly newSerialized: Readonly<Record<string, RawCellContent>>;
+    };
+    readonly verified: boolean;
+    readonly limitations: readonly string[];
+    readonly changes: readonly WorkPaperChange[];
+    readonly serializedDocument?: string;
+}
+export interface A1WorkPaper {
+    readonly workpaper: WorkPaperInstance;
+    readCell(address: string): A1CellRead;
+    get(address: string): A1CellValue;
+    display(address: string): string;
+    formula(address: string): string | null;
+    readRange(range: string): A1RangeRead;
+    range(range: string): A1CellValue[][];
+    setCell(address: string, value: A1CellInput): WorkPaperChange[];
+    set(address: string, value: A1CellInput): WorkPaperChange[];
+    readMany(addresses: readonly string[]): Readonly<Record<string, A1CellRead>>;
+    setCells(edits: Readonly<Record<string, A1CellInput>>): WorkPaperChange[];
+    setMany(edits: Readonly<Record<string, A1CellInput>>): WorkPaperChange[];
+    validateFormula(formula: string): boolean;
+    setCellAndReadback(address: string, value: A1CellInput, options: A1SetCellAndReadbackOptions): A1SetCellAndReadbackProof;
+    editAndReadback(address: string, value: A1CellInput, options: A1SetCellAndReadbackOptions): A1SetCellAndReadbackProof;
+    editManyAndReadback(edits: Readonly<Record<string, A1CellInput>>, options: A1SetCellAndReadbackOptions): A1EditManyAndReadbackProof;
+    exportDocument(options?: {
+        readonly includeConfig?: boolean;
+    }): PersistedWorkPaperDocument;
+    serialize(options?: {
+        readonly includeConfig?: boolean;
+    }): string;
+    saveJson(options?: {
+        readonly includeConfig?: boolean;
+    }): string;
+    restoreJson(input: string | PersistedWorkPaperDocument): A1WorkPaper;
+    dispose(): void;
+}
+export declare function createA1WorkPaper(workpaper: WorkPaperInstance, options?: A1WorkPaperOptions): A1WorkPaper;
+export declare function buildA1WorkPaper(sheets: WorkPaperSheets, config?: WorkPaperConfig, options?: A1WorkPaperOptions): A1WorkPaper;
+export declare function restoreA1WorkPaper(input: string | PersistedWorkPaperDocument, options?: A1WorkPaperOptions): A1WorkPaper;
+export {};

package/dist/a1.js

@@ -0,0 +1,361 @@
+import { WorkPaper, createWorkPaperFromDocument, exportWorkPaperDocument, parseWorkPaperDocument, serializeWorkPaperDocument, } from '@bilig/headless';
+export function createA1WorkPaper(workpaper, options = {}) {
+    return new A1WorkPaperFacade(workpaper, options);
+}
+export function buildA1WorkPaper(sheets, config, options = {}) {
+    return createA1WorkPaper(WorkPaper.buildFromSheets(sheets, config), options);
+}
+export function restoreA1WorkPaper(input, options = {}) {
+    const document = typeof input === 'string' ? parseWorkPaperDocument(input) : input;
+    return createA1WorkPaper(createWorkPaperFromDocument(document), options);
+}
+class A1WorkPaperFacade {
+    workpaper;
+    defaultSheetName;
+    writableSheets;
+    limitations;
+    constructor(workpaper, options) {
+        this.workpaper = workpaper;
+        this.defaultSheetName = options.defaultSheetName;
+        this.writableSheets = options.writableSheets;
+        this.limitations = options.limitations ?? [];
+    }
+    readCell(address) {
+        const parsed = this.requireCellAddress(address);
+        return this.readParsedCell(parsed);
+    }
+    get(address) {
+        return this.readCell(address).value;
+    }
+    display(address) {
+        return this.readCell(address).displayValue;
+    }
+    formula(address) {
+        return this.readCell(address).formula;
+    }
+    readRange(range) {
+        const parsed = this.requireRange(range);
+        const cells = this.readRangeCells(parsed);
+        return {
+            range: this.formatRange(parsed),
+            values: cells.map((row) => row.map((cell) => cell.value)),
+            serialized: cells.map((row) => row.map((cell) => cell.serialized)),
+            displayValues: cells.map((row) => row.map((cell) => cell.displayValue)),
+            formulaDiagnostics: cells.flatMap((row) => row.flatMap((cell) => cell.formulaDiagnostics)),
+            cells,
+        };
+    }
+    range(range) {
+        return this.readRange(range).values;
+    }
+    setCell(address, value) {
+        const parsed = this.requireCellAddress(address);
+        this.assertWritable(parsed);
+        this.assertFormulaCanParse(value, parsed);
+        return this.workpaper.setCellContents(parsed, value);
+    }
+    set(address, value) {
+        return this.setCell(address, value);
+    }
+    readMany(addresses) {
+        const reads = {};
+        for (const address of addresses) {
+            const read = this.readCell(address);
+            reads[read.address] = read;
+        }
+        return reads;
+    }
+    setCells(edits) {
+        const prepared = this.prepareEdits(edits);
+        return this.applyPreparedEdits(prepared);
+    }
+    setMany(edits) {
+        return this.setCells(edits);
+    }
+    validateFormula(formula) {
+        return this.workpaper.validateFormula(formula);
+    }
+    setCellAndReadback(address, value, options) {
+        const proof = this.editManyAndReadback({ [address]: value }, options);
+        const editedCell = proof.editedCells[0];
+        if (editedCell === undefined) {
+            throw new Error('Expected one edited WorkPaper cell');
+        }
+        const before = proof.before[editedCell];
+        const after = proof.after[editedCell];
+        if (before === undefined || after === undefined) {
+            throw new Error(`Expected proof reads for ${editedCell}`);
+        }
+        return {
+            editedCell,
+            readbackRange: proof.readbackRange,
+            before,
+            after,
+            beforeReadback: proof.beforeReadback,
+            afterReadback: proof.afterReadback,
+            restoredReadback: proof.restoredReadback,
+            persistedDocumentBytes: proof.persistedDocumentBytes,
+            checks: {
+                readbackChanged: proof.checks.readbackChanged,
+                computedReadbackChanged: proof.checks.computedReadbackChanged,
+                editedFormulaReadbackChanged: proof.checks.editedFormulaReadbackChanged,
+                readbackIncludesEditedCell: proof.checks.readbackIncludesEditedCells,
+                readbackContainsOnlyEditedCell: proof.checks.readbackContainsOnlyEditedCells,
+                restoredReadbackMatchesAfter: proof.checks.restoredReadbackMatchesAfter,
+                blockingFormulaDiagnosticCount: proof.checks.blockingFormulaDiagnosticCount,
+                formulaDiagnostics: proof.checks.formulaDiagnostics,
+                previousSerialized: before.serialized,
+                newSerialized: after.serialized,
+            },
+            verified: proof.verified,
+            limitations: proof.limitations,
+            changes: proof.changes,
+            ...(options.includeSerializedDocument && proof.serializedDocument !== undefined
+                ? { serializedDocument: proof.serializedDocument }
+                : {}),
+        };
+    }
+    editAndReadback(address, value, options) {
+        return this.setCellAndReadback(address, value, options);
+    }
+    editManyAndReadback(edits, options) {
+        const requireReadbackChange = options.requireReadbackChange ?? true;
+        const includeConfig = options.includeConfig ?? true;
+        const prepared = this.prepareEdits(edits);
+        const editedCells = prepared.map((edit) => edit.address);
+        const editedCellSet = new Set(editedCells);
+        const before = this.readPreparedCells(prepared);
+        const beforeReadback = this.readRange(options.readbackRange);
+        const changes = this.applyPreparedEdits(prepared);
+        const after = this.readPreparedCells(prepared);
+        const afterReadback = this.readRange(options.readbackRange);
+        const serializedDocument = this.serialize({ includeConfig });
+        const restored = restoreA1WorkPaper(serializedDocument, this.facadeOptions());
+        try {
+            const restoredReadback = restored.readRange(options.readbackRange);
+            const persistedDocumentBytes = new TextEncoder().encode(serializedDocument).byteLength;
+            const readbackChanged = !sameJson(rangeComparison(beforeReadback), rangeComparison(afterReadback));
+            const computedReadbackChanged = !sameJson(rangeComparisonExcludingEditedCells(beforeReadback, editedCellSet), rangeComparisonExcludingEditedCells(afterReadback, editedCellSet));
+            const editedFormulaReadbackChanged = readbackChanged && readbackEditedFormulaCells(afterReadback, editedCellSet).length > 0;
+            const readbackAddresses = rangeCellAddresses(afterReadback);
+            const readbackIncludesEditedCells = readbackAddresses.some((readbackAddress) => editedCellSet.has(readbackAddress));
+            const readbackContainsOnlyEditedCells = readbackAddresses.length > 0 && readbackAddresses.every((readbackAddress) => editedCellSet.has(readbackAddress));
+            const restoredReadbackMatchesAfter = sameJson(rangeComparison(afterReadback), rangeComparison(restoredReadback));
+            const formulaDiagnostics = afterReadback.formulaDiagnostics;
+            const blockingFormulaDiagnosticCount = formulaDiagnostics.filter((diagnostic) => diagnostic.severity === 'error').length;
+            const meaningfulReadbackChanged = computedReadbackChanged || editedFormulaReadbackChanged;
+            return {
+                editedCells,
+                readbackRange: afterReadback.range,
+                before,
+                after,
+                beforeReadback,
+                afterReadback,
+                restoredReadback,
+                persistedDocumentBytes,
+                checks: {
+                    readbackChanged,
+                    computedReadbackChanged,
+                    editedFormulaReadbackChanged,
+                    readbackIncludesEditedCells,
+                    readbackContainsOnlyEditedCells,
+                    restoredReadbackMatchesAfter,
+                    blockingFormulaDiagnosticCount,
+                    formulaDiagnostics,
+                    previousSerialized: serializedByAddress(before),
+                    newSerialized: serializedByAddress(after),
+                },
+                verified: persistedDocumentBytes > 0 &&
+                    restoredReadbackMatchesAfter &&
+                    blockingFormulaDiagnosticCount === 0 &&
+                    (!requireReadbackChange || meaningfulReadbackChanged),
+                limitations: [...this.limitations, ...(options.limitations ?? [])],
+                changes,
+                ...(options.includeSerializedDocument ? { serializedDocument } : {}),
+            };
+        }
+        finally {
+            restored.dispose();
+        }
+    }
+    exportDocument(options = {}) {
+        return exportWorkPaperDocument(this.workpaper, options);
+    }
+    serialize(options = {}) {
+        return serializeWorkPaperDocument(this.exportDocument(options));
+    }
+    saveJson(options = {}) {
+        return this.serialize(options);
+    }
+    restoreJson(input) {
+        return restoreA1WorkPaper(input, this.facadeOptions());
+    }
+    dispose() {
+        this.workpaper.dispose();
+    }
+    facadeOptions() {
+        return {
+            ...(this.defaultSheetName !== undefined ? { defaultSheetName: this.defaultSheetName } : {}),
+            ...(this.writableSheets !== undefined ? { writableSheets: this.writableSheets } : {}),
+            limitations: this.limitations,
+        };
+    }
+    readParsedCell(address) {
+        const formula = this.workpaper.getCellFormula(address);
+        return {
+            address: this.formatCell(address),
+            value: this.workpaper.getCellValue(address),
+            serialized: this.workpaper.getCellSerialized(address),
+            formula: formula ?? null,
+            displayValue: this.workpaper.getCellDisplayValue(address),
+            formulaDiagnostics: this.workpaper.getCellFormulaDiagnostics(address),
+        };
+    }
+    readRangeCells(range) {
+        const rows = [];
+        for (let row = range.start.row; row <= range.end.row; row += 1) {
+            const cells = [];
+            for (let col = range.start.col; col <= range.end.col; col += 1) {
+                cells.push(this.readParsedCell({ sheet: range.start.sheet, row, col }));
+            }
+            rows.push(cells);
+        }
+        return rows;
+    }
+    prepareEdits(edits) {
+        const prepared = [];
+        const seen = new Set();
+        for (const [address, value] of Object.entries(edits)) {
+            const parsed = this.requireCellAddress(address);
+            const formatted = this.formatCell(parsed);
+            if (seen.has(formatted)) {
+                throw new Error(`Duplicate WorkPaper edit target: ${formatted}`);
+            }
+            this.assertWritable(parsed);
+            this.assertFormulaCanParse(value, parsed);
+            seen.add(formatted);
+            prepared.push({ address: formatted, parsed, value });
+        }
+        if (prepared.length === 0) {
+            throw new Error('At least one WorkPaper edit is required');
+        }
+        return prepared;
+    }
+    applyPreparedEdits(edits) {
+        return this.workpaper.transaction(() => {
+            for (const edit of edits) {
+                this.workpaper.setCellContents(edit.parsed, edit.value);
+            }
+        });
+    }
+    readPreparedCells(edits) {
+        const reads = {};
+        for (const edit of edits) {
+            reads[edit.address] = this.readParsedCell(edit.parsed);
+        }
+        return reads;
+    }
+    requireCellAddress(address) {
+        this.assertDefaultSheetAllowsUnqualifiedAddress(address, 'cell address');
+        const parsed = this.workpaper.simpleCellAddressFromString(address, this.defaultSheetId());
+        if (parsed === undefined) {
+            throw new Error(`Invalid WorkPaper cell address: ${address}`);
+        }
+        return parsed;
+    }
+    requireRange(range) {
+        this.assertDefaultSheetAllowsUnqualifiedAddress(range, 'range');
+        const parsedRange = this.workpaper.simpleCellRangeFromString(range, this.defaultSheetId());
+        if (parsedRange !== undefined) {
+            return parsedRange;
+        }
+        const parsedCell = this.workpaper.simpleCellAddressFromString(range, this.defaultSheetId());
+        if (parsedCell !== undefined) {
+            return {
+                start: parsedCell,
+                end: parsedCell,
+            };
+        }
+        throw new Error(`Invalid WorkPaper range: ${range}`);
+    }
+    assertDefaultSheetAllowsUnqualifiedAddress(value, kind) {
+        if (this.defaultSheetName === undefined && !value.includes('!')) {
+            throw new Error(`Sheet-qualified WorkPaper ${kind} required: ${value}`);
+        }
+    }
+    defaultSheetId() {
+        if (this.defaultSheetName === undefined) {
+            return undefined;
+        }
+        const sheetId = this.workpaper.getSheetId(this.defaultSheetName);
+        if (sheetId === undefined) {
+            throw new Error(`Expected default sheet "${this.defaultSheetName}" to exist`);
+        }
+        return sheetId;
+    }
+    assertWritable(address) {
+        if (this.writableSheets === undefined) {
+            return;
+        }
+        const sheetName = this.workpaper.getSheetName(address.sheet);
+        if (sheetName === undefined || !this.writableSheets.includes(sheetName)) {
+            throw new Error(`Sheet "${sheetName ?? address.sheet}" is not writable`);
+        }
+    }
+    assertFormulaCanParse(value, address) {
+        if (typeof value !== 'string' || !value.startsWith('=')) {
+            return;
+        }
+        if (!this.workpaper.validateFormula(value)) {
+            throw new Error(`Invalid WorkPaper formula for ${this.formatCell(address)}: ${value}`);
+        }
+    }
+    formatCell(address) {
+        return this.workpaper.simpleCellAddressToString(address, {
+            includeSheetName: true,
+        });
+    }
+    formatRange(range) {
+        if (sameAddress(range.start, range.end)) {
+            return this.formatCell(range.start);
+        }
+        return this.workpaper.simpleCellRangeToString(range, {
+            includeSheetName: true,
+        });
+    }
+}
+function rangeComparison(read) {
+    return read.cells.map((row) => row.map(cellComparison));
+}
+function rangeComparisonExcludingEditedCells(read, editedCells) {
+    return read.cells.map((row) => row.filter((cell) => !editedCells.has(cell.address)).map(cellComparison)).filter((row) => row.length > 0);
+}
+function readbackEditedFormulaCells(read, editedCells) {
+    return read.cells.flatMap((row) => row.filter((cell) => editedCells.has(cell.address) && cell.formula !== null));
+}
+function rangeCellAddresses(read) {
+    return read.cells.flatMap((row) => row.map((cell) => cell.address));
+}
+function cellComparison(read) {
+    return {
+        address: read.address,
+        displayValue: read.displayValue,
+        formula: read.formula,
+        serialized: read.serialized,
+        value: read.value,
+    };
+}
+function serializedByAddress(reads) {
+    const serialized = {};
+    for (const [address, read] of Object.entries(reads)) {
+        serialized[address] = read.serialized;
+    }
+    return serialized;
+}
+function sameJson(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function sameAddress(left, right) {
+    return left.sheet === right.sheet && left.row === right.row && left.col === right.col;
+}
+//# sourceMappingURL=a1.js.map