docs: composability boundary + public-clone deployment anchor

- vision: 'ALPN as a service' section (core is front-door-blind; v1
  reduces to storage + ACL + protocol adapters); primary deployment
  target = public anonymous fetch, authenticated push, minimal ACL
- alk-stack: concrete composability boundary (core+transport depend on
  alkcall types only; adapters replaceable)
- AGENTS.md: convention 15 codifies the boundary

Verified: none needed (markdown only)
This commit is contained in:
glm-5.3-flash committed 2026-09-19 17:07:25 +00:00
1 parent 1df339f4ec
commit 4d3ec3cc63
3 files changed
+62 -2

No files matched your search

+37 -1
View File
@@ -45,7 +45,8 @@ is designed from day one, not retrofitted.
3. **No plaintext secrets at rest** — alkvault or nothing.
4. **Thin interfaces, one core** — http and ssh are adapters that authenticate,
resolve a repo, and hand a duplex stream to the transport layer. Policy
lives in exactly one place.
lives in exactly one place. The core never knows which front door is
talking (see "ALPN as a service" below).
5. **Honest capability advertisement** — the git protocol advertises only
what we actually serve (this is both protocol correctness and the
security pattern: promise/enforce in the same place).
@@ -75,6 +76,41 @@ is designed from day one, not retrofitted.
| `alkgit-ssh` | ssh front door (git commands over alkcall channels) |
| `alkgitd` | binary: config, assembly, TLS/ACME, serving loops |
## Composability: "ALPN as a service"
alkgit is the git member of the alk "ALPN as a service" family — alktty,
alktunnels, and alksocks (socks5) follow the same pattern, and the alknet
mono-repo is being decomposed into exactly these pieces for rewrite. The
pattern's load-bearing rule: **`alkgit-core` + `alkgit-transport` never know
which front door is talking.** The transport layer consumes (identity, repo
id, duplex stream, limits) and speaks git; everything above the stream is
the adapter's problem. That is what keeps alkgit composable for downstream
use:
- A future gitea/gitlab-like application should be able to embed
`alkgit-core` + `alkgit-transport` (or talk to `alkgitd`) and add its own
UI/issues/PR layer without forking anything here.
- The admin API is a set of alkcall ops, not an embedded web framework —
a downstream app can either use it or replace it.
- Nothing in the core may reach upward into alkhttp/alkssh concerns
(no http types, no channel types below the transport boundary).
The v1 reduction follows from this: **storage + ACL + protocol adapters**.
A simple static/template web UI for the public repo listing is explicitly
out of scope here (would be a separate downstream thing on top).
## Primary deployment target
Our own use case is the design anchor: **public self-hosted repos with
anonymous clone over http, authenticated push, no gitea-style app features
in use**. So:
- Anonymous *fetch* (clone/fetch advertisement + pack) on explicitly-public
repos is a first-class path, not an afterthought.
- Push is always authenticated, on every repo, no exceptions.
- ACL must be simple enough to reason about completely: repo visibility
(public/private) + identity-based read/write, nothing richer in v1.
## What phase 0 must still produce before phase 1
- [x] gitoxide capability + version research (`gitoxide.md`)