Files

glm-5.2 f9c0ab092b docs(arch): sync call-completion specs with implementation — Dispatcher/RemoteFilter, ClientError, OQ-29

Post-implementation spec sync after the call-completion batch landed
(commits e4a2594..a3825f5). The sub-agent review flagged no spec drift, but
comparing the implemented types against the spec sketches surfaced five
details the specs didn't name — filled in here so the spec matches what was
built:

- client-and-adapters.md: name the shared Dispatcher (protocol/dispatch.rs)
  + RemoteFilter mechanism that enforces ADR-028's default-deny at dispatch
  time (the load-bearing security gate — checks remote_safe before building
  context, before any capability material reaches the handler). Add
  ClientError/RemoteIdentity types, the spawn_dispatch lower-level API, and
  the services_list_handler_peer_scoped wiring (the assembly layer must
  register the peer-scoped services/list handler for a CallClient's registry,
  not the plain one). Record the v1 TLS client-auth gap (AcceptAnyServerCertVerifier,
  with_no_client_auth) as OQ-29.
- call-protocol.md: point the adapter dispatch-loop description at the shared
  Dispatcher (dispatch.rs) so readers find the mechanism ADR-017 §1 commits to.
- open-questions.md: OQ-29 — CallClient TLS client-auth + remote-identity
  verification is a two-way-door remainder; the no-env-vars invariant is
  unaffected (auth_token flows via call-protocol payload, not TLS).
- READMEs: current-state now reflects completion done + reviewed (207 lib +
  2 integration tests); OQ-29 added to both OQ summaries.

2026-06-26 13:42:42 +00:00

10 KiB

Raw Blame History

status, last_updated, review

status	last_updated	review
draft	2026-06-26	call/review-call passed 2026-06-23 — registry, protocol, ADR (005/012/014/015/016/017/022/023/024), security, and pattern-consistency checks all conformant; 159 unit/integration tests green; `cargo build`, `cargo clippy -- -D warnings`, `cargo fmt --check`, `cargo test` clean. Call-completion gap (ADR-017 client/adapter surface) addressed 2026-06-26 — ADR-028 + client-and-adapters.md added; implementation pending.

alknet-call

Structured RPC over QUIC: operations, request/response, streaming subscriptions, and service discovery. Implements ProtocolHandler on ALPN alknet/call.

Documents

Document	Status	Description
call-protocol.md	draft	CallAdapter, EventEnvelope framing, stream model, PendingRequestMap, bidirectional calls
operation-registry.md	draft	OperationSpec, Handler, OperationRegistry, AccessControl, service discovery, irpc integration
client-and-adapters.md	draft	CallClient (outbound connection opener), from_call / from_jsonschema, OperationAdapter trait, adapter location map, no-env-vars invariant, exchange-of-operations pattern

Applicable ADRs

ADR	Title	Relevance
001	ALPN-Based Protocol Dispatch	CallAdapter registers on ALPN `alknet/call`
002	ProtocolHandler Trait	CallAdapter implements ProtocolHandler
003	Crate Decomposition	alknet-call depends on alknet-core and irpc
013	Rust as Canonical Implementation Language	Adapter traits defined in Rust; TS is reference/browser adaptation
004	Auth as Shared Core	AuthContext passed to call handlers
005	irpc as Call Protocol Foundation	irpc provides framing and service dispatch
006	ALPN String Convention	`alknet/call` ALPN, one ALPN per connection
007	BiStream Type Definition	CallAdapter receives Connection, not BiStream
008	Vault Integration Point	Vault accessed at assembly layer, not on the wire
010	ALPN Router and Endpoint	Static handler registration
012	Call Protocol Stream Model	Bidirectional streams, EventEnvelope, ID-based correlation
014	Secret Material Flow and Capability Injection	Call protocol carries no secret material; capabilities injected at assembly layer
015	Privilege Model and Authority Context	`internal` = authority switch not ACL skip; External/Internal visibility; handler identity + scoped env
016	Abort Cascade for Nested Calls	`call.aborted` cascades to descendants; default `abort-dependents`, `continue-running` opt-in
017	Call Protocol Client and Adapter Contract	`CallClient` opens connections; `from_call` imports remote ops; connection direction independent of call direction
022	Handler Registration, Provenance, and Composition Authority	Registration bundle carries provenance, composition authority, scoped env, capabilities
023	Operation Error Schemas	Operations declare domain errors; `call.error` carries typed `details`; adapter fidelity
024	Operation Registry Layering	Curated (static) + session/connection overlays (dynamic); `OperationEnv` as trait-object integration point; `OperationContext.env` split into `scoped_env` (data) and `env` (dispatch trait)
028	Peer-Scoped Registry Filtering for CallClient Inbound Dispatch	Default-deny peer-scoped registry view; `remote_safe` marking on `HandlerRegistration`; trusted-peer opt-in; locks the ADR-017 §1 security-dimension one-way door

