feat(spec): introduce OSImage / NodeBinding / CyberneticAssignment seam

docs/adr/0001-os-build-cybernetic-boundary.md

@@ -0,0 +1,58 @@
+# ADR-0001: OS build / cybernetic boundary contracts
+
+**Date:** 2026-04-14  
+**Status:** Proposed
+
+---
+
+## Context
+
+The typed contract canon currently models metadata, governance, execution, provenance, agent sessions, release receipts, and related domain objects, but it does not yet expose a first-class boundary between:
+
+1. immutable host image identity,
+2. mutable install-time or enrollment-time node assignment, and
+3. runtime cybernetic identity and control semantics.
+
+Without this separation, downstream repos risk mixing environment, topology, runtime service identity, and control-loop meaning into image identity or installer state.
+
+## Decision
+
+Introduce three additive schema types:
+
+- `OSImage`
+- `NodeBinding`
+- `CyberneticAssignment`
+
+These contracts formalize the plane boundary as follows:
+
+- `OSImage` owns immutable substrate identity, host ABI, boot/update posture, os-release identity, OCI metadata, and provenance references.
+- `NodeBinding` owns install-time and enrollment-time mutable assignment such as topology, fleet, update ring, installer profile, registry mirrors, and bootstrap trust roots.
+- `CyberneticAssignment` owns runtime service identity, deployment environment projection, policy refs, graph relations, and control objectives.
+
+## Alternatives considered
+
+| Alternative | Reason not chosen |
+|-------------|------------------|
+| Encode environment and runtime role directly in image naming | Pollutes immutable image identity and makes shared-image reuse brittle. |
+| Put binding and cybernetic semantics into installer-only contracts | Loses a shared cross-repo canonical object model and makes runtime enforcement harder. |
+| Keep the seam purely documentary with no schema types | Fails to make the boundary machine-checkable for downstream validation and release gating. |
+
+## Consequences
+
+Positive:
+
+- gives downstream build, policy, runtime, and deployment repos a single canonical seam;
+- enables validation rules that reject cybernetic leakage into immutable image metadata;
+- supports additive rollout through existing SemVer and ADR discipline.
+
+Negative:
+
+- requires follow-on updates to schema catalog documentation, OpenAPI/AsyncAPI surfaces, semantic overlays, and changelog entries;
+- introduces new URN namespaces that must be carried consistently in examples and downstream imports.
+
+## References
+
+- `docs/specs/canon.os-build.v1.md`
+- `schemas/OSImage.json`
+- `schemas/NodeBinding.json`
+- `schemas/CyberneticAssignment.json`

docs/specs/canon.os-build.v1.md

