SourceOS-Linux · mdheller · Jul 5, 2026 · Jul 5, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- Epistemic Assay contracts: `ReasoningAssay` (a typed verdict on a claim over five orthogonal axes — method, binding, verifier, agreement, authority — whose `ok`/`sad`/`bad` `projectedState` is a render-time projection, not a stored scalar) and `AssayStandard` (a verifier's measured, versioned reliability — the calibration reference every assay must point at). Includes canonical `ok`/`sad`/`bad` examples, ADR (`docs/adr/ADR-epistemic-assay-verdict-v0-1.md`), and a `validate-reasoning-examples` target that also enforces projection soundness (recomputes `assay()` from the stored axes and fails on drift) and retroactively brings the existing reasoning family under `make validate`.
 - Onboarding control-plane contract family: `WorkspaceScope`, `TrustMode`, `CapabilityPack`, `ConnectorActionScope`, `AutomationTemplate`, and `OnboardingReceipt`, with canonical first-run examples, semantic vocabulary seed, ADR, and `validate-onboarding-examples` validation target.
 - `ReasoningEvent.controlFlow` (optional) + a reserved control-flow `eventType` vocabulary (`reasoning.tool.called` / `reasoning.decision.branched` / `reasoning.subrun.spawned` / `reasoning.subrun.joined` / `reasoning.run.completed`) so emitters can carry a run's operational control flow for downstream narration-fidelity verification (SP-TRACE-CFR). Backward-compatible; operational structure only (no raw reasoning). See `docs/reasoning-control-flow-events.md` and `examples/reasoning_event_control_flow.json`.
 - SourceOS interaction substrate top-level index and README discovery links for `SourceOSInteractionEvent`, generated TypeScript/Python artifacts, and the Noetica → Superconscious → AgentPlane → AgentTerm reference flow.

diff --git a/Makefile b/Makefile
@@ -1,8 +1,12 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples
 	@echo "OK: validate"
 
+validate-reasoning-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_reasoning_examples.py
+
 validate-agentic-os-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_agentic_os_examples.py

diff --git a/docs/adr/ADR-epistemic-assay-verdict-v0-1.md b/docs/adr/ADR-epistemic-assay-verdict-v0-1.md
@@ -0,0 +1,82 @@
+# ADR: The Epistemic Assay — Verdicts as Projections, Not Scalars (v0.1)
+
+## Status
+
+Proposed.
+
+## Context
+
+The operational health of a subsystem is well modelled by a tri-state readout — `ok` / `sad` / `bad`
+(came up / degraded-but-survived / hard failure). These are mutually exclusive states of a single
+thing (the outcome of an operation), and the middle state is deliberately first-class.
+
+That same three-state readout was being reached for to describe the trustworthiness of a **claim**.
+This conflates concerns that are not points on one severity scale. Recent evaluation work surfaced at
+least four independent facts hiding behind a single "confidence" pixel:
+
+- **method** — was the claim computed, retrieved, or generated? These behave as decorrelated *classes*,
+  not degrees; the verified-compute arm is decorrelated from grounding arms precisely because it is a
+  different method.
+- **binding time** — was the supporting evidence produced *inline* with the computation, or attached
+  *post-hoc*? Generative paths are post-hoc bound; only deterministic paths are inline. A post-hoc
+  "verified" is a different animal from an inline one, and nothing recorded which was obtained.
+- **verifier authority** — who judged, and how reliable is that judge, *measured*? A deployed verifier
+  grading at low F1 with only "slight" inter-rater agreement does not issue a weaker verdict — it
+  issues an **unanchored** one, because its own reliability is unrecorded.
+- **agreement** — arm concurrence overstates confidence when arms are correlated (they fail together),
+  so raw "N arms agree" is closer to one vote than N.
+
+Collapsing orthogonal axes into one stored scalar is the design flaw. It also makes history
+un-re-judgeable: when the verifier improves, every past verdict is stuck at the reliability it was
+stamped with.
+
+## Decision
+
+### 1. Keep the tri-state readout for operational health; do not store it as a claim's verdict
+
+`ok` / `sad` / `bad` remains the canonical readout for operational outcomes. For **claims**, the verdict
+is no longer a stored scalar.
+
+### 2. Introduce `ReasoningAssay` — a typed verdict over five orthogonal axes
+
+`schemas/ReasoningAssay.json` records `method`, `binding`, `verifier`, `agreement`, and `authority`.
+The `ok` / `sad` / `bad` value (`projectedState`) is a **render-time projection** of these axes, cached
+at `assayedAt` and re-derivable — never the source of truth. This is the "operation ⊥ verdict" principle
+(separate the fact from the judgement so history stays re-judgeable) applied to epistemics.
+
+The projection is defined so that:
+
+- `ok` requires inline binding **and** an attestable method (computed/retrieved) **and** a calibrated verifier;
+- `sad` ("unassayed") covers everything real-but-unresolved — post-hoc binding, generation-with-citations,
+  an uncalibrated verifier, or correlated-arm agreement. The amber band is deliberately wide and *earned*;
+- `bad` covers refuted / failed / authority-broken.
+
+### 3. Introduce `AssayStandard` — the verifier's measured reliability as canon
+
+`schemas/AssayStandard.json` records a verifier's confusion matrix, sample size, optional derived metrics
+and inter-rater agreement, and a `calibrated` flag, versioned per measurement. A `ReasoningAssay`'s
+`verifier.calibrationRef` **must** point at one; a verdict without it cannot project above `sad`. This
+gives "who verifies the verifier" a mechanical answer: the verifier's own measured receipts. Re-measuring
+publishes a new version, and referencing assays re-project against it — the same discipline as keeping
+every benchmark arm rather than only its current winner.
+
+### 4. The projection is executable and CI-enforced
+
+`tools/validate_reasoning_examples.py` recomputes `assay()` from each example's stored axes and fails the
+build if the recorded `projectedState` does not follow from them. The projection cannot silently drift from
+the axes it claims to summarise.
+
+## Consequences
+
+- On the current stack, essentially only inline-bound verified-compute paths project to `ok`. This is
+  honest, and renders the verified-compute moat directly as UX.
+- Authenticity is a property of the actor/channel (mirroring `EventEnvelope.actor`/`integrity`), so a
+  confident-sounding answer cannot launder its own authority.
+- The single highest-leverage follow-on is populating real `AssayStandard` records from verifier calibration
+  runs, so production verdicts reference measured — not assumed — reliability.
+
+## Non-goals
+
+- This ADR does not change operational-health telemetry.
+- It does not mandate a runtime; it defines the canonical shapes that emitters (e.g. superconscious,
+  agentplane evidence sealing) conform to.
diff --git a/examples/assay_standard.json b/examples/assay_standard.json
@@ -0,0 +1,25 @@
+{
+  "id": "urn:srcos:assay-standard:narration-fidelity-verifier:0.2.0",
+  "type": "AssayStandard",
+  "specVersion": "2.0.0",
+  "verifierId": "urn:srcos:verifier:narration-fidelity",
+  "version": "0.2.0",
+  "confusionMatrix": {
+    "truePositive": 41,
+    "falsePositive": 12,
+    "trueNegative": 38,
+    "falseNegative": 9
+  },
+  "metrics": {
+    "f1": 0.8,
+    "precision": 0.77,
+    "recall": 0.82
+  },
+  "interRaterAgreement": {
+    "kappa": 0.68,
+    "interpretation": "substantial"
+  },
+  "sampleSize": 100,
+  "calibrated": true,
+  "measuredAt": "2026-07-05T00:00:00Z"
+}
diff --git a/examples/reasoning_assay.json b/examples/reasoning_assay.json
@@ -0,0 +1,25 @@
+{
+  "id": "urn:srcos:reasoning-assay:superconscious-demo-ok",
+  "type": "ReasoningAssay",
+  "specVersion": "2.0.0",
+  "runRef": "urn:srcos:reasoning-run:superconscious-demo",
+  "claimRef": "sha256:claim-computed-answer",
+  "method": "computed",
+  "binding": "inline",
+  "verifier": {
+    "verifierId": "urn:srcos:verifier:narration-fidelity",
+    "calibrationRef": "urn:srcos:assay-standard:narration-fidelity-verifier:0.2.0"
+  },
+  "agreement": {
+    "arms": 3,
+    "correlation": 0.18,
+    "effectiveVotes": 2.6
+  },
+  "authority": {
+    "actorRef": "urn:srcos:agent:superconscious",
+    "channel": "tool",
+    "integrityVerified": true
+  },
+  "projectedState": "ok",
+  "assayedAt": "2026-07-05T00:00:01Z"
+}
diff --git a/examples/reasoning_assay.refuted.json b/examples/reasoning_assay.refuted.json
@@ -0,0 +1,25 @@
+{
+  "id": "urn:srcos:reasoning-assay:superconscious-demo-refuted",
+  "type": "ReasoningAssay",
+  "specVersion": "2.0.0",
+  "runRef": "urn:srcos:reasoning-run:superconscious-demo",
+  "claimRef": "sha256:claim-authority-broken",
+  "method": "generated",
+  "binding": "post-hoc",
+  "verifier": {
+    "verifierId": "urn:srcos:verifier:narration-fidelity",
+    "calibrationRef": "urn:srcos:assay-standard:narration-fidelity-verifier:0.2.0"
+  },
+  "agreement": {
+    "arms": 3,
+    "correlation": 0.22,
+    "effectiveVotes": 2.4
+  },
+  "authority": {
+    "actorRef": "urn:srcos:agent:superconscious",
+    "channel": "sdk",
+    "integrityVerified": false
+  },
+  "projectedState": "bad",
+  "assayedAt": "2026-07-05T00:00:01Z"
+}
diff --git a/examples/reasoning_assay.unassayed.json b/examples/reasoning_assay.unassayed.json
@@ -0,0 +1,26 @@
+{
+  "id": "urn:srcos:reasoning-assay:superconscious-demo-unassayed",
+  "type": "ReasoningAssay",
+  "specVersion": "2.0.0",
+  "runRef": "urn:srcos:reasoning-run:superconscious-demo",
+  "claimRef": "sha256:claim-generated-with-citations",
+  "method": "generated",
+  "binding": "post-hoc",
+  "verifier": {
+    "verifierId": "urn:srcos:verifier:deployed-nli",
+    "calibrationRef": "urn:srcos:assay-standard:deployed-nli:0.1.0"
+  },
+  "agreement": {
+    "arms": 3,
+    "correlation": 0.66,
+    "effectiveVotes": 1.2
+  },
+  "authority": {
+    "actorRef": "urn:srcos:agent:superconscious",
+    "channel": "sdk",
+    "integrityVerified": true
+  },
+  "projectedState": "sad",
+  "unassayedReason": "post-hoc-binding+correlated-arms+uncalibrated-verifier",
+  "assayedAt": "2026-07-05T00:00:01Z"
+}
diff --git a/schemas/AssayStandard.json b/schemas/AssayStandard.json
@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/AssayStandard.json",
+  "title": "AssayStandard",
+  "description": "The measured, versioned reliability of a verifier ('judge') — the calibrated reference every ReasoningAssay is checked against. Answers 'who verifies the verifier' mechanically: a verdict may only claim 'ok' when it points at a standard whose reliability was actually measured. Re-measuring publishes a new version; historical assays that reference an older version can be re-projected against the newer one.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "verifierId", "version", "confusionMatrix", "sampleSize", "measuredAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:assay-standard:",
+      "description": "Stable URN for this measured standard. Pattern: urn:srcos:assay-standard:<verifier-slug>:<version>."
+    },
+    "type": { "const": "AssayStandard" },
+    "specVersion": { "type": "string", "description": "Spec version, e.g. \"2.0.0\"." },
+    "verifierId": {
+      "type": "string",
+      "description": "URN or stable identifier of the verifier/judge whose reliability this standard records."
+    },
+    "version": {
+      "type": "string",
+      "description": "Version of the verifier at the time of measurement. A new measurement of the same verifier yields a new AssayStandard with a bumped version."
+    },
+    "confusionMatrix": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["truePositive", "falsePositive", "trueNegative", "falseNegative"],
+      "description": "Raw counts from the calibration run. Facts, not interpretation — metrics below are derived from these and may be recomputed.",
+      "properties": {
+        "truePositive": { "type": "integer", "minimum": 0 },
+        "falsePositive": { "type": "integer", "minimum": 0 },
+        "trueNegative": { "type": "integer", "minimum": 0 },
+        "falseNegative": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional derived scores (recomputable from confusionMatrix). Present as a convenience; the matrix is authoritative.",
+      "properties": {
+        "f1": { "type": "number", "minimum": 0, "maximum": 1 },
+        "precision": { "type": "number", "minimum": 0, "maximum": 1 },
+        "recall": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "interRaterAgreement": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional inter-rater reliability when the standard was set against multiple human/reference judges.",
+      "properties": {
+        "kappa": { "type": "number", "minimum": -1, "maximum": 1 },
+        "interpretation": {
+          "enum": ["poor", "slight", "fair", "moderate", "substantial", "almost-perfect"]
+        }
+      }
+    },
+    "sampleSize": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Number of labelled items the standard was measured over. A standard measured on too few items is itself weak evidence."
+    },
+    "calibrated": {
+      "type": "boolean",
+      "description": "Whether this standard clears the project's minimum bar to let a referencing assay project to 'ok'. Uncalibrated standards can still be recorded — a referencing assay then projects no better than 'sad'."
+    },
+    "measuredAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the measurement was taken. Standards are perishable; consumers may treat an old measurement as stale."
+    }
+  }
+}