alkgit/docs/architecture/open-questions.md

---
status: draft
last_updated: 2026-09-21
---

# Open Questions

All unresolved architecture questions, centrally tracked. Status values:
`open` (needs resolution now), `partially resolved` (decision made but a
narrower question remains — named in the entry), `resolved` (decision
made, ADR recorded), `deferred(scope)` (waiting on external information —
blocked-on condition stated), `deferred(unclear)` (pieces exist, shape
needs investigation). See `docs/sdd_process.md` for the deferral protocol
(blocker tasks in `tasks/architecture/`).

**Door type** classifies reversal cost: `one-way` decisions are
expensive/impossible to reverse once published (wire formats, public API
shapes); `two-way` decisions can be revisited while nothing is published.
Door type does not change urgency — all decisions here need resolution
when their impacts say so; it records how careful the resolution must be.

## Deferred / Blocked summary

| OQ | Status | Blocked on / investigation |
|---|---|---|
| OQ-09 | open (discussion) | slim-crate model: doors as family infrastructure; subsumes OQ-01 if Slim-B |
| OQ-04 | deferred(unclear) | receive-pack walkthrough (capabilities, shallow, thin-pack, CAS timing) + push POC |
| OQ-06 | deferred(scope) | concrete metadata-scale requirements (feeders: OQ-07, OQ-08 outputs) |
| OQ-05 | deferred(scope) | ecosystem need for sha256 |

## Theme: composition / crate shapes

### OQ-01: HTTP adapter home and composability (alkhttp `git` feature vs alkgit-owned factory)

- **Origin**: [overview.md], [http.md], user session question
- **Status**: partially resolved — ADR-006 written **Proposed** with
  Option A (alkgit-owned router factory) as the recommendation and the
  alkhttp-side sugar as a recorded escape hatch. Needs user review.
- **Door type**: two-way (adapter shape can change before anything is
  published)
- **Priority**: high
- **Impacts**: blocks finalizing http.md and ADR-006; small effect on
  downstream ergonomics.
- **Resolution path**: user reviews ADR-006; accept → ADR becomes
  Accepted; or choose Option B (alkhttp feature) → ADR reworked.
- **Cross-references**: ADR-001, ADR-006, http.md

### OQ-03: Downstream embedding surface (what "embeds core + transport" means concretely)

- **Origin**: [overview.md], [transport.md], [ssh.md], vision §ALPN as a
  service
- **Status**: partially resolved — v1 ssh-door decision made: alkgitd
  terminates SSH via russh for stock git clients (ssh.md); what remains
  deferred is whether a *pure-alkcall-channels* ssh variant and a
  russh-flavored adapter are exported for embedders.
- **Door type**: two-way
- **Priority**: medium
- **Impacts**: blocks nothing in v1 (alkgitd is the only consumer); shapes
  the crates' public API freeze before publish.
- **Blocked on**: a concrete downstream embedder use case (e.g. a real
  gitea-like app or test harness wanting to serve git) — until one
  exists, the embedding seam is designed by example (alkgitd) only.
  Tracker task: `tasks/architecture/oq-03-embedder.md`.
- **Cross-references**: ADR-001, ADR-002, transport.md §public API,
  ssh.md §russh

## Theme: transport / protocol

### OQ-02: V2 multi-round negotiation (ack/NAK logic, `wait-for-done` retirement)

- **Origin**: [transport.md], poc2-findings §"does NOT settle"
- **Status**: open
- **Priority**: medium (full-closure-on-`done` works; multi-round is an
  efficiency feature, not correctness)
- **Impacts**: fetch efficiency on repos with large shared history;
  capability advertisement text (`fetch=` value).
- **Resolution path**: design the ack loop (rounds budget per ADR-009)
  when transport implementation begins; POC-2's generator is
  negotiation-agnostic already.
- **Cross-references**: ADR-003, ADR-004, ADR-009, transport.md §fetch

### OQ-04: receive-pack (push) — validation gap

- **Origin**: [transport.md], poc3-findings §"does NOT settle"
- **Status**: deferred(unclear)
- **Door type**: two-way
- **Priority**: high
- **Impacts**: blocks receive-pack implementation tasks; push is the
  always-authenticated half of the wire surface.
