Module debug_session 

Scripted debug sessions (#3247/#3248): the shared verb set the test harness, the CLI debugger and the studio all drive, so there is one definition of “step over” rather than three. Scripted debug sessions — the shared verb set for driving a debugger (issue #3247, extracted here by #3248).

Why this lives in brink-runtime. Three consumers need one definition of “step over”: the scripted test harness, the CLI debugger, and the studio. brink-cli is a published crate, so it cannot depend on the test-only harness where this started; and a new crate purely to hold it would be publishable-but-unpublished, which CI’s own publishable check refuses until a maintainer publishes it by hand. brink-runtime already owns the debug vocabulary (debug_control’s BreakpointSet, StepMode, DebugRunOutcome), so this is its sibling rather than a new home. Gated behind debug-hooks, so a build without the debugger carries none of it.

Why debugger semantics need an artifact at all. They were otherwise defined only by Rust unit tests written alongside the code they test — so a refactor that quietly changes what step over does passes, because the test gets updated to match. A scripted transcript makes the behaviour itself the artifact.

Source level, never bytecode. Every assertion and transcript line is main.ink:7, a local’s name and value, a stack of frame names. Bytecode offsets churn on every codegen change; goldens written against them would break constantly and teach everyone to re-accept snapshots without reading them — worse than no goldens, because it launders real regressions through a habit.

Two granularities, both first-class (RULED 2026-08-28). stepi is VM-instruction stepping; step (and next) is line stepping. Neither is a wrapper over the other: the studio presents the .inkt disassembly beside the source, so an author can watch a line and the instructions it became at the same time. GDB’s vocabulary is borrowed on purpose — it is the convention every debugger user already has.

Lines are 1-based here. A script is a thing a person writes, and main.ink:7 means what every editor means by line 7. The engine is 0-based; the conversion happens at this one edge, which faces a human.

Structs

ScriptError

A script failed to parse. Carries the 1-based line number so a broken fixture points at itself.

Session

A driven debug session: the story, its breakpoints, and the sources needed to report positions in source terms.

Enums

Command

One action or assertion from a .dbg script.

Functions

parse_script

Parse a .dbg script. Line-oriented; # starts a comment; blank lines are skipped.

run_script

Run a parsed script, returning the transcript.