Commit 1e906714 authored by Dimitrios Gogos's avatar Dimitrios Gogos
Browse files

docs(oeg): remove overlapping topic pages and repoint links 

Remove oeg/architecture.md, oeg/persistence-model.md and
oeg/translation-example-uc1.md; their content duplicates the overview,
contract §9 and contract §6. Keep the three flow pages as plain-language
walkthroughs.

Repoint ADR and AI² links to the owning spec sections, keep historical
ADR context as plain filenames, and drop the stale AI² note about the
OEG spec naming /qod/v0.

Co-Authored-By: default avatarClaude Opus 5.5 <noreply@anthropic.com>
parent c74bab66

ai2/implementation-and-delivery.md

+1 −1
Changes for ai2/implementation-and-delivery.md: 1 added line, 1 removed line.
Original line number Diff line number Diff line
@@ -232,7 +232,7 @@ Unspecified means no reason has been agreed. 
| Health checks miss Groq, Redis and OEG | Unspecified | Watch the logs |

| Containers run as root; no pod security settings for the agent or MCP server | Unspecified | None |

| No CPU or memory requests or limits for the agent and MCP server | Unspecified | None |

| OEG does not yet scope reads and deletes by tenant, and that applies through AI² ([oeg/architecture.md F5](/oeg/architecture.md)) | Deferred in OEG's spec | None in AI² |

