Merge branch 'docs/srm-list-svc-spec-endpoint' into 'develop'

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=...`

(`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

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

(`srm/interface-contract.md` §E.1), with `app_provider_id` from the JWT. SRM scopes the result

to that tenant, so OEG does not post-filter by tenant — the

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

which OEG resolves back to `appId` per row via `oeg_db` (`app_registrations`) to build the

response. Returns an empty array when nothing matches.

  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: the list form hits

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

  `GET /internal/catalog/service-specifications?app_provider_id=...` (from the JWT), 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

| Method | Path | Purpose |

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

| GET | `http://srm:8081/internal/catalog/service-specifications` | Catalog proxy (list/get service specs) |

| GET | `http://srm:8081/internal/catalog/service-specifications` | Catalog proxy (list/get service specs); the list form requires `app_provider_id` |

| POST | `http://srm:8081/internal/catalog/service-specifications` | Synchronous catalog write for app registration (`POST /apps`) — the one synchronous internal-HTTP mutation, see [oeg/architecture.md](/oeg/architecture.md) |

| GET | `http://srm:8081/internal/zones` | Zone list for deployment UX and operator tooling |

| GET | `http://srm:8081/internal/service-instances/{id}` | Live instance snapshot read (used by `GET`/`DELETE /appinstances`) |

| GET | `http://srm:8081/internal/network-capabilities/{service_instance_id}` | Live capability detail for one async network capability — used by `GET /sessions/{id}` and `GET /traffic-influences/{id}`. The path key is the caller-facing CAMARA id (ADR-0033) |

| GET | `http://srm:8081/internal/network-capabilities` | Collection form, filtered by `capability_type` / `service_specification_id` — used by `GET /traffic-influences?appId=...` |

| GET | `http://srm:8081/internal/network-capabilities` | Collection form, scoped by the required `app_provider_id` and filtered by `capability_type` / `service_specification_id` — used by `GET /traffic-influences?appId=...` |

| POST | `http://srm:8081/internal/network-queries/location` | Sync CAMARA Device Location query |

| POST | `http://srm:8081/internal/network-queries/device-status` | Sync CAMARA Device Status query |

**Illustrative internal read**

```http

GET http://srm:8081/internal/catalog/service-specifications

GET http://srm:8081/internal/catalog/service-specifications?app_provider_id=acme_corp

x-correlator: req-cat-001

```

  Because `appInstanceId == service_instance_id` (ADR-0005), OEG uses this endpoint directly to

  resolve the target of `DELETE /appinstances/{appInstanceId}` before publishing

  `command.srm.service.terminate` — no separate by-`external_ref` lookup is needed.

- `GET /service-instances` — collection form of the above, always scoped to the caller's own

  `app_provider_id` (from auth context, never client-supplied), and optionally filtered further

- `GET /service-instances` — collection form of the above, always scoped to one tenant by

  the required `app_provider_id` query param (set by OEG from the JWT), and optionally filtered further

  by `service_specification_id` and/or `service_instance_id`; same response shape as the

  single-instance form, as a list; ids/specs not found are simply omitted, not a 404 for the

  whole call. OEG uses this for genuinely multi-result reads — `GET /appinstances?appId=...`

  It differs from `GET /service-instances/{id}` by projecting the capability's canonical

  parameters and result rather than the instance and its capability list — callers of these API

  families need the QoS profile, duration, or traffic filters, not the runtime root.

- `GET /network-capabilities` — collection form, always scoped to the caller's own

  `app_provider_id` (from auth context, never client-supplied), optionally filtered by

- `GET /network-capabilities` — collection form, always scoped to one tenant by

  the required `app_provider_id` query param (set by OEG from the JWT), optionally filtered by

  `capability_type`, `service_instance_id`, `service_specification_id`, and `external_ref`.

  Same response shape as the single form, as a list; ids not found are omitted rather than

  failing the whole call. Serves OEG's `GET /traffic-influences?appId=...`, translating CAMARA

  before the future runtime-coordinator component exists.

- `GET /domains`, `GET /capabilities` — topology reads.

- `GET /service-instances?scope=all` — same response shape as the §E.1 collection read, but

  bypasses the auth-context `app_provider_id` filter: all `service_instance` rows, all

  tenants/apps. Requires an elevated/ops credential, not a tenant's own auth context.

  Diagnostics/ops use only — `service_instance` rows are soft-deleted, never removed (§F

  takes no `app_provider_id` filter: all `service_instance` rows, all

  tenants/apps. Diagnostics/ops use only — `service_instance` rows are soft-deleted, never removed (§F

  Terminate), so this list grows without bound over the platform's lifetime. OEG's

  tenant-facing `GET /appinstances` must use the scoped §E.1 form, never this one.

### E.4 Trusted catalog/admin

- `GET /catalog/service-specifications` — list with linked units/requirements.

- `GET /catalog/service-specifications?app_provider_id=<id>` — list with linked

  units/requirements for one tenant. `app_provider_id` is **required** (query param;

  same trusted-internal pattern as `GET /service-instances`). Response is an array of

  the same shape as `GET /catalog/service-specifications/{id}`; an unknown provider

  returns `200 []`, not `404`.

- `POST /catalog/service-specifications` — create a specification with its

  `service_deployment_unit`(s) and `service_capability_requirement`(s) in one transaction;

  emits `event.srm.catalog.updated`. `service_specification.id` is **optional client-supplied**: