deepstrike_core/syscall/mod.rs
1//! Primitive P1: the single syscall trap boundary.
2//!
3//! Every variant of [`Syscall`] has a live gate call site; this is wiring, not a type scaffold.
4//! `evaluate_syscall` ([`crate::scheduler::state_machine`]'s `gate.rs`) is the one adjudicator, and
5//! it is reached from:
6//!
7//! * [`Syscall::Invoke`] — the governance pipeline, from `gate_tool_calls`;
8//! * [`Syscall::Spawn`] — `state_machine/process.rs`'s `spawn_sub_agent`, and the workflow run
9//! queue's deferrable variant in `spawn_ready_workflow_nodes`;
10//! * [`Syscall::WriteMemory`] — the `WriteMemory` trap in `runtime/kernel/runtime.rs`, and the
11//! canonical driver's `RequestMemoryWrite` reduction;
12//! * [`Syscall::SubmitNodes`] / [`Syscall::LoadWorkflow`] — `state_machine/workflow.rs`'s
13//! `append_workflow_nodes` and `submit_workflow`'s bootstrap arm.
14//!
15//! **Who the caller is, is not on this type.** A `Syscall` carries only *what* is asked. The
16//! canonical ABI derives the caller from kernel-owned causation — a tool call inside the provider
17//! result being resolved, or a kernel-issued child attempt (spec §7.6) — and refuses the request
18//! before this gate is reached when that derivation fails. There is no host-declared actor, and
19//! adding one to this enum would reintroduce exactly the bypass §22.10 rejects.
20//!
21//! Concept overlap this primitive collapses: the two parallel decision vocabularies
22//! ([`crate::types::policy::GovernanceVerdict`] and `SignalDisposition`). Tool/spawn/memory
23//! decisions converge on [`Disposition`]; signals feed the P2 scheduler instead.
24
25use crate::mm::memory::MemoryRecord;
26use crate::types::agent::IsolationManifest;
27use crate::types::message::ToolCall;
28use crate::types::policy::GovernanceVerdict;
29
30/// An effectful request from the SDK that the kernel must adjudicate.
31///
32/// Every side-effecting service request becomes a `Syscall` variant; the opcode is **data**, so
33/// adding a service does not add a new ABI shape (unlike the per-feature `Load*Policy` events today).
34#[derive(Debug, Clone)]
35pub enum Syscall {
36 /// Model-proposed tool call (today: the only thing through the governance gate).
37 Invoke(ToolCall),
38 /// Spawn a sub-agent (today: bypasses the gate).
39 Spawn(IsolationManifest),
40 /// Persist a long-term memory entry.
41 WriteMemory(MemoryRecord),
42 /// R3-1: append `count` nodes to the in-flight workflow DAG at runtime. Gating DAG growth through
43 /// the trap lets a `ResourceQuota` backstop a runaway loop-until-done (denied past
44 /// `max_workflow_nodes`); per-node spawns are still gated separately by `Spawn`.
45 SubmitNodes { count: usize },
46 /// M5/G1: an agent authors a whole workflow `spec` (`node_count` nodes). Bootstraps the DAG when
47 /// none is active, else flattens onto it — either way it is gated by the same `max_workflow_nodes`
48 /// quota as `SubmitNodes` (a spec is just a node batch with a bootstrap fast-path), so an
49 /// agent-authored harness cannot overgrow the DAG past the run's budget.
50 LoadWorkflow { node_count: usize },
51}
52
53/// The kernel's adjudication of a [`Syscall`]. Generalizes [`GovernanceVerdict`]:
54/// `AskUser` becomes [`Disposition::Gate`] (suspend the calling task via the P2 TCB),
55/// which is where this primitive meets P2.
56#[derive(Debug, Clone)]
57pub enum Disposition {
58 /// Proceed as requested.
59 Allow,
60 /// Reject. `stage` names the gate stage that vetoed.
61 Deny { stage: &'static str, reason: String },
62 /// Suspend the calling task until an external party resolves it (e.g. human approval).
63 /// `reason` carries the human-readable justification (e.g. the governance `AskUser` reason).
64 Gate { reason: String },
65 /// Accept but queue for later scheduling (backpressure).
66 Defer { slot: u32 },
67 /// Rejected by a rate limiter; retry permitted after the delay.
68 RateLimited { retry_after_ms: u64 },
69}
70
71impl Disposition {
72 /// Whether the syscall may proceed to execution now.
73 pub fn is_allowed(&self) -> bool {
74 matches!(self, Self::Allow)
75 }
76}
77
78/// Bridge from the existing tool-decision vocabulary. `AskUser` → `Gate(Approval)`: a tool
79/// awaiting human approval suspends the task, which M2+M1 realize via the TCB.
80impl From<GovernanceVerdict> for Disposition {
81 fn from(verdict: GovernanceVerdict) -> Self {
82 match verdict {
83 GovernanceVerdict::Allow => Disposition::Allow,
84 GovernanceVerdict::Deny { stage, reason } => Disposition::Deny { stage, reason },
85 GovernanceVerdict::RateLimited { retry_after_ms } => {
86 Disposition::RateLimited { retry_after_ms }
87 }
88 GovernanceVerdict::AskUser { reason } => Disposition::Gate { reason },
89 }
90 }
91}
92
93#[cfg(test)]
94mod tests {
95 use super::*;
96
97 #[test]
98 fn verdict_allow_maps_to_allow() {
99 let d: Disposition = GovernanceVerdict::Allow.into();
100 assert!(d.is_allowed());
101 }
102
103 #[test]
104 fn verdict_deny_preserves_stage_and_reason() {
105 let d: Disposition = GovernanceVerdict::Deny {
106 stage: "veto",
107 reason: "blocked".into(),
108 }
109 .into();
110 match d {
111 Disposition::Deny { stage, reason } => {
112 assert_eq!(stage, "veto");
113 assert_eq!(reason, "blocked");
114 }
115 other => panic!("expected Deny, got {other:?}"),
116 }
117 assert!(
118 !Disposition::Deny {
119 stage: "veto",
120 reason: String::new()
121 }
122 .is_allowed()
123 );
124 }
125
126 #[test]
127 fn verdict_ask_user_maps_to_gate_approval() {
128 let d: Disposition = GovernanceVerdict::AskUser {
129 reason: "confirm".into(),
130 }
131 .into();
132 assert!(matches!(
133 &d,
134 Disposition::Gate { reason } if reason == "confirm"
135 ));
136 assert!(!d.is_allowed());
137 }
138
139 #[test]
140 fn verdict_rate_limited_preserves_delay() {
141 let d: Disposition = GovernanceVerdict::RateLimited {
142 retry_after_ms: 500,
143 }
144 .into();
145 assert!(matches!(
146 d,
147 Disposition::RateLimited {
148 retry_after_ms: 500
149 }
150 ));
151 }
152}