docs: clarify phase boundaries — Phase 1 vs downstream concerns
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
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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<DynamicConfig>`. Config
|
||||
uses `ConfigServiceImpl` backed by `ArcSwap<DynamicConfig>`. 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.
|
||||
|
||||
@@ -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<DynamicConfig>`.
|
||||
|
||||
## 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 {
|
||||
|
||||
Reference in New Issue
Block a user