Wire control plane schemas into README

Author: mdheller

README.md

@@ -6,7 +6,7 @@ SourceOS State Integrity daemon: local-first object, actor, schema, repair, prov
 
 `sourceos-syncd` is the reference substrate for SourceOS local-first state integrity. It should make state observable, explainable, policy-governed, repairable, attestable, and safe for agent use.
 
-This repository is the canonical home for the SourceOS State Integrity Report, Index Lane model, and telemetry signal-control doctrine.
+This repository is the canonical home for the SourceOS State Integrity Report, Index Lane model, telemetry signal-control doctrine, and the first SourceOS control-plane contract spine.
 
 ## Core concepts
 
@@ -18,28 +18,62 @@ This repository is the canonical home for the SourceOS State Integrity Report, I
 - **Attested operations**: Lampstand preserves important state reports and repair actions as signed evidence.
 - **Telemetry signal control**: raw logs are evidence, not the product; expected policy blocks are classified correctly and duplicate noise is coalesced.
 - **Operator narrative**: SourceOS explains what happened, why policy acted, what risk remains, and what action is required.
+- **Control-plane receipts**: events, services, capabilities, launch manifests, and incident bundles share one typed vocabulary.
 
 ## Specs
 
 - [`docs/specs/sourceos-state-integrity-report.md`](docs/specs/sourceos-state-integrity-report.md)
 - [`docs/specs/sourceos-index-lanes.md`](docs/specs/sourceos-index-lanes.md)
+- [`docs/specs/sourceos-control-plane-integration.md`](docs/specs/sourceos-control-plane-integration.md)
 - [`docs/telemetry-noise-control-spec.md`](docs/telemetry-noise-control-spec.md)
 - [`docs/canonical-event-envelope.md`](docs/canonical-event-envelope.md)
 - [`docs/implementation-roadmap.md`](docs/implementation-roadmap.md)
+- [`adr/0001-sourceos-control-plane.md`](adr/0001-sourceos-control-plane.md)
 
 ## JSON Schemas
 
+State integrity:
+
 - [`schemas/sourceos.state-integrity-report.v1alpha1.schema.json`](schemas/sourceos.state-integrity-report.v1alpha1.schema.json)
 - [`schemas/sourceos.repair-plan.v1alpha1.schema.json`](schemas/sourceos.repair-plan.v1alpha1.schema.json)
 
+Control plane:
+
+- [`schemas/sourceos-event.schema.json`](schemas/sourceos-event.schema.json)
+- [`schemas/sourceos-service.schema.json`](schemas/sourceos-service.schema.json)
+- [`schemas/sourceos-capability.schema.json`](schemas/sourceos-capability.schema.json)
+- [`schemas/sourceos-launch-manifest.schema.json`](schemas/sourceos-launch-manifest.schema.json)
+- [`schemas/sourceos-incident.schema.json`](schemas/sourceos-incident.schema.json)
+
 The runtime validator is standard-library-only today; the schemas are the canonical external contract for downstream validators, SDKs, dashboards, and cross-repo integrations.
 
 ## Golden examples
 
+Health and repair:
+
 - [`examples/health/healthy.snapshot.json`](examples/health/healthy.snapshot.json)
 - [`examples/health/degraded.snapshot.json`](examples/health/degraded.snapshot.json)
 - [`examples/health/repair-plan.json`](examples/health/repair-plan.json)
 
+Control plane:
+
+- [`examples/events/apple-mdm-entitlement-denial.coalesced.json`](examples/events/apple-mdm-entitlement-denial.coalesced.json)
+- [`examples/events/apple-darkwake-network-receipt.json`](examples/events/apple-darkwake-network-receipt.json)
+- [`examples/services/bearbrowser.service.json`](examples/services/bearbrowser.service.json)
+- [`examples/capabilities/browser-gpu-spawn.capability.json`](examples/capabilities/browser-gpu-spawn.capability.json)
+- [`examples/launch/bearbrowser.launch-manifest.json`](examples/launch/bearbrowser.launch-manifest.json)
+- [`examples/incidents/bearbrowser-identity-leak.incident.json`](examples/incidents/bearbrowser-identity-leak.incident.json)
+
+## Validation
+
+Bootstrap control-plane validation uses only Python standard-library checks:
+
+```bash
+python3 tools/validate_control_plane_examples.py
+```
+
+This validator is intentionally narrower than a full JSON Schema validator. It enforces schema-version alignment, controlled vocabulary basics, required operator narrative fields, causality fields, service capability lists, and the invariant that expected policy blocks do not render as warning/error by default.
+
 ## Intended CLI contract
 
 ```bash
@@ -66,6 +100,9 @@ sourceos repair rollback
 sourceos events explain
 sourceos events coalesce
 sourceos events verify
+sourceos control-plane validate
+sourceos services graph
+sourceos incidents explain
 ```
 
 ## Intended local HTTP contract
