ThothII/docs/contracts/archive-repair.md

Session corrections to Memory and Evidence

reviewer_archive_repair presents one to five closed alternatives for a conflict. Each alternative updates one existing Memory Card or one existing local Evidence unit, showing complete current and resulting content. The reviewer chooses one alternative, rejects all as inadequate, or asks for reformulation. A correction does not approve or advance the session phase; the ordinary gate still reviews its use in the current question.

The harness coordinator tht/archive_repair.py joins two independent domains. It uses Memory's PostgreSQL repository, workspace mutation lock and projection service, and the same local Evidence save/consolidation boundary as administration. Evidence activation runs the existing corpus pipeline without reacquiring configured external sources. No database binding, schema configuration, other archive, or Git repository is changed.

Authority and recovery

Migration 004_archive_repairs.sql stores session-bound proposals and receipts in thoth_memory.archive_repairs, isolated by workspace RLS. Each receipt captures the session decision context, current target revision, complete resulting content, selected choice, acting principal and publication outcome. The preparation command changes no archive content. Application accepts only an option ID from the persisted proposal.

Memory writes its new revision and receipt in one SQL transaction. Projection failures leave a durable pending operation; retry propagates the saved revision. A later card edit invalidates replay of the correction.

Evidence records the exact choice before writing its canonical file. Recovery accepts either the reviewed original revision or the already-written approved result; it never overwrites a different intervening correction. Before a first proposal, the editable checkout must match its active snapshot. Other curated files are fingerprinted and checked again before application/retry so a session decision cannot publish unrelated external edits. A crash after replacement is recoverable by the same receipt. Original document provenance is retained as the lineage of the manual correction.

The gate displays these outcomes:

Status	Meaning
proposed	Waiting for a human choice; no content saved
rejected	All alternatives declined; reformulation required
applying	Choice recorded; file write or candidate recovery still required
pending_activation	Content saved; index activation incomplete
active	Saved correction matches the currently active revision
superseded	The target was removed or changed after the saved correction

The reviewer may retry a pending correction or continue the current question while leaving activation explicitly pending. The latter is not persistent-resolution success. repair-show refreshes target status; repairs lists the historical receipt status. The final Memory summary must not create a duplicate of a correction already saved here.

Authorization and commands

Inspection/preparation requires an accessible open session in the same workspace. Applying either archive correction requires an administrator. Browser responses are also checked against the responding principal's memory.manage or evidence.manage permission and the Pi runtime owner. An administrator using another principal's runtime must resume it under their own account first, preserving truthful receipt attribution. Non-administrators may reject proposals or continue question review without changing the archives. The Pi shell guard blocks repair-apply; only the human gate invokes it.

The Python workflow CLI provides memory repair-target, repair-prepare, repair-show, repair-apply, and repairs. These are workflow integration commands, not new native installation commands. All accept --session and command-local -c; JSON output remains machine-readable. Proposal bodies are bounded to 1 MB. Durable receipts support both filesystem and server session storage without a persisted chat transcript.