SourceOS-Linux · mdheller · Aug 3, 2026 · Aug 3, 2026
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: build test validate validate-portable-ai validate-model-carry-boundary validate-model-carry-manifest dist release-dry-run clean
+.PHONY: build test validate validate-portable-ai validate-model-carry-boundary validate-model-carry-manifest validate-confidential-compute-escalation dist release-dry-run clean
 
 BIN := sourceos-ai
 DIST_DIR := dist
@@ -26,7 +26,10 @@ validate-model-carry-boundary:
 validate-model-carry-manifest:
 	python3 tools/validate_model_carry_manifests.py
 
-validate: build validate-portable-ai validate-model-carry-boundary validate-model-carry-manifest
+validate-confidential-compute-escalation:
+	python3 tools/validate_confidential_compute_escalations.py
+
+validate: build validate-portable-ai validate-model-carry-boundary validate-model-carry-manifest validate-confidential-compute-escalation
 	python3 tools/validate_carry_refs.py
 	bin/$(BIN) carry validate --refs examples
 	bin/$(BIN) carry list --refs examples

diff --git a/contracts/confidential-compute-escalation.schema.json b/contracts/confidential-compute-escalation.schema.json
@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/model-carry/confidential-compute-escalation.schema.json",
+  "title": "SourceOS Confidential Compute Escalation",
+  "description": "The tiered confidential-compute escalation contract (SourceOS-vs-Apple ModelCarry spec, section 5.2). Model execution escalates to a higher confidential-compute tier (e.g. on-device -> sealed enclave -> attested TEE) based on the data-residency / sensitivity class of the inputs. The escalation decision is governed and receipted: a request whose sensitivity class requires a minimum tier MUST run at or above that tier, and any tier that requires attestation MUST carry an attestation reference. Fail-closed is the core invariant: a request run below its required minimum tier is rejected, never silently downgraded. SHA-256 is the authoritative receipt-hash algorithm (FIPS 180-4).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "escalationId",
+    "invariants",
+    "computeTiers",
+    "sensitivityClassMap",
+    "decision"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "v0.1" },
+    "kind": { "const": "ConfidentialComputeEscalation" },
+    "escalationId": {
+      "type": "string",
+      "pattern": "^urn:srcos:cc-escalation:",
+      "description": "SourceOS confidential-compute-escalation URN."
+    },
+    "invariants": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "belowMinimumTierIsRejected",
+        "unattestedTierRequiringAttestationIsRejected",
+        "tierOrderingMustBeMonotonic",
+        "receiptHashAlgorithm"
+      ],
+      "properties": {
+        "belowMinimumTierIsRejected": {
+          "const": true,
+          "description": "Fail-closed core invariant. A request run at a tier below the minimum required by its sensitivity class MUST be rejected, never silently downgraded to a weaker tier."
+        },
+        "unattestedTierRequiringAttestationIsRejected": {
+          "const": true,
+          "description": "A decision that selects a tier which requires attestation MUST carry a non-null attestationRef; a missing attestation is a hard stop."
+        },
+        "tierOrderingMustBeMonotonic": {
+          "const": true,
+          "description": "computeTiers MUST be ordered by strictly increasing rank. A non-monotonic ordering is non-conformant: the tier lattice must be totally ordered for a minimum-tier comparison to be meaningful."
+        },
+        "receiptHashAlgorithm": {
+          "const": "sha256",
+          "description": "Authoritative receipt-hash algorithm. SHA-256 (FIPS 180-4) only."
+        }
+      }
+    },
+    "computeTiers": {
+      "type": "array",
+      "minItems": 2,
+      "description": "The ordered confidential-compute tier lattice, weakest first. rank is strictly increasing in array order.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["tierRef", "tierClass", "rank", "requiresAttestation", "attestationKind"],
+        "properties": {
+          "tierRef": { "type": "string", "pattern": "^urn:srcos:cc-tier:" },
+          "tierClass": {
+            "type": "string",
+            "enum": ["on_device", "sealed_enclave", "attested_tee"],
+            "description": "The confidential-compute posture of this tier."
+          },
+          "rank": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Position in the tier lattice. Higher rank = stronger confidential-compute guarantee. Strictly increasing across computeTiers in array order."
+          },
+          "requiresAttestation": {
+            "type": "boolean",
+            "description": "Whether selecting this tier requires a non-null attestationRef in the decision."
+          },
+          "attestationKind": {
+            "type": ["string", "null"],
+            "enum": ["none", "enclave_measurement", "tee_remote_attestation", null],
+            "description": "The kind of attestation this tier's guarantee is anchored to. null/none for tiers that require no attestation."
+          }
+        }
+      }
+    },
+    "sensitivityClassMap": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Maps each data-sensitivity / residency class to the minimum confidential-compute tier permitted to process it.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sensitivityClass", "dataResidencyClass", "minimumTierRef"],
+        "properties": {
+          "sensitivityClass": {
+            "type": "string",
+            "enum": ["public", "internal", "confidential", "restricted"],
+            "description": "Sensitivity class of the inputs."
+          },
+          "dataResidencyClass": {
+            "type": "string",
+            "enum": ["on_device_only", "sealed_compute_only", "attested_compute_only"],
+            "description": "Residency posture required for this class, aligned with the estate InferenceReceipt dataResidencyClass vocabulary."
+          },
+          "minimumTierRef": {
+            "type": "string",
+            "pattern": "^urn:srcos:cc-tier:",
+            "description": "tierRef of the weakest tier permitted to process this class. A request in this class run below this tier is rejected."
+          }
+        }
+      }
+    },
+    "decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requestSensitivityClass",
+        "chosenTierRef",
+        "reason",
+        "attestationRef",
+        "receiptSha256"
+      ],
+      "description": "The governed, receipted escalation decision record.",
+      "properties": {
+        "requestSensitivityClass": {
+          "type": "string",
+          "enum": ["public", "internal", "confidential", "restricted"],
+          "description": "Sensitivity class of the request being routed. MUST be present in sensitivityClassMap."
+        },
+        "chosenTierRef": {
+          "type": "string",
+          "pattern": "^urn:srcos:cc-tier:",
+          "description": "tierRef of the tier the request was actually executed on."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable justification for the escalation decision, propagated as first-class provenance."
+        },
+        "attestationRef": {
+          "type": ["string", "null"],
+          "description": "Reference to the attestation evidence for the chosen tier. MUST be non-null when the chosen tier requiresAttestation."
+        },
+        "receiptSha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA-256 (FIPS 180-4) of the decision receipt. Content-addressed; never null."
+        }
+      }
+    },
+    "notes": { "type": "string" }
+  }
+}
diff --git a/docs/confidential-compute-escalation.md b/docs/confidential-compute-escalation.md
@@ -0,0 +1,64 @@
+# Confidential Compute Escalation
+
+The confidential-compute escalation contract governs how model execution escalates
+to a higher confidential-compute tier based on the data-residency / sensitivity
+class of the inputs. It is the SourceOS analogue of Apple's on-device to Private
+Cloud Compute boundary (SourceOS-vs-Apple ModelCarry spec, section 5.2): where does
+an over-scale or high-sensitivity request go, and under what attested-compute
+guarantee?
+
+- Contract: `contracts/confidential-compute-escalation.schema.json`
+- Validator: `tools/validate_confidential_compute_escalations.py` (`make validate-confidential-compute-escalation`)
+- Example: `examples/confidential-compute-escalation.attested-tee.json`
+
+## The tier lattice
+
+`computeTiers` is an ordered, totally ordered lattice of confidential-compute
+postures, weakest first:
+
+| tierClass | Guarantee | Attestation |
+|---|---|---|
+| `on_device` | Execution stays on the workstation. | none |
+| `sealed_enclave` | Execution in a sealed enclave. | `enclave_measurement` |
+| `attested_tee` | Execution in a remotely attested TEE. | `tee_remote_attestation` |
+
+Each request carries a sensitivity class (`public` / `internal` / `confidential` /
+`restricted`) and a `dataResidencyClass` aligned with the estate InferenceReceipt
+residency vocabulary (`on_device_only` / `sealed_compute_only` /
+`attested_compute_only`). `sensitivityClassMap` binds each class to the weakest
+tier permitted to process it. The `decision` records the tier actually chosen, the
+reason, the attestation reference, and a SHA-256 receipt -- escalation is a
+first-class, receipted provenance record, not an implicit routing side effect.
+
+## Invariants (enforced by the validator)
+
+| Invariant | Rule |
+|---|---|
+| Fail-closed | A request whose class requires a minimum tier and is run **below** that tier is **rejected**, never silently downgraded. This is the core invariant. |
+| Attestation required | A chosen tier with `requiresAttestation: true` MUST carry a non-null `attestationRef`; a missing attestation is a hard stop. |
+| Totally ordered lattice | `computeTiers` ranks are strictly increasing in array order; a non-monotonic ordering is rejected. |
+| Declared class | The request's sensitivity class MUST appear in `sensitivityClassMap`; an unknown class is rejected, never defaulted to the weakest tier. |
+| Authoritative receipt hash | `invariants.receiptHashAlgorithm` is `sha256` (FIPS 180-4); `decision.receiptSha256` is a SHA-256 digest. |
+
+## Teeth (negative fixtures)
+
+| Fixture | Rejected because |
+|---|---|
+| `confidential-compute-escalation.below-minimum-tier.invalid.json` | A `restricted`-class request (minimum: attested TEE, rank 2) was run on-device (rank 0). Fail-closed. |
+| `confidential-compute-escalation.missing-attestation.invalid.json` | The chosen attested TEE tier requires attestation, but the decision has no `attestationRef`. |
+| `confidential-compute-escalation.non-monotonic-tiers.invalid.json` | The tier lattice is not strictly monotonic by rank. |
+| `confidential-compute-escalation.unknown-class.invalid.json` | The request's class is not declared in `sensitivityClassMap`. |
+
+## Carry boundary
+
+This contract is a decision/verification object. It does not perform live TEE
+attestation, verify real enclave measurements, provision compute, or authorize
+runtime execution. It proves that an escalation decision is well formed and
+fail-closed before it is acted on.
+
+## Not yet in scope (tracked as follow-up)
+
+- Live TEE attestation verification (real enclave measurement / remote-attestation
+  quote validation) rather than a structural attestation reference.
+- Governed staged pre-load plus atomic swap under a resource governor
+  (`sourceos-model-carry#21`).
diff --git a/examples/confidential-compute-escalation.attested-tee.json b/examples/confidential-compute-escalation.attested-tee.json
@@ -0,0 +1,64 @@
+{
+  "schemaVersion": "v0.1",
+  "kind": "ConfidentialComputeEscalation",
+  "escalationId": "urn:srcos:cc-escalation:office-assist-confidential",
+  "invariants": {
+    "belowMinimumTierIsRejected": true,
+    "unattestedTierRequiringAttestationIsRejected": true,
+    "tierOrderingMustBeMonotonic": true,
+    "receiptHashAlgorithm": "sha256"
+  },
+  "computeTiers": [
+    {
+      "tierRef": "urn:srcos:cc-tier:on-device",
+      "tierClass": "on_device",
+      "rank": 0,
+      "requiresAttestation": false,
+      "attestationKind": "none"
+    },
+    {
+      "tierRef": "urn:srcos:cc-tier:sealed-enclave",
+      "tierClass": "sealed_enclave",
+      "rank": 1,
+      "requiresAttestation": true,
+      "attestationKind": "enclave_measurement"
+    },
+    {
+      "tierRef": "urn:srcos:cc-tier:attested-tee",
+      "tierClass": "attested_tee",
+      "rank": 2,
+      "requiresAttestation": true,
+      "attestationKind": "tee_remote_attestation"
+    }
+  ],
+  "sensitivityClassMap": [
+    {
+      "sensitivityClass": "public",
+      "dataResidencyClass": "on_device_only",
+      "minimumTierRef": "urn:srcos:cc-tier:on-device"
+    },
+    {
+      "sensitivityClass": "internal",
+      "dataResidencyClass": "on_device_only",
+      "minimumTierRef": "urn:srcos:cc-tier:on-device"
+    },
+    {
+      "sensitivityClass": "confidential",
+      "dataResidencyClass": "sealed_compute_only",
+      "minimumTierRef": "urn:srcos:cc-tier:sealed-enclave"
+    },
+    {
+      "sensitivityClass": "restricted",
+      "dataResidencyClass": "attested_compute_only",
+      "minimumTierRef": "urn:srcos:cc-tier:attested-tee"
+    }
+  ],
+  "decision": {
+    "requestSensitivityClass": "restricted",
+    "chosenTierRef": "urn:srcos:cc-tier:attested-tee",
+    "reason": "Request carries restricted-class inputs (attested_compute_only residency); task exceeds on-device capability, escalated to the attested TEE tier which satisfies the minimum required tier.",
+    "attestationRef": "urn:srcos:attestation:tee:2026-08-03T00:00:00Z:a1b2c3",
+    "receiptSha256": "a05ede635e9b4a5fdc86444c5207d9d0cddd626d93e138311d6aa033bd8065ea"
+  },
+  "notes": "Valid: a restricted-class request run at the attested TEE tier, at or above its required minimum, with an attestation reference for a tier that requires one. Escalation decision, reason, and receipt are first-class provenance."
+}
diff --git a/examples/confidential-compute-escalation.below-minimum-tier.invalid.json b/examples/confidential-compute-escalation.below-minimum-tier.invalid.json
@@ -0,0 +1,54 @@
+{
+  "schemaVersion": "v0.1",
+  "kind": "ConfidentialComputeEscalation",
+  "escalationId": "urn:srcos:cc-escalation:below-minimum-tier",
+  "invariants": {
+    "belowMinimumTierIsRejected": true,
+    "unattestedTierRequiringAttestationIsRejected": true,
+    "tierOrderingMustBeMonotonic": true,
+    "receiptHashAlgorithm": "sha256"
+  },
+  "computeTiers": [
+    {
+      "tierRef": "urn:srcos:cc-tier:on-device",
+      "tierClass": "on_device",
+      "rank": 0,
+      "requiresAttestation": false,
+      "attestationKind": "none"
+    },
+    {
+      "tierRef": "urn:srcos:cc-tier:sealed-enclave",
+      "tierClass": "sealed_enclave",
+      "rank": 1,
+      "requiresAttestation": true,
+      "attestationKind": "enclave_measurement"
+    },
+    {
+      "tierRef": "urn:srcos:cc-tier:attested-tee",
+      "tierClass": "attested_tee",
+      "rank": 2,
+      "requiresAttestation": true,
+      "attestationKind": "tee_remote_attestation"
+    }
+  ],
+  "sensitivityClassMap": [
+    {
+      "sensitivityClass": "public",
+      "dataResidencyClass": "on_device_only",
+      "minimumTierRef": "urn:srcos:cc-tier:on-device"
+    },
+    {
+      "sensitivityClass": "restricted",
+      "dataResidencyClass": "attested_compute_only",
+      "minimumTierRef": "urn:srcos:cc-tier:attested-tee"
+    }
+  ],
+  "decision": {
+    "requestSensitivityClass": "restricted",
+    "chosenTierRef": "urn:srcos:cc-tier:on-device",
+    "reason": "Routed restricted-class inputs to the on-device tier to save latency.",
+    "attestationRef": null,
+    "receiptSha256": "f86705ca895b2eaa669151564dd1506b3c897df0e9f69b566be9f11c80a7d7b6"
+  },
+  "notes": "INVALID (core teeth): a restricted-class request whose required minimum tier is the attested TEE (rank 2) was run at the on-device tier (rank 0). Fail-closed: running below the required minimum tier is REJECTED, never silently downgraded."
+}