glm-5.2
c62a6adc7b
Governance (Tier 2):
- Advance ADR-022 and ADR-023 from Proposed to Accepted (specs already
depend on their types as source of truth)
- Amend ADR-015: mark Decision 3 and Assumption 6 as superseded by ADR-022;
update handler_identity type to CompositionAuthority
- Amend ADR-002: note handle() signature revised by ADR-007 (BiStream → Connection)
- Amend ADR-004: note 'enrich/replace' AuthContext language superseded by
ADR-011's immutability model; update to describe set_identity on Connection
- Update main README ADR table to show ADR-022/023 as Accepted
Spec-ADR consistency (Tier 3):
- Add abort_policy: AbortPolicy field to OperationContext struct (ADR-016
Decision 6 mandated this but the spec omitted it)
- Define AbortPolicy enum (AbortDependents | ContinueRunning) with Default impl
- Add abort_policy to build_root_context and LocalOperationEnv::invoke()
- Define the OperationEnv trait explicitly with invoke() and
invoke_with_policy() methods (was referenced as 'must remain a trait'
but never defined)
- Specify From<StreamError> for HandlerError impl with exact variant mapping
- Add Connection::from_quinn() / from_iroh() constructors (was referenced
as Connection::new() but never defined)
- Remove undefined CertAuthorityEntry placeholder from AuthPolicy v1 (will
be added additively when alknet-ssh lands)
- Fix config.md key-differences table: rate limits are in DynamicConfig,
not StaticConfig
Mechanical fixes (Tier 1):
- overview.md: 'closes the QUIC stream' → 'closes the connection' (stale
from pre-ADR-007 model)
- overview.md: OQ-04 entry updated from stale 'defer to implementation'
to 'resolved: static at startup'
- mnemonic-derivation.md: remove duplicate helper functions block (incomplete
first copy, complete second copy)
- ADR-003: add iroh (feature-gated) to alknet-core dependency list, added
by ADR-010
- ADR-021: fix ambiguous 'W1 drift issue from the vault review' cross-reference
- ADR-022: rephrase FromCall 'leaf locally' to 'leaf in the local registry'
- ADR-017: add error_schemas to from_call mirror list and services/schema
step (inconsistency with ADR-023)
- ADR-016: fix self-referential citation ('ADR-016 Assumption 5' → 'Assumption 5')
- Add ScopedOperationEnv::empty(), allows(), new() and
CompositionAuthority::none(), new() impl blocks (referenced but undefined)
- Add call.completed clarification for non-subscription calls
- Add services/schema leading-slash normalization note
- Crate README ADR tables: add missing ADR-013 (call), ADR-015 (core),
ADR-006 + ADR-010 (vault)
- Vault README: add consolidated 'Known Source Drift' table tracking all
four drift items (OsRng, unwrap, CURRENT_KEY_VERSION, spawn bug) in one
place, including the two previously missing from README
3.2 KiB
3.2 KiB
status, last_updated
| status | last_updated |
|---|---|
| draft | 2026-06-22-21 |
alknet-core
Core library for ALPN-based protocol dispatch. Every handler crate depends on alknet-core.
Documents
| Document | Status | Description |
|---|---|---|
| core-types.md | draft | ProtocolHandler trait, HandlerError, Connection, BiStream, StreamError |
| endpoint.md | draft | ALPN router, HandlerRegistry, accept loop, graceful shutdown |
| auth.md | draft | AuthContext, Identity, IdentityProvider, AuthToken, resolution flow |
| config.md | draft | StaticConfig, DynamicConfig, ArcSwap, ConfigReloadHandle |
Applicable ADRs
| ADR | Title | Relevance |
|---|---|---|
| 001 | ALPN-Based Protocol Dispatch | Core architectural model |
| 002 | ProtocolHandler Trait | The trait every handler implements |
| 003 | Crate Decomposition | alknet-core's position in the crate graph |
| 004 | Auth as Shared Core | IdentityProvider in core |
| 006 | ALPN String Convention | ALPN format, one-ALPN-per-connection |
| 007 | BiStream Type Definition | Connection, BiStream trait, SendStream, RecvStream |
| 009 | One-Way Door Framework | Decision classification |
| 010 | ALPN Router and Endpoint | Endpoint, HandlerRegistry, accept loop |
| 011 | AuthContext Structure | AuthContext fields and resolution flow |
| 015 | Privilege Model and Authority Context | Per-request identity on OperationContext; admin scope for config reload |
Relevant Open Questions
| OQ | Title | Status | Relevance |
|---|---|---|---|
| OQ-04 | Dynamic handler registration | resolved (start static) | HandlerRegistry is immutable at startup |
| OQ-05 | Multi-connectivity endpoint | resolved (quinn + iroh) | AlknetEndpoint supports both, both feature-gated |
| OQ-11 | Handler-level auth resolution observability | resolved | Handlers store resolved identity on Connection; two identity scopes (connection-level for observability, per-request for ACL) |
Key Design Principles
- One trait, one dispatch point:
ProtocolHandleris the only abstraction handlers implement. No StreamInterface/MessageInterface split. - ALPN does the routing: The endpoint dispatches by ALPN string. No byte-peeking, no ListenerConfig enum.
- Handlers own their wire format: Each handler manages its own protocol parsing. alknet-core provides the Connection, not the framing.
- Auth is hybrid: The endpoint provides what it can (TLS-level auth). Handlers complete what they need. AuthContext may be partial.
- WASM door preserved: BiStream is a trait, Connection is an opaque type. Core types don't assume tokio or quinn in public APIs.