Skip to content

docs: stale-reference sweep — engine rename, Dockerfile, ADR-0007 errata#311

Closed
lgahdl wants to merge 9 commits into
dev/m1from
docs/108-62-123-sweep
Closed

docs: stale-reference sweep — engine rename, Dockerfile, ADR-0007 errata#311
lgahdl wants to merge 9 commits into
dev/m1from
docs/108-62-123-sweep

Conversation

@lgahdl

@lgahdl lgahdl commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

What

Docs-only sweep clearing stale references left over from the crate rename and the M5 Docker ship:

  • docs/deployment.md: replaces the "Dockerfile is planned for M5" placeholder and inline sketch with a pointer to the real Dockerfile + docker-compose.yml at the repo root, and to docs/deployment/docker.md for the full container workflow. Notes the image is published to ghcr.io/nullislabs/shepherd:<tag> on every merged commit to main.
  • docs/production.md: replaces the "Dockerfile (interim)" multi-stage sketch and its status note with a pointer to the real root Dockerfile, plus the docker build/root docker-compose.yml build path.
  • docs/qa-signoff.md: nexum-engine -> nexum-runtime in the warn(unused_crate_dependencies) check row.
  • docs/adr/0007-upstream-protocol-logic-to-cow-rs.md: adds errata noting the crates/nexum-engine -> crates/nexum-runtime + crates/nexum-cli rename, and that the workspace now pins cowprotocol = "0.2.0" from crates.io with a temporary [patch.crates-io] git override to nullislabs/cow-rs pending a release with the hash-only OrderCreationAppData constructor.
  • docs/sdk.md: updates the versioning section from cowprotocol = "0.1.0" (no patch) to 0.2.0 with the same temporary patch override described above.
  • docs/02-modules-events-packaging.md: fixes the manifest-naming aside, the pre-rename filename was nexum.toml, not module.toml as the earlier draft claimed.

Historical ADRs, migration docs, and operations reports that describe what was true at the time are left as-is.

Why

Several docs pages still described planned-but-since-shipped work (the Dockerfile) or pre-rename crate/manifest names (nexum-engine, nexum.toml), which misleads new operators and reviewers cross-referencing the ADRs against the current tree.

Testing

Docs-only change, no build required. Verified crate names against the current workspace Cargo.toml and confirmed the linked docs/deployment/docker.md and root Dockerfile/docker-compose.yml exist and match the described workflow.

Closes #123, #108, #62

@lgahdl
lgahdl requested a review from mfw78 as a code owner July 9, 2026 22:25
@jean-neiverth

jean-neiverth commented Jul 10, 2026

Copy link
Copy Markdown
Collaborator

Nice cleanup! The new text references ghcr.io/nullislabs/shepherd:<tag>, which matches what CI produces on the canonical repo. But docker-compose.yml (line 26) still hardcodes ghcr.io/bleu/nullis-shepherd:latest, and both .env.example and docs/deployment/docker.md also reference the old bleu/nullis-shepherd name.

Since this section cross-references those files and shows the docker compose up -d quick start, wonder if an operator would end up seeing two different image names depending on which file they're reading. I think PR #220 addresses the same root cause — maybe worth coordinating so they land consistently.

