@bilig/workbook 0.55.0 → 0.58.0

package/README.md

@@ -1,364 +1,209 @@
 # @bilig/workbook
 
-Agent-first workbook model API and transport-neutral workbook operation language for bilig.
+Generic workbook intent for agents and runtimes.
 
 Build `@bilig/workbook` so an agent would love using it: simple, generic,
 predictable, inspectable, verifiable, and never dependent on hardcoded business
 models or human spreadsheet UI assumptions.
 
-Use this package when a consumer needs to describe workbook work without taking a
-dependency on the engine, app server, transport, or replica-state implementation.
-
-The public surface stays generic:
-
-- `defineModel`
-- `buildWorkbookActionPlan`
-- `planWorkbookAction`
-- `inspectModel`
-- `collectWorkbookRefs`
-- `findTable`, `findColumn`, `findRange`, `findName`, `findRows`
-- `find`
-- `workbookRefKinds`
-- `isWorkbookRefKind`
-- `isWorkbookRef`
-- `workbookRowOperators`
-- `isWorkbookRowOperator`
-- `check`
-- `describeModel`
-- `describeRef`
-- `describePlan`
-- `describePlanResult`
-- `describeRunResult`
-- `describeRuntimeRequirements`
-- `verifyPlan`
-- `verifyModel`
-- `runWorkbookPlan`
-- `runWorkbookAction`
-- `verifyWorkbookReadbacks`
-- `normalizeWorkbookActionInputDescription`
-- `workbookActionInputDescriptionKinds`
-- `isWorkbookActionInputDescriptionKind`
-- `isWorkbookActionInputDescription`
-- `isWorkbookActionInput`
-- `builtInWorkbookCheckKinds`
-- `isBuiltInWorkbookCheckKind`
-- `workbookRunErrorCodes`
-- `isWorkbookRunErrorCode`
-- `formula`
-- `workbook.addOp(op, { target?, message? })` inside model actions
-- `WorkbookModel`
-- `WorkbookAction`
-- `WorkbookActionConfig`
-- `WorkbookActionDefinition`
-- `WorkbookActionContext`
-- `WorkbookCheckContext`
-- `WorkbookFindWorkbook`
-- `WorkbookCheckWorkbook`
-- `WorkbookActionWorkbook`
-- `WorkbookModelWorkbook`
-- `WorkbookFindNamespace`
-- `WorkbookRef`
-- `WorkbookRefKind`
-- `WorkbookRangeRef`
-- `WorkbookNameRef`
-- `WorkbookTableRef`
-- `WorkbookColumnRef`
-- `WorkbookRowsRef`
-- `WorkbookRowOperator`
-- `WorkbookActionInput`
-- `WorkbookActionInputDescription`
-- `WorkbookActionInputDescriptionKind`
-- `WorkbookActionInspection`
-- `WorkbookAddOpOptions`
-- `WorkbookActionPlanResult`
-- `WorkbookModelDescription`
-- `WorkbookRefDescription`
-- `WorkbookActionPlanDescription`
-- `WorkbookActionPlanResultDescription`
-- `WorkbookRunResultDescription`
-- `WorkbookUndoRefDescription`
-- `WorkbookRuntimeRequirements`
-- `WorkbookRuntimeRequirement`
-- `WorkbookRuntimeCapability`
-- `WorkbookPlanVerification`
-- `WorkbookPlanIssue`
-- `WorkbookModelVerification`
-- `WorkbookModelActionVerification`
-- `WorkbookModelVerificationOptions`
-- `WorkbookRunAdapter`
-- `WorkbookRunApplyResult`
-- `WorkbookRunReadback`
-- `WorkbookReadbackVerification`
-- `WorkbookReadbackIssue`
-- `WorkbookReadbackIssueCode`
-- `WorkbookCheckExpectation`
-- `WorkbookCheckExpectationDescription`
-- `WorkbookBuiltInCheckKind`
-- `WorkbookCustomCheckOptions`
-- `WorkbookReadbackCheckOptions`
-- `WorkbookRawFormulaOptions`
-- `WorkbookRunResult`
-- `WorkbookRunError`
-- `WorkbookRunErrorCode`
-- `WorkbookCheckResult`
-
-The low-level operation language remains available:
-
-- `WorkbookOp`
-- `WorkbookTxn`
-- `EngineOp`
-- `EngineOpBatch`
-- `isEngineOpBatch`
-
-Formula helpers create portable formula expressions with `@bilig/formula`.
-Calculation and workbook execution stay in `@bilig/core` and the app runtime.
-Use `planWorkbookAction` when an action name comes from an agent or user input;
-it returns `planned` or structured `failed` results instead of requiring
-exception control flow.
-`defineModel` returns frozen, normalized model metadata. Model and action names
-must be non-empty and already trimmed, while descriptions and input metadata are
-trimmed and frozen so the manifest an agent inspected cannot be mutated later by
-the caller.
-Actions can also accept a JSON-safe input:
+Use this package when a consumer wants to define their own workbook model and
+hand a runtime a portable plan. The package does not import the engine, start a
+server, calculate formulas, ship revenue/quote/forecast models, or depend on
+`zod`, `effect`, `@bilig/core`, `@bilig/headless`, or `@bilig/agent-api`.
+
+```sh
+pnpm add @bilig/workbook
+```
+
+## The Shape
 
 ```ts
-import { defineModel } from '@bilig/workbook'
+import {
+  defineModel,
+  describePlan,
+  describeRunResult,
+  describeRuntimeRequirements,
+  formula,
+  planWorkbookAction,
+  runWorkbookPlan,
+  verifyPlan,
+} from "@bilig/workbook";
 
 export const model = defineModel({
-  name: 'custom-writer',
+  name: "generic-row-calculator",
 
   find(workbook) {
+    const table = workbook.findTable({
+      headers: ["Item", "Quantity", "Rate", "Status", "Total"],
+    });
+    const rows = workbook.findRows({
+      table,
+      where: { column: "Status", op: "eq", value: "ready" },
+    });
+
     return {
-      output: workbook.findRange({ sheetName: 'Sheet1', address: 'B2' }),
-    }
+      table,
+      rows,
+      quantity: rows.column("Quantity"),
+      rate: rows.column("Rate"),
+      total: rows.column("Total"),
+    };
+  },
+
+  checks({ refs, workbook }) {
+    return [workbook.check.exists(refs.table), workbook.check.noFormulaErrors(refs.total)];
   },
 
   actions: {
-    write({ refs, workbook, input }) {
-      if (typeof input !== 'object' || input === null || Array.isArray(input)) {
-        throw new Error('input object required')
-      }
-      const value = input.value
-      if (typeof value !== 'number') {
-        throw new Error('numeric value required')
-      }
-      workbook.writeValue(refs.output, value)
+    recompute({ refs, workbook }) {
+      const expected = formula.multiply(refs.quantity, refs.rate);
+      workbook.writeFormula(refs.total, expected);
+      workbook.check.formulaEquals(refs.total, expected);
     },
   },
-})
-```
+});
 
