alkgit/docs/architecture/decisions/017-consumer-half-git-session.md

ADR-017: The consumer half — GitSession is a real typed client in v1

Status

Accepted (resolves review 001 A-5; amends ADR-010's consumer-half sentence and resolves ADR-012 §4's deferred gix-protocol call)

Context

ADR-010 named the consumer half — "GitSession typed client with connect_direct and open_via_channels constructors … the alkcall-native primitive for replication/mirroring in the alknet rewrite" — but no document specified what it does, and review 001 (A-5, major) found the largest uncut ambiguity for decomposition: either the half is silently omitted (the headline claim unimplemented) or its scope is invented.

The review's initial reading ("thin wrapper like TtySession") does not survive the use cases. The consumer half's downstream is the alk system's two deployment targets:

1. Self-hosted git platform (the gitea-like app): stock git clients over ssh/http doors; the consumer half is not on this path.
2. The p2p github-like platform: replicators push and pull over direct alkcall connections. A replicator is a full git client — pull is wants/haves negotiation + pack application; push is V0 advertisement parsing + command/pack send + report parsing. There is no "no downstream yet" hedge here: the replicator is the named downstream, and the client protocol layer is the lower-level machinery it requires. Delegating pkt-line framing and machine state to every replicator workstream would repeat the exact mistake ADR-005 exists to prevent on the server side ("if adapters hand-roll the framing, each gets it subtly wrong" — the same principle, client side).

The manifest already carries gix-protocol and gix-transport unconditionally (ADR-012 §4 had deferred "use gix-protocol's response parsing or hand-roll the small client surface" to implementation time), so the scope question also decided what those deps were for. Source verification against the reference clone (0.87.1-equivalent) settled the build-vs-reuse split:

• gix-protocol models the fetch/ls-refs client completely: Command::{LsRefs, Fetch}, handshake(), the full negotiation state machine (gix-negotiate), and response parsing — driven by any gix_transport::client::Transport impl.
• gix-transport's client side is transport-agnostic by explicit design: client::Transport is a trait (handshake + request), built so a custom transport can plug in. A transport over an alkcall duplex stream is exactly its intended use.
• Nothing in gitoxide models the send-pack (push) client at all — a push client is hand-rolled regardless of this decision.

The client grammar is capture-grounded without new capture work: the push client's target grammar is pinned by push-captures.md (real git pushes, ADR-013's normative basis) and the fetch client's by negotiation-captures.md (ADR-014's) — the client machines speak the same grammar the captures record and ADR-013/014 serve.

Decision

GitSession is a real typed git client in v1: both constructors, the ADR-016 preamble, and ls_refs/fetch/push operations — fetch reusing gitoxide's client machinery over a custom alkcall transport, push hand-rolled to ADR-013's shapes, storage-agnostic throughout.

