CRPT Engine - Rust Implementation

A stack-only, function-pointer-only instantiation of Compositional Recursive Projection Theory (CRPT) with five minimal axioms.

Architecture Overview

Two-Layer Design

Layer 1: Compositional Projection (A1-A5)

• Five minimal first-order axioms
• Projection operator P
• Semantic equivalence
• Assembly index (complexity measure)
• Substrate operations
• Module: crpt_comp

Layer 2: Categorical Projection

• Extensions of Compositional Projection
• Morphism codes and reification
• Categorical structures
• Regime-based constructions
• Module: crpt_cat

Facade: CRPT Engine

• Unified public API
• Storage management
• Composition operations
• Law verification
• Categorical validation
• Module: crptengine

Module Structure

src/
├── lib.rs                      # Library entry point (reexports)
├── error.rs                    # Error types and context
├── logging.rs                  # Logging infrastructure
├── storage.rs                  # Stack-only fixed-capacity storage
├── composition.rs              # Composition operations
├── law_verification.rs         # Law verification infrastructure
├── categorical_validation.rs   # Categorical validation infrastructure
├── api_utils.rs                # API utilities (context, result types)
├── crpt_comp/                  # Layer 1: Compositional Projection
│   ├── mod.rs                  # Reexports
│   ├── axioms.rs               # A1-A5 axiom definitions
│   ├── projection.rs           # Projection operator P
│   ├── substrate.rs            # Substrate and substrate elements
│   ├── equivalence.rs          # Semantic equivalence relation
│   └── assembly_index.rs       # Assembly index complexity measure
├── crpt_cat/                   # Layer 2: Categorical Projection
│   ├── mod.rs                  # Reexports
│   ├── regimes.rs              # Regime types
│   ├── morphism_codes.rs       # Morphism reification
│   └── categorical_structure.rs # Category and functor structures
├── crptengine/                 # Facade API
│   ├── mod.rs                  # Reexports and important types
│   └── crptengine.rs           # Main implementation
└── bin/
    └── main.rs                 # Example binary entry point

Core Principles

No Heap Allocations

• All data structures are stack-allocated with fixed capacity
• Capacities configured via StorageConfig
• No dynamic growth; all capacity bounded at compile time

Function Pointers Only

• No closures or lambda functions
• All extensibility via function pointer types
• Clean separation between implementation and pluggable handlers

All Code is Used

• No PhantomData - all fields serve explicit purposes
• No unused imports - all modules only import what they use
• No unused variables - all variables have specific purposes
• No underscore pattern - no hiding or silencing of warnings
• No dead functions - all functions are called and tested

Explicit Error Handling

• Every fallible operation returns Result<T, CrptError>
• All errors have specific ErrorKind variants
• All errors include ErrorContext with function, module, and details
• No unwrap() or panic() in production code

Key Types

Error Handling

• CrptError - Complete error type with kind and context
• ErrorKind - Enumeration of all possible error types
• ErrorContext - Error location and details (function, module, message)

Logging

• Logger - Logger with function pointer sink
• LogLevel - Debug, Info, Warn, Error
• LogComponent - System component classification
• LogEvent - Single log event
• LogSink - Function pointer for log sinks

Storage

• Storage - Fixed-capacity stack-only storage
• StorageConfig - Configuration with capacities
• ElementHandle - Handle to stored element
• MorphismHandle - Handle to stored morphism
• StoredElement - Element metadata
• StoredMorphism - Morphism metadata

Composition

• Composition - Composition operator handler
• CompositionOp - Operation type enumeration
• CompositionResult - Result of composition operation

Validation

• LawVerifier - Law verification handler
• CategoricalValidator - Categorical validation handler
• VerificationResult - Valid, Invalid, IncompleteData
• ValidationResult - Valid, Invalid, Uncertain

Engine

• CrptEngine - Main engine coordinator
• EngineConfig - Engine configuration
• EngineState - Engine state enumeration
• ApiContext - Context for API operations

Constraints and Requirements

See AGENTS.md for complete development guidelines.

Core Constraints

• ✗ No heap allocations
• ✗ No closures
• ✗ No PhantomData
• ✗ No unused code
• ✗ No underscore variables
• ✓ All fields used
• ✓ All functions called
• ✓ All imports used
• ✓ Explicit error handling

Design Pattern: mod.rs Files

All mod.rs files contain ONLY:

1. Reexports from implementation files
2. Important trait/enum definitions
3. Module-level documentation

All implementation code goes in separate files (e.g., module/module.rs or module/submodule.rs).

Example structure:

// module/mod.rs - Reexports and important types
//! Module documentation.

mod implementation;
pub use implementation::{PublicType, PublicFunction};

pub trait ImportantTrait { /* ... */ }

// module/implementation.rs - All actual code
use crate::module::ImportantTrait;

pub struct PublicType { /* ... */ }
pub fn public_function() { /* ... */ }

Building

Build library

cargo build --lib

Build release

cargo build --release

Run example binary

cargo build --bin crpt_engine --release
./target/release/crpt_engine

Run tests

cargo test

Check for warnings

cargo clippy

Example Usage

use crpt_engine::{CrptEngine, EngineConfig, StorageConfig};

fn main() {
    let storage_config = StorageConfig::new(256, 512, 128);
    let config = EngineConfig::new(storage_config, 16)
        .with_logging(true);

    let engine = CrptEngine::new(config);

    match engine.validate() {
        Ok(valid) => {
            println!("Engine valid: {}", valid);
            println!("Storage capacity: {}", 
                engine.storage().element_count());
        }
        Err(err) => eprintln!("Error: {}", err),
    }
}

Testing

All modules include comprehensive tests:

• Creation tests
• Happy path tests
• Error condition tests
• Boundary/overflow tests

Tests use explicit Result assertions, not unwrap().

Example:

#[test]
fn storage_overflow() {
    let config = StorageConfig::new(2, 512, 128);
    let mut storage = Storage::new(config);
    
    let elem = StoredElement::new(1, 0, true);
    storage.store_element(elem).expect("first store failed");
    storage.store_element(elem).expect("second store failed");
    
    let result = storage.store_element(elem);
    assert!(result.is_err());
}

Function Pointer Pattern

All pluggable behavior uses function pointers:

pub type CustomFn = fn(Args) -> Result<Output, CrptError>;

pub struct Handler {
    custom_fn: CustomFn,
}

impl Handler {
    pub fn new(custom_fn: CustomFn) -> Self {
        Handler { custom_fn }
    }

    pub fn execute(&self, args: Args) -> Result<Output, CrptError> {
        (self.custom_fn)(args)
    }
}

Performance

• Stack-only allocation with zero-copy designs where possible
• Fixed-capacity bounded by configuration
• Function pointers have zero runtime cost
• No dynamic allocation overhead
• Deterministic execution paths

Future Work

1. Implement full A1-A5 axiom checkers
2. Complete compositional projection layer
3. Implement categorical projection extensions
4. Formal verification integration
5. Performance optimizations
6. Parallel composition support

Documentation

• AGENTS.md - Complete development guidelines
• src/lib.rs - Library documentation
• Each module has comprehensive doc comments
• All public items documented with examples

License

GPL-3.0-only

---

Version: 0.1.0
Last Updated: February 1, 2026
Status: Active Development