From 580f2527a87abadb45a4920220dedb754589ac5c Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 15 Apr 2026 20:33:24 -0400
Subject: [PATCH 1/5] Add software operational incident schema

---
 schemas/SoftwareOperationalIncident.json | 224 +++++++++++++++++++++++
 1 file changed, 224 insertions(+)
 create mode 100644 schemas/SoftwareOperationalIncident.json

diff --git a/schemas/SoftwareOperationalIncident.json b/schemas/SoftwareOperationalIncident.json
new file mode 100644
index 0000000..3b7ae80
--- /dev/null
+++ b/schemas/SoftwareOperationalIncident.json
@@ -0,0 +1,224 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/SoftwareOperationalIncident.json",
+  "title": "SoftwareOperationalIncident",
+  "description": "A normalized outage, degradation, integrity, or upstream-related operational incident affecting a software-dependent critical service.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "incidentTitle",
+    "provider",
+    "eventFamily",
+    "status",
+    "startedAt",
+    "evidenceGrade",
+    "sourceRefs"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:oprisk-incident:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:oprisk-incident:<local-id>"
+    },
+    "type": {
+      "const": "SoftwareOperationalIncident",
+      "description": "Discriminator constant — always \"SoftwareOperationalIncident\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "incidentTitle": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Human-readable incident title."
+    },
+    "provider": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Primary provider, operator, or service owner associated with the incident."
+    },
+    "product": {
+      "type": "string",
+      "description": "Affected product or service family, if known."
+    },
+    "eventFamily": {
+      "type": "string",
+      "enum": [
+        "execution_process_failure",
+        "system_platform_disruption",
+        "supply_chain_upstream_failure",
+        "integrity_trust_failure",
+        "external_event",
+        "concentration_common_mode_failure",
+        "upstream_drift_integration_misalignment"
+      ],
+      "description": "Canonical software operational risk event family."
+    },
+    "affectedLayer": {
+      "type": "string",
+      "enum": [
+        "control_plane",
+        "runtime",
+        "registry",
+        "package_manager",
+        "ci_cd",
+        "identity",
+        "network",
+        "storage",
+        "model_provider",
+        "tool_server",
+        "unknown"
+      ],
+      "description": "Primary affected technical layer."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "investigating",
+        "identified",
+        "monitoring",
+        "resolved",
+        "archived"
+      ],
+      "description": "Operational state of the incident record."
+    },
+    "severity": {
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high",
+        "critical"
+      ],
+      "description": "Optional normalized severity level."
+    },
+    "startedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Incident start time in ISO 8601 format."
+    },
+    "endedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Incident resolution time in ISO 8601 format, if known."
+    },
+    "detectedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Time the incident was first externally or internally observed, if distinct from start time."
+    },
+    "durationMinutes": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Normalized duration in minutes, if known."
+    },
+    "regions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Affected regions, availability zones, or tenant segments, if known."
+    },
+    "affectedServices": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Named products, APIs, or service surfaces affected by the incident."
+    },
+    "rootCauseSummary": {
+      "type": "string",
+      "description": "Provider-stated or normalized root-cause summary."
+    },
+    "evidenceGrade": {
+      "type": "string",
+      "enum": [
+        "L1_disclosed_loss",
+        "L2_modeled_estimate",
+        "L3_cost_bearing_evidence",
+        "L4_benchmark_imputation",
+        "timing_scope_only"
+      ],
+      "description": "Evidence grade for financial interpretation and source quality."
+    },
+    "sourceRefs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "kind",
+          "uri",
+          "observedAt"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "status_page",
+              "postmortem",
+              "filing",
+              "earnings_call",
+              "insurer_estimate",
+              "news",
+              "benchmark",
+              "other"
+            ]
+          },
+          "uri": {
+            "type": "string",
+            "format": "uri"
+          },
+          "observedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Canonical sources used to build or normalize the incident record."
+    },
+    "financialImpact": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "amount": {
+          "type": "number"
+        },
+        "basis": {
+          "type": "string",
+          "enum": [
+            "disclosed_loss",
+            "modeled_estimate",
+            "reimbursement_or_claim",
+            "benchmark_imputation"
+          ]
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        }
+      },
+      "description": "Optional financial impact object used when cost evidence exists."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional normalized tags for downstream filtering and clustering."
+    }
+  }
+}

