tasks: clarify phase boundaries in remaining task descriptions
The remaining task descriptions implied that downstream concerns (StorageIdentityProvider, irpc service layer, agent services, multi-node deployment) already exist. Updated to clearly distinguish: - spec-update-server: Phase 1 ships ConfigIdentityProvider, not irpc auth - spec-update-call-protocol: Phase 1 is local dispatch only; irpc and remote dispatch are contracted for later. Agent services are downstream concerns. - spec-update-overview: Note which crates exist now vs which are Phase 2+ contracts - review-spec-foundation: Add phase boundary check to acceptance criteria
This commit is contained in:
@@ -33,7 +33,7 @@ Review all Phase 0 spec documents after they're written. This is the Phase 0 rev
|
||||
- [ ] **No inline open questions** — all OQs are in open-questions.md, specs reference OQ numbers
|
||||
- [ ] **Terminology is consistent** — head/worker everywhere (no hub/spoke in specs, ADRs retain historical language)
|
||||
- [ ] **Layer boundaries are clear** — every component belongs to exactly one layer (Transport, Interface, Protocol)
|
||||
- [ ] **Crate dependencies are acyclic** — core doesn't depend on secret, storage, or flowgraph per ADR-027
|
||||
- [ ] **Phase boundaries are clear** — specs distinguish what ships in Phase 1 (ConfigIdentityProvider, ArcSwap, local dispatch) from what's contracted for later (StorageIdentityProvider, irpc service layer, application services, multi-node deployment). No spec should imply that alknet-storage, alknet-secret, or the irpc service implementations already exist.
|
||||
- [ ] **Every spec has YAML frontmatter** with status and last_updated
|
||||
- [ ] **Identity is consistently defined** — Identity struct is `{id, scopes, resources}` everywhere (identity.md is canonical, auth.md references it)
|
||||
- [ ] **OperationEnv is consistently described** — three dispatch paths match across services.md, call-protocol.md, and identity.md
|
||||
|
||||
@@ -23,7 +23,9 @@ The current call-protocol.md already covers: operation paths, EventEnvelope wire
|
||||
2. **Three dispatch paths** — local dispatch, irpc service dispatch, remote dispatch, all producing the same ResponseEnvelope
|
||||
3. **OperationContext** — request_id, parent_request_id, identity, metadata, env, trusted
|
||||
4. **How irpc is one backend** — not a replacement for the call protocol or for OperationEnv
|
||||
5. **How a call protocol handler can call an irpc service internally** (e.g., /head/auth/verify calls AuthProtocol::VerifyPubkey)
|
||||
5. **How a call protocol handler can call an irpc service internally** (e.g., /head/auth/verify calls AuthProtocol::VerifyPubkey) — note: this is Phase 2+ composition; Phase 1 uses IdentityProvider directly
|
||||
|
||||
**Phase boundary note**: Phase 1 ships with local dispatch only (direct function calls through the operation registry). The irpc service dispatch and remote dispatch paths are contracted here but not built yet. OperationEnv should be documented with all three paths, but the spec should make it clear that Phase 1 is local-only. The agent service pattern example (`/head/agent/chat`) is a downstream application concern, not a core requirement.
|
||||
|
||||
**What stays the same**: Operation paths, EventEnvelope, call protocol events, bidirectional routing, head/worker architecture, PendingRequestMap, protocol adapter layer.
|
||||
|
||||
@@ -37,7 +39,8 @@ The current call-protocol.md already covers: operation paths, EventEnvelope wire
|
||||
- [ ] ResponseEnvelope as universal return type documented
|
||||
- [ ] Operation handlers receive `(input: Value, context: OperationContext) -> ResponseEnvelope`
|
||||
- [ ] irpc explicitly positioned as one dispatch backend for OperationEnv per ADR-033
|
||||
- [ ] Shows how a call protocol handler can internally call an irpc service (example: /head/auth/verify → AuthProtocol::VerifyPubkey)
|
||||
- [ ] Phase boundary clear: Phase 1 is local dispatch only; irpc and remote dispatch paths are contracted but not built yet
|
||||
- [ ] Agent service pattern is noted as a downstream application concern, not a core requirement
|
||||
- [ ] Hard constraint stated: OperationEnv composition model matches @alkdev/operations behavioral contract
|
||||
- [ ] ADR table updated with references to 028, 033
|
||||
- [ ] Reference to services.md for full OperationEnv and irpc service details
|
||||
|
||||
@@ -17,10 +17,10 @@ level: implementation
|
||||
|
||||
Update `docs/architecture/overview.md` to reflect the expanded scope from the integration plan. The current overview documents the alpha scope (SSH tunneling). It needs additions for:
|
||||
|
||||
1. **Crate structure** — alknet-core, alknet-secret, alknet-storage, alknet-flowgraph, alknet-napi, alknet (CLI). Per ADR-027.
|
||||
1. **Crate structure** — alknet-core, alknet-secret, alknet-storage, alknet-flowgraph, alknet-napi, alknet (CLI). Per ADR-027. Note which crates exist now (core, napi) vs which are contracted for later phases (secret, storage, flowgraph).
|
||||
2. **Three-layer model** — Transport (Layer 1), Interface (Layer 2), Protocol (Layer 3). SSH is an interface, not a transport. Per ADR-026.
|
||||
3. **Service layer concept** — irpc services for in-cluster communication, OperationEnv for composition. Per ADR-033.
|
||||
4. **Identity as core type** — Identity struct and IdentityProvider trait in alknet-core. Per ADR-029.
|
||||
3. **Service layer concept** — irpc services for in-cluster communication, OperationEnv for composition. Per ADR-033. Note this is Phase 2+ for the service implementations; Phase 1 uses ConfigIdentityProvider and ConfigServiceImpl directly.
|
||||
4. **Identity as core type** — Identity struct and IdentityProvider trait in alknet-core. Per ADR-029. Phase 1 ships ConfigIdentityProvider only; StorageIdentityProvider is contracted for when alknet-storage is built.
|
||||
5. **Updated dependency table** — new dependencies (irpc feature-gated, bip39, rusqlite, honker, petgraph, jsonschema)
|
||||
6. **Updated ADR table** — add ADRs 026-034
|
||||
7. **Updated architecture constraints** — add: Interface as Layer 2, OperationEnv as universal composition, event boundary discipline, static/dynamic config split
|
||||
@@ -29,7 +29,8 @@ The existing content (purpose, SSH tunneling, transport pluggability, etc.) stay
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Crate structure section added: the six crates and their brief descriptions per ADR-027
|
||||
- [ ] Crate structure section added with phase notes: core and napi exist now; secret, storage, flowgraph are Phase 2+ contracts
|
||||
- [ ] Phase boundary noted: service implementations (irpc) are Phase 2+; Phase 1 uses ConfigIdentityProvider and ArcSwap directly
|
||||
- [ ] Three-layer model mentioned in architecture constraints per ADR-026
|
||||
- [ ] Service layer concept mentioned: irpc + OperationEnv per ADR-033
|
||||
- [ ] Identity and IdentityProvider mentioned as core types per ADR-029
|
||||
|
||||
@@ -19,10 +19,12 @@ level: implementation
|
||||
|
||||
Update `docs/architecture/server.md` to reflect the architectural changes from Phase 1: DynamicConfig, ForwardingPolicy in channel handling, IdentityProvider replacing direct ServerAuthConfig reads, and the interface abstraction concept.
|
||||
|
||||
**Phase boundary note**: Phase 1 ships `ConfigIdentityProvider` (ArcSwap-backed) as the only `IdentityProvider` implementation. The irpc `AuthProtocol` and `StorageIdentityProvider` are contracted in the specs but not built yet. Server.md should describe what the server actually does in Phase 1 — reading auth from `ArcSwap<DynamicConfig>` via `ConfigIdentityProvider` — with a forward reference to identity.md for the full trait hierarchy. Don't describe irpc service wiring or SQLite-backed auth as if they exist.
|
||||
|
||||
The current server.md is thorough but reflects the alpha architecture where auth is read directly from `ServerAuthConfig` and there's no forwarding policy concept.
|
||||
|
||||
**Changes needed**:
|
||||
1. Update Authentication section: auth delegation goes through `IdentityProvider` trait (reference identity.md, ADR-028), not direct `ServerAuthConfig` reads
|
||||
1. Update Authentication section: auth goes through `IdentityProvider` trait (reference identity.md, ADR-029), with `ConfigIdentityProvider` as the Phase 1 impl reading from `ArcSwap<DynamicConfig>` (reference ADR-030). Note that `StorageIdentityProvider` is a future implementation.
|
||||
2. Add ForwardingPolicy check in Channel Handling section: before proxy spawn, evaluate ForwardingPolicy against Identity (reference configuration.md, ADR-031)
|
||||
3. Replace `Arc<ServerAuthConfig>` with `Arc<ArcSwap<DynamicConfig>>` in ServerHandler description (reference ADR-030)
|
||||
4. Add note about Interface abstraction: SSH is one interface (Layer 2), ServerHandler logic maps to SshInterface (reference interface.md, ADR-026) — but detail is in interface.md, not here
|
||||
@@ -33,14 +35,15 @@ The current server.md is thorough but reflects the alpha architecture where auth
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Authentication section updated: references IdentityProvider trait, not just ServerAuthConfig
|
||||
- [ ] Authentication section updated: references `IdentityProvider` trait with `ConfigIdentityProvider` as Phase 1 impl, notes `StorageIdentityProvider` as future
|
||||
- [ ] Channel Handling section updated: ForwardingPolicy check before proxy spawn, reference ADR-031
|
||||
- [ ] ServerHandler struct updated: `Arc<ArcSwap<DynamicConfig>>`, not `Arc<ServerAuthConfig>`
|
||||
- [ ] Note added about Interface abstraction pointing to interface.md and ADR-026
|
||||
- [ ] CLI section mentions `--config` flag (TOML) and `[[listeners]]` for multi-transport
|
||||
- [ ] Single-transport constraint softened (noted as current, changing per ADR-030)
|
||||
- [ ] Phase boundary clear: what ships in Phase 1 vs what's contracted for later
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] ADR table updated with references to 026, 028, 030, 031
|
||||
- [ ] ADR table updated with references to 026, 028, 029, 030, 031
|
||||
- [ ] References section updated to include configuration.md, identity.md, interface.md
|
||||
|
||||
## References
|
||||
|
||||
Reference in New Issue
Block a user