feat(meta): D-563(b) — Var :line/:column/:file source meta; def meta rides the AOT wire (envelope v9)

Smell-audited: 2: the meta-as-code design pivoted twice in-cycle (analyze
raw → NameError on defn's raw :arglists lists; measured that quoted
composites DO round-trip the wire) and settled on wholesale-quote = ONE
composite constant preserving cljw's static-data meta semantics — the
measurement-first pivot is recorded here + in the debt row. defmacro's
def_node meta_expr is a named residual (D-563 row).

- analyzeDef mints {:line :column :file} under user ^meta/:doc (compiler
  wins on collision — clj-oracle: ^{:line 999} yields the real line).
- DefNode.meta_expr evaluated at def time by BOTH backends: tree_walk
  evalDef + new op_var_meta (0x56; pops meta, sets Var.meta, var stays).
  Dual-backend contract: TreeWalk arm + compile arm + dispatch arm +
  diff case in this commit.
- fix(aot): def meta now survives `cljw build` artifacts — docstrings
  were silently LOST in built apps ((:doc (meta #'f)) → nil) while the
  lazy-source bootstrap kept them; envelope v8 → v9 (new opcode).
- clojure.test FAIL/ERROR lines regain the ` (file:line)` suffix from
  the deftest var's meta; AD-041 NARROWED (cljw points at the deftest
  line, clj at the assertion's stack line — no JVM stack to read).
e2e phase15_var_source_meta (8 cases incl. AOT round-trip + fixture
file line/path) + phase15_clojure_test_output pins updated.

Author: chaploud

.dev/accepted_divergences.yaml

@@ -599,20 +599,21 @@ accepted:
     derives_from: "F-011 (behavioural equivalence is the contract; the macros run identically — only the intermediate macroexpand-1 FORM differs; cljw's Zig transforms lower eagerly in one step). Functionally-equivalent expansion form, like ClojureScript's macroexpansions vs JVM clj."
     pin: "test/e2e/phase14_when_if_not.sh — `cond_expand_full` locks (macroexpand-1 '(cond a 1 :else 2)) => (if a 1 (if :else 2 nil)) (cljw's full form), and `when_expand_multi`/`when_expand_single` lock when's byte-match with clj"
   - id: "AD-041"
-    summary: "clojure.test's FAIL/ERROR report line omits clj's ` (file:line)` source-location suffix, and `report :error` prints the exception's value instead of clj's JVM cause trace. The test name, expected/actual, context line, and counts all match clj."
-    example: "(deftest a (is (= 1 2))) (run-tests) => cljw `FAIL in (a)` / clj `FAIL in (a) (NO_SOURCE_FILE:1)`. An erroring test: cljw `  actual: #error {…}` (the ex value) / clj a multi-line `clojure.lang.ExceptionInfo … at …` cause trace."
-    why: |-
-      cljw Vars carry no source location — `(meta #'a)` has `:name`/`:ns` but no
-      `:line`/`:file` (clj attaches both at compile time). So `testing-vars-str`
-      cannot emit the ` (file:line)` suffix clj appends, and there is no JVM
-      stack to print for an errored assertion. Everything that does NOT depend on
-      a source location — the `(test-name)` list, `expected:`/`  actual:` (incl.
-      the clj `(not (= …))` actual form), the joined `testing` context line, the
-      `Testing <ns>` begin line, and the `Ran … / failures, errors.` summary —
-      matches clj byte-for-line. Reproducing the suffix/trace would require a
-      source-location + JVM-stack model cljw does not have (ADR-0059 no-JVM).
+    summary: "clojure.test's FAIL/ERROR ` (file:line)` suffix points at the DEFTEST var's line (from Var source meta, D-563b) where clj points at the failing assertion's line (JVM stack frame); and `report :error` prints the exception's value instead of clj's JVM cause trace. Names, expected/actual, context, and counts all match clj."
+    example: "(deftest a (is (= 1 2))) in f.clj: cljw `FAIL in (a) (f.clj:LINE-OF-DEFTEST)` / clj `FAIL in (a) (f.clj:LINE-OF-IS)`. An erroring test: cljw `  actual: #error {…}` (the ex value) / clj a multi-line `clojure.lang.ExceptionInfo … at …` cause trace."
+    why: |-
+      Since D-563(b) cljw Vars DO carry `:line`/`:column`/`:file` source meta
+      (compiler-minted, AOT-wire-carried), so `testing-vars-str` emits the
+      ` (file:line)` suffix — but from the deftest VAR's meta. clj derives it
+      from the failing ASSERTION's stack frame, and cljw has no JVM stack to
+      read (ADR-0059), so cljw points at the deftest line where clj points at
+      the `is` line. The `report :error` cause-trace half is unchanged (no JVM
+      stack to print). Everything else — the `(test-name)` list,
+      `expected:`/`  actual:` (incl. the clj `(not (= …))` form), the joined
+      `testing` context line, `Testing <ns>`, and the summary — matches clj
+      byte-for-line.
     derives_from: "ADR-0059 (no-JVM: no JVM stack / class-file source positions) + F-011 (behavioural equivalence — pass/fail/error outcomes + counts match; only the unreproducible location/trace text differs)."
-    pin: "test/e2e/phase15_clojure_test_output.sh — asserts the clj-matching lines (`FAIL in (eqfail)`, `  actual: (not (= 1 2))`, context, `Testing demo`, summary) are present and that `*test-out*` is re-enabled; the absent ` (file:line)` suffix is the locked divergence."
+    pin: "test/e2e/phase15_clojure_test_output.sh (suffix present, deftest-var-sourced) + test/e2e/phase15_var_source_meta.sh (the Var meta channel + AOT round-trip)."
   - id: "AD-042"
     summary: "`(pr-str v)` / `(str v)` print the bare ISO toString for a `java.time.*` value (Instant, Duration, …), where clj's `pr` emits the opaque `#object[java.time.X 0x.. \"ISO\"]` identity form. cljw makes both str and pr the toString; the value's `(str …)`, method results, and `=` all match clj."
     example: "(pr-str (java.time.Instant/ofEpochSecond 0)) => cljw \"1970-01-01T00:00:00Z\" / clj \"#object[java.time.Instant 0x5d3411d \\\"1970-01-01T00:00:00Z\\\"]\". (str (java.time.Duration/ofSeconds 90)) => both \"PT1M30S\"."

.dev/debt.yaml

@@ -69,10 +69,19 @@ active:
       the value; call heads fall through to analyzeCall. e2e: 6 cases on
       phase14_host_class_identity (map String/.length, Thread/new,
       StringBuilder chain, Date/new higher-order), clj-1.12-oracle-matched.
-      (b) **Var source meta** — clj vars carry :line/:file/:column from
-      the compiler; cljw def sites know their SourceLocation but drop it.
-      Adding it converges `(meta #'x)` and clojure.test's
-      ` (file:line)` FAIL-line suffix (AD-041's divergence dissolves).
+      (b) DISCHARGED 2026-07-17 — Vars carry :line/:column/:file (analyzeDef
+      mints them under user ^meta/:doc, compiler-wins on collision per clj
+      oracle) AND def meta now RIDES THE AOT WIRE: DefNode.meta_expr (the
+      merged map, wholesale-quoted = cljw's static-data meta semantics) is
+      evaluated at def time by both backends — tree_walk evalDef + the new
+      op_var_meta opcode (envelope v9). This also FIXED the pre-existing
+      user-AOT docstring loss ((:doc (meta #'f)) was nil in `cljw build`
+      artifacts while lazy-source bootstrap kept it). clojure.test's
+      ` (file:line)` suffix restored from the deftest var's meta — AD-041
+      NARROWED (deftest-line vs clj's assertion-stack-line residual).
+      e2e phase15_var_source_meta (8) + diff case + the narrowed pin.
+      Residual: defmacro's def_node has no meta_expr yet (macro vars keep
+      analyze-time meta only; small follow-up on the same channel).
       (c) **var-existence gaps mainline completion surfaced**:
       `default-data-readers` (needs reader fns exposed as vars) and
       `defstruct`/`create-struct`/`struct-map`/`accessor` (legacy

src/eval/analyzer/special_forms.zig

@@ -607,6 +607,47 @@ pub fn analyzeDef(
         const meta_map: Form = .{ .data = .{ .map = try arena.dupe(Form, meta_items.items) }, .location = form.location };
         var_ptr.meta = try analyzer_mod.formToValue(rt, env, try unquoteMetaValues(arena, meta_map));
     }
+    // D-563(b): the full Var-meta EXPRESSION — user `^meta` + `:doc`, with the
+    // compiler-minted `:line`/`:column`/`:file` appended AFTER them (a map
+    // literal is last-key-wins, so the source location overrides a user
+    // `^{:line …}` — clj parity). Both backends evaluate it at def time and
+    // set `Var.meta`, so def meta rides the AOT wire (the analyze-time lift
+    // above only covers the pre-eval window). Skipped for locationless
+    // internal defs (line 0 = no real source position).
+    const def_meta_expr: ?*const Node = blk: {
+        const src_loc = items[1].location;
+        if (src_loc.line == 0) break :blk null;
+        var meta_items: std.ArrayList(Form) = .empty;
+        if (items[1].meta) |mf| {
+            if (mf.data == .map) try meta_items.appendSlice(arena, mf.data.map);
+        }
+        if (doc_form) |d| {
+            try meta_items.append(arena, .{ .data = .{ .keyword = .{ .name = "doc" } }, .location = form.location });
+            try meta_items.append(arena, d);
+        }
+        const kws = [_]struct { name: []const u8, v: i64 }{
+            .{ .name = "line", .v = @intCast(src_loc.line) },
+            .{ .name = "column", .v = @intCast(src_loc.column) },
+        };
+        for (kws) |kv| {
+            try meta_items.append(arena, .{ .data = .{ .keyword = .{ .name = kv.name } }, .location = form.location });
+            try meta_items.append(arena, .{ .data = .{ .integer = kv.v }, .location = form.location });
+        }
+        try meta_items.append(arena, .{ .data = .{ .keyword = .{ .name = "file" } }, .location = form.location });
+        try meta_items.append(arena, .{ .data = .{ .string = src_loc.file }, .location = form.location });
+        const meta_map: Form = .{ .data = .{ .map = try arena.dupe(Form, meta_items.items) }, .location = form.location };
+        // The whole map is wrapped in (quote …): def-meta is STATIC DATA in
+        // cljw (same semantics as the formToValue lift above — defn's raw
+        // `:arglists ([s] …)` lists must never evaluate; clj's
+        // evaluate-meta-exprs nuance is out of scope, AD candidate if ever
+        // hit). The quoted map analyzes to ONE composite constant, which the
+        // AOT wire carries (quoted literals round-trip `cljw build` today).
+        const quote_items = try arena.alloc(Form, 2);
+        quote_items[0] = macro_dispatch.makeSymbol("quote", form.location);
+        quote_items[1] = try unquoteMetaValues(arena, meta_map);
+        const quoted: Form = .{ .data = .{ .list = quote_items }, .location = form.location };
+        break :blk try analyzer_mod.analyze(arena, rt, env, scope, quoted, macro_table);
+    };
     // `^:dynamic` / `^:private` on the def target set the Var flags (evalDef /
     // op_def copy DefNode flags onto the Var). Without this the metadata was
     // lifted into Var.meta but the flags stayed false, so `(def ^:dynamic *x*)`
@@ -634,6 +675,7 @@ pub fn analyzeDef(
         .is_dynamic = is_dynamic,
         .is_private = is_private,
         .has_init = init_idx != null,
+        .meta_expr = def_meta_expr,
         .loc = form.location,
     } };
     return n;

src/eval/backend/tree_walk.zig

@@ -875,6 +875,12 @@ fn evalDef(rt: *Runtime, env: *Env, locals: []Value, n: node_mod.DefNode) !Value
     var_ptr.flags.dynamic = n.is_dynamic;
     var_ptr.flags.macro_ = n.is_macro;
     var_ptr.flags.private = n.is_private;
+    // D-563(b): the merged def-meta (user ^meta/:doc under the compiler's
+    // :line/:column/:file) is set at DEF time so it also rides the AOT wire
+    // (the VM twin is op_var_meta).
+    if (n.meta_expr) |me| {
+        var_ptr.meta = try eval(rt, env, locals, me);
+    }
     return Value.encodeHeapPtr(.var_ref, var_ptr);
 }
 

src/eval/backend/vm.zig

@@ -550,6 +550,19 @@ inline fn stepOnce(
             stack[sp] = Value.encodeHeapPtr(.var_ref, var_ptr);
             sp += 1;
         },
+        .op_var_meta => {
+            // D-563(b): stack is [.., var, meta] — pop the meta map, set it as
+            // the Var's meta (the merged user ^meta/:doc + :line/:column/:file
+            // the analyzer minted); the var stays as def's result value.
+            if (sp < 2) return raiseInternal("vm: op_var_meta needs var + meta on the stack");
+            sp -= 1;
+            const meta_val = stack[sp];
+            const var_val = stack[sp - 1];
+            if (var_val.tag() != .var_ref)
+                return raiseInternal("vm: op_var_meta target is not a Var");
+            const var_ptr = var_val.decodePtr(*env_mod.Var);
+            var_ptr.meta = meta_val;
+        },
         .op_def_unbound => {
             // No-init `(def x)`: intern an UNBOUND placeholder (no stack value,
             // does not clobber an existing root, Var.bound stays false).

src/eval/backend/vm/compiler.zig

@@ -886,6 +886,14 @@ const Compiler = struct {
         if (n.is_macro) packed_operand |= opcode_mod.DEF_FLAG_MACRO;
         if (n.is_private) packed_operand |= opcode_mod.DEF_FLAG_PRIVATE;
         try self.emit(if (n.has_init) .op_def else .op_def_unbound, packed_operand);
+        // D-563(b): def meta — the map is BUILT by ordinary ops (the wire
+        // constant pool has no map kind) on top of the Var op_def left on
+        // the stack; op_var_meta pops it and sets Var.meta. Meta thereby
+        // rides any AOT artifact.
+        if (n.meta_expr) |me| {
+            try self.compileNode(me);
+            try self.emit(.op_var_meta, 0);
+        }
     }
 
     /// Emit a jump opcode with a placeholder operand and return the

src/eval/backend/vm/opcode.zig

@@ -353,6 +353,15 @@ pub const Opcode = enum(u8) {
     /// vector index; every error case (OOB / negative / non-vector / nil, which
     /// 2-arg `nth` RAISES) defers to the cached `nth` Var for the correct error.
     op_nth2 = 0x55,
+    /// Pops a meta map; sets it as `Var.meta` of the `.var_ref` left at the
+    /// stack top (the var STAYS — def's result value). Emitted right after
+    /// `op_def` / `op_def_unbound` when the def carries meta — since D-563(b)
+    /// the analyzer mints source meta (:line/:column/:file) for every def, so
+    /// effectively always. The meta map is BUILT by ordinary ops on the stack
+    /// (the wire constant pool has no map kind), so def meta rides any AOT
+    /// artifact — fixing the pre-existing loss where a `cljw build` app's
+    /// docstrings vanished while the lazy-source bootstrap kept them.
+    op_var_meta = 0x56,
 
     /// True when this opcode carries a **signed-i16 instruction-position
     /// offset** in `operand`, relative to the instruction after itself
@@ -368,6 +377,7 @@ pub const Opcode = enum(u8) {
             .op_const,
             .op_load_local,
             .op_store_local,
+            .op_var_meta,
             .op_def,
             .op_def_unbound,
             .op_get_var,
@@ -462,6 +472,7 @@ pub const Opcode = enum(u8) {
         return switch (self) {
             .op_const, .op_load_local => true,
             .op_store_local,
+            .op_var_meta,
             .op_def,
             .op_def_unbound,
             .op_get_var,

src/eval/bytecode/serialize.zig

@@ -76,7 +76,7 @@ const tree_walk = @import("../backend/tree_walk.zig");
 const Function = tree_walk.Function;
 
 pub const MAGIC: [4]u8 = .{ 'C', 'L', 'J', 'W' };
-pub const VERSION: u16 = 8; // v8 (ADR-0174): host-class fqcn identity unification — baked class-value constants carry JVM FQCNs ("java.util.Date", was "Date"/"cljw.java.*"), so ≤v7 artifacts are version-rejected; v7 (ADR-0173 C2'): 4B WireInstr wire + 4B-aligned instr sections + source_file/has_handlers in the chunk + interned-name constant pool (pool_ref) + headerless nested fn-method chunks; v6: rt ns merged into clojure.core (ADR-0171)
+pub const VERSION: u16 = 9; // v9 (D-563b): op_var_meta — def meta (:doc + :line/:column/:file) rides the wire, fixing the user-AOT docstring loss; v8 (ADR-0174): host-class fqcn identity unification — baked class-value constants carry JVM FQCNs ("java.util.Date", was "Date"/"cljw.java.*"), so ≤v7 artifacts are version-rejected; v7 (ADR-0173 C2'): 4B WireInstr wire + 4B-aligned instr sections + source_file/has_handlers in the chunk + interned-name constant pool (pool_ref) + headerless nested fn-method chunks; v6: rt ns merged into clojure.core (ADR-0171)
 
 pub const SerializeError = error{
     OutOfMemory,

src/eval/node.zig

@@ -160,6 +160,12 @@ pub const DefNode = struct {
     /// interns an UNBOUND placeholder (`internDeclare`) — it must not clobber
     /// an existing root (clj parity) and leaves `Var.bound` false for `bound?`.
     has_init: bool = true,
+    /// The Var-meta map EXPRESSION (D-563b): user `^meta` + `:doc` merged
+    /// under the analyzer-minted `:line`/`:column`/`:file` (compiler wins on
+    /// collision, clj parity). Evaluated at def time and set as `Var.meta`
+    /// by both backends (tree_walk evalDef / VM op_var_meta), so def meta
+    /// survives the AOT wire. Null only for internal defs with no location.
+    meta_expr: ?*const Node = null,
     loc: SourceLocation = .{},
 };
 

src/lang/clj/clojure/test.clj

@@ -15,10 +15,12 @@
 ;; multimethod (`=` / `thrown?` / default), a `report` multimethod keyed on
 ;; `:type`, and `*report-counters*` as a dynamic var holding an atom.
 ;;
-;; cljw adaptations (no JVM): vars carry no source location, so the FAIL/ERROR
-;; line omits clj's ` (file:line)` suffix and `report :error` cannot print a JVM
-;; cause trace — both are AD-041. Deferred: per-var lifecycle events
-;; (begin/end-test-var, end-test-ns), use-fixtures, with-test.
+;; cljw adaptations (no JVM): the FAIL/ERROR ` (file:line)` suffix reads the
+;; deftest VAR's :file/:line meta (D-563b) where clj reads the failing
+;; assertion's stack frame (deftest-line vs is-line — the narrowed AD-041);
+;; `report :error` cannot print a JVM cause trace (also AD-041). Deferred:
+;; per-var lifecycle events (begin/end-test-var, end-test-ns), use-fixtures,
+;; with-test.
 
 (ns clojure.test
   (:refer-clojure)
@@ -65,10 +67,19 @@
   `(binding [*out* *test-out*] ~@body))
 
 ;; A string naming the test(s) currently running, for a reporter's pass/fail
-;; line: the simple test name(s) in a list, e.g. "(my-test)" (clj form, minus
-;; the ` (file:line)` suffix — cljw has no source location on Vars, AD-041).
+;; line: "(my-test) (file.clj:12)". The suffix reads the deftest VAR's
+;; :file/:line source meta (D-563b); clj derives it from the failing
+;; ASSERTION's stack frame instead, so clj points at the `is` line where
+;; cljw points at the deftest line — the narrowed AD-041 residual (no JVM
+;; stack frames to read).
 (defn testing-vars-str [_m]
-  (str "(" (clojure.string/join " " (reverse (map #(:name (meta %)) *testing-vars*))) ")"))
+  (let [names (str "(" (clojure.string/join " " (reverse (map #(:name (meta %)) *testing-vars*))) ")")
+        vm (meta (first *testing-vars*))
+        file (:file vm)
+        line (:line vm)]
+    (if (and file line)
+      (str names " (" (last (clojure.string/split (str file) #"/")) ":" line ")")
+      names)))
 
 ;; A string of the active `testing` context strings (outermost first).
 (defn testing-contexts-str []