sourceos/immutable-node-contracts-v0-current

examples/hostcapabilityplacement.json

@@ -0,0 +1,20 @@
+{
+  "id": "urn:srcos:host-capability-placement:sourceos-supervisor",
+  "type": "HostCapabilityPlacement",
+  "specVersion": "2.2.0",
+  "name": "SourceOS host supervisor",
+  "placementClass": "image-baked-host-capability",
+  "authority": "sourceos-base",
+  "mandatoryForBaseNode": true,
+  "requiresEnrollment": false,
+  "lifecycleCoupling": "host-release",
+  "pathHints": [
+    "/usr/libexec/sourceos/supervisor",
+    "/usr/lib/systemd/system/sourceos-supervisor.service"
+  ],
+  "evidenceRefs": [
+    "urn:srcos:release-receipt:sourceos-supervisor-bootstrap"
+  ],
+  "policyRef": "urn:srcos:policy:immutable-node-host-supervisor",
+  "notes": "Base SourceOS capability. This is not a Socios enrollment dependency."
+}

examples/immutablenodeprofile.json

@@ -0,0 +1,39 @@
+{
+  "id": "urn:srcos:immutable-node-profile:m2-asahi-dev",
+  "type": "ImmutableNodeProfile",
+  "specVersion": "2.2.0",
+  "name": "M2 Asahi SourceOS dev immutable node",
+  "channel": "m2-asahi-dev",
+  "substrate": {
+    "strategy": "bootc-first",
+    "hostMutationPosture": "staged-updates-only",
+    "sociosRequired": false
+  },
+  "bootReleaseSetRef": "urn:srcos:boot-release-set:m2-asahi-dev",
+  "releaseSetRef": "urn:srcos:release-set:m2-asahi-dev",
+  "workstationProfileRef": "urn:srcos:workstation-profile:workstation-v0",
+  "agentMachineProfileRef": "urn:srcos:agent-machine-profile:m2-asahi-dev",
+  "hostCapabilityPlacementRefs": [
+    "urn:srcos:host-capability-placement:sourceos-supervisor"
+  ],
+  "nodeStateSchemaRefs": [
+    "urn:srcos:node-state-schema:sourceos-evidence-root"
+  ],
+  "optionalSociosCapabilityPackRefs": [
+    "urn:socios:capability-pack:automation-commons-opt-in"
+  ],
+  "validation": {
+    "planCommand": "sourceosctl immutable-node plan --profile m2-asahi-dev --dry-run",
+    "validateCommand": "sourceosctl immutable-node validate --profile m2-asahi-dev",
+    "inspectCommand": "sourceosctl immutable-node inspect --profile m2-asahi-dev",
+    "evidenceCommand": "agent-machine release evidence inspect --profile m2-asahi-dev"
+  },
+  "policyRefs": [
+    "urn:srcos:policy:immutable-node-base",
+    "urn:srcos:policy:socios-opt-in-required"
+  ],
+  "evidenceRefs": [
+    "urn:srcos:release-receipt:m2-asahi-dev"
+  ],
+  "notes": "SourceOS base node profile. Socios pack reference is optional and does not imply enrollment."
+}

examples/nodestateschema.json

@@ -0,0 +1,14 @@
+{
+  "id": "urn:srcos:node-state-schema:sourceos-evidence-root",
+  "type": "NodeStateSchema",
+  "specVersion": "2.2.0",
+  "name": "SourceOS evidence root",
+  "rootPath": "/var/lib/sourceos/evidence",
+  "stateClass": "append-only-evidence",
+  "schemaRef": "urn:srcos:release-receipt:sourceos-evidence",
+  "rollbackCompatibility": "required-n-and-n-minus-1",
+  "mutability": "append-only",
+  "owner": "agent-machine",
+  "evidenceRequired": true,
+  "notes": "Durable evidence root survives host rollback and must preserve reader compatibility."
+}

schemas/HostCapabilityPlacement.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/HostCapabilityPlacement.json",
+  "title": "HostCapabilityPlacement",
+  "description": "A SourceOS immutable-node placement declaration for one host capability, service workload, extension, or state root.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "name",
+    "placementClass",
+    "authority"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:host-capability-placement:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:host-capability-placement:<local-id>."
+    },
+    "type": {
+      "const": "HostCapabilityPlacement",
+      "description": "Discriminator constant — always HostCapabilityPlacement."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. 2.2.0."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable capability name."
+    },
+    "placementClass": {
+      "type": "string",
+      "enum": [
+        "image-baked-host-capability",
+        "sysext-host-capability",
+        "confext-policy-config-capability",
+        "quadlet-bound-service-workload",
+        "quadlet-floating-service-workload",
+        "var-state-object"
+      ],
+      "description": "Canonical placement class inherited from the immutable-node host capability model."
+    },
+    "authority": {
+      "type": "string",
+      "enum": [
+        "sourceos-base",
+        "sourceos-boot",
+        "agent-machine",
+        "sourceos-devtools",
+        "agentplane",
+        "prophet-platform",
+        "socios-optional-pack"
+      ],
+      "description": "Repo or plane class that owns the implementation boundary for this capability."
+    },
+    "mandatoryForBaseNode": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the capability is required for a base SourceOS immutable node without Socios enrollment."
+    },
+    "requiresEnrollment": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether activation requires opt-in enrollment, Proof-of-Life, or signed intent."
+    },
+    "lifecycleCoupling": {
+      "type": "string",
+      "enum": [
+        "host-release",
+        "extension-release",
+        "service-release",
+        "state-schema",
+        "operator-local"
+      ],
+      "description": "Primary lifecycle to which this capability is coupled."
+    },
+    "pathHints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Expected implementation paths such as /usr/libexec/sourceos, /usr/share/containers/systemd, /var/lib/sourceos, or /var/lib/socios."
+    },
+    "evidenceRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional references to evidence records emitted by the capability."
+    },
+    "policyRef": {
+      "type": ["string", "null"],
+      "description": "Optional policy identifier or URN governing activation or mutation."
+    },
+    "notes": {
+      "type": ["string", "null"],
+      "description": "Human-readable review notes."
+    }
+  }
+}

