merge: hs-f into architecture — JIT Phase 1 (tiered compilation)

# Conflicts:
#	hosts/ocaml/lib/sx_primitives.ml

hosts/ocaml/bin/run_tests.ml

@@ -1279,7 +1279,7 @@ let run_foundation_tests () =
   assert_true "sx_truthy \"\"" (Bool (sx_truthy (String "")));
   assert_eq "not truthy nil" (Bool false) (Bool (sx_truthy Nil));
   assert_eq "not truthy false" (Bool false) (Bool (sx_truthy (Bool false)));
-  let l = { l_params = ["x"]; l_body = Symbol "x"; l_closure = Sx_types.make_env (); l_name = None; l_compiled = None } in
+  let l = { l_params = ["x"]; l_body = Symbol "x"; l_closure = Sx_types.make_env (); l_name = None; l_compiled = None; l_call_count = 0 } in
   assert_true "is_lambda" (Bool (Sx_types.is_lambda (Lambda l)));
   ignore (Sx_types.set_lambda_name (Lambda l) "my-fn");
   assert_eq "lambda name mutated" (String "my-fn") (lambda_name (Lambda l))

hosts/ocaml/lib/sx_primitives.ml

@@ -4109,4 +4109,25 @@ let () =
         | k :: v :: rest -> ignore (env_bind child (value_to_string k) v); add_bindings rest
         | [_] -> raise (Eval_error "env-extend: odd number of key-val pairs") in
       add_bindings pairs;
-      Env child)
+      Env child);
+
+  (* JIT cache control & observability — backed by refs in sx_types.ml to
+     avoid creating a sx_primitives → sx_vm dependency cycle. sx_vm reads
+     these refs to decide when to JIT. *)
+  register "jit-stats" (fun _args ->
+    let d = Hashtbl.create 8 in
+    Hashtbl.replace d "threshold"        (Number (float_of_int !Sx_types.jit_threshold));
+    Hashtbl.replace d "compiled"         (Number (float_of_int !Sx_types.jit_compiled_count));
+    Hashtbl.replace d "compile-failed"   (Number (float_of_int !Sx_types.jit_skipped_count));
+    Hashtbl.replace d "below-threshold"  (Number (float_of_int !Sx_types.jit_threshold_skipped_count));
+    Dict d);
+  register "jit-set-threshold!" (fun args ->
+    match args with
+    | [Number n] -> Sx_types.jit_threshold := int_of_float n; Nil
+    | [Integer n] -> Sx_types.jit_threshold := n; Nil
+    | _ -> raise (Eval_error "jit-set-threshold!: (n) where n is integer"));
+  register "jit-reset-counters!" (fun _args ->
+    Sx_types.jit_compiled_count := 0;
+    Sx_types.jit_skipped_count := 0;
+    Sx_types.jit_threshold_skipped_count := 0;
+    Nil)

hosts/ocaml/lib/sx_types.ml

