T2-5 — Audit Chain-Hash Hardening (actor + before/after tamper-evidence) (#686)

Per-row versioning is mandatory. The chain formula is append-only and load-bearing; changing it retroactively would un-verify every existing row. A new hash_version SMALLINT column (DEFAULT 1 backfills history; SET DEFAULT 2 for future) lets compute_event_hash + verify_chain dispatch per row. v1 = the current formula, bytes unchanged; new rows are v2. Mixed v1/v2 chains verify. Zero churn for history is a hard gate.

v2 = JCS over a typed struct, not a delimiter-free concat. A no-delimiter concatenation with a "NONE" null-sentinel is genuinely ambiguous (field-boundary shifts; None vs Some("NONE") collisions). v2 mirrors DeterminationSnapshot::canonical_bytes: a #[derive(Serialize)] struct AuditChainInputsV2 hashed via Sha256::digest(serde_jcs::to_vec(&inputs)?) (RFC 8785) — named keys, None→JSON null, no sentinel, no boundary ambiguity, and metadata is a field (no separate metadata-hash).

v2 covers the full reader-visible + scoping set. Fields: previous_hash, event_id, event_type, timestamp (canonical), user_id, user_role, action, resource_type, resource_id, source_service, household_id, metadata. source_service scopes fact-history selection and household_id scopes case-audit reads, so both must be hashed or a privileged rewrite could move/hide events from those views.

JSONB round-trip closed by construction. The chain hashes metadata at insert and re-hashes at verify; a non-integer float could round-trip through Postgres JSONB differently. At insert the metadata is normalized through Postgres once (SELECT $1::jsonb) and that normalized value is both hashed and stored, so verify re-hashes the identical bytes — for any JSON, including floats.

Verification is server-side / DB-level. verify_chain recomputes per the row’s hash_version (a DB column). The wire event_hash stays an opaque integrity token (it was never independently recomputable from the DTO — the DTO omits previous_hash/event_id/…), so hash_version is not exposed on the wire. No contract/OpenAPI change.

Typed error. A local AuditHashError (thiserror) wraps the JCS serde_json::Error and the unknown-version case; insert maps it into sqlx::Error::Encode(Box::new(e)), verify maps it to its inner (id, String) chain-break — `verify_chain’s public signature is unchanged (historic-signature preservation).

Deterministic ordering. clock_timestamp() is microsecond-precision; ties are possible. Insert’s previous-hash lookup and verify’s walk both order by created_at, id (UUIDv7 tie-break) so the chain order is deterministic.

Migration services/canopy-security/migrations/<ts>_add_audit_hash_version.sql — both audit_events + audit_events_archive: ADD COLUMN hash_version SMALLINT NOT NULL DEFAULT 1 then ALTER COLUMN hash_version SET DEFAULT 2. SPDX header; timestamp sorts after 20260603120000. DDL is not blocked by the append-only guard; DEFAULT 1 backfills via catalog metadata (no row UPDATE).

Cargo services/canopy-security/Cargo.toml — serde_jcs.workspace = true
thiserror.workspace = true (deps), proptest.workspace = true (dev-dep).

Hash (store/mod.rs) — compute_event_hash_v1(prev, event_id, event_type, canonical_ts: &str) keeps the current update sequence verbatim (the .format(…​) lifts to the caller; bytes unchanged); add AuditHashError, AuditChainInputsV2<'a>, compute_event_hash_v2(&inputs) → Result<String, AuditHashError> (format!("{:x}", Sha256::digest(serde_jcs::to_vec(&inputs)?))), and a compute_event_hash(version, &inputs) dispatcher (other ⇒ UnknownVersion).

Insert (store/mod.rs insert_audit_event) — previous-hash lookup ORDER BY created_at DESC, id DESC LIMIT 1; SELECT $1::jsonb normalize; build AuditChainInputsV2; compute_event_hash(2, …).map_err(|e| sqlx::Error::Encode(Box::new(e)))?; bind normalized metadata + hash_version = 2.

Row model (store/models.rs) — pub hash_version: i16.

Verify (store/mod.rs verify_chain) — walk ORDER BY created_at ASC, id ASC; per-row rebuild the struct + dispatch; AuditHashError → inner break; add the contiguous leading NULL-event_hash genesis-prefix skip (ADR-014 FTI precedent verify_fti_chain); preserve #[expect(clippy::assigning_clones)].

Tests (in the store/mod.rs #[cfg(test)] module, reusing reset_chain_pool()
sample_event() + the maintenance-window tamper pattern) — see Verification.

Docs — ADR-014 Amendment 1, data-models/canopy-security.adoc, api/canopy-security.adoc, CHANGELOG.adoc, the master plan, and this plan’s Status.