From edb692df68a208243d4cc1cbea90e368356cdba3 Mon Sep 17 00:00:00 2001 From: Michael Heller <21163552+mdheller@users.noreply.github.com> Date: Sun, 5 Jul 2026 18:00:44 -0400 Subject: [PATCH] spec(reasoning): wire the Assay into ReasoningReceipt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add optional ReasoningReceipt.assay — the reserved receipt landing spot for the epistemic Assay (PR #198 follow-on). Run-level, render-time summary that references its run's ReasoningAssay records by URN (assayRefs, so verdicts stay independently re-projectable) and surfaces overallState, weakest-link binding, verifier calibrationRef, per-state counts, and projectedAt. A cache, never authoritative over the assays. EventEnvelope needs no structural change: each assay's authority axis already mirrors EventEnvelope.actor/integrity by reference. Backward-compatible (optional field). validate-reasoning-examples green. --- CHANGELOG.md | 1 + examples/reasoning_receipt.json | 8 ++++++ schemas/ReasoningReceipt.json | 40 +++++++++++++++++++++++++++ schemas/reasoning-contracts.README.md | 8 ++++++ 4 files changed, 57 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c5a4a71..08897be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi ### 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`. +- `ReasoningReceipt.assay` (optional) — the reserved receipt landing spot for the Assay: a render-time, run-level epistemic summary that references its run's `ReasoningAssay` records by URN (`assayRefs`) and surfaces the projected `overallState`, weakest-link `binding`, verifier `calibrationRef`, per-state `counts`, and `projectedAt`. A cache of the referenced verdicts, not authoritative over them — re-projectable when an `AssayStandard` improves. Backward-compatible (optional field). The assay's `authority` axis continues to mirror `EventEnvelope.actor`/`integrity`, so the envelope needs no structural change. - 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/examples/reasoning_receipt.json b/examples/reasoning_receipt.json index e2de401..d5eb5ce 100644 --- a/examples/reasoning_receipt.json +++ b/examples/reasoning_receipt.json @@ -12,6 +12,14 @@ "memory": "proposal-only", "approval": "not-required" }, + "assay": { + "assayRefs": ["urn:srcos:reasoning-assay:superconscious-demo-ok"], + "overallState": "ok", + "binding": "inline", + "calibrationRef": "urn:srcos:assay-standard:narration-fidelity-verifier:0.2.0", + "counts": { "ok": 1, "sad": 0, "bad": 0 }, + "projectedAt": "2026-07-05T00:00:02Z" + }, "replayClass": "exact", "capturedAt": "2026-05-05T00:00:01Z" } diff --git a/schemas/ReasoningReceipt.json b/schemas/ReasoningReceipt.json index 745a26e..7b69b87 100644 --- a/schemas/ReasoningReceipt.json +++ b/schemas/ReasoningReceipt.json @@ -18,6 +18,46 @@ "type": "object", "additionalProperties": true }, + "assay": { + "type": "object", + "additionalProperties": false, + "description": "Run-level epistemic posture: a render-time summary projected from the run's ReasoningAssay records. A cache, not the source of truth — re-derivable by re-projecting the referenced assays against the current AssayStandard, so it is optional and never authoritative over the assays themselves. The reserved receipt landing spot for binding + verifier calibration.", + "properties": { + "assayRefs": { + "type": "array", + "items": { "type": "string", "pattern": "^urn:srcos:reasoning-assay:" }, + "description": "URNs of the ReasoningAssay records covering this run's claims. Referenced, not embedded, so each verdict stays independently re-projectable." + }, + "overallState": { + "enum": ["ok", "sad", "bad"], + "description": "assay() projection for the run's overall answer AT projectedAt — the weakest-link readout across the referenced assays. A cache of the tuple, not a stored severity." + }, + "binding": { + "enum": ["inline", "post-hoc"], + "description": "Weakest evidence binding across the run's assays. A single post-hoc claim pulls the run's binding to post-hoc; recorded so a post-hoc 'verified' run is not mistaken for an inline one." + }, + "calibrationRef": { + "type": "string", + "pattern": "^urn:srcos:assay-standard:", + "description": "The AssayStandard the overall verdict rests on. An absent or uncalibrated reference caps overallState at 'sad'." + }, + "counts": { + "type": "object", + "additionalProperties": false, + "description": "Tally of the referenced assays by projected state at projectedAt.", + "properties": { + "ok": { "type": "integer", "minimum": 0 }, + "sad": { "type": "integer", "minimum": 0 }, + "bad": { "type": "integer", "minimum": 0 } + } + }, + "projectedAt": { + "type": "string", + "format": "date-time", + "description": "When this summary was projected. Re-projection against a newer AssayStandard yields a later summary rather than mutating this one." + } + } + }, "replayClass": { "enum": ["exact", "best-effort", "evidence-only", "non-replayable-side-effect"] }, "capturedAt": { "type": "string", "format": "date-time" } } diff --git a/schemas/reasoning-contracts.README.md b/schemas/reasoning-contracts.README.md index b876f41..9a9fd4f 100644 --- a/schemas/reasoning-contracts.README.md +++ b/schemas/reasoning-contracts.README.md @@ -54,6 +54,14 @@ historical assays re-project without mutating their records — the same discipl arm rather than only its current winner. `tools/validate_reasoning_examples.py` enforces this: it recomputes `assay()` from the stored axes and fails CI if the recorded `projectedState` does not follow from them. +`ReasoningReceipt.assay` is the reserved receipt landing spot: a run-level, render-time summary that +**references** its run's `ReasoningAssay` records by URN (`assayRefs`) rather than embedding them — so each +verdict stays independently re-projectable — and surfaces the projected `overallState`, the weakest-link +`binding`, the verifier `calibrationRef`, per-state `counts`, and `projectedAt`. It is a cache, never +authoritative over the assays themselves, and optional so existing receipts remain valid. The `authority` +axis of each assay mirrors `EventEnvelope.actor`/`integrity`, so authenticity is corroborated from the +envelope the claim arrived on rather than asserted by the content — the envelope needs no structural change. + Expected consumers: - `SocioProphet/superconscious` as the reference governed cognition loop;