alkdev/alkcall
6
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: re-key architecture docs off the alknet mono-repo — speak as alkcall

Browse Source 
The ported docs still framed alknet siblings (alknet-core/-call/-channels/
-http/-tls/-client) as live load-bearing context of this crate. With the
extraction complete and alknet headed for glue-level replacement, the docs
now speak as alkcall and cite the real sibling crates (alkhttp, alktls,
alktty, alktunnels, alktrader).

- ADR-054 (new): re-own the verifier-selection rule in-crate — three
  remote roles (public X.509 endpoint / transport relay / hub),
  ServerCertVerifier by PeerEntry presence, RemoteIdentity None
  load-bearing. Provenance: alknet ADR-034 (never ported), demoted to
  footnote. Resolves OQ-21's cross-repo authority gap.
- OQ-43 (new, deferred(scope)): composition-layer ownership and shape
  after the alknet replacement — the named receiver for the
  downstream-side deferrals (OQ-33 endpoint layer, OQ-41 QUIC-native
  substrate, OQ-42 hub broker, OQ-19 persistence adapters, ADR-045 dial
  seam). README layering diagram redrawn with the composition layer as
  TBD-ownership instead of "alknet / alknode" in concrete.
- Spec docs reframed: titles, self-references, dial/TLS/from_jsonschema
  homes, malformed legacy cite rows removed; dead relative research
  paths qualified as source-repo paths.
- ADR amendments (append-only): 027 (alknet-http -> alkhttp), 031 (post-
  extraction state), 044 (split landed as modules in alkcall), 045
  (name normalization; citation-space note).
- Citation hygiene: unprefixed/colliding source-repo cites prefixed
  ("alknet ADR-NNN (provenance)") across 009/011/022/034/035/038/040/
  043/044/045; stale OQ cites corrected (session registries OQ-04, batch
  semantics OQ-03, verifier rule ADR-054); stale anchors fixed.
- README provenance note consolidated; citation conventions documented.

