deferred item: scope-correct rename (shadowing), gated; Layer-2 boundary verified

(A) Scope-correct rename — the local-shadowing gap, CLOSED. The name-based rename
over-renames a shadowing local (param/let named like the def); the fix is identity
not spelling. chartroom's resolve.clj (Turtle #5) is a lexical resolver adding
refers_to edges (nearest enclosing scope), so renaming a def edits ONE node +
references follow refers_to — a shadowing local is a different node, untouched.
That's the principled "id-references" fix the deferral named, and it's Layer 2
(chartroom owns the engine). bin/test/code-as-claims/rename-scope.sh (CI-gated,
checks out chartroom) proves: def + caller-ref renamed; shadowing param + its use
untouched; recompiles. rename-in-store noted as the simpler module-local version.

(B) Layer-2 boundary — VERIFIED, not relocated. The language core (parse/check/
emit-clj/js/nix/types/ast) is clean: zero graph-engine machinery, only tombstone
comments for the removed (claim …) surface form. The code-intelligence engine
(resolver/rename/call-graph) is Layer 2 in chartroom; beagle gates RENT it. A
physical repo-split of bin/ tooling is org churn the principle doesn't require
(language already clean) and would risk the dev loop/gates — documented in
fram/docs as a separate deliberate migration, not a cleanliness fix.

Also: independently re-ran the eddy crm-v2 spike over its artifact with my own
reaches-closure — blast(contact.company)={contact.display-name}, decoy note.company
excluded. Unification confirmed both sides.

Author: tompassarelli

.github/workflows/test.yml

@@ -58,6 +58,12 @@ jobs:
           repository: tompassarelli/fram
           path: .fram
 
+      - name: Checkout chartroom (Layer-2 code-intelligence: the refers_to resolver)
+        uses: actions/checkout@v5
+        with:
+          repository: tompassarelli/chartroom
+          path: .chartroom
+
       - name: Graph-native cascade — scope-correctness gate
         run: FRAM_OUT="$GITHUB_WORKSPACE/.fram/out" bin/test/cascade-graph/run.sh
 
@@ -95,6 +101,12 @@ jobs:
       - name: Authoring substrate — recompile-gated edit transaction
         run: FRAM_OUT="$GITHUB_WORKSPACE/.fram/out" bin/test/code-as-claims/author.sh
 
+      # Scope-correct rename: renaming a def leaves a SHADOWING local of the same name
+      # untouched, via chartroom's refers_to resolver (binding identity, not spelling).
+      # The Layer-2 code-intelligence engine driven by a beagle gate.
+      - name: Scope-correct rename (shadowing) — refers_to resolver gate
+        run: FRAM_OUT="$GITHUB_WORKSPACE/.fram/out" CHARTROOM="$GITHUB_WORKSPACE/.chartroom" bin/test/code-as-claims/rename-scope.sh
+
       - name: Show accumulated surface debt
         if: always()
         run: |

bin/test/code-as-claims/rename-in-store.clj

