docs(fm): update implementation and delivery configuration details and clarify...

each callback (`204` for `onPartnerStatusEvent` and `onInstanceStatusEvent`, `200` for

`onZoneResourceUpdateEvent`).

**Order of work.** `onPartnerStatusEvent` comes first: partners can already send it, and its effect

is specified (it updates `federation_contexts.status`, whose values mirror the callback's `Status`

enum). `onInstanceStatusEvent` follows with FM's outbound `InstallApp`, which creates the transaction

it updates, and publishing `event.fm.operation.completed` from it waits on ADR-0053.

`onZoneResourceUpdateEvent` waits for `shared_resource_catalogues`.

**Order of work.** `onPartnerStatusEvent` came first: it updates `federation_contexts.status`, whose

values mirror the callback's `Status` enum. `onInstanceStatusEvent` followed with FM's outbound

`InstallApp`, which creates the transaction it updates, and publishes `event.fm.operation.completed`

(ADR-0053). Both are built. `onZoneResourceUpdateEvent` is not built yet.

**Keycloak.** The `federation` realm defines a `fed-mgmt-notif` client scope and attaches it to each

partner client as an **optional** scope, beside the default `fed-mgmt`. Optional means a token only

- `api/security.py` and `application/authentication.py` validate inbound Bearer JWTs and resolve partner identity; `middleware/` handles topology hiding.

- `adapters/` handles PostgreSQL, DataBus, and HTTP client integrations.

### Configuration

Settings are environment variables with the `FM_` prefix (`core/config.py`; a `.env` file is also read).

| Setting | Default | Purpose |

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

| `FM_POSTGRES_URL` | `postgresql+asyncpg://fm:fm@localhost:5433/fm_db` | `fm_db` connection |

| `FM_POSTGRES_ECHO` | `false` | Log SQL statements |

| `FM_LOG_LEVEL` | `INFO` | Log level |

| `FM_NATS_URL` | `nats://localhost:4222` | DataBus |

| `FM_EVENT_CONSUMER_DURABLE` | `fm-event-worker` | Durable consumer name on `OOP_EVENTS` |

| `FM_SRM_INTERNAL_URL` | `http://localhost:8081` | SRM internal HTTP base URL |

| `FM_KEYCLOAK_ISSUER` | `http://localhost:8090/realms/federation` | Issuer partners' tokens must carry |

| `FM_KEYCLOAK_JWKS_URL` | unset | Where FM fetches the signing keys when it can't reach the issuer URL; unset means the issuer's JWKS |

| `FM_FEDERATION_ID`, `FM_COUNTRY_CODE`, `FM_MCC`, `FM_MNCS` | `oop-local`, `ES`, `214`, `07` | Our OPG.04 identity, sent on `CreateFederation` and served on `GET /internal/identity` |

| `FM_PLATFORM_CAPS` | `serviceAPIs` | Platform capabilities we advertise |

| `FM_PARTNER_STATUS_LINK` | `http://127.0.0.1:8082/operatorplatform/federation/v1/callbacks/partner-status` | Callback URL handed to partners; a deployment sets the URL partners can reach |

| `FM_INSTANCE_STATUS_LINK` | `http://127.0.0.1:8082/operatorplatform/federation/v1/callbacks/instance-status` | Same, for `onInstanceStatusEvent` after our `InstallApp` |

| `FM_AVAIL_ZONE_NOTIF_LINK` | unset | `availZoneNotifLink` for zone notifications |

| `FM_ALLOW_INSECURE_PARTNER_ENDPOINTS` | `false` | Allow plain-HTTP partner endpoints; development only |

| `FM_BOOTSTRAP_FEDERATION` | `false` | At startup, federate with every active partner that has no outbound context (ADR-0043) |

| `FM_PARTNER_SECRET_KEY` | unset | Key (base64url, 32 bytes) that encrypts typed-in partner secrets; unset, FM accepts only secret files (ADR-0067) |

---

## P. Implementation Mapping

| 2.0 | 2026-09-08 | S.3 Contract Tests: added the federation-lifecycle proxy alias note (ADR-0051) — OEG serves seven canonical OPG.04 operations for the operator-triggered outbound direction, disjoint from FM's surface by ingress split; open follow-ups recorded (explicit alias entry for the 74-op gate, an OEG-side conformance check, and the still-open OPG.04 contract version/vendoring). |

| 2.0 | 2026-09-16 | ADR-0051 amended after FM-side review, reversing this file's own previous entry above: OEG's alias moves to its own `/platform/v1/federation/partners/{partnerOpId}/federations/...` namespace, not the canonical prefix, removing the ingress-split framing entirely (no path collision at all). Now eight operations (`GetZoneData` added). The OPG.04 contract version question is resolved — pinned to v6.0 / artifact v1.4.0, FM's profiled overlay. ADR-0047/0048 renumbered to ADR-0050/0051. |

| 2.0 | 2026-10-13 | Application layer: the inbound capacity check is marked not built yet. |

| 2.0 | 2026-10-13 | Full audit against FM `develop`: module tree and key classes replaced with FM's real layout; no `oop-commons`; operator access to `/internal/*` is cluster-internal and authenticated at OEG; rate limiting, metrics, header stripping, partner health tracking and the OpenAPI contract gate marked not built yet; compliance snapshot and delivery status brought up to date |

| 2.0 | 2026-10-13 | Full audit against FM `develop`: module tree and key classes replaced with FM's real layout; no `oop-commons`; operator access to `/internal/*` is cluster-internal and authenticated at OEG; rate limiting, metrics, header stripping, partner health tracking and the OpenAPI contract gate marked not built yet; compliance snapshot and delivery status brought up to date. §O gains the configuration reference (all `FM_*` settings) |

| REQ-FED-11 | The system shall enforce per-partner rate limits keyed by `partner_op_id` and API type with configurable windows, to protect internal infrastructure from partner abuse. Limits are enforced per FM pod for the current release; the effective fleet-wide rate is approximately (configured limit × pod count) rather than a single global ceiling — see [fm/implementation-and-delivery.md](/fm/implementation-and-delivery.md) §Q.3. Not built yet. | OPG.02 v10.0 §3.3.2.2 (Traffic Management) |

| REQ-FED-12 | The system shall implement OPG.04 federation-management operations, including `CreateFederation`, `GetFederationDetails`, `DeleteFederationDetails`, `GetFederationHealth`, and `RenewFederation`, maintaining partner connection status and alerting on consecutive health-check failures. Not built yet: `RenewFederation`, and periodic health checks of partners with alerting; FM answers `GetFederationHealth`. | OPG.04 v6.0 OpenAPI v1.4.0 |

| REQ-FED-13 | The system shall persist all federation transactions (inbound and outbound) in `federation_transactions` in `fm_db` with enough detail for dispute resolution and audit compliance. | OPG.04 v6.0 |

| REQ-FED-14 | The system shall return EWBI errors as OPG.04 `application/problem+json` `ProblemDetails`, using only response statuses declared by each operation unless an explicit OOP OpenAPI profile extends the contract. | OPG.04 v6.0 OpenAPI v1.4.0 |

| REQ-FED-14 | The system shall return EWBI errors as OPG.04 `application/problem+json` `ProblemDetails`, using only response statuses declared by each operation unless an explicit OOP OpenAPI profile extends the contract. Not built yet on the partner-facing EWBI routes: request-validation failures are FastAPI's plain `422` and unexpected failures a plain-text `500`, not `ProblemDetails`; the OEG-proxied `/internal` routes already answer both as `ProblemDetails` (`invalid-request`, `internal-error`). | OPG.04 v6.0 OpenAPI v1.4.0 |

| REQ-FED-15 | The system shall expose `GET /healthz` and `GET /readyz`, with readiness checking PostgreSQL and DataBus connectivity (same baseline as OEG and SRM). Partner federation health is monitored per REQ-FED-12 but does not gate `/readyz`. | Platform baseline |

| REQ-FED-16 | For each OPG.04 operation mapped to SRM, FM shall publish the same canonical command subject and schema as OEG, ensuring SRM receives identical formats regardless of origin (ADR-0001). FM shall not expose `command.srm.service.scale` through EWBI unless a documented OPG.04 profile/extension defines that operation. | Platform binding (Component Boundary Matrix) |

| REQ-FED-17 | The system shall emit structured JSON logs including `correlation_id`, `external_txn_id`, `partner_op_id`, EWBI method/path, and outcome for all federation operations. Today FM logs JSON events (structlog) with timestamp, level, `service` and the identifiers each event adds; the per-request fields (EWBI method/path, outcome) are not built yet. | Platform baseline |

| `partner-response-invalid` | A partner's answer did not match the GSMA schema |

| `partner-rejected` | A partner refused the request |

| `internal-error` | Internal failure (topology-safe message only) |

| `invalid-request` | Request body or parameters failed validation; `invalidParams` names the fields (OEG-proxied `/internal` routes) |

| `service-not-applicable` | SRM reports that the query does not apply to this subscriber or service |

| `service-specification-unknown` | SRM does not know the service specification (outbound deploy, ADR-0068) |

| `instance-unknown` | A callback names an application instance FM does not know |

FM's internal routes also return `zone-not-federated` (`GET /internal/federated-zones/{zone_id}`: no partner offers the zone) and, on the partner registry (§L.2), `partner-registration-conflict` (a unique field is already registered), `partner-credentials-incomplete` (client id, secret and token endpoint must come together) and `partner-secret-storage-unavailable` (`501`, no `FM_PARTNER_SECRET_KEY`; ADR-0067).

Not built yet on the partner-facing EWBI routes: request-validation failures are FastAPI's plain `422` and unexpected failures a plain-text `500`, not `ProblemDetails`; the OEG-proxied `/internal` routes already answer both as `ProblemDetails` (`invalid-request`, `internal-error`).

Not built yet: `capacity-insufficient` (capacity check, REQ-FED-09) and `rate-limit-exceeded` (REQ-FED-11).

18. SRM fulfills and publishes `event.srm.operation.completed`.

19. FM consumes the event, updates the transaction by internal `operation_id`, and topology-hides the result.

20. FM obtains a `fed-mgmt-notif` token and sends the required `onInstanceStatusEvent` callback to persisted `appInstCallbackLink`, updating durable callback attempts/status.

21. `GetAppInstanceDetails` may supplement callback recovery but does not replace required callback delivery.

21. `GetAppInstanceDetails` may supplement callback recovery but does not replace required callback delivery (`GetAppInstanceDetails` is not built yet).

22. FM acknowledges the completion event after transaction and callback-delivery state are durable.

### Workflow 2: Outbound Federation — Device Location on Partner Network

| 2.0 | 2026-09-29 | REQ-FED-21 restored to its ADR-0053 wording (DataBus hand-off, deploy and terminate, outcome on `event.fm.operation.completed`); a conflict resolution when §L.3b's status rule merged in had put back the pre-ADR-0053 text. |

| 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. ADR-0068 (was ADR-0061 on this branch, renumbered to clear `develop`'s ADR-0061). |

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