feat(schemas): add reserve scenario report contract for software operational risk

docs/software-oprisk-analysis-bundle.md

@@ -0,0 +1,36 @@
+# Software Operational Analysis Bundle
+
+This note documents the linkage envelope added for the software operational risk report family.
+
+## Added schema
+
+- `schemas/SoftwareOperationalAnalysisBundle.json`
+
+## Added example
+
+- `examples/softwareoperationalanalysisbundle.json`
+
+## Purpose
+
+This contract exists to make the report lineage explicit without requiring in-place edits to previously added report objects.
+
+It binds:
+
+- one typed `SoftwareOperationalScenarioRun`,
+- one or more typed `ReserveScenarioReport` objects,
+- and the assessed subject into a single typed bundle.
+
+## Why this matters
+
+The current software operational risk contract family now includes:
+
+- incident inputs,
+- watchlist inputs,
+- scenario-run lineage,
+- reserve/report outputs,
+- and now an additive linkage object that joins run and report artifacts together.
+
+## Follow-on contract work
+
+1. Add model-metadata envelopes where deeper reproducibility is required.  
+2. Fold these contract-family links into API and event exposure once first service consumers exist.

docs/software-oprisk-reserve-envelope.md

@@ -0,0 +1,38 @@
+# Software Operational Risk Reserve Envelope
+
+This note documents the first reserve/report contract added for the software operational risk lane.
+
+## Added schema
+
+- `schemas/ReserveScenarioReport.json`
+
+## Added example
+
+- `examples/reservescenarioreport.json`
+
+## Purpose
+
+The reserve/report envelope gives the platform a typed object for:
+
+- expected annual loss,
+- benchmark reserve,
+- scenario reserve,
+- suggested reserve,
+- current-versus-target control deltas,
+- and scenario-level reserve contributions.
+
+## Why this matters
+
+The earlier incident and watchlist schemas describe event and upstream-state inputs.
+This envelope describes a financially legible output layer that can be consumed by:
+
+- governance reporting,
+- reserve and capital analysis,
+- control ROI narratives,
+- and downstream dashboards.
+
+## Follow-on contract work
+
+1. Add scenario-run and model-metadata envelopes.  
+2. Add explicit references to typed incident and watchlist inputs.  
+3. Add API / event exposure once the first consumers are ready.

docs/software-oprisk-scenario-run.md

@@ -0,0 +1,36 @@
+# Software Operational Scenario Run Contract
+
+This note documents the scenario-run lineage envelope added for the software operational risk lane.
+
+## Added schema
+
+- `schemas/SoftwareOperationalScenarioRun.json`
+
+## Added example
+
+- `examples/softwareoperationalscenariorun.json`
+
+## Purpose
+
+This contract makes the modeling lineage explicit by typing:
+
+- the assessed subject,
+- the modeling mode and method,
+- the typed incident inputs,
+- the typed upstream watch inputs,
+- and the typed reserve/report outputs produced by the run.
+
+## Why this matters
+
+The current software operational risk family now has:
+
+- typed incident inputs,
+- typed watchlist inputs,
+- typed reserve/report outputs,
+- and now a typed scenario-run object that links them together.
+
+## Follow-on contract work
+
+1. Add model-metadata envelopes if the modeling surface needs separate provenance.  
+2. Extend reserve reports with optional direct references back to their scenario-run objects.  
+3. Expose the run/report family through OpenAPI / AsyncAPI when the first service consumers are ready.

examples/reservescenarioreport.json

@@ -0,0 +1,65 @@
+{
+  "id": "urn:srcos:oprisk-reserve-report:devtools-agent-2026-q2",
+  "type": "ReserveScenarioReport",
+  "specVersion": "2.0.0",
+  "generatedAt": "2026-04-20T22:45:00Z",
+  "subjectRef": "urn:srcos:service-portfolio:devtools-agent-stack",
+  "reportingWindow": {
+    "startAt": "2026-01-01T00:00:00Z",
+    "endAt": "2026-03-31T23:59:59Z",
+    "horizonDays": 365
+  },
+  "currency": "USD",
+  "bindingBasis": "transparent_benchmark",
+  "method": "hybrid",
+  "tailConfidence": 0.99,
+  "transparentBenchmarkReserve": 24056000,
+  "scenarioReserve": 10205000,
+  "suggestedReserve": 24056000,
+  "expectedAnnualLoss": 786000,
+  "controlDelta": {
+    "targetExpectedAnnualLoss": 505000,
+    "expectedAnnualLossReduction": 281000,
+    "targetSuggestedReserve": 23720000,
+    "reserveRelease": 336000
+  },
+  "scenarioSet": [
+    {
+      "scenarioId": "SCN-001",
+      "scenarioName": "Cloud control plane outage",
+      "eventFamily": "system_platform_disruption",
+      "frequency": 0.18,
+      "severity": 1200000,
+      "expectedLoss": 216000,
+      "reserveContribution": 1800000,
+      "controlState": "current"
+    },
+    {
+      "scenarioId": "SCN-011",
+      "scenarioName": "Upstream release and integration drift",
+      "eventFamily": "upstream_drift_integration_misalignment",
+      "frequency": 0.22,
+      "severity": 165000,
+      "expectedLoss": 36300,
+      "reserveContribution": 240000,
+      "controlState": "current"
+    }
+  ],
+  "sourceRefs": [
+    {
+      "kind": "corpus",
+      "uri": "https://status.openai.com/history",
+      "note": "Illustrative corpus input source."
+    },
+    {
+      "kind": "benchmark",
+      "uri": "https://www.bis.org/bcbs/publ/d515.pdf",
+      "note": "Illustrative benchmark and governance reference."
+    }
+  ],
+  "tags": [
+    "oprisk",
+    "reserve",
+    "scenario-report"
+  ]
+}

examples/softwareoperationalanalysisbundle.json

@@ -0,0 +1,16 @@
+{
+  "id": "urn:srcos:oprisk-analysis-bundle:devtools-agent-2026-q2",
+  "type": "SoftwareOperationalAnalysisBundle",
+  "specVersion": "2.0.0",
+  "generatedAt": "2026-04-20T23:30:00Z",
+  "subjectRef": "urn:srcos:service-portfolio:devtools-agent-stack",
+  "scenarioRunRef": "urn:srcos:oprisk-scenario-run:devtools-agent-baseline-2026-q2",
+  "reportRefs": [
+    "urn:srcos:oprisk-reserve-report:devtools-agent-2026-q2"
+  ],
+  "tags": [
+    "analysis-bundle",
+    "oprisk",
+    "baseline"
+  ]
+}

examples/softwareoperationalscenariorun.json

@@ -0,0 +1,31 @@
+{
+  "id": "urn:srcos:oprisk-scenario-run:devtools-agent-baseline-2026-q2",
+  "type": "SoftwareOperationalScenarioRun",
+  "specVersion": "2.0.0",
+  "generatedAt": "2026-04-20T23:20:00Z",
+  "subjectRef": "urn:srcos:service-portfolio:devtools-agent-stack",
+  "runKind": "baseline",
+  "method": "hybrid",
+  "modelVersion": "oprisk-model-v0.2",
+  "parameterSummary": {
+    "horizonDays": 365,
+    "currency": "USD",
+    "tailConfidence": 0.99,
+    "simulationCount": 10000
+  },
+  "incidentInputRefs": [
+    "urn:srcos:oprisk-incident:openai-codex-unresponsive-2026-03-09"
+  ],
+  "watchInputRefs": [
+    "urn:srcos:upstream-watch:socioprophet-agentplane-main",
+    "urn:srcos:upstream-watch:provider:openai-codex"
+  ],
+  "outputReportRefs": [
+    "urn:srcos:oprisk-reserve-report:devtools-agent-2026-q2"
+  ],
+  "tags": [
+    "baseline",
+    "scenario-run",
+    "oprisk"
+  ]
+}