Skip to content

Commit 5206689

Browse files
mdhellermdheller
authored
Merge pull request #47 from SourceOS-Linux/oprisk-reserve-envelope-v1
2 parents 7f23948 + ce02625 commit 5206689

9 files changed

Lines changed: 643 additions & 0 deletions

‎docs/software-oprisk-analysis-bundle.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Software Operational Analysis Bundle
2+
3+
This note documents the linkage envelope added for the software operational risk report family.
4+
5+
## Added schema
6+
7+
- `schemas/SoftwareOperationalAnalysisBundle.json`
8+
9+
## Added example
10+
11+
- `examples/softwareoperationalanalysisbundle.json`
12+
13+
## Purpose
14+
15+
This contract exists to make the report lineage explicit without requiring in-place edits to previously added report objects.
16+
17+
It binds:
18+
19+
- one typed `SoftwareOperationalScenarioRun`,
20+
- one or more typed `ReserveScenarioReport` objects,
21+
- and the assessed subject into a single typed bundle.
22+
23+
## Why this matters
24+
25+
The current software operational risk contract family now includes:
26+
27+
- incident inputs,
28+
- watchlist inputs,
29+
- scenario-run lineage,
30+
- reserve/report outputs,
31+
- and now an additive linkage object that joins run and report artifacts together.
32+
33+
## Follow-on contract work
34+
35+
1. Add model-metadata envelopes where deeper reproducibility is required.
36+
2. Fold these contract-family links into API and event exposure once first service consumers exist.

‎docs/software-oprisk-reserve-envelope.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Software Operational Risk Reserve Envelope
2+
3+
This note documents the first reserve/report contract added for the software operational risk lane.
4+
5+
## Added schema
6+
7+
- `schemas/ReserveScenarioReport.json`
8+
9+
## Added example
10+
11+
- `examples/reservescenarioreport.json`
12+
13+
## Purpose
14+
15+
The reserve/report envelope gives the platform a typed object for:
16+
17+
- expected annual loss,
18+
- benchmark reserve,
19+
- scenario reserve,
20+
- suggested reserve,
21+
- current-versus-target control deltas,
22+
- and scenario-level reserve contributions.
23+
24+
## Why this matters
25+
26+
The earlier incident and watchlist schemas describe event and upstream-state inputs.
27+
This envelope describes a financially legible output layer that can be consumed by:
28+
29+
- governance reporting,
30+
- reserve and capital analysis,
31+
- control ROI narratives,
32+
- and downstream dashboards.
33+
34+
## Follow-on contract work
35+
36+
1. Add scenario-run and model-metadata envelopes.
37+
2. Add explicit references to typed incident and watchlist inputs.
38+
3. Add API / event exposure once the first consumers are ready.

‎docs/software-oprisk-scenario-run.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Software Operational Scenario Run Contract
2+
3+
This note documents the scenario-run lineage envelope added for the software operational risk lane.
4+
5+
## Added schema
6+
7+
- `schemas/SoftwareOperationalScenarioRun.json`
8+
9+
## Added example
10+
11+
- `examples/softwareoperationalscenariorun.json`
12+
13+
## Purpose
14+
15+
This contract makes the modeling lineage explicit by typing:
16+
17+
- the assessed subject,
18+
- the modeling mode and method,
19+
- the typed incident inputs,
20+
- the typed upstream watch inputs,
21+
- and the typed reserve/report outputs produced by the run.
22+
23+
## Why this matters
24+
25+
The current software operational risk family now has:
26+
27+
- typed incident inputs,
28+
- typed watchlist inputs,
29+
- typed reserve/report outputs,
30+
- and now a typed scenario-run object that links them together.
31+
32+
## Follow-on contract work
33+
34+
1. Add model-metadata envelopes if the modeling surface needs separate provenance.
35+
2. Extend reserve reports with optional direct references back to their scenario-run objects.
36+
3. Expose the run/report family through OpenAPI / AsyncAPI when the first service consumers are ready.

