alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash addc874667 docs(architecture): resolve OQ-06/07/08 — per-repo authz, registry backing, CRUD ops

ADR-011 (resolves OQ-08): per-repo authorization — grants live in repo
records keyed on the stable logical identity id (alkcall ADR-025,
referenced); policy is alkgit-core's authorize() function (public+read
anonymous-first-class, write always authenticated+granted); alkgit
stores no identity records; vault placement resolved as nothing to
place in v1.

ADR-012 (resolves OQ-06/OQ-07): registry backing + write surface —
GitRegistryStore write supertrait (alknet ADR-035 read/write split
shape); registry-file default (per-repo record files + in-memory
index, config-seeded, op-mutable, no gitoxide); git/repo/* CRUD ops
shipped External with scope+ownership ACL (create mints ownership and
seeds creator grants; ownership never implies git access); the
two-op-kind classification recorded (open op + call ops from one
crate, per alkcall ADR-047); recorded split trigger for a downstream
platform crate.

Doc sync: backend.md (five-trait family, feature model split,
two-op-kinds), doors.md + overview.md (authorize policy, dual-kind
crate map), open-questions.md (OQ-06/07/08 resolved), README (ADR
table, current state), oq-06 tracker task closed (resolved early).

Verification: cargo test (default + --no-default-features), clippy
-D warnings, fmt --check.

2026-09-21 16:26:59 +00:00

3.6 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-09-21

alkgit Architecture

Phase 1 (SDD) output for alkgit — the git payload service of the alk family: a pure protocol crate on alkcall channels (the alk/git ALPN), following the alktty/alktunnels template (ADR-010). Phase 0 research lives in docs/research/; every design claim here traces to a POC finding or research doc, or is flagged as an open question.

Current State

Phase 1, architecture committed to the pure-protocol-crate shape (ADR-010; OQ-09 resolved). All docs below are draft except the superseded ADRs. POC-1/2/3 validated the git protocol half end-to-end against real git 2.43. This cycle settled the auth/backend theme: per-repo authorization (ADR-011, OQ-08), registry backing + write surface + CRUD ops (ADR-012, OQ-06/OQ-07). The remaining design work is the receive-pack state machine (OQ-04) and V2 multi-round negotiation (OQ-02).

Architecture Documents

Doc	Area	Status
overview.md	Cross-cutting: crate shape, halves, security invariants	draft
transport.md	Wire layer: substrates, V2 state machines, upload/receive-pack	draft
backend.md	Backend traits + feature-gated gix implementation	draft
doors.md	Door mappings: alkhttp `git` feature, alkssh requirement, native path	draft
open-questions.md	Centralized OQ tracker	—

ADRs

ADR	Decision	Status
001	Workspace crate decomposition (5 crates)	Superseded (ADR-010)
002	Session boundary (identity, repo, stream, limits)	Accepted
003	Protocol V2-first with honest capability advertisement	Accepted
004	Pack pipeline (`data::output` gen / `data::input` ingestion)	Accepted
005	Session substrate types (duplex + stateless APIs)	Accepted
006	HTTP adapter composition (alkgit-owned router factory)	Superseded (ADR-010)
007	ACL runs before any advertisement/ref line	Accepted
008	Wire repo names are registry IDs, never paths	Accepted
009	Bounded-resources budget model	Accepted
010	Pure protocol crate (alktty/alktunnels template)	Accepted
011	Per-repo authorization (grants in records, policy in core)	Accepted
012	Registry backing, write surface, CRUD ops, feature split	Accepted

Open Questions

All unresolved questions are tracked in open-questions.md with stable OQ-IDs, priorities, and cross-references. Highest-priority open: OQ-04 (receive-pack validation). Also open: OQ-02 (multi-round negotiation), OQ-03 (publish freeze inventory), OQ-05 (sha256, deferred).

Document Lifecycle

Status	Meaning	Transitions
`draft`	Under active development; may change significantly	→ `reviewed` when its OQs are resolved
`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

3.6 KiB Raw Blame History