Refine source stepping: line-start cursor (S19) and end-of-trace termination (S20)

Statement stepping rested the cursor on the DWARF column of a run's first
record — an arbitrary interior sub-expression that differed between visits of
the same line — and a forward step at the outermost function's closing brace
clamped in place, re-reporting the same line.

S19: the source frame now reports the line's first non-whitespace column
(falling back to the DWARF column only when the line text is unavailable), so
the cursor lands predictably at the start of the statement. Disassembly-row
columns are unchanged.

S20: a forward statement step (next/stepIn/stepOut) with no stop point ahead
now terminates the session — the replayed contract has returned from its
outermost recorded frame. Instruction stepping and wasm-less replay still clamp
(S2), continue/reverseContinue still settle (S14), reverse steps still clamp to
the first stop (S3/S8), and the epilogue-brace stop is still kept (S18).

Developed test-first (red -> green -> review): 24 tests pinned the new behavior
before implementation; full suite green (270 passing).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: RaoulSchaffranek

docs/stepping.md

@@ -64,10 +64,14 @@ frame) with no stop point at all.
   index 0. The user's first view is a real statement inside the invoked
   function, never the `#[contractimpl]` export shim or a bare signature line,
   and never a sourceless, addressless frame.
-- **S2** (forward exhaustion): a forward step (any kind, any granularity) with
-  no further stop point ahead moves to the **last** stop point of the trace
-  (staying put when already there) and still reports a stop. It never
-  strands the cursor on trailing invisible/unmapped records.
+- **S2** (forward exhaustion): a forward step with no further stop point ahead
+  never strands the cursor on trailing invisible/unmapped records. At
+  **instruction** granularity — and in wasm-less replay, where statement
+  stepping falls back to the visible records — it moves to the **last** stop
+  point of the trace (staying put when already there) and still reports a stop.
+  At **statement** granularity it instead **terminates the session** (S20): a
+  forward source step past the last source statement finishes the replay rather
+  than re-reporting the same line.
 - **S3** (backward exhaustion): a backward step with no earlier stop point
   moves to the **first** stop point (staying put when already there). It never
   falls off onto the unmapped records at the head of the trace.
@@ -80,13 +84,15 @@ frame) with no stop point at all.
 - **S5** (step over): `next` moves to the next run start whose depth is ≤ the
   current depth: a call inside the current line is stepped over in one press —
   including calls whose return is implicit (no `return` record). One press,
-  one new line.
+  one new line. Exhausted forward (no such run start ahead), it terminates the
+  session (S20).
 - **S6** (per-iteration loop stops): a source line that executes again (loop
   back-edge) is a **new** run: `next`/`stepIn` stop once per iteration, even
   when consecutive iterations are separated only by unmapped records.
 - **S7** (step out): `stepOut` moves to the next run start whose depth is <
-  the current depth. At the outermost recorded depth it behaves like S2
-  (runs to the last stop point).
+  the current depth. At the outermost recorded depth there is no shallower
+  stop, so a statement `stepOut` terminates the session (S20); at instruction
+  granularity it clamps to the last visible record (S2).
 - **S8** (reverse step): `stepBack` at statement granularity is the reverse of
   `next`: it moves to the start of the previous run with depth ≤ the current
   depth, skipping deeper-frame records. Landing is always on a run **start**
@@ -130,6 +136,27 @@ frame) with no stop point at all.
   the stack frame carries that record's source and line; the frame is
   sourceless only when the cursor legitimately rests on an unmapped stop point
   (instruction granularity, or no line info at all).
