alknet/docs/architecture/decisions/024-operation-registry-layering.md

ADR-024: Operation Registry Layering

Status

Accepted

Context

The architecture has two registries that the spec documents previously treated as sharing one immutability argument:

1. The endpoint's HandlerRegistry (ALPN string → ProtocolHandler). This is what ADR-010 and OQ-04 are about. Its immutability is load-bearing: ALPN strings are baked into the TLS ServerConfig at startup, so adding a protocol handler at runtime requires rebuilding the TLS config. This is a genuine one-way door and the rationale is correct.

2. The call protocol's OperationRegistry (operation name → HandlerRegistration). This lives inside the CallAdapter, which is one ProtocolHandler behind the single ALPN alknet/call. Adding an operation to the OperationRegistry does not touch the TLS ServerConfig — the ALPN is already alknet/call, registered once at startup.

operation-registry.md stated the operation registry "is immutable after construction… consistent with OQ-04 and ADR-010." That inheritance was by analogy, not by shared rationale. The TLS argument that justifies HandlerRegistry immutability does not apply to the OperationRegistry. The operation registry's mutability profile is a separate question, and it has been answered incorrectly by inheriting a constraint that belongs to a different registry.

Why from_call breaks the inherited constraint

The import adapters have different lifecycle requirements:

• from_openapi / from_mcp can run at startup — the assembly layer reads a static spec file or queries a known service before the registry is frozen. Static import, fits immutability.
• from_call requires a live connection to discover operations (services/list + services/schema). Connections happen at runtime. Workers join and leave dynamically in the machine→worker topology. You cannot pre-freeze a set you discover over a connection you haven't opened yet.

