Add runtime observability and capability governance contracts

CHANGELOG.md

@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- Runtime observability and capability governance contracts: `CapabilityLedger`, `BrowserAutomationReceipt`, `GitWorkspaceState`, `OrphanEventReceipt`, and `RuntimeInstallReceipt` with canonical examples, validation wiring (`tools/validate_runtime_observability_examples.py`), a contract catalog, and ADR-0012.
 - Reasoning run contracts: `ReasoningRun`, `ReasoningEvent`, `ReasoningReceipt`, `ReasoningReplayPlan`, and `ReasoningBenchmark` with canonical examples and a contract-additions note for the Superconscious reference loop.
 - Agent Machine / Model Carry schemas: `SourceOSModelCarryRef`, `InferenceProvider`, `ModelResidency`, `PlacementFact`, and `AgentMachineReceipt` with canonical examples and a contract-additions placement note.
 - NLBoot object schemas: `NLBootPlan`, `ArtifactCacheRecord`, `BootProofRecord`, `AppleSiliconAdapterEvidence` with canonical examples and validation (`tools/validate_nlboot_examples.py`)

Makefile

@@ -1,6 +1,6 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples
 	@echo "OK: validate"
 
 validate-control-plane-examples:
@@ -18,3 +18,7 @@ validate-lattice-data-governai-examples:
 validate-ops-history-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_ops_history_examples.py
+
+validate-runtime-observability-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_runtime_observability_examples.py

docs/adr/0012-runtime-observability-capability-governance.md

@@ -0,0 +1,83 @@
+# ADR-0012: Runtime observability and capability governance contracts
+
+## Status
+
+Accepted for review.
+
+## Context
+
+SourceOS needs a shared contract layer for runtime capability state, browser assistance sessions, terminal workspace classification, session-event recovery, and runtime installation provenance.
+
+The motivating design issue is cross-plane drift: configuration, UI, runtime, server, plugin, policy, schema, and transport planes can disagree about whether a capability is available or effective. Without typed evidence records, downstream components can only infer state from logs.
+
+## Decision
+
+Add an additive runtime observability contract family:
+
+| Schema | Purpose |
+|---|---|
+| `CapabilityLedger` | Records effective capability state after cross-plane reconciliation. |
+| `BrowserAutomationReceipt` | Records visible, owned, scoped, policy-governed browser assistance sessions. |
+| `GitWorkspaceState` | Records typed Git/workspace classification before passive or requested Git operations. |
+| `OrphanEventReceipt` | Records recovery or quarantine for lifecycle events without immediate session attachment. |
+| `RuntimeInstallReceipt` | Records runtime manifest resolution, artifact verification, install lifecycle state, and compact log mode. |
+
+These contracts complement existing `SessionReceipt`, `AgentMachineReceipt`, `PolicyDecision`, `TelemetryEvent`, release, and provenance records.
+
+## Design constraints
+
+1. Effective capability state must be reconciled, not locally asserted.
+2. Browser assistance sessions must have visible ownership and revocation state.
+3. Terminal Git discovery must classify expected negative states without misleading warning noise.
+4. Lifecycle events without immediate session attachment must enter a typed recovery or quarantine path.
+5. Runtime installation must record manifest and artifact evidence while keeping ordinary logs compact.
+6. Examples must carry evidence references, policy-decision references, stable URN prefixes, and parseable timestamps.
+
+## Validation
+
+The repository adds `tools/validate_runtime_observability_examples.py` and wires it into `make validate` through `validate-runtime-observability-examples`.
+
+The validator checks schema conformance plus evidence-discipline invariants:
+
+- unique example IDs
+- required URN prefixes
+- non-empty `evidenceRefs`
+- required `policyDecisionRef`
+- timestamp parseability
+- no raw path storage in `GitWorkspaceState`
+- browser-session timestamp ordering
+- orphan-event recovery/quarantine consistency
+- compact runtime-install log mode in the canonical example
+
+## Downstream ownership
+
+| Downstream repo | Contract responsibility |
+|---|---|
+| `SourceOS-Linux/sourceos-shell` | Emit and surface `CapabilityLedger` entries. |
+| `SourceOS-Linux/BearBrowser` | Emit `BrowserAutomationReceipt` entries and expose visible session controls. |
+| `SourceOS-Linux/agent-term` | Emit `GitWorkspaceState` entries and enforce severity discipline. |
+| `SocioProphet/sociosphere` | Emit `OrphanEventReceipt` entries and implement event recovery/quarantine. |
+| Agent Machine / runtime installer lane | Emit `RuntimeInstallReceipt` entries. |
+
+## Consequences
+
+Positive:
+
+- Makes capability drift detectable and reviewable.
+- Gives downstream repos concrete schema targets.
+- Improves log quality by using compact receipt references.
+- Provides a path for cross-repo validation before downstream runtime implementation.
+
+Costs:
+
+- Adds five new schemas and examples.
+- Requires downstream emitters and validators to adopt the contract family.
+- Requires future schema evolution discipline as implementations mature.
+
+## Related issues
+
+- Parent spec: `SourceOS-Linux/sourceos-spec#99`
+- Browser implementation: `SourceOS-Linux/BearBrowser#25`
+- Terminal implementation: `SourceOS-Linux/agent-term#39`
+- Shell implementation: `SourceOS-Linux/sourceos-shell#12`
+- Sociosphere implementation: `SocioProphet/sociosphere#283`

