Files
alkssh/docs/architecture
glm-5.3-flash e9f78bf6f7 docs(architecture): ADR-006 (route-1 bridge, exec-only git, SOCKS dispatch) + OQ-02 resolved
- ADR-006 (Accepted): direct-tcpip rides the adapter-side bridge
  (alktunnels route 1; registry-side bridging rejected as door-posture
  inversion; absence note resolved); git over SSH is exec-only with
  subsystem declining (vanilla git's connection model is exec of
  git-{upload,receive}-pack — POC-3 grammar table); session dispatch:
  request-driven parse wins, request-less channels get the bounded
  SOCKS-detect (first-byte 0x05, 500 ms default, assembly-configurable);
  spawn-and-return recorded as a structural constraint
- OQ-02 resolved by ADR-006; README doc/ADr tables + OQ summary updated
2026-10-26 15:12:52 +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, 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. Five resolved (ADR-002/006 review + evidence), four deferred with named blockers.

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