Skip to content

feat(spec): add immutable node profile contracts#91

Open
mdheller wants to merge 8 commits intomainfrom
sourceos/immutable-node-contracts-v0
Open

feat(spec): add immutable node profile contracts#91
mdheller wants to merge 8 commits intomainfrom
sourceos/immutable-node-contracts-v0

Conversation

@mdheller
Copy link
Copy Markdown
Contributor

@mdheller mdheller commented May 5, 2026

Summary

Adds the first SourceOS machine-readable immutable-node contract tranche.

Added

Schemas:

  • schemas/ImmutableNodeProfile.json
  • schemas/HostCapabilityPlacement.json
  • schemas/NodeStateSchema.json

Examples:

  • examples/immutablenodeprofile.json
  • examples/hostcapabilityplacement.json
  • examples/nodestateschema.json

Validation/docs:

  • tools/validate_immutable_node_examples.py
  • docs/contract-additions/immutable-node-profiles.md

Why

The platform standards repo now has ADR-070 for the generic immutable host placement grammar and an ADR-071 PR clarifying the SourceOS/Socios boundary.

This PR turns the SourceOS side into typed contracts so downstream repos can render, validate, and emit evidence around immutable-node profiles without making Socios a mandatory base OS dependency.

Boundary

  • SourceOS immutable node profiles are base substrate contracts.
  • Optional Socios capability packs are modeled as optional references only.
  • substrate.sociosRequired is constrained to false.
  • This does not replace BootReleaseSet.
  • This does not implement boot execution, host mutation, or runtime rendering.

Validation

Focused validation command added:

python3 tools/validate_immutable_node_examples.py

Upstream state

This branch is additive but currently behind main by recent upstream movement. It should be replayed onto current main before merge.

Follow-on work

  1. Wire the new validator into Makefile.
  2. Index the schemas in schemas/README.md and ARCHITECTURE.md.
  3. Add Agent Machine renderer/validator support.
  4. Add sourceosctl immutable-node plan|validate|inspect in sourceos-devtools.
  5. Register cross-repo topology edges in sociosphere.

Copy link
Copy Markdown
Contributor Author

mdheller commented May 5, 2026

Superseded by #95.

Reason: this PR was the first immutable-node contract tranche, but the replacement PR reframes the contracts explicitly as node / agent-runtime substrate work rather than desktop-owned work and was replayed onto a newer base branch.

Please review #95 instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant