U2 (D-RU-2): let-bound planes over the contract set algebra

.claude/board/STATUS_BOARD.md

@@ -6,7 +6,7 @@ Plan: `.claude/plans/d-relalg-unified-v1.md`. Decisions recorded there: ADMISSIO
 |---|---|---|---|
 | **D-RU-0** | decisions: ADMISSION = B, D-RA-2 = A | DECIDED (operator, 2026-10-20) | — |
 | **D-RU-1** | U1: JC statistical batch, distinct (selection, key, lane pair) triples over shared power-sum terminals | MEASURED (`crates/jc-batch-probe`; `entries/2026-10-20-u1-jc-batch.md`): 252 requests → 2 selection + 42 cross passes; at 1M rows 6.4× faster, 11.5× fewer rows traversed, 8.5× fewer values read, 126× fewer mask bytes; bit-identical to per-request; no R reference (R absent) | rows traversed and terminal passes below the per-request baseline; results bit-exact on integer lanes; overflow refused, not wrapped; R references |
-| **D-RU-2** | U2: `let`-bound planes on the contract IR, immutable `Plane(i)`, versioned coordinates, no DAG inside a fold | Queued (after D-CMR-1) | rows traversed and planes materialized against recompute; width test ≤ 3 slots; answers and versions unchanged |
+| **D-RU-2** | U2: `let`-bound planes on the contract IR, immutable `Plane(i)`, versioned coordinates, no DAG inside a fold | MEASURED (`contract::set_program`, `relalg::program`; `entries/2026-10-21-u2-let-planes.md`): 16 queries sharing one conjunction at 1M rows: 3.1× faster, 14 vs 59 lane reads, 2 planes (250 kB) materialized, ≤ 2 scratch slots; answers equal recompute and a row oracle; other versions refused | rows traversed and planes materialized against recompute; width test ≤ 3 slots; answers and versions unchanged |
 | **D-RU-3** | cross-rule CSE in crepe-plan-probe (256-rule benchmark, separate from the hop benchmark) | Queued (after D-RU-2) | answers == crepe and ascent; traversals and materializations measured |
 | **D-RU-4** | co-addressed join operator over `JoinDomain` | Queued (after D-RU-2) | parity with the star path; no position taken from another table's values |
 | **D-RU-5** | Quack physical pins (dense vs sorted, materialize vs recompute) | Queued (after D-RU-3/4) | can-fire and can-stay-silent per pin |

.claude/board/entries/2026-10-21-u2-let-planes.md

