docs: ADR bundle 0001-0007 — 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 mfw78 sign-off; landing them here makes the decisions reviewable independently from the implementing draft PRs in nullislabs/shepherd (nullislabs#8, nullislabs#9, nullislabs#10).

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	nullislabs#8, nullislabs#9
0002	Per-chain alloy provider transport selected by URL scheme	nullislabs#8, nullislabs#9
0003	Per-module namespacing in local-store via length-prefixed key	nullislabs#8
0004	Patch cowprotocol to bleu/cow-rs main	nullislabs#10
0005	cow-api host backend via cached OrderBookApi per chain	nullislabs#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 (Envio-style)	(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.

Highlights worth mfw78's attention

• 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 ADR where 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. The EthFlow module is positioned as the Rust externalization of the ethflow indexer currently inside cowprotocol/services/crates/autopilot/src/database/onchain_order_events/ethflow_events.rs, in line with how watch-tower and refunder were extracted.
• 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 in bleu/cow-rs first 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.

Next

Once mfw78 reacts, 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 mfw78 already specified.

[yvesfracari]

I think that here we have another decision to make. If we need to make historical index as well. Let's discuss this with mfw but it makes the project more complex without need

[brunota20]

When sending this to mfw, I will comment that this last ADR is discussable