docs(arch): review-001 doc batch — A-4, D-2, D-3, N-1, N-2

Amendment batch (no new decisions, all doc-level):

- A-4: done-round boundary set is the recognized subset — request
  haves filtered through common_haves, the same honest-boundary rule
  as the ack rounds (never honor an unverified have); amendment clause
  in ADR-014 §2, same rule restated in transport.md §fetch.
- D-2: amendment note on ADR-007 step 3 — the per-repo check is
  ADR-011's authorize policy function (static ACL engine fails closed
  on None identity); step order unchanged.
- D-3: authorized-repo marker added to both substrate input tuples in
  transport.md and to backend.md's public-API list (ADR-007's
  type-level enforcement promise is now findable from the transport
  spec).
- N-1: advertisement ref cap is fail-closed (breach is an error, never
  a silent truncation) — transport.md §Limits.
- N-2: RegistryError::NotFound and authorization failure collapse to
  the same wire error at the variant→wire mapping — transport.md
  §error taxonomy.
- review 001: A-4/D-2/D-3/N-1/N-2 marked resolved.

Verification: cargo doc --no-deps, cargo test — clean.
This commit is contained in:
glm-5.3-flash committed 2026-09-29 08:30:26 +00:00
1 parent d067cf558a
commit 85bde4c241
5 files changed
+52 -11

No files matched your search

+20 -4
View File
@@ -22,12 +22,16 @@ full decision (what each substrate owns and why); the surface is:
- **Duplex session** (the `alk/git` ALPN producer, channels-opened git
sessions, embedder stream doors) — input: (peer identity, resolved repo
id, duplex stream, `Limits`). Encapsulates the split/compat/packetline
id, authorized-repo marker, duplex stream, `Limits`). The marker is a
type the door/adapter constructs only after the ADR-007 check passes
(skipping the check is a type error — ADR-007; D-3). Encapsulates the
split/compat/packetline
bridge, the request reader (delim-aware parsing, `reset()` discipline,
break-on-error), and the sideband writer.
- **Stateless session** (smart-http doors, e.g. alkhttp's future `git`
feature) — input: (peer identity, resolved repo id, request-reader,
response-writer, `Limits`) per http POST; adds the http-framing rules
feature) — input: (peer identity, resolved repo id, authorized-repo
marker, request-reader, response-writer, `Limits`) per http POST; adds
the http-framing rules
(capability-dump skip, flush-only responses, probe handling). IO-abstract:
the door supplies reader/writer; see [doors.md](doors.md) for the
mounting.
@@ -66,7 +70,10 @@ substrate property (per-request state), not a protocol fork.
get an `acknowledgments` section (`ACK <oid>` per recognized have via
the backend's `common_haves`, `NAK` when none, flush; never `ready`),
the `done` round generates closure(wants) − closure(haves) via
`GitPackGen`. No cross-round state on either substrate (the client
`GitPackGen`, with the boundary set the *recognized* subset (request
haves filtered through `common_haves` — the same honest-boundary rule
as the ack rounds; never honor an unverified have; ADR-014 §2). No
cross-round state on either substrate (the client
re-sends wants + commons each round — negotiation-captures.md).
Advertisement text is unchanged: `fetch=wait-for-done`.
- Pack generation via `GitPackGen` (ADR-004), streamed over sideband on
@@ -118,12 +125,21 @@ grammar-inferred.
- io errors are terminal (session ends); protocol errors map to pkt-line
error bands (duplex) or http status + body (stateless). Substrate-level
`thiserror` enum; no panics in library code (convention 2).
- At the wire-mapping point (review 001 N-2), `RegistryError::NotFound`
and an authorization failure collapse to the same wire error — the
unknown-repo ≡ unauthorized indistinguishability rule (ADR-007/ADR-008)
holds at the variant→wire mapping, so no variant leaks an existence
oracle to the client.
## Limits
Every session carries `Limits` (ADR-009): negotiation rounds, haves per
round, receive-pack max size, wall clock, sideband chunk size (fixed
65000), advertisement ref cap. Missing `Limits` is a type-level error.
The advertisement ref cap is fail-closed like every other budget
(review 001 N-1): breach is a session error, never a silent truncation —
a partial ref list is the worst failure mode an advertisement can have
(clones appear to succeed).
## Public API surface (v1)