Files
alkssh/docs/architecture
glm-5.3-flash 9d2e962bec docs(architecture): ADR-002 (russh pin) + ADR-003 (feature graph)
- ADR-002 (Accepted): pin russh 0.65 (0.65.0 published 2026-10-25
  after the POCs' 0.64.1 verification — six security fixes incl.
  three in internet-facing classes; breaks are handler-signature
  shapes only, wire evidence transfers); aws-lc-rs backend confirmed
  with a clean in-scratch build record (no provisioning; ring kept as
  the recorded fallback); flate2 off (no compression); rsa on (front-
  door compat — supersedes the research docs' earlier off-leaning;
  RC-tree posture accepted with a recorded stable-release trigger);
  des/dsa never; rust-version 1.89 lands with the dep
- russh.md: re-verification-at-architecture-time section added
  (0.65.0 delta: PublicKeyOffer/VerifiedPublicKey, async-trait
  removed, GHSA list, verified build + tree facts)
- ADR-003 (Accepted): five features (session/git/tunnel/
  dynamic-forward/sftp-placeholder), flat + independent, default [],
  two-direction symmetry rule (one name, both doors), client acceptor
  fail-closed (not russh's accept-and-drop), x11/auth-agent never
  features, honest advertisement per build
2026-10-26 12:16:00 +00:00
..

status, last_updated
status last_updated
draft 2026-10-26

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. This directory is being populated: ADR-001 (the alk/ssh ALPN pin) is drafted for review, the OQ tracker is seeded from the POC findings, and the spec documents below are being written. No implementation until specs reach reviewed (per docs/sdd_process.md).

Architecture Documents

Document Status Scope
open-questions.md draft Centralized OQ tracker (seeded from phase 0 findings)
decisions/001 Proposed The alk/ssh ALPN pin (ledger rule 1)

Planned documents (not yet written)

Planned doc Scope
overview.md Crate purpose, exports, dependency posture, bounded-resources policy
mapping.md The spine — server-direction channel-type/request→family-seam rows (absorbs the validated mapping-table.md)
client.md Client-direction surface: dial rows, the forwarded-channel acceptor, reverse-runner shape
auth.md Server auth bridge + client-side vault key custody

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, RSA in 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

Open Questions

Tracked in open-questions.md — OQ-01 … OQ-13, seeded from the phase 0 POC findings and research docs.

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/004/009/034/042/051, alkhttp ADR-014/016/073-analogs