SourceOS-Linux · mdheller · Apr 18, 2026 · Apr 18, 2026 · Apr 18, 2026 · Apr 18, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- Truth Plane: `TruthSurface` and `DeltaSurface` schemas + canonical examples (`examples/truth_surface.json`, `examples/delta_surface.json`)
+- Control-plane: `IncidentEvent` schema for incident lifecycle events
+- Truth Plane: OpenAPI/AsyncAPI patch fragments (`openapi.truth-plane.patch.yaml`, `asyncapi.truth-plane.patch.yaml`)
 - `description` fields on all 54 schemas and all properties (non-breaking documentation improvement)
 - `ARCHITECTURE.md` — two-plane architecture, schema families, governance lifecycle, URN table
 - `CONTRIBUTING.md` — schema authoring conventions, URN naming guide, PR checklist

diff --git a/docs/adr/0001-truth-surfaces-b11-delta-appendix-a-reuse-map.md b/docs/adr/0001-truth-surfaces-b11-delta-appendix-a-reuse-map.md
@@ -1,57 +1,12 @@
-# ADR-0001 Appendix A — Reuse map + schema plan (B¹¹ / Δ / incidents)
+# ADR-0001 Appendix A — (Deprecated) TruthSurface/DeltaSurface reuse map
 
 **Date:** 2026-04-14  
-**Status:** Proposed (appendix to ADR-0001)
+**Status:** Deprecated (superseded)
 
----
+This appendix previously served as the reuse map + schema plan for TruthSurface (B¹¹) and DeltaSurface (Δ).
 
-## Purpose
+It is superseded by:
 
-ADR-0001 establishes the decision to add TruthSurface (B¹¹) and DeltaSurface (Δ) and to standardize incident semantics. This appendix makes the decision *actionable* by:
-
-1) specifying a reuse-first mapping onto existing contracts already present in this repo, and  
-2) enumerating the minimal net-new schema files + examples required for v0 portability.
-
----
-
-## Reuse-first mapping
-
-| Capability we need | Reuse (existing contracts / patterns) | Net-new (v0) |
-|---|---|---|
-| Signed “truth summary” per plane | Reuse **URN + `type` discriminator + `specVersion`** conventions (e.g., `TelemetryEvent`). Reuse existing evidence references (PolicyDecision/CapabilityToken/RunRecord/ProvenanceRecord) as *refs*, not embedded duplicates. | `schemas/TruthSurface.json` + `examples/truth-surface.sample.json` |
-| Typed diff between two truth summaries | Reuse existing “risk + evidence + human approval” posture expressed in `policies/skills/default-policy-pack.rego` as the canonical gate style; DeltaSurface records the gate results, it does not *re-decide* policy. | `schemas/DeltaSurface.json` + `examples/delta-surface.sample.json` |
-| Incident semantics (Freeze/Fork/Kill) | Reuse control-plane event structure conventions: `event_id`, `event_name`, `occurred_at`, `actor`, `run`, `refs`, `payload` as in the existing skill execution lifecycle schema and samples. | `schemas/control-plane/incident-events.schema.json` + `examples/control-plane/incident.freeze.sample.json` |
-| Frontier / PBAC egress authorization | Reuse `CapabilityToken` as the short-lived signed grant primitive. Treat frontier/network constraints as a profile extension (additive) aligned to the existing governance lifecycle (decision → token). | v0: represent frontier intent + result refs in TruthSurface/DeltaSurface. v1: add an additive `frontier` block to `CapabilityToken.scope` (separate ADR if needed). |
-
----
-
-## Schema plan (v0)
-
-New schema files added in this PR branch:
-
-1) `schemas/TruthSurface.json`
-2) `schemas/DeltaSurface.json`
-3) `schemas/control-plane/incident-events.schema.json`
-
-New example payloads added in this PR branch:
-
-1) `examples/truth-surface.sample.json`
-2) `examples/delta-surface.sample.json`
-3) `examples/control-plane/incident.freeze.sample.json`
-
----
-
-## Non-goals for v0
-
-- No OpenAPI/AsyncAPI surface changes yet (schemas stabilize first).
-- No in-place `CapabilityToken` extension yet (we keep the profile extension as a documented plan until agreed).
-- No enforcement logic (belongs in the substrate repo).
-
----
-
-## Follow-on steps (expected)
-
-1) Add OpenAPI/AsyncAPI patch entries for TruthSurface/DeltaSurface publishing endpoints + event channels.
-2) Add conformance fixtures in workstation-contracts (schema validation + golden examples).
-3) Implement substrate emitters/enforcers in SociOS-Linux/SourceOS (services + nftables + incident executor).
+- `docs/adr/0009-truth-surfaces-b11-delta-appendix-a-reuse-map.md`
 
