Feature/data plane v0 placement launch plan (#38)

* feat: implement data-plane-v0-placement-launch-plan API

* feat: Data Plane V0 Placement-to-Launch Plan

* fix: address codex review findings for launch plan

* docs, examples: fix quickstart numbering and plan-launch.sh style

* chore: ignore .codex metadata directory

* feat: make launch planning node-scoped

Signed-off-by: InderdeepBajwa <InderdeepBajwa@users.noreply.github.com>

* feat: add node-side launch preparation

* fix: satisfy clippy for node preparation

---------

Signed-off-by: InderdeepBajwa <InderdeepBajwa@users.noreply.github.com>

Author: InderdeepBajwa

.gitignore

@@ -5,3 +5,4 @@ schedune-control-plane/schedune-control-plane
 bin/
 var/
 .schedune.pid
+.codex

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build build-agent build-control-plane test test-agent test-control-plane fmt lint doctor dev-preflight dev-up dev-down demo dev-db-reset example-intake example-schedule example-launch-validate example-launch-dry-run example-launch-execute example-launch-list example-launch-observe example-readiness example-orphans
+.PHONY: help build build-agent build-control-plane test test-agent test-control-plane fmt lint doctor dev-preflight dev-up dev-down demo dev-db-reset example-intake example-schedule example-launch-plan example-launch-validate example-launch-dry-run example-launch-execute example-launch-list example-launch-observe example-readiness example-orphans
 
 # Configuration
 BIN_DIR=bin
@@ -91,6 +91,9 @@ example-intake: ## Ingest the local node capability payload
 example-schedule: ## Run a workload eligibility evaluation explanation
 	@bash examples/curls/schedule-explain.sh
 
+example-launch-plan: ## Plan a launch (placement, validation, and dry-run) without executing
+	@bash examples/curls/plan-launch.sh
+
 example-launch-validate: ## Validate a launch without executing it
 	@bash examples/curls/launch-validate.sh
 

docs/api.md

@@ -13,6 +13,10 @@ Schedune provides a clear, RESTful interface for scheduling, validating, executi
 ### Orchestration
 *   `POST /api/v1alpha1/schedule/explain`: Given a `WorkloadIntent`, evaluates all nodes and returns `RankedNodes` and `RejectedNodes` with explicit `HardRejectionCodes`.
 *   `POST /api/v1alpha1/schedule/select`: Simulates placement and returns the optimal node ID for the given intent.
+*   `POST /api/v1alpha1/plan/launch`: Bridges scheduling and execution. Returns a hydrated `LaunchSpec` and explains rejections. In `dry_run` mode, validates selected node readiness and returns a pending `PreparationResult` indicating that node-agent scoped preparation is required. The node agent can then be invoked locally via `schedune-agent prepare --spec <path>`.
+
+### Node Agent
+*   `schedune-agent prepare --spec <path>`: Local CLI command to prepare the selected runtime backend for a workload. To be called by the node agent after receiving a `PrepareOnNode` action from `/plan/launch`. Reads a `LaunchSpec` JSON from file or stdin (`-`) and outputs a `LaunchPreparationResult` JSON.
 
 ### Execution
 *   `POST /api/v1alpha1/launch/validate`: Given a `LaunchSpec`, assesses if the specific host has the prerequisites to run the chosen backend without launching the process.

docs/quickstart.md

@@ -86,15 +86,24 @@ make example-schedule
 ```
 *(This evaluates an x86 VM intent and explains the eligibility outcome.)*
 
-#### 6. Validate Launch
+#### 6. Plan Launch
+
+Combine your workload intent and a launch template to find an eligible node, validate the launch on it, and dry-run prepare the environment—all without executing anything:
+
+```bash
+make example-launch-plan
+```
+*(This bridges scheduling and execution into a single, safe, read-only explainable response. If `next_actions` includes `PrepareOnNode`, you can invoke the local node agent using `schedune-agent prepare --spec <path>` to locally provision the environment without executing the VM.)*
+
+#### 7. Validate Launch
 
 Validate a launch payload to ensure the backend is available and capabilities match, without starting the VM:
 
 ```bash
 make example-launch-validate
 ```
 
-#### 7. Execute Launch
+#### 8. Execute Launch
 
 If your host has the required binary (`cloud-hypervisor`), execute the launch:
 
@@ -103,7 +112,7 @@ make example-launch-execute
 ```
 *Note the returned `execution_id`.*
 
-#### 8. Inspect Lifecycle
+#### 9. Inspect Lifecycle
 
 Use the `execution_id` to inspect the VM's state, readiness, trace, and events:
 
@@ -124,15 +133,15 @@ make example-readiness EXECUTION_ID=<EXECUTION_ID>
 curl http://127.0.0.1:9090/api/v1alpha1/launch/<EXECUTION_ID>/events
 ```
 
-#### 9. Inspect Orphans
+#### 10. Inspect Orphans
 
 Schedune automatically sweeps for orphan processes. You can list them via:
 
 ```bash
 make example-orphans
 ```
 
-#### 10. Terminate
+#### 11. Terminate
 
 When you are done, terminate the execution and stop the control plane:
 

examples/curls/plan-launch.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+API_BASE="${API_BASE:-http://127.0.0.1:9090}"
+
+echo "=== Planning a VM Launch (Placement -> Validation -> DryRun) ==="
+
+if command -v python3 >/dev/null 2>&1; then
+    curl -s -X POST -H "Content-Type: application/json" -d @examples/plans/vm-plan.json "${API_BASE}/api/v1alpha1/plan/launch" | python3 -m json.tool || true
+else
+    curl -s -X POST -H "Content-Type: application/json" -d @examples/plans/vm-plan.json "${API_BASE}/api/v1alpha1/plan/launch"
+    echo ""
+fi

examples/plans/vm-plan.json

@@ -0,0 +1,36 @@
+{
+  "schema_version": "v1alpha1",
+  "mode": "dry_run",
+  "workload_intent": {
+    "schema_version": "v1alpha1",
+    "workload_id": "wl-demo-plan",
+    "tenant_id": "demo-tenant",
+    "runtime_class": "VirtualMachine",
+    "required_architecture": "x86_64",
+    "max_telemetry_age_sec": 300,
+    "requires_kvm": true,
+    "required_compatibility_classes": [
+      "linux_x86_kvm"
+    ],
+    "preferred_features": [
+      "qemu_binary_present"
+    ],
+    "allow_backend_fallback": true
+  },
+  "launch_template": {
+    "schema_version": "v1alpha1",
+    "workload_id": "wl-demo-plan",
+    "tenant_id": "demo-tenant",
+    "runtime_class": "VirtualMachine",
+    "architecture": "x86_64",
+    "vcpu": 2,
+    "memory_mb": 1024,
+    "storage": [
+      {
+        "host_path": "/var/run/demo.qcow2",
+        "format": "qcow2",
+        "read_only": false
+      }
+    ]
+  }
+}

schedune-agent/src/main.rs

@@ -3,6 +3,7 @@ mod collectors;
 mod daemon;
 mod health;
 mod migration;
+mod prepare;
 mod scheduler_contract;
 
 use anyhow::Result;
@@ -36,6 +37,12 @@ enum Commands {
         #[arg(short, long, default_value_t = 8080)]
         port: u16,
     },
+    /// Prepare the launch environment for a workload
+    Prepare {
+        /// Path to the LaunchSpec JSON file (or '-' for stdin)
+        #[arg(long)]
+        spec: String,
+    },
 }
 
 #[tokio::main]
@@ -80,6 +87,19 @@ async fn main() -> Result<()> {
         Commands::Serve { port } => {
             daemon::run(*port).await;
         }
+        Commands::Prepare { spec } => {
+            let json_str = if spec == "-" {
+                std::io::read_to_string(std::io::stdin())?
+            } else {
+                std::fs::read_to_string(spec)?
+            };
+
+            let launch_spec: crate::prepare::LaunchSpec = serde_json::from_str(&json_str)?;
+            let result = crate::prepare::prepare_launch(launch_spec);
+
+            let json = serde_json::to_string_pretty(&result)?;
+            println!("{}", json);
+        }
     }
 
     Ok(())