Module rules 

Hot-swappable compiled rule artifacts.

Per docs/superpowers/specs/2026-04-17-v1.1-vyngraph-gaps.md section 3.3, this module lets RingKernel accept opaque compiled rule artifacts (PTX + metadata) and hot-swap them atomically without runtime restart.

Design philosophy

RingKernel stays rule-format-agnostic. Callers such as VynGraph own OWL 2 RL / SHACL parsing and compile rules to PTX using our existing ringkernel-cuda-codegen pipeline. RingKernel receives the compiled artifact via CompiledRule and manages versioning, validation, rollback, and the atomic swap state machine.

Artifact lifecycle

CompiledRule  ─register_rule()─►  RuleStatus::Registered
     │                                    │
     │         reload_rule()              │
     ▼                                    ▼
(new version) ─pre_stage/quiesce/swap─► RuleStatus::Active
                                             │
     prior version: Superseded(new_ver)      │
                                             │
                      rollback_rule() ◄──────┤
     current version: Rolledback                │
     prior version: Active                      │

Guarantees

• Version monotonicity (downgrades rejected unless explicit rollback)
• Bounded history (FIFO eviction beyond max_history)
• Validation-before-swap (compute cap, dependencies, signature)
• Pluggable swap backend (NoopSwapBackend for tests, CUDA in production)

Example

use std::sync::Arc;
use ringkernel_core::rules::{
    ActorConfig, CompiledRule, NoopSwapBackend, RuleMetadata, RuleRegistry,
};

let registry = RuleRegistry::new(5, Arc::new(NoopSwapBackend));
let rule = CompiledRule {
    rule_id: "gaap-consolidation".into(),
    version: 1,
    ptx: b".version 8.0\n.target sm_90\n".to_vec(),
    compute_cap: "sm_90".into(),
    depends_on: vec![],
    signature: None,
    actor_config: ActorConfig::default(),
    metadata: RuleMetadata::default(),
};
let handle = registry.register_rule(rule, "sm_90").await.unwrap();
assert_eq!(handle.version, 1);

HotReloadManager::rule_registry() exposes the registry for use by existing multi-GPU hot-reload plumbing.

Re-exports

pub use registry::NoopSwapBackend;

pub use registry::RuleRegistry;

pub use registry::RuleSwapBackend;

pub use registry::SignatureVerifier;

Modules

registry

Rule registry: version history, validation, and swap orchestration.

Structs

ActorConfig

Launch configuration for the rule’s actor kernel.

CompiledRule

A compiled rule artifact ready for GPU hot-swap.

ReloadReport

Report emitted after a successful reload (or rollback).

RuleHandle

Lightweight handle returned after a successful registry operation.

RuleMetadata

Opaque metadata attached to a compiled rule.

Enums

RuleError

Errors produced by the rule registry.

RuleStatus

Lifecycle status of a specific rule version.