docs(architecture): add Phase 0 architecture specs for ALPN-as-service model

Foundational architecture documents following the SDD process:

ADRs:
- 001: ALPN-based protocol dispatch (one endpoint, ALPN negotiation)
- 002: ProtocolHandler trait (replaces StreamInterface/MessageInterface)
- 003: Crate decomposition (one crate per handler, core provides shared infra)
- 004: Auth as shared core (IdentityProvider, hybrid resolution model)
- 005: irpc as call protocol foundation
- 006: ALPN string convention and connection model (alknet/ prefix, one ALPN per connection)

Docs:
- overview.md: crate graph, shared types, ALPN registry, failure modes
- README.md: index with doc table, ADR table, lifecycle definitions
- open-questions.md: 10 OQs across 7 themes (3 resolved, 7 open)

Crate spec stubs for all 11 planned crates (alknet-core through alknet CLI).

Key decisions resolved during self-review:
- AuthContext resolution is hybrid: endpoint resolves TLS-level auth,
  handlers resolve protocol-level auth (resolves OQ-02)
- ALPN is per-connection not per-stream, corrected ADR-001 (resolves OQ-06)
- ALPN naming uses alknet/ prefix without versions (resolves OQ-03)
- HandlerError return type on ProtocolHandler trait
- alknet/secret removed from ALPN registry until OQ-08 resolved
This commit is contained in:
2026-06-15 22:14:58 +00:00
parent b5a4600d74
commit f77b515968
20 changed files with 1017 additions and 0 deletions

View File

@@ -0,0 +1,26 @@
---
status: planned
last_updated: 2026-06-15
---
# alknet-core
> **Status: Planned** — This spec has not been written yet. It will be produced as part of Phase 1 architecture work.
## Purpose
Core crate providing the `ProtocolHandler` trait, ALPN router, endpoint, `BiStream`, `AuthContext`, `IdentityProvider`, configuration types, and shared infrastructure used by all handler crates.
## Key Questions
- **OQ-01**: BiStream type definition — trait vs concrete type vs newtype
- **OQ-05**: Multi-transport endpoint — TCP, TLS, iroh support scope
## References
- [overview.md](../../overview.md)
- ADR-001: ALPN-based protocol dispatch
- ADR-002: ProtocolHandler trait
- ADR-003: Crate decomposition
- ADR-004: Auth as shared core
- ADR-006: ALPN string convention and connection model