docs: reconcile keeper prose and Verdict poll-seam references#335
Conversation
d86e052 to
56b3790
Compare
57472d6 to
339c9fb
Compare
78f8bcd to
bcd338e
Compare
806fc83 to
fa31ad5
Compare
cecab4f to
e28590b
Compare
lgahdl
left a comment
There was a problem hiding this comment.
Reviewed for completeness against the stale-reference list our #334 review flagged, since that's this PR's whole purpose. The renames actually made are accurate (Verdict/LegacyRevertAdapter verified to exist at the stated paths, behavior claims match composable.rs), and no semantic change is smuggled into the prose-only diff (+26/-21 fully accounted for, no use blocks touched despite the PR body's claim). But the sweep is incomplete:
- All three live-code
decode_revertreferences from the #334 review are still unfixed, none touched by this diff:crates/nexum-runtime/src/host/provider_pool.rs:431(rustdoc naming the nonexistentshepherd_sdk::cow::decode_revert),crates/nexum-runtime/src/host/impls/chain.rs:127(test comment),crates/nexum-sdk/src/proptests.rs:13(module doc). All three should becomeLegacyRevertAdapter::classify/LegacyRevertAdapter. Ready(not aVerdictvariant — it'sPost) survives in two spots this PR partially touched:docs/00-overview.mdline 281 ("submitReadyorders behind thesubmitted:journal guard") is the row directly below the one this PR fixed at line 280;crates/shepherd-sdk/src/cow/run.rs'ssubmit_readydoc ("Submit one freshly-polledReadyorder") is in the same file this PR edited at the top-of-file module doc.docs/diagrams/sequence-twap.mmdis half-renamed: line 34's label changedPollOutcome→Verdict, but thealtarms below (Ready (order, signature)/NotReady (try at epoch t)/Terminal) are the pre-ADR-0013 three-variant model with module-computednext_attemptepoch math. The realVerdicthas six variants (Post/TryNextBlock/WaitBlock/WaitTimestamp/Invalid/NeedsInput) with gate values contract-supplied, not module-computed. A reader would concludeVerdictstill hasReady/NotReady/Terminal— the type name changed but the diagram's model didn't.docs/operations/m2-testnet-runbook.md:136-139tells operators to expectReady/TryAtEpoch(t)in poll logs — present-tense operator guidance, not in the PR's historical-record exclusion set. Post-rename the module logs Verdict vocabulary, so an operator matching lines against this runbook would misdiagnose a healthy run as broken.docs/qa-signoff.md:62's "Outstanding / deferred" table lists a pending#[non_exhaustive]task againstPollOutcome— a checklist item, not history. One-word fix toVerdictkeeps it executable.- Nit:
docs/sdk.md's "cow::LegacyRevertAdapter(s)" carries over a(s)pluralization from the olddecode_revert/decode_revert_hexfunction-pair naming that reads oddly applied to a single type.
Everything else checked out clean: docs/sdk.md, docs/00-overview.md line 280, docs/05-sdk-design.md, docs/08-platform-generalisation.md, and docs/diagrams/engine-boot.mmd are all accurate; the new single-tenant-keeper paragraph in nexum-sdk/src/keeper.rs matches the code; tree-wide grep for PollOutcome|decode_revert|classify_poll_error|chassis found nothing else outside ADRs/migration-guide/qa-signoff (correctly excluded as history) plus the items above.
1894f9d to
d1cefb8
Compare
Tip-level residual after the chassis to keeper rename was folded down through the train. Carries the doc-comment prose the fold could not move mechanically (the private-keeper caveat, keeper-run wording) and the current-state design docs brought in line with the Verdict poll seam (PollOutcome to Verdict, decode_revert to LegacyRevertAdapter).
e28590b to
1a4fe7f
Compare
What
Doc-comment prose polish for the keeper (
nexum-sdk::keeper) that the earlier fold-down commits could not carry mechanically: the private, single-tenantKeepercaveat, the "keeper run" wording, and the rewordedlocal_store_redbfile-open comment.Brings the design docs in line with the Verdict poll seam (#334): the old reverting-poll enum and revert-decode helpers are renamed to
VerdictandLegacyRevertAdapter, across00-overview.md,05-sdk-design.md,08-platform-generalisation.md,sdk.md, and thesequence-twap/engine-bootdiagrams.A couple of import-ordering normalisations in the
cowmodule files.Why
The keeper and run-loop rename was folded down through every PR in the M1 train, but a handful of tip-level prose and doc references were not owned by any single earlier PR. This PR carries the remainder so the train reads keeper end to end, not just at the tip. The historical ADRs, migration guide, and QA sign-off keep their original terms as records.
Testing
nix develop+cargo test --workspacepasses (docs and comments only, no behavioural change). A mid-stack keeper commit was independently rebuilt and tested green to confirm the fold compiles at every point in the stack.AI Assistance
Claude (Opus) used for the fold-down rewrite and doc reconciliation.