Workbook runtime intent API

Use @bilig/workbook when your product already owns calculation but needs a stable way to describe workbook intent before anything mutates state.

The package is for model authors, adapter authors, MCP servers, and tool hosts that need plan data, requirements, command receipts, checks, schemas, and readback proof. It does not calculate formulas or own WorkPaper state.

Use @bilig/workpaper when Bilig should run the workbook. Use @bilig/workbook when another runtime should run the workbook but still needs a proof-bound contract.

Install

npm install @bilig/workbook

Use It When

• a tool host needs to inspect workbook intent before a runtime mutates state;
• a framework wants plain JSON plan data instead of callback closures;
• a runtime adapter needs to prove planId, revision, applied ops, resolved refs, command receipts, and check results;
• a product wants workbook operations to cross process or service boundaries;
• the calculation engine is not Bilig, but the handoff still needs proof.

Do Not Use It When

• Bilig should own workbook state and formula recalculation; use @bilig/workpaper;
• the only problem is stale formulas in an .xlsx file; use @bilig/xlsx-formula-recalc, @bilig/sheetjs-formula-recalc, or @bilig/exceljs-formula-recalc;
• the workflow depends on desktop Excel features such as macros, pivots, charts, add-ins, or exact UI layout.

Proof Contract

An integration should be able to answer these questions without asking a human to inspect a spreadsheet UI:

1. Which model and action were selected?
2. Which refs did selectors bind?
3. Which commands and low-level ops were planned?
4. Did prepareWorkbookAction produce valid plan data?
5. Did the plan survive JSON transport?
6. Which runtime capabilities are required?
7. Did apply proof match preview proof?
8. Are command receipts bound to the planned digests?
9. Which checks passed, and what evidence proved them?

runWorkbookPlan(planData, adapter, { strict: true }) fails closed unless the adapter returns the required proof. That is the main distinction from a thin “call this function and trust the result” wrapper.

Minimal Shape

import {
  defineModel,
  describeRunResult,
  formula,
  prepareWorkbookAction,
  runWorkbookPlan,
} from "@bilig/workbook";

const model = defineModel({
  name: "named-range-formula",
  find(workbook) {
    return {
      input: workbook.findName("input"),
      factor: workbook.findName("factor"),
      result: workbook.findName("result"),
    };
  },
  checks({ refs, workbook }) {
    return [workbook.check.exists(refs.result), workbook.check.noFormulaErrors(refs.result)];
  },
  actions: {
    calculate({ refs, workbook }) {
      const expected = formula.multiply(refs.input, refs.factor);
      workbook.writeFormula(refs.result, expected);
      workbook.check.formulaEquals(refs.result, expected);
    },
  },
});

const prepared = prepareWorkbookAction(model, "calculate");
if (prepared.status === "failed") {
  throw new Error(prepared.errors[0]?.message ?? "workbook plan failed");
}

const result = await runWorkbookPlan(prepared.planData, adapter, { strict: true });
console.log(describeRunResult(result));

Package Boundary

The older workbook-agent-intent-api.html URL remains as a compatibility alias for existing links.