‎examples/reservescenarioreport.json‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
{
2+
"id": "urn:srcos:oprisk-reserve-report:devtools-agent-2026-q2",
3+
"type": "ReserveScenarioReport",
4+
"specVersion": "2.0.0",
5+
"generatedAt": "2026-04-20T22:45:00Z",
6+
"subjectRef": "urn:srcos:service-portfolio:devtools-agent-stack",
7+
"reportingWindow": {
8+
"startAt": "2026-01-01T00:00:00Z",
9+
"endAt": "2026-03-31T23:59:59Z",
10+
"horizonDays": 365
11+
},
12+
"currency": "USD",
13+
"bindingBasis": "transparent_benchmark",
14+
"method": "hybrid",
15+
"tailConfidence": 0.99,
16+
"transparentBenchmarkReserve": 24056000,
17+
"scenarioReserve": 10205000,
18+
"suggestedReserve": 24056000,
19+
"expectedAnnualLoss": 786000,
20+
"controlDelta": {
21+
"targetExpectedAnnualLoss": 505000,
22+
"expectedAnnualLossReduction": 281000,
23+
"targetSuggestedReserve": 23720000,
24+
"reserveRelease": 336000
25+
},
26+
"scenarioSet": [
27+
{
28+
"scenarioId": "SCN-001",
29+
"scenarioName": "Cloud control plane outage",
30+
"eventFamily": "system_platform_disruption",
31+
"frequency": 0.18,
32+
"severity": 1200000,
33+
"expectedLoss": 216000,
34+
"reserveContribution": 1800000,
35+
"controlState": "current"
36+
},
37+
{
38+
"scenarioId": "SCN-011",
39+
"scenarioName": "Upstream release and integration drift",
40+
"eventFamily": "upstream_drift_integration_misalignment",
41+
"frequency": 0.22,
42+
"severity": 165000,
43+
"expectedLoss": 36300,
44+
"reserveContribution": 240000,
45+
"controlState": "current"
46+
}
47+
],
48+
"sourceRefs": [
49+
{
50+
"kind": "corpus",
51+
"uri": "https://status.openai.com/history",
52+
"note": "Illustrative corpus input source."
53+
},
54+
{
55+
"kind": "benchmark",
56+
"uri": "https://www.bis.org/bcbs/publ/d515.pdf",
57+
"note": "Illustrative benchmark and governance reference."
58+
}
59+
],
60+
"tags": [
61+
"oprisk",
62+
"reserve",
63+
"scenario-report"
64+
]
65+
}

‎examples/softwareoperationalanalysisbundle.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"id": "urn:srcos:oprisk-analysis-bundle:devtools-agent-2026-q2",
3+
"type": "SoftwareOperationalAnalysisBundle",
4+
"specVersion": "2.0.0",
5+
"generatedAt": "2026-04-20T23:30:00Z",
6+
"subjectRef": "urn:srcos:service-portfolio:devtools-agent-stack",
7+
"scenarioRunRef": "urn:srcos:oprisk-scenario-run:devtools-agent-baseline-2026-q2",
8+
"reportRefs": [
9+
"urn:srcos:oprisk-reserve-report:devtools-agent-2026-q2"
10+
],
11+
"tags": [
12+
"analysis-bundle",
13+
"oprisk",
14+
"baseline"
15+
]
16+
}

‎examples/softwareoperationalscenariorun.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"id": "urn:srcos:oprisk-scenario-run:devtools-agent-baseline-2026-q2",
3+
"type": "SoftwareOperationalScenarioRun",
4+
"specVersion": "2.0.0",
5+
"generatedAt": "2026-04-20T23:20:00Z",
6+
"subjectRef": "urn:srcos:service-portfolio:devtools-agent-stack",
7+
"runKind": "baseline",
8+
"method": "hybrid",
9+
"modelVersion": "oprisk-model-v0.2",
10+
"parameterSummary": {
11+
"horizonDays": 365,
12+
"currency": "USD",
13+
"tailConfidence": 0.99,
14+
"simulationCount": 10000
15+
},
16+
"incidentInputRefs": [
17+
"urn:srcos:oprisk-incident:openai-codex-unresponsive-2026-03-09"
18+
],
19+
"watchInputRefs": [
20+
"urn:srcos:upstream-watch:socioprophet-agentplane-main",
21+
"urn:srcos:upstream-watch:provider:openai-codex"
22+
],
23+
"outputReportRefs": [
24+
"urn:srcos:oprisk-reserve-report:devtools-agent-2026-q2"
25+
],
26+
"tags": [
27+
"baseline",
28+
"scenario-run",
29+
"oprisk"
30+
]
31+
}

0 commit comments

Comments
 (0)