So from_call is structurally incompatible with "frozen at startup, never touched again." The pre-ADR-024 spec held two contradictory positions: the registry is immutable (operation-registry.md), and from_call imports remote operations at connection time (ADR-017). An implementer would have to resolve the contradiction by guessing — likely by either forcing all from_call imports to happen at startup (awkward, doesn't fit worker topologies) or quietly making the registry mutable (undermining the stated constraint without acknowledging it).

Why immutability is not the load-bearing security control for imported ops

Imported operations (FromOpenAPI, FromMCP, FromCall) are leaves — they cannot compose (ADR-022 Assumption 5). They have no composition authority, no scoped env, Internal visibility by default, and their trust model is "the remote endpoint is trusted as much as my own handlers" (ADR-017). Their reachability from a composing handler is bounded by the parent handler's scoped env, not by their registration timing.

The security controls on imported ops are provenance and composition authority — both set at registration, both checked at dispatch. Immutability is redundant here. An imported op registered at runtime is no more or less privileged than one registered at startup; it's a forwarding stub either way, and its capacity to do harm is bounded by what the composing parent's authority and scoped env permit.

Immutability is load-bearing for curated operations — the Local ops the assembly layer writes at startup, which can compose and therefore can escalate privilege under their own authority. For those, the trust boundary is "the assembly layer declared them at startup," and immutability is what locks that declaration. But that's a constraint on Local provenance specifically, not on the registry as a whole.

The trust-boundary principle

The right axis is not visibility (Internal vs External) or wire-vs-local — it is provenance combined with import timing, which maps to where each operation's trust decision is made:

Provenance	Import timing	Trust boundary	Layer	Lifetime
Local	Startup	Assembly layer at startup	0 (curated)	Process — immutable
Session	Sandbox creation	Composing handler at sandbox creation	1 (session)	Session — dynamic
FromCall	Connection (runtime)	Remote node at connection time	2 (connection)	Connection — dynamic
FromOpenAPI / FromMCP	Startup	External endpoint, discovered at startup	0 (curated)	Process — immutable
FromOpenAPI / FromMCP	Runtime (rare)	External endpoint, discovered at runtime	2 (discovery)	Discovery-scoped — dynamic

FromOpenAPI / FromMCP provenance is layer-polymorphic: the same provenance lands in Layer 0 (immutable) or Layer 2 (dynamic) depending on when the import happens. The common case is startup import into Layer 0 (Decision 6); runtime import into Layer 2 is permitted but rare.

Immutability follows the trust boundary. Operations are mutable at the scope where their trust decision is made. Local ops (and startup-imported FromOpenAPI/FromMCP) are trusted at startup → immutable. Session ops are trusted at sandbox creation → session-scoped dynamic. FromCall ops (and runtime-imported FromOpenAPI/FromMCP) are trusted at connection/discovery time → connection/runtime dynamic.

Session ops are the edge case that proves the rule: they are Internal visibility and can compose, but their trust boundary is per-session (the parent handler grants them restricted authority at sandbox creation, per ADR-022 Assumption 6), not per-startup. Visibility alone would misclassify them; provenance correctly identifies them as dynamic.

The precedent: IdentityProvider

The structural problem — N consumers need to resolve something from M sources, don't globalize the sources into one pot, don't make each consumer know about all sources — is the same problem IdentityProvider solves for auth (ADR-004). An IdentityProvider is a trait (Arc<dyn IdentityProvider>) that centralizes resolution policy behind a stable interface; source composition is an impl detail. Handlers consume the result; the trait owns the routing.

OperationEnv is the same problem one layer over: N handlers need to dispatch to operations, operations come from M sources (curated local, this session, this peer connection, that peer connection), don't globalize all sources into one mutable pot, don't make each handler know about all sources and pick the right registry. The solution is the same shape: a trait — Arc<dyn OperationEnv> — that centralizes dispatch routing behind a stable interface, with overlay composition as an impl detail.

The alternative — a single global ArcSwap<OperationRegistry> into which all imported ops merge with namespace prefixes — is the registry equivalent of "every handler reads identity from a global env var." It works at one connection. At many connections it produces: an unbounded pot, namespace collisions scaling with connection count, disconnect cleanup requiring a reverse index (op → owning connection), zero source isolation, and routing-by-naming-convention instead of routing-by-structure. That is the failure mode the IdentityProvider pattern exists to prevent.

Decision

1. The operation registry is layered by trust boundary

The OperationRegistry is not a single flat map. It is a layered structure where each layer corresponds to a trust boundary:

Layer 0 — Curated (static, immutable, startup trust boundary)
  Local provenance operations from the assembly layer.
  Registered once at startup, never mutated for the process lifetime.
  This is where immutability is load-bearing: these ops can compose,
  therefore can escalate privilege under their own authority. The
  startup trust boundary + immutability is the security control.

Layer 1 — Session (dynamic, per-session, sandbox-creation trust boundary)
  Session provenance operations, agent-written, sandboxed.
  Created and destroyed with each session.
  Already specified by OQ-19 as an overlay on Layer 0.

Layer 2 — Imported (dynamic, per-connection, peer trust boundary)
  FromCall operations discovered when a peer connects.
  FromOpenAPI / FromMCP operations when imported at runtime (rare;
  usually at startup into Layer 0, but runtime import is permitted).
  Created and destroyed with the connection / discovery event.

Layers 1 and 2 are the same shape: per-scope dynamic overlays on the static curated base. The scope is "session" for Layer 1 and "connection" (or "discovery event") for Layer 2. OQ-19 already specified the overlay mechanism for Layer 1 (session env wraps global env via OperationEnv trait layering). This ADR generalizes the same mechanism to Layer 2.

2. The OperationEnv trait is the integration point

OperationContext.env is Arc<dyn OperationEnv + Send + Sync> — a trait object, not a concrete struct. This is required by the overlay model: a composite env (curated base + connection overlay + session overlay) is built by composing OperationEnv impls, not by merging registries.

This resolves review #002 finding C6 (OperationContext.env type identity crisis). The pre-ADR-024 spec had env: OperationEnv (a trait, which can't be a field without dyn) and used the same field as both a reachability set (parent.env.allows()) and a dispatch trait (context.env.invoke()). One field cannot be both. The split:

• scoped_env: ScopedOperationEnv — reachability data. Populated from the registration bundle's scoped_env (ADR-022). The reachability check in invoke() consults parent.scoped_env.allows(&name).
• env: Arc<dyn OperationEnv + Send + Sync> — dispatch trait. The handler calls context.env.invoke(...); the trait impl routes to the right overlay.

This is the IdentityProvider-shaped integration point: handlers consume the trait; source composition is an impl detail.

3. The CallAdapter composes the root env per incoming call

When a call.requested arrives over connection C, the CallAdapter does not look up the operation in a single global registry. It composes the root OperationContext.env from the layers active for this call:

root env = CompositeOperationEnv {
    base:       curated_registry_env,       // Layer 0 — static
    connection: C.imported_operations,       // Layer 2 — this connection's overlay
    session:    active_session_overlay,      // Layer 1 — if a session is active
}

The composite impl checks overlays in order (session first, then connection, then curated base) and dispatches to the first match. This is structural source binding: a handler composing worker/exec reaches it via the connection overlay that contains it, not via a naming convention in a global pot.

Env inheritance through composition: the child's env is parent.env.clone() — an Arc::clone, not a re-composition. Overlay composition happens once at the root (in build_root_context) and propagates by Arc through the composition tree. A child handler sees the same active overlays its parent saw. This is deliberate: re-composing per invoke() would re-resolve overlays on every dispatch and would break the session-overlay case (a session that was active when the parent ran must still be active for the child, even if the session ended mid-composition — the child is part of the same call tree the parent started). The root env is composed per incoming call; nested calls inherit it by Arc::clone.

When connection C disconnects, its overlay is dropped. Operations imported from C vanish from the reachable set with no global mutation and no reverse index. Handlers that try to compose a now-gone op receive NOT_FOUND (if the overlay was already dropped when invoke() runs the reachability check) or a connection error with code INTERNAL (if the call was dispatched to the forwarding handler and the connection drops mid-flight). Both cases are clean failures — no stale-handler-binds-to-dead-connection hazard.

4. Curated operations remain immutable; imported and session ops are dynamic

The blanket immutability claim in operation-registry.md is replaced by:

• Layer 0 (curated, Local): immutable after startup. The OperationRegistry holding curated ops is constructed once by the assembly layer and never mutated. This is where the security argument for immutability applies: composing ops are privileged, the startup trust boundary is where that privilege is granted, immutability locks it.
• Layer 1 (session, Session): dynamic, per-session. Created at sandbox creation, destroyed at session end. Already specified by OQ-19.
• Layer 2 (imported, FromCall etc.): dynamic, per-connection. Created when a peer connection completes from_call discovery, destroyed when the connection closes.

Adding a Local op at runtime is not supported — it would require re-entering the startup trust boundary, which is a deployment (restart), not a runtime operation. This preserves the security property ADR-010/OQ-04 were concerned with, scoped to where it actually applies.

5. from_call imports into the connection's overlay, not the global registry

The from_call adapter (ADR-017) discovers operations on a remote peer and produces HandlerRegistration bundles. Under ADR-024, those bundles are registered into the connection's overlay, not a global mutable registry.

// On CallConnection establishment:
let imported = from_call(&connection, config).await;
connection.imported_operations.extend(imported);
// The connection's env now includes these ops.

The handler closures produced by from_call capture the CallConnection — when the connection drops, the handlers become unreachable (their env is dropped), and any in-flight calls to them return connection errors. This is the natural lifecycle; no explicit deregistration is needed.

6. from_openapi and from_mcp default to startup import into Layer 0

For the common case — the assembly layer imports a static OpenAPI spec or connects to a known MCP server at startup — from_openapi / from_mcp register into the curated (Layer 0) registry, which is then frozen. This preserves the pre-ADR-024 behavior for the case where it was correct.

Runtime from_openapi / from_mcp import (e.g., discovering an MCP server at connection time) is permitted and follows the Layer 2 model — the imported ops live in a connection/discovery-scoped overlay. This is additive and does not affect the startup-import path.

7. OQ-04 scope clarification and OQ-19 generalization

This ADR amends OQ-04 to scope its immutability claim to the HandlerRegistry (ALPN-level, ADR-010). The OperationRegistry's mutability profile is now governed by this ADR: curated (Layer 0) is immutable; session and imported layers are dynamic at their trust-boundary scopes. See the OQ-04 amendment in open-questions.md.

This ADR generalizes OQ-19's session-overlay mechanism to also cover connection-scoped remote imports. Both are per-scope dynamic overlays on the static curated base, composed into the per-call OperationContext.env by the CallAdapter. OperationEnv being a trait object is what enables both. See the OQ-19 resolution update in open-questions.md.

Consequences

Positive:

• from_call has a coherent home. Imported ops live with the connection that produced them, appear when the connection is established, and disappear when it closes. No contradiction with immutability, no awkward "import everything at startup" workaround.
• The immutability argument is now correctly scoped. Layer 0 (curated, composing ops) is immutable because that's where the security control applies. Layers 1 and 2 are dynamic because their trust boundaries are per-scope. An implementer reading the spec sees the right constraint in the right place, instead of a blanket claim that doesn't fit all cases.
• The OperationEnv-as-trait constraint (OQ-19) is now required by the overlay model, not just by the session-overlay pattern. The same mechanism (trait layering) supports both session overlays and connection overlays — one pattern, two scopes. This makes C6's resolution (env: Arc<dyn OperationEnv>) structurally motivated, not just a type-system cleanup.
• Disconnect handling is structural. A connection drops → its overlay drops → its ops vanish from the reachable set. No ArcSwap coordination, no reverse index from op to owning connection, no stale handlers bound to a dead connection. This is the same lifecycle property session overlays already have (session ends → session overlay drops).
• Source isolation is structural. Imported ops from peer X are only reachable from handlers whose OperationEnv is wired to X's overlay. They are not globally callable. A handler that shouldn't be able to reach peer X's ops simply doesn't have X's overlay in its env. This is better hygiene than a global registry with namespace prefixes, where every handler sees every imported op and isolation is a naming convention.
• The IdentityProvider precedent makes the design legible. A future reader sees "trait-object integration point, source composition as impl detail" and recognizes the pattern; they don't have to re-derive why trait-composed overlays were chosen over a global mutable registry.

Negative:

• The dispatch path is a composite lookup (session → connection → curated) rather than a single HashMap lookup. This is a small constant cost — three hash lookups in the worst case instead of one — and the overlays are small (a session's ops, a connection's imported ops). The common case (composing a curated op) hits Layer 0 after two empty-overlay misses, which is a predictable and cache-friendly path. The cost is justified by the source isolation and lifecycle properties it buys.
• OperationContext.env is now Arc<dyn OperationEnv + Send + Sync>, which is a trait object with dynamic dispatch. This is the same cost as Arc<dyn IdentityProvider> — a vtable call per invoke(). Negligible relative to the work an operation does, and the same pattern the codebase already uses for auth.
• The CallAdapter has more responsibility: it composes the root env per call from the active layers, rather than handing every call the same global registry. This is expected — the CallAdapter is the integration point for the call protocol, and per-call env composition is the same shape as per-call identity resolution (which the CallAdapter already does via IdentityProvider).
• Naming across overlays: if two connections import ops with the same name (e.g., both peers expose worker/exec), the composite env dispatches to the first overlay that contains the name. This is the same ambiguity FromCallConfig's namespace prefix (ADR-017) was designed to address — the caller disambiguates with a prefix at import time. ADR-024 does not change this; it makes the disambiguation structural (which overlay is in the env) rather than nominal (which prefix is in the name).
• The blanket immutability claim in operation-registry.md and the cross-references that inherit it (the "Two-way door — ArcSwap<OperationRegistry> can be added later" note, OQ-04's framing) must be updated. This is a spec edit, not a migration — no implementation exists yet.

On review #002 findings resolved by this ADR:

• C6 (OperationContext.env type identity crisis): resolved by Decision 2. The field is split into scoped_env (reachability data) and env (dispatch trait object). The split is structurally motivated by the overlay model, not just a type-system cleanup.
• W4 (hot-swap ↔ registry mutability coupling): localized to the connection scope. There is no global mutable registry to hot-swap. Overlays are per-scope and replace naturally with connect/disconnect and session start/end. The schema-drift hazard (a peer re-runs services/list on reconnect and re-imports with a changed schema) moves from global to per-connection — it does not vanish. A handler mid-composition whose peer reconnects with a changed schema sees the old schema until the overlay is rebuilt. This is a per-connection concern, not a global one; the guard clause the review asked for becomes a note on overlay rebuild semantics rather than a global hot-swap protocol.
• W3 (CallClient registry security dimension): partially addressed. The registry-shape sub-question is resolved by the overlay model — a CallClient's incoming-call dispatch uses the same overlay composition, and sharing the curated base with a remote peer is fine (curated ops are trusted). The capability-exposure sub-question (a remote peer calling /llm/generate uses the local node's API key) is not resolved by this ADR — it is a separate concern about what capabilities a remote peer can trigger, and it is unaffected by the registry shape. That sub-question remains open for ADR-017 (a guard-clause note: a peer-scoped subset must filter by capability remote-safety, not just operation name). ADR-024 resolves the dispatch shape; ADR-017 retains the capability-exposure decision.

Assumptions

1. Provenance is knowable at registration time and stable for the registration's lifetime. A Local op does not become FromCall later; a FromCall op does not become Local. If a remote-imported op is later "promoted" to curated, that's a re-registration at the next startup (deployment), not a runtime mutation. Inherited from ADR-022 Assumption 2.

2. Layer 0 immutability is the security control for composing ops. The pre-ADR-024 blanket immutability claim was overbroad but not wrong about Local ops. Curated composing ops must be immutable because the startup trust boundary is where their authority is granted. This ADR narrows the claim, it does not remove it.

3. Imported and session ops do not need immutability as a security control for privilege escalation. Their security against privilege escalation is bounded by provenance (no composition authority → no privilege escalation) and by the parent handler's scoped env (reachability control). This is the central argument; if it's wrong — if a from_call op can escalate in some way provenance + scoped env don't bound — the model needs revisiting. Immutability is not the control for non-escalation threats (availability, schema drift): availability is bounded by per-handler timeouts (ADR-016) and the connection's overlay being drop-on-disconnect; schema drift on reconnect is a per-connection overlay-rebuild concern (see W4 in Consequences), not a global-registry-mutation concern. The point of scoping immutability to Layer 0 is that immutability is the right control for composing ops and the wrong control for non-composing ops; it is not a claim that non-composing ops face no threats.

4. A connection's overlay is the right scope for from_call imports. Operations discovered from peer X are reachable from handlers whose env includes X's overlay. If a use case requires imported ops to be globally reachable (every handler sees every peer's ops), the composite env can be built to include all active connection overlays — but the default is per-connection scoping for isolation.

5. Disconnect → overlay drop → op vanishes is acceptable behavior. A handler composing an op whose peer has disconnected receives NOT_FOUND (or a connection error if the in-flight call was mid-dispatch). This is the same behavior as a peer that never exposed the op. If a use case requires disconnected-peer ops to remain reachable (e.g., cached results), that's a handler-level caching concern, not a registry concern.

6. The root env is composed per incoming call, not cached per connection. The active session overlay can change during a connection's lifetime (a session starts or ends mid-connection), so the env cannot be composed once at connection establishment and reused. build_root_context runs per call.requested and composes the env from the layers active at that moment. The cost (constructing an Arc<CompositeOperationEnv> per call) is negligible — it's three Arc::clones, not three registry traversals.

7. Session-overlay attachment is an agent-crate concern. ADR-024 generalizes OQ-19's session overlay to also cover connection overlays, but the mechanism by which a session overlay attaches to a given wire call (session ID in metadata, payload field, connection-bound session state, etc.) is not specified here. The CallAdapter is wired with an optional session-overlay source by the assembly layer; the lookup mechanism belongs to the agent crate spec (OQ-19: "the agent-specific mechanism belongs to the agent crate spec"). If a wire call has no active session, the root env is curated base + connection overlay (no session layer).

References

• ADR-010: ALPN router and endpoint (the HandlerRegistry immutability argument — this ADR clarifies that it applies to the ALPN registry, not the operation registry)
• ADR-014: Secret material flow and capability injection (capabilities are per-HandlerRegistration bundle, not per-registry — the overlay model doesn't change how capabilities flow; an imported op's capabilities come from its bundle, which for from_call is whatever the assembly layer granted the import)
• ADR-017: Call protocol client and adapter contract (from_call adapter; the FromCallConfig namespace prefix is the disambiguation mechanism this ADR's overlay model uses structurally)
• ADR-022: Handler registration, provenance, and composition authority (provenance is the axis this ADR's layering is based on; the HandlerRegistration bundle shape is unchanged)
• ADR-004: Auth as shared core (IdentityProvider — the precedent for the trait-object integration point pattern this ADR applies to OperationEnv)
• OQ-04: Dynamic handler registration (this ADR amends OQ-04 to scope it to the HandlerRegistry; the operation registry's mutability is now governed by ADR-024)
• OQ-19: Session-scoped operation registries (this ADR generalizes the session-overlay mechanism to connection overlays — same pattern, two scopes)
• docs/reviews/002-pre-implementation-architecture-sanity-check.md (findings C6, W3, W4 — resolved by this ADR)