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-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-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: resolved — ADR-010 (pure protocol crate, the alktty/ alktunnels template): single alkgit crate, producer/consumer halves, backend traits with feature-gated gix, no doors, no binary; ALPN alk/git; http mounting → alkhttp git feature; git-over-ssh → alkssh (russh scaffolding dropped); the monorepo/binary framing was an init-agent artifact (vision amended).
• Resolution: [decisions/010-pure-protocol-crate.md]. All five sub-decisions recorded there (ssh deletion, http home, crate granularity, backend-trait surface, binary fate).
• Cross-references: ADR-001/006 (superseded), OQ-01, OQ-03, OQ-08, doors.md, backend.md, overview.md

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

• Origin: user session question (OQ-01, resolved 2026-09-21)
• Status: resolved (subsumed by OQ-09/ADR-010) — the smart-http stateless substrate stays in alkgit (IO-abstract); the http mounting (routes, content types, with_extra_routes wiring) becomes an alkhttp git feature published after alkgit's first publish. The ADR-006 router-factory shape is superseded; the alkhttp-side feature is the outcome.
• Cross-references: ADR-006 (superseded), ADR-010, doors.md

OQ-03: Downstream embedding surface (what "embeds alkgit" means concretely)

• Origin: [overview.md], [transport.md], vision §"ALPN as a service"
• Status: partially resolved — the shape is settled (ADR-010): embedding = one crate + backend traits (own storage via default-features = false, or the gix feature) + optional door features. What remains deferred is the publish-time API freeze itself: which type/feature names are pinned at first crates.io publish.
• Door type: one-way (API freeze is registry-visible to dependents)
• Priority: medium
• Impacts: blocks the first publish only, not implementation.
• Blocked on: first-publish timing (a release decision, not an architecture question). The API surface inventory lives in backend.md §public API and transport.md §public API.
• Cross-references: ADR-010, ADR-002, backend.md, transport.md

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, backend.md §"The trait family" (GitRefs), doors.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: Registry identity space + vault placement (narrowed)

• Origin: [overview.md], [doors.md], [backend.md]; originally "identity sources per front door"
• Status: open — narrowed by ADR-010. Door auth mechanics (http token handling, ssh keys) belong to the door crates; what remains for alkgit is: the identity model the GitRegistry knows (what an identity is, what identity records exist, whether they live in the same metadata store as repo records — OQ-06's field list may grow), and where credential material lives (alkvault; metadata holds references only).
• Door type: two-way
• Priority: high
• Impacts: blocks backend.md's registry trait field list finalizing; blocks the admin-ops shapes (OQ-07).
• Resolution path: one focused session on the registry identity model
  • alkvault placement.
• Cross-references: ADR-007, ADR-010, OQ-06, OQ-07, backend.md §GitRegistry, doors.md

Theme: storage / metadata

OQ-06: Registry/metadata backing store (gix feature)

• Origin: [backend.md] (was storage.md), ADR-008
• Status: deferred(scope)
• Door type: two-way (backing choice is swappable behind the GitRegistry trait)
• Priority: high for the gix feature's default story, but choice deferrable because the trait boundary is what matters
• Impacts: blocks backend.md's gix-feature registry impl finalizing; does NOT block the wire layer (it codes against the trait).
• Blocked on: concrete metadata-scale requirements (how many repos, what metadata fields beyond id/root/visibility/ACL scope, whether identity records join — OQ-08's output, whether 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, ADR-010, backend.md §"The trait family" (GitRegistry), OQ-08 (whose identity-records question may extend this store's field list)

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

• Origin: [overview.md], alk-stack.md §"The gitea lesson"
• Status: open — rescope note (ADR-010): there is no alkgit binary, so there is no alkgit-owned admin surface. The question narrows to whether the gix feature's GitRegistry implementation ships with any management ops (repo create/delete, visibility, ACL grant) as reusable alkcall ops, or whether registry mutation is entirely downstream assembly work. If shipped, they are Visibility::Internal alkcall ops over the assembler's admin listener — never the git traffic surface.
• Priority: medium
• Impacts: blocks the gix feature's registry impl scope; OQ-08's identity model determines the op shapes.
• Resolution path: decide alongside OQ-08 (one session can settle both).
• Cross-references: ADR-007, ADR-010, OQ-08, backend.md §"The trait family" (GitRegistry)