REL-NB-002 — Define the supported Jupyter message contract

Field	Value
Status	Open; source-verified, protocol tests incomplete
Architecture state	Source-backed current behavior
Severity	Medium
Affected surface	Cell execution, rich output, reconnect, stdin, widgets, and partial output
Components	sparqd/oqullus, sparqd/bff-api, Jupyter messaging protocol
Associated issue	oqullus #521

Where the problem appears

Execute cells that produce different Jupyter message families or experience duplicated, delayed, malformed, reordered, or interrupted messages.

Concrete observed case

Workspace creates raw kernel-channel connections, writes execution requests, correlates parent message IDs, and handles a limited set of output, reply, and status messages. Completion requires the matching reply and idle status.

Expected condition

The product either uses maintained Jupyter client primitives or publishes and tests its supported protocol subset. Unsupported messages must not corrupt another cell or leave execution non-terminal.

Cause and evidence

No assessment tests cover late or duplicate frames, comms and widgets, stdin, clear/update-display messages, reconnect ordering, or BFF fan-out behavior.

Why it matters

Protocol gaps can lose output, duplicate effects, corrupt cell association, or leave the UI executing indefinitely even when the kernel has finished.

Existing controls and workarounds

Basic stream, result, display, error, reply, and status messages are handled. Avoid relying on widgets, stdin, or advanced display mutation until their support is explicit.

Alternatives considered

1. Adopt maintained Jupyter session/client primitives and retain product UX.
2. Keep the custom client but define a bounded protocol contract with fixtures for every accepted and rejected message.
3. Silently ignore unknown messages — rejected because it obscures incomplete execution and output loss.

Component involvement

• sparqd/oqullus owns message handling, correlation, terminal state, and rendering.
• sparqd/bff-api owns transport fan-out, reconnect, and close semantics.
• Jupyter defines the protocol contract used for compatibility tests.

Reproduction and verification

Follow NB-S009, NB-S010, and NB-S020.

Resolution conditions

Close when the supported message matrix is published and automated tests prove correct correlation, output, completion, disconnect, and unsupported-message behavior.

Validation and blockers

Source coverage is known. Controlled protocol injection and reconnect evidence remain outstanding.