feat(vz): add runtime primitive conformance parity matrix

Author: lightsofapollo

.beads/issues.jsonl

@@ -22,15 +22,87 @@ on:
         default: false
         type: boolean
   schedule:
-    - cron: "0 8 * * 1"
+    - cron: "0 8 * * *"
 
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
 
 jobs:
-  vm-e2e:
-    name: Real VM Sandbox E2E
+  vm-e2e-smoke:
+    name: VM E2E Smoke Lane
+    if: github.event_name == 'schedule'
+    runs-on: [self-hosted, macOS, ARM64]
+    timeout-minutes: 240
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: crates
+
+      - name: Run sandbox VM E2E harness
+        run: |
+          PROFILE="${{ github.event.inputs.profile }}"
+          if [[ -z "$PROFILE" ]]; then
+            PROFILE="debug"
+          fi
+          SUITES="sandbox"
+
+          ./scripts/run-sandbox-vm-e2e.sh \
+            --suite "$SUITES" \
+            --profile "$PROFILE" \
+            --output-dir "$RUNNER_TEMP/sandbox-vm-e2e-smoke"
+
+      - name: Upload VM E2E artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: sandbox-vm-e2e-smoke-artifacts
+          path: ${{ runner.temp }}/sandbox-vm-e2e-smoke
+          if-no-files-found: warn
+
+  vm-e2e-nightly-full:
+    name: VM E2E Nightly Full Lane
+    if: github.event_name == 'schedule'
+    runs-on: [self-hosted, macOS, ARM64]
+    timeout-minutes: 480
+    needs: vm-e2e-smoke
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: crates
+
+      - name: Run sandbox VM E2E full lane
+        run: |
+          PROFILE="${{ github.event.inputs.profile }}"
+          if [[ -z "$PROFILE" ]]; then
+            PROFILE="debug"
+          fi
+          ./scripts/run-sandbox-vm-e2e.sh \
+            --suite all \
+            --profile "$PROFILE" \
+            --output-dir "$RUNNER_TEMP/sandbox-vm-e2e-full"
+
+      - name: Upload VM E2E artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: sandbox-vm-e2e-nightly-full-artifacts
+          path: ${{ runner.temp }}/sandbox-vm-e2e-full
+          if-no-files-found: warn
+
+  vm-e2e-manual:
+    name: VM E2E Manual
+    if: github.event_name == 'workflow_dispatch'
     runs-on: [self-hosted, macOS, ARM64]
     timeout-minutes: 240
 

.github/workflows/vm-e2e.yml

@@ -160,6 +160,10 @@ Full VM lanes (runtime + stack + buildkit):
 
 See `docs/sandbox-vm-e2e.md` for reproducible debug workflow and artifact paths.
 
+Conformance and parity coverage:
+
+- [Runtime primitive conformance matrix](docs/runtime-primitive-conformance.md)
+
 ## License
 
 [MIT](LICENSE.md)

README.md

@@ -392,6 +392,7 @@ mod tests {
     use super::*;
     use axum::body::{Body, to_bytes};
     use axum::http::Request;
+    use std::collections::BTreeSet;
     use tempfile::tempdir;
     use tower::ServiceExt;
     use vz_stack::StackEvent;
@@ -409,6 +410,13 @@ mod tests {
         }
     }
 
