feat: add boot storage and staged deployment contracts

examples/bootsurface.json

@@ -0,0 +1,32 @@
+{
+  "id": "urn:srcos:boot-surface:fedora-asahi-m2-main",
+  "specVersion": "2.1.0-alpha.1",
+  "hostRef": "urn:srcos:asset:fedora-asahi-m2",
+  "platform": "apple-silicon-asahi",
+  "esp": {
+    "device": "/dev/nvme0n1p1",
+    "mountPoint": "/boot/efi",
+    "label": "EFI-SOURCEOS",
+    "pairedInstanceId": "asahi-fedora-instance-a"
+  },
+  "bootChain": ["m1n1", "u-boot", "efi-bootaa64", "grub", "linux-kernel"],
+  "entries": [
+    {
+      "name": "fedora-asahi-main",
+      "role": "main",
+      "path": "EFI/BOOT/BOOTAA64.EFI",
+      "active": true
+    },
+    {
+      "name": "fedora-asahi-recovery",
+      "role": "recovery",
+      "path": "EFI/BOOT/BOOTAA64-RECOVERY.EFI",
+      "active": false
+    }
+  ],
+  "recovery": {
+    "knownGoodRef": "sha256:known-good-boot-assets-001",
+    "lastVerifiedAt": "2026-04-15T16:00:00Z",
+    "notes": "Boot-critical assets verified before staged substrate promotion."
+  }
+}

examples/stageddeployment.json

@@ -0,0 +1,40 @@
+{
+  "id": "urn:srcos:staged-deployment:fedora-asahi-m2-2026-04-15-a",
+  "specVersion": "2.1.0-alpha.1",
+  "hostRef": "urn:srcos:asset:fedora-asahi-m2",
+  "targetRef": "urn:srcos:dataset:sourceos-substrate-profile-fedora-asahi-m2",
+  "bootSurfaceRef": "urn:srcos:boot-surface:fedora-asahi-m2-main",
+  "storageSurfaceRef": "urn:srcos:storage-surface:fedora-asahi-m2-main",
+  "stageLane": {
+    "environment": "vm",
+    "candidateRef": "github:SourceOS/substrate#asahi-fedora-m2",
+    "mounts": [
+      {
+        "source": "/srv/sourceos/config",
+        "target": "/mnt/config",
+        "readOnly": true
+      },
+      {
+        "source": "/srv/sourceos/state/hn-tick",
+        "target": "/mnt/state/hn-tick",
+        "readOnly": false
+      },
+      {
+        "source": "/srv/sourceos/evidence",
+        "target": "/mnt/evidence",
+        "readOnly": false
+      }
+    ],
+    "smokeRef": "agentplane:bundles/sourceos-asahi-stage/smoke.sh"
+  },
+  "promotionPolicy": {
+    "requiresStagePass": true,
+    "requiresHumanApproval": true,
+    "rollbackStrategy": "multi_layer"
+  },
+  "evidence": {
+    "artifactDir": "/srv/sourceos/evidence/staged/2026-04-15-a",
+    "emit": ["stage", "promote", "rollback", "health"]
+  },
+  "status": "planned"
+}

examples/storagesurface.json

@@ -0,0 +1,50 @@
+{
+  "id": "urn:srcos:storage-surface:fedora-asahi-m2-main",
+  "specVersion": "2.1.0-alpha.1",
+  "hostRef": "urn:srcos:asset:fedora-asahi-m2",
+  "filesystem": {
+    "rootFs": "btrfs",
+    "snapshotCapable": true,
+    "subvolumeModel": "@root,@home,@state,@logs",
+    "notes": "Host upgrade snapshots and stage/promotion snapshots are supported."
+  },
+  "volumes": [
+    {
+      "name": "rendered-config",
+      "class": "immutable_input",
+      "mountPoint": "/srv/sourceos/config",
+      "readOnly": true,
+      "snapshotPolicy": "none",
+      "backingStore": "host-path"
+    },
+    {
+      "name": "hn-tick-state",
+      "class": "mutable_state",
+      "mountPoint": "/srv/sourceos/state/hn-tick",
+      "readOnly": false,
+      "snapshotPolicy": "manual",
+      "backingStore": "btrfs-subvolume"
+    },
+    {
+      "name": "evidence-artifacts",
+      "class": "audit_evidence",
+      "mountPoint": "/srv/sourceos/evidence",
+      "readOnly": false,
+      "snapshotPolicy": "pre_post_promotion",
+      "backingStore": "btrfs-subvolume"
+    },
+    {
+      "name": "substrate-sensitive",
+      "class": "substrate_sensitive",
+      "mountPoint": "/srv/sourceos/substrate",
+      "readOnly": false,
+      "snapshotPolicy": "pre_post_host_upgrade",
+      "backingStore": "btrfs-subvolume"
+    }
+  ],
+  "containerPolicy": {
+    "rootlessRequired": true,
+    "selinuxRelabelRequired": true,
+    "allowHostSensitiveMounts": false
+  }
+}

