Add DWARF-driven Rust source-level Variables view

Debug Soroban contracts at the Rust level: a new "Variables" scope resolves
named locals/params with their types and values, expandable for structs, enums,
slices and strings — driven by the contract wasm's DWARF, replacing the raw
wasm locals/stack view.

New pure DWARF subsystem under src/dwarf/:
  - forms.ts / die.ts: value-returning form reader + full DIE-tree parse with a
    global offset index (CU-relative and cross-CU ref resolution).
  - TypeRegistry.ts: lazy, cycle-safe decoded type model (base/pointer/struct/
    union/array/enum/Rust variant_part enums/typedef/qualifier).
  - locexpr.ts / debugLoc.ts: DWARF location/expression evaluator
    (DW_OP_WASM_location incl. the kind-3 fixed-u32 case, DW_OP_fbreg via the
    frame base, addr/plus_uconst/stack_value) + v4 .debug_loc selection.
  - ScopeIndex.ts: PC -> function -> in-scope variables (high_pc-as-size,
    lexical-block ranges, .debug_ranges).
  - ValueDecoder.ts: type-aware value + lazy children, with &str/slice/Option
    recognition, budgets and cycle guards; never throws.
  - DebugInfo.ts: fromWasm facade, mirroring DwarfLineTable.

Runtime + wiring:
  - trace.ts consumes komet-node's new per-step linear-memory snapshots (hex
    sparse runs; null = unchanged) and globals; MemoryImage reconstructs memory
    at any replay cursor; runtimeState bridges a record to the DWARF evaluator.
  - VariableResolver (Dwarf/Null) mirrors the SourceMapper split; threaded
    through buildDebugArtifacts and both backends; SorobanDebugSession exposes
    the source Variables scope with lazily-expandable children.

Performance: the wasm uploaded to komet-node is now debug-stripped
(stripDebugSections) — carrying DWARF into the executed module bloated the KORE
config ~3x and stalled the RPC path; the code section is byte-identical so trace
positions still align with the full DWARF used for resolution.

Tested per module (unit) plus end-to-end variable inspection over a real komet
trace: dapMemoryVariables and the TurnkeyPipeline mock-node test both resolve a
shadow-stack parameter (by: u32 == 5) from linear memory; a gated live test
(KOMET_NODE_E2E) covers the full stack against a real komet-node.

Author: RaoulSchaffranek

src/debugAdapter/MemoryImage.ts

@@ -0,0 +1,72 @@
+/**
+ * Reconstructs WASM linear memory at a replay cursor from the FULL sparse
+ * snapshots carried by a trace (see src/komet/trace.ts). Each record's `mem`
+ * (when present) is the whole module memory at that step; a record with no
+ * snapshot (`undefined`) leaves the memory unchanged since the previous one.
+ * So the memory at a cursor is simply the latest snapshot at an index <=
+ * cursor — no folding across records. Any byte not covered by a run reads as 0
+ * (wasm memory is zero-initialized), including before the first snapshot.
+ *
+ * The index of that latest snapshot is precomputed once per record, so a read
+ * (forward or backward) is a direct lookup plus a copy of the overlapping runs.
+ *
+ * Pure module (no `vscode` / DAP imports).
+ */
+
+import { TraceRecord } from '../komet/trace';
+
+export class MemoryImage {
+  private readonly records: ReadonlyArray<TraceRecord>;
+  /**
+   * For each record index i, the greatest index j <= i whose record carries a
+   * `mem` snapshot, or -1 when no snapshot exists at or before i.
+   */
+  private readonly lastSnapshotAt: number[];
+
+  constructor(records: ReadonlyArray<TraceRecord>) {
+    this.records = records;
+    this.lastSnapshotAt = new Array(records.length);
+    let last = -1;
+    for (let i = 0; i < records.length; i++) {
+      if (records[i].mem !== undefined) {
+        last = i;
+      }
+      this.lastSnapshotAt[i] = last;
+    }
+  }
+
+  /**
+   * The `size` bytes at `[addr, addr+size)` as of the latest snapshot at or
+   * before `cursor`. Never-covered bytes (and everything before the first
+   * snapshot) read as 0. Returns a fresh `Uint8Array` of length `size`, or
+   * `undefined` for `size <= 0` / `addr < 0`.
+   */
+  readMemory(cursor: number, addr: number, size: number): Uint8Array | undefined {
+    if (size <= 0 || addr < 0) {
+      return undefined;
+    }
+    const out = new Uint8Array(size);
+
+    if (this.records.length === 0) {
+      return out;
+    }
+    const clamped = Math.max(0, Math.min(cursor, this.records.length - 1));
+    const j = this.lastSnapshotAt[clamped];
+    if (j < 0) {
+      // No snapshot at or before the cursor: memory is all zeros.
+      return out;
+    }
+
+    const runs = this.records[j].mem!;
+    const end = addr + size;
+    for (const run of runs) {
+      const runEnd = run.addr + run.bytes.length;
+      const from = Math.max(addr, run.addr);
+      const to = Math.min(end, runEnd);
+      for (let a = from; a < to; a++) {
+        out[a - addr] = run.bytes[a - run.addr];
+      }
+    }
+    return out;
+  }
+}

