alknet/docs/architecture/decisions/085-workspace-scope-core-vs-consumer-repos.md

ADR-085: Workspace Scope — Core vs. Consumer Repos

Status

Accepted

Context

The original crate decomposition (ADR-003, 2026-06) listed a flat workspace of ~12 crates: alknet-core, alknet-vault, alknet-ssh, alknet-call, alknet-agent, alknet-git, alknet-sftp, alknet-msg, alknet-http, alknet-dns, alknet-napi, and a CLI binary. This was written before two things were clear:

1. Channels (ADR-071) — a multiplexing substrate that carries alknet/call on channel 0 and any ALPN on data channels. Channels did not exist when ADR-003 was written; it was created to solve a pain point that surfaced writing the first consumers. Channels changed the shape: a "hub" is a channels hub, a "worker" is a channels worker, and most protocol handlers (TTY, tunnels, SFTP, SOCKS5, git, SSH) ride inside channels as data-channel ALPNs, not as top-level endpoint ALPNs.

2. The hub/worker topology (ADR-029, ADR-034, ADR-079) — the deployment shape where a central hub accepts worker connections, relays channels between legs, and aggregates operations. This is the "vpn-like without being a vpn" target. A hub is one who initiates an AlknetEndpoint serving many transports; a worker dials out to a hub. A hub-worker does both.

Because ADR-003's flat list was never revised, the overview's crate graph has been describing the wrong scope the entire time. It lists crates that should be consumers in separate repos (alknet-agent, alknet-docker) and omits crates that are core to the actual target (alknet-tls, alknet-channels, alknet-hub, alknet-worker, alknet-tty). It also lists crates that were never specced and are not part of the current scope (alknet-dns, alknet-msg, alknet-napi).

This stale scope is a causal factor in the "assembly layer" hedging pattern. When the overview implies everything lives in one repo, but the actual architecture requires a hub/worker composition layer that isn't in the graph, agents fill the gap with "assembly layer" as an escape hatch — a path-of-least-resistance solution to an impossible bind. The fix is not to suppress the hedging; it's to make the scope clear so the bind doesn't arise.

What "core" means now

The alknet mono-repo is the core networking toolkit — the crates that a hub, a worker, or a hub-worker are built from, plus the protocol handlers that are foundational to the "p2p-capable vpn-like without being a vpn" target. Crates that build on top of a hub or worker (docker operations, agent, future applications) are consumers in their own repos — they depend on alknet-call / alknet-channels / alknet-hub / alknet-worker, not on alknet-core directly.

The distinction is:

• Core mono-repo: the substrate (core, tls, call, channels), the deployment shapes (hub, worker), and the foundational protocol handlers that every hub/worker needs (tty, tunnels, fs, sftp, ssh, http). Vault is core because it's foundational to ACL (key derivation, identity).
• Consumer repos: crates that build on top of a hub or worker (docker operations, agent, future applications). These are independent repos that depend on the published core crates.

The foundational handlers

The protocol handlers that are foundational to the vpn-like target ride inside channels as data-channel ALPNs:

ALPN (inside channels)	Crate	Status
alknet/tty	alknet-tty	specced (ADR-052–057), implemented
alknet/tunnel	(in alknet-channels or a sibling)	POC-validated, not yet specced — minimal (the channels POC covers this use case)
alknet/socks5	(TBD)	not yet discussed — SOCKS5 proxy over channels
alknet/fs	(TBD)	not yet specced — filesystem access over channels
alknet/sftp	(TBD)	not yet specced — SFTP protocol core over channels

Additionally, alknet-http (the HTTP edge case — registration endpoint, browser access, MCP/OpenAPI adapters) and a future alknet-ssh (russh server channels wrapper as an option for hubs, for git/sftp compatibility) are core mono-repo concerns because they are part of the hub's inbound surface.

What leaves the mono-repo

Crate	Destination	Why it's a consumer, not core
alknet-docker	own repo	Docker operations build on top of a hub/worker — a docker host is a worker, not a substrate concern. Depends on alknet-call + alknet-tty, not on core transport.
alknet-agent	own repo	The agent builds on alknet-call for tool dispatch — it's an application, not networking substrate.

These specs are kept in docs/architecture/crates/docker/ for reference (the work is not lost), but the crates move to their own repos as consumers. The overview's crate graph no longer lists them as mono-repo members.

What was never in scope (and is removed from the graph)

alknet-dns, alknet-msg, alknet-napi were listed in ADR-003's flat decomposition but were never specced, never implemented, and are not part of the current target. They are removed from the overview's crate graph. If a DNS or messaging handler becomes needed, it will be a consumer repo (a handler that rides inside channels or registers on the endpoint), not a mono-repo member. NAPI projection, if needed, lives with whatever consumer needs the Node.js bridge.

Decision

The alknet mono-repo scope is the core networking toolkit

The mono-repo contains the substrate, the deployment shapes, and the foundational protocol handlers. Everything else is a consumer in its own repo.

alknet mono-repo (the core networking toolkit)
│
├── Substrate
│   ├── alknet-core      (ProtocolHandler, endpoint, auth, config, Connection)
│   ├── alknet-tls       (shared TLS config — ADR-082)
│   ├── alknet-call      (call protocol on alknet/call)
│   └── alknet-channels  (multiplexing substrate on alknet/channels — ADR-071)
│       ├── alknet-channels-core  (pure multiplexer — ADR-081)
│       └── alknet-channels-call   (channel 0 pre-negotiation — ADR-081)
│
├── Deployment shapes
│   ├── alknet-hub       (channels hub — accepts workers, relays, aggregates)
│   └── alknet-worker    (channels worker — dials out to a hub)
│
├── Foundational handlers (inside channels as data-channel ALPNs, or on the endpoint)
│   ├── alknet-tty       (alknet/tty — specced, implemented)
│   ├── alknet-http      (h2/http1.1 + WebSocket — the HTTP edge case)
│   ├── alknet-tty-local (PTY/pipe backend — sibling crate)
│   ├── alknet-ssh       (russh server channels wrapper — for git/sftp compat) [not yet specced]
│   ├── alknet-tunnel    (alknet/tunnel — POC-validated, minimal spec needed) [not yet specced]
│   ├── alknet-socks5    (SOCKS5 proxy over channels) [not yet specced]
│   ├── alknet-fs        (filesystem access over channels) [not yet specced]
│   └── alknet-sftp      (SFTP over channels) [not yet specced]
│
└── alknet-vault         (standalone — foundational to ACL: key derivation, identity)

Dependency rules

• The substrate crates (core, tls, call, channels) depend on each other in a clean DAG: channels → call → core; tls → core. No cycles.
• alknet-hub and alknet-worker depend on the substrate (channels, call, core) and on the handlers they wire. They are consumers of the substrate, not part of it.
• Foundational handlers depend on alknet-core (for ProtocolHandler, Connection) and/or alknet-channels (for ChannelBidiStreamSource, into_sub_streams). No handler depends on another handler — cross-handler communication goes through alknet/call on channel 0.
• alknet-vault is standalone (zero alknet crate dependencies — ADR-018). It is foundational to ACL: the hub/worker identity model (IdentityProvider, PeerEntry, fingerprint resolution) derives from vault-managed keys. Vault is accessed only at the assembly layer (ADR-019); handlers receive derived credentials via capabilities (ADR-014), never a vault reference.
• Consumer repos (docker, agent, future applications) depend on the published core crates (alknet-call, alknet-channels, alknet-hub, alknet-worker), not on alknet-core directly.

The hub/worker model

A hub is a channels hub — it accepts inbound connections (over quinn, iroh, TCP+TLS — ADR-083), runs ChannelsAdapter on alknet/channels, relays data channels between legs (ADR-079), aggregates workers' operations into a shared env, and serves the discovery API. A hub may also serve HTTP (h2/http/1.1 for registration and browser access) and, optionally, an SSH server (russh channels wrapper for git/sftp compatibility).

