Skip to main content

vibe/extension_registry/
graph_logic_providers.rs

1//! Stage S6 (`VS03-13`) Named provider migration: `StagedGraphMutationProvider` (`qgraph`)
2//! and `DeonticTemporalProvider` (`modality`) with direct-call reference oracles.
3
4use vibescript_abi::{
5    q_hash_str, BorrowedSliceView, CallerOutputSlice, CanonicalIri, ContractVersionAxes,
6    DeterminismGuarantee, EffectSet, FuncDescriptor, NQuin48, OntologicalContract, ParamSpec,
7    PrimitiveKind, ProviderDescriptor, ResourceEnvelope, ReversibilityKind, SemVer64, StableFuncId,
8    SubNamespaceDescriptor, TargetProfileMask, VibeNamespaceProvider, VibeTrap,
9};
10
11const SEAL_QUIN_PARAMS: &[ParamSpec] = &[ParamSpec::slice(
12    "fields_spocm",
13    PrimitiveKind::U64,
14    5,
15    5,
16)];
17
18const VERIFY_QUIN_PARAMS: &[ParamSpec] = &[ParamSpec::slice(
19    "quin_words",
20    PrimitiveKind::U64,
21    6,
22    6,
23)];
24
25const SEAL_ENV: ResourceEnvelope = ResourceEnvelope::hot_zero_heap(24, 48);
26const VERIFY_ENV: ResourceEnvelope = ResourceEnvelope::hot_zero_heap(16, 8);
27
28const STAGING_FUNCS: &[FuncDescriptor] = &[
29    FuncDescriptor {
30        name: "seal_quin",
31        canonical_iri: CanonicalIri::new(
32            "https://qualiadb.org/ext/qualia/graph/staging/seal_quin",
33        ),
34        stable_id: StableFuncId::new(0, 0),
35        params: SEAL_QUIN_PARAMS,
36        output_kind: PrimitiveKind::U64,
37        required_output_elems: 6,
38        effects: EffectSet::GRAPH_MUTATE,
39        determinism: DeterminismGuarantee::DeterministicExact,
40        reversibility: ReversibilityKind::StagedReversible,
41        envelope: SEAL_ENV,
42        contract: OntologicalContract {
43            contract_digest: OntologicalContract::canonical_digest(
44                q_hash_str("https://qualiadb.org/ext/qualia/graph/staging/seal_quin"),
45                StableFuncId::new(0, 0),
46                q_hash_str("(u64[5])->u64[6]"),
47                EffectSet::GRAPH_MUTATE,
48                DeterminismGuarantee::DeterministicExact,
49                ReversibilityKind::StagedReversible,
50                SEAL_ENV,
51                (0, 1),
52                (1, 1),
53                (2, 1),
54            ),
55            schema_hash: q_hash_str("(u64[5])->u64[6]"),
56            precondition_quin_span: (0, 1),
57            postcondition_quin_span: (1, 1),
58            invariant_quin_span: (2, 1),
59        },
60    },
61    FuncDescriptor {
62        name: "verify_quin_parity",
63        canonical_iri: CanonicalIri::new(
64            "https://qualiadb.org/ext/qualia/graph/staging/verify_quin_parity",
65        ),
66        stable_id: StableFuncId::new(0, 1),
67        params: VERIFY_QUIN_PARAMS,
68        output_kind: PrimitiveKind::U64,
69        required_output_elems: 1,
70        effects: EffectSet::GRAPH_READ,
71        determinism: DeterminismGuarantee::DeterministicExact,
72        reversibility: ReversibilityKind::PureNoState,
73        envelope: VERIFY_ENV,
74        contract: OntologicalContract {
75            contract_digest: OntologicalContract::canonical_digest(
76                q_hash_str("https://qualiadb.org/ext/qualia/graph/staging/verify_quin_parity"),
77                StableFuncId::new(0, 1),
78                q_hash_str("(u64[6])->u64"),
79                EffectSet::GRAPH_READ,
80                DeterminismGuarantee::DeterministicExact,
81                ReversibilityKind::PureNoState,
82                VERIFY_ENV,
83                (0, 1),
84                (1, 1),
85                (2, 1),
86            ),
87            schema_hash: q_hash_str("(u64[6])->u64"),
88            precondition_quin_span: (0, 1),
89            postcondition_quin_span: (1, 1),
90            invariant_quin_span: (2, 1),
91        },
92    },
93];
94
95const GRAPH_SUB_NAMESPACES: &[SubNamespaceDescriptor] = &[SubNamespaceDescriptor {
96    name: "staging",
97    sub_id: 0,
98    functions: STAGING_FUNCS,
99}];
100
101const GRAPH_DESCRIPTOR: ProviderDescriptor = ProviderDescriptor {
102    canonical_iri: CanonicalIri::new("https://qualiadb.org/ext/qualia/graph"),
103    short_alias: "qgraph",
104    versions: ContractVersionAxes::v0_3_default(
105        SemVer64::release(0, 3, 0),
106        SemVer64::release(0, 1, 0),
107    ),
108    supported_targets: TargetProfileMask::ALL_CPU,
109    sub_namespaces: GRAPH_SUB_NAMESPACES,
110    max_ontology_quins: 16,
111};
112
113const GRAPH_ONTOLOGY_QUINS: &[NQuin48] = &[
114    NQuin48::from_parts(
115        q_hash_str("https://qualiadb.org/ext/qualia/graph"),
116        q_hash_str("https://qualiadb.org/schema/vibe#hasPrecondition"),
117        q_hash_str("https://qualiadb.org/schema/vibe#CanonicalFiveFieldTuple"),
118        q_hash_str("https://qualiadb.org/context/public"),
119        1,
120    ),
121    NQuin48::from_parts(
122        q_hash_str("https://qualiadb.org/ext/qualia/graph"),
123        q_hash_str("https://qualiadb.org/schema/vibe#hasPostcondition"),
124        q_hash_str("https://qualiadb.org/schema/vibe#XorParitySealedNQuin48"),
125        q_hash_str("https://qualiadb.org/context/public"),
126        2,
127    ),
128    NQuin48::from_parts(
129        q_hash_str("https://qualiadb.org/ext/qualia/graph"),
130        q_hash_str("https://qualiadb.org/schema/vibe#preservesInvariant"),
131        q_hash_str("https://qualiadb.org/schema/vibe#ReversibleBeforeReceiptCommit"),
132        q_hash_str("https://qualiadb.org/context/public"),
133        3,
134    ),
135];
136
137/// Staged semantic graph provider (`VS03-13`).
138#[derive(Debug, Clone, Copy, Default)]
139pub struct StagedGraphMutationProvider;
140
141impl VibeNamespaceProvider for StagedGraphMutationProvider {
142    fn descriptor(&self) -> &'static ProviderDescriptor {
143        &GRAPH_DESCRIPTOR
144    }
145
146    fn static_ontology_nquins(&self) -> &'static [NQuin48] {
147        GRAPH_ONTOLOGY_QUINS
148    }
149
150    fn call(
151        &self,
152        stable_id: StableFuncId,
153        inputs: &[BorrowedSliceView<'_>],
154        output: &mut CallerOutputSlice<'_>,
155    ) -> Result<u64, VibeTrap> {
156        match (stable_id.sub_namespace_id, stable_id.func_id) {
157            (0, 0) => {
158                // staging::seal_quin
159                let mut spocm = [0u64; 5];
160                for (i, slot) in spocm.iter_mut().enumerate() {
161                    *slot = inputs[0].read_u64_le(i)?;
162                }
163                let q = oracle_seal_quin(spocm);
164                for &w in &q.0 {
165                    output.push_u64_le(w)?;
166                }
167                Ok(12)
168            }
169            (0, 1) => {
170                // staging::verify_quin_parity
171                let mut words = [0u64; 6];
172                for (i, slot) in words.iter_mut().enumerate() {
173                    *slot = inputs[0].read_u64_le(i)?;
174                }
175                let ok = oracle_verify_quin_parity(words);
176                output.push_u64_le(if ok { 1 } else { 0 })?;
177                Ok(8)
178            }
179            _ => Err(VibeTrap::FunctionNotFound),
180        }
181    }
182}
183
184/// Direct-call oracle for `qgraph::staging::seal_quin`.
185#[inline]
186pub const fn oracle_seal_quin(spocm: [u64; 5]) -> NQuin48 {
187    NQuin48::from_parts(spocm[0], spocm[1], spocm[2], spocm[3], spocm[4])
188}
189
190/// Direct-call oracle for `qgraph::staging::verify_quin_parity`.
191#[inline]
192pub const fn oracle_verify_quin_parity(words: [u64; 6]) -> bool {
193    NQuin48(words).verify_parity()
194}
195
196// ---------------------------------------------------------------------------
197// DeonticTemporalProvider (VS03-13)
198// ---------------------------------------------------------------------------
199
200const ALLEN_PARAMS: &[ParamSpec] = &[
201    ParamSpec::slice("interval_a", PrimitiveKind::I64, 2, 2),
202    ParamSpec::slice("interval_b", PrimitiveKind::I64, 2, 2),
203];
204
205const DEONTIC_PACK_PARAMS: &[ParamSpec] = &[
206    ParamSpec::scalar("prop_hash", PrimitiveKind::U64),
207    ParamSpec::scalar("opcode", PrimitiveKind::U64),
208    ParamSpec::scalar("is_defeater", PrimitiveKind::U64),
209];
210
211const ALLEN_ENV: ResourceEnvelope = ResourceEnvelope::hot_zero_heap(16, 8);
212const DEONTIC_ENV: ResourceEnvelope = ResourceEnvelope::hot_zero_heap(12, 8);
213
214const ALLEN_FUNCS: &[FuncDescriptor] = &[FuncDescriptor {
215    name: "interval_relation",
216    canonical_iri: CanonicalIri::new(
217        "https://qualiadb.org/ext/qualia/modality/allen/interval_relation",
218    ),
219    stable_id: StableFuncId::new(0, 0),
220    params: ALLEN_PARAMS,
221    output_kind: PrimitiveKind::U64,
222    required_output_elems: 1,
223    effects: EffectSet::PURE_COMPUTE,
224    determinism: DeterminismGuarantee::DeterministicExact,
225    reversibility: ReversibilityKind::PureNoState,
226    envelope: ALLEN_ENV,
227    contract: OntologicalContract {
228        contract_digest: OntologicalContract::canonical_digest(
229            q_hash_str("https://qualiadb.org/ext/qualia/modality/allen/interval_relation"),
230            StableFuncId::new(0, 0),
231            q_hash_str("(i64[2],i64[2])->u64"),
232            EffectSet::PURE_COMPUTE,
233            DeterminismGuarantee::DeterministicExact,
234            ReversibilityKind::PureNoState,
235            ALLEN_ENV,
236            (0, 1),
237            (1, 1),
238            (2, 1),
239        ),
240        schema_hash: q_hash_str("(i64[2],i64[2])->u64"),
241        precondition_quin_span: (0, 1),
242        postcondition_quin_span: (1, 1),
243        invariant_quin_span: (2, 1),
244    },
245}];
246
247const DEONTIC_FUNCS: &[FuncDescriptor] = &[FuncDescriptor {
248    name: "pack_norm_predicate",
249    canonical_iri: CanonicalIri::new(
250        "https://qualiadb.org/ext/qualia/modality/deontic/pack_norm_predicate",
251    ),
252    stable_id: StableFuncId::new(1, 0),
253    params: DEONTIC_PACK_PARAMS,
254    output_kind: PrimitiveKind::U64,
255    required_output_elems: 1,
256    effects: EffectSet::PURE_COMPUTE,
257    determinism: DeterminismGuarantee::DeterministicExact,
258    reversibility: ReversibilityKind::PureNoState,
259    envelope: DEONTIC_ENV,
260    contract: OntologicalContract {
261        contract_digest: OntologicalContract::canonical_digest(
262            q_hash_str("https://qualiadb.org/ext/qualia/modality/deontic/pack_norm_predicate"),
263            StableFuncId::new(1, 0),
264            q_hash_str("(u64,u64,u64)->u64"),
265            EffectSet::PURE_COMPUTE,
266            DeterminismGuarantee::DeterministicExact,
267            ReversibilityKind::PureNoState,
268            DEONTIC_ENV,
269            (0, 1),
270            (1, 1),
271            (2, 1),
272        ),
273        schema_hash: q_hash_str("(u64,u64,u64)->u64"),
274        precondition_quin_span: (0, 1),
275        postcondition_quin_span: (1, 1),
276        invariant_quin_span: (2, 1),
277    },
278}];
279
280const MODALITY_SUB_NAMESPACES: &[SubNamespaceDescriptor] = &[
281    SubNamespaceDescriptor {
282        name: "allen",
283        sub_id: 0,
284        functions: ALLEN_FUNCS,
285    },
286    SubNamespaceDescriptor {
287        name: "deontic",
288        sub_id: 1,
289        functions: DEONTIC_FUNCS,
290    },
291];
292
293const MODALITY_DESCRIPTOR: ProviderDescriptor = ProviderDescriptor {
294    canonical_iri: CanonicalIri::new("https://qualiadb.org/ext/qualia/modality"),
295    short_alias: "modality",
296    versions: ContractVersionAxes::v0_3_default(
297        SemVer64::release(0, 3, 0),
298        SemVer64::release(0, 1, 0),
299    ),
300    supported_targets: TargetProfileMask::ALL_CPU,
301    sub_namespaces: MODALITY_SUB_NAMESPACES,
302    max_ontology_quins: 16,
303};
304
305const MODALITY_ONTOLOGY_QUINS: &[NQuin48] = &[
306    NQuin48::from_parts(
307        q_hash_str("https://qualiadb.org/ext/qualia/modality"),
308        q_hash_str("https://qualiadb.org/schema/vibe#hasPrecondition"),
309        q_hash_str("https://qualiadb.org/schema/vibe#WellFormedTemporalIntervals"),
310        q_hash_str("https://qualiadb.org/context/public"),
311        1,
312    ),
313    NQuin48::from_parts(
314        q_hash_str("https://qualiadb.org/ext/qualia/modality"),
315        q_hash_str("https://qualiadb.org/schema/vibe#hasPostcondition"),
316        q_hash_str("https://qualiadb.org/schema/vibe#CanonicalAllenRelationOrDeonticOpcode"),
317        q_hash_str("https://qualiadb.org/context/public"),
318        2,
319    ),
320    NQuin48::from_parts(
321        q_hash_str("https://qualiadb.org/ext/qualia/modality"),
322        q_hash_str("https://qualiadb.org/schema/vibe#preservesInvariant"),
323        q_hash_str("https://qualiadb.org/schema/vibe#OpcodesAbove0x10ReservedForModalities"),
324        q_hash_str("https://qualiadb.org/context/public"),
325        3,
326    ),
327];
328
329/// Deontic & Allen temporal modality provider (`VS03-13`).
330#[derive(Debug, Clone, Copy, Default)]
331pub struct DeonticTemporalProvider;
332
333impl VibeNamespaceProvider for DeonticTemporalProvider {
334    fn descriptor(&self) -> &'static ProviderDescriptor {
335        &MODALITY_DESCRIPTOR
336    }
337
338    fn static_ontology_nquins(&self) -> &'static [NQuin48] {
339        MODALITY_ONTOLOGY_QUINS
340    }
341
342    fn call(
343        &self,
344        stable_id: StableFuncId,
345        inputs: &[BorrowedSliceView<'_>],
346        output: &mut CallerOutputSlice<'_>,
347    ) -> Result<u64, VibeTrap> {
348        match (stable_id.sub_namespace_id, stable_id.func_id) {
349            (0, 0) => {
350                // allen::interval_relation
351                let a0 = inputs[0].read_i64_le(0)?;
352                let a1 = inputs[0].read_i64_le(1)?;
353                let b0 = inputs[1].read_i64_le(0)?;
354                let b1 = inputs[1].read_i64_le(1)?;
355                let rel = oracle_allen_interval_relation([a0, a1], [b0, b1])?;
356                output.push_u64_le(rel)?;
357                Ok(10)
358            }
359            (1, 0) => {
360                // deontic::pack_norm_predicate
361                let prop_hash = inputs[0].read_u64_le(0)?;
362                let opcode = inputs[1].read_u64_le(0)?;
363                let is_defeater = inputs[2].read_u64_le(0)? != 0;
364                let packed = oracle_pack_deontic_predicate(prop_hash, opcode, is_defeater)?;
365                output.push_u64_le(packed)?;
366                Ok(6)
367            }
368            _ => Err(VibeTrap::FunctionNotFound),
369        }
370    }
371}
372
373/// Direct-call oracle for `modality::allen::interval_relation`.
374///
375/// Returns canonical Allen relation code `1..=7`:
376/// `1 = Before`, `2 = Meets`, `3 = Overlaps`, `4 = Starts`, `5 = During`, `6 = Finishes`, `7 = Equals`, `8 = Other/Inverse`.
377#[inline]
378pub const fn oracle_allen_interval_relation(
379    a: [i64; 2],
380    b: [i64; 2],
381) -> Result<u64, VibeTrap> {
382    if a[0] > a[1] || b[0] > b[1] {
383        return Err(VibeTrap::NumericalDomainError);
384    }
385    let code = if a[1] < b[0] {
386        1 // Before
387    } else if a[1] == b[0] {
388        2 // Meets
389    } else if a[0] == b[0] && a[1] == b[1] {
390        7 // Equals
391    } else if a[0] == b[0] && a[1] < b[1] {
392        4 // Starts
393    } else if a[0] > b[0] && a[1] < b[1] {
394        5 // During
395    } else if a[0] > b[0] && a[1] == b[1] {
396        6 // Finishes
397    } else if a[0] < b[0] && a[1] > b[0] && a[1] < b[1] {
398        3 // Overlaps
399    } else {
400        8 // Inverse / After
401    };
402    Ok(code)
403}
404
405/// Direct-call oracle for `modality::deontic::pack_norm_predicate`.
406#[inline]
407pub const fn oracle_pack_deontic_predicate(
408    prop_hash: u64,
409    opcode: u64,
410    is_defeater: bool,
411) -> Result<u64, VibeTrap> {
412    // Deontic opcodes must be in 0x10..=0x12 per AGENTS.md §1/§2
413    if opcode < 0x10 || opcode > 0x12 {
414        return Err(VibeTrap::NumericalDomainError);
415    }
416    let mut pred = ((prop_hash & 0x007F_FFFF_FFFF_FFFF) << 8) | (opcode & 0xFF);
417    if is_defeater {
418        pred |= 1u64 << 63;
419    }
420    Ok(pred)
421}