docs/runtime-observability-contracts.md

@@ -0,0 +1,87 @@
+# Runtime observability and capability governance contracts
+
+## Purpose
+
+This contract family adds typed runtime evidence records for SourceOS desktop, browser, terminal, session, and runtime-install flows. The goal is to make effective capability state, assisted browser sessions, workspace classification, session-event recovery, and runtime installation provenance explicit and reviewable.
+
+The family is additive. It does not replace `SessionReceipt`, `AgentMachineReceipt`, `PolicyDecision`, `TelemetryEvent`, or release records. It adds focused evidence surfaces that downstream implementations can emit and validators can check.
+
+## Contract family
+
+| Schema | Type | URN prefix | Primary owner |
+|---|---|---|---|
+| `schemas/CapabilityLedger.json` | `CapabilityLedger` | `urn:srcos:capability-ledger:` | `SourceOS-Linux/sourceos-shell` |
+| `schemas/BrowserAutomationReceipt.json` | `BrowserAutomationReceipt` | `urn:srcos:receipt:browser-automation:` | `SourceOS-Linux/BearBrowser` |
+| `schemas/GitWorkspaceState.json` | `GitWorkspaceState` | `urn:srcos:git-workspace-state:` | `SourceOS-Linux/agent-term` |
+| `schemas/OrphanEventReceipt.json` | `OrphanEventReceipt` | `urn:srcos:receipt:orphan-event:` | `SocioProphet/sociosphere` |
+| `schemas/RuntimeInstallReceipt.json` | `RuntimeInstallReceipt` | `urn:srcos:receipt:runtime-install:` | Agent Machine / runtime installer lane |
+
+## Canonical examples
+
+| Example | Schema | Scenario |
+|---|---|---|
+| `examples/capabilityledger.json` | `CapabilityLedger` | Browser assistance capability resolves to `enabled` after cross-plane reconciliation. |
+| `examples/browserautomationreceipt.json` | `BrowserAutomationReceipt` | User-visible, revocable browser assistance session with policy decision and evidence references. |
+| `examples/gitworkspacestate.json` | `GitWorkspaceState` | Passive Git discovery classifies a non-repo directory as an expected negative state. |
+| `examples/orphaneventreceipt.json` | `OrphanEventReceipt` | Lifecycle event initially missing session attachment is recovered and linked to a session DAG node before TTL expiry. |
+| `examples/runtimeinstallreceipt.json` | `RuntimeInstallReceipt` | Runtime install resolves a manifest, verifies an artifact, emits compact receipt references, and records install success. |
+
+## Trace story
+
+```text
+AgentSession
+  -> CapabilityLedger
+       records effective capability truth after cross-plane reconciliation
+  -> BrowserAutomationReceipt
+       records owned, visible, scoped, policy-governed browser assistance
+  -> GitWorkspaceState
+       classifies workspace state before passive or requested Git operations
+  -> OrphanEventReceipt
+       records recovery or quarantine for lifecycle events without immediate session attachment
+  -> RuntimeInstallReceipt
+       records runtime manifest resolution, artifact verification, install state, and compact log mode
+```
+
+## Design requirements
+
+1. A feature becomes effective only after the capability ledger records a reconciled state.
+2. Browser assistance sessions must be visible, owned, scoped, policy-governed, evidence-backed, and revocable.
+3. Git discovery must classify workspace state before issuing user-facing remediation.
+4. Lifecycle events without immediate session attachment must enter recovery or quarantine.
+5. Runtime install logs should emit compact receipt references by default; full manifests belong in evidence bundles.
+6. Examples must include non-empty `evidenceRefs`, `policyDecisionRef`, parseable timestamps, and stable URN prefixes.
+
+## Validation
+
+The `validate-runtime-observability-examples` make target runs `tools/validate_runtime_observability_examples.py`. It validates schema conformance plus evidence-discipline invariants:
+
+- unique example IDs
+- required URN prefixes
+- non-empty `evidenceRefs`
+- required `policyDecisionRef`
+- parseable timestamps
+- no raw path storage in `GitWorkspaceState`
+- browser session timestamp ordering
+- orphan-event recovery/quarantine consistency
+- compact runtime-install log mode in the canonical example
+
+```bash
+make validate-runtime-observability-examples
+```
+
+## Downstream rollout order
+
+1. Merge the schema/example/validation tranche in `SourceOS-Linux/sourceos-spec`.
+2. Implement `BrowserAutomationReceipt` emission and visible session controls in `SourceOS-Linux/BearBrowser`.
+3. Implement `GitWorkspaceState` classifier and severity discipline in `SourceOS-Linux/agent-term`.
+4. Implement `CapabilityLedger` reconciliation and surface display in `SourceOS-Linux/sourceos-shell`.
+5. Implement `OrphanEventReceipt` queue/recovery/quarantine in `SocioProphet/sociosphere`.
+6. Implement `RuntimeInstallReceipt` emission in the Agent Machine / runtime installer lane.
+
+## Related issues
+
+- Parent spec: `SourceOS-Linux/sourceos-spec#99`
+- Browser implementation: `SourceOS-Linux/BearBrowser#25`
+- Terminal implementation: `SourceOS-Linux/agent-term#39`
+- Shell implementation: `SourceOS-Linux/sourceos-shell#12`
+- Sociosphere implementation: `SocioProphet/sociosphere#283`

