alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash 8f73da5d12 docs(architecture): phase 1 bootstrap — specs, 9 ADRs, OQ tracker

Architecture documentation structure per sdd_process phase 1:

- README index (doc table, ADR table, lifecycle), overview with crate
  map, dependency rules, and security invariants
- Component specs: storage, transport, http, ssh, alkgitd (all draft)
- ADRs 001-009: crate decomposition, front-door-blind core, V2-first
  protocol, pack pipeline (data::output generation / data::input
  ingestion), session substrate types, http adapter composition
  (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo
  identity, bounded-resources budgets
- open-questions.md: OQ-01..08 with two deferred(scope), one
  deferred(unclear), door-type definitions, blocker tracker tasks in
  tasks/architecture/
- v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd;
  alkcall channels stay the internal substrate (OQ-03 partially
  resolved)

Two review rounds (fresh-context subagent): 4 critical + 17 warnings
fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in
round two. All ADR/OQ cross-references verified resolving.

2026-09-21 03:55:33 +00:00

3.2 KiB

Raw Blame History

ADR-002: Front-door-blind core — the session boundary

Status

Accepted

Context

The load-bearing composability rule ("ALPN as a service", docs/research/vision.md): alkgit-core + alkgit-transport must never know which front door is talking. POC-1 proved the exact shape survives the wire: Connection::accept_bi() → BiStream → tokio::io::split → tokio-util compat → gix-packetline ran a full V2 fetch against real git. POC-3 proved the stateless-http variant: the same protocol state machines ran per-POST over (request-reader, response-writer) instead of a duplex stream.

The question this ADR settles: what is the interface the core/transport exposes to adapters?

Alternatives considered:

Adapters implement an alkcall-style ProtocolHandler themselves and call into transport with raw BiStream — pushes too much protocol responsibility (advertisement timing, framing errors) into every adapter.
Transport speaks alkcall Connection directly — forces stateless http (one request per connection) through a session-shaped API; wrong shape for http, and couples transport to alkcall connection lifecycle.
HTTP-specific abstractions in transport — violates the blind-core rule.

Decision

The transport exposes two session entry points, both consuming the same tuple (peer identity, resolved repo, limits):

Duplex session (ssh, git://, any stream door): transport consumes a BiStream-shaped duplex byte stream (AsyncRead + AsyncWrite + Unpin, the alkcall BiStream contract, alkcall ADR-005/009) and runs the advertise-once → command-loop state machine. Adapters hand it over after ACL and repo resolution (ADR-007, ADR-008).
Stateless session (smart-http): transport consumes a (request-reader, response-writer) pair per http request and runs one command per invocation, matching smart-http's stateless framing. The same core state machines run under both entry points.

Storage-facing side: transport calls alkgit-core for advertisement data, pack generation (want/have set in → streaming pack out), and pack ingestion + ref CAS (receive-pack). Storage never sees pkt-lines.

The futures-io bridging detail (tokio_util::compat), the split/compat glue, and the packetline stop-delimiter handling live inside transport — adapters never see futures_io types (POC-1 follow-ups 1–2, POC-3 follow-up 2).

Consequences

The core+transport pair is embeddable with any front door; POC-1/3 are existence proofs of both shapes.
State machines are written once; http statelessness is a substrate property, not a protocol fork.
Transport depends on alkcall types only (BiStream shape, identity, limits) — no alkhttp, no channel types below the stream.
One cost: the stateless entry point needs explicit per-request limits (body budget, wall clock) since there is no session to amortize them (ADR-009).

References

docs/research/vision.md §"ALPN as a service"
docs/research/poc-1-findings.md (duplex shape validated), docs/research/poc3-findings.md (stateless shape validated)
alkcall ADR-005 (BiStream type), ADR-009 (BiStream as handler leaf)
ADR-005 (substrate types detail), ADR-007/008 (what adapters do before calling transport)
overview.md §"Interfaces"

3.2 KiB Raw Blame History Unescape Escape