@@ -0,0 +1,175 @@
+# canon.os-build.v1
+
+**Status:** Draft  
+**Intended repository:** `SourceOS-Linux/sourceos-spec`  
+**Suggested first release:** `v2.1.0`
+
+## Context
+
+SourceOS and SociOS need a normative contract boundary between immutable host-image identity, mutable install-time binding, and runtime cybernetic meaning. Existing platform discussions and downstream repos already distinguish build substrate, install/enrollment flow, and runtime policy/evidence lanes, but the typed contract canon does not yet expose first-class objects for these layers.
+
+## Decision
+
+This specification defines three first-class contract objects:
+
+- `OSImage` — immutable substrate identity and host contract
+- `NodeBinding` — mutable install-time and enrollment-time node assignment
+- `CyberneticAssignment` — runtime identity, policy, telemetry, relations, and control semantics
+
+The governing rule is:
+
+- a field belongs in `OSImage` if it changes boot, measured identity, host ABI, update behavior, extension compatibility, or image provenance;
+- a field belongs in `NodeBinding` if two nodes can boot the same image but must receive different install-time or enrollment-time values;
+- a field belongs in `CyberneticAssignment` if it changes runtime service identity, deployment environment projection, policy, relations, objectives, or control-loop behavior.
+
+## Naming rules
+
+### Immutable short IDs
+
+`OSImage.shortId` uses the pattern:
+
+`so<epoch>-<host-profile>`
+
+Examples:
+
+- `so1-edge-appliance`
+- `so1-workstation`
+- `so1-vm-base`
+- `so1-installer`
+
+### Artifact projection
+
+Rendered artifact names may append artifact and architecture:
+
+`<shortId>-<artifact>-<arch>`
+
+Examples:
+
+- `so1-edge-appliance-oci-aarch64`
+- `so1-vm-base-qcow2-x86_64`
+- `so1-installer-iso-x86_64`
+
+### Forbidden in immutable short IDs
+
+Do not encode:
+
+- environment (`dev`, `stage`, `prod`)
+- topology (`na-use1`, `eu-de1`)
+- customer or site names
+- cybernetic role words (`sensor`, `planner`, `governor`)
+- runtime service names
+
+## Required object shape
+
+### `OSImage`
+
+Must contain:
+
+- URN identity
+- `shortId`
+- `family`, `epoch`, `hostProfile`, `artifact`, `architecture`
+- `osRelease` with at least `ID`, `VERSION_ID`, `IMAGE_ID`, `IMAGE_VERSION`
+- OCI annotations
+- substrate capability list
+- provenance references
+
+### `NodeBinding`
+
+Must contain:
+
+- URN identity
+- `imageRef`
+- `nodeProfile`
+- topology
+- fleet
+- update ring
+
+May contain:
+
+- registry mirrors
+- hostname template
+- installer profile
+- bootstrap trust roots
+- install-time target image reference
+
+### `CyberneticAssignment`
+
+Must contain:
+
+- URN identity
+- `nodeRef`
+- runtime service identity
+- deployment environment name
+- policy refs
+- graph relations
+
+May contain:
+
+- principal reference
+- control profile reference
+- objective set
+
+## Allowlist and denylist
+
+### `OSImage` allowlist categories
+
+- distro lineage and ABI epoch
+- boot and update contract
+- secure boot / TPM / measured boot posture
+- generic hardware and virtualization enablement
+- `os-release` identity
+- OCI image metadata
+- build provenance and attestations
+- substrate agents tightly coupled to the host
+
+### `OSImage` denylist categories
+
+- runtime service identity
+- deployment environment name
+- runtime graph relations
+- control objectives
+- workload selection intent
+- live enrollment tokens
+- long-lived secrets
+
+## Versioning
+
+This addition is additive if introduced as new schema types and optional API/event surfaces. Recommended versioning policy:
+
+- patch — clarifications, descriptions, examples
+- minor — additive fields and additive schema types
+- major — boundary changes or incompatible rename/removal
+
+## Reference example
+
+```json
+{
+  "id": "urn:srcos:osimage:so1-edge-appliance",
+  "type": "OSImage",
+  "specVersion": "2.1.0",
+  "shortId": "so1-edge-appliance",
+  "family": "sourceos",
+  "epoch": 1,
+  "hostProfile": "edge-appliance",
+  "artifact": "oci",
+  "architecture": "aarch64",
+  "osRelease": {
+    "ID": "sourceos",
+    "ID_LIKE": ["fedora"],
+    "VERSION_ID": "1",
+    "IMAGE_ID": "so1-edge-appliance",
+    "IMAGE_VERSION": "2026.04.14.1"
+  },
+  "ociAnnotations": {
+    "org.opencontainers.image.version": "2026.04.14.1",
+    "org.opencontainers.image.revision": "fcea8a4bf4cb4f06b63e090fd9cf89fcdb24194c",
+    "org.opencontainers.image.source": "https://github.com/SourceOS-Linux/sourceos-spec",
+    "com.socioprophet.os.channel": "stable"
+  },
+  "substrateCapabilities": ["bootc", "secureboot", "tpm2", "measured-boot"],
+  "provenance": {
+    "statementRef": "urn:srcos:attestation:osimage:so1-edge-appliance:2026.04.14.1",
+    "slsaPredicateRef": "urn:srcos:slsa:osimage:so1-edge-appliance:2026.04.14.1"
+  }
+}
+```

