Files
alkssh/docs/architecture
glm-5.3-flash c7ab19ed8a docs(architecture): retire the dynamic-forward feature — the -D untangle
Review untangle (three layers: local door / wire protocol / fabric):
- vanilla ssh -D binds its SOCKS5 proxy client-side (the local door —
  alksocks' local-door shape) and opens plain direct-tcpip per
  connection: the server needs nothing SOCKS-shaped (tunnel row +
  route-1 bridge cover the leg; POC-3 correction 2 already said this)
- the family-native SOCKS5-in-channel server row served no consumer
  of ours: family apps compose alksocks' local door locally over the
  alkssh client's direct-tcpip DialFn — alkssh doesn't depend on
  alksocks on this path
- amendments: ADR-003 §1a (feature removed), ADR-006 point 3 (SOCKS-
  detect retired; session dispatch is parse-only; request-less
  session channels decline), OQ-02 resolution updated with the
  simplification, mapping-table.md rows annotated (research doc keeps
  POC-3 stage B as the re-add feasibility record)
2026-10-26 15:32:08 +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