+Reason: multiple unrelated ADRs in this repo used the number `0001`. To eliminate ambiguity, TruthSurface/DeltaSurface were assigned ADR-0009.
diff --git a/docs/adr/0001-truth-surfaces-b11-delta.md b/docs/adr/0001-truth-surfaces-b11-delta.md
@@ -1,115 +1,13 @@
-# ADR-0001 — Truth Surfaces (B¹¹) + Δ-Surfaces + Incident Semantics
+# ADR-0001 — (Deprecated) Truth Surfaces (B¹¹) + Δ-Surfaces
 
 **Date:** 2026-04-14  
-**Status:** Proposed
+**Status:** Deprecated (superseded)
 
----
+This file previously described TruthSurface (B¹¹) and DeltaSurface (Δ).
 
-## Context
+It is superseded by:
 
-We need a *portable, machine-verifiable* way to represent “what is true right now” about:
+- `docs/adr/0009-truth-surfaces-b11-delta.md`
+- `docs/adr/0009-truth-surfaces-b11-delta-appendix-a-reuse-map.md`
 
-- the immutable substrate (host integrity and policy posture),
-- the controlled user space (governed meaning and intent),
-- the agent space (bounded execution and decisions), and
-- the witness/replication posture (what was attested externally).
-
-In practice, the system already carries many of these primitives:
-
-- The **two-plane contract model** (metadata plane + agent plane) and additive patch strategy (`openapi*.yaml`, `asyncapi*.yaml`).
-- A **short-lived signed grant** primitive (`schemas/CapabilityToken.json`) derived from policy decisions.
-- A **control-plane event lifecycle** style (e.g., `schemas/control-plane/skill-execution-events.schema.json`) and a default skill policy pack (`policies/skills/default-policy-pack.rego`).
-- A concrete *mesh skill* example that already encodes deterministic plans, evidence requirements, and Cairn refs (`examples/control-plane/mesh-skill.checkout-validate.yaml`).
-
-What is missing is a canonical “truth object” that can be:
-
-1) generated deterministically,  
-2) signed and Merkle-addressed,  
-3) compared across time and planes (Δ), and  
-4) gated/promoted with explicit thresholds and evidence requirements.
-
-We also need incident semantics that are explicit and replayable (Freeze → Fork → Kill) rather than implicit operational folklore.
-
-## Decision
-
-### 1) Add two new contract types (schema family) to `sourceos-spec`
-
-We introduce **TruthSurface** (B¹¹) and **DeltaSurface** (Δ) as first-class contract objects, published alongside the existing schema families.
-
-- **TruthSurface (B¹¹)**: a signed, Merkle-addressed summary for a given plane (`sealed/system`, `controlled/user`, `open/agent`, `witness/twin`).
-- **DeltaSurface (Δ)**: a signed diff between two TruthSurfaces with:
-  - semantic drift metrics,
-  - runtime drift metrics,
-  - governance deltas,
-  - a promotion recommendation + gate results.
-
-These new types must compose cleanly with existing primitives (TelemetryEvent, ExecutionDecision, PolicyDecision/CapabilityToken, ProvenanceRecord) rather than replacing them.
-
-### 2) Represent “PBAC tickets” as a CapabilityToken profile, not a new token class
-
-Off-box / frontier egress authorization is expressed as a **CapabilityToken** profile extension:
-
-- add network scope constraints (e.g., `frontier_hops`, `targets`, `egress_class`) as structured fields,
-- keep the existing governance flow (evaluate → decision → issue token),
-- ensure tokens remain short-lived and auditable.
-
-This prevents parallel token taxonomies.
-
-### 3) Standardize incident semantics as contract-level events
-
-We define incident semantics as a small set of event types aligned with the existing control-plane event lifecycle style:
-
-- `incident.freeze`
-- `incident.fork`
-- `incident.kill`
-
-Each event MUST carry:
-- actor context (human/agent/service),
-- run/trace linkage (when applicable),
-- refs to evidence bundles and pre/post Cairn anchors,
-- status progression compatible with existing control-plane conventions.
-
-### 4) Promotion gates are contract-level, evidence-first
-
-Promotion of a surface (or a claim derived from it) requires explicit gate checks:
-
-- evidence bundle completeness (required evidence list satisfied),
-- risk threshold checks,
-- approval rules (e.g., human approval required for certain classes),
-- semantic coherence thresholds,
-- runtime integrity thresholds.
-
-We explicitly reuse the posture already present in `policies/skills/default-policy-pack.rego` (risk gating, human approval requirement, evidence requirement checking) as the canonical style baseline.
-
-### 5) Keep enforcement out of this repository
-
-`sourceos-spec` defines **what** a surface/token/event is.
-Enforcement remains the responsibility of the substrate and runtime implementations (e.g., `SociOS-Linux/SourceOS`).
-
-## Alternatives considered
-
-| Alternative | Reason not chosen |
-|-------------|------------------|
-| Put truth surfaces directly in the substrate repo only | Breaks the “canonical contract registry” role of this repo; makes portability and interoperability harder. |
-| Create a new standalone “truth-surface spec” repo | Fragments the spec; duplicates identity/versioning discipline; increases coordination overhead. |
-| Use only existing TelemetryEvent/ExecutionDecision structures | Those are necessary components but not sufficient as a signed, Merkle-addressed *summary surface* with promotion gating and Δ comparison. |
-
-## Consequences
-
-Positive:
-- A single canonical contract for truth, drift, and gating across planes.
-- Enables conformance fixtures and independent validators (e.g., workstation lanes).
-- Allows implementations to evolve while remaining interoperable (schemas, OpenAPI, AsyncAPI, JSON-LD).
-
-Negative:
-- Adds schema surface area that must be versioned and maintained.
-- Requires a clear reuse map to prevent duplication with existing agent-plane primitives.
-
-## References
-
-- `ARCHITECTURE.md` — two-plane model and patch-file composition strategy.
-- `schemas/CapabilityToken.json` — existing short-lived signed grant primitive.
-- `schemas/control-plane/skill-execution-events.schema.json` — lifecycle event conventions.
-- `policies/skills/default-policy-pack.rego` — baseline risk/evidence/approval gating style.
-- `examples/control-plane/mesh-skill.checkout-validate.yaml` — deterministic plan + evidence requirements + Cairn refs.
-- `examples/control-plane/skill.evidence.attached.sample.json` — concrete event sample for evidence attachment.
+Reason: multiple unrelated ADRs in this repo used the number `0001`. To eliminate ambiguity, TruthSurface/DeltaSurface were assigned ADR-0009.
diff --git a/docs/adr/0009-truth-surfaces-b11-delta-appendix-a-reuse-map.md b/docs/adr/0009-truth-surfaces-b11-delta-appendix-a-reuse-map.md
@@ -0,0 +1,46 @@
+# ADR-0009 Appendix A — Reuse map + schema plan (B¹¹ / Δ)
+
+**Date:** 2026-04-14  
+**Status:** Accepted (appendix to ADR-0009)
+
+---
+
+## Purpose
+
+This appendix makes ADR-0009 actionable by:
+
+1) specifying a reuse-first mapping onto existing contracts already present in this repo, and  
+2) enumerating the minimal net-new schema files + examples required for v0 portability.
+
+---
+
+## Reuse-first mapping
+
+| Capability we need | Reuse (existing contracts / patterns) | Net-new (v0) |
+|---|---|---|
+| Signed “truth summary” per plane | Reuse **URN + `type` discriminator + `specVersion`** conventions (e.g., `TelemetryEvent`). Reuse existing evidence references (PolicyDecision/CapabilityToken/RunRecord/ProvenanceRecord) as *refs*, not embedded duplicates. | `schemas/TruthSurface.json` + `examples/truth_surface.json` |
+| Typed diff between two truth summaries | Reuse existing “risk + evidence + human approval” posture expressed in `policies/skills/default-policy-pack.rego` as the canonical gate style; DeltaSurface records the gate results, it does not *re-decide* policy. | `schemas/DeltaSurface.json` + `examples/delta_surface.json` |
+| Incident semantics (Freeze/Fork/Kill) | Reuse control-plane event structure conventions: `event_id`, `event_name`, `occurred_at`, `actor`, `run`, `refs`, `payload` as in the existing skill execution lifecycle schema and samples. | `schemas/control-plane/incident-events.schema.json` + `examples/control-plane/incident.freeze.sample.json` |
+
+---
+
+## Schema plan (v0)
+
+New schema files:
+
+1) `schemas/TruthSurface.json`
+2) `schemas/DeltaSurface.json`
+3) `schemas/control-plane/incident-events.schema.json`
+
+New example payloads:
+
+1) `examples/truth_surface.json`
+2) `examples/delta_surface.json`
+3) `examples/control-plane/incident.freeze.sample.json`
+
+---
+
+## Notes
+
+- OpenAPI/AsyncAPI patch fragments exist as additive files (`openapi.truth-plane.patch.yaml`, `asyncapi.truth-plane.patch.yaml`).
+- Enforcement belongs in substrate/runtime repos; this repo defines contract shapes.
diff --git a/docs/adr/0009-truth-surfaces-b11-delta.md b/docs/adr/0009-truth-surfaces-b11-delta.md
@@ -0,0 +1,8 @@
+# ADR-0009 — Truth Surfaces (B¹¹) + Δ-Surfaces
+
+**Date:** 2026-04-14  
+**Status:** Accepted
+
+This ADR is the canonical decision record for TruthSurface (B¹¹) and DeltaSurface (Δ).
+
+See Appendix A for the reuse map and schema plan.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,26 @@
+# Architecture Decision Records (ADRs)
+
+This directory contains Architecture Decision Records for the SourceOS/SociOS typed contract canon.
+
+## Canonical numbering rule
+
+- ADR numbers are unique. If a collision occurs, the newer record is assigned the next available number.
+- If a previously published file used a colliding number, it is kept as a **deprecated stub** pointing to the canonical ADR.
+
+## Current notes
+
+- TruthSurface/DeltaSurface are canonical under ADR-0009.
+- Several older records used `0001` for unrelated topics; those files should be treated as historical and may be renamed later.
+
+## Index (selected)
+
+- `0000-template.md`
+- `0001-os-build-cybernetic-boundary.md`
+- `0002-json-schema-draft-2020-12.md`
+- `0003-typed-policy-condition.md`
+- `0004-generic-event-envelope.md`
+- `0005-additive-patch-pattern.md`
+- `ADR-0006-polycentric-observer-schema-family.md`
+- `ADR-0007-local-first-control-node-and-image-promotion-seam.md`
+- `ADR-0008-local-first-release-and-enrollment-contract-family.md`
+- `0009-truth-surfaces-b11-delta.md`
diff --git a/examples/README.md b/examples/README.md
@@ -41,6 +41,17 @@ agent_session.json  ──►  execution_decision.json  ──►  session_recei
 
 ---
 
