Formula workbooks for Node services and tool integrations

@bilig/workpaper is for one specific job: keep workbook-shaped business logic as cells and formulas, but run it from a Node service, queue worker, serverless route, test, or tool integration.

The runtime boundary is a WorkPaper: write known input cells, recalculate, read known output cells, and persist the workbook as JSON. No browser grid, spreadsheet account, screenshot automation, or hosted sheet is required.

The evaluator path

Run the quote approval proof from an empty directory:

mkdir bilig-quote-approval
cd bilig-quote-approval
npm init -y
npm pkg set type=module
npm install @bilig/workpaper
npm install -D tsx typescript @types/node
curl -fsSLo quote-approval-api.ts \
  https://raw.githubusercontent.com/proompteng/bilig/main/examples/serverless-workpaper-api/quote-approval-api.ts
npx tsx quote-approval-api.ts

Expected shape:

{
  "route": "Quote approval WorkPaper API",
  "before": {
    "netRevenue": 43200,
    "grossMargin": 0.2963,
    "decision": "review"
  },
  "edit": {
    "after": {
      "netRevenue": 45600,
      "grossMargin": 0.3333,
      "decision": "approved"
    },
    "checks": {
      "decisionChanged": true,
      "formulasPersisted": true,
      "inputPersisted": true,
      "restoredMatchesAfter": true
    }
  },
  "verified": true
}

The important check is restoredMatchesAfter: true: the service wrote inputs into cells, formulas recalculated, the WorkPaper serialized to JSON, and a restored WorkPaper produced the same decision.

Why this is not just a formula parser

A backend evaluator usually needs more than =A1+B1:

• typed business input maps to stable cell addresses
• dependent formulas update after each write
• output values are read back from the workbook runtime
• formulas survive persistence
• restored state can be tested without Excel, Google Sheets, or a browser

That shape fits pricing rules, quote approval, payout checks, budget guardrails, import validation, and tool integrations where the user wants a durable result rather than a plausible screenshot.

Agent tool boundary

For agents, expose small tools:

• list_sheets
• read_cell
• read_range
• set_cell_contents
• set_cell_contents_and_readback
• get_cell_display_value
• export_workpaper_document

The published MCP server can run against a local WorkPaper JSON file:

npm exec --package @bilig/workpaper@latest -- \
  bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable

With --writable, set_cell_contents persists the updated WorkPaper JSON back to the file. The point is not to let an agent "look" at a spreadsheet. The point is to let the agent make a workbook edit and prove the recalculated value it used.

Where other tools may be better

Use HyperFormula first when you need a mature, broad formula engine with a large function surface and the WorkPaper persistence shape is not the differentiator.

Use SheetJS or ExcelJS first when the primary job is reading, writing, styling, or generating spreadsheet files. Bilig's XLSX paths are secondary to the WorkPaper runtime boundary.

Use Google Sheets API first when a shared hosted spreadsheet, permissions, comments, and human collaboration are the actual product requirement.

Use @bilig/workpaper when a Node service or agent tool owns the workbook state and needs formula readback, persistence, and restore proof.

Evidence and limits

The useful proof is workbook behavior: edit an input, recalculate dependent formulas, persist the WorkPaper document, restore it, and read back the same formula result. Saved XLSX files are a separate contract and should be checked with the compatibility report and Excel oracle fixtures before production use.

This page does not claim full Excel compatibility. It does not claim chart, macro, formatting, collaborative editing, or complete XLSX fidelity. Start with the compatibility page before importing real workbooks. Do not treat WorkPaper as a universal spreadsheet-engine replacement.

Start here

• Quote approval WorkPaper API proof
• Try @bilig/workpaper in Node
• MCP spreadsheet tool server
• Where bilig is not Excel-compatible yet

Repository and release notes: https://github.com/proompteng/bilig.

If it does not match yet, open a concrete implementation-gap discussion: https://github.com/proompteng/bilig/discussions/new?category=general. The most useful feedback names the workflow, blocker type, proof already tried, and the smallest example, benchmark, or compatibility note that would unblock a real trial.