docs: pythia python#104 + python#105 amendments to Tier 8 spec + CLAUDE.md

SonicField · SonicField · commit e8a83df48a9b · 2026-04-23T19:14:38.000-07:00
Bundle of two theologian-authored doc amendments per supervisor dispositions: CLAUDE.md (+2L) — Pre-Edit WT Integrity 'undiagnosed-recurring' honest framing per pythia python#105 (3) + supervisor 02:13:12Z + theologian 02:13:54Z. Acknowledges 5+ prior incidents closed at SYMPTOM layer without root-cause attribution; this 4-step discipline codifies reactive HALT, not automated detection. Detection still depends on agent noticing mid-edit. Recurrence-prevention claim does not exceed what text mechanizes; automated detection feasibility (file-watcher / git-hook) is fixup PIR territory and remains open. docs/tier8-class-b-cport-migrate-arm-spec.md (+93/-20) — pythia python#104 amendments per theologian 01:38:08Z + supervisor 01:38:26Z + 01:37:05Z: §1.1 container-shape transferability caveat (vector-pilot ≠ hash/ stack/allocator-shape pattern transferability) §5 python#11 NEW: bridge-count-delta acceptance (each pilot must NET- SUBTRACT bridges OR honestly add with W45 fixture coverage) §5 python#12 NEW: Phase B FORCING-FUNCTION (Tier 8 SECOND-PILOT block_map_ Step A BLOCKED until exception_table_ Phase B commit lands) Bundle scope: doc-only, no §3.5 BUILD MODE (no builder*.{cpp,h,c} touched). Atomic per supervisor 02:13:12Z + 01:38:26Z dispositions. Push 28 advances the Tier 8 Phase A resume deadline tracker per theologian 02:13:54Z + supervisor 02:13:12Z (push 28 OR session-end whichever first). If Alex disposition + fixup PIR not received by deadline, theologian amends Phase 3 closure summary fa8dfef to remove Tier 8 pilot citation + re-opens pythia python#103 escape question.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -158,3 +158,5 @@ Multi-file edit sequences (≥2 files) require working-tree integrity discipline
 4. **HALT response.** When integrity violation detected, restore to clean HEAD per gate-#3 prescription (librarian 01:46:19Z) + post observed-but-not-attributed report per don't-speculate-on-cause (generalist 01:24:43Z precedent). Surface trigger for supervisor disposition; do NOT auto-resume.
 
 Rationale: 5+ prior incidents (D-1775810621, D-1775669703, D-1776414469, D-1776434533, D-1776887480/D-1776890644) caused gate failures + false BUILD PASS + ARM64 build BLOCK. Per pythia #104 (3): gate #3 (HEAD==binary AND tree-clean during build) is REACTIVE; this discipline is PROACTIVE complement.
+
+**Honest framing per pythia #105 2026-04-24:** This is an UNDIAGNOSED-RECURRING class. The 5+ prior incidents closed at the SYMPTOM layer (build break, gate fail, Alex directive) without confirmed root-cause attribution. This 4-step discipline codifies a reactive HALT — it does not provide automated detection. Detection still depends on the agent noticing mid-edit (which generalist did at 01:23Z without the discipline). Recurrence-prevention claim does not exceed what this text mechanizes; automated detection (file-watcher / git-hook) feasibility is fixup PIR territory and remains open.
diff --git a/docs/tier8-class-b-cport-migrate-arm-spec.md b/docs/tier8-class-b-cport-migrate-arm-spec.md
@@ -28,6 +28,24 @@ ELIMINATED. Honest test of the keep-vs-migrate forcing-decision
 mechanism vs satisfying §5 by emptying the test set (per pythia #103
 critique).
 
