feat(debug): PostDebugSession.stepInstruction() (7.0.0-alpha.7, #101)

[mellonis]

Summary

Adds PostDebugSession.stepInstruction() — a Post-level step control that advances to the next numbered Post instruction in the current scope. Resolves #101. Post-only bump 7.0.0-alpha.6 → 7.0.0-alpha.7.

Semantics

Two rules cover the full semantics:

1. Advance until the click-time (scope, instructionIndex) pair changes — sub-step transitions (inside groups) and sub-scope descents (call('foo') → foo::1) stay silent.
2. If there's no next numbered instruction in the current scope (you hit stop or fall through the end), the natural engine continuation fires — return to caller's continuation if inside a call/group, halt if at top level.

Position-independent. Same behavior whether paused at an atomic instruction, a call(...) entry, a group entry, mid-group, or inside a called scope. Resolves the "interp A vs interp B" fork from the issue body — only the user's numbered instructions count.

Implementation

• Anchors (clickScope, clickInstructionIndex) from the latest pause's arrivalPath.
• Drives the engine via repeated internal stepIn. On each step-cause pause, if the path is still "inside the click-time instruction" (same scope+index, sub-step transition, OR descended into a sub-scope), keep stepping silently. Otherwise surface as a normal step-cause pause.
• Breakpoints / external pause() mid-advance surface normally and consume the stepInstruction intent.
• Throws if called without a paused state.

Behavior across positions

Paused at	stepInstruction outcome
Atomic 10: mark (in main)	20
At a call('foo') entry	run the call to completion + return → caller's next
At a group entry	run the group to completion + return → caller's next
Mid-group sub-step	finish the rest of the group + return → caller's next
Inside foo at foo::N (non-last)	next numbered in foo's scope (foo::N+1)
Inside foo at last numbered	returns to caller's continuation
At a non-stop numbered, next numbered is terminal stop	engine halts (no pause before stop)

Test plan

• 7 new tests in PostMachine.debugger.spec.ts covering all rows in the behavior table
• Full suite: 330/330 pass (was 323; +7 new)
• npm run check / lint / build clean
• npm publish --dry-run --workspace @post-machine-js/machine --tag next — tarball clean at 7.0.0-alpha.7
• After merge: npm publish --tag next from packages/machine/
• After publish: gh release create v7.0.0-alpha.7 --target v7 --prerelease

Compatibility

• Peer dep @turing-machine-js/machine widened ^7.0.0-alpha.6 → ^7.0.0-alpha.7. (Semver-prerelease caret already accepted alpha.7+; the widening is the workspace convention.)
• Existing stepIn / stepOver / stepOut / continue / pause / stop / setRunInterval controls unchanged.

Issue thread

• #101 — original proposal
• Resolution comment: PostDebugSession: add instruction-granularity step (stepInstruction()) — step to next instruction index, skipping group sub-steps #101 (comment)