aid-dap-real-debugpy-fixture

Files (1)

• SKILL.md

SKILL.md (first lines)

# DAP Real Debugpy Fixture — VERIFIED Wire-In Recipe

## Status: VERIFIED GREEN (2026-09-03)

`tests/arch/dap-contract.test.ts` — **9/9 tests pass in 8.5s** with the fixture described below. The real debugpy round-trip (`real debugpy adapter round trip on the fizz_engine fixture`) passes in 3.0s against debugpy 1.8.21 on Windows.

## What this skill is

The AIDE arch build has a real-DAP test at `tests/arch/dap-contract.test.ts:326` and a daemon-level fixture test at `daemon/test-dap-fixture.mjs` that read a Python debuggee from `fixtures/debuggee/fizz_engine.py` and run it through debugpy. The fixture was missing. This skill encodes the **exact verified content** of that fixture, the failure modes that cost cycles, the PID marker required for the daemon orphan check, and the wire-in path so both tests stay green.

Primary sources (verified 2026-09-03):
- DAP spec: `https://microsoft.github.io/debug-adapter-protocol/specification`
- DAP overview: `https://microsoft.github.io/debug-adapter-protocol/overview`
- debugpy README: `https://github.com/microsoft/debugpy`
- debugpy quirks: verified via direct probe of debugpy 1.8.21 on this machine (see `aide-arch-protocols` field notes)

## The exact file the test needs (VERIFIED)

**Path**: `E:\aide-sovereign-workbench\fixtures\debuggee\fizz_engine.py`

**The test at line 348 reads:**
```ts
const source = await fs.readFile(path.join(repoRoot, 'fixtures', 'debuggee', 'fizz_engine.py'), 'utf8');
```

**The test resolves the breakpoint lines from markers (line 351-355):**
```ts
const lines = source.split('\n');
const lineOf = (marker: string): number => lines.findIndex(line => line.includes(marker)) + 1;
const first = lineOf('total = sum');
const second = lineOf('print(report)');
assert.ok(first > 0 && second > 0, 'fixture markers must resolve');
```

**`lineOf` uses `.includes()` (SUBSTRING match) and `findIndex` returns the FIRST match.** This is the root cause of 3 of the 5 failure modes below — the docstring, the list-of-dicts, and the comprehension all matched BEFORE the intended code line.

## The VERIFIED fixture content (copy verbatim, 9/9 pass)

```python
#!/usr/bin/env python3

import os
from pathlib import Path


def main():
    Path(__file__).with_name('debuggee.pid').write_text(str(os.getpid()), encoding='ascii')
    engine = build_engine()
    values = [int(x) for x in engine['items'] if x.isdigit()]
    total = sum(values)
    report = {'total': total, 'count': len(engine['items'])}
    print(report)


def build_engine():
    items = [
        '1', '2', 'Fizz', '4', 'Buzz',
        'Fizz', '7', '8', 'Fizz', 'Buzz',
        '11', '10'
    ]
    return {'items': items}


if __name__ == '__main__':
    main()
```

## Why this exact content passes 9/9 (line-by-line against the test)

