Commit 4ee40871 authored by Dimitrios Gogos's avatar Dimitrios Gogos
Browse files

docs: enhance SRM and OEG interface contracts with provenance details for... 

docs: enhance SRM and OEG interface contracts with provenance details for network capability commands
parent da7c5a45

fm/requirements-and-design.md

+5 −0
Changes for fm/requirements-and-design.md: 5 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -270,6 +270,11 @@ partner's tenant identity — `partner_ops.id` (ADR-0001, ADR-0018). 
| `command.srm.network.capability.activate` | Inbound EWBI network capability request | `SrmNetworkCapabilityActivateV1` |

| `command.srm.network.capability.deactivate` | Inbound EWBI network capability release | `SrmNetworkCapabilityDeactivateV1` |



FM populates `network_capability.source_spec` with `family=gsma_opg` and the vendored OPG.04 API

version it mapped from ([srm/interface-contract.md](/srm/interface-contract.md) §B.5). The envelope's

`source=federation` records which component published the command, not which specification the payload

was translated from; the two differ on every federated request, so neither substitutes for the other.



**Consuming from `OOP_EVENTS`:**



| Subject | Consumer | Purpose |

oeg/interface-contract.md

+2 −0
Changes for oeg/interface-contract.md: 2 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -180,6 +180,8 @@ OEG also publishes `command.srm.network.capability.activate` / `.update` / `.dea 


Reads for these families use `GET /internal/network-capabilities/{service_instance_id}` and its collection form ([srm/interface-contract.md](/srm/interface-contract.md) §E.1) for capability detail; OEG resolves identity, ownership and cached status from `qod_sessions` / `traffic_influences` first, exactly as `/appinstances` resolves from `app_instances` before reading instance detail live.



**Provenance on requests to SRM.** OEG populates `source_spec` with the family, API and vendored `info.version` of the external spec that served the request — as `network_capability.source_spec` on the activate/update commands ([srm/interface-contract.md](/srm/interface-contract.md) §B.5) and as the top-level field on the §E.2 sync query bodies. OEG owns the spec-to-canonical translation, so it is the only component that has seen the original payload; omitting it makes SRM fall back to the catalog template's provenance, which cannot distinguish two API versions served side by side (§H.1). Deploy/scale/terminate carry no `source_spec` — Compute Resource Intent (`srm.compute/v1`) has no such field.



This alignment matters because OEG and SRM must share the same interpretation of `command.srm.*` messages.



Reference: [srm/interface-contract.md](/srm/interface-contract.md) §B.

srm/canonical-parameters-schema.md

+8 −0
Changes for srm/canonical-parameters-schema.md: 8 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -136,6 +136,14 @@ though they persist nothing. 
}

```



**`family: internal` — no external specification produced this shape.** Used when the

payload was not translated from an external API: an operator-created catalog entry

(trusted catalog/admin path) or a platform-seeded requirement (Interface Contract §E.2).

`api` names the SRM-side origin — the specification's `ref` — and `version` its

`service_specification.version`, never a vendored external `info.version`. This is a

positive statement that no external spec was mapped, not a placeholder for provenance

that is unknown or missing.



### CAMARA → canonical mapping (proof of coverage)



| CAMARA field | Canonical path |