@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# scripts/check_repr_decode.sh — collection representation-encapsulation guard.
+#
+# Born from Discussion #12: `valueSetToForm` decoded a set's backing map as an
+# ArrayMap unconditionally, so a 9+-element set literal (promoted to a HashMap
+# backing) segfaulted macroexpansion. The same misread was then found live in
+# multimethod hierarchy dispatch (silently gone at the 9th defmethod), the
+# http client (9-entry :headers rejected) and the http server (>8 response
+# headers dropped). One bug, five sites, three symptom faces.
+#
+# The class: code OUTSIDE src/runtime/collection/ decoding a collection's
+# backing-representation struct directly. The representation (array vs HAMT,
+# promotion boundaries) is the collection module's private business; everyone
+# else iterates via the generic accessors (`map.forEachEntry`,
+# `set.forEachElem`, `count`, `get`, …), which handle every backing.
+#
+# What it does:
+#   1. HARD: flag any `decodePtr(*const <mod>.<ReprStruct>)` outside
+#      src/runtime/collection/ whose line (or the line above) does not carry a
+#      `repr-decode-ok:` waiver. Violations beyond BASELINE fail --gate.
+#   2. WARN (informational, never fails): a lone one-representation tag test
+#      (`== .array_map` with no `hash_map` nearby) — the guard-shape that is
+#      memory-safe but drops semantics past the promotion boundary.
+#
+# Waiver form (line above or same line; keep it greppable):
+#   // repr-decode-ok: <why this site may know the representation> [refs: …]
+#
+# Modes:
+#   bash scripts/check_repr_decode.sh           informational; always exits 0
+#   bash scripts/check_repr_decode.sh --strict  exit 1 on any violation
+#   bash scripts/check_repr_decode.sh --gate    exit 1 if violations > BASELINE
+
+set -euo pipefail
+
+BASELINE=0
+MODE="${1:-info}"
+
+cd "$(dirname "$0")/.."
+
+# Representation structs private to src/runtime/collection/. Matching on the
+# TYPE name (not the import alias) is deliberate: files alias the module as
+# map_collection / map_mod / set_mod / …, but the struct names are unique in
+# the tree today.
+REPR_TYPES='ArrayMap|PersistentHashMap|HamtMapNode|HashCollisionMapNode|PersistentHashSet|SortedMap|SortedSet|RbNode|Vector|TailNode|HamtNode'
+
+violations=0
+while IFS= read -r hit; do
+    file="${hit%%:*}"
+    rest="${hit#*:}"
+    line="${rest%%:*}"
+    # Waiver on the flagged line or the line above.
+    if sed -n "$((line > 1 ? line - 1 : 1)),${line}p" "$file" | grep -q 'repr-decode-ok:'; then
+        continue
+    fi
+    echo "REPR-DECODE: $hit"
+    violations=$((violations + 1))
+done < <(grep -rnE "decodePtr\(\*(const )?[A-Za-z_]+\.(${REPR_TYPES})\)" src \
+           --include='*.zig' | grep -v '^src/runtime/collection/' || true)
+
+if [ "$violations" -gt 0 ]; then
+    echo "check_repr_decode: $violations un-waived representation decode(s) outside src/runtime/collection/."
+    echo "  Iterate via the generic accessors (map.forEachEntry / set.forEachElem / count / get)"
+    echo "  — they handle every backing, incl. past the ArrayMap→HashMap promotion at 9 entries."
+    echo "  A site that legitimately must know the representation takes an inline waiver:"
+    echo "    // repr-decode-ok: <why> [refs: …]"
+else
+    echo "check_repr_decode: no un-waived representation decodes outside src/runtime/collection/"
+fi
+
+# Secondary, WARN-only: single-representation tag tests with no dual-backing
+# awareness on the same line. Catches the guard-shape (semantics silently
+# dropped past promotion) once the decode itself is gone. Deliberately not a
+# gate: printers/serializers legitimately scope by tag.
+warns=$(grep -rnE '[=!]= *\.array_map' src --include='*.zig' \
+    | grep -v '^src/runtime/collection/' | grep -v 'hash_map' | grep -v 'repr-decode-ok:' || true)
+if [ -n "$warns" ]; then
+    echo
+    echo "WARN (informational) — lone .array_map tag tests (no hash_map on the line):"
+    printf '%s\n' "$warns" | sed 's/^/  /'
+fi
+
+case "$MODE" in
+    --strict) [ "$violations" -eq 0 ] || exit 1 ;;
+    --gate)   [ "$violations" -le "$BASELINE" ] || exit 1 ;;
+    *) ;;
+esac
+exit 0
@@ -226,20 +226,23 @@ fn formatErrorEdn(info: error_mod.Info, ctx: error_print.SourceContext, w: *Writ
         }
     }
     // Merge the snapshotted `cljw.error/*error-context*` entries as
