---
status: draft
last_updated: 2026-09-29
---

# Backend traits: the storage seam

## What this is

The payload side of the protocol crate: the traits a service deployer
implements (or consumes via the feature-gated gix implementation) so the
git protocol can talk to storage. Per ADR-010 this mirrors alktty's
`TtyBackend` pattern — traits in-crate, real implementation behind a
feature. Unlike alktunnels (no backend trait), git needs the seam: pack
generation/ingestion is too heavy to hard-wire.

## The trait family (ADR-010 sub-decision 4, ADR-011/012)

Five traits, kept small and orthogonal — the protocol crate never sees
gix types:

1. **`GitRegistry`** — repo id → `RepoRecord` (storage root, visibility,
   grants keyed on the stable logical identity id, action set
   `{read, write, manage}` — ADR-011, ADR-015). Async
   `resolve`; the authoritative mapping (ADR-008); resolution failure is
   indistinguishable from authorization failure (ADR-007). Authorization
   is alkgit-core's policy function evaluated on the record (data in the
   backend, policy in core — an embedder with a foreign permission
   system maps its ACL into grants at resolve time).
2. **`GitRegistryStore: GitRegistry`** — the write supertrait
   (`put_repo`/`update_repo`/`remove_repo`; alknet ADR-035's read/write
   split shape). The `git/repo/*` ops wrap it (ADR-012 §3). Grants ride
   the record, so grant mutation is `update_repo` (convenience wrappers
   additive later, two-way) — which is also the app's promotion path
   (roles/teams compile to flat grants upstream; ADR-015 §6) and the
   shape a future replication sync would write through (ADR-015 §8).
3. **`GitRefs`** — listing for advertisement (refs + peeled tags + symref
   targets, the ls-refs response data) and ref transactions (CAS apply
   for receive-pack, name validation per git ref rules + reserved-
   namespace deny-list).
4. **`GitPackGen`** — (repo, wants, haves, limits) → streaming pack
   (`io::Write` consumer), plus `common_haves(repo, haves) -> recognized
   subset` for the negotiation ack loop (a have is recognized iff it
   exists in the object store and is a commit — the honest boundary:
   never ack what we cannot subtract; ADR-014). Negotiation-agnostic
   generation. Missing objects abort with an error, never a broken pack
   (ADR-004).
5. **`GitPackIngest`** — client pack stream → indexed pack + fsck/
   connectivity report. Thin-pack bases resolve from the server's own odb
   (push sends thin packs by default — ADR-013 §5); the pack lands with a
   `.keep` guard; missing objects → `unpack ng`. It *prepares* the
   validated ref updates; the transaction itself is applied by `GitRefs`
   (single CAS home — ingest validates, refs commits; one transaction per
   push is what makes `atomic` correct — ADR-013 §7). The prepare binding
   carries `push_options: Option<&PushOptions>` (ADR-013 §11, review 001
   N-4): the parsed per-push metadata, present only when `push-options`
   was negotiated — `None` until the config gate opens; alkgit parses and
   forwards the option pairs verbatim, never interprets them (their
   meaning is the caller's policy domain). Budgeted (ADR-009
   max pack size); the impl runs its blocking work off the async
   executor (concurrency model below).

Minimal-vs-full was the open sub-question; resolved as **full family** —
each trait is one or two methods plus types, and collapsing them (e.g.
refs into the registry) would force one impl block per downstream where
independent seams are cheaper to satisfy. The `gix` feature implements
the three object-storage traits (3–5: `GitRefs`, `GitPackGen`,
`GitPackIngest`); a downstream with its own object store implements 3–5
and reuses 1–2 (`GitRegistry`/`GitRegistryStore`), or none of it.

## Feature model (ADR-012 §4, amends ADR-010's single-`gix` story)

Two independent seams, two default-on features:

| Feature | Contents | gitoxide |
|---|---|---|
| `gix` | `GitRefs`/`GitPackGen`/`GitPackIngest` impls — the local-disk object-storage engine (odb/pack/ref/object/fsck components) | yes |
| `registry-file` | `GitRegistry`/`GitRegistryStore` default impl (per-repo record files + in-memory index, config-seeded, op-mutable, atomic writes) | no |

