fix: update oeg-fm spec based on the latest decisions

# 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; the rest (federation establishment is an OEG-routed product-facing action, not direct against FM's L.2 admin API; FM also supports 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-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

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

## Context

[ADR-0043](/decisions/0043-oeg-proxied-federation-establishment.md) decided that operator-triggered

federation establishment is proxied through OEG **asynchronously over the DataBus** — OEG persists

a `PENDING` `operations` row and publishes a new `command.fm.federation.create` /

`command.fm.federation.zone_subscribe` subject family, wrapping "the same payload shape FM's L.2

endpoints already define" in a thin envelope; FM consumes it. ADR-0043 also stated that the

mandatory inbound EWBI termination (partner OPs calling our `POST /partner` directly) was

unaffected and stayed with FM, reached via Nginx routing `/operatorplatform/federation/v1/*`

straight to FM.

A follow-up discussion (2026-09-07) narrowed OEG's role to a stateless proxy and proposed carrying

the OEG→FM hop as **NATS request/reply over the DataBus** with two OEG-side GSMA↔internal mapper

functions. That transport and that mapping layer were never written into the specs.

The 2026-09-08 call revisited both and reversed the transport and the mapping:

- The DataBus is the wrong tool for federation establishment. These operations are

  request/response by nature (GSMA OPG.04 `POST /partner` has no deferred-result channel — the

  caller gets `federationContextId` on the same call), there is no fan-out, and no durability

  requirement beyond the life of the HTTP request. An async command family plus a completion

  channel is machinery with no payoff here.

- An OEG↔FM internal schema (envelope or mapper stubs) is redundant. FM already parses OPG.04

  payloads for the operations it terminates directly; having OEG re-shape the same payload into an

  internal form only to have FM re-derive the OPG.04 meaning is duplicated work and a second

  schema to keep in lockstep.

federation establishment is proxied through OEG asynchronously over the DataBus: OEG persists a

`PENDING` `operations` row and publishes a new `command.fm.federation.create` /

`command.fm.federation.zone_subscribe` subject family — a thin envelope wrapping the same payload

shape FM's L.2 endpoints already define — which FM consumes. ADR-0043 left the mandatory inbound

EWBI termination (partner OPs calling our `POST /partner` directly) with FM, reached via Nginx

routing `/operatorplatform/federation/v1/*` straight to FM. A follow-up discussion on 2026-09-07

narrowed OEG's role to a stateless proxy and proposed carrying the OEG→FM hop as NATS

request/reply over the DataBus with two OEG-side GSMA↔internal mapper functions; that transport

and that mapping layer were never written into the specs.

The 2026-09-08 call revisited both and reversed the transport and the OEG-side mapping. Federation

establishment is request/response by nature — GSMA OPG.04 `POST /partner` has no deferred-result

channel, so the caller gets `federationContextId` on the same call — with no fan-out and no

durability requirement beyond the life of the HTTP request, so an async command family plus a

completion channel is machinery with no payoff. And an OEG↔FM internal schema is redundant: FM

already parses OPG.04 payloads for the operations it terminates directly, so having OEG re-shape

the same payload into an internal form only for FM to re-derive its OPG.04 meaning is duplicated

work and a second schema to keep in lockstep.

Options considered:

- Option A: Keep ADR-0043 as written — async `command.fm.federation.*` over the DataBus, OEG

  persists an operation record, inbound `POST /partner` stays direct-to-FM.

- Option B: OEG fronts the federation-lifecycle and zone-subscription EWBI operations and proxies

  each one to FM as a **synchronous internal HTTP call**, forwarding the GSMA/OPG.04 request body

  unchanged and relaying FM's response unchanged. OEG holds no federation state. No DataBus, no

  each one to FM over a synchronous internal HTTP call, forwarding the OPG.04 request body

  unchanged and relaying FM's response unchanged, holding no federation state — no DataBus, no

  internal schema.

## Decision

Option B.

**Transport.** Every OEG→FM federation interaction is a synchronous internal HTTP request to FM

(`http://fm:8082/internal/...`). The DataBus (`command.fm.federation.*`) is not used for

federation establishment; those subjects are not created. The DataBus remains in the picture only

for the unrelated `command.srm.*` / `event.srm.*` flows FM already uses.

**No internal schema.** OEG forwards the GSMA/OPG.04 request body to FM byte-for-byte and relays

FM's response body back to the caller unchanged. OEG does not translate, re-shape, or validate

OPG.04-specific fields beyond what it needs to route. All OPG.04 parsing, validation, agreement

checks, topology hiding, and state live in FM.

**OEG is a stateless pass-through.** OEG persists nothing for these operations — no `operations`

row, no `OperationType` value, no domain model, repository, migration, or completion consumer.

The only "state" is the in-flight HTTP request awaiting FM's reply. OEG still applies its normal

edge concerns (TLS termination, authentication, correlation-id propagation, structured logging).

