Implement RuntimeInstallReceipt emission for runtime install/update flows

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: validate validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-release-bundle validate-sourceos-projections validate-package validate-cli validate-formula doctor probe
+.PHONY: validate validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-release-bundle validate-sourceos-projections validate-package validate-cli validate-formula validate-runtime-install-receipts doctor probe
 
 PYTHON ?= python3
 RUBY ?= ruby
@@ -20,7 +20,7 @@ DECIDED_AT := 2026-05-04T12:51:00Z
 PYCLI := PYTHONPATH=src $(PYTHON) -m agent_machine.cli
 PYMOD := PYTHONPATH=src $(PYTHON) -m
 
-validate: validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-release-bundle validate-sourceos-projections validate-package validate-cli validate-formula
+validate: validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-release-bundle validate-sourceos-projections validate-package validate-cli validate-formula validate-runtime-install-receipts
 
 validate-json:
 	$(PYTHON) scripts/validate-json.py
@@ -86,6 +86,9 @@ validate-cli:
 validate-formula:
 	$(RUBY) -c $(FORMULA)
 
+validate-runtime-install-receipts:
+	$(PYTHON) scripts/validate-runtime-install-receipts.py
+
 doctor:
 	$(BOOTSTRAP_CLI) doctor --format json
 

contracts/runtime-install-receipt.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RuntimeInstallReceipt.json",
+  "title": "RuntimeInstallReceipt",
+  "description": "Receipt for runtime installation, update, rollback, denial, or partial install flows with artifact verification, compact log references, policy decision linkage, and evidence references.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "sessionRef", "capabilityLedgerRef", "runtimeRef", "targetRef", "platform", "installState", "manifest", "artifacts", "logMode", "policyDecisionRef", "evidenceRefs", "startedAt", "capturedAt"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:receipt:runtime-install:" },
+    "type": { "const": "RuntimeInstallReceipt" },
+    "specVersion": { "type": "string" },
+    "sessionRef": { "type": "string", "pattern": "^urn:srcos:session:" },
+    "capabilityLedgerRef": { "type": "string", "pattern": "^urn:srcos:capability-ledger:" },
+    "agentMachineReceiptRef": { "type": ["string", "null"], "pattern": "^urn:srcos:agent-machine-receipt:" },
+    "runtimeRef": { "type": "string", "pattern": "^urn:srcos:runtime:" },
+    "runtimeName": { "type": ["string", "null"] },
+    "runtimeVersion": { "type": ["string", "null"] },
+    "targetRef": { "type": "string", "pattern": "^urn:srcos:target:" },
+    "platform": { "type": "string", "enum": ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64", "win32-x64"] },
+    "installState": { "type": "string", "enum": ["requested", "manifest_resolved", "artifact_verified", "installing", "installed", "failed", "rolled_back", "partial", "denied", "deferred"] },
+    "manifest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["manifestRef", "manifestDigest", "resolvedAt"],
+      "properties": {
+        "manifestRef": { "type": "string" },
+        "manifestDigest": { "type": "string", "pattern": "^sha256:[a-fA-F0-9]{64}$" },
+        "bundleFormatVersion": { "type": ["string", "integer", "null"] },
+        "resolvedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["artifactRef", "digest", "verificationState"],
+        "properties": {
+          "artifactRef": { "type": "string" },
+          "digest": { "type": "string", "pattern": "^sha256:[a-fA-F0-9]{64}$" },
+          "sizeBytes": { "type": ["integer", "null"], "minimum": 0 },
+          "verificationState": { "type": "string", "enum": ["not_checked", "verified", "failed", "skipped"] }
+        }
+      }
+    },
+    "rollbackRef": { "type": ["string", "null"] },
+    "failureReason": { "type": ["string", "null"] },
+    "logMode": { "type": "string", "enum": ["compact_receipt_ref", "full_debug_redacted"] },
+    "causalRefs": { "type": "array", "items": { "type": "string" } },
+    "policyDecisionRef": { "type": "string", "pattern": "^urn:srcos:decision:" },
+    "evidenceRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": ["string", "null"], "format": "date-time" },
+    "capturedAt": { "type": "string", "format": "date-time" }
+  }
+}

examples/runtime-install-receipt.deferred.json

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

examples/runtime-install-receipt.denied.json

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

examples/runtime-install-receipt.failed.json

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

examples/runtime-install-receipt.installed.json

@@ -0,0 +1,43 @@
+{
+  "id": "urn:srcos:receipt:runtime-install:agent-runtime-installed-0001",
+  "type": "RuntimeInstallReceipt",
+  "specVersion": "0.1.0",
+  "sessionRef": "urn:srcos:session:runtime-install-demo-0001",
+  "capabilityLedgerRef": "urn:srcos:capability-ledger:runtime-install-demo-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-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-install-demo-0001"
+  ],
+  "policyDecisionRef": "urn:srcos:decision:runtime-install-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"
+}

examples/runtime-install-receipt.partial.json

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

examples/runtime-install-receipt.rolled_back.json

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