Merge branch 'docs/fm-federated-service-instances' into 'develop'

| REQ-FED-18 | *(later phase)* The system shall produce secure federation usage/charging records and integrate them with the operator-controlled charging system according to configured charging factors. FM does not perform inter-operator financial settlement. | OPG.02 v10.0 §4.3.3 and Annex G |

| REQ-FED-19 | The system shall provide an internal admin API (L.2) for the partner registration lifecycle (register, read, update, retire via `status`), federation agreements, and routing rules. Partner registration is the operator's normal first step, not a break-glass action: OEG proxies `POST`/`GET /internal/partners` and `GET`/`PATCH /internal/partners/{id}` byte-for-byte from `/platform/v1/federation/partners[/{partnerOpId}]` (§L.3b, OEG §N.7; ADR-0051), and the id FM assigns is the `partnerOpId` every federation-lifecycle call is scoped by (REQ-FED-20). FM's bootstrap configuration does not register partners; it federates with those already registered (REQ-FED-20). Federation agreements and routing rules are not proxied — L.2 stays their sole path. Establishing and managing the federation itself (the GSMA federation context) is REQ-FED-20, not this requirement. The agreement and routing-rule endpoints are not built yet. | OA UC-FM-06, ADR-0051 |

| REQ-FED-20 | The system shall expose internal HTTP endpoints under `/internal/*` (§L.3b), mirroring OEG's `/platform/v1/federation/partners/{partnerOpId}/federations/...` paths 1:1, that accept the eight operator-triggered outbound federation-lifecycle operations proxied synchronously by OEG (`CreateFederation`, `GetFederationContextId`, `GetFederationDetails`, `DeleteFederationDetails`, `GetZoneData`, `ZoneSubscribe`, `GetZoneDetails`, `ZoneUnsubscribe`; `UpdateFederation` out of scope), receiving the raw GSMA request payload and query string OEG forwards byte-for-byte (no OEG↔FM envelope, no reshaping). This hop is protected only by cluster-internal network-policy reachability, not a dedicated credential — no `aud`/token check is added (ADR-0042 covers EWBI partner-facing authorization only, not this hop). FM shall resolve `partnerOpId` against the partner's registration record (REQ-FED-19) and reject a `federationContextId` presented against the wrong partner, validate and execute the outbound OPG.04 operation, and — for `CreateFederation` — store the partner-issued `federationContextId` and return the full `FederationResponseData` on the synchronous response. It shall support an equivalent self-initiated bootstrap path from startup configuration. It shall reject a `CreateFederation` whose identity fields (`partnerStatusLink`, `origOPFederationId`, `origOPCountryCode`, `origOPMobileNetworkCodes`) do not match its own configuration (MNCs may be a subset), fill in the optional ones left out, and serve that identity on `GET /internal/identity` (§L.2). OEG does not publish `command.fm.federation.*`, and inbound EWBI termination on the canonical prefix is unchanged (ADR-0051, keeping ADR-0046's synchronous-HTTP transport and superseding ADR-0043's DataBus transport). | ADR-0051 |

| REQ-FED-21 | The system shall expose an internal endpoint for SRM to query federated zone/capability data (`shared_resource_catalogues`) by `zone_id`, and shall consume SRM's federated hand-off (`command.fm.service.deploy` / `.terminate` on `OOP_TASKS`) for work that resolves to a partner, executing the outbound OPG.04 `InstallApp` or `RemoveApp` onboarding the application at the partner first when needed (ADR-0068), and reporting the outcome on `event.fm.operation.completed` (§L.3a). | ADR-0044, ADR-0053, OA UC-FM-07 |

| REQ-FED-21 | The system shall expose an internal endpoint for SRM to query federated zone/capability data (`shared_resource_catalogues`) by `zone_id`, and to read the partner-hosted service instances SRM handed off, by `service_instance_id` or per `app_provider_id`, and shall consume SRM's federated hand-off (`command.fm.service.deploy` / `.terminate` on `OOP_TASKS`) for work that resolves to a partner, executing the outbound OPG.04 `InstallApp` or `RemoveApp` onboarding the application at the partner first when needed (ADR-0068), and reporting the outcome on `event.fm.operation.completed` (§L.3a). | ADR-0044, ADR-0053, OA UC-FM-07 |

