Epic: source debugging for SharpTS interpreter mode via DAP

## Goal

Deliver first-class source debugging for SharpTS **interpreter mode** through a standards-based Debug Adapter Protocol (DAP) implementation, if and only if interpreter-debugging demand justifies a separate debugger product.

This is intentionally separate from #1306 and from compiled-mode portable-PDB debugging. A managed debugger cannot control the SharpTS AST interpreter; this epic requires debugger protocol, execution-control, inspection, async, and editor-integration work of its own.

## Status — verified 2026-08-19

The implementation is substantially complete, but this epic should remain open until the release gates in #1405 are complete.

Completed:

- #1401–#1403 were delivered by #1406; #1404 was completed by `497d7900`.
- The product and architecture decisions, execution model, inspection/evaluation policy, performance bounds, packaging model, and manual acceptance procedure are documented.
- The remaining automatable #1405 work is implemented in local commit `d944f489`: the acceptance fixture, bounded adapter logging, VS Code project-context launch configuration, extension tests, macOS raw-DAP packaging gate, and final UI checklist.
- Verification at `d944f489`: Release solution build passed with 0 warnings/errors; debugger functional tests passed 41/41; load gate passed 1/1; VS Code extension tests passed 2/2; all 9 workflow files and all 10 NuGet-release helper checks passed; the packaged VSIX contains the interpreter debug command and `SharpTS.DebugAdapter.dll`, whose reported version matches the commit. The merged implementation is also green in Windows, Ubuntu, and AOT CI.

Remaining before closure:

1. Publish/integrate local commit `d944f489` (currently one commit ahead of `origin/main`) and obtain CI results for that commit.
2. Onboard the `SharpTS.DebugAdapter` NuGet package ID by publishing the first package; NuGet does not support reserving an ID independently of a package upload.
3. Run the documented UI checklist in both a VS Code Extension Development Host and a clean install of the packaged VSIX, then attach the results and environment details to #1405.
4. Close #1405 after those gates pass, then close this epic.

## Product/architecture gate

Before implementation proceeds beyond the protocol foundation:

- [x] Document concrete interpreter-debugging use cases that compiled `--debug` does not satisfy (startup latency, interpreter-only behavior, embedding, REPL/evaluation, hot reload, etc.).
- [x] Choose a DAP process/hosting model (`sharpts-dap` tool or another explicit boundary), launch-only v1 scope, packaging/versioning, and security model.
- [x] Define the supported concurrency model for event-loop callbacks, tasks, and workers.
- [x] Define expression-evaluation side-effect policy and how guest exceptions from debugger evaluation are contained.
- [x] Approve the maintenance cost of a debugger state machine and editor integration; otherwise close the epic as not planned with the decision recorded.

## Planned children and dependencies

- [x] #1401 — DAP protocol, lifecycle, packaging, and deterministic test harness. Foundation for all children.
- [x] #1402 — interpreter execution control, breakpoint binding, and step semantics. Depends on #1401.
- [x] #1403 — stack frames, lexical scopes, variables, and safe evaluation. Depends on #1401 and #1402.
- [x] #1404 — async flow, exceptions/rejections, modules, and workers. Depends on #1402 and #1403.
- [ ] #1405 — VS Code integration, final packaging, documentation, and end-to-end acceptance. Depends on #1401–#1404. Repository work is implemented at `d944f489`; external/manual release gates remain.

```text
#1401 ──> #1402 ──> #1403 ──> #1404 ──> #1405
```

## Cross-cutting requirements

- Use original TypeScript `SourceDocument`/span provenance and lexical environments; do not infer locations or variables from display text.
- Interpreter behavior without an attached debugger remains unchanged and pays negligible overhead when debugging is disabled.
- Pausing is cooperative, deterministic at declared safe points, and cannot deadlock the event loop or host process.
- DAP messages are versioned/tested over stdio and do not depend on VS Code internals.
- Every request observes cancellation/disconnect and returns protocol errors instead of crashing the debuggee or adapter.
- Imported modules, virtual stdlib documents, exceptions, promises/timers, and nested calls have an explicit presentation policy.

## Epic acceptance

- [ ] Every child meets its focused automated and manual verification criteria.
- [ ] A packaged adapter launches a representative interpreted multi-module TS/TSX program from VS Code and at least one other DAP client or protocol harness. The protocol-harness half is complete; manual VS Code verification remains.
- [x] Breakpoints bind in entry/imported files; continue, pause, step in/over/out, stack traces, scopes, variables, watches/evaluate, and exception stops behave according to the documented contract.
- [x] Async/timer/module behavior remains live while running and stable while paused; disconnect/termination leaves no orphan process or blocked worker.
- [x] Protocol transcript tests are deterministic and cover invalid order, cancellation, disconnect, malformed requests, and debuggee failure.
- [x] Interpreter conformance and performance baselines show no non-debug regression; compiled-mode debugging remains unaffected.
- [x] Packaging, VS Code configuration, client-agnostic setup, limitations, and troubleshooting are documented.

## Non-goals unless separately approved

- Time-travel/reverse debugging.
- Hot code replacement.
- Native/managed debugging inside CLR calls.
- Attaching to an arbitrary already-running embedded interpreter in v1.
- Perfect V8/Node Inspector protocol compatibility; DAP is the editor boundary.

Related: #1306, #1399.

Start with #1405 and the documented work at local commit d944f489, then review the remaining release gates in this epic. Done means the commit is integrated and passes CI, the SharpTS.DebugAdapter package is published, and the VS Code UI checklist is completed for both development-host and packaged-VSIX installs before closing #1405 and this epic.

Written by the indexing model from the issue text.