docs: Update various flow specifications and interface contracts for clarity and accuracy

   to a **terminal state** (`deleted`, or an error state when SRM reports failure).

**Notification rule.** The CAMARA notification for user-requested teardown fires **only** on the

transition out of the live state. Because step 3 moves the record off that state synchronously, a

repeat `DELETE` is naturally idempotent — it neither re-publishes nor re-notifies. For QoD this

satisfies the spec rule that no event is sent when the status was already `UNAVAILABLE`.

transition out of the live state, with `qosStatus=UNAVAILABLE`, `statusInfo=DELETE_REQUESTED` for

QoD. Because step 3 moves the record off that state synchronously, a repeat `DELETE` is naturally

idempotent — it neither re-publishes nor re-notifies. For QoD this satisfies the spec rule that no

event is sent when the status was already `UNAVAILABLE`.

**Read behaviour after deletion.** CAMARA has no representation for a deleted session or policy,

so reads of a terminal record return `404`. The row is retained for audit and for the

  9. Write oeg_db:

       - operations row (PENDING)

       - app_deployments row (appDeploymentId → operation_id,

         app_registration_id resolved from appId (ADR-0010) — for referential

         integrity/joins back to app_registrations, not sent to SRM — appDeploymentName

         app_registration_id resolved from appId (ADR-0010) — also sent to SRM as

         the deploy command's service_specification_id (ADR-0011) — appDeploymentName

         from the request body, edgeCloudZones[])

       - one app_instances row per zone (state=instantiating, app_deployment_id set)

 10. Store callback if subscriptionRequest.sink present

## Response 2 — GET /appinstances (200 — List)

> **Implementation status:** not implemented on the SRM side — neither

> `GET /internal/service-instances` (collection) nor `GET /internal/service-instances/{id}`

> (single-instance) exists on SRM's `develop` branch today; only the catalog

> `service-specifications` endpoints are built. Responses 2 and 3 below, and the pre-delete

> check in the Terminate section, describe the intended design, not current behavior.

Returns the app instances for the authenticated client, optionally filtered by the CAMARA query

parameters `appId`, `appInstanceId`, and `region`. `region` is a real, distinct CAMARA-defined

free-text geography filter — "human readable name of the geographical Edge Cloud Region" — not

an alias for `edgeCloudZoneId`; it resolves through the instance's zone

(`zone.metadata.location.region`, same free-form field `GET /edge-cloud-zones?region=...` reads),

but SRM's collection read doesn't join that yet, so it's accepted but **not yet filterable**

(OQ-05 below).

parameters `appId` and `region` — a genuine multi-result list. (`appInstanceId` narrows to exactly

one known row and is handled by Response 3 below, not this collection path, regardless of whether

`appId` is also given.) `region` is a real, distinct CAMARA-defined free-text geography filter —

"human readable name of the geographical Edge Cloud Region" — not an alias for `edgeCloudZoneId`;

it resolves through the instance's zone (`zone.metadata.location.region`, same free-form field

`GET /edge-cloud-zones?region=...` reads), but SRM's collection read doesn't join that yet, so

it's accepted but **not yet filterable** (OQ-05 below).

OEG resolves `appId` to `app_registration_id` via `oeg_db` (unchanged from the single-instance

path), then calls `GET /internal/service-instances?service_specification_id=...&service_instance_id=...`

path), then calls `GET /internal/service-instances?service_specification_id=...`

(`srm/interface-contract.md` §E.1). SRM itself scopes the result to the caller's own

`app_provider_id` from auth context, so OEG does not pre-resolve or post-filter by tenant — the

collection SRM returns is already the correct set. Each row carries `service_specification_id`,

# Terminate — DELETE /appinstances/{appInstanceId}

Same async pattern as deploy. OEG looks up the `app_instances` row, writes a new `operations` row

(`operation_type = "terminate"`, `status = PENDING`), sets `app_instances.state = terminating`,

publishes `command.srm.service.terminate` (`SrmServiceTerminateV1`:

`service_instance_id = appInstanceId`, `terminate.grace_period_seconds`, see

[srm/interface-contract.md](/srm/interface-contract.md) §B.4), and returns `202 Accepted`.

Same async pattern as deploy. OEG looks up the `app_instances` row, then confirms with SRM —

the source of truth for whether the instance is still live — via

`GET /internal/service-instances/{appInstanceId}` (`srm/interface-contract.md` §E.1); a `404`

there maps straight to CAMARA `404 NOT_FOUND` and no command is published. Otherwise OEG writes a

new `operations` row (`operation_type = "terminate"`, `status = PENDING`), sets

`app_instances.state = terminating`, publishes `command.srm.service.terminate`

(`SrmServiceTerminateV1`: `service_instance_id = appInstanceId`, `terminate.grace_period_seconds`,

see [srm/interface-contract.md](/srm/interface-contract.md) §B.4), and returns `202 Accepted`.

**Completion (soft-terminate):** SRM processes the terminate command asynchronously and publishes

`event.srm.operation.completed` for this operation, same as the deploy completion path (§UC7 above).

- **`GET /apps`** and **`GET /apps/{appId}`** return `AppManifest` data. The manifest lives in

  SRM (`service_specification` + `service_deployment_units[]` — a catalog entry may carry more

  than one unit, and not every unit need carry its own `artifact_ref`) — OEG resolves the

  caller's `app_registrations` rows and proxies the SRM catalog read

  (`GET /internal/catalog/service-specifications`), translating back to the CAMARA manifest

  shape. `oeg_db` alone cannot serve these reads (it stores only the summary row, §8). If no

  caller's `app_registrations` rows and proxies the SRM catalog read: the list form hits

  `GET /internal/catalog/service-specifications`, the single form hits

  `GET /internal/catalog/service-specifications/{app_registration_id}` (addressed by the OEG

  surrogate, ADR-0011). Translated back to the CAMARA manifest shape. `oeg_db` alone cannot

  serve these reads (it stores only the summary row, §8). If no

  unit in the entry carries an `artifact_ref` — the only source for the CAMARA-mandatory

  `appRepo.imagePath` — the read fails with `DownstreamServiceException` (503 `UNAVAILABLE`)

  rather than omitting the entry: `getApps`' `200` has no partial-success shape, so a single

  ```

  api/

    camara/

      edge_application_management/v1/   (routes, request/response schemas — CAMARA EAM)

      edge_application_management/vwip/ (routes, request/response schemas — CAMARA EAM)

      qod/v0/                           (routes, request/response schemas)

    tmf/

      service_catalog/v4/    (routes, request/response schemas)