@@ -0,0 +1,66 @@
+# 2026-10-21 — D-RU-2 (U2): let-bound planes over the contract set algebra
+
+**Status:** MEASURED (lab; `crates/lance-graph-contract/src/set_program.rs`, `crates/lance-graph-relalg/src/program.rs`). Plan: `.claude/plans/d-relalg-unified-v1.md`, stage table (U2). Builds on D-CMR-1 (`lance_graph_contract::set_algebra`, #1644).
+
+## What landed
+
+- `set_program::SetProgram { version, resident, lets, queries }`.
+  - `Sym(i)` with `i < resident` is a resident plane.
+  - `Sym(resident + k)` is `lets[k]`.
+  - A let may read only earlier lets; queries may read any let.
+  - `validate()` refuses forward and unknown references.
+  - A program describes one table version.
+- `set_program::share(version, resident, queries)` lifts a junction subset into a let when two or more junctions of the same kind hold it. Rules:
+  - largest subset first;
+  - judged after `normalize`, because `normalize` flattens nested junctions, so identical subtrees rarely survive whole;
+  - lets are ordered by dependency and renumbered densely.
+- `relalg::run_program`:
+  - evaluates each let once into a scratch plane of `n_rows / 8` bytes;
+  - runs every query over the resident planes plus those planes;
+  - a let's plane is one more resident plane, so every fold stays a tree.
+- `relalg::run_recompute` is the baseline: each query with its lets inlined.
+- Both refuse:
+  - a program for another version (`VersionMismatch`);
+  - a malformed program (`Shape`);
+  - the wrong number of resident planes;
+  - a measure count that does not match the queries.
+- `ProgramCost` counts, from the folds that ran: programs, ops, lane reads, plane reads, planes materialized and their bytes, and the most scratch slots one fold used.
+
+## Measured
+
+`examples/program_bench`, release build: 16 queries that share one three-comparison conjunction; one of every three also reads a resident plane. Medians of 9 runs on 4 cores, load below 1.
+
+| rows | program ms | recompute ms | time | lane reads | ops | materialized |
+|---|---|---|---|---|---|---|
+| 100,000 | 0.35 | 1.15 | 3.3× | 14 vs 59 | 15 vs 59 | 2 planes, 25 kB |
+| 1,000,000 | 4.77 | 14.87 | 3.1× | 14 vs 59 | 15 vs 59 | 2 planes, 250 kB |
+| 4,000,000 | 20.98 | 69.35 | 3.3× | 14 vs 59 | 15 vs 59 | 2 planes, 1 MB |
+
+- The lane-read count is the row-traversal count: each comparison reads one whole lane of `n_rows` values.
+- The program runs 18 mask-risc programs against 16 for recompute: one per let more, each a whole pass.
+- With 4 queries, the program reads 6 lanes against 15 and is 2.1× faster at 1M rows.
+- Both paths use at most 2 scratch slots per fold, inside the ≤ 3 target.
+
+**Correctness.**
+- Three paths agree on every answer (count, sum, min, max) and on every kept mask: the program, recompute, and a row-at-a-time oracle over the inlined descriptions.
+- Fixtures: hand-built sets with one shared conjunction; with nested and distinct lets; with nothing shared; and 60 generated sets.
+- With nothing shared, the program's cost equals recompute's exactly.
+- Versions: a program built for version 7 is refused against version 8.
+
+**Disables.** Eight, all red-then-green:
+- wrong let evaluated;
+- lets cannot read earlier lets;
+- version check removed;
+- `validate` removed;
+- resident-count check removed;
+- lane reads not counted;
+- bytes not counted;
+- `share` lifts nothing.
+
+The first and second were green at first: no fixture held a program with more than one let. `nested_and_distinct_lets_agree_with_recompute_and_the_oracle` closes that.
+
+## Open
+
+- `share` is greedy (largest subset first). It does not weigh a let's materialization cost against the reads it saves. A subset held by two junctions is lifted even when its comparisons are cheaper than the extra pass. Measured here only where sharing wins.
+- The ops count includes the let passes. Total cost is bounded by time, which is measured; there is no byte-level traffic counter.
+- U3 (cross-rule CSE in crepe-plan-probe) and U4 (join over `JoinDomain`) are unblocked.

.claude/board/entries/README.md

@@ -25,10 +25,11 @@ index row, (3) no duplicate entry id. Checks 1 and 2 are deliberately
 opposite directions; the stranding this convention prevents shows up in
 exactly one of them, never both.
 
-401 entries, 2026-08-06 .. 2026-10-21.
+402 entries, 2026-08-06 .. 2026-10-21.
 
 | date | entry id | finding | file |
 |---|---|---|---|
+| 2026-10-21 | `D-RU-2` |  | [2026-10-21-u2-let-planes.md](2026-10-21-u2-let-planes.md) |
 | 2026-10-21 | `D-RU-6-LAB-1` |  | [2026-10-21-d-ru-6-tile-walk-probe.md](2026-10-21-d-ru-6-tile-walk-probe.md) |
 | 2026-10-21 | `D-RU-6-LAB-2` |  | [2026-10-21-d-ru-6-sparse-compute.md](2026-10-21-d-ru-6-sparse-compute.md) |
 | 2026-10-21 | `D-CMR-5` |  | [2026-10-21-d-cmr-5-rescope.md](2026-10-21-d-cmr-5-rescope.md) |

.claude/plans/d-relalg-unified-v1.md

@@ -298,4 +298,4 @@ One workload, run under three toggles. Each toggle changes one mechanism only.
 | U7 | prefetch and staging of Arm B ranges | U6 or a non-recursive multi-stage plan | critical-path overlap measured; bytes read unchanged |
 | U8 | Wikidata and SAP-shaped fixtures; completeness refusals | U6, U7 | refusal tests; witness carried end to end |
 
-U1 needs nothing new and comes first. **U1 MEASURED (2026-10-20, `crates/jc-batch-probe`, `entries/2026-10-20-u1-jc-batch.md`):** 252 requests reduce to 2 selection and 42 cross passes; at 1M rows the batch is 6.4× faster with 11.5× fewer rows traversed, 8.5× fewer values read and 126× fewer mask bytes, and its answers equal the per-request answers bit for bit. The R reference is replaced by JC's slice functions because R is not installed. U2 builds on D-CMR-1. Both are accepted only on measured row traversals, materializations and total cost (§ Decisions), not on operator counts.
+U1 needs nothing new and comes first. **U1 MEASURED (2026-10-20, `crates/jc-batch-probe`, `entries/2026-10-20-u1-jc-batch.md`):** 252 requests reduce to 2 selection and 42 cross passes; at 1M rows the batch is 6.4× faster with 11.5× fewer rows traversed, 8.5× fewer values read and 126× fewer mask bytes, and its answers equal the per-request answers bit for bit. The R reference is replaced by JC's slice functions because R is not installed. **U2 MEASURED (2026-10-21, `contract::set_program` + `relalg::program`, `entries/2026-10-21-u2-let-planes.md`):** each shared junction subset is evaluated once into a scratch plane; for 16 queries sharing one conjunction at 1M rows the program is 3.1× faster than recompute and reads 14 lanes instead of 59, at the cost of 2 materialized planes (250 kB). Answers equal recompute and a row oracle, and a program for another version is refused. Both are accepted only on measured row traversals, materializations and total cost (§ Decisions), not on operator counts.

.github/workflows/crepe-plan-probe.yml

@@ -71,3 +71,6 @@ jobs:
           cargo fmt --check
           cargo test
           cargo clippy --all-targets -- -D warnings
+          # D-RU-2 benchmark smoke run; an n that is not a multiple of 64
+          # exercises the plane tail.
+          BENCH_N=100003 BENCH_REPS=1 cargo run --example program_bench

crates/lance-graph-contract/src/lib.rs

@@ -191,6 +191,9 @@ pub mod scheduler;
 pub mod selection;
 pub mod sensorium;
 pub mod set_algebra;
+/// D-RU-2 / U2: a batch of selections whose shared parts are named once
+/// (`lets` over `set_algebra::SetExpr::Sym`). See module docs.
+pub mod set_program;
 pub mod settlement;
 /// D-BLW-5 payload-law DTO (`ShapeRankPayload`, `RemeasureKey`, `RemeasureLedger`) —
 /// distribution shape × Prozentrang, never the raw statistic. See module docs.