feat(interop): D-376 — Murmur3/hashUnencodedChars, real UTF-16 JVM bit-parity

Smell-audited: 1: the row's either/or (UTF-8 shortcut accepting AD-009
divergence vs a real UTF-16 path) resolved to the REAL path — ~30 lines,
removes the divergence entirely; unlike the AD-009 collection hashes the
input is pure code units, so JVM bit-parity is achievable and locked.

hash.zig hashUnencodedChars: streaming UTF-8 -> UTF-16 code units
(surrogate pairs for astral codepoints), 2 units per 32-bit block, fmix
over 2*unit-count — the exact JVM Murmur3.hashUnencodedChars. Registered
on the existing cljw.clojure.lang.Murmur3 surface (string arg; a
CharSequence deftype raises until a consumer needs it). Unit test pins 6
clj-oracle values incl. surrogate pairs; corpus clojure_lang_util +5
clj-byte-matched goldens. data.xml's full-lib run stays with D-528.

Author: chaploud

.dev/debt.yaml

@@ -649,15 +649,6 @@ active:
       allow/deny set consulted at the single var-resolution site. Lower priority
       than D-351/D-352.
     last_reviewed: "2026-06-09"
-  - id: "D-376"
-    status: "open (2026-06-10, ADR-0108 am1 out-of-scope). `clojure.lang.Murmur3/hashUnencodedChars` (2 sites, data.xml only) hashes a CharSequence's UTF-16 code units. cljw's hashString deliberately hashes UTF-8 bytes (hash.zig — a WASM/edge-native choice, F-011 internals are impl-specific), so there is no UTF-16-codeunit hasher to delegate to. Deferred from the D-375 closed set. Revisit if data.xml is promoted to a verified lib: add a hashUnencodedChars hashing UTF-8 (accept the AD-009 value divergence) or build a real UTF-16 path then."
-    category: "interop"
-    barrier: |-
-      `Murmur3/hashUnencodedChars` hashes UTF-16 code units; cljw hashes UTF-8
-      (no UTF-16 hasher exists). Low value (data.xml only, 2 sites). Revisit when a
-      verified lib needs it; then hash UTF-8 (AD-009) or add a UTF-16 path. Cross-ref
-      ADR-0108 am1, AD-009.
-    last_reviewed: "2026-06-10"
   - id: "D-033"
     status: "DUE — trigger fired (corrected 2026-06-17 audit). primitive/ files long past the ~500 trigger: core.zig 1837 / math.zig 1444 / collection.zig 1190; core + math also breach the ROADMAP A6 ≤1000-line cap. Split never done. Next: confirm A6 still applies, then split (primitive/core|sequence|…) or amend the cap with an ADR."
     category: "structure"
@@ -6537,6 +6528,12 @@ discharged:
     barrier: "DISCHARGED (was: print-control dynamic vars)."
     last_reviewed: "2026-07-06"
 
+  - id: "D-376"
+    status: "DISCHARGED 2026-07-06 (easiest-first drain). `clojure.lang.Murmur3/hashUnencodedChars` landed as a REAL UTF-16 code-unit Murmur3 (hash.zig hashUnencodedChars: UTF-8 -> UTF-16 units streaming, surrogate pairs for astral codepoints, 2 units/block, fmix over 2*unit-count — the exact JVM algorithm), registered on the existing cljw.clojure.lang.Murmur3 surface. UNLIKE the AD-009 collection hashes this is JVM BIT-PARITY (input is pure code units, no cljw-native value hash) — unit test pins 6 clj-oracle values incl. a surrogate-pair case (𠮷野家 -> -383720716); corpus clojure_lang_util +5 clj-byte-matched goldens. The 2026-06-10 either/or (hash UTF-8 accepting AD-009 divergence, OR build a real UTF-16 path) resolved to the REAL path — it costs ~30 lines and removes the divergence entirely. String-arg only (a CharSequence deftype arg raises type_arg_invalid; extend on a real consumer). data.xml (the 2 call sites) has no local clone — take its full-lib run up under D-528 when cloned."
+    category: "interop"
+    barrier: "DISCHARGED (was: no UTF-16 hasher)."
+    last_reviewed: "2026-07-06"
+
 conventions: |-
   - Structure: two top-level lists — `active:` and `discharged:`. Active entries carry id / status / category / barrier (+ optional quality_floor / last_reviewed); discharged entries carry id / discharged_at / resolution. Edit as YAML (no Markdown table to align).
   - New debt: grep `.dev/debt.yaml` for class-overlap before adding (per `.claude/rules/debt_dedup.md`).

src/runtime/clojure/lang/Murmur3.zig

@@ -22,6 +22,7 @@ const Env = @import("../../env.zig").Env;
 const SourceLocation = @import("../../error/info.zig").SourceLocation;
 const error_catalog = @import("../../error/catalog.zig");
 const hash = @import("../../hash.zig");
