docs(reviews): post-remediation re-review — gate passed, specs to reviewed
- docs/reviews/002-post-remediation-review.md: verifies all 14 review-001 findings landed faithfully (sibling-source re-verification + gix-transport async_trait(?Send) check + four-config/MSRV probes), records the eight residual findings (R-1..R-8) and their resolutions (ADR-018 + doc batch) - README lifecycle: draft→reviewed allows properly-tracked non-circular OQ deferrals (release-timing OQ-03 no longer blocks the transition) — R-7 - overview/transport/backend/doors/open-questions: frontmatter flipped to reviewed, timestamps refreshed; ADR-018 added to all ADR tables and the OQ-03 freeze-inventory narrative Phase-1 gate verdict: decomposition may begin Verification: cargo doc/test/clippy/fmt clean; four feature configs + MSRV 1.88 check/clippy clean
This commit is contained in:
1 parent
666abd1da4
commit
18106f461c
5 files changed
+342
-30
No files matched your search
+23
-19
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-09-25
|
||||
last_updated: 2026-09-30
|
||||
---
|
||||
|
||||
# alkgit Architecture
|
||||
@@ -16,29 +16,31 @@ to a POC finding or research doc, or is flagged as an open question.
|
||||
Phase 1, architecture committed to the pure-protocol-crate shape (ADR-010;
|
||||
OQ-09 resolved). POC-1/2/3 validated the git protocol half end-to-end
|
||||
against real git 2.43. Previous cycles settled the auth/backend theme
|
||||
(ADR-011, ADR-012). This cycle settled the wire surface against
|
||||
(ADR-011, ADR-012). Past cycles settled the wire surface against
|
||||
real-client captures: the receive-pack push state machine (ADR-013,
|
||||
OQ-04) and the V2 multi-round negotiation ack loop (ADR-014, OQ-02). All
|
||||
wire-layer design is now capture-grounded; the remaining open questions
|
||||
are the publish-freeze timing (OQ-03, a release decision), sha256
|
||||
policy (OQ-05, deferred on ecosystem need), and the grant-key identity
|
||||
namespace (OQ-16, deferred on the first cross-assembly deployment —
|
||||
blocks nothing in v1). ADR-015 resolved
|
||||
review 001's A-1 (the repo-op gate) with the `manage` grant tier; ADR-016
|
||||
resolved its A-3 (the native session preamble — `{repo, service}`
|
||||
open-op params, the git-daemon request line on the direct path, and the
|
||||
service dimension in the session tuple); ADR-017 resolved its A-5 (the
|
||||
consumer half: `GitSession` is a real typed fetch/push client in v1 —
|
||||
the direct-connection primitive for the p2p replicator deployment).
|
||||
wire-layer design is now capture-grounded. Reviews 001 and 002 have run;
|
||||
all findings from both are resolved, and decomposition into
|
||||
implementation tasks may begin (see the lifecycle gate note in the
|
||||
Document Lifecycle section). Review 001's resolution produced ADR-015
|
||||
(the repo-op gate, `manage` grant tier), ADR-016 (the native session
|
||||
preamble — `{repo, service}` open-op params, the git-daemon request
|
||||
line on the direct path, and the service dimension in the session
|
||||
tuple), and ADR-017 (the consumer half: `GitSession` is a real typed
|
||||
fetch/push client in v1 — the direct-connection primitive for the p2p
|
||||
replicator deployment). Review 002's resolution produced ADR-018 (the
|
||||
object-storage trait signatures and the `StorageError` model — the last
|
||||
unpinned backend-seam shapes) plus the op-surface pins in backend.md
|
||||
(update PATCH semantics, repo-id grammar, the `already_exists` posture).
|
||||
|
||||
## Architecture Documents
|
||||
|
||||
| Doc | Area | Status |
|
||||
|---|---|---|
|
||||
| [overview.md](overview.md) | Cross-cutting: crate shape, halves, security invariants | draft |
|
||||
| [transport.md](transport.md) | Wire layer: substrates, V2 state machines, upload/receive-pack | draft |
|
||||
| [backend.md](backend.md) | Backend traits + feature-gated gix implementation | draft |
|
||||
| [doors.md](doors.md) | Door mappings: alkhttp `git` feature, alkssh requirement, native path | draft |
|
||||
| [overview.md](overview.md) | Cross-cutting: crate shape, halves, security invariants | reviewed |
|
||||
| [transport.md](transport.md) | Wire layer: substrates, V2 state machines, upload/receive-pack | reviewed |
|
||||
| [backend.md](backend.md) | Backend traits + feature-gated gix implementation | reviewed |
|
||||
| [doors.md](doors.md) | Door mappings: alkhttp `git` feature, alkssh requirement, native path | reviewed |
|
||||
| [open-questions.md](open-questions.md) | Centralized OQ tracker | — |
|
||||
|
||||
## ADRs
|
||||
@@ -62,6 +64,7 @@ the direct-connection primitive for the p2p replicator deployment).
|
||||
| [015](decisions/015-manage-grant-and-op-gate.md) | Manage grant tier + repo-op gate (admin scope OR manage grant) | Accepted |
|
||||
| [016](decisions/016-native-session-preamble.md) | Native session preamble (`{repo, service}` params, request line, service in tuple) | Accepted |
|
||||
| [017](decisions/017-consumer-half-git-session.md) | Consumer half — `GitSession` typed fetch/push client (custom alkcall Transport + gix-protocol, hand-rolled push) | Accepted |
|
||||
| [018](decisions/018-backend-trait-signatures-and-storage-error-model.md) | Backend trait signatures + storage error model (`StorageError` for traits 3–5) | Accepted |
|
||||
|
||||
## Open Questions
|
||||
|
||||
@@ -71,13 +74,14 @@ with stable OQ-IDs, priorities, and cross-references. Remaining: OQ-03
|
||||
timing), OQ-05 (sha256, deferred on ecosystem need), and OQ-16 (grant-key
|
||||
identity namespace, deferred on the first cross-assembly record-sharing
|
||||
deployment). The wire-layer
|
||||
questions (OQ-02, OQ-04) resolved this cycle with ADR-014/ADR-013.
|
||||
questions (OQ-02, OQ-04) resolved with ADR-014/ADR-013; the registry/
|
||||
op-surface questions (OQ-06/07/08) with ADR-011/012/015.
|
||||
|
||||
## Document Lifecycle
|
||||
|
||||
| Status | Meaning | Transitions |
|
||||
|---|---|---|
|
||||
| `draft` | Under active development; may change significantly | → `reviewed` when its OQs are resolved |
|
||||
| `draft` | Under active development; may change significantly | → `reviewed` when its OQs are resolved *or* every unresolved OQ is a properly-tracked deferral with a concrete non-circular blocker (the gate review's standard — review 001 finding D-1's remediation cycle and review 002 set this precedent; deferred-on-release-timing OQs like OQ-03 do not hold specs in draft) |
|
||||
| `reviewed` | Architecture final; implementation may begin; changes need review | → `stable` when implementation verified |
|
||||
| `stable` | Locked; changes require review, may warrant an ADR | → `deprecated` when superseded |
|
||||
| `deprecated` | Superseded; kept for reference | Removed when no longer referenced |
|
||||
Reference in new issue
Block a user