Struct LogicProgram 

pub struct LogicProgram { /* private fields */ }

A compiled Datalog program ready for GPU evaluation.

Implementations

impl LogicProgram

pub fn compile(source: &str) -> Result<Self>

Compile a Datalog source string into a GPU-executable program.

pub fn compile_program(program: Program) -> Result<Self>

Compile an already parsed program into a GPU-executable program.

This method does not resolve imports; import-aware callers merge them first. The program enters the canonical execution normalizer once here.

pub fn compile_with_resolver( source: &str, resolver: &ModuleResolver, ) -> Result<Self>

Compile a program with module resolution.

This method resolves all imports using the provided resolver and merges imported predicates, functions, and rules into the main program.

Pragmas are entry-file-scoped: directives declared in imported modules are dropped at merge time. This library entry point does not surface them — embedders that want the CLI’s warning[W0510] behavior should call resolver.ignored_import_pragmas() before compiling and report the returned records on their own diagnostics channel.

Arguments

• source - The source code of the main program
• resolver - A pre-loaded ModuleResolver with all dependencies resolved

Returns

The compiled LogicProgram with all imports merged

pub fn epistemic_plan_json(&self) -> Option<String>

Serialize the compiled epistemic execution plan to a JSON summary.

Returns None for ordinary (non-epistemic) programs. For epistemic programs this dumps the EIR-derived GPU plan(s): selected mode, the epistemic know/possible literals (with negation), required GPU hot-path phases/kernels, world-view integrity constraints, reduced-program head summaries, the fail-closed GPU execution policy, and a deterministic plan id (a stable hash of the canonical summary). Runtime evidence separately records observed dispatch, kernel, device-buffer, candidate-accounting, solver/probability event, and scoped-transfer behavior.

pub fn schema(&self, relation: &str) -> Option<&Schema>

Look up the schema for a named relation.

pub fn schemas(&self) -> &HashMap<String, Schema>

Return the full schema map (relation name to schema).

pub fn argument_schema( &self, relation: &str, ) -> Option<Vec<LogicArgumentSchema>>

Return ordered argument metadata for a compiled relation.

Column names and scalar types come from the compiled schema. Source declarations additionally preserve whether each name was explicit and which domain alias, if any, supplied its scalar type.

pub fn rule_provenance(&self) -> Vec<RuleProvenance>

Return stable rule provenance for source-visible rules.

pub fn proof_traces(&self) -> Vec<QueryProofTrace>

Return direct proof traces for source queries.

pub fn create_relation_store( &self, provider: Arc<CudaKernelProvider>, ) -> Result<RelationStore>

Create a persistent user-visible relation store initialized with inline facts.

pub fn evaluate_with_relation_store( &self, provider: Arc<CudaKernelProvider>, relation_store: &RelationStore, profiling: bool, ) -> Result<LogicEvalResult>

Evaluate using a persistent base relation store.

The provided store is treated as immutable seed state. Buffers are cloned into a fresh executor for each evaluation so repeated evaluations reuse stored relations without mutating the persistent store itself.

pub fn evaluate_with_relation_store_and_cache( &self, provider: Arc<CudaKernelProvider>, relation_store: &RelationStore, profiling: bool, ) -> Result<(LogicEvalResult, LogicMaterializedStore)>

Evaluate using a persistent relation store and return the complete runtime store.

pub fn create_session_runtime( &self, provider: Arc<CudaKernelProvider>, relation_store: &RelationStore, profiling: bool, ) -> Result<LogicSessionRuntime>

Create retained runtime state for a persistent relation session.

pub fn evaluate_with_session_runtime( &self, provider: Arc<CudaKernelProvider>, runtime: &mut LogicSessionRuntime, ) -> Result<(LogicEvalResult, LogicMaterializedStore)>

Evaluate with retained session runtime state and return a materialized store snapshot.

pub fn evaluate_cached_relation_store( &self, provider: Arc<CudaKernelProvider>, relation_store: &LogicMaterializedStore, ) -> Result<LogicEvalResult>

Build query results from an already materialized runtime store.

A raw relation store cannot attest that it was materialized by this compiled program:

use std::sync::Arc;
use xlog_core::Result;
use xlog_cuda::CudaKernelProvider;
use xlog_gpu::logic::LogicProgram;
use xlog_runtime::RelationStore;

fn evaluate_untrusted_store(
    program: &LogicProgram,
    provider: Arc<CudaKernelProvider>,
    raw_store: &RelationStore,
) -> Result<()> {
    program.evaluate_cached_relation_store(provider, raw_store)?;
    Ok(())
}

pub fn apply_relation_deltas( &self, provider: Arc<CudaKernelProvider>, relation_store: &mut RelationStore, cached_store: &mut Option<LogicMaterializedStore>, deltas: HashMap<String, RelationDelta>, ) -> Result<LogicDeltaReport>

Apply relation deltas to a persistent session store through the runtime delta path.

A cache from another compiled program is rejected without consuming it. After identity validation, an operational preparation failure leaves the authoritative relation store unchanged but discards the consumed cache.

pub fn apply_relation_deltas_with_session_runtime( &self, provider: Arc<CudaKernelProvider>, relation_store: &mut RelationStore, cached_store: &mut Option<LogicMaterializedStore>, session_runtime: &mut Option<LogicSessionRuntime>, deltas: HashMap<String, RelationDelta>, ) -> Result<LogicDeltaReport>

Apply relation deltas while preserving retained session runtime state.

State from another compiled program is rejected without consuming it. After identity validation, an operational preparation failure leaves the authoritative store unchanged and the derived-state slots empty.

