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:cow@0.2.0	(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.