---
model: accounts/fireworks/routers/kimi-k2p5-turbo
---

# Plan: `ask262Debug` Module for engine262

## Overview

Runtime execution tracker that records which ECMAScript spec sections are entered during execution. The Babel transform auto-injects `ask262Debug.mark()` at the start of every function body with URL comments — developer writes nothing. All metadata (sectionId, file, line) resolved at build time.

**Primary Use Case:** AI analysis of execution flow mapped to ECMAScript spec sections for understanding JavaScript engine behavior.

## Files to Change

| File | Action |
|------|--------|
| `engine262/src/ask262-debug.mts` | **CREATE** — the module with deduplication logic |
| `engine262/src/index.mts` | **MODIFY** — add named re-export |
| `engine262/scripts/transform.mts` | **MODIFY** — auto-inject `mark()` and import |
| `engine262/scripts/verify-ask262-debug.mts` | **CREATE** — post-build verification script |

## 1. `scripts/transform.mts` — Enhance the Babel Plugin

### 1a. Extend State Interface

Add `ask262Debug` to the `NeededNames` type and extend `State` interface:

```typescript
type NeededNames = 'Completion' | 'AbruptCompletion' | 'Assert' | 'Call' | 
                   'IteratorClose' | 'AsyncIteratorClose' | 'Value' | 
                   'skipDebugger' | 'ask262Debug';  // NEW

interface State extends PluginPass {
  needed: Partial<Record<NeededNames, boolean>>;
  fileRelativePath?: string;  // NEW: captured at Program enter
}
```

### 1b. Add Import Creator Function

Add alongside existing `createImport*` functions:

```typescript
function createImportAsk262Debug() {
  return template.ast(`
    import { ask262Debug } from "#self";
  `);
}
```

### 1c. Refactor `addSectionFromComments`

The current function (lines 101-133) handles only single URLs. Update to capture multiple section IDs and inject `mark()`:

```typescript
function addSectionFromComments(
  path: NodePath<t.FunctionDeclaration> | NodePath<t.VariableDeclaration> | 
        NodePath<t.ExportNamedDeclaration> | NodePath<t.ClassMethod> | NodePath<t.ObjectMethod>,
  state: State,
  getName: () => string,
  getBody: () => t.BlockStatement | null
) {
  if (!path.node.leadingComments) return;

  const sectionIds: string[] = [];
  let url = '';
  
  for (const c of path.node.leadingComments) {
    for (const line of c.value.split('\n')) {
      const matches = line.match(/#(sec-[a-zA-Z0-9._%-]+)/g);
      if (matches) {
        sectionIds.push(...matches.map(m => m.substring(1)));
        if (!url) {
          const section = line.split(' ').find(l => l.includes('#sec'));
          // Only capture external URLs (skip local/fragment references)
          if (section?.startsWith('https://')) {
            url = section;
          }
        }
      }
    }
  }
  
  if (sectionIds.length === 0) return;

  const name = getName();
  
  // 1. Keep existing .section (backward compat) - uses first URL
  // Only applies to named functions
  if (name && url) {
    path.insertAfter(template.ast(`${name}.section = '${url}';`));
  }

  // 2. Get function body via callback (node-type check done by caller)
  const body = getBody();

  // 3. Inject mark() at start of function body (only for block bodies)
  if (body?.type === 'BlockStatement') {
    const line = path.node.loc?.start.line ?? 0;
    const markCall = template.statement(
      `ask262Debug.mark(${JSON.stringify(sectionIds)}, ${JSON.stringify(state.fileRelativePath)}, ${line});`
    )();
    body.body.unshift(markCall);
    state.needed.ask262Debug = true;
  }
}
```

### 1d. Update Visitors

Update existing visitors to use new `addSectionFromComments` signature, and add new visitors for ClassMethod and ObjectMethod:

