7a9ce6845f
Decomposes Milestone 3 (mTLS handshake + list/get/capabilities + scope enforcement) into 14 tasks following the M1/M2 pattern. Updates mission manifest to reflect M2 done, M3 in-progress (2/7 milestones complete), and appends session 23 entry to the MVP scratchpad. M3 structure: - Foundation: M3-01 (DTOs in packages/types/src/federation/) - Server stream: M3-03 (AuthGuard) → M3-04 (ScopeService) → M3-05/06/07 (verbs) - Client stream (parallel): M3-08 (FederationClient) → M3-09 (QuerySourceService) - Test infra (parallel): M3-02 (tools/federation-harness/ — local two-gateway) - Validation: M3-10 (Integration) → M3-11 (E2E) → M3-12 (Independent security review) - Close: M3-13 (Docs) → M3-14 (release tag fed-v0.3.0-m3, close #462) Estimate ~100K tokens vs MILESTONES.md 40K — same per-task expansion as M1/M2 once tests, review, and docs are split out. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
8.4 KiB
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: M3 active — mTLS handshake + list/get/capabilities verbs + scope enforcement
Current Milestone: FED-M3
Progress: 2 / 7 milestones
Status: active
Last Updated: 2026-04-21 (M2 closed via PR #503, tag fed-v0.2.0-m2, issue #461 closed; M3 decomposed into 14 tasks)
Parent Mission: None — new mission
Test Infrastructure
| Host | Role | Image | Tier |
|---|---|---|---|
mos-test-1.woltje.com |
Federation Server A (querying side) | gateway:fed-v0.1.0-m1 (M1 baseline) |
federated |
mos-test-2.woltje.com |
Federation Server B (serving side) | gateway:fed-v0.1.0-m1 (M1 baseline) |
federated |
These are TEST hosts for federation E2E (M3+). Distinct from PRD AC-12 production targets (woltje.com ↔ uscllc.com). Deployment workstream tracked in docs/federation/TASKS.md under FED-M2-DEPLOY-*.
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:
- Makes federation gateway-to-gateway, not agent-to-service
- Keeps each user's home instance as source of truth for their data
- Exposes scoped, read-only data on demand without persisting across the boundary
- Uses X.509 mTLS via Step-CA so rotation/revocation/CRL/OCSP are standard
- Supports multi-tenant serving sides (employees on uscllc.com each federating back to their own home gateway) with no cross-user leakage
- Requires federation-tier instances on both sides (PG + pgvector + Valkey) — local/standalone tiers cannot federate
- Works over public HTTPS (no VPN required); Tailscale is an optional overlay
Key design references:
docs/federation/PRD.md— 16-section product requirementsdocs/federation/MILESTONES.md— 7-milestone decomposition with per-milestone acceptance testsdocs/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,memoryrespecting 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_logwithin 1 second - AC-9: Scope excluding
credentialsmeans credentials are never returned — even viasearchwith matching keywords - AC-10:
mosaic federation statusshows 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 | done | (12 PRs #470-#481) | #460 | 2026-04-19 | 2026-04-19 |
| 2 | FED-M2 | Step-CA + grant schema + admin CLI | done | (PRs #483-#503) | #461 | 2026-04-21 | 2026-04-21 |
| 3 | FED-M3 | mTLS handshake + list/get + scope enforcement | in-progress | (decomposition) | #462 | 2026-04-21 | — |
| 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 |
| S2-S4 | 2026-04-19 | claude | FED-M1 complete: 12 tasks (PRs #470-#481) merged; tag fed-v0.1.0-m1 |
| S5-S22 | 2026-04-19 → 2026-04-21 | claude | FED-M2 complete: 13 tasks (PRs #483-#503) merged; tag fed-v0.2.0-m2; issue #461 closed. Step-CA + grant schema + admin CLI shipped. |
| S23 | 2026-04-21 | claude | M3 decomposed into 14 tasks in docs/federation/TASKS.md. Manifest M3 row → in-progress. Next: kickoff M3-01. |
Next Step
FED-M3 active. Decomposition landed in docs/federation/TASKS.md (M3-01..M3-14, ~100K estimate). Tracking issue #462.
Execution plan (parallel where possible):
- Foundation: M3-01 (DTOs in
packages/types/src/federation/) starts immediately — sonnet subagent onfeat/federation-m3-types. Blocks all server + client work. - Server stream (after M3-01): M3-03 (AuthGuard) + M3-04 (ScopeService) in series, then M3-05 / M3-06 / M3-07 (verbs) in parallel.
- Client stream (after M3-01, parallel with server): M3-08 (FederationClient) → M3-09 (QuerySourceService).
- Harness (parallel with everything): M3-02 (
tools/federation-harness/) — needed for M3-11. - Test gates: M3-10 (Integration) → M3-11 (E2E with harness) → M3-12 (Independent security review, two rounds budgeted).
- Close: M3-13 (Docs) → M3-14 (release tag
fed-v0.3.0-m3, close #462).
Test-bed fallback: mos-test-1/-2 deploy is still blocked on FED-M2-DEPLOY-IMG-FIX. The harness in M3-02 ships a local two-gateway docker-compose so M3-11 is not blocked. Production-host validation is M7's responsibility (PRD AC-12).