Module debug_repl 

Interactive solver debugger front end — “pdb for the IPM”.

Implements pounce_algorithm::debug::DebugHook. The core fires us at every checkpoint (today: the top of each outer iteration); we pause, hand the user (or an agent) a command prompt, and apply inspect / mutate / flow commands against the live DebugCtx before returning DebugAction::Resume or DebugAction::Stop.

Two front ends share one command engine (SolverDebugger::dispatch):

• DebugMode::Repl — a human line REPL. Prompts and command output go to stderr so they never interleave with the solver’s iteration table on stdout.

• DebugMode::Json — a newline-delimited JSON protocol on stdin/stdout for an LLM agent, visual debugger, or any program. stdout is a pure protocol channel (the CLI routes the banner / problem stats / summary to stderr and forces print_level 0), so a GUI can consume it line-by-line. Session lifecycle:

  1. {"event":"hello",…} — once, up front: protocol version, advertised capabilities, command / metric / block vocabulary.
  2. {"event":"pause",…} — at each stop: iter, μ, residuals, dims, active breakpoints/conditions, and the firing reason.
  3. {"event":"result",…} — one per command, echoing the client’s request_id for async correlation.
  4. {"event":"terminated",…} — emitted by the CLI after the solve, carrying the final status, iteration count, objective, and eval counts.

  Commands may be a bare string or {"cmd":…,"args":[…],"id":…}.

Flow / exit model: the debugger pauses at the first checkpoint (so you get control at iter 0), then only when re-armed — by step (pause next iteration), break N (pause at iter N), break if … (pause on a condition), or run N (pause at iter ≥ N). Exit paths:

• continue — run to the next breakpoint, else to completion.
• detach — stop pausing; run to completion.
• quit — stop now (surfaces as UserRequestedStop).
• stdin EOF — REPL (Ctrl-D) detaches and finishes; JSON (pipe closed → client gone) aborts the solve.

Every non-kill path ends with a terminated event in JSON mode.

Modules

interrupt

SIGINT → “break into the debugger at the next iteration”. A first Ctrl-C sets a pending flag the hook consumes at the next checkpoint; a second Ctrl-C before that (or any Ctrl-C once detached) hard-exits, preserving the usual “abort” escape hatch.

Structs

EquationBook

Rendered constraint equations from the source model, indexed in original .nl row order. Lets the debugger answer print equation <name|row> with the actual algebra — the source expression for a constraint, resolved by its model name. This closes the loop on the residual-name labeling (print residuals): once a culprit equation is named, the user can read it. Naming and printing culprit equations rather than bare indices is the diagnostic recommendation of Lee et al. (2024, https://doi.org/10.69997/sct.147875).

RestartRequest

Request to re-run the solve from a captured point with new options. Written by the resolve command into the shared RestartCell and read by the CLI after the solve unwinds.

SolverDebugger

StructureBook

Structural rank analysis of the equality constraint Jacobian, after the Dulmage–Mendelsohn decomposition used by IDAES’s DiagnosticsToolbox. The Hessian-free, iterate-independent sparsity pattern alone tells us whether a subset of equations is over-determined — more equations than the variables they jointly touch — which forces at least one of them to be redundant or mutually inconsistent (a structurally singular Jacobian, LICQ failure).

Functions

print_open_banner

Print the branded open banner (human REPL only): the project POUNCE wordmark (shared with the solve header) over a brief command cheat sheet. Colour only on a TTY and unless NO_COLOR is set.

Type Aliases

RestartCell

Shared slot the debugger uses to hand a RestartRequest back to the CLI’s re-solve loop.