alkcall/docs/architecture/decisions/028-from-call-manual-free-function.md

ADR-028: from_call Is a Manual Free Function, Not Auto-Wired

Status

Proposed (amended 2026-07-16 by ADR-045 §5: CallClient::connect() is removed; from_call is now called by the assembly layer after AlknetClient::dial_* + CallClient::new(...).spawn_dispatch(conn), not after connect(). The manual-free-function decision stands; the connect() references in the body are the pre-ADR-045 shape.)

Context

OQ-27 resolved (2026-06-27): "The decision is auto-re-import on connection establishment. The overlay is per-connection (Layer 2, ADR-019), so a stale overlay dies with the connection; re-import on reconnect is naturally scoped to the new connection."

The spec in client-and-adapters.md §"from_call" (line 358) states: "This is the v1 default; explicit re-import via a future CallConnection::refresh() is additive."

The implementation does not match. from_call is a standalone free function (client/from_call.rs:80). CallClient::connect() does not call it. The assembly layer must call from_call() + register_imported_all() explicitly after every connect(). There is no CallConnection::refresh().

The "v1 default" language is hedging — it makes a committed-but-not-implemented feature sound like a deliberate phase. The spec says "auto-re-import on connection establishment" but the code says "the assembly layer calls from_call immediately after connect()" (the doc comment on from_call, line 76). These are different things: auto-wiring means connect() calls from_call() internally; manual means the caller does it.

The alkapi project identified this as gap G.4: the hedging language in the spec, and the question of whether from_call should be auto-wired into connect().

Decision

from_call is a manual free function. The assembly layer calls it after connect(). It is not auto-wired into CallClient::connect().

Why manual is correct

1. The hub controls discovery timing. A hub may want to verify the connection, resolve the peer's identity, check authorization, and then discover operations. Auto-wiring from_call into connect() would run discovery before the assembly layer has a chance to inspect the connection.

2. Discovery is not always wanted. A pure-client connection to a public X.509 endpoint (ADR-034) has no PeerEntry and no PeerId — the remote is not in the peer graph. Auto-discovering ops on such a connection would register them in a connection overlay that has no peer key, making them unreachable via PeerRef. The assembly layer decides whether to run from_call based on whether the remote is a known peer.

3. The from_call function is already the right API. It takes a &CallConnection and a FromCallConfig, returns Result<Vec<HandlerRegistration>, AdapterError>, and the caller registers the bundles. This is a clean separation: connect, discover, register. Each step is independently testable and independently controllable.

4. Auto-wiring would require from_call to know about the registry. CallClient holds an Arc<OperationRegistry>, but from_call produces HandlerRegistration bundles that the caller registers — the caller decides where to register them (the connection's overlay, a session overlay, or not at all). Auto-wiring would hardcode the registration target.

What changes in the spec

The "v1 default" language in client-and-adapters.md and ADR-022 is replaced with an honest statement: from_call is a free function; the assembly layer calls it after connect(); there is no CallConnection::refresh() for mid-connection re-discovery. A CallConnection::refresh() method is a genuine feature addition — non-breaking, additive — if a deployment needs manual re-discovery without drop-and-reconnect.

OQ-27 is updated: the resolution changes from "auto-re-import on connection establishment" to "manual — the assembly layer calls from_call after connect()." The door type remains two-way (auto-wiring is additive).

What does NOT change

• The from_call function signature, behavior, and tests are unchanged.
• CallClient::connect() is unchanged.
• The re-import-on-reconnect pattern is unchanged: the assembly layer's supervision loop calls from_call after each connect(). The overlay is per-connection, so a stale overlay dies with the connection; re-import on reconnect is naturally scoped. This is the correct behavior — it just isn't automatic.

Consequences

Positive:

• The spec matches the implementation. No hedging language.
• The assembly layer has full control over discovery timing and registration target.
• The separation of concerns (connect / discover / register) is clean and testable.
• No code changes needed — this is a spec correction, not an implementation change.

Negative:

• The assembly layer must remember to call from_call after connect(). This is a documentation concern, not a correctness concern — forgetting to call from_call means the peer's ops are not imported, which is immediately visible (calls to those ops return NOT_FOUND).
• The "auto-re-import on connection establishment" resolution of OQ-27 was aspirational and is now corrected. The resolution was written before the implementation existed; the implementation made the right call (manual), and the spec is catching up.

References

• ADR-022 §3: from_call adapter specification
• ADR-022 Amendments (DC-2): the amended from_call re-import resolution (manual free function)
• ADR-029: Aggregated Peer-Environment Wiring (sibling hub-wiring decision)
• ADR-030: PeerCompositeEnv::peer_operations Override (sibling hub-wiring decision)
• OQ-27: from_call re-import trigger (amended 2026-07-09)
• client-and-adapters.md §"from_call" (updated)
• crates/alknet-call/src/client/from_call.rs:80 — from_call free function
• crates/alknet-call/src/client/call_client.rs:142-168 — connect() does not call from_call
• alkapi gap G.4: from_call wiring + "v1 default" hedging cleanup