alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash 86bf5a0cf0 refactor(architecture): ADR-010 — pure protocol crate (alktty template)

Structural decision (OQ-09 resolved): alkgit follows the alktty/
alktunnels template — a single published protocol crate on alkcall
channels, no binary, no front doors.

- ADR-010 supersedes ADR-001 (crate decomposition) and ADR-006
  (http router factory); both marked Superseded
- Single crate at repo root: Cargo.toml with gix feature (default-on
  backend implementations; wire layer compiles without it —
  gix-hash always-on with sha1 per the compile-time-rejected
  invariant), crates/ workspace deleted, src/lib.rs stub in place
- doors.md replaces http.md/ssh.md/alkgitd.md: alkhttp git-feature
  sequencing (after first publish), alkssh requirement (fixed-grammar
  exec dispatch), native alk/git path, downstream assembly
- backend.md replaces storage.md: GitRegistry/GitRefs/GitPackGen/
  GitPackIngest traits (ingest validates, refs commits — single CAS
  home), gix feature encodes POC-2 prerequisites
- transport.md reframed for the single crate; backend traits replace
  hook traits in the public API
- OQ-09 resolved (all five sub-decisions in ADR-010), OQ-01 resolved
  (subsumed), OQ-03 narrowed to publish-freeze, OQ-08 narrowed to
  registry identity + vault placement, OQ-07 rescoped to the gix
  feature's registry impl
- vision.md v2: single-binary/monorepo framing corrected as
  init-agent artifact; POC checklist marked complete
- AGENTS.md + .opencode agent specs updated to the new shape

Verification: cargo build (default + no-default-features), cargo test
--all-features, clippy --all-features -D warnings, fmt --check all
pass. Third review round: zero critical, all warnings/suggestions
addressed (GitPackGen signature amended in ADR-004, stale anchors
fixed, ADR-006 body tense normalized, CAS split stated, vision
residuals cleaned).

2026-09-21 10:54:03 +00:00

2.6 KiB

Raw Blame History

ADR-001: Workspace crate decomposition (5 crates)

Status

Superseded by ADR-010 (pure protocol crate — single alkgit, no workspace, no front-door crates, no binary)

Context

The workspace skeleton (created before phase 1) proposed five crates: alkgit-core, alkgit-transport, alkgit-http, alkgit-ssh, alkgitd. The decomposition has to serve two masters: the "ALPN as a service" composability rule from docs/research/vision.md (downstream apps embed core + transport and bring their own front doors) and the POC findings that fixed the actual layering between protocol, storage, and front doors (POC-1/2/3).

Alternatives considered:

Single crate — simplest, but forces front-door code into the same dependency graph as embedders who only want core+transport, and blocks independent evolution of the http adapter.
Split core into registry/metadata vs storage — premature; the registry storage backing is still an open question (OQ-06) and the split would bake in a boundary we may want to move.
http+ssh in one alkgit-frontends crate — reduces crate count but couples alkhttp to alkcall-channels consumers and vice versa.

Decision

Keep the five-crate decomposition from the skeleton:

alkgit-core — repository storage: registry, refs, odb wrappers, pack generate/ingest, fsck, access-rule input types. Transport-agnostic.
alkgit-transport — smart protocol: pkt-line sessions, V2 capability advertisement, ls-refs, fetch, receive-pack state machines.
alkgit-http — http front door (smart-http over alkhttp).
alkgit-ssh — ssh front door (git command exec dispatch; wire SSH terminated by russh in alkgitd, or alkcall channels in embedded variants — both converge on the adapter's dispatch).
alkgitd — the binary: config, assembly, TLS/ACME, serving loops.

Dependency edges: core ← transport ← {http, ssh} ← alkgitd. http and ssh have no edge between them. Core and transport depend on alkcall types only (never alkhttp/alkgit-ssh); see ADR-002 for the exact boundary.

Consequences

Downstream embedders take alkgit-core + alkgit-transport and stop there; front-door crates are replaceable adapters.
The binary crate carries all assembly knowledge (config schema, listener setup, vault wiring), keeping the library crates front-door-blind.
Crate count stays at five; any future split (e.g. metadata store) is a new ADR.

References

docs/research/vision.md §"ALPN as a service", §"Sub-crate shape"
docs/research/alk-stack.md §"Composability boundary"
POC findings 1–3 (layering validated end-to-end)
ADR-002 (the core boundary)
overview.md §"Crate map"

2.6 KiB Raw Blame History Unescape Escape