Skip to content

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

Merged
mdheller merged 8 commits intomainfrom
work/os-build-cybernetic-seam-v1
Apr 16, 2026
Merged

feat(spec): introduce OSImage / NodeBinding / CyberneticAssignment seam#26
mdheller merged 8 commits intomainfrom
work/os-build-cybernetic-seam-v1

Conversation

@mdheller
Copy link
Copy Markdown
Contributor

Summary

This draft PR stages the foundational additive contract tranche for the OS build / cybernetic boundary:

  • adds schemas/OSImage.json
  • adds schemas/NodeBinding.json
  • adds schemas/CyberneticAssignment.json
  • adds aligned examples for all three types
  • adds docs/specs/canon.os-build.v1.md
  • adds docs/adr/0001-os-build-cybernetic-boundary.md

Intent

The goal is to formalize the seam between:

  • immutable host image identity (OSImage)
  • mutable install/enrollment assignment (NodeBinding)
  • runtime identity / policy / relation semantics (CyberneticAssignment)

Why draft

This branch was cut from main and staged successfully, but main advanced during authoring and the branch is now behind the current base. The added files are isolated new paths, so review can begin now, but the branch should be rebased or replayed onto current main before merge.

Follow-on required in this PR or immediate successor

To fully satisfy the repository contribution discipline, the following still need to be added or updated on top of this draft:

  • README.md schema family table / repo layout references
  • ARCHITECTURE.md URN table and lifecycle discussion
  • schemas/README.md catalog rows for the three new types
  • CHANGELOG.md additive Unreleased entry (or release entry if cut as v2.1.0)
  • openapi.yaml additive REST exposure if these objects are promoted to first-class API resources
  • asyncapi.yaml additive event exposure if these objects emit first-class change events
  • semantic overlay updates if these become first-class semantic classes

Notes for reviewers

This PR is intentionally limited to the foundational new-file tranche because the connector path available during staging exposed a straightforward create-file workflow for new files but not a clean single-step update path for the existing catalog/changelog/API files.

Suggested next review order

  1. schema naming and URN prefixes
  2. boundary semantics across the three contract types
  3. example payload coherence
  4. follow-on catalog / API / changelog patch plan

Copy link
Copy Markdown
Contributor Author

Execution note for reviewers:

This PR is the anchor tranche for the OS build / cybernetic boundary rollout.

Recommended merge order after review:

  1. SourceOS-Linux/sourceos-spec PR feat(spec): introduce OSImage / NodeBinding / CyberneticAssignment seam #26 (this PR)
  2. SocioProphet/prophet-platform-standards PR chore: document merge conflict remediation in CHANGELOG #7
  3. SocioProphet/policy-fabric PR feat(spec): add execution-control contract pack tranche 1 #20
  4. SocioProphet/agentplane PR ci(validate): guardrail against duplicate schema $id values #40
  5. SocioProphet/prophet-platform lock / release-consumer patch (not opened yet)

Downstream draft PRs have already been staged against this seam and should be treated as dependent consumers, not parallel schema authorities.

Before merge, this PR still needs the existing-file completion tranche noted in the description:

  • README.md
  • ARCHITECTURE.md
  • schemas/README.md
  • CHANGELOG.md
  • additive openapi.yaml and optional asyncapi.yaml / semantic overlay decisions

Once those are complete and the branch is refreshed on current main, the downstream PRs can be rebased only if schema names or required fields changed.

@mdheller mdheller marked this pull request as ready for review April 16, 2026 20:59
@mdheller mdheller merged commit 025ebc0 into main Apr 16, 2026
4 checks passed
@mdheller mdheller deleted the work/os-build-cybernetic-seam-v1 branch April 16, 2026 20:59
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