docs: port architecture specs + 45 ADRs from alknet, renumbered
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).
This commit is contained in:
1 parent
1ceb9b785d
commit
cc470a363a
58 files changed
+16729
No files matched your search
@@ -0,0 +1,126 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user