feat: add vz-stack crate with typed spec model and sqlite state store (B16)

New crate providing the stack control plane foundation:
- StackSpec/ServiceSpec/NetworkSpec/VolumeSpec typed domain model
- SQLite-backed StateStore for desired state, observed state, and events
- No-op apply() entrypoint that persists state and emits lifecycle events
- 26 tests covering round-trip serialization, persistence, idempotency,
  and event streaming

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lightsofapollo

crates/Cargo.lock

@@ -7,6 +7,7 @@ members = [
     "vz-guest-agent",
     "vz-linux",
     "vz-oci",
+    "vz-stack",
 ]
 
 [workspace.package]

crates/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "vz-stack"
+version = "0.1.0"
+description = "Stack control plane for multi-service OCI workloads"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+rusqlite = { version = "0.34", features = ["bundled"] }
+
+[lints]
+workspace = true

crates/vz-stack/Cargo.toml

@@ -0,0 +1,15 @@
+/// Errors produced by `vz-stack` operations.
+#[derive(Debug, thiserror::Error)]
+pub enum StackError {
+    /// State store operation failed.
+    #[error("state store error: {0}")]
+    Store(#[from] rusqlite::Error),
+
+    /// Serialization or deserialization failed.
+    #[error("serialization error: {0}")]
+    Serialization(#[from] serde_json::Error),
+
+    /// Invalid stack specification.
+    #[error("invalid stack spec: {0}")]
+    InvalidSpec(String),
+}

crates/vz-stack/src/error.rs

@@ -0,0 +1,106 @@
+//! Structured event types for stack lifecycle observability.
+
+use serde::{Deserialize, Serialize};
+
+/// Structured event emitted during stack lifecycle operations.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(tag = "type")]
+pub enum StackEvent {
+    /// Reconciliation started for a stack.
+    #[serde(rename = "stack_apply_started")]
+    StackApplyStarted {
+        /// Stack name.
+        stack_name: String,
+        /// Number of services in the spec.
+        services_count: usize,
+    },
+    /// Reconciliation completed for a stack.
+    #[serde(rename = "stack_apply_completed")]
+    StackApplyCompleted {
+        /// Stack name.
+        stack_name: String,
+        /// Number of actions that succeeded.
+        succeeded: usize,
+        /// Number of actions that failed.
+        failed: usize,
+    },
+    /// Reconciliation failed for a stack.
+    #[serde(rename = "stack_apply_failed")]
+    StackApplyFailed {
+        /// Stack name.
+        stack_name: String,
+        /// Error description.
+        error: String,
+    },
+    /// A service is being created.
+    #[serde(rename = "service_creating")]
+    ServiceCreating {
+        /// Stack name.
+        stack_name: String,
+        /// Service name.
+        service_name: String,
+    },
+    /// A service is ready and running.
+    #[serde(rename = "service_ready")]
+    ServiceReady {
+        /// Stack name.
+        stack_name: String,
+        /// Service name.
+        service_name: String,
+        /// Runtime container identifier.
+        runtime_id: String,
+    },
+    /// A service failed to start or crashed.
+    #[serde(rename = "service_failed")]
+    ServiceFailed {
+        /// Stack name.
+        stack_name: String,
+        /// Service name.
+        service_name: String,
+        /// Error description.
+        error: String,
+    },
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+
+    use super::*;
+
+    #[test]
+    fn event_round_trip() {
+        let events = vec![
+            StackEvent::StackApplyStarted {
+                stack_name: "myapp".to_string(),
+                services_count: 3,
+            },
+            StackEvent::StackApplyCompleted {
+                stack_name: "myapp".to_string(),
+                succeeded: 2,
+                failed: 1,
+            },
+            StackEvent::ServiceReady {
+                stack_name: "myapp".to_string(),
+                service_name: "web".to_string(),
+                runtime_id: "ctr-123".to_string(),
+            },
+        ];
+
+        for event in events {
+            let json = serde_json::to_string(&event).unwrap();
+            let deserialized: StackEvent = serde_json::from_str(&json).unwrap();
+            assert_eq!(deserialized, event);
+        }
+    }
+
+    #[test]
+    fn event_tag_serialization() {
+        let event = StackEvent::StackApplyStarted {
+            stack_name: "test".to_string(),
+            services_count: 1,
+        };
+        let json = serde_json::to_string(&event).unwrap();
+        assert!(json.contains("\"type\":\"stack_apply_started\""));
+    }
+}

crates/vz-stack/src/events.rs

@@ -0,0 +1,22 @@
+//! Stack control plane for multi-service OCI workloads.
+//!
+//! Provides a typed [`StackSpec`] model, a durable SQLite-backed
+//! [`StateStore`], and an [`apply`] entrypoint that persists desired
+//! and observed state for idempotent reconciliation.
+
+#![forbid(unsafe_code)]
+
+mod error;
+mod events;
+mod reconcile;
+mod spec;
+mod state_store;
+
+pub use error::StackError;
+pub use events::StackEvent;
+pub use reconcile::{ApplyResult, apply};
+pub use spec::{
+    HealthCheckSpec, MountSpec, NetworkSpec, PortSpec, ResourcesSpec, RestartPolicy, ServiceSpec,
+    StackSpec, VolumeSpec,
+};
+pub use state_store::{ServiceObservedState, ServicePhase, StateStore};