examples/browserautomationreceipt.json

@@ -0,0 +1,32 @@
+{
+  "id": "urn:srcos:receipt:browser-automation:runtime-observability-0001",
+  "type": "BrowserAutomationReceipt",
+  "specVersion": "0.1.0",
+  "sessionRef": "urn:srcos:session:runtime-observability-demo-0001",
+  "capabilityLedgerRef": "urn:srcos:capability-ledger:runtime-observability-0001",
+  "ownerRef": "urn:srcos:agent:bearbrowser-demo-agent",
+  "transport": "native_pipe",
+  "permissionScope": ["read_page", "activate_control", "enter_text", "navigate"],
+  "origin": "workspace",
+  "controlledScope": {
+    "windowRef": "urn:srcos:browser-window:demo-0001",
+    "tabRef": "urn:srcos:browser-tab:demo-0001",
+    "urlOrigin": "https://example.invalid",
+    "workspaceRef": "urn:srcos:workspace:runtime-observability-demo"
+  },
+  "userVisible": true,
+  "revocable": true,
+  "startedAt": "2026-05-06T04:31:00Z",
+  "revokedAt": null,
+  "terminalState": "active",
+  "causalRefs": [
+    "urn:srcos:capability-ledger:runtime-observability-0001",
+    "urn:srcos:event:browser-automation-started-0001"
+  ],
+  "policyDecisionRef": "urn:srcos:decision:runtime-observability-policy-0001",
+  "evidenceRefs": [
+    "urn:srcos:evidence:browser-automation-session-visible-0001",
+    "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+  ],
+  "capturedAt": "2026-05-06T04:31:05Z"
+}

examples/capabilityledger.json

@@ -0,0 +1,21 @@
+{
+  "id": "urn:srcos:capability-ledger:runtime-observability-0001",
+  "type": "CapabilityLedger",
+  "specVersion": "0.1.0",
+  "capabilityRef": "urn:srcos:capability:browser-automation@0.1.0",
+  "sessionRef": "urn:srcos:session:runtime-observability-demo-0001",
+  "agentMachineReceiptRef": "urn:srcos:agent-machine-receipt:runtime-probe-0001",
+  "declaredBy": ["config", "ui"],
+  "negotiatedBy": ["runtime", "server", "plugin", "policy", "schema", "transport"],
+  "effectiveState": "enabled",
+  "stateReason": "All planes agreed on the requested browser automation capability under policy.",
+  "ownerRefs": ["urn:srcos:agent:bearbrowser-demo-agent"],
+  "conflictRefs": [],
+  "causalRefs": ["urn:srcos:event:runtime-capability-negotiation-0001"],
+  "policyDecisionRef": "urn:srcos:decision:runtime-observability-policy-0001",
+  "evidenceRefs": [
+    "urn:srcos:evidence:runtime-observability-capability-handshake-0001",
+    "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+  ],
+  "capturedAt": "2026-05-06T04:30:00Z"
+}

examples/gitworkspacestate.json

@@ -0,0 +1,39 @@
+{
+  "id": "urn:srcos:git-workspace-state:runtime-observability-0001",
+  "type": "GitWorkspaceState",
+  "specVersion": "0.1.0",
+  "sessionRef": "urn:srcos:session:runtime-observability-demo-0001",
+  "capabilityLedgerRef": "urn:srcos:capability-ledger:runtime-observability-0001",
+  "agentMachineReceiptRef": "urn:srcos:agent-machine-receipt:runtime-probe-0001",
+  "workspaceRef": "urn:srcos:workspace:runtime-observability-demo",
+  "state": "not_a_repo",
+  "severity": "info",
+  "operation": "passive_discovery",
+  "actionability": "none",
+  "pathEvidence": {
+    "pathDigest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "redactedPathHint": "~/Documents/New project",
+    "redaction": "user_home_redacted",
+    "rawPathStored": false
+  },
+  "gitFacts": {
+    "branch": null,
+    "headSha": null,
+    "remoteState": "not_applicable",
+    "worktreeRootDigest": null,
+    "gitDirDigest": null,
+    "failureReason": "Passive discovery classified the directory as not_a_repo; no warning is required.",
+    "commandClass": "rev_parse"
+  },
+  "expectedNegativeState": true,
+  "causalRefs": [
+    "urn:srcos:event:git-passive-discovery-0001",
+    "urn:srcos:capability-ledger:runtime-observability-0001"
+  ],
+  "policyDecisionRef": "urn:srcos:decision:runtime-observability-policy-0001",
+  "evidenceRefs": [
+    "urn:srcos:evidence:git-workspace-passive-discovery-0001",
+    "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+  ],
+  "capturedAt": "2026-05-06T04:32:00Z"
+}

examples/orphaneventreceipt.json

@@ -0,0 +1,39 @@
+{
+  "id": "urn:srcos:receipt:orphan-event:runtime-observability-0001",
+  "type": "OrphanEventReceipt",
+  "specVersion": "0.1.0",
+  "eventRef": "urn:srcos:event:turn-started-before-session-registry-0001",
+  "eventClass": "agent_lifecycle",
+  "observedAt": "2026-05-06T04:33:00Z",
+  "rawEventDigest": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+  "sessionResolution": {
+    "state": "recovered",
+    "candidateSessionRefs": [
+      "urn:srcos:session:runtime-observability-demo-0001"
+    ],
+    "recoveredSessionRef": "urn:srcos:session:runtime-observability-demo-0001",
+    "recoveredDagNodeRef": "urn:srcos:session-dag-node:runtime-observability-demo-turn-started-0001",
+    "reconciledAt": "2026-05-06T04:33:10Z",
+    "quarantinedAt": null
+  },
+  "ttl": {
+    "expiresAt": "2026-05-06T04:38:00Z",
+    "expired": false
+  },
+  "correlationKeys": {
+    "conversationId": "runtime-observability-demo-conversation",
+    "parentId": null,
+    "workspaceRef": "urn:srcos:workspace:runtime-observability-demo",
+    "taskRef": "urn:srcos:task:runtime-observability-demo-0001"
+  },
+  "causalRefs": [
+    "urn:srcos:event:runtime-session-bootstrap-0001",
+    "urn:srcos:capability-ledger:runtime-observability-0001"
+  ],
+  "policyDecisionRef": "urn:srcos:decision:runtime-observability-policy-0001",
+  "evidenceRefs": [
+    "urn:srcos:evidence:orphan-event-reconciliation-0001",
+    "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
+  ],
+  "capturedAt": "2026-05-06T04:33:15Z"
+}

examples/runtimeinstallreceipt.json

@@ -0,0 +1,43 @@
+{
+  "id": "urn:srcos:receipt:runtime-install:runtime-observability-0001",
+  "type": "RuntimeInstallReceipt",
+  "specVersion": "0.1.0",
+  "sessionRef": "urn:srcos:session:runtime-observability-demo-0001",
+  "capabilityLedgerRef": "urn:srcos:capability-ledger:runtime-observability-0001",
+  "agentMachineReceiptRef": "urn:srcos:agent-machine-receipt:runtime-probe-0001",
+  "runtimeRef": "urn:srcos:runtime:sourceos-agent-runtime@0.1.0",
+  "runtimeName": "sourceos-agent-runtime",
+  "runtimeVersion": "0.1.0",
+  "targetRef": "urn:srcos:target:developer-workstation-demo-0001",
+  "platform": "linux-x64",
+  "installState": "installed",
+  "manifest": {
+    "manifestRef": "urn:srcos:artifact:runtime-manifest-sourceos-agent-runtime-0.1.0",
+    "manifestDigest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+    "bundleFormatVersion": "1",
+    "resolvedAt": "2026-05-06T04:34:00Z"
+  },
+  "artifacts": [
+    {
+      "artifactRef": "urn:srcos:artifact:sourceos-agent-runtime-linux-x64-0.1.0.tar.xz",
+      "digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+      "sizeBytes": 1048576,
+      "verificationState": "verified"
+    }
+  ],
+  "rollbackRef": null,
+  "failureReason": null,
+  "logMode": "compact_receipt_ref",
+  "causalRefs": [
+    "urn:srcos:event:runtime-install-requested-0001",
+    "urn:srcos:capability-ledger:runtime-observability-0001"
+  ],
+  "policyDecisionRef": "urn:srcos:decision:runtime-observability-policy-0001",
+  "evidenceRefs": [
+    "urn:srcos:evidence:runtime-install-verified-0001",
+    "sha256:3333333333333333333333333333333333333333333333333333333333333333"
+  ],
+  "startedAt": "2026-05-06T04:34:00Z",
+  "finishedAt": "2026-05-06T04:35:00Z",
+  "capturedAt": "2026-05-06T04:35:05Z"
+}