ik session: the persistent evaluation protocol (ADR 0009 phase 6)

[ademar]

What

Phase 6 of ADR 0009, closing the ADR's plan: the session protocol is built; the debug adapter is recorded as proposed, deliberately not built yet (ADR 0008 sense), with what it actually needs named.

ik session

A persistent evaluation session over the same Content-Length framed JSON-RPC as ik lsp — the framing/dispatch layer moves into a shared Jsonrpc module rather than existing twice. Requests:

• initialize → name, version, and the honored capability profile
• eval {code} → the phase-6 point, results and errors finally separated:
  • value (showVal) with an inert flag,
  • output — everything the program printed, captured so it travels in the response instead of corrupting the framed channel,
  • or a structured error: message, rendered caret diagnostic, and spans in the same 1-based shape as ik check --json
• reset → fresh bootstrap; definitions otherwise persist across evals

The interrupt story is explicitly the client's: a hung evaluation cannot be cancelled, so the request timeout kills the process and the next eval starts a fresh session. One known leak is recorded: raw standard-output ports write past the Console capture.

Extension

• Eval Selection in Session (editor context menu + palette): selection or current line, evaluated in one persistent ik session process; results, captured output, and rendered errors land in the output channel. State survives between evals.
• Restart Session; ironkernel.session.timeoutMs (default 10s) with kill-and-restart on hang; changing the capability profile restarts both the language server and the session so displayed authority stays actual authority.
• The TS client is vscode-free (session.ts) with an incremental frame decoder tested in vitest, including split-chunk and garbage-resync cases.

Why the debug adapter stays proposed

The protocol was never its hard part. Stepping requires cancellation and suspension points in the CPS trampoline; breakpoints need the CLocated span map wired to those suspension points; and the compiled-coverage view phase 5 deferred wants the same runtime instrumentation. Those are one design and should be taken whole — the ADR says so where the next reader will look.

Verification

• Clean --no-incremental rebuild: zero warnings. Full suite: 451/451 (4 new session tests: persistence + multi-form eval + structured error spans + reset; output capture with inert flag; the minimal profile refusing print; method-not-found).
• Scripted end-to-end session against the real binary: initialize, evals, persistence, error spans, reset, exit 0. (It also reproduced the pre-existing print/show evaluator bug already filed as a separate task — the structured channel surfaces it clearly.)
• Extension: tsc --noEmit clean, vitest 26/26 (3 new framing tests), vsce package produces the VSIX.
• All examples run (yingyang skipped); CLR fault sweep: faulted (process aborted): 0.
• Benchmarks deliberately skipped: cold code behind a new subcommand; the Jsonrpc extraction moves the LSP's private helpers verbatim.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}