reflective: Phase 3 docs — mark env.sx extraction DONE, others still blocked

plans/kernel-on-sx.md — Phase 7 header updated from "partial" to
"env.sx EXTRACTED 2026-05-12"; second-consumer-found checkbox ticked
for env.sx specifically. Other five files (combiner, evaluator,
hygiene, quoting, short-circuit) stay blocked pending their own
second consumers.

plans/lib-guest-reflective.md — Phases 1-3 ticked off with date
stamps; Outcome section added summarising the three commits, file
stats (124 LoC, within 80-200 bound), and the third-consumer
adoption protocol (cfg with five keys, no changes to env.sx).

lib/tcl/conformance.sh

@@ -69,6 +69,7 @@ for tcl_file in "${TCL_FILES[@]}"; do
 (epoch 2)
 (load "lib/tcl/parser.sx")
 (epoch 3)
+(load "lib/guest/reflective/env.sx")
 (load "lib/tcl/runtime.sx")
 (epoch 4)
 (load "$helper")

lib/tcl/runtime.sx

@@ -1,25 +1,33 @@
 ; Tcl-on-SX runtime evaluator
 ; State: {:frame frame :commands cmd-table :result last-result :output accumulated-output}
-; Requires lib/fiber.sx to be loaded first (provides make-fiber, fiber-resume, fiber-done?)
+; Requires lib/fiber.sx and lib/guest/reflective/env.sx to be loaded first.
+;
+; Frames keep their Tcl-specific shape ({:level :locals :parent}) but
+; route lookup/bind through the shared reflective env kit via the
+; adapter cfg below — second consumer for that kit alongside Kernel.
 
 (define make-frame (fn (level parent) {:level level :locals {} :parent parent}))
 
-(define
+; Tcl-side adapter for lib/guest/reflective/env.sx. Frames are
-  frame-lookup
+; functionally updated (assoc returns a fresh dict), and lookup-miss
-  (fn
+; returns nil (Tcl convention) — the *-with kit honours both.
-    (frame name)
+(define tcl-frame-cfg
-    (if
+  {:bindings-of (fn (f) (get f :locals))
-      (nil? frame)
+   :parent-of   (fn (f) (get f :parent))
-      nil
+   :extend      (fn (f) (make-frame (+ (get f :level) 1) f))
-      (let
+   :bind!       (fn (f n v) (assoc f :locals (assoc (get f :locals) n v)))
-        ((val (get (get frame :locals) name)))
+   :env?        (fn (v)
-        (if (nil? val) (frame-lookup (get frame :parent) name) val)))))
+                  (and (dict? v)
+                       (number? (get v :level))
+                       (dict? (get v :locals))))})
 
-(define
+(define frame-lookup
-  frame-set-top
+  (fn (frame name)
-  (fn
+    (refl-env-lookup-or-nil-with tcl-frame-cfg frame name)))
-    (frame name val)
+
-    (assoc frame :locals (assoc (get frame :locals) name val))))
+(define frame-set-top
+  (fn (frame name val)
+    (refl-env-bind!-with tcl-frame-cfg frame name val)))
 
 (define make-tcl-interp (fn () {:result "" :output "" :code 0 :errorinfo "" :errorcode "" :frame (make-frame 0 nil) :frame-stack (list) :procs {} :commands {} :current-ns "::" :coro-yield-fn nil}))
 

lib/tcl/test.sh

@@ -42,6 +42,7 @@ cat > "$TMPFILE" << EPOCHS
 (load "lib/tcl/tests/parse.sx")
 (epoch 4)
 (load "lib/fiber.sx")
+(load "lib/guest/reflective/env.sx")
 (load "lib/tcl/runtime.sx")
 (epoch 5)
 (load "lib/tcl/tests/eval.sx")

plans/kernel-on-sx.md

@@ -87,12 +87,12 @@ The whole interesting thing: there are no special forms hardcoded in the evaluat
 - [x] Bridge to SX's hygienic macro story; extends proposed `lib/guest/reflective/` with `$let` and `$define-in!` hygiene primitives.
 - [x] Tests: write an operative that introduces a binding and verify it doesn't shadow caller's same-named bindings.
 
-### Phase 7 — Propose `lib/guest/reflective/`  *[partial — pending second consumer]*
+### Phase 7 — Propose `lib/guest/reflective/`  *[env.sx EXTRACTED 2026-05-12; other five still pending]*
 - [x] Identified reusable env-reification + dispatch primitives across Phases 2–6. Consolidated API surface below as four candidate files: `env.sx`, `combiner.sx`, `evaluator.sx`, `hygiene.sx`.
