T1-6 — Scoped Fact Change-History Endpoint (#674)

FactResourceKind { Income, Asset, Expense } (#[serde(rename_all="snake_case")], strum::Display/EnumString for the path param + CLI parse).

FactChangeEntry { action: String, fact_id: Uuid, version_id: Option<Uuid>, actor_sub: Option<String>, actor_role: Option<String>, claim_source: Option<String>, claim_status: Option<String>, before: serde_json::Value, after: serde_json::Value, recorded_at: DateTime<Utc>, event_hash: Option<String> } (Serialize+Deserialize+ToSchema; before/after opaque per-kind shapes — #[schema(value_type=Object)]; version_id/actor_* Option because a close carries no version_id and author:null). Roundtrip proptest.

paths.rs: FACT_CHANGE_HISTORY = "/v1/security/persons/{person_id}/fact-history/{resource}".

SELECT * FROM audit_events WHERE source_service='canopy-persons' AND resource_type=$1 AND metadata @> jsonb_build_object('person_id', $2::text) ORDER BY created_at ASC, decoded into the existing AuditEventRow via query_as (chain order; $2 bound as text — PersonId is #[serde(transparent)] (canopy-common/src/id.rs:41) so it lands as a top-level JSON string in the stored metadata (= the event payload clone, store/mod.rs:112), and a text param to jsonb_build_object becomes a JSON string → @> matches). Index: the GIN on metadata serves the @> containment; PG bitmap-ANDs it with the resource_type/source_service btree indexes — adequate at audit volume, no new index. recorded_at on the entry = the row’s created_at (the transaction-time the audit row was committed, ADR-027 §4 — NOT event_timestamp/envelope-creation).

As-built: a private project(person_id, AuditEventRow) → FactChangeEntry navigates the row’s already-typed metadata value (AuditEventRow.metadata is the only untyped-JSON field in canopy-security src) with method calls only — fact_id from resource_id; actor_sub/actor_role from the nested author.sub/author.author_type; version_id/claim_source/claim_status from top-level keys; and before/after are metadata.get("before"/"after") .cloned().unwrap_or_default() (a close carries no after → JSON null). This adds no new serde_json::Value literal to canopy-security src (no view struct, no to_value), so B3a stays flat — verified with quality-budgets (the regex counts comments too, so the type name is kept out of new doc comments). The earlier draft sketched a typed sqlx::types::Json<…View> decode; navigating the existing AuditEventRow.metadata is simpler and equally budget-safe, so the as-built took that path.

GET handler fact_change_history(Extension(claims), State, Pathperson_id, resource) → claims.is_service() || claims.require_admin()? (house auth); parse resource → FactResourceKind (400 on unknown); store::list_fact_change_history → Json<Vec<FactChangeEntry>>. #[utoipa::path(get, …, responses(200 body = Vec<FactChangeEntry>, 400, 401, 403))]; register on route_path(paths::FACT_CHANGE_HISTORY).

cargo xtask api-docs --update → the canopy-security snapshot gains one path.

A read path GET /cases/{household_id}/fact-history/{resource} (following the existing /cases/{household_id} case-detail route family) — gate: worker can access this case (existing case-access) AND session.in_program_scope(program) (the fact resources are cross-program generic facts — gate on the case, not a single program; if a per-program gate is wanted, default to "any in-scope program on the case", decide in review). Resolve household→members (household_full/batchGet, already loaded for case-detail), fan out per member to the canopy-security endpoint with_service_identity concurrently (futures::future::join_all — N members is small, parallel keeps latency flat), merge + sort by recorded_at, into the composed Vec<FactChangeEntry>. One typed SecurityClient::fact_history test-lib method (B7 untyped-client budget is 0 — add it typed).

UI (the parity half): a case-detail "Change history" section (an Askama template + an HTMX-loaded partial off the read path, matching the existing case-detail section pattern — e.g. the Audit section, api/audit_log.rs) rendering the ordered entries (actor, action, source/status, before→after, timestamp) grouped by fact. Read-only display; the fact-AUTHORING editors (add/correct/close) are T1-8. Light + dark.

Integration (canopy-security/tests/fact_change_history_test.rs, devstack-gated): via the persons API (the real producer) author an income claim → a correcting claim → a close on one fact; poll_until the three audit_events rows land (async subscriber); GET the canopy-security endpoint; assert the ordered entries — claim (before [], after v1), claim (before=[v1], after=v2, the correction), close (actor null, before=[v2]). A second person isolates the metadata→>'person_id' filter (no cross-person bleed). asset + expense claim each surface once.

Unit: the store projection (claimed vs closed shape → entry, null author); the canopy-web scope gate (out-of-scope worker → denied); contracts roundtrip.

E2E (Playwright, the UI parity gate): a case-detail "Change history" section spec — author facts via the seed/API, open the case, assert the section renders the ordered attributed entries (actor, before→after); light + dark.

Docs: api/canopy-security.adoc (the new endpoint + the attributable-not-tamper-evident posture + the BFF-composes-household note); services.adoc canopy-security line (publishes nothing new — it now exposes fact change-history); plan Status flips; CHANGELOG.adoc == Unreleased; api-docs --update (snapshot delta committed) + quality-budgets (flat).