docs: ADR bundle (0001-0008) — engine and CoW architectural decisions

[brunota20]

Captures the eight architectural decisions Bleu has made (engine-side) or proposed (CoW host helpers, upstream policy, forward-looking factory pattern) across the M1 → M2 work. All eight carry status proposed pending upstream sign-off; landing them here makes the decisions reviewable independently from the implementing draft PRs (#8, #9, #10).

These ADRs went through internal Bleu review in bleu/nullis-shepherd#1 before opening here.

ADRs are ordered for reading (foundations → CoW infra → CoW helpers → cross-cutting), not chronologically.

Scope

ADR	Title	Implementing PR
0001	Operator engine.toml separate from module nexum.toml	#8, #9
0002	Per-chain alloy provider transport selected by URL scheme	#8, #9
0003	Per-module namespacing in local-store via length-prefixed key	#8
0004	Patch cowprotocol to the head of upstream PR #5	#10
0005	cow-api host backend via cached OrderBookApi per chain	#8
0006	TWAP and EthFlow as intent helpers in shepherd:[email protected]	(design, not yet implemented)
0007	Push CoW Protocol logic to cow-rs first, adopt in engine second	policy
0008	Dynamic address registration for log subscriptions	(design, forward-looking, M3+)

Also adds data/ (engine state_dir default) and skills-lock.json (local skill lockfile) to .gitignore so the engine's runtime state does not pollute the working tree.

Format

ADRs follow the grill-with-docs format: short title, 1-2 paragraph Context, Decision, Considered options (rejected alternatives worth remembering), and Consequences. Frontmatter carries status: proposed and an implemented-in: <PR> pointer where applicable.

Points to weigh on review

• ADR-0003 diverges from docs/04-state-store.md — the linked doc specifies one redb file per module; we propose a single shared file with a [len:u8][module][key] prefix. Rationale in the ADR. This is the one place Bleu deliberately deviates from the published design and needs explicit sign-off.
• ADR-0006 is the M2 grant deliverable design — TWAP and EthFlow as thin host helpers backed by upstream cowprotocol primitives. EthFlow is positioned as the Rust externalization of the ethflow indexer currently inside cowprotocol/services/crates/autopilot/src/database/onchain_order_events/ethflow_events.rs.
• ADR-0007 is the load-bearing policy — five protocol primitives (composable::poll_and_build_order with rich PollOutcome, eth_flow::decode_placement, OrderPostError rich variants + retry_hint, OrderBookApi::with_base_url, wasm32 feature-gate) land as additional commits on cowdao-grants/cow-rs PR #5 and are consumed via the patched dependency in ADR-0004.
• ADR-0008 is forward-looking — does not affect M2 deliverables (TWAP and EthFlow use static subscriptions only). Lands in the 0.2 breaking-change window so adding factory support later does not require a major bump, but the design itself is the least firm of the eight. Internal review flagged the historical-backfill complexity; we already trimmed it. Happy to defer to 0.3 entirely if upstream prefers.

Next

Once feedback comes in, statuses flip to accepted (or superseded) in a follow-up commit. The most likely point of pushback is ADR-0003 (single redb file vs per-module file); the rest of the surface is either gap-filling or implementation choice over interfaces the upstream spec already defines.

[mfw78]

This is interesting. I'm not so sure on this. I'm pretty sure from my understanding that eth_getLogs is capable of being queried by topic without an address for the log to originate from. The question is whether or not this JSON-RPC method is supported by RPCs (i.e. is it a general case that public / free RPCs generally gate on requiring the address as well as the topics?).

[brunota20]

Good question. Combined with an internal complexity flag (the schema and host-function surface adds engine state that no M2 deliverable consumes), ADR-0008 has been deferred entirely (status: deferred, target 0.3). The reference design (Envio HyperIndex-style register-address + topic-only [[subscription.template]]) is preserved as historical context but does not land in 0.2. Topic-only eth_getLogs is explicitly listed as the simplest alternative for the eventual 0.3 conversation; the question of "do public RPCs gate on address" is the right one to validate at that point against a concrete consumer module.

[brunota20]

Heads up: I just force-pushed bleu:docs/adr-bundle to rebuild this PR with the reconciled, M5-current version of all the files originally proposed here. The file set is the same (8 ADRs in docs/adr/, 9 diagrams in docs/diagrams/, the CI workflow, .gitignore, modules/example/Cargo.toml), but the content has been updated to match what actually shipped through M2-M5:

• ADR-0001: nexum.toml -> module.toml rename
• ADR-0003: 32-byte hash namespacing in redb local-store
• ADR-0006: capability gating is link-time (boot validation against KNOWN_CAPABILITIES), not per-call dispatch
• docs/diagrams/diagrams.md: ASCII hyphens per rubric; vapor features (cargo-nexum CLI, separate nexum-sdk crate, :8080/health endpoint, per-module [module.resources] caps) marked as future direction (0.3+ target), with pointers to ADR-0009 for the host-trait seam that supersedes the macro design

Old head: e5579a3 (5 commits). New head: 439bd2f (1 squashed commit). Your prior review threads will need to be re-anchored against the updated text — apologies for the rebase noise, this was the cleanest way to align the PR with shipped reality before you do the final pass.

Surfaced via the 2026-06-23 conformance audit on the bleu fork (see bruno-brain/wiki/projects/shepherd-audits/m2-m5-conformance-2026-06-23.md for the trail).