Verification: markdown link check (all local links resolve, all in-crate
ADR cites point at existing decisions/ files); table integrity check
(uniform row widths across open-questions.md and edited tables); residual
alknet-mention sweep (only provenance/historical/intentional framing
remains); architecture review subagent pass with zero remaining criticals.
Docs-only change — no code paths touched.
This commit is contained in:
glm-5.3-flash committed 2026-10-13 10:53:47 +00:00
1 parent 7b8a3e7558
commit 5f019c02f1
26 files changed
+670 -383
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/architecture/README.md
+52 -34
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-13
last_updated: 2026-10-13 (composition re-key, ADR-054, alkcall reframing of ported docs)
---
# alkcall
@@ -9,12 +9,13 @@ The call + channels RPC crate. Structured JSON RPC (operations, streaming
subscriptions, service discovery) and N-channel multiplexing over one
transport stream (channel 0 pre-negotiated as `alk/call`).
This crate unifies `alknet-call` and `alknet-channels` from the alknet
mono-repo, plus the vendored core types formerly in `alknet-core`. The
source architecture docs were ported from
`/workspace/@alkdev/alknet/docs/architecture/` and renumbered as alkcall
ADRs (ADR-001..053). The ALPN strings (`alk/call`, `alk/channels`)
are wire-stable and unchanged — see ADR-004.
This crate is the extraction and unification of the former `alknet-call`
and `alknet-channels` crates plus the vendored core types formerly in
`alknet-core` (see ADR-031). It is a pure protocol crate: no networking,
no transport dependencies — dial, TLS config, and composition live in
downstream crates. The ALPN strings (`alk/call`, `alk/channels`) are
wire-stable — see ADR-004. (Historical origin and cross-repo citation
conventions: see the provenance note at the end of this document.)
## Documents
@@ -69,7 +70,7 @@ are wire-stable and unchanged — see ADR-004.
| [024](decisions/024-peer-graph-routing-model.md) | Peer-Graph Routing Model | PeerCompositeEnv, PeerRef, AccessControl peer auth |
| [025](decisions/025-peerentry-and-identity-id-decoupling.md) | PeerEntry and Identity.id Decoupling | PeerId = Identity.id (stable) |
| [026](decisions/026-forwarded-for-identity.md) | Forwarded-For Identity | Metadata only, never used by ACL |
| [027](decisions/027-from-jsonschema-as-http-adapter.md) | from_jsonschema as HTTP Adapter | FromJsonSchema provenance stays; impl in alknet-http |
| [027](decisions/027-from-jsonschema-as-http-adapter.md) | from_jsonschema as HTTP Adapter | FromJsonSchema provenance stays; impl moved to alkhttp (ex-`alknet-http`) |
| [028](decisions/028-from-call-manual-free-function.md) | from_call Is a Manual Free Function | Assembly layer calls it after dial |
| [029](decisions/029-aggregated-peer-env-wiring.md) | Aggregated Peer-Environment Wiring | Dispatcher hub wiring |
| [030](decisions/030-peer-composite-env-peer-operations.md) | PeerCompositeEnv::peer_operations | OperationEnv::peer_operations override |
@@ -82,7 +83,7 @@ are wire-stable and unchanged — see ADR-004.
| [032](decisions/032-one-way-door-decision-framework.md) | One-Way Door Decision Framework | Reversal cost classification |
| [033](decisions/033-rust-canonical-implementation.md) | Rust as Canonical Implementation Language | Rust canonical, TS reference |
### Channels — ADR-034..045
### Channels, pub/sub, and later amendments — ADR-034..054
| ADR | Title | Relevance |
|-----|-------|-----------|
@@ -106,6 +107,7 @@ are wire-stable and unchanged — see ADR-004.
| [051](decisions/051-channel-relay-and-hub-leg.md) | In-Tree Channel Relay (`ChannelRelay`) and the Hub-Leg Assembly | ADR-042 amended — the relay implementation is an alkcall export; translate hop = ADR-049 establisher (`register_relay_openable`), byte-forward hop = `pump_bidi`; implicit per-channel id mapping; two-phase registration (discover/stash → fork-register); hub-leg install template; ACL layering note |
| [052](decisions/052-channel-control-surface.md) | `channel/control` Control-Handle Surface | Establisher-contributed `ChannelControl` (`Establishment::with_control`), wrapper-installed/teardown-removed in the manager; `channel:no_control_handle` capability answer; resolves OQ-39 |
| [053](decisions/053-resource-enumerators.md) | Live Resource Enumerators | `ResourceEnumerators` (peer-shared registry); snapshot-then-changes enumerator contract; scan-once aggregation; empty seed; resolves OQ-40 |
| [054](decisions/054-outgoing-only-x509-three-remote-roles.md) | Outgoing-Only X.509 and the Three Remote Roles (Re-Owned) | Verifier-selection by `PeerEntry` presence; three remote roles; `RemoteIdentity` `None` semantics — re-owned in-crate (provenance: alknet ADR-034); resolves OQ-21's cross-repo authority gap |
## Relevant Open Questions
@@ -128,6 +130,11 @@ questions affecting this crate:
amendment 2026-10-13, ADR-047 amendment 4 §4.8); the sanctioned
compositions are `ChannelRelay::register_relay_openable` (ADR-051) and
`ChannelClient`.
- **OQ-43** (deferred(scope)): Composition-layer ownership and shape
after the alknet replacement — the named receiver for the
downstream-side deferrals (OQ-33 endpoint layer, OQ-41 QUIC-native
substrate, OQ-42 hub broker, OQ-19 persistence adapters). Not
blocking any alkcall API surface.
## Key Design Principles
@@ -192,8 +199,9 @@ Within a single connection, direction is independent of role:
```
┌──────────────────────────────────────────────┐
│ alknet / alknode │
│ (networking + composition) │
│ Composition layer │
│ (today: the alknet glue — being replaced; │
│ future owner and shape → OQ-43) │
│ │
│ • QUIC / TCP+TLS dial and accept │
│ • Hub: ChannelsAdapter + Dispatcher + │
@@ -201,7 +209,7 @@ Within a single connection, direction is independent of role:
│ • Spoke: ChannelClient + CallConnection + │
│ from_call │
│ • Wires protocol crates' producers into │
│ registries, consumers into clients │
│ registries, consumers into clients │
└──────────────────┬───────────────────────────┘
│ depends on
┌──────────────┼──────────────┐
@@ -245,10 +253,12 @@ alkcall. They provide two halves:
(e.g. `trader_client.status().await` instead of
`call_connection.call("trader/status", ...).await`).
**alk/alknode** depends on alkcall + whichever protocol crates are
needed. It's the composition layer — the only place that knows about
network topology, peer routing, and which protocol crates are wired in.
Protocol crates never import a QUIC or TLS dependency.
**The composition layer** depends on alkcall + whichever protocol
crates are needed. It's the only place that knows about network
topology, peer routing, and which protocol crates are wired in.
Protocol crates never import a QUIC or TLS dependency. Today this
layer is the alknet glue; its post-replacement owner and shape is
tracked as OQ-43.
### Pattern for protocol crates
@@ -285,31 +295,39 @@ A protocol crate that uses channels (e.g. alktty) follows this pattern:
The protocol crate doesn't know which path it's on. It takes a
`BiStream` (or `AsyncRead + AsyncWrite`) and drives the session. The
two adapters are thin and live either in the protocol crate (behind
feature flags) or in the downstream alknet crate.
feature flags) or in the composition layer.
## References
- `@alkdev/alknet: docs/architecture/` — the source architecture docs
these were ported from (renumbered from alknet ADR-001..094 to alkcall
ADR-001..048; ADR-049 and later were authored in this crate)
- `@alkdev/alktype` — the binary struct engine; compiles BAST documents
(e.g. `chunk-header.bast.json`) into readers/writers/validators
- `@alkdev/alkhttp`, `@alkdev/alktls`, `@alkdev/alktty`,
`@alkdev/alktunnels`, `@alkdev/alktrader` — sibling crates; the
live homes of the surfaces older docs call `alknet-http`,
`alknet-tls`, `alknet-tty`, `alknet-tunnels`, `alknet-trader`
- `@alkdev/pubsub` — the TypeScript EventEnvelope prior art the call
wire format was derived from
> **Note**: The source ADRs and spec docs were ported from the parent
> `@alkdev/alknet` workspace where this crate originated. They are
> preserved here as the authoritative spec for alkcall; the alknet
> mono-repo will consume alkcall's versions when it is reworked.
> **Provenance and cross-repo citations.** The source ADRs and spec
> docs were ported from the parent `@alkdev/alknet` workspace where
> this crate originated, and renumbered to alkcall ADR-001..048
> (ADR-049 and later were authored in this crate). They are the
> authoritative spec here; the alknet mono-repo is being replaced by
> thin glue over alkcall and its siblings, so alknet-specific citations
> are expected to decay into footnotes over time, and anything that
> genuinely constrains alkcall's surface gets re-owned by an in-crate
> ADR (e.g. ADR-054 re-owns alknet ADR-034's verifier-selection rule).
>
> **Cross-references to non-ported ADRs**: alkcall's own ADRs are
> `decisions/001..053` in this directory. Some ported docs also cite
> sibling-crate ADRs that were **not** ported (e.g., alknet ADR-052 for
> TTY's wire format, alknet ADR-034 for outgoing-only X.509, alknet
> ADR-082 for alknet-tls, alknet ADR-086 for endpoint types). The alknet
> number space collides with alkcall's (alknet ADR-052 has nothing to do
> with alkcall's `channel/control` ADR-052), so unambiguous references
> carry the `alknet` prefix (e.g., "alknet ADR-052") and link to the
> alknet repo: `/workspace/@alkdev/alknet/docs/architecture/decisions/`
> **Citation conventions**: alkcall's own ADRs are `decisions/001..054`
> in this directory. Some ported docs also cite source-repo ADRs that
> were **not** ported (e.g. alknet ADR-052 for TTY's wire format). The
> alknet number space collides with alkcall's (alknet ADR-052 has
> nothing to do with alkcall's `channel/control` ADR-052), so unambiguous
> references carry the `alknet` prefix (e.g. "alknet ADR-052") and link
> to the alknet repo: `/workspace/@alkdev/alknet/docs/architecture/`
> (a few legacy cites without the prefix still mean the alknet ADR —
> check the link target).
> check the link target). Dead relative paths like
> `docs/research/alknet-channels/...` live in the alknet repo, not this
> one. Similarly, `alknet OQ-NN` citations refer to the alknet repo's
> question tracker — this crate's OQ tracker runs its own numbering
> (OQ-01..43, see [open-questions.md](open-questions.md)).