alkgit/docs/reviews/001-architecture-pre-decomposition-review.md

status, last_updated, reviewed_artifacts, tool, reviewer, scope_note

status	last_updated	reviewed_artifacts	tool	reviewer	scope_note
open	2026-09-29	docs/architecture/README.md docs/architecture/overview.md docs/architecture/transport.md docs/architecture/backend.md docs/architecture/doors.md docs/architecture/open-questions.md docs/architecture/decisions/ (ADR-001..014) docs/research/ (vision, git-protocol, gitoxide, alk-stack, reference-policy, pocs, poc-1/2/3 findings, push-captures, negotiation-captures) docs/sdd_process.md tasks/architecture/ (all five tracker/backlog tasks) Cargo.toml src/lib.rs	manual full-corpus read + alkcall/alktty source cross-checks + gitoxide source verification + feature-matrix compile probes + dyn-compatibility probe (scratch crate, MSRV-pinned) + cargo test/clippy/fmt/doc/publish-dry-run	architecture pre-decomposition review (contradiction + gap + staleness pass)	phase-1 gate review — the entire committed architecture corpus against the sibling-crate surfaces it leans on (alkcall 0.8, alktty template) and the pinned gitoxide versions. No implementation exists to review (src/lib.rs is the skeleton); this review asks whether the spec set is internally consistent and implementable as written.

Review 001 — Architecture Pre-Decomposition Review

Purpose

The phase-1 OQ cycle is complete (OQ-04/ADR-013 and OQ-02/ADR-014 landed 2026-09-25; every wire-shape question has a capture-grounded decision) and the next step is decomposition into implementation tasks. This review is the gate between those phases: it reads the whole architecture corpus the way a decomposer and then an implementation agent would — looking for

1. Contradictions between decisions — places where two Accepted documents (or an ADR and the sibling-crate API it cites) disagree, where an implementer would have to pick a winner or guess.
2. Spec gaps that strand implementers — wire shapes, trait signatures, or gate mechanics the docs reference but never pin, where two implementation workstreams would invent incompatible answers.
3. Stale text — superseded statements left standing in docs the decomposer reads first.

Findings A-1/A-2/A-3 are the reason this review exists: each is a place where an implementation agent hits a hard failure (a compile error, an unservable wire path, an unenforceable gate) that the decomposition agent cannot resolve because the mechanism is not specified anywhere. The rest are smaller, but each would have cost a session to discover mid-implementation.

This review is docs-only by design — there is no code to review yet (the crate is the skeleton). The code-level review passes (alkty-001 / alksocks-002 style) come after the first implementation batches land.

Methodology

• Full read of every architecture document, all 14 ADRs, every research document, the SDD process, and all five tasks/architecture/ files.
• Cross-check of every load-bearing external API claim against the real sibling sources: alkcall 0.8 (AccessControl::check semantics, OwnershipStore, Identity, ChannelOpenSpec, OperationSpec, ADR-025/017/011/047 texts) and alktty (TtyBackend async-trait pattern, register_openable/establisher shape, TtySession).
• Cross-check of the pinned gitoxide APIs against the reference clone (/workspace/gitoxide, matching published 0.87.1): the ADR-013 ingestion composition (Bundle::write_to_directory_eagerly, thin_pack_base_object_lookup, PreviousValue::MustExistAndMatch), ADR-014's subtraction mechanism (gix_traverse::commit::Simple filtered walks), gix_validate::reference::name, and the gix-pack feature set claims.
• Feature-matrix probe: cargo check under all four configurations (default, --no-default-features, --features sha256, --all-features) — the ADR-012 §4 feature split and the wire-layer-without-gix claim, tested rather than trusted.
• Dyn-compatibility probe: a scratch crate (/tmp/opencode/dynasync) reproducing ADR-012 §1's literal trait shape (async fn + Arc<dyn Trait>) under both the active toolchain (1.94) and the pinned MSRV (1.88) — see A-2.
• Verification battery on the current tree (see baseline below).
• Cross-reference integrity sweep: every ADR-NNN / OQ-NN reference in docs/architecture/ resolved against existing files, including the sibling-crate ADR citations (alkcall 003/011/017/025/040/047, alknet 033/035); every deferred OQ checked for the two-half protocol (tracker entry + tasks/architecture/ task) and for circular deferral.

Verification Baseline

All commands on the reviewed tree (commit d6d013e, clean):

