REL-NB-003 — Surface kernel death and state loss
| Field | Value |
|---|---|
| Status | Open; source-verified, controlled crash pending |
| Architecture state | Source-backed failure path |
| Severity | High |
| Affected surface | Kernel crash, Spark driver failure, reconnect, and replacement |
| Components | sparqd/oqullus, sparqd/bff-api, Jupyter Server, Enterprise Gateway |
| Associated issues | oqullus #517 and #521 |
Where the problem appears
Terminate a disposable kernel or Spark driver during execution and observe the connection, cell, kernel, and recovery states.
Concrete observed case
The BFF retries an unexpectedly closed upstream channel three times against the same kernel ID. After exhaustion it closes the browser connection. The UI then clears connection bookkeeping without presenting kernel death, state loss, or an incomplete execution.
Expected condition
Connection state and kernel state remain distinct. The UI reports reconnecting, dead, restarted, or replaced; marks interrupted execution terminal; and never automatically reruns a potentially non-idempotent cell.
Cause and evidence
Transport retry cannot restart a dead kernel. Reviewed client close/error paths do not record a terminal cause or first reconcile the cached kernel ID before a later execution.
Why it matters
A restarted namespace can be mistaken for the original state, while a failed write cell might be run twice if recovery is treated as automatic retry.
Existing controls and workarounds
Users can explicitly stop or restart compute, but current feedback does not reliably distinguish transport loss from kernel loss. Save content and inspect runtime identities after an unexplained disconnect.
Alternatives considered
- Recommended: bounded transport reconnect followed by authoritative session and kernel reconciliation and explicit state-loss UX.
- Automatically restart and rerun — rejected because cells may perform writes or external side effects.
- Treat every close as kernel death — rejected because transient network loss can preserve the same kernel.
Component involvement
sparqd/bff-apiexposes bounded reconnect outcome and close reason.sparqd/oqullusreconciles runtime state and presents recovery choices.- Jupyter Server/Enterprise Gateway supply authoritative kernel identity and any upstream restart event.
Reproduction and verification
Resolution conditions
Close when transient disconnect returns to the same kernel, terminal failure is visible with retained partial output, replacement warns of namespace loss, and no cell is automatically resubmitted.
Validation and blockers
Controlled kernel and Spark-driver termination requires an approved disposable runtime.