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).

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

subscriber silo                    federation gateway                source silo
─────────────────                  ──────────────────                ───────────
POST /federation/recall  ─────▶
                                   1. OpenFGA `check` (visible?)
                                   2. mint signed share token (HS256/RS256, 600s)
                                   3. POST /kb/corpora/.../recall ──▶
                                                                    verify share token
                                                                    return hits
                                   4. BitemporalMerger.merge_layers
                                   5. cache + audit
◀───────── ComposedResult

Subscription writer

POST /federation/subscriptions writes the matching OpenFGA tuple + emits 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

• 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 enforces

• 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.