tasks: decompose Phase 0b spec documents and Phase 0c review
Add 15 new tasks under tasks/architecture/ for Phase 0b (spec writing) and Phase 0c (review): Phase 0b — New specs (6): - spec-configuration: promote from research, cleanup, align with ADRs - spec-identity: carry from auth.md + services.md, canonical Identity - spec-secret-service: from research/services.md SecretProtocol - spec-storage: from research/storage.md, contract-level - spec-flowgraph: from research/flow.md, pure computation crate - spec-interface: new Layer 2 spec (highest risk new spec) - spec-services: irpc service layer + OperationEnv (broadest scope) Phase 0b — Spec updates (6): - spec-update-overview: add crate structure, Layer 3, services - spec-update-auth: IdentityProvider vs AuthService relationship - spec-update-call-protocol: OperationEnv dispatch paths - spec-update-server: DynamicConfig, ForwardingPolicy, IdentityProvider - spec-update-napi: reload API, call protocol references - spec-update-open-questions: resolve OQs per ADR decisions Phase 0b — Assembly (1): - spec-update-readme: add new docs and ADRs to tables Phase 0c — Review (1): - review-spec-foundation: validate consistency checklist Generation structure (6 total): Gen 1: 6 independent ADRs (parallel) Gen 2: adr-027, adr-028 (depend on adr-029) Gen 3: adr-033 + 6 spec docs + open-questions update (parallel) Gen 4: adr review + interface/services specs + 4 spec updates Gen 5: call-protocol update + readme update Gen 6: spec review
This commit is contained in:
58
tasks/architecture/review-spec-foundation.md
Normal file
58
tasks/architecture/review-spec-foundation.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
id: architecture/review-spec-foundation
|
||||
name: Review Phase 0 specs — validate consistency, completeness, and ADR alignment
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/spec-configuration
|
||||
- architecture/spec-identity
|
||||
- architecture/spec-secret-service
|
||||
- architecture/spec-storage
|
||||
- architecture/spec-flowgraph
|
||||
- architecture/spec-interface
|
||||
- architecture/spec-services
|
||||
- architecture/spec-update-overview
|
||||
- architecture/spec-update-auth
|
||||
- architecture/spec-update-call-protocol
|
||||
- architecture/spec-update-server
|
||||
- architecture/spec-update-napi
|
||||
- architecture/spec-update-readme
|
||||
- architecture/spec-update-open-questions
|
||||
scope: broad
|
||||
risk: low
|
||||
impact: project
|
||||
level: review
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Review all Phase 0 spec documents after they're written. This is the Phase 0 review checklist from the integration plan, applied against the actual deliverables.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] **No inline decision rationale** — all "why" decisions are in ADRs, specs reference ADR numbers
|
||||
- [ ] **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
|
||||
- [ ] **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
|
||||
- [ ] **irpc positioning is consistent** — always described as one dispatch backend for OperationEnv, never as a replacement for the call protocol
|
||||
- [ ] **Interface trait is consistent** — SshInterface and RawFramingInterface match across interface.md and server.md
|
||||
- [ ] **ForwardingPolicy is consistently placed** — in DynamicConfig, checked before proxy spawn, reference in server.md and configuration.md
|
||||
- [ ] **README.md and ADR table** include all new documents and ADRs
|
||||
- [ ] **No broken links** between doc references
|
||||
- [ ] **All specs follow the format**: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/integration-plan.md — Phase 0: Review Checklist
|
||||
- docs/architecture/ — all architecture docs
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
63
tasks/architecture/spec-configuration.md
Normal file
63
tasks/architecture/spec-configuration.md
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
id: architecture/spec-configuration
|
||||
name: Promote configuration.md from research to architecture spec
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-030-static-dynamic-config-split
|
||||
- architecture/adr-031-forwarding-policy
|
||||
- architecture/adr-028-auth-irpc-service
|
||||
scope: moderate
|
||||
risk: medium
|
||||
impact: phase
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Promote `docs/research/configuration.md` to `docs/architecture/configuration.md` as a proper architecture spec document. The research doc is nearly spec-ready — this task is primarily cleanup, restructuring, and aligning with ADR decisions.
|
||||
|
||||
**Source**: `docs/research/configuration.md` (651 lines, well-analyzed)
|
||||
|
||||
**Key cleanup items**:
|
||||
1. Remove duplicate "## Problem" heading (lines 20-21 both say `## Problem`)
|
||||
2. Resolve open questions per ADRs: OQ-12 (global rules + principal matching via IdentityProvider), OQ-13 (no file watching, confirmed), OQ-14 (ArcSwap, confirmed), OQ-16 (TransportKind match in ForwardingRule), OQ-18 (IdentityProvider owns scopes)
|
||||
3. Remove inline decision rationale — reference ADR-030, ADR-031, ADR-028
|
||||
4. Remove inline open questions — reference open-questions.md OQ numbers
|
||||
5. Add YAML frontmatter: `status: draft`, `last_updated: <date>`
|
||||
6. Restructure to follow established spec format (What, Why, Architecture, Constraints, Open Questions, Design Decisions)
|
||||
7. Update terminology: head/worker (already done in research doc)
|
||||
8. Reconcile ADR-011: TOML config file amends ADR-011 (convenience layer), doesn't supersede it
|
||||
9. Remove research-only sections that are exploration/analysis — keep only the decisions and their architecture
|
||||
|
||||
**What stays**: StaticConfig/DynamicConfig split, ArcSwap model, ForwardingPolicy design, multi-transport listeners, ConfigService, NAPI reload API, TOML format, CLI vs programmatic behavior table
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docs/architecture/configuration.md` exists with YAML frontmatter (`status: draft`)
|
||||
- [ ] No duplicate "## Problem" heading
|
||||
- [ ] All inline decision rationale replaced with ADR references (030, 031, 028)
|
||||
- [ ] All inline open questions replaced with OQ references
|
||||
- [ ] OQ-12 resolved: global rules + principal matching, reference ADR-031
|
||||
- [ ] OQ-16 resolved: TransportKind match, reference ADR-031
|
||||
- [ ] OQ-18 resolved: IdentityProvider owns scopes, reference ADR-029
|
||||
- [ ] TOML config file positioned as amending ADR-011, not replacing programmatic API
|
||||
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
- [ ] Consistent head/worker terminology throughout
|
||||
- [ ] `docs/architecture/README.md` updated to include configuration.md in architecture docs table
|
||||
- [ ] `docs/research/configuration.md` retains its content (not deleted — it's research source material)
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/configuration.md — source material to promote
|
||||
- docs/architecture/decisions/030-static-dynamic-config-split.md — ADR to reference
|
||||
- docs/architecture/decisions/031-forwarding-policy.md — ADR to reference
|
||||
- docs/architecture/decisions/028-auth-irpc-service.md — ADR to reference
|
||||
- docs/architecture/decisions/011-no-ssh-config-programmatic-api.md — amended by TOML config
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
52
tasks/architecture/spec-flowgraph.md
Normal file
52
tasks/architecture/spec-flowgraph.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: architecture/spec-flowgraph
|
||||
name: Create flowgraph.md architecture spec (or stub referencing crate docs)
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-027-crate-decomposition
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Create `docs/architecture/flowgraph.md` — an architecture spec for the `alknet-flowgraph` crate, covering FlowGraph<N,E>, operation graph construction, call graph population, and type compatibility checking.
|
||||
|
||||
Like storage.md, this can be a contract-level document if the crate will have its own docs later. The key contract point: `OperationSpec` and `CallNodeAttrs` types must match alknet-core's definitions, with serialization as the bridge.
|
||||
|
||||
**Source**: `docs/research/flow.md` (472 lines, straightforward port of TypeScript design)
|
||||
|
||||
This is the lowest-risk new spec — pure computation crate, no I/O, no external state, straightforward petgraph port.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docs/architecture/flowgraph.md` exists with YAML frontmatter (`status: draft`)
|
||||
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
- [ ] Documents `FlowGraph<N, E>` generic graph over `petgraph::DiGraph`
|
||||
- [ ] Documents `NodeAttributes` / `EdgeAttributes` traits
|
||||
- [ ] Documents operation graph construction from `OperationSpec`s
|
||||
- [ ] Documents call graph population from `EventEnvelope` events
|
||||
- [ ] Documents type compatibility checking (jsonschema)
|
||||
- [ ] Documents cycle detection, topological sort, reachability queries
|
||||
- [ ] Documents serde serialization/deserialization
|
||||
- [ ] States crate dependencies: petgraph, serde, serde_json, jsonschema, thiserror
|
||||
- [ ] States crate does NOT depend on alknet-core, alknet-storage, or alknet-secret
|
||||
- [ ] States interface back to core: OperationSpec and CallNodeAttrs types match alknet-core's definitions; bridge is serialization
|
||||
- [ ] References ADR-027
|
||||
- [ ] `docs/architecture/README.md` updated to include flowgraph.md
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/flow.md — full FlowGraph, operation graph, call graph design
|
||||
- docs/research/integration-plan.md — Phase 2.3 (alknet-flowgraph)
|
||||
- docs/architecture/decisions/027-crate-decomposition.md
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
55
tasks/architecture/spec-identity.md
Normal file
55
tasks/architecture/spec-identity.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
id: architecture/spec-identity
|
||||
name: Create identity.md architecture spec
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-029-identity-core-type
|
||||
- architecture/adr-028-auth-irpc-service
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: phase
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Create `docs/architecture/identity.md` — a new architecture spec defining the `Identity` type, `IdentityProvider` trait, and the auth flows for SSH key-based and token-based authentication.
|
||||
|
||||
This is mostly a carry-forward from `auth.md` (which already defines `IdentityProvider` trait and `Identity` struct) plus the Identity section from `research/services.md`. The key addition is making the IdentityProvider vs AuthService relationship explicit per ADR-028: `IdentityProvider` is the contract, `ConfigIdentityProvider` is the default ArcSwap-backed impl, and `AuthProtocol` irpc service is one way to satisfy the trait (behind feature flag).
|
||||
|
||||
**Source material**:
|
||||
- `auth.md` sections: IdentityProvider Trait, AuthPolicy Structure, Auth Flow in the Server, Token Authentication
|
||||
- `research/services.md` AuthService section (AuthProtocol enum, AuthResult type)
|
||||
- ADR-029 (identity as core type), ADR-028 (auth as irpc service), ADR-023 (unified auth)
|
||||
|
||||
**Relationship to auth.md**: After identity.md exists, auth.md should be updated to reference identity.md for the `Identity` and `IdentityProvider` definitions rather than defining them inline. This is handled in the `auth.md` update task.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docs/architecture/identity.md` exists with YAML frontmatter (`status: draft`)
|
||||
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
- [ ] Defines `Identity` struct: `{ id, scopes, resources }` — canonical definition per ADR-029
|
||||
- [ ] Defines `IdentityProvider` trait: `resolve_from_fingerprint()`, `resolve_from_token()`
|
||||
- [ ] Documents default implementation: `ConfigIdentityProvider` reading from `ArcSwap<DynamicConfig.auth>`
|
||||
- [ ] Documents head implementation: `StorageIdentityProvider` backed by SQLite `peer_credentials` + ACL graph (in alknet-storage, not core)
|
||||
- [ ] Documents irpc service path: `AuthProtocol` enum (VerifyPubkey, VerifyToken, ReloadKeys, CheckAccess) behind `irpc` feature flag per ADR-028
|
||||
- [ ] Shows both auth flows: SSH key path and token auth path, both resolving to same `Identity`
|
||||
- [ ] Consistent head/worker terminology
|
||||
- [ ] References ADR-029, ADR-028, ADR-023
|
||||
- [ ] `docs/architecture/README.md` updated to include identity.md
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/auth.md — existing IdentityProvider and Identity definitions
|
||||
- docs/research/services.md — AuthService, AuthProtocol enum
|
||||
- docs/architecture/decisions/029-identity-core-type.md — identity placement decision
|
||||
- docs/architecture/decisions/028-auth-irpc-service.md — auth as irpc service
|
||||
- docs/architecture/decisions/023-unified-auth-shared-key-material.md — unified auth
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
73
tasks/architecture/spec-interface.md
Normal file
73
tasks/architecture/spec-interface.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
id: architecture/spec-interface
|
||||
name: Create interface.md architecture spec (Layer 2)
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-026-transport-interface-separation
|
||||
- architecture/adr-033-operationenv-irpc-call-protocol
|
||||
scope: moderate
|
||||
risk: high
|
||||
impact: project
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Create `docs/architecture/interface.md` — the new Layer 2 spec defining the Interface abstraction. This is the most architecturally significant new spec document.
|
||||
|
||||
Currently, SSH is deeply embedded in the server handler. The Interface trait extracts it into a pluggable Layer 2 component:
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait Interface: Send + Sync + 'static {
|
||||
type Session;
|
||||
async fn accept(stream: TransportStream, config: &InterfaceConfig) -> Result<Self::Session>;
|
||||
// The session produces call protocol events and handles responses
|
||||
}
|
||||
```
|
||||
|
||||
The spec must define:
|
||||
1. **The `Interface` trait** — consumes a `Transport::Stream` and produces call protocol sessions
|
||||
2. **`SshInterface`** — wraps existing russh handler, produces SSH channels + control channel
|
||||
3. **`RawFramingInterface`** — reads length-prefixed JSON EventEnvelope frames directly, no SSH wrapping
|
||||
4. **Valid (Transport, Interface) pairs** — enumerated per ADR-026
|
||||
5. **How the call protocol is interface-agnostic** — it receives EventEnvelope frames from any interface
|
||||
|
||||
**The hard part**: The existing `ServerHandler` owns auth, channel management, and proxy logic. The spec must cleanly define what moves to Layer 3 (call protocol), what stays in the interface, and what's shared. The split needs to be clean — this is explicitly flagged as needing careful design review in the integration plan.
|
||||
|
||||
**Depends on ADR-033 because**: The Interface trait must produce call protocol events, and OperationEnv defines how those events are dispatched. The Interface needs to produce the right shape of events for the OperationEnv to consume.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docs/architecture/interface.md` exists with YAML frontmatter (`status: draft`)
|
||||
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
- [ ] Defines the three-layer model (reference ADR-026): Transport (Layer 1), Interface (Layer 2), Protocol (Layer 3)
|
||||
- [ ] Defines `Interface` trait with signature, bounds, and lifecycle
|
||||
- [ ] Defines `SshInterface` — what it wraps from existing ServerHandler (auth delegation, channel open, proxy)
|
||||
- [ ] Defines `RawFramingInterface` — 4-byte BE length prefix + JSON EventEnvelope, no SSH
|
||||
- [ ] Enumerates valid (Transport, Interface) pairs per ADR-026 table
|
||||
- [ ] Defines what `InterfaceConfig` contains (different per interface type)
|
||||
- [ ] Clearly separates what moves to call protocol (Layer 3) vs what stays in the interface (Layer 2)
|
||||
- [ ] Shows how `auth_publickey()` maps to SshInterface (not RawFramingInterface which uses token auth)
|
||||
- [ ] Shows how `channel_open_direct_tcpip()` proxy logic relates to Layer 3 forwarding policy
|
||||
- [ ] DNS control channel explicitly defined as (DNS transport, raw framing interface) — NOT SSH inside DNS
|
||||
- [ ] Call protocol is interface-agnostic: receives EventEnvelope from any interface
|
||||
- [ ] References ADR-026, ADR-033
|
||||
- [ ] `docs/architecture/README.md` updated to include interface.md
|
||||
- [ ] Flags any open design questions (e.g., exactly how auth maps across interfaces)
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/integration-plan.md — Phase 1.8, three-layer model, valid (Transport, Interface) pairs
|
||||
- docs/research/core.md — DNS transport, interface concept
|
||||
- docs/architecture/decisions/026-transport-interface-separation.md
|
||||
- docs/architecture/decisions/033-operationenv-irpc-call-protocol.md
|
||||
- docs/architecture/server.md — current ServerHandler (source of SshInterface logic)
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
59
tasks/architecture/spec-secret-service.md
Normal file
59
tasks/architecture/spec-secret-service.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
id: architecture/spec-secret-service
|
||||
name: Create secret-service.md architecture spec
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-027-crate-decomposition
|
||||
- architecture/adr-032-event-boundary-discipline
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Create `docs/architecture/secret-service.md` — a new architecture spec for the `alknet-secret` crate and its `SecretProtocol` irpc service.
|
||||
|
||||
This slides from the research in `docs/research/services.md` (SecretProtocol definition) and `docs/research/storage.md` (secrets section, key derivation paths). The secret service is well-bounded: BIP39 mnemonics, SLIP-0010 Ed25519 HD key derivation, AES-256-GCM encryption for external credentials, and a lock/unlock lifecycle.
|
||||
|
||||
**Scope**: alknet-secret crate definition, not alknet-core changes.
|
||||
|
||||
**Key content from research**:
|
||||
- SecretProtocol enum: Unlock, Lock, DeriveEd25519, DeriveEncryptionKey, DeriveEthereumKey, DerivePassword, Encrypt, Decrypt
|
||||
- DerivedKey, KeyType, EncryptedData types
|
||||
- Security model: locked/unlocked states, seed in RAM only, never on disk
|
||||
- Derivation path constants (SLIP-0044 coin type 74')
|
||||
- Event boundary: SecretService domain events (honker streams for key derivation notifications) stay internal. External consumers use irpc calls or call protocol operations that project to integration events.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docs/architecture/secret-service.md` exists with YAML frontmatter (`status: draft`)
|
||||
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
- [ ] Documents BIP39 mnemonic generation and seed derivation
|
||||
- [ ] Documents SLIP-0010 Ed25519 HD key derivation (SLIP-0044 coin type 74')
|
||||
- [ ] Documents AES-256-GCM encryption/decryption for external credentials
|
||||
- [ ] Documents SecretProtocol irpc service: Unlock, Lock, DeriveEd25519, DeriveEncryptionKey, Encrypt, Decrypt variants
|
||||
- [ ] Documents EncryptedData type (key_version, salt, iv, ciphertext)
|
||||
- [ ] Documents derivation path constants
|
||||
- [ ] Documents security model: locked/unlocked states, seed lifecycle, never persisted
|
||||
- [ ] States crate dependencies: bip39, ed25519-bip32, aes-gcm, sha2, irpc
|
||||
- [ ] States crate does NOT depend on alknet-core or alknet-storage
|
||||
- [ ] States interface back to core: EncryptedData format referenced by alknet-storage (wire format compatibility, not crate dependency)
|
||||
- [ ] Event boundary per ADR-032: honker streams internal, irpc calls internal, no direct EventEnvelope emission
|
||||
- [ ] References ADR-027, ADR-032
|
||||
- [ ] `docs/architecture/README.md` updated to include secret-service.md
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/services.md — SecretProtocol definition, DerivedKey, KeyType, EncryptedData
|
||||
- docs/research/storage.md — secrets section, key derivation paths
|
||||
- docs/research/integration-plan.md — Phase 2.1 (alknet-secret)
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
69
tasks/architecture/spec-services.md
Normal file
69
tasks/architecture/spec-services.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
id: architecture/spec-services
|
||||
name: Create services.md architecture spec (irpc service layer + OperationEnv)
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-033-operationenv-irpc-call-protocol
|
||||
- architecture/adr-027-crate-decomposition
|
||||
- architecture/adr-028-auth-irpc-service
|
||||
- architecture/adr-032-event-boundary-discipline
|
||||
scope: broad
|
||||
risk: high
|
||||
impact: project
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Create `docs/architecture/services.md` — the irpc service layer spec. This integrates three things that the research treated separately:
|
||||
|
||||
1. **irpc service protocols** — AuthProtocol, SecretProtocol, ConfigProtocol, StorageProtocol — their enum definitions, wire formats, and backends
|
||||
2. **OperationEnv** — the universal composition mechanism with three dispatch paths (local, irpc, remote)
|
||||
3. **OperationContext** — the request context that handlers receive
|
||||
|
||||
This is the second most complex new spec (after interface.md). The integration plan spends the most words on this topic because it's where the most confusion existed between irpc services, call protocol operations, and external services.
|
||||
|
||||
The spec must make it crystal clear:
|
||||
- irpc services are in-cluster, Rust-to-Rust, postcard serialization
|
||||
- Call protocol operations are cross-node, cross-language, JSON EventEnvelope
|
||||
- OperationEnv unifies them from the handler's perspective
|
||||
- An irpc service can back a call protocol operation via OperationEnv
|
||||
- Both are Layer 3 but at different scope boundaries
|
||||
|
||||
**Source**: `docs/research/services.md` (808 lines) + integration plan's OperationEnv and dispatch path sections + ADR-033
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docs/architecture/services.md` exists with YAML frontmatter (`status: draft`)
|
||||
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
- [ ] Documents irpc service pattern: `#[rpc_requests]` enum, Serializable vs WithChannels, `Client<S>`
|
||||
- [ ] Documents all four service protocols: AuthProtocol, SecretProtocol, ConfigProtocol, StorageProtocol (type signatures, not full implementations — those go in per-crate specs)
|
||||
- [ ] Documents OperationContext struct: request_id, parent_request_id, identity, metadata, env, trusted
|
||||
- [ ] Documents OperationEnv as universal composition mechanism per ADR-033
|
||||
- [ ] Shows three dispatch paths with examples: local (direct call), irpc service (postcard over mpsc/QUIC), remote (call protocol EventEnvelope)
|
||||
- [ ] Shows OperationEnv wiring for minimal and production deployments
|
||||
- [ ] Shows how adapters (MCP, OpenAPI, HTTP, DNS) map to OperationEnv
|
||||
- [ ] Consistent naming: irpc service / operation / external service (per ADR-033)
|
||||
- [ ] Composition diagram: Call Protocol → irpc Service → Honker Streams (per ADR-032)
|
||||
- [ ] Hard constraint stated: handler-facing OperationEnv API matches @alkdev/operations behavioral contract
|
||||
- [ ] Event boundary per ADR-032: domain events never cross boundaries without projection
|
||||
- [ ] References ADR-027, ADR-028, ADR-032, ADR-033
|
||||
- [ ] `docs/architecture/README.md` updated to include services.md
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/services.md — full service protocol definitions, OperationContext, OperationEnv
|
||||
- docs/research/integration-plan.md — OperationEnv section, three dispatch paths, adapter patterns
|
||||
- docs/architecture/decisions/033-operationenv-irpc-call-protocol.md
|
||||
- docs/architecture/decisions/027-crate-decomposition.md
|
||||
- docs/architecture/decisions/028-auth-irpc-service.md
|
||||
- docs/architecture/decisions/032-event-boundary-discipline.md
|
||||
- @alkdev/operations — TypeScript OperationEnv implementation
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
56
tasks/architecture/spec-storage.md
Normal file
56
tasks/architecture/spec-storage.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: architecture/spec-storage
|
||||
name: Create storage.md architecture spec (or stub referencing crate docs)
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-027-crate-decomposition
|
||||
- architecture/adr-029-identity-core-type
|
||||
- architecture/adr-032-event-boundary-discipline
|
||||
scope: moderate
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Create `docs/architecture/storage.md` — an architecture spec for the `alknet-storage` crate, covering the metagraph data model, identity tables, ACL graph, honker integration, and StorageProtocol irpc service.
|
||||
|
||||
The integration plan notes this could be "a new spec or reference alknet-storage's own docs." Since alknet-storage doesn't exist yet as a crate, we need an architecture spec here to define its contract — especially the interface back to core (`StorageIdentityProvider` implementing alknet-core's `IdentityProvider` trait).
|
||||
|
||||
If the crate will have its own detailed docs later, this spec can be a contract-level document: what storage provides, what it depends on, and how it connects to core.
|
||||
|
||||
**Source**: `docs/research/storage.md` (460 lines, comprehensive)
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docs/architecture/storage.md` exists with YAML frontmatter (`status: draft`)
|
||||
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
|
||||
- [ ] Documents metagraph data model: GraphType, NodeType, EdgeType, Graph, Node, Edge
|
||||
- [ ] Documents identity tables: accounts, organizations, peer_credentials, api_keys, audit_logs
|
||||
- [ ] Documents ACL as metagraph: PrincipalNode, DelegatesEdge, access control graph
|
||||
- [ ] Documents encrypted node type: bridges to alknet-secret's EncryptedData format
|
||||
- [ ] Documents honker integration: stream_publish/subscribe, notify/listen, queue/claim
|
||||
- [ ] Documents System DB vs Tenant DB separation
|
||||
- [ ] Documents `StorageIdentityProvider`: implements alknet-core's `IdentityProvider` trait (queries peer_credentials + ACL graph) per ADR-029
|
||||
- [ ] Documents `StorageProtocol` irpc service with key variants
|
||||
- [ ] States crate dependencies: rusqlite, honker, petgraph, jsonschema, irpc
|
||||
- [ ] States crate does NOT depend on alknet-core (implements core's trait by depending on alknet-core types, not the full crate — or via the trait definition only)
|
||||
- [ ] Event boundary per ADR-032: honker streams stay within storage service, StorageProtocol serves as internal boundary, call protocol events are projections
|
||||
- [ ] References ADR-027, ADR-029, ADR-032
|
||||
- [ ] `docs/architecture/README.md` updated to include storage.md
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/storage.md — full metagraph, identity, ACL, honker definitions
|
||||
- docs/research/integration-plan.md — Phase 2.2 (alknet-storage)
|
||||
- docs/architecture/decisions/027-crate-decomposition.md
|
||||
- docs/architecture/decisions/029-identity-core-type.md
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
55
tasks/architecture/spec-update-auth.md
Normal file
55
tasks/architecture/spec-update-auth.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
id: architecture/spec-update-auth
|
||||
name: Update auth.md — add IdentityProvider vs AuthService relationship
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/spec-identity
|
||||
- architecture/adr-028-auth-irpc-service
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Update `docs/architecture/auth.md` to add the IdentityProvider vs AuthService relationship and update for the `AuthProtocol` irpc service per ADR-028.
|
||||
|
||||
The current auth.md already defines `IdentityProvider` trait and `Identity` struct — which is good. After identity.md exists as the canonical home for those definitions, auth.md should reference identity.md instead of defining them inline.
|
||||
|
||||
**Changes needed**:
|
||||
1. Replace inline `Identity` and `IdentityProvider` definitions with references to identity.md
|
||||
2. Add section on `AuthProtocol` irpc service (VerifyPubkey, VerifyToken, ReloadKeys, CheckAccess) behind `irpc` feature flag
|
||||
3. Add section on `ConfigIdentityProvider` as the default impl (ArcSwap-backed)
|
||||
4. Clarify the relationship: `IdentityProvider` is the contract, irpc `AuthProtocol` is one way to implement it, `ConfigIdentityProvider` is another
|
||||
5. Remove inline decision rationale about IdentityProvider placement — reference ADR-029
|
||||
6. Reference ADR-028 for the irpc service decision
|
||||
|
||||
**What stays the same**: Token authentication design, AuthPolicy structure, browser-side token construction, WebTransport session request inspection, security considerations, all existing constraints.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `Identity` and `IdentityProvider` definitions reference identity.md (canonical) rather than defining inline
|
||||
- [ ] `AuthProtocol` irpc service documented with variants (VerifyPubkey, VerifyToken, ReloadKeys, CheckAccess) per ADR-028
|
||||
- [ ] `ConfigIdentityProvider` documented as default implementation (ArcSwap path)
|
||||
- [ ] Relationship between trait-based path and irpc path clearly stated
|
||||
- [ ] `irpc` feature flag mentioned for AuthProtocol
|
||||
- [ ] Inline decision rationale replaced with ADR references (028, 029)
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] No hub/spoke terminology
|
||||
- [ ] References section updated to include identity.md, ADR-028, ADR-029
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/auth.md — current content to update
|
||||
- docs/research/integration-plan.md — auth.md update entry
|
||||
- docs/architecture/decisions/028-auth-irpc-service.md
|
||||
- docs/architecture/decisions/029-identity-core-type.md
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
61
tasks/architecture/spec-update-call-protocol.md
Normal file
61
tasks/architecture/spec-update-call-protocol.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
id: architecture/spec-update-call-protocol
|
||||
name: Update call-protocol.md — add OperationEnv dispatch paths, irpc as backend
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-033-operationenv-irpc-call-protocol
|
||||
- architecture/spec-services
|
||||
- architecture/spec-interface
|
||||
scope: moderate
|
||||
risk: medium
|
||||
impact: phase
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Update `docs/architecture/call-protocol.md` to add OperationEnv as the universal composition mechanism with three dispatch paths, and show how irpc is one backend for OperationEnv (not a replacement).
|
||||
|
||||
The current call-protocol.md already covers: operation paths, EventEnvelope wire format, call protocol events, bidirectional routing, head/worker architecture, operation registry, ACL, service discovery, PendingRequestMap, and protocol adapter layer. It was already updated for head/worker terminology.
|
||||
|
||||
**What's missing** (per integration plan):
|
||||
1. **OperationEnv as universal composition mechanism** — the handler-facing API that unifies local calls, irpc service calls, and remote call protocol calls
|
||||
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)
|
||||
|
||||
**What stays the same**: Operation paths, EventEnvelope, call protocol events, bidirectional routing, head/worker architecture, PendingRequestMap, protocol adapter layer.
|
||||
|
||||
**Note**: Hub/spoke was already updated to head/worker. ADR references are partial (currently references 018, 024, 025).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] OperationEnv section added, documenting it as universal composition mechanism per ADR-033
|
||||
- [ ] Three dispatch paths documented with examples: local (zero serialization), irpc service (postcard), remote (JSON EventEnvelope)
|
||||
- [ ] OperationContext struct documented (request_id, parent_request_id, identity, metadata, env, trusted)
|
||||
- [ ] 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)
|
||||
- [ ] 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
|
||||
- [ ] Reference to interface.md for how EventEngrams flow from interfaces
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] No hub/spoke terminology in any new content
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/call-protocol.md — current content to update
|
||||
- docs/research/integration-plan.md — call-protocol.md update entry
|
||||
- docs/architecture/decisions/033-operationenv-irpc-call-protocol.md
|
||||
- @alkdev/operations — TypeScript OperationEnv
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
50
tasks/architecture/spec-update-napi.md
Normal file
50
tasks/architecture/spec-update-napi.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
id: architecture/spec-update-napi
|
||||
name: Update napi-and-pubsub.md — add reload API and call protocol references
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/spec-configuration
|
||||
- architecture/adr-033-operationenv-irpc-call-protocol
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Update `docs/architecture/napi-and-pubsub.md` to add the NAPI reload API (reloadAuth, reloadForwarding, reloadAll) and references to the call protocol integration.
|
||||
|
||||
The current spec is reviewed and stable. Changes are additive:
|
||||
|
||||
1. Add `reloadAuth()`, `reloadForwarding()`, `reloadAll()` methods to `AlknetServer` interface
|
||||
2. Add note about call protocol integration: NAPI consumers can register operation handlers
|
||||
3. Add note about irpc service creation for NAPI consumers (behind feature flag)
|
||||
4. Reference configuration.md and services.md for details
|
||||
|
||||
**What stays the same**: Everything else. The NAPI wrapper, pubsub adapter, connect vs serve semantics, stream handling, constraints — all unchanged.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `AlknetServer` interface in NAPI section updated with reloadAuth(), reloadForwarding(), reloadAll()
|
||||
- [ ] TypeScript interface signature for reload methods matches research/configuration.md NAPI section
|
||||
- [ ] Note added: call protocol integration — NAPI consumers can register operation handlers
|
||||
- [ ] Note added: irpc service creation available for NAPI consumers (feature-gated)
|
||||
- [ ] References to configuration.md and services.md added
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] Existing content unchanged except where additions are made
|
||||
- [ ] ADR references remain correct
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/napi-and-pubsub.md — current content
|
||||
- docs/research/configuration.md — NAPI Reload API section
|
||||
- docs/research/integration-plan.md — Phase 3.4 (NAPI layer updates)
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
58
tasks/architecture/spec-update-open-questions.md
Normal file
58
tasks/architecture/spec-update-open-questions.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
id: architecture/spec-update-open-questions
|
||||
name: Update open-questions.md — resolve questions per ADR decisions
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-031-forwarding-policy
|
||||
- architecture/adr-029-identity-core-type
|
||||
- architecture/adr-028-auth-irpc-service
|
||||
- architecture/adr-030-static-dynamic-config-split
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Update `docs/architecture/open-questions.md` to record resolutions for the open questions that the new ADRs address.
|
||||
|
||||
**Questions to resolve**:
|
||||
- **OQ-12** (Per-user forwarding scope vs global rules): Resolved per ADR-031 — start with global rules + principal matching. Per-user scope from peer_credentials.metadata.scopes via IdentityProvider.
|
||||
- **OQ-16** (Transport-specific forwarding policy): Resolved per ADR-031 — add TransportKind match in ForwardingRule. WebTransport clients can be restricted to alknet-* channels.
|
||||
- **OQ-18** (Source of Identity.scopes): Resolved per ADR-029 and ADR-031 — IdentityProvider owns scopes, ForwardingPolicy uses scopes from Identity.
|
||||
- **OQ-22** (Client streaming in call protocol): Resolved per integration plan — defer. Current model (single request, optional streaming response) covers all identified use cases.
|
||||
- **New** (irpc dependency: always or feature flag?): Resolved per ADR-027 — feature flag. Nodes that only do SSH tunneling don't need the service layer.
|
||||
- **New** (DNS control channel scope): Resolved per ADR-026 — call protocol frames only (no SSH over DNS).
|
||||
- **New** (alknet-storage and alknet-secret irpc dependency): Resolved per ADR-027 — independently.
|
||||
|
||||
**Questions that remain open** (deferred):
|
||||
- **OQ-15** (TLS + WebTransport + iroh QUIC coexistence): Deferred to Phase 4 per integration plan.
|
||||
- **OQ-19** (Separate TLS identity for WebTransport): Deferred to Phase 4.
|
||||
- **OQ-20** (Worker registration and discovery): Still open per integration plan. Register on connect, cleanup on disconnect is the leading approach but needs spec in call-protocol.md.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] OQ-12 marked as resolved with ADR-031 reference
|
||||
- [ ] OQ-16 marked as resolved with ADR-031 reference
|
||||
- [ ] OQ-18 marked as resolved with ADR-029/ADR-031 reference
|
||||
- [ ] OQ-22 marked as resolved (deferred) with note
|
||||
- [ ] New OQ (irpc feature flag) added and resolved with ADR-027 reference
|
||||
- [ ] New OQ (DNS control channel scope) added and resolved with ADR-026 reference
|
||||
- [ ] New OQ (storage/secret irpc dep) added and resolved with ADR-027 reference
|
||||
- [ ] OQ-15, OQ-19, OQ-20 remain open with notes on deferral
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] Format consistent with existing resolved entries (strikethrough priority, ADR reference)
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/open-questions.md — current content
|
||||
- docs/research/integration-plan.md — "Open Questions to Resolve Before Phase 1" section
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
54
tasks/architecture/spec-update-overview.md
Normal file
54
tasks/architecture/spec-update-overview.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
id: architecture/spec-update-overview
|
||||
name: Update overview.md — add crate structure, Layer 3, services, identity
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-027-crate-decomposition
|
||||
- architecture/adr-026-transport-interface-separation
|
||||
- architecture/adr-033-operationenv-irpc-call-protocol
|
||||
- architecture/adr-029-identity-core-type
|
||||
scope: moderate
|
||||
risk: low
|
||||
impact: project
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
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.
|
||||
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.
|
||||
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
|
||||
|
||||
The existing content (purpose, SSH tunneling, transport pluggability, etc.) stays. We're adding, not replacing.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Crate structure section added: the six crates and their brief descriptions per ADR-027
|
||||
- [ ] 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
|
||||
- [ ] Updated dependency table with new crate dependencies
|
||||
- [ ] ADR table updated: ADRs 026-034 added with correct titles and status
|
||||
- [ ] Architecture constraints updated: add Layer 2 interface concept, OperationEnv, event boundary, static/dynamic config
|
||||
- [ ] All new references to architecture specs link correctly (identity.md, services.md, interface.md, configuration.md, etc. — even if those specs are still being written)
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] No hub/spoke terminology remains
|
||||
|
||||
## References
|
||||
|
||||
- docs/research/integration-plan.md — expanded scope, dependency graph
|
||||
- docs/architecture/overview.md — current content to update
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
54
tasks/architecture/spec-update-readme.md
Normal file
54
tasks/architecture/spec-update-readme.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
id: architecture/spec-update-readme
|
||||
name: Update architecture README.md — add new docs and ADRs to tables
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/spec-configuration
|
||||
- architecture/spec-identity
|
||||
- architecture/spec-secret-service
|
||||
- architecture/spec-storage
|
||||
- architecture/spec-flowgraph
|
||||
- architecture/spec-interface
|
||||
- architecture/spec-services
|
||||
- architecture/review-adr-foundation
|
||||
scope: narrow
|
||||
risk: trivial
|
||||
impact: project
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Update `docs/architecture/README.md` to add all new architecture documents and ADRs (026-034) to their respective tables. This is the final documentation assembly task — it runs after all new spec docs are created.
|
||||
|
||||
**Changes to Architecture Documents table**:
|
||||
Add rows for: identity.md, services.md, interface.md, configuration.md, secret-service.md, storage.md, flowgraph.md
|
||||
|
||||
**Changes to Research Documents table**:
|
||||
No changes needed — research docs stay as-is.
|
||||
|
||||
**Changes to ADR Table**:
|
||||
Add ADRs 026-034 with correct titles and status (Accepted).
|
||||
|
||||
**Changes to Current State section**:
|
||||
Update to reflect the new scope: services, identity, interface layer, configuration architecture.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Architecture Documents table includes all new docs (identity.md, services.md, interface.md, configuration.md, secret-service.md, storage.md, flowgraph.md) with correct status and descriptions
|
||||
- [ ] ADR table includes ADRs 026-034 with correct titles and "Accepted" status
|
||||
- [ ] Current State section updated to reflect expanded scope
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] No broken links (all new doc references point to files that exist)
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/README.md — current content to update
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
60
tasks/architecture/spec-update-server.md
Normal file
60
tasks/architecture/spec-update-server.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: architecture/spec-update-server
|
||||
name: Update server.md — add DynamicConfig, ForwardingPolicy, IdentityProvider references
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-030-static-dynamic-config-split
|
||||
- architecture/adr-031-forwarding-policy
|
||||
- architecture/adr-028-auth-irpc-service
|
||||
- architecture/adr-026-transport-interface-separation
|
||||
- architecture/spec-configuration
|
||||
- architecture/spec-identity
|
||||
scope: narrow
|
||||
risk: medium
|
||||
impact: component
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
5. Update CLI interface section: mention `--config` flag for TOML config, `[[listeners]]` for multi-transport
|
||||
6. Update constraint about single transport: "Currently binds to a single transport" → note that multi-transport is coming per ADR-030
|
||||
|
||||
**What stays the same**: TLS cert provisioning, stealth mode, outbound proxy modes, logging/rate limiting, graceful shutdown, error handling, most CLI flags.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Authentication section updated: references IdentityProvider trait, not just ServerAuthConfig
|
||||
- [ ] 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)
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] ADR table updated with references to 026, 028, 030, 031
|
||||
- [ ] References section updated to include configuration.md, identity.md, interface.md
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/server.md — current content to update
|
||||
- docs/architecture/decisions/030-static-dynamic-config-split.md
|
||||
- docs/architecture/decisions/031-forwarding-policy.md
|
||||
- docs/architecture/decisions/028-auth-irpc-service.md
|
||||
- docs/architecture/decisions/026-transport-interface-separation.md
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
Reference in New Issue
Block a user