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

3.8 KiB

Raw Blame History

ADR-003: Protocol V2-first with honest capability advertisement

Status

Accepted

Context

The git smart protocol has three versions in the wild: V0 (the original), V1 (capability line prefixed), and V2 (command-based, default since git 2.18+). POC-1 and POC-2 validated the full V2 fetch path against real git 2.43 end-to-end (advertisement, ls-refs, fetch with sideband packs) over both duplex and http substrates. V0/V1 stateless-http is a different framing (per-round POSTs, stateless ack re-derivation).

The research inventory (git-protocol.md §"Open items") left the V0/V1 question open: support V0/V1 on http? On ssh? Which first?

Decision drivers:

Our deployment anchor (vision §"Primary deployment target") is modern git clients over http and ssh; every git client from the last six years speaks V2.
Honest capability advertisement (vision principle 5) is easiest to keep honest with fewer served shapes.
V0/V1 stateless-http needs multi-round negotiation state re-derivation — meaningful complexity for a client population that is effectively extinct.

Decision

Serve protocol V2 first. alkgit v1 serves V2 on both doors:

Advertisement is once-per-session (duplex) / per-request-set (http), exactly as observed in POC-1 (re-advertising between commands hangs real git).
Advertised capabilities are exactly what we serve: ls-refs=unborn, fetch=wait-for-done (v1 fetch policy is full-closure pack on done; multi-round negotiation, OQ-02, may add capability values when it lands), object-format=sha1 (+ sha256 under the feature flag, if and when tested — OQ-05). Nothing unimplemented is advertised (shallow, filter, packfile-uris, object-info, server-option are declined by omission; POC-1 confirmed real git accepts this). On the push side, git-upload-archive is not served at all — ssh exec requests for it get a fixed refusal (doors.md; ADR-008's never-execute rule).
HTTP requests protocol V2 only; ssh requests protocol V2 only (see below).

V0/V1 policy: decided now as V2-only for v1. Both doors (http and ssh) speak V2; clients that cannot speak V2 get a clear pkt-line error. Reversal is wire-visible (the advertised version set is a wire format), so treat this as effectively one-way once published — the decision is still made now, and revisiting it needs a new ADR plus a deprecation window for clients. The motivation stands: a concrete consumer needing V0/V1 (e.g. very old CI images) has not been identified. The V0/V1 receive-pack shape (used by git push on http stateless framing in older clients) is unaffected by this choice: receive-pack is mostly version-independent (see transport.md).

Sequencing note (fixes the scope contradiction the review found): the v1 fetch policy that ships first is full-closure-on-done (POC-validated). Multi-round V2 negotiation (haves/acks without done) is in v1's scope but lands after the done-path works end-to-end; its ack logic is OQ-02's open question, and any capability-advertisement change it requires happens then.

Consequences

Smallest honest surface; POC-validated shapes only.
Old-client support is declined explicitly (error, not silence).
The POC's observed done-path shape (no acknowledgments section, no ready, response ends at flush) is our normative wire behavior, not the docs' grammar — git-protocol.md §V2 records this.
If V0/V1 is ever added, the state machines in transport must be re-shaped around a version-dispatch at session start (single point, by design — see ADR-005).

References

docs/research/git-protocol.md §"Protocol surface inventory", §"Negotiation policy"
docs/research/poc-1-findings.md (advertisement-once, capability declination), POC-3 (http V2 framing)
ADR-005 (substrate types), ADR-007 (ACL before advertisement)
transport.md, doors.md

3.8 KiB Raw Blame History