ARCH-NB-001 — Recover notebooks by canonical session identity
| Field | Value |
|---|---|
| Status | Open; source-verified |
| Architecture state | Source-backed current behavior; target identity contract incomplete |
| Severity | Medium |
| Affected surface | Refresh, rename, move, duplicate sessions, and concurrent restoration |
| Components | sparqd/oqullus; Jupyter Server session API |
| Associated issue | oqullus #519 |
Where the problem appears
Restore a notebook whose browser runtime state is absent, especially after its path changed or when multiple clients restore it concurrently.
Concrete observed case
The UI selects the first Jupyter session whose path exactly equals the tab path and contains a kernel ID. It performs this lookup only when execution needs a kernel and otherwise creates a new session when no match is found.
Expected condition
One canonical notebook identity resolves to zero or one authorized live session. Rename and move preserve that association, and concurrent clients cannot create duplicate sessions for the same notebook.
Cause and evidence
Canonical notebook identity, path normalization, rename mapping, duplicate session handling, and serialized creation are absent from the reviewed recovery contract.
Why it matters
Path-based recovery can attach to the wrong session, miss an existing one, or create duplicate kernels and cost after rename or concurrent refresh.
Existing controls and workarounds
Users can reopen the exact original path and operators can inspect Jupyter session listings. Neither prevents races or supplies durable identity.
Alternatives considered
- Recommended: persist and authorize canonical notebook/session identity and reconcile it on mount.
- Normalize and continue matching by path — improves simple cases but does not solve rename or duplicate creation.
- Let every tab create a session — rejected because it multiplies kernels and breaks shared notebook state.
Component involvement
sparqd/oqullusowns canonical identity restoration and serialized creation.- Jupyter Server remains authoritative for live sessions and kernel references.
Reproduction and verification
Resolution conditions
Close when zero, one, and multiple matches are handled explicitly; rename and concurrent restoration retain one authorized session; and no orphan kernel is created.
Validation and blockers
Source behavior is confirmed. Deployed rename and concurrent-client identity captures remain outstanding.