@lgahdl
lgahdl force-pushed the docs/108-62-123-sweep branch from 3653ce8 to 4e69f91 Compare July 10, 2026 19:28
@lgahdl lgahdl mentioned this pull request Jul 13, 2026
Merged
6 tasks
@mfw78
mfw78 force-pushed the docs/108-62-123-sweep branch from 4e69f91 to f61b04a Compare July 14, 2026 02:19
@mfw78
mfw78 force-pushed the feat/m1-mock-venue branch from b8aeb1c to d94a4bd Compare July 14, 2026 03:33
@mfw78
mfw78 force-pushed the docs/108-62-123-sweep branch 2 times, most recently from 0eb2ace to 9457e82 Compare July 14, 2026 04:47
@mfw78
mfw78 force-pushed the feat/m1-mock-venue branch from d94a4bd to 6db87ec Compare July 14, 2026 04:47
@mfw78
mfw78 force-pushed the docs/108-62-123-sweep branch from 9457e82 to ff77942 Compare July 14, 2026 07:45
@mfw78
mfw78 force-pushed the feat/m1-mock-venue branch from b4734ce to e15aa66 Compare July 14, 2026 09:33
@mfw78
mfw78 force-pushed the docs/108-62-123-sweep branch from ff77942 to d7227ad Compare July 14, 2026 09:33
@mfw78
mfw78 force-pushed the feat/m1-mock-venue branch from e15aa66 to 4c508ec Compare July 14, 2026 10:05
@mfw78
mfw78 force-pushed the docs/108-62-123-sweep branch from d7227ad to 09a7c78 Compare July 14, 2026 10:05
@mfw78
mfw78 force-pushed the feat/m1-mock-venue branch from 4c508ec to 6f83ed6 Compare July 14, 2026 12:25
@mfw78
mfw78 force-pushed the docs/108-62-123-sweep branch from 09a7c78 to 24d9f1b Compare July 14, 2026 12:26
mfw78 and others added 9 commits July 14, 2026 12:47
@mfw78
feat(sdk): add the keeper conditional-source seam, retry ledger, and run
4e1ec36 
Introduce the world-neutral half of the poll loop in
nexum_sdk::keeper: a ConditionalSource trait (one watch in, one
outcome out, generic over the host, no venue-transport
pre-abstraction), a Tick carrying the dispatch instant, and the
RetryAction (try-next-block / backoff / drop) whose effects the
Retrier runs through the gate and watch-set stores. RetryAction
moves out of shepherd-sdk; the CoW crate re-exports it so no module
rewires.

shepherd-sdk keeps classify_api_error as the CoW errorType table but
returns the keeper action, and encodes two fixes in the one
classification path: classify_poll_error maps an unrecognised revert
selector with a structured payload to DontTryAgain instead of
re-polling every block forever, and DuplicatedOrder (both spellings)
classifies as already-submitted - the run records the
submitted: receipt and keeps the watch rather than dropping every
future tranche. classify_submit_error widens the table to the whole
CowApiError surface and gives Backoff its producer: a rate-limit
fault with server guidance gates the watch on the epoch clock.

cow::run composes the loop: watch-set scan -> gate check ->
source poll -> PollOutcome dispatch, driving submission through the
existing CowApiHost seam with the journal as the idempotency guard
and the retry ledger as the failure dispatch. Acceptance tests run
against the composed shepherd-sdk-test MockHost as integration
tests; no module is rewired yet.
@mfw78
docs(sdk): disambiguate the run intra-doc link
06c9b07
@mfw78
fix(cow): build the classify_poll_error test RpcError data as Bytes
149c7d2 
RpcError.data is now Bytes; the test helper takes raw Vec<u8> and wraps
it (Vec -> Bytes is O(1)).
@mfw78
feat(sdk): log run diagnostics through the tracing facade
752163a 
The run logged through the LoggingHost seam, which the
guest tracing capture cannot observe - module tests proving
behaviour identity for keeper ports assert on tracing events.
Route the submit-path diagnostics through the tracing macros with
the wording the legacy twap poll loop established, and give
ConditionalSource a defaulted label so shared log lines attribute
the strategy that produced them.
@mfw78
refactor(twap-monitor): port the poll loop onto the keeper composition
a56902a 
Reduce strategy.rs to decode and evaluate: log decoding persists
watches through the keeper watch set, and the
getTradeableOrderWithSignature evaluation moves behind
ConditionalSource. The hand-rolled gate keys, watch-update
lifecycle, submitted: markers, and submit-retry dispatch are
deleted in favour of cow::run over the keeper stores and
retry ledger, still on the legacy CowApiHost seam. The MockHost
dispatch tests are untouched - the behaviour-identity proof for
the port.
@mfw78
feat(sdk-test): namespace the mock local store and share its limits
bf4d14e 
Rework MockLocalStore to mirror the runtime store's shape: namespaced
views over one shared row map, so identical key strings in sibling
namespaces never collide, plus store-wide entry and byte limits that
span namespaces the way one database file does. Fault injection stays
per-view.
@mfw78
feat(sdk-test): add the programmable MockVenue on the cow-api seam
02e6276 
Script per-call venue behaviour where MockCowApi replays one response:
a strictly-draining queue of submit outcomes with a configurable
steady-state fallback, per-route response sequences whose final entry
sticks (a terminal order status persists across re-polls), and venue
fault injection that overrides both without consuming them. MockHost
grows a defaulted venue type parameter so the composed host carries
either mock on the same CowApiHost seam. Acceptance tests drive the
keeper run across multi-tick retry, backoff, and outage
scenarios, and module-shaped strategy code against status sequences.
@lgahdl @claude @mfw78
docs: stale-reference sweep — engine rename, Dockerfile, ADR-0007 err…
2ffdc07 
…ata (#123, #108, #62)

- deployment.md: replace the "planned for M5" Dockerfile sketch with a
  pointer to the real Dockerfile + docker.md; update nexum-runtime log
  directive examples
- qa-signoff.md: nexum-engine → nexum-runtime in crate-dependency row
- adr/0007: add errata noting the nexum-engine → nexum-runtime rename
  and the [patch.crates-io] retirement now that cowprotocol 0.1.0 is
  on crates.io

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TfSsJPYDQ1GQGbnSVFxATx
@lgahdl @claude @mfw78
docs: fix the sweep's own stale claims - cowprotocol override, produc…
a9c0c50 
…tion.md 3.1

Review catches on the stale-reference sweep itself:

- ADR-0007 errata and sdk.md Versioning both claimed cowprotocol is a
  clean 0.1.0 registry dependency "with no git override". The branch's
  own Cargo.toml pins 0.2.0 WITH an active [patch.crates-io] override
  to nullislabs/cow-rs (pending the hash-only OrderCreationAppData
  constructor release). Both now describe that state and point at the
  patch-block comment as the source of truth.
- production.md 3.1 still shipped the "interim" hand-rolled Dockerfile
  recipe issue #123 flagged; replaced with a pointer to the real root
  Dockerfile and docs/deployment/docker.md.
- 02-modules-events-packaging.md: un-garble the parenthetical the
  earlier rename made self-contradictory ("was module.toml in earlier
  drafts" -> "was nexum.toml").

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TfSsJPYDQ1GQGbnSVFxATx
@mfw78
mfw78 force-pushed the docs/108-62-123-sweep branch from 24d9f1b to a9c0c50 Compare July 14, 2026 12:47
@lgahdl

lgahdl commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

Good catch @jean-neiverth — confirmed, and you've identified the exact coordination knot: PR #220 owns that rename (it fixes docker-compose.yml, docs/deployment/docker.md, .env.example, and production.md — all on develop), while this PR sits on the m1 train, whose base predates it. I deliberately did not duplicate the renames here so the same hunks don't get applied twice when the train next rebases over develop.

So the landing order that keeps everything consistent:

  1. fix(packaging): align ghcr image name to ghcr.io/nullislabs/shepherd #220 merges to develop first — it's been review-hardened and MERGEABLE for a while, and it's also soak-relevant (the runbook has operators cp .env.example .env).
  2. The train's next rebase over develop picks the renames up, at which point the files this section cross-references show ghcr.io/nullislabs/shepherd everywhere and the quick start is self-consistent.
  3. This PR merges into the train before or after that rebase — either way no conflict, since it never touches the three files fix(packaging): align ghcr image name to ghcr.io/nullislabs/shepherd #220 owns.

The transient window where an operator could see two names only exists on the train branch between this PR landing and the next rebase — never on develop. If that window bothers us, the alternative is holding this PR until the rebase lands; my preference is the sequencing above since #220 unblocks it.

@mfw78 — this is one more reason to get #220 in ahead of the next train rebase; flagging the dependency here so it's visible when you sequence.

@mfw78
mfw78 force-pushed the feat/m1-mock-venue branch from 02e6276 to 6076837 Compare July 14, 2026 23:33
Base automatically changed from feat/m1-mock-venue to dev/m1 July 14, 2026 23:36
@mfw78 mfw78 added the base: dev/m1 Open PR targets dev/m1 integration branch — merge AFTER develop PRs; develop merged in last. label Jul 15, 2026
@mfw78

mfw78 commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Superseded by #352 — rebased onto current dev/m1, redundant train commits dropped, doc fixes already covered by the landed keeper-prose reconcile dropped, Claude trailers + body footer stripped, authorship preserved (@lgahdl). Closing in favour of #352.

@mfw78 mfw78 closed this Jul 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jean-neiverth jean-neiverth jean-neiverth approved these changes
@mfw78 mfw78 Awaiting requested review from mfw78 mfw78 is a code owner

Assignees

No one assigned

Labels

base: dev/m1 Open PR targets dev/m1 integration branch — merge AFTER develop PRs; develop merged in last.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@lgahdl @jean-neiverth @mfw78