Skip to main content

vibescript_abi/
lifecycle.rs

1//! Six-stage governed execution lifecycle (`Register -> Prepare -> Admit -> Execute -> Validate -> Commit/Abort`),
2//! deterministic trap taxonomy (`VibeTrap`), and `SentinelPolicyGate`.
3
4use crate::effects::{AsyncExecutionClass, EffectSet, ExecutionMode, ResourceEnvelope};
5use crate::identity::{PreparedCallHandle, RegistryGeneration, StableFuncId, VibeOpCode};
6use crate::memory::NQuin48;
7
8/// Stage at which an extension lifecycle failure occurred.
9#[repr(u8)]
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
11pub enum FailureStage {
12    Register = 1,
13    Prepare = 2,
14    Admit = 3,
15    Execute = 4,
16    Validate = 5,
17    CommitReceipt = 6,
18}
19
20/// Deterministic, zero-allocation trap code returned across the extension boundary.
21#[repr(u16)]
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
23pub enum VibeTrap {
24    // Registration stage (100..199)
25    RegistryCapacityExceeded = 100,
26    InvalidCanonicalIri = 101,
27    HashMismatch = 102,
28    DuplicateNamespaceIri = 103,
29    DuplicateShortAlias = 104,
30    DuplicateFunctionIri = 105,
31    DuplicateStableFuncId = 106,
32    HashCollisionDetected = 107,
33    IncompatibleVersionAxes = 108,
34    OntologyBudgetExceeded = 109,
35    InvalidOntologySpan = 110,
36    InvalidQuinParity = 111,
37
38    // Preparation stage (200..299)
39    NamespaceNotFound = 200,
40    FunctionNotFound = 201,
41    VersionRequirementUnsatisfied = 202,
42    TargetProfileUnsupported = 203,
43    StaleRegistryGeneration = 204,
44    ContractDigestMismatch = 205,
45
46    // Admission stage (300..399)
47    SentinelUnavailable = 300,
48    PolicyDenied = 301,
49    ExplicitDenyRule = 302,
50    AuthorityExpired = 303,
51    DelegationScopeMismatch = 304,
52    RevokedPolicyGeneration = 305,
53    EffectNotPermittedInMode = 306,
54    ResourceEnvelopeExceeded = 307,
55    PreconditionFailed = 308,
56
57    // Execution & memory stage (400..499)
58    ArityMismatch = 400,
59    TypeMismatch = 401,
60    SliceBoundsOverflow = 402,
61    SliceLengthMismatch = 403,
62    OutputBufferTooSmall = 404,
63    InvalidResourceHandleOwner = 405,
64    StaleResourceHandleGeneration = 406,
65    TickBudgetExhausted = 407,
66    NumericalDomainError = 408,
67
68    // Validation & Commit/Receipt stage (500..599)
69    PostconditionFailed = 500,
70    MidExecutionPolicyRevoked = 501,
71    ReceiptPersistenceFailed = 502,
72    StagingAbortRequired = 503,
73}
74
75impl VibeTrap {
76    /// Returns the lifecycle stage associated with this trap.
77    #[inline]
78    pub const fn stage(self) -> FailureStage {
79        let code = self as u16;
80        if code < 200 {
81            FailureStage::Register
82        } else if code < 300 {
83            FailureStage::Prepare
84        } else if code < 400 {
85            FailureStage::Admit
86        } else if code < 500 {
87            FailureStage::Execute
88        } else if code < 502 {
89            FailureStage::Validate
90        } else {
91            FailureStage::CommitReceipt
92        }
93    }
94}
95
96/// Terminal completion status recorded in an `ExecutionReceiptHeader`.
97#[repr(u8)]
98#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
99pub enum CompletionStatus {
100    /// Governed call admitted, validated, receipt persisted, and state committed.
101    Committed = 1,
102    /// Simulated governance test call completed (receipt flagged `simulated = true`).
103    SimulatedCommitted = 2,
104    /// Standalone developer call completed (no governed authority claimed).
105    StandaloneCompleted = 3,
106    /// Rejected during `Admit` by the Sentinel policy gate.
107    AbortedPolicyDenied = 4,
108    /// Rejected during `Validate` (postcondition or mid-call policy revocation); staged state rolled back.
109    AbortedValidationFailed = 5,
110    /// Rejected during `Commit` because receipt persistence failed; staged state rolled back.
111    AbortedReceiptFailed = 6,
112    /// Trapped during `Execute`; staged state rolled back.
113    TrappedExecution = 7,
114}
115
116/// Admission request submitted to `SentinelPolicyGate::admit_call`.
117#[repr(C)]
118#[derive(Debug, Clone, Copy, PartialEq, Eq)]
119pub struct AdmissionRequest {
120    pub handle: PreparedCallHandle,
121    pub actor_did_hash: u64,
122    pub context_world_hash: u64,
123    pub lamport_timestamp: u64,
124    pub mode: ExecutionMode,
125    pub requested_effects: EffectSet,
126    pub declared_envelope: ResourceEnvelope,
127    pub input_fingerprint: u64,
128}
129
130impl AdmissionRequest {
131    /// Returns the requested synchronous vs bounded-async execution class.
132    #[inline]
133    pub const fn async_class(&self) -> AsyncExecutionClass {
134        self.declared_envelope.async_class()
135    }
136}
137
138/// Scoped admission ticket returned by `SentinelPolicyGate::admit_call`.
139#[repr(C)]
140#[derive(Debug, Clone, Copy, PartialEq, Eq)]
141pub struct AdmissionTicket {
142    pub ticket_id: u64,
143    pub policy_generation: u64,
144    pub actor_did_hash: u64,
145    pub context_world_hash: u64,
146    pub granted_effects: EffectSet,
147    pub approved_envelope: ResourceEnvelope,
148    pub expiry_lamport: u64,
149    pub simulated: bool,
150}
151
152impl AdmissionTicket {
153    /// Returns the approved synchronous vs bounded-async execution class.
154    #[inline]
155    pub const fn async_class(&self) -> AsyncExecutionClass {
156        self.approved_envelope.async_class()
157    }
158}
159
160/// Compact, zero-heap cryptographic/audit receipt header for a VibeScript extension call.
161///
162/// Seals cleanly into two parity-valid `NQuin48` records via `to_audit_nquins()`.
163#[repr(C)]
164#[derive(Debug, Clone, Copy, PartialEq, Eq)]
165pub struct ExecutionReceiptHeader {
166    pub ticket_id: u64,
167    pub actor_did_hash: u64,
168    pub provider_iri_hash: u64,
169    pub func_iri_hash: u64,
170    pub stable_id: StableFuncId,
171    pub mode: ExecutionMode,
172    pub status: CompletionStatus,
173    pub simulated: bool,
174    pub reserved: [u8; 5],
175    pub policy_generation: u64,
176    pub registry_generation: RegistryGeneration,
177    pub ticks_consumed: u32,
178    pub output_bytes_written: u32,
179    pub trap_code: u16,
180    pub failure_stage: u16,
181    pub input_output_fold_hash: u64,
182    pub lamport_timestamp: u64,
183}
184
185impl ExecutionReceiptHeader {
186    /// Encodes this receipt into two parity-valid `NQuin48` records for zero-heap persistence.
187    #[inline]
188    pub const fn to_audit_nquins(&self) -> [NQuin48; 2] {
189        let status_pack = ((self.mode as u64) << 56)
190            | ((self.status as u64) << 48)
191            | ((self.simulated as u64) << 40)
192            | ((self.trap_code as u64) << 16)
193            | (self.failure_stage as u64);
194        let q0 = NQuin48::from_parts(
195            self.actor_did_hash,
196            self.func_iri_hash,
197            self.provider_iri_hash,
198            self.ticket_id,
199            status_pack,
200        );
201        let metrics_pack = ((self.registry_generation.0 as u64) << 32) | (self.ticks_consumed as u64);
202        let q1 = NQuin48::from_parts(
203            self.ticket_id,
204            self.policy_generation,
205            self.input_output_fold_hash,
206            self.lamport_timestamp,
207            metrics_pack ^ ((self.output_bytes_written as u64) << 16),
208        );
209        [q0, q1]
210    }
211}
212
213/// Host-neutral policy & receipt gate implemented by QualiaDB's Webizen Sentinel
214/// (and by deterministic simulated test harnesses).
215pub trait SentinelPolicyGate {
216    /// Returns `true` if the underlying Sentinel controller is alive and reachable.
217    fn is_controller_alive(&self) -> bool;
218
219    /// Returns the current active policy generation counter.
220    fn current_policy_generation(&self) -> u64;
221
222    /// Stage 3 (`Admit`): Evaluates deontic norms, delegation scope, expiry, and resource bounds.
223    fn admit_call(&mut self, request: &AdmissionRequest) -> Result<AdmissionTicket, VibeTrap>;
224
225    /// Stage 5 (`Validate`): Verifies postconditions, mid-execution policy generation validity,
226    /// and actual resource usage before state publication.
227    fn validate_post_execution(
228        &mut self,
229        ticket: &AdmissionTicket,
230        opcode: VibeOpCode,
231        ticks_consumed: u64,
232        output_bytes_written: usize,
233        output_digest: u64,
234    ) -> Result<(), VibeTrap>;
235
236    /// Stage 6 (`Commit` / `Abort`): Persists the execution receipt.
237    ///
238    /// **Fail-closed rule**: If `commit_receipt` returns `Err(VibeTrap::ReceiptPersistenceFailed)`,
239    /// the caller MUST abort all staged state mutations and withhold publication.
240    fn commit_receipt(&mut self, receipt: &ExecutionReceiptHeader) -> Result<[NQuin48; 2], VibeTrap>;
241}