Files
alkssh/docs/architecture
glm-5.3-flash 9f443e982b docs(architecture): close the OQ-07/OQ-10 upstream watch items; amend ADR-005 §3 + the mapping rows
- ADR-005 decision 3 amended (the gap is closed upstream: alkvault
  0.2.0's Zeroizing<String> return on every path incl. the error one;
  the adapter wrap dropped — the double wrap would be dead posture);
  the Negative consequence amended; the vault-surface note updated.
- mapping.md: the forwarded-tcpip row rides the gate shape (typed
  call-plane miss, residual race re-scoped); derivation-contract
  rule 5 amended (the PTY flattening constraint retired, alktty
  0.8.2 — no contract change); the exit_signal row + OQ anchors
  updated.
- open-questions.md: OQ-07 + OQ-10 amended with the upstream
  closures; the two closed watch items struck with pointers.
- client.md: the OQ-07 anchor updated.
2026-11-04 09:45:33 +00:00
..

status, last_updated
status last_updated
reviewed 2026-10-28

Architecture index

Current State

Phase 1 (architecture) — complete pending implementation. 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 reviewed (2026-10-28): the OQ resolution pass closed all thirteen open questions (OQ-08/11 decided, OQ-10 converted to a derivation contract + upstream constraint, OQ-01/04/09/13 closed as fully-decided dispositions) and the review pass came back clean. Implementation may begin.

Architecture Documents

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

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, session dispatch Accepted

Open Questions

Tracked in open-questions.md — OQ-01 … OQ-13, seeded from the phase 0 POC findings and research docs. All thirteen are resolved: the three mapping-detail decisions settled this pass (OQ-08 shell convention → assembly-supplied serve-config field, no crate default; OQ-10 → closed as the derivation contract on mapping.md's exit rows + the upstream PTY-path constraint; OQ-11 → universal compile + runtime Unix-gated decline), and the previously deferred entries closed as fully-decided dispositions (OQ-01/04/09/13 — the decision surfaces were already fixed by ADR-001/ADR-004 and the decline postures; what remained was forecasts about consumers, not pending alkssh decisions). Upstream dependencies are listed as watch items in the tracker, not OQs.

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)