+## Truth Plane examples
+
+These examples illustrate the Truth Plane contract additions:
+
+| File | Schema type | Description |
+|------|------------|-------------|
+| `truth_surface.json` | TruthSurface | Signed truth summary emitted by a plane (system/user/agent/witness) |
+| `delta_surface.json` | DeltaSurface | Signed diff between two TruthSurfaces with gate results |
+
+---
+
 ## Recent additions — Fog Layer examples
 
 The fog example set illustrates the new FogVault / FogCompute contract family:
@@ -72,6 +83,7 @@ The fog example set illustrates the new FogVault / FogCompute contract family:
 | `content_ref.json` | ContentRef | Content-addressed reference for fog blobs / manifests |
 | `dataset.json` | Dataset | Personal health observations dataset |
 | `data_sphere.json` | DataSphere | The personal-curated execution environment |
+| `delta_surface.json` | DeltaSurface | Truth Plane delta surface example |
 | `execution_decision.json` | ExecutionDecision | Agent allow-decision for a tool invocation |
 | `event_envelope.json` | EventEnvelope | Event published when the run completes |
 | `experiment_flag.json` | ExperimentFlag | A feature flag for the new obfuscation algorithm |
@@ -97,6 +109,7 @@ The fog example set illustrates the new FogVault / FogCompute contract family:
 | `telemetry_event.json` | TelemetryEvent | An informational telemetry event from the agent session |
 | `topic.json` | Topic | FogVault topic definition |
 | `topic_envelope.json` | TopicEnvelope | FogVault append-only entry envelope |