schemas/ImmutableNodeProfile.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ImmutableNodeProfile.json",
+  "title": "ImmutableNodeProfile",
+  "description": "A SourceOS immutable-node profile tying together boot/release references, host capability placements, durable state schemas, validation entrypoints, and optional Socios capability-pack posture.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "name",
+    "channel",
+    "substrate"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:immutable-node-profile:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:immutable-node-profile:<local-id>."
+    },
+    "type": {
+      "const": "ImmutableNodeProfile",
+      "description": "Discriminator constant — always ImmutableNodeProfile."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. 2.2.0."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable immutable node profile name."
+    },
+    "channel": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Realization channel such as linux-dev, linux-stable, m2-asahi-dev, or fog-node."
+    },
+    "substrate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strategy", "hostMutationPosture", "sociosRequired"],
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["bootc-first", "ostree-compatible", "rpm-ostree", "coreos-assembler", "nixos-adapter", "other"],
+          "description": "Primary immutable-host realization strategy."
+        },
+        "hostMutationPosture": {
+          "type": "string",
+          "enum": ["immutable-runtime", "staged-updates-only", "lab-live-mutation-allowed", "unknown"],
+          "description": "Allowed host mutation posture for this profile."
+        },
+        "sociosRequired": {
+          "const": false,
+          "description": "Base SourceOS immutable nodes must not require Socios enrollment. Optional Socios packs are modeled separately."
+        }
+      }
+    },
+    "bootReleaseSetRef": {
+      "type": ["string", "null"],
+      "description": "Optional BootReleaseSet or boot/recovery handoff reference."
+    },
+    "releaseSetRef": {
+      "type": ["string", "null"],
+      "description": "Optional ReleaseSet assignment reference."
+    },
+    "workstationProfileRef": {
+      "type": ["string", "null"],
+      "description": "Optional WorkstationProfile reference for desktop/workstation realization."
+    },
+    "agentMachineProfileRef": {
+      "type": ["string", "null"],
+      "description": "Optional Agent Machine or AgentPod profile reference for local runtime realization."
+    },
+    "hostCapabilityPlacementRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:host-capability-placement:" },
+      "description": "References to HostCapabilityPlacement objects used by this profile."
+    },
+    "nodeStateSchemaRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:node-state-schema:" },
+      "description": "References to NodeStateSchema objects used by this profile."
+    },
+    "optionalSociosCapabilityPackRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional Socios capability pack references. Presence does not imply base node dependency or enrollment."
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "planCommand": { "type": ["string", "null"] },
+        "validateCommand": { "type": ["string", "null"] },
+        "inspectCommand": { "type": ["string", "null"] },
+        "evidenceCommand": { "type": ["string", "null"] }
+      },
+      "description": "Operator-facing dry-run, validation, inspection, and evidence entrypoints."
+    },
+    "policyRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Policy references that govern activation, mutation, enrollment, or rollback."
+    },
+    "evidenceRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Evidence or receipt references expected from this node profile."
+    },
+    "notes": {
+      "type": ["string", "null"],
+      "description": "Human-readable review notes."
+    }
+  }
+}

schemas/NodeStateSchema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/NodeStateSchema.json",
+  "title": "NodeStateSchema",
+  "description": "A SourceOS immutable-node durable state schema declaration for rollback-aware host and service state roots.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "name",
+    "rootPath",
+    "stateClass",
+    "rollbackCompatibility"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:node-state-schema:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:node-state-schema:<local-id>."
+    },
+    "type": {
+      "const": "NodeStateSchema",
+      "description": "Discriminator constant — always NodeStateSchema."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. 2.2.0."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable state root name."
+    },
+    "rootPath": {
+      "type": "string",
+      "pattern": "^/var/(lib|cache)/",
+      "description": "Durable or rebuildable state root. Authoritative mutable truth must not live under /usr or /etc."
+    },
+    "stateClass": {
+      "type": "string",
+      "enum": [
+        "durable-truth",
+        "append-only-evidence",
+        "replay-checkpoint",
+        "model-cache",
+        "rebuildable-cache",
+        "operator-local"
+      ],
+      "description": "Semantic class of the state root."
+    },
+    "schemaRef": {
+      "type": ["string", "null"],
+      "description": "Optional schema, contract, or URN reference for records stored in this root."
+    },
+    "rollbackCompatibility": {
+      "type": "string",
+      "enum": [
+        "required-n-and-n-minus-1",
+        "best-effort",
+        "not-required-rebuildable",
+        "operator-managed"
+      ],
+      "description": "Rollback compatibility expectation for readers and writers of this state root."
+    },
+    "mutability": {
+      "type": "string",
+      "enum": [
+        "append-only",
+        "controlled-write",
+        "rebuildable",
+        "ephemeral-cache"
+      ],
+      "description": "Expected write posture for this root."
+    },
+    "owner": {
+      "type": ["string", "null"],
+      "description": "Owning plane or repository class for this state root."
+    },
+    "evidenceRequired": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether writes to this state root require evidence emission."
+    },
+    "notes": {
+      "type": ["string", "null"],
+      "description": "Human-readable review notes."
+    }
+  }
+}