docs: fix documentation and validation rules regarding app registration and...

description: "SRM DataBus contract — `command.srm.*` / `event.srm.*` with versioned envelope and per-command schemas"

tags: [adr]

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

status: "accepted — stream subject set for `OOP_EVENTS` amended by ADR-0022 (may also carry future `event.charging.>` subjects; SRM event subjects in this ADR unchanged)"

status: "accepted"

---

# ADR-0001: SRM DataBus contract — `command.srm.*` / `event.srm.*` with versioned envelope and per-command schemas

**Status:** accepted — stream subject set for `OOP_EVENTS` amended by ADR-0022 (may also carry future `event.charging.>` subjects; SRM event subjects in this ADR unchanged)

**Status:** accepted

**Date:** 2026-06-19

**Affects:** [srm/interface-contract.md](/srm/interface-contract.md), [srm/architecture.md](/srm/architecture.md), [oeg/architecture.md](/oeg/architecture.md), [oeg/interface-contract.md](/oeg/interface-contract.md), [oeg/persistence-model.md](/oeg/persistence-model.md), [platform/architecture.md](/platform/architecture.md)

**Envelope.** The envelope `source` enum is

`nbi_camara | nbi_tmf | operator_portal | federation`.

**Streams.** JetStream binds `OOP_TASKS` to `command.srm.>` (SRM sole consumer). `OOP_EVENTS` is

filtered on `event.srm.>` for SRM lifecycle events in this ADR; ADR-0022 additionally places

future charging events (`event.charging.>`) on the same stream without changing SRM's event

subject set.

**Streams.** JetStream binds `OOP_TASKS` to `command.srm.>` (SRM sole consumer). `OOP_EVENTS`

carries SRM lifecycle events on `event.srm.>`, and shares the stream with future charging events

(`event.charging.>`) from other producers (ADR-0022); SRM's own event subject set is `event.srm.>`.

## Consequences

description: "CAMARA app-instance vs deployment identity — `appInstanceId`/`appDeploymentId` are OEG-minted (adopted by SRM), and one operation maps to N app instances"

tags: [adr]

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

status: "accepted — read-path wording superseded by ADR-0007 (single-resource reads use collection query parameters, not path GETs); `instances[].zone_ref` renamed to `zone_id` (zone UUID) by ADR-0013; identity model unchanged; target-tuple pin field names aligned to SRM vocabulary by ADR-0031"

status: "accepted"

---

# ADR-0005: CAMARA app-instance vs deployment identity — `appInstanceId`/`appDeploymentId` are OEG-minted (adopted by SRM), and one operation maps to N app instances

**Status:** accepted — read-path wording superseded by ADR-0007 (single-resource reads use collection query parameters, not path GETs); `instances[].zone_ref` renamed to `zone_id` (zone UUID) by ADR-0013; identity model unchanged; target-tuple pin field names aligned to SRM vocabulary by ADR-0031

**Status:** accepted

**Date:** 2026-07-04

**Affects:** [srm/interface-contract.md](/srm/interface-contract.md), [srm/persistence-model.md](/srm/persistence-model.md), [srm/end-to-end-examples.md](/srm/end-to-end-examples.md), [oeg/architecture.md](/oeg/architecture.md), [oeg/persistence-model.md](/oeg/persistence-model.md), [oeg/app-instance-flow.md](/oeg/app-instance-flow.md), [oeg/interface-contract.md](/oeg/interface-contract.md), [platform/architecture.md](/platform/architecture.md), [platform/glossary.md](/platform/glossary.md)

description: "`oeg_db` schema — the flow docs' schema is authoritative; `app_registrations` is the CAMARA app record (surrogate PK per ADR-0010)"

tags: [adr]

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

status: "accepted — `app_registrations` keying and child-table FKs amended by ADR-0010 (surrogate PK `app_registration_id`; `app_id` unique external identity; internal FKs use `app_registration_id`)"

status: "accepted"

---

# ADR-0006: `oeg_db` schema — the flow docs' schema is authoritative; `app_registrations` is the CAMARA app record

**Status:** accepted — `app_registrations` keying and child-table FKs amended by ADR-0010 (surrogate PK `app_registration_id`; `app_id` unique external identity; internal FKs use `app_registration_id`)

**Status:** accepted

**Date:** 2026-07-04

**Affects:** [oeg/persistence-model.md](/oeg/persistence-model.md), [oeg/app-registration-flow.md](/oeg/app-registration-flow.md), [oeg/app-instance-flow.md](/oeg/app-instance-flow.md), [oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md)

Option (b). `oeg_db` uses the flows' schema:

- **`app_registrations`** is the CAMARA app record: `app_registration_id` (UUID PK, OEG-generated;

  ADR-0010), `app_id` (`UNIQUE NOT NULL` — the CAMARA `appId`, `= service_specification_id`),

  ADR-0010), `app_id` (`UNIQUE NOT NULL` — the CAMARA `appId`),

  `tenant_id`, `name`, `version`, `package_type`, `status`, `registered_at`, `updated_at`. Its

  `status` is the **registration lifecycle only** (`REGISTERED`, later `DELETED`); it is **not**

  flipped per deploy operation — instance state lives in `app_instances.state`.

