DESIGN.md
Rama main · réplica de lectura del repositorio original.
# Aivyx PA Design — Phase 0
Started 2026-04-13 as an agent-first rebuild following the archival of the
pre-rebuild codebase (`~/_archive/aivyx-2026-04-13/`). Agent-first means the
turn loop is the core of `aivyx-core` from commit one; every other crate
justifies its existence relative to what a running turn loop needs.
---
## Deliverable 1 — The Turn Loop Contract (LOCKED 2026-04-13)
This paragraph is the north star. Every subsequent deliverable is measured
against it: does this make the paragraph easier or harder to say?
> A turn begins when a `ChannelContext` delivers an inbound `Message` to an
> `Agent`. The agent resolves the channel's trust tier and loads the
> corresponding `CapabilitySet`, then enters a tool-calling loop with its
> `LlmProvider`. On each LLM step, the agent either receives streamed text
> to relay back through the channel or receives a structured tool call.
> Each tool call — including memory recall, which is itself a tool — is
> scope-checked against the agent's capability set before execution, and
> on completion returns a `ToolOutcome` that distinguishes "the call
> returned `Ok`" from "the intended effect was observed." Every tool call,
> scope check, and outcome is appended to an HMAC-chained audit log
> synchronously as it happens. The loop terminates when the LLM emits a
> final assistant message, when a tool call returns `RequiresEscalation`,
> when a timeout fires, or when the channel cancels. The turn ends by
> flushing any pending audit entries, returning a `TurnOutcome` to the
> channel, and yielding control.
### What this commits us to
1. **No entry point bypasses a channel.** CLI, desktop, REST, Telegram —
all are channels. No "internal" turn with no channel context. This
closes the `aivyx-pa/src/api.rs:526` class of bug by construction.
2. **Trust tier resolution happens first.** Before any LLM call, before
any tool call, the agent knows what it's allowed to do. Capability
attenuation is not retrofitted onto a running agent.
3. **Memory is a tool, not an ambient system.** Lazy recall via
`memory.recall(query)` with scope `memory.read`. Writes via
`memory.write` with scope `memory.write`. Every memory access is
audited because it's just a tool call.
4. **Tool success ≠ intent completed.** `ToolOutcome::Completed` carries
a `verified: bool` flag. Tool authors must think about verification at
the type level. Closes `feedback_tool_success_vs_intent.md`.
5. **Audit is synchronous, inline, HMAC-chained.** If the process crashes
mid-turn, the audit log still tells the truth about what got executed.
The cost is microseconds per tool call; the trustworthiness gain is
large.
6. **Four termination conditions, named explicitly.** Final assistant
message, `RequiresEscalation`, timeout, channel cancel. A fifth is a
design conversation.
7. **Turn ends by yielding control to the channel.** The agent doesn't
spin waiting for "next message" — control returns to the channel
adapter between turns.
### What the paragraph deliberately does not say
- Streaming protocol details — deferred to Phase 1 trait design
- Single-shot vs. multi-step tool loop structure — covered by "tool-calling loop"
- Concurrency model (sequential? parallel tools?) — **resolved by
[Amendment A6](docs/amendments/2026-04-21-parallel-tool-execution.md)**:
batch dispatch via `join_all` when planner returns `NextStep::ToolCalls`
- Multi-agent coordination — out of scope for v1; **shipped post-v1 as
Chapter J (the Nonagon)** — a lead convening ≤9 *attenuated, in-process*
specialists on the one daemon/chain, which preserves (not breaks) the
single-agent ethos. See [`docs/NONAGON.md`](docs/NONAGON.md).
- Federation / remote agents — out of scope for v1 (still deferred)
### Scenario tests
Four scenarios the paragraph should make easy to reason about:
1. **"Tell me what I worked on yesterday"** — LLM emits `memory.recall`
tool call, scope-checked, returns recalled entries, LLM summarizes.
✓ Paragraph holds.
2. **"Close the terminal window"** — LLM emits `window.close_focused`,
tool executes and verifies the window is gone, `ToolOutcome::Completed
{ verified: true }`. ✓ Paragraph holds; closes the Alfred window-close
bug class.
3. **"Run rm -rf ~ from Telegram"** — Trust tier 2 excludes `shell.exec`.
Scope check denies. `ToolOutcome::Denied`. LLM sees denial and either
explains or escalates. ✓ Paragraph holds.
4. **"User hits Ctrl-C mid-tool-call"** — In-flight tool finishes, loop
checks cancellation before next LLM step, terminates with
`TurnOutcome::Cancelled`. ✓ Paragraph holds; open question is
*when* the cancellation check fires (between LLM steps, not
mid-tool-call). Defer to Phase 1.
### Concepts named but not yet defined (Phase 1 work)
- **`ChannelContext`** — delivers messages, carries trust tier, supports
cancellation. Likely `&dyn ChannelContext` at trait boundaries.
- **`TurnOutcome`** — at minimum: `Completed`, `Cancelled`, `Escalated`,
`TimedOut`, `Failed(AivyxError)`. Possibly `AwaitingInput`.
- **`ToolOutcome`** — at minimum: `Completed { verified: bool }`,
`Denied { scope: Scope }`, `RequiresEscalation { reason: String }`,
`Failed(AivyxError)`.
> **Amendment (2026-04-17):** The turn loop described above now runs
> inside a daemon process. Channel frontends deliver messages over a
> Unix-domain-socket IPC protocol rather than by direct trait call.
> See amendment
> [`docs/amendments/2026-04-17-daemon-ipc-protocol.md`](docs/amendments/2026-04-17-daemon-ipc-protocol.md)
> for the daemon execution topology, IPC envelope types, and
> multi-connection model that implement this contract in production.
> See also amendment
> [`docs/amendments/2026-04-17-mission-state-machine.md`](docs/amendments/2026-04-17-mission-state-machine.md)
> for the fifth termination condition (`TurnOutcome::Escalated` as
> mission gate suspension).
>
> **Amendment (2026-04-21):** The IPC protocol now supports optional
> version negotiation via `ProtocolNegotiation`/`ProtocolAccepted`/
> `ProtocolRejected` messages. For v0.1, the daemon always accepts.
> The daemon also writes a `daemon.state` file for crash recovery
> and emits `RecoveryNotice` lifecycle events on restart after
> unclean shutdown. See amendment
> [`docs/amendments/2026-04-21-protocol-negotiation.md`](docs/amendments/2026-04-21-protocol-negotiation.md).
---
---
## Deliverable 2 — The Open-Core Line (LOCKED 2026-04-13)
> **Amendment A14 (2026-06-19) — relicense MIT → BUSL-1.1.** Chapter Charter
> ([`docs/LICENSING.md`](docs/LICENSING.md),
> [Amendment A14](docs/amendments/2026-06-19-busl-relicense.md)) supersedes the
> *mechanism* of this Deliverable. Every "MIT" entry in the rule and tables below
> now reads **"BUSL-1.1 (→ MIT after 4 years)"**: the whole public workspace is
> **source-available under BUSL-1.1** — free for personal/non-commercial use,
> paid for commercial use, auto-reverting to MIT four years after each release.
> The *spirit* (auditable free core + sustainable commercial side) is preserved
> and strengthened — the core now carries its own monetization hook, not just the
> separate products below. v0.2.0 and prior remain MIT in perpetuity. The
> branding exception is unchanged in substance (`aivyx-pa` is now "BUSL-1.1 +
> branded"). Read the original text below as historical-but-superseded.
### The Rule
> **Protocol and security surface are MIT. Products are commercial.
> Ambiguous cases default to MIT if they would otherwise weaken the
> agent's auditability.**
### How to apply it
For any new crate or component, ask in order:
1. **Is it a protocol?** (Trait, interface, wire format, namespace.) → MIT
2. **Is it a security surface?** (Crypto, capability, audit, auth.) → MIT
3. **Is it a product?** (Runtime, marketplace, hosted service.) → Commercial
4. **If ambiguous:** Would closing it weaken auditability or block
third-party integration? → MIT. Otherwise → Commercial.
### The v1 table
| Crate / Artifact | License | Rationale |
|---|---|---|
| `aivyx-core` | MIT | The protocol itself — traits, IDs, turn loop. |
| `aivyx-crypto` | MIT | Commodity crypto primitives. No moat. |
| `aivyx-capability` | MIT | Security surface. Must be readable to be trustable. |
| `aivyx-audit` | MIT | Security surface. Closed audit is worth less. |
| `aivyx-config` | MIT | Commodity config loader. |
| `aivyx-storage` | MIT | redb + HKDF wrapper. Security surface. |
| `aivyx-channel` | MIT | Trait + `LocalChannel` reference impl. Protocol. |
| `aivyx-llm` | MIT | `LlmProvider` trait + reference impls. Protocol. |
| `aivyx-memory` | MIT | `Memory` trait + default impl. Protocol + commodity. |
| `aivyx-pa` (rebuilt PA) | **MIT + branded** | Code MIT, name/distribution trademarked. |
| Channel adapters (Telegram/Discord/Slack/Matrix/Email) | MIT | Reference impls of `aivyx-channel`. |
**11 crates in v1. All MIT.** The commercial side of the open-core line
is composed entirely of Phase 7+ products built on top of v1.
### Deferred to later phases (not in v1)
| Component | License | Notes |
|---|---|---|
| `aivyx-engine` / factory | Commercial | Multi-tenant runtime. The product. |
| `aivyx-hub` | Commercial | Marketplace + network effects. |
| `aivyx-federation` | Commercial *(tentative)* | Revisit when built. |
| `aivyx-mcp` | MIT *(when built)* | Bridge to an open protocol. |
### The branding exception (aivyx-pa)
`aivyx-pa` is MIT + branded. This means:
- **The code** is MIT-licensed. Anyone can fork, modify, redistribute,
commercialize.
- **The name, logo, and official distribution channels** are trademarked.
A fork cannot call itself "Aivyx PA" or ship via Aivyx-branded app
store listings, official installers, or aivyx.ai domains.
- Enforcement: trademark, not license. `LICENSE` says MIT; `TRADEMARK.md`
documents the brand restriction.
- Precedents: Code-OSS / VSCode, Chromium / Chrome, Firefox / Iceweasel.
---
## Deliverable 3 — Agent Trait + Outcome Types (LOCKED 2026-04-13)
Pseudo-code sketches, not compilable Rust. The goal is pinning down shapes
and names, not producing something `cargo check` accepts. Supporting types
(`TrustTier`, `CapabilitySet`, `Scope`, `AivyxError`) are referenced here
and defined in later deliverables.
### Message — the inbound unit
```rust
pub struct Message {
pub id: MessageId,
pub session_id: SessionId,
pub content: MessageContent,
pub received_at: SystemTime,
}
pub enum MessageContent {
Text(String),
// Phase 2: Image, Audio, File, StructuredData
}
```
> **Multimodal extension** — the actual `MessageContent` /
> `ContentPart` enums in `aivyx-core` carry `Image` and
> `Document` variants alongside `Text`. The `Image` variant
> landed during the multimodal MVP work; the `Document`
> variant is governed by
> [`docs/amendments/2026-06-04-content-part-document.md`](docs/amendments/2026-06-04-content-part-document.md)
> (A13) so PDFs route to provider-specific document content
> blocks rather than image blocks.
### ChannelContext — the delivery surface
```rust
#[async_trait]
pub trait ChannelContext: Send + Sync {
fn channel_name(&self) -> &str;
fn platform(&self) -> ChannelPlatform;
fn trust_tier(&self) -> TrustTier;
fn session_id(&self) -> SessionId;
async fn stream_event(&self, event: StreamEvent<'_>) -> Result<(), ChannelError>;
async fn finalize(&self, outcome: &TurnOutcome) -> Result<(), ChannelError>;
fn cancellation_token(&self) -> CancellationToken;
}
pub enum ChannelPlatform {
Local, // CLI, desktop app
Telegram,
Discord,
Slack,
Matrix,
Email,
Rest, // HTTP API
// extensible
}
pub enum StreamEvent<'a> {
/// LLM token stream — the 95% case.
Text(&'a str),
/// Status signal for long-running tools: "Searching…", "Downloading…".
Status(&'a str),
/// A tool call is about to execute. Channels may render (e.g., GUI)
/// or ignore (e.g., minimal REST channels).
ToolCallStarted {
tool: ToolId,
input: &'a serde_json::Value,
},
/// A tool call finished. Outcome summary is a human-readable
/// one-liner, not a structured result.
ToolCallFinished {
tool: ToolId,
outcome_summary: &'a str,
},
/// File, image, or audio attachment. Matrix/Email channels use
/// this on day one when they're rebuilt.
Attachment {
kind: AttachmentKind,
data: &'a [u8],
filename: Option<&'a str>,
},
}
pub enum AttachmentKind {
Image { mime: &'static str }, // e.g., "image/png"
Audio { mime: &'static str },
File { mime: &'static str },
}
```
**Key commitments:**
- `&dyn ChannelContext` at trait boundaries (dynamic dispatch — swapping channels at runtime is worth the cost)
- `trust_tier()` is *read* from the channel, not set on it
- **`stream_event` is a rich enum from day one** (decision: "start how we mean to go on"). Text is the 95% case; Status / ToolCallStarted / ToolCallFinished / Attachment cover the rest.
- `StreamEvent<'a>` is borrowed — agents build events that reference their own buffers without allocating. Channels that need ownership can serialize or clone.
- Channels are free to **ignore** any variant they don't care about. `StreamEvent` is a superset of what a rich channel *can* do, not a minimum every channel must honor.
- MIME types are `&'static str` for now — small, finite, auditable set. Promote to `Cow<'static, str>` if user-supplied MIMEs become necessary.
- `cancellation_token` resolves scenario-4 ambiguity: cancellation is checked between LLM steps, not mid-tool-call
### ToolOutcome — with typed verification
```rust
pub enum ToolOutcome {
Completed {
output: serde_json::Value,
verified: Verification,
},
Denied {
scope: Scope,
held: CapabilitySet,
},
RequiresEscalation {
reason: String,
},
Failed(AivyxError),
}
pub enum Verification {
/// Tool queried the system and confirmed its effect happened.
Verified,
/// Tool returned Ok but did not verify.
Unverified,
/// Verification not meaningful (e.g., pure read-only query).
NotApplicable,
}
```
**Why `Verification` is an enum, not a bool:** `NotApplicable` captures
the "calculator doesn't need to verify 2+2=4" case explicitly, so tool
authors don't lie by marking everything `Verified`. Encodes
`feedback_tool_success_vs_intent.md` at the type level.
### TurnOutcome — the five termination paths
```rust
pub enum TurnOutcome {
Completed {
final_message: String,
tool_calls_made: usize,
duration: Duration,
},
Escalated {
reason: String,
pending_tool: ToolId,
tool_calls_made: usize,
},
TimedOut {
tool_calls_made: usize,
elapsed: Duration,
},
Cancelled {
tool_calls_made: usize,
},
Failed(AivyxError),
}
```
Five variants matching the four paragraph-named termination conditions
plus failure. No `AwaitingInput` — speculative, not needed yet.
### Agent — four lines
```rust
#[async_trait]
pub trait Agent: Send + Sync {
fn id(&self) -> AgentId;
fn capabilities(&self) -> &CapabilitySet;
async fn turn(
&self,
message: Message,
channel: &dyn ChannelContext,
) -> TurnOutcome;
}
```
**Key commitments:**
- `&self`, not `&mut self` — agents shared across concurrent turns via `Arc<dyn Agent>`
- Returns `TurnOutcome` directly, **not** `Result<TurnOutcome, _>`. Any error is part of the turn's history (`Failed(AivyxError)` variant). A turn always *completes in some way*.
- No explicit timeout parameter — budget lives in the agent's config
- No session parameter — `session_id` lives inside `Message`
**The unusual choice:** returning `TurnOutcome` rather than `Result<TurnOutcome, _>`
is contrarian. The Rust instinct is to surface errors in the type. But for
`turn`, errors are *part of what happened*, audited inline, and need to be
rendered by the channel. Burying them inside `TurnOutcome::Failed` keeps
the return type honest about "every turn completes."
### Tool — with ToolContext
```rust
#[async_trait]
pub trait Tool: Send + Sync {
fn id(&self) -> ToolId;
fn name(&self) -> &str;
fn description(&self) -> &str;
fn input_schema(&self) -> &serde_json::Value; // JSON Schema
fn required_scope(&self) -> Scope;
async fn execute(
&self,
input: serde_json::Value,
context: &ToolContext<'_>,
) -> ToolOutcome;
}
pub struct ToolContext<'a> {
pub agent_id: AgentId,
pub session_id: SessionId,
pub channel: &'a dyn ChannelContext,
pub audit: &'a dyn AuditWriter,
pub cancellation: &'a CancellationToken,
}
```
**Key commitments:**
- `execute` returns `ToolOutcome` directly, same pattern as `Agent::turn`
- `ToolContext` gives tools access to channel (progress streaming), audit writer (structured entries), and cancellation
- `required_scope` returns single `Scope` — composite-scope handling deferred to Deliverable 4
### Paragraph-to-type traceability
Every clause in the Deliverable 1 paragraph traces to a concrete type
operation:
| Paragraph clause | Type operation |
|---|---|
| "ChannelContext delivers Message to Agent" | `agent.turn(message, channel)` |
| "resolves the channel's trust tier" | `channel.trust_tier()` |
| "loads the corresponding CapabilitySet" | Agent attenuates `self.capabilities()` by trust tier |
| "tool-calling loop with its LlmProvider" | Internal `llm.chat_stream(...)` |
| "streamed text to relay back through the channel" | `channel.stream_event(StreamEvent::Text(chunk)).await` |
| "scope-checked before execution" | `if !caps.grants(tool.required_scope())` → `ToolOutcome::Denied` |
| "on completion returns a ToolOutcome" | `tool.execute(input, &ctx).await` |
| "distinguishes Ok from intended effect" | `ToolOutcome::Completed { verified: Verification }` |
| "HMAC-chained audit synchronously as it happens" | `ctx.audit.append(entry).await` (blocking) |
| "LLM emits a final assistant message" | Stream end → `TurnOutcome::Completed` |
| "tool call returns RequiresEscalation" | Match on `ToolOutcome::RequiresEscalation` → `TurnOutcome::Escalated` |
| "timeout fires" | Elapsed > budget → `TurnOutcome::TimedOut` |
| "channel cancels" | `cancellation.is_cancelled()` → `TurnOutcome::Cancelled` |
| "returning TurnOutcome to the channel" | `channel.finalize(&outcome).await; outcome` |
| "yielding control" | Function returns, tokio yields to runtime |
The paragraph compiles.
### Deliberately omitted from this sketch
- **`LlmProvider`** — already stable in the archived codebase, re-derived in Phase 1 without design changes
- **`AuditWriter` full definition** — referenced in `ToolContext`, fully defined in Deliverable 6 (error contract) or a separate audit deliverable
- **`SessionStore` / `MemoryStore`** — implementation details of concrete agents, not core contracts. Memory is a tool (Deliverable 1 commitment A2); underlying storage is private to the concrete agent
- **Agent construction / builder** — the sketch shows what an agent *is*, not how to build one. Builder lives in concrete impl
> **Amendment (2026-04-17):** The `ChannelContext` trait is now
> implemented twice per channel: once for in-process mode (the
> original adapter) and once for daemon mode (`IpcChannelBridge`
> on the server side). `StreamEvent<'a>` has an owned IPC mirror
> (`StreamEventPayload`) for serialization over the wire. See
> amendment
> [`docs/amendments/2026-04-17-daemon-ipc-protocol.md`](docs/amendments/2026-04-17-daemon-ipc-protocol.md).
---
## Deliverable 4 — Capability Taxonomy (LOCKED 2026-04-13)
Four foundational decisions (locked):
- **Scope shape**: hierarchical strings with a type wrapper (`Scope(String)`)
- **Attenuation**: prefix-based (glob / URL-prefix / allowlist / simple-glob)
- **Taxonomy completeness**: start with ~20 active scopes, reserve the rest
- **Audit events**: per-tool for grants, per-scope for denials, with dedicated `MemoryAccess` for queryability
### The Scope type
```rust
/// Hierarchical string form: `base` or `base:qualifier`.
/// Base is a dotted identifier; qualifier is an optional attenuation string.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Scope(String);
impl Scope {
/// Returns None if the base is not a known scope in v1 or any registered extension.
pub fn parse(s: &str) -> Option<Scope>;
pub fn base(&self) -> &str;
pub fn qualifier(&self) -> Option<&str>;
/// Prefix-attenuation check: true iff `self` is granted by `other`.
pub fn is_granted_by(&self, other: &Scope) -> bool;
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CapabilitySet {
scopes: Vec<Scope>, // deduplicated, sorted for deterministic serialization
}
impl CapabilitySet {
pub fn empty() -> Self;
pub fn from_scopes(scopes: impl IntoIterator<Item = Scope>) -> Self;
pub fn grants(&self, needed: &Scope) -> bool;
pub fn intersect(&self, other: &CapabilitySet) -> CapabilitySet;
pub fn iter(&self) -> impl Iterator<Item = &Scope>;
}
```
**Key commitments:**
- `Scope::parse` returns `Option` — unknown scopes fail at parse time, not check time. Registration lives in `aivyx-capability`.
- `is_granted_by` is the *only* authoritative check function. No scattered string comparisons.
- `CapabilitySet::intersect` is how trust tiers cap agent caps: `effective = agent_caps.intersect(&tier_ceiling)`.
- Sorted vec, not HashSet — deterministic serialization is required for HMAC-chained audit.
### Attenuation rules
When a scope has a qualifier, `is_granted_by` applies:
1. **Bases must match exactly.** `fs.read:/foo` is not granted by `fs.write:/foo`.
2. **Unqualified held grants any qualified needed** with the same base.
3. **Qualified held grants qualified needed** iff the qualifier matches:
- Path-like (`/` or contains `/`): glob semantics
- URL-like (contains `://`): URL prefix match
- Allowlist (comma-separated idents): superset check
- Simple glob: glob match on the string
4. **Qualified held does NOT grant unqualified needed.** A tool requesting bare `fs.read` wants unrestricted access; a restricted capability cannot grant that.
Rule 4 is intentional: tools must be specific. Unrestricted requests are visible to users at the capability-set level and require justification.
### The v1 active namespace (21 scopes)
**`fs` — filesystem**
| Scope | Qualifier | Description |
|---|---|---|
| `fs.read` | path glob | Read file contents or list directory |
| `fs.write` | path glob | Create or overwrite file |
| `fs.delete` | path glob | Remove file or directory |
| `fs.metadata` | path glob | Stat — size, mtime, perms. Weaker than fs.read. |
**`net` — network**
| Scope | Qualifier | Description |
|---|---|---|
| `net.fetch` | URL prefix | HTTP GET / HEAD |
| `net.post` | URL prefix | HTTP POST / PUT / PATCH / DELETE |
| `net.dns` | domain glob | Hostname resolution |
**`shell` — subprocess**
| Scope | Qualifier | Description |
|---|---|---|
| `shell.exec` | command allowlist | Run a command, capture output |
| `shell.spawn` | command allowlist | Spawn long-lived subprocess |
**`git` — version control** *(read added in Amendment A12, Phase 109; write added in Amendment A13b, Chapter Forge)*
| Scope | Qualifier | Description |
|---|---|---|
| `git.read` | repo path glob | Read repo state — `git.status` and `git.diff` share this base |
| `git.write` | repo path glob | Write repo history — `git.commit` (stage + commit); Trusted-tier only, confirm-first |
> **Amendment (2026-05-28):** `git.read` joins the substrate
> base table as the qualifier-by-repo-path gate for the
> `git.status` + `git.diff` tools added in Phase 109. See
> amendment
> [`docs/amendments/2026-05-28-substrate-tool-count-thirteen.md`](docs/amendments/2026-05-28-substrate-tool-count-thirteen.md)
> for the P10 count update from ten to thirteen and the
> shared-scope-base rationale (one `git.read` rather than
> separate `git.status` / `git.diff` bases, mirroring the
> read-invariant grouping).
>
> **Amendment (2026-06-19):** `git.write` joins the table as the
> destructive sibling A12 anticipated — the qualifier-by-repo-
> path gate for the `git.commit` tool (Chapter Forge). It reuses
> `git.read`'s `[git] repos` allow-set, sits at `CEILING_TRUSTED`
> only (writing history is as sensitive as `shell.exec` /
> `fs.delete`), and is confirm-first when `confirm_destructive`
> is on. See amendment
> [`docs/amendments/2026-06-19-substrate-tool-count-fifteen.md`](docs/amendments/2026-06-19-substrate-tool-count-fifteen.md)
> for the P10 count update from thirteen to fifteen (also adding
> `web.extract` over the existing `net.fetch` base).
**`skills` — learned procedural pattern surface** *(added in Phase 110)*
| Scope | Qualifier | Description |
|---|---|---|
| `skills.propose` | — | Propose a `LearnedSkill` delta through `reflection.propose` |
| `skills.list` | — | Enumerate operator-approved skills |
| `skills.invoke` | — | Render the full procedure body of one approved skill |
> **Phase 110 — Skills Auto-Creation (Reflection Staging).**
> Three new scope bases gate the skills primitive:
> `skills.propose` is the sibling capability to
> `persona.propose` for proposals whose `persona_deltas` array
> contains any `PersonaDeltaCategory::LearnedSkill` entry
> (Q2b at Phase 110 sign-off — operator picked per-category
> granularity over extending `persona.propose`).
> `skills.list` and `skills.invoke` gate the two substrate
> tools that let agents read the approved skill set
> (enumeration vs. on-demand procedure-body render). All three
> bases live in `CEILING_TRUSTED` only; SemiTrusted remote
> adapters do not get skills.* by default. **No amendment
> filed** — Phase 110 stays inside PRODUCT.md P8's
> outcome-driven-audited-reflection envelope; the
> propose-approve-apply shape P8 commits to is unchanged, and
> the LearnedSkill extension is a new category inside that
> shape rather than a new commitment. P10's substrate tool
> count was last set to thirteen at A12 (Phase 109); skills.*
> tools are **infrastructure tools** per P10's
> substrate/infrastructure/third-party taxonomy (the agent
> uses them to manage itself's identity layer) so they are
> not counted against P10's substrate-tool cap.
**`graph` — typed knowledge graph** *(added in Chapter Lattice)*
| Scope | Qualifier | Description |
|---|---|---|
| `graph.read` | — | Query the agent's typed knowledge graph — a read-only multi-hop directed traversal (`graph.query`) |
> **Chapter Lattice — typed knowledge graph.** `graph.read`
> gates `graph.query`, a read-only multi-hop traversal of the
> agent's own knowledge graph (entities + directed
> `(subject)-[predicate]->(object)` relations extracted from
> memory). Like `skills.*`, it is an **infrastructure tool**
> per P10's taxonomy — the agent querying its own *derived*
> self-knowledge, not a new operator-owned resource primitive —
> so it grows `KNOWN_BASES` (86 → 87) **without a P10 substrate-
> count amendment**, exactly the `skills.*` / `loop.*` /
> `reflection.*` precedent. Bare base (like `skills.list`),
> `CEILING_TRUSTED` only; SemiTrusted does not get it by
> default. See
> [`docs/amendments/2026-04-17-capability-taxonomy-growth.md`](docs/amendments/2026-04-17-capability-taxonomy-growth.md)
> (Lattice addendum).
**`llm` — language model**
| Scope | Qualifier | Description |
|---|---|---|
| `llm.call` | model name glob | Chat endpoint call |
| `llm.embed` | model name glob | Embedding endpoint call |
**`memory` — agent memory**
| Scope | Qualifier | Description |
|---|---|---|
| `memory.read` | session/topic glob | Recall entries matching a query |
| `memory.write` | session/topic glob | Store entry |
| `memory.forget` | session/topic glob | Delete entries matching filter |
**`channel` — communication**
| Scope | Qualifier | Description |
|---|---|---|
| `channel.send` | channel name glob | Send on an outbound channel (not necessarily the inbound one) |
| `channel.receive` | channel name glob | Listen on a channel |
The turn's own inbound channel is **implicitly granted** — you don't need `channel.send` to reply where the message came from.
**`audit` — introspection**
| Scope | Qualifier | Description |
|---|---|---|
| `audit.read` | event type glob | Read audit log entries |
There is no `audit.write`. Only the kernel writes audit entries.
**`config` — configuration**
| Scope | Qualifier | Description |
|---|---|---|
| `config.read` | key glob | Read config value |
| `config.write` | key glob | Update config value |
### Reserved — named but not defined in v1
These are part of the public namespace but have no implementation. Any
tool using them fails at `Scope::parse` time until promoted.
- **Agent coordination**: `agent.spawn`, `agent.delegate`, `agent.terminate`
- **Scheduling**: `schedule.create`, `schedule.read`, `schedule.delete`, `schedule.run`
- **System**: `system.shutdown`, `system.notify`, `system.clipboard_read`, `system.clipboard_write`
- **Display / window**: `display.window_focus`, `display.window_close`, `display.screenshot`
- **Federation** (Phase 7+): `federation.discover`, `federation.call`, `federation.accept`
### Audit event naming (mixed model)
```rust
pub enum AuditEvent {
/// A tool executed. Primary key: tool_id.
ToolCall {
tool_id: ToolId,
scope_used: Scope,
input_hash: [u8; 32], // hash, not raw input — secrets safety
outcome: ToolOutcomeSummary,
duration: Duration,
},
/// A scope check denied a tool call. Primary key: scope.
ScopeDenied {
scope_requested: Scope,
scope_qualifier: Option<String>,
tool_attempted: ToolId,
held_capabilities: CapabilitySet, // snapshot, not reference
},
/// Turn started — for correlation via turn_id.
TurnStarted {
turn_id: TurnId,
session_id: SessionId,
channel: ChannelPlatform,
trust_tier: TrustTier,
effective_capabilities: CapabilitySet,
},
/// Turn ended — paired with TurnStarted.
TurnEnded {
turn_id: TurnId,
outcome: TurnOutcomeSummary,
tool_calls_made: usize,
duration: Duration,
},
/// Dedicated view of memory operations for queryability.
/// Redundant with ToolCall (every memory op is also a tool call).
MemoryAccess {
turn_id: TurnId,
operation: MemoryOperation,
scope: Scope,
query_or_key: String,
},
}
pub enum MemoryOperation { Read, Write, Forget }
```
**Commitments:**
- Every event is self-contained — readable without cross-referencing others.
- `input_hash` (not raw input) prevents secrets leaking into the audit log.
- `held_capabilities` on denials is a snapshot — the set at denial time is preserved even if caps change later.
- `MemoryAccess` is redundant with `ToolCall` but indexed for fast memory-specific queries. This is the one deviation from the strict mixed model.
### Findings from sanity-checking against D1 scenarios
**A. `required_scope()` needs to be computable from input, not static.**
A tool may need different scopes depending on its arguments. The `Tool`
trait's `required_scope()` should become:
```rust
fn required_scope(&self, input: &serde_json::Value) -> Scope;
```
This lets a memory-recall tool request `memory.read:session:<id>` when
called with a specific session ID, or bare `memory.read` when called
with no filter. **Update to Deliverable 3 pending** — will fold into the
final D3 skeleton during Phase 1 trait design.
**B. Scenario 2 (window close) requires scopes in the Reserved section.**
The v1 PA does not handle window control. Window-control tools and their
scopes (`display.window_close`, etc.) are deferred to Phase 1, when the
tool crate is built. The Reserved section already lists them; they'll be
promoted to active when the tool lands.
> **Amendment (2026-04-17):** The capability taxonomy has grown
> from 12 to 23 known bases across Phases 1–21. Two bases
> added by Phase 21 (`mission.create`, `mission.gate`) are
> infrastructure tools per P10's taxonomy. See amendment
> [`docs/amendments/2026-04-17-mission-state-machine.md`](docs/amendments/2026-04-17-mission-state-machine.md)
> for the mission-specific bases and amendment
> [`docs/amendments/2026-04-17-capability-taxonomy-growth.md`](docs/amendments/2026-04-17-capability-taxonomy-growth.md)
> for the full 23-base inventory.
---
## Deliverable 5 — Trust Tier Model (LOCKED 2026-04-13)
### The TrustTier type
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum TrustTier {
/// Tier 3 — Untrusted. Public webhooks, anonymous HTTP, unknown senders.
Untrusted,
/// Tier 2 — SemiTrusted. Authenticated user on a remote channel.
SemiTrusted,
/// Tier 1 — Trusted. Authenticated user on an owned channel.
Trusted,
/// Tier 0 — Kernel. Unconditional. Never assigned to a user-facing channel.
Kernel,
}
impl TrustTier {
pub fn default_ceiling(self) -> &'static CapabilitySet;
pub fn is_more_trusted_than(self, other: TrustTier) -> bool;
}
```
**Note on ordering:** the variants are declared in *ascending trust order*
so the derived `Ord` gives `Kernel > Trusted > SemiTrusted > Untrusted`.
The display-label numbers (Tier 0 = Kernel, Tier 3 = Untrusted) run
opposite to `Ord`. The numeric labels are a *naming convention*; the
ordering used in code is the enum's `Ord`.
### Tier definitions
**Tier 0 — Kernel.** Unconditional. The turn loop itself, audit writer,
capability enforcer, storage encryption. Never held by a user-facing
channel — a channel returning `Kernel` from `trust_tier()` is a bug.
Default ceiling: unlimited. Exists so internal operations pass capability
checks without being special-cased as "exempt."
**Tier 1 — Trusted.** Authenticated user on an owned channel:
- Local CLI
- Desktop GUI (Tauri app on own machine)
- Local REST API bound to 127.0.0.1 only
The user is presumed present; the channel cannot be reached from the
network without explicit local access. Default ceiling: near-total, with
extra audit on `fs.delete` / `shell.exec` / `shell.spawn`.
**Tier 2 — SemiTrusted.** Authenticated user on a remote channel:
- Telegram DMs from allowlisted user
- Slack DMs from allowlisted user
- Matrix rooms where sender is authenticated
- Email from SPF/DKIM-verified, allowlisted sender
- Discord DMs from allowlisted user
The user is identified but the transport is out of our control; identity
verification is best-effort. Default ceiling: substantially narrower
than Tier 1 — no unqualified shell, no `fs.delete`, no `config.write`,
remote-write/remote-post require explicit qualifiers.
**Tier 3 — Untrusted.** Anonymous or unverified contexts:
- WhatsApp webhooks (public, HMAC-verified but sender spoofable)
- Anonymous HTTP endpoints (if they exist)
- Email from non-allowlisted senders
- Any context where identity cannot be trusted
Default ceiling: near-empty. Channels at this tier can *deliver* a
message but the agent cannot exercise meaningful capabilities — only
canned responses or public-safe reads.
### Per-tier ceiling table
Notation: ✓ = granted unqualified, ▲ = granted only with explicit
qualifier, ⊘ = denied entirely.
| Scope | Tier 1 (Trusted) | Tier 2 (SemiTrusted) | Tier 3 (Untrusted) |
|---|---|---|---|
| `fs.read` | ✓ | ▲ path qualifier required | ⊘ |
| `fs.write` | ✓ | ▲ path qualifier required | ⊘ |
| `fs.delete` | ✓ (audited) | ⊘ | ⊘ |
| `fs.metadata` | ✓ | ✓ | ⊘ |
| `net.fetch` | ✓ | ✓ | ⊘ |
| `net.post` | ✓ | ▲ URL prefix required | ⊘ |
| `net.dns` | ✓ | ✓ | ⊘ |
| `shell.exec` | ✓ (audited) | ⊘ | ⊘ |
| `shell.spawn` | ✓ (audited) | ⊘ | ⊘ |
| `llm.call` | ✓ | ✓ | ⊘ |
| `llm.embed` | ✓ | ✓ | ⊘ |
| `memory.read` | ✓ | ✓ | ▲ `memory.read:scope:public:*` only |
| `memory.write` | ✓ | ✓ | ⊘ |
| `memory.forget` | ✓ | ▲ scope qualifier required | ⊘ |
| `channel.send` | ✓ | ▲ channel allowlist | ⊘ |
| `channel.receive` | ✓ | ▲ channel allowlist | ⊘ |
| `audit.read` | ✓ | ▲ event type qualifier | ▲ `audit.read:public` only |
| `config.read` | ✓ | ✓ | ⊘ |
| `config.write` | ✓ | ⊘ | ⊘ |
**The ▲ semantic:** when a tier grants a scope "only with qualifier,"
held capability must be a *qualified* form — holding bare `fs.write`
does NOT satisfy `▲` at Tier 2. Remote channels must request narrowly
scoped capabilities, not broad ones.
### The effective-capabilities computation
```rust
// Inside Agent::turn, exactly once before the tool-calling loop:
let tier = channel.trust_tier();
let ceiling = tier.default_ceiling();
let effective = self.capabilities().intersect(ceiling);
```
**Commitments:**
- Computed **once per turn**, before any LLM call. Not recomputed mid-turn.
- Recorded as `effective_capabilities` in the `TurnStarted` audit event.
- This snapshot is authoritative for the entire turn.
- Mid-turn capability changes (e.g., user-confirmed escalation) are NOT
supported in v1 — they're a dedicated escalation mechanism, out of scope.
### Design principle — "build narrower tools, don't loosen ceilings"
When a tier can't execute a scope and you want that capability from that
tier, the right answer is **a dedicated narrower-scope tool**, not a
ceiling relaxation. Example:
- Problem: "I want `git status` to work from Telegram"
- Wrong fix: grant `shell.exec` at Tier 2
- Right fix: build a `git.status` tool that holds a narrower scope
(e.g., `git.read:<repo>`) which is grantable at Tier 2
This keeps the ceilings stable and the attack surface understandable.
Every loosened ceiling is a new class of attack; every narrower tool is
a new controlled primitive.
### Sanity check against D1 scenarios
| Scenario | Tier | Outcome |
|---|---|---|
| "What did I work on yesterday" (CLI) | Trusted | ✓ `memory.read:session:*` granted, tool runs |
| "Close terminal window" | Trusted | Deferred — window scopes are Reserved |
| "Run rm -rf from Telegram" | SemiTrusted | ⊘ `shell.exec` denied by ceiling, `ToolOutcome::Denied` |
| "git status from Telegram" | SemiTrusted | ⊘ Same denial — use a dedicated `git.status` tool |
| User cancellation mid-turn | Any | Tier-independent, handled by `cancellation_token` |
---
## Deliverable 6 — Error Contract (LOCKED 2026-04-13)
### The variants (14 of a 15-variant cap)
```rust
#[derive(Debug, thiserror::Error)]
pub enum AivyxError {
// Configuration & Startup
#[error("configuration error: {0}")]
Config(String),
#[error("storage error: {0}")]
Storage(#[from] StorageError),
#[error("crypto error: {0}")]
Crypto(#[from] CryptoError),
// Capability & Trust
#[error("capability denied: scope {scope} not held")]
CapabilityDenied { scope: Scope, held: CapabilitySet },
#[error("invalid scope: {0}")]
InvalidScope(String),
// Agent Turn Execution
#[error("LLM provider error: {0}")]
Llm(#[from] LlmError),
#[error("tool error in {tool}: {source}")]
Tool {
tool: ToolId,
#[source]
source: Box<dyn std::error::Error + Send + Sync>,
},
#[error("tool {tool} requires escalation: {reason}")]
ToolEscalation { tool: ToolId, reason: String },
// Channel & Transport
#[error("channel error: {0}")]
Channel(#[from] ChannelError),
// Audit & Integrity
#[error("audit integrity error: {0}")]
Audit(String),
// Time & Cancellation
#[error("operation timed out after {0:?}")]
Timeout(std::time::Duration),
#[error("operation cancelled")]
Cancelled,
// Lookup & Identity
#[error("not found: {kind} {id}")]
NotFound { kind: &'static str, id: String },
// Catch-all
#[error("internal error: {0}")]
Internal(String),
}
```
### Why each variant exists
| Variant | Source in D1–D5 | Why not another variant |
|---|---|---|
| `Config` | D7 config loading | Startup failures, before any tool/channel exists |
| `Storage` | D7 redb wrapping | Rich nested failure modes (corruption, locking, crypto) |
| `Crypto` | D2, D7 | Rich nested failure modes (AEAD, HKDF, Argon2) |
| `CapabilityDenied` | D4, D5 | Carries scope + held set for diagnostics |
| `InvalidScope` | D4 `Scope::parse` | Parse failure is distinct from check failure |
| `Llm` | D1 tool loop | Rich nested: rate limits, context overflow, auth |
| `Tool` | D1, D3 `ToolOutcome::Failed` | Plugin surface — source is erased |
| `ToolEscalation` | D1, D3 `RequiresEscalation` | Not a failure — a structured pause request |
| `Channel` | D1, D3 `stream_event` | Platform-specific failures preserved in nested type |
| `Audit` | D1 HMAC-chained audit | Integrity failures are their own class — not `Storage` |
| `Timeout` | D1, D3 `TimedOut` | Unambiguous, carries budget |
| `Cancelled` | D1, D3 `Cancelled` | User-initiated, not a real error — separable in match |
| `NotFound` | D3 lookups | `kind` field avoids needing 4 variants |
| `Internal` | Last resort | Should be rare; each usage tagged TODO for promotion |
### Nested error types (not counted against the cap)
Four variants wrap nested types that live in their own crates and can be
as rich as needed: `StorageError`, `CryptoError`, `LlmError`, `ChannelError`.
Top-level `AivyxError` captures **kind for a caller's purposes** (retry?
escalate? give up?); nested enums capture **detail for a debugger's
purposes**.
### The design rule
> **Adding a 15th variant requires a design note in DESIGN.md explaining
> why no existing variant fits. Adding a 16th requires a conversation.**
This is the forcing function against drift. The archived codebase had 22
variants; the cap keeps future-us honest.
### Match rule at call sites
> **Match specifically what you can handle; propagate the rest with `?`.**
Don't catch `AivyxError` wholesale. Catch `CapabilityDenied` to trigger
escalation, `Timeout` to retry, `Cancelled` to clean up. Let everything
else propagate. The turn loop is the outermost matcher and converts each
to the appropriate `TurnOutcome`.
---
## Deliverable 7 — Storage Decision (LOCKED 2026-04-13)
### The stack (carried over from the archive, unchanged)
- **redb** — embedded pure-Rust ACID KV store, single file, cross-platform
- **ChaCha20-Poly1305** — at-rest encryption (AEAD, constant-time)
- **Argon2id** — passphrase → master key (m=64MB, t=3, p=4 starting params, tunable)
- **HKDF-SHA256** — domain-separated subkey derivation from master
- **Single-writer, single-process** — explicit non-goal to support otherwise
### HKDF domain list
```rust
pub enum KeyDomain {
Sessions, // session metadata, turn history
Memory, // memory.read / memory.write substrate
Audit, // HMAC-chained audit log entries
Secrets, // encrypted config values (API keys, tokens)
ChannelState, // per-channel persistent state (Matrix sync tokens, IMAP UIDs, etc.)
}
```
Subkey derivation:
```
subkey_{domain} = HKDF-SHA256(
ikm = master_key,
salt = "aivyx-v1-storage", // versioned, allows clean key rotation
info = domain.as_bytes(), // "sessions" | "memory" | ...
length = 32 // ChaCha20-Poly1305 key size
)
```
The **versioned salt** is new in the rebuild. Bumping to `"aivyx-v2-storage"`
later produces entirely different subkeys from the same master, enabling
clean migration.
### Three changes from the archive
1. **Versioned HKDF salt** (above) — enables clean key-schedule migration.
2. **Passphrase prompt lives in the channel adapter, not the storage
layer.** In the archive, `aivyx serve` prompted directly at startup,
mixing concerns. In the rebuild, the **local CLI channel** obtains
the passphrase (terminal prompt, OS keyring, env var, test fixture)
and passes the *derived master key* to the agent at construction.
Storage never sees raw passphrases. Different channels can use
different passphrase flows.
3. **Storage is opened once per process.** The archive had paths that
re-opened redb per-request in the HTTP layer. The rebuild commits to
**one open redb handle per running process**, held in the concrete
agent impl. `StorageHandle` is `Clone + Send + Sync`, wrapping
`Arc<Database>`.
### Storage trait (high-level sketch)
```rust
#[async_trait]
pub trait Storage: Send + Sync {
async fn open(config: &StorageConfig, master_key: &MasterKey) -> Result<Self, StorageError>
where
Self: Sized;
fn domain(&self, domain: KeyDomain) -> DomainHandle;
async fn flush(&self) -> Result<(), StorageError>;
}
pub struct DomainHandle { /* wraps a redb table + subkey */ }
impl DomainHandle {
pub async fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, StorageError>;
pub async fn put(&self, key: &[u8], value: &[u8]) -> Result<(), StorageError>;
pub async fn delete(&self, key: &[u8]) -> Result<(), StorageError>;
pub async fn scan(&self, prefix: &[u8]) -> Result<BoxStream<'_, Result<(Vec<u8>, Vec<u8>), StorageError>>, StorageError>;
}
```
**Commitments:**
- Single `Storage` trait + single concrete impl (`RedbStorage`) in `aivyx-storage`
- `DomainHandle` is per-domain so callers can't leak across domains
- All methods async; redb sync calls wrapped in `spawn_blocking`
- `scan` returns a stream — memory recalls iterate without loading everything
### Non-goals (explicit)
- **No multi-writer.** One process opens the store at a time. Enforced by redb file lock.
- **No distributed replication.** No sharding, no read replicas, no sync-between-devices.
- **No schema migrations framework.** Schema changes are one-off scripts + HKDF salt bump.
---
## Deliverable 8 — Repo Skeleton (LOCKED)
- [x] **Deliverable 8** — Repo skeleton (9-crate workspace, `cargo check` green)
### Workspace layout
```
~/Projects/aivyx/
├── Cargo.toml workspace manifest (resolver = "2", edition 2024)
├── Cargo.lock committed — this workspace produces binaries
├── rust-toolchain.toml pinned stable + rustfmt + clippy
├── DESIGN.md this document
├── LICENSE MIT, © 2026 Julian (Aivyx)
├── TRADEMARK.md MIT + branded usage rule
├── README.md stub pointing at DESIGN.md
├── .gitignore standard Rust ignores (Cargo.lock NOT ignored)
└── crates/
├── aivyx-core/ turn loop, Agent/Tool traits, TurnOutcome
├── aivyx-crypto/ HKDF, ChaCha20-Poly1305, Argon2id
├── aivyx-capability/ Scope, CapabilitySet, TrustTier
├── aivyx-audit/ HMAC-chained audit log
├── aivyx-config/ config loading, secret-field resolution
├── aivyx-storage/ redb-backed, KeyDomain, Storage trait
├── aivyx-llm/ LlmProvider trait + reference impls
├── aivyx-memory/ memory.{read,write,forget} tools
├── aivyx-channel/ ChannelContext, StreamEvent, LocalChannel
└── aivyx-mcp/ MCP client adapter (Phase 23)
```
Every crate is a stub at this point: doc comments pointing at DESIGN.md
deliverables, `#![allow(dead_code)]`, and the minimum placeholder types
referenced by sibling crates (`Agent`, `Tool`, `Message`, `TurnOutcome`,
`ToolOutcome`, `Verification`, `Scope`, `CapabilitySet`, `TrustTier`,
`KeyDomain`). No runtime logic. No dependencies between crates yet —
each one has an empty `[dependencies]` section.
### Verification
`cargo check --workspace` compiles all 11 crates clean on rust 1.85 /
edition 2024 in ~0.03s. The skeleton is the minimum artifact that
proves the design is buildable — it is not an implementation.
> **Amendment (2026-04-17):** The workspace has grown from 9
> to 11 crates (adding `aivyx-telegram` in Phase 8 and
> `aivyx-mcp` in Phase 23), and `aivyx-channel` has expanded
> into the platform's integration
> hub with 15 modules. See amendment
> [`docs/amendments/2026-04-17-workspace-layout.md`](docs/amendments/2026-04-17-workspace-layout.md)
> for the full current layout and module map.
### Phase 1 entry criterion
Phase 1 begins from this commit. The first Phase 1 task is to wire
`aivyx-core` against `aivyx-capability` and `aivyx-channel` to produce
the first compiling (though not yet running) turn-loop skeleton. All
subsequent work happens against trait shapes already locked in
Deliverables 3–7 of this document — any deviation requires a Phase 0
amendment, not a silent drift.
Known Phase 1 refinements already flagged:
- **D3**: `Tool::required_scope` signature should become
`required_scope(&self, input: &Value) -> Scope` to express
input-dependent scope requirements (e.g., `memory.read` needing
different scopes based on session filter). Caught during D4 sanity
check against D1 scenarios.
- **D4**: `display.window_close` and related window-control scopes
are Reserved in v1; promoting them to active is a Phase 1 tool-crate
decision, not a Phase 0 scope taxonomy change.
---
## Status
Phase 0 is closed. This document is the **locked contract** — edits
require an amendment under `docs/amendments/`. For the Phase 0 exit
record and the lessons carried forward, see
[`docs/PHASE_0.md`](docs/archive/phases/PHASE_0.md). For the current phase and its
open tasks, see [`docs/PHASE_1.md`](docs/archive/phases/PHASE_1.md). The split
between this contract document and the per-phase journals is
explained in [`docs/README.md`](docs/README.md).