From e7941da04a2a90dcf5faa02101868750818c4942 Mon Sep 17 00:00:00 2001 From: "glm-5.1" Date: Sun, 7 Jun 2026 10:29:52 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20clarify=20phase=20boundaries=20?= =?UTF-8?q?=E2=80=94=20Phase=201=20vs=20downstream=20concerns?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The architecture specs were implying that StorageIdentityProvider, irpc service implementations, and application services (agent, Docker, etc.) already exist. This commit makes the phasing explicit: - services.md: deployment topology now clearly labels 'Current (Phase 1)' vs 'Future (Phase 2+)', notes that application services are downstream - identity.md: StorageIdentityProvider labeled 'Future — Phase 2+', clarifying alknet-storage doesn't exist yet - storage.md: adds phase note that the crate hasn't been built yet, StorageIdentityProvider is a future impl - ADR-028: ConfigAuthService is Phase 1 path, StorageAuthService is Phase 2+ contract - call-protocol.md: Agent Service Pattern section explicitly framed as a downstream application concern, not a core requirement --- docs/architecture/call-protocol.md | 18 +++++----- .../decisions/028-auth-irpc-service.md | 9 ++--- docs/architecture/identity.md | 18 ++++++---- docs/architecture/services.md | 35 ++++++++++++++++--- docs/architecture/storage.md | 17 ++++++--- 5 files changed, 68 insertions(+), 29 deletions(-) diff --git a/docs/architecture/call-protocol.md b/docs/architecture/call-protocol.md index 6409e73..ded1649 100644 --- a/docs/architecture/call-protocol.md +++ b/docs/architecture/call-protocol.md @@ -335,11 +335,11 @@ through core, out over SSH channel, into a JavaScript pubsub adapter, and be dispatched through `@alkdev/operations`'s call handler** — with zero translation at the wire level. -### Agent Service Pattern +### Agent Service Pattern (Future) -The head commonly runs an agent service that coordinates between LLM providers -and tool calls. This service is just another set of registered operations — -no special treatment: +An agent service — coordinating between LLM providers and tool calls — is a +primary use case for the call protocol. It would be just another set of +registered operations with no special treatment: - `/head/agent/chat` — send a message, get a completion. Routes to the appropriate LLM provider based on available workers and configuration. @@ -348,10 +348,12 @@ no special treatment: durable storage). - `/head/sessions/history` — retrieve a specific session's message history. -The agent service uses the same call protocol to invoke tools on workers: -`/dev1/fs/readFile` for file access, `/dev1/bash/exec` for shell commands. It -stores session state via whatever mechanism the head deployment provides — core -doesn't mandate Honker or any specific storage. +The agent service would use the same call protocol to invoke tools on workers +(e.g., `/dev1/fs/readFile` for file access, `/dev1/bash/exec` for shell +commands). This is a **downstream application concern**, not a core +requirement. The call protocol enables it by providing the universal composition +mechanism (OperationEnv, ADR-033), but the agent service itself is built on +top, not into the core. ## Constraints diff --git a/docs/architecture/decisions/028-auth-irpc-service.md b/docs/architecture/decisions/028-auth-irpc-service.md index f5d12ec..ce9ba2d 100644 --- a/docs/architecture/decisions/028-auth-irpc-service.md +++ b/docs/architecture/decisions/028-auth-irpc-service.md @@ -81,14 +81,15 @@ feature is disabled, auth goes through `IdentityProvider` directly. ### AuthServiceImpl -Two implementations exist: +Two implementations exist (the second is a future phase): - **ConfigAuthService** — backed by `ConfigIdentityProvider` (ArcSwap path). Wraps the trait in an irpc service for deployments that use the service layer - but don't have SQLite. + but don't have SQLite. This is the Phase 1 path: it ships with alknet-core. - **StorageAuthService** — backed by SQLite `peer_credentials` and `api_keys` - tables (in alknet-storage). Queries on demand. Can maintain an LRU cache for - hot fingerprints. This is the production implementation. + tables (in alknet-storage, not yet built). Queries on demand. Can maintain an + LRU cache for hot fingerprints. This is a Phase 2+ implementation — the + contract is defined here so alknet-storage can implement it later. Both produce the same `AuthResult` — an `Identity` or a denial. Callers don't know or care which backend is running. diff --git a/docs/architecture/identity.md b/docs/architecture/identity.md index b2032f6..a84a13d 100644 --- a/docs/architecture/identity.md +++ b/docs/architecture/identity.md @@ -96,13 +96,16 @@ impl IdentityProvider for ConfigIdentityProvider { } ``` -### StorageIdentityProvider (Production) +### StorageIdentityProvider (Future — Phase 2+) -Implemented in `alknet-storage` (not in alknet-core). Backed by SQLite -`peer_credentials` and `api_keys` tables plus the ACL graph. Resolves -fingerprint → account → organization membership → effective scopes. Uses the -`IdentityProvider` trait defined in alknet-core, providing the concrete impl via -the trait. +Implemented in `alknet-storage` (a crate that doesn't exist yet). Backed by +SQLite `peer_credentials` and `api_keys` tables plus the ACL graph. Resolves +fingerprint → account → organization membership → effective scopes. + +This implementation is defined here so the contract is clear, but alknet-storage +hasn't been built yet. Phase 1 uses `ConfigIdentityProvider` exclusively. When +alknet-storage is built, it implements alknet-core's `IdentityProvider` trait, +and the CLI/NAPI assembly layer wires the concrete implementation. ### AuthProtocol irpc Service @@ -132,7 +135,8 @@ The relationship: which internally delegates to `AuthProtocol::VerifyPubkey` via an irpc client. Used in production deployments with SQLite-backed auth. -Both paths produce the same `Identity` result. +Both paths produce the same `Identity` result. Note: the irpc path requires the +service layer to be built (Phase 2+). Phase 1 uses the trait path exclusively. ### Auth Flows diff --git a/docs/architecture/services.md b/docs/architecture/services.md index d380d78..35fb93c 100644 --- a/docs/architecture/services.md +++ b/docs/architecture/services.md @@ -5,6 +5,16 @@ last_updated: 2026-06-07 # Services +> **Phase note**: This spec defines the contracts for the service layer — the +> protocol enums, OperationEnv, and deployment topologies. Phase 1 ships +> `ConfigIdentityProvider` (ArcSwap-based) and `ConfigServiceImpl` (ArcSwap-based) +> as the only auth and config implementations. The irpc service protocols +> (`AuthProtocol`, `SecretProtocol`, etc.) and the production deployment +> topology (multi-node with `StorageIdentityProvider`) are contracted here but +> will be implemented in Phase 2+. Application services (DockerService, +> NodeService, agent services) are downstream concerns that build on top of +> the call protocol and OperationEnv — they are not core requirements. + ## What The irpc service layer decomposes alknet's core responsibilities into @@ -143,18 +153,30 @@ HTTP, MCP, DNS, and WebSocket adapters all resolve through OperationEnv: ### Deployment Topologies -**Minimal (single node, CLI)**: All services run locally via tokio channels. +**Current (Phase 1, single node, CLI)**: This is what exists and ships today. +Auth uses `ConfigIdentityProvider` backed by `ArcSwap`. Config +uses `ConfigServiceImpl` backed by `ArcSwap`. There is no +database dependency. ``` ┌──────────────────────────────────────────────┐ │ Single Process │ -│ Auth (ArcSwap) | Secret (seed in RAM) | │ -│ Config (ArcSwap) | alknet-core Server │ +│ ConfigIdentityProvider (ArcSwap) │ +│ ConfigServiceImpl (ArcSwap) │ +│ alknet-core Server │ └──────────────────────────────────────────────┘ ``` -**Production (multi-node)**: Auth and secrets on dedicated nodes; workers -access them remotely. +The irpc service layer (`AuthProtocol`, `SecretProtocol`, `ConfigProtocol`, +`StorageProtocol`) and the application services (DockerService, NodeService, +WalletService, agent services) are downstream concerns that will be built in +later phases. The architecture defines the contracts (`IdentityProvider` trait, +`OperationEnv`, service protocol enums) so that implementations can plug in +without modifying core, but the implementations don't exist yet. + +**Future (multi-node, production)**: Auth and secrets on dedicated nodes; +workers access them remotely via irpc over QUIC. StorageIdentityProvider +backed by SQLite replaces ConfigIdentityProvider for auth. ``` Auth Node (SQLite) Secret Node (seed in RAM) @@ -168,6 +190,9 @@ Head Node (Config, Storage, alknet-core Server) Worker Node (alknet-core Client) ``` +This topology requires alknet-storage, alknet-secret, and the irpc service +layer to be built — they are Phase 2+ concerns. + ## Constraints - Services are **internal** — they run within a node or cluster. diff --git a/docs/architecture/storage.md b/docs/architecture/storage.md index b6da05b..70cb61c 100644 --- a/docs/architecture/storage.md +++ b/docs/architecture/storage.md @@ -5,9 +5,16 @@ last_updated: 2026-06-07 # Storage +> **Phase note**: `alknet-storage` is a future crate (Phase 2+). This spec +> defines its contract — the data model, the `IdentityProvider` impl, the +> irpc service protocol — so that alknet-core can define the traits +> (`IdentityProvider`) that storage will later implement. The crate itself +> hasn't been built yet. Phase 1 uses `ConfigIdentityProvider` backed by +> `ArcSwap`. + ## What -The `alknet-storage` crate provides SQLite-backed graph storage, identity +The `alknet-storage` crate will provide SQLite-backed graph storage, identity management, access control, and reactivity via honker. It mirrors the TypeScript `@alkdev/storage` package's design while leveraging Rust's type system and honker's built-in pub/sub. @@ -99,11 +106,11 @@ The ACL graph is a directed, non-multi metagraph: Delegation edges carry `narrowed_scopes` — the delegate can only exercise scopes that are a subset of the delegator's. -### StorageIdentityProvider +### StorageIdentityProvider (Future — Phase 2+) -Implements alknet-core's `IdentityProvider` trait (ADR-029). Queries -`peer_credentials` (for SSH key resolution) and `api_keys` (for token auth), then -traverses the ACL graph to compute effective scopes and resources. +Implements alknet-core's `IdentityProvider` trait (ADR-029). This is defined +here as a contract. When alknet-storage is built, it will provide this +implementation. Phase 1 uses `ConfigIdentityProvider` backed by `ArcSwap`. ```rust impl IdentityProvider for StorageIdentityProvider {