diff --git a/docs/FEDERATION_V2.md b/docs/FEDERATION_V2.md index 52a98c8..a9d7f8f 100644 --- a/docs/FEDERATION_V2.md +++ b/docs/FEDERATION_V2.md @@ -1,9 +1,9 @@ # Federation v2 — the multi-machine trust architecture (master structure) -> Status: **design**. This is the planned structure for turning the federation layer -> (`council/net/`) into a real multi-machine work marketplace. The security-critical pieces -> (2–4) ship only after a written security review. Built so far this round: the tamper-evident -> result digest (step 1). See `docs/DECISIONS.md` D18 for the governing principles. +> Status: steps 0–3 are **built**, step 4 is **partially built**, and §5 (MCP interop) is +> **built** — this doc originally described all of it as future design; it now records what +> actually shipped, with the D-numbers and rounds. See `docs/DECISIONS.md` D18 for the +> governing principles. ## Governing principles (non-negotiable) @@ -21,7 +21,7 @@ ## The components -### 0. Human-in-the-loop `assisted` task class — the centerpiece +### 0. Human-in-the-loop `assisted` task class — BUILT (D21, R9) — the centerpiece The marketplace capability that makes "computer-use" safe and legal. - New job type `assisted`. The asker submits a brief + the **minimal** context needed. @@ -34,8 +34,10 @@ The marketplace capability that makes "computer-use" safe and legal. - **Licensed-software tasks** are a sub-type: the brief declares "needs your licensed X"; only operators who advertised that capability and opted in are offered it; always-prompt. -Build phases: (a) job type + brief routing + a basic accept/decline operator view; (b) bounded-context -enforcement + per-class consent defaults; (c) licensed-software sub-type + capability gating. +Build phases: (a) job type + brief routing + a basic accept/decline operator view — **done**; (b) +bounded-context enforcement + per-class consent defaults — **done**; (c) licensed-software sub-type + +explicit capability-declaration flags (`licensed-software`, `heavy-compute`) at node registration — +**not built** (verified: no such flags exist in `council/`'s registration code). See D21. ### 1. Tamper-evident results — BUILT Every task result is stored with a canonical SHA-256 (`store.result_digest`), surfaced in @@ -56,22 +58,34 @@ step 2 raises it to defend against a hostile coordinator. - This is the operator's "encryption between computers / no one can inject into the work," at the right layer. -### 3. Content-addressed artifact store + chunking — design -- Deliverables become **files**, not just text rows. Producer splits a file into chunks, hashes each, - and commits a **Merkle root**; coordinator stores opaque (encrypted) blobs keyed by hash; asker - reassembles and verifies against the root. Enables large + resumable + integrity-checked - deliverables. The operator's "split files / share files" idea, done verifiably. +### 3. Content-addressed artifact store + chunking — BUILT (D22, R10) +Deliverables are **files**, not just text rows. `council/artifacts.py` (stdlib only) splits a file +into 256 KiB chunks, sha256-hashes each (the chunk's own address), and records a manifest of +`{name, size, chunk_size, root, chunks:[hashes]}`, where `root` is a flat **Merkle root** (sha256 of +the ordered chunk hashes). The coordinator stores chunks as opaque, deduped, content-addressed blobs; +the asker's receiver verifies every chunk against its hash and the manifest root before reassembling, +and rejects on any mismatch, missing chunk, or path-traversal attempt. Operator side: `pw deliver + @file `; asker side: `pw fetch `. See D22 for auth, caps, and the adversarial +fixes (dedup-per-job PK, blob-presence check before settlement, retention reaper). -### 4. Consent + capability disclosure — design -- Nodes declare which work classes they accept: `research`, `batch` (low-risk, opt-in auto-approve) - and gated classes `assisted`, `licensed-software`, `heavy-compute` (always-prompt). -- Builds on the existing capability profile (models/RAM, `store._meets`) — add work-class consent and - the operator approval surface. No task type is ever offered to a node that didn't opt in. +### 4. Consent + capability disclosure — PARTIALLY BUILT +- **Consent (D53, settled):** operators give class-level consent at `pw join` (which work classes — + research/judging/batch/assisted — their node accepts); `assisted` tasks additionally require + explicit per-task consent via `pw accept`, since that's the sensitive, human-mediated class (D18). +- **Capability gating (D24, settled):** marketplace offers can require a capability/reputation + threshold (`requires.min_reputation`, model/RAM match); enforced at both offer-listing and accept, + fail-closed on a malformed threshold (`store._meets`, `store._meets_reputation` in + `council/net/store.py`). +- **Still open:** explicit `licensed-software`/`heavy-compute` capability-*declaration* flags at node + registration (same gap as §0 phase c) — nodes aren't yet able to advertise these specific + capabilities for gating to key off. -### 5. MCP interop — roadmap -Ship an MCP server so Claude and other agents can call our research/marketplace engine, and let our -nodes call ecosystem tools via MCP. Makes us a node in the agent ecosystem, not a fork. (Prior art: -gpt-researcher's MCP server.) +### 5. MCP interop — BUILT (D19, R7) +`pw mcp` (optional `[mcp]` extra) runs an MCP server (`council/mcp_server.py`, stdio) so Claude +Desktop, Codex, or any MCP client can call the research/marketplace engine as a tool. Exposes 3 tools: +`research`, `library_search`, `library_add`. Makes us a node in the agent ecosystem, not a fork. +(Prior art: gpt-researcher's MCP server.) See D19 for the adversarial-review fixes (path confinement, +ingest caps, sanitized output, stdout-corruption fix). ## Threats this addresses Hostile coordinator (steps 1–2), MITM (2), tampering node operator (1, + existing judge spot-checks &