+    fn sample_openapi_path(path: &str) -> String {
+        match path {
+            "/v1/events/{stack_name}" => "/v1/events/runtime-conformance-stack".to_string(),
+            _ => path.to_string(),
+        }
+    }
+
     #[test]
     fn openapi_document_contains_required_paths() {
         let document = openapi_document();
@@ -598,4 +606,80 @@ mod tests {
         assert!(paths.contains_key("/v1/events/{stack_name}/stream"));
         assert!(paths.contains_key("/v1/events/{stack_name}/ws"));
     }
+
+    #[tokio::test]
+    async fn transport_parity_openapi_matrix_paths_match_contract() {
+        let document = openapi_document();
+        let paths = document["paths"].as_object().unwrap();
+        let mut matrix_paths = BTreeSet::new();
+
+        for entry in vz_runtime_contract::PRIMITIVE_CONFORMANCE_MATRIX {
+            if let Some(surface) = entry.openapi {
+                assert!(!surface.path.is_empty());
+                assert!(surface.path.starts_with('/'));
+                assert!(!surface.surface.is_empty());
+                assert!(
+                    paths.contains_key(surface.path),
+                    "missing OpenAPI path `{}` for `{}`",
+                    surface.path,
+                    entry.operation.as_str()
+                );
+                matrix_paths.insert(surface.path);
+            }
+        }
+
+        assert!(!matrix_paths.is_empty());
+    }
+
+    #[tokio::test]
+    async fn transport_parity_openapi_surface_errors_match_runtime_operation_labels() {
+        let temp_dir = tempdir().unwrap();
+        let state_path = temp_dir.path().join("state.db");
+        StateStore::open(&state_path).unwrap();
+
+        let app = router(test_config(state_path));
+
+        for entry in vz_runtime_contract::PRIMITIVE_CONFORMANCE_MATRIX {
+            let Some(surface) = entry.openapi else {
+                continue;
+            };
+
+            let request = Request::builder()
+                .uri(sample_openapi_path(surface.path))
+                .body(Body::empty())
+                .unwrap();
+            let response = app.clone().oneshot(request).await.unwrap();
+            let status = response.status();
+
+            if status == StatusCode::NOT_IMPLEMENTED {
+                let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+                let envelope: MachineErrorEnvelope = serde_json::from_slice(&body).unwrap();
+
+                assert_eq!(
+                    envelope.error.code,
+                    vz_runtime_contract::MachineErrorCode::UnsupportedOperation
+                );
+                assert_eq!(
+                    envelope.error.details.get("operation").map(String::as_str),
+                    Some(surface.surface),
+                    "matrix operation mismatch for `{}` at `{}`",
+                    entry.operation.as_str(),
+                    surface.path
+                );
+                continue;
+            }
+
+            if status == StatusCode::OK
+                && matches!(surface.path, "/v1/capabilities" | "/v1/events/{stack_name}")
+            {
+                continue;
+            }
+
+            panic!(
+                "unexpected matrix API status for `{}` at `{}`: {status}",
+                entry.operation.as_str(),
+                surface.path
+            );
+        }
+    }
 }

crates/vz-api/src/lib.rs

@@ -2810,6 +2810,29 @@ mod tests {
         assert!(no_key.is_none());
     }
 
+    #[test]
+    fn cli_transport_parity_matrix_is_claimed_for_idempotency_behavior() {
+        let components = ["stack-a", "web-service", "echo_hello"];
+        for entry in vz_runtime_contract::PRIMITIVE_CONFORMANCE_MATRIX {
+            if !entry.cli {
+                continue;
+            }
+
+            let key = runtime_idempotency_key(entry.operation, &components);
+            let expected = entry
+                .operation
+                .idempotency_key_prefix()
+                .map(|prefix| format!("{prefix}:stack-a:web-service:echo_hello"));
+
+            assert_eq!(
+                key,
+                expected,
+                "CLI parity key mismatch for {}",
+                entry.operation.as_str()
+            );
+        }
+    }
+
     #[test]
     fn control_request_idempotency_key_is_deterministic() {
         let key = control_request_idempotency_key(

crates/vz-cli/src/commands/stack.rs

@@ -157,10 +157,10 @@ impl GrpcAgentClient {
         operation: Option<RuntimeOperation>,
     ) -> ProtoTransportMetadata {
         self.next_request_sequence = self.next_request_sequence.saturating_add(1);
-        let request_id = format!("req_{:016x}", self.next_request_sequence);
-        let idempotency_key = operation
-            .and_then(RuntimeOperation::idempotency_key_prefix)
-            .map(|prefix| format!("{prefix}:{request_id}"));
+        let (request_id, idempotency_key) = vz_runtime_contract::transport_metadata_for_sequence(
+            self.next_request_sequence,
+            operation,
+        );
         let normalized = ContractRequestMetadata::new(Some(request_id), idempotency_key);
 
         ProtoTransportMetadata {
@@ -843,4 +843,36 @@ mod tests {
                 .unwrap_err();
         assert!(err.to_string().contains("request_id mismatch"));
     }
+
+    #[test]
+    fn transport_parity_grpc_metadata_generation_is_stable_for_matrixed_operations() {
+        let mut expected_sequence = 0u64;
+        for entry in vz_runtime_contract::PRIMITIVE_CONFORMANCE_MATRIX {
+            if !entry.grpc_metadata {
+                continue;
+            }
+
+            let (expected_request_id, expected_key) =
+                vz_runtime_contract::transport_metadata_for_sequence(
+                    expected_sequence,
+                    Some(entry.operation),
+                );
+            expected_sequence = expected_sequence.saturating_add(1);
+
+            let expected_prefix = entry
+                .operation
+                .idempotency_key_prefix()
+                .map(|prefix| format!("{prefix}:{expected_request_id}"));
+            assert_eq!(expected_key, expected_prefix);
+
+            assert_eq!(
+                expected_request_id,
+                format!("req_{:016x}", expected_sequence),
+                "request id sequence mismatch for {}",
+                entry.operation.as_str()
+            );
+        }
+
+        assert!(expected_sequence > 0);
+    }
 }