tasks: decompose vault, core, call crates into 28 atomic implementation tasks

Break down the three initial crates (alknet-vault, alknet-core, alknet-call)
into dependency-ordered task files for implementation agents.

Structure:
- tasks/vault/ (10 tasks) — drift fixes from ADR-025/026 refactor, review,
  spec sync. Vault is independent and can run fully in parallel with core/call.
- tasks/core/ (6 tasks) — crate init, core types, config, auth, endpoint,
  review. Core is foundational; call depends on it.
- tasks/call/ (12 tasks) — split into registry/ and protocol/ topic subdirs
  reflecting the two subsystems. CallAdapter is the merge point.

Key decisions:
- Drifts 3+9+10 grouped as one task (key-versioning-rotation) — the complete
  ADR-021 rotation feature that doesn't compile in pieces
- Reviews injected at end of each crate phase (vault, core, call)
- Vault spec-sync task removes the drift table and bumps doc status to stable
- ACME deferred in core/endpoint (noted as TODO; X509 manual certs for now)
- OperationEnv kept as a trait (load-bearing for ADR-024 layering)

Validated: 28 tasks, no cycles, 11 generations of parallel work.
Critical path runs through call (11 tasks). Vault completes by generation 4.
6 high-risk tasks identified (21%): irpc-removal, endpoint, operation-context,
operation-env, call-adapter, abort-cascade.
This commit is contained in:
2026-06-23 12:41:47 +00:00
parent 2e34590522
commit 098fd8b9b9
28 changed files with 4271 additions and 0 deletions

122
tasks/core/review-core.md Normal file
View File

@@ -0,0 +1,122 @@
---
id: core/review-core
name: Review alknet-core implementation for spec conformance and pattern consistency
status: pending
depends_on: [core/endpoint]
scope: moderate
risk: low
impact: phase
level: review
---
## Description
Review the alknet-core implementation for spec conformance, pattern
consistency, and correctness before alknet-call (which depends on core)
begins implementation. This is the quality checkpoint at the end of the core
phase.
### Review Checklist
1. **Core types conformance** (core-types.md):
- `ProtocolHandler` trait signature matches spec (alpn, handle)
- `HandlerError` has all 4 variants (ConnectionClosed, StreamError, AuthRequired, Internal)
- `Connection` has all methods, from_quinn/from_iroh feature-gated
- `Connection::set_identity` is write-once via OnceLock
- `BiStream` is a trait (AsyncRead + AsyncWrite + Send + Unpin)
- `SendStream` implements AsyncWrite, `RecvStream` implements AsyncRead
- `StreamError` has all 4 variants
- `From<StreamError> for HandlerError` impl matches spec mapping table
- `Capabilities` is non-serializable, zeroized, immutable, Clone+Send+Sync
- `Capabilities` has builder API (new, with_api_key, with_http_token, get), private fields
2. **Config conformance** (config.md):
- `StaticConfig` fields match (listen_addr, tls_identity, iroh_relay, drain_timeout)
- `TlsIdentity` has X509, RawKey, SelfSigned
- `DynamicConfig` has auth and rate_limits
- `AuthPolicy` has authorized_fingerprints (HashSet<String>), api_keys (Vec<ApiKeyEntry>)
- `ApiKeyEntry` has all 5 fields (prefix, hash, scopes, description, expires_at)
- `ConfigReloadHandle` has reload() and dynamic()
- No russh dependency (fingerprints as strings)
- No removed fields (host_key, stealth, transport_mode, listeners)
3. **Auth conformance** (auth.md):
- `AuthContext` has all 4 fields, derives Clone
- `Identity` has id, scopes, resources
- `AuthToken` has raw field
- `IdentityProvider` trait with both methods
- `ConfigIdentityProvider` reads from ArcSwap on every call
- Fingerprint resolution looks up in authorized_fingerprints
- Token resolution: alk_ prefix, hash match, expiry check
- Two identity scopes documented (connection-level vs per-request)
4. **Endpoint conformance** (endpoint.md):
- `AlknetEndpoint` has quinn/iroh (both Option, both feature-gated)
- `HandlerRegistry` register/get/alpn_strings, panics on duplicate
- Quinn accept loop: select on accept + shutdown, dispatch by ALPN
- iroh accept loop: select on accept + shutdown, dispatch by ALPN
- Dispatch spawns handler task via tokio::spawn
- AuthContext constructed from connection (alpn, remote_addr, fingerprint, identity)
- TLS RawKey: only_raw_public_keys(), on-the-fly cert from Ed25519
- TLS X509: load from files
- TLS SelfSigned: generate on startup
- ALPN list in ServerConfig from registry.alpn_strings()
- Graceful shutdown: drain timeout, force close
- EndpointError has all 3 variants
- No byte-peeking, no per-handler loops, no SSH-specific logic
5. **Pattern consistency**:
- ArcSwap used consistently for DynamicConfig
- Feature flags (quinn, iroh) gate transport code correctly
- Error handling patterns consistent (thiserror, Result propagation)
- No quinn/iroh types in public API (Connection wraps them)
6. **Security constraints**:
- Capabilities non-serializable (no Serialize derive)
- Capabilities zeroized (Zeroize, ZeroizeOnDrop)
- Capabilities immutable (no mut accessors)
- Config reload is privilege escalation (no unauthenticated reload endpoint)
- Token entropy requirement documented
7. **Test coverage**:
- Unit tests for Capabilities (build, get, clone, zeroize)
- Unit tests for config types and reload
- Unit tests for auth resolution (fingerprint, token, expiry)
- Unit tests for HandlerRegistry
- Integration test: endpoint dispatch by ALPN
## Acceptance Criteria
- [ ] All core types match core-types.md
- [ ] All config types match config.md
- [ ] All auth types match auth.md
- [ ] Endpoint matches endpoint.md (accept loops, TLS modes, shutdown)
- [ ] Capabilities security constraints satisfied (non-serializable, zeroized, immutable)
- [ ] No russh dependency in core
- [ ] No quinn/iroh types in public API
- [ ] ArcSwap pattern consistent
- [ ] Feature flags gate transport code correctly
- [ ] Test coverage adequate for all functionality
- [ ] `cargo fmt --check -p alknet-core` passes
- [ ] `cargo clippy -p alknet-core` passes with no warnings
- [ ] All tests pass
## References
- docs/architecture/crates/core/README.md
- docs/architecture/crates/core/core-types.md
- docs/architecture/crates/core/config.md
- docs/architecture/crates/core/auth.md
- docs/architecture/crates/core/endpoint.md
- docs/architecture/decisions/ (relevant ADRs: 001-011, 014, 015, 022)
## Notes
> This review verifies core is spec-conformant before alknet-call begins.
> alknet-call depends heavily on core types (ProtocolHandler, Connection,
> AuthContext, Capabilities, IdentityProvider) — any issues here propagate to
> call. If deviations are found, document and fix before proceeding.
## Summary
> To be filled on completion