cuda-flux-debugger

The Deeper Connection.

FLUX VM debugging, tracing, and introspection tools. Part of the FLUX ecosystem alongside flux-runtime-c (VM execution) and flux-disasm (instruction decoding).

Features

• Breakpoints — unconditional, conditional (register, memory, confidence, energy thresholds)
• Watchpoints — detect memory mutations at specific addresses
• Execution tracing — full VM state capture at each instruction with human-readable and JSON output
• Performance profiling — opcode frequency, hot paths, bottleneck analysis
• Deterministic replay — capture sessions, replay them, diff to find non-determinism
• FLUX-aware — confidence propagation tracking, apoptosis warnings, trust check instrumentation

Quick Start

use cuda_flux_debugger::*;

let mut debugger = Debugger::new();

// Set a breakpoint
debugger.add_breakpoint(Breakpoint::with_condition(
    0x100,
    BreakCondition::ConfidenceBelow { threshold: 0.3 },
));

// Enable tracing
tracer::trace_enable(&mut debugger);

// At each VM step, capture state
let mut state = VmState::new();
state.pc = 0x100;
state.opcode = 0x04; // ADD
state.confidence = 0.1;
tracer::trace_record(&mut debugger, &state);

// Check if we should halt
if let Some(event) = debugger.check_breakpoints(&state) {
    println!("Debug event: {:?}", event);
}

// Profile the run
let session = profiler::profile_begin(&debugger);
// ... execute more instructions ...
let result = profiler::profile_end(&debugger, session);
println!("{}", profiler::bottleneck_analysis(&result));

Cross-Pollination

flux-runtime-c

The debugger consumes VmState snapshots that mirror the runtime's internal state. In production, the C runtime would export state via FFI at each instruction boundary. The replay system assumes deterministic execution matching flux-runtime-c's step semantics.

flux-disasm

Opcode names and operand decoding in tracer.rs align with flux-disasm's instruction definitions. The trace_to_string() output uses the same mnemonic names. Keep these in sync when adding new FLUX opcodes.

Modules

Module	Description
lib	Core types: Debugger, Breakpoint, TraceRecord, DebugEvent, VmState
tracer	Execution tracing: enable/disable, record, format output
profiler	Performance profiling: opcode stats, hot paths, bottleneck analysis
replay	Deterministic replay: capture, replay, diff sessions

License

MIT