ERR/E3.3: trace formatting (library/modules/trace.sx) + catch-clear timing fix

The trace formatter, unblocked now that 0057 is fixed.

- library/modules/trace.sx: to_string() walks the trace buffer (sx_trace_len /
  frame_at / truncated) and renders "error return trace ..." with one line per
  frame; print_current() writes it to stderr (libc write(2, ...)). Frame
  locations are "<location pending DWARF>" until E3.0 resolves PCs; count +
  ordering + the overflow note are already meaningful.

- Catch-clear timing fix (lowerCatch): move the absorption clear from
  runCatchBody ENTRY to the handler's non-diverging EXIT (both the pure and
  value-carrying paths). This reconciles the two PLAN-ERR statements that
  conflicted — §clear-points "buffer cleared before the catch body" vs
  §catch-over-or "frames still in the buffer when the body runs". Exit-clear
  satisfies both: the handler can inspect the trace (trace.print_current()
  shows the chain), and the buffer is empty once the handler completes. A
  diverging body (raise/return) keeps/discards on its own path.

- examples/243-trace-format.sx: catch handler prints the tag + the 2-frame
  trace, then shows the buffer is empty after. examples/241 updated: the
  handler now observes len=2 (was 0 under the buggy entry-clear).

Gates: zig build, zig build test, bash tests/run_examples.sh (280 passed; lone
failure is the user's uncommitted 213-canonical-map pack WIP).

examples/241-error-trace-buffer.sx

@@ -24,12 +24,14 @@ propagate :: (n: s32) -> !E {
 }
 
 main :: () -> s32 {
-    // `catch` absorbs the failure → buffer cleared before the handler runs.
+    // `catch` lets the handler INSPECT the trace, then absorbs: the buffer is
+    // cleared when the handler completes (a non-diverging exit), not on entry.
+    // So inside the handler the frames are still visible (here: the `raise` in
+    // `fail` + the `try fail` propagation in `propagate` = 2 frames)...
     propagate(-1) catch e {
-        // The pushes from `raise` + `try` were cleared on catch entry.
+        print("in catch: len={}\n", sx_trace_len());   // 2 (handler sees the chain)
-        print("in catch: len={}\n", sx_trace_len());   // 0
     };
-    print("after catch: len={}\n", sx_trace_len());     // 0
+    print("after catch: len={}\n", sx_trace_len());     // 0 (absorbed at handler exit)
 
     // A success leaves the buffer empty (nothing pushed).
     propagate(1) catch e { };

examples/243-trace-format.sx

@@ -0,0 +1,36 @@
+// Error return-trace formatting (ERR step E3.3). `library/modules/trace.sx`
+// reads the trace buffer (E3.1, populated by E3.2's raise/try push wiring) and
+// renders it. `trace.print_current()` writes the trace to stderr; the catch
+// handler sees the full chain because the absorption clear fires at handler
+// EXIT, not entry. Frame locations are placeholders until DWARF (ERR E3.0)
+// resolves PCs to file:line; the count + ordering are already meaningful.
+//
+// Note: the trace goes to stderr. The test runner merges stderr+stdout, so the
+// snapshot shows the trace lines interleaved with the `print` (stdout) lines.
+
+#import "modules/std.sx";
+trace :: #import "modules/trace.sx";
+
+// Buffer length probe (the runtime symbol; public read API is the trace module).
+sx_trace_len :: () -> u32 #foreign;
+
+E :: error { BadInput, Overflow }
+
+leaf :: (n: s32) -> !E {
+    if n < 0 { raise error.BadInput; }   // pushes frame 0
+    return;
+}
+
+mid :: (n: s32) -> !E {
+    try leaf(n);                          // propagation pushes frame 1
+    return;
+}
+
+main :: () -> s32 {
+    mid(-1) catch e {
+        print("[stdout] caught {}\n", e);   // tag name via the always-linked table
+        trace.print_current();               // [stderr] the 2-frame trace
+    };
+    print("[stdout] recovered; trace buffer now empty (len {})\n", sx_trace_len());
+    return 0;
+}

library/modules/trace.sx

@@ -0,0 +1,62 @@
+#import "std.sx";
+
+// =====================================================================
+// trace.sx — error return-trace formatting (ERR step E3.3).
+//
+// Reads the thread-local return-trace buffer (ERR E3.1, populated by the
+// push/clear wiring in E3.2) and renders it. A `raise` / propagating `try`
+// pushes a frame; an absorbing site (`catch` / `or value` / destructure)
+// clears the buffer. So at format time the buffer holds exactly the frames
+// of failures that escaped to where you're formatting — typically inside a
+// `catch` handler (the clear fires when the handler completes, so the body
+// still sees the chain) or the (future) failable-`main` wrapper.
+//
+// Frame resolution: a frame is an opaque u64. Resolving it to `file:line:col`
+// needs DWARF line-info (ERR E3.0), which sx does not emit yet — so for now
+// each frame prints as "<location pending DWARF>". The frame COUNT, ordering,
+// and overflow note are already meaningful; once E3.0 lands, only the
+// per-frame location string changes. (The comptime path — resolving a packed
+// `(func_id, ir_offset)` via the interpreter's IR tables — also lands with the
+// resolver in E3.0/E3.3-full.)
+// =====================================================================
+
+libc :: #library "c";
+
+// The error-trace buffer C API (library/vendors/sx_trace_runtime/sx_trace.c),
+// linked in for the JIT and auto-injected for AOT when traces are used.
+sx_trace_len       :: () -> u32 #foreign;
+sx_trace_truncated :: () -> u32 #foreign;
+sx_trace_frame_at  :: (i: u32) -> u64 #foreign;
+
+write :: (fd: s32, buf: [*]u8, count: usize) -> isize #foreign libc;
+
+// Render the current trace buffer to a string (allocated from
+// context.allocator). Empty buffer → "" so callers can cheaply skip output.
+to_string :: () -> string {
+    n := sx_trace_len();
+    if n == 0 { return ""; }
+
+    result := "error return trace (most recent call last):\n";
+    if sx_trace_truncated() != 0 {
+        result = concat(result, "  ... older frames omitted (buffer full)\n");
+    }
+
+    i : u32 = 0;
+    while i < n {
+        frame := sx_trace_frame_at(i);
+        // DWARF (E3.0) will resolve `frame` to file:line:col + function name.
+        // Until then the raw frame value is shown (a placeholder, not a PC yet).
+        line := format("  frame {}: <location pending DWARF> (raw {})\n", i, xx frame);
+        result = concat(result, line);
+        i = i + 1;
+    }
+    result;
+}
+
+// Write the current trace to stderr (fd 2). No-op when the buffer is empty.
+print_current :: () {
+    s := to_string();
+    if s.len > 0 {
+        write(2, s.ptr, xx s.len);
+    }
+}

src/ir/lower.zig

@@ -15678,7 +15678,16 @@ pub const Lowering = struct {
             self.builder.condBr(is_err, handle_bb, &.{}, merge_bb, &.{});
             self.builder.switchToBlock(handle_bb);
             _ = self.runCatchBody(ce, err_val, err_set, null);
-            if (!self.currentBlockHasTerminator()) self.builder.br(merge_bb, &.{});
+            // The handler can inspect the trace (`trace.print_current()`); the
+            // absorption clear fires once it completes WITHOUT re-raising (a
+            // fall-through). A diverging body (`raise` / `return`) keeps /
+            // discards the buffer on its own path (ERR E3.2; reconciles
+            // PLAN-ERR §clear-points "cleared before body" with §catch-over-or
+            // "frames still in the buffer when the body runs").
+            if (!self.currentBlockHasTerminator()) {
+                self.emitTraceClear();
+                self.builder.br(merge_bb, &.{});
+            }
             self.builder.switchToBlock(merge_bb);
             return self.builder.constInt(0, .void);
         }
@@ -15715,6 +15724,9 @@ pub const Lowering = struct {
                 }
                 break :blk self.builder.constUndef(succ_ty);
             };
+            // Absorption clear on a non-diverging handler (see the pure-failable
+            // path above): the body saw the trace, now it's consumed.
+            self.emitTraceClear();
             self.builder.br(merge_bb, &.{bv});
         }
 