-`planWorkbookAction(model, "write", { value: 12 })` clones and canonicalizes
-that input into the plan so an agent can inspect exactly what was requested.
-Inputs must be plain JSON values: strings, finite numbers, booleans, `null`,
-arrays without holes, and plain objects. This package intentionally does not add
-schema dependencies; consumers own their own input validation inside actions.
-Use `verifyModel(model, { inputs: { write: { value: 12 } } })` when whole-model
-verification needs parameters for specific actions.
+const planned = planWorkbookAction(model, "recompute");
+if (planned.status === "failed") throw new Error(planned.errors[0]?.message);
 
-Actions can also be plain action objects when an agent needs a richer manifest
-without running workbook code:
+const staticProof = verifyPlan(planned.plan);
+const requirements = describeRuntimeRequirements(planned.plan);
+const planForLogs = describePlan(planned.plan);
 
-```ts
-actions: {
-  write: {
-    description: 'Write a consumer-provided value',
-    input: {
-      kind: 'object',
-      fields: {
-        value: { kind: 'number', required: true },
-      },
-    },
-    run({ refs, workbook, input }) {
-      if (typeof input !== 'object' || input === null || Array.isArray(input)) {
-        throw new Error('input object required')
-      }
-      const value = input.value
-      if (typeof value !== 'number') {
-        throw new Error('numeric value required')
-      }
-      workbook.writeValue(refs.output, value)
-    },
-  },
-}
+const result = await runWorkbookPlan(planned.plan, adapter);
+const resultForLogs = describeRunResult(result);
 ```
 
