alkgit 0.1.0

Git smart protocol for the alk family: pkt-line substrates, protocol V2 serving (upload-pack/receive-pack), producer/consumer halves on alkcall channels, and the backend seam traits — the shipped alkstore+alkblobs composition is the alkgit-substrate crate (ADR-010/025)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# alkgit

Git smart protocol for the alk family: the producer and consumer halves
of the git smart protocol as a pure protocol crate, riding alkcall
channels on the `alk/git` ALPN.

The crate serves the wire — V2 upload-pack (advertisement, ls-refs,
the negotiation ack loop, the done round's streamed pack) and V0
receive-pack (push advertisement, the bounded packless peek, ingestion
through the seam, status reports) — and consumes it (`GitSession`, the
typed fetch/push client). It is a pure protocol crate (ADR-010, the
alktty/alktunnels template): no binary, no front doors — the alkhttp
`git`/`lfs` features and alkssh are family infrastructure
(doors.md); a downstream app embeds this crate, brings its own door
(alkcall duplex or the smart-http shapes), and supplies the backends.
The shipped alkstore + alkblobs composition is the separate
[`alkgit-substrate`](substrate/) crate (ADR-025).

## The backend seam

Everything the wire layer runs *through* — five `#[async_trait]`,
dyn-compatible traits (ADR-018) every backend implements:

| Trait | Contract |
|---|---|
| `GitRegistry` | repo id → `RepoRecord` (ADR-012 §1) |
| `GitRegistryStore` | registry writes (put/update/remove; grants ride `RepoRecord`) |
| `GitRefs` | ref listings + `apply_updates` — the single CAS home (ADR-013 §7) |
| `GitPackGen` | pack generation (wants/haves closure) + `common_haves` (the ack-loop recognition seam, ADR-014 §5) |
| `GitPackIngest` | push ingestion, the prepare/apply split (`PreparedPush`) (ADR-020 §2) |

Supporting surface: `RepoRecord` / `Visibility` / `AccessAction` +
the repo-id grammar, the error model (`RegistryError`, `StorageError`),
the budget model (`Limits` — wall clock, request bodies, refs,
negotiation rounds, haves, pack and object sizes, the packless peek
window, blocking-pool concurrency — ADR-009), and the wire shapes
(`RefLine`, `RefUpdate`, `RefOutcome`, `PushOptions`).

## Serving — the producer half

Sessions take the `AuthorizedRepo` marker by type (ADR-007 — the
resolve→authorize check is unskippable; ACL runs before any protocol
byte) and are bounded by `Limits` throughout:

```rust
use std::sync::Arc;
use tokio::sync::Semaphore;

use alkgit::{AuthorizedRepo, AccessAction, Limits, Service, serve_duplex};

// the door resolves + authorizes, then hands the marker on:
let marker = AuthorizedRepo::authorize(record, identity, AccessAction::Read)
    .expect("the check passed");

let pipeline = Arc::new(Semaphore::new(limits.max_concurrent_blocking_tasks));
serve_duplex(
    &marker, stream, Limits::default(), Service::UploadPack,
    refs, packgen, ingest, /* push_options_negotiated */ false, pipeline,
).await?;
```

On the native transport, `GitAdapter` fronts the `alk/git` ALPN
directly (it holds the same handles and emits the ADR-016 request-line
preamble discipline), and `register_openable` mounts the
`channels/git/sub` open op for channel-mediated sessions. On the
smart-http shapes, `serve_stateless_post` / `serve_stateless_advertisement`
mount the per-POST entry (one POST = one command invocation) the http
door composes — see `tests/duplex_serving.rs` and
`tests/stateless_serving.rs` for full, working assemblies.

## Consuming — the consumer half

`GitSession` is a typed git client over gix-transport's git-daemon
`Connection` on the alkcall `BiStream` compat halves (ADR-017):

```rust
let mut session = GitSession::connect_direct(
    bistream, "owner/repo", Service::UploadPack, Some("peer.alk.dev"), limits,
)?;

let refs = session.ls_refs(&LsRefsArgs::default()).await?;
let reports = session.fetch(
    vec![FetchRound { wants, haves, done: true }],
    &mut pack_sink,
).await?;
```

Push rides its own session (`Service::ReceivePack`, the hand-rolled
send-pack — commands, the caller's pack streamed raw, the typed
`PushReport` parsed in both framings).

## Status

The protocol core is at its first release; the architecture specs
(`docs/architecture/`) are the authoritative contract — the ADRs and
`transport.md` / `backend.md` pin every wire shape and trait
signature the publish froze. The substrate track (waves 6–10) lands
the shipped backend composition in `alkgit-substrate`.

## Documentation

- [Architecture docs](docs/architecture/) — the authoritative spec:
  ADRs, wire formats, and the backend contracts.
- [API docs](https://docs.rs/alkgit) — full crate documentation.
- [Changelog](CHANGELOG.md)

## License

MIT OR Apache-2.0