alphaswarm_kb_federation

The federation gateway is a standalone FastAPI service that brokers cross-silo recall. It is the only sanctioned cross-silo recall path (hard rule 60).

Status. Only the T02 scaffold has shipped: app factory, settings, the /healthz / /readyz / /metrics health surface, the no-import CI guard, and the Dockerfile/Helm/Compose deployment skeletons. The /federation/recall and /federation/subscriptions routers and their backing services (silo-registry client, share-token signer/verifier, result cache, bitemporal merger) described below are the planned design (plan WS-B, tracked as T10/T13 in alphaswarm_docs/design/kg-platform-progress.md) — they are not yet implemented. See alphaswarm_kb_federation/INDEX.md for the live-vs-planned module breakdown.

Why a separate service

• The federation logic is fundamentally stateless except for the result cache + OpenFGA Watch subscriber. Running it as a sidecar to alphaswarm_kb would couple lifecycle with the monolith; running it standalone lets it scale horizontally on its own.
• Cross-silo traffic crosses trust boundaries (subscriber tenant → source tenant). Keeping the broker in its own process makes the trust boundary explicit and audit-friendly.
• The CI guard check_alphaswarm_kb_federation_no_alphaswarm.py enforces no_alphaswarm_imports so the boundary cannot drift.

Sequence (planned — T10)

subscriber silo                    federation gateway                source silo
─────────────────                  ──────────────────                ───────────
POST /federation/recall  ─────▶
                                   1. OpenFGA `check` (visible?)
                                   2. mint signed share token (RS256, 600s)
                                   3. POST /kb/corpora/.../recall ──▶
                                                                    verify share token
                                                                    return hits
                                   4. bitemporal merge (precedence semantics
                                      shared with `alphaswarm_kb`'s
                                      `merge_layer_results`)
                                   5. cache + audit
◀───────── ComposedResult

Subscription writer (planned — T10)

POST /federation/subscriptions is designed to write the matching OpenFGA tuple and emit a subscription.granted event on the NATS / Redis Pub/Sub bus that subscribers consume to flush bitmap caches.

Step-up MFA gates every subscription mutation per AlphaSwarm rule 52.

Caching (planned — T10)

• Per-(subscriber_tenant, cache_key) Redis namespace under alphaswarm:kb:federation:*.
• 60s default TTL.
• Cache miss + upstream call budget: 5s default. The gateway aims for ≤250ms p95 federation overhead on a warm cache.

Deployment

Surface	Where
Multi-arch Dockerfile	alphaswarm_kb_federation/deployments/docker/Dockerfile
Helm chart	alphaswarm_kb_federation/deployments/kubernetes/helm/alphaswarm-kb-federation/
Docker Compose (local)	alphaswarm_kb_federation/deployments/compose/docker-compose.federation.yml
Terraform module	alphaswarm_platform/terraform/modules/kb_marketplace_federation/

Hard rules it is designed to enforce

These are enforced once the T10 routers land; today rule 60 is upheld by there being no other cross-silo recall path at all (the gateway's own /federation/* endpoints don't exist yet either).

• Hard rule 60: cross-silo recall goes through this service only.
• Hard rule 26: every upstream call mints its own M2M token via CredentialResolver.
• Hard rule 52: step-up MFA on subscription admin endpoints.
• Hard rule 49 (no-token-passthrough): the share token's aud claim is bound to the source silo; passthrough across audiences is rejected at the verifier.