# Federation SLA (honest sit tier)

**Status URL:** `https://geniusflow-federation.vercel.app/api/status`  
**Live copy of this doc:** `https://geniusflow-federation.vercel.app/docs/FEDERATION_SLA.md`  
**Tier:** `best_effort_vercel`  
**Capital / product:** sit / PT HOLD — this is an ops surface, not a paid uptime contract.

## What is promised

- A public JSON status document with `build_id`, `baked_at`, baked surface counts, and on-disk endpoint presence checks after each federation bake/deploy.
- Best-effort availability of federation read endpoints (dossier, report_feed, cite, verify, package, darshan, return_wire GET, openapi).
- Honest language: cold starts, hobby-plan limits, and Vercel platform incidents can cause brief failures.
- **proof_shape v1.0.0 stability** on `/api/package` and `/api/verify`: required field names and limb order stay frozen under this tier (see `docs/ATTESTATION_PROOF_SHAPE.md`). Additive optional keys ok; silent drops are a contract break.

## Return-wire durability model

Layered (see `durability` on `GET /api/return_wire`):

| Layer | Survives cold start? | Notes |
|-------|----------------------|-------|
| Deploy-baked snapshot | **Yes** | Embedded in handler + static `/return_wire/acks.jsonl` (+ `.json`) at bake/deploy |
| Warm `/tmp` + memory ring | No | Best-effort while the instance stays warm |
| Vercel KV / Upstash Redis REST | **Yes** (if wired) | Only when Host sets free-tier `KV_REST_API_*` or `UPSTASH_REDIS_REST_*` — not invented here |
| `GENIUSFLOW_RETURN_WIRE_LOG_URL` | Host-dependent | Optional external append log Host already operates |
| Engine `return-wire pull` → `data/return_wire_acks.jsonl` | **Yes** (Host disk) | Always the Host durable merge path |

**Residual (honest):** without Host KV/Upstash token (or external log URL), live POST acks between pulls/redeploys may be lost on cold start. Free durable path = deploy bake + engine pull. True cross-instance write durability needs Host free-tier Upstash/KV — no new paid SaaS. Do **not** claim `kv_upstash: true` until Host pastes secrets and verify (below) passes.

## Host: free Upstash Redis REST (cross-instance write durability)

Code already reads these names (either pair is enough — prefer Upstash names):

| Role | Env var | Where to copy |
|------|---------|---------------|
| REST URL | `UPSTASH_REDIS_REST_URL` | Upstash console → Redis DB → **REST** / Connect |
| REST token | `UPSTASH_REDIS_REST_TOKEN` | same (standard token, not read-only) |
| Alias URL | `KV_REST_API_URL` | optional; same value as REST URL (Vercel KV / Upstash integration) |
| Alias token | `KV_REST_API_TOKEN` | optional; same value as REST token |
| Optional | `GENIUSFLOW_RETURN_WIRE_LOG_URL` | Host-operated append endpoint (skip if unused) |

Handler uses stdlib `POST {url}/pipeline` with `Authorization: Bearer {token}` (`LPUSH` / `LTRIM` / `LRANGE` on key `gf:return_wire:acks`). No paid plan required for sit traffic.

### Click-path (Upstash)

1. Open [https://console.upstash.com](https://console.upstash.com) → sign in / create free account.
2. **Redis** → **Create Database** → free / pay-as-you-go (stay on free allowance; no paid 5.4).
3. Name e.g. `geniusflow-return-wire` → pick a region near Vercel (often `us-east-1` / `iad1`).
4. Open the DB → **Connect** / **REST** tab → copy **`UPSTASH_REDIS_REST_URL`** and **`UPSTASH_REDIS_REST_TOKEN`**.

### Click-path (Vercel → `geniusflow-federation`)

1. [https://vercel.com](https://vercel.com) → project **`geniusflow-federation`**.
2. **Settings** → **Environment Variables**.
3. Add for **Production** (and Preview if you want parity):
   - `UPSTASH_REDIS_REST_URL` = copied HTTPS URL (`https://….upstash.io`)
   - `UPSTASH_REDIS_REST_TOKEN` = copied token
4. **Redeploy** the latest Production deployment (env vars apply on new deploys). Dashboard: **Deployments** → ⋮ on latest → **Redeploy**. Or from repo after env is set:
   ```bash
   GENIUSFLOW_BUILDER_DEPLOY=1 python3 -c \
     "from engine.bridge.federation_manifest import deploy_manifest; print(deploy_manifest())"
   ```
5. Do **not** commit tokens to git. `vercel` CLI is optional; dashboard paste is enough. Agent will not invent that KV is live until verify shows `true`.

### Confirm after Host pastes keys

```bash
# Expect layers.kv_upstash == true (only after secrets + redeploy)
curl -sS https://geniusflow-federation.vercel.app/api/return_wire | jq .durability
curl -sS https://geniusflow-federation.vercel.app/api/return_wire | jq .durability.layers.kv_upstash
# Optional: host_env lists the names the handler accepts
curl -sS https://geniusflow-federation.vercel.app/api/return_wire | jq .durability.host_env
python3 run.py return-wire live-probe --entity AAVE_V3
python3 run.py return-wire pull
```

Until Host sets secrets, live remains `kv_upstash: false` (honest residual).

## What is not promised

- No **99.99%** (or any invented) uptime percentage.
- No multi-region HA, no dedicated SRE on-call, no contractual credits.
- No paid 5.4 settlement SLA; no bank / design-partner mandate coverage.

## How to use

```bash
curl -sS https://geniusflow-federation.vercel.app/api/status | jq .
curl -sS https://geniusflow-federation.vercel.app/api/return_wire | jq .durability
python3 run.py return-wire pull
python3 run.py return-wire live-probe --entity AAVE_V3
```

Agents: prefer OpenAPI (`/openapi.json`) + MCP (`engine/mcp/federation_mcp_server.py`) — see `docs/AGENT_TOOL_ADAPTER.md`.

## Redeploy

Federation bake+deploy refreshes `build_id` / `baked_at` and the return-wire bake snapshot:

```bash
GENIUSFLOW_BUILDER_DEPLOY=1 python3 -c \
  "from engine.bridge.federation_manifest import deploy_manifest; print(deploy_manifest())"
```