alkgit/docs/architecture/open-questions.md

status, last_updated

status	last_updated
draft	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-states: Slim-A — keep alkgit-http factory, 5-crate layout, ADR-006 Option A as written; Slim-B — protocol crates + alkhttp git feature for smart-http (requires alkgit published first); Option C (pure protocol crate) — follow the alktty/alktunnels template exactly: single alkgit crate, producer half (GitAdapter for alk/git ALPN + channels register_openable, POC-1 substrate), consumer half (typed GitSession — the replication/mirroring primitive), backend traits (registry/refs/pack-gen/pack-ingest) with the gix implementation feature-gated (mirrors alktty's local; NOT a wasm goal, the cleanliness just falls out), smart-http stateless substrate stays in-crate while the http mounting becomes alkhttp's git feature. No binary; assembly is downstream's. Consequences to record on commitment: vision.md's "single-binary git server" framing is amended (assembly belongs to downstream consumers); ADR-001/006 superseded by a new ADR; ssh.md defers entirely to alkssh (the temporary russh scaffolding decision is dropped, not shipped); OQ-08 narrows to the registry identity space + vault placement.
• 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) crate granularity — keep core+transport split (embedders wanting storage-only) vs merge into one alkgit (Option C's shape); (4) under Option C, backend-trait surface: full family (registry, refs, pack-gen, pack-ingest) vs minimal (pack + registry, refs ride the registry trait); (5) alkgitd's fate — deleted, or kept as a thin reference assembly once doors exist to assemble against.
• 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