| OEG does not yet scope reads and deletes by tenant, and that applies through AI² ([oeg/overview-and-architecture.md F5](/oeg/overview-and-architecture.md#f-open-questions)) | Deferred in OEG's spec | None in AI² |

| Plain logs, `DEBUG` on the MCP server, no request id or metrics (F11) | Unspecified | None |

| `/debug/objgraph` needs no token (F9) | Unspecified | Keep the agent `ClusterIP` |

| The system prompt ends mid-sentence; `TOOL_USING_ASSISTANT_PROMPT` and `UserPhoneInput` are unused | Unspecified | None |

ai2/interface-contract.md

+1 −1
Changes for ai2/interface-contract.md: 1 added line, 1 removed line.
Original line number Diff line number Diff line
@@ -218,7 +218,7 @@ and `qosStatus` (`REQUESTED`, `AVAILABLE`, `UNAVAILABLE`). `statusInfo` is `DURA 


| Field | Rule |

|---|---|

| `device` | Optional here; same rules as §3.1. OEG requires it, since no token claim maps to a device ([oeg/architecture.md F4](/oeg/architecture.md)), so a call without it fails at OEG |

| `device` | Optional here; same rules as §3.1. OEG requires it, since no token claim maps to a device ([oeg/overview-and-architecture.md F4](/oeg/overview-and-architecture.md#f-open-questions)), so a call without it fails at OEG |

| `maxAge` | Seconds, at least 0 |

| `maxSurface` | Square metres, at least 1 |

ai2/overview-and-architecture.md

+2 −2
Changes for ai2/overview-and-architecture.md: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -18,7 +18,7 @@ status: "ETSI SDG OOP" 


**Closest neighbours:**

[portal/requirements-and-design.md](/portal/requirements-and-design.md),

[oeg/architecture.md](/oeg/architecture.md),

[oeg/overview-and-architecture.md](/oeg/overview-and-architecture.md),

[ADR-0048](/decisions/0048-platform-roles.md)



---
@@ -164,7 +164,7 @@ In the platform chart only the agent may connect to it; Docker Compose publishes 
| ID | Assumption | Risk if Wrong |

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

| E1 | Tokens the portal forwards carry the `oeg` audience and the user's product scopes, as for the portal's own OEG calls ([portal E2](/portal/overview-and-architecture.md)) | OEG refuses every tool call; the agent answers that it could not act |

| E2 | OEG checks the product scope on every operation a tool calls, QoD sessions included ([oeg/architecture.md §D](/oeg/architecture.md)) | A user could act through AI² beyond their grants. ADR-0048's Consequences say OEG skips QoD scope checks; OEG's spec says it enforces them. Confirm in OEG's code |

| E2 | OEG checks the product scope on every operation a tool calls, QoD sessions included ([oeg/overview-and-architecture.md §D](/oeg/overview-and-architecture.md#d-boundaries)) | A user could act through AI² beyond their grants. ADR-0048's Consequences say OEG skips QoD scope checks; OEG's spec says it enforces them. Confirm in OEG's code |

| E3 | Only the portal backend and trusted cluster software can reach the agent and MCP services | Anyone with any token string can run the LLM on the platform's Groq key (F1) |

| E4 | The Groq API key is set (`secrets.groqApiKey`) | Every chat answers `500` |

| E5 | The Groq model chosen supports tool calling | The model cannot call tools and answers without acting |

ai2/requirements-and-design.md

+1 −5
Changes for ai2/requirements-and-design.md: 1 added line, 5 removed lines.
Original line number Diff line number Diff line
@@ -181,10 +181,6 @@ These OEG CAMARA operations have no tool: QoD `extend` and `retrieve-sessions`, 
`traffic-influence-devices` and `PATCH`, deployment `PATCH` and `clusters`. OEG's platform routes

(`/platform/v1/...`: federation, operations, health) and its TMF facade have no tool either.



**Note:** [oeg/architecture.md](/oeg/architecture.md) names the QoD path `/qod/v0` and

QoD v0 field names. OEG's code serves `/quality-on-demand/v1`, which AI² uses with QoD v1 fields

(`sink`, `sinkCredential`). The OEG spec needs correcting.



### K.2 Request Rules



| Rule | Detail |
@@ -338,7 +334,7 @@ AI² has no agreed retry rules; retrying a chat may repeat writes (overview F7). 


| Concern | Position |

|---|---|

| Authentication, authorization, tenant isolation | The caller's token is passed on; OEG decides ([ADR-0048](/decisions/0048-platform-roles.md)). Where OEG does not yet scope reads and deletes by tenant ([oeg/architecture.md F5](/oeg/architecture.md)), for example `GET /apps` listing every tenant's apps, the same gap applies through AI². AI² does not validate tokens (F1). Memory is not tied to the caller (F4) |

| Authentication, authorization, tenant isolation | The caller's token is passed on; OEG decides ([ADR-0048](/decisions/0048-platform-roles.md)). Where OEG does not yet scope reads and deletes by tenant ([oeg/overview-and-architecture.md F5](/oeg/overview-and-architecture.md#f-open-questions)), for example `GET /apps` listing every tenant's apps, the same gap applies through AI². AI² does not validate tokens (F1). Memory is not tied to the caller (F4) |

| Ownership, state transitions, invariants | AI² owns no platform resource. OEG and SRM own every lifecycle. AI²'s only state is session memory (§L). Invariant: AI² holds no OEG credentials (REQ-AI2-01); its only secret is the Groq API key |

| Transactions, concurrency, consistency | No transactions. Each tool call is a separate OEG call, so a failed run can leave some changes done (§J.3). Same-session requests are not coordinated (§L.3) |

| Idempotency, timeouts, retries, cancellation | Groq: 15 seconds per attempt, up to 3 retries. OEG: 15 seconds, no tool retries. Three tools can send `Idempotency-Key` (§K.2). Portal: 120 seconds. Cancellation and duplicate handling are open (F5, F7) |

decisions/0001-srm-command-event-subject-scheme.md

+1 −1
Changes for decisions/0001-srm-command-event-subject-scheme.md: 1 added line, 1 removed line.
Original line number Diff line number Diff line
@@ -11,7 +11,7 @@ status: "accepted" 


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

**Affects:** [srm/interface-contract.md](/srm/interface-contract.md), [srm/architecture.md](/srm/architecture.md), [oeg/overview-and-architecture.md](/oeg/overview-and-architecture.md), [oeg/interface-contract.md](/oeg/interface-contract.md), [oeg/interface-contract.md §9](/oeg/interface-contract.md#9-data-dictionary), [platform/architecture.md](/platform/architecture.md)



## Context