diff --git a/docs/software-oprisk-analysis-bundle.md b/docs/software-oprisk-analysis-bundle.md
new file mode 100644
index 0000000..3c9b8c2
--- /dev/null
+++ b/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.
diff --git a/docs/software-oprisk-reserve-envelope.md b/docs/software-oprisk-reserve-envelope.md
new file mode 100644
index 0000000..5cc1ee9
--- /dev/null
+++ b/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.
diff --git a/docs/software-oprisk-scenario-run.md b/docs/software-oprisk-scenario-run.md
new file mode 100644
index 0000000..9156e9c
--- /dev/null
+++ b/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.
diff --git a/examples/reservescenarioreport.json b/examples/reservescenarioreport.json
new file mode 100644
index 0000000..65f7e98
--- /dev/null
+++ b/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"
+  ]
+}
diff --git a/examples/softwareoperationalanalysisbundle.json b/examples/softwareoperationalanalysisbundle.json
new file mode 100644
index 0000000..74bf580
--- /dev/null
+++ b/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"
+  ]
+}
diff --git a/examples/softwareoperationalscenariorun.json b/examples/softwareoperationalscenariorun.json
new file mode 100644
index 0000000..7c5e4ce
--- /dev/null
+++ b/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"
+  ]
+}
diff --git a/schemas/ReserveScenarioReport.json b/schemas/ReserveScenarioReport.json
new file mode 100644
index 0000000..373f689
--- /dev/null
+++ b/schemas/ReserveScenarioReport.json
@@ -0,0 +1,235 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ReserveScenarioReport.json",
+  "title": "ReserveScenarioReport",
+  "description": "A typed report envelope for expected annual loss, reserve components, scenario contributions, and capital-style binding basis in the software operational risk lane.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "generatedAt",
+    "subjectRef",
+    "currency",
+    "bindingBasis",
+    "method",
+    "expectedAnnualLoss",
+    "suggestedReserve",
+    "scenarioSet"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:oprisk-reserve-report:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:oprisk-reserve-report:<local-id>"
+    },
+    "type": {
+      "const": "ReserveScenarioReport",
+      "description": "Discriminator constant — always \"ReserveScenarioReport\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 date-time when the report was generated."
+    },
+    "subjectRef": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Reference to the assessed company, service, portfolio, or environment."
+    },
+    "reportingWindow": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "startAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "endAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "horizonDays": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "description": "Optional reporting window used to generate the report."
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$",
+      "description": "ISO 4217 currency code used for monetary values in this report."
+    },
+    "bindingBasis": {
+      "type": "string",
+      "enum": [
+        "transparent_benchmark",
+        "scenario_reserve",
+        "mixed",
+        "policy_override"
+      ],
+      "description": "Which reserve basis is binding for the current suggested reserve."
+    },
+    "method": {
+      "type": "string",
+      "enum": [
+        "parametric",
+        "monte_carlo",
+        "hybrid",
+        "benchmark_only"
+      ],
+      "description": "Primary modeling method used for the scenario reserve layer."
+    },
+    "tailConfidence": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "exclusiveMaximum": 1,
+      "description": "Optional tail confidence level, such as 0.95 or 0.99."
+    },
+    "transparentBenchmarkReserve": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Board-facing or benchmark-derived reserve floor."
+    },
+    "scenarioReserve": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Reserve implied by scenario-based loss modeling."
+    },
+    "suggestedReserve": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Current suggested reserve after selecting the binding basis."
+    },
+    "expectedAnnualLoss": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Expected annual loss for the assessed environment or service set."
+    },
+    "controlDelta": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "targetExpectedAnnualLoss": {
+          "type": "number",
+          "minimum": 0
+        },
+        "expectedAnnualLossReduction": {
+          "type": "number"
+        },
+        "targetSuggestedReserve": {
+          "type": "number",
+          "minimum": 0
+        },
+        "reserveRelease": {
+          "type": "number"
+        }
+      },
+      "description": "Optional current-versus-target control comparison summary."
+    },
+    "scenarioSet": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "scenarioId",
+          "scenarioName",
+          "eventFamily",
+          "frequency",
+          "severity",
+          "expectedLoss"
+        ],
+        "properties": {
+          "scenarioId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "scenarioName": {
+            "type": "string",
+            "minLength": 1
+          },
+          "eventFamily": {
+            "type": "string"
+          },
+          "frequency": {
+            "type": "number",
+            "minimum": 0
+          },
+          "severity": {
+            "type": "number",
+            "minimum": 0
+          },
+          "expectedLoss": {
+            "type": "number",
+            "minimum": 0
+          },
+          "reserveContribution": {
+            "type": "number",
+            "minimum": 0
+          },
+          "controlState": {
+            "type": "string",
+            "enum": [
+              "current",
+              "target",
+              "stress"
+            ]
+          },
+          "linkedIncidentRefs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^urn:srcos:oprisk-incident:"
+            }
+          }
+        }
+      },
+      "description": "Scenario-level contribution objects used to assemble the report outputs."
+    },
+    "sourceRefs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "kind",
+          "uri"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "corpus",
+              "model",
+              "benchmark",
+              "other"
+            ]
+          },
+          "uri": {
+            "type": "string",
+            "format": "uri"
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Optional links to corpus, model, or benchmark sources used in the report."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional normalized tags for downstream filtering and clustering."
+    }
+  }
+}
diff --git a/schemas/SoftwareOperationalAnalysisBundle.json b/schemas/SoftwareOperationalAnalysisBundle.json
new file mode 100644
index 0000000..6e08ff9
--- /dev/null
+++ b/schemas/SoftwareOperationalAnalysisBundle.json
@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/SoftwareOperationalAnalysisBundle.json",
+  "title": "SoftwareOperationalAnalysisBundle",
+  "description": "A typed linkage envelope that binds software operational-risk scenario runs to one or more reserve/report outputs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "generatedAt",
+    "subjectRef",
+    "scenarioRunRef",
+    "reportRefs"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:oprisk-analysis-bundle:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:oprisk-analysis-bundle:<local-id>"
+    },
+    "type": {
+      "const": "SoftwareOperationalAnalysisBundle",
+      "description": "Discriminator constant — always \"SoftwareOperationalAnalysisBundle\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 date-time when this bundle was assembled."
+    },
+    "subjectRef": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Reference to the assessed company, service, or environment."
+    },
+    "scenarioRunRef": {
+      "type": "string",
+      "pattern": "^urn:srcos:oprisk-scenario-run:",
+      "description": "Typed scenario-run input to this analysis bundle."
+    },
+    "reportRefs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^urn:srcos:oprisk-reserve-report:"
+      },
+      "description": "One or more reserve/report outputs associated with the scenario run."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional normalized tags for filtering and clustering."
+    }
+  }
+}
diff --git a/schemas/SoftwareOperationalScenarioRun.json b/schemas/SoftwareOperationalScenarioRun.json
new file mode 100644
index 0000000..94adf55
--- /dev/null
+++ b/schemas/SoftwareOperationalScenarioRun.json
@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/SoftwareOperationalScenarioRun.json",
+  "title": "SoftwareOperationalScenarioRun",
+  "description": "A typed envelope describing one software operational-risk modeling run, its typed inputs, and its produced report outputs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "generatedAt",
+    "subjectRef",
+    "runKind",
+    "method",
+    "incidentInputRefs",
+    "watchInputRefs"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:oprisk-scenario-run:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:oprisk-scenario-run:<local-id>"
+    },
+    "type": {
+      "const": "SoftwareOperationalScenarioRun",
+      "description": "Discriminator constant — always \"SoftwareOperationalScenarioRun\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 date-time when the scenario run was executed."
+    },
+    "subjectRef": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Reference to the assessed company, service, or portfolio."
+    },
+    "runKind": {
+      "type": "string",
+      "enum": [
+        "baseline",
+        "target",
+        "stress",
+        "backtest"
+      ],
+      "description": "Semantic mode of the scenario run."
+    },
+    "method": {
+      "type": "string",
+      "enum": [
+        "parametric",
+        "monte_carlo",
+        "hybrid",
+        "benchmark_only"
+      ],
+      "description": "Primary modeling method used for the run."
+    },
+    "modelVersion": {
+      "type": "string",
+      "description": "Optional model version label for reproducibility."
+    },
+    "parameterSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "horizonDays": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "tailConfidence": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "exclusiveMaximum": 1
+        },
+        "simulationCount": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "description": "Optional model parameter summary for reproducibility and audit."
+    },
+    "incidentInputRefs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^urn:srcos:oprisk-incident:"
+      },
+      "description": "Typed incident inputs used by this run."
+    },
+    "watchInputRefs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^urn:srcos:upstream-watch:"
+      },
+      "description": "Typed upstream watch inputs used by this run."
+    },
+    "outputReportRefs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^urn:srcos:oprisk-reserve-report:"
+      },
+      "description": "Typed reserve or scenario report outputs produced by this run."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional normalized tags for filtering and clustering."
+    }
+  }
+}