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:
1 parent
d067cf558a
commit
85bde4c241
5 files changed
+52
-11
No files matched your search
@@ -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)
|
||||
|
||||
|
||||
Reference in new issue
Block a user