Document PRISM refactor review stack

[kiwidream]

Position in the stack

PR 9 of 9. Base: prism-final-ownership-cleanup. Depends on PR 80.

This PR is the documentation and final-evidence slice. Review and merge the stack bottom-up if the slices are landed individually. The stack guide records the complete order and reconstruction rules.

Why this slice exists

The refactor changes internal ownership, review structure, validation cadence, and an existing-database migration. Those contracts need to remain understandable after the implementation discussion is gone. This slice makes the completed architecture, invariants, decisions, operations, and evidence part of the repository.

What changes

• Replace the retired gate-heavy work plan with a concise completed roadmap and risk-based validation strategy.
• Record the final ownership map, coordinator size exception, optional future decomposition, and structural audit.
• Record release invariants for mining delivery, shares/candidates, payout, audit artifacts, observability, HTTP, shutdown, and liveness.
• Document the A1 audit artifact contract and the evidence-based decision to omit the optional B3 second finalization lane.
• Document the nine-PR review order and reconstruction rules.
• Add operator guidance for the cumulative 001_share_ledger.sql migration, lock impact, application procedure, and reactivation ordinal behavior.
• Cross-link the refactor and ledger guidance from the existing documentation indexes.

Reading the diff

This is a small documentation-only slice: about 560 additions and five deletions across 11 files. The only production-file change is a comment clarifying that reactivation reuses an already-published audit ordinal. Review the documents against the final owner modules and migration behavior; there is no runtime implementation hidden in this PR.

Final validation

• PRISM Python discovery: 1,251 passed.
• Full Python discovery: 1,585 passed with the temporary-repository Git config override scoped to that command.
• Rust qbit-prism: 182 passed.
• Permissionless, real-miner-smoke, auxpow, and prism Compose profiles passed configuration validation.
• Structural, target-tree, whitespace, conflict-marker, local-path, and generated-artifact checks passed.
• PostgreSQL integration, Docker Python compile, Docker Ruff, and the PRISM image build are UNAVAILABLE because the OrbStack Docker daemon is stopped. Lint was not run outside Docker.
• Live and live-PostgreSQL Stratum validation is UNAVAILABLE: their doctor stops at the unreachable Docker daemon, and qbitd/qbit-cli are also absent.

Operator impact

Existing PostgreSQL deployments must follow docs/prism-ledger-ops.md before upgrade. The migration uses ACCESS EXCLUSIVE DDL, a later serialized SHARE ROW EXCLUSIVE phase, and a non-concurrent unique index, so it requires a reviewed maintenance window or a stopped old coordinator.

Landing state

The reviewed stack is integrated with origin/1.x.x at b002caa. Retry pacing (#71), delivery-health grace (#82), and share hot-path lock isolation (#83) are ported into the extracted template, refresh, candidate, session, submission, vardiff, delivery, ledger, observability, and metrics owners without restoring domain logic to prism_coordinator.py.

---

Note

Low Risk
Documentation and index cross-links only, plus a non-behavioral comment in production code; operator migration steps are advisory and do not change runtime logic in this PR.

Overview
Adds a PRISM coordinator refactor documentation tree under docs/prism-coordinator-refactor/: completion status, release invariants, final owner map, validation evidence, nine-PR stack guide, A1 audit-artifact contract, and the decision to omit B3.

Operator and ledger guidance expands docs/prism-ledger-ops.md and crates/qbit-prism/README.md: cumulative idempotent 001_share_ledger.sql, audit_publication_sequence migration (locks, psql procedure, reactivation reusing published ordinals), finalize-only outbox replay when the network outcome is already known, and cross-links from docs/README.md.

The only runtime change is a comment in block_finalization.py clarifying that reactivation keeps an already-published audit ordinal rather than allocating a new one.

^{Reviewed by Cursor Bugbot for commit f4f6773. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bb8eb53edc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".