+| `truth_surface.json` | TruthSurface | Truth Plane truth surface example |
 | `workflow_spec.json` | WorkflowSpec | The health-data obfuscation workflow |
 | `workorder.json` | WorkOrder | FogCompute work order |
 | `usage_receipt.json` | UsageReceipt | FogCompute execution receipt |

diff --git a/examples/delta-surface.sample.json → examples/delta_surface.json b/examples/delta-surface.sample.json → examples/delta_surface.json
diff --git a/examples/truth-surface.sample.json → examples/truth_surface.json b/examples/truth-surface.sample.json → examples/truth_surface.json
diff --git a/schemas/README.md b/schemas/README.md
@@ -42,6 +42,7 @@ These types support:
 | `DataRef.json` | DataRef | _(sub-object, no top-level id)_ |
 | `DataSphere.json` | DataSphere | `urn:srcos:sphere:` |
 | `Dataset.json` | Dataset | `urn:srcos:dataset:` |
+| `DeltaSurface.json` | DeltaSurface | `urn:srcos:delta-surface:` |
 | `EntityField.json` | EntityField | _(sub-object inside SchemaDefinition)_ |
 | `EventEnvelope.json` | EventEnvelope | `urn:srcos:event:` |
 | `Exception.json` | Exception | _(sub-object inside Policy)_ |