**Operations OEG fronts** (partner-initiated inbound EWBI, plus the operator-initiated

establishment trigger, all proxied synchronously to FM):

| Method / EWBI path | OPG.04 operation | Notes |

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

| `POST /partner` | `CreateFederation` | FM creates the federation, mints `federationContextId`, and returns the full `FederationResponseData` on the same synchronous response; OEG relays it to the partner |

| `GET /{federationContextId}/partner` | `GetFederationDetails` | pass-through |

| `PATCH /{federationContextId}/partner` | `UpdateFederation` | pass-through |

| `DELETE /{federationContextId}/partner` | `DeleteFederationDetails` | pass-through |

| `GET /fed-context-id` | `GetFederationContextId` | pass-through |

| `POST /{federationContextId}/zones` | `ZoneSubscribe` | pass-through |

| `DELETE /{federationContextId}/zones/{zoneId}` | `ZoneUnsubscribe` | pass-through |

**Operations that stay direct to FM** (Nginx routes `/operatorplatform/federation/v1/*` for these

straight to FM; OEG never sees them): `GET /federation-resources` (`GetFederationAPIs`),

`POST /{federationContextId}/application/lcm` (`InstallApp`) and the rest of application LCM,

`POST /{federationContextId}/apiservice/{serviceAPINameVal}` (`APIForwarding`) and Service API

session operations, `GET /{federationContextId}/health` (`GetFederationHealth`),

`POST /{federationContextId}/renew` (`RenewFederation`),

`GET /{federationContextId}/platform-caps` (`GetPlatformCapabilities`).

**FM ownership is unchanged.** FM remains the sole owner of OPG.04 protocol execution — inbound

and outbound — including the outbound `CreateFederation` / `ZoneSubscribe` handshake with a

partner FM. ADR-0043's FM bootstrap-config path (self-initiated federation from startup

configuration) is untouched by this decision.

Option B. OEG terminates the federation-lifecycle and zone-subscription EWBI operations and

forwards each one to FM over a synchronous internal HTTP call under `http://fm:8082/internal/...`,

passing the OPG.04 request body through unchanged and relaying FM's response unchanged. The

`command.fm.federation.*` subject family is not created; the DataBus is not used for federation

establishment, and stays scoped to the `command.srm.*` / `event.srm.*` flows FM already uses.

The operations OEG fronts are `CreateFederation` (`POST /partner`), `GetFederationDetails` /

`UpdateFederation` / `DeleteFederationDetails` (`GET` / `PATCH` / `DELETE

/{federationContextId}/partner`), `GetFederationContextId` (`GET /fed-context-id`), and

`ZoneSubscribe` / `ZoneUnsubscribe` (`POST` / `DELETE /{federationContextId}/zones`). Every other

EWBI operation — `GetFederationAPIs`, `InstallApp` and the rest of application LCM, `APIForwarding`

and the Service API session operations, `GetFederationHealth`, `RenewFederation`,

`GetPlatformCapabilities` — is unaffected: Nginx routes it straight to FM and OEG never sees it.

OEG holds no federation state for any of this — no `operations` row, no `OperationType` value, no

domain model, repository, migration, or completion consumer; the only "state" is the in-flight

HTTP request awaiting FM's reply. OEG applies its normal edge concerns (TLS termination,

authentication, correlation-id propagation, structured logging) and nothing else. FM performs all

OPG.04 parsing, validation, agreement checks, topology hiding, and persistence, and owns all

federation state including `federationContextId` — on `CreateFederation` it mints the

`federationContextId` and returns the full `FederationResponseData` on the same synchronous

response, which OEG relays to the partner. FM remains the sole owner of OPG.04 protocol execution,

inbound and outbound, including the outbound `CreateFederation` / `ZoneSubscribe` handshake with a

partner FM.

This supersedes ADR-0043's transport and its operation-record requirement. ADR-0043's remaining

substance — that federation establishment is a product-facing action routed through OEG for

auth/policy/audit rather than direct against FM's L.2 admin API, and that FM also supports

config-bootstrap federation — stands.

substance stands: federation establishment is a product-facing action routed through OEG for

auth/policy/audit rather than direct against FM's L.2 admin API, and FM also supports self-initiated

bootstrap federation from startup configuration, which this decision does not touch.

## Consequences

What becomes easier:

- No new DataBus subject family, no stream/consumer topology to design, no completion channel.

  ADR-0043's open item (whether FM gets a second consumer binding on `OOP_TASKS` or a dedicated

  stream) disappears.

- One payload shape end to end (GSMA OPG.04). No OEG↔FM internal schema to define, version, or

  keep in lockstep; the 2026-09-07 mapper stubs are not built.

- OEG stays genuinely thin for federation — a routing and edge-concern layer with no

- No new DataBus subject family, no stream or consumer topology to design, no completion channel.

  ADR-0043's open item — whether FM gets a second consumer binding on `OOP_TASKS` or a dedicated

  stream — disappears.