• cargo check (default features): clean.
• cargo check --no-default-features: clean — the wire layer compiles without gix (the ADR-010/ADR-012 §4 claim is true today).
• cargo check --features sha256 and --all-features: clean.
• cargo test: passes (0 tests — the skeleton; the suite is trivially green).
• cargo clippy --all-targets -- -D warnings: clean.
• cargo fmt --check: clean.
• cargo doc --no-deps: 0 warnings.
• cargo +1.88 check: clean (the manifest's rust-version = "1.88" is real).
• cargo publish --dry-run --allow-dirty: completes.
• git --version: 2.43.0 — the integration-test surface the ADR-013/014 captures were built against is present in this environment for implementation-phase verification.

Summary Statistics

Severity	Count	IDs
Critical	3	A-1, A-2, A-3
Major	3	A-4, A-5, A-6
Minor (stale doc)	3	D-1, D-2, D-3
Observation	5	N-1..N-5

No finding questions the architecture's direction — the pure-protocol- crate shape (ADR-010), the capture-grounded wire decisions (ADR-013/ 014), and the auth model (ADR-011) all survived the pass intact. Every finding is a mechanism gap: the WHAT is decided, a HOW the docs implicitly assumed turns out to be wrong or missing, and the resolution is an amendment or one small ADR each. The three criticals share a property: they sit exactly where a decomposer would cut tasks (the op gate, the backend trait signatures, the native session preamble), so they would each silently fork into incompatible implementations rather than fail loudly.

Finding prefixes: A (architecture/spec defect — decision or mechanism), D (documentation staleness), N (notes/observations).

---

Part A — Findings

A-1 [critical] — ADR-012 §3's two-tier op gate ("scope git:admin or ownership") is not expressible in alkcall's AccessControl, which composes restrictions as AND

Files: docs/architecture/decisions/012-registry-backing-and-ops.md §3 (the gate table and the "uses the checks AccessControl::check already composes" claim); alkcall src/registry/spec.rs:94-171 (the mechanism); docs/architecture/backend.md §"The two op kinds".

Problem: ADR-012 §3 gates the CRUD ops with a two-tier rule — git/repo/delete|update|get are allowed to "scope git:admin or ownership" — and states the rule "uses the checks AccessControl::check already composes: required_scopes for the global tier, resource_type

• ownership for the self-owned tier." I verified alkcall's check() directly: the restrictions compose as AND, in a fixed order — required_scopes are checked first and fail hard (Forbidden), then required_scopes_any, then the ownership/resource block. There is no scope-OR-ownership composition, and required_scopes_any is scope-set-OR, not scope-or-ownership. A single OperationSpec therefore cannot express the gate:

• required_scopes: ["git:admin"] + resource_type on one spec → requires both; a self-owned non-admin user is Forbidden at the registry and the handler never runs.
• ownership-only (resource_type + resource_id_path, no scopes) → a global admin who does not own the repo is Forbidden at the registry.
• The "or" cannot be recovered handler-side, because the registry gate fires before dispatch reaches the handler in both shapes.

Consequence: any of the three gate rows in the ADR-012 §3 table, built naively, either locks out the self-owned tier (the entire point of the two-tier design — "a user who creates a repo administers their own repos") or locks out the global admin. This is not a corner: it is the primary authorization path for every management op in the crate.

Options:

• (a) Handler-side two-tier check (recommended). git/repo/create keeps its pure-scope registry gate (required_scopes: ["git:repo:create"] — no ownership tier, so the static engine serves it fine). git/repo/delete|update|get carry an empty AccessControl::default() and the handler evaluates the two-tier rule itself: admin scope OR OwnershipProvider::owns(identity, "git/repo", repo_id, action), else a generic FORBIDDEN. This matches ADR-011 §4's own pattern — policy lives in alkgit core, one tested function — and keeps the two-tier rule unit-testable in-crate instead of hidden in an assembly-supplied provider. The gitea lesson is unaffected: visible-surface = authorized-surface is about enforcement living in the same place as exposure, and a handler-side check is exactly as enforcement-shaped as the registry gate (it denies with the same generic error; no existence oracle — the handler must return the same denial for unknown-repo and not-owner, per ADR-008's rule).
• (b) Ownership-provider composition. Keep the gate registry-side (resource_type + resource_id_path, no scopes) and have the assembly's OwnershipProvider report admin-scoped identities as owning everything. Mechanically clean (all enforcement in alkcall dispatch), but it hides the two-tier policy in assembly code — untestable in-crate, invisible to the architecture, and it overloads owns() semantics.
• (c) Extend alkcall's AccessControl with a scope-or-ownership mode. Cleanest long-term but it is a family-crate change on someone else's release cadence; not alkgit's decision to make unilaterally.

