[tbitcs]

Companion to AXIOVEX/axiomere Spec 003 (verification policy), claim AXM-003-15, item (1): the axiomere-python half. The core work is merged on AXIOVEX/axiomere main (cc45299). This PR exposes it idiomatically from Python; it does not merge itself — coordinator verifies and merges.

The surface

• Database.verify(*, trusted=None, expected_head=None) and axiomere.verify_file(path, *, trusted=None, expected_head=None).
  • trusted is a plain dict {actor: public_key_hex}: None = bare mode (signatures checked against the keys embedded in the events — self-consistency); a dict = trusted mode (identity: every actor named in the map, every event signed with the mapped key, no fallback to embedded keys); {} trusts nobody and is deliberately distinct from None.
  • expected_head is a plain dict with any of head_hash, min_events, checkpoint_root (checkpoint root compared against the root verification recomputes).
• Verification gains the two new result fields — now the full eight the bindings return: ok, events, break_seq, reason, signatures_checked, signatures_failed, unsigned_events (tuple of seqs), untrusted_actors (tuple of actor names).
• verify_file returns the full Verification instead of the old reduced (ok, count, reason) tuple, and a malformed/unreadable file is a verdict (ok=False + named reason), never an exception — FR-VP-11 at this surface. Database.open keeps raising, per C3.
• Append-side honesty (from the rebuilt extension): NaN / ±∞ / out-of-range integers raise ValueError and append nothing.

Docs (plain language)

• docs/verification.md rewritten around the policy: the eight result fields, what is checked (incl. canonical bytes and checkpoint recomputation), signature presence and what unsigned_events / untrusted_actors mean, bare vs trusted, head pinning — with the plain statement that a truncated prefix passes bare verification and the pin is the detection, and the write-time ValueError.
• docs/api.md updated to the new shapes; docs/format.md gains the pinned canonical encoding from core Spec 003 §5 and the corrected snapshot-id construction (SHA-256(canonical({"content":…, "parent":…}))). mkdocs build --strict clean.
• CHANGELOG.md: [Unreleased] entry (Added / Changed / Fixed). No version bump — releases are the coordinator's.

Tests

Extension built from axiomere main cc45299 via the repo's own flow (maturin, venv). Full suite: 17 passed.

New tests/test_verification_policy.py (10 tests) mirrors the core's acceptance from Python, rebuilding the red team's constructions with a pure-Python Ed25519 re-signing harness (its soundness is proven by a control that re-signs an untouched event and still verifies):

• honest ledger verifies bare and trusted, both surfaces returning identical results;
• wrong key → signer-key-mismatch; unmapped actor → untrusted-actor with the actor in untrusted_actors (F-VP-5 shape), via both verify_file and the ledger object; empty map trusts nobody;
• transplanted checkpoint root fails with checkpoint-root-mismatch — bare and trusted, identity genuine, root recomputed;
• partial sig-strip fails every mode with unsigned-event; full strip is a visible bare-mode state (signatures_checked=0, all seqs in unsigned_events) and fails trusted mode;
• truncation passes bare verification (asserted — the documented limit) and fails under expected_head as shortfall / head-mismatch / root-mismatch;
• F-VP-8 battery: NaN, ±∞, 2**70, -(2**70) raise and leave the file byte-identical; 2**64-1, 2**63, -2**63 round-trip as exact ints; a finite float round-trips bit-exact;
• verify_file on garbage / empty / broken / missing files returns failed verdicts, never raises.

Teeth check: the same 10 tests run against the pre-fix 0.1.0 extension (PyPI build) — 10 failed, as they must. Existing tuple-shape uses in test_axiomere.py and test_float_roundtrip.py were updated to the full result shape.

Scope: no changes to AXIOVEX/axiomere or Tekmerion. The Tekmerion companion (recomputed-root comparison at study boundaries) is a separate item under AXM-003-15 and is not claimed by this PR.

[read-the-docs-community]

Documentation build overview

📚 axiomere | 🛠️ Build #35131075 | 📁 Comparing a55f8f8 against latest (711dd49)

  🔍 Preview build  

3 files changed

± api/index.html
± format/index.html
± verification/index.html