+- **S19** (line-start cursor): whenever the cursor rests on a mapped record, the
+  stack frame's source **column** is the 1-based position of the **first
+  non-whitespace character** of that source line — never the DWARF column,
+  which for an opt-0 line table points at an arbitrary interior sub-expression
+  (the `0` of `let mut acc = 0`, the `3` of `match x % 3`) and jumps
+  unpredictably between visits of the same line. A statement stop already rests
+  on the run start — the line's first executed instruction, before any
+  sub-expression's result is in hand — so with S19 the cursor lands at the
+  start of the statement, predictably, on every visit. Disassembly rows keep
+  their precise per-instruction DWARF columns (`disassembleRequest` is
+  unaffected); S19 governs only the source stack frame.
+- **S20** (statement forward-exhaustion terminates): a forward *statement* step
+  (`next`/`stepIn`/`stepOut`, granularity ≠ `instruction`, over the source
+  run-start stop set) that finds no qualifying stop point ahead ends the debug
+  session with a `TerminatedEvent` instead of clamping in place. The replayed
+  contract has returned from its outermost recorded frame; a user pressing
+  step-over at the closing brace expects the program to finish, not the cursor
+  to sit on the same line. Instruction-granularity forward steps still clamp
+  (S2), `continue`/`reverseContinue` still settle on the last/first stop (S14),
+  and reverse steps still clamp to the first stop (S3/S8) — only forward
+  *source* stepping past the end terminates.
 
 ### Statement stops: declarations and braces
 

src/debugAdapter/SorobanDebugSession.ts

