---
status: reviewed
last_updated: 2026-10-28
---

# Architecture index

## Current State

Phase 1 (architecture) is 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](overview.md) | reviewed | Crate purpose, family position, surface categories, bounded-resources policy, non-goals |
| [mapping.md](mapping.md) | reviewed | The spine: server-direction rows, dispatch, spawn-and-return, decline matrix |
| [client.md](client.md) | reviewed | Client-direction surface: dial, op rows, the acceptor, lifecycle primitives |
| [auth.md](auth.md) | reviewed | The auth bridge (server) + custody & host-key policy (client) |
| [open-questions.md](open-questions.md) | reviewed | Centralized OQ tracker (all OQ-01…13 resolved) |

## ADR Table

| ADR | Title | Status |
|---|---|---|
| [ADR-001](decisions/001-alkssh-alpn-pin.md) | The `alk/ssh` ALPN pin: edge-termination contract for `SshAdapter` | Accepted |
| [ADR-002](decisions/002-russh-pin.md) | The russh pin (0.65.0, aws-lc-rs, no compression, ed25519-only) | Accepted |
| [ADR-003](decisions/003-feature-graph.md) | The capability feature graph: flat, independent, two-direction | Accepted |
| [ADR-004](decisions/004-auth-dispositions.md) | Auth dispositions: publickey-only, fail-closed, fingerprint identity | Accepted |
| [ADR-005](decisions/005-at-rest-key-custody.md) | At-rest key custody: vault-wrapped OpenSSH-PEM, decrypt-at-use | Accepted |
| [ADR-006](decisions/006-mapping-bridge-and-dispatch.md) | Mapping decisions: route-1 bridge, exec-only git, session dispatch | Accepted |

## Open Questions

Tracked in [open-questions.md](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,
whose 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)