diff --git a/CHANGELOG.md b/CHANGELOG.md index 0eb6b27..9144504 100644 --- 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 index c81bc0a..d1754c5 100644 --- 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 index f6c5bd3..69c6c43 100644 --- 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 new file mode 100644 index 0000000..d0ccbe9 --- /dev/null +++ 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 new file mode 100644 index 0000000..a4a7947 --- /dev/null +++ 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 new file mode 100644 index 0000000..66f6fde --- /dev/null +++ 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 index 404934c..1564b50 100644 --- 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 b/examples/delta_surface.json similarity index 100% rename from examples/delta-surface.sample.json rename to examples/delta_surface.json diff --git a/examples/truth-surface.sample.json b/examples/truth_surface.json similarity index 100% rename from examples/truth-surface.sample.json rename to examples/truth_surface.json diff --git a/schemas/README.md b/schemas/README.md index 1b4efd8..7e89420 100644 --- 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 index 0ea8d3d..aff4abe 100644 --- 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",