ADR-038: Trait-Object & Registry Patterns

CRAIG traits use one of four dispatch styles. Pick by the dominant caller pattern. (Line ranges verified 2026-06-09.)

Selection rule:

Companion trait when typed + polymorphic both needed: ship a Tier-T trait + a separate Tier-O erased seam trait (per ADR-032 §1.1 ErasedAdapter precedent). The erased seam goes in the same crate as the typed contract; impls auto-derive via a declarative macro (impl_erased_adapter! precedent).

A trait MUST live in a crate that the trait declaration’s referenced types + the impls + the callers can all reach via the dep graph. Rust’s orphan rule further constrains: impl Trait for Type is only legal if either the trait OR the type is owned by the crate doing the impl.

The rule has 4 sub-clauses:

Example resolution (ADR-032 amendment A2):

Anti-pattern check: any time a trait’s return type references a type from a downstream crate, the trait is in the wrong crate. If a trait’s impls require depending on the trait’s crate from a crate already-upstream-of, the impls must move to the trait’s crate (orphan rule + dep direction force this).

Known limitation — closed-enum aggregators vs open registries: when an aggregator type (like PartnerAuditEvent) is a closed enum over known impl-types, the "open registry" semantic that ADR-032 §1.2 promises is incomplete. A non-georgia state adding their own partner adapter cannot add a PartnerAuditEvent variant from outside craig-partner-audit. The architectural resolutions are (a) make the aggregator a Box<dyn Trait> or Value-based seam (loses type safety), (b) per-state aggregators (each state’s bundle ships its own typed aggregator), or (c) accept the closed-enum limitation + edit craig-partner-audit per non-georgia state adoption. Plan T inherits option (c); decoupling the closed-enum aggregator from the registry is filed as a future tracking issue.

Registries are immutable lookups built once at boot. Their entries can be:

Per-row and per-request data NEVER flow through registry construction — they flow through the trait method signature (send(format, endpoint, payload)). The factory-shape question is purely about boot-time resource availability.

Selection rule: use factory shape if EITHER of these is true at BOOT TIME:

Per-row data (e.g. exchange_partners.endpoint + exchange_partners.format from DB) and per-request claims are NOT boot-time inputs — they belong on the trait method signature (send(format, endpoint, payload)), NOT as factory parameters or per-instance state.

Otherwise use pre-materialized values.

Concrete dispatch shape: ErasedAdapter::send_value(endpoint: String, payload: Value, format: Option<&str>) carries per-row format on the method signature. Current SHINES at services/craig-exchange/src/adapters/standard.rs:214 stores format as a per-instance field; ADR-038 §3 says per-row data goes on the call site (not factory). The migration removes the per-instance field + threads format through every call.

Mutability + re-entrancy: registries are write-once at boot; mutation requires a service restart. Cross-registry lookup DURING construction is forbidden — the boot orchestrator materializes registries in dep-order (e.g. partner_type_registry before adapter_registry if adapters consult partner_types). An adapter constructor MAY consult BootContext (boot-time-constructed inputs) but MUST NOT consult another registry by reference; doing so creates boot-order dependencies the orchestrator can’t validate.

Companion: BootContext. Factory shape requires a context type that flows through the orchestrator at materialization time. CRAIG convention: a per-crate BootContext struct that grows additively for genuinely-new resources (Plan W adds plugin_registry; etc.). The lone exception is Plan V Step 2, which replaced the original http_client: reqwest::Client field with transport: Arc<dyn OutboundTransport> rather than adding alongside it — exposing the concrete wire client beside the transport abstraction would leak the very library the seam hides; the additive convention still governs every other resource. The orchestrator constructs BootContext once at boot and passes &BootContext to each factory.

Aggregate types like BundleContribution (per ADR-032 §2.1) carry contributions from N bundle authors. Each field has a source-crate constraint: the field’s value type must originate in a crate the bundle author’s crate can see (i.e. upstream of the bundle author’s crate in the dep graph).

Rule: a field F: T on aggregate A whose value comes from bundle crate B_i REQUIRES that type T lives in a crate B_i depends on.

Example resolution (ADR-032 amendment A5 — mock_routes ownership):

Field-sourcing pre-flight: before adding a field to BundleContribution, trace the shortest dep path from each potential bundle author’s crate to the field’s value type. If the path doesn’t exist, restructure either the field type or the source location BEFORE the field lands.

§4 applies to AGGREGATES contributed-to by multiple author crates. Single-producer aggregates resolve trivially.