glm-5.2
cc470a363a
Port the call + channels architecture documentation from the alknet mono-repo into docs/architecture/, renumbered as alkcall ADR-001..045. Renumbering map (alknet -> alkcall): Core: 001,002,004,006,007,011,065,070,092,014,050,091 -> 001-012 Call: 005,064,012,023,015,022,024,016,049,017,028,029,030,032,066,069,067,068 -> 013-030 Shared: 003,009,013 -> 031-033 Channels: 071,093,072,073,074,075,076,094,079,080,081,089 -> 034-045 3 superseded/reversed ADRs kept for historical trail: - ADR-013 (irpc foundation, superseded by ADR-014) - ADR-023 (peer-scoped filtering, superseded by ADR-024) - ADR-077 (TTY inside channels, reversed by ADR-035 — not ported, TTY-only) Ported docs (11 spec files + README + open-questions): - call-README.md, call-protocol.md, operation-registry.md, client-and-adapters.md - channels-README.md, channels-overview.md, channels-wire.md, channels-connection.md, channels-adapter.md, channel-operations.md, channel-client.md - README.md (index with doc table, ADR table grouped by category, key principles) - open-questions.md (lean — 30 OQs, renumbered OQ-01..030; includes new OQ-22 for the pub/sub gap) Cross-reference rewriting: - All ADR-NNN references rewritten single-pass (no chaining bug) - Markdown link paths fixed - Title lines aligned with filenames - Non-ported ADR refs (052, 082, 086, etc.) left as-is with README note The open-questions.md includes OQ-22 (new): the call protocol pub/sub gap — subscribe exists but pub does not, needed for channels channel/resources/subscribe fan-out. This is the next ADR to write (alkcall ADR-046).
127 lines
6.0 KiB
Markdown
127 lines
6.0 KiB
Markdown
# 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
|