Module router 

Lifecycle router skeleton: pre-dispatch validation and adapter resolution.

Lifeloop owns lifecycle event routing as a neutral mechanism. Clients own product behavior: a client receives the routed event via a callback and decides what (if anything) to deliver. The router is the seam that turns a CallbackRequest plus the adapter manifest registry into a typed RoutingPlan that downstream stages — capability negotiation, callback invocation, receipt emission, failure mapping — consume without re-validating wire-level invariants.

Boundary (issue #7, skeleton slice)

This module owns:

• pre-dispatch validation of crate::CallbackRequest envelopes (schema version, non-empty identifiers, frame-context invariants, payload-ref structure);
• adapter manifest resolution by both adapter_id and adapter_version (the two are distinguished failure classes — wrong id is not the same as wrong version of a known id);
• synthesis of a typed RoutingPlan that names the resolved adapter and preserves opaque PayloadRefs for downstream stages;
• the trait seams through which later issues plug in negotiation, callback invocation, receipt emission, and failure mapping.

This module does not own:

• capability negotiation (future router issue) — see NegotiationStrategy;
• callback invocation against renderers (issue #3 will wire a protocol renderer into CallbackInvoker) — see CallbackInvoker;
• receipt persistence/emission (future router issue) — see ReceiptEmitter;
• failure-class mapping for receipt synthesis (future router issue) — see FailureMapper;
• payload body inspection. The router treats crate::PayloadRef and crate::PayloadEnvelope bodies as opaque: it does not parse, transform, or pattern-match on payload contents.

Client compatibility

This module has none. It is provider-neutral by construction. Any historic host-adapter flow that fused lifecycle routing with client product semantics is replaced by Lifeloop routing plus client callbacks — every client (including the first one) becomes a consumer of these seams, not a peer of the router.

Structs

BuiltinAdapterRegistry

Adapter registry backed by crate::manifest_registry.

CapabilityRequest

A client’s capability request for one lifecycle dispatch.

CapabilityRequirement

One requirement in a CapabilityRequest.

DefaultCallbackInvoker

Concrete CallbackInvoker for issue #14.

DefaultNegotiationStrategy

Concrete NegotiationStrategy for issue #13.

FnClientCallback

Adapter that lifts any Fn(&CallbackRequest, &[PayloadEnvelope]) -> Result<CallbackResponse, E> into a ClientCallback.

IdempotencyKey

Composite key the idempotency store uses internally. The spec scopes idempotency by (client_id, adapter_id, idempotency_key) — the key type pins that triple so a consumer’s persistent store cannot accidentally collapse the scope.

InMemoryIdempotencyStore

In-memory reference IdempotencyStore backed by a HashMap behind a Mutex for interior mutability through &self.

LifeloopFailureMapper

Concrete FailureMapper for issue #15.

LifeloopReceiptEmitter

Concrete ReceiptEmitter for issue #14.

NegotiatedPlan

Negotiation result wrapping a RoutingPlan.

ReceiptContext

Caller-supplied identifiers and clock value Lifeloop cannot synthesize on its own. Every field except the harness ids is required.

RoutingPlan

Pre-dispatch routing plan produced by route.

SequenceGenerator

Per-lifeloop_run_id monotonic sequence counter.

SubprocessCallbackInvoker

Subprocess-backed CallbackInvoker.

SubprocessInvokerConfig

Configuration for SubprocessCallbackInvoker.

Enums

AdapterResolution

Resolution outcome for an (adapter_id, adapter_version) pair.

CapabilityKind

Vocabulary of lifecycle capabilities a client can name in a CapabilityRequest.

PayloadPlacementDecision

Per-payload placement decision produced by negotiation.

PlacementRejection

Why a particular AcceptablePlacement was rejected during per-payload placement evaluation.

ReceiptError

Failure variants from receipt emission.

RouteError

Reasons the router refused a crate::CallbackRequest before dispatch.

StoreOutcome

Outcome of a successful IdempotencyStore::put.

SubprocessInvokerError

Failure variants surfaced by SubprocessCallbackInvoker::invoke.

TransportError

Coarse shape of a callback-transport failure.

Traits

AdapterRegistry

Source of AdapterManifests the router consults at dispatch time.

CallbackInvoker

Callback invocation seam.

ClientCallback

Pluggable client-callback seam.

FailureMapper

Failure-class mapping seam.

IdempotencyStore

Replay-boundary store. Distinct trait so a consumer can plug in a real database without this module knowing.

NegotiationStrategy

Capability negotiation seam.

ReceiptEmitter

Receipt emission seam.

Functions

classes_for_negotiation_outcome

Map a NegotiationOutcome to a (failure_class, retry_class) pair when the outcome blocks dispatch. Returns None for non-blocking outcomes (Satisfied, Degraded).

failure_class_for_receipt_error

Map a ReceiptError to a FailureClass.

failure_class_for_route_error

Map a RouteError to a FailureClass.

failure_class_for_subprocess_error

Map a SubprocessInvokerError onto the shared FailureClass vocabulary.

failure_class_for_transport

Map a TransportError to a FailureClass.

negotiate

Negotiate a CapabilityRequest (and any payload envelopes) against an existing RoutingPlan.

retry_class_for

Per-failure default retry-class hint.

route

Validate a CallbackRequest and resolve its adapter against the supplied AdapterRegistry, producing a RoutingPlan.

synthesize_request

Synthesize the outbound CallbackRequest from a RoutingPlan. Free function (does not depend on the client type) so tests can inspect what the invoker would dispatch without naming a ClientCallback.

transport_error_for

Convert a SubprocessInvokerError into the shared TransportError enum so callers that already speak in super::LifeloopFailureMapper::map_transport_error terms can route subprocess failures through the same path. None for variants that are not transport-class (validation, parse, receipt-emitted rejection).

validate_receipt_eligible

Validation-layer guard: refuse to plan receipt synthesis for a receipt.emitted event.