schemas/BootSurface.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/BootSurface.json",
+  "title": "BootSurface",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "specVersion",
+    "hostRef",
+    "platform",
+    "bootChain",
+    "recovery"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:boot-surface:[A-Za-z0-9._:-]+$"
+    },
+    "specVersion": {
+      "type": "string"
+    },
+    "hostRef": {
+      "type": "string"
+    },
+    "platform": {
+      "type": "string",
+      "enum": [
+        "apple-silicon-asahi",
+        "generic-uefi",
+        "generic-bios"
+      ]
+    },
+    "esp": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "device": { "type": "string" },
+        "mountPoint": { "type": "string" },
+        "label": { "type": "string" },
+        "pairedInstanceId": { "type": "string" }
+      }
+    },
+    "bootChain": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "m1n1",
+          "u-boot",
+          "efi-bootaa64",
+          "grub",
+          "systemd-boot",
+          "linux-kernel"
+        ]
+      }
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "role", "path"],
+        "properties": {
+          "name": { "type": "string" },
+          "role": {
+            "type": "string",
+            "enum": ["main", "recovery", "staging", "other"]
+          },
+          "path": { "type": "string" },
+          "active": { "type": "boolean" }
+        }
+      }
+    },
+    "recovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["knownGoodRef"],
+      "properties": {
+        "knownGoodRef": { "type": "string" },
+        "lastVerifiedAt": { "type": "string" },
+        "notes": { "type": "string" }
+      }
+    }
+  }
+}

schemas/StagedDeployment.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/StagedDeployment.json",
+  "title": "StagedDeployment",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "specVersion",
+    "hostRef",
+    "targetRef",
+    "stageLane",
+    "promotionPolicy",
+    "status"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:staged-deployment:[A-Za-z0-9._:-]+$"
+    },
+    "specVersion": { "type": "string" },
+    "hostRef": { "type": "string" },
+    "targetRef": { "type": "string" },
+    "bootSurfaceRef": { "type": "string" },
+    "storageSurfaceRef": { "type": "string" },
+    "stageLane": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["environment", "candidateRef"],
+      "properties": {
+        "environment": {
+          "type": "string",
+          "enum": ["vm", "container", "nspawn", "remote"]
+        },
+        "candidateRef": { "type": "string" },
+        "mounts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source", "target", "readOnly"],
+            "properties": {
+              "source": { "type": "string" },
+              "target": { "type": "string" },
+              "readOnly": { "type": "boolean" }
+            }
+          }
+        },
+        "smokeRef": { "type": "string" }
+      }
+    },
+    "promotionPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requiresStagePass", "rollbackStrategy"],
+      "properties": {
+        "requiresStagePass": { "type": "boolean" },
+        "requiresHumanApproval": { "type": "boolean" },
+        "rollbackStrategy": {
+          "type": "string",
+          "enum": ["generation", "image_digest", "snapshot", "multi_layer"]
+        }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "artifactDir": { "type": "string" },
+        "emit": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["stage", "promote", "rollback", "health"]
+          }
+        }
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": ["planned", "staged", "promoted", "rolled_back"]
+    }
+  }
+}

schemas/StorageSurface.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/StorageSurface.json",
+  "title": "StorageSurface",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "specVersion",
+    "hostRef",
+    "filesystem",
+    "volumes"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:storage-surface:[A-Za-z0-9._:-]+$"
+    },
+    "specVersion": { "type": "string" },
+    "hostRef": { "type": "string" },
+    "filesystem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rootFs", "snapshotCapable"],
+      "properties": {
+        "rootFs": { "type": "string" },
+        "snapshotCapable": { "type": "boolean" },
+        "subvolumeModel": { "type": "string" },
+        "notes": { "type": "string" }
+      }
+    },
+    "volumes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "class", "mountPoint", "readOnly", "snapshotPolicy"],
+        "properties": {
+          "name": { "type": "string" },
+          "class": {
+            "type": "string",
+            "enum": [
+              "immutable_input",
+              "mutable_state",
+              "audit_evidence",
+              "substrate_sensitive"
+            ]
+          },
+          "mountPoint": { "type": "string" },
+          "readOnly": { "type": "boolean" },
+          "snapshotPolicy": {
+            "type": "string",
+            "enum": [
+              "none",
+              "manual",
+              "pre_post_promotion",
+              "pre_post_host_upgrade"
+            ]
+          },
+          "backingStore": { "type": "string" }
+        }
+      }
+    },
+    "containerPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "rootlessRequired": { "type": "boolean" },
+        "selinuxRelabelRequired": { "type": "boolean" },
+        "allowHostSensitiveMounts": { "type": "boolean" }
+      }
+    }
+  }
+}