vtcode_utility_tool_specs/
matrix.rs

1//! Passive schemas for durable local matrix control and attempt-owned reports.
2
3use serde_json::{Value, json};
4
5/// Model-visible description of deterministic matrix orchestration.
6pub const MATRIX_DESCRIPTION: &str = "Manage a durable local task matrix. create persists an explicit specification without launching workers; start freezes it and begins scheduler-owned execution. status shows task/resource/verification progress; pause stops new dispatch, resume reconciles durable state before dispatch, retry requests a coordinator decision for a task, and cancel is terminal. report is worker-only: runtime supplies task and attempt identity and validates durable command evidence. Final success requires every declared check against the final workspace generation; worker summaries are insufficient.";
7
8/// Wire parameters; lifecycle validation and report authorization are runtime-owned.
9#[must_use]
10pub fn matrix_parameters() -> Value {
11    json!({
12        "type": "object",
13        "additionalProperties": false,
14        "required": ["action"],
15        "properties": {
16            "action": {"type": "string", "enum": ["create", "start", "status", "pause", "resume", "retry", "cancel", "report"]},
17            "matrix_id": {"type": "string", "minLength": 1, "description": "Coordinator controls: matrix to inspect or control."},
18            "task_id": {"type": "string", "minLength": 1, "description": "Coordinator retry only: task requiring another attempt. Reports cannot select a task."},
19            "spec": matrix_spec_schema(),
20            "outcome": {"type": "string", "enum": ["executed", "failed", "interrupted", "timed_out", "permission_denied", "budget_exhausted"], "description": "Worker report only; runtime authenticates the current assignment. executed means instructions finished, not final verification success."},
21            "evidence_ids": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Worker report only: canonical durable evidence references; unrelated, stale, or cancelled commands cannot verify success."}
22        }
23    })
24}
25
26fn matrix_spec_schema() -> Value {
27    json!({
28        "type": "object",
29        "additionalProperties": false,
30        "required": ["id", "tasks", "resources"],
31        "properties": {
32            "id": {"type": "string", "minLength": 1},
33            "resources": resource_map_schema(),
34            "tasks": {"type": "array", "minItems": 1, "items": {
35                "type": "object", "additionalProperties": false,
36                "required": ["id", "instructions", "workspace", "access", "checks", "timeout_secs"],
37                "properties": {
38                    "id": {"type": "string", "minLength": 1, "description": "Stable unique task ID."},
39                    "instructions": {"type": "string", "minLength": 1},
40                    "dependencies": {"type": "array", "items": {"type": "string", "minLength": 1}, "default": []},
41                    "workspace": {"type": "string", "minLength": 1, "description": "Session-workspace-relative directory; use . for the root. Absolute paths, traversal, and symlink escapes are rejected."},
42                    "access": {"type": "string", "enum": ["read", "write"], "description": "Readers may overlap; a writer excludes every other matrix task."},
43                    "checks": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}, "description": "Standalone verification commands rerun after execution against the final workspace generation."},
44                    "inputs": {"type": "array", "items": {"type": "string", "minLength": 1}, "default": [], "description": "Declared untracked input files relative to this task's workspace, included with tracked source in the verification fingerprint."},
45                    "resources": resource_map_schema(),
46                    "timeout_secs": {"type": "integer", "minimum": 1},
47                    "replay_safe": {"type": "boolean", "default": false, "description": "Allows one automatic interrupted/timeout retry only after owned work is confirmed stopped."}
48                }
49            }}
50        }
51    })
52}
53
54fn resource_map_schema() -> Value {
55    json!({"type": "object", "additionalProperties": {"type": "integer", "minimum": 1}, "description": "Named resource capacities on the spec, or required quantities on a task; all quantities are positive integers."})
56}
57
58#[cfg(test)]
59mod tests {
60    use super::*;
61
62    #[test]
63    fn matrix_schema_keeps_report_identity_runtime_owned() {
64        let schema = matrix_parameters();
65        assert_eq!(schema["additionalProperties"], false);
66        for forbidden in ["attempt_id", "worker_id", "thread_id", "generation"] {
67            assert!(schema["properties"].get(forbidden).is_none(), "{forbidden}");
68        }
69        assert!(
70            schema["properties"]["task_id"]["description"]
71                .as_str()
72                .unwrap()
73                .contains("retry only")
74        );
75        assert_eq!(
76            schema["properties"]["spec"]["properties"]["tasks"]["items"]["properties"]["replay_safe"]["default"],
77            false
78        );
79    }
80
81    #[test]
82    fn matrix_schema_requires_checks_timeouts_and_positive_resources() {
83        let schema = matrix_parameters();
84        let task = &schema["properties"]["spec"]["properties"]["tasks"]["items"];
85        for field in ["id", "instructions", "workspace", "access", "checks", "timeout_secs"] {
86            assert!(task["required"].as_array().unwrap().contains(&json!(field)), "{field}");
87        }
88        assert_eq!(task["properties"]["checks"]["minItems"], 1);
89        assert_eq!(task["properties"]["resources"]["additionalProperties"]["minimum"], 1);
90        assert_eq!(task["properties"]["timeout_secs"]["minimum"], 1);
91    }
92}
vtcode_utility_tool_specs/matrix.rs

vtcode_utility_tool_specs/
matrix.rs