src/debugAdapter/SorobanDebugSession.ts

@@ -31,10 +31,15 @@ import {
   statementStops,
 } from './stops';
 import { SourceMapper } from '../sourcemap/SourceMapper';
+import { VariableResolver, NullVariableResolver } from '../sourcemap/VariableResolver';
 import { Disassembly } from '../wasm/Disassembly';
 import { ResolvedTrace, SessionBackend, SorobanLaunchArgs } from './types';
 import { TypedValue } from '../komet/trace';
 import { renderInstr } from '../komet/mnemonics';
+import { MemoryImage } from './MemoryImage';
+import { makeRuntimeState } from './runtimeState';
+import { DecodedValue, ChildVar } from '../dwarf/ValueDecoder';
+import { ScopeVar } from '../dwarf/ScopeIndex';
 
 const THREAD_ID = 1;
 const FRAME_ID = 1;
@@ -43,6 +48,7 @@ const FRAME_ID = 1;
 enum ScopeRef {
   Locals = 1,
   Stack = 2,
+  SourceVars = 3,
 }
 
 export class SorobanDebugSession extends DebugSession {
@@ -91,6 +97,16 @@ export class SorobanDebugSession extends DebugSession {
   private instructionBreakpointAddrs: number[] = [];
   /** Container handles for structured variable expansion. */
   private readonly variableHandles = new Handles<TypedValue[]>();
+  /** Source-level variable resolver (Null until a DWARF-bearing wasm loads). */
+  private variables: VariableResolver = new NullVariableResolver();
+  /** Folded linear-memory view for decoding memory-backed source variables. */
+  private memoryImage?: MemoryImage;
+  /**
+   * Handles for lazily-expanded source-variable children. High start avoids
+   * colliding with the fixed ScopeRef range; reset on every stop so refs are
+   * fresh per cursor position.
+   */
+  private readonly sourceVarChildren = new Handles<() => ChildVar[]>(1000);
 
   constructor(backend: SessionBackend) {
     super();
@@ -137,6 +153,8 @@ export class SorobanDebugSession extends DebugSession {
       const resolved: ResolvedTrace = await this.backend.resolve(args, (msg) => this.log(msg));
       this.model = resolved.model;
       this.source = resolved.source;
+      this.variables = resolved.variables;
+      this.memoryImage = new MemoryImage(this.model.records);
       this.disassembly = resolved.disassembly;
       this.positions = resolved.positions;
       this.validatedPosToIndices = new Map();
@@ -351,6 +369,24 @@ export class SorobanDebugSession extends DebugSession {
     return undefined;
   }
 
+  /**
+   * The current record's validated code offset, or — when it has none — the
+   * NEAREST earlier record that does, so in-scope variable lookup stays
+   * anchored on the last real instruction. Null when no record qualifies.
+   */
+  private currentPc(): number | null {
+    if (!this.model) {
+      return null;
+    }
+    for (let i = this.model.cursor; i >= 0; i--) {
+      const pos = this.positions[i];
+      if (pos !== null && pos !== undefined) {
+        return pos;
+      }
+    }
+    return null;
+  }
+
   protected disassembleRequest(
     response: DebugProtocol.DisassembleResponse,
     args: DebugProtocol.DisassembleArguments,
@@ -403,12 +439,18 @@ export class SorobanDebugSession extends DebugSession {
     response: DebugProtocol.ScopesResponse,
     _args: DebugProtocol.ScopesArguments,
   ): void {
-    response.body = {
-      scopes: [
-        new Scope('Locals', ScopeRef.Locals, false),
-        new Scope('Value Stack', ScopeRef.Stack, false),
-      ],
-    };
+    // Fresh child-expansion refs per stop: last cursor's handles are stale.
+    this.sourceVarChildren.reset();
+    const scopes: Scope[] = [
+      new Scope('Locals', ScopeRef.Locals, false),
+      new Scope('Value Stack', ScopeRef.Stack, false),
+    ];
+    // The source-level Variables scope is offered only when the resolver has
+    // DWARF functions; without it the list is exactly [Locals, Value Stack].
+    if (this.variables.hasVariables()) {
+      scopes.unshift(new Scope('Variables', ScopeRef.SourceVars, false));
+    }
+    response.body = { scopes };
     this.sendResponse(response);
   }
 
@@ -419,6 +461,39 @@ export class SorobanDebugSession extends DebugSession {
     const variables: DebugProtocol.Variable[] = [];
     const rec = this.model?.current;
 
+    if (args.variablesReference === ScopeRef.SourceVars) {
+      // Source-level variables: resolve the in-scope DWARF variables at the
+      // current PC and decode each against the folded runtime state.
+      if (this.model && this.memoryImage) {
+        const pc = this.currentPc();
+        if (pc !== null) {
+          const state = makeRuntimeState(this.model.current, this.memoryImage, this.model.cursor);
+          for (const v of this.variables.variablesInScope(pc) as ScopeVar[]) {
+            const decoded = this.variables.decodeVariable(v, state, pc);
+            variables.push(this.toDapVariable(v.name ?? '<anon>', decoded));
+          }
+        }
+      }
+      response.body = { variables };
+      this.sendResponse(response);
+      return;
+    }
+
+    const childThunk = this.sourceVarChildren.get(args.variablesReference);
+    if (childThunk) {
+      // A lazily-expanded source-variable container handed out via toDapVariable.
+      try {
+        for (const child of childThunk()) {
+          variables.push(this.toDapVariable(child.name, child.value));
+        }
+      } catch {
+        variables.push({ name: '<error>', value: '<unreadable>', variablesReference: 0 });
+      }
+      response.body = { variables };
+      this.sendResponse(response);
+      return;
+    }
+
     if (rec) {
       if (args.variablesReference === ScopeRef.Locals) {
         for (const [index, tv] of Object.entries(rec.locals)) {
@@ -666,6 +741,16 @@ export class SorobanDebugSession extends DebugSession {
     };
   }
 
+  /**
+   * Render a decoded source-level value as a DAP variable. Expandable values
+   * register their lazy children behind a fresh `sourceVarChildren` handle;
+   * leaves report a zero reference (not expandable).
+   */
+  private toDapVariable(name: string, decoded: DecodedValue): DebugProtocol.Variable {
+    const variablesReference = decoded.children ? this.sourceVarChildren.create(decoded.children) : 0;
+    return { name, value: decoded.display, type: decoded.typeName, variablesReference };
+  }
+
   private log(message: string): void {
     this.sendEvent(new OutputEvent(`${message}\n`, 'console'));
   }

src/debugAdapter/artifacts.ts

@@ -26,6 +26,8 @@ import { normalizeMnemonic } from '../komet/mnemonics';
 import { SourceMapper } from '../sourcemap/SourceMapper';
 import { DwarfSourceMapper } from '../sourcemap/DwarfSourceMapper';
 import { NullSourceMapper } from '../sourcemap/NullSourceMapper';
+import { VariableResolver, NullVariableResolver, DwarfVariableResolver } from '../sourcemap/VariableResolver';
+import { DwarfDebugInfo } from '../dwarf/DebugInfo';
 
 /**
  * Validate each record's `pos` against the static disassembly: the position is
@@ -67,7 +69,7 @@ export function buildDebugArtifacts(
   wasm: Uint8Array,
   model: TraceModel,
   report: ProgressReporter,
-): { source: SourceMapper; disassembly: Disassembly; positions: (number | null)[] } {
+): { source: SourceMapper; variables: VariableResolver; disassembly: Disassembly; positions: (number | null)[] } {
   let disassembly: Disassembly;
   try {
     disassembly = Disassembly.fromWasm(wasm);
@@ -81,6 +83,7 @@ export function buildDebugArtifacts(
     // (there is no independent ground truth to validate against).
     return {
       source: new NullSourceMapper(),
+      variables: new NullVariableResolver(),
       disassembly: Disassembly.fromTrace(model),
       positions: model.records.map((rec) => rec.pos),
     };
@@ -96,17 +99,41 @@ export function buildDebugArtifacts(
         `Warning: could not parse the wasm's DWARF debug info (${errorMessage(err)}); ` +
           'debugging continues at the wasm level.',
       );
-      return { source: new NullSourceMapper(), disassembly, positions };
+      return { source: new NullSourceMapper(), variables: resolveVariables(wasm, report), disassembly, positions };
     }
     throw err;
   }
   if (table === null || table.entries.length === 0) {
     report('Note: the contract wasm carries no DWARF line info; debugging continues at the wasm level.');
-    return { source: new NullSourceMapper(), disassembly, positions };
+    return { source: new NullSourceMapper(), variables: resolveVariables(wasm, report), disassembly, positions };
   }
 
   const source = new DwarfSourceMapper(model, table, positions);
-  return { source, disassembly, positions };
+  return { source, variables: resolveVariables(wasm, report), disassembly, positions };
+}
+
+/**
+ * Resolve the source-level variable resolver from the wasm bytes, in its own
+ * INDEPENDENT try/catch so a variable-resolution failure never disables the
+ * line table (callers have already committed their SourceMapper by this point).
+ * Degrades to a NullVariableResolver — the wasm-level variables view.
+ */
+function resolveVariables(wasm: Uint8Array, report: ProgressReporter): VariableResolver {
+  try {
+    const dwarf = DwarfDebugInfo.fromWasm(wasm);
+    if (dwarf && dwarf.scopes.hasFunctions()) {
+      return new DwarfVariableResolver(dwarf);
+    }
+  } catch (err) {
+    if (err instanceof DwarfParseError || err instanceof WasmFormatError) {
+      report(
+        `Warning: could not parse DWARF variable info (${errorMessage(err)}); variables view stays wasm-level.`,
+      );
+    } else {
+      throw err;
+    }
+  }
+  return new NullVariableResolver();
 }
 
 function errorMessage(err: unknown): string {

src/debugAdapter/backends/RawTraceBackend.ts

@@ -14,6 +14,7 @@ import { parseTraceJsonl } from '../../komet/trace';
 import { TraceModel } from '../TraceModel';
 import { Disassembly } from '../../wasm/Disassembly';
 import { NullSourceMapper } from '../../sourcemap/NullSourceMapper';
+import { NullVariableResolver } from '../../sourcemap/VariableResolver';
 import { buildDebugArtifacts } from '../artifacts';
 import { ProgressReporter, ResolvedTrace, SessionBackend, SorobanLaunchArgs } from '../types';
 
@@ -30,15 +31,16 @@ export class RawTraceBackend implements SessionBackend {
     if (args.wasmPath) {
       report(`Reading contract wasm from ${args.wasmPath}`);
       const wasm = await fs.readFile(args.wasmPath);
-      const { source, disassembly, positions } = buildDebugArtifacts(wasm, model, report);
-      return { model, source, disassembly, positions };
+      const { source, variables, disassembly, positions } = buildDebugArtifacts(wasm, model, report);
+      return { model, source, variables, disassembly, positions };
     }
     // Without wasm there is nothing to validate positions against; the raw
     // `pos` values are used as-is, which is self-consistent because the
     // trace-derived disassembly is built from those same values.
     return {
       model,
       source: new NullSourceMapper(),
+      variables: new NullVariableResolver(),
       disassembly: Disassembly.fromTrace(model),
       positions: records.map((rec) => rec.pos),
     };

src/debugAdapter/runtimeState.ts

@@ -0,0 +1,57 @@
+/**
+ * Bridges a single `TraceRecord` (plus the snapshot-backed `MemoryImage`) at a
+ * replay cursor to the `RuntimeState` the DWARF location evaluator consumes. The
+ * trace stores locals/globals/stack as `[wasmType, value]` pairs; the evaluator
+ * wants bare numeric slot values, so `typedValueToNumber` normalizes them.
+ *
+ * Pure module (no `vscode` / DAP imports).
+ */
+
+import { TraceRecord, TypedValue } from '../komet/trace';
+import { RuntimeState } from '../dwarf/locexpr';
+import { MemoryImage } from './MemoryImage';
+
+/**
+ * Coerce a trace `[wasmType, value]` to a numeric slot value. i32/f32/f64
+ * arrive as JS numbers; i64 (and other large values) may arrive as decimal
+ * strings, which become `bigint`; booleans map to 0/1. Anything else — a
+ * missing value or an unexpected shape — is `undefined`.
+ */
+export function typedValueToNumber(tv: TypedValue | undefined): number | bigint | undefined {
+  if (tv === undefined) {
+    return undefined;
+  }
+  const value = tv[1];
+  switch (typeof value) {
+    case 'number':
+      return value;
+    case 'string':
+      try {
+        return BigInt(value);
+      } catch {
+        return undefined;
+      }
+    case 'boolean':
+      return value ? 1 : 0;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Build a `RuntimeState` view over `record` at `cursor`. Register slots read
+ * from the record's typed-value maps/array; memory reads delegate to `memory`
+ * at `cursor` (the latest snapshot at or before it).
+ */
+export function makeRuntimeState(
+  record: TraceRecord,
+  memory: MemoryImage,
+  cursor: number,
+): RuntimeState {
+  return {
+    localValue: (index: number) => typedValueToNumber(record.locals[String(index)]),
+    globalValue: (index: number) => typedValueToNumber(record.globals?.[String(index)]),
+    stackValue: (index: number) => typedValueToNumber(record.stack[index]),
+    readMemory: (address: number, size: number) => memory.readMemory(cursor, address, size),
+  };
+}