```typescript
return {
  visitor: {
    Program: {
      enter(path, state) {
        state.needed = {};
        // Capture relative file path from state.filename
        const absolutePath = state.filename || '';
        state.fileRelativePath = absolutePath.replace(/.*\/(src\/)/, '$1').replace(/\.mts$/, '.mts') || 'unknown.mts';
      },
      exit(path, state) {
        // ... existing imports (skipDebugger, Completion, etc.) ...
        // NEW: Add ask262Debug import if needed
        if (state.needed.ask262Debug) {
          path.unshiftContainer('body', createImportAsk262Debug());
        }
      },
    },
    FunctionDeclaration(path, state) {
      addSectionFromComments(
        path, state,
        () => path.node.id!.name,
        () => path.node.body
      );
    },
    VariableDeclaration(path, state) {
      const init = path.get('declarations.0.init');
      if (init.isFunctionExpression()) {
        const id = path.node.declarations[0].id as t.Identifier;
        addSectionFromComments(
          path, state,
          () => id.name,
          () => init.node.body
        );
      } else if (init.isArrowFunctionExpression()) {
        const id = path.node.declarations[0].id as t.Identifier;
        addSectionFromComments(
          path, state,
          () => id.name,
          () => init.node.body.type === 'BlockStatement' ? init.node.body : null
        );
      }
    },
    ExportNamedDeclaration(path, state) {
      const declaration = path.node.declaration;
      if (declaration?.type === 'FunctionDeclaration') {
        addSectionFromComments(
          path, state,
          () => declaration.id!.name,
          () => declaration.body
        );
      }
    },
    // NEW: Add ClassMethod visitor
    ClassMethod(path, state) {
      const key = path.node.key;
      if (key.type === 'Identifier') {
        addSectionFromComments(
          path, state,
          () => key.name,
          () => path.node.body
        );
      }
    },
    // NEW: Add ObjectMethod visitor
    ObjectMethod(path, state) {
      const key = path.node.key;
      if (key.type === 'Identifier') {
        addSectionFromComments(
          path, state,
          () => key.name,
          () => path.node.body
        );
      }
    },
    // ... rest of existing visitors (CallExpression, ThrowStatement, etc.) unchanged
  },
};
```

### 1e. Arrow Function Special Handling

The updated `addSectionFromComments` handles this automatically:
- Arrow with block body `() => { ... }`: `.section` + `mark()` injected
- Arrow with expression body `() => expr`: `.section` only, no `mark()`

## 2. `engine262/src/index.mts` — Add Named Re-export

Add the re-export alongside existing exports (around line 20):

```typescript
// Add to existing exports from './helpers.mts' or create new export section
export { ask262Debug, type MarkData } from './ask262-debug.mts';
```

## 3. `engine262/src/ask262-debug.mts` — The Module

Deduplicated data collection. No stack parsing, no `node:` imports, no decorators.

```typescript
export interface MarkData {
  readonly sectionIds: string[];
  readonly fileRelativePath: string;
  readonly lineNumber: number;
  readonly important: boolean;
}

interface MarkKey {
  readonly sectionIds: string;
  readonly file: string;
  readonly line: number;
}

class Ask262Debug {
  marks: MarkData[] = [];
  private _importantStack = false;
  private _markIndex = new Map<string, number>(); // key -> index in marks

  private _makeKey(sectionIds: string[], file: string, line: number): string {
    return `${sectionIds.join(',')}|${file}|${line}`;
  }

  mark(sectionIds: string[], file: string, line: number) {
    const key = this._makeKey(sectionIds, file, line);
    const existingIndex = this._markIndex.get(key);
    
    if (existingIndex !== undefined) {
      // Merge important flag
      const existing = this.marks[existingIndex];
      if (this._importantStack && !existing.important) {
        (this.marks[existingIndex] as any).important = true;
      }
      return;
    }
    
    const newMark: MarkData = {
      sectionIds: [...sectionIds], // defensive copy
      fileRelativePath: file,
      lineNumber: line,
      important: this._importantStack,
    };
    
    this._markIndex.set(key, this.marks.length);
    this.marks.push(newMark);
  }

  startImportant() {
    this._importantStack = true;
  }

  stopImportant() {
    this._importantStack = false;
  }
}

export const ask262Debug = new Ask262Debug();
```

### Key Behaviors

| Scenario | Behavior |
|----------|----------|
| Duplicate `(sectionIds, file, line)` | Keep one entry, merge `important` flags (OR logic) |
| Generator resumption | Mark on every `.next()` call (may create duplicates if same location) |
| Nested functions | Each entry adds its mark (chronological trace) |

## 4. `engine262/scripts/verify-ask262-debug.mts` — Verification Script

```typescript
#!/usr/bin/env node
import { ask262Debug, Agent, ManagedRealm } from '#self';

console.log('=== ask262Debug Verification ===\n');

// 1. Check export exists
console.log('1. Checking export...');
if (!ask262Debug) {
  console.error('FAIL: ask262Debug not exported');
  process.exit(1);
}
console.log('   ✓ ask262Debug exported\n');

// 2. Run code that hits known spec sections
console.log('2. Executing test code...');
const agent = new Agent();
const realm = new ManagedRealm({ agent });

realm.evaluateScript(`
  // Array.prototype.every - should hit sec-array.prototype.every
  [1, 2, 3].every(x => x > 0);
  
  // Proxy creation - should hit sec-proxycreate or similar
  new Proxy({}, {});
