docs(architecture): N-4 + N-5 — push-options trait param, unborn-HEAD rider

- N-4: GitPackIngest's prepare binding carries push_options:
  Option<&PushOptions> (parsed (key, value) pairs, verbatim and
  un-interpreted; None until the config gate opens) — pinned in
  ADR-013 §11 and backend.md's trait description so opening the
  config gate later is value-additive, not a trait redesign
- N-5: ls-refs=unborn verification recorded as a rider in
  transport.md §ls-refs + tracker task tasks/architecture/
  n5-unborn-head-rider.md (unborn fixture, real client, both
  substrates; drop the token if it cannot be served — ADR-003)
- review 001: N-4, N-5 marked resolved

verification: cargo test, clippy -D warnings, fmt --check, doc — clean
This commit is contained in:
glm-5.3-flash committed 2026-09-30 04:19:37 +00:00
1 parent 82653c31b6
commit 11ceead6fd
5 files changed
+80 -4

No files matched your search

@@ -0,0 +1,58 @@
---
id: architecture/n5-unborn-head-rider
name: Verify ls-refs=unborn serving (unborn-HEAD fixture, both substrates)
status: pending
depends_on: []
scope: narrow
risk: low
impact: wire-claim
level: implementation
tags: [verification-rider, advertisement-honesty]
---
## Description
Review 001 N-5: `ls-refs=unborn` is advertised (transport.md §advertisement,
ADR-003), and POC-1 validated real git accepting the capability *token* —
but serving an unborn HEAD's symref line was never exercised against a
real client (every POC fixture had refs). This is the only advertised
promise in the corpus without capture evidence. The rider is the
verification that closes it.
## Work
Implementation-phase test (lands with the ls-refs workstream):
1. Fixture: an unborn repo — registry record exists, `git init`-equivalent
storage with no refs (the POC set's unborn repo has refs; a new one
without any is needed).
2. V2 ls-refs against it over the duplex substrate with a real git client
(`git -c protocol.version=2 ls-remote`), asserting the unborn HEAD
symref line appears per the ls-refs grammar
(`<zero-oid> HEAD symref-target:refs/heads/<default>` unpeeled).
3. Same over the stateless (smart-http-shape) substrate.
4. Backend seam: the refs listing must expose the unborn symref for an
empty repo — verify the `GitRefs` trait shape carries it (a
`symref-target` with no oid); adjust the trait surface if the gix
listing cannot produce it.
If it cannot be served correctly: drop the `ls-refs=unborn` token from
the advertisement (the honest move per ADR-003 — decline by omission)
and record the drop in transport.md §advertisement.
## Verification
- Real `git ls-remote` (V2) against an unborn repo lists the unborn HEAD
symref line, both substrates.
- The full advertisement suite still passes against repos with refs
(the token must not change the served behavior there).
## Out of scope
- Unborn-HEAD push (an unborn repo's first push is ordinary ref creation
— ADR-013; not this rider).
- Any capability beyond the token's existing grammar.
## Summary
> Filled on completion.