@@ -78,6 +115,10 @@ Local-only by default:
 - `/events` canonical event stream, privacy-tiered by caller capability
 - `/events/{id}` canonical event with evidence references
 - `/events/{id}/explain` human operator narrative
+- `/services` local service graph
+- `/services/{id}` service manifest and health state
+- `/capabilities` capability registry
+- `/incidents` local incident bundle index
 - `/metrics` Prometheus/OpenTelemetry export
 - `/repairz` repair planning endpoint, disabled remotely unless policy explicitly allows it
 
@@ -92,17 +133,37 @@ Required behaviors:
 - Redaction preserves causal structure: actor, target class, policy rule, and outcome remain understandable.
 - Local-first trust verification is the baseline; network trust lookup must be explicit and policy-authorized.
 - Analytics, hardware/UI diagnostics, and developer traces are separate lanes and suppressed from default security/operator views.
+- Wake, launch, identity, parser, incident, and telemetry activity must produce receipts instead of opaque logs.
+
+## Control-plane release gates
+
+A SourceOS service or product is not release-ready unless:
+
+1. It has a service manifest.
+2. It emits canonical events or explicitly documents why it does not.
+3. It declares required, optional, and denied capabilities.
+4. It has a hermetic launch manifest if it is an app.
+5. It produces an incident bundle for crashes, denial storms, wake anomalies, identity mismatches, and parser faults.
+6. It does not perform silent remote trust lookup.
+7. It does not emit remote telemetry by default.
+8. It coalesces repeated expected denials.
+9. It preserves privacy while retaining causal structure.
+10. It has a DeliveryExcellence signal-quality metric.
 
 ## Estate integration targets
 
-- `SocioProphet/policy-fabric`: policy decisions for indexing, retention, replication, purge, agent access, telemetry outcomes, and explanation codes.
+- `SocioProphet/policy-fabric`: policy decisions for indexing, retention, replication, purge, agent access, telemetry outcomes, explanation codes, capability grants, and release gates.
 - `SocioProphet/agentplane`: trust gates before agent actions against state substrates and process/agent lineage traces.
 - `SocioProphet/lampstand`: signed evidence, repair records, event attestations, and incident timelines.
 - `SocioProphet/memory-mesh`: memory-lane health, tombstones, staleness, replay, and event-linked memory provenance.
 - `SocioProphet/smart-tree`: object graph freshness, repo index health, structural churn, and package/source provenance.
-- SocioSphere dashboarding: operator cards for process, policy, trust, sync, repair, and narrative events.
+- SourceOS browser surfaces: product identity invariants, helper topology, hermetic app launch, parser/media worker receipts, and local incident bundles.
+- TurtleTerm / developer runtime: developer-mode scope, tty/session provenance, command-hash ledger, privileged-action receipts, and toolchain environment manifests.
+- SocioSphere dashboarding: operator cards for process, policy, trust, sync, repair, incident, wake, identity, and narrative events.
 - DeliveryExcellence stack: estate-wide health scoring, signal-to-noise metrics, SLOs, release readiness, and regression tracking.
 
 ## First implementation target
 
 The first implementation should produce and validate the golden examples, then expose `health snapshot`, `health explain`, `repair plan`, `events explain`, `events coalesce`, and `events verify` without destructive `repair apply`.
+
+The control-plane extension adds one immediate next target: turn `tools/validate_control_plane_examples.py` into a CI gate, then replace the bootstrap checks with full JSON Schema validation once a dependency policy is selected.