REL-NB-001 — Restore the active kernel after refresh
| Field | Value |
|---|---|
| Status | Open; deployed state loss observed and source-supported |
| Architecture state | Deployed behavior |
| Severity | High |
| Affected surface | Refresh, navigation, reconnect, notebook rename, and duplicate tabs |
| Components | sparqd/oqullus; BFF API, Jupyter Server, Enterprise Gateway, and Spark are runtime dependencies |
| Associated issues | oqullus #519; related project-management #1341 and #1375 |
Where the problem appears
Run a stateful cell, refresh the Workspace notebook page without stopping its server, and continue using the notebook.
Concrete observed case
The deployed Workspace lost active kernel state after a page refresh. Tab and file metadata returned, but the active session, kernel association, connection, and in-memory execution state did not return with it.
Expected condition
Refresh reconnects to the same authorized live session and kernel. If that kernel expired or was replaced, the page explicitly reports state loss before allowing another execution.
Cause and evidence
Reviewed UI source persists tab metadata but excludes session and kernel IDs. Runtime maps and connections remain browser-memory state. Session recovery is deferred until the next execution and depends on an exact notebook-path match.
Why it matters
A fresh namespace can appear to continue an old notebook. Users can rely on missing initialization, obtain different results, or leave the previous Spark workload running without realizing it.
Existing controls and workarounds
Save notebook content before refreshing and expect to rerun initialization cells. Operators can compare session, kernel, process, and SparkApplication IDs to distinguish UI detachment from kernel replacement. This is diagnostic, not an acceptable durability contract.
Alternatives considered
- Recommended: restore the canonical server session during page hydration and reconnect before execution.
- Continue lazy path lookup — rejected because it is late, rename-sensitive, and can silently create a replacement.
- Persist only the kernel ID in browser storage — insufficient because server authorization and current session ownership must be reconciled.
Component involvement
sparqd/oqullusowns page hydration, session reconciliation, state-loss UX, and prevention of duplicate session creation.- BFF API and Jupyter Server provide the authenticated authoritative session.
- Enterprise Gateway and Spark provide the remote-kernel identity to correlate.
Reproduction and verification
Follow NB-S002, then repeat across rename, navigation, duplicate tabs, idle culling, and gateway recovery.
Resolution conditions
Close when refresh deterministically reconnects to the same live kernel or announces replacement, and tests prove no duplicate or orphan workload is created.
Validation and blockers
The initial behavior was observed, but its exact deployed branch was not captured. A disposable notebook and before/after runtime identities are needed.