feat(bookspec): the checker crate, the Engine trait and the runner (P13)

bookspec is a specification first: every rule normative and sourced,
every rule demonstrated by concrete examples, and any accounting engine
checked against them through one interface (D-34). This moves the
examples' schema out of the test that happened to parse them and makes
the interface explicit.

- `bookspec/checker` (its own workspace, inside this repository until
  the harness is stable): `Example`, `Setup`, `Event`, `Expect`, `Query`,
  `Refusal` and the TOML parser, every structure `deny_unknown_fields`,
  with `Example::from_toml` checking the cross-field shape (closed lists,
  exact decimal amounts, dates, one event kind, `reverses` counting from
  1, the shares summing to 1, commands accepted or refused and not both).
- `Engine` (`load`, `apply`, `query`, `claims`) and `Refusal { rule,
  reason }`; the refusal's rule is the bookspec identifier, so a refusal
  names the rule it belongs to. `Claims` also carries the option an
  engine picks for a CHOICE rule.
- `bookspec/runner` drives any `Engine` through the examples and reports
  per rule: pass, fail, not claimed. It compares the answer itself; an
  engine is never asked whether it agrees with itself.
- `crates/ledger-core/tests/bookspec.rs` is the wanderbooks adapter over
  `Store`: the loader parses through the checker, its own checks are
  unchanged, and the new `the_runner_reports_every_claimed_rule_green`
  runs all 56 examples through the trait. The IIF appendix is answered
  through `ledger_package::export_iif`, the code its own test checks.
- `just check` runs the bookspec workspace's fmt, clippy, rustdoc and
  tests too, so an example cannot rot (D-34, Z-17).

The plan's trait has four methods and no path for an example's
`[[changes]]` (a rename, the policy, an asset correction), which post no
entry: `change` is the fifth, required so an engine cannot skip those
examples silently. This is reported to the EM as the one departure.

One money rule holds here too: an answer's figures are exact decimal
strings, never JSON numbers, so no engine can round a cent through a
float.
This commit is contained in:
swaits committed 2026-10-26 21:22:46 -06:00
1 parent 8c956e8d74
commit b7be5a5472
18 files changed
+5822 -702

No files matched your search

+23
View File
@@ -0,0 +1,23 @@
//! bookspec's checker: the example schema, the rule identifiers, and the
//! [`Engine`] trait an accounting engine implements (`plan/served.md` P13,
//! D-34).
//!
//! bookspec is a specification first: every rule is stated normatively,
//! sourced, and demonstrated by concrete examples (`bookspec/examples/`).
//! This crate is the machine-readable part: [`Example`] is the schema and
//! its parser, [`mod@rules`] the catalogue (`BS-<area>-<n>`), and [`Engine`]
//! the only interface a conformance runner needs. The runner lives in
//! `bookspec-runner`; wanderbooks' adapter is
//! `crates/ledger-core/tests/bookspec.rs`.
//!
//! The crate knows nothing of any engine: no money type, no ledger, no
//! store. That is what lets a second engine (the GnuCash oracle, later) be
//! checked by the same examples.
pub mod engine;
pub mod rules;
pub mod schema;
pub use engine::{Claims, Engine, Refusal, RuleId, RuleIdError, fallback_refusal};
pub use rules::{Area, Rule, Status, covered_rules, rule, rule_for_id, rule_for_refusal, rules};
pub use schema::*;