vtcode_exec_events/
matrix.rs

1//! Canonical durable contracts for local matrix execution.
2use serde::{Deserialize, Serialize};
3use std::collections::BTreeMap;
4
5#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
7pub struct MatrixSpec {
8    pub id: String,
9    pub tasks: Vec<MatrixTaskSpec>,
10    #[serde(default)]
11    pub resources: BTreeMap<String, u32>,
12}
13
14#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
15#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
16pub struct MatrixTaskSpec {
17    pub id: String,
18    pub instructions: String,
19    #[serde(default)]
20    pub dependencies: Vec<String>,
21    pub workspace: String,
22    pub access: WorkspaceAccess,
23    pub checks: Vec<String>,
24    #[serde(default)]
25    pub resources: BTreeMap<String, u32>,
26    pub timeout_secs: u64,
27    #[serde(default)]
28    pub replay_safe: bool,
29    #[serde(default)]
30    pub inputs: Vec<String>,
31}
32
33#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
34#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
35#[serde(rename_all = "snake_case")]
36pub enum WorkspaceAccess {
37    Read,
38    Write,
39}
40
41#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
42#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
43#[serde(rename_all = "snake_case")]
44pub enum MatrixLifecycle {
45    Created,
46    Running,
47    Paused,
48    Verifying,
49    Succeeded,
50    Cancelled,
51    Blocked,
52}
53
54#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
55#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
56#[serde(rename_all = "snake_case")]
57pub enum MatrixTaskStatus {
58    Queued,
59    Assigned,
60    Executed,
61    Verified,
62    Failed,
63    Interrupted,
64    TimedOut,
65    CleanupUncertain,
66}
67
68#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
69#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
70#[serde(rename_all = "snake_case")]
71pub enum MatrixPhase {
72    Execute,
73    Verify,
74}
75
76#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
77#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
78#[serde(rename_all = "snake_case")]
79pub enum MatrixOutcome {
80    Success,
81    Failed,
82    Interrupted,
83    TimedOut,
84    Cancelled,
85    PermissionDenied,
86    BudgetExhausted,
87}
88
89#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
90#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
91pub struct MatrixCommandEvidence {
92    pub command: String,
93    pub attempt_id: String,
94    pub worker_id: String,
95    pub generation: String,
96    pub event_id: String,
97    pub exit_code: Option<i32>,
98    pub cancelled: bool,
99}
100
101#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
102#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
103pub struct MatrixAttempt {
104    pub id: String,
105    pub worker_id: String,
106    pub phase: MatrixPhase,
107    pub generation: Option<String>,
108    pub launch_requested: bool,
109    pub outcome: Option<MatrixOutcome>,
110    pub cleanup_confirmed: bool,
111    pub evidence: Vec<MatrixCommandEvidence>,
112}
113
114#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
115#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
116pub struct MatrixTaskState {
117    pub id: String,
118    pub status: MatrixTaskStatus,
119    pub attempts: Vec<MatrixAttempt>,
120    pub automatic_retries: u8,
121}
122
123/// A complete checkpoint carried in the canonical event log; derived views replay it.
124#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
125#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
126pub struct MatrixSnapshot {
127    pub spec: MatrixSpec,
128    pub lifecycle: MatrixLifecycle,
129    pub tasks: Vec<MatrixTaskState>,
130    pub generation: Option<String>,
131    pub revision: u64,
132}
133
134/// Runtime-created assignment identity. Workers never choose these identifiers.
135#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
136#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
137pub struct MatrixAssignment {
138    pub task_id: String,
139    pub attempt_id: String,
140    pub worker_id: String,
141    pub phase: MatrixPhase,
142    pub generation: Option<String>,
143}
vtcode_exec_events/matrix.rs

vtcode_exec_events/
matrix.rs
