alkdev/alkssh

0 Fork 0

Files

T

glm-5.3-flash ab6fb9de87 docs(architecture): resolve all open questions (OQ-01..13), mark specs reviewed

- OQ-08: shell convention = assembly-supplied serve config (shell argv
  for shell_request; exec wrapper argv + command string for exec; no
  crate default; unset -> clean decline)
- OQ-11: direct-streamlocal = universal compile + runtime Unix-gated
  decline (channel and listen flow)
- OQ-10: closed as contract + upstream constraint; derivation rules
  formalized in mapping.md (Exit chunk -> SSH exit reporting), incl.
  the -1/genuine-SIGHUP fidelity tradeoff and an unmapped-negative
  fallback rule
- OQ-01/04/09/13: resolved as fully-decided dispositions (ADR-001/
  ADR-004/fixed decline postures); remainders were forecasts about
  consumers, not pending alkssh decisions; upstream deps now listed
  as watch items, not OQs
- OQ-12 restored to the tracker (dropped in the rewrite)
- review-agent criticals/warnings fixed: exec-unset + wrap mechanics
  specified, streamlocal listen gate added, stale deferred/tracked
  language removed, ADR-006 title fixed, 0.64.1-vs-0.65.0 crosswalk
  added in ADR-004, ADR frontmatter aligned to 'reviewed'

All specs + ADRs 001-006 now reviewed; implementation may begin.

2026-10-28 05:08:01 +00:00

4.1 KiB

Raw Blame History

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)

4.1 KiB Raw Blame History Unescape Escape