alkgit/docs/reviews/002-post-remediation-review.md

---
status: resolved
last_updated: 2026-09-30
reviewed_artifacts:
  - 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..017, post-review-001 amendments)
  - Cargo.toml
  - tasks/architecture/ (all seven tracker/rider tasks)
tool: manual full-corpus re-read post-remediation + sibling-crate
  re-verification (alkcall spec.rs/registry surface, alktty channels
  establisher) + gitoxide reference-clone checks (gix-transport
  async traits, gix-protocol Cargo) + four-config compile probes on
  the amended manifest + MSRV 1.88 check/clippy
reviewer: architecture pre-decomposition re-review (fix-verification
  + residual-gap pass over review 001's remediated corpus)
scope_note: gate re-review — verifies every review 001 finding landed
  correctly, then hunts the residuals the fixes created at the new
  seams. Same standard as 001: could a decomposition agent and an
  implementation agent proceed without inventing divergent answers?
---

# Review 002 — Post-Remediation Re-Review

## Purpose

Review 001 gated phase 1 on its remediation. This review verifies that
remediation (all 14 findings, A–D–N) landed correctly and completely,
then re-runs the contradiction/gap/staleness pass over the amended
corpus. Same methodology class as 001: full-corpus read, sibling-source
cross-checks, and compile probes — this time *after* the fix round, on
the amended manifest (which gained `async-trait = "0.1"` and
`async-client` on `gix-protocol`/`gix-transport`).

## Verification Baseline

All commands on the post-remediation tree (commit `11ceead` + the N-3
commit `b6040d3`, clean):

- `cargo test`: **passes** (0 tests — still the skeleton).
- `cargo clippy --all-targets -- -D warnings`: **clean**.
- `cargo fmt --check`: **clean**.
- `cargo doc --no-deps`: **0 warnings**.
- All four feature configurations check clean: default,
  `--no-default-features`, `--features sha256`, `--all-features` —
  the manifest grew `async-trait` and the `async-client` features
  without breaking the wire-layer-without-gix claim (ADR-012 §4 still
  true).
- `cargo +1.88 check` and `cargo +1.88 clippy --all-targets -- -D
  warnings`: **clean** — the new dep configuration holds at the pinned
  MSRV.
- `cargo publish --dry-run --allow-dirty`: **completes**.
- Sibling re-verification: alkcall `AccessControl` still AND-composes
  as ADR-015 routes around (spec.rs:67–72); `AuthContext.identity` is
  `Option<Identity>` — anonymous-public fetch through the channels
  establisher (ADR-016's open-time `authorize`) is expressible as
  specified; `ChannelOpenSpec`/`ErrorDefinition`/`OperationSpec`
  match backend.md's op-schema citations; alktty's
  `channels/tty/sub` establisher template matches ADR-016's
  `channels/git/sub` claims (including the per-call `AuthContext`
  identity the establisher reads); gix-transport's async client
  traits are `#[async_trait(?Send)]` exactly as ADR-017 §2 states;
  gix-protocol's `async-client` feature exists and pulls
  `async-trait` (both rust-version 1.88 — manifest alignment
  verified).

## Remediation Verification (Part A — all 14 findings)

Each verified at file level, not from the remediation table's claim:

- **A-1 → ADR-015**: the two-tier op gate is re-expressed as
  admin-scope-OR-`manage`-grant, handler-evaluated; ADR-012 §3's table
  carries the amendment note; backend.md §"The two op kinds" restates
  the mechanism; `create` keeps its static scope gate. The AND-
  composition premise re-verified against alkcall source.
- **A-2**: `#[async_trait]` amendment on ADR-012 §1's signatures with
  the desugared boxed form pinned into OQ-03's freeze inventory;
  `async-trait = "0.1"` in the manifest with provenance comment.
- **A-3 → ADR-016**: `{repo, service}` open-op params
  (`additionalProperties: false`), the git-daemon request line
  (verified verbatim against poc-1-findings §2), service in both
  substrate tuples, ADR-002/005/010 amendment notes all present.
- **A-4**: ADR-014 §2's amendment clause (recognized-subset boundary
  via `common_haves`, ack rule ≡ subtraction rule) + the same rule in
  transport.md §fetch.
- **A-5 → ADR-017**: consumer half specified as a real typed client
  (superseding the review's thin-wrapper recommendation with grounded
  use cases); manifest deps carry purpose comments; the
  `#[async_trait(?Send)]` claim verified against gix-transport source.
- **A-6**: backend.md's concurrency model commits to the trait-level
  permit / impl-internal `spawn_blocking` split; ADR-009's
  enforcement-point consequence updated; transport.md rephrased.
- **D-1/D-2/D-3, N-1..N-5**: supersession notes in vision.md +
  alk-stack.md + AGENTS.md OQ list (now OQ-03/05/16); ADR-007 step-3
  amendment; authorized-repo marker in transport tuples + backend API
  list; fail-closed ref-cap clause; unknown ≡ unauthorized at the
  variant→wire mapping; N-3 schemas section; `push_options` param on
  the prepare binding; unborn-HEAD rider task + transport.md note.

**Remediation verdict: complete and faithful.** No fix landed in a way
that contradicts its finding or another decision.

## Findings (Part B — residuals at the fixed seams)

Severity: the corpus no longer has criticals. The majors are one
backend.md section each; the minors are one-sentence fixes.

### R-1 [major] — Traits 3–5 have no pinned signatures; ADR-012 §1 (as amended by A-2) covers only the registry pair

**Files**: ADR-012 §1 (the A-2 amendment claims "all five traits'
signatures" are pinned there — only traits 1–2 are); backend.md
§"The trait family" (prose descriptions only); review 001's remediation
row for A-2 ("all five traits `#[async_trait]`, signatures per ADR-012
§1" — over-claims its own fix).

**Problem**: `GitRefs`, `GitPackGen`, `GitPackIngest` — the traits the
`gix` feature exists to implement — have no method names, no parameter
shapes, and no shared type definitions anywhere in the corpus. Sharpest
fork: `(repo, wants, haves, limits)`'s `repo` parameter — the wire
layer (backend-trait-only per ADR-010) holds only the resolved repo
id, while the gix impl needs the `storage_root` to open the odb
(`gix-odb::Store::at`), and traits 3–5 are speced as independent seams
from `GitRegistry`, so they cannot lean on the resolve path. Is `repo`
a `&str` id, a `PathBuf`, a registry-derived handle? Equally unpinned:
the `GitPackIngest`→`GitRefs` prepared-updates handoff (the mechanism
`atomic` correctness depends on — ADR-013 §7), and the object-id
representation. Two workstreams (wire layer, gix impl) would invent
incompatible answers, and the invented shapes are OQ-03 freeze
surface. This is review 001 A-2's own failure mode surviving at the
three traits whose signatures were never written.

**Resolution — ADR-018 §2, §4, §5**: signatures pinned for all three
traits; `repo` is `&RepoRecord` (the wire layer resolves once per
ADR-007 and the record carries `storage_root`; no handle type, no
second lookup); shared types pinned (`RefLine` with the unborn-symref
`oid: None` shape for the N-5 rider, `RefUpdate`, `RefOutcome`,
`PreparedPush`, `PushOptions`); object ids are `gix_hash::ObjectId`
(always-on in the manifest, hash-parameterized internally — OQ-05-safe);
parameter ownership is boxed-`Send` streams/owned vecs so the A-6
execution model (impl-internal `spawn_blocking`) has mechanical
support.

### R-2 [major] — backend.md's `RegistryError` pin over-claims: "every failure the trait family can produce"

**Files**: backend.md §`RegistryError` (the "no catch-all, every
failure the trait family can produce" sentence); ADR-013 §7–8 (CAS
outcomes are *business results*, reasons client-displayed).

**Problem**: the five-variant set genuinely covers the registry pair —
but not the object-storage traits' characteristic failures. CAS-stale
is a per-ref *outcome* of receive-pack with its own report semantics
(ADR-013 gives it a server-chosen reason shown to the client); fsck/
unpack failures and missing-object aborts are report legs and aborts
with dedicated wire mappings (ADR-004, ADR-013 §8). Forcing those into
`Io(String)` or `Invalid` contradicts the structural-errors rationale
the variant set exists for, or breaks the "session survives" report
semantics.

**Resolution — ADR-018 §7**: `RegistryError` is re-scoped to the
registry family (the backend.md sentence corrected); traits 3–5 get
`StorageError` (`ObjectMissing { oid }` — the ADR-004 abort;
`Invalid(String)`; `Io(String)` with `RegistryError::Io`'s stability
rule), with the report-vs-error separation stated explicitly (CAS and
fsck outcomes are `RefOutcome`/`PreparedPush.unpack` values, not
variants — which keeps the no-catch-all claim true for both types).

### R-3 [minor] — `git/repo/update` PATCH-vs-PUT ambiguity

**Files**: backend.md §op schemas (`{repo_id, visibility?, grants?}` —
"both optional, full-record replace of the provided fields").

**Problem**: "optional" reads PATCH; "full-record replace" reads PUT
(omitted = cleared). The wrong reading is destructive: a
visibility-only update that clears grants locks the grant-holder out
of the repo via the op they legitimately called.

**Resolution**: PATCH pinned in backend.md — omitted fields left
unchanged; present fields replaced wholesale (`grants` present =
whole-map replace; partial grant edits are caller-side
read-modify-write); the response echo (already specified) is the
confirmation surface. The table cell wording aligned.

### R-4 [minor] — doors.md's alkssh hand-off tuple predates both amendment rounds

**Files**: doors.md §alkssh ("hand (identity, repo, post-auth stream,
limits)").

**Problem**: missing the `service` dimension (ADR-016) and the
authorized-repo marker (review 001 D-3, whose fix swept transport.md
and backend.md but not this third tuple site) — the exact miss D-3
itself warned about ("the first session-tuple task will fix the
signature").

**Resolution**: the tuple now reads `(identity, repo, service,
authorized-repo marker, post-auth stream, limits)` with the exec
command named as the service selector per ADR-016.

### R-5 [minor] — Repo-id grammar unpinned; the N-3 example implies a two-segment id the http route shape doesn't express

**Files**: backend.md §`RepoRecord` (example `"alkdev/alkgit"`), §op
schemas (`invalid` for "empty repo id" implies charset rules exist);
doors.md (single-placeholder routes `/{repo}/…`).

**Problem**: two-segment ids need a two-placeholder http route shape no
doc pins; the `Invalid` variant's empty-id check implies a grammar that
is nowhere stated; the `registry-file` store's record-file naming
derives from the id (a slash in the id forces nested dirs or encoding —
an on-disk layout decision that is freeze-adjacent per ADR-012 §2).

**Resolution**: grammar pinned in backend.md §"Repo-id grammar" —
`owner/name` shape (lowercase alphanumerics + `-_`, ≤100 bytes, one
segment allowed), rejection-only parsing (never decomposition —
ADR-008 governs), error mapping (grammar-invalid = the collapsed
denial on serving paths, `invalid` on op paths),
percent-encoded flat record-file naming for `registry-file`, and an
explicit note that the http door pins its own route grammar
(`/{owner}/{repo}/…`) when the alkhttp `git` feature lands.

### R-6 [observation] — `already_exists` on create is an existence oracle to create-scope holders probing arbitrary ids

**Files**: backend.md §op error codes (the disclosure rationale reasons
only about "the caller knows the id").

**Problem**: a `git:repo:create`-scoped identity can probe ids it
didn't choose and learn which exist. Defensible (trusted, scope-gated,
low-population surface; upstream gitea behaves the same), but the
position was unstated — a later agent might "fix" the disclosure and
break an upstream-compatible error clients rely on.

**Resolution**: the disclosure posture is recorded explicitly in
backend.md (accepted: id-probing at create-scope is inside the trust
boundary the scope grants; resolve-side disclosure stays collapsed per
ADR-008/N-2) so the position survives personnel changes.

### R-7 [minor] — Lifecycle gate ambiguity: docs cannot reach `reviewed` while release-timing OQs are deferred by design

**Files**: docs/architecture/README.md §Document Lifecycle
("→ `reviewed` when its OQs are resolved") vs open-questions.md (OQ-03
partially resolved, OQ-05/OQ-16 deferred(scope) — the deferrals are
correct and non-circular); review 001's remediation note ("the spec
docs are candidates for `reviewed` status per the lifecycle
definition" — which the letter of the definition forbids).

**Problem**: as written, the `draft → reviewed` transition requires
resolved OQs, but the remaining OQs resolve only at first publish /
ecosystem events. An implementer following the letter is blocked; one
following the review's intent is not. Also caught in this pass: stale
`last_updated` frontmatter (2026-09-25) on README/overview/
open-questions/doors despite 09-29/30 edits.

**Resolution**: README's transition definition extended — docs reach
`reviewed` when their OQs are resolved *or* every unresolved OQ is a
properly-tracked deferral with a concrete non-circular blocker (which
is the state review 001's own deferral-hygiene check certified).
All four spec docs flipped to `reviewed` (this review is the gate);
frontmatter timestamps refreshed.

### R-8 [cosmetic] — ADR-016 text glitches

**Files**: ADR-016 §2 ("freeze␣␣␣␣inventory" — collapsed multiple
spaces), §4 (code span broken across a line break: `` `open_via_
channels` `` renders as a broken identifier).

**Resolution**: both fixed; no semantic change.

## Summary Statistics

| Severity | Count | IDs |
|----------|------:|-----|
| Major | 2 | R-1, R-2 |
| Minor | 4 | R-3, R-4, R-5, R-7 |
| Observation | 1 | R-6 |
| Cosmetic | 1 | R-8 |

All resolved in this cycle (ADR-018 + the backend.md/doors.md/README
doc batch). No finding questions the architecture's direction; no
criticals. The corpus is now fully pinned at every seam a decomposer
cuts: session tuples, preamble wire shapes, op schemas, registry types,
trait signatures, error models, concurrency model, and freeze-inventory
entries.

## Verification (post-fix battery)

Re-run after the R-1..R-8 fixes land (see the commit series): four
config compile probes, MSRV check + clippy, full test/clippy/fmt/doc
+ publish dry-run — all expected clean (no code changed; docs-only +
manifest-already-verified).

## References

- Review 001 (the gate this re-review verifies the remediation of) —
  `docs/reviews/001-architecture-pre-decomposition-review.md`
- ADR-015/016/017 (review 001's resolution ADRs), ADR-018 (this
  review's R-1/R-2 resolution)
- backend.md §"Pinned signatures", §"Registry types and schemas"
  (re-scoped), §"Repo-id grammar" (new), §op-surface notes
- Phase-1 gate verdict: **decomposition may begin**