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}