examples/cyberneticassignment.json

@@ -0,0 +1,37 @@
+{
+  "id": "urn:srcos:cyberassign:edge-gateway-na-use1-001",
+  "type": "CyberneticAssignment",
+  "specVersion": "2.1.0",
+  "nodeRef": "urn:srcos:node:edge-gateway-na-use1-001",
+  "principalRef": "urn:srcos:principal:edge-gateway-na-use1-001",
+  "controlProfileRef": "urn:srcos:control-profile:regional-sensor-hub",
+  "serviceIdentity": {
+    "namespace": "socioprophet.edge",
+    "name": "gateway-control",
+    "instanceId": "edge-gateway-na-use1-001"
+  },
+  "deploymentEnvironmentName": "production",
+  "policyRefs": [
+    "urn:srcos:policy:edge-guardrails-v1"
+  ],
+  "relations": {
+    "reports_to": [
+      "urn:srcos:council:regional-ops"
+    ],
+    "observes": [
+      "urn:srcos:signal:market-edge-demand"
+    ],
+    "acts_on": [
+      "urn:srcos:workflow:route-shift"
+    ],
+    "governed_by": [
+      "urn:srcos:policy:edge-guardrails-v1"
+    ]
+  },
+  "objectives": [
+    {
+      "name": "routing-latency-p95",
+      "target": "<=200ms"
+    }
+  ]
+}

examples/nodebinding.json

@@ -0,0 +1,19 @@
+{
+  "id": "urn:srcos:nodebinding:edge-gateway-na-use1-001",
+  "type": "NodeBinding",
+  "specVersion": "2.1.0",
+  "imageRef": "urn:srcos:osimage:so1-edge-appliance",
+  "nodeProfile": "field-gateway",
+  "topology": "na-use1",
+  "fleet": "edge-prod",
+  "updateRing": "stable",
+  "targetImgref": "quay.io/sourceos/edge-appliance:2026.04.14.1",
+  "hostnameTemplate": "edge-gateway-%03d",
+  "registries": [
+    "registry-use1.internal"
+  ],
+  "bootstrapTrustRootRefs": [
+    "urn:srcos:trustroot:global-platform-root"
+  ],
+  "installerProfile": "edge-default"
+}

examples/osimage.json

@@ -0,0 +1,42 @@
+{
+  "id": "urn:srcos:osimage:so1-edge-appliance",
+  "type": "OSImage",
+  "specVersion": "2.1.0",
+  "shortId": "so1-edge-appliance",
+  "family": "sourceos",
+  "epoch": 1,
+  "hostProfile": "edge-appliance",
+  "artifact": "oci",
+  "architecture": "aarch64",
+  "osRelease": {
+    "ID": "sourceos",
+    "ID_LIKE": [
+      "fedora"
+    ],
+    "VERSION_ID": "1",
+    "IMAGE_ID": "so1-edge-appliance",
+    "IMAGE_VERSION": "2026.04.14.1"
+  },
+  "ociAnnotations": {
+    "org.opencontainers.image.version": "2026.04.14.1",
+    "org.opencontainers.image.revision": "fcea8a4bf4cb4f06b63e090fd9cf89fcdb24194c",
+    "org.opencontainers.image.source": "https://github.com/SourceOS-Linux/sourceos-spec",
+    "com.socioprophet.os.channel": "stable",
+    "com.socioprophet.os.capabilities": [
+      "bootc",
+      "secureboot",
+      "tpm2"
+    ]
+  },
+  "substrateCapabilities": [
+    "bootc",
+    "secureboot",
+    "tpm2",
+    "measured-boot"
+  ],
+  "provenance": {
+    "statementRef": "urn:srcos:attestation:osimage:so1-edge-appliance:2026.04.14.1",
+    "slsaPredicateRef": "urn:srcos:slsa:osimage:so1-edge-appliance:2026.04.14.1",
+    "sbomRef": "urn:srcos:sbom:osimage:so1-edge-appliance:2026.04.14.1"
+  }
+}