+const string_mod = @import("../../collection/string.zig");
 
 /// Resolve `clojure.core/<name>` and call it through the backend vtable.
 fn callCore(rt: *Runtime, env: *Env, name: []const u8, args: []const Value, loc: SourceLocation) !Value {
@@ -57,12 +58,27 @@ fn mixCollHash(rt: *Runtime, env: *Env, args: []const Value, loc: SourceLocation
     return Value.initInteger(@as(i32, @bitCast(mixed)));
 }
 
+/// `(clojure.lang.Murmur3/hashUnencodedChars s)` — Murmur3 over the string's
+/// UTF-16 code units. Unlike the AD-009 collection hashes this is JVM
+/// BIT-PARITY (the input is pure code units — no cljw-native value hash is
+/// involved), so clj and cljw agree on the value (D-376; data.xml's 2 sites).
+fn hashUnencodedChars(rt: *Runtime, env: *Env, args: []const Value, loc: SourceLocation) anyerror!Value {
+    _ = rt;
+    _ = env;
+    try error_catalog.checkArity("clojure.lang.Murmur3/hashUnencodedChars", args, 1, loc);
+    if (args[0].tag() != .string)
+        return error_catalog.raise(.type_arg_invalid, loc, .{ .fn_name = "clojure.lang.Murmur3/hashUnencodedChars", .expected = "string", .actual = @tagName(args[0].tag()) });
+    const h = hash.hashUnencodedChars(string_mod.asString(args[0]));
+    return Value.initInteger(@as(i32, @bitCast(h)));
+}
+
 fn initMurmur3(td: *type_descriptor.TypeDescriptor, gpa: std.mem.Allocator) anyerror!void {
     if (td.method_table.len != 0) return; // idempotent re-run
     const specs = .{
         .{ "hashOrdered", &hashOrdered },
         .{ "hashUnordered", &hashUnordered },
         .{ "mixCollHash", &mixCollHash },
+        .{ "hashUnencodedChars", &hashUnencodedChars },
     };
     const entries = try gpa.alloc(type_descriptor.TypeDescriptor.MethodEntry, specs.len);
     inline for (specs, 0..) |spec, i| {

src/runtime/hash.zig

@@ -90,6 +90,40 @@ pub fn hashString(input: []const u8) u32 {
     return fmix(h1, @truncate(input.len));
 }
 
+/// JVM `clojure.lang.Murmur3.hashUnencodedChars` bit-parity: Murmur3 over
+/// the string's UTF-16 CODE UNITS (surrogate pairs for astral codepoints),
+/// two units per 32-bit block, `fmix` over `2 * unit-count` bytes. Distinct
+/// from `hashString` (cljw-native UTF-8 bytes, AD-009) — this serves the
+/// `Murmur3/hashUnencodedChars` static (data.xml), where JVM value-parity is
+/// achievable because the input is pure code units, not value identity (D-376).
+pub fn hashUnencodedChars(utf8: []const u8) u32 {
+    var h1: u32 = SEED;
+    var unit_count: u32 = 0;
+    var pending: ?u32 = null;
+    var it = std.unicode.Utf8View.initUnchecked(utf8).iterator();
+    while (it.nextCodepoint()) |cp| {
+        var units: [2]u32 = .{ @as(u32, cp), 0 };
+        var n: usize = 1;
+        if (cp >= 0x10000) {
+            const v: u32 = @as(u32, cp) - 0x10000;
+            units[0] = 0xD800 + (v >> 10);
+            units[1] = 0xDC00 + (v & 0x3FF);
+            n = 2;
+        }
+        for (units[0..n]) |u| {
+            unit_count += 1;
+            if (pending) |lo| {
+                h1 = mixH1(h1, mixK1(lo | (u << 16)));
+                pending = null;
+            } else {
+                pending = u;
+            }
+        }
+    }
+    if (pending) |lo| h1 ^= mixK1(lo);
+    return fmix(h1, 2 *% unit_count);
+}
+
 /// Mix a precomputed collection hash with its element count.
 pub fn mixCollHash(hash_val: u32, count: u32) u32 {
     var h1 = SEED;
@@ -177,3 +211,15 @@ test "hashUnordered is order-independent" {
     const b = [_]u32{ hashInt(3), hashInt(1), hashInt(2) };
     try testing.expectEqual(hashUnordered(&a), hashUnordered(&b));
 }
+
+test "hashUnencodedChars matches JVM Murmur3 (clj oracle 2026-07-06)" {
+    // clj: (clojure.lang.Murmur3/hashUnencodedChars s) — UTF-16 code-unit
+    // hash, JVM bit-parity (D-376). Values incl. a surrogate-pair case (𠮷 =
+    // U+20BB7 → 2 UTF-16 units).
+    try testing.expectEqual(@as(i32, 1118836419), @as(i32, @bitCast(hashUnencodedChars("abc"))));
+    try testing.expectEqual(@as(i32, 1867108634), @as(i32, @bitCast(hashUnencodedChars("a"))));
+    try testing.expectEqual(@as(i32, 0), @as(i32, @bitCast(hashUnencodedChars(""))));
+    try testing.expectEqual(@as(i32, 1689409188), @as(i32, @bitCast(hashUnencodedChars("hello world"))));
+    try testing.expectEqual(@as(i32, 1524218000), @as(i32, @bitCast(hashUnencodedChars("あいう"))));
+    try testing.expectEqual(@as(i32, -383720716), @as(i32, @bitCast(hashUnencodedChars("𠮷野家"))));
+}

test/diff/clj_corpus/clojure_lang_util.txt

@@ -22,3 +22,13 @@
 ;;=> true
 (clojure.lang.Util/hashCombine 7 13)
 ;;=> -1640531072
+(clojure.lang.Murmur3/hashUnencodedChars "abc")
+;;=> 1118836419
+(clojure.lang.Murmur3/hashUnencodedChars "")
+;;=> 0
+(clojure.lang.Murmur3/hashUnencodedChars "hello world")
+;;=> 1689409188
+(clojure.lang.Murmur3/hashUnencodedChars "あいう")
+;;=> 1524218000
+(clojure.lang.Murmur3/hashUnencodedChars "𠮷野家")
+;;=> -383720716