Add NLBoot integration docs, fixtures, Makefile validation, and maturity record

.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/

Makefile

@@ -0,0 +1,15 @@
+.PHONY: validate test
+
+validate:
+	python src/sourceos_boot/validate_boot_release_set.py examples/boot-release-set.example.json
+	PYTHONPATH=src python -m sourceos_boot.cli adapt-nlboot \
+	  --manifest examples/nlboot/manifest.json \
+	  --token examples/nlboot/token.json \
+	  --device-id device-demo-m2 \
+	  --public-key-fingerprint sha256:0000000000000000000000000000000000000000000000000000000000000000 \
+	  --platform apple-silicon \
+	  --nonce nonce-demo-1 \
+	  --correlation-id corr-demo-1
+
+test:
+	python -m pytest

docs/NLBOOT_INTEGRATION.md

@@ -0,0 +1,101 @@
+# NLBoot Integration Guide
+
+`sourceos-boot` adapts the [`SociOS-Linux/nlboot`](https://github.com/SociOS-Linux/nlboot) safe planning protocol into SourceOS BootReleaseSet contracts and Prophet Lattice evidence envelopes.
+
+## What nlboot provides
+
+The nlboot reference implementation defines:
+
+| Object | Description |
+|---|---|
+| `SignedBootManifest` | Signed artifact manifest with kernel/initrd/rootfs refs, boot mode, and crypto profile |
+| `EnrollmentToken` | One-time, time-bound, boot-mode-scoped authorization token |
+| `BootPlan` | Side-effect-free plan record with `execute=false` and required proof gates |
+
+nlboot enforces RSA-PSS/SHA-256 manifest verification and FIPS-140-3-compatible crypto profile markers before emitting any plan.
+
+## Integration stance
+
+`sourceos-boot` does not fork the nlboot protocol vocabulary. Instead:
+
+- nlboot remains the safe planner and reference protocol lane.
+- `sourceos-boot` adapts nlboot manifest/token/plan output into BootReleaseSet patches, BootAuthorization records, and evidence envelopes.
+- BootReleaseSet is the handoff object for Prophet Platform, SourceOS, and Lattice.
+
+See [`NLBOOT_COMPATIBILITY.md`](NLBOOT_COMPATIBILITY.md) for the field-level mapping.
+
+## Adapter flow
+
+The `SourceOSBootAdapter` models a five-stage, side-effect-free handshake:
+
+```
+announce → authorize → fetch manifest → verify → emit evidence
+```
+
+1. **Announce** — build a `SourceOSBootAnnounce` payload from a `DeviceClaim`.
+2. **Authorize** — convert an nlboot `EnrollmentToken` document into a `BootAuthorization`.
+3. **Fetch** — build a `SourceOSBootFetchRequest` using the `BootAuthorization`.
+4. **Verify** — apply the nlboot manifest to produce a `BootReleaseSet` patch.
+5. **Evidence** — emit a `BootEvidence` envelope covering device claim, manifest hash, channel, boot mode, and verification result.
+
+All operations are pure and side-effect-free. No disk writes, kexec calls, or network requests are performed.
+
+## Boot mode mapping
+
+| nlboot `boot_mode` | SourceOS channel | SourceOS action |
+|---|---|---|
+| `installer` | `installer` | `install` |
+| `recovery` | `recovery` | `repair` |
+| `ephemeral` | `live` | `kexec` |
+| `bootstrap` | `live` | `enroll` |
+
+## CLI usage
+
+```bash
+PYTHONPATH=src python -m sourceos_boot.cli adapt-nlboot \
+  --manifest examples/nlboot/manifest.json \
+  --token   examples/nlboot/token.json \
+  --device-id             device-demo-m2 \
+  --public-key-fingerprint sha256:0000000000000000000000000000000000000000000000000000000000000000 \
+  --platform              apple-silicon \
+  --nonce                 nonce-demo-1 \
+  --correlation-id        corr-demo-1
+```
+
+The command emits an `NlbootAdapterOutput` JSON object to stdout. See
+`examples/nlboot/adapted-output.example.json` for the expected structure.
+
+## Fixture files
+
+| File | Description |
+|---|---|
+| `examples/nlboot/manifest.json` | Minimal nlboot `SignedBootManifest` fixture |
+| `examples/nlboot/token.json` | Minimal nlboot `EnrollmentToken` fixture |
+| `examples/nlboot/adapted-output.example.json` | Expected `NlbootAdapterOutput` for the above fixtures |
+
+## Validation
+
+```bash
+make validate   # validate BootReleaseSet example and exercise the nlboot adapter
+make test       # run pytest suite
+```
+
+The CI workflow (`ci.yml`) also validates `examples/boot-release-set.example.json`
+and runs the full pytest suite on every push and pull request.
+
+## Known gaps
+
+- Real nlboot manifest signature verification (RSA-PSS/SHA-256) is not yet wired
+  into this adapter; the adapter accepts a pre-verified manifest document.
+- Artifact fetch, SHA-256 check, and content-addressed cache are implemented in
+  the Rust `nlboot-client` lane; the Python adapter here covers planning only.
+- Host mutation (kexec, install, rollback) remains disabled pending explicit
+  platform adapter review. See `WORLD_CLASS_TARGETS.md` for the implementation path.
+
+## References
+
+- [`NLBOOT_COMPATIBILITY.md`](NLBOOT_COMPATIBILITY.md) — detailed field mapping
+- [`INTEGRATION.md`](INTEGRATION.md) — upstream/downstream dependency contract
+- [`WORLD_CLASS_TARGETS.md`](WORLD_CLASS_TARGETS.md) — implementation roadmap
+- [`SociOS-Linux/nlboot`](https://github.com/SociOS-Linux/nlboot) — upstream safe planner
+- [`src/sourceos_boot/adapter.py`](../src/sourceos_boot/adapter.py) — adapter implementation

examples/nlboot/adapted-output.example.json

@@ -0,0 +1,76 @@
+{
+  "apiVersion": "sourceos.dev/v1",
+  "kind": "NlbootAdapterOutput",
+  "authorization": {
+    "bootReleaseSetRef": "boot/demo",
+    "correlationId": "corr-demo-1",
+    "expiresAt": "2026-04-26T01:00:00Z",
+    "tokenId": "token-demo-1"
+  },
+  "bootReleaseSetPatch": {
+    "artifacts": [
+      {
+        "name": "kernel",
+        "role": "kernel",
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "uri": "https://example.invalid/kernel"
+      },
+      {
+        "name": "initrd",
+        "role": "initrd",
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "uri": "https://example.invalid/initrd"
+      },
+      {
+        "name": "rootfs",
+        "role": "rootfs",
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "uri": "https://example.invalid/rootfs"
+      }
+    ],
+    "channels": [
+      "recovery"
+    ],
+    "policy": {
+      "allowedActions": [
+        "announce",
+        "enroll",
+        "fetch",
+        "verify",
+        "repair",
+        "attest"
+      ]
+    },
+    "provenance": {
+      "attestations": [
+        "slsa",
+        "in-toto"
+      ],
+      "builderId": "trusted-key-1",
+      "sourceRefs": [
+        "manifest-demo-1"
+      ]
+    },
+    "releaseSetRef": "release/demo",
+    "signature": {
+      "bundleRef": "urn:srcos:signature:demo",
+      "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+      "type": "x509"
+    }
+  },
+  "evidence": {
+    "bootMode": "recovery",
+    "correlationId": "corr-demo-1",
+    "deviceId": "device-demo-m2",
+    "manifestHash": "sha256:b5014e848fc8ce3acd28a7cc8c2435340bf3871647d298bec102fb7dbe737e1a",
+    "reports": [
+      "device-claim",
+      "manifest-hash",
+      "verification-result",
+      "selected-channel",
+      "boot-mode"
+    ],
+    "selectedChannel": "recovery",
+    "verificationResult": "pass"
+  }
+}

repo.maturity.yaml

@@ -0,0 +1,49 @@
+schemaVersion: repo-maturity.v1
+repository: SourceOS-Linux/sourceos-boot
+plane: sourceos-carry
+status: active
+canonicality: implementation
+owners:
+  - SourceOS-Linux
+maturity:
+  level: M2
+  targetLevel: M3
+  evidence:
+    - README.md describes the BootReleaseSet model and boot/recovery surface.
+    - schemas/boot-release-set.schema.json is the BootReleaseSet v1 contract.
+    - examples/boot-release-set.example.json is a minimal valid fixture.
+    - examples/nlboot/ contains nlboot manifest, token, and adapted-output fixtures.
+    - src/sourceos_boot/adapter.py implements the nlboot-to-BootReleaseSet adapter.
+    - src/sourceos_boot/control_plane.py implements the control-plane boot plan builder.
+    - make validate exercises schema validation and the nlboot adapter CLI path.
+    - python -m pytest passes all tests.
+validation:
+  commands:
+    - make validate
+    - python -m pytest
+  ciRequired: true
+  lastKnownStatus: passing
+integrations:
+  - repository: SociOS-Linux/nlboot
+    relationship: upstream safe planner; sourceos-boot adapts nlboot manifest/token/plan into BootReleaseSet and evidence contracts
+    required: true
+  - repository: SourceOS-Linux/sourceos-spec
+    relationship: should consume normative BootReleaseSet, ReleaseSet, TokenDoor, and Fingerprint schemas once published
+    required: true
+  - repository: SocioProphet/prophet-platform
+    relationship: downstream release service and control-plane UI consumer of BootReleaseSet artifacts
+    required: false
+  - repository: SocioProphet/lattice-forge
+    relationship: downstream runtime/image/kernel artifact producer referenced by BootReleaseSet
+    required: false
+  - repository: SocioProphet/agentplane
+    relationship: downstream agent-plane recovery and runtime repair consumer
+    required: false
+nextActions:
+  - Wire nlboot RSA-PSS/SHA-256 manifest signature verification into the adapter.
+  - Add Apple Silicon M2 platform adaptation layer (PAL) design notes and stubs.
+  - Add UEFI/iPXE PAL design notes for PC/Purism class hardware.
+  - Align BootReleaseSet v1 with sourceos-spec once shared schemas land.
+  - Add enrollment-token exchange stub with control-plane endpoint.
+  - Add artifact digest verification and content-addressed cache path.
+  - Emit evidence records from the boot/recovery execution boundary.