Disposable canonical-event inbox rehearsal

docs/custody-sale-rehearsal.md

@@ -31,11 +31,17 @@ The existing sandbox `mock-sale-settlement` journal and `fixture-complete`/`fixt
 
 A submitted history that conflicts with, removes or makes immature an already posted outcome triggers `sale-rehearsal-outcome-reorg`. Business changes roll back, and a redacted durable integrity incident commits while retaining the shared writer lock. All custody instances then reject new mutations; private reads and original signed receipts remain available. The original seller credit/refund stays recorded: no automatic compensation, reversal or second payout. Re-submitting the old mature history cannot clear the incident. Existing schema-owner incident review procedures are not a substitute for resolving chain risk; production resolution requires retained canonical evidence and approved loss policy.
 
-This rehearsal is **not a durable connect/disconnect observer**. It retains first/terminal evidence and the redacted incident reason, not every submitted fork transcript. It cannot detect an intermediate disconnect that is never submitted, even if an outcome later reappears. The caller must retain conflicting evidence for investigation. Production must integrate a replay-safe canonical event inbox/cursor, history anchors, disconnect-before-reconnect handling and persistent per-order review. No monotonic canonical-height guarantee is claimed for this caller-driven seam.
+## Local canonical-event inbox foundation
+
+The same explicitly disposable PostgreSQL instance now has `observeCanonicalEvents()` and `observeLedgerCanonicalEvents(ledger)`. The ledger adapter requires an actual in-process `Ledger` object, checks its network/chain identity, and fetches one page at a time from its locally validated [canonical event API](../server/testnet/canonical-index.ts)—no caller/HTTP/peer page can enter through that adapter. The inbox is append-only and bounded. It checks stream identity, page limits, predecessor anchors, event hashes, sequence continuity, connect parent/tip and tip-first disconnect rules against a reconstructed canonical hash stack. It accepts exact retries and overlapping pages from concurrent consumers only after matching their persisted overlap; stale retries report the durable cursor/head, not the stale page head. The startup/periodic financial audit replays and verifies the stored inbox; a changed stream, gap or malformed/tampered event creates the normal durable integrity hold. Inbox records use namespaced `custody_meta` keys and the existing runtime role; there is no schema migration or mutable cursor.
+
+The adapter is not automatically scheduled: there is no HTTP route or background worker. PostgreSQL tests include synthetic event pages for malformed/retry cases and one integration using blocks accepted by a local `Ledger` configured with a **test-only fake PoW engine**, including an equal-work side branch and a reorg. This tests the local adapter/API boundary, not real RandomX validation, external provenance or production multi-node behavior. Hash-anchor consistency is not proof of honest observation; the stream ID and unkeyed hashes are stored beside the events, so a schema owner able to coherently rewrite the complete history can also recompute the hashes. The included corruption test detects a partial edit, not a fully rewritten valid history. Production must anchor custody checkpoints outside the database's mutable trust domain. The disposable inbox is capped at 4,096 total events, stores the append-only event history and fully rescans it during audits. That is intentionally a small-fixture design, not production storage/cursor architecture or a scale claim.
+
+Most importantly, the inbox is not connected to candidate transaction IDs, `replayReservedSale()` or settlement decisions. Existing v6 blocks cannot contain candidate sale transactions, and local free transfers are not accepted as sale completion evidence. It therefore **does not create a sale-specific disconnect hold** or detect an unsubmitted intermediate fork that later disappears before a page is observed. The synthetic sale transcript still retains only first/terminal evidence and the redacted incident reason; the caller must retain conflicting transcript evidence. Production must integrate a durable replay-safe canonical consumer with per-order candidate transaction linkage, then persist a review hold for a previously posted outcome. No production sale-observation guarantee is claimed for this increment.
 
 ## Validation and remaining gates
 
-TypeScript/Vite Docker build passed; **172 offline regressions and 22 PostgreSQL integration tests passed, zero failures/skips**. [Candidate tests](../tests/sale-candidate.test.ts) cover signature compatibility/recipient tampering and candidate transition rules. [PostgreSQL tests](../tests/postgres/custody.test.ts) add:
+TypeScript/Vite Docker build passed; **172 offline regressions and 27 PostgreSQL integration tests passed, zero failures/skips**. [Candidate tests](../tests/sale-candidate.test.ts) cover signature compatibility/recipient tampering and candidate transition rules. [PostgreSQL tests](../tests/postgres/custody.test.ts) add:
 
 - explicit instance/database consent and exact signed reservation matching;
 - seed-binding changes, malformed/cyclic/oversized collections, and denial of ordinary cancellation after binding;
@@ -44,8 +50,9 @@ TypeScript/Vite Docker build passed; **172 offline regressions and 22 PostgreSQL
 - identical-rounded-allocation but different fee-rate rejection;
 - one-atomic settlement and signed custom-recipient revenue across current-policy changes;
 - conflicting outcome → durable cross-instance/restart hold without a second credit;
+- anchored canonical-event connect/disconnect paging, overlapping/stale consumer retries, reconnect, partial history mutation audit, forged disconnect-ancestor rejection and tamper-triggered hold; actual validated local-ledger blocks, excluded equal-work branch and a canonical reorg through the adapter (no candidate sale link);
 - injected terminal-evidence failure → complete rollback and safe retry; corrupted evidence → audit hold.
 
 A first bounded-checkpoint implementation attempted metadata UPDATE and was rejected by the real runtime grants. It was corrected to retain insert-only first/terminal evidence; no privilege was widened. Test evidence is for this implementation boundary, not production approval.
 
-**M3 remains open.** Next work is independently reviewed protocol/policy and explicit new-network activation design, then actual PoW/peer/index/undo integration and durable canonical observation tied to financially fenced host-signing intent. Monero deposit confirmation/unlock observation, treasury/signer separation, real withdrawal controls, coordinated recovery, capacity and legal/operational release gates remain separate. The active v6 chain still rejects every candidate sale transaction. Persistent local custody deployments were not switched or restarted by this rehearsal.
+**M3 remains open.** Next work is independently reviewed protocol/policy and explicit new-network activation design, then actual PoW/peer/index/undo integration and durable canonical observation tied to financially fenced host-signing intent. Monero deposit confirmation/unlock observation, treasury/signer separation, real withdrawal controls, coordinated recovery, capacity and legal/operational release gates remain separate. The active v6 chain still rejects every candidate sale transaction. Persistent local custody deployments were not switched or restarted by this rehearsal.

docs/production-plan.md

@@ -88,6 +88,8 @@ Blocked on P0 ADR; use P1 amount types and P2 durable events. Consensus work is
 
 **Accounting rehearsal increment, 2026-10-20:** [signed candidate → PostgreSQL reservation resolution](custody-sale-rehearsal.md) now exercises actual restricted-role SQL terminal postings from bounded synthetic transcripts, behind explicit disposable database/instance guards and without an HTTP route. Exact terms/hosting recipients and reservation commitments are checked; mature completion credits seller/fees once, cancellation/non-admission releases buyer funds, and conflicting post-settlement evidence durably holds mutations rather than repaying. Insert-only first/terminal evidence is audited. Final build, 172 offline tests and 22 PostgreSQL integration tests passed. This supersedes the earlier absence of any balance-posting test integration, **not** the production/activation boundary: caller-supplied seeds/blocks are not canonical evidence, intermediate unseen disconnects cannot be detected, and no signer, canonical inbox, live deposit/withdrawal or current-chain paid sale is enabled. M3 remains open.
 
+**Canonical inbox rehearsal increment, 2026-10-20:** the same gated disposable PostgreSQL instance now stores bounded append-only pages from an in-process `Ledger` adapter, checks stream/anchor/hash/tip/ancestor continuity, permits exact/overlapping/stale consumer retries, and verifies retained history during audits. Integration tests use locally validated blocks to exercise an excluded equal-work branch and a real reorg; tampering or stream changes durably hold mutations. Final build and 27 PostgreSQL tests pass; the offline regression count remains 172. The adapter is not scheduled, its stream is not tamper-proof against a schema owner, it does not match candidate transaction IDs or drive per-order settlement/reorg review, and the inbox's 4,096-event cap/full scan make it explicitly non-production. M3 remains blocked on production observer/checkpoint design, candidate network activation, transaction linkage and per-order reorg handling.
+
 - If a reviewed trustless design is selected: implement its actual cross-chain validity/evidence rules, compatible cryptographic primitives, both-party failure/refund paths and commission semantics. Run maintained reference vectors, negative tests, fuzz/property tests and specialist audit before claiming atomicity.
 - If a custodial/attested fallback is explicitly approved: define chain-enforced NFT lock, order identity, authorized releaser, cancellation/refund/expiry and stale-signature rules. Separate host control keys from seller wallet and processor payout keys. Reserve/refund procedures must not permit both buyer refund and later seller delivery/release. Describe who can steal, censor or lock assets and how recovery is authorized.
 - Completed-sale inclusion must require the approved evidence that payment is sufficiently confirmed. A peer must not insert a completed sale merely because its local database says paid. Define threshold/policy version, proof/attestation authorization and deterministic validation; no external HTTP calls in consensus validation.

docs/sale-lock-candidate.md

@@ -73,6 +73,6 @@ Initial candidate evidence: 162 offline tests passed, including 13 candidate tes
 1. Independent protocol/consensus review and operator approval of authority, cancellation and numeric policy parameters; final specification and test vectors.
 2. Versioned network/manifest and explicit migration/activation strategy. No enabling the candidate under the existing v6 chain identity.
 3. Integrate new transaction encodings/state commitments with mint/transfer/trade validation, canonical SQL undo/indexes/events, actual RandomX blocks, peer sync, restart and multi-host fork/partition tests. The current model supplies no PoW, issuance or fork-choice implementation.
-4. Production PostgreSQL sale witness/terms storage, financially reserved host-signing workflow, outbox fencing, canonical observer/inbox, atomic terminal postings and reorg holds. The disposable signed-transcript rehearsal exercises terminal postings and durable review, but supplies none of the canonical observer/host-signing integration. Existing sandbox signatures do not authorize the new sale protocol. No signing before final exact order consent.
+4. Production PostgreSQL sale witness/terms storage, financially reserved host-signing workflow, outbox fencing, local-ledger canonical observer/inbox, transaction linkage, atomic terminal postings and per-order reorg holds. The disposable signed-transcript rehearsal exercises terminal postings and durable review. A separate bounded PostgreSQL event-inbox rehearsal checks page hashes, anchors, overlapping retries and connect/disconnect tip progression, but is not wired to the ledger and is not linked to a sale. Existing sandbox signatures do not authorize the new sale protocol. No signing before final exact order consent.
 5. Publication/review UI, key management/rotation, privacy and public-price disclosure, window/griefing/storage limits and operational recovery. Public terms would reveal sale linkage and amounts; privacy acceptance is a product decision.
 6. Monero confirmation/unlock observation, real treasury controls, coordinated financial/node recovery and independently reviewed production release gates. No live wallet, funds or credentials were used in this increment.