Visitar URL original
docs: phase4-hir-burndown-spec — §4.A.5 + §4.C Pilot 5 per pythia #189 · SonicField/cpython@64272bf · GitHub
Skip to content

Commit 64272bf

Browse files
committed
docs: phase4-hir-burndown-spec — §4.A.5 + §4.C Pilot 5 per pythia python#189
Closes the spec-extrapolation gap surfaced by pythia python#189 2026-04-27: kwnames_ probe (c2f255e, 1 LOC net) demonstrates single-commit class-state migration WORKS for low-site-count fields. It does NOT extrapolate to high-site-count fields (code_ at 46 sites, preloader_ at 28, current_func_ at ~30). 'The first thread pulled proves only that thread can be pulled.' Changes: §4.A.5 step 3 reframed: same-commit-deletion = no parallel-state interval = no equality DCHECK needed. ONLY for ≤5-site-class fields. §4.A.5b (NEW): explicit DO-NOT-EXTRAPOLATE acknowledgment + per-field complexity bracket (≤5/6-15/>15 sites → single/medium/multi-commit with JIT_DCHECK equality required for the latter two) + pre-Pilot-5 per-field site-count audit grep + failure-mode predictions per bracket. §4.C Pilot 5: per-field bracket with measured site counts, mandatory pre-audit step, JIT_DCHECK equality REQUIRED for all 4 remaining fields (each is >5-site-class). Estimate revised from 25-40 commits uniform to 13-19 commits per measured bracket. Authored 2026-04-27 per pythia python#189 + supervisor 2026-04-27T10:13:10Z (a)+(b)+(c)+(d) framing + theologian §4.C per-field bracket addition.
1 parent c2f255e commit 64272bf

1 file changed

Lines changed: 92 additions & 20 deletions

File tree

‎docs/phase4-hir-burndown-spec.md‎

Lines changed: 92 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -156,42 +156,96 @@ printer, hir_instr_c_verify, hir) have ZERO HirBuilder class-state
156156
dependency, so they validate the algorithm-port + bridge-dissolution
157157
pattern 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
183185
migration 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
188191
container/lifecycle complexity). Failure modes are concentrated.
189192

190193
**Why before 4.B:** §5.A close gate is LOC-trajectory only and won't
191194
catch class-state failure modes. inliner.cpp (4.B medium-state) gates
192195
on Pilot 3 (temps_) anyway, so the probe surface naturally precedes
193196
4.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

Comments
 (0)