@@ -15727,10 +15739,6 @@ pub const Lowering = struct {
     /// catch), returns the body's value (or null if the body diverged); when
     /// null (pure-failable catch), runs the body for effect and returns null.
     fn runCatchBody(self: *Lowering, ce: *const ast.CatchExpr, err_val: Ref, err_set: TypeId, want_ty: ?TypeId) ?Ref {
-        // `catch` absorbs the LHS's failure: clear the trace buffer before the
-        // handler runs (ERR E3.2), so a failure consumed here leaves no residue.
-        // Runs on the error/handle path only (this fn is called from handle_bb).
-        self.emitTraceClear();
         var handle_scope = Scope.init(self.alloc, self.scope);
         const saved_scope = self.scope;
         self.scope = &handle_scope;

tests/expected/241-error-trace-buffer.txt

@@ -1,3 +1,3 @@
-in catch: len=0
+in catch: len=2
 after catch: len=0
 after success: len=0

tests/expected/243-trace-format.exit

@@ -0,0 +1 @@
+0

tests/expected/243-trace-format.txt

@@ -0,0 +1,5 @@
+[stdout] caught BadInput
+error return trace (most recent call last):
+  frame 0: <location pending DWARF> (raw 1)
+  frame 1: <location pending DWARF> (raw 1)
+[stdout] recovered; trace buffer now empty (len 0)