fix: renumber fm sync-proxy adr 0045 to 0046

# ADR-0043: Operator-triggered federation establishment is proxied through OEG over the DataBus; FM also supports config-driven bootstrap federation

**Status:** accepted — the transport (async `command.fm.federation.*` over the DataBus) and the `PENDING` operation-record requirement are superseded by [ADR-0045](/decisions/0045-oeg-fronts-federation-lifecycle-ewbi-as-sync-proxy.md), which makes the OEG→FM hop a stateless synchronous HTTP call; everything else (OEG-routed rather than direct against FM's L.2 admin API; FM config-bootstrap federation) stands

**Status:** accepted — the transport (async `command.fm.federation.*` over the DataBus) and the `PENDING` operation-record requirement are superseded by [ADR-0046](/decisions/0046-oeg-fronts-federation-lifecycle-ewbi-as-sync-proxy.md), which makes the OEG→FM hop a stateless synchronous HTTP call; everything else (OEG-routed rather than direct against FM's L.2 admin API; FM config-bootstrap federation) stands

**Date:** 2026-09-04

**Affects:** [oeg/architecture.md](/oeg/architecture.md), [oeg/interface-contract.md](/oeg/interface-contract.md), [fm/overview-and-architecture.md](/fm/overview-and-architecture.md), [fm/requirements-and-design.md](/fm/requirements-and-design.md), [platform/architecture.md](/platform/architecture.md)

---

type: Decision Record

title: "ADR-0045: OEG fronts the federation-lifecycle and zone-subscription EWBI operations as a stateless synchronous HTTP proxy to FM; no DataBus, no internal schema"

title: "ADR-0046: OEG fronts the federation-lifecycle and zone-subscription EWBI operations as a stateless synchronous HTTP proxy to FM; no DataBus, no internal schema"

description: "OEG fronts the federation-lifecycle and zone-subscription EWBI operations as a stateless synchronous HTTP proxy to FM; no DataBus, no internal schema"

tags: [adr]

timestamp: 2026-09-08T00:00:00Z

status: "accepted"

---

# ADR-0045: OEG fronts the federation-lifecycle and zone-subscription EWBI operations as a stateless synchronous HTTP proxy to FM; no DataBus, no internal schema

# ADR-0046: OEG fronts the federation-lifecycle and zone-subscription EWBI operations as a stateless synchronous HTTP proxy to FM; no DataBus, no internal schema

**Status:** accepted

**Date:** 2026-09-08

* [ADR-0040](0040-target-serveability-is-a-tri-state.md) - can_serve_target answers can_serve | unknown_subscriber | unsupported_identifier; a boolean cannot carry the 404/422 split §E.2 requires, and 404 needs positive evidence (supersedes ADR-0038's boolean)

* [ADR-0041](0041-tfsdk-owns-adapter-construction.md) - TF-SDK builds adapters behind a factory keyed by adapter kind; SRM resolves control_path_ref to an instance but never enumerates adapter kinds

* [ADR-0042](0042-ewbi-oauth2-client-credentials-mtls-deferred.md) - E/WBI authorization is OAuth2 Client-Credentials: local Keycloak for inbound, partner Authorization Server for outbound; mTLS deferred

* [ADR-0043](0043-oeg-proxied-federation-establishment.md) - operator-triggered federation establishment is proxied through OEG over the DataBus (command.fm.federation.*); FM also supports config-driven bootstrap federation (transport superseded by ADR-0045)

* [ADR-0043](0043-oeg-proxied-federation-establishment.md) - operator-triggered federation establishment is proxied through OEG over the DataBus (command.fm.federation.*); FM also supports config-driven bootstrap federation (transport superseded by ADR-0046)

* [ADR-0044](0044-srm-owns-federated-zone-locality-and-hand-off.md) - SRM resolves Edge Cloud Zone locality for deployment targets and forwards non-local deploys to FM; interim layer pending a future runtime-coordinator component

* [ADR-0045](0045-pin-narrows-candidates-not-probing.md) - a zone/domain pin narrows the device-targeted candidate set rather than bypassing target probing; probing is triggered by how many candidates survive the pin (amends ADR-0038's unpinned scoping)

* [ADR-0045](0045-oeg-fronts-federation-lifecycle-ewbi-as-sync-proxy.md) - OEG fronts the federation-lifecycle and zone-subscription EWBI operations as a stateless synchronous HTTP proxy to FM; no DataBus, no internal schema (supersedes ADR-0043's transport)

* [ADR-0046](0046-oeg-fronts-federation-lifecycle-ewbi-as-sync-proxy.md) - OEG fronts the federation-lifecycle and zone-subscription EWBI operations as a stateless synchronous HTTP proxy to FM; no DataBus, no internal schema (supersedes ADR-0043's transport)

If you are new to FM, this is the simplest useful way to think about it:

- **FM is the bridge to other operators.** When a request needs capabilities on a partner operator's network — or a partner operator needs capabilities on ours — FM handles the cross-boundary routing, identity validation, and response sanitization.

- **FM terminates the East/Westbound Interface (EWBI).** Nginx routes the canonical OPG.04 prefix `/operatorplatform/federation/v1/*` to FM, except the federation-lifecycle and zone-subscription operations (RD §L.3b; ADR-0045), which OEG terminates and proxies to FM's internal HTTP surface synchronously. FM still executes all OPG.04 protocol for those — OEG only passes the payload through, unchanged.

- **FM terminates the East/Westbound Interface (EWBI).** Nginx routes the canonical OPG.04 prefix `/operatorplatform/federation/v1/*` to FM, except the federation-lifecycle and zone-subscription operations (RD §L.3b; ADR-0046), which OEG terminates and proxies to FM's internal HTTP surface synchronously. FM still executes all OPG.04 protocol for those — OEG only passes the payload through, unchanged.

- **FM does not fulfill requests itself.** For OPG.04 lifecycle mutations (install/remove application and supported network-capability operations), it publishes the same `command.srm.*` commands to DataBus that OEG publishes (ADR-0001). For stateless queries (device location, device status), it calls SRM's internal HTTP endpoints synchronously. Either way, SRM handles all fulfillment identically regardless of whether the request came from OEG or FM.

- **FM enforces topology hiding.** Before any response leaves the operator boundary, FM strips internal IPs, cluster names, namespace names, pod UIDs, node names, and internal trace IDs. Partner operators never see our internal infrastructure details.

- **FM manages partner relationships.** It stores partner operator profiles, federation agreements, routing rules, and shared resource catalogues in its own PostgreSQL database (`fm_db`).

- **Establishing a new federation is triggered two ways:** a partner- or operator-initiated call that OEG terminates and proxies to FM over a synchronous internal HTTP request — no DataBus, no internal schema, the OPG.04 body forwarded unchanged and the response relayed unchanged (ADR-0045, superseding ADR-0043's `command.fm.federation.*` transport) — or FM self-initiating from bootstrap configuration at startup (ADR-0043). Either way, FM mints `federationContextId`, owns all federation state, and alone executes the outbound OPG.04 `CreateFederation`/`ZoneSubscribe` handshake.

- **Establishing a new federation is triggered two ways:** a partner- or operator-initiated call that OEG terminates and proxies to FM over a synchronous internal HTTP request — no DataBus, no internal schema, the OPG.04 body forwarded unchanged and the response relayed unchanged (ADR-0046, superseding ADR-0043's `command.fm.federation.*` transport) — or FM self-initiating from bootstrap configuration at startup (ADR-0043). Either way, FM mints `federationContextId`, owns all federation state, and alone executes the outbound OPG.04 `CreateFederation`/`ZoneSubscribe` handshake.

- **For zone-based deployment targeting, SRM — not OEG — determines locality and hands off to FM (ADR-0044).** SRM checks its own zone inventory first, queries FM for federated zone data when the target isn't found locally, and forwards the deploy using FM's internal schema. This is an interim layer pending a future "runtime coordinator" component (see [platform/future-architecture.md](/platform/future-architecture.md) §6.1). OEG's outbound hand-off to FM (below) is now scoped to subscriber-identifier (MSISDN/IP) routing only.

```text

| Area | Current architecture position |

|---|---|

| **EWBI termination** | Terminate inbound EWBI HTTPS requests routed via Nginx under the OPG.04 server prefix `/operatorplatform/federation/v1/*`. The federation-lifecycle and zone-subscription operations (§L.3b; ADR-0045) instead arrive as a synchronous internal HTTP call from OEG carrying the unmodified OPG.04 body — FM processes them exactly as if received on EWBI directly. Client mTLS is a future defense-in-depth layer (ADR-0042), not required today. |

| **EWBI termination** | Terminate inbound EWBI HTTPS requests routed via Nginx under the OPG.04 server prefix `/operatorplatform/federation/v1/*`. The federation-lifecycle and zone-subscription operations (§L.3b; ADR-0046) instead arrive as a synchronous internal HTTP call from OEG carrying the unmodified OPG.04 body — FM processes them exactly as if received on EWBI directly. Client mTLS is a future defense-in-depth layer (ADR-0042), not required today. |

| **Partner authentication** | OAuth2 Client-Credentials + signed JWT. Our Keycloak `federation` realm issues inbound tokens; each target partner's Authorization Server issues outbound tokens. FM validates `fed-mgmt` and maps inbound `azp` to the partner profile (ADR-0042). |

| **Federation agreement enforcement** | Check that the requesting partner has a valid agreement before routing any request. |

| **Outbound federation routing** | Resolve target partner from user identifiers (MSISDN — Mobile Station International Subscriber Directory Number — prefix, IP CIDR — Classless Inter-Domain Routing block) via routing table. Forward requests over EWBI to partner OPs. |

An operator onboards, updates, or decommissions a federation partner.

- **Actor:** Operator or partner OP, via OEG's synchronous federation-lifecycle proxy (ADR-0045); Portal or FM's own internal admin API (L.2) remain available for direct read/update/decommission operations on existing partner records.

- **Actor:** Operator or partner OP, via OEG's synchronous federation-lifecycle proxy (ADR-0046); Portal or FM's own internal admin API (L.2) remain available for direct read/update/decommission operations on existing partner records.

- **Trigger:** New bilateral agreement signed, OAuth2 credential rotation, endpoint change, or partner decommission — or FM's own bootstrap configuration at startup (ADR-0043).

- **Main flow:**

  1. The establishment/lifecycle request reaches FM as a synchronous internal HTTP call from OEG carrying the unmodified OPG.04 body (ADR-0045), or FM self-initiates from bootstrap config; profile fields are the same either way (EWBI/token endpoints, inbound and outbound OAuth2 client IDs, mounted-secret reference, supported APIs, SLA limits).

  1. The establishment/lifecycle request reaches FM as a synchronous internal HTTP call from OEG carrying the unmodified OPG.04 body (ADR-0046), or FM self-initiates from bootstrap config; profile fields are the same either way (EWBI/token endpoints, inbound and outbound OAuth2 client IDs, mounted-secret reference, supported APIs, SLA limits).

  2. FM stores profile in `partner_ops` table.

  3. FM creates/updates federation agreement in `federation_agreements` table, minting `federationContextId` for a new inbound federation and returning it on the synchronous response.

  4. FM populates routing rules.

### In Scope

- **EWBI termination** under `/operatorplatform/federation/v1/*` (behind Nginx) for all inbound partner operator requests, and the same processing for the federation-lifecycle and zone-subscription operations when they arrive as a synchronous internal HTTP call proxied by OEG (§L.3b; ADR-0045) instead of directly on EWBI.

- **EWBI termination** under `/operatorplatform/federation/v1/*` (behind Nginx) for all inbound partner operator requests, and the same processing for the federation-lifecycle and zone-subscription operations when they arrive as a synchronous internal HTTP call proxied by OEG (§L.3b; ADR-0046) instead of directly on EWBI.

- **OAuth2 Client-Credentials authorization** with signed JWTs for all EWBI requests (`fed-mgmt`; `fed-mgmt-notif` for callbacks).

- **Federation agreement management** — partner profiles, agreements, routing rules, and catalogue sharing.

- **Inbound request dispatch** — publish `command.srm.*` commands to DataBus with `source=federation` for SRM fulfillment.

FM sits between **partner operators** and **internal platform services**:

- **Upstream:** Partner Operator Platforms (over EWBI)

- **Lateral:** OEG (synchronous internal-HTTP proxy for the federation-lifecycle + zone-subscription EWBI operations, ADR-0045; subscriber-identifier outbound hand-off, UC-FM-02); SRM (federated zone query and zone-based deploy hand-off, ADR-0044)

- **Lateral:** OEG (synchronous internal-HTTP proxy for the federation-lifecycle + zone-subscription EWBI operations, ADR-0046; subscriber-identifier outbound hand-off, UC-FM-02); SRM (federated zone query and zone-based deploy hand-off, ADR-0044)

- **Downstream:** SRM (via DataBus for mutations, internal HTTP for reads/capacity checks)

Per the component boundary matrix:

| Concern | Owner |

|---|---|

| EWBI termination and federation routing | **FM** (OEG terminates only the federation-lifecycle + zone-subscription subset and proxies it straight through, ADR-0045) |

| EWBI termination and federation routing | **FM** (OEG terminates only the federation-lifecycle + zone-subscription subset and proxies it straight through, ADR-0046) |

| EWBI OAuth2 authentication/authorization (and future mTLS sender-binding) | **FM** |

| `federationContextId` minting and all federation state | **FM** |

| Topology hiding for federation responses | **FM** |

| Federation usage-record generation toward the charging integration | **FM** |

| Async command dispatch (`command.srm.*` publishing) | **FM** (shared with OEG) |

| Internal HTTP endpoints for OEG's synchronous federation-lifecycle proxy (ADR-0045) | **FM** (called by OEG; OPG.04 body passed through unchanged) |

| Internal HTTP endpoints for OEG's synchronous federation-lifecycle proxy (ADR-0046) | **FM** (called by OEG; OPG.04 body passed through unchanged) |

| TF-SDK adapter invocation | **SRM** (not FM) |

| Placement decisions, including local-vs-federated zone determination for deployment targets (ADR-0044) | **SRM** (not FM) |

| Service and resource inventory | **SRM** (not FM) |

|---------|------|---------|

| 2.0 | 2026-07-07 | OOP Release 2.0. |

| 2.0 | 2026-09-04 | Added OEG-proxied federation-establishment trigger and FM bootstrap config (ADR-0043, UC-FM-06 updated). Added UC-FM-07: SRM (not OEG) now owns zone-based deployment locality and the hand-off to FM (ADR-0044); UC-FM-02/G3 narrowed to subscriber-identifier routing; added G4 for the open SRM→FM transport question. |

| 2.0 | 2026-09-08 | OEG→FM federation establishment moves from async over the DataBus (ADR-0043) to a stateless synchronous HTTP proxy (ADR-0045): OEG terminates the federation-lifecycle and zone-subscription EWBI operations and forwards the OPG.04 body to FM's internal HTTP surface unchanged; FM mints `federationContextId` and replies on the same call. EWBI-termination scope, UC-FM-06, boundaries and boundary matrix updated; `command.fm.federation.*` consumer row replaced. |

| 2.0 | 2026-09-08 | OEG→FM federation establishment moves from async over the DataBus (ADR-0043) to a stateless synchronous HTTP proxy (ADR-0046): OEG terminates the federation-lifecycle and zone-subscription EWBI operations and forwards the OPG.04 body to FM's internal HTTP surface unchanged; FM mints `federationContextId` and replies on the same call. EWBI-termination scope, UC-FM-06, boundaries and boundary matrix updated; `command.fm.federation.*` consumer row replaced. |