alkgit/docs/architecture/overview.md

status, last_updated

status	last_updated
draft	2026-09-21

Overview: alkgit

Purpose

alkgit is the git payload service of the alk family: a pure protocol crate (per ADR-010, following the alktty/alktunnels template) implementing the git smart protocol over alkcall channels — the alk/git ALPN. It provides repository storage as backend traits (with a feature-gated gitoxide implementation), the git smart protocol as producer/consumer halves, and nothing else: no binary, no front doors. The original framing of this repo (a monorepo with an alkgitd binary and its own http/ssh crates) was an init-agent artifact corrected by OQ-09/ADR-010; docs/research/vision.md is amended accordingly.

The one-line architecture

One protocol crate: producer + consumer + backend traits, gix behind a feature. Doors (alkhttp, alkssh, alknet) expose it; assembly belongs to downstream consumers.

Crate map

Single crate alkgit:

Half	Contents	POC evidence
Producer	GitAdapter (alk/git ALPN via alkcall ProtocolHandler), channels register_openable (repo id in open-op params — the negotiation + ACL point)	POC-1 verbatim
Consumer	GitSession typed client (connect_direct, open_via_channels) — the replication/mirroring primitive for alknet	new, small (TtySession analog)
Substrate	duplex session + stateless request/response layer (ADR-005); wire framing, V2 state machines (ADR-003)	POC-1, POC-3
Backends	GitRegistry (+ write supertrait), GitRefs, GitPackGen, GitPackIngest traits; impls behind the default-on gix (engine) and registry-file (records) features	POC-2 (gix impl)
Management ops	git/repo/* call ops over GitRegistryStore (ADR-012 §3) — the JSON half alongside the alk/git open op (first dual-kind payload; ADR-012 §5)	thin over the store trait

Feature model: gix (engine impls) and registry-file (record store + ops) are independent default-on seams (ADR-012 §4); default-features = false gives the wire/protocol layer without either (wasm-clean as a side effect, not a goal); the sha256 passthrough and (eventually, in alkhttp) the git door feature ride the same pattern. Doors live in the door crates — see doors.md.

Security invariants (spec-level, carried from vision/principles)

1. Authenticated by default — anonymous fetch only on explicitly- public repos; push always authenticated.
2. Visible-surface = authorized-surface — alkcall ACL end-to-end; internal ops never wire-callable.
3. ACL before advertisement — nothing is emitted before the check (ADR-007); the channels open-op carrying the repo id is the natural enforcement point on the native path.
4. Registry-resolved repo identity — wire names are ids, never paths (ADR-008).
5. No secret material on the wire or at rest outside alkvault — metadata holds vault references; no env-var credential reads. (In v1 alkgit's metadata holds no credential-shaped material at all, so nothing is vault-placed — ADR-011 §5.)
6. No shelling out to git — pure Rust on gix primitives.
7. Bounded resources — every session carries Limits (ADR-009).
8. Honest capability advertisement — advertise exactly what we serve (ADR-003).

What is already validated (POC-backed)

• pkt-line over alkcall BiStream end-to-end (POC-1 → producer half).
• Pack generation pipeline streaming with O(counts) memory (POC-2 → gix backend impl).
• Smart-http streaming both ways (POC-3 → the stateless substrate that alkhttp's future git feature maps onto; docs/research/poc3-findings.md §alkhttp fit is the mounting reference). The full V2 fetch path against real git 2.43 is proven; receive-pack is designed but not yet exercised (OQ-04).

Design Decisions

ADR	Decision	Summary
001	Crate decomposition	superseded by ADR-010
002	Session boundary	(identity, repo, stream, limits) — unchanged, load-bearing
003	V2-first protocol	V2-only both doors; honest advertisement
004	Pack pipeline	data::output gen / data::input ingestion
005	Substrate types	duplex + stateless APIs over one state machine
006	HTTP adapter composition	superseded by ADR-010 (mounting → alkhttp feature)
007	ACL first	no ref/capability line before ACL passes
008	Repo identity	wire names are registry IDs
009	Budgets	every session carries limits
010	Pure protocol crate	single crate, producer/consumer halves, no doors/binary
011	Per-repo authorization	grants in repo records, policy in core, vault-nil
012	Registry + ops	read/write split, file default, CRUD ops, feature split

Open Questions

Key questions tracked in open-questions.md:

• OQ-04: receive-pack (push) validation gap (high — the always-authenticated half of the wire surface).
• OQ-02: V2 multi-round negotiation (medium — efficiency, not correctness).
• OQ-03: publish-time API freeze inventory (the git/repo/* op set enters it; ADR-012).
• OQ-05: sha256 policy (deferred(scope), low).

Resolved this cycle: OQ-08 (ADR-011 — per-repo authorization, grants in records, vault-nil), OQ-06 (ADR-012 — registry-file default, persistence adapters additive), OQ-07 (ADR-012 — CRUD ops shipped External with scope+ownership ACL).