@@ -138,6 +138,7 @@ and lambda = {
   l_closure : env;
   mutable l_name : string option;
   mutable l_compiled : vm_closure option;  (** Lazy JIT cache *)
+  mutable l_call_count : int;              (** Tiered-compilation counter — JIT after threshold calls *)
 }
 
 and component = {
@@ -449,7 +450,20 @@ let make_lambda params body closure =
     | List items -> List.map value_to_string items
     | _ -> value_to_string_list params
   in
-  Lambda { l_params = ps; l_body = body; l_closure = unwrap_env_val closure; l_name = None; l_compiled = None }
+  Lambda { l_params = ps; l_body = body; l_closure = unwrap_env_val closure; l_name = None; l_compiled = None; l_call_count = 0 }
+
+(** {1 JIT cache control}
+
+    Tiered compilation: only JIT a lambda after it's been called [jit_threshold]
+    times. This filters out one-shot lambdas (test harness, dynamic eval, REPLs)
+    so they never enter the JIT cache. Counters are exposed to SX as [(jit-stats)].
+
+    These live here (in sx_types) rather than sx_vm so [sx_primitives] can read
+    them without creating a sx_primitives → sx_vm dependency cycle. *)
+let jit_threshold = ref 4
+let jit_compiled_count = ref 0
+let jit_skipped_count = ref 0
+let jit_threshold_skipped_count = ref 0
 
 let make_component name params has_children body closure affinity =
   let n = value_to_string name in

hosts/ocaml/lib/sx_vm.ml

@@ -57,6 +57,9 @@ let () = Sx_types._convert_vm_suspension := (fun exn ->
 let jit_compile_ref : (lambda -> (string, value) Hashtbl.t -> vm_closure option) ref =
   ref (fun _ _ -> None)
 
+(* JIT threshold and counters live in Sx_types so primitives can read them
+   without creating a sx_primitives → sx_vm dependency cycle. *)
+
 (** Sentinel closure indicating JIT compilation was attempted and failed.
     Prevents retrying compilation on every call. *)
 let jit_failed_sentinel = {
@@ -364,13 +367,21 @@ and vm_call vm f args =
      | None ->
        if l.l_name <> None
        then begin
-         l.l_compiled <- Some jit_failed_sentinel;
+         l.l_call_count <- l.l_call_count + 1;
-         match !jit_compile_ref l vm.globals with
+         if l.l_call_count >= !Sx_types.jit_threshold then begin
-         | Some cl ->
+           l.l_compiled <- Some jit_failed_sentinel;
-           l.l_compiled <- Some cl;
+           match !jit_compile_ref l vm.globals with
-           push_closure_frame vm cl args
+           | Some cl ->
-         | None ->
+             incr Sx_types.jit_compiled_count;
+             l.l_compiled <- Some cl;
+             push_closure_frame vm cl args
+           | None ->
+             incr Sx_types.jit_skipped_count;
+             push vm (cek_call_or_suspend vm f (List args))
+         end else begin
+           incr Sx_types.jit_threshold_skipped_count;
            push vm (cek_call_or_suspend vm f (List args))
+         end
        end
        else
          push vm (cek_call_or_suspend vm f (List args)))

plans/jit-cache-architecture.md

@@ -164,13 +164,22 @@ gets the same API for free.
 
 ## Rollout
 
-**Phase 1: Tiered compilation (1-2 days)**
+**Phase 1: Tiered compilation — IMPLEMENTED (commit b9d63112)**
-- Add `l_call_count` to lambda type
+- ✅ `l_call_count : int` field on lambda type (sx_types.ml)
-- Wire counter increment in `cek_call_or_suspend`
+- ✅ Counter increment + threshold check in cek_call_or_suspend Lambda case (sx_vm.ml)
-- Add `jit-set-threshold!` primitive
+- ✅ Module-level refs in sx_types: `jit_threshold` (default 4), `jit_compiled_count`,
-- Default threshold = 1 (no change in behavior)
+  `jit_skipped_count`, `jit_threshold_skipped_count`. Refs live in sx_types so
-- Bump default to 4 once test suite confirms stability
+  sx_primitives can read them without creating an import cycle.
-- Verify: HS conformance full-suite run completes without JIT saturation
+- ✅ Primitives: `jit-stats`, `jit-set-threshold!`, `jit-reset-counters!` (sx_primitives.ml)
+- Verified: 4771/1111 OCaml run_tests, identical to baseline — no regressions.
+
+**WASM rollout note:** The native binary has Phase 1 active. The browser
+WASM (`shared/static/wasm/sx_browser.bc.js`) needs to be rebuilt, but the
+new build uses a different value-wrapping ABI ({_type, __sx_handle} for
+numbers) incompatible with the current test runner (`tests/hs-run-filtered.js`).
+For now the test tree pins the pre-rewrite WASM. Resolving the ABI gap
+is a separate task — either update the test runner to unwrap, or expose
+a value-marshalling helper from the kernel.
 
 **Phase 2: LRU cache (3-5 days)**
 - Extract `Lambda.l_compiled` into central `sx_jit_cache.ml`

plans/minikanren-deferred.md

@@ -0,0 +1,216 @@
+# miniKanren-on-SX: deferred work
+
+The main plan (`plans/minikanren-on-sx.md`) carries Phases 1–7 through the
+naive-tabling milestone. This file collects the four pieces left on the
+shelf, with enough scope and design notes to drive a follow-up loop.
+
+Branch convention: keep the same `loops/minikanren` worktree; commit and
+push to `origin/loops/minikanren`. Squash-merge to `architecture` only
+when each numbered piece is shipped + tests green.
+
+Cumulative test count snapshot at squash-merge: **644** across
+**71 test files**. Every change below should grow the number, not break
+existing tests.
+
+## The four pieces
+
+### Piece A — Phase 7 SLG (cyclic patho, mutual recursion, fixed-point iteration)
+
+**Problem.** Naive tabling drains the answer stream eagerly, then caches.
+Recursive tabled calls with the SAME ground key see an empty cache (the
+in-progress entry never exists), so they recurse and the host
+overflows. Fibonacci works only because each recursive call has a
+*different* key; cyclic `patho` and any genuinely self-recursive tabled
+predicate diverge.
+
+**Approach** — a small subset of SLG / OLDT resolution, enough to handle
+the demos in the brief.
+
+1. **In-progress sentinel.** When a tabled call `T(args)` starts, store
+   `(:in-progress nil)` under its key. Recursive calls into `T(args)`
+   from inside its own computation see the sentinel and return only
+   the answers accumulated so far (initially empty).
+2. **Answer accumulator.** As each new answer is found, push it into
+   the cache entry: `(:in-progress accumulated-answers)`. After a
+   cycling caller returns, the outer continuation can re-consult the
+   updated cache.
+3. **Fixed-point iteration.** The driver repeatedly re-runs the goal
+   until no new answers appear in a full pass, then transitions the
+   cache from `:in-progress` to `:done`.
+4. **Subgoal table.** Track (subgoal, last-seen-cache-version) per
+   subscriber so each consumer only re-reads what it hasn't seen.
+
+**Suggested artefacts.**
+- `lib/minikanren/tabling-slg.sx` — new module with `table-slg-2`
+  (parallel to `table-2` from naive tabling). Keep `table-2` working
+  unchanged so Fibonacci/Ackermann don't regress.
+- `lib/minikanren/tests/cyclic-graph-tabled.sx` — the canonical demo:
+  two-cycle `patho` from a→b→a→b plus a→b→c. With SLG, `(run* q
+  (tab-patho :a :c q))` returns the single shortest path, not divergence.
+- `lib/minikanren/tests/mutual-recursion.sx` — even/odd via mutual
+  recursion (`even-o n` ↔ `odd-o (n-1)`), tabled at both names.
+
+**Reference reading.**
+- TRS chapter on tabling.
+- "Tabled Logic Programming" — Sagonas & Swift (the XSB / SLG paper).
+- core.logic's `tabled` macro for an SX-dialect-friendly precedent.
+
+**Risk.** This is the brief's "research-grade complexity, not a
+one-iteration item". Plan for 4–6 commits: in-progress sentinel,
+answer accumulator, fixed-point driver, then one demo per commit.
+
+### Piece B — Phase 6 polish: bounds-consistency for `fd-plus` / `fd-times`
+
+**Problem.** Current `fd-plus-prop` and `fd-times-prop` propagate only
+when two of three operands walk to ground numbers. When all three are
+domain-bounded vars, the propagator returns `s` unchanged — search has
+to label down to ground before any narrowing happens.
+
+**Approach** — narrow domains via interval reasoning even when no operand
+is ground.
+
+For `(fd-plus x y z)` with bounded x, y, z:
+- `x ∈ [z.min − y.max .. z.max − y.min]`
+- `y ∈ [z.min − x.max .. z.max − x.min]`
+- `z ∈ [x.min + y.min .. x.max + y.max]`
+
+For `(fd-times x y z)`: same shape, but with multiplication; need to
+handle sign cases (negative domain ranges) and the divisor-when-not-zero
+constraint already in place.
+
+**Suggested artefacts.**
+- Patch `fd-plus-prop` and `fd-times-prop` in `lib/minikanren/clpfd.sx`
+  with new `:else` branches that compute new domain bounds and call
+  `fd-set-domain` for each var.
+- New tests in `lib/minikanren/tests/clpfd-plus.sx` /
+  `clpfd-times.sx` exercising the all-domain case: two domain-bounded
+  vars in the body of a goal, with no labelling, after which their
+  domains have narrowed.
+- A demo: cryptarithmetic puzzle (see Piece D) using bounds
+  consistency to avoid labelling explosion.
+
+**Risk.** Low. The math is well-known; just careful min/max arithmetic
+and watch for edge cases (empty domain after narrowing).
+
+### Piece C — `=/=` disequality with constraint store
+
+**Problem.** `nafc` is sound only on ground args; `fd-neq` only on FD
+domains. There is no general-purpose Prolog-style structural
+disequality `=/=` that works on logic terms.
+
+**Approach.** Generalise the FD constraint store to a uniform
+"constraint store" that carries:
+- domain map (existing)
+- *pending disequalities* — a list of `(u v)` pairs that must remain
+  non-unifiable under any future extension.
+
+After every `==` / `mk-unify`, re-check each pending disequality:
+- If `(u v)` are now unifiable, fail.
+- If they're now structurally distinct (no shared substitution can
+  unify), drop from the store (the constraint is satisfied).
+- Otherwise leave in store.
+
+**Where it bites.** The kernel currently uses `mk-unify` everywhere.
+Either:
+1. Replace `mk-unify` with a constraint-aware wrapper everywhere
+   (intrusive, but principled).
+2. Keep `mk-unify` for goals that don't use `=/=`, and provide a
+   parallel `==-cs` / `=/=-cs` pair plus an alternative `run*-cs`
+   driver that fires the constraint check after each binding.
+
+Option 2 mirrors the `fd-fire-store` pattern and stays out of the
+common path.
+
+**Suggested artefacts.**
+- `lib/minikanren/diseq.sx` — disequality store on top of the
+  existing `_fd` reserved key (re-using the constraint list, just
+  with disequality-shaped closures instead of FD propagators).
+- `=/=` goal that posts a disequality and immediately checks it.
+- `=/=-test` integration: rewrite a few Phase 5 puzzles using `=/=`
+  instead of `nafc + ==`.
+- Tests covering: ground-pair fail, partial-pair satisfied later by
+  binding, partial-pair *contradicted* later by binding.
+
+**Risk.** Medium. The hard cases are *eventual* unifiability — a
+disequality `(=/= (cons a 1) (cons 2 b))` should hold until both `a`
+gets bound to `2` and `b` gets bound to `1`. Implementations like
+core.logic's encode this as a list of "violating bindings" the
+disequality remembers.
+
+### Piece D — Bigger CLP(FD) demos: send-more-money + Sudoku 4×4
+
+**Problem.** The current N-queens demo only verifies the constraint
+chain end-to-end. The brief's full Phase 6 list includes
+"send-more-money, N-queens with CLP(FD), map coloring,
+cryptarithmetic" — most of which exercise *more* than just `fd-neq +
+fd-distinct`.
+
+**Approach.** Two concrete puzzles that both stress
+bounds-consistency (Piece B) once it lands:
+
+#### send-more-money
+
+```
+  S E N D
++ M O R E
+---------
+M O N E Y
+```
+
+8 distinct digits ∈ {0..9}, S ≠ 0, M ≠ 0. Encoded as a sum-of-digits
+equation using `fd-plus` + carry chains.
+
+Without Piece B (bounds-consistency), the search labels every digit
+combination upfront — slow but tractable on a fast machine. With
+Piece B, the impossible high-digit cases prune early.
+
+Test: a single solution `(9 5 6 7 1 0 8 2)`.
+
+#### Sudoku 4×4
+
+Easier than 9×9 but exercises the full pattern:
+- 16 cells, each ∈ {1..4}
+- 4 rows, 4 cols, 4 2×2 boxes — 12 `fd-distinct` constraints
+- Some cells fixed as clues
+
+A small solver should handle 4×4 in well under a second once
+bounds-consistency narrows columns / boxes after each label step.
+
+**Suggested artefacts.**
+- `lib/minikanren/tests/send-more-money.sx` — single-solution test.
+- `lib/minikanren/tests/sudoku-4x4.sx` — at least three cluesets:
+  unique solution, multiple solutions, no solution.
+- Optional: `lib/minikanren/sudoku.sx` with a parameterised
+  `sudoku-n` for both 4×4 and a 9×9 stress test.
+
+**Risk.** Low–medium for 4×4 + send-more-money once Piece B lands.
+9×9 Sudoku is a stretch; treat it as a stretch goal once the smaller
+demos are green.
+
+## Suggested ordering
+
+1. **Piece B first** (bounds-consistency for `fd-plus` / `fd-times`).
+   Self-contained, low-risk, and unlocks Piece D's harder puzzles.
+2. **Piece D** (the two demos). Validates Piece B with concrete
+   puzzles. Doubles as the brief's missing canary tests.
+3. **Piece C** (`=/=`). Independent track; once shipped, refactor the
+   pet/diff puzzles in Phase 5 to use it instead of nafc.
+4. **Piece A** (SLG tabling). Last because it's the highest-risk
+   piece; do it when the rest of the library is stable so regressions
+   are easy to spot.
+
+## Operating ground rules (carry over from the original brief)
+
+- **Scope:** `lib/minikanren/**` and the two plan files (this one and
+  the original).
+- **Commit cadence:** one feature per commit. Short factual messages
+  (`mk: piece B — bounds-consistency for fd-plus`).
+- **Plan updates:** tick boxes here as pieces land; mirror status in
+  `plans/minikanren-on-sx.md` Roadmap.
+- **Test discipline:** every commit ends with the cumulative count
+  green. No-regression rule from the original brief still applies.
+- **`sx-tree` MCP only** for `.sx` edits. `sx_validate` after every
+  structural edit.
+- **Pushing:** `origin/loops/minikanren` only. Never `main`. Squash to
+  `architecture` only with explicit user permission, as we did for
+  the v1 merge.