- There is no separate client-registration entity; client identity is the JWT `client_id`

  (= `tenant_id`). **`api_subscriptions`** and **`api_usage_records`** are keyed by `tenant_id`.

- `app_instances` and `app_deployments` reference the owning app via `app_registration_id`

  (FK → `app_registrations`; ADR-0010). The CAMARA `appId` stays on the NBI/SRM surfaces as

  `app_id` / `service_specification_id`, resolved at request time.

  (FK → `app_registrations`; ADR-0010). The CAMARA `appId` stays on the NBI surface as `app_id`

  and reaches SRM as `service_specification.ref`; SRM commands carry `app_registration_id` as

  `service_specification_id`, resolved at request time (ADR-0011).

## Consequences

**Status:** accepted

**Date:** 2026-07-04

**Affects:** [oeg/app-instance-flow.md](/oeg/app-instance-flow.md), [oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md), [oeg/persistence-model.md](/oeg/persistence-model.md), [oeg/architecture.md](/oeg/architecture.md); amends the read-path wording of ADR-0005

**Affects:** [oeg/app-instance-flow.md](/oeg/app-instance-flow.md), [oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md), [oeg/persistence-model.md](/oeg/persistence-model.md), [oeg/architecture.md](/oeg/architecture.md)

## Context

The NBI surface matches the vendored OpenAPI file exactly, so contract tests can be generated

from it without exceptions. Clients must filter by query parameter and unwrap a one-element

array. ADR-0005's mentions of `GET /deployments/{appDeploymentId}` and

`GET /appinstances/{appInstanceId}` are superseded by this read-path rule (the identity model in

ADR-0005 is unchanged). Revisit trigger: a future CAMARA EAM release adding path GETs — adopt

them then.

array. `GET /deployments/{appDeploymentId}` and `GET /appinstances/{appInstanceId}` are not part

of the NBI surface; the identity model in ADR-0005 is unaffected. Revisit trigger: a future

CAMARA EAM release adding path GETs — adopt them then.

**Status:** accepted

**Date:** 2026-07-04

**Affects:** [oeg/persistence-model.md](/oeg/persistence-model.md), [oeg/app-registration-flow.md](/oeg/app-registration-flow.md), [oeg/app-instance-flow.md](/oeg/app-instance-flow.md), [oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md); amends ADR-0006's `app_registrations` keying **and** child-table FK topology (`operations`, `app_instances`, `app_deployments` → `app_registration_id`)

**Affects:** [oeg/persistence-model.md](/oeg/persistence-model.md), [oeg/app-registration-flow.md](/oeg/app-registration-flow.md), [oeg/app-instance-flow.md](/oeg/app-instance-flow.md), [oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md)

## Context

ADR-0006 keyed `app_registrations` directly by `app_id` (the CAMARA `appId`). ADR-0011 originally

made `app_id = service_specification_id` by accepting a caller-supplied catalog id as that value

(ADR-0011 was later amended, 2026-07-30, to send `app_registration_id` instead — see that ADR —

but the coupling problem described below is what this decision addresses regardless).

But `appId` is the **CAMARA-facing** identity of the application: the vendored spec defines it as

`app_registrations` (ADR-0006) needs a primary key, and the obvious candidate is `app_id` — the

CAMARA `appId` — since every request path already carries it. But `appId` is the

**CAMARA-facing** identity of the application: the vendored spec defines it as

platform-generated at submission, yet `AppManifest.appId` may also be supplied by the App

Provider, so OEG does not unconditionally control the value. Using an externally visible,

potentially client-supplied identifier as the internal primary key couples `oeg_db` FKs to the

All internal FKs (`operations`, `app_instances`, `app_deployments`) reference `app_registration_id`;

request handling resolves `appId → app_registration_id` when it validates that the app exists —

this same resolution is also what SRM commands key off of, as `service_specification_id`

(`= app_registration_id`, not `app_id`, per ADR-0011's 2026-07-30 amendment).

(`= app_registration_id`, not `app_id`, per ADR-0011).

## Consequences

Internal keys are decoupled from client-visible (and partially client-suppliable) identifiers;

this is what let a later re-registration/appId-reuse policy (soft-delete `app_registrations` on

`DELETE /apps/{appId}`, allow the freed `appId` to be re-registered) land without corrupting FK

this is what lets the re-registration/appId-reuse policy (soft-delete `app_registrations` on

`DELETE /apps/{appId}`, allow the freed `appId` to be re-registered) hold without corrupting FK

chains — each registration cycle gets its own `app_registration_id`, and history under an earlier

cycle stays attributed to it. **Current conflict behavior:** duplicate `appId` (an *active*

registration already in `oeg_db`) → `409 Conflict` / `ALREADY_EXISTS`

([oeg/app-registration-flow.md](/oeg/app-registration-flow.md)); a soft-deleted registration no

longer counts. Cost: one indexed lookup per request path (already needed to validate the app

exists) and one extra column. `app_id` keeps flowing outward unchanged (`service_specification.ref`,

CAMARA responses) — deploy commands carry `app_registration_id` instead, per ADR-0011's

2026-07-30 amendment.

CAMARA responses) — deploy commands carry `app_registration_id` instead, per ADR-0011.

Revisit trigger: none expected; this is a stable internal convention.