docs(arch): draft alknet-docker architecture specs (ADRs 058-063, OQs 048-051)

Greenfield architecture spec set for the alknet-docker crate — a thin,
single-host bollard wrapper exposing docker container/image operations
as call-protocol ops on the shared alknet/call ALPN, plus a
DockerTtyBackend (impl TtyBackend) behind a tty feature for interactive
terminal sessions into containers over alknet/tty.

Six ADRs:
- 058: docker ops on alknet/call (no separate ALPN; raw-carriage handoff
  dissolved by alknet-tty extraction — interactive attach moved to
  alknet/tty via DockerTtyBackend, no carriage field on call.requested)
- 059: bollard 0.21 (verified current on crates.io) + feature selection
  (http+pipe+time; no ssl/ssh/websocket/buildkit)
- 060: container resource model (ADR-050 application) — alknet.managed/
  alknet.owner labels, list owned_only flag, hosted-services operator
  role via static-resource fallback, handler-driven revoke with
  autonomous-death tolerance, resource-action vocabulary
- 061: DockerTtyBackend in alknet-docker behind tty feature (attach vs
  exec mode; POC drive_attach_raw as reference)
- 062: Docker client + OwnershipStore injection via closure capture
  (not Capabilities, not OperationContext — matches from_openapi pattern)
- 063: exit code on terminal call.responded for non-interactive exec
  (call.completed stays empty, ADR-012 unchanged)

Four spec docs (crates/docker/): README, overview, docker-operations,
docker-tty-backend. Four deferred-scope OQs (048-051): network/volume
ops, buildkit, system events subscription, create options surface.

Updates the tty-backend.md Backend implementations table (DockerTtyBackend
row now specced) and the architecture README (doc table, ADR table,
current-state paragraph, OQ count).

Grounded in the alknet-docker POC (docs/research/alknet-docker/poc-summary.md)
which validated the hard parts; the remaining lifecycle ops are mechanical
bollard wrapping. Reviewed by architecture-reviewer subagent; criticals
(the docker_client injection model conflicting with the Capabilities
contract) resolved via ADR-062/063 before commit.
This commit is contained in:
glm-5.2 committed 2026-07-08 09:29:22 +00:00
1 parent 5873fa22d6
commit 1ce11717d8
17 files changed
+3196 -9

No files matched your search

@@ -0,0 +1,30 @@
# OQ-48: Network and Volume Operation Surface
- **Origin**:
[crates/docker/docker-operations.md](crates/docker/docker-operations.md)
§"Operation Surface (v1 scope)" (out-of-scope list).
- **Status**: deferred(scope)
- **Door type**: Two-way
- **Priority**: low
- **Blocked on**: a concrete use case for network or volume management
over the call protocol. The two container use cases (disposable dev
containers, hosted services) don't currently require
network/volume CRUD over the call protocol — dev containers use
the default bridge network; hosted services are configured via
`docker compose` with networks/volumes declared in the compose file.
- **Resolution**: Not yet decidable. bollard has the API surface
(`network.rs`: `create_network`, `remove_network`, `inspect_network`,
`list_networks`, `connect_network`, `disconnect_network`;
`volume.rs`: `list_volumes`, `create_volume`, `inspect_volume`,
`remove_volume`, `prune_volumes`) — the mapping is mechanical, the
same shape as the container lifecycle ops (`Query`/`Mutation`,
single `call.responded`). The deferral is scope, not feasibility:
v1 is containers + images; networks and volumes are added when a
use case forces them (e.g., a coordinator that needs to create
isolated networks for dev containers, or a fleet layer that manages
volumes across hosts). Adding them is additive (new operations in
the registry) and does not break the existing surface.
- **Cross-references**:
[ADR-058](decisions/058-alknet-docker-on-alknet-call.md) (the shared
`alknet/call` registration model new ops would follow),
[crates/docker/docker-operations.md](crates/docker/docker-operations.md)