Skip to main content

vibescript_abi/
effects.rs

1//! Effect bitflags (`EffectSet`), determinism and reversibility classifications,
2//! bounded resource envelopes (`ResourceEnvelope`), and explicit execution modes (`ExecutionMode`).
3
4/// Composable effect bitflags for extension functions.
5#[repr(transparent)]
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
7pub struct EffectSet(pub u32);
8
9impl EffectSet {
10    /// Pure deterministic calculation with zero side effects or state reads.
11    pub const PURE_COMPUTE: Self = Self(0);
12    /// Reads from the semantic graph or snapshot without mutation.
13    pub const GRAPH_READ: Self = Self(1 << 0);
14    /// Stages or mutates state in the semantic graph.
15    pub const GRAPH_MUTATE: Self = Self(1 << 1);
16    /// Interacts with local hardware devices (GPU compute queue, HID, audio, sensors).
17    pub const HARDWARE_IO: Self = Self(1 << 2);
18    /// Performs external network disclosure or transport publish.
19    pub const EXTERNAL_NET: Self = Self(1 << 3);
20    /// Accesses cryptographic key vault operations (signing, key generation).
21    pub const CRYPTO_VAULT: Self = Self(1 << 4);
22    /// Spawns bounded child tasks or DAG nodes.
23    pub const TASK_SPAWN: Self = Self(1 << 5);
24
25    /// Combines two `EffectSet` masks.
26    #[inline]
27    pub const fn union(self, other: Self) -> Self {
28        Self(self.0 | other.0)
29    }
30
31    /// Returns `true` if `self` has no side effects (`PURE_COMPUTE`).
32    #[inline]
33    pub const fn is_pure(self) -> bool {
34        self.0 == 0
35    }
36
37    /// Returns `true` if `self` contains all effects in `required`.
38    #[inline]
39    pub const fn contains_all(self, required: Self) -> bool {
40        (self.0 & required.0) == required.0
41    }
42
43    /// Returns `true` if `self` is a subset of `allowed_mask`.
44    #[inline]
45    pub const fn is_subset_of(self, allowed_mask: Self) -> bool {
46        (self.0 & !allowed_mask.0) == 0
47    }
48}
49
50/// Determinism guarantee declared by an extension function.
51#[repr(u8)]
52#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
53pub enum DeterminismGuarantee {
54    /// Bit-exact across all target architectures (integer/fixed-point/exact hash).
55    DeterministicExact = 0,
56    /// Deterministic within a bounded IEEE-754 floating-point ULPs / tolerance envelope.
57    DeterministicTolerance = 1,
58    /// Depends on external clocks, hardware sensors, or network state; requires replay receipt.
59    NonDeterministicExternal = 2,
60}
61
62/// Reversibility / undo contract for an extension function.
63#[repr(u8)]
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
65pub enum ReversibilityKind {
66    /// Pure computation; mutates no external or graph state.
67    PureNoState = 0,
68    /// Mutates staged snapshot state that can be cleanly aborted before commit.
69    StagedReversible = 1,
70    /// Requires an explicit compensating action to undo after commit.
71    CompensatingAction = 2,
72    /// Irreversible external disclosure or hardware actuation.
73    IrreversibleExternal = 3,
74}
75
76/// Synchronous vs bounded-async execution classification.
77#[repr(u8)]
78#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
79pub enum AsyncExecutionClass {
80    /// Completes synchronously within the caller's frame and tick budget.
81    SynchronousBounded = 0,
82    /// Schedules a bounded asynchronous job monitored by a lease ticket.
83    AsyncBoundedTask = 1,
84}
85
86/// Worst-case resource budget declared by an extension function and enforced by the Sentinel.
87#[repr(C)]
88#[derive(Debug, Clone, Copy, PartialEq, Eq)]
89pub struct ResourceEnvelope {
90    /// Maximum logical instruction / evaluator ticks consumed per invocation.
91    pub max_ticks: u64,
92    /// Maximum cold/scratch arena bytes required (`0` for Tier-1 `HotZeroHeap`).
93    pub max_scratch_bytes: u32,
94    /// Maximum GPU VRAM bytes required (`0` for CPU-only calls).
95    pub max_vram_bytes: u32,
96    /// Maximum output buffer bytes written (`<= CallerOutputSlice` capacity).
97    pub max_output_bytes: u32,
98    /// Maximum child tasks spawned (`0` for leaf calls).
99    pub max_spawned_tasks: u16,
100    /// Reserved flags (`0`).
101    pub flags: u16,
102}
103
104impl ResourceEnvelope {
105    /// `ResourceEnvelope::flags` bit indicating `AsyncExecutionClass::AsyncBoundedTask`.
106    pub const FLAG_ASYNC_BOUNDED_TASK: u16 = 1 << 0;
107
108    /// Default Tier-1 zero-heap compute envelope (`max_scratch_bytes = 0`, `max_vram_bytes = 0`).
109    #[inline]
110    pub const fn hot_zero_heap(max_ticks: u64, max_output_bytes: u32) -> Self {
111        Self {
112            max_ticks,
113            max_scratch_bytes: 0,
114            max_vram_bytes: 0,
115            max_output_bytes,
116            max_spawned_tasks: 0,
117            flags: 0,
118        }
119    }
120
121    /// Returns the synchronous vs bounded-async execution class encoded in `flags`.
122    #[inline]
123    pub const fn async_class(&self) -> AsyncExecutionClass {
124        if (self.flags & Self::FLAG_ASYNC_BOUNDED_TASK) != 0 {
125            AsyncExecutionClass::AsyncBoundedTask
126        } else {
127            AsyncExecutionClass::SynchronousBounded
128        }
129    }
130
131    /// Returns a copy of this envelope with `AsyncExecutionClass` encoded in `flags`.
132    #[inline]
133    pub const fn with_async_class(mut self, class: AsyncExecutionClass) -> Self {
134        match class {
135            AsyncExecutionClass::SynchronousBounded => {
136                self.flags &= !Self::FLAG_ASYNC_BOUNDED_TASK;
137            }
138            AsyncExecutionClass::AsyncBoundedTask => {
139                self.flags |= Self::FLAG_ASYNC_BOUNDED_TASK;
140            }
141        }
142        self
143    }
144
145    /// Checks whether this envelope fits within `budget`.
146    #[inline]
147    pub const fn fits_within(&self, budget: &ResourceEnvelope) -> bool {
148        self.max_ticks <= budget.max_ticks
149            && self.max_scratch_bytes <= budget.max_scratch_bytes
150            && self.max_vram_bytes <= budget.max_vram_bytes
151            && self.max_output_bytes <= budget.max_output_bytes
152            && self.max_spawned_tasks <= budget.max_spawned_tasks
153    }
154}
155
156/// Target hardware/runtime profiles supported by a provider.
157#[repr(transparent)]
158#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
159pub struct TargetProfileMask(pub u16);
160
161impl TargetProfileMask {
162    pub const NATIVE_DESKTOP: Self = Self(1 << 0);
163    pub const WASM_SANDBOX: Self = Self(1 << 1);
164    pub const EDGE_EMBEDDED: Self = Self(1 << 2);
165    pub const GPU_COMPUTE: Self = Self(1 << 3);
166    pub const ALL_CPU: Self =
167        Self(Self::NATIVE_DESKTOP.0 | Self::WASM_SANDBOX.0 | Self::EDGE_EMBEDDED.0);
168
169    #[inline]
170    pub const fn supports(self, target: Self) -> bool {
171        (self.0 & target.0) == target.0
172    }
173}
174
175/// Explicit execution mode governing Sentinel policy enforcement and receipt semantics.
176#[repr(u8)]
177#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
178pub enum ExecutionMode {
179    /// Production governed application mode. Requires a live `SentinelPolicyGate`;
180    /// missing or disconnected controller fails closed (`VibeTrap::SentinelUnavailable`).
181    GovernedApplication = 0,
182    /// Standalone developer / CLI / REPL mode. Runs `PureCompute` (and explicitly
183    /// mocked local scratch) without claiming governed authority.
184    StandaloneDeveloper = 1,
185    /// Deterministic in-memory policy table for unit and conformance tests.
186    /// Receipts are explicitly marked `simulated = true`.
187    SimulatedGovernanceTest = 2,
188    /// End-to-end integration test mode wired to the real QualiaDB Webizen Sentinel
189    /// and staged `PoetSnapshot` receipt pipeline.
190    IntegratedGovernanceTest = 3,
191}
192
193impl ExecutionMode {
194    /// Returns `true` when a live `SentinelPolicyGate` is mandatory.
195    #[inline]
196    pub const fn requires_sentinel_gate(self) -> bool {
197        matches!(
198            self,
199            Self::GovernedApplication
200                | Self::SimulatedGovernanceTest
201                | Self::IntegratedGovernanceTest
202        )
203    }
204}