- `default-features = false` — wire/protocol layer only (an embedder
  brings its own backends). Both features default-on (batteries
  included); they are independent seams — DB-registry + gix-engine and
  S3-storage + simple-registry combinations both exist downstream.
- The `gix` **facade crate is not a dependency** (ADR-012 §4): the
  backends drive `gix-odb`/`gix-pack`/`gix-ref` at the component level
  (POC-2's shape); repo opening from a registry-resolved root is
  `gix-discover` + `gix-odb::Store::at`. Verified at implementation.
- The registry-file store needs no gitoxide; persistence adapters
  (SQLite et al.) are future, separate, additive — ADR-012 §2.
- Hash: `sha1` pinned (the compile-time-rejected invariant from
  `docs/research/gitoxide.md`); `sha256` passthrough feature (OQ-05
  policy unchanged).
- Encodes the POC-2 prerequisites by construction: odb handle sharing
  (`Arc<Store>` shared, per-session handles, `prevent_pack_unload()` +
  `ignore_replacements = true`), generation on blocking threads,
  O(counts) memory, missing-objects abort.
- Received-pack ingestion via `gix-pack::Bundle::write_to_directory_eagerly`
  (`streaming-input`, thin-base lookup) + `gix-fsck` + `gix-ref`
  transactions with `PreviousValue::MustExistAndMatch` CAS (ADR-004, ADR-013
  — the full push state machine is decided there).

## Concurrency model

- `gix` structures: `parking_lot` short-held locks; per-session handles
  and `spawn_blocking` live inside the gix impls (POC-2's shape: store
  shared, handle per session, generation on blocking threads).
- Poisoned locks: `unwrap_or_else(|e| e.into_inner())` (convention 2).
- **Trait execution model** (review 001 A-6): all five traits are
  `#[async_trait]` — `Send + Sync`, dyn-compatible (E0038 forbids bare
  `async fn`), signatures per ADR-012 §1. `GitRegistry::resolve` is
  async (one call per session/request, before the first protocol byte —
  ADR-011 §6); no sync-hot-path constraint exists here, unlike alkcall's
  accept loop. The execution model the signatures imply:
  - **The wire layer enforces the pipeline-concurrency budget itself**
    (ADR-009's "max concurrent blocking pipeline tasks" — a permit
    acquired in the wire layer around each `GitPackGen`/`GitPackIngest`
    call; the admission point of "enforced at assembly/acceptance
    time"). The wire layer is backend-trait-only (ADR-010) and knows
    nothing of stores, handles, or threads — so the permit, not
    `spawn_blocking`, is its entire concurrency contract.
  - **Implementations must not block the async executor** and own their
    internal threading: the gix impls run pack generation/ingestion on
    `spawn_blocking` with the owned handle moved in *inside the trait
    impl* (POC-2's shape, restated at its true layer — it is the impl's
    internal structure, invisible from the wire layer).
  - The traits are async so an embedder whose storage is async (DB
    registries, network object stores) implements them natively; the
    gix impl's blocking work is an internal detail, not part of the
    seam.

## Public API surface

Crate-root re-exports (the alktty pattern): backend traits + types
(including `RepoRecord`, `AccessAction`, the `authorize` policy
function, the authorized-repo marker type (the door constructs it only
after the ADR-007 check passes — session tuples carry it, transport.md
substrate layer), and the `git/repo/*` op spec+handler pairs),
`GitAdapter`/`register_openable` (producer), `GitSession` (consumer —
the ADR-017 typed client: `ls_refs`/`fetch`/`push`), substrate
types, `Limits`, protocol error enums; feature types (`GixBackend`
family under `gix`, the file registry under `registry-file`) exported
under their features. The embedder-facing freeze point remains OQ-03
(narrowed: it is now this crate's own publish).

## The two op kinds (ADR-012 §3, the classification)

alkgit ships both alkcall op kinds from one crate — the first family
payload to do so (alktty/alktunnels: open ops only; alknet-docker,
planned: call ops only):

- **Open op** (`channels/git/sub` via `register_openable`; open-op
  params `{repo, service}` — ADR-016) — the binary half: negotiation +
  service selector + ACL point (ADR-007; the service selects the
  `authorize` action, read for fetch / write for push), yields the
  duplex git session.
- **Call ops** (`git/repo/{create,delete,update,get}`) — the JSON half:
  thin `OperationSpec`+handler pairs over `Arc<dyn GitRegistryStore>`,
  `Visibility::External`, always-on (no gitoxide). `create` is gated by
  the static registry check (`required_scopes: ["git:repo:create"]`);
  `delete`/`update`/`get` carry an empty `AccessControl` and the handler
  evaluates the ADR-015 gate — scope `git:admin` OR the record's
  `manage` grant, via the `authorize` policy function, generic FORBIDDEN
  denial, unknown-repo ≡ unauthorized (ADR-008). Registered by the
  assembler wherever it wants them exposed. Managing records (op scopes)
  and git access (repo grants) are distinct sources — but the record is
  the single per-repo authz surface, and repo creation seeds the
  creator's `{read, write, manage}` grants (ADR-015).

## Registry types and schemas (review 001 N-3; the freeze-inventory draft)

The serde shapes the ops handlers and the `registry-file` store both
serialize — pinned here so the two workstreams cannot invent them
independently. These are the N-3 schemas ADR-015 chained after the
manage-grant shape: they capture the three-action grant shape (ADR-015),
the opaque grant-key rule (ADR-015 §7 / OQ-16), and the
unknown-repo ≡ unauthorized rule at the op layer (ADR-008). Draft until
first publish (additive fields have been added before publish before —
ADR-016's params, ADR-017's API); at publish they enter OQ-03's
inventory as compat surface.

### `RepoRecord` (serde shape)

```json
{
  "repo_id": "alkdev/alkgit",          // the registry id (string, non-empty)
  "storage_root": "/var/lib/alkgit/…", // server-side path, never on the wire (ADR-008)
  "visibility": "public",              // "public" | "private" (lowercase)
  "grants": {                          // identity_id (opaque string, ADR-015 §7) → grant set
    "u-7731": ["read", "write", "manage"]
  }
}
```

- `grants` values are arrays of the action strings `read` / `write` /
  `manage` (unique, lowercase; `manage` implies the lower actions per
  ADR-015 §2's monotonicity — stored sets need not be closed, the
  policy function evaluates that).
- `storage_root` is the one field that must never round-trip through an
  op response (ops return record *data*, not paths — ADR-008's never-a-
  path rule; the get-op response schema omits it, the `resolve`
  trait surface keeps it). Keys are `snake_case`, no serde renames —
  the record file IS the serde shape (ADR-012 §2's on-disk form).
- Additive-field rule: unknown fields are rejected, fail-closed, both
  on-disk (an unknown field in a stored record file is a version skew
  the operator must see, not silently dropped) and in op input schemas
  (`additionalProperties: false` — the same extension rule as
  ADR-016's open-op params; extensions replace, not accumulate, before
  publish).

### `RegistryError` (the variant set)

`thiserror` enum, five variants — every failure the trait family can
produce, no catch-all:

| Variant | Meaning | Wire mapping |
|---|---|---|
| `NotFound` | repo id unresolved | collapses with `Forbidden` to the generic denial (unknown ≡ unauthorized, ADR-008; transport.md error taxonomy) |
| `Forbidden` | gate denied (op-layer or `authorize`) | generic FORBIDDEN — same wire shape as `NotFound`, never a variant leak |
| `AlreadyExists` | create with a taken id | op-level error; still NOT disclosed as an existence oracle to non-creators — `create` responses may carry it, `resolve` never returns it |
| `Invalid` | malformed record/field (store-side validation, e.g. empty repo id, unknown action string) | op-level error with the field name |
| `Io(String)` | backing-store failure (serialized as message — not `std::io::Error`, which is not serde-stable) | session/op error, substrate-appropriate |

`Io` is the only stringly-typed variant; everything else is structural
so ops can report precise JSON errors (`{"error": "already_exists", …}`)
while the trait surface stays `Result<_, RegistryError>` per ADR-012 §1.

### `git/repo/*` op JSON schemas (request/response)

| Op | Request | Response | Errors |
|---|---|---|---|
| `git/repo/create` | `{repo_id, visibility}` — storage root assigned by the store's naming rules (ADR-012 §2); grants seeded `{read, write, manage}` for the caller (ADR-015 §4); an explicit grants field is an admin-shape extension, NOT v1 | `{repo_id, visibility}` | `already_exists`, `invalid` |
| `git/repo/delete` | `{repo_id}` | `{}` | `unauthorized` (the single wire code for unknown-repo ≡ not-authorized — N-2's collapse rule; `io`) |
| `git/repo/update` | `{repo_id, visibility?, grants?}` — both optional, full-record replace of the provided fields; grant mutation is the only grant-write path (ADR-015 §3) | `{repo_id, visibility, grants}` (post-write record, no storage root) | `unauthorized` (collapsed, N-2), `invalid`, `io` |
| `git/repo/get` | `{repo_id}` (single read; list is a v2 additive op) | `{repo_id, visibility, grants}` (no storage root — ADR-008) | `unauthorized` (collapsed, N-2), `io` |

- Error codes are the wire `code` strings in the table (snake_case,
  one namespace `git:repo:*`), each carried in the op's
  `ErrorDefinition` (alkcall ADR-016 disclosure convention — the same
  pattern alktty's `channel:open_failed` uses). The `unauthorized` code
  is the collapsed denial: both `RegistryError::NotFound` and
  `Forbidden` map to it at the op-wire boundary (unknown ≡
  unauthorized, ADR-008 + review 001 N-2), so no variant leaks an
  existence oracle; `AlreadyExists` is create-side only (the caller
  knows the id — discloseable without an oracle).
- `update`'s response echoes the post-write record so grant edits
  confirm what landed (the last-writer-race posture is ADR-012
  §Consequences, unchanged).
- All four op input schemas: `additionalProperties: false` (the
  alksocks `{}`-precedent — same fail-closed extension rule as
  ADR-016's open-op params).

## Design Decisions

| ADR | Decision | Summary |
|---|---|---|
| [004](decisions/004-pack-pipeline.md) | Pack pipeline | `data::output` gen / `data::input` ingestion |
| [007](decisions/007-acl-before-advertisement.md) | ACL first | registry returns rule inputs |
| [008](decisions/008-registry-resolved-repo-identity.md) | Repo identity | wire names are registry ids |
| [009](decisions/009-bounded-resources-budget.md) | Budgets | limits flow into gen/ingest |
| [010](decisions/010-pure-protocol-crate.md) | Pure protocol crate | traits in-crate, impls behind features |
| [011](decisions/011-per-repo-authorization.md) | Per-repo authorization | grants in records, policy in core (amended: ADR-015) |
| [012](decisions/012-registry-backing-and-ops.md) | Registry + ops | write trait, file default, CRUD ops, feature split (gate amended: ADR-015) |
| [015](decisions/015-manage-grant-and-op-gate.md) | Manage grant + op gate | `manage` tier, admin-scope-OR-manage gate, create seeds manage |
| [013](decisions/013-receive-pack-state-machine.md) | receive-pack | thin-pack ingestion, transaction CAS, report framing |
| [014](decisions/014-v2-negotiation-ack-loop.md) | Negotiation | ack loop, `common_haves` seam, no `ready` |
| [016](decisions/016-native-session-preamble.md) | Native session preamble | `{repo, service}` open-op params, request-line preamble, service in the tuple |
| [017](decisions/017-consumer-half-git-session.md) | Consumer half | `GitSession` typed client (`ls_refs`/`fetch`/`push`), custom alkcall Transport + gix-protocol, hand-rolled push |

## Open Questions

- **OQ-05**: sha256 policy (deferred(scope)).
- **OQ-03**: publish-time API freeze inventory (the op set enters it).
- OQ-04 resolved (ADR-013 — ingestion composition bound: thin-base
  lookup, `.keep` landing, transaction CAS).
- OQ-02 resolved (ADR-014 — `common_haves` ack seam added to
  `GitPackGen`).

## References

- `docs/research/gitoxide.md` (API contract notes — normative for the
  gix impl)
- `docs/research/poc2-findings.md` (generation pipeline + prerequisites)
- alktty `backend.rs`/`local` module (the trait + feature template)
- alknet ADR-033/035 (the repo/adapter + read/write-split pattern)
- ADR-010 (the structural decision), ADR-011/012 (the seam this doc
  specifies)