Files
alkssh/docs/architecture
glm-5.3-flash f36c268694 docs(architecture): OQ-10 reopened — premise corrected in place, derivation details deferred to mapping.md
- OQ-10 is not resolved: the mapping-contract derivation details (name
  table, core-dumped disposition, −1 disposition) are working
  dispositions on mapping.md's exit rows until formalized there / as an
  ADR-006 amendment. The 1a40bfb commit prematurely closed them and left
  ADR-006's reference (OQ-10 open) stale.
- Premise correction integrated into the seed, not argued after the
  fact; the portable-pty 0.9.0 source now cited as verified
  (From<std::process::ExitStatus> maps signal-terminated → code 1 +
  locale-dependent strsignal string; the number is unrecoverable).
- mapping.md: exit_signal row and the Open Questions entry updated to
  open OQ-10 with the working-draft framing.

Verification: cargo test (2/2 targets ok), cargo clippy --all-targets -- -D warnings, cargo fmt --check (docs-only change)
2026-10-27 15:19:08 +00:00
..

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)