+**AMENDMENT per pythia #104 2026-04-24 (container-shape transferability):**
+The `exception_table_` pilot validates ONLY the std::vector → typed-
+inline-array migration shape. Remaining 3 live Class B containers have
+DIFFERENT shapes that the vector-pilot does NOT predict transferability
+for:
+- `block_map_` is hash-shape (2× std::unordered_map) — needs hash-table
+  port, structurally different infra
+- `static_method_stack_` is stack-shape (jit::Stack<Register*> LIFO) —
+  needs stack port, different ops
+- `temps_` is allocator-shape (TempAllocator class with state) —
+  needs allocator port, fundamentally different from container
+
+Each remaining container requires its OWN pilot OR explicit
+re-validation per shape. Phase A success on `exception_table_` does
+not authorize 'pattern proven, do all 4'; full Tier 8 across all
+containers requires 4 separate pilot validations or a meta-spec
+demonstrating shape transferability.
+
 ### 1.2 Out-of-scope
 
 - Porting ALL 4 live Class B containers (multi-Tier-8 workstream;
@@ -94,16 +112,35 @@ Concrete migration shape:
    `findExceptionHandler` shims; HIRBuilder no longer touches
    exception_table_ at all (PhxHirBuilderState owns it pure-C).
 
-### 3.2 PhxArray prerequisite check
+### 3.2 Container infrastructure (corrected per Tier 8 Step A grep)
+
+Original spec assumed generic `PhxArray<T>` template existed; Step A
+grep verification (generalist 2026-04-24T01:11:34Z) found only:
+- `PhxPtrArray` (void*-only dynamic array; not POD-inline)
+- `PhxStateMap` (refcount-specific hash map; not generic)
+
+No generic `PhxArray<T>` template exists. Three options surfaced:
+
+(A) `PhxPtrArray` + per-entry malloc: reuses existing infra; heap
+    fragmentation + malloc overhead per access.
+(B) **NEW `PhxExceptionTable` typed inline-storage struct in
+    `builder_state_c.{h,c}`**: purpose-built; ~30L new C; no
+    fragmentation; sets pilot precedent for per-container custom
+    structs.
+(C) Defer pilot, file W47 generic `PhxArray<T>` template: bigger
+    blast radius; multi-session template-design workstream itself.
 
-Existing PhxArray usage (refcount_pass C-port) covers:
-- `PhxArray_push(arr, &elem)` — single-element push
-- `PhxArray_size(arr) → size_t`
-- `PhxArray_at(arr, i) → T*` (or equivalent index access)
+**ADOPTED: (B) per generalist 2026-04-24T01:11:34Z + theologian
+2026-04-24T01:12:14Z + supervisor TBD.** Pilot's job is validating
+that ONE Class B can be ported, not laying full Tier-8 infrastructure
+simultaneously. Per spec §1.2 out-of-scope ('not re-architecting
+PhxArray API beyond what pilot needs'), (C) is over-engineered.
 
-If `PhxArray<T>` template is generic enough for `ExceptionTableEntry`
-(POD struct), pilot uses existing API as-is. If gaps surface, file
-W47 PhxArray-extension spec before pilot Step 1.
+Post-pilot consideration: if (B) per-container custom struct (4
+containers = ~120L total infra) proves ugly across full Tier 8,
+W47 generic `PhxArray<T>` template SUPERSEDES via bulk refactor.
+(B) does not preclude (C); it sequences pilot first, generalization
+second.
 
 ---
 
@@ -164,18 +201,54 @@ Tier 8 pilot closure requires ALL:
    single bench <0.5x absolute).
 9. W45 §3.5 Fixture 3 amended to target C-side struct; still
    triggers build-fail.
-10. **Substantive C++-line burndown:** Phase 3 added +257L (B1-B6).
-    Tier 8 pilot must net-subtract enough that Phase 3+Tier-8
-    cumulative ≤ +0L (validates 'transitional foundation cost paid
-    back' framing, not 'permanent +257L scaffold').
-
-Estimated subtraction from pilot:
-- 4 bridge impl bodies (~80L total, builder.cpp/builder_state_c.c)
-- 4 bridge decls (~20L, builder_state_c.h)
-- C++ struct + field + 2 method shims (~50L, builder.h + builder.cpp)
-- Total estimate: ~-150L (could bring B1-B6 +257L closer to ~+107L
-  cumulative; full Tier-8 across all 4 Class B containers projects
-  net-negative)
+10. **Substantive C++-line burndown (LINE delta):** Phase 3 added
+    +257L (B1-B6). Pilot must net-subtract proportionally to its
+    container scope; cumulative ≤+0L is the FULL Tier-8 endpoint
+    (all 4 live Class B containers ported), NOT single-pilot
+    endpoint per theologian 2026-04-24T01:14:29Z amendment.
+
+    Estimated per-container subtraction:
+    - exception_table_ pilot ~-48L (~19% of Phase 3 +257L); pure-
+      C container infra cost (~+25L PhxExceptionTable) offsets some
+      bridge deletion (~-73L)
+    - block_map_ ~-50L (1 bridge + hash port)
+    - static_method_stack_ ~-30L (1 bridge + Stack port)
+    - temps_ ~-50L (1 bridge + alloc port)
+    - Full Tier 8 projection ~-180L cumulative; Phase 3+full-Tier 8
+      ~+77L; further surface elimination beyond Class B (HirBuilder
+      C++ class shim) needed for ≤+0L absolute.
+
+11. **Bridge-count delta acceptance (NEW per pythia #104 2026-04-24
+    + supervisor 01:37:05Z):** Each Tier 8 pilot must NET-SUBTRACT
+    bridges (or honestly add NEW bridges with W45 fixture coverage
+    same-commit). Closes 'Phase A adds helper bridges silently'
+    blind spot.
+
+    For exception_table_ pilot Phase A:
+    - Net bridge delta = -3 (delete push_cpp + size_cpp + entry_cpp;
+      keep find_exception_handler_c as algorithmic port)
+    - If Phase A adds ANY new helper bridges to port buildHIRImpl:1198
+      or emit_call_method_exception_handler_inline_c:2883, those
+      MUST appear in the same commit's W45 fixture set + bridge-count
+      delta becomes (-3 + new_count); spec acceptance requires net
+      negative
+    - W27a/W27b ZERO-new-bridge precedent (D-1776903189, D-1776904264)
+      is the structural target — pilot should not silently break it
+
+12. **Phase B FORCING-FUNCTION (NEW per pythia #104 + supervisor
+    01:37:05Z):** Tier 8 SECOND-PILOT (block_map_) Step A is
+    BLOCKED until exception_table_ Phase B commit lands. Phase B
+    deletes C++ findExceptionHandler + parseExceptionTable shims +
+    rewires builder.cpp:1198 + 2883 callers to PhxExceptionTable
+    direct.
+
+    Rationale: prevents 'Phase B never lands' keep-bias-one-layer-
+    deeper risk. Without forcing function, kept-shim-with-
+    PhxExceptionTable-internals replaces kept-vector — identical
+    retraction-debt shape with fresh _cpp surface stacked atop.
+    Block_map_ pilot represents the next opportunity to validate
+    migrate-arm; gating it on Phase B closure ensures no
+    half-migration accumulates.
 
 ---
 
