docs: align internal field names with SRM vocabulary

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"

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"

---

# 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

**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

**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)

`GET /deployments?appDeploymentId=...` (ADR-0007) and the deployment callback.

**Internal shapes (both paths).** `command.srm.service.deploy` carries a `targets[]` list (each

`{app_instance_id, resource_zone_id?, compute_domain_id?}`); SRM creates one `service_instance` per

`{app_instance_id, zone_id?, domain_id?}`); SRM creates one `service_instance` per

target using the provided `app_instance_id`. `event.srm.operation.completed` reports an

`instances[]` array — each entry carrying `service_instance_id` (= `appInstanceId`), `zone_id`

(zone UUID; ADR-0013), and per-instance `status` — replacing the single `service_instance_id`

Costs: (1) `command.srm.service.deploy` (`SrmServiceDeployV1`) gains a `targets[]` list (each

carrying an OEG-minted `app_instance_id` + optional zone/domain pins), replacing the single

top-level `resource_zone_id`; (2) `event.srm.operation.completed` (`SrmOperationCompletedV1`)

top-level `zone_id`; (2) `event.srm.operation.completed` (`SrmOperationCompletedV1`)

changes from a single `service_instance_id` to an `instances[]` list — both breaking internal

changes that OEG and FM consumers must adopt, and which the OOP Platform command/event summary must

reflect. SRM adopts the provided `app_instance_id` as its `service_instance` id and stops reusing

Option (a) — no new table until something needs to query targets relationally:

- `service_instance` gains `zone_id UUID NOT NULL REFERENCES zone(id)` — the zone the instance

  is (being) realized in, set from the target's `resource_zone_id` pin or the planner's choice.

  is (being) realized in, set from the target's `zone_id` pin or the planner's choice.

- The name-uniqueness constraint becomes a partial unique index on

  `(app_provider_id, ref, zone_id)` over live rows (`state NOT IN ('terminated','failed')`),

  mirroring `uq_ci_external_ref`: a multi-zone deploy may reuse one `instance_name` across zones,

description: "Zone identity on cross-component contracts is the zone UUID (`zone.id` = CAMARA `EdgeCloudZoneId`); `zone.ref` is internal-only"

tags: [adr]

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

status: "accepted"

status: "accepted — pin field naming aligned to SRM vocabulary by ADR-0031; zone identity model unchanged"

---

# ADR-0013: Zone identity on cross-component contracts is the zone UUID (`zone.id` = CAMARA `EdgeCloudZoneId`); `zone.ref` is internal-only

**Status:** accepted

**Status:** accepted — pin field naming aligned to SRM vocabulary by ADR-0031; zone identity model unchanged

**Date:** 2026-07-05

**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/persistence-model.md](/oeg/persistence-model.md), [oeg/app-instance-flow.md](/oeg/app-instance-flow.md), [oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md); amends the `instances[].zone_ref` field of ADR-0005's event shape

Two zone identifiers coexist: `zone.id` (UUID, PK in `srm_db`) and `zone.ref` (human-readable

slug like `zone-berlin-01`, from bootstrap YAML). The docs disagreed on which one crosses

component boundaries: `command.srm.service.deploy` normalizes the CAMARA `edgeCloudZoneId` into

`targets[].resource_zone_id` (a UUID), but `event.srm.operation.completed.instances[].zone_ref`

`targets[].zone_id` (a UUID), but `event.srm.operation.completed.instances[].zone_ref`

was shown carrying the slug in SRM examples and the UUID in OEG flow examples, and OEG's

`app_instances.zone_ref` column was an untyped VARCHAR. Since SRM is authoritative for zones and

OEG proxies the zone list to clients, the CAMARA `EdgeCloudZoneId` a client uses **is** SRM's

## Decision

Option (a). Every cross-component field that identifies a zone carries the zone UUID

(`zone.id` = the CAMARA `EdgeCloudZoneId`): `targets[].resource_zone_id` (already true),

(`zone.id` = the CAMARA `EdgeCloudZoneId`): `targets[].zone_id` (already true),

`event.srm.operation.completed.instances[].zone_id` (renamed from `zone_ref`), and OEG's

`app_instances.edge_cloud_zone_id` column (renamed from `zone_ref`, typed UUID). `zone.ref`

remains an internal human-readable label used in bootstrap YAML, structured logs, and operator

Option (a). The zone identifier that crosses the EWBI is the zone UUID itself — the same value

partners receive in the shared resource catalogue is the value they send back in deploy requests,

and FM places it directly into `targets[].resource_zone_id` with no translation. UUIDs reveal no

and FM places it directly into `targets[].zone_id` with no translation. UUIDs reveal no

internal naming conventions, so topology hiding is preserved without an alias layer, and no

mapping table exists to drift.

## Consequences

What becomes easier: OEG's `ResourceZoneMetadata.provider: str` (required, no default) is now

What becomes easier: OEG's `SRMZoneMetadata.provider: str` (required, no default) is now

correct and justified — no per-entry parsing failure risk from this field, and no zone can

silently disappear from `GET /edge-cloud-zones` due to a missing provider name. `platform_ref`

keeps its own distinct scope, so F3 is not conflated with this decision.

guaranteed key inside it is a partial exception that must stay clearly documented so future

readers don't assume the rest of `metadata` is similarly guaranteed.

Deferred or excluded: general per-entry defensive parsing in OEG's `get_resource_zones()` for

Deferred or excluded: general per-entry defensive parsing in OEG's `get_zones()` for

*other* unexpected SRM data issues is still worth doing as generic robustness, independent of

this guarantee. `architecture.md` F3 (multi-platform scoping via `platform_ref`) remains open and

unrelated to this decision.