v0.6.0

A Bellbook log has always known more than it could tell you. Replay derives lineage, evidence, standing, taint - and until now, asking about any of it meant walking records by hand. RFC-0002 names the seven questions the log can answer, and this release implements the closed set on every surface:

• descent - the line of descent from a candidate back to its roots
• descendants - everything downstream of a record
• siblings - a candidate's generation
• frontier - candidates never considered, and winners with no continuation yet
• standing - one record's standing, taint, retraction status, and restorations
• evidence - what a selection or a whole line rests on
• selected - the selections under an exact objective, with chosen candidates and evidence

No new record kinds and no spec change - the epoch stays 0.3, and existing 0.3/0.4/0.5 receipts and rules validate identically. And no ranking anywhere: queries report annotated facts (standing, taint, retraction - nothing silently filtered) and the caller decides.

Every surface, the same answer

• Rust: the bellbook::queries module - deterministic, read-only, derived from what replay already computes. Queries answer only over verified state: an invalid log returns an error, never answers, and rejected records are not addressable.
• CLI: bellbook query NAME [ID|OBJECTIVE] (--log DIR --rules FILE | --receipt FILE) [--json] - the same queries over a live log or a portable receipt, with byte-identical JSON on both inputs (asserted in CI).
• Python: the seven queries as methods on Writer and Receipt, returning plain dicts/lists in the shared shapes.
• Conformance: the corpus gains query-cases.json - executable answers, with a build-failing assertion that every query name has vectors - and the independent Python validator implements the named set from scratch and agrees with the reference byte for byte, the same cross-implementation discipline the verdicts live under.

The gate proof

RFC-0002 pre-registered its own success criterion: re-running the project's field tests must need zero hand-walking of records. That proof now lives in CI - the canary best-of-N story (adopt a baseline on a benchmark, run a round, discover the benchmark was broken, retract, repair) rewritten so that every question is answered by bellbook query alone: who won and on what evidence, the full line of descent, what the line rests on (the retracted benchmark surfaces, annotated), standing after the repair, and what is still open on the frontier.

Tie-breaks become evidence

When two candidates pass and one wins, the reason deserves to be evidence, not prose. The best-of-N quickstart now documents the pattern: record the discriminating fact as an Evaluation under its own criterion, and the selection's evidence genuinely distinguishes the winner - queryable ever after. (rationale stays what it is: a recorded statement, verified by no one.)

Boundaries, kept

The general query engine - patterns, predicates, composition - remains gated on RFC-0001 section 15's adoption criterion, and nothing in this release re-opens that decision. The named set is closed, its semantics pinned three ways: the RFC for edge cases, SPEC section 12.4 for existence and boundaries, and the corpus for executable answers.

Install

cargo add bellbook            # 0.6.0
pip install bellbook          # 0.6.0

Full details in the CHANGELOG.

v0.5.0

Retraction and standing on every surface. This release adds no new record kinds and no spec change - the epoch stays 0.3 - and the library API is unchanged. What changes is reach: the semantics that define Bellbook (retraction, transitive taint, standing, restoration) were previously exercisable only from the Rust core; the CLI and the Python package can now tell the whole story, and the story is enforced in CI on both surfaces. Existing 0.3/0.4 receipts and rules validate identically.

Added

