glm-5.3-flash
8f73da5d12
Architecture documentation structure per sdd_process phase 1: - README index (doc table, ADR table, lifecycle), overview with crate map, dependency rules, and security invariants - Component specs: storage, transport, http, ssh, alkgitd (all draft) - ADRs 001-009: crate decomposition, front-door-blind core, V2-first protocol, pack pipeline (data::output generation / data::input ingestion), session substrate types, http adapter composition (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo identity, bounded-resources budgets - open-questions.md: OQ-01..08 with two deferred(scope), one deferred(unclear), door-type definitions, blocker tracker tasks in tasks/architecture/ - v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd; alkcall channels stay the internal substrate (OQ-03 partially resolved) Two review rounds (fresh-context subagent): 4 critical + 17 warnings fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in round two. All ADR/OQ cross-references verified resolving.
178 lines
8.4 KiB
Markdown
178 lines
8.4 KiB
Markdown
---
|
|
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-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 |