Skip to content

docs: reconcile keeper prose and Verdict poll-seam references#335

Merged
mfw78 merged 1 commit into
dev/m1from
refactor/rename-chassis-to-keeper
Jul 15, 2026
Merged

docs: reconcile keeper prose and Verdict poll-seam references#335
mfw78 merged 1 commit into
dev/m1from
refactor/rename-chassis-to-keeper

Conversation

@mfw78

@mfw78 mfw78 commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

What

Doc-comment prose polish for the keeper (nexum-sdk::keeper) that the earlier fold-down commits could not carry mechanically: the private, single-tenant Keeper caveat, the "keeper run" wording, and the reworded local_store_redb file-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 Verdict and LegacyRevertAdapter, across 00-overview.md, 05-sdk-design.md, 08-platform-generalisation.md, sdk.md, and the sequence-twap/engine-boot diagrams.

A couple of import-ordering normalisations in the cow module 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 --workspace passes (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.

@mfw78 mfw78 force-pushed the refactor/cow-verdict-poll-seam branch from d86e052 to 56b3790 Compare July 14, 2026 09:33
@mfw78 mfw78 force-pushed the refactor/rename-chassis-to-keeper branch from 57472d6 to 339c9fb Compare July 14, 2026 09:33
@mfw78 mfw78 changed the title refactor: rename the strategy chassis to keeper (materialise -> run, RetryLedger -> Retrier) docs: reconcile keeper prose and Verdict poll-seam references Jul 14, 2026
@mfw78 mfw78 force-pushed the refactor/rename-chassis-to-keeper branch 2 times, most recently from 78f8bcd to bcd338e Compare July 14, 2026 10:05
@mfw78 mfw78 force-pushed the refactor/cow-verdict-poll-seam branch from 806fc83 to fa31ad5 Compare July 14, 2026 12:25
@mfw78 mfw78 force-pushed the refactor/rename-chassis-to-keeper branch 2 times, most recently from cecab4f to e28590b Compare July 14, 2026 12:47

@lgahdl lgahdl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. All three live-code decode_revert references from the #334 review are still unfixed, none touched by this diff: crates/nexum-runtime/src/host/provider_pool.rs:431 (rustdoc naming the nonexistent shepherd_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 become LegacyRevertAdapter::classify / LegacyRevertAdapter.
  2. Ready (not a Verdict variant — it's Post) survives in two spots this PR partially touched: docs/00-overview.md line 281 ("submit Ready orders behind the submitted: journal guard") is the row directly below the one this PR fixed at line 280; crates/shepherd-sdk/src/cow/run.rs's submit_ready doc ("Submit one freshly-polled Ready order") is in the same file this PR edited at the top-of-file module doc.
  3. docs/diagrams/sequence-twap.mmd is half-renamed: line 34's label changed PollOutcomeVerdict, but the alt arms below (Ready (order, signature) / NotReady (try at epoch t) / Terminal) are the pre-ADR-0013 three-variant model with module-computed next_attempt epoch math. The real Verdict has six variants (Post/TryNextBlock/WaitBlock/WaitTimestamp/Invalid/NeedsInput) with gate values contract-supplied, not module-computed. A reader would conclude Verdict still has Ready/NotReady/Terminal — the type name changed but the diagram's model didn't.
  4. docs/operations/m2-testnet-runbook.md:136-139 tells operators to expect Ready / 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.
  5. docs/qa-signoff.md:62's "Outstanding / deferred" table lists a pending #[non_exhaustive] task against PollOutcome — a checklist item, not history. One-word fix to Verdict keeps it executable.
  6. Nit: docs/sdk.md's "cow::LegacyRevertAdapter(s)" carries over a (s) pluralization from the old decode_revert/decode_revert_hex function-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.

@mfw78 mfw78 force-pushed the refactor/cow-verdict-poll-seam branch from 1894f9d to d1cefb8 Compare July 15, 2026 01:24
Base automatically changed from refactor/cow-verdict-poll-seam to dev/m1 July 15, 2026 01:25
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).
@mfw78 mfw78 force-pushed the refactor/rename-chassis-to-keeper branch from e28590b to 1a4fe7f Compare July 15, 2026 01:26
@mfw78 mfw78 merged commit df91716 into dev/m1 Jul 15, 2026
5 checks passed
@mfw78 mfw78 deleted the refactor/rename-chassis-to-keeper branch July 15, 2026 01:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants