Skip to main content

vibe/extension_registry/
dispatch_adapter.rs

1//! Zero-heap hot dispatch (`dispatch_prepared_call`) enforcing the 6-stage lifecycle
2//! (`Admit -> Execute -> Validate -> Commit/Abort`) across all 4 `ExecutionMode`s.
3
4use super::registry::ExtensionRegistry;
5use vibescript_abi::{
6    q_hash, AdmissionRequest, AdmissionTicket, BorrowedSliceView, CallerOutputSlice,
7    CompletionStatus, EffectSet, ExecutionMode, ExecutionReceiptHeader, NQuin48,
8    PreparedCallHandle, ResourceEnvelope, SentinelPolicyGate, VibeOpCode, VibeTrap,
9};
10
11/// Context supplied by the caller for a single prepared extension invocation.
12#[repr(C)]
13#[derive(Debug, Clone, Copy)]
14pub struct CallExecutionContext {
15    pub actor_did_hash: u64,
16    pub context_world_hash: u64,
17    pub lamport_timestamp: u64,
18    pub mode: ExecutionMode,
19}
20
21/// Complete outcome of a prepared extension call, including its sealed receipt and audit `NQuin48`s.
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub struct DispatchOutcome {
24    pub ticks_consumed: u64,
25    pub output_elems_written: usize,
26    pub output_bytes_written: usize,
27    pub receipt: ExecutionReceiptHeader,
28    pub audit_nquins: [NQuin48; 2],
29}
30
31/// Executes a `PreparedCallHandle` in zero heap allocations (`Tier-1 HotZeroHeap`).
32///
33/// Enforces:
34/// 1. `RegistryGeneration` freshness (`StaleRegistryGeneration` on mismatch).
35/// 2. `contract_digest` integrity (`ContractDigestMismatch`).
36/// 3. Parameter arity, type, and element count bounds (`ArityMismatch`, `TypeMismatch`, `SliceLengthMismatch`).
37/// 4. Pre-dispatch output buffer capacity (`OutputBufferTooSmall`) before any admission or side effects.
38/// 5. Mode-specific Sentinel admission (`GovernedApplication`, `StandaloneDeveloper`, `SimulatedGovernanceTest`, `IntegratedGovernanceTest`).
39/// 6. Post-execution validation and fail-closed receipt persistence (`ReceiptPersistenceFailed`).
40pub fn dispatch_prepared_call<'g>(
41    registry: &ExtensionRegistry<'_>,
42    handle: &PreparedCallHandle,
43    ctx: &CallExecutionContext,
44    mut gate: Option<&mut (dyn SentinelPolicyGate + 'g)>,
45    inputs: &[BorrowedSliceView<'_>],
46    output: &mut CallerOutputSlice<'_>,
47) -> Result<DispatchOutcome, VibeTrap> {
48    // 1. Verify registry generation freshness in O(1)
49    if handle.registry_generation != registry.generation() {
50        return Err(VibeTrap::StaleRegistryGeneration);
51    }
52
53    // 2. Resolve provider and function descriptor in O(1)
54    let (provider, func) = registry.resolve_opcode(handle.opcode)?;
55    if func.contract.contract_digest != handle.contract_digest {
56        return Err(VibeTrap::ContractDigestMismatch);
57    }
58    let ontology = provider.static_ontology_nquins();
59    if !func.contract.validate_spans(ontology.len()) {
60        return Err(VibeTrap::InvalidOntologySpan);
61    }
62
63    // 3. Validate input parameter arity, types, and element count bounds
64    if inputs.len() != func.params.len() {
65        return Err(VibeTrap::ArityMismatch);
66    }
67    let mut input_fold = handle.func_iri_hash;
68    let mut i = 0;
69    while i < inputs.len() {
70        let spec = &func.params[i];
71        let view = &inputs[i];
72        if view.kind() != spec.kind {
73            return Err(VibeTrap::TypeMismatch);
74        }
75        let count = view.elem_count();
76        if count < spec.min_elems as usize || count > spec.max_elems as usize {
77            return Err(VibeTrap::SliceLengthMismatch);
78        }
79        input_fold ^= q_hash(view.as_bytes());
80        i += 1;
81    }
82
83    // 4. Pre-validate caller output slice type and capacity BEFORE admission or execution
84    if output.kind() != func.output_kind {
85        return Err(VibeTrap::TypeMismatch);
86    }
87    output.ensure_elem_capacity(func.required_output_elems as usize)?;
88
89    // 5. Stage 3: Admission
90    let ticket = match ctx.mode {
91        ExecutionMode::StandaloneDeveloper => {
92            // Standalone developer mode permits PureCompute without a Sentinel gate.
93            if !func.effects.is_pure() {
94                return Err(VibeTrap::EffectNotPermittedInMode);
95            }
96            AdmissionTicket {
97                ticket_id: ctx.lamport_timestamp ^ handle.func_iri_hash,
98                policy_generation: 0,
99                actor_did_hash: ctx.actor_did_hash,
100                context_world_hash: ctx.context_world_hash,
101                granted_effects: EffectSet::PURE_COMPUTE,
102                approved_envelope: func.envelope,
103                expiry_lamport: u64::MAX,
104                simulated: false,
105            }
106        }
107        ExecutionMode::GovernedApplication
108        | ExecutionMode::SimulatedGovernanceTest
109        | ExecutionMode::IntegratedGovernanceTest => {
110            let policy_gate = gate.as_deref_mut().ok_or(VibeTrap::SentinelUnavailable)?;
111            if !policy_gate.is_controller_alive() {
112                return Err(VibeTrap::SentinelUnavailable);
113            }
114            let req = AdmissionRequest {
115                handle: *handle,
116                actor_did_hash: ctx.actor_did_hash,
117                context_world_hash: ctx.context_world_hash,
118                lamport_timestamp: ctx.lamport_timestamp,
119                mode: ctx.mode,
120                requested_effects: func.effects,
121                declared_envelope: func.envelope,
122                input_fingerprint: input_fold,
123            };
124            let ticket = policy_gate.admit_call(&req)?;
125            if ctx.lamport_timestamp > ticket.expiry_lamport {
126                return Err(VibeTrap::AuthorityExpired);
127            }
128            if !func.effects.is_subset_of(ticket.granted_effects) {
129                return Err(VibeTrap::PolicyDenied);
130            }
131            if func.envelope.max_ticks > ticket.approved_envelope.max_ticks
132                || func.envelope.max_output_bytes > ticket.approved_envelope.max_output_bytes
133                || func.envelope.max_scratch_bytes > ticket.approved_envelope.max_scratch_bytes
134                || func.envelope.max_vram_bytes > ticket.approved_envelope.max_vram_bytes
135                || func.envelope.max_spawned_tasks > ticket.approved_envelope.max_spawned_tasks
136            {
137                return Err(VibeTrap::ResourceEnvelopeExceeded);
138            }
139            ticket
140        }
141    };
142
143    // 6. Stage 4: Execute
144    let ticks_consumed = match provider.call(func.stable_id, inputs, output) {
145        Ok(t) => t,
146        Err(trap) => {
147            if let Some(policy_gate) = gate {
148                let abort_receipt = ExecutionReceiptHeader {
149                    ticket_id: ticket.ticket_id,
150                    actor_did_hash: ctx.actor_did_hash,
151                    provider_iri_hash: handle.provider_iri_hash,
152                    func_iri_hash: handle.func_iri_hash,
153                    stable_id: func.stable_id,
154                    mode: ctx.mode,
155                    status: CompletionStatus::TrappedExecution,
156                    simulated: ticket.simulated || ctx.mode == ExecutionMode::SimulatedGovernanceTest,
157                    reserved: [0; 5],
158                    policy_generation: ticket.policy_generation,
159                    registry_generation: handle.registry_generation,
160                    ticks_consumed: 0,
161                    output_bytes_written: 0,
162                    trap_code: trap as u16,
163                    failure_stage: trap.stage() as u16,
164                    input_output_fold_hash: input_fold,
165                    lamport_timestamp: ctx.lamport_timestamp,
166                };
167                if let Err(commit_trap) = policy_gate.commit_receipt(&abort_receipt) {
168                    return Err(commit_trap);
169                }
170            }
171            return Err(trap);
172        }
173    };
174
175    let output_bytes_written = output.written_bytes();
176    let limit_trap = if ticks_consumed > ticket.approved_envelope.max_ticks {
177        Some(VibeTrap::TickBudgetExhausted)
178    } else if output_bytes_written > ticket.approved_envelope.max_output_bytes as usize {
179        Some(VibeTrap::ResourceEnvelopeExceeded)
180    } else {
181        None
182    };
183    if let Some(trap) = limit_trap {
184        if let Some(policy_gate) = gate {
185            let abort_receipt = ExecutionReceiptHeader {
186                ticket_id: ticket.ticket_id,
187                actor_did_hash: ctx.actor_did_hash,
188                provider_iri_hash: handle.provider_iri_hash,
189                func_iri_hash: handle.func_iri_hash,
190                stable_id: func.stable_id,
191                mode: ctx.mode,
192                status: CompletionStatus::AbortedValidationFailed,
193                simulated: ticket.simulated || ctx.mode == ExecutionMode::SimulatedGovernanceTest,
194                reserved: [0; 5],
195                policy_generation: ticket.policy_generation,
196                registry_generation: handle.registry_generation,
197                ticks_consumed: ticks_consumed as u32,
198                output_bytes_written: output_bytes_written as u32,
199                trap_code: trap as u16,
200                failure_stage: trap.stage() as u16,
201                input_output_fold_hash: input_fold,
202                lamport_timestamp: ctx.lamport_timestamp,
203            };
204            if let Err(commit_trap) = policy_gate.commit_receipt(&abort_receipt) {
205                    return Err(commit_trap);
206                }
207        }
208        return Err(trap);
209    }
210
211    // 7. Stage 5 & 6: Validate and Commit Receipt
212    let output_hash = q_hash(output.written_byte_slice());
213    let io_fold = input_fold ^ output_hash.rotate_left(17);
214
215    let (status, simulated) = match ctx.mode {
216        ExecutionMode::StandaloneDeveloper => (CompletionStatus::StandaloneCompleted, false),
217        ExecutionMode::SimulatedGovernanceTest => (CompletionStatus::SimulatedCommitted, true),
218        ExecutionMode::GovernedApplication | ExecutionMode::IntegratedGovernanceTest => {
219            (CompletionStatus::Committed, ticket.simulated)
220        }
221    };
222
223    let receipt = ExecutionReceiptHeader {
224        ticket_id: ticket.ticket_id,
225        actor_did_hash: ctx.actor_did_hash,
226        provider_iri_hash: handle.provider_iri_hash,
227        func_iri_hash: handle.func_iri_hash,
228        stable_id: func.stable_id,
229        mode: ctx.mode,
230        status,
231        simulated,
232        reserved: [0; 5],
233        policy_generation: ticket.policy_generation,
234        registry_generation: handle.registry_generation,
235        ticks_consumed: ticks_consumed as u32,
236        output_bytes_written: output_bytes_written as u32,
237        trap_code: 0,
238        failure_stage: 0,
239        input_output_fold_hash: io_fold,
240        lamport_timestamp: ctx.lamport_timestamp,
241    };
242
243    let audit_nquins = if let Some(policy_gate) = gate {
244        if let Err(trap) = policy_gate.validate_post_execution(
245            &ticket,
246            handle.opcode,
247            ticks_consumed,
248            output_bytes_written,
249            output_hash,
250        ) {
251            let mut abort_receipt = receipt;
252            abort_receipt.status = CompletionStatus::AbortedValidationFailed;
253            abort_receipt.trap_code = trap as u16;
254            abort_receipt.failure_stage = trap.stage() as u16;
255            if let Err(commit_trap) = policy_gate.commit_receipt(&abort_receipt) {
256                    return Err(commit_trap);
257                }
258            return Err(trap);
259        }
260        policy_gate.commit_receipt(&receipt)?
261    } else {
262        receipt.to_audit_nquins()
263    };
264
265    Ok(DispatchOutcome {
266        ticks_consumed,
267        output_elems_written: output.written_elems(),
268        output_bytes_written,
269        receipt,
270        audit_nquins,
271    })
272}
273
274/// Deterministic in-memory policy gate for `ExecutionMode::SimulatedGovernanceTest`.
275pub struct SimulatedPolicyGate {
276    pub controller_alive: bool,
277    pub policy_generation: u64,
278    pub revoke_during_execution: bool,
279    pub fail_receipt_commit: bool,
280    pub allowed_actor_hash: u64,
281    pub explicit_deny_func_hash: u64,
282    pub max_expiry_lamport: u64,
283    pub allowed_effects: EffectSet,
284    pub budget: ResourceEnvelope,
285    pub committed_receipts_count: usize,
286}
287
288impl SimulatedPolicyGate {
289    /// Creates a permissive test policy gate for `allowed_actor_hash`.
290    pub const fn new_for_actor(allowed_actor_hash: u64) -> Self {
291        Self {
292            controller_alive: true,
293            policy_generation: 1,
294            revoke_during_execution: false,
295            fail_receipt_commit: false,
296            allowed_actor_hash,
297            explicit_deny_func_hash: 0,
298            max_expiry_lamport: 1_000_000,
299            allowed_effects: EffectSet(0xFFFF_FFFF),
300            budget: ResourceEnvelope {
301                max_ticks: 100_000,
302                max_scratch_bytes: 0,
303                max_vram_bytes: 0,
304                max_output_bytes: 4096,
305                max_spawned_tasks: 0,
306                flags: 0,
307            },
308            committed_receipts_count: 0,
309        }
310    }
311}
312
313impl SentinelPolicyGate for SimulatedPolicyGate {
314    fn is_controller_alive(&self) -> bool {
315        self.controller_alive
316    }
317
318    fn current_policy_generation(&self) -> u64 {
319        self.policy_generation
320    }
321
322    fn admit_call(&mut self, request: &AdmissionRequest) -> Result<AdmissionTicket, VibeTrap> {
323        if !self.controller_alive {
324            return Err(VibeTrap::SentinelUnavailable);
325        }
326        if request.handle.func_iri_hash == self.explicit_deny_func_hash {
327            return Err(VibeTrap::ExplicitDenyRule);
328        }
329        if self.allowed_actor_hash != 0 && request.actor_did_hash != self.allowed_actor_hash {
330            return Err(VibeTrap::DelegationScopeMismatch);
331        }
332        if request.lamport_timestamp > self.max_expiry_lamport {
333            return Err(VibeTrap::AuthorityExpired);
334        }
335        if !request.requested_effects.is_subset_of(self.allowed_effects) {
336            return Err(VibeTrap::PolicyDenied);
337        }
338        if !request.declared_envelope.fits_within(&self.budget) {
339            return Err(VibeTrap::ResourceEnvelopeExceeded);
340        }
341        Ok(AdmissionTicket {
342            ticket_id: request.lamport_timestamp ^ request.input_fingerprint ^ 0xA5A5_5A5A,
343            policy_generation: self.policy_generation,
344            actor_did_hash: request.actor_did_hash,
345            context_world_hash: request.context_world_hash,
346            granted_effects: request.requested_effects,
347            approved_envelope: self.budget,
348            expiry_lamport: self.max_expiry_lamport,
349            simulated: request.mode == ExecutionMode::SimulatedGovernanceTest,
350        })
351    }
352
353    fn validate_post_execution(
354        &mut self,
355        ticket: &AdmissionTicket,
356        _opcode: VibeOpCode,
357        ticks_consumed: u64,
358        output_bytes_written: usize,
359        _output_digest: u64,
360    ) -> Result<(), VibeTrap> {
361        if self.revoke_during_execution || ticket.policy_generation != self.policy_generation {
362            return Err(VibeTrap::MidExecutionPolicyRevoked);
363        }
364        if ticks_consumed > ticket.approved_envelope.max_ticks {
365            return Err(VibeTrap::TickBudgetExhausted);
366        }
367        if output_bytes_written > ticket.approved_envelope.max_output_bytes as usize {
368            return Err(VibeTrap::ResourceEnvelopeExceeded);
369        }
370        Ok(())
371    }
372
373    fn commit_receipt(
374        &mut self,
375        receipt: &ExecutionReceiptHeader,
376    ) -> Result<[NQuin48; 2], VibeTrap> {
377        if self.fail_receipt_commit {
378            return Err(VibeTrap::ReceiptPersistenceFailed);
379        }
380        self.committed_receipts_count += 1;
381        Ok(receipt.to_audit_nquins())
382    }
383}