---

SRM treats a `404` as an ordinary placement failure, the same path as an unresolvable local zone.

#### Reads: `GET /internal/federated-service-instances` and `GET /internal/federated-service-instances/{service_instance_id}`

SRM keeps no rows for instances a partner hosts (ADR-0053, amended 2026-10-08), but its

instance reads (srm/interface-contract.md §E.1) have to list them, since OEG answers

`GET /appinstances` from those reads. FM answers them from its outbound `federation_transactions`.

| Method | Path | Description |

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

| `GET` | `/internal/federated-service-instances?app_provider_id=...` | Every partner-hosted instance SRM handed off for that App Provider; `app_provider_id` is required |

| `GET` | `/internal/federated-service-instances/{service_instance_id}` | One instance, by SRM's `service_instance_id`; `404` `instance-not-federated` if no partner hosts it |

An instance is the outbound `install-app` transaction FM wrote for SRM's hand-off, plus the

`remove-app` that ended it, if any. Only hand-offs count: their `request_summary` carries SRM's

`service_instance_id` and `app_provider_id`. A deploy started through the operator route

(§L.3b) has no SRM instance and isn't listed. When retries left several `install-app` rows for one

instance, the latest wins.

The body is shaped as SRM's own service instance, which SRM validates it against and which

forbids extra fields:

```json

{

  "id": "7e7dfe3f-da70-478c-86e9-b0559395a5a4",

  "service_specification_id": "7592770f-44aa-4635-9ced-39b186964e61",

  "zone_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",

  "ref": "federated:7e7dfe3f-da70-478c-86e9-b0559395a5a4",

  "state": "active",

  "app_provider_id": "acme",

  "federation_partner_ref": null,

  "metadata": {"provider": "federation", "partner_op_id": "3f6c1d7e-9a52-4b08-b6d2-2e4f8a913c55"},

  "capabilities": [],

  "created_at": "2026-10-15T09:00:00Z",

  "updated_at": "2026-10-15T09:02:10Z",

  "terminated_at": null

}

```

| `state` | When |

|---|---|

| `creating` | `InstallApp` accepted, no final `onInstanceStatusEvent` yet |

| `active` | The partner reported `READY` |

| `failed` | The partner reported `FAILED` |

| `terminated` | FM sent `RemoveApp` and the partner accepted it (`200`) or no longer had the instance (`404`); OPG.04 has no removal callback |

`zone_id` is the platform-side zone UUID from `GET /internal/federated-zones`. Topology hiding

holds: the partner's `appInstIdentifier`, its own `zoneId` and the `federationContextId` stay in

FM. `federation_partner_ref` is `null` because SRM uses it for the partner a deploy came *from*;

these went out from us.

#### Commands FM consumes: `command.fm.service.deploy` and `command.fm.service.terminate`

| Subject | Stream | Payload | Published by SRM when |

pending.

The result, success or failure, arrives only on `event.fm.operation.completed` (§M.1). FM returns no

instance state, partner topology or `federationContextId` to SRM; the topology-hiding rules

(REQ-FED-13) apply to that event like every other FM output.

partner topology or `federationContextId` to SRM, on that event or on the instance reads above,

which carry the instance's state and nothing of the partner's; the topology-hiding rules

(REQ-FED-13) apply to both like every other FM output.

### L.3b OEG → FM Internal HTTP (Federation-Lifecycle Proxy, ADR-0051)

| 2.0 | 2026-10-08 | §L.3a: terminate publish trigger aligned with ADR-0053's 2026-10-08 amendment (instance absent from SRM local inventory; no partner instance rows). |

| 2.0 | 2026-10-13 | REQ-FED-19: bootstrap federates with registered partners, it does not register them. REQ-FED-20, §L.2 and §L.3b: `GET /internal/identity` (proxied by OEG) and the rule that `CreateFederation`'s identity fields must be FM's own. §L.3b: the partner routes' "not built yet (federation-manager#20)" note removed; the partner body can carry the secret (ADR-0067). ADR-0051, amended 2026-10-13. |