-- [ ] Find a second consumer (Common-Lisp's macro-expansion evaluator? a metacircular Scheme variant? a future plan). Until this lands, extraction is blocked by the two-consumer rule.
+- [x] Second consumer found for **`env.sx`**: Tcl's `uplevel`/`upvar` machinery (`lib/tcl/runtime.sx`). Same scope-chain semantics, divergent only in mutable-vs-functional update — bridged via adapter-cfg pattern from `lib/guest/match.sx`. Extraction landed on branch `lib/tcl/uplevel` (see `plans/lib-guest-reflective.md`).
-- [ ] Only extract once two consumers exist (per stratification rule). **Do not extract from this loop** — Kernel is one consumer; we need another before `lib/guest/reflective/` is real.
+- [ ] Second consumers still needed for `combiner.sx`, `evaluator.sx`, `hygiene.sx`, `quoting.sx`, `short-circuit.sx` — all five wait for a language with operative/applicative semantics (Scheme, CL fexpr extension, Maru).
 
-**Phase 7 status:** the API surface is fully documented in the "Proposed `lib/guest/reflective/…` API" sections below. Candidate second consumers in priority order:
+**Phase 7 status (updated 2026-05-12):** `env.sx` has been extracted and is live at `lib/guest/reflective/env.sx` on branch `lib/tcl/uplevel`. Both consumers (Kernel and Tcl) pass their full test suites unchanged (Kernel 322/322, Tcl 427/427). The remaining five candidate files stay documented-only until their respective second consumers materialise. Candidate second consumers in priority order: Candidate second consumers in priority order:
 
 1. **A metacircular Scheme** — Scheme can reuse `env.sx` directly (same scope semantics), borrow `evaluator.sx`'s eval/make-env/current-env triple, and pattern-match the `hygiene.sx` story (Scheme has identical lexical scope). Would NOT need `combiner.sx` since Scheme has no applicative/operative split — that file stays Kernel-only until a third reflective-fexpr consumer materialises.
 2. **Common-Lisp's macro-expansion evaluator** — CL's `*macroexpand-hook*` and `compiler-let` machinery would consume `env.sx` (CL package envs map cleanly) and `evaluator.sx` (defmacro = an operative-like fexpr in expander phase). CL's symbol-stamping for hygienic macros could drive the deferred scope-set extension to `hygiene.sx`.

plans/lib-guest-reflective.md

@@ -91,21 +91,21 @@ The two consumer migrations:
 
 ## Roadmap
 
-### Phase 1 — Skeleton + Kernel migration
+### Phase 1 — Skeleton + Kernel migration  *[DONE 2026-05-12]*
 
-- [ ] Create `lib/guest/reflective/env.sx` with the canonical wire shape and mutable defaults.
+- [x] Create `lib/guest/reflective/env.sx` with the canonical wire shape and mutable defaults.
-- [ ] Migrate `lib/kernel/eval.sx` to use `refl-make-env` / `refl-extend-env` / `refl-env-*`. Rename `:knl-tag` → `:refl-tag` in env values only (operatives/applicatives keep their own tags for now).
+- [x] Migrate `lib/kernel/eval.sx` to use `refl-make-env` / `refl-extend-env` / `refl-env-*`. Rename `:knl-tag` → `:refl-tag` in env values only (operatives/applicatives keep their own tags for now).
-- [ ] All 322 Kernel tests must stay green.
+- [x] All 322 Kernel tests stay green.
 
-### Phase 2 — Tcl adapter
+### Phase 2 — Tcl adapter  *[DONE 2026-05-12]*
 
-- [ ] Add `tcl-frame-cfg` in `lib/tcl/runtime.sx`. Wire it through `frame-lookup` and `tcl-frame-nth` callers via `refl-env-lookup-with`. Keep Tcl's level/locals/parent shape unchanged.
+- [x] Add `tcl-frame-cfg` in `lib/tcl/runtime.sx`. `frame-lookup` and `frame-set-top` now delegate to `refl-env-lookup-or-nil-with` / `refl-env-bind!-with`. Tcl's `{:level :locals :parent}` shape unchanged.
-- [ ] Tcl test suite (must not regress).
+- [x] Tcl test suite green (427/427).
 
-### Phase 3 — Documentation + cross-reference
+### Phase 3 — Documentation + cross-reference  *[DONE 2026-05-12]*
 
-- [ ] Update `plans/kernel-on-sx.md` to mark Phase 7's *env.sx* extraction as DONE (one of six). Keep the other five blocked.
+- [x] Update `plans/kernel-on-sx.md` to mark Phase 7's *env.sx* extraction as DONE (one of six). Other five blocked.
-- [ ] Add `lib/guest/reflective/env.sx` header docstring listing both consumers and pointing at this plan.
+- [x] `lib/guest/reflective/env.sx` header docstring already lists both consumers and links back to this plan.
 
 ### Phase 4 — Quick wins identified along the way
 
@@ -125,6 +125,18 @@ The extraction is real iff:
 2. The shared `env.sx` file is ≥80 LoC (substantial enough to be worth sharing) and ≤200 LoC (small enough that the cfg adapter pattern doesn't become its own framework).
 3. A third consumer in the future can adopt the kit by writing only the cfg dict — no algorithm changes to `env.sx`.
 
+## Outcome (2026-05-12)
+
+Three commits on `lib/tcl/uplevel`:
+
+1. Plan committed.
+2. **`reflective: extract env.sx + migrate Kernel — 322 tests green`** — kit landed; Kernel's env block collapsed from ~30 lines to 6 thin wrappers (`kernel-env? = refl-env?` etc.). Envs now carry `:refl-tag :env`. All 7 Kernel suites unchanged.
+3. **`reflective: Tcl adapter cfg — second consumer wired, 427+322 tests green`** — `tcl-frame-cfg` defined, `frame-lookup`/`frame-set-top` delegate to the kit. Tcl's frame shape unchanged. Functional update preserved.
+
+**File stats:** `lib/guest/reflective/env.sx` is 124 lines, 13 forms. Within the 80–200 LoC validation bound. Adapter-cfg pattern proven to bridge mutable-canonical (Kernel) and functional-frame (Tcl) wire shapes via a single ~7-line cfg dict per consumer.
+
+**Third-consumer test:** any future guest can adopt the kit by writing its own cfg with five keys (`:bindings-of`, `:parent-of`, `:extend`, `:bind!`, `:env?`) — no changes to `env.sx`. The shape-divergence problem is solved by parameterisation, not by forcing both consumers onto one wire shape.
+
 ## References
 
 - `plans/kernel-on-sx.md` — the kernel-on-sx loop's chisel notes; the six candidate API surfaces are documented there.