Fix (small): a short ADR (or an explicit amendment block on ADR-012 §3, the pattern ADR-004 used for ADR-010's layout change) recording the mechanism — recommended: option (a), with the create-op carve-out, the generic-denial requirement, and the (store, ownership) handler wiring spelled out. The ADR-012 §3 sentence "uses the checks AccessControl::check already composes" must be corrected either way — as written it certifies a composition that does not exist.

---

A-2 [critical] — ADR-012 §1's literal trait signatures (async fn in traits) do not compile as Arc<dyn GitRegistryStore>: not dyn-compatible (E0038); async-trait is absent from the manifest

Files: docs/architecture/decisions/012-registry-backing-and-ops.md §1 (the signature block), docs/architecture/backend.md §"Concurrency model" ("The traits are Send + Sync object-safe"), §3 ("thin OperationSpec+handler pairs over Arc<dyn GitRegistryStore>"), Cargo.toml (no async-trait).

Problem: ADR-012 §1 writes the registry traits with bare async fn:

pub trait GitRegistry: Send + Sync {
    async fn resolve(&self, repo_id: &str) -> Result<RepoRecord, RegistryError>;
}

backend.md simultaneously claims the traits are "Send + Sync object-safe," and ADR-012 §3 puts them behind Arc<dyn GitRegistryStore>. Bare async fn in a trait is not dyn-compatible — I reproduced this exactly with a scratch crate (/tmp/opencode/dynasync, a trait with one async fn coerced to Arc<dyn Trait>): rustc 1.94 and the pinned MSRV 1.88 both reject it with E0038 ("the trait Reg is not dyn-compatible ... method resolve is async"). The family precedent resolves it the same way every time: #[async_trait] (alktty's TtyBackend, alkcall's ProtocolHandler, both pinned at async-trait = "0.1" in their manifests) — but alkgit's manifest does not carry the dependency, and neither ADR-012 §1 nor backend.md says the word.

Consequence: the registry traits are the first thing every backend/ops/registry-file workstream touches; the first task that writes Arc<dyn GitRegistryStore> hits E0038 against a signature the ADR presents as normative. Because these signatures are the OQ-03 freeze inventory, the correction should be pinned before decomposition so no task bakes in an ad-hoc answer (hand-rolled BoxFuture signatures, a private ErasedRegistry wrapper, per-trait #[async_trait] vs manual desugaring — three workstreams, three answers, one freeze surface).

Fix (small): amend ADR-012 §1 and backend.md to #[async_trait] on all five traits (the signatures otherwise stand — Send + Sync, resolve async per ADR-011 §6, the write supertrait split per alknet ADR-035's shape), and add async-trait = "0.1" to the manifest. One conscious note for the freeze inventory: #[async_trait] desugars to Pin<Box<dyn Future + Send + 'async_trait>> — that boxed form is the published vtable shape, which is fine, but it should be pinned deliberately (OQ-03) rather than discovered at first publish. The five-trait family (GitRefs, GitPackGen, GitPackIngest too) should get the same attribute in the same amendment so all six signatures in the corpus agree.

---

A-3 [critical] — The native path has no pinned session preamble: the service dimension is missing from the session tuple, and the channels open-op params are pinned as "repo id" only — as written, push is unservable over the alk/git ALPN

Files: docs/architecture/overview.md (crate map: "repo id in open-op params"), docs/architecture/decisions/010-pure-protocol-crate.md (same pin), docs/architecture/decisions/002-front-door-blind-core.md (the session tuple), docs/architecture/decisions/005-session-substrate-types.md, docs/architecture/transport.md §substrate, docs/architecture/decisions/013-receive-pack-state-machine.md §2 (server-speaks-first on duplex push).

Problem: every door selects the git service (upload-pack vs receive-pack) before the protocol starts — http by route (/{repo}/git-upload-pack vs /{repo}/git-receive-pack, doors.md), ssh by the parsed exec command (git-upload-pack '<repo>' vs git-receive-pack '<repo>', doors.md's alkssh requirement). On the native path the carrier is underdetermined, and the two native sub-paths the crate map names each have a hole:

1. Channels path (register_openable): the docs pin the open-op params as "repo id in open-op params — the negotiation + ACL point" (ADR-010, overview crate map). Nothing carries the service, and the consequences start before the state machine even runs:
   • The open-time ACL point cannot evaluate the write tier. The reason the repo id rides the open-op params is that the open op is "the negotiation + ACL enforcement point" — ADR-007's resolve→authorize sequence runs at open time, before the channel carries protocol data. But authorize(record, identity, action) is per-action (ADR-011): fetch needs the read check, push needs the write check. Without the service in the params, the open gate cannot know which check to run — it either admits a pusher it should have rejected at the gate (deferring the write check into the session, weakening the ADR-007 posture) or over-restricts.
   • The session cannot choose its state machine. Both advertisements are server-emitted firsts on the duplex path (the V2 capability advertisement for fetch, ADR-003; the V0 ref advertisement for push — ADR-013 §2 "the server speaks first" — where "speaks first" means the advertisement precedes the client's protocol request, not the open op itself). With no service anywhere in the open-op handshake, the server cannot select which advertisement to emit. As specified, push over alk/git channels is impossible.
2. Direct-ALPN path (GitAdapter): the crate map says "POC-1 verbatim," and POC-1's shape carries the service in-band — the git-daemon request line (git-upload-pack <repo>\0host=…\0\0version=2\0 for fetch; git-receive-pack <repo>\0host=…\0 for push, poc-1-findings §2 / push-captures §request), client-sent before the server speaks. But that framing on the alk/git ALPN is alkgit-specific wire format (real git clients never touch the native path — they speak to doors), and AGENTS.md convention 9 explicitly says alkgit-specific framing "will get ADRs when it exists." No ADR pins it: whether GitAdapter parses a git-daemon-style request line, a JSON preamble, or expects the caller to pre-negotiate is unspecified. (POC-1's bridge emulated a git:// TCP server because real git was the client; GitAdapter's native clients are GitSession and alkcall-speaking embedders — a different contract that no doc defines.)

The session tuple itself lacks the dimension: ADR-002's tuple and transport.md's substrate inputs are "(peer identity, resolved repo id, duplex stream, Limits)" and "(peer identity, resolved repo id, request-reader, response-writer, Limits)" — no service/variant selector. The stateless substrate gets the service from the door's route, but the substrate input must carry it explicitly (nothing in the POST body reliably distinguishes an upload-pack POST from a receive-pack POST before parsing). GitSession (the consumer half) mirrors whatever is pinned here, so the consumer half is blocked on it too.

Fix (small — one ADR): pin the native session preamble. The shape the corpus already points at (my recommendation, but the ADR should decide):

• The channels open-op params schema is {repo, service} — JSON, service ∈ {"git-upload-pack", "git-receive-pack"}, additive- extension rule (alksocks pinned {} with additionalProperties: false for exactly this reason: extensions stay additive; here the first extension already exists at v1). The params are the open-time ACL point (ADR-010 unchanged) and the service selector — the service at open time is what lets the gate run the correct authorize action (read for fetch, write for push) per ADR-011, instead of deferring the write check into the session.
• The duplex session tuple gains the service dimension: (identity, repo, service, stream, limits) — amend ADR-002, ADR-005, and transport.md's substrate input lists (the authorized- repo marker from D-3 rides the same amendment).
• GitAdapter (direct ALPN) parses a pinned in-band preamble carrying the same fields — the git-daemon request-line grammar (POC-1 verbatim, real-git-compatible framing, service-in-first-line) is the natural candidate and needs the ADR convention 9 asks for, since it is alkgit-specific wire format on a published ALPN (freeze inventory, one-way).
• GitSession::open_via_channels sends the same params schema.

Note the version dimension does not ride the preamble: fetch is V2-only (ADR-003 — V0/V1 clients get a clear error) and push is V0-framed unconditionally (ADR-013 §1), so service fully determines the state machine. That is worth stating in the ADR — it is the reason one field suffices.

---

A-4 [major] — ADR-014 §2's done-round boundary set is "the request's haves," but haves include unverified client claims; the boundary set should be the recognized subset (the ADR's own honesty rule)

Files: docs/architecture/decisions/014-v2-negotiation-ack-loop.md §2, docs/architecture/transport.md §fetch, cross-checked against docs/research/negotiation-captures.md and upstream behavior.

Problem: ADR-014 §2 says the done round "generates closure(wants) − closure(haves) … with the request's haves as the boundary set." The request's haves are a mix of acked commons (which the server verified via common_haves in an earlier round) and new, never-verified haves the negotiator is offering. Taking the boundary set literally — subtract on the raw request haves — means the server honors unverified client claims: a client (buggy or malicious) that claims have-X without having it receives a pack missing closure(X) ∩ closure(wants) and fails client-side with "did not send all necessary objects." Self-inflicted, not a server-side hole — but it contradicts the ADR's own honesty principle ("never ack what we cannot subtract," §1/§5) at the one place subtraction actually happens, and it deviates from upstream: upload-pack marks a have uninteresting only after confirming the object exists server-side.

The mechanism to do it right is already in the corpus: §5's common_haves seam. The boundary set should be the recognized subset — common_haves(repo, request_haves) — applied on the done round exactly as on the ack rounds. Existence is the operative predicate for subtraction (a non-commit have can legitimately bound traversal); the is-commit refinement in §1 exists for ACK-line correctness, not for subtraction. I verified the traversal side supports this cheaply: gix_traverse::commit::Simple::filtered(tips, find, predicate) takes exactly a boundary predicate ("whether a commit should be included as well as whether its parents should be traversed" — gix-traverse source), so verify-then-subtract is one predicate, not a custom walk.

Fix (small): one clause in ADR-014 §2 ("the boundary set is the recognized subset — request haves filtered through common_haves — not the raw request list; the ack rule and the subtraction rule are the same honest-boundary rule at different points") and the same clause in transport.md §fetch. Cost: one existence check per have on the done round — already paid on every ack round; no new budget kind.

---

A-5 [major] — The consumer half (GitSession) is named in five documents and specified in none; its scope is the largest uncut ambiguity for decomposition

Files: docs/architecture/overview.md (crate map: "new, small (TtySession analog)"), docs/architecture/decisions/010-pure-protocol-crate.md, docs/architecture/backend.md §"Public API surface", docs/architecture/transport.md §"Public API surface", docs/architecture/doors.md, docs/architecture/decisions/012-registry-backing-and-ops.md §4 (the dependency rider), Cargo.toml (unconditional gix-protocol = "0.65" + gix-transport = "0.59").

Problem: ADR-010 makes the consumer half a load-bearing half — "GitSession typed client with connect_direct and open_via_channels constructors … the alkcall-native primitive for replication/mirroring in the alknet rewrite" — and every public-API list includes it. But no document says what it does. The reading that it is "small" like TtySession (a typed wrapper over an established byte stream) is doing unexamined work: a git client that can drive fetch/push means client-side protocol state machines (want/have negotiation, V2 request encoding, push command/pack construction, response parsing) — an entire second surface that transport.md does not cover (it is server-side only). ADR-012 §4 explicitly deferred the deciding call — "gix-protocol's response parsing or hand-roll the small client surface; gix-transport is almost certainly droppable. Implementation-time call, recorded, not an architecture commitment" — but the manifest carries both crates unconditionally today (not feature-gated, not optional), so the "pending decision" is already a compile-graph commitment.

Consequence: the decomposer either silently omits the half (leaving ADR-010's producer/consumer claim unimplemented and the manifest overweight) or invents its scope (client protocol machines nobody designed). Both are bad; the decision is cheap now.

Options:

• (a) Thin wrapper in v1 (recommended) — GitSession is what the crate-map words say: connect_direct / open_via_channels constructors, the session preamble (A-3's shape), and raw pkt-line-adjacent access sufficient for alkgit↔alkgit replication to ride it — with client protocol state machines explicitly deferred (recorded as out of scope). This matches the "TtySession analog" reading exactly (TtySession wraps streams; the tty protocol lives in the negotiation layer), keeps gix-protocol as the future client parser, and lets the manifest carry the two deps honestly as the consumer half's declared seam.
• (b) Defer the half entirely — drop gix-protocol/gix-transport from the manifest (real dependency-graph reduction; both pull nontrivial trees), amend ADR-010's crate map and both public-API sections, and record the alknet-replication primitive as a future half. Cleanest scope, but it walks back a headline ADR-010 claim.
• (c) Full client in v1 — make the consumer half real (V2 request encoding, negotiation loop, push construction). This is a second protocol surface with its own capture-testing burden; nothing in the research corpus validates it and no consumer needs it before the alknet rewrite.

Fix: a user scope decision, then either an amendment (a/b) or a small ADR; whichever is chosen, the manifest's two client-side deps become honest (carried with purpose, or dropped).

---

A-6 [major] — The backend traits' execution model is unspecified: async-trait methods on the executor vs sync methods on the blocking pool determines where ADR-009's pipeline budget lives

Files: docs/architecture/backend.md §"Concurrency model" ("impls run under the adapter's tokio context"; GitPackIngest "blocking-thread friendly"), §"The trait family" (GitPackGen/ GitPackIngest signatures), docs/architecture/transport.md §fetch ("generation runs on spawn_blocking with the owned handle moved in"), docs/architecture/decisions/009-bounded-resources-budget.md ("max concurrent blocking pipeline tasks … enforced at assembly/acceptance time"), ADR-013 §6 / ADR-014 §5.

Problem: the corpus describes the execution model three different ways without committing to one. transport.md §fetch states the POC-2 shape in the wire layer's voice ("generation runs on spawn_blocking with the owned handle moved in — store shared, handle per session") — but the wire layer is backend-trait-only (ADR-010): it holds Arc<dyn GitPackGen> and there is no "store" or "handle" in its vocabulary; store/handle/spawn_blocking is the gix impl's internal shape. backend.md says the traits are async (resolve is; A-2's amendment makes all of them #[async_trait]) and impls "run under the adapter's tokio context" while also being "blocking-thread friendly." And ADR-009's blocking-pipeline budget is "enforced at assembly/acceptance time (reject/slow-path excess concurrent generations)" — but who admits: the wire layer around the trait call, or the impl inside it? Two workstreams implementing the same trait from these texts will diverge: one puts spawn_blocking in the wire layer (which then can't, because the trait method is async and the layer is gix-free), one puts it in the impl (and then the wire layer's admission budget has nothing to count).

Consequence: ADR-009's only concurrency budget for the heaviest operations (pack gen/ingest) has no specified enforcement point, and the wire-layer spec carries gix-implementation vocabulary it structurally cannot use.

Fix (small): one paragraph in backend.md's concurrency model (referenced from transport.md), committing to the model the trait signatures already imply: trait methods are #[async_trait]; the wire layer enforces the pipeline-concurrency budget itself (a permit acquired around gen/ingest calls — ADR-009's admission point, now concrete); implementations must not block the async executor and own their internal threading (the gix impls run spawn_blocking with store-shared/handle-per-session inside the impl — POC-2's shape, restated at its true layer). transport.md §fetch's spawn_blocking sentence gets rephrased to the trait-contract version so the wire spec stops speaking gix.

---

D-1 [minor] — Stale superseded text in the docs the decomposer reads first: the "Internal ops over an admin listener" framing survives in vision.md and alk-stack.md, and AGENTS.md's lifecycle list names resolved OQs as active

Files: docs/research/vision.md (threat-model notes: "Registry management ops, if the gix feature ships any, are alkcall Visibility::Internal ops over an admin-only listener"), docs/research/alk-stack.md (gitea-lesson item 2: "Admin API = internal ops … Visibility::Internal ops over the admin interface"), AGENTS.md (Lifecycle Status: "Open architecture questions live in … (OQ-04 receive-pack, OQ-06 registry backing, OQ-08 identity model are the active ones)").

Problem: all three statements are superseded. ADR-012 §3 resolved OQ-07 by rejecting the Internal-ops framing in exactly these words ("right mechanism, wrong axis" — the ops are Visibility::External, gated by scope+ownership, registered by the assembler), and OQ-04/ OQ-06/OQ-08 are all resolved (ADR-013, ADR-012, ADR-011); the active set is OQ-03 (partially resolved) and OQ-05 (deferred). AGENTS.md further declares docs/research/ "the current source of truth for design direction," which makes the stale bullets actively misleading rather than merely historical: a decomposer told to treat research as truth reads two contradicting admin-API designs and a stale OQ list.

Fix (trivial): one-line amendments — vision.md's threat-model bullet and alk-stack.md item 2 get a supersession note pointing at ADR-012 §3 (the research docs are phase-0 records; the note marks the supersession without rewriting history), and AGENTS.md's lifecycle paragraph updates the active-OQ list to OQ-03/OQ-05.

---

D-2 [minor] — ADR-007 step 3 still names AccessControl::check as the enforcement mechanism — superseded in place by ADR-011's authorize policy function, with no note on the older ADR

Files: docs/architecture/decisions/007-acl-before-advertisement.md (step 3: "Run alkcall AccessControl::check(peer_identity) against the repo's required access"), docs/architecture/decisions/011-per-repo-authorization.md §3 (the policy function that replaced it).

Problem: ADR-011 resolved the gap in ADR-007's own context (the static ACL engine "fails closed on identity: None," so it cannot express anonymous-public fetch — verified against alkcall's check(), which returns Forbidden("authentication required") for None with restrictions). ADR-011 records the resolution, but ADR-007's decision text — the doc an implementer reads for the enforcement order — still instructs wiring the wrong mechanism. A literal implementation of ADR-007 breaks anonymous-public fetch, the deployment anchor.

Fix (trivial): an amendment note on ADR-007 step 3 ("mechanism amended by ADR-011 §3: the per-repo check is alkgit-core's authorize policy function evaluated on the registry record; the step order is unchanged") — the same pattern ADR-004 used when ADR-010 amended its layout.

---

D-3 [minor] — The authorized-repo marker ADR-007 promises is missing from the session tuples in transport.md (and backend.md's API list)

Files: docs/architecture/decisions/007-acl-before-advertisement.md ("the session entry points take an authorized-repo marker — a type the adapter constructs only after step 3 passes — so skipping the check is a type error"), docs/architecture/transport.md §substrate (inputs listed without the marker), docs/architecture/backend.md §"Public API surface" (the marker type is absent from the re-export list).

Problem: ADR-007's type-level enforcement is one of the design's better moves (skipping ACL is a compile error, not a runtime log), but the promise is unfindable from the transport spec — the substrate input tuples omit the marker, so the decomposer slicing transport tasks from transport.md will not include it, and the first session- tuple task will "fix" the signature by removing it (or never add it).

Fix (trivial): add the marker to both substrate input tuples in transport.md (and note it in backend.md's public-API list — it is crate-root surface: the door must be able to construct it). Rides the A-3 tuple amendment if that lands first.

---

Part B — Non-findings (verified correct, recorded to bound re-review)

• The feature story is real, not aspirational. All four configurations compile today on the skeleton manifest: default (gix + registry-file), --no-default-features (wire-only), --features sha256, --all-features. ADR-012 §4's feature split and the default-features = false embed claim are verified properties of the current manifest, not promises about future code. The manifest also already encodes the ADR-012 §4 facade-dropping (component crates only: gix-odb/pack/ref/object/fsck — no gix facade dep) and the sha1 compile-time pin.
• alkcall's ACL semantics verify ADR-011's premise exactly. AccessControl::check (spec.rs:94) fails closed on anonymous callers whenever restrictions exist — the precise property ADR-011 §3 cites as why the static engine cannot express anonymous-public fetch. The premise of the per-repo authorization design is confirmed against the real engine, not assumed.
• The alkcall surface the ADRs cite exists as cited: Identity.id as the stable logical id (auth.rs:15, alkcall ADR-025's decoupling), OwnershipStore::record as the async mint (ownership.rs:58, ADR-011), ChannelOpenSpec + openable-ALPNs-are-operations (spec.rs:26, ADR-047), resource_id_path for registry-side ownership extraction, AccessControl's scope/resource composition (the AND-composition that A-1 turns on). alktty's register_openable/establisher/ TtySession template matches ADR-010's producer/consumer claims piece for piece.
• The gitoxide API pins are real. Verified in the reference clone: PreviousValue::MustExistAndMatch (gix-ref transaction CAS), Bundle::write_to_directory_eagerly with thin_pack_base_object_lookup: Option<impl gix_object::Find> (ADR-013 §5/§6's thin-pack composition, exactly the named parameter), gix_validate::reference::name (ADR-013 §9), and — load-bearing for ADR-014 — gix_traverse::commit::Simple::filtered with Predicate: FnMut(&oid) -> bool, the have-boundary traversal A-4's verify-then-subtract rides. The gix-pack feature-set claims (generate, streaming-input, parallel as separate features) match the crate's Cargo.toml. One item remains honestly deferred by the docs themselves: gix-discover + gix_odb::Store::at composition is marked "Verified at implementation" in backend.md — it was not independently verified here, and the docs do not claim it was.
• ADR-013 and ADR-014 are model capture-grounded decisions. Both resolve every listed unknown against real-client behavior (raw stdio into real git receive-pack for policy ground truth; fetch-pack.c source cross-checks), record the failure modes of getting it wrong, bind prior tool decisions (ADR-004) to concrete calls, and file their own backlog riders (oq-13-cas-failfast). transport.md and backend.md are consistent with both ADRs in every detail I compared (advertisement sets, report framing, ack grammar, budget placements).
• Deferral hygiene is clean. Both remaining OQs are properly two-half-tracked: OQ-05 (deferred(scope), ecosystem need) and OQ-03 (partially resolved; the freeze inventory itself) each have the tracker entry in open-questions.md with a concrete blocked-on condition and the machine-readable tasks/architecture/ tracker task. Neither is circular — OQ-03's blocker (first-publish timing) is genuinely downstream of implementation, and OQ-05 waits on external ecosystem need. Resolved-early trackers (OQ-04, OQ-06) are correctly closed with their resolution recorded.
• Cross-reference integrity is exceptional. Every ADR-NNN and OQ-NN reference across the corpus resolves to an existing file, and every sibling-crate citation I checked (alkcall ADR-003/011/017/025/ 040/047, alknet ADR-033/035, alkcall AccessControl/OwnershipStore) says what the citing document claims it says. The superseded pair (ADR-001, ADR-006) is marked Superseded and consistently referenced as such.
• The crate manifest is coherent with the architecture beyond the two findings above: rust-version = "1.88" verified real, the feature comments state their ADR provenance, the dev-deps match the planned test surface (tokio full + test-util), and cargo publish --dry-run completes.

---

Part C — Notes and observations

N-1 [observation] — The advertisement ref-cap's breach behavior is unstated, and truncation is the tempting implementation

ADR-009's table carries "max advertisement refs" but its breach rule ("the session ends with a substrate-appropriate error") was written for the loop/size budgets; a streaming ls-refs implementation hitting the cap will be tempted to stop emitting refs and flush (a silent partial ref list — the nastiest failure mode a ref advertisement can have, since clones appear to succeed). One clause in transport.md (§Limits): the ref cap is fail-closed like every other budget — breach is an error, never a truncation.

N-2 [observation] — The unknown-repo ≡ unauthorized indistinguishability is not stated at the wire-mapping point

ADR-007 step 2 and ADR-008 pin the rule, but transport.md's error taxonomy (the place RegistryError variants get mapped onto pkt-line bands / http statuses) does not mention it. RegistryError::NotFound and an authorization failure must collapse to one wire error at that mapping — one sentence in transport.md §error taxonomy prevents the variant leak.

N-3 [observation] — The freeze inventory's schemas are unpinned: RepoRecord, RegistryError, and the git/repo/* request/response shapes

OQ-03 counts "names + schemas" in the freeze inventory, but nothing specifies the serde shape of RepoRecord (field names, the grants map's value shape, visibility representation), RegistryError's variant set, or the four ops' JSON schemas. Two workstreams would invent them independently (the ops handlers and the registry-file store both serialize the record). One backend.md section (types + schemas, even as draft) closes it before the freeze inventory is taken as complete.

N-4 [observation] — ADR-013 §11's push-options seam has no trait input to surface into

"surfaced to the ingest/refs seam as per-push metadata" — but no backend trait signature carries a per-push metadata input, and push-options are default-off in v1. Pin the additive shape now (e.g. an Option<&PushOptions>-style parameter on the GitPackIngest binding, default None until the config gate opens) so opening the gate later is a signature-additive change, not a trait redesign.

N-5 [observation] — ls-refs=unborn is advertised but unborn-HEAD serving was never capture-verified

Every POC fixture had refs; the advertisement promises ls-refs=unborn (transport.md §advertisement, POC-1-validated as an accepted capability token, not as a served behavior — serving an unborn HEAD's symref line was never exercised against real git). This is the only advertised promise in the corpus without capture evidence. One implementation test (ls-refs against an unborn repo, real client, both substrates) closes it; if it cannot be served, the honest move per ADR-003 is dropping the token.

---

What's Good

• The two newest ADRs are the strongest documents in the corpus. ADR-013 and ADR-014 are exactly what capture-grounded architecture should be: real-client walkthroughs (including raw stdio probes for policy ground truth), source cross-checks recorded with versions, every unknown from the OQ resolved with evidence, consequences stated honestly (including the accepted capability gaps), and backlog riders filed where optimization was declined.
• The structural spine (ADR-010/002/005/007/008/009) has survived four decision cycles without drift — the pure-protocol-crate correction, the feature split, and the two wire ADRs all amend around it cleanly, and the corpus's cross-reference integrity is the best I have traced in the family.
• The honest-capability discipline is consistent everywhere it appears — fetch declination by omission (POC-1-validated), the push served set matched to exactly what the state machine serves (quiet's omission reasoned through, report-status-v2's v1-shape argument capture-backed), and git-upload-archive's fixed refusal carried across every door.
• The deferral protocol worked. Both resolved-early deferrals (OQ-04, OQ-06) record why the deferral dissolved, both remaining deferrals have concrete non-circular blockers, and the two-half tracking (OQ entry + tracker task) is in place for every one of them.

---

Remediation

Nothing is remediated yet — this review is the gate output. Suggested batches for the fix round (each is one session-sized unit; the criticals are ADR-writing work, not code):

ID	Finding	Recommended fix	Effort	Risk	Status
A-1	op-gate OR not expressible in AccessControl	new ADR (or ADR-012 §3 amendment): handler-side two-tier check, create keeps static scope gate	small	none	resolved (ADR-015) — option (a) shape with the OR-term generalized to the manage grant
A-2	async fn traits not dyn-compatible	ADR-012 §1 + backend.md amendment: #[async_trait]; add async-trait = "0.1" to manifest	small	none	resolved — all five traits #[async_trait], desugared boxed form pinned in the freeze inventory (OQ-03), dep in manifest
A-3	native preamble / service dimension unpinned	new ADR: open-op params {repo, service}, session tuple + stateless entry gain the service selector, GitAdapter preamble pinned	moderate	wire-format (freeze inventory)	resolved (ADR-016) — {repo, service} open-op params (channels/git/sub, additionalProperties: false), git-daemon request line on the direct path (POC-1 verbatim, freeze inventory), service in both substrate tuples, GitSession mirrors the shapes
A-4	done-round boundary set unverified	ADR-014 §2 + transport.md clause: boundary = common_haves-filtered haves	trivial	none	resolved — boundary set is the recognized subset (common_haves-filtered), amendment clause in ADR-014 §2 + transport.md §fetch
A-5	consumer half unspecified	user scope decision, then amendment or small ADR (recommended: thin wrapper, deps carried with purpose)	small	scope	resolved (ADR-017) — superseding the thin-wrapper recommendation: GitSession is a real typed client in v1 (ls_refs/fetch/push), grounded in the two deployment use cases (the p2p replicator is the named downstream and needs the client protocol layer); fetch reuses gix-protocol over a custom alkcall Transport, push is hand-rolled to ADR-013's shapes (gitoxide has no send-pack), storage-agnostic
A-6	trait execution model unspecified	backend.md paragraph + transport.md rephrase: async traits, wire-layer permit, impl-internal spawn_blocking	small	none	resolved — backend.md concurrency model: wire layer enforces the ADR-009 permit around gen/ingest trait calls; impls own internal spawn_blocking (ADR-009/ADR-013 aligned)
D-1	stale Internal-ops + OQ-list text	supersession notes (vision, alk-stack, AGENTS)	trivial	none	resolved — supersession notes in vision.md (with ADR-015) and alk-stack.md item 2; AGENTS.md active-OQ list updated to OQ-03/05/16
D-2	ADR-007 step-3 mechanism superseded	amendment note on ADR-007	trivial	none	resolved — amendment note on ADR-007 step 3 (mechanism → ADR-011 authorize; step order unchanged)
D-3	authorized-repo marker missing from tuples	add to transport.md tuples + backend.md API list	trivial	none	resolved — marker added to both substrate input tuples (transport.md) and backend.md public-API list
N-1	ref-cap breach behavior	one fail-closed clause in transport.md	trivial	none	resolved — ref cap fail-closed clause in transport.md §Limits (breach is an error, never truncation)
N-2	unknown ≡ unauthorized at wire mapping	one sentence in transport.md error taxonomy	trivial	none	resolved — collapse rule stated at the variant→wire mapping in transport.md §error taxonomy
N-3	schemas unpinned	backend.md types/schemas section	small	freeze inventory	open
N-4	push-options seam	pin additive parameter shape	trivial	none	resolved — 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 + backend.md trait description, so opening the gate is value-additive, not a trait redesign
N-5	ls-refs=unborn unverified	implementation-phase test rider (record in transport.md or a task)	trivial	none	resolved (rider) — unborn-HEAD verification recorded in transport.md §ls-refs and 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)

Suggested sequencing: (1) A-2 + A-6 together (one trait-surface amendment set + manifest change — they are the same signature surface); (2) A-3 (the one new wire-format ADR; A-5's decision unblocks with it); (3) A-1 (the op-gate ADR); (4) A-4 + D-2 + D-3 + N-1 + N-2 (one doc batch — all transport/ADR amendments, no new decisions); (5) A-5 (user decision, then the doc change); (6) D-1 + N-3 + N-4 + N-5 (hygiene batch). After the batch that resolves each spec's findings, the spec docs are candidates for reviewed status per the lifecycle definition, and decomposition can start.

---

References

• ADR-010/002/005 (the structural spine A-3 amends), ADR-012 (§1/§3 — A-2/A-1's subject), ADR-013/014 (A-4's subject; verified sound), ADR-007/008/011 (the auth chain — D-2/D-3), ADR-009 (N-1, A-6's budget), ADR-003 (honest advertisement — N-5)
• alkcall src/registry/spec.rs (AccessControl::check — A-1's mechanism evidence), src/core/auth.rs, src/core/ownership.rs; alkcall ADRs 003/011/017/025/040/047 (all citations verified)
• alktty src/backend.rs/src/channels.rs/src/session.rs (the async-trait + register_openable + TtySession template)
• gitoxide reference clone /workspace/gitoxide (gix-ref PreviousValue, gix-pack Bundle::write_to_directory_eagerly, gix-traverse Simple::filtered, gix-validate reference::name, gix-pack feature set)
• docs/research/poc-1-findings.md (the in-band request-line shape — A-3's direct-ALPN evidence), push-captures.md / negotiation-captures.md (ADR-013/014's normative basis)
• The house format: alksocks docs/reviews/001-rfc1928-full-review.md (structure, severity legend, non-findings discipline), alkty docs/reviews/001-code-review.md (status conventions)