-Input descriptions are intentionally descriptive metadata, not a schema engine.
-They support boring JSON kinds: `json`, `object`, `array`, `string`, `number`,
-`boolean`, and `null`. `object` descriptions may list sorted `fields`; `array`
-descriptions may list `items`. `normalizeWorkbookActionInputDescription` trims
-text, rejects malformed metadata, returns frozen data, and keeps the package
-free of `zod`, `effect`, or model-specific validators.
-`workbookActionInputDescriptionKinds`, `isWorkbookActionInputDescriptionKind`,
-`isWorkbookActionInputDescription`, and `isWorkbookActionInput` expose the same
-contract as stable data so generic tool builders can validate model metadata and
-JSON-safe payloads without ad hoc string matching.
-
-Formula expressions also keep their workbook inputs separate from their formula
-text. A planned `writeFormula` command includes both the parseable formula
-string and the generic model refs it used, so an agent can inspect what the
-action depends on without reverse-parsing placeholder names.
-For formulas outside the small helper set, use
-`formula.raw(source, { inputs })`; the source stays parseable while the
-declared refs remain inspectable and verifiable. These inputs are a declared
-dependency contract for agents, not parser-discovered proof that every formula
-reference has been mapped to a model ref.
-Formula operands intentionally do not accept bare strings. Use `formula.raw`
-for formula source and `formula.text` for spreadsheet string literals, so an
-agent cannot confuse a label, cell address, named range, or user-provided string
-with executable formula text.
-
-Known single-cell `workbook.format(ref, { numberFormat })` actions compile to
-concrete `setCellFormat` ops. Use `numberFormat: null` to plan an explicit
-format clear. Style patches remain high-level intent until the runtime resolves
-style ids.
-Use `workbook.addOp(op, { target?, message? })` inside model actions when a
-consumer needs the existing low-level workbook operation language directly. The
-op is runtime-guarded with `isWorkbookOp`, cloned into `plan.ops`, and kept in
-the command log so agents can inspect it without depending on `@bilig/core`.
-When a `target` is supplied for an address or range op, `verifyPlan` checks that
-the op touches the same range. For op kinds without an inferable range, `target`
-is still useful for logs and approvals but cannot prove the affected cells by
-itself.
-
-Action plans expose `refsUsed`, a flat deduped list of workbook refs found in
-the consumer-defined `refs` object. Use `collectWorkbookRefs` directly when an
-agent needs to inspect refs from any nested consumer shape.
-Use `findTable`, `findColumn`, `findRange`, `findName`, and `findRows` directly
-when an agent or test needs the same generic refs outside a model callback. The
-same helpers are also available as a frozen `find` namespace with short aliases
-such as `find.table(...)`, `find.range(...)`, and `find.rows(...)`.
-Use the frozen `workbookRefKinds` and `workbookRowOperators` lists, plus
-`isWorkbookRefKind`, `isWorkbookRef`, and `isWorkbookRowOperator`, when a
-generic agent tool needs to validate model refs or row predicates without
-copying string unions or depending on a schema package.
-Selector helpers trim text, canonicalize cell addresses, and reject empty table
-names, column names, named ranges, headers, invalid range addresses, invalid row
-operators, and non-finite row predicate values before a plan reaches runtime.
-`findRows` refs include the predicate value in their stable id so two
-consumer-defined row selectors do not collapse during dedupe, while labels stay
-human-readable for agent logs.
-Refs are frozen data objects. Ergonomic helpers like `table.column()` and
-`rows.column()` remain available, but they are non-enumerable so JSON
-inspection, object keys, and plan descriptions stay data-first.
-For table-backed rows, use `rows.column("Amount")` to target only that column in
-the matching rows. Runtime adapters can materialize row-filtered columns into
-the exact cells to read, write, format, clear, or use as row-wise formula inputs
-without hardcoding a business model.
-Use `check.exists(ref)` and `check.noFormulaErrors(ref)` directly when an agent
-or test needs the same generic planned checks outside a model callback.
-Use `check.valueEquals(ref, value)` and `check.formulaEquals(ref, formula)` when
-an action should carry machine-readable readback expectations for runtime
-verification. `formulaEquals` stores normalized formula text plus explicit model
-refs used by that formula, so an agent can inspect the post-action proof target
-without depending on a rendered spreadsheet UI.
-Use `check.custom({ kind, message, target, refs })` for consumer-defined
-invariants; the package does not need to know what the model means. `target`
-names the main ref, and `refs` names any supporting refs the invariant depends
-on so agents can describe and verify the full check contract.
-Custom check kinds cannot reuse built-in names. Use the frozen
-`builtInWorkbookCheckKinds` list or `isBuiltInWorkbookCheckKind` guard when a
-consumer-facing tool needs to validate check kinds before planning.
-
-Model callback phases are deliberately scoped. `find(workbook)` receives only
-the find API; `checks({ workbook })` receives find helpers plus `workbook.check`;
-actions receive find helpers, checks, and mutation planning methods. That keeps
-discovery and proof declaration separate from workbook mutation intent.
-
-Use `describeModel` when an agent needs a JSON-safe manifest of model name,
-model description, sorted action names, per-action descriptions, optional input
-descriptions, and whether model-level checks exist without running `find`,
-checks, or actions.
-Use `describeRef` and `describePlan` when an agent needs JSON-safe intent for
-logs, comparisons, approvals, or runtime handoff. Descriptions keep the same
-generic action input, refs, commands, checks, changes, and ops, but omit
-consumer-private `refs` object shape and helper functions such as
-`table.column()`.
-Use `describePlanResult` when the same JSON-safe handoff is needed for either
-planned or failed action planning.
-Use `describeRunResult` after execution when an agent needs the same JSON-safe
-shape for `done` or `failed` run results. It preserves changed summaries,
-checks, errors, and undo ops, but describes workbook refs without helper
-functions such as `table.column()` or `rows.column()`.
-Run errors use a stable `WorkbookRunErrorCode` union rather than arbitrary
-strings. Use the frozen `workbookRunErrorCodes` list and `isWorkbookRunErrorCode`
-guard when an adapter, logger, or approval layer needs to branch on known
-failure classes. Runtime adapters should use `apply_failed` for apply
-exceptions and `runtime_rejected` for intentional runtime refusal with a
-specific message instead of inventing new public codes.
-Use `describeRuntimeRequirements(plan)` before runtime handoff when an agent
-needs to inspect what the adapter must do. It returns a JSON-safe list of
-generic `apply`, `read`, and `verify` requirements with boring capabilities
-such as `writeFormula`, `writeValue`, `format`, `clear`, `applyOp`, `read`, and
-`verifyCheck`. Command-derived concrete single-cell ops are not repeated as
-extra `applyOp` requirements, while explicit or manually assembled ops still
-appear as `applyOp`. It does not execute anything and it does not import the
-engine.
-
-Use `verifyPlan` before runtime handoff when an agent needs to prove a planned
-action is internally consistent. It checks for non-JSON-safe action input,
-unresolved refs, unparsable formulas, duplicate resolved refs, and missing
-concrete ops for write, clear, and number-format commands that already target a
-known single cell. Custom check targets and supporting refs must also resolve
-through the model's `refsUsed` contract. Formula readback expectation inputs
-must also resolve through `refsUsed`, and expectation formulas must be parseable.
-Checks must start as `planned`; consumer code cannot mark a check passed or
-failed before runtime proof.
-Low-level `addOp` commands must contain valid `WorkbookOp` values, must still
-appear in `plan.ops`, and must match their declared `target` when the op exposes
-a concrete address or range.
-Use `verifyModel` to plan and verify every action in a consumer-defined model
-with one JSON-safe result. Pass `inputs` when specific actions require
-parameters. Each successfully planned action also includes its runtime
-requirements, so an agent can inspect the action manifest, planned intent,
-static verification result, and adapter handoff checklist from the same object.
-
-Use `runWorkbookPlan(plan, adapter)` or
-`runWorkbookAction(model, actionName, adapter, input)` when an agent needs a
-generic apply-and-prove loop. The adapter owns runtime execution and semantic
-readback:
+That is the core flow:
+
+1. `defineModel` freezes a consumer-defined model.
+2. `find` returns generic refs.
+3. `checks` declares facts the runtime must prove.
+4. An action builds workbook intent.
+5. `verifyPlan` checks the plan without running an engine.
+6. `describeRuntimeRequirements` tells an adapter what it must apply, read, and prove.
+7. `runWorkbookPlan` applies the plan through a runtime-owned adapter and returns a boring result with check proof and apply proof when the adapter provides it.
+
+## Public Contract
+
+The main API is intentionally small:
+
+- model: `defineModel`, `inspectModel`, `planWorkbookAction`, `buildWorkbookActionPlan`
+- selectors: `findTable`, `findColumn`, `findRange`, `findName`, `findRows`, `find`
+- checks: `check.exists`, `check.noFormulaErrors`, `check.valueEquals`, `check.formulaEquals`, `check.custom`
+- formulas: `formula.add`, `formula.subtract`, `formula.multiply`, `formula.divide`, `formula.sum`, `formula.call`, `formula.raw`, `formula.text`
+- proof: `verifyPlan`, `verifyModel`, `verifyWorkbookReadbacks`
+- descriptions: `describeModel`, `describeRef`, `describePlan`, `describePlanResult`, `describeRuntimeRequirements`, `describeRunResult`
+- runtime handoff: `runWorkbookPlan`, `runWorkbookAction`, `WorkbookRunAdapter`
+- low-level language: `WorkbookOp`, `WorkbookTxn`, `EngineOp`, `EngineOpBatch`, `isEngineOpBatch`
+
+Stable data helpers are exported for generic tool builders:
+
+- `workbookRefKinds`, `isWorkbookRefKind`, `isWorkbookRef`
+- `workbookRowOperators`, `workbookRowOperatorValueTypes`, `isWorkbookRowOperator`, `isWorkbookRowValueCompatible`
+- `builtInWorkbookCheckKinds`, `isBuiltInWorkbookCheckKind`
+- `workbookActionInputDescriptionKinds`, `isWorkbookActionInputDescriptionKind`, `isWorkbookActionInputDescription`, `isWorkbookActionInput`
+- `workbookRunErrorCodes`, `isWorkbookRunErrorCode`
+
+## Selectors
+
+Selectors are not a human spreadsheet UI. They are stable intent for runtimes and
+agents.
+
+- `findTable({ headers })` means "find a table with all these headers." Header
+  order is normalized, duplicate headers are rejected, and matching is
+  case-sensitive after trimming.
+- `findRows({ table, where })` means "find rows in this table matching this
+  predicate." `eq` and `neq` accept any JSON literal; `contains` and
+  `startsWith` accept strings; ordered comparisons accept numbers or strings.
+- `findRange` is the escape hatch for an explicit range when the consumer really
+  has one. It validates and canonicalizes addresses before runtime handoff.
+
+Refs are frozen data. Helpers such as `table.column("Total")` and
+`rows.column("Total")` are non-enumerable, so JSON descriptions stay data-first.
+
+## Formulas
+
+`@bilig/workbook` creates formula expressions. `@bilig/formula` parses and
+normalizes formula text. `@bilig/core` or an app runtime calculates it.
+
+Formula helpers keep formula text and workbook dependencies separate. A planned
+formula write includes both the formula string and the refs used to build it.
+For custom formula text, use `formula.raw(source, { inputs })`. For spreadsheet
+string literals, use `formula.text(value)`. Bare strings are not formula
+operands because agents should not guess whether a string is code, a label, a
+named range, or user text.
+
+## Runtime Adapter
+
+`@bilig/workbook` does not execute plans. A runtime owns that:
 
 ```ts
-const result = await runWorkbookAction(model, 'write', {
+const adapter = {
   apply(plan) {
-    return runtime.apply(plan.ops)
+    const ops = materializeForThisRuntime(plan);
+    return {
+      status: "applied",
+      previewOps: ops,
+      appliedOps: ops,
+      proof: { source: "runtime", opCount: ops.length },
+      undo: { id: "undo-1" },
+    };
   },
-  read(targets) {
-    return runtime.read(targets)
+  read(targets, plan) {
+    return targets.map((target) => ({ target, value: 12 }));
   },
-})
+  verifyChecks(checks, plan) {
+    return checks.map((entry) => ({ ...entry, status: "passed" }));
+  },
+};
 ```
 
