vcli-runtime: deterministic 10 fps scheduler (plan 3)

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "crates/vcli-input",
     "crates/vcli-ipc",
     "crates/vcli-perception",
+    "crates/vcli-runtime",
     "crates/vcli-store",
 ]
 
@@ -38,6 +39,9 @@ hex = "0.4"
 
 tracing = "0.1"
 
+# Added by vcli-runtime lane
+crossbeam-channel = "0.5"
+
 # Platform-specific (used by vcli-input + vcli-capture)
 core-graphics = { version = "0.24", features = ["highsierra"] }
 core-foundation = "0.10"

crates/vcli-runtime/Cargo.toml

@@ -0,0 +1,77 @@
+[package]
+name        = "vcli-runtime"
+version.workspace     = true
+edition.workspace     = true
+rust-version.workspace= true
+license.workspace     = true
+repository.workspace  = true
+authors.workspace     = true
+description = "Deterministic 10 fps scheduler that wires Capture → Perception → Arbiter → Input for vcli programs."
+
+[dependencies]
+vcli-core        = { path = "../vcli-core" }
+vcli-capture     = { path = "../vcli-capture" }
+vcli-input       = { path = "../vcli-input" }
+vcli-perception  = { path = "../vcli-perception" }
+
+crossbeam-channel = { workspace = true }
+thiserror         = { workspace = true }
+tracing           = { workspace = true }
+serde_json        = { workspace = true }
+
+[dev-dependencies]
+vcli-dsl          = { path = "../vcli-dsl" }
+proptest          = { workspace = true }
+tempfile          = { workspace = true }
+
+[[test]]
+name = "one_shot_watch"
+path = "tests/scenarios/one_shot_watch.rs"
+
+[[test]]
+name = "persistent_watch"
+path = "tests/scenarios/persistent_watch.rs"
+
+[[test]]
+name = "until_predicate"
+path = "tests/scenarios/until_predicate.rs"
+
+[[test]]
+name = "watch_timeout"
+path = "tests/scenarios/watch_timeout.rs"
+
+[[test]]
+name = "while_true_retry"
+path = "tests/scenarios/while_true_retry.rs"
+
+[[test]]
+name = "wait_for_timeout"
+path = "tests/scenarios/wait_for_timeout.rs"
+
+[[test]]
+name = "assert_failure"
+path = "tests/scenarios/assert_failure.rs"
+
+[[test]]
+name = "input_postcondition"
+path = "tests/scenarios/input_postcondition.rs"
+
+[[test]]
+name = "novelty_timeout"
+path = "tests/scenarios/novelty_timeout.rs"
+
+[[test]]
+name = "action_conflict"
+path = "tests/scenarios/action_conflict.rs"
+
+[[test]]
+name = "predicate_dedup"
+path = "tests/scenarios/predicate_dedup.rs"
+
+[[test]]
+name = "elapsed_ms_since_true"
+path = "tests/scenarios/elapsed_ms_since_true.rs"
+
+[[test]]
+name = "daemon_restart_marker"
+path = "tests/scenarios/daemon_restart_marker.rs"

crates/vcli-runtime/build.rs

@@ -0,0 +1,13 @@
+fn main() {
+    #[cfg(target_os = "macos")]
+    {
+        // vcli-runtime pulls in vcli-capture → screencapturekit transitively.
+        // screencapturekit's Swift bridge references libswift_Concurrency.dylib.
+        // vcli-capture sets this rpath for its own artifacts; we repeat it here
+        // so vcli-runtime's test + binary output can load the Swift dylib too.
+        let xcode_swift55_path =
+            "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain\
+             /usr/lib/swift-5.5/macosx";
+        println!("cargo:rustc-link-arg=-Wl,-rpath,{xcode_swift55_path}");
+    }
+}

crates/vcli-runtime/src/arbiter.rs