pub fn prepare_relation_deltas_commit_with_session_runtime<'a>( &self, provider: Arc<CudaKernelProvider>, relation_store: &'a mut RelationStore, cached_store: &'a mut Option<LogicMaterializedStore>, session_runtime: &'a mut Option<LogicSessionRuntime>, deltas: HashMap<String, RelationDelta>, ) -> Result<PreparedRelationDeltaCommit<'a>>

Prepare raw relation deltas without ordered-batch coalescing.

This preserves the runtime’s delete-then-insert semantics when one relation delta contains both directions. Callers that accept an ordered batch must use LogicProgram::prepare_relation_delta_batch exactly once and pass its result to LogicProgram::prepare_relation_delta_commit_with_session_runtime. Foreign reusable state is rejected before it is consumed. Once identity validation succeeds, the current cache and runtime are consumed during preparation; on operational error their caller slots remain empty while the authoritative store remains unchanged.

pub fn prepare_relation_delta_batch( &self, provider: &CudaKernelProvider, delta_batch: Vec<(String, RelationDelta)>, cancellation_capture_relations: &BTreeSet<String>, ) -> Result<PreparedRelationDeltaBatch>

Coalesce an ordered batch on the device and retain cancellation tuples for selected relations.

pub fn clone_prospective_base_for_prepared_delta_batch( &self, provider: &Arc<CudaKernelProvider>, authoritative_relation_store: &RelationStore, prepared_batch: &PreparedRelationDeltaBatch, ) -> Result<RelationStore>

Build the prospective authoritative base store for an independent full-recompute diagnostic without consuming retained session state.

This must run before preparing the retained-runtime commit. If cloning or applying a base delta fails, the caller’s cache and session runtime remain available for subsequent evaluations.

pub fn prepare_relation_delta_commit_with_session_runtime<'a>( &self, provider: Arc<CudaKernelProvider>, relation_store: &'a mut RelationStore, cached_store: &'a mut Option<LogicMaterializedStore>, session_runtime: &'a mut Option<LogicSessionRuntime>, prepared_batch: PreparedRelationDeltaBatch, ) -> Result<PreparedRelationDeltaCommit<'a>>

Prepare a fully staged retained-runtime commit from a coalesced batch.

Foreign reusable state is rejected before the coalesced batch is consumed. Once identity validation succeeds, the current runtime and cache move into the transaction. An operational preparation failure discards those values and leaves the caller slots empty; the authoritative store is unchanged.

pub fn apply_relation_delta_batch( &self, provider: Arc<CudaKernelProvider>, relation_store: &mut RelationStore, cached_store: &mut Option<LogicMaterializedStore>, delta_batch: Vec<(String, RelationDelta)>, ) -> Result<LogicDeltaReport>

Apply an ordered batch of relation deltas after device-side coalescing.

A fully canceled batch returns a no-op report without changing the authoritative store or advancing derived runtime state. If preparation fails, the authoritative store remains unchanged. A foreign cache is rejected before device coalescing and is not consumed; after successful identity validation an operational failure may discard the cache.

pub fn apply_relation_delta_batch_with_session_runtime( &self, provider: Arc<CudaKernelProvider>, relation_store: &mut RelationStore, cached_store: &mut Option<LogicMaterializedStore>, session_runtime: &mut Option<LogicSessionRuntime>, delta_batch: Vec<(String, RelationDelta)>, ) -> Result<LogicDeltaReport>

Apply an ordered batch of relation deltas while preserving session runtime state.

A fully canceled batch returns a no-op report without changing the authoritative store or advancing derived runtime state. If preparation fails, the authoritative store remains unchanged while the derived cache and retained runtime slots are left empty. Foreign state is rejected before device coalescing and remains in the caller slots.

pub fn evaluate( &self, provider: Arc<CudaKernelProvider>, inputs: HashMap<String, CudaBuffer>, ) -> Result<LogicEvalResult>

Evaluate the program with the given input relations (no profiling).

pub fn evaluate_with_options( &self, provider: Arc<CudaKernelProvider>, inputs: HashMap<String, CudaBuffer>, profiling: bool, ) -> Result<LogicEvalResult>

Evaluate the program with optional profiling

Arguments

• provider - The CUDA kernel provider
• inputs - Input relations
• profiling - Whether to collect execution statistics

pub fn execute_epistemic_evidence( &self, provider: Arc<CudaKernelProvider>, inputs: HashMap<String, CudaBuffer>, ) -> Result<EpistemicGpuExecutionResult>

Execute an epistemic program and return its accepted GPU execution evidence.

evaluate reduces the epistemic result to query rows and drops the accepted world-view evidence with it. The probabilistic production adapter needs that evidence itself, so this entry point keeps the raw execution result.

Only single-component epistemic plans are supported: split, stratified and WFS plans produce several world views whose probabilistic conditioning contract is not settled yet, so they are rejected loudly rather than silently reduced.

“Ordinary” here names a plan kind, not the source. An admissible recursive modal program (reach(X, Z) :- reach(X, Y), know link(Y, Z).) is lowered by the Case-A reduction to ordinary recursion: the world-view machinery is erased, so no accepted world view survives to hand over and the program is rejected here despite being full of know. The rejection names the epistemic_provenance reduction class so the message explains the lowering instead of reading as a misclassification.

pub fn relation_stores_query_equivalent( &self, provider: &CudaKernelProvider, left: &RelationStore, right: &RelationStore, ) -> Result<bool>

Compare query result relations between two stores using GPU set difference.

Trait Implementations

impl Clone for LogicProgram

fn clone(&self) -> LogicProgram

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.