refactore: simplify oeg docs

1. Read [platform/architecture.md](platform/architecture.md) for the end-to-end mental model.

2. Open the component folder ([oeg/](oeg/), [srm/](srm/), [fm/](fm/), [tf-sdk/](tf-sdk/), [data-lab/](data-lab/), [portal/](portal/), [ai2/](ai2/)) via its `index.md`.

3. Follow architecture → interface contract → persistence model → flow walk-throughs in that order.

3. Follow the reading order stated in that component’s index. OEG uses overview → requirements and design → implementation and delivery → interface contract.

4. When a spec cites an ADR, read the decision record for the rationale behind the rule.

**Looking up a term or cross-cutting concern**

| [ai2/](ai2/) | AI² — agent and MCP server over OEG's APIs |

| [decisions/](decisions/) | Architecture Decision Records |

| [external-specs/](external-specs/) | Vendored third-party API definitions |

| [archive/](archive/) | Superseded working documents |

| `archive/` (planned) | Superseded working documents, created when needed |

title: "AI² — Overview & Architecture"

description: "What AI² (AI squared) is: the platform's AI component, an agent and an MCP server that turn a chat message into OEG calls made as the caller. Who can use it, its terms, features, boundaries with the portal, OEG, Groq and Redis, assumptions and open questions."

tags: [ai2, mcp, agent, llm, architecture]

timestamp: 2026-10-21T00:00:00Z

timestamp: 2026-10-22T00:00:00Z

component: AI²

version: "2.0"

status: "ETSI SDG OOP"

**OEG: every platform action.** Each tool calls one OEG CAMARA operation with the caller's

token. OEG checks the token's scopes and answers in CAMARA's error format, which the tool turns

into a tool error ([oeg/interface-contract.md](/oeg/interface-contract.md)). Where OEG does not

yet scope reads and deletes by tenant ([oeg/architecture.md F5](/oeg/architecture.md)), neither

does AI².

into a tool error ([oeg/interface-contract.md](/oeg/interface-contract.md)). OEG applies provider

ownership checks to reads and deletes; another provider's resource is hidden with 404. AI² uses

the caller's token and does not bypass those checks. Organization-wide sharing remains unresolved

