Skip to main content

vibe/extension_registry/
mod.rs

1//! VibeScript 0.03 Extension Registry, Cold Preparation, Zero-Heap Hot Dispatch,
2//! and Deterministic Domain Provider Adapters (`VS03-06`, `VS03-07`, `VS03-08`).
3
4pub mod dispatch_adapter;
5pub mod domain_providers;
6pub mod eval_router;
7pub mod gpu_inference_providers;
8pub mod graph_logic_providers;
9pub mod prepare;
10pub mod registry;
11pub mod scalar_compat;
12
13pub use dispatch_adapter::{
14    dispatch_prepared_call, CallExecutionContext, DispatchOutcome, SimulatedPolicyGate,
15};
16pub use domain_providers::{
17    oracle_aabb_volume, oracle_excavation_prism_volume, oracle_kinetic_energy,
18    oracle_spring_damper_force, oracle_verlet_step, DeterministicMechanicsProvider,
19};
20pub use etalon_vibe::{
21    EtalonForgeProvider, EtalonModelProvider, EtalonNQuinProvider, EtalonRenderProvider,
22    EtalonSenseProvider, EtalonSignalProvider, ETALON_VIBE_PROVIDERS,
23};
24pub use eval_router::{
25    execute_prepared_value_call, is_extension_call_path, is_extension_namespace, route_call,
26    trap_to_diagnostic, try_prepare_path, PreparedCallCache, BUILTIN_EXTENSION_ALIASES,
27    BUILTIN_EXTENSION_IRIS,
28};
29pub use gpu_inference_providers::{
30    oracle_governed_token_step, oracle_gpu_affine_f32, oracle_gpu_gemv4_f32,
31    oracle_gpu_rmsnorm_f32, oracle_gpu_rope_f32, oracle_gpu_topk2_f32, oracle_rms_norm_f64,
32    oracle_softmax_f64, EtalonGpuComputeProvider, GovernedInferenceProvider,
33};
34pub use graph_logic_providers::{
35    oracle_allen_interval_relation, oracle_pack_deontic_predicate, oracle_seal_quin,
36    oracle_verify_quin_parity, DeonticTemporalProvider, StagedGraphMutationProvider,
37};
38pub use prepare::prepare_extension_call;
39pub use registry::{ExtensionRegistry, MAX_EXTENSION_PROVIDERS};
40
41#[cfg(test)]
42mod tests {
43    use super::*;
44    use vibescript_abi::{
45        q_hash_str, BorrowedSliceView, CallerOutputSlice, CompletionStatus, ExecutionMode,
46        PrimitiveKind, SemVer64, SemVerReq, TargetProfileMask, VibeTrap,
47    };
48
49    fn f64_1_to_bytes(v: f64) -> [u8; 8] {
50        v.to_le_bytes()
51    }
52
53    fn f64_3_to_bytes(vals: [f64; 3]) -> [u8; 24] {
54        let mut out = [0u8; 24];
55        for (i, v) in vals.iter().enumerate() {
56            out[i * 8..(i + 1) * 8].copy_from_slice(&v.to_le_bytes());
57        }
58        out
59    }
60
61    #[test]
62    fn vs03_registration_atomicity_and_duplicate_rejection() {
63        static PROVIDER: DeterministicMechanicsProvider = DeterministicMechanicsProvider;
64        let mut reg = ExtensionRegistry::new();
65        let gen0 = reg.generation();
66        let slot = reg.register(&PROVIDER).expect("first registration succeeds");
67        assert_eq!(slot, 0);
68        assert!(reg.generation() > gen0);
69
70        let gen1 = reg.generation();
71        // Registering the same provider again must fail atomically without changing generation
72        let dup_err = reg.register(&PROVIDER).unwrap_err();
73        assert_eq!(dup_err, VibeTrap::DuplicateNamespaceIri);
74        assert_eq!(reg.generation(), gen1);
75        assert_eq!(reg.active_count(), 1);
76    }
77
78    #[test]
79    fn vs03_prepare_checks_zero_major_semver_and_target_profile() {
80        static PROVIDER: DeterministicMechanicsProvider = DeterministicMechanicsProvider;
81        let mut reg = ExtensionRegistry::new();
82        reg.register(&PROVIDER).unwrap();
83
84        // Provider version is 0.4.2 -> matches ^0.4.0, fails ^0.5.0 and ^0.3.0
85        let ok_handle = prepare_extension_call(
86            &reg, "mech", "kinematics", "verlet_step",
87            SemVerReq::Caret(SemVer64::release(0, 4, 0)), TargetProfileMask::NATIVE_DESKTOP,
88        ).expect("^0.4.0 matches 0.4.2");
89        assert_eq!(ok_handle.opcode.ns_slot(), 0);
90
91        let bad_ver = prepare_extension_call(
92            &reg, "mech", "kinematics", "verlet_step",
93            SemVerReq::Caret(SemVer64::release(0, 5, 0)), TargetProfileMask::NATIVE_DESKTOP,
94        ).unwrap_err();
95        assert_eq!(bad_ver, VibeTrap::VersionRequirementUnsatisfied);
96
97        // GPU_COMPUTE is not in ALL_CPU
98        let bad_target = prepare_extension_call(
99            &reg, "mech", "kinematics", "verlet_step",
100            SemVerReq::AnyStable, TargetProfileMask::GPU_COMPUTE,
101        ).unwrap_err();
102        assert_eq!(bad_target, VibeTrap::TargetProfileUnsupported);
103    }
104
105    #[test]
106    fn vs03_stale_registry_generation_fails_closed_after_unregister() {
107        static PROVIDER: DeterministicMechanicsProvider = DeterministicMechanicsProvider;
108        let mut reg = ExtensionRegistry::new();
109        let slot = reg.register(&PROVIDER).unwrap();
110        let handle = prepare_extension_call(
111            &reg, "mech", "kinematics", "kinetic_energy",
112            SemVerReq::AnyStable, TargetProfileMask::NATIVE_DESKTOP,
113        ).unwrap();
114
115        // Unregister advances generation
116        reg.unregister(slot).unwrap();
117
118        let mass_b = f64_1_to_bytes(2.0);
119        let vel_b = f64_3_to_bytes([3.0, 4.0, 0.0]);
120        let inputs = [
121            BorrowedSliceView::from_raw_bytes(&mass_b, PrimitiveKind::F64, 1).unwrap(),
122            BorrowedSliceView::from_raw_bytes(&vel_b, PrimitiveKind::F64, 3).unwrap(),
123        ];
124        let mut out_raw = [0u8; 8];
125        let mut out = CallerOutputSlice::new(&mut out_raw, PrimitiveKind::F64).unwrap();
126        let ctx = CallExecutionContext {
127            actor_did_hash: q_hash_str("did:q42:dev"),
128            context_world_hash: 1,
129            lamport_timestamp: 10,
130            mode: ExecutionMode::StandaloneDeveloper,
131        };
132
133        let res = dispatch_prepared_call(&reg, &handle, &ctx, None, &inputs, &mut out);
134        assert_eq!(res, Err(VibeTrap::StaleRegistryGeneration));
135    }
136
137    #[test]
138    fn vs03_standalone_and_simulated_modes_match_direct_oracle_and_check_output_capacity() {
139        static PROVIDER: DeterministicMechanicsProvider = DeterministicMechanicsProvider;
140        let mut reg = ExtensionRegistry::new();
141        reg.register(&PROVIDER).unwrap();
142
143        let handle = prepare_extension_call(
144            &reg, "https://qualiadb.org/ext/etalon/mechanics", "kinematics", "verlet_step",
145            SemVerReq::Caret(SemVer64::release(0, 4, 0)), TargetProfileMask::WASM_SANDBOX,
146        ).unwrap();
147
148        let (pos, vel, acc, dt) = ([1.0, 2.0, 3.0], [0.5, -1.0, 2.0], [0.0, -9.81, 0.0], 0.1);
149        let (pos_b, vel_b, acc_b, dt_b) = (
150            f64_3_to_bytes(pos), f64_3_to_bytes(vel), f64_3_to_bytes(acc), f64_1_to_bytes(dt),
151        );
152        let inputs = [
153            BorrowedSliceView::from_raw_bytes(&pos_b, PrimitiveKind::F64, 3).unwrap(),
154            BorrowedSliceView::from_raw_bytes(&vel_b, PrimitiveKind::F64, 3).unwrap(),
155            BorrowedSliceView::from_raw_bytes(&acc_b, PrimitiveKind::F64, 3).unwrap(),
156            BorrowedSliceView::from_raw_bytes(&dt_b, PrimitiveKind::F64, 1).unwrap(),
157        ];
158
159        // 1. Pre-dispatch capacity check: 5 elements (< required 6) fails closed before execution
160        let mut small_raw = [0u8; 5 * 8];
161        let mut small_out = CallerOutputSlice::new(&mut small_raw, PrimitiveKind::F64).unwrap();
162        let standalone_ctx = CallExecutionContext {
163            actor_did_hash: q_hash_str("did:q42:alice"),
164            context_world_hash: 1,
165            lamport_timestamp: 42,
166            mode: ExecutionMode::StandaloneDeveloper,
167        };
168        assert_eq!(
169            dispatch_prepared_call(&reg, &handle, &standalone_ctx, None, &inputs, &mut small_out),
170            Err(VibeTrap::OutputBufferTooSmall)
171        );
172
173        // 2. StandaloneDeveloper mode with 6-element output buffer matches direct-call oracle
174        let mut out_raw = [0u8; 6 * 8];
175        let mut out = CallerOutputSlice::new(&mut out_raw, PrimitiveKind::F64).unwrap();
176        let outcome = dispatch_prepared_call(&reg, &handle, &standalone_ctx, None, &inputs, &mut out)
177            .expect("standalone call succeeds");
178        assert_eq!(outcome.receipt.status, CompletionStatus::StandaloneCompleted);
179        assert!(!outcome.receipt.simulated);
180
181        let out_view =
182            BorrowedSliceView::from_raw_bytes(out.written_byte_slice(), PrimitiveKind::F64, 6)
183                .unwrap();
184        let exp = oracle_verlet_step(pos, vel, acc, dt).unwrap();
185        for i in 0..3 {
186            assert!((out_view.read_f64_le(i).unwrap() - exp[i]).abs() < 1e-12);
187            assert!((out_view.read_f64_le(i + 3).unwrap() - exp[i + 3]).abs() < 1e-12);
188        }
189
190        // 3. GovernedApplication mode without a Sentinel gate fails closed
191        let governed_ctx = CallExecutionContext {
192            mode: ExecutionMode::GovernedApplication,
193            ..standalone_ctx
194        };
195        let mut out_raw2 = [0u8; 6 * 8];
196        let mut out2 = CallerOutputSlice::new(&mut out_raw2, PrimitiveKind::F64).unwrap();
197        assert_eq!(
198            dispatch_prepared_call(&reg, &handle, &governed_ctx, None, &inputs, &mut out2),
199            Err(VibeTrap::SentinelUnavailable)
200        );
201
202        // 4. SimulatedGovernanceTest mode marks receipt `simulated = true` and enforces receipt failure
203        let sim_ctx = CallExecutionContext {
204            mode: ExecutionMode::SimulatedGovernanceTest,
205            ..standalone_ctx
206        };
207        let mut sim_gate = SimulatedPolicyGate::new_for_actor(standalone_ctx.actor_did_hash);
208        let mut out_raw3 = [0u8; 6 * 8];
209        let mut out3 = CallerOutputSlice::new(&mut out_raw3, PrimitiveKind::F64).unwrap();
210        let sim_outcome =
211            dispatch_prepared_call(&reg, &handle, &sim_ctx, Some(&mut sim_gate), &inputs, &mut out3)
212                .expect("simulated governance succeeds");
213        assert!(sim_outcome.receipt.simulated);
214        assert_eq!(sim_outcome.receipt.status, CompletionStatus::SimulatedCommitted);
215
216        // Simulated receipt persistence failure must fail closed
217        sim_gate.fail_receipt_commit = true;
218        let mut out_raw4 = [0u8; 6 * 8];
219        let mut out4 = CallerOutputSlice::new(&mut out_raw4, PrimitiveKind::F64).unwrap();
220        assert_eq!(
221            dispatch_prepared_call(&reg, &handle, &sim_ctx, Some(&mut sim_gate), &inputs, &mut out4),
222            Err(VibeTrap::ReceiptPersistenceFailed)
223        );
224    }
225
226    #[test]
227    fn vs03_intra_provider_duplicate_stable_id_with_distinct_names_rejected() {
228        use vibescript_abi::{
229            CanonicalIri, ContractVersionAxes, DeterminismGuarantee, EffectSet, FuncDescriptor,
230            NQuin48, OntologicalContract, ParamSpec, ProviderDescriptor, ResourceEnvelope,
231            ReversibilityKind, StableFuncId, SubNamespaceDescriptor, VibeNamespaceProvider,
232        };
233
234        const PARAMS: &[ParamSpec] = &[ParamSpec::scalar("x", PrimitiveKind::F64)];
235        const ENV: ResourceEnvelope = ResourceEnvelope::hot_zero_heap(8, 8);
236        const CONTRACT: OntologicalContract = OntologicalContract {
237            contract_digest: [0x44; 32],
238            schema_hash: 1,
239            precondition_quin_span: (0, 0),
240            postcondition_quin_span: (0, 0),
241            invariant_quin_span: (0, 0),
242        };
243        const FUNCS: &[FuncDescriptor] = &[
244            FuncDescriptor {
245                name: "alpha",
246                canonical_iri: CanonicalIri::new("https://qualiadb.org/ext/test/dup/sub/alpha"),
247                stable_id: StableFuncId::new(0, 7),
248                params: PARAMS,
249                output_kind: PrimitiveKind::F64,
250                required_output_elems: 1,
251                effects: EffectSet::PURE_COMPUTE,
252                determinism: DeterminismGuarantee::DeterministicExact,
253                reversibility: ReversibilityKind::PureNoState,
254                envelope: ENV,
255                contract: CONTRACT,
256            },
257            FuncDescriptor {
258                name: "beta",
259                canonical_iri: CanonicalIri::new("https://qualiadb.org/ext/test/dup/sub/beta"),
260                stable_id: StableFuncId::new(0, 7), // duplicate StableFuncId!
261                params: PARAMS,
262                output_kind: PrimitiveKind::F64,
263                required_output_elems: 1,
264                effects: EffectSet::PURE_COMPUTE,
265                determinism: DeterminismGuarantee::DeterministicExact,
266                reversibility: ReversibilityKind::PureNoState,
267                envelope: ENV,
268                contract: CONTRACT,
269            },
270        ];
271        const SUBS: &[SubNamespaceDescriptor] = &[SubNamespaceDescriptor {
272            name: "sub",
273            sub_id: 0,
274            functions: FUNCS,
275        }];
276        const DESC: ProviderDescriptor = ProviderDescriptor {
277            canonical_iri: CanonicalIri::new("https://qualiadb.org/ext/test/dup"),
278            short_alias: "dup",
279            versions: ContractVersionAxes::v0_3_default(
280                SemVer64::release(0, 3, 0),
281                SemVer64::release(0, 1, 0),
282            ),
283            supported_targets: TargetProfileMask::ALL_CPU,
284            sub_namespaces: SUBS,
285            max_ontology_quins: 4,
286        };
287        struct BadDupProvider;
288        impl VibeNamespaceProvider for BadDupProvider {
289            fn descriptor(&self) -> &'static ProviderDescriptor {
290                &DESC
291            }
292            fn static_ontology_nquins(&self) -> &'static [NQuin48] {
293                &[]
294            }
295            fn call(
296                &self,
297                _stable_id: StableFuncId,
298                _inputs: &[BorrowedSliceView<'_>],
299                _output: &mut CallerOutputSlice<'_>,
300            ) -> Result<u64, VibeTrap> {
301                Ok(1)
302            }
303        }
304        static BAD: BadDupProvider = BadDupProvider;
305        let mut reg = ExtensionRegistry::new();
306        assert_eq!(reg.register(&BAD), Err(VibeTrap::DuplicateStableFuncId));
307        assert_eq!(reg.active_count(), 0);
308    }
309
310    #[test]
311    fn vs03_stage_s6_ast_bytecode_and_task_scheduler_cutover_parity() {
312        use crate::bind::LocalHost;
313        use crate::budget::Budget;
314        use crate::bytecode::{compile, Vm};
315        use crate::eval::{Engine, Env};
316        use crate::value::Value;
317        use vibescript_abi::ResourceEnvelope;
318
319        // 1. AST Evaluator 3-level & 2-level extension calls across mech, gpu, infer, qgraph, modality
320        let src = r#"
321            import "vibe:0.3/mech" as mech;
322            import "vibe:0.3/gpu" as gpu;
323            import "vibe:0.3/infer" as infer;
324            import "vibe:0.3/qgraph" as qgraph;
325            import "vibe:0.3/modality" as modality;
326
327            fn run_suite() {
328                let ke = mech.kinematics.kinetic_energy(4.0, [3.0, 0.0, 4.0]);
329                let aff = gpu.compute.affine_f32([1.0, 2.0, -1.0, 0.5], [2.0, 1.0]);
330                let probs = infer.activations.softmax_f64([0.0, 0.0, 0.0, 0.0]);
331                let sealed = qgraph.staging.seal_quin([10, 20, 30, 40, 50]);
332                let ok_parity = qgraph.staging.verify_quin_parity(sealed);
333                let allen_rel = modality.allen.interval_relation([0, 10], [10, 20]);
334                return [ke, aff[0], probs[0], ok_parity, allen_rel];
335            }
336        "#;
337        let prog = crate::parse_program(src).expect("parses");
338        crate::check_program(&prog).expect("checks");
339
340        let actor = q_hash_str("did:q42:local_engine");
341        let mut sim_gate = SimulatedPolicyGate::new_for_actor(actor);
342        sim_gate.budget = ResourceEnvelope {
343            max_ticks: 1024,
344            max_scratch_bytes: 1024,
345            max_vram_bytes: 2048,
346            max_output_bytes: 256,
347            max_spawned_tasks: 0,
348            flags: 0,
349        };
350        let sim_ctx = CallExecutionContext {
351            actor_did_hash: actor,
352            context_world_hash: 1,
353            lamport_timestamp: 10,
354            mode: ExecutionMode::SimulatedGovernanceTest,
355        };
356
357        let mut host = LocalHost::default();
358        let mut env = Env::default();
359        crate::eval::populate_import_aliases(&mut env, &prog.imports).unwrap();
360        let mut engine = Engine::with_program(&mut host, Budget::default(), &prog);
361        engine.set_extension_governance(sim_ctx, Some(&mut sim_gate));
362        let res = engine
363            .call_function(&prog, "run_suite", vec![], &mut env)
364            .expect("AST evaluates extension calls");
365
366        let exp_ke = oracle_kinetic_energy(4.0, [3.0, 0.0, 4.0]).unwrap();
367        let exp_aff = oracle_gpu_affine_f32([1.0, 2.0, -1.0, 0.5], 2.0, 1.0);
368        let exp_probs = oracle_softmax_f64([0.0, 0.0, 0.0, 0.0]);
369        let exp_allen = oracle_allen_interval_relation([0, 10], [10, 20]).unwrap();
370        assert_eq!(
371            res,
372            Value::List(vec![
373                Value::F64(exp_ke),
374                Value::F64(exp_aff[0] as f64),
375                Value::F64(exp_probs[0]),
376                Value::U64(1),
377                Value::U64(exp_allen),
378            ])
379        );
380        assert!(engine.last_extension_outcome().is_some());
381
382        // 2. Bytecode compiler + VM executes extension calls through the same unified router
383        let bc_src = r#"
384            fn compute_ke() -> f64 {
385                return mech.kinematics.kinetic_energy(4.0, [3.0, 0.0, 4.0]);
386            }
387        "#;
388        let bc_prog = crate::parse_program(bc_src).expect("parses bc_prog");
389        let chunk = compile(&bc_prog).expect("compiles to bytecode");
390        let mut bc_host = LocalHost::default();
391        let mut vm = Vm::new(&chunk, &mut bc_host, Budget::default());
392        let bc_val = vm.call_function(0, &[]).expect("VM executes extension call");
393        assert_eq!(bc_val, Value::F64(exp_ke));
394        assert!(vm.last_extension_outcome().is_some());
395
396        // 3. Task scheduler (`task.spawn` + `task.await`) executes extension calls and enforces
397        // policy generation freshness
398        let task_src = r#"
399            fn run_task() {
400                let h = task.spawn("= mech.kinematics.kinetic_energy(2.0, [3.0, 4.0, 0.0])");
401                return task.await(h);
402            }
403        "#;
404        let task_prog = crate::parse_program(task_src).expect("parses task_prog");
405        let mut task_host = LocalHost::default();
406        let mut task_env = Env::default();
407        let mut task_engine = Engine::with_program(&mut task_host, Budget::default(), &task_prog);
408        let task_res = task_engine
409            .call_function(&task_prog, "run_task", vec![], &mut task_env)
410            .expect("task.await evaluates extension call");
411        if let Value::Record(rec) = task_res {
412            assert_eq!(rec.get("status"), Some(&Value::String("completed".into())));
413            assert_eq!(
414                rec.get("result"),
415                Some(&Value::F64(
416                    oracle_kinetic_energy(2.0, [3.0, 4.0, 0.0]).unwrap()
417                ))
418            );
419        } else {
420            panic!("expected task record, got {task_res:?}");
421        }
422
423        // 4. All 11 built-in providers (8 Etalon + 3 Qualia) register and execute across VibeScript
424        let builtin = ExtensionRegistry::with_builtin_providers();
425        assert_eq!(builtin.active_count(), 11);
426        assert_eq!(builtin.iter_providers().count(), 11);
427        let etalon_src = r#"
428            import "vibe:0.3/forge" as forge;
429            import "vibe:0.3/render" as render;
430            import "vibe:0.3/signal" as signal;
431            import "vibe:0.3/sense" as sense;
432            import "vibe:0.3/p64" as p64;
433            import "vibe:0.3/nquin" as nquin;
434            import "vibe:0.3/mech" as mech;
435            import "vibe:0.3/gpu" as gpu;
436            fn run_etalon() {
437                let tile = forge.shader.tile_schedule_gemm([64, 64, 64], [16, 16, 16]);
438                let sdf = render.spatial.sdf_torus_eval([3.0, 0.0, 0.0], [2.0, 0.5]);
439                let rms = signal.dsp.signal_rms_peak([1.0, -1.0, 1.0, -1.0]);
440                let drift = sense.telemetry.clock_stamp_drift_ns([1050, 1000], 100);
441                let align = p64.runtime.p64_align_offset([100, 64]);
442                let par = nquin.wire.compute_wire_parity([1, 2, 4, 8, 16]);
443                let f = mech.kinematics.spring_damper_force([1.0, 0.0, 0.0], [0.0, 0.0, 0.0], [10.0, 1.0]);
444                let rn = gpu.compute.rmsnorm_f32([0.0, 0.0, 0.0, 0.0], [1.0, 1.0, 1.0, 1.0], 1.0);
445                return [tile[0], sdf, rms[0], drift[1], align[0], par, f[0], rn[0]];
446            }
447        "#;
448        let etalon_prog = crate::parse_program(etalon_src).expect("parses etalon_src");
449        crate::check_program(&etalon_prog).expect("checks etalon_src");
450        let mut etalon_env = Env::default();
451        crate::eval::populate_import_aliases(&mut etalon_env, &etalon_prog.imports).unwrap();
452        let mut etalon_engine = Engine::with_program(&mut host, Budget::default(), &etalon_prog);
453        let actor = q_hash_str("did:q42:local_engine");
454        let sim_ctx = CallExecutionContext {
455            actor_did_hash: actor,
456            context_world_hash: 1,
457            lamport_timestamp: 1,
458            mode: ExecutionMode::SimulatedGovernanceTest,
459        };
460        let mut etalon_gate = SimulatedPolicyGate::new_for_actor(actor);
461        etalon_gate.budget.max_scratch_bytes = 1_048_576;
462        etalon_gate.budget.max_vram_bytes = 1_048_576;
463        etalon_engine.set_extension_governance(sim_ctx, Some(&mut etalon_gate));
464        let etalon_res = etalon_engine
465            .call_function(&etalon_prog, "run_etalon", vec![], &mut etalon_env)
466            .expect("evaluates all 8 Etalon providers");
467        assert_eq!(
468            etalon_res,
469            Value::List(vec![
470                Value::U64(4),
471                Value::F64(0.5),
472                Value::F64(1.0),
473                Value::U64(1),
474                Value::U64(128),
475                Value::U64(31),
476                Value::F64(-10.0),
477                Value::F64(0.0),
478            ])
479        );
480    }
481}