1. Operations, not raw access. GitSession exposes:

   • ls_refs — list remote refs (V2 ls-refs command, peel/symrefs/ ref-prefix arguments).
   • fetch — wants + optional haves/negotiation round(s) → pack. Full ack-loop negotiation (no-done rounds per ADR-014's grammar — the client side of the loop we serve); done whenever the caller has the necessary refs locally (the common replicate-everything case needs no multi-round negotiation at all).
   • push — ref updates + pack → server report (per-remote-ref ok|ng, unpack ok|ng), atomic and push-options as caller- supplied options within the ADR-013 grammar. Each operation runs to completion (or error) on the session; the duplex session persists across operations (ALK duplex — no statelessness on the native path).

2. A gix_transport::client::Transport impl over the alkcall duplex stream drives the gitoxide client. One impl, two construction modes: open_via_channels (the preamble is the open-op's {repo, service} params — the transport's handshake writes nothing; alkcall carries it) and connect_direct (the transport's handshake writes ADR-016's git-daemon request line onto the stream, then yields the response to gix-protocol::handshake). gix-protocol is activated with its async-client feature (all transitively-pinned crates share the manifest's MSRV 1.88 — verified). gix-transport's async client traits are #[async_trait(?Send)] — a session drives one operation at a time on one task; the runtime bound is stated as the design shape, matching how a replicator uses a remote (an operation per remote at a time). The manifest's two unconditional deps become honest with this ADR: this is what they were for.

3. Push is hand-rolled (gitoxide has no send-pack): a mirror of ADR-013's server shapes at the same honesty bar — parse the V0 ref advertisement (capabilities^{} sentinel for empty repos), send command lines (old/new/ref with the correct zero-id create/delete shapes), optional push-options section, pack stream, then parse the status report in both framings (sideband band-1-wrapped and bare — the same distinction ADR-013 §8 pins server-side). Pack generation is not re-implemented: the caller supplies the pack (see 5) — for a replicator using the gix feature, pack generation is the same GitPackGen-class primitive the server half uses. Recorded as a candidate for upstream gix-protocol contribution later; not a dependency of this crate's design on it.

4. Storage-agnostic: packs stream both ways; GitSession never touches an object store. fetch delivers the sideband-unwrapped pack bytes to a caller-supplied consumer (the replicator/applies it to its own odb — with the gix feature, Bundle::write_to_directory-class ingestion is available, but alkgit does not couple to it). push takes a caller-supplied pack stream + the caller-computed commands. Client-side want/have computation, ref bookkeeping, and local-merge policy are the application's; GitSession is the transport + grammar layer, not a git client policy engine (the app-level cases — remote-tracking refs, shallow policy UI, tag auto-follow — are the app's, on top).

5. No credentials in the session. Identity is established by the alkcall transport before the preamble (the session tuple's identity input, ADR-016); the preamble carries no credential material; no client-side credential helper exists (the no-secret-material invariant; alkvault handles any replication credentials at the app layer). The gix-protocol handshake's credentials callback is never wired — the alkcall paths authenticate at the transport, not at git's credentials-protocol layer.

6. Bounded like every other session. Client operations carry Limits (ADR-009): negotiation round budgets, wall-clock, max response pack size (a malicious or stalled peer server is the internet-facing threat; a hub must not stall a replicator unboundedly). Client-side breaches end the session with an error — the same fail-closed discipline as the server side.

Consequences

• Positive: the p2p replicator downstream has its primitive — a replicator task is open_via_channels/connect_direct + fetch/ push against its own storage, with no pkt-line exposure; ADR-010's producer/consumer claim becomes fully specified; the manifest deps carry purpose; client-vs-our-server integration tests are cheap (in-process, both halves in one test) — a verification surface neither the server-only design nor a real-git-only client would have; ADR-012 §4's deferred decision is resolved with the manifest unchanged.
• Negative: v1's implementation surface grows — two client machines (fetch via gitoxide integration, push hand-rolled) each need integration tests against our server half and captures against real git (for the push client's grammar fidelity to upstream behavior); the async-client feature of gix-protocol pulls its client-side tree (futures-lite, gix-negotiate, gix-credentials — MSRV-verified); the push client is a surface we own and maintain upstream-independent.
• Neutral: the consumer half is wire-layer (no feature flag — it compiles with default-features = false); ADR-012 §4's "recorded, not an architecture commitment" rider is superseded by this ADR (an architecture commitment is exactly what was missing); ADR-010's consumer-half bullet is amended in place.

References

• Review 001 A-5 (the trigger; its option (c) direction, grounded here in the two deployment use cases rather than the review's (a) recommendation), OQ-03 (the freeze inventory this ADR's public API enters)
• ADR-010 (the producer/consumer structure — consumer half now specified), ADR-016 (the preamble connect_direct/open_via_channels send), ADR-013 (the push grammar the hand-rolled client mirrors), ADR-014 (the negotiation grammar the fetch client speaks), ADR-005 (the no-hand-rolled-framing principle this ADR applies client-side), ADR-009 (bounded sessions, client-side), ADR-012 §4 (the deferred gix-protocol call this resolves; the feature-split story unchanged)
• gix-protocol 0.65 (Command::{LsRefs,Fetch}, handshake, fetch, Arguments, response parsing — async-client feature), gix-transport 0.59 (client::Transport trait + Service/Protocol — the transport-agnostic client seam; #[async_trait(?Send)] mode)
• alk-stack context: the two named downstreams (self-hosted platform app; p2p replicators with donation-based on-chain ACL/naming, off-chain git data) — vision.md is the record of the platform use cases
• doors.md §"The alkcall-native path", backend.md §public API, transport.md §public API, overview.md §crate map