glm-5.3-flash
86bf5a0cf0
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).
82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# 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 |