@@ -23,7 +23,13 @@ import {
 import { DebugProtocol } from '@vscode/debugprotocol';
 import * as path from 'path';
 import { TraceModel } from './TraceModel';
-import { classifyLineRole, computeDepths, computeRunStarts, statementStops } from './stops';
+import {
+  classifyLineRole,
+  computeDepths,
+  computeRunStarts,
+  firstNonWhitespaceColumn,
+  statementStops,
+} from './stops';
 import { SourceMapper } from '../sourcemap/SourceMapper';
 import { Disassembly } from '../wasm/Disassembly';
 import { ResolvedTrace, SessionBackend, SorobanLaunchArgs } from './types';
@@ -304,9 +310,18 @@ export class SorobanDebugSession extends DebugSession {
     const frameName = `${renderInstr(rec.instr)}  [${this.model.cursor}/${this.model.length - 1}]`;
 
     // Unmapped records get no Source at all (and line 0): the client keeps
-    // showing the frame name instead of opening a wrong file.
+    // showing the frame name instead of opening a wrong file. S19: a mapped
+    // frame reports the line's first non-whitespace column, not the arbitrary
+    // DWARF sub-expression column; fall back to the DWARF column when the line
+    // text is unavailable or all-whitespace.
     const frame: DebugProtocol.StackFrame = loc
-      ? new StackFrame(FRAME_ID, frameName, new Source(path.basename(loc.path), loc.path), loc.line, loc.column ?? 0)
+      ? new StackFrame(
+          FRAME_ID,
+          frameName,
+          new Source(path.basename(loc.path), loc.path),
+          loc.line,
+          firstNonWhitespaceColumn(this.source.sourceTextForIndex(this.model.cursor)) ?? loc.column ?? 0,
+        )
       : new StackFrame(FRAME_ID, frameName);
     const reference = this.instructionPointerReference();
     if (reference !== undefined) {
@@ -443,7 +458,7 @@ export class SorobanDebugSession extends DebugSession {
   ): void {
     this.sendResponse(response);
     // S5/S10: step over — the next stop point not in a deeper frame.
-    this.stopAfter(() => this.moveCursor(this.stopPoints(args.granularity), 1, this.currentDepth()));
+    this.stepForward(args.granularity, this.currentDepth());
   }
 
   protected stepInRequest(
@@ -452,7 +467,7 @@ export class SorobanDebugSession extends DebugSession {
   ): void {
     this.sendResponse(response);
     // S4/S10: step in — the next stop point regardless of depth.
-    this.stopAfter(() => this.moveCursor(this.stopPoints(args.granularity), 1, Infinity));
+    this.stepForward(args.granularity, Infinity);
   }
 
   protected stepOutRequest(
@@ -461,8 +476,9 @@ export class SorobanDebugSession extends DebugSession {
   ): void {
     this.sendResponse(response);
     // S7: step out — the next stop point in a shallower frame; at the
-    // outermost recorded depth this exhausts and clamps like S2.
-    this.stopAfter(() => this.moveCursor(this.stopPoints(args.granularity), 1, this.currentDepth() - 1));
+    // outermost recorded depth this exhausts and terminates (S20) at statement
+    // granularity, or clamps like S2 at instruction granularity.
+    this.stepForward(args.granularity, this.currentDepth() - 1);
   }
 
   // --- Reverse stepping (time travel) ----------------------------------
@@ -472,8 +488,10 @@ export class SorobanDebugSession extends DebugSession {
     args: DebugProtocol.StepBackArguments,
   ): void {
     this.sendResponse(response);
-    // S8/S10: reverse step over — the previous stop point not in a deeper frame.
-    this.stopAfter(() => this.moveCursor(this.stopPoints(args.granularity), -1, this.currentDepth()));
+    // S8/S10: reverse step over — the previous stop point not in a deeper
+    // frame. Reverse steps always CLAMP to the first stop (S3/S8) and never
+    // terminate; S20 is forward-only.
+    this.stopAfter(() => this.moveCursorBackward(this.stopPoints(args.granularity), this.currentDepth()));
   }
 
   protected reverseContinueRequest(
@@ -563,34 +581,65 @@ export class SorobanDebugSession extends DebugSession {
   }
 
   /**
-   * Move the cursor to the nearest stop point in `direction` whose depth is
-   * <= `maxDepth`. With none ahead/behind, clamp to the last/first stop point
-   * (S2/S3/S7) — staying put when already there. An empty stop-point list
-   * (trace with no visible record at all) leaves the cursor where it is.
+   * Forward step (S2/S5/S7/S20): seek to the first stop point after the cursor
+   * whose depth is <= `maxDepth`, then report a stop. With no such stop ahead,
+   * a STATEMENT step (granularity !== 'instruction' over the source run-start
+   * stop set) TERMINATES the session (S20) — the replayed contract has returned
+   * from its outermost recorded frame — while an INSTRUCTION step, or a
+   * wasm-less replay with no run starts, clamps to the last stop point and
+   * reports a stop (S2). Emits its own event, so it is called directly (not via
+   * stopAfter): a termination must NOT be followed by a StoppedEvent.
    */
-  private moveCursor(points: readonly number[], direction: 1 | -1, maxDepth: number): void {
-    if (!this.model || points.length === 0) {
+  private stepForward(
+    granularity: DebugProtocol.SteppingGranularity | undefined,
+    maxDepth: number,
+  ): void {
+    if (!this.model) {
       return;
     }
+    const points = this.stopPoints(granularity);
     const cursor = this.model.cursor;
-    if (direction > 0) {
-      for (const i of points) {
-        if (i > cursor && this.depths[i] <= maxDepth) {
-          this.model.seek(i);
-          return;
-        }
+    for (const i of points) {
+      if (i > cursor && this.depths[i] <= maxDepth) {
+        this.model.seek(i);
+        this.sendEvent(new StoppedEvent('step', THREAD_ID));
+        return;
       }
+    }
+    // Nothing qualifying ahead.
+    if (granularity !== 'instruction' && this.runStarts.length > 0) {
+      // S20: a forward source step past the last statement ends the session.
+      this.sendEvent(new TerminatedEvent());
+      return;
+    }
+    // S2: instruction granularity / wasm-less replay clamps to the last stop
+    // point (staying put when already there) and still reports a stop.
+    if (points.length > 0) {
       this.model.seek(points[points.length - 1]);
-    } else {
-      for (let k = points.length - 1; k >= 0; k--) {
-        const i = points[k];
-        if (i < cursor && this.depths[i] <= maxDepth) {
-          this.model.seek(i);
-          return;
-        }
+    }
+    this.sendEvent(new StoppedEvent('step', THREAD_ID));
+  }
+
+  /**
+   * Reverse step (S3/S8): move the cursor to the nearest earlier stop point
+   * whose depth is <= `maxDepth`. With none behind, clamp to the first stop
+   * point (staying put when already there). An empty stop-point list (trace
+   * with no visible record at all) leaves the cursor where it is. Reverse steps
+   * always clamp and never terminate.
+   */
+  private moveCursorBackward(points: readonly number[], maxDepth: number): void {
+    if (!this.model || points.length === 0) {
+      return;
+    }
+    const cursor = this.model.cursor;
+    for (let k = points.length - 1; k >= 0; k--) {
+      const i = points[k];
+      if (i < cursor && this.depths[i] <= maxDepth) {
+        this.model.seek(i);
+        return;
       }
-      this.model.seek(points[0]);
     }
+    this.model.seek(points[0]);
   }
 
   /** The trace's first stop point: run start, else visible record, else 0. */

src/debugAdapter/stops.ts

@@ -230,6 +230,24 @@ export function statementStops(
   return result;
 }
 
+/**
+ * The 1-based column of the first non-whitespace character of a source line
+ * (S19). Returns null when the text is null or entirely whitespace, so the
+ * caller can fall back to the DWARF column. This is what a statement stop's
+ * stack frame reports instead of the arbitrary DWARF sub-expression column.
+ */
+export function firstNonWhitespaceColumn(text: string | null): number | null {
+  if (text === null) {
+    return null;
+  }
+  for (let i = 0; i < text.length; i++) {
+    if (!/\s/.test(text[i])) {
+      return i + 1;
+    }
+  }
+  return null;
+}
+
 /** Index of the sorted range containing `pos`, or -1 when outside all of them. */
 function functionIndexAt(ranges: readonly FunctionRange[], pos: number): number {
   let lo = 0;

test/dap.test.ts

@@ -184,12 +184,9 @@ describe('SorobanDebugSession (DAP replay)', () => {
       assert.strictEqual(frame.line, 16);
       assert.ok(frame.name.includes('[29/40]'), `unexpected frame name: ${frame.name}`);
 
-      // Statement granularity: the :16 body is the only statement stop, so a
-      // step stays put on it (the :12 shim runs are dropped by S17).
-      await stopAfter(dc.nextRequest({ ...THREAD, granularity: 'statement' }), 'step');
-      frame = await topFrame();
-      assert.ok(frame.source?.path?.endsWith(LIB_RS_SUFFIX));
-      assert.strictEqual(frame.line, 16);
+      // (A forward statement next here would exhaust the single stop and END the
+      // session under S20 — see the dedicated S20 test below — so it is omitted
+      // from this breakpoint/reverse-continue flow.)
 
       // Move forward off the run start, then reverse-continue lands on the same
       // run START (29), not on the run's last record (33).
@@ -231,16 +228,21 @@ describe('SorobanDebugSession (DAP replay)', () => {
       assert.ok(frame.name.includes('[40/40]'), `unexpected frame name: ${frame.name}`);
     });
 
-    it('default-granularity next clamps on the single statement stop', async () => {
+    it('S20: default-granularity next past the single statement stop terminates', async () => {
       await launchAndStop(WITH_WASM);
       // The entry stop is the only statement stop, lib.rs:16 (record 29); the
-      // :12 #[contractimpl] runs are dropped by S17, so a default-granularity
-      // next has nowhere to advance and stays put (S2).
-      await stopAfter(dc.nextRequest(THREAD), 'step');
-      const frame = await topFrame();
-      assert.ok(frame.source?.path?.endsWith(LIB_RS_SUFFIX), `unexpected source: ${frame.source?.path}`);
-      assert.strictEqual(frame.line, 16);
-      assert.ok(frame.name.includes('[29/40]'), `unexpected frame name: ${frame.name}`);
+      // :12 #[contractimpl] runs are dropped by S17. A default-granularity next
+      // (granularity !== 'instruction', so it is a statement step) has nowhere to
+      // advance and ENDS the session (S20) instead of clamping in place. Race
+      // 'terminated' vs 'stopped' so a clamp-in-place regression fails fast
+      // rather than blocking on a 'stopped' that never comes.
+      const req = dc.nextRequest(THREAD);
+      const ended = await Promise.race([
+        dc.waitForEvent('terminated').then(() => true),
+        dc.waitForEvent('stopped').then(() => false),
+      ]);
+      await req;
+      assert.ok(ended, 'expected the default-granularity next past the last statement stop to terminate (S20)');
     });
 
     it('instruction-granularity stepIn advances exactly one record', async () => {