# 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` (the full-closure pack on `done` policy
  validated in POC-1/2; the multi-round ack loop, ADR-014, needs no
  capability change — the acknowledgments section is grammar, not
  capability), `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 — fetch only.** Both doors
(http and ssh) speak V2 for *fetch*; 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.
**Receive-pack is exempt**: the push path is V0-framed by upstream design
on every client generation (no version negotiation exists on push at
all — ADR-013 §1), so the V2-only rule never touches `git push`. The
V0/V1 decline applies to the fetch path only.

Sequencing note: 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 loop is now
decided (ADR-014) and needs no capability-advertisement change.

## 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