-`runWorkbookAction` plans the action, runs `verifyPlan`, calls
-`adapter.apply(plan)`, then evaluates `valueEquals` and `formulaEquals` checks
-against `adapter.read(targets, plan)`. It never imports the engine, headless
-runtime, app server, or UI. If static verification fails, the apply adapter is
-not called. If a readback expectation is missing or mismatched, the returned
-`WorkbookRunResult` is `failed` with deterministic error codes such as
-`readback_missing`, `value_mismatch`, or `formula_mismatch`. `adapter.read`
-must return exactly the requested targets; extra readbacks fail with
-`readback_unexpected` because an agent should not accept proof for cells it did
-not ask the runtime to inspect.
-Formula readbacks are exact: adapters should return formula text in the same
-normalized no-leading-`=` form produced by `formula.source`.
-`adapter.apply` only applies the plan and may return an undo ref; it cannot
-drop, replace, or prove checks. An apply result with `status: "applied"` and
-non-empty `errors` is rejected as `runtime_rejected`.
-Adapters provide `verifyChecks(checks, plan)` to prove non-readback checks such
-as `exists`, `noFormulaErrors`, and consumer-defined `custom` invariants. The
-verifier must return the same checks in the same order and may only change
-`status` or add JSON-safe `proof`. Changing `kind`, `target`, `refs`,
-`expectation`, or `message` fails the run as `invalid_check_verification`.
-Unsupported verifier fields are stripped from accepted results. If any verified
-check is `failed`, the run returns `failed` with `check_failed`. If any check
-remains `planned` after readback and adapter verification, the run returns
-`failed` with `check_not_verified`; `status: "done"` means every planned check
-has proof.
-
-When running against Bilig's engine, use `createWorkbookRunAdapter(engine)` from
-`@bilig/core`. The adapter materializes generic `plan.commands` into engine
-operations, falls back to explicit `plan.ops` for low-level plans, reads
-single-cell expectation targets, and verifies generic `exists` and
-`noFormulaErrors` checks without adding workbook-specific business models to
-this package. If the engine captures undo, the run result includes `undo.ops` in
-the same portable operation language.
+`runWorkbookPlan` refuses to call `apply` if static plan verification fails.
+If an adapter returns both `previewOps` and `appliedOps`, the result reports
+whether they matched. If the adapter returns neither, the run records an
+unverified apply fact. Use `runWorkbookPlan(plan, adapter, { requireApplyProof:
+true })` when an agent must fail closed instead of accepting an unproved apply.
+Readback checks attach proof to passed checks, such as
+`{ source: "readback", value: 12 }` or
+`{ source: "readback", formula: "(Table[Quantity])*(Table[Rate])" }`.
+Generic check verifiers may only change `status` or add JSON-safe `proof`; they
+cannot rewrite the check contract.
+
+The result is deliberately plain:
+
+```ts
+type WorkbookRunResult =
+  | {
+      status: "done";
+      apply?: WorkbookRunApplySummary;
+      changed: WorkbookChangeSummary[];
+      checks: WorkbookCheckResult[];
+      undo?: WorkbookUndoRef;
+      unverified?: WorkbookRunUnverified[];
+    }
+  | {
+      status: "failed";
+      errors: WorkbookRunError[];
+      apply?: WorkbookRunApplySummary;
+      checks: WorkbookCheckResult[];
+      unverified?: WorkbookRunUnverified[];
+    };
+```
+
+## Low-Level Ops
+
+Most models should use the small action API: `writeFormula`, `writeValue`,
+`format`, `clear`, and checks. If a consumer needs the existing workbook
+operation language directly, call `workbook.addOp(op, { target, message })`
+inside an action.
+
+The op is guarded with `isWorkbookOp`, cloned into `plan.ops`, and kept in the
+command log. If a target is supplied and the op exposes a concrete range,
+`verifyPlan` checks that the target and op agree.
+
+## Example
+
+See [examples/workbook-agent-model](../../examples/workbook-agent-model) for a
+generic model that plans, verifies, describes, runs, and prints proof without
+depending on a hardcoded business model.