| 2.0 | 2026-10-13 | §L.3a and §M.3: the deploy-callback deadline (`deadline_expired`) is marked not built yet. §L.3b: the internal `POST .../federations/{federationContextId}/applications` deploy route (ADR-0068), not relayed by OEG. §L.3a refusals list the `urn:oop:fm:error:*` types FM publishes; the partner-status and agreement checks and the `partner-unreachable` event are marked not built yet. §L.1a: callback status column says built / not built yet; the callback link defaults are FM's own local URLs. §K.1: the table definitions moved to fm/persistence-model.md §J.1, now the single source for FM's schema. REQ-FED-08/09, the SRM endpoint and subject tables, and Workflow 1: catalogue re-sync, capacity check and rate limit marked not built yet; REQ-FED-06 (Service API capability operations), REQ-FED-07, the Service API mapping and Workflow 2 marked proposed, to be discussed in the next releases; Workflow 1 resolves the application from EWBI onboarding first. Full audit against FM `develop`: REQ-FED-05/11/12/15/17/19/21, §J, §K.2, §L.1–§L.5, §M and Workflow 1 corrected (EWBI operations FM serves or not, no `oop-commons`, error types as FM returns them, `FmOperationCompletedV1` nullability, integration points); §L.3 marked proposed. Second pass: all error codes FM returns listed in §L.5; the EWBI request-validation gap noted in REQ-FED-14 and §L.5; Workflow 1 step 21 marked not built yet. ADR-0068 (was ADR-0061 on this branch, renumbered to clear `develop`'s ADR-0061). |

| 2.0 | 2026-10-15 | §L.3a: `GET /internal/federated-service-instances` and `.../{service_instance_id}`, so SRM's instance reads can include partner-hosted instances it keeps no rows for (ADR-0053); REQ-FED-21 extended. The "no instance state to SRM" sentence narrowed to partner topology and `federationContextId`. |

  JSON path as the `GET /zones` `region` filter above). This endpoint does not yet perform that

  join — `region` is accepted but not filtered server-side today (open question, see

  [oeg/app-instance-flow.md](/oeg/app-instance-flow.md) Open Questions, OQ-05).

- **Partner-hosted instances.** SRM keeps no rows for them (§F.4a), so both forms above ask FM:

  the single-instance form calls `GET /internal/federated-service-instances/{service_instance_id}`

  when the id isn't in the local inventory (FM's `404` stays a `404`), and the collection form

  appends `GET /internal/federated-service-instances?app_provider_id=...`, filtered by the same

  `service_specification_id` / `service_instance_id`, to the local rows. FM returns SRM's own

  instance shape ([fm/requirements-and-design.md §L.3a](/fm/requirements-and-design.md)). Any

  other FM error fails the read.

- `GET /network-capabilities/{service_instance_id}` — the capability projection of one async

  network-capability realization: `service_instance_id` (= the caller-facing CAMARA id, ADR-0033),

  `capability_type` (derived via `capability_id → capability.kind`, never from

`service_instance` rows. The order stays `in_progress` until every `federated_handoff` target is

non-`pending`; SRM then completes it and publishes `event.srm.operation.completed` listing local

instances plus partner entries from `federated_handoff`, which is what OEG updates its

`app_instances` from.

`app_instances` from. Reads of a partner-hosted instance go to FM (§E.1).

**Retry ownership.** SRM owns getting the command onto `OOP_TASKS`, inside its own `command.srm.*`

handling. FM owns everything after

| 2.0 | 2026-10-02 | §E.3: `GET /zones` `state` values listed as `active`/`inactive`/`unknown`, the CAMARA `edgeCloudZoneStatus` values, so OEG's unchanged pass-through matches (ADR-0062). |

| 2.0 | 2026-10-08 | §F.4a: ADR-0053 amendment — partner progress on `service_order.federated_handoff` only; no partner zone/instance inventory; terminate again keys off "not found locally"; complete when no `federated_handoff` target is `pending`. |

| 2.0 | 2026-10-13 | §F.4a: FM's deploy-callback deadline (`deadline_expired`) is marked not built yet (ADR-0053). |

| 2.0 | 2026-10-15 | §E.1: both instance reads include partner-hosted instances from FM's `GET /internal/federated-service-instances` (fm/requirements-and-design.md §L.3a); §F.4a points there. |