Relevant Open Questions

OQ	Title	Status	Relevance
OQ-07	Call protocol scope within a connection	resolved (ADR-012)	Stream model, multiplexing, scope
OQ-13	Operation path format and routing scope	resolved	`/{service}/{op}` is the correct design; remote dispatch is a separate layer
OQ-14	Batch operation semantics	resolved	Correlated `call.requested` events is the correct protocol design
OQ-16	Safe vault operations for call protocol exposure	resolved (ADR-014)	None exposed for now
OQ-19	Session-scoped operation registries	resolved	Agent-written operations overlaid on curated registry via `OperationEnv` trait layering. Protocol doesn't need changes; `OperationEnv` must remain a trait. Generalized by ADR-024 to cover connection-scoped overlays.
OQ-25	Remote-safe marking shape for CallClient peer-scoped filtering	open (two-way)	Existence of default-deny filtering locked by ADR-028; shape (`remote_safe: bool` v1 vs per-peer allowlist) is the two-way-door remainder
OQ-26	OperationAdapter error type (AdapterError variants)	open (two-way)	`import()` returns `Result<_, AdapterError>`; variants decided in implementation
OQ-27	from_call re-import trigger	open (two-way)	v1 default: auto-on-reconnect; explicit `refresh()` is additive
OQ-28	from_call namespace collision behavior	open (two-way)	v1 default: error on collision (no prefix by default)
OQ-29	CallClient TLS client-auth and remote-identity verification	open (two-way)	v1 connects with `with_no_client_auth()` + `AcceptAnyServerCertVerifier`; wiring RawKey client-auth and a real `ServerCertVerifier` is additive (no-env-vars invariant unaffected — `auth_token` flows via call-protocol payload, not TLS)

Key Design Principles

One connection, full access: An alknet/call connection gives access to the entire operation registry — calls, subscriptions, batch, schema.
Protocol is symmetric: Both sides can initiate calls. The server calling a client uses the same EventEnvelope format and correlation.
Stream-agnostic correlation: PendingRequestMap correlates by request ID, not by stream. The protocol works with any stream arrangement.
Operation registry is layered: The curated layer (Local provenance) is static — registered at startup by the CLI binary, immutable for the process lifetime. Session (Session) and imported (FromCall etc.) ops are dynamic overlays at their respective scopes (per-session, per-connection). The registry supports JSON Schema discovery. See ADR-024.
irpc is one dispatch backend: Local operations dispatch directly. irpc service calls (in-process, type-safe) are internal. The call protocol is the external interface.
Local dispatch only: The operation registry dispatches to local handlers. Remote dispatch (federation, head/worker routing) would be a separate mechanism at a different layer, not a modification to alknet-call's path format.
No secret material on the wire: The call protocol carries no private keys, API keys, mnemonics, or decrypted credentials. Handlers receive outbound credentials through OperationContext.capabilities, injected at the assembly layer. See ADR-014.
Abort cascades to descendants: call.aborted for a parent request cascades to all non-terminal descendants. Default abort-dependents; continue-running opt-in. See ADR-016.
Internal calls switch authority context, not skip ACL: The internal flag marks composition-originated calls. ACL runs against the handler's composition authority, not the caller's and not as a blanket skip. Operations have External/Internal visibility. Scoped composition env bounds reachability. See ADR-015, ADR-022.
Provenance determines composition capability: Only Local and Session ops can compose. Leaves (FromOpenAPI, FromMCP, FromCall) are forwarding stubs — they don't get composition authority or a scoped env. The assembly layer is the sole grantor of composition authority. See ADR-022.
Connection direction is independent of call direction: Who opens the QUIC connection is a connection-layer concern, not a protocol-layer concern. Both sides can call each other once connected. The CallAdapter accepts connections; the CallClient opens them; both produce the same CallConnection and dispatch through the same loop. See ADR-017, client-and-adapters.md.
CallClient registry is default-deny: A CallClient exposes no operations to the remote peer unless explicitly marked remote-safe. Sharing the global registry is an explicit trusted-peer opt-in, never the default. This prevents a remote peer's call from triggering dispatch that populates OperationContext.capabilities from the local node's registration bundle. See ADR-028.
Adapter trait lives with the types; implementations live with their transport: OperationAdapter is in alknet-call; from_call/from_jsonschema are in alknet-call (QUIC / pure parse); from_openapi/from_mcp/to_openapi/to_mcp are in alknet-http (reqwest / axum). alknet-call stays lean — no HTTP client, no HTTP server. See client-and-adapters.md.
No handler reads outbound credentials from any source other than OperationContext.capabilities (no-env-vars invariant): the credential injection path is vault → assembly layer → Capabilities → HandlerRegistration.capabilities → OperationContext.capabilities → handler. Downstream consumers' std::env::var reads are unreachable because the assembly layer never calls Default::default(). See ADR-014, client-and-adapters.md.

10 KiB Raw Blame History