fix: recover from stale federated state

# EWBI contract artifacts

- `OPG.04-v6.0-EWBI-Federation-API-v1.4.0.yaml` — GSMA's published OpenAPI, vendored byte-for-byte

  (sha256 `890801d6…`). Never edited. The contract checker compares FM against this file.

- `opg04-v1.4.0-oop-profile.overlay.yaml` — [OpenAPI Overlay 1.0.0](https://spec.openapis.org/overlay/v1.0.0.html)

  document recording every known defect of the published artifact, each corrected from OPG.04

  v6.0 prose and cited by clause/table. This is the only place a deviation may be introduced.

- `OPG.04-v6.0-EWBI-Federation-API-v1.4.0-oop-profile.yaml` — generated result of base + overlay.

  Parses in Swagger Editor and other OpenAPI tooling. Regenerate after changing the overlay:

```bash

.venv/bin/python scripts/apply_overlay.py

```

overlay: 1.0.0

info:

  title: OOP profile for GSMA OPG.04 v6.0 EWBI Federation API v1.4.0

  version: 0.1.0

  description: |

    Recorded defects in the published GSMA artifact, corrected from OPG.04 v6.0 prose.

    The vendored artifact stays byte-identical; scripts/apply_overlay.py produces the

    rendered profile. Every action cites the OPG.04 clause or table that settles it.

  x-base-sha256: 890801d61c148762897f18ce3b88823c0d486b1defdd04227f6a65f97c62fccf

extends: ./OPG.04-v6.0-EWBI-Federation-API-v1.4.0.yaml

actions:

  # --- Structural defects: the artifact does not parse in OpenAPI tooling ---

  - target: $.components.schemas.serviceAPIContent.properties.APIContent

    description: Placeholder $ref 'https://github.com/camaraproject' is not a resolvable schema.

    remove: true

  - target: $.components.schemas.serviceAPIContent.properties

    description: >-

      OPG.04 §4.2.1.6.2.1 Table 196: APIContent is the Service API body as received over the NBI,

      whose schema is the CAMARA API named by serviceAPINameVal; opaque at the EWBI layer.

    update:

      APIContent:

        type: object

        additionalProperties: true

  - target: $.components.schemas.serviceAPIEventDef.properties.NetworkEventDef

    description: Placeholder $ref 'https://github.com/camaraproject' is not a resolvable schema.

    remove: true

  - target: $.components.schemas.serviceAPIEventDef.properties

    description: >-

      Network event payload defined by the CAMARA API in question; opaque at the EWBI layer.

    update:

      NetworkEventDef:

        type: object

        additionalProperties: true

  - target: $.paths['/{federationContextId}/application/onboarding/app/{appId}/zoneForbid'].post.requestBody.content['application/json'].schema.required

    description: LockUnlockApplicationZone declares required/properties on the array instead of its items.

    remove: true

  - target: $.paths['/{federationContextId}/application/onboarding/app/{appId}/zoneForbid'].post.requestBody.content['application/json'].schema.properties

    description: See previous action.

    remove: true

  - target: $.paths['/{federationContextId}/application/onboarding/app/{appId}/zoneForbid'].post.requestBody.content['application/json'].schema.items

    description: Same zoneId/forbid definition, moved under items where OpenAPI expects it.

    update:

      required:

        - zoneId

        - forbid

      properties:

        zoneId:

          $ref: '#/components/schemas/ZoneIdentifier'

        forbid:

          type: boolean

          description: Value 'true' will forbid application instantiation on this zone.  No new instance of the application can be created on this zone.

  # --- Semantic defects: artifact contradicts OPG.04 prose ---

  - target: $.paths['/{federationContextId}/apiservice/{serviceAPINameVal}'].post.requestBody.content['application/json'].schema.properties

    description: >-

      APIForwarding lists apiServiceId and customerInfo as required but defines neither.

      OPG.04 §4.2.1.2 Table 186 and §4.2.1.6.3.1 Table 201 define both as String.

    update:

      apiServiceId:

        type: string

        description: Named identifier of the API service, e.g. QualityOnDemand, DeviceStatus, DeviceLocation (Table 201).

      customerInfo:

        type: string

        description: Name identification information associated to the Application Provider of the Leading OP (Table 201).

  - target: $.paths['/{federationContextId}/apiservice/{serviceAPINameVal}'].post.requestBody

    description: OPG.04 §4.2.1.2 Table 186 marks the request data mandatory.

    update:

      required: true

  - target: $.paths['/{federationContextId}/application/lcm'].post.requestBody

    description: OPG.04 §4.1.4.2 Table 159 marks the InstallApp request data mandatory.

    update:

      required: true

  - target: $.components.schemas.serviceAPIResponse.properties.apiResponse

    description: apiResponse wrongly references the customerID (UUID) schema.

    remove: true

  - target: $.components.schemas.serviceAPIResponse.properties

    description: OPG.04 §4.2.1.6.2.5 Table 200 defines apiResponse as {mediaType, responseContent}.

    update:

      apiResponse:

        type: object

        required:

          - mediaType

          - responseContent

        properties:

          mediaType:

            type: string

            description: May contain value e.g. "application/json".

          responseContent:

            type: object

            additionalProperties: true

            description: Result of the Service API processing, formatted according to mediaType and defined by the Service API specification.

  - target: $.components.schemas.FederationHealthInfo.properties.federationStatus

    description: >-

      federationStatus references State, the alarm-lifecycle object {alarmState}. OPG.04

      §3.1.1.12.2.12 Table 41 defines it as the federation Status enum, and the

      onPartnerStatusEvent callback in this same document already uses Status for the

      identically named field.

    update:

      $ref: '#/components/schemas/Status'

  - target: $.components.schemas.serviceAPIResponse.required

    description: >-

      The artifact requires both targetUserContext and apiResponse; OPG.04 §4.2.1.6.2.2 Table 197

      makes targetUserContext conditional (session-based APIs) and apiResponse conditional

      (sessionless APIs).

    remove: true

  - target: $.components.schemas.serviceAPIResponse

    description: See previous action; at least one of the two conditional members must be present.

    update:

      required:

        - customerID

        - txnIdentifier

      anyOf:

        - required:

            - targetUserContext

        - required:

            - apiResponse