Finalize and compose extraction outcomes

[Khamel83]

Summary

• add immutable extraction plans/outcomes, closed finalization truth tables, and receipt-bearing durable acceptance
• enforce exactly-once Persist structured extraction rejection reasons for Atlas callers #57 classification, bounded private traces, cache authority/origin identity, and safe first/retry projections
• compose retrieval clusters only from exact durable accepted extraction projections, with artifact reuse and cross-plan integrity
• separate archive lookup from durable authority-consumed creation authorization
• add migration 0007 plus a real-PostgreSQL-derived recovery schema contract covering tables, columns, constraints, indexes, defaults, and deparsed definitions

Verification

• controller task-focused suite — 184 passed, 7 skipped
• controller recovery/status — 122 passed, 4 skipped
• controller full suite — 1499 passed, 42 skipped
• real disposable PostgreSQL contract, migration rollback, and concurrency checks passed
• scoped Ruff and git diff --check passed
• independent full-range review — Approved, no findings

Stack and gates

• stacked on S2 PR Normalize provider evidence batches #87, S1 PR Resolve deterministic retrieval plans #85, and S0 PR feat: freeze accepted operation contracts #83
• no production migration, archive creation, historical replay, provider traffic, or deployment
• human merge remains required

Resolves #88
Parent: #58

AI-generated implementation and PR description; independently reviewed and controller-verified.

[github-actions]

Fast review (openai/gpt-oss-20b:free, automated)

• No obvious syntax or formatting issues found.

[github-actions]

Deep review (inclusionai/ling-3.0-flash:free, automated)

Architecture concerns

• SQLiteArchiveCreationAuthorizationStore opens a new sqlite3.connect() per consume() call — each consume acquires its own file handle and transaction, risking contention under concurrent extraction and depending on WAL mode for cross-connection durability, which isn't configured.
• The _submit_and_fetch compatibility wrapper silently routes through create_archive, which now always raises ArchiveCreationPolicyRejected when called without an authorization — a behavioral change hidden behind a private function that no caller should reach.
• _validate_creation_authorization compares bounded_target != url with raw string equality after splitting the URL, so http://example.com and http://example.com/ (or a canonicalized form) won't match — authorization can fail non-obviously.
• ExtractionCache is now coupled to an acceptance_repository with an optional attribute check (getattr(..., loader, None)) — if the repository interface evolves, the silent early-return path makes failures difficult to detect.

Runtime edge cases

• Cache identity canonicalization falls back to re-hashing plan.normalized_url when normalized_url_identity is missing — if that field is populated inconsistently, the same extraction produces different cache keys and silently misses.
• In put, the identity round-trip ExtractionCacheIdentity.from_accepted(content) != url compares against the identity object used as key; if JSON sort_keys or field insertion order drifts at any point, valid entries become permanently ineligible.
• consume returns False for any exception during authority.verify or store.consume — swallowing the original exception with raise ... from error in create_archive masks root causes but the bare Exception catch there also traps programming errors like attribute typos.
• The cache has no max size and no TTL background eviction; entries expire only on lazy get hits, so a burst of distinct normalized URLs grows memory without bound.

Performance issues

• canonical_bytes() serializes the full identity dict to JSON + SHA-256 on every cache lookup (both _key and the durable reload inside put), making hot retrieval path O(n) in identity fields rather than a lightweight hash.
• Precomputing and storing canonical_bytes() or its hash on ExtractionCacheIdentity would eliminate repeated serialization overhead.
• SQLiteArchiveCreationAuthorizationStore's per-call connection pattern is fine for low throughput, but under concurrent extraction it will serialize on file locks rather than sharing a single connection — a connection pool or module-level sqlite3.connect(..., check_same_thread=False) with explicit locking would reduce overhead.
• The consume method hashes the target URL with SHA-256 on every call even though the target is already provided as a plain string; hashing is fast but wasteful when a direct comparison on the target itself would suffice for the uniqueness constraint.

[github-actions]

Fast review (openai/gpt-oss-20b:free, automated)

(no response from model)