feat: versioning scheme — lockstep crates + four independent surfaces

Establish how versions are assigned, bumped, and checked across the
five things that actually change for users: the product itself, the
Rhai SDK, the HTTP API, the database schema, and the inter-service
wire (reserved for cluster mode). Crates ship in lockstep — drift
between picloud-shared and picloud-manager-core is fiction since
they always release together — but surfaces are versioned and
checked at their natural boundaries.

  * docs/versioning.md is the authoritative reference: what gets a
    version, the per-surface compatibility rules, how each surface
    bump cascades to the product version (loose pre-1.0, strict
    post-1.0), and the five enforcement mechanisms (lockstep at
    compile time, /version at runtime, golden SDK contract tests,
    migration replay, CI guardrail).

  * shared::version exposes four constants — PRODUCT_VERSION (from
    CARGO_PKG_VERSION), SDK_VERSION ("1.0"), API_VERSION (1),
    WIRE_VERSION (1). Scripts read SDK_VERSION as ctx.sdk_version
    and can feature-detect against it.

  * Workspace inheritance: `[workspace.package] version = "0.2.0"`
    is the single point of truth; every crate uses
    `version.workspace = true`. dashboard/package.json mirrors.

  * Routes move to /api/v1/* — both control plane
    (/api/v1/admin/*) and data plane (/api/v1/execute/{id}).
    Picloud composes them via a single `/api/v{API_VERSION}` nest,
    so the next major is a copy-paste-and-bump. Caddyfile (dev and
    prod) routes /api/v1/* to picloud and 404s any other /api/*
    so old clients fail loudly instead of getting the SPA shell.
    Dashboard client + integration tests updated.

  * /healthz remains a plain "ok" string (k8s probes); /version is
    the new JSON endpoint returning every surface version in one
    place — product, sdk, api, schema (from
    manager-core::migrations::latest_version), wire.

  * Reasonable bump rationale: API path changes are breaking by
    definition, so 0.1.0 → 0.2.0 (pre-1.0 license to bump minor on
    any breaking change). SDK starts at 1.0 because scripts depend
    on it more strictly than the product depends on its internals;
    we'd rather promise SDK stability early than pull the rug.

Verified live:
  * /healthz → "ok" (plain text)
  * /version → {product:"0.2.0",sdk:"1.0",api:1,schema:1,wire:1}
  * /api/v1/admin/scripts → 200
  * /api/admin/scripts → 404 with error JSON (sunset major)
  * Script can read ctx.sdk_version → "1.0"
  * All 14 integration tests pass against new paths
  * 11 executor-core unit tests pass (added one for sdk_version
    exposure with the major.minor format invariant)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crates/picloud/tests/api.rs

@@ -42,7 +42,7 @@ async fn healthz_responds_ok(pool: PgPool) {
 async fn create_script_returns_201_with_full_record(pool: PgPool) {
     let s = server(pool);
     let r = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({
             "name": "echo",
             "description": "test",
@@ -61,7 +61,7 @@ async fn create_script_returns_201_with_full_record(pool: PgPool) {
 #[sqlx::test(migrations = "../manager-core/migrations")]
 async fn create_with_invalid_syntax_returns_422(pool: PgPool) {
     let r = server(pool)
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({ "name": "broken", "source": "@@@ not rhai @@@" }))
         .await;
     r.assert_status(axum::http::StatusCode::UNPROCESSABLE_ENTITY);
@@ -73,12 +73,12 @@ async fn create_with_invalid_syntax_returns_422(pool: PgPool) {
 #[sqlx::test(migrations = "../manager-core/migrations")]
 async fn duplicate_name_returns_409(pool: PgPool) {
     let s = server(pool);
-    s.post("/api/admin/scripts")
+    s.post("/api/v1/admin/scripts")
         .json(&json!({ "name": "dup", "source": "42" }))
         .await
         .assert_status(axum::http::StatusCode::CREATED);
     let r = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({ "name": "dup", "source": "43" }))
         .await;
     r.assert_status(axum::http::StatusCode::CONFLICT);
@@ -89,12 +89,12 @@ async fn duplicate_name_returns_409(pool: PgPool) {
 async fn list_returns_all_scripts(pool: PgPool) {
     let s = server(pool);
     for name in ["alpha", "bravo", "charlie"] {
-        s.post("/api/admin/scripts")
+        s.post("/api/v1/admin/scripts")
             .json(&json!({ "name": name, "source": "1" }))
             .await
             .assert_status(axum::http::StatusCode::CREATED);
     }
-    let r = s.get("/api/admin/scripts").await;
+    let r = s.get("/api/v1/admin/scripts").await;
     r.assert_status_ok();
     let body: Vec<Value> = r.json();
     assert_eq!(body.len(), 3);
@@ -107,14 +107,14 @@ async fn list_returns_all_scripts(pool: PgPool) {
 async fn update_bumps_version_and_persists_changes(pool: PgPool) {
     let s = server(pool);
     let created: Value = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({ "name": "u", "source": "1" }))
         .await
         .json();
     let id = created["id"].as_str().unwrap();
 
     let r = s
-        .put(&format!("/api/admin/scripts/{id}"))
+        .put(&format!("/api/v1/admin/scripts/{id}"))
         .json(&json!({ "source": "#{ statusCode: 200, body: \"v2\" }", "timeout_seconds": 60 }))
         .await;
     r.assert_status_ok();
@@ -129,14 +129,14 @@ async fn update_bumps_version_and_persists_changes(pool: PgPool) {
 async fn update_with_invalid_source_returns_422(pool: PgPool) {
     let s = server(pool);
     let created: Value = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({ "name": "u", "source": "1" }))
         .await
         .json();
     let id = created["id"].as_str().unwrap();
 
     let r = s
-        .put(&format!("/api/admin/scripts/{id}"))
+        .put(&format!("/api/v1/admin/scripts/{id}"))
         .json(&json!({ "source": "@@@ broken @@@" }))
         .await;
     r.assert_status(axum::http::StatusCode::UNPROCESSABLE_ENTITY);
@@ -147,17 +147,17 @@ async fn update_with_invalid_source_returns_422(pool: PgPool) {
 async fn delete_then_get_returns_404(pool: PgPool) {
     let s = server(pool);
     let created: Value = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({ "name": "d", "source": "1" }))
         .await
         .json();
     let id = created["id"].as_str().unwrap();
 
-    s.delete(&format!("/api/admin/scripts/{id}"))
+    s.delete(&format!("/api/v1/admin/scripts/{id}"))
         .await
         .assert_status(axum::http::StatusCode::NO_CONTENT);
 
-    s.get(&format!("/api/admin/scripts/{id}"))
+    s.get(&format!("/api/v1/admin/scripts/{id}"))
         .await
         .assert_status_not_found();
 }
@@ -166,7 +166,7 @@ async fn delete_then_get_returns_404(pool: PgPool) {
 #[sqlx::test(migrations = "../manager-core/migrations")]
 async fn get_nonexistent_returns_404(pool: PgPool) {
     let r = server(pool)
-        .get("/api/admin/scripts/00000000-0000-0000-0000-000000000000")
+        .get("/api/v1/admin/scripts/00000000-0000-0000-0000-000000000000")
         .await;
     r.assert_status_not_found();
 }
@@ -180,7 +180,7 @@ async fn get_nonexistent_returns_404(pool: PgPool) {
 async fn execute_echoes_body_back(pool: PgPool) {
     let s = server(pool);
     let created: Value = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({
             "name": "echo",
             "source": "#{ statusCode: 200, body: ctx.request.body }",
@@ -190,7 +190,7 @@ async fn execute_echoes_body_back(pool: PgPool) {
     let id = created["id"].as_str().unwrap();
 
     let r = s
-        .post(&format!("/api/execute/{id}"))
+        .post(&format!("/api/v1/execute/{id}"))
         .json(&json!({ "n": 42 }))
         .await;
     r.assert_status_ok();
@@ -203,7 +203,7 @@ async fn execute_echoes_body_back(pool: PgPool) {
 async fn execute_passes_through_status_and_headers(pool: PgPool) {
     let s = server(pool);
     let created: Value = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({
             "name": "header-test",
             "source": "#{ statusCode: 201, headers: #{ \"x-tag\": \"on\" }, body: 1 }",
@@ -212,7 +212,10 @@ async fn execute_passes_through_status_and_headers(pool: PgPool) {
         .json();
     let id = created["id"].as_str().unwrap();
 
-    let r = s.post(&format!("/api/execute/{id}")).json(&json!({})).await;
+    let r = s
+        .post(&format!("/api/v1/execute/{id}"))
+        .json(&json!({}))
+        .await;
     r.assert_status(axum::http::StatusCode::CREATED);
     assert_eq!(r.header("x-tag"), "on");
 }
@@ -221,7 +224,7 @@ async fn execute_passes_through_status_and_headers(pool: PgPool) {
 #[sqlx::test(migrations = "../manager-core/migrations")]
 async fn execute_nonexistent_returns_404(pool: PgPool) {
     let r = server(pool)
-        .post("/api/execute/00000000-0000-0000-0000-000000000000")
+        .post("/api/v1/execute/00000000-0000-0000-0000-000000000000")
         .json(&json!({}))
         .await;
     r.assert_status_not_found();
@@ -232,7 +235,7 @@ async fn execute_nonexistent_returns_404(pool: PgPool) {
 async fn execution_logs_capture_invocations(pool: PgPool) {
     let s = server(pool);
     let created: Value = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({
             "name": "logger",
             "source": "log::info(\"called\", #{ marker: 7 }); #{ statusCode: 200, body: \"done\" }",
@@ -242,22 +245,25 @@ async fn execution_logs_capture_invocations(pool: PgPool) {
     let id = created["id"].as_str().unwrap();
 
     // No logs yet.
-    let r = s.get(&format!("/api/admin/scripts/{id}/logs")).await;
+    let r = s.get(&format!("/api/v1/admin/scripts/{id}/logs")).await;
     r.assert_status_ok();
     let logs: Vec<Value> = r.json();
     assert!(logs.is_empty());
 
     // Two invocations.
-    s.post(&format!("/api/execute/{id}"))
+    s.post(&format!("/api/v1/execute/{id}"))
         .json(&json!({ "first": true }))
         .await
         .assert_status_ok();
-    s.post(&format!("/api/execute/{id}"))
+    s.post(&format!("/api/v1/execute/{id}"))
         .json(&json!({ "second": true }))
         .await
         .assert_status_ok();
 
-    let logs: Vec<Value> = s.get(&format!("/api/admin/scripts/{id}/logs")).await.json();
+    let logs: Vec<Value> = s
+        .get(&format!("/api/v1/admin/scripts/{id}/logs"))
+        .await
+        .json();
     assert_eq!(logs.len(), 2);
 
     // Most-recent-first ordering.
@@ -282,7 +288,7 @@ async fn execution_logs_capture_invocations(pool: PgPool) {
 async fn execution_errors_are_still_logged(pool: PgPool) {
     let s = server(pool);
     let created: Value = s
-        .post("/api/admin/scripts")
+        .post("/api/v1/admin/scripts")
         .json(&json!({
             "name": "boom",
             "source": "1 / 0",
@@ -291,10 +297,16 @@ async fn execution_errors_are_still_logged(pool: PgPool) {
         .json();
     let id = created["id"].as_str().unwrap();
 
-    let r = s.post(&format!("/api/execute/{id}")).json(&json!({})).await;
+    let r = s
+        .post(&format!("/api/v1/execute/{id}"))
+        .json(&json!({}))
+        .await;
     r.assert_status(axum::http::StatusCode::BAD_GATEWAY);
 
-    let logs: Vec<Value> = s.get(&format!("/api/admin/scripts/{id}/logs")).await.json();
+    let logs: Vec<Value> = s
+        .get(&format!("/api/v1/admin/scripts/{id}/logs"))
+        .await
+        .json();
     assert_eq!(logs.len(), 1);
     assert_eq!(logs[0]["status"], "error");
     assert!(logs[0]["response_body"]["error"].is_string());