@@ -156,42 +156,96 @@ printer, hir_instr_c_verify, hir) have ZERO HirBuilder class-state
156156dependency, so they validate the algorithm-port + bridge-dissolution
157157pattern but NOT the harder Class A/B migration that Phase 4.C requires.
158158
159- ** Scope (1 commit, ~ 30-50 LOC ):**
159+ ** Scope (1 commit, ≤5 site-count Class A only ):**
160160- Pick the SIMPLEST Class A field for migration: recommend ` kwnames_ `
161161 (` Register* ` , mirrored to ` state_.kwnames ` , low call-site count).
162162 Rationale: it's a Pilot 5 dry-run on the cheapest field; failure
163163 surfaces structural problems (silent-drift, mutator-site enumeration
164164 gap, JIT_DCHECK equality drift) before the 1500 LOC sunk in 4.A is
165165 fully committed.
166- - Steps:
167- 1 . grep all ` kwnames_ ` C++ direct-access sites in builder.cpp.
168- 2 . Migrate each access to read/write ` state_.kwnames ` instead of the
166+ - Steps (single-commit-class fields, ≤5 direct member access sites):
167+ 1 . grep all ` <field>_ ` C++ direct-access sites in builder.cpp.
168+ 2 . Verify site count ≤5; otherwise this is a multi-commit-class field
169+ (see §4.A.5b), do NOT proceed under single-commit pattern.
170+ 3 . Migrate each access to read/write ` state_.<field> ` instead of the
169171 C++ duplicate field.
170- 3 . JIT_DCHECK on equality of ` state_.kwnames == kwnames_ ` at every
171- mutator site (until the C++ field is deleted).
172- 4 . Delete the C++ ` kwnames_ ` field. Re-grep returns zero references.
173- 5 . Run full Phase JIT test suite + ABBA + ARM64.
172+ 4 . Delete the C++ ` <field>_ ` field IN THE SAME COMMIT. No
173+ parallel-state interval = no equality DCHECK needed (deletion in
174+ same commit guarantees no drift surface).
175+ 5 . Re-grep returns zero references to bare ` <field>_ ` .
176+ 6 . Run full Phase JIT test suite + ABBA + ARM64.
174177
175178** Acceptance:** the 1-commit probe must pass the per-trajectory metric
176179(§5.0) AND introduce zero functional regressions. If any of:
177180- Mutator-site enumeration miss (a write site uses C++ field without
178181 state_ update — silent drift)
179- - JIT_DCHECK equality failure during migration
180182- ABBA regression
181183- ARM64 build failure or test divergence
182184...then PAUSE Phase 4.B + 4.C. Theologian re-spec the Class B-kept
183185migration approach before more pilots commit.
184186
185- ** Why kwnames_ specifically:** least call-site count among Class A
186- mirrored fields (sub-10 estimated; vs code_ at 46, current_func_ at
187- ~ 30, preloader_ at 28); pure setter/getter semantics (no
187+ ** Why kwnames_ specifically (per-2026-04-27 measured site counts):**
188+ sub-5 site count among Class A mirrored fields (kwnames_ : 1 direct
189+ read + 2 bridge sites = 3 sites total; vs code_ at 46, current_func_
190+ at ~ 30, preloader_ at 28); pure setter/getter semantics (no
188191container/lifecycle complexity). Failure modes are concentrated.
189192
190193** Why before 4.B:** §5.A close gate is LOC-trajectory only and won't
191194catch class-state failure modes. inliner.cpp (4.B medium-state) gates
192195on Pilot 3 (temps_ ) anyway, so the probe surface naturally precedes
1931964.B without re-sequencing.
194197
198+ ### 4.A.5b — DO NOT EXTRAPOLATE: kwnames_ -class vs code_ -class (per pythia #189 2026-04-27)
199+
200+ ** Acknowledgment** (per pythia #189 + supervisor 2026-04-27T10:13:10Z
201+ (a)): kwnames_ probe at c2f255e5c9 is the EASIEST-CASE migration; net
202+ +1 LOC, 1 read site, 2 bridge sites. Single-commit migration WORKS for
203+ this site-count class. ** Results DO NOT extrapolate** to high-site-
204+ count Class A fields where dependency density is qualitatively
205+ different. "The first thread pulled proves only that thread can be
206+ pulled." — pythia #189 .
207+
208+ ** Per-field complexity bracket (decision rule per supervisor (b))** :
209+
210+ | Site count | Migration mode | Equality DCHECK |
211+ | ---| ---| ---|
212+ | ** ≤5 sites** (kwnames_ -class) | Single-commit (delete C++ field in same commit) | Not needed (no parallel-state interval) |
213+ | ** 6-15 sites** (medium-class) | 2-3 commits (migrate accesses → verify → delete field) | REQUIRED on each commit until field is deleted |
214+ | ** >15 sites** (code_ -class: 46; current_func_ : 30; preloader_ : 28) | Multi-commit per-mutator-batch + JIT_DCHECK equality REQUIRED on every intermediate commit | REQUIRED + verified pre-deletion (zero failures across full test suite) |
215+
216+ ** JIT_DCHECK equality infra (per supervisor (c))** : for medium-class
217+ and code_ -class fields, the spec REQUIRES — not "moot" as in
218+ single-commit-class — `JIT_DCHECK(state_ .<field > == <field >_ , "drift
219+ detected at <site >")` at every mutator site during the migration
220+ window. The DCHECK is removed only when the C++ field is deleted (in
221+ the final commit of the per-field migration sequence).
222+
223+ ** Pre-Pilot-5 per-field site-count audit (per supervisor (d))** :
224+ BEFORE choosing migration mode for any Class A field, run:
225+ ```
226+ grep -cE '\b<field>_\b' Python/jit/hir/builder.cpp \
227+ | grep -vE '(state_\.|hir_builder_state_[a-z_]+_c?p?p?\(|^[[:space:]]*//)'
228+ ```
229+ Filter to direct-access sites only. Report site count + classify per
230+ the bracket above. Theologian patch-shape review verifies the chosen
231+ migration mode matches the site-count bracket.
232+
233+ ** Failure-mode predictions per bracket:**
234+ - ≤5 sites: silent-drift risk LOW (3-4 site enumeration is verifiable
235+ by inspection + grep). kwnames_ probe c2f255e5c9 demonstrates this.
236+ - 6-15 sites: silent-drift risk MEDIUM. JIT_DCHECK equality required.
237+ - > 15 sites: silent-drift risk HIGH. JIT_DCHECK equality + per-mutator
238+ batch migration + per-batch ABBA + per-batch ARM64 STRICT. code_ at
239+ 46 sites likely needs 4-6 batches; preloader_ at 28 likely needs
240+ 3-4 batches; current_func_ at 30 likely needs 3-4 batches. Each
241+ batch carries its own gate.
242+
243+ ** Spec authority** : this section (§4.A.5b) supersedes any inferred
244+ "single-commit migration is the new pattern" reading from the
245+ kwnames_ probe outcome. The pattern applies ONLY to ≤5-site-class
246+ fields. Pilot 5 in §4.C MUST classify per this bracket BEFORE
247+ authoring any migration commit.
248+
195249### 4.B — Medium-state HIR files
196250- ` inliner.cpp ` 704 LOC — uses HIRBuilder for inlineHIR; depends on
197251 Phase 4.C class-state migration partially landing
@@ -224,14 +278,32 @@ on Pilot 3 (temps_) anyway, so the probe surface naturally precedes
224278 - ** Bridge delete: 2** (push_cpp + pop_cpp)
225279 - ** Estimated cost:** 3-5 commits, 0.5 session
226280
227- - ** Pilot 5 (lockstep with 3+4):** delete the 5 Class A C++ duplicates
228- (` code_ ` , ` preloader_ ` , ` current_func_ ` , ` func_ ` , ` kwnames_ ` ). All
229- access goes through ` state_ ` exclusively. Removes the silent-drift
230- latent bug class.
231- - ** Estimated cost:** 5-8 commits per field × 5 = 25-40 commits, 3-4
232- sessions; each commit migrates 1 field across all C++ access sites
233- and verifies via grep + JIT_DCHECK + benchmark gate
234- - ** Subtotal Phase 4.C:** 33-53 commits, 4.5-5.5 sessions
281+ - ** Pilot 5 (lockstep with 3+4):** delete the 4 remaining Class A C++
282+ duplicates (` code_ ` , ` preloader_ ` , ` current_func_ ` , ` func_ ` ;
283+ ` kwnames_ ` already migrated by §4.A.5 probe c2f255e5c9). All access
284+ goes through ` state_ ` exclusively. Removes the silent-drift latent
285+ bug class.
286+ - ** Per-field complexity bracket (per §4.A.5b 2026-04-27):**
287+
288+ | Field | Site count (measured) | Migration mode | Estimated commits |
289+ | ---| ---| ---| ---|
290+ | ` func_ ` | TBD pre-Pilot-5 audit | per bracket | 1-3 |
291+ | ` current_func_ ` | ~ 30 (estimate) | code_ -class >15 multi-commit + JIT_DCHECK equality | 3-4 batches |
292+ | ` preloader_ ` | 28 (measured 2026-04-27) | code_ -class >15 multi-commit + JIT_DCHECK equality | 3-4 batches |
293+ | ` code_ ` | 46 (measured 2026-04-27) | code_ -class >15 multi-commit + JIT_DCHECK equality | 4-6 batches |
294+ - ** Pre-Pilot-5 mandatory step:** run the §4.A.5b per-field
295+ site-count audit grep on each remaining field. Theologian
296+ patch-shape review verifies migration-mode choice matches
297+ measured bracket BEFORE any per-field commits authored.
298+ - ** JIT_DCHECK equality infra REQUIRED** for all 4 remaining fields
299+ (each is >5-site-class). Removed only at final per-field deletion
300+ commit.
301+ - ** Estimated cost (revised per bracket):** ~ 13-19 commits across 4
302+ fields, 2-3 sessions. Lower than original 25-40 estimate because
303+ the bracket is more accurate than the prior uniform "5-8 per
304+ field × 5" estimate, and kwnames_ is already done.
305+ - ** Subtotal Phase 4.C (revised):** 21-32 commits (Pilot 3: 5-8 +
306+ Pilot 4: 3-5 + Pilot 5: 13-19), 3.5-4.5 sessions.
235307
236308### 4.D — Dispatch loop + builder.cpp shrinkage
237309- ` translate() ` dispatch loop conversion to C — the central method
0 commit comments