-    // top-level event fields (ADR-0055 D3). array_map only — context
-    // maps are small (the >8-entry hash_map path mirrors printMap's
-    // limitation; a large context is rare and never silently truncated
-    // because count ≤ 8 stays array_map).
+    // top-level event fields (ADR-0055 D3). Iterate via the generic
+    // `forEachEntry` so a >8-entry context (promoted to hash_map) lands in
+    // the event whole — the old array_map-only decode skipped it entirely
+    // (Discussion #12 bug class).
     if (info.context) |ctx_map| {
-        if (ctx_map.tag() == .array_map) {
-            const am = ctx_map.decodePtr(*const map_collection.ArrayMap);
-            var i: u32 = 0;
-            while (i < am.count) : (i += 1) {
-                try w.writeByte(' ');
-                try print_value(w, am.entries[2 * i]);
-                try w.writeByte(' ');
-                try print_value(w, am.entries[2 * i + 1]);
-            }
+        if (ctx_map.tag() == .array_map or ctx_map.tag() == .hash_map) {
+            const CtxEmit = struct {
+                w: *Writer,
+                fn put(c: *@This(), k: Value, v: Value) anyerror!void {
+                    try c.w.writeByte(' ');
+                    try print_value(c.w, k);
+                    try c.w.writeByte(' ');
+                    try print_value(c.w, v);
+                }
+            };
+            var cctx: CtxEmit = .{ .w = w };
+            try map_collection.forEachEntry(ctx_map, &cctx, CtxEmit.put);
         }
     }
     try w.writeAll("}\n");
 
@@ -215,8 +215,8 @@ pub fn tryClojureLangMethod(
     // `(comparator [_] (.comparator backing-sorted-map))` chains through here.
     if (std.mem.eql(u8, name, "comparator") and args.len == 0) {
         const comp = switch (receiver.tag()) {
-            .sorted_map => receiver.decodePtr(*const sorted.SortedMap).comparator,
-            .sorted_set => receiver.decodePtr(*const sorted.SortedSet).map.decodePtr(*const sorted.SortedMap).comparator,
+            .sorted_map => receiver.decodePtr(*const sorted.SortedMap).comparator, // repr-decode-ok: comparator field read; sorted_map has a single backing
+            .sorted_set => receiver.decodePtr(*const sorted.SortedSet).map.decodePtr(*const sorted.SortedMap).comparator, // repr-decode-ok: comparator field read; sorted_set has a single backing
             else => return null,
         };
         if (!comp.isNil()) return comp;
 
@@ -385,7 +385,7 @@ fn writeValueRaw(ctx: *WriteCtx, w: *std.Io.Writer, v: Value) SerializeError!voi
         },
         .array_map => {
             try writeU8(w, @intFromEnum(ValueTag.array_map));
-            const am = v.decodePtr(*const map_mod.ArrayMap);
+            const am = v.decodePtr(*const map_mod.ArrayMap); // repr-decode-ok: serialized format is representation-dependent by design; a hash_map raises HashMapNotSerializable
             try writeU32(w, am.count);
             var i: u32 = 0;
             while (i < am.count) : (i += 1) {
@@ -402,9 +402,9 @@ fn writeValueRaw(ctx: *WriteCtx, w: *std.Io.Writer, v: Value) SerializeError!voi
         },
         .hash_set => {
             try writeU8(w, @intFromEnum(ValueTag.hash_set));
-            const s = v.decodePtr(*const set_mod.PersistentHashSet);
+            const s = v.decodePtr(*const set_mod.PersistentHashSet); // repr-decode-ok: set backing read for the serializable (array_map) check below
             if (s.map.tag() != .array_map) return SerializeError.HashMapNotSerializable;
-            const am = s.map.decodePtr(*const map_mod.ArrayMap);
+            const am = s.map.decodePtr(*const map_mod.ArrayMap); // repr-decode-ok: serialized format is representation-dependent by design; guarded by the check above
             try writeU32(w, am.count);
             var i: u32 = 0;
             while (i < am.count) : (i += 1) try writeValue(ctx, w, am.entries[2 * i]);
 
@@ -592,8 +592,8 @@ pub fn emptyFn(rt: *Runtime, env: *Env, args: []const Value, loc: SourceLocation
         // Sorted variants keep their comparator (clj PersistentTreeMap.empty()
         // returns an empty tree with the same comp) — data.priority-map's
         // `(empty priority->set-of-items)` relies on it.
-        .sorted_map => try sorted.emptyMapBy(rt, coll.decodePtr(*const sorted.SortedMap).comparator),
-        .sorted_set => try sorted.emptySetBy(rt, coll.decodePtr(*const sorted.SortedSet).map.decodePtr(*const sorted.SortedMap).comparator),
+        .sorted_map => try sorted.emptyMapBy(rt, coll.decodePtr(*const sorted.SortedMap).comparator), // repr-decode-ok: comparator field read; sorted_map has a single backing
+        .sorted_set => try sorted.emptySetBy(rt, coll.decodePtr(*const sorted.SortedSet).map.decodePtr(*const sorted.SortedMap).comparator), // repr-decode-ok: comparator field read; sorted_set has a single backing
         .persistent_queue => try persistent_queue.emptyQueue(rt), // (empty q) → EMPTY
         .list, .cons => try list.emptyList(rt), // (empty '(1 2)) → () (D-164)
         // JVM Clojure: (empty "hi") → nil (String is not a Clojure
 
@@ -165,7 +165,7 @@ fn rebuildArrayMap(
     ctx: anytype,
 ) anyerror!Value {
     var result = map_collection.empty();
-    const am = form.decodePtr(*const map_collection.ArrayMap);
+    const am = form.decodePtr(*const map_collection.ArrayMap); // repr-decode-ok: dispatch-guaranteed .array_map; the .hash_map arm routes to rebuildHashMap
     // GC-ROOT: C6 — root the source map + accumulator + the in-flight [k v] entry
     // across transform_child (D-252) [ref: .dev/gc_rooting.md §C].
     var gc_roots: [3]Value = .{ form, result, .nil_val };
 
@@ -58,18 +58,24 @@ fn doRequest(rt: *Runtime, method: std.http.Method, args: []const Value, loc: So
 
         const hdr_v = map_mod.get(m, try keyword_mod.intern(rt, null, "headers")) catch Value.nil_val;
         if (!hdr_v.isNil()) {
-            if (hdr_v.tag() != .array_map)
+            if (hdr_v.tag() != .array_map and hdr_v.tag() != .hash_map)
                 return error_catalog.raise(.http_opts_invalid, loc, .{ .detail = "the :headers option must be a map of string→string" });
-            const am = hdr_v.decodePtr(*const map_mod.ArrayMap);
+            // Iterate via the generic `forEachEntry`: a 9+-entry :headers map
+            // promotes to hash_map and the old array_map-only decode rejected
+            // it as "not a map" (Discussion #12 bug class).
             var list: std.ArrayList(std.http.Header) = .empty;
-            var i: u32 = 0;
-            while (i < am.count) : (i += 1) {
-                const k = am.entries[2 * i];
-                const v = am.entries[2 * i + 1];
-                if (!k.isString() or !v.isString())
-                    return error_catalog.raise(.http_opts_invalid, loc, .{ .detail = "each :headers entry must be string→string" });
-                try list.append(scratch, .{ .name = string_mod.asString(k), .value = string_mod.asString(v) });
-            }
+            const HdrCollect = struct {
+                scratch: std.mem.Allocator,
+                list: *std.ArrayList(std.http.Header),
+                loc: SourceLocation,
+                fn put(c: *@This(), k: Value, v: Value) anyerror!void {
+                    if (!k.isString() or !v.isString())
+                        return error_catalog.raise(.http_opts_invalid, c.loc, .{ .detail = "each :headers entry must be string→string" });
+                    try c.list.append(c.scratch, .{ .name = string_mod.asString(k), .value = string_mod.asString(v) });
+                }
+            };
+            var hctx: HdrCollect = .{ .scratch = scratch, .list = &list, .loc = loc };
+            try map_mod.forEachEntry(hdr_v, &hctx, HdrCollect.put);
             extra_headers = list.items;
         }
     }
 
@@ -188,23 +188,34 @@ pub fn runServer(
             const b = map_mod.get(resp, kw_body) catch Value.nil_val;
             if (b.tag() == .string) body = string_mod.asString(b);
             const h = map_mod.get(resp, kw_headers) catch Value.nil_val;
-            if (h.tag() == .array_map) {
-                const am = h.decodePtr(*const map_mod.ArrayMap);
-                var i: u32 = 0;
-                while (i < am.count and n_headers < header_buf.len) : (i += 1) {
-                    const hk = am.entries[2 * i];
-                    const hv = am.entries[2 * i + 1];
-                    if (hk.tag() == .string and hv.tag() == .string) {
+            if (h.tag() == .array_map or h.tag() == .hash_map) {
+                // Iterate via the generic `forEachEntry`: a 9+-entry :headers
+                // map promotes to hash_map and the old array_map-only decode
+                // dropped ALL custom headers past that boundary (Discussion
+                // #12 bug class). The 16-header cap + SE-5 CRLF check are
+                // preserved inside the callback.
+                const HdrEmit = struct {
+                    header_buf: *[16]std.http.Header,
+                    n_headers: *usize,
+                    headers_clean: *bool,
+                    fn put(c: *@This(), hk: Value, hv: Value) anyerror!void {
+                        if (!c.headers_clean.* or c.n_headers.* >= c.header_buf.len) return;
+                        if (hk.tag() != .string or hv.tag() != .string) return;
                         const nm = string_mod.asString(hk);
                         const vl = string_mod.asString(hv);
                         if (!headerFieldClean(nm) or !headerFieldClean(vl)) {
-                            headers_clean = false;
-                            break;
+                            c.headers_clean.* = false;
+                            return;
                         }
-                        header_buf[n_headers] = .{ .name = nm, .value = vl };
-                        n_headers += 1;
+                        c.header_buf[c.n_headers.*] = .{ .name = nm, .value = vl };
+                        c.n_headers.* += 1;
                     }
-                }
+                };
+                var hctx: HdrEmit = .{ .header_buf = &header_buf, .n_headers = &n_headers, .headers_clean = &headers_clean };
+                // The callback never errors and the tag is guarded above, so a
+                // failure here is unreachable; swallow to keep the serve loop
+                // crash-free on handler data (the surrounding contract).
+                map_mod.forEachEntry(h, &hctx, HdrEmit.put) catch {};
             }
         }
         // SE-5: a control byte in any response header would split the response (or
 
@@ -287,32 +287,40 @@ pub fn getMethod(
     // Cycle 2-3 hierarchy resolution: collect isa? candidates;
     // if ≥ 2 use `dominates` (prefer-method ∪ isa?) to pick the
     // best; if no dominator survives the walk → raise ambiguity.
-    var best_key: ?Value = null;
-    var best_method: ?Value = null;
-    var ambiguous = false;
-    if (mf.method_table.tag() == .array_map) {
-        const am = mf.method_table.decodePtr(*const map_mod.ArrayMap);
-        var i: u32 = 0;
-        while (i < am.count) : (i += 1) {
-            const key = am.entries[2 * i];
-            if (@intFromEnum(key) == @intFromEnum(dispatch_val)) continue;
-            if (!(try isaCheck(ancestors, dispatch_val, key))) continue;
-
-            if (best_key) |bk| {
-                if (try dominates(mf.prefer_table, ancestors, key, bk)) {
-                    best_key = key;
-                    best_method = am.entries[2 * i + 1];
-                    ambiguous = false;
-                } else if (!(try dominates(mf.prefer_table, ancestors, bk, key))) {
-                    ambiguous = true;
+    // Iterate via the generic `forEachEntry` so a method_table that has
+    // promoted past the ArrayMap ceiling (9+ defmethods) is walked too —
+    // the old array_map-only decode silently skipped the whole isa? walk
+    // past that boundary, so hierarchy dispatch vanished at the 9th method
+    // while exact-match kept working (Discussion #12 bug class).
+    const IsaWalk = struct {
+        prefer_table: Value,
+        ancestors: Value,
+        dispatch_val: Value,
+        best_key: ?Value = null,
+        best_method: ?Value = null,
+        ambiguous: bool = false,
+        fn visit(c: *@This(), key: Value, method: Value) anyerror!void {
+            if (@intFromEnum(key) == @intFromEnum(c.dispatch_val)) return;
+            if (!(try isaCheck(c.ancestors, c.dispatch_val, key))) return;
+
+            if (c.best_key) |bk| {
+                if (try dominates(c.prefer_table, c.ancestors, key, bk)) {
+                    c.best_key = key;
+                    c.best_method = method;
+                    c.ambiguous = false;
+                } else if (!(try dominates(c.prefer_table, c.ancestors, bk, key))) {
+                    c.ambiguous = true;
                 }
             } else {
-                best_key = key;
-                best_method = am.entries[2 * i + 1];
+                c.best_key = key;
+                c.best_method = method;
             }
         }
-    }
-    if (ambiguous) {
+    };
+    var walk: IsaWalk = .{ .prefer_table = mf.prefer_table, .ancestors = ancestors, .dispatch_val = dispatch_val };
+    try map_mod.forEachEntry(mf.method_table, &walk, IsaWalk.visit);
+    const best_method = walk.best_method;
+    if (walk.ambiguous) {
         const name_sym = symbol.asSymbol(mf.name);
         return error_catalog.raise(.multimethod_ambiguous_dispatch, loc, .{
             .name = name_sym.name,