docs(arch): resolve call-crate OQs, promote OQ-29 to load-bearing on ADR-030

Resolve the call-crate open questions where the decision is made —
OQ-27 (auto-re-import), OQ-28 (same-peer collision = error), OQ-30
(PeerRef::Any insertion-order first-match), OQ-31 (services/list-peers
opt-in). These were previously marked 'open' with 'v1' hedging language
despite having a decided default. What remains (refresh(), richer routing,
services/list-peers the op) is genuine feature addition, not unmade
architecture.

Reframe OQ-32 (multi-hop) as a feature extension rather than a 'v1'
deferral — the one-hop model is the architectural commitment; extending
to multi-hop doesn't break downstream.

Promote OQ-29 (CallClient TLS client-auth) from medium to high priority
and surface its real interaction with ADR-030. Previously framed as
'additive — two-way-door remainder,' but ADR-030's PeerEntry fingerprint
→ peer_id resolution requires the client to present a TLS client cert.
With with_no_client_auth(), no fingerprint is extracted, the PeerEntry
path is dormant, and PeerCompositeEnv keys on None or the API-key prefix
instead of the stable peer_id. This is the activation path for ADR-030's
primary use case, not an additive feature. Three options laid out: (a)
wire client-auth with the ADR-029 migration, (b) ship token-only and
switch later (the 'compounds into a mess' path), (c) extend PeerEntry
to cover auth_token-based identity. Requires a decision before the
migration lands.

Clarify OQ-36 (concrete adapter shapes): the trait shapes and in-memory
adapters ship with core — the deferral is only for the persistence
adapters (SQLite, etc.). The in-memory adapters are real implementations
of a full repo pattern, not stubs.

Update call_client.rs source comment to reference OQ-29 instead of the
'v1' / 'two-way-door remainder' framing.

Workspace green: 326 tests pass, build clean.
This commit is contained in:
2026-06-28 05:35:52 +00:00
parent f224ea998c
commit 1d94aaea51
5 changed files with 224 additions and 151 deletions

View File

@@ -207,17 +207,21 @@ fn build_quinn_client_config(
_credentials: &CallCredentials,
alpn: &[u8],
) -> Result<quinn::ClientConfig, String> {
// v1 connects without client-auth TLS identity: the server-side
// `AcceptAnyCertVerifier` (in alknet-core::endpoint) does not require or
// TODO(OQ-29): connects without client-auth TLS identity. The server-side
// `AcceptAnyCertVerifier` (in alknet-core::endpoint) requests but does not
// verify client certs, so a client cert is not needed to establish a
// connection. Wiring the local node's RawKey/X509 identity as a quinn
// client-auth cert (for servers that *do* verify client identity) is a
// two-way-door remainder — the `credentials.tls_identity` field is
// carried through `CallCredentials` so the assembly layer can populate
// it, and a future task plugs it into the rustls client config. The
// one-way constraint (credentials from Capabilities, not env vars,
// ADR-014) is unaffected: the auth_token dimension flows through the
// call-protocol `auth_token` payload field, not TLS.
// connection. However, without a client cert, the server cannot extract a
// fingerprint, so `IdentityProvider::resolve_from_fingerprint` returns
// None and the peer gets no stable `PeerEntry.peer_id` (ADR-030). This is
// load-bearing on ADR-030's peer-identity model — see OQ-29 for the
// decision needed before the ADR-029 migration lands.
//
// The `credentials.tls_identity` field is carried through `CallCredentials`
// so the assembly layer can populate it; wiring it into the rustls client
// config is the missing piece. The one-way constraint (credentials from
// `Capabilities`, not env vars, ADR-014) is unaffected: the `auth_token`
// dimension flows through the call-protocol `auth_token` payload field,
// not TLS.
let provider = Arc::new(rustls::crypto::aws_lc_rs::default_provider());
let mut config = rustls::ClientConfig::builder_with_provider(provider)
.with_safe_default_protocol_versions()