@@ -0,0 +1,155 @@
+//! Action arbitration. Spec §403.
+
+use vcli_core::program::Priority;
+use vcli_core::ProgramId;
+
+/// One pending action for the arbiter to consider.
+#[derive(Debug, Clone)]
+pub struct Candidate<T> {
+    /// Source program.
+    pub program_id: ProgramId,
+    /// Static priority from `program.priority`.
+    pub priority: Priority,
+    /// The action / step payload (opaque to the arbiter).
+    pub payload: T,
+}
+
+/// Outcome of arbitration for one candidate.
+#[derive(Debug, Clone)]
+pub struct Decision<T> {
+    /// Source program.
+    pub program_id: ProgramId,
+    /// Payload (passed through unchanged).
+    pub payload: T,
+    /// True if this payload should dispatch.
+    pub dispatch: bool,
+    /// If not dispatched, the conflicting winner's id.
+    pub loser_of: Option<ProgramId>,
+}
+
+/// Resolve conflicts: at most one dispatch per tick. Ordering:
+/// 1. highest `Priority` wins
+/// 2. tiebreak by lexicographic `ProgramId` (larger wins, for determinism)
+///
+/// If `candidates.len() <= 1` everyone dispatches.
+pub fn resolve<T: Clone>(candidates: Vec<Candidate<T>>) -> Vec<Decision<T>> {
+    if candidates.len() <= 1 {
+        return candidates
+            .into_iter()
+            .map(|c| Decision {
+                program_id: c.program_id,
+                payload: c.payload,
+                dispatch: true,
+                loser_of: None,
+            })
+            .collect();
+    }
+    let winner = candidates
+        .iter()
+        .max_by(|a, b| {
+            a.priority
+                .cmp(&b.priority)
+                .then_with(|| a.program_id.to_string().cmp(&b.program_id.to_string()))
+        })
+        .map(|c| c.program_id)
+        .expect("len > 1 handled above");
+    candidates
+        .into_iter()
+        .map(|c| {
+            let is_winner = c.program_id == winner;
+            Decision {
+                program_id: c.program_id,
+                payload: c.payload,
+                dispatch: is_winner,
+                loser_of: if is_winner { None } else { Some(winner) },
+            }
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn id(n: u8) -> ProgramId {
+        let s = format!("{n:02x}345678-1234-4567-8910-111213141516");
+        s.parse().unwrap()
+    }
+
+    #[test]
+    fn single_candidate_always_dispatches() {
+        let out = resolve(vec![Candidate {
+            program_id: id(1),
+            priority: Priority(0),
+            payload: "a",
+        }]);
+        assert_eq!(out.len(), 1);
+        assert!(out[0].dispatch);
+        assert!(out[0].loser_of.is_none());
+    }
+
+    #[test]
+    fn higher_priority_wins() {
+        let out = resolve(vec![
+            Candidate {
+                program_id: id(1),
+                priority: Priority(0),
+                payload: "a",
+            },
+            Candidate {
+                program_id: id(2),
+                priority: Priority(5),
+                payload: "b",
+            },
+        ]);
+        let dispatched: Vec<_> = out.iter().filter(|d| d.dispatch).collect();
+        assert_eq!(dispatched.len(), 1);
+        assert_eq!(dispatched[0].program_id, id(2));
+        assert_eq!(
+            out.iter().find(|d| !d.dispatch).unwrap().loser_of,
+            Some(id(2))
+        );
+    }
+
+    #[test]
+    fn tie_breaks_by_program_id_lex_desc() {
+        let out = resolve(vec![
+            Candidate {
+                program_id: id(1),
+                priority: Priority(0),
+                payload: "a",
+            },
+            Candidate {
+                program_id: id(2),
+                priority: Priority(0),
+                payload: "b",
+            },
+        ]);
+        let winner = out.iter().find(|d| d.dispatch).unwrap().program_id;
+        assert_eq!(winner, id(2));
+    }
+
+    #[test]
+    fn three_way_drops_two_losers() {
+        let out = resolve(vec![
+            Candidate {
+                program_id: id(1),
+                priority: Priority(3),
+                payload: "a",
+            },
+            Candidate {
+                program_id: id(2),
+                priority: Priority(3),
+                payload: "b",
+            },
+            Candidate {
+                program_id: id(3),
+                priority: Priority(3),
+                payload: "c",
+            },
+        ]);
+        let dispatched: Vec<_> = out.iter().filter(|d| d.dispatch).collect();
+        assert_eq!(dispatched.len(), 1);
+        assert_eq!(dispatched[0].program_id, id(3));
+    }
+}