docs(arch): ADR-029 peer-graph routing model — supersedes ADR-028
ADR-028's remote_safe/trusted_peer was a parallel, weaker authorization system
that duplicated the existing AccessControl/Identity machinery and couldn't
express the head→N-workers pattern (the primary use case). The flat-namespace
single-peer overlay model (one connection layer in CompositeOperationEnv)
structurally breaks the moment a head has two workers both exposing
/container/exec.
ADR-029 replaces it with:
- Peer-keyed overlays: PeerCompositeEnv { connections: HashMap<PeerId, ...> }
replaces CompositeOperationEnv's singular connection layer. A head node
routes invoke_peer() to the right peer via PeerRef::Specific / PeerRef::Any.
- AccessControl-based peer authorization: the existing AccessControl::check
(peer_identity) gates peer calls — the same mechanism that gates every other
call. remote_safe/trusted_peer/RemoteFilter/list_operations_peer_scoped/
services_list_handler_peer_scoped are retired. The op's AccessControl IS the
peer-authorization policy; no parallel system.
- ScopedPeerEnv: peer-qualified reachability (peer-pinned allowlist) replaces
from_call's namespace_prefix as the disambiguation mechanism. Cross-peer
collision dissolves (separate sub-overlays); same-peer collision stays error.
- services/list-peers opt-in for peer-attributed re-export listing.
POC-validated against real types (scratch module written, type-checked,
removed; build clean, 207 tests pass). Petgraph not needed for v1 (one-hop,
shallow); nested HashMap suffices; extends to multi-hop without redesign (OQ-32).
OQ impact: OQ-25 dissolved (no marking); OQ-28 cross-peer dissolved / same-peer
stays; OQ-26/27/29 stay; new OQ-30 (Any routing policy), OQ-31 (list-peers
semantics), OQ-32 (multi-hop federation).
Research: docs/research/alknet-call-peer-routing/findings.md (POC shapes,
prior art — Ray.io actors, Dapr service invocation, full ADR draft).
ADR-028 marked Superseded; ADR-017 DC-1 amendment updated to point at ADR-029.
This commit is contained in:
@@ -360,19 +360,20 @@ noted re-import hot-swap is a two-way door; §3 mentioned the namespace prefix).
|
||||
The call-completion gap analysis (`docs/research/alknet-call-completion/gap-analysis.md`
|
||||
DC-1..4) resolved them. The resolutions:
|
||||
|
||||
### DC-1 — CallClient registry scope: resolved by ADR-028
|
||||
### DC-1 — CallClient registry scope: resolved by ADR-028, superseded by ADR-029
|
||||
|
||||
The §1 Consequences security dimension is resolved by
|
||||
[ADR-028](028-callclient-peer-scoped-registry-filtering.md). The one-way
|
||||
door (existence of peer-scoped filtering as the v1 default) is locked:
|
||||
**default-deny**, with a `remote_safe: bool` on `HandlerRegistration`
|
||||
v1 shape and a trusted-peer opt-in. The shape of the marking is the
|
||||
two-way-door remainder, tracked as OQ-25. This ADR's §1 text ("It has its own
|
||||
operation registry to dispatch incoming calls from the remote side") and
|
||||
the Consequences note ("The specific mechanism … is a two-way door") are
|
||||
superseded by ADR-028's decision that the *default* is filtered, not
|
||||
shared-global. Share-global remains available as the explicit opt-in
|
||||
(ADR-028 §3).
|
||||
The §1 Consequences security dimension was originally resolved by ADR-028
|
||||
(default-deny `remote_safe: bool` + `trusted_peer` opt-in). **ADR-028 is now
|
||||
superseded by [ADR-029](029-peer-graph-routing-model.md)** (2026-06-27):
|
||||
the flat-namespace single-peer model ADR-028 built on cannot express the
|
||||
head→N-workers pattern, and the `remote_safe`/`trusted_peer` gate duplicates
|
||||
the existing `AccessControl`/`Identity` machinery while reintroducing the
|
||||
blanket-bypass anti-pattern ADR-015 killed. ADR-029 replaces the flat overlay
|
||||
with peer-keyed overlays + `PeerRef` routing, and retires `remote_safe`/
|
||||
`trusted_peer` in favor of `AccessControl::check(peer_identity)` — the
|
||||
existing authorization path that was already in the dispatch path. The peer-
|
||||
scoping question this section flagged is now answered structurally (peer-keyed
|
||||
overlays), not by a parallel boolean gate.
|
||||
|
||||
### DC-4 — OperationAdapter trait error type: resolved
|
||||
|
||||
|
||||
Reference in New Issue
Block a user