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/src/lib.rs

@@ -6,20 +6,27 @@
 use std::sync::Arc;
 use std::time::Duration;
 
-use axum::{routing::get, Router};
+use axum::{routing::get, Json, Router};
 use picloud_executor_core::{Engine, Limits};
 use picloud_manager_core::{
-    admin_router, AdminState, PostgresExecutionLogRepository, PostgresExecutionLogSink,
+    admin_router, migrations, AdminState, PostgresExecutionLogRepository, PostgresExecutionLogSink,
     PostgresScriptRepository, RepoResolver,
 };
 use picloud_orchestrator_core::{data_plane_router, DataPlaneState, LocalExecutorClient};
-use picloud_shared::{ExecutionLogSink, ScriptValidator};
+use picloud_shared::{
+    ExecutionLogSink, ScriptValidator, API_VERSION, PRODUCT_VERSION, SDK_VERSION, WIRE_VERSION,
+};
 use sqlx::postgres::PgPoolOptions;
 use sqlx::PgPool;
 use tower_http::trace::TraceLayer;
 
 /// Compose the manager + orchestrator routes on top of a shared
 /// Postgres pool, returning an Axum router ready to be served.
+///
+/// All API routes live under `/api/v{API_VERSION}/...`. New major
+/// versions get a parallel nest under `/api/v{N+1}/...`; the old
+/// prefix is kept live for at least one product-minor deprecation
+/// window (see `docs/versioning.md`).
 pub fn build_app(pool: PgPool) -> Router {
     let engine = Arc::new(Engine::new(Limits::default()));
 
@@ -43,11 +50,15 @@ pub fn build_app(pool: PgPool) -> Router {
         log_sink,
     };
 
+    let api_v1 = Router::new()
+        .nest("/admin", admin_router(admin))
+        .merge(data_plane_router(data_plane));
+
     Router::new()
         .route("/healthz", get(healthz))
+        .route("/version", get(version))
         .route("/", get(root))
-        .nest("/api/admin", admin_router(admin))
-        .nest("/api", data_plane_router(data_plane))
+        .nest(&format!("/api/v{API_VERSION}"), api_v1)
         .layer(TraceLayer::new_for_http())
 }
 
@@ -67,7 +78,20 @@ async fn healthz() -> &'static str {
 }
 
 async fn root() -> &'static str {
-    "picloud — see /api/admin/* (manager) and /api/execute/* (orchestrator)"
+    "picloud — see /api/v1/admin/* (manager), /api/v1/execute/* (orchestrator), /version"
+}
+
+/// Snapshot of every compatibility-surface version this process speaks.
+/// Documented in `docs/versioning.md`; the source of truth is
+/// `shared::version` plus the embedded migrations.
+async fn version() -> Json<serde_json::Value> {
+    Json(serde_json::json!({
+        "product": PRODUCT_VERSION,
+        "sdk":     SDK_VERSION,
+        "api":     API_VERSION,
+        "schema":  migrations::latest_version(),
+        "wire":    WIRE_VERSION,
+    }))
 }
 
 // ----------------------------------------------------------------------------