From 941f58cfcfcbfdbbee1f8bf97720a1c39032b7bf Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 15 Apr 2026 20:34:25 -0400
Subject: [PATCH 2/5] Add upstream watch item schema

---
 schemas/UpstreamWatchItem.json | 171 +++++++++++++++++++++++++++++++++
 1 file changed, 171 insertions(+)
 create mode 100644 schemas/UpstreamWatchItem.json

diff --git a/schemas/UpstreamWatchItem.json b/schemas/UpstreamWatchItem.json
new file mode 100644
index 0000000..64f5ed6
--- /dev/null
+++ b/schemas/UpstreamWatchItem.json
@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/UpstreamWatchItem.json",
+  "title": "UpstreamWatchItem",
+  "description": "A normalized watchlist item describing the live state of an upstream dependency surface and its drift or concentration implications.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "subjectType",
+    "subjectKey",
+    "observedAt",
+    "riskState",
+    "signals"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:upstream-watch:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:upstream-watch:<local-id>"
+    },
+    "type": {
+      "const": "UpstreamWatchItem",
+      "description": "Discriminator constant — always \"UpstreamWatchItem\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "subjectType": {
+      "type": "string",
+      "enum": [
+        "github_repository",
+        "git_branch",
+        "package",
+        "registry",
+        "cloud_service",
+        "model_provider",
+        "status_page",
+        "tool_server",
+        "other"
+      ],
+      "description": "Primary type of upstream surface being watched."
+    },
+    "subjectKey": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Canonical lookup key, such as owner/repo, package name, provider/service, or URL-derived key."
+    },
+    "displayName": {
+      "type": "string",
+      "description": "Optional human-readable label."
+    },
+    "owner": {
+      "type": "string",
+      "description": "Owning org, vendor, or provider, if applicable."
+    },
+    "defaultBranch": {
+      "type": "string",
+      "description": "Default branch when the watched object is a repository."
+    },
+    "currentVersion": {
+      "type": "string",
+      "description": "Current observed version, tag, or release label, if applicable."
+    },
+    "observedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Time the watch item was last refreshed."
+    },
+    "riskState": {
+      "type": "string",
+      "enum": [
+        "normal",
+        "watch",
+        "elevated",
+        "critical"
+      ],
+      "description": "Normalized operational-risk state for the watched upstream surface."
+    },
+    "signals": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "signalType",
+          "value"
+        ],
+        "properties": {
+          "signalType": {
+            "type": "string",
+            "enum": [
+              "open_pr_count",
+              "open_issue_count",
+              "release_gap",
+              "package_version_gap",
+              "recent_incident_count",
+              "branch_divergence",
+              "concentration_score",
+              "custom"
+            ]
+          },
+          "value": {
+            "type": [
+              "number",
+              "string",
+              "boolean"
+            ]
+          },
+          "unit": {
+            "type": "string"
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Observed drift, concentration, or freshness signals attached to this watch item."
+    },
+    "linkedIncidentRefs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^urn:srcos:oprisk-incident:"
+      },
+      "description": "Optional links to normalized operational incidents relevant to this watch item."
+    },
+    "sourceRefs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "kind",
+          "uri"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "github",
+              "package_registry",
+              "status_page",
+              "api",
+              "other"
+            ]
+          },
+          "uri": {
+            "type": "string",
+            "format": "uri"
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Sources used to refresh this watch item."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional normalized tags for filtering and clustering."
+    }
+  }
+}

From 7a7cdc93e1c1179200418e32cef4115e8578ef70 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 15 Apr 2026 20:34:55 -0400
Subject: [PATCH 3/5] Add software operational incident example

---
 examples/softwareoperationalincident.json | 36 +++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 examples/softwareoperationalincident.json