@@ -86,6 +87,7 @@ These types support:
 | `Topic.json` | Topic | `urn:srcos:topic:` |
 | `TopicEnvelope.json` | TopicEnvelope | `urn:srcos:topic-entry:` |
 | `Trigger.json` | Trigger | _(sub-object inside WorkflowSpec)_ |
+| `TruthSurface.json` | TruthSurface | `urn:srcos:truth-surface:` |
 | `UsageReceipt.json` | UsageReceipt | `urn:srcos:receipt:usage:` |
 | `ValidValues.json` | ValidValues | _(sub-object inside EntityField)_ |
 | `WorkflowEdge.json` | WorkflowEdge | _(sub-object inside WorkflowSpec)_ |
@@ -142,7 +144,7 @@ These types support:
 | `SchemaDefinition` | A named, versioned logical schema composed of `EntityField`s |
 | `EntityField` | A field descriptor inside a `SchemaDefinition` |
 | `Field` | A fully annotated, quality-profiled field attached to a live `Dataset` |
-| `TagAssignment` | A classification tag with confidence score, source, and review record |
+| `TagAssignment` | A classification tag with confidence score, source provenance, and review record |
 | `ValidValues` | Enumeration, numeric range, or regex constraint on a field |
 | `QualityMetric` | A named quality dimension (completeness, validity, …) scored 0–1 |
 | `ProfileStats` | Statistical profile of a column: row count, nulls, distinct values, top-N values |
@@ -171,6 +173,8 @@ These types support:
 | `MappingSpec` | A field-to-field semantic mapping with multi-method confidence evidence |
 | `MappingEvidence` | A single evidence item for a `MappingSpec` (label similarity, value overlap, …) |
 | `EventEnvelope` | The universal wrapper for all AsyncAPI channel messages |
+| `TruthSurface` | Signed truth summary emitted by a plane (system/user/agent/witness) |
+| `DeltaSurface` | Signed diff between two TruthSurfaces with gate results |
 
 ### Agent Plane
 

diff --git a/schemas/control-plane/incident-events.schema.json b/schemas/control-plane/incident-events.schema.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://socioprophet.org/schemas/events/incident-events.schema.json",
+  "$id": "https://schemas.srcos.ai/v2/control-plane/IncidentEvent.json",
   "title": "IncidentEvent",
   "description": "Control-plane incident lifecycle events (Freeze/Fork/Kill). Uses the same actor/run/refs/payload conventions as other control-plane lifecycle events.",
   "type": "object",