feat(gateway): audit read API + chain verification (Step 6.6a)

[officialCodeWork]

Summary

First of two slices for Step 6.6 — Immutable audit log. Step 0.7c shipped the foundation (append-only AuditStore SPI, NoopAuditStore SHA-256 hash chain, AuditWriter), but the log was write-only — only the corpus router wrote corpus.route, into a store nothing could read or verify. 6.6a makes it usable + provably intact.

• One shared audit store. build_app creates a single AuditWriter over a hash-chain store, exposes app.state.audit_store / audit_writer / audit_enabled, and hands the same writer to the corpus router — so events the writers append land in exactly the store the read API serves (before this, the corpus router held a private NoopAuditStore the gateway couldn't read). New AuditWriter.store accessor; default in-memory NoopAuditStore, production injects a durable one.
• GET /v1/audit — tenant-scoped (a principal sees only its own tenant's events, filtered by ctx.tenant_id at the boundary, same pattern as GET /v1/query/{id}/trace), newest-first, bounded by limit ([1,1000]), optional action / outcome filters. AuditListResponse carries chain_verified so one read both returns the events and attests the log is untampered.
• GET /v1/audit/verify — whole-log hash-chain integrity (the chain is one global sequence across tenants), returning {ok, event_count} — a boolean + total, no event content, so global verification leaks nothing cross-tenant.
• The hash chain is the tamper-evidence mechanism (no second scheme); immutability at rest (the WORM signed export) is Step 6.6b.
• Read API on by default via cfg.audit.enabled (a passive, tenant-scoped compliance record, unlike the behaviour-changing ACL/PII toggles); off → 404 (AuditNotFoundError), events still recorded. Adds AuditListResponse / AuditVerifyResponse wire types + AuditError / AuditNotFoundError.

Scope / deferred: read + verify only (WORM signed export is 6.6b). Today the populated event is corpus.route (every query); expanding audit coverage (ACL/PII/ingest decisions as audit events) is a follow-up — the surface + chain are in place for it.

Tests & gates

• ~10 gateway tests (apps/gateway/tests/test_audit.py): tenant-scoped list, cross-tenant isolation, verify ok + tamper detection (corrupt a stored chain hash → ok=False, chain_verified=False), action/outcome filters, limit/total, disabled→404, no-auth→401, shared-store wiring (a query's corpus.route event is visible via GET /v1/audit).
• Gateway suite 290 passed; full tests/ packages/ 2315 passed, 1 skipped. Green: ruff, mypy --strict (298 files), RAG001, policy-coverage, log-schema, schema-drift + openapi-drift (dist/openapi.* + dist/rag.schema.* regenerated for the new endpoints + AuditConfig).

Documentation

• New ADR-0038 — the two-slice decision (tamper-evidence vs immutability-at-rest; shared store; tenant-scoped read vs whole-log verify; read-API-default-on).
• New docs/reference/audit.md + docs/architecture/audit-log.md.
• docs/README.md — ADR-0038 + reference/architecture rows.

Test plan

• uv run pytest apps/gateway/tests — 290 passed
• uv run pytest tests/ packages/ -m "not integration" — 2315 passed, 1 skipped
• ruff + mypy --strict (298 files) + RAG001 + policy-coverage + log-schema
• schema-drift + openapi-drift gates (regenerated artifacts committed)
• Cross-tenant isolation + tamper detection verified

🤖 Generated with Claude Code