A worker is a channels worker — it dials out to a hub via ChannelClient, runs from_call to discover the hub's (and other workers') operations, and exposes its own operations on channel 0. A worker has no inbound endpoints unless it is also a hub (hub-worker).

A hub-worker does both — accepts inbound and dials out. This is a valid deployment shape; the topology is not strictly hierarchical.

The bidirectionality of call and channels means both sides can be both hub and worker within a connection. A hub (A) that uses a client to connect to another hub (B) is, from B's perspective, a worker. This does not require a separate "hub-as-client" abstraction — the ChannelClient / CallClient take-over APIs (from_connection, spawn_dispatch) are transport-agnostic and work regardless of whether the dialer is a hub, a worker, or a hub-worker.

ADR-003 is amended

ADR-003's flat crate table is superseded for scoping purposes. The "one crate per protocol handler, core provides shared infra" principle survives; the specific crate list does not. The crate list is now this ADR's scope table. ADR-003's amendments (the alknet-call as protocol-foundation clarification, the alknet-tty no-alknet-call clarification, the irpc removal) survive — they are about dependency edges, not about which crates are in the mono-repo.

Consequences

Positive:

• The overview's crate graph will match reality for the first time. Future sessions start with an accurate scope, not a stale flat list that implies the wrong boundary.
• The "assembly layer" escape hatch has a bounded home: the hub and worker crates. "Assembly layer" = the deployment binary (hub, worker, or hub-worker), not a dump for unknowns. This is the fix for the hedging pattern's root cause.
• Consumer repos (docker, agent) are unblocked — they can be developed independently against the published core crates, without waiting for the mono-repo to accommodate their concerns.
• The scope is narrow enough to finish. Six substrate + deployment crates (core, tls, call, channels, hub, worker) plus the foundational handlers (tty, http, ssh, tunnel, socks5, fs, sftp) plus vault is a bounded surface. The previous scope (~12 flat crates including DNS, messaging, NAPI) was never the target.
• The foundational handlers that ride inside channels (tunnel, socks5, fs, sftp) are correctly scoped as channels data-channel ALPNs, not top-level endpoint handlers. This is the "p2p-capable vpn-like" shape — these services are available over channels, with the ACL and bidirectionality that channels + call provide.

Negative:

• alknet-docker and alknet-agent leave the mono-repo. Their specs stay in docs/architecture/crates/docker/ (and a future crates/agent/ if specced) for reference, but the crate code moves to consumer repos. This is a repository boundary change, not a loss of work — the specs and ADRs (058–063 for docker) remain valid as the consumer's architecture.
• Several foundational handlers (ssh, tunnel, socks5, fs, sftp) are named in the scope but not yet specced. The scope table makes this visible — it is a backlog, not a hidden gap.
• alknet-worker has no spec yet. The worker pattern is described inside the hub README (as the inverse of hub), but a dedicated crates/worker/README.md or a combined hub/worker doc is needed.

Door type

One-way. The repo boundary (core mono-repo vs. consumer repos) is structural — once docker and agent are in their own repos with their own release cycles, reversing means merging them back and breaking downstream consumers that depend on the published crates. The scope table (which crates are core) is one-way for the same reason: the dep graph and the overview orient around it.

References

• ADR-003: Crate Decomposition (amended — the flat crate list is superseded; the decomposition principle survives)
• ADR-029: Peer-Graph Routing Model (the hub/worker topology)
• ADR-034: Three Peer Roles (hub = role-3, worker = role-1/2)
• ADR-071: alknet-channels Wire Format (the multiplexing substrate)
• ADR-079: Hub Relay (translate, not transparently forward)
• ADR-080: ChannelClient (the worker's dial path)
• ADR-081: channels sub-crate decomposition (channels-core / channels-call)
• ADR-082: alknet-tls extraction
• ADR-083: Endpoint as multi-transport accept-loop runner
• docs/architecture/crates/hub/README.md (the hub pattern — the deployment shape this scope is built around)