Effect bus: the crate split (rig-bus, rig-effect-log, registry to rig-agent)

[gold-silver-copper]

Effect bus: the crate split (PR #2445)

Stacked on #2443 (feat/effect-bus); base branch feat/effect-bus, lands by fast-forward push (the repository is squash-only), retarget to main when #2443 merges. Executing prompt: effect-bus/effect-bus-crate-split-pr.md (audited 2026-09-03 against 5a8958620). Toolchain 1.94.0. Four code commits and this description.

What the PR does

Draws the crate line where the dependency edges already were. rig-core keeps the vocabulary and what a handler author implements; a new rig-bus is the runtime; a new rig-effect-log is record and replay; the tool registry moves to rig-agent, the only crate that drives it. Nothing in rig-core names a type from the two new crates, and a guard says so. A Bevy runtime (rig-bevy, next) imports rig-core and rig-bus and nothing agent-shaped.

Crate layout as built

rig-core ──► rig-bus ──► rig-effect-log ──► rig-agent ──► rig (facade)
   │            │                              ▲
   │            └──────────────────────────────┘
   └───────────────────────────────────────────┘

crate	holds	depends on
rig-core	effect (the vocabulary: EffectKind, Outcome, FamilyDescriptor, Family, Key<F>, EffectRecord, model_key/tool_key) and serve (Serve, OutcomeSink, the one erasure ErasedHandler, serve_inline, StreamWriter, the adapters, the driver seam)	providers only
rig-bus	Bus, Dispatcher, Registrar, BusDriver, BusConfig, Recorder, Pending, EffectStream, Handle and the typed views, Typed, wrap_stream; the sync shim and the loom models	rig-core, futures, tracing, serde
rig-effect-log	EffectLog, LogHeader, EFFECT_LOG_FORMAT, stable_hash, EffectLogRecorder, EffectLogReplayer	rig-core, rig-bus, serde
rig-agent	the engine, and now the tool registry: RegisteredTool, ToolSet, ToolDispatch, dispatch_tool, ToolCatalog, ToolLease beside ToolServer	all three

Why the line is here. The vocabulary must sit with the domain types (orphan rule on Family impls and the From<XError> for ErrorReport conversions). The adapters implement Serve over rig-core's six traits, so they stay with Serve. The runtime knows only the vocabulary and ErrorReport. The registry was the one type that straddled the line: it holds an ErasedHandler and mints a Key, and its only driver is ToolServer.

Two seams made explicit.

• The driver seam (rig_core::serve): OutcomeSink::unary, OutcomeSink::stream, OutcomeSink::with_tap, OnOutcome/OnEvent, ErasedHandler::handle, HandlerFuture, StreamTap, finish_unary, stream_truncated. What a bus driver builds to hand a handler its sink and observe what it answers. rig-bus is one such driver; an ECS schedule is another. Public, documented, not hidden.
• The recorder seam (rig_bus::Recorder): handlers, begin, keep_events, event, resolve. BusDriver::record_to takes any Recorder + Clone + Send + Sync and holds it as closures, the way the sink holds its taps, so the driver names no recorder type. EffectLogRecorder implements it.

Key<F> is vocabulary. A typed key is a HandlerKey plus a type-level proof of the family; it holds nothing of the runtime, so it lives in rig_core::effect. This is what lets the registry compile without the runtime and is why the split has no cycle.

Guards, as they follow the code

guard	now
one_erasure	scans rig-core, rig-bus, rig-effect-log, rig-agent; the erasure file is rig-core/src/serve/handler.rs; the typed-view impl scan reads rig-bus's handle.rs; the no-unsafe scan covers all of rig-bus and rig-core's serve/
stream_ids	allows serve/handler.rs and serve/writer.rs
bevy_bus_host	the fixture's rig side must be exactly ["rig-bus", "rig-core"]
dependency_graph	rig-bus and rig-effect-log carry neither tokio nor reqwest; rig-core depends on neither; rig-bus does not depend on rig-effect-log
provider_layout	Exempt rows for both new packages
CI	the loom job runs -p rig-bus -p rig-agent; the wasm matrix checks rig-bus and rig-effect-log

Migration (public breaks)

was	is
rig_core::bus::{Key, model_key, tool_key}	rig_core::effect::…
rig_core::tool::{RegisteredTool, ToolSet, ToolDispatch, dispatch_tool, ToolCatalog, ToolLease}	rig_agent::tool::… (the ToolSet/dispatch_tool paths already resolved there)
rig_core::bus::{Bus, BusConfig, BusDriver, Dispatcher, Registrar, Pending, EffectStream, Handle, ModelHandle, ToolHandle, MemoryHandle, IndexHandle, EmbedHandle, RerankHandle, Typed, Completion, ToolCall, Retrieval, wrap_stream}	rig_bus::…
rig_core::bus::{Serve, OutcomeSink, SinkClosed, ErasedHandler, serve_inline, events_from_response, StreamWriter} and rig_core::bus::adapters	rig_core::serve::…
rig_core::effect::{EffectLog, LogHeader, EFFECT_LOG_FORMAT, stable_hash}	rig_effect_log::…
rig_core::bus::{EffectLogRecorder, EffectLogReplayer}	rig_effect_log::…
BusDriver::record_to(EffectLogRecorder)	record_to(impl Recorder + Clone + Send + Sync)
facade	rig::bus, rig::effect_log (named modules like rig::run); rig::tool::{RegisteredTool, …} under the agent feature

Additive: rig_core::tool::LivenessFn, DynamicTool::into_parts, PortableDynamicTool::into_parts (the seam a registry needs); rig_core::serve::StreamTap and the sink constructors above.

Bench

Unary dispatch, release: median 625 ns, p90 708 ns (the 50 µs threshold test moved with the runtime; a crate boundary is not a call boundary).

Risks, as they stand

• The driver seam is three sink constructors plus the tap types. A second driver may want one OutcomeSink::for_driver(reply, tap); recorded as a follow-up, not done.
• cargo publish --dry-run of rig-bus and rig-effect-log fails against the registry's rig-core (no serve, no effect published yet), as rig-agent's does on rig-reqwest today. Publishing order is rig-core, rig-bus, rig-effect-log, rig-agent.
• The record/replay tests over a live bus now live in rig-effect-log with copies of rig-bus's test helpers (a dev-dependency back onto rig-bus builds the crate twice and the trait impls stop lining up). Two copies of ~150 lines of helpers.

Audit trail

Commit map

commit	subject	finding
e29c116c8	S1 refactor(core): a typed key is vocabulary	CI's doc job caught two [HandlerKey] links in bus/mod.rs that the removed import had been resolving; fixed in S2 (the local gate had run per-crate docs; the fix-forward rule applied)
fdd43d264	S2 feat(agent)!: the tool registry is the agent's	RegisteredTool::from_dynamic reached into DynamicTool's private fields — into_parts is the seam; rig-agent already re-exported ToolSet/dispatch_tool, so the break is smaller than drafted; the facade gates the registry under agent
6ef12d19e	S3 feat!: rig-bus, the runtime as its own crate	OutcomeSink::writer is an inherent method, so StreamWriter stays in rig-core (the prompt had it moving); the sink's tap held the driver's StreamTap — moved into the handler module (audit ruling 1a); Recorder held as closures; the trybuild diagnostic now spells rig_core::serve::handler::Serve
742f12c2e	S4 feat!: rig-effect-log, record and replay as their own crate	a dev-dependency cycle rig-bus → rig-effect-log → rig-bus builds rig-bus twice under test and EffectLogRecorder: Recorder no longer unifies — the seven record/replay tests moved to the log crate with copied helpers

What the split did not find

No hidden coupling beyond the two the audit named (the sink's tap, the writer's inherent method). Every test count held: rig-core + rig-bus + rig-effect-log + rig-agent + rig-verify + rig-derive at 2461, the root guards at 207 (one new dependency-graph test), all six loom models green.

Gate

Fast local gate per commit: fmt, clippy on the workspace, rustdoc -D warnings on the workspace (the CI command, after S1's miss), nextest on the six crates, the root tests/core guards on every commit, the wasm check on rig-core/rig-bus/rig-effect-log/rig-agent, the four fixtures under -D warnings with regenerated lockfiles, loom and the bench on S3 and S4, the publish dry-runs recorded. CI is the gate of record.