From 5425548d51b34aa9baee9ad3310cbbe4c9bf377a Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:10:18 -0400 Subject: [PATCH 1/7] feat(sourceos-spec): add BootSurface contract for substrate lanes --- schemas/BootSurface.json | 86 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 schemas/BootSurface.json diff --git a/schemas/BootSurface.json b/schemas/BootSurface.json new file mode 100644 index 0000000..125929e --- /dev/null +++ b/schemas/BootSurface.json @@ -0,0 +1,86 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "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" } + } + } + } +} From 56cc4b3d81b0ead4c46b28ab008c0fb73fe7b0e3 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:11:06 -0400 Subject: [PATCH 2/7] feat(sourceos-spec): add StorageSurface contract for substrate lanes --- schemas/StorageSurface.json | 74 +++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 schemas/StorageSurface.json diff --git a/schemas/StorageSurface.json b/schemas/StorageSurface.json new file mode 100644 index 0000000..ac721d7 --- /dev/null +++ b/schemas/StorageSurface.json @@ -0,0 +1,74 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "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" } + } + } + } +} From 44320b7527d4fe431bfbebd0acd5a6a9964f16a8 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:11:46 -0400 Subject: [PATCH 3/7] feat(sourceos-spec): add StagedDeployment contract for substrate lanes --- schemas/StagedDeployment.json | 83 +++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 schemas/StagedDeployment.json diff --git a/schemas/StagedDeployment.json b/schemas/StagedDeployment.json new file mode 100644 index 0000000..00c76bd --- /dev/null +++ b/schemas/StagedDeployment.json @@ -0,0 +1,83 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "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"] + } + } +} From 6a587bdddfdc044713cf0f9c0969f7e1a1d5ef6c Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:12:21 -0400 Subject: [PATCH 4/7] docs(sourceos-spec): add BootSurface example for substrate lanes --- examples/bootsurface.json | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 examples/bootsurface.json diff --git a/examples/bootsurface.json b/examples/bootsurface.json new file mode 100644 index 0000000..769147f --- /dev/null +++ b/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." + } +} From d3dc5e8f6ee214d0279c00f938c8b66920e0ba28 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:13:12 -0400 Subject: [PATCH 5/7] docs(sourceos-spec): add StorageSurface example for substrate lanes --- examples/storagesurface.json | 50 ++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 examples/storagesurface.json diff --git a/examples/storagesurface.json b/examples/storagesurface.json new file mode 100644 index 0000000..ead8b32 --- /dev/null +++ b/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 + } +} From c6b5a05405760d821ad1adbea0d258a61cbe8662 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:13:47 -0400 Subject: [PATCH 6/7] docs(sourceos-spec): add StagedDeployment example for substrate lanes --- examples/stageddeployment.json | 40 ++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 examples/stageddeployment.json diff --git a/examples/stageddeployment.json b/examples/stageddeployment.json new file mode 100644 index 0000000..4227480 --- /dev/null +++ b/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" +} From 574cea8f570b234b9955d5fbd59c6c1861e30e7a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 16 Apr 2026 20:55:25 +0000 Subject: [PATCH 7/7] fix(schemas): add missing $id fields for new substrate contracts Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-spec/sessions/405dc93f-f69a-4d1c-951b-e6aa9589fc95 Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com> --- schemas/BootSurface.json | 1 + schemas/StagedDeployment.json | 1 + schemas/StorageSurface.json | 1 + 3 files changed, 3 insertions(+) diff --git a/schemas/BootSurface.json b/schemas/BootSurface.json index 125929e..91d9e49 100644 --- a/schemas/BootSurface.json +++ b/schemas/BootSurface.json @@ -1,5 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/BootSurface.json", "title": "BootSurface", "type": "object", "additionalProperties": false, diff --git a/schemas/StagedDeployment.json b/schemas/StagedDeployment.json index 00c76bd..4272d83 100644 --- a/schemas/StagedDeployment.json +++ b/schemas/StagedDeployment.json @@ -1,5 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/StagedDeployment.json", "title": "StagedDeployment", "type": "object", "additionalProperties": false, diff --git a/schemas/StorageSurface.json b/schemas/StorageSurface.json index ac721d7..28189a9 100644 --- a/schemas/StorageSurface.json +++ b/schemas/StorageSurface.json @@ -1,5 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/StorageSurface.json", "title": "StorageSurface", "type": "object", "additionalProperties": false,