package/dist/check.d.ts

@@ -19,7 +19,7 @@ export interface WorkbookCheckApi {
     readonly custom: (options: WorkbookCustomCheckOptions) => WorkbookCheckResult;
 }
 export type WorkbookBuiltInCheckKind = 'exists' | 'noFormulaErrors' | 'valueEquals' | 'formulaEquals';
-export declare const builtInWorkbookCheckKinds: readonly ("valueEquals" | "formulaEquals" | "exists" | "noFormulaErrors")[];
+export declare const builtInWorkbookCheckKinds: readonly ("exists" | "noFormulaErrors" | "valueEquals" | "formulaEquals")[];
 export declare function isBuiltInWorkbookCheckKind(value: unknown): value is WorkbookBuiltInCheckKind;
 export declare function createWorkbookCheckResult(kind: string, target: WorkbookRef, message: string): WorkbookCheckResult;
 export declare function createWorkbookCustomCheck(options: WorkbookCustomCheckOptions): WorkbookCheckResult;

package/dist/check.js

@@ -46,14 +46,22 @@ function uniqueRefs(refs) {
 }
 function createWorkbookCheck(options) {
     const refs = uniqueRefs(options.refs);
-    return {
+    const expectation = options.expectation === undefined
+        ? undefined
+        : options.expectation.kind === 'formulaEquals'
+            ? Object.freeze({
+                ...options.expectation,
+                inputs: Object.freeze([...options.expectation.inputs]),
+            })
+            : Object.freeze({ ...options.expectation });
+    return Object.freeze({
         status: 'planned',
         kind: requiredText(options.kind, 'kind'),
         ...(options.target !== undefined ? { target: options.target } : {}),
-        ...(refs !== undefined ? { refs } : {}),
+        ...(refs !== undefined ? { refs: Object.freeze([...refs]) } : {}),
         message: requiredText(options.message, 'message'),
-        ...(options.expectation !== undefined ? { expectation: options.expectation } : {}),
-    };
+        ...(expectation !== undefined ? { expectation } : {}),
+    });
 }
 export function createWorkbookCustomCheck(options) {
     const kind = requiredText(options.kind, 'kind');

package/dist/check.js.map

@@ -1 +1 @@
-{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"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"}

package/dist/describe.d.ts

@@ -3,7 +3,7 @@ import type { WorkbookRef, WorkbookRefKind, WorkbookRowOperator } from './find.j
 import { type WorkbookActionInspection, type WorkbookActionMap, type WorkbookActionPlan, type WorkbookActionPlanResult, type WorkbookModel } from './model.js';
 import type { WorkbookActionInput } from './input.js';
 import type { WorkbookOp } from './ops.js';
-import type { WorkbookCheckStatus, WorkbookRunErrorCode, WorkbookRunResult } from './result.js';
+import type { WorkbookCheckStatus, WorkbookRunErrorCode, WorkbookRunResult, WorkbookRunUnverifiedKind } from './result.js';
 export interface WorkbookModelDescription {
     readonly name: string;
     readonly description?: string;
@@ -117,15 +117,29 @@ export interface WorkbookUndoRefDescription {
     readonly id: string;
     readonly ops?: readonly WorkbookOp[];
 }
+export interface WorkbookRunApplySummaryDescription {
+    readonly matched: boolean | null;
+    readonly previewOps?: readonly WorkbookOp[];
+    readonly appliedOps?: readonly WorkbookOp[];
+    readonly proof?: WorkbookActionInput;
+}
+export interface WorkbookRunUnverifiedDescription {
+    readonly kind: WorkbookRunUnverifiedKind;
+    readonly message: string;
+}
 export type WorkbookRunResultDescription = {
     readonly status: 'done';
+    readonly apply?: WorkbookRunApplySummaryDescription;
     readonly changed: readonly WorkbookChangeSummaryDescription[];
     readonly checks: readonly WorkbookCheckResultDescription[];
     readonly undo?: WorkbookUndoRefDescription;
+    readonly unverified?: readonly WorkbookRunUnverifiedDescription[];
 } | {
     readonly status: 'failed';
     readonly errors: readonly WorkbookRunErrorDescription[];
+    readonly apply?: WorkbookRunApplySummaryDescription;
     readonly checks: readonly WorkbookCheckResultDescription[];
+    readonly unverified?: readonly WorkbookRunUnverifiedDescription[];
 };
 export interface WorkbookRunErrorDescription {
     readonly code: WorkbookRunErrorCode;