Files

glm-5.2 c62a6adc7b docs(architecture): resolve review #002 Tiers 1-3 — mechanical and consistency fixes

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

2026-06-22 05:46:37 +00:00

auth.md

docs(architecture): security constraints from security review

2026-06-19 06:55:54 +00:00

config.md

docs(architecture): resolve review #002 Tiers 1-3 — mechanical and consistency fixes

2026-06-22 05:46:37 +00:00

core-types.md

docs(architecture): resolve review #002 Tiers 1-3 — mechanical and consistency fixes

2026-06-22 05:46:37 +00:00

endpoint.md

docs(architecture): resolve review #002 Tiers 1-3 — mechanical and consistency fixes

2026-06-22 05:46:37 +00:00

README.md

docs(architecture): resolve review #002 Tiers 1-3 — mechanical and consistency fixes

2026-06-22 05:46:37 +00:00

README.md

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: ProtocolHandler is 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.