> **See also:** [ROADMAP.md](../ROADMAP.md)

## v1.9.0 — Federation & State Management

> **Release Theme**
> The furthest point on the distributed axis: stream tables that span multiple
> PostgreSQL clusters, and state that can be checkpointed and recovered
> independently of PostgreSQL's own backup machinery.
>
> This is explicitly the least certain item on the roadmap. It is recorded here
> because the design work exists, not because it is committed. It will only be
> built if real users ask for it — a single PostgreSQL instance, made fast
> (v0.88.0–v0.89.0) and trustworthy (v0.82.0–v0.87.0, v0.90.0–v0.93.0), covers
> the overwhelming majority of the problem pg_trickle exists to solve.

### Multi-cluster federation

```
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ Cluster A        │     │ Cluster B        │     │ Cluster C        │
│ • Source: orders │     │ • Source: users  │     │ • ST: dashboard  │
│ • ST: order_agg  │────▶│ • ST: user_stats │────▶│   (joins A + B)  │
└──────────────────┘     └──────────────────┘     └──────────────────┘
         │                        │                        │
         └────────────────────────┴────────────────────────┘
                                  │
                        ┌───────────────────┐
                        │ Federation        │
                        │ Coordinator       │
                        │ (global DAG)      │
                        └───────────────────┘
```

| Item | Description | Ref |
|------|-------------|-----|
| FD-1 | **Federation coordinator.** A standalone service maintaining the global DAG across clusters, deployable as a Kubernetes `Deployment` or a plain binary. Clusters register via `pgtrickle.register_federation(coordinator_url)`. | LT-5 |
| FD-2 | **Cross-cluster change forwarding.** When an upstream cluster refreshes a stream table, its change events are forwarded downstream through the change log backend from v1.8.0. | LT-5 |
| FD-3 | **Global frontier synchronization.** The coordinator tracks per-cluster frontiers so a downstream cluster only processes events up to the consistent frontier of all its upstreams — the existing single-cluster consistency guarantee, extended. | LT-5 |
| FD-4 | **`create_federated_stream_table()`.** SQL API for defining a stream table whose sources live in other registered clusters. | LT-5 |

### State management

| Item | Description | Ref |
|------|-------------|-----|
| ST-1 | **Object-storage checkpointing.** Checkpoint stream table state and frontiers to S3/GCS for disaster recovery independent of `pg_basebackup`, with a documented restore path and a recovery-time objective measured in the test suite. | LT-8 |
| ST-2 | **Global priority queue and resource governor.** Cross-database and cross-cluster scheduling that respects freshness SLAs (v0.90.0) globally rather than per database. | — |

**Exit criteria:**
- [ ] Federated stream tables produce results identical to the equivalent
      single-cluster computation
- [ ] Global frontier synchronization proven under injected cross-cluster lag
      and partition
- [ ] Object-storage checkpoint restore validated end to end with a measured RTO
- [ ] Nothing in this release is required by, or affects, a single-cluster
      deployment