feat(audit): add bounded snapshot manifests

[seonghobae]

Commercial and acquisition gap

PR #65 adds bounded stable audit export pages, but a buyer/operator still needs a package-owned deterministic identity for one complete snapshot-stable audit traversal. This bounded slice adds a compact SHA-256 snapshot manifest without claiming signature, non-repudiation, delivery, external retention, provenance, or administrator-proof tamper resistance.

Implemented bounded slice

• adds immutable CheckpointAuditSnapshotManifest schema version 1 and the opt-in build_audit_snapshot_manifest_in_transaction() API;
• requires one caller-owned active PostgreSQL transaction before any manifest page is read;
• requires REPEATABLE READ or SERIALIZABLE and transaction_read_only = on, failing closed on autocommit, READ COMMITTED, read-write transactions, malformed transaction metadata, or unknown modes before page traversal;
• prevents a caller from hashing its own uncommitted accepted-save audit rows into an exported manifest and then rolling those rows back;
• walks the existing tenant-qualified keyset pages incrementally with strict page_size 1..1,000 and max_events 1..100,000 bounds, keeping only one page plus fixed digest state in package-owned memory;
• refuses silent truncation when a continuation remains after the event budget is exhausted;
• binds the trusted tenant/consumer/endpoint/batch key and every retained audit-event field in strict newest-first order with domain-separated length framing and SHA-256;
• normalizes retained event timestamps to UTC microsecond precision and freezes schema-version-1 framing with a deterministic compatibility vector;
• keeps page boundaries out of the digest so valid page-size changes do not change identity for the same database snapshot;
• revalidates manifest count, identity range, and lowercase 64-hex digest on public construction;
• preserves standalone and modular MSA operation without a migration, provider credential, LLM key, network exporter, background scheduler, version bump, publication, attestation, or release authority; and
• synchronizes contributor, architecture, changelog, ADR, operator, doctoring, and deterministic/live PostgreSQL contracts, with APA 7 references to PostgreSQL 18, Psycopg 3, FIPS 180-4, and NIST SP 800-53 Rev. 5 where material.

Strict RED → GREEN → refactor evidence

• Initial manifest-contract RED head: 6849ae16f2231c699bcb543421afcc6ba6028c48.
• Read-only retained-evidence RED head: 30f947a8ce99f28d0028ea54dfd5ce54ff0d7cbd; exact-head CI 31197234197 failed the new deterministic regression because the predecessor implementation accepted an active read-write REPEATABLE READ transaction.
• Production read-only implementation: 664e182f8717086bd4ccd59c9f18f1dd51fe11a0; _require_audit_snapshot_isolation() now verifies active INTRANS, stable isolation, and SHOW transaction_read_only = on before any page traversal.
• Live PostgreSQL contract was updated to establish SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY and remains least-privilege.
• Authoritative-documentation RED head: e945a3bb64fa551c6a791f5bb3426cb0862678d6 required the read-only boundary across project contracts.
• Exact-head CI 31198877520 on predecessor 4522a609842871d2393daa5a2b242cb897052c4c proved all unit, live PostgreSQL, container, lint, and docstring jobs green but correctly exposed one uncovered malformed read-only-evidence branch, leaving production coverage at 99.94%; that run is failure evidence only.
• Current head eec888bdbb4612abbb0f03d73ec90ad3f911028e adds deterministic malformed transaction_read_only evidence coverage without weakening the production gate.

Current exact-head evidence

• Head: eec888bdbb4612abbb0f03d73ec90ad3f911028e.
• Exact current base-branch tip: 4589fe07abd8a3c151bc98c5cfabfe9328d5f992 (agent/bounded-checkpoint-audit-export-pages-v2). Git compare reports the head ahead of that exact base and zero behind.
• CI 31199147845: completed / success on the exact source head. Python 3.10, 3.12, and 3.14 unit jobs, exact-head checkout assertions, compilation, Ruff, public-docstring enforcement, locked dependency verification, package build, Compose/container builds, and the live checkpoint-audit PostgreSQL integration all succeeded.
• Coverage: the exact-head coverage job completed successfully at the repository's mandatory 100% production statement and branch gate; public docstrings are 100%.
• Release Acceptance 31199146966: completed / success on the exact source head.
• CodeRabbit commit status: success on the exact current head; automated status is not independent approval.
• Formal reviews: no qualifying independent non-author GitHub APPROVED review exists on this draft.
• Unresolved inline review threads: zero at the latest inspection.
• No queued, pending, cancelled, skipped-required, absent, neutral-required, stale-head, predecessor-head, stale-base, synthetic-merge-only, or automated-status-only evidence is counted as merge success.

Assurance boundary

The snapshot digest is deterministic content identity and change detection only. It is not a MAC, signature, credential, trusted timestamp, delivery receipt, authenticated provenance statement, or non-repudiation mechanism. External immutable/WORM retention, signing/authentication, key management, legal hold, delivery evidence, destination credentials, and reconciliation remain host/operator controls. PostgreSQL owners, superusers, BYPASSRLS identities, disabled triggers, and physical database administrators remain outside the package's tamper-resistance claim.

Dependency and merge boundary

Required order remains .github#790 -> #53 -> #55 -> #56 -> #57 -> #58 -> #59 -> #60 -> #61 -> #62 -> #63 -> #65 -> this PR.

This PR remains intentionally draft. It must not be marked ready or merged until every prerequisite integrates into protected main, the branch is reconciled onto the actual integrated base, and fresh integrated exact-head/exact-base quality, security, dependency, packaging, live PostgreSQL, provenance, supply-chain, release-acceptance, branch-protection, ruleset, required-check, and independent-review gates all succeed. Zero unresolved valid findings and a qualifying independent non-author GitHub APPROVED review are mandatory.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2892aed1-947e-4cab-bc15-56ca9ecd688a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Closing as superseded by #84. Exact #66 head remains eec888bdbb4612abbb0f03d73ec90ad3f911028e on superseded #65 history. Replacement #84 is open/mergeable at exact head d2fee308e48cc963a195fb6d52846a70fe46cf63 directly on #83 exact head 0d3366de78c6b1373588d682560d3d50a6ee8a9a, exactly one commit ahead and zero behind. The replacement reproduces the exact 16-file snapshot-manifest delta and aggregate 1887 additions / 26 deletions. Fresh exact-head CI 31286925728 and Release Acceptance 31286925720 both completed successfully; CodeRabbit status is success, with no formal reviews or unresolved inline threads observed on the replacement. No checks, reviews, or approvals from this PR transfer to #84.