REL-NB-007 — Preserve authoritative user-server state
| Field | Value |
|---|---|
| Status | Open; source-verified and focused source tests pass |
| Architecture state | Source-backed state contract is incomplete |
| Severity | High |
| Affected surface | Server start, stop, health failure, timeout, and queued execution |
| Components | sparqd/bff-api, then sparqd/oqullus; JupyterHub is authoritative upstream |
| Associated issues | bff-api #228, then oqullus #516 |
Where the problem appears
Observe server status while spawning, stopping, failing, or while only the status request is temporarily unavailable.
Concrete observed case
The BFF exposes absent, ready, and generic non-ready states. Workspace maps status errors and exhausted startup polling to stopped. A false stopped transition clears local kernel activity and queues new work even when the user server remains alive.
Expected condition
Present stopped, spawning, running, stopping, failed, and
unreachable separately. Transport failure retains the last known state and
observation time and continues bounded reconciliation.
Cause and evidence
The BFF omits upstream pending direction, progress, and failure details. The UI therefore cannot distinguish server absence from startup, shutdown, failure, or unreachability.
Why it matters
Incorrect server state can retarget queued execution, hide failures, lose local kernel association, or instruct a user to start a server that already exists.
Existing controls and workarounds
Workspace checks on mount, polls during startup, health-checks a running server, and prompts other tabs to recheck. These checks do not correct the reduced state contract.
Alternatives considered
- Recommended: preserve the authoritative Hub server model and progress through the BFF and map each state explicitly.
- Increase polling retries — rejected because more polling cannot recover information discarded by the API contract.
- Treat request failure as stopped — rejected because absence and unreachability have different effects.
Component involvement
sparqd/bff-apireturns the authoritative state and failure/progress detail.sparqd/oqulluspresents and reconciles it without clearing kernel identity on transport failure.- JupyterHub remains the server lifecycle authority.
Reproduction and verification
Follow NB-S019.
Resolution conditions
Close when every state and transition is deterministic, temporary status loss self-recovers, and queued work is neither lost nor retargeted.
Validation and blockers
Source tests cover current transitions. Deployed spawn failure, stop, and status-isolation sequences remain pending.