- **Investigation**: the pieces are decided (POC-2: pack ingestion via
  `gix-pack::data::input` with `streaming-input` (ADR-004); `gix-ref`
  transaction CAS; fsck via `gix-fsck`; POC-3: request bodies stream). The shape to
  work through: the full push state machine —
  (a) the receive-pack **capability advertisement set**
  (`report-status`/`report-status-v2`, `delete-refs`, `push-options`,
  `atomic`, `side-band-64k`, `object-format`) under the honest-advertisement
  invariant (ADR-003); (b) request-line parsing
  (`<old> <new> <ref>` + shallow lines policy — expected resolution:
  **reject shallow on push for v1**, mirroring fetch's decline-by-omission
  in ADR-003, so depth semantics stay symmetric; confirm against real
  `git push` behavior);
  (c) thin-pack acceptance on push (client packs may be thin; accepting
  implies base-object availability requirements); (d) pack ingestion
  mid-stream; (e) CAS validation timing (before vs after pack index);
  (f) status report (`unpack ok|ng` + per-ref lines); (g) the
  receive-pack version/framing surface over http (which framing `git push`
  uses against us; ADR-003's V2 decision covers fetch only). Method:
  walkthrough against real `git push` captures, then a small POC if the
  ingestion composition is not obvious from POC-2's findings. Tracker
  task: `tasks/architecture/oq-04-receive-pack.md`.
- **Cross-references**: ADR-003, ADR-004, ADR-009, transport.md
  §receive-pack, storage.md §ref transactions, http.md

### OQ-05: sha256 support policy

- **Origin**: [transport.md], git-protocol.md §"Open items"
- **Status**: deferred(scope)
- **Door type**: two-way
- **Priority**: low
- **Impacts**: none for v1 (sha1 pinned); feature-flag passthrough
  compiles but is untested end-to-end.
- **Blocked on**: ecosystem need (a real client/repo requiring sha256) or
  upstream gix sha256 maturity; POC-2 left the pipeline hash-generic but
  untested. Tracker task: `tasks/architecture/oq-05-sha256.md`.
- **Cross-references**: ADR-003, ADR-004

## Theme: identity / auth

### OQ-08: Identity sources per front door (v1 auth mechanics)

- **Origin**: [overview.md], [http.md], [ssh.md], [alkgitd.md]
- **Status**: open
- **Priority**: high
- **Impacts**: blocks http.md and ssh.md auth sections finalizing; blocks
  the identity-extractor callback design in ADR-006's seam; blocks
  alkgitd config schema and the OQ-07 admin op shapes.
- **Resolution path**: decide per door — http (bearer token? basic? via
  alkvault-stored credentials), ssh (russh-terminated public-key auth →
  alkgit identity mapping per ssh.md), and which identities exist in
  v1's registry — including whether identity records live in the same
  metadata store as repo records (OQ-06's field list may grow for this).
- **Cross-references**: ADR-006, ADR-007, OQ-06 (metadata backing where
  identity records live),
  http.md §auth, ssh.md §identity, alkgitd.md, OQ-07

## Theme: storage / metadata

### OQ-06: Registry/metadata backing store

- **Origin**: [storage.md], ADR-008
- **Status**: deferred(scope)
- **Door type**: two-way (backing choice is swappable behind the core
  trait)
- **Priority**: high for v1 config story, but choice deferrable because
  the trait boundary is what matters
- **Impacts**: blocks storage.md's registry section finalizing and
  alkgitd's config schema; does NOT block core/transport work (they code
  against the trait).
- **Blocked on**: concrete metadata-scale requirements (how many repos,
  what metadata fields beyond id/root/visibility/ACL scope, whether
  alkcall-hub integration lands in v1). A config-file or embedded-store
  decision without those inputs would be a guess. Tracker task:
  `tasks/architecture/oq-06-metadata-backing.md`.
- **Cross-references**: ADR-008, storage.md §registry, alkgitd.md §config,
  OQ-08 (whose identity-records question may extend this store's field
  list)

### OQ-07: Admin API operation set (v1 scope)

- **Origin**: [overview.md], [alkgitd.md], alk-stack.md §"The gitea lesson"
- **Status**: open
- **Priority**: medium
- **Impacts**: blocks the admin-ops inventory (repo create/delete,
  visibility set, ACL grant/revoke, user/identity management — if v1 has
  users at all, which is OQ-08 territory). Deliberately small: everything
  is `Visibility::Internal` alkcall ops over the admin surface.
- **Resolution path**: one dedicated session once OQ-08's identity model
  exists (the ops' shapes depend on what identities/credentials mean).
- **Cross-references**: ADR-007, OQ-08, alkgitd.md §admin API

### OQ-09: Slim-crate model — doors as family infrastructure, git as a payload service

- **Origin**: user session (2026-09-21); ADR-006, ADR-001, ssh.md
- **Status**: open — under discussion, no commitment
- **Door type**: one-way once anything is published (crate deletion and
  feature-promotion are wire/registry-visible to dependents)
- **Priority**: high
- **Impacts**: blocks ADR-006 finalization (OQ-01 is subsumed by this if
  Slim-B is chosen); reshapes ADR-001 (crate set), ssh.md (delete or
  defer), OQ-08 (narrows: git consumes door identity), alkgitd's assembly
  surface, and publish sequencing (alkhttp `git` feature requires
  alkgit-transport on crates.io first).
- **Context**: the alk family shares doors — alkhttp exists, alkssh is
  planned (after alksocks), alknet rewrite coming. Doors wrap alkcall
  producer/consumer in their wire protocol; services (git, tty, tunnels,
  socks) are payloads doors optionally expose. git should be a service
  exposed by downstream consumers rather than owning its own doors:
  candidate end-state is protocol crates (core + transport) + http adapter
  either in alkgit or as an alkhttp `git` feature (Slim-B) or kept as
  alkgit-http (Slim-A). alkssh is where git-over-ssh belongs when it
  exists — the temporary russh-in-alkgitd decision (ssh.md) is scaffolding
  either way.
- **Sub-decisions**: (1) delete `alkgit-ssh` now and defer git-over-ssh to
  alkssh, or keep temporary russh scaffolding in alkgitd until then
  (hinges on whether our deployment needs git-over-ssh before alkssh
  lands); (2) http adapter home — Slim-A (keep alkgit-http, ADR-006
  Option A as written) vs Slim-B (alkhttp 0.6 `git` feature; requires
  alkgit published first); (3) if Slim-B, whether `alkgitd` keeps an
  internal factory consumption path or consumes the alkhttp feature like
  any downstream.
- **Resolution path**: dedicated discussion session; decide the three
  sub-decisions, then rewrite ADR-001/006 and ssh.md (a new ADR superseding
  the affected parts, per ADR stability rules), and re-scope OQ-08.
- **Cross-references**: OQ-01, OQ-03, OQ-08, ADR-001, ADR-006, ssh.md,
  alkgitd.md