- One payload shape end to end (GSMA OPG.04). There is no OEG↔FM internal schema to define,

  version, or keep in lockstep, and the 2026-09-07 mapper stubs are not built.

- OEG stays genuinely thin for federation: a routing and edge-concern layer with no

  federation-domain code, model, or persistence.

- `federationContextId` reaches the partner on the same call, matching GSMA OPG.04's synchronous

  `CreateFederation` contract without OEG needing to bridge an async result back to a sync

  response.

  `CreateFederation` contract without OEG bridging an async result back onto a synchronous response.

What becomes harder:

- FM must expose an internal HTTP endpoint surface for OEG to call (the operations in the table

  above), distinct from the EWBI surface FM terminates directly.

- FM must expose an internal HTTP surface for OEG to call, distinct from the EWBI surface it

  terminates directly; the endpoint paths and bodies are specified in

  [fm/requirements-and-design.md](/fm/requirements-and-design.md) §L.3b.

- Federation establishment now couples OEG's request path to FM availability — if FM is down, a

  partner's `CreateFederation` fails synchronously rather than being queued. Acceptable: GSMA

  OPG.04 already models this as a synchronous operation, and there is no requirement to accept a

Deferred or excluded:

- The exact internal FM endpoint paths and request/response bodies for the OEG→FM calls are

  finalised in [fm/requirements-and-design.md](/fm/requirements-and-design.md) §L.3b.

- No change to the SRM→FM federated-deploy hand-off (ADR-0044) or to subscriber-identifier

  routing for synchronous query APIs (UC-FM-02 / §G3).

- No change to the SRM→FM federated-deploy hand-off (ADR-0044) or to subscriber-identifier routing

  for synchronous query APIs (UC-FM-02 / §G3).

Revisit trigger:

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 (`POST /partner`, `GET`/`PATCH`/`DELETE /{federationContextId}/partner`, `GET /fed-context-id`, `POST`/`DELETE /{federationContextId}/zones`), which OEG terminates and proxies to FM's internal HTTP surface synchronously (ADR-0045). FM still executes all OPG.04 protocol for those — OEG only passes the payload through.

- **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 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-initiated or operator-initiated call that OEG proxies to FM over a **synchronous internal HTTP request** (no DataBus, no internal schema — OEG forwards the GSMA/OPG.04 body unchanged and relays FM's response, 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-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.

- **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/*`. **Exception (ADR-0045):** the federation-lifecycle and zone-subscription operations (`POST /partner`, `GET`/`PATCH`/`DELETE /{federationContextId}/partner`, `GET /fed-context-id`, `POST`/`DELETE /{federationContextId}/zones`) are terminated by OEG and arrive at FM as a synchronous internal HTTP call carrying the unmodified GSMA/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-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. |

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

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

- **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 GSMA/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-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).

  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, **plus** the same processing for the federation-lifecycle and zone-subscription operations when they arrive as a synchronous internal HTTP call proxied by OEG (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-0045) 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.

| 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; GSMA/OPG.04 body passed through unchanged) |

| Internal HTTP endpoints for OEG's synchronous federation-lifecycle proxy (ADR-0045) | **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) |

**Status:** unresolved. The 2026-09-01 TSC+MDL meeting decided SRM (not OEG) owns this hand-off, but did not conclude the transport. **Recommendation:** default to synchronous internal HTTP for consistency with L.4's existing FM↔SRM pattern, with SRM treating the call as part of its own already-async `command.srm.service.deploy` handling (SRM owns retry/timeout toward FM, not OEG). Revisit once FM/SRM implementation work starts on UC-FM-07.

### G5. OEG → FM Hand-off for the Federation-Lifecycle EWBI Operations (ADR-0045)

**The question:** How does OEG hand the federation-lifecycle and zone-subscription EWBI operations

(`POST /partner`, `GET`/`PATCH`/`DELETE /{federationContextId}/partner`, `GET /fed-context-id`,

`POST`/`DELETE /{federationContextId}/zones`) to FM?

**Status:** resolved (ADR-0045). Synchronous internal HTTP: OEG terminates the request, calls FM's

corresponding endpoint under `http://fm:8082/internal/...` with the GSMA/OPG.04 body forwarded

byte-for-byte, and relays FM's response unchanged. No DataBus (`command.fm.federation.*` is not

created), no OEG↔FM internal schema, no `operations` row on the OEG side. FM mints

`federationContextId` on `POST /partner` and returns it on the same response. Endpoint shapes in

[fm/requirements-and-design.md §L.3b](/fm/requirements-and-design.md).

---

## Revision History

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

| 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 | ADR-0045: the OEG→FM federation-establishment hop is now a stateless synchronous HTTP proxy, not async over the DataBus. OEG terminates the federation-lifecycle + zone-subscription EWBI operations and forwards the GSMA/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 + boundary matrix updated; `command.fm.federation.*` consumer row replaced; added G5. |

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