- **Line 7** `def main():` — entry point. `frame[0]?.name === 'main'` (test line 370) ✓
- **Line 11** `total = sum(values)` — contains the marker `total = sum` (test line 353), is a **simple assignment with no comprehension on the same line** (critical for `next` to report `reason: 'step'` not `'breakpoint'` per debugpy quirk #5 below), is **inside `main()`** (so the frame is `main` not a helper). ✓
- **Line 13** `print(report)` — contains the marker `print(report)` (test line 354), is inside `main()`. ✓
- **The PID marker is written before the first breakpoint** — `daemon/test-dap-fixture.mjs` reads `fixtures/debuggee/debuggee.pid` after disconnect and verifies that PID is no longer alive. ✓
- **No docstring** with the markers (critical — the docstring caused failure mode #1 below).
- **`items` is a flat list of strings** (critical — list-of-dicts caused failure mode #2 below).
- **`items[2]` is `'Fizz'`** (0-based, 3rd item) — test asserts `vars3.some(v => v.name === '02' && v.value === "'Fizz'")` (line 385). ✓
- **Digit-only sum = 1+2+4+7+8+11+10 = 43** — test asserts `total?.value === '43'` (line 404). ✓
- **Standalone run**: `py -3.10 -E <path>` → stdout: `{'total': 43, 'count': 12}` and writes a sibling `debuggee.pid`. Exit 0. ✓

## The 5 failure modes I hit (and how to fix each)

| # | Error message | Root cause | Fix |
|---|---|---|---|
| 1 | `'<module>' !== 'main'` (test line 370) | Docstring at lines 5-6 contained the literal text `total = sum` and `print(report)`. `lineOf` matched the docstring FIRST (line 5/6) not the code (line 22/24). debugpy stopped at the docstring (module level) not inside `main()`. | Remove the docstring OR rewrite it to not contain the markers. The verified fixture has NO docstring. |
| 2 | `'items[2] = Fizz' at depth 3` (test line 385) | `items` was a list of dicts: `[{"name":"1","score":4}, ...]`. `items[2]` was `{"name":"Fizz","score":5}` — a DICT, not the string `'Fizz'`. The test expects a flat list of strings. | Change `items` to a flat list of strings where index 2 is `'Fizz'`. |
| 3 | `'breakpoint' !== 'step'` (test line 390) | `total = sum(int(x) for x in engine['items'] if x.isdigit())` had a generator expression on the same line as the breakpoint. Per debugpy quirk: when a `next` lands in a comprehension frame on the same physical line as a breakpoint, the `stopped` reason is `breakpoint` not `step`. | Split the comprehension into a separate line: `values = [int(x) for x in engine['items'] if x.isdigit()]` then `total = sum(values)`. The breakpoint on `total = sum(values)` is now a simple assignment. |
| 4 | `'compute_total' !== 'main'` (test line 370) | I moved `total = sum(values)` into a helper function `compute_total()`. debugpy stopped inside the helper, so the frame was `compute_total` not `main`. | Keep `total = sum(values)` inside `main()`, not a helper. The test expects `frame[0]?.name === 'main'`. |
| 5 | `'Channel was closed before the response'` (debugpy stderr) | My direct probe killed the child process's stdin before debugpy could respond. NOT a fixture bug — a probe-script bug. | When probing debugpy manually, give it 5-10 seconds to respond before killing. |
| 6 | `pid file check failed: ENOENT` (daemon test line 206) | The daemon-level battery launches the repository fixture directly and requires a PID marker to verify the debuggee was reaped; the original arch-only recipe did not write one. | Keep the `Path(__file__).with_name('debuggee.pid').write_text(...)` line before the first breakpoint. Do not weaken or remove the orphan assertion. |

## The DAP lifecycle the DapManager must enforce (port from aide-arch-protocols)

```
client:start(id)
  → spawn python -m debugpy.adapter   (stdio: pipe, cwd=workspace, shell:false)
  → decoder listens on stdout

client:initialize(id)
  → request: { command: 'initialize', arguments: { adapterID: 'aide', ... } }
  → response.body stored as capabilities
  → wait for 'initialized' EVENT (this comes during launch, not before)

client:launch(id, program, args, cwd)
  → fire-and-forget request: { command: 'launch', arguments: { program, args, cwd, type: 'python' } }
  → DO NOT await the response — debugpy defers it until configurationDone
  → store the launch promise for later await

client:setBreakpoints(id, source, lines)
  → request: { command: 'setBreakpoints', arguments: { source: { path }, breakpoints: [{line}] } }
  → MUST be before launch response resolves

client:configure(id)
  → request: { command: 'configurationDone' }
  → debugpy now sends the launch response

client: await launch → stopped(reason: 'breakpoint', threadId)
  → threads → stackTrace → scopes → variables (nested by variablesReference)
  → continue/next/stepIn/stepOut with threadId from stopped event

From AnonymousNomad/covert-coder, Apache-2.0.

More from AnonymousNomad/covert-coder