• CLI bellbook retract (#83). Retract a committed record from a log: bellbook retract --log DIR --rules FILE --author ID --target RECORD_ID --reason TEXT [--json], with the same conventions as the other mutating commands. The record stays in the log; the receipt reports Tainted from then on.
• Python Writer.retract(author, target, reason) (#82). The same verb from the bellbook package, returning a Commit like the other verbs. Ownership is enforced by replay: the retractor must be the target's author or an admin retraction actor, an Executor may never author one, and a Verdict or Retraction cannot be retracted.
• Retraction-story rules knobs on both surfaces (#84). bellbook rules init --admin ID and --reaffirmer ID, with matching admins= and reaffirmers= keyword arguments on Python default_rules. Without these, records authored by an Executor were retractable only through a knob no adoption surface could set.
• The repair pattern, verified and documented (#85). A candidate motivated by an evaluation names it in derives_from alongside the candidate it derives from; Cause carries intent, not taint, so retracting that evaluation later does not compromise the repair.
• The release gate, enforced (#87). A CLI test and a Python test each replay the broken-benchmark story end to end - Clean, retract, standing collapse at depth, reaffirm, restoration recorded - asserting behavioral equivalence with examples/broken_benchmark.rs, plus an ownership battery.
• Quickstart Phase 2: the benchmark was broken (#86). docs/quickstart-best-of-n.md walks retract -> Tainted -> reaffirm -> restoration in both columns, stating plainly: restoration restores standing, not Clean. The receipt stays Tainted permanently, because a record that could quietly return to Clean would be a record you could not trust.

Install

Rust:

cargo add bellbook@0.5.0

Python (prebuilt wheels for Linux, macOS, Windows; no Rust toolchain needed):

pip install bellbook==0.5.0

Verified

• crates.io: https://crates.io/crates/bellbook/0.5.0
• PyPI: https://pypi.org/project/bellbook/0.5.0/
• pip install bellbook==0.5.0 in a clean venv: the full retraction story (admin cross-author retract -> Tainted, reaffirm -> restoration recorded, receipt stays Tainted) passes against the published wheel.

Full Changelog: https://github.com/bellbook-ai/bellbook/blob/v0.5.0/CHANGELOG.md

v0.4.0

Adoption and hardening release. It adds no new record kinds and no spec change - it still implements spec epoch 0.3 - and instead closes the gap between the shipped wedge and a first successful run: the CLI now completes the record -> receipt -> validate loop by itself (no language binding required), the receipt trust boundary is fuzzed, and worked examples plus a best-of-N quickstart show the three proving workloads. The published crate's API is unchanged; existing 0.3.0 receipts and rules validate identically.

Added

• CLI bellbook rules init and bellbook export (#70, #71). rules init writes a starter verifier-rules file from --author <id>:<role> bindings, so a new user no longer hand-authors one (it is feature-independent, like validate). export bundles a log directory into a portable receipt, closing the record -> receipt -> validate loop from the CLI alone; previously the export step required the Rust or Python API. Both were surfaced as adoption friction while writing the best-of-N quickstart.
• Python bellbook.default_rules(authors, max_context=200). Builds a starter verifier-rules JSON string from actor-id -> role bindings - the Python counterpart to bellbook rules init - so Writer users need not hand-author a rules object.
• Fuzzing harness over the receipt trust boundary (#65). A fast, seeded harness (tests/fuzz_trust_boundary.rs) runs in the ordinary test suite on every push, asserting that validate never panics and that its reports, along with Receipt::from_bytes and RFC 8785 canonicalization, stay self-consistent for arbitrary input. A coverage-guided libFuzzer target set (fuzz/) runs weekly and on demand for deeper exploration. SECURITY.md documents both layers and the pending external-review gate. Development-only; the published crate API is unchanged.
• Adoption worked examples and a best-of-N quickstart (#66, #67, #68). examples/iterative_evolution.rs records a multi-generation fork-evaluate-select loop and reads the surviving lineage back; examples/repair_reevaluate.rs shows a single-candidate repair and why a repair motivated by a retracted evaluation is not tainted by it (Cause carries intent, not taint). docs/quickstart-best-of-n.md takes a best-of-N harness to a portable receipt with the CLI and the Python package side by side, with a committed starter docs/quickstart/rules.json.

Install

Rust:

cargo add bellbook@0.4.0

Python (prebuilt wheels for Linux, macOS, Windows; no Rust toolchain needed):

pip install bellbook==0.4.0

Verified

• crates.io: https://crates.io/crates/bellbook/0.4.0
• PyPI: https://pypi.org/project/bellbook/0.4.0/
• pip install bellbook==0.4.0 in a clean venv; default_rules + Writer (candidate/evaluate/select) + validate round-trips to a clean receipt.

Full Changelog: https://github.com/bellbook-ai/bellbook/blob/v0.4.0/CHANGELOG.md

v0.3.0

Bellbook 0.3.0 implements spec version 0.3, the evolution epoch, layered
over the unchanged v0.2 trust kernel. Published to crates.io as
bellbook 0.3.0.

Added

• Three record kinds for software evolution. Candidate binds a Git
  source state (reported or canonical-manifest binding), Evaluation judges
  one candidate under one criterion (decode-bounded scores), and Selection
  records a set-valued decision over candidates — with a full per-kind rule
  battery and six new reason codes.
• Standing — a replay-derived lineage dimension. When an evaluation is
  retracted and taint reaches the selections that used it, the replay report
  marks every descendant candidate of those selections compromised,
  transitively, at any depth; one reaffirming selection on surviving evidence
  restores the line. Standing is re-derived by every validator like the taint
  set — never embedded in a receipt, never merged into kernel taint or
  evidence.
• Selection approval binding, canonical manifest v1, and a
  recording CLI (candidate / eval / select / lineage).
• Flagship worked example — cargo run --example broken_benchmark runs
  the whole story end to end and prints the standing section changing across
  the retraction and the recovery.
• Independent, from-scratch Python validator reproduces the vectors and
  the entire v0.3 conformance corpus, confirming cross-implementation
  agreement on canonical forms, ids, hashes, decisions, and the standing
  section — byte for decision.

Compatibility

• Spec v0.2 remains a frozen, still-valid epoch: its artifacts are
  byte-frozen, the published 0.2.0 crate stays their validator (a CI epoch
  check confirms the frozen v0.2 receipts validate identically under it), and
  this validator rejects a v0.2 receipt with a clear unsupported-version
  report.

Limitations (what the verifier does not claim)

• Proves consistency of captured activity, not capture completeness.
• Integrity, not confidentiality — records and receipts may hold
  sensitive payloads.
• Lineage, standing, and taint are conditional on producer recording
  discipline: basis, parent, and refs are producer claims a verifier
  cannot check against intent. A receipt carries no source contents — a
  reported binding is a verifiable record of an unverified claim; a manifest
  binding lets a party holding the tree recompute and compare.
• "Clean" is relative to the rules embedded in the receipt.

See CHANGELOG.md
and SPEC.md §13
for full detail.

v0.2.0

Bellbook 0.2.0 is the first public release. It implements Bellbook spec
version 0.2, the first published compatibility epoch.

A tamper-evident, replay-verifiable record of captured agent activity:
typed records in an append-only, hash-chained log, each judged by a
deterministic verifier and replayable from genesis or a checkpoint.

Added

• Twelve typed record kinds (requests, actions, responses, results,
  authority, approvals, refusals, plans, usage, summaries, retractions,
  deterministic verdicts).
• RFC 8785 JSON canonicalization and SHA-256 content-addressed record ids.
• Typed Cause, Use, Require, Replace references between records.
• Deterministic record and full-log verification: gap-free logical time,
  subject/verdict pairing, verdict re-derivation, author-role enforcement,
  request lifecycle checks, and authority resolution.
• Five evidence classes with weakest-link derivation and configurable
  per-kind thresholds.
• Strict Ed25519 signatures with actor key pinning and a version-specific
  signing domain.
• Append-only retractions with transitive taint through epistemic
  dependencies.
• A crash-safe, exclusively locked file writer with verified open,
  bounded loading, pair-atomic commits, recovery, deterministic batches,
  and idempotent compare-and-append.
• Portable receipts and the bellbook validate CLI for bounded offline
  validation from genesis.
• Trusted checkpoints and canonical head attestations for external
  anchoring.
• Deterministic context selection and verified state construction.
• Versioned canonical test vectors, including signed-record vectors.
• CI across Linux, macOS, and Windows, Rust 1.75 checks, documentation
  checks, scheduled RustSec scanning, and Dependabot updates.

Security

• Record ids bind completed signatures; removing or substituting a
  signature changes the id and every dependent reference or anchored head.
• Signature input is domain-separated (bellbook.record-signature.v0.2),
  preventing cross-protocol and cross-version replay.
• Strict decoding: unknown fields, duplicate logical keys, and
  non-canonical payloads reject.
• Receipt and persistent-log input is resource-bounded before verification.
• Replay recomputes record ids and stored verdicts, including full verdict
  envelope validation.
• Checkpoints cannot arrive through receipts; only the explicit
  trusted-checkpoint API accepts them.
• Persistent commits reserve and recover the complete subject/verdict pair.
• Key-pinned actors must sign every record; actor identities are bound to
  configured roles.
• Actions name the exact capability and approval that authorized them;
  retracted authority no longer authorizes later actions.

Known limitations

• Proves consistency of captured activity, not capture completeness.
• Integrity, not confidentiality: records and receipts may contain
  sensitive payloads.
• A storage owner can replace an unanchored log from genesis; key-pinned
  signatures and externally stored head attestations limit that threat.
• Receipt status is evaluated under the embedded verifier rules; consumers
  compare rules_hash against rules they trust.

See SPEC.md for normative behavior and SECURITY.md
for the threat model.

Full details: CHANGELOG.md