diff --git a/examples/softwareoperationalincident.json b/examples/softwareoperationalincident.json
new file mode 100644
index 0000000..7bf8bed
--- /dev/null
+++ b/examples/softwareoperationalincident.json
@@ -0,0 +1,36 @@
+{
+  "id": "urn:srcos:oprisk-incident:openai-codex-unresponsive-2026-03-09",
+  "type": "SoftwareOperationalIncident",
+  "specVersion": "2.0.0",
+  "incidentTitle": "Codex unresponsive",
+  "provider": "OpenAI",
+  "product": "Codex",
+  "eventFamily": "system_platform_disruption",
+  "affectedLayer": "model_provider",
+  "status": "resolved",
+  "severity": "high",
+  "startedAt": "2026-03-09T21:00:00Z",
+  "endedAt": "2026-03-11T18:00:00Z",
+  "durationMinutes": 2700,
+  "regions": [
+    "global"
+  ],
+  "affectedServices": [
+    "Codex"
+  ],
+  "rootCauseSummary": "Provider-reported service unresponsiveness affecting Codex availability.",
+  "evidenceGrade": "timing_scope_only",
+  "sourceRefs": [
+    {
+      "kind": "status_page",
+      "uri": "https://status.openai.com/incidents/01JNZR03S0YZD1K3E2M4X8J1E0",
+      "observedAt": "2026-04-15T22:00:00Z",
+      "note": "Illustrative example using official incident history."
+    }
+  ],
+  "tags": [
+    "codex",
+    "model-provider",
+    "availability"
+  ]
+}

From 11ed86ab91096b82954ef0d96960a9c79833ac20 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 15 Apr 2026 20:48:00 -0400
Subject: [PATCH 4/5] Add upstream watch item example

---
 examples/upstreamwatchitem.json | 39 +++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 examples/upstreamwatchitem.json

diff --git a/examples/upstreamwatchitem.json b/examples/upstreamwatchitem.json
new file mode 100644
index 0000000..106d1cc
--- /dev/null
+++ b/examples/upstreamwatchitem.json
@@ -0,0 +1,39 @@
+{
+  "id": "urn:srcos:upstream-watch:socioprophet-agentplane-main",
+  "type": "UpstreamWatchItem",
+  "specVersion": "2.0.0",
+  "subjectType": "github_repository",
+  "subjectKey": "SocioProphet/agentplane",
+  "displayName": "SocioProphet agentplane",
+  "owner": "SocioProphet",
+  "defaultBranch": "main",
+  "currentVersion": "docs-alignment-pr-35",
+  "observedAt": "2026-04-15T22:45:00Z",
+  "riskState": "watch",
+  "signals": [
+    {
+      "signalType": "open_pr_count",
+      "value": 35,
+      "unit": "pull_requests",
+      "note": "Illustrative signal placeholder for schema consumers."
+    },
+    {
+      "signalType": "branch_divergence",
+      "value": 0,
+      "unit": "commits",
+      "note": "Measured relative to the current base during capture."
+    }
+  ],
+  "sourceRefs": [
+    {
+      "kind": "github",
+      "uri": "https://github.com/SocioProphet/agentplane",
+      "note": "Illustrative example for repository watch items."
+    }
+  ],
+  "tags": [
+    "github",
+    "execution-plane",
+    "upstream-drift"
+  ]
+}

From 0d2cd14e9242aa6b39b095644745610dab3c9ffc Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 15 Apr 2026 21:27:02 -0400
Subject: [PATCH 5/5] Document software operational risk schema family

---
 docs/software-oprisk-schema-family.md | 31 +++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 docs/software-oprisk-schema-family.md

diff --git a/docs/software-oprisk-schema-family.md b/docs/software-oprisk-schema-family.md
new file mode 100644
index 0000000..26c4097
--- /dev/null
+++ b/docs/software-oprisk-schema-family.md
@@ -0,0 +1,31 @@
+# Software Operational Risk Schema Family
+
+This note documents the initial software operational risk schema family added in this branch.
+
+## Current schemas
+
+- `schemas/SoftwareOperationalIncident.json`
+- `schemas/UpstreamWatchItem.json`
+
+## Intended URN prefixes
+
+- `urn:srcos:oprisk-incident:` — normalized outage, degradation, integrity, and upstream-related operational incidents
+- `urn:srcos:upstream-watch:` — normalized live watchlist items for repos, packages, providers, registries, and related upstream surfaces
+
+## Initial examples
+
+- `examples/softwareoperationalincident.json`
+- `examples/upstreamwatchitem.json`
+
+## Intended downstream consumers
+
+- `SocioProphet/sociosphere` — harvester outputs and watchlist refresh jobs
+- `SocioProphet/agentplane` — execution and evidence crosswalks
+- `SociOS-Linux/source-os` — runtime/package/update posture
+- financial and reserve-analysis layers that need a typed envelope for outage corpus records and upstream drift inputs
+
+## Follow-on contract work
+
+1. Add reserve / scenario report envelopes.
+2. Add OpenAPI / AsyncAPI exposure where operational-risk objects move across service boundaries.
+3. Fold these schemas into the main schema catalog and root spec documentation.