@@ -11,6 +11,12 @@
 ;; toolchain owns it. Refuses (exit 3) if `new` already binds in a target module
 ;; (the rename-doesn't-collide invariant) — no claims mutated on refusal.
 ;;
+;; SCOPE: this is the MODULE-LOCAL, name-based rename (renames every same-named
+;; symbol leaf in the target module) — correct across MODULES (the mod_a/mod_b
+;; collision), but it would over-rename a SHADOWING local of the same name. The
+;; scope-correct-under-shadowing rename is chartroom's resolve.clj (Turtle #5,
+;; refers_to identity) — gated by bin/test/code-as-claims/rename-scope.sh.
+;;
 ;;   bb -cp <fram>/out rename-in-store.clj <old> <new> <target-substr> <outdir> <edn>...
 (ns rename-in-store
   (:require [clojure.edn :as edn]

bin/test/code-as-claims/rename-scope.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Scope-correct rename — the deferred local-shadowing gap, CLOSED.
+#
+# The name-based rename (rename-in-store) renames every same-named symbol leaf in a
+# module, so it CORRUPTS a shadowing local (a param/let named like the def). The fix
+# is identity, not spelling: chartroom's resolve.clj (Turtle #5) is a lexical
+# resolver that adds `refers_to <binding-node-id>` edges (nearest enclosing scope),
+# so renaming a DEF edits one node + references follow refers_to — a shadowing local
+# is a DIFFERENT node and is left untouched. That is the principled "id-references"
+# fix the deferral named, and it lives in chartroom = Layer 2 (the code-intelligence
+# engine); this beagle gate drives it (a consumer renting the engine).
+#
+# Fixture: `helper` is a top-level def AND a shadowing param in `other`. Renaming the
+# def must rename the def + the caller's reference, and leave the shadowing param
+# (and its use) ALONE. Needs racket + bb + fram out/ + chartroom's resolve.clj.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$HERE/../../.." && pwd)"
+RT="$ROOT/beagle-lib/private/claims-roundtrip.rkt"
+FRAM_OUT="${FRAM_OUT:-$HOME/code/fram/out}"
+CHARTROOM="${CHARTROOM:-$HOME/code/chartroom}"
+RES="$CHARTROOM/src/resolve.clj"
+fail=0
+
+echo "================ scope-correct rename — shadowing handled (refers_to resolver) ================"
+[ -d "$FRAM_OUT" ] || { echo "  (need FRAM_OUT)"; exit 3; }
+[ -f "$RES" ]     || { echo "  (need chartroom resolve.clj at $RES — set CHARTROOM)"; exit 3; }
+
+W="$(mktemp -d)"; trap 'rm -rf "$W" /tmp/resolved-mod.bclj.edn' EXIT
+racket "$RT" --emit-edn "$HERE/shadow-corpus/mod.bclj" 2>/dev/null > "$W/a.edn"
+# the Layer-2 engine: scope-correct rename of the DEF `helper` -> `safe-add`
+bb -cp "$FRAM_OUT" "$RES" rename helper safe-add mod "$W/a.edn" 2>/dev/null
+racket "$RT" --render /tmp/resolved-mod.bclj.edn 2>/dev/null > "$W/regen.bclj"
+echo "--- rename result ---"; sed 's/^/    /' "$W/regen.bclj"
+
+R="$W/regen.bclj"
+chk() { if eval "$2"; then echo "  PASS  $1"; else echo "  FAIL  $1"; fail=1; fi; }
+echo "--- assertions ---"
+chk "def renamed: '(defn safe-add'"                      "grep -q '(defn safe-add' '$R'"
+chk "def name 'helper' gone as a def"                    "! grep -q '(defn helper' '$R'"
+chk "caller reference renamed: '(safe-add y)'"           "grep -q '(safe-add y)' '$R'"
+chk "SHADOWING param untouched: 'other \[helper'"        "grep -qE 'other \[helper' '$R'"
+chk "SHADOWING use untouched: '(* helper 2)'"            "grep -qF '(* helper 2)' '$R'"
+echo "--- recompiles ---"
+mkdir -p "$W/r/fram"; cp "$R" "$W/r/fram/mod.bclj"
+if "$ROOT/bin/beagle-build-all" "$W/r" --out "$W/o" 2>&1 | grep -q '0 error'; then
+  echo "  PASS  renamed module builds clean"
+else echo "  FAIL  renamed module does not build"; fail=1; fi
+
+echo
+if [ "$fail" = 0 ]; then
+  echo "RESULT: PASS — rename follows binding identity: def + refs renamed, shadowing local untouched."
+else
+  echo "RESULT: FAIL"; exit 1
+fi

bin/test/code-as-claims/shadow-corpus/mod.bclj

@@ -0,0 +1,8 @@
+#lang beagle/clj
+;; `helper` is a top-level def AND a shadowing param in `other`.
+(defn helper [x :- Int] :- Int
+  (+ x 1))
+(defn other [helper :- Int] :- Int
+  (* helper 2))
+(defn caller [y :- Int] :- Int
+  (helper y))