feat(debug): --step — the eigsdap v1 CLI tape-stepper (#418)#538
Merged
Conversation
eigenscript --step <tape> [source.eigs] opens a recorded trace tape in an interactive time-travel debugger: step forward AND backward over L records, breakpoints as line filters (c/rc continue both directions), jump-to-line both ways, bindings reconstructed from A records at any position, and each binding's observer-trajectory label alongside its value — computed by the runtime's own #294 value-channel classifier (observer_slot_record_value is now exported; the stepper feeds reconstructed histories through a real ObserverSlot, so a label is by construction what report_value would have said at that moment). Stepping back rewinds the diagnosis, not just values. Pure tape reader — nothing executes; step-back is an index decrement. The #411 version rule is enforced exactly like replay (refuse-on-mismatch, exit 3). src/step.c is a CLI-only translation unit (Makefile CLI_ONLY), excluded from the embed/LSP/freestanding profiles; freestanding-check green. Suite section [42f] (tests/test_step.sh, 16 checks): stepping, the acceptance label-flip on back-step, breakpoints, jumps, all three #411 refusal classes, EOF quit, and driving a --test --trace-on-fail tape. Ships docs/DEBUGGING.md — failure→replay→interrogate, the stepper, and the temporal interrogatives unified — linked from both READMEs + TRACE.md. Release suite 2722/2722; ASan+detect_leaks 2722/2722, leak tally 0. Closes #418 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GdDAVfZHgoQ2UNP63FYUXm
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…te.sh build.sh carried its own copy of the source list and fell behind when step.c landed (third instance of the class — the install.sh/bench/matrix CI legs fail at link while make is green). Both scripts now read SOURCES and the CLI_ONLY drop set from the Makefile, the single source of truth, so a new translation unit cannot silently miss any build path again. Verified locally: build.sh, build.sh lsp, tools/amalgamate.sh (step.c correctly excluded from the embed amalgamation), make, freestanding-check. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GdDAVfZHgoQ2UNP63FYUXm
n is clamped to >=1 two lines up, so the conjunct was always true. The two cpp/path-injection alerts on main.c's --step block are the documented CLI false-positive class (#105/#107) — dismissed per-alert. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GdDAVfZHgoQ2UNP63FYUXm
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
eigenscript --step <tape> [source.eigs]— an interactive time-travel debugger over a recorded trace tape (from--trace,EIGS_TRACE, or a--test --trace-on-failfailure). Closes #418 (the issue's v1 scope; v2/v3 follow-up filed separately).c/rccontinue in both directions, jump-to-line both waysp), with each binding's observer-trajectory label alongside its valuet <name>: the running label per assignment — scrub to the exact step a binding flipped from[moving]to[oscillating]The honest part
Labels are computed by the runtime's own #294 value-channel classifier:
observer_slot_record_valueis exported and the stepper feeds reconstructed numeric histories through a realObserverSlot, so[converged]here is by construction whatreport_value of xwould have said at that moment. No mirror implementation to drift.The #411 version rule is enforced exactly as replay enforces it: format + runtime version must match this binary, else refuse with exit 3 — a viewer that guessed at a foreign encoding would show plausible-but-wrong state. Encoding untouched; no tape-format impact.
Acceptance (from the issue)
Stepping back through a failing run flips the culprit binding's label — pinned in the suite:
convreads[converged]at tape end,[moving]40 steps earlier. Works on a--trace-on-failtape (also pinned).Build & gates
src/step.cis a CLI-only translation unit (MakefileCLI_ONLY), excluded from embed/LSP/freestanding profiles;make freestanding-checkgreentests/test_step.sh)detect_leaks=12722/2722, leak tally 0; doc_drift_check clean🤖 Generated with Claude Code
https://claude.ai/code/session_01GdDAVfZHgoQ2UNP63FYUXm