docs: roles, composition, and dependency layering for downstream crates

- docs/architecture/README.md: add Roles and Composition section with
  the four roles (producer, consumer, hub, spoke), dependency layering
  diagram, protocol crate pattern, and the two-path adapter model
- docs/architecture/channels-overview.md: fix stale alknet ADR numbers
  (071/072/073/074/075/076/077/078/079/080/081 -> 034-044), update
  relationship section for post-extraction world, update crate
  dependencies to reflect single-crate alkcall
- src/lib.rs: add Downstream composition section with role table and
  protocol crate pattern, linking to the architecture README

Verification: cargo test (483 passed), cargo clippy (clean),
cargo fmt (clean), cargo doc (no warnings)
This commit is contained in:
deepseek-v4-pro committed 2026-08-14 09:25:18 +00:00
1 parent 6c5aa0c8e1
commit 7cd8a57bc7
3 files changed
+250 -104

No files matched your search

+39
View File
@@ -28,6 +28,45 @@
//! pre-negotiated as `alknet/call`; channels 1..N are opened via
//! per-ALPN open ops (`channels/<alpn>/sub`, `channels/<alpn>/pub`)
//! on channel 0 (ADR-047).
//!
//! ## Downstream composition
//!
//! alkcall is a pure protocol crate — no networking, no transport
//! dependencies. Downstream crates compose on top of it in a layered
//! dependency chain. See `docs/architecture/README.md` §"Roles and
//! Composition" for the full layering diagram and role definitions.
//!
//! ### The four roles
//!
//! | Role | Call protocol | Channels protocol |
//! |------|---------------|-------------------|
//! | **Producer** | Registers ops on an `OperationRegistry`, runs a `Dispatcher` | Runs a `ChannelsAdapter`, registers openable ALPNs via `ChannelCore::register_openable` |
//! | **Consumer** | Uses `CallConnection` to call ops, uses `from_call` to discover/import remote ops | Uses `ChannelClient` to open channels via `call_open_op` + `open_channel` |
//! | **Hub** | Both: runs a `Dispatcher` for ops it produces, holds `CallConnection`s to spokes for ops it consumes | Both: runs a `ChannelsAdapter` for inbound connections, holds `ChannelClient`s to spokes |
//! | **Spoke / Worker** | Both: produces ops (its own services), consumes hub ops | Both: produces channels (TTY, tunnel), may consume hub channels |
//!
//! A single process can be a producer of some ops, a consumer of others,
//! a channel opener for TTY, and a channel acceptor for tunnels — all on
//! the same `alknet/channels` connection.
//!
//! ### Pattern for protocol crates
//!
//! A protocol crate (e.g. alktty, alktunnels) depends only on alkcall
//! and provides two halves:
//!
//! 1. **Producer half** — a `register_*()` function that takes an
//! `&mut OperationRegistry` and registers ops with their handlers.
//! For channels-based protocols, an `OpenHandler` factory registered
//! via [`channels::operations::ChannelCore::register_openable`].
//! 2. **Consumer half** — a typed client wrapper around
//! [`protocol::connection::CallConnection`] (or
//! [`channels::client::ChannelClient`]) that exposes the crate's ops
//! as async methods.
//!
//! The protocol crate doesn't know whether it's running on a hub, a
//! spoke, or a standalone process. The networking + composition layer
//! (alknet/alknode) wires protocol crates' producers into registries
//! and consumers into clients.
pub mod channels;
pub mod client;