glm-5.3-flash
c4b9c53674
Resolves review 001 finding A-1 (critical): ADR-012 §3's "scope
git:admin OR ownership" gate is not expressible in alkcall's
AccessControl (AND-composition). Resolution is the review's option (a)
shape with the OR-term generalized: the per-repo grant action set gains
manage, authorize(record, identity, read|write|manage) becomes the
single policy function for git access and repo administration, and the
delete/update/get gate is admin scope OR manage grant (handler-side,
generic FORBIDDEN, unknown-repo = unauthorized per ADR-008). Repo
create seeds the creator's {read, write, manage} grants —
administration is grantable, so collaborators/bots/app-compiled roles
work without global scopes. Ownership stays as alkcall spawn-tracking
(mint at create unchanged); "ownership never implies git access" is
superseded.
- ADR-015 (new): manage grant tier, op gate, flat-grants-as-replication-
substrate, opaque grant-key rule
- ADR-011: action set + policy domain amended, references updated
- ADR-012 §3: gate table replaced, two-tier paragraph superseded
- backend.md/doors.md/overview.md: gate + grant restatements, ADR tables
- OQ-16 (new, deferred(scope)): grant-key identity namespace —
globally-comparable ids for cross-assembly/replicator grant state;
tracker task tasks/architecture/oq-16-grant-identity-namespace.md
- review 001: A-1 marked resolved (ADR-015)
- vision.md: supersession notes (Internal-ops framing, v1 grant set)
Verification: cargo test, clippy -D warnings, fmt --check, doc --no-deps
all clean.
76 lines
4.5 KiB
Markdown
76 lines
4.5 KiB
Markdown
---
|
|
status: draft
|
|
last_updated: 2026-09-25
|
|
---
|
|
|
|
# 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/](../research/README.md); 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). 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
|
|
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.
|
|
|
|
## 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 |
|
|
| [open-questions.md](open-questions.md) | Centralized OQ tracker | — |
|
|
|
|
## ADRs
|
|
|
|
| ADR | Decision | Status |
|
|
|---|---|---|
|
|
| [001](decisions/001-crate-decomposition.md) | Workspace crate decomposition (5 crates) | Superseded (ADR-010) |
|
|
| [002](decisions/002-front-door-blind-core.md) | Session boundary (identity, repo, stream, limits) | Accepted |
|
|
| [003](decisions/003-protocol-v2-first.md) | Protocol V2-first with honest capability advertisement | Accepted |
|
|
| [004](decisions/004-pack-pipeline.md) | Pack pipeline (`data::output` gen / `data::input` ingestion) | Accepted |
|
|
| [005](decisions/005-session-substrate-types.md) | Session substrate types (duplex + stateless APIs) | Accepted |
|
|
| [006](decisions/006-http-adapter-composition.md) | HTTP adapter composition (alkgit-owned router factory) | Superseded (ADR-010) |
|
|
| [007](decisions/007-acl-before-advertisement.md) | ACL runs before any advertisement/ref line | Accepted |
|
|
| [008](decisions/008-registry-resolved-repo-identity.md) | Wire repo names are registry IDs, never paths | Accepted |
|
|
| [009](decisions/009-bounded-resources-budget.md) | Bounded-resources budget model | Accepted |
|
|
| [010](decisions/010-pure-protocol-crate.md) | Pure protocol crate (alktty/alktunnels template) | Accepted |
|
|
| [011](decisions/011-per-repo-authorization.md) | Per-repo authorization (grants in records, policy in core) | Accepted |
|
|
| [012](decisions/012-registry-backing-and-ops.md) | Registry backing, write surface, CRUD ops, feature split | Accepted |
|
|
| [013](decisions/013-receive-pack-state-machine.md) | receive-pack state machine (V0-framed push, thin-pack, unpack-first CAS) | Accepted |
|
|
| [014](decisions/014-v2-negotiation-ack-loop.md) | V2 negotiation ack loop (no `ready`, wait-for-done stays) | Accepted |
|
|
| [015](decisions/015-manage-grant-and-op-gate.md) | Manage grant tier + repo-op gate (admin scope OR manage grant) | Accepted |
|
|
|
|
## Open Questions
|
|
|
|
All unresolved questions are tracked in [open-questions.md](open-questions.md)
|
|
with stable OQ-IDs, priorities, and cross-references. Remaining: OQ-03
|
|
(publish freeze inventory — partially resolved, blocked on first-publish
|
|
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.
|
|
|
|
## 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 | |