PrincetonUniversity / PsyNeuLink / 30393080566 / 1

84%

master: 84%

push

github

Add an internal _debugger execution hook (#3603)

# Add an internal `_debugger` execution hook

`psyneulink._debugger` — an opt-in hook to observe execution at
well-defined boundaries without monkey-patching. One global listener;
with none attached, `step()` is a single `is not None` check (zero cost,
zero behavior change). Fills the inert `assert 'DEBUGGING BREAK POINT:
...'` markers already present in the execution path. Internal API
(leading underscore); nothing opts in by default.

**Motivation:** it powers **PsyNeuView**'s enhanced run-stepping /
value-inspection UX — an external consumer the surface has already
stabilized against — so upstreaming lets any PsyNeuLink user attach a
debugger / tracer / visualizer without monkey-patching.

**Purely additive** except the `EXCEPTION` category (one `try/except`,
detailed below). Backward-compat is otherwise guaranteed by the existing
test matrix passing unchanged. **6 files, +603 / −24** on
`devel@fd4854b`.

```python
from psyneulink import _debugger

def listener(category, locals_provider):
    if category is _debugger.BreakpointCategory.NODE_EXECUTION:
        archive.snapshot(locals_provider())   # dict built only when consumed

_debugger.set_listener(listener)
composition.run(inputs)
_debugger.set_listener(None)
```

<details><summary><b>Design</b></summary>

- **Single listener**, not a multicast bus — consumers needing fan-out
wrap callables themselves. Assignment is atomic in CPython (set at
startup, clear at teardown), so no lock.
- **Lazy locals** — the per-category state dict is built only inside
`locals_provider()`, so a listener that ignores a category pays nothing.
- **Internal API** — the leading underscore is deliberate; the surface
may evolve until promoted to a public `psyneulink.debugger`.
</details>

<details><summary><b>Categories &amp; payloads</b></summary>

| Category | Locals keys | Fires at |
|---|---|---|
| `BEGINNING_OF_RUN` | scheduler, context, num_trials | start of
`Compos... (continued)

11514 of 14958 branches covered (76.98%)

Branch coverage included in aggregate %.

39115 of 45176 relevant lines covered (86.58%)

0.87 hits per line