docs(federation): PRD, milestones, mission manifest, and M1 task breakdown

Plans the Federation v1 mission: cross-instance data federation between Mosaic Stack gateways with asymmetric trust (home gateway sees blended A+B at session time; work gateway sees only its own tenants), mTLS via X.509 / Step-CA for auth, multi-tenant RBAC with no cross-user leakage, and no data persistence across the boundary. - docs/federation/PRD.md — 16-section product requirements (v1 locked) - docs/federation/MILESTONES.md — 7-milestone decomposition with per-milestone acceptance test tables across unit/integration/E2E layers - docs/federation/MISSION-MANIFEST.md — mission scope, success criteria, milestone table linked to issues #460-#466 - docs/federation/TASKS.md — FED-M1 decomposed into 12 tasks; M2-M7 deferred to per-milestone planning to avoid speculative decomposition Refs: #460 #461 #462 #463 #464 #465 #466 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-19 17:04:39 -05:00
parent 81c1775a03
commit 47aac682f5
4 changed files with 859 additions and 0 deletions
--- a/docs/federation/MISSION-MANIFEST.md
+++ b/docs/federation/MISSION-MANIFEST.md
@@ -0,0 +1,85 @@
+# Mission Manifest — Federation v1
+
+> Persistent document tracking full mission scope, status, and session history.
+> Updated by the orchestrator at each phase transition and milestone completion.
+
+## Mission
+
+**ID:** federation-v1-20260419
+**Statement:** Jarvis operates across 3–4 workstations in two physical locations (home, USC). The user currently reaches back to a single jarvis-brain checkout from every session; a prior OpenBrain attempt caused cache, latency, and opacity pain. This mission builds asymmetric federation between Mosaic Stack gateways so that a session on a user's home gateway can query their work gateway in real time without data ever persisting across the boundary, with full multi-tenant isolation and standard-PKI (X.509 / Step-CA) trust management.
+**Phase:** Planning complete — M1 implementation not started
+**Current Milestone:** FED-M1
+**Progress:** 0 / 7 milestones
+**Status:** active
+**Last Updated:** 2026-04-19 (PRD + MILESTONES + tracking issues filed)
+**Parent Mission:** None — new mission
+
+## Context
+
+Federation is the solution to what originally drove OpenBrain. The prior attempt coupled every agent session to a remote service, introduced cache/latency/opacity pain, and created a hard dependency that punished offline use. This redesign:
+
+1. Makes federation **gateway-to-gateway**, not agent-to-service
+2. Keeps each user's home instance as source of truth for their data
+3. Exposes scoped, read-only data on demand without persisting across the boundary
+4. Uses X.509 mTLS via Step-CA so rotation/revocation/CRL/OCSP are standard
+5. Supports multi-tenant serving sides (employees on uscllc.com each federating back to their own home gateway) with no cross-user leakage
+6. Requires federation-tier instances on both sides (PG + pgvector + Valkey) — local/standalone tiers cannot federate
+7. Works over public HTTPS (no VPN required); Tailscale is an optional overlay
+
+Key design references:
+
+- `docs/federation/PRD.md` — 16-section product requirements
+- `docs/federation/MILESTONES.md` — 7-milestone decomposition with per-milestone acceptance tests
+- `docs/federation/TASKS.md` — per-task breakdown (M1 populated; M2-M7 deferred to mission planning)
+- `docs/research/mempalace-evaluation/` (in jarvis-brain) — why we didn't adopt MemPalace
+
+## Success Criteria
+
+- [ ] AC-1: Two Mosaic Stack gateways on different hosts can establish a federation grant via CLI-driven onboarding
+- [ ] AC-2: Server A can query Server B for `tasks`, `notes`, `memory` respecting scope filters
+- [ ] AC-3: User on B with no grant cannot be queried by A, even if A has a valid grant for another user (cross-user isolation)
+- [ ] AC-4: Revoking a grant on B causes A's next request to fail with a clear error within one request cycle
+- [ ] AC-5: Cert rotation happens automatically at T-7 days; in-progress session survives rotation without user action
+- [ ] AC-6: Rate-limit enforcement returns 429 with `Retry-After`; client backs off
+- [ ] AC-7: With B unreachable, a session on A completes using local data and surfaces "federation offline for `<peer>`" once per session
+- [ ] AC-8: Every federated request appears in B's `federation_audit_log` within 1 second
+- [ ] AC-9: Scope excluding `credentials` means credentials are never returned — even via `search` with matching keywords
+- [ ] AC-10: `mosaic federation status` shows cert expiry, grant status, last success/failure per peer
+- [ ] AC-11: Full 3-employee multi-tenant scenario passes with no cross-user leakage
+- [ ] AC-12: Two-gateway production deployment (woltje.com ↔ uscllc.com) operational ≥7 days without incident
+- [ ] AC-13: All 7 milestones ship as merged PRs with green CI and closed issues
+
+## Milestones
+
+| #   | ID     | Name                                          | Status      | Branch | Issue | Started | Completed |
+| --- | ------ | --------------------------------------------- | ----------- | ------ | ----- | ------- | --------- |
+| 1   | FED-M1 | Federated tier infrastructure                 | not-started | —      | #460  | —       | —         |
+| 2   | FED-M2 | Step-CA + grant schema + admin CLI            | not-started | —      | #461  | —       | —         |
+| 3   | FED-M3 | mTLS handshake + list/get + scope enforcement | not-started | —      | #462  | —       | —         |
+| 4   | FED-M4 | search verb + audit log + rate limit          | not-started | —      | #463  | —       | —         |
+| 5   | FED-M5 | Cache + offline degradation + OTEL            | not-started | —      | #464  | —       | —         |
+| 6   | FED-M6 | Revocation + auto-renewal + CRL               | not-started | —      | #465  | —       | —         |
+| 7   | FED-M7 | Multi-user RBAC hardening + acceptance suite  | not-started | —      | #466  | —       | —         |
+
+## Budget
+
+| Milestone | Est. tokens | Parallelizable?        |
+| --------- | ----------- | ---------------------- |
+| FED-M1    | 20K         | No (foundation)        |
+| FED-M2    | 30K         | No (needs M1)          |
+| FED-M3    | 40K         | No (needs M2)          |
+| FED-M4    | 20K         | No (needs M3)          |
+| FED-M5    | 20K         | Yes (with M6 after M4) |
+| FED-M6    | 20K         | Yes (with M5 after M3) |
+| FED-M7    | 25K         | No (needs all)         |
+| **Total** | **~175K**   |                        |
+
+## Session History
+
+| Session | Date       | Runtime | Outcome                                             |
+| ------- | ---------- | ------- | --------------------------------------------------- |
+| S1      | 2026-04-19 | claude  | PRD authored, MILESTONES decomposed, 7 issues filed |
+
+## Next Step
+
+Begin FED-M1 implementation: federated tier infrastructure. Breakdown in `docs/federation/TASKS.md`.