alkssh/docs/architecture

status, last_updated

status	last_updated
draft	2026-10-27

Architecture index

Current State

Phase 1 (architecture) — in progress. Phase 0 is closed: all three POCs passed (121 checks; docs/research/poc-{1,2,3}-*.md) and the research docs record their corrections. The ADR set (001–006) is Accepted — including the post-review amendments (ADR-002's ed25519-only revert; ADR-003/006's dynamic-forward retirement) — and the four spec docs (overview/mapping/client/auth) are drafted; the architecture review pass is next, after which specs go to reviewed.

Architecture Documents

Document	Status	Scope
overview.md	draft	Crate purpose, family position, surface categories, bounded-resources policy, non-goals
mapping.md	draft	The spine — server-direction rows, dispatch, spawn-and-return, decline matrix
client.md	draft	Client-direction surface: dial, op rows, the acceptor, lifecycle primitives
auth.md	draft	The auth bridge (server) + custody & host-key policy (client)
open-questions.md	draft	Centralized OQ tracker (seeded from phase 0 findings)

ADR Table

ADR	Title	Status
ADR-001	The alk/ssh ALPN pin — edge-termination contract for SshAdapter	Accepted
ADR-002	The russh pin — 0.65.0, aws-lc-rs, no compression, ed25519-only	Accepted
ADR-003	The capability feature graph — flat, independent, two-direction	Accepted
ADR-004	Auth dispositions — publickey-only, fail-closed, fingerprint identity	Accepted
ADR-005	At-rest key custody — vault-wrapped OpenSSH-PEM, decrypt-at-use	Accepted
ADR-006	Mapping decisions — route-1 bridge, exec-only git, SOCKS dispatch	Accepted

Open Questions

Tracked in open-questions.md — OQ-01 … OQ-13, seeded from the phase 0 POC findings and research docs. Six resolved (OQ-02/03/05/06/07/12), three open (OQ-08/10/11 — mapping-detail decisions in the current review pass), four deferred with named blockers (OQ-01/04/09/13).

Document Lifecycle

Status	Meaning	Transitions
draft	Under active development; may change significantly	→ reviewed when its open questions are resolved
reviewed	Final; implementation may begin; changes require review	→ stable when implementation is complete and verified
stable	Locked; changes require review and may warrant an ADR	→ deprecated when superseded
deprecated	Superseded; kept for reference	Removed when unreferenced

References

• docs/sdd_process.md — the SDD process
• docs/research/ — phase 0 (vision, POC plans + findings, russh inventory, auth bridge, mapping table, reverse-runner extraction)
• Family: /workspace/@alkdev/alkfamily/docs/architecture/decisions/001..003 (ADR-003 is the alkssh structural decision)
• Sibling: alkcall ADRs 002/003/004/006/009/010/034/042/051 (ALPN dispatch, auth surface, channels wire/relay); alkhttp ADR-014/073 (secret-material flow and door-surface posture — the patterns ADR-005 and auth.md mirror)