`);

// 4. Verify marks were captured
console.log('3. Checking marks...');
const marks = ask262Debug.marks;
console.log(`   Captured ${marks.length} unique marks\n`);

if (marks.length === 0) {
  console.error('FAIL: No marks captured');
  process.exit(1);
}

// 5. Show sample marks
console.log('4. Sample marks:');
marks.slice(0, 5).forEach((m, i) => {
  console.log(`   [${i}] ${m.sectionIds.join(', ')} @ ${m.fileRelativePath}:${m.lineNumber}${m.important ? ' [important]' : ''}`);
});

console.log('=== All Checks Passed ===');
```

## Key Design Decisions Summary

| Decision | Choice | Rationale |
|----------|--------|-----------|
| **Use case** | AI execution flow analysis | Map runtime to spec sections |
| **Import pattern** | `import { ask262Debug } from '#self'` | Uses existing pattern (315+ occurrences) |
| **Bundle strategy** | Included in engine262.mjs | Single artifact, no config changes needed |
| **Data structure** | Deduplicated array | Chronological trace with unique entries only |
| **Deduplication key** | `(sectionIds, file, line)` | Same location = same semantic entry |
| **Duplicate handling** | Merge `important` flags (OR) | If any call was important, mark it important |
| **All metadata** | From transform (build time) | No runtime stack parsing, no `node:` imports |
| **`mark()` injection** | Auto-injected at start of block body | Developer writes nothing |
| **Arrow functions** | Block body: `.section` + `mark()`, Expression: `.section` only | Can't inject statement in expression |
| **Multi-section** | Array of section IDs per function | Functions can implement multiple spec sections |
| **`.section`** | Kept (backward compat) | Used by test262-intrinsics |
| **Generators** | Mark on every `.next()` | Simpler, deduplication handles repeats |
| **Nested functions** | Mark all | Chronological trace for AI analysis |
| **`important`** | User-driven `startImportant()`/`stopImportant()` | Manual annotation of interesting sections |
| **Function types** | FunctionDeclaration + ClassMethod + ObjectMethod + VariableDeclaration | Covers all URL comment patterns |
| **Class/Object method keys** | Identifier names only | Simple, covers 99% of cases |
| **File paths** | Relative to `engine262/src/`, `.mts` extension | Maps to source, not compiled output |
| **Line numbers** | 1-indexed from Babel AST | Matches source file line numbers |

## Implementation Checklist

1. [ ] **Create** `engine262/src/ask262-debug.mts` with the module code
2. [ ] **Modify** `engine262/src/index.mts` - add re-export
3. [ ] **Modify** `engine262/scripts/transform.mts`:
   - [ ] Add `ask262Debug` to `NeededNames` type
   - [ ] Extend `State` interface with `fileRelativePath`
   - [ ] Add `createImportAsk262Debug()` function
   - [ ] Update `addSectionFromComments()` signature and logic
   - [ ] Update `Program.exit` to inject ask262Debug import
   - [ ] Update `FunctionDeclaration` visitor
   - [ ] Update `VariableDeclaration` visitor  
   - [ ] Update `ExportNamedDeclaration` visitor
   - [ ] Add `ClassMethod` visitor
   - [ ] Add `ObjectMethod` visitor
4. [ ] **Create** `engine262/scripts/verify-ask262-debug.mts`
5. [ ] **Type checking**: `cd engine262 && npx tsc -b .`
6. [ ] **Linting**: `cd engine262 && npm run lint`
7. [ ] **Build**: `cd engine262 && npm run build:engine`
8. [ ] **Verification**: `cd engine262 && node --enable-source-maps --disable-warning=ExperimentalWarning --experimental-strip-types scripts/verify-ask262-debug.mts`

## Expected Output from Verification

```
=== ask262Debug Verification ===

1. Checking export...
   ✓ ask262Debug exported

2. Executing test code...
3. Checking marks...
   Captured 47 unique marks

4. Sample marks:
   [0] sec-array.prototype.every @ intrinsics/ArrayPrototypeShared.mts:173
   [1] sec-proxycreate @ abstract-ops/proxy-objects.mts:540
   ...

=== All Checks Passed ===
```

## Troubleshooting

### Issue: No marks captured after build
**Cause:** Transform not injecting `mark()` calls
**Fix:** Check that functions have URL comments with `#sec-` patterns

### Issue: Build fails with "Cannot find module '#self'"
**Cause:** Rollup not resolving the import
**Fix:** Ensure babel transform runs before resolution in rollup config

### Issue: Line numbers are off
**Cause:** Babel source maps not configured
**Fix:** Check that `sourceMap: true` in babelOptions and `loc` is preserved

### Issue: Duplicate marks for same function
**Cause:** Generator resumption or recursion
**Fix:** This is expected behavior - deduplication happens on `(sectionIds, file, line)`