vyre-debug

vyre-debug is the static diagnostic and inspection toolkit for the Vyre 0.4.2 megakernel ecosystem.

Overview

This crate provides tools to validate, diff, and inspect Vyre's intermediate representation (IR) at the descriptor level, ensuring that passes like vyre-lower and vyre-emit-naga behave correctly. It is heavily utilized by vyre-bench and internal fuzzing infrastructure to catch regressions in descriptor equivalence and detect invalid control-flow rewrites.

Features

Dangling Reference Detection: Inspects nested KernelBody structures to catch references to SSA IDs that are out of scope, accounting for inherited results and completed child body variables.
Descriptor Diffing: Compares two kernel descriptors (e.g., before and after an optimization pass) and generates a structured summary of changes (dropped bindings, added bindings, operation counts).
WGSL Emission Inspection: Wraps vyre-emit-naga to provide validated, line-numbered WGSL dumps for any Program or KernelDescriptor.
Carrier Tracing: Identifies loops without valid loop carriers and summarizes reads/writes for debugging loop_carry and bank_conflict rewrites.
Scan Explain Reports: Summarizes scan decomposition metadata from descriptor intents and scan database headers, including extracted factors, selected engines, rejected accelerator candidates, verifier fragments, exactness class, verifier cost estimate, literal selectivity basis, streaming state, table bytes, baseline id, and release evidence links.

Command Line Interface

The crate provides the vyre-dbg executable for interactive debugging. It operates on a registry of hardcoded test fixtures.

# Dump the generated WGSL for the 'loop_carry_smoke' fixture
cargo run --bin vyre-dbg -- dump-wgsl --prog loop_carry_smoke --lines

# Check for dangling SSA references
cargo run --bin vyre-dbg -- find-dangling --prog c11_extract_calls --num-tokens 8

# Compare descriptors before and after lowering passes
cargo run --bin vyre-dbg -- diff-lower --prog c11_extract_calls --num-tokens 4

Architecture

As part of the Santh monorepo architecture, vyre-debug adheres to strict tier separation. It provides both a reusable library for agent-driven fuzzing and a standalone tool (vyre-dbg) for operational config.

All diagnostics are structured and support JSON emission (--json) for automated regressions.

License