docs: nightly doc-gardening sweep 2026-06-08

[litbot-9000]

Automated nightly doc-gardening sweep for 2026-06-08.

What changed

• New CLAUDE.md/AGENTS.md: p-models/durableactor/bridge, serverconn/mailboxpull, scripts/check-sample-darepod-conf
• Updated CLAUDE.md/AGENTS.md: vtxo, unroll, db, oor, round, ledger, baselib/actor, serverconn, txconfirm, p-models/durableactor
• ARCHITECTURE.md: added serverconn/mailboxpull and p-models/p-models/durableactor/bridge to the layer tables

Key changes reflected:

• vtxo: startup orphan-reservation sweep, unilateral-exit reconcile, SpendingReservationStore, ExitOutcomeResolver
• unroll: VTXOUnrollActor migrated to Read/Commit TxBehavior path
• db: migration 000017 (spending_reservations table), SpendingReservationPersistenceStore, LatestMigrationVersion = 17
• oor: ReservationStore interface, IncomingSnapshot.MetadataAttempts, bounded backoff for metadata resolution
• round: RoundClientConfig.RegistrationTimeout, lazy reaping of failed rounds via reapFailedRounds
• ledger: LedgerActor migrated to Read/Commit TxBehavior path

Review notes

Please review the updated CLAUDE.md and AGENTS.md diffs and ARCHITECTURE.md for accuracy.
make doc-check passes cleanly on this branch.

[gemini-code-assist]

Code Review

This pull request updates the project's documentation across several AGENTS.md and CLAUDE.md files to reflect recent architectural changes. These include concurrent worker pools for durable actors, startup reconciliation of unilateral-exit VTXOs, spending reservation stores for orphan sweeps, and shared retry primitives for mailbox pull loops. The review feedback correctly identifies a typo in a referenced method name and points out an inaccuracy regarding transaction confirmation retry behaviors, noting that the persistent retry behavior for no-mempool transactions applies specifically to anchor (CPFP) transactions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The statement that only structurally permanent errors fail terminally is slightly inaccurate. According to the implementation in txconfirm/actor.go (lines 539-544), any non-anchor direct broadcast failure (other than ErrParentAlreadyBroadcast) will also fail terminally immediately. This "never give up" behavior only applies to anchor (CPFP) transactions.

Suggested change

	overcome. Only a structurally permanent error
	(`isPermanentBroadcastError`, currently `ErrNonTRUCParent`) fails
	terminally; `ErrParentAlreadyBroadcast` advances to
	`AwaitingConfirmation` (a live parent exists on another path). Rationale:
	overcome. For anchor transactions, only a structurally permanent error
	(`isPermanentBroadcastError`, currently `ErrNonTRUCParent`) fails
	terminally; `ErrParentAlreadyBroadcast` advances to
	`AwaitingConfirmation` (a live parent exists on another path). Non-anchor
	direct broadcasts will fail terminally on any broadcast error. Rationale:

[gemini-code-assist]

The method name LeaseNextMailboxMessage is a typo. The actual method implemented on the store and called in durable_mailbox.go is LeaseNextMessage.

Suggested change

- `DurableActorConfig.NumWorkers` — How many concurrent worker loops drain the actor's single mailbox. Default and any value `<= 1` is one worker (strictly-sequential processing). A value `> 1` turns the actor into a competing-consumer pool: that many goroutines each lease distinct messages via `LeaseNextMailboxMessage`, so independent messages run in parallel while per-correlation-key FIFO still keeps same-key messages ordered. Only for behaviors whose handlers are concurrency-safe and hold no writer across their side effects (e.g. the serverconn egress sender on the Read/Commit path). `NewDurableActor` **fails closed** with `ErrConcurrentClassicBehavior` when `NumWorkers > 1` is paired with a classic (`Left`) `ActorBehavior`, since the classic path wraps the whole `Receive` in one write transaction and assumes sequential delivery; pools are only valid on the Read/Commit (`TxBehavior`) path. The test-only `DurableActorConfig.AllowConcurrentClassicBehavior()` escape hatch bypasses the guard for the egress benchmark that measures the forbidden config; production code must never call it.

- `DurableActorConfig.NumWorkers` — How many concurrent worker loops drain the actor's single mailbox. Default and any value `<= 1` is one worker (strictly-sequential processing). A value `> 1` turns the actor into a competing-consumer pool: that many goroutines each lease distinct messages via `LeaseNextMessage`, so independent messages run in parallel while per-correlation-key FIFO still keeps same-key messages ordered. Only for behaviors whose handlers are concurrency-safe and hold no writer across their side effects (e.g. the serverconn egress sender on the Read/Commit path). `NewDurableActor` **fails closed** with `ErrConcurrentClassicBehavior` when `NumWorkers > 1` is paired with a classic (`Left`) `ActorBehavior`, since the classic path wraps the whole `Receive` in one write transaction and assumes sequential delivery; pools are only valid on the Read/Commit (`TxBehavior`) path. The test-only `DurableActorConfig.AllowConcurrentClassicBehavior()` escape hatch bypasses the guard for the egress benchmark that measures the forbidden config; production code must never call it.