v5.15.2 5 March 2026 Improvement

Kernel Governance Infrastructure — Axiomatic Contract, Axiom Registry & Development Contract v1.5

Why This Matters

A deterministic financial kernel is only as trustworthy as the governance system that surrounds it. Code can be correct today and drift tomorrow — through a well-intentioned refactor, a changelog claim that overstates enforcement, or a new developer who inherits the system without understanding its invariant model. This release addresses that risk directly.

SpeyBooks now has a formal, machine-verifiable governance stack: every architectural invariant is classified, registered, and linked to a proof anchor. Public changelog entries are bound by a mathematical honesty rule that prevents enforcement claims from outrunning what the system actually guarantees. The development contract governs not just what to build, but how to reason about what has been built.

This is infrastructure for the kernel sequence. Milestones 3 through 6 depend on this governance layer being in place before the work begins.

Governance Infrastructure

Development Contract v1.5

The kernel development contract has been hardened with structural additions that close the gap between architectural intent and verifiable reality.

  • Invariant classification introduced Every invariant is now formally Class M (mechanically enforced, violation is fatal) or Class O (operationally enforced, with a declared bypass vector, mitigation, and upgrade path to Class M). No invariant may claim enforcement it does not have.

  • Two-layer minimum rule formalised Any invariant affecting money, tenancy, ledger integrity, or state machines must be enforced by at least two independent layers, one of which must be database-level.

  • Drift Governance section added Canonical truth sources defined in priority order, drift ban encoded, axiom registry requirement specified. Mismatch between the live schema and migration history is a defect, not documentation lag.

  • Axiom Stability Rule Once registered, an axiom may not be modified or removed without an ADR. Weakening a class (M to O) is a kernel architecture change requiring the same ADR process as a schema change affecting financial tables.

  • CI Proof Verification Rule Proof anchors in the registry must resolve to real artifacts — named tests, migration invariant queries, or verification scripts. CI fails if a proof anchor references a missing or renamed artifact.

  • Migration Envelope formalised All migrations touching tenant or financial tables must include timeout controls, in-transaction invariant DO blocks that RAISE EXCEPTION on breach, post-commit verification queries, and pre-flight read-only checks. Silent failures are structurally impossible.

  • RLS Canonical Predicate Rule Policy predicates have a single canonical form stored in docs/kernel/rls.md. No alternative formatting permitted. Canonical string form is a contract.

  • State machine morphism model Transitions are formally defined as f: S → S with declared arrows enforced at DB trigger, TypeScript, and test layers simultaneously. Undeclared transitions are impossible by construction.

  • Audit trail hardened Canonical JSON enforced by a single function. Required fields expanded to include source and schema_version. Upgrade path to Class M documented against Milestone 6.

  • Changelog communication rules added Two-tier format with proof anchors required for all enforcement claims. No internal implementation details in public entries. Class O guarantees must be described as operational controls, not invariants.

Kernel Axiom Registry

docs/kernel/axioms.yml introduced as the single source of truth for all architectural invariants. The registry is machine-verifiable by design: every axiom carries its enforcement class, required and current layers, proof anchors with delivery status, and upgrade path where applicable.

Initial axioms registered:

  • AX-KERNEL-001 — Dual-Layer Enforcement Mandate (self-referential meta-axiom)
  • A1.1 — Absolute RLS
  • A1.2 — Mutation Containment
  • A2.1 — The Posted Set
  • A2.2 — State Machine Forward-Only
  • A4.1 — Audit Trail Completeness
  • L1.1 — Canonical Time Axis (Milestone 6)
  • M1.1 — Money Singularity
  • M1.2 — Sub-Penny Prohibition
  • D1.1 — Double-Entry Conservation
  • O1.1 — Rounding Policy Integrity (Class O, upgrade path to M3)
  • AX-AUD-001 — Audit JSON Canonical Form (Class O, upgrade path to M6)

A known ADR collision was identified and corrected: ADR-003 is the UIE hypothesis solver, not the rounding policy. The rounding policy ADR is pending assignment and must be written before Milestone 3 begins.

Session Bootstrap Documents

Two governed development session documents introduced:

  • speybooks-ai-bootstrap.md — canonical session brief covering system identity, invariant classification, milestone roadmap, monetary rules, deterministic SQL, concurrency model, audit requirements, and drift governance.

  • speybooks-m3-bootstrap.md — scoped brief for the Milestone 3 monetary domain migration session. Covers completed milestone state, M3 axiom targets, migration envelope skeleton, risk vectors, and deliverables in priority order.

Operational Impact

Governance: Every architectural invariant now has a stable ID, enforcement class, and proof anchor. Drift between documentation and implementation is detectable by CI.

Milestone readiness: M3 has a complete scoped brief. The ADR-003 collision is identified and corrected before it could produce a false proof anchor in production.

Changelog integrity: The completeness rule and proof anchor requirement close the gap between template and published record. Entries are engineering documents, not partially-filled forms.

Files Changed

Backend: None — no application code changed.

Governance:

  • docs/kernel/axioms.yml — kernel axiom registry v1.2, 12 axioms registered
  • docs/kernel/rls.md — canonical RLS predicate store introduced
  • docs/kernel/speybooks-ai-bootstrap.md — canonical session brief
  • docs/kernel/speybooks-m3-bootstrap.md — Milestone 3 scoped session brief
  • docs/dev/development-contract.md — development contract updated to v1.5

Milestone 3 — Monetary Domain Migration — is the next kernel release, converting all financial columns to integer pence and elevating rounding policy to a mechanically enforced database invariant.