From 090792364493ab985ff9724ca37770c453c59385 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 14:53:26 -0400 Subject: [PATCH 1/2] docs(integration): capture SourceOS local control node and Node Commander seam --- ...ocal-control-node-and-node-commander-v0.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/integration/sourceos-local-control-node-and-node-commander-v0.md diff --git a/docs/integration/sourceos-local-control-node-and-node-commander-v0.md b/docs/integration/sourceos-local-control-node-and-node-commander-v0.md new file mode 100644 index 0000000..02c39e4 --- /dev/null +++ b/docs/integration/sourceos-local-control-node-and-node-commander-v0.md @@ -0,0 +1,86 @@ +# SourceOS local control node and Node Commander integration (v0) + +## Purpose + +This note records how the current SourceOS / SociOS Linux local control-node work should bind into `agentplane`. + +`agentplane` remains the downstream execution control plane. It is not the canonical home for host bootstrap or workstation profile semantics. But it is the correct place to capture how those host-side surfaces feed bundle validation, placement, run, replay, and promotion evidence. + +## Current upstream split + +- `SourceOS-Linux/sourceos-spec` + - canonical typed-contract and ADR lane +- `SociOS-Linux/source-os` + - workstation/bootstrap and profile application lane +- `SocioProphet/agentplane` + - execution control plane, executor selection, evidence and replay +- `SocioProphet/prophet-platform` + - deployable runtime/service implementation lane + +This file documents the `agentplane` seam only. + +## What the local control node already proves + +The current operator-node prototype has already demonstrated: + +- declarative macOS control-node configuration via nix-darwin +- OCI build/push/run using Podman +- local `Node Commander` image staging +- a user-scoped runtime envelope suitable for local-first operation + +That work is not yet a production runtime, but it is enough to define the downstream `agentplane` seam. + +## Agentplane responsibilities in this slice + +For the local-first control-node / image-promotion slice, `agentplane` is responsible for: + +1. **Validate** candidate execution bundles and emit `ValidationArtifact`. +2. **Place** work according to local-first / trusted-private / attested-fog / explicit-cloud ordering. +3. **Run** on the selected executor and emit `RunArtifact`. +4. **Replay** with enough evidence to deterministically inspect the decision and execution path. +5. **Consume** promotion-gate evidence from the operator-side control node without becoming the canonical source of those contract meanings. + +## What `agentplane` should consume from the control node + +The control node / Node Commander side is expected to hand off at least the following: + +- candidate build identity +- build provenance digest(s) +- target image or profile identity +- local validation scenario outputs +- promotion-gate decision inputs +- promotion-gate decision result +- references to local state, logs, or receipts that belong in replay/evidence artifacts + +`agentplane` should consume those as downstream inputs and emit its own runtime/evidence artifacts. It should not redefine the contract meanings owned by `sourceos-spec`. + +## Immediate implementation guidance + +This repo should treat the local control-node lane as: + +- a **downstream executor/integration surface** +- compatible with Podman/OCI-based local execution +- compatible with a future Linux/NixOS builder path +- evidence-forward and replay-friendly + +This implies the next `agentplane` work items should be additive and narrow: + +1. document a local-control-node executor/inventory example +2. add a promotion-gate evidence consumption note or fixture +3. add a runner/integration note for OCI-backed local command execution where appropriate +4. keep host bootstrap details out of canonical `agentplane` contract ownership + +## Non-goals for this repo + +This repo should not become the home for: + +- nix-darwin host bootstrap instructions +- workstation shell/profile management +- Docker helper or registry-helper implementation details +- canonical contract definitions for `ControlNodeProfile`, `NodeCommanderRuntime`, or `ImagePromotionGate` + +Those belong elsewhere in the repo topology. + +## Why this note exists now + +`agentplane` is active and already carrying repository-placement and runtime-governance work on `main`. Capturing the local control-node seam here avoids the current implementation work becoming disconnected from the execution/evidence plane that will ultimately consume it. From f76eeb8de796de8a3229fa3c9ba9bfdda1f3e952 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:00:34 -0400 Subject: [PATCH 2/2] docs(integration): bind sourceos-spec local-first release contract seam --- .../sourceos-local-first-release-contracts.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/integration/sourceos-local-first-release-contracts.md diff --git a/docs/integration/sourceos-local-first-release-contracts.md b/docs/integration/sourceos-local-first-release-contracts.md new file mode 100644 index 0000000..d5a91d9 --- /dev/null +++ b/docs/integration/sourceos-local-first-release-contracts.md @@ -0,0 +1,125 @@ +# Integration guide: sourceos-spec local-first release contracts → agentplane + +This guide explains how `agentplane` should consume the local-first release-control contract family published from `SourceOS-Linux/sourceos-spec`. + +The canonical upstream object family is introduced in: + +- `ReleaseSet` +- `BootReleaseSet` +- `EnrollmentToken` +- `Fingerprint` +- `ExperienceProfile` +- `IsolationProfile` + +`agentplane` is the downstream execution-plane consumer of those objects. It should not redefine them locally. + +--- + +## Purpose of the seam + +`sourceos-spec` owns the machine-readable typed contracts for local-first release assignment and post-apply attestation. + +`agentplane` owns: + +- bundle validation and execution eligibility +- placement and replay/evidence behavior +- downstream apply/rollback execution semantics +- runtime-side consumption of release assignment and fingerprint evidence + +--- + +## What agentplane should consume + +The minimum downstream consumption surface is: + +1. `ReleaseSet` +2. optional `BootReleaseSet` +3. optional `EnrollmentToken` when boot/recovery or first-join flow is required +4. `ExperienceProfile` reference +5. `IsolationProfile` reference +6. `Fingerprint` after apply + +--- + +## Minimal execution rule + +Before a local-first apply or rollback path proceeds, `agentplane` should be able to answer: + +- which `ReleaseSet` governs this target? +- which experience and isolation profiles are attached? +- is there a required boot/recovery companion set? +- is there a valid enrollment token when the requested path requires one? +- after apply, did the emitted fingerprint remain compliant with the assigned release? + +If those questions cannot be answered, the path should be treated as incomplete for this slice. + +--- + +## Recommended handoff shape + +A narrow downstream handoff envelope should include at least: + +```json +{ + "release_set_ref": "rs_local_0001", + "boot_release_set_ref": "brs_local_0001", + "experience_profile_ref": "xp_local_0001", + "isolation_profile_ref": "iso_local_0001", + "enrollment_token_ref": "tok_local_0001", + "target_id": "m2-control-node-01" +} +``` + +After apply, downstream artifacts should preserve: + +```json +{ + "release_set_ref": "rs_local_0001", + "fingerprint_ref": "fp_local_0001", + "compliance_status": "compliant" +} +``` + +--- + +## Execution behavior + +### When the assignment is complete + +`agentplane` may continue into normal validation, placement, apply, and evidence flow. + +### When boot/recovery authorization is required + +`agentplane` should require the `BootReleaseSet` and any valid `EnrollmentToken` expected by that path. + +### When fingerprint evidence is missing or non-compliant + +`agentplane` should not silently mark the assignment successful. Missing or drifted fingerprint evidence should remain visible in downstream artifacts and replay surfaces. + +--- + +## Evidence expectations + +Downstream artifacts should preserve: + +- `ReleaseSet` reference +- `BootReleaseSet` reference when used +- `ExperienceProfile` reference +- `IsolationProfile` reference +- `EnrollmentToken` reference when used +- `Fingerprint` reference +- compliance outcome (`compliant`, `drifted`, `unknown`, `failed`) + +That lets replay and review explain not just that a local-first apply occurred, but whether the resulting host actually matched the assigned release contract. + +--- + +## Non-goals + +This guide does not require `agentplane` to: + +- become the canonical schema source +- own higher-level workstation/bootstrap semantics +- define transport bindings for these objects + +Those remain upstream responsibilities in `sourceos-spec` and adjacent repos.