([OEG ownership rules](/oeg/requirements-and-design.md#i1-authentication-and-ownership),

[OEG F5](/oeg/overview-and-architecture.md#f-open-questions)).

**Keycloak: tokens only.** AI² never calls Keycloak. It receives tokens Keycloak issued and

passes them on without checking them (F1).

## Revision History

| Version | Date | Summary |

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

| 2.0 | 2026-10-21 | First version, describing the Release 2 implementation. |

| Version | Summary |

|---|---|

| 2.0 | Initial specification for OOP Release 2.0. |

title: "CAMARA Edge Application Management — Vendored Spec Snapshot"

description: "Pinned OpenAPI snapshot from camaraproject/EdgeApplicationManagement with commit-level provenance for OEG NBI implementation."

tags: [external-spec, camara, oeg]

timestamp: 2026-07-07T00:00:00Z

timestamp: 2026-10-22T00:00:00Z

component: external

version: "1.2"

version: "2.0"

status: "API info.version 0.1.0-alpha.1; pinned at upstream release r1.1, commit 8798eac (see Provenance)"

---

**Companion documents:** [external-specs/index.md](/external-specs/index.md) (vendoring convention, ADR-0026)

The metadata version identifies this OOP document edition. Upstream release tags, API versions and source commits are recorded separately below.

Source repo: https://github.com/camaraproject/EdgeApplicationManagement

Fetched from: release tag `r1.1` (main spec); `main` (common files)

Fetched: 2026-09-30 (main spec); 2026-07-04 (common files)

zones) and returns an `AppDeploymentInfo` identified by `appDeploymentId`;

the per-zone `appInstanceId`s are read back via

`GET /deployments?appDeploymentId=...`. This split drives the two OEG

flows: [oeg/app-instance-flow.md](/oeg/app-instance-flow.md) (single zone)

and [oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md) (multi-zone);

flows: [OEG single-zone design](/oeg/requirements-and-design.md#j2-single-zone-deployment) (single zone)

and [OEG multi-zone design](/oeg/requirements-and-design.md#j3-multi-zone-deployment) (multi-zone);

see also ADR-0005 and ADR-0007.

**URL pin.** The vendored OpenAPI `servers` entry uses path segment `v0.1alpha1`; OEG serves

`/edge-application-management/v0.1alpha1/...` ([oeg/architecture.md](/oeg/architecture.md) §H.1).

`/edge-application-management/v0.1alpha1/...` ([OEG versioning design](/oeg/requirements-and-design.md#i2-api-paths-and-compatibility) §I.2).

## Revision History

| Version | Date | Summary |

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

| 1.0 | 2026-07-04 | Initial vendored CAMARA EAM snapshot (fetched 2026-07-04, repo HEAD 7924d48). |

| 1.1 | 2026-07-07 | OKF frontmatter, license note, link to external-specs index and ADR-0026. OOP Release 2 URL pin: exposed segment `v1` vs vendored `vwip`/`wip` documented. |

| 1.2 | 2026-09-30 | Main spec re-vendored at upstream release `r1.1` (`0.1.0-alpha.1`, commit 8798eac), matching OEG; path segment `vwip` → `v0.1alpha1`. |

| Version | Summary |

|---|---|

| 2.0 | Initial specification for OOP Release 2.0. |

title: "Federation Manager — Overview & Architecture"

description: "Federation Manager mental model, business view, use cases, and architecture; terminates the East/Westbound Interface."

tags: [fm, federation, architecture]

timestamp: 2026-07-07T00:00:00Z

timestamp: 2026-10-22T00:00:00Z

component: Federation Manager (FM)

version: "2.0"

status: "ETSI SDG OOP"

**Companion documents:**

[fm/requirements-and-design.md](/fm/requirements-and-design.md), [fm/implementation-and-delivery.md](/fm/implementation-and-delivery.md)

**OEG implementation evidence:** the [OEG disagreement register](/oeg/requirements-and-design.md#n3-disagreements-and-decision-register) distinguishes intended contracts from selected implementation, including operations GET, native health/helpers, consent, messaging, relay query bytes and network-policy evidence. These disagreements remain unresolved.

## Mental Model

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

| Area | Current architecture position |

|---|---|

| **EWBI termination** | Terminate all inbound EWBI HTTPS requests routed via the partner-facing ingress under the OPG.04 server prefix `/operatorplatform/federation/v1/*`. That ingress is not deployed today, so there is no partner-facing EWBI ingress and inbound federation from external partner OPs is not exercised — it is a future release (OEG interface-contract §K.0). Separately, eight GSMA operations arrive for the operator-triggered *outbound* direction as a synchronous internal HTTP call from OEG's own `/platform/v1/federation/partners/{partnerOpId}/federations/...` namespace onto FM's mirrored `/internal/*` endpoint (§L.3b; ADR-0051), carrying the raw GSMA payload and query string byte-for-byte, protected only by cluster-internal network-policy reachability and validated/executed by FM — this path works today and does not depend on the partner-facing ingress. The two directions are on different paths entirely, not split at the ingress. Client mTLS is a future defense-in-depth layer (ADR-0042) for the EWBI partner hop, not required today and not applicable to the internal OEG→FM hop. |

| **EWBI termination** | Terminate all inbound EWBI HTTPS requests routed via the partner-facing ingress under the OPG.04 server prefix `/operatorplatform/federation/v1/*`. That ingress is not deployed today, so there is no partner-facing EWBI ingress and inbound federation from external partner OPs is not exercised — it is a future release (OEG [interface-contract §1](/oeg/interface-contract.md#1-api-surfaces-and-errors)). Separately, eight GSMA operations arrive for the operator-triggered *outbound* direction as a synchronous internal HTTP call from OEG's own `/platform/v1/federation/partners/{partnerOpId}/federations/...` namespace onto FM's mirrored `/internal/*` endpoint (§L.3b; ADR-0051), carrying the raw GSMA payload and query string byte-for-byte, protected only by cluster-internal network-policy reachability and validated/executed by FM — this path works today and does not depend on the partner-facing ingress. The two directions are on different paths entirely, not split at the ingress. Client mTLS is a future defense-in-depth layer (ADR-0042) for the EWBI partner hop, not required today and not applicable to the internal OEG→FM hop. |

| **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, via OEG's synchronous proxy on `/platform/v1/federation/partners/...` (§N.7, §L.3b; ADR-0051) — partner registration, agreements, and the eight federation-lifecycle operations. Routing rules stay on FM's own internal admin API (L.2).

- **Actor:** Operator, via OEG's synchronous proxy on `/platform/v1/federation/partners/...` (OEG contract §5, FM §L.3b; ADR-0051) — partner registration, agreements, and the eight federation-lifecycle operations. Routing rules stay on FM's own internal admin API (L.2).

- **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. **Register the partner.** The operator calls `POST /platform/v1/federation/partners`; OEG forwards the L.2 partner body byte-for-byte to `POST /internal/partners`. Profile fields: name, MCC-MNC, the partner's EWBI base URL, the client ID we issued the partner, and for outbound calls our client ID at the partner, its secret (a mounted-file reference, or the value itself, stored encrypted; ADR-0067) and the partner's token endpoint.

## Revision History

| Version | Date | Summary |

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

| 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 | Dropped the `X-Federation-Correlation-ID` extension (UC-FM-02/UC-FM-05, scope, glossary): no custom headers on EWBI; correlation via OPG.04 identifiers. |

| 2.0 | 2026-09-08 | OEG→FM transport for the *operator-triggered* federation-establishment trigger moves from async over the DataBus (ADR-0043) to a synchronous internal HTTP call (ADR-0046); scope, the operator endpoint and its payload are unchanged from ADR-0043. FM authenticates OEG's platform service credential and maps the operator payload to OPG.04; FM mints `federationContextId` and replies on the same call. Inbound EWBI termination is unchanged — the whole `/operatorplatform/federation/v1/*` prefix stays with FM, no OEG carve-out. UC-FM-06, boundaries and boundary matrix updated; `command.fm.federation.*` consumer row replaced. |

| 2.0 | 2026-09-08 | A.1 EWBI-termination row notes the Nginx EWBI ingress is not deployed today, so there is no partner-facing inbound EWBI ingress and inbound federation is a future release; the operator-triggered OEG→FM internal path (§L.3b) works today regardless. Clarification, no behaviour change. |

| 2.0 | 2026-09-08 | ADR-0051 corrects ADR-0046's scope/payload/namespace (transport kept): OEG serves **seven** canonical OPG.04 federation-lifecycle operations (create/read/update/delete federation, `GetFederationContextId`, zone subscribe/unsubscribe) for the operator-triggered *outbound* direction, on `/operatorplatform/federation/v1/*`, forwarding the raw GSMA payload **byte-for-byte** — FM no longer "maps an operator-facing payload to OPG.04". Inbound partner traffic on the same paths still terminates at FM; the two directions split at the ingress. Intro bullets, A.1 EWBI-termination row, UC-FM-06, dependency and boundary-matrix rows updated. |

| 2.0 | 2026-09-16 | ADR-0051 amended after FM-side review, reversing this file's own previous entry above: OEG's federation-lifecycle surface moves back to its own `/platform/v1/federation/partners/{partnerOpId}/federations/...` namespace, not the canonical prefix — the two directions no longer share a URL or split at the ingress at all. Eight operations now (`GetZoneData` added). The "authenticated by OEG's platform service credential" language is corrected everywhere it appeared: this hop has no dedicated credential, only cluster-internal network-policy reachability. Intro bullets, A.1 EWBI-termination row, UC-FM-06, dependency and boundary-matrix rows updated again. ADR-0047/0048 renumbered to ADR-0050/0051. |

| 2.0 | 2026-09-24 | UC-FM-06 rewritten: partner registration goes through OEG onto L.2 `/internal/partners` (the id FM assigns is the `partnerOpId`), agreements and routing rules stay on L.2 directly, federation establishment and later changes go through OEG. Removes the contradictory "read/update/decommission via L.2, unchanged" step. ADR-0051, amended 2026-09-24. |

| 2.0 | 2026-10-08 | UC-FM-07 / §G4: ADR-0053 amendment — SRM tracks pending partner targets in `service_order.federated_handoff`; no partner zone/instance inventory in SRM. |

| 2.0 | 2026-10-13 | UC-FM-06 matches the built FM: the profile fields are the partner API's, the secret may be typed in (ADR-0067); agreements and routing rules are not needed to federate (and not built yet); bootstrap federates with partners already registered, it does not register them; `CreateFederation`'s identity fields come from OEG's `GET /platform/v1/federation/identity`. ADR-0051, amended 2026-10-13. |

| 2.0 | 2026-10-13 | G4: the 30-minute deploy-callback wait is marked not built yet (ADR-0053). |

| 2.0 | 2026-10-13 | UC-FM-01, -03, -06 and -07 rewritten, text and diagrams, to match FM `develop`: `InstallApp` answers `202` and reports through `onInstanceStatusEvent`; the zones we offer are computed on request and partner zones come from `CreateFederation` and operator subscriptions; partner registration and federation go through OEG; the SRM hand-off runs over the DataBus with onboarding before `InstallApp`. Capacity check, rate limit and catalogue re-sync are marked not built yet. UC-FM-02, -04 and -05 (federated Device Location, Device Status and network capabilities such as QoS) are marked proposed, to be discussed in the next releases. |

| 2.0 | 2026-10-13 | Mental model, diagram, A.1, scope and assumptions match FM `develop`: the SRM hand-off goes over the DataBus; FM consumes only `event.srm.operation.completed`; the zones we offer are computed on request; no `oop-commons` dependency. Periodic partner health checks, `operation.status` consumption and the agreement/routing admin API marked not built yet; Service API capabilities and queries marked proposed |

| 2.0 | 2026-10-19 | UC-FM-06: agreements are proxied by OEG like partner registration, with `GET /local-zones` to pick zones; routing rules alone stay on L.2 (ADR-0051, amended 2026-10-15). |

| Version | Summary |

|---|---|

| 2.0 | Initial specification for OOP Release 2.0. |

title: "FM Persistence Model"

description: "Federation Manager domain model and storage design: entities, fm_db schema, DataBus roles, and operational guidance."

tags: [fm, federation, persistence]

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

timestamp: 2026-10-22T00:00:00Z

component: Federation Manager (FM)

version: "2.0"

status: "ETSI SDG OOP Release 2 — living draft, tracked against the FM rewrite"

status: "OOP Release 2.0 specification — implementation status documented separately"

---

# FM Persistence Model

> **Status: living draft.** This document promotes the data model from

> [requirements-and-design.md](/fm/requirements-and-design.md) §J–§K into a first-class

> persistence model (mirroring [oeg/persistence-model.md](/oeg/persistence-model.md) and

> persistence model (mirroring [OEG data dictionary](/oeg/interface-contract.md#9-data-dictionary) and

> [srm/persistence-model.md](/srm/persistence-model.md)). It is the authoritative FM schema and

> is expected to change as the FM rewrite lands each table. §"Implementation Status" tracks what

> is actually built versus specified.

## Revision History

| Version | Date | Summary |

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

| 2.0-draft | 2026-08-06 | Initial FM persistence model, promoted from requirements-and-design §J–§K. |

| 2.1-draft | 2026-09-08 | Align entities, context routing, transaction audit fields, ADR references, and DataBus roles with current FM architecture. |

| 2.1-draft | 2026-09-08 | Dropped `X-Federation-Correlation-ID`; `federation_correlation_id` replaced by `external_txn_id`. |

| 2.1-draft | 2026-09-08 | `federation_contexts` landed in code; status vocabulary enumerated from the OPG.04 `Status` enum. |

| 2.1-draft | 2026-09-08 | `external_resource_id` records the wire spelling of the external identifier; LCM audit columns (idempotency key, request fingerprint, callback) landed in code. |

| 2.1-draft | 2026-10-13 | Single source for FM's schema: §J.1 takes over the table definitions from requirements-and-design §K.1, adding `partner_op_secrets` (ADR-0067) and `federation_agreements.zone_resources`. §J.2 subjects corrected for ADR-0051 and ADR-0053. Implementation status brought up to date with FM `develop`. |

| 2.1-draft | 2026-10-16 | `federation_agreements`: partial unique index `uq_federation_agreements_one_per_partner`, so a partner has one agreement that isn't `expired` (migration `0008_one_agreement_per_partner` marks the extra ones `expired`). |

| 2.1-draft | 2026-10-16 | `partner_ops.supported_apis` built (the partner's `platformCaps`); `federation_contexts.offered_zone_ids` added (migration `0009_zone_offer_state`). |

| 2.1-draft | 2026-10-13 | Full audit against FM `develop`: shared-resource types, synchronous-query audit order, secret storage, Alembic, operator access to `/internal/*` and topology-hiding names corrected; module tree moved to implementation-and-delivery §O; partner SLA/API columns and rate limiting marked not built yet. |

| Version | Summary |

|---|---|

| 2.0 | Initial specification for OOP Release 2.0. |