reeve 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67bc82ca855e0385d021e54477cbcfcef697a1134d3c93e4fc073fea2ff3b748
-  data.tar.gz: 0c11093e604b6a056a23bec7ebd419620d4dd1780f93ff7e30fc8a08bdbd92d3
+  metadata.gz: 03d0a3695140d0703272da744486caa3ab21530eddb0d48d275977e3b83047c0
+  data.tar.gz: aa8988dd9d7fc1dfb40b5c7a67f1f0a9f70d5ba72350b7669ba32afb2121f140
 SHA512:
-  metadata.gz: 0524a6cd7376dc9cc8b7f2611d4a0a6a8b1fa81b6b5ff59ab662d3e5f5f313b4f47e7ad5b2d52d272da8bab1f1c19042ae937300beb382f57804f2fc72b77d3e
-  data.tar.gz: 4ead6c668edcde8b543c1e4ead9817e08015ecbf42adfbc34d44c5fa31426206284efb3ffdd88dad4cd983033be7708e256ac9cc2e5eb4758a6fc92f2ac14a19
+  metadata.gz: 116dbf0359f8666ffa50cb70a9a85aa7a037d76390305b3315fc4ecc37233fe83a5faabb14103c0ae999ae69f5cc5fa020813cd7da3ade8ae86f837639604c98
+  data.tar.gz: 4ae861908807ec1bc3b3363442edda7cf6936d60d01e39b5aa03f6ae91cd7e0daad49ac8a154a53db277894c866cf9adfdb2e8776d99071b20d6d4704647f4b0

data/CHANGELOG.md

@@ -4,6 +4,111 @@ All notable changes are recorded here. This project follows [Semantic
 Versioning](https://semver.org), with one rule specific to what it does — see
 [Versioning policy](#versioning-policy).
 
+## [0.6.0] - 2026-10-10
+
+The ledger has been append-only at the library level since 0.1.0: no API updates or deletes
+an entry, and the generated migration documents the grant that enforces the rest. Nothing
+*detected* a change made outside the library. A DBA, a stolen application credential or a
+well-meant data fix could edit, delete or reorder rows, and the ledger read exactly as
+before. Now every row is chained to the one before it with a keyed digest, and
+`bin/rails reeve:verify_ledger` reports every place the chain no longer holds.
+
+**Audit-entry contract `2` → `3`, and a migration is required.** The new columns are
+nullable, so the shape change is additive; the bump is MAJOR by the contract's own rule,
+because what an absence means changed. On a contract 1–2 row a NULL digest means "written
+before chaining"; on a contract-3 row it means the row was written unchained, which
+verification reports. Upgrading is three steps:
+
+```bash
+bin/rails generate reeve:upgrade
+bin/rails db:migrate
+```
+
+then add the line the generator prints to `config/initializers/reeve.rb`:
+
+```ruby
+config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+```
+
+Existing rows are not touched. They are reported as "not covered" from then on, and are
+exactly as trustworthy as they were before.
+
+What this detects and what it does not are set out in the README, under "Tamper-evident,
+within stated limits". In short, it does **not** detect a change made by someone holding
+the key; the newest rows deleted by someone who also rewinds the chain record's head; the
+whole ledger deleted (reported as *no chain*, never as a pass); or anything about rows
+written before the upgrade. It detects; it does not prevent.
+
+Behaviour changes worth reading before upgrading:
+
+- **A ledger key is required.** Without one, every guarded call fails with
+  `Reeve::AuditWriteError` (cause `Reeve::LedgerKeyError`, naming the setting). Under
+  `audit_failure_mode = :warn` the call goes through and the row is written *unchained*, a
+  warning is logged on every such write, and verification reports the row.
+- **Rotating `secret_key_base` rotates the ledger key**, if you keep the generated line. Put
+  the old derived key in `config.retired_ledger_keys`, or entries it signed become
+  unverifiable — reported as such, never as tampered. A dedicated key avoids the coupling.
+- **Writes serialize on the chain record.** About 0.5 ms more per ledger write on SQLite and
+  about 1 ms on PostgreSQL. Under the default recorder inside a transaction the host opened,
+  the lock is held until that transaction ends; `IsolatedRecorder` holds it for one insert.
+- **Rails 7.0 with SQLite:** sqlite3 1.x waits for the write lock while holding Ruby's GVL,
+  so concurrent guarded calls in one process can fail closed after the busy timeout. Rails
+  7.1+ or a server database avoids it. The limit predates this release; the chain's longer
+  write makes it likelier.
+- **The compliance suites run one more check, `LedgerChain`.** It writes an entry of its own
+  and fails without a key, on a broken or unverifiable chain, or on unchained entries. It is
+  skipped, saying so, when there is no compliance tool to write with or no ledger loaded.
+  The test environment needs the key line too; the generated one works there unchanged.
+- **Breaking for custom recorders** that write to `Reeve::Audit::Entry`: rows must be written
+  through `Reeve::Audit::Chain#append!` (or `#append_unchained!` to keep running without a
+  key), or verification reports them as unchained.
+- **A table still at contract 2** now fails with `Reeve::ConfigurationError` naming
+  `reeve:upgrade`, instead of a column error from inside the write.
+- **Known limit, MySQL:** a number in a tool's arguments beyond double precision is stored
+  rounded by MySQL's `JSON` type, and its row then fails to verify. A false alarm, never a
+  false pass.
+- **During a rolling deploy**, servers still on 0.5.0 keep writing contract-2 rows. They
+  are counted as not covered, not reported as tampering.
+
+### Added
+
+- **The ledger chain** (`Reeve::Audit::Chain`). Every entry carries a sequence number, the
+  16-character fingerprint of the key that signed it, and an HMAC-SHA256 digest over its
+  canonical form and its predecessor's digest. The digest is computed over the values the
+  database stores — defaults, casts and JSON normalization included — so a row verifies
+  after a dump and restore with every primary key renumbered.
+- **`Reeve::Audit::Chain.verify`** (optionally with `keys:`, for an auditor's own copy of the
+  key) and **`bin/rails reeve:verify_ledger`**, registered by a Railtie that loads only when
+  Rails is present. Exit status `0` intact, `1` broken, `2` could not verify; `LIMIT=` caps
+  the breaks listed, never the totals; `FORMAT=json` writes every break. Every line that
+  says *intact* or *pass* states the covered range and the uncovered count beside it.
+  `Reeve::Tasks.verify_ledger` is the same check without Rake.
+- **`config.ledger_key`** and **`config.retired_ledger_keys`**, validated at assignment (32
+  bytes minimum) and shown only as fingerprints in `to_h`, `inspect`, logs and reports.
+- **`Checks::LedgerChain`**, in both compliance suites.
+- **`reeve:upgrade`**'s contract-3 step, which prints the initializer line, the rotation
+  warning and how to build the new index concurrently on a large PostgreSQL ledger. A step
+  now counts as applied only when its columns and its tables both exist.
+
+### Fixed
+
+- **A per-tool compliance check with no tools to check is skipped, not passed.** With no
+  tool registered, `compliance_tools` set to `[]`, or `tools: []`, `Reeve::Checks.run`
+  returned an empty `Report` — which reads as passed — so the RSpec shared group and
+  `ComplianceAssertions` showed all six per-tool checks green over zero tools. Each now
+  returns one skipped result, "no compliance tools to check, so GuardDeclared established
+  nothing — the registry is empty and no endpoint inventory routes a tool" (or `the run was
+  given tools: []`, or `compliance_tools is []`), shown as pending in RSpec and as a skip
+  in Minitest. Over an empty registry `run_all` used to report only the ledger-wide checks
+  (two in 0.5.0); it now also reports the six per-tool skips. Nothing that ran over at
+  least one tool changes.
+- **The framework-free gate fails when a check had nothing to check.** The README's
+  `abort report.to_s unless report.passed?` stayed green over zero tools, because a skip is
+  not a failure. The documented gate is now
+  `abort report.to_s if report.failed? || report.nothing_checked?`, using the new
+  `Report#nothing_checked?`. A skip for a missing inventory does not trip it.
+
+
 ## [0.5.0] - 2026-10-01
 
 Reeve protects the tools routed through it, and only those. A server that registers its
@@ -412,4 +517,4 @@ is for:
 - Adding a nullable ledger column is minor and leaves the audit-entry contract version
   alone. Removing or renaming a column, or changing what a value means, is major and bumps
   it.
-- The audit-entry contract version is `2`.
+- The audit-entry contract version is `3`.

data/README.md

@@ -7,7 +7,7 @@ A Ruby gem that makes it safe for a Rails application to expose MCP tools to AI
 declarative per-record authorization, an append-only audit ledger, and a testing kit that
 proves both hold.
 
-> **Status: 0.5.0.** Read the known limitations in
+> **Status: 0.6.0.** Read the known limitations in
 > [CHANGELOG.md](CHANGELOG.md) before adopting it — particularly the one about a
 > transaction wrapped around an invocation, if your application wraps requests in one.
 
@@ -52,7 +52,10 @@ end
 ```
 
 Until that resolver is set, every guarded call denies with `no_principal`. That is the
-intended behaviour: the library is safe before it is configured.
+intended behaviour: the library is safe before it is configured. The initializer also
+derives the key that chains the audit ledger from `secret_key_base`, so that works in
+every environment with nothing to set up — see [Tamper-evident, within stated
+limits](#tamper-evident-within-stated-limits).
 
 **2. Guard a tool.**
 
@@ -186,6 +189,108 @@ transaction holds the write lock; `IsolatedRecorder.available?` lets you branch
 develop on one and deploy on the other. The default recorder warns when it detects the
 case rather than failing silently.
 
+## Tamper-evident, within stated limits
+
+Every row Reeve writes is linked to the one before it by a keyed digest (HMAC-SHA256), with
+a key the database does not hold. Someone who can write to the ledger table but does not
+hold the key can still change it, but the change shows when the chain is checked:
+
+```bash
+bin/rails reeve:verify_ledger
+```
+
+```text
+reeve ledger: INTACT — sequences 1–48,211 verified (head at start: 48,211); 5,000 earlier entries not covered (5,000 when the chain started)
+```
+
+It exits `0` when the chain is intact, `1` when it is broken, and `2` when it could not
+verify (no chain, no key, or rows signed by a key it does not hold). Run it on a schedule
+and alert on anything but `0`. `LIMIT=` caps the breaks it lists, never the totals;
+`FORMAT=json` writes every break. The same answer from Ruby, or with an auditor's own copy
+of the key:
+
+```ruby
+result = Reeve::Audit::Chain.verify
+result.status   # => :intact, :broken, :unverifiable or :no_chain
+result.covered  # => 1..48211
+puts result     # the report above, with every break listed under it
+```
+
+In CI the compliance suite you already run includes `LedgerChain`, in both frameworks:
+it writes entries of its own and fails on a broken chain, a missing key, or entries that
+were not chained.
+
+**The key.** The generated initializer derives it from `secret_key_base`:
+
+```ruby
+config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+```
+
+Rotating `secret_key_base` therefore rotates the ledger key. Keep the old one, or the
+entries it signed become *unverifiable* — reported as such, never as tampered:
+
+```ruby
+config.retired_ledger_keys = [old_key]   # verify with these; never sign with them
+```
+
+A dedicated key decouples the two: `config.ledger_key = Rails.application.credentials.reeve_ledger_key`.
+Keys must be at least 32 bytes and are only ever printed as 16-character fingerprints.
+Without a key, every guarded call fails closed; under `audit_failure_mode = :warn` it is
+recorded unchained instead, logged each time, and reported by verification.
+
+**Detected**, provided the key has not leaked:
+
+- a chained row whose recorded content was changed;
+- a chained row removed from anywhere before the newest one;
+- chained rows swapped, renumbered or moved, or a row inserted that Reeve did not write —
+  including one numbered past the head;
+- the newest rows removed while the chain record was left alone;
+- the chain record removed while chained rows remain.
+
+**Not detected** — stated plainly, because these are the limits of the guarantee:
+
+1. **A leaked key.** Anyone holding it can rewrite the chain from any point forward. By
+   default that is anyone holding `secret_key_base`.
+2. **The newest rows deleted by someone who also rewinds the chain record's head.** Only a
+   checkpoint held outside the database could catch that; Reeve does not ship one.
+3. **The whole ledger deleted, chain record included.** Reported as *no chain*, never as a
+   pass — but indistinguishable from a ledger that was never chained.
+4. **Rows written before you upgraded.** They are counted as "not covered" and are exactly
+   as trustworthy as they were before.
+
+And it prevents nothing: it detects a change after the fact. The `GRANT INSERT, SELECT` in
+the generated migration is what prevents one. The chain record needs `UPDATE` as well,
+which is why a role allowed to rewind it is limit 2.
+
+**What it costs.** About half a millisecond per ledger write on SQLite and about one on
+PostgreSQL. Every chained write locks the chain record, so writes serialize. Under the
+default recorder inside a transaction your application opened, that lock is held until the
+transaction ends, and every other guarded call waits behind it — up to the database's own
+lock wait: indefinitely on PostgreSQL (`lock_timeout` is 0 by default), 50 seconds on MySQL
+(`innodb_lock_wait_timeout`), and ActiveRecord's `timeout` on SQLite (5 seconds in a
+generated `database.yml`). `IsolatedRecorder` holds it for the length of one insert. On
+**Rails 7.0 with SQLite**, a thread waiting for SQLite's write lock holds Ruby's GVL
+(sqlite3 1.x), so concurrent guarded calls in one process can fail closed after the busy
+timeout. Rails 7.1+ or a server database avoids it.
+
+**Your own recorder.** A recorder that writes to Reeve's table chains its rows through the
+same door the built-in ones use, or verification reports them as unchained:
+
+```ruby
+Reeve::Audit::Chain.new(entry_class: Reeve::Audit::Entry).append!(row)
+```
+
+**Upgrading from 0.5.0:**
+
+```bash
+bin/rails generate reeve:upgrade
+bin/rails db:migrate
+```
+
+Then add the `config.ledger_key` line the generator prints. Existing rows are not touched;
+the next guarded call starts the chain. Servers still on 0.5.0 during a rolling deploy keep
+writing unchained rows, which are counted as not covered rather than reported as tampering.
+
 ## Provable in CI, in whichever framework you already use
 
 All the logic lives in framework-neutral checks. RSpec and Minitest are thin front-ends
@@ -223,11 +328,13 @@ script, or a boot-time assertion in staging:
 require "reeve/testing"
 
 report = Reeve::Checks.run_all(principals: [alice, bob])
-abort report.to_s unless report.passed?
+abort report.to_s if report.failed? || report.nothing_checked?
 ```
 
 `alice` and `bob` are two fixture principals with disjoint records — that disjointness is
-what makes a shared record identifier proof of a leak.
+what makes a shared record identifier proof of a leak. `passed?` only means nothing failed,
+so a run over no tools at all passes; `nothing_checked?` is what stops this gate when the
+registry is empty, since a script has no pending test to show it.
 
 **The suite walks every tool that included `Reeve::Guard`, not only the ones that declared
 a guard.** A tool that forgot `guard_with` is the one worth finding, and it is absent from
@@ -257,7 +364,7 @@ namespace :reeve do
     require "reeve/testing"
 
     report = Reeve::Checks.run_all(principals: Reeve::Testing.compliance_principals)
-    abort report.to_s unless report.passed?
+    abort report.to_s if report.failed? || report.nothing_checked?
     puts report
   end
 end
@@ -470,7 +577,7 @@ ActiveRecord unless they are not — a plain object with an `id` works.
 ## What you have not gained
 
 Rate limiting, prompt-injection defence, cost control, and connection authentication are
-out of scope. This library governs *what an authenticated agent may touch* and *what it
+out of scope, and the ledger's chain detects tampering rather than preventing it. This library governs *what an authenticated agent may touch* and *what it
 touched*. Keep your existing auth.
 
 Ruby 3.0+, Rails 7.0+. No runtime dependencies. The fast-mcp adapter needs Ruby 3.1+,

data/lib/generators/reeve/install/templates/create_audit_entries.rb.tt

@@ -13,12 +13,23 @@
 #   REVOKE ALL   ON reeve_audit_entries FROM app_role;
 #   GRANT INSERT, SELECT ON reeve_audit_entries TO app_role;
 #   GRANT USAGE  ON SEQUENCE reeve_audit_entries_id_seq TO app_role;
+#   -- the chain record: its head moves on every write
+#   GRANT INSERT, SELECT, UPDATE ON reeve_audit_chains TO app_role;
+#   GRANT USAGE  ON SEQUENCE reeve_audit_chains_id_seq TO app_role;
+#
+# Every row is chained to the one before it with a keyed digest (audit-entry contract 3),
+# so a row changed, removed or reordered outside reeve is reported by
+# `bin/rails reeve:verify_ledger`. That is tamper-evidence, not tamper-proofing: it
+# detects a change after the fact and prevents nothing — the grant above is what
+# prevents. It does not detect a change made by someone holding the ledger key, nor the
+# newest rows being deleted by a role that can also rewind the head in
+# reeve_audit_chains; that role needs UPDATE there, which is why the chain table is
+# granted separately from the ledger.
 #
 # Also explicitly out of scope for now, so you can plan around it:
 #   * no retention, rotation or archival — this table grows until you prune it, and
-#     pruning is your policy, run by a role that is allowed to delete;
-#   * no cryptographic chaining or tamper-evidence. If that lands later it arrives as a
-#     nullable column, which the audit-entry contract's versioning already permits.
+#     pruning is your policy, run by a role that is allowed to delete. Deleting rows
+#     breaks the chain by design.
 #
 # `invocation_id` is a UUID stored as a string rather than a native `uuid` column,
 # because reeve supports every database ActiveRecord does and only PostgreSQL has the
@@ -61,6 +72,13 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
       # it means "the caller passed none". Stamping each row keeps an export readable
       # across an upgrade instead of collapsing that distinction.
       t.integer  :contract_version, null: false
+
+      # The chain (contract 3). Nullable: a row written before the chain began has no
+      # honest value for these, and nothing is backfilled into an append-only table.
+      # `chain_key_id` is the key's fingerprint, never the key.
+      t.bigint   :chain_sequence
+      t.string   :chain_key_id,   limit: 16
+      t.string   :chain_digest,   limit: 64
     end
 
     add_index :reeve_audit_entries, :invocation_id, unique: true
@@ -73,5 +91,25 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
     add_index :reeve_audit_entries, %i[tool_name occurred_at]
     add_index :reeve_audit_entries, %i[agent_id occurred_at]
     add_index :reeve_audit_entries, %i[outcome occurred_at]
+
+    # One position, one row. NULLs are distinct, so unchained rows never collide; the
+    # index also orders the walk `reeve:verify_ledger` makes.
+    add_index :reeve_audit_entries, :chain_sequence, unique: true
+
+    # The chain record: one row. The genesis columns are written once, when the first
+    # chained entry is; the head moves with every chained write, in the same transaction
+    # as the row it points at.
+    create_table :reeve_audit_chains do |t|
+      t.string   :name,                      null: false
+      t.datetime :genesis_at,                null: false, precision: 6
+      t.bigint   :pre_chain_count,           null: false
+      t.bigint   :pre_chain_unchained_count, null: false
+      t.string   :genesis_key_id,            null: false, limit: 16
+      t.string   :genesis_digest,            null: false, limit: 64
+      t.bigint   :head_sequence,             null: false
+      t.string   :head_digest,               null: false, limit: 64
+    end
+
+    add_index :reeve_audit_chains, :name, unique: true
   end
 end

data/lib/generators/reeve/install/templates/initializer.rb.tt

@@ -72,6 +72,26 @@ Reeve.configure do |config|
   #
   # Left unset, which resolves to Reeve::Audit::Recorder.
 
+  # ---------------------------------------------------------------------------
+  # The key that chains the audit ledger, so a row changed, removed or reordered
+  # outside reeve is reported by `bin/rails reeve:verify_ledger`. It must live
+  # outside the database: someone who can write the table but does not hold the
+  # key cannot forge the chain.
+  #
+  # Derived from secret_key_base, it works in every environment — test included —
+  # with no new secret to provision. Without a key, every guarded call fails
+  # closed (or, under audit_failure_mode :warn, is recorded unchained).
+  config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+
+  # Rotating secret_key_base rotates this key too. Keep the old one here, or the
+  # entries it signed become unverifiable (reported as such, never as tampered):
+  #
+  #   config.retired_ledger_keys = [old_key]
+  #
+  # Or use a dedicated key, so secret_key_base can rotate on its own schedule:
+  #
+  #   config.ledger_key = Rails.application.credentials.reeve_ledger_key
+
   # Cap on how many record identifiers one entry stores. The true count is
   # always recorded, and the entry says when the list was truncated.
   config.max_recorded_ids = 1000

data/lib/generators/reeve/upgrade/templates/add_ledger_chain_to_reeve_audit_entries.rb.tt

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Audit-entry contract 2 → 3. Generated by `bin/rails generate reeve:upgrade`.
+#
+# Chains every row reeve writes from here on to the one before it with a keyed digest, so a
+# row changed, removed or reordered outside reeve is reported by
+# `bin/rails reeve:verify_ledger`.
+#
+# Rows already in the table are not touched: there is no honest digest to give a row
+# nobody was there to sign, and nothing is backfilled into an append-only table. They are
+# reported as "not covered" from now on — exactly as trustworthy as they were before this
+# migration, and no more. The three columns are nullable for that reason.
+#
+# The chain needs a key, held outside the database. Add this to
+# config/initializers/reeve.rb, or every guarded call fails closed after you migrate:
+#
+#   config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+#
+# The chain record's head moves on every write, so the role your application connects as
+# needs UPDATE on reeve_audit_chains (the ledger itself stays INSERT, SELECT):
+#
+#   GRANT INSERT, SELECT, UPDATE ON reeve_audit_chains TO app_role;
+#
+# A role holding that UPDATE can rewind the head, and a rewound head hides the deletion of
+# the newest rows. Tamper-evidence detects a change after the fact; the grants are what
+# prevent one.
+#
+# On a very large ledger, the unique index below scans the table once. On PostgreSQL that
+# scan blocks writes for its duration; to avoid it, add `disable_ddl_transaction!` to this
+# class and `algorithm: :concurrently` to the add_index call.
+class AddLedgerChainToReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    add_column :reeve_audit_entries, :chain_sequence, :bigint
+    add_column :reeve_audit_entries, :chain_key_id,   :string, limit: 16
+    add_column :reeve_audit_entries, :chain_digest,   :string, limit: 64
+    add_index  :reeve_audit_entries, :chain_sequence, unique: true
+
+    create_table :reeve_audit_chains do |t|
+      t.string   :name,                      null: false
+      t.datetime :genesis_at,                null: false, precision: 6
+      t.bigint   :pre_chain_count,           null: false
+      t.bigint   :pre_chain_unchained_count, null: false
+      t.string   :genesis_key_id,            null: false, limit: 16
+      t.string   :genesis_digest,            null: false, limit: 64
+      t.bigint   :head_sequence,             null: false
+      t.string   :head_digest,               null: false, limit: 64
+    end
+
+    add_index :reeve_audit_chains, :name, unique: true
+  end
+end

data/lib/generators/reeve/upgrade/upgrade_generator.rb

@@ -33,15 +33,29 @@ module Reeve
       # contracts/audit-entry.md, which exists so that stays hypothetical: an append-only
       # ledger cannot be backfilled, so a column that is not additive has no honest value
       # to give the rows already written.
+      # `creates` names any table a step builds. A step is applied only when every column it
+      # adds and every table it creates exist: a ledger with one half and not the other is
+      # half-migrated, and calling it current would leave the host with no way forward.
       STEPS = [
         {
           contract: 2,
           adds: %w[contract_version],
+          creates: [],
           template: "add_contract_version_to_reeve_audit_entries.rb.tt",
           destination: "add_contract_version_to_reeve_audit_entries.rb"
+        },
+        {
+          contract: 3,
+          adds: %w[chain_sequence chain_key_id chain_digest],
+          creates: %w[reeve_audit_chains],
+          template: "add_ledger_chain_to_reeve_audit_entries.rb.tt",
+          destination: "add_ledger_chain_to_reeve_audit_entries.rb"
         }
       ].freeze
 
+      KEY_LINE = "config.ledger_key = " \
+                 'Rails.application.key_generator.generate_key("reeve audit ledger", 32)'
+
       source_root File.expand_path("templates", __dir__)
 
       desc "Brings an existing reeve audit ledger up to the current audit-entry contract."
@@ -93,7 +107,7 @@ module Reeve
       end
 
       def pending_message
-        <<~NEXT
+        message = <<~NEXT
 
           #{@emitted.size} migration#{'s' if @emitted.size != 1} written, taking the ledger
           to audit-entry contract #{@emitted.last[:contract]}. Run:
@@ -103,13 +117,37 @@ module Reeve
           Existing rows are stamped with the contract they were actually written under,
           not with the current one.
         NEXT
+        message += chain_message if @emitted.any? { |step| step[:contract] == 3 }
+        message
+      end
+
+      # Contract 3 changes what the application must configure, not only the table: without
+      # a key, every guarded call fails closed once the migration runs. The host is reading
+      # this output at exactly the moment they need to know that.
+      def chain_message
+        <<~CHAIN
+
+          The ledger is now chained (contract 3). Add this line to config/initializers/reeve.rb
+          before you deploy, or every guarded call fails closed:
+
+            #{KEY_LINE}
+
+          It derives the key from secret_key_base, so rotating secret_key_base rotates the
+          ledger key: keep the old derived key in config.retired_ledger_keys, or entries it
+          signed become unverifiable. A dedicated key avoids that coupling.
+
+          Very large ledger on PostgreSQL? The migration builds a unique index that blocks
+          writes while it scans; the migration's header shows how to build it with
+          algorithm: :concurrently instead.
+        CHAIN
       end
 
       # Asked of the table rather than of a version the host recorded: the table is the
       # thing being changed, and it is the only party that cannot be out of date about
       # itself.
       def applied?(step)
-        (step[:adds] - existing_columns).empty?
+        (step[:adds] - existing_columns).empty? &&
+          step[:creates].all? { |table| connection.table_exists?(table) }
       end
 
       def existing_columns

data/lib/reeve/audit/chain/canonical.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "json"
+require "openssl"
+
+module Reeve
+  module Audit
+    class Chain
+      # The exact text a digest is computed over (specs/002 FR-002, FR-003; research R1, R2
+      # step 2; data-model "Canonical entry").
+      #
+      # Computed once when a row is written and again, from what the database returns,
+      # when it is verified — so everything here exists to make those two readings produce
+      # identical text:
+      #
+      # * object keys sorted at every depth, so a database that reorders JSON keys
+      #   (PostgreSQL jsonb, MySQL JSON) changes nothing;
+      # * one spelling per number, so `1.0e+20` written and `100000000000000000000` read
+      #   back are the same number;
+      # * times as integer microseconds since the epoch, so neither the time zone nor the
+      #   driver's Time class matters;
+      # * strings, booleans and nil typed, so "1" and 1 never digest alike.
+      #
+      # The field list is written out rather than read from the table — a check that
+      # derives its expectation from the thing it checks checks nothing — and is keyed by
+      # contract version, so a future column joins the digest for rows written under that
+      # contract only. The tags keep an entry digest and a genesis digest from ever being
+      # interchangeable, and let a future canonical form be told apart from this one.
+      module Canonical
+        ENTRY_TAG = "reeve-ledger-entry-v1"
+        GENESIS_TAG = "reeve-ledger-genesis-v1"
+
+        ENTRY_FIELDS = {
+          3 => %w[
+            chain_sequence chain_key_id contract_version
+            invocation_id occurred_at agent_id agent_name principal_type principal_id
+            tool_name arguments outcome rule detail record_type record_ids record_count
+            truncated derived guard duration_ms metadata
+          ].freeze
+        }.freeze
+
+        GENESIS_FIELDS = %w[genesis_at pre_chain_count pre_chain_unchained_count
+                            genesis_key_id].freeze
+
+        TIME_FIELDS = %w[occurred_at genesis_at].freeze
+
+        module_function
+
+        def entry_digest(secret, row, previous_digest:)
+          hmac(secret, ENTRY_TAG, entry_message_body(row, previous_digest))
+        end
+
+        def genesis_digest(secret, genesis)
+          pairs = GENESIS_FIELDS.map { |field| [field, value(genesis, field)] }
+          hmac(secret, GENESIS_TAG, dump(pairs))
+        end
+
+        def entry_message_body(row, previous_digest)
+          version = value(row, "contract_version")
+          fields = ENTRY_FIELDS.fetch(version) do
+            raise ArgumentError,
+                  "there is no canonical field list for audit-entry contract " \
+                  "#{version.inspect}; only contract " \
+                  "#{ENTRY_FIELDS.keys.join(', ')} rows are chained"
+          end
+
+          pairs = fields.map { |field| [field, value(row, field)] }
+          dump([["previous_digest", previous_digest], *pairs])
+        end
+
+        def microseconds(time)
+          (time.to_r * 1_000_000).floor
+        end
+
+        def dump(value)
+          case value
+          when Array then "[#{value.map { |item| dump(item) }.join(',')}]"
+          when Hash then object(value)
+          else scalar(value)
+          end
+        end
+
+        def scalar(value)
+          case value
+          when nil, true, false then value.nil? ? "null" : value.to_s
+          when Integer, Float, BigDecimal then number(value)
+          when String, Symbol then JSON.generate(value.to_s)
+          else
+            raise ArgumentError,
+                  "#{value.class} has no canonical form; normalize it before it is digested"
+          end
+        end
+
+        def object(hash)
+          pairs = hash.map { |key, item| [key.to_s, item] }.sort_by(&:first)
+          "{#{pairs.map { |key, item| "#{JSON.generate(key)}:#{dump(item)}" }.join(',')}}"
+        end
+
+        # The shortest exact decimal: no exponent, no trailing zeros, no "-0".
+        def number(value)
+          if value.is_a?(Float) && !value.finite?
+            raise ArgumentError,
+                  "a non-finite number has no canonical form; normalize it before it is digested"
+          end
+
+          decimal = value.is_a?(Float) ? BigDecimal(value.to_s) : BigDecimal(value)
+          return "0" if decimal.zero?
+          return decimal.to_i.to_s if decimal.frac.zero?
+
+          decimal.to_s("F")
+        end
+
+        def value(row, field)
+          raw = if row.is_a?(Hash)
+                  row.key?(field) ? row[field] : row[field.to_sym]
+                else
+                  row[field]
+                end
+          TIME_FIELDS.include?(field) && !raw.nil? ? microseconds(raw) : raw
+        end
+
+        def hmac(secret, tag, body)
+          OpenSSL::HMAC.hexdigest("SHA256", secret, "#{tag}\n#{body}")
+        end
+      end
+    end
+  end
+end