Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Add `marimo._core`, a model of a host's notebooks and runtimes (#11179)

Trevor Manz7ed09249548b
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index bcf9251ad5..0448c47dfa 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -71,3 +71,9 @@ repos:
language: system
pass_filenames: false
files: ^tests/.*\.py$
+ - id: core-imports
+ name: Check core imports
+ entry: bash -c 'if command -v uv >/dev/null 2>&1; then uv run python scripts/check_core_imports.py; else python scripts/check_core_imports.py; fi'
+ language: system
+ pass_filenames: false
+ files: ^marimo/_core/.*\.py$
diff --git a/marimo/_core/__init__.py b/marimo/_core/__init__.py
new file mode 100644
index 0000000000..0c91eb2a3c
--- /dev/null
+++ b/marimo/_core/__init__.py
@@ -0,0 +1,6 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Types and state for the marimo host protocol.
+
+Hosts track projects and notebooks. Notebooks track runtimes, client
+attachments, and runs. State changes are published as events.
+"""
diff --git a/marimo/_core/backend.py b/marimo/_core/backend.py
new file mode 100644
index 0000000000..1205887903
--- /dev/null
+++ b/marimo/_core/backend.py
@@ -0,0 +1,152 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Kernel commands and updates for the host API.
+
+```python
+notebook = host.add_notebook(record, backend)
+notebook.start() # Calls backend.start(...).
+
+# The backend reports kernel startup through Notebook.observe.
+notebook.observe(Starting("Launching kernel"))
+notebook.observe(Running())
+```
+
+marimo currently manages sessions and kernels outside the core model.
+A backend lets the host API run as a sidecar, reporting activity from
+both API commands and existing clients. The adapter may become
+unnecessary if marimo adopts the core model directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from marimo._core import protocol
+
+
+class Backend(Protocol):
+ """Commands for managing a notebook's kernel.
+
+ Commands return without waiting for completion. Implementations report
+ updates through `Notebook.observe` and assign execution and item IDs.
+ """
+
+ def start(self, runtime_id: protocol.RuntimeId) -> None:
+ """Start a kernel for the given runtime.
+
+ Report `Starting` while launching, then `Running` on success or
+ `Exited` with a reason on failure.
+ """
+
+ def stop(self) -> None:
+ """Stop the kernel and report `Exited` when shutdown completes."""
+
+ def run(self, run_id: protocol.RunId, code: str) -> None:
+ """Evaluate scratch code and report the run's progress and output."""
+
+ def interrupt(self, run_id: protocol.RunId) -> None:
+ """Interrupt a run and report an `interrupted` execution outcome."""
+
+
+# Runtime lifecycle
+
+
+@dataclass(frozen=True)
+class Starting:
+ """Kernel startup progress, with an optional status message."""
+
+ message: str | None = None
+
+
+@dataclass(frozen=True)
+class Running:
+ """The kernel is ready to execute code."""
+
+ marimo_version: str | None = None
+
+
+@dataclass(frozen=True)
+class Exited:
+ """The kernel stopped or exited unexpectedly."""
+
+ reason: str | None = None
+
+
+# Runs
+
+
+@dataclass(frozen=True)
+class Scheduled:
+ """The runtime scheduled a run independently of a host API request."""
+
+ run_id: protocol.RunId
+ caused_by: protocol.ExecutionId | None = None
+
+
+@dataclass(frozen=True)
+class PlannedExecution:
+ id: protocol.ExecutionId
+ cell_id: str | None
+ code_hash: str
+ code: str | None
+ caused_by: protocol.ExecutionId | None = None
+
+
+@dataclass(frozen=True)
+class Planned:
+ """A run's planned executions, reported before any execution starts."""
+
+ run_id: protocol.RunId
+ executions: tuple[PlannedExecution, ...]
+
+
+@dataclass(frozen=True)
+class Status:
+ """An execution changed status to `running` or `completed`."""
+
+ execution_id: protocol.ExecutionId
+ status: protocol.Lifecycle
+
+
+@dataclass(frozen=True)
+class Produced:
+ """Console or display output from an execution.
+
+ Reusing an item ID replaces its previous value.
+ """
+
+ item: protocol.Console | protocol.Display
+
+
+@dataclass(frozen=True)
+class Concluded:
+ """An execution's current outcome; final once the execution is completed."""
+
+ execution_id: protocol.ExecutionId
+ outcome: protocol.Outcome
+
+
+@dataclass(frozen=True)
+class Done:
+ """The cycle ended and will schedule no more executions.
+
+ All planned executions must already have a final outcome and status.
+ The outcome also accounts for failures or interruption of the cycle
+ itself, including termination before any execution was planned.
+ """
+
+ run_id: protocol.RunId
+ outcome: protocol.RunOutcome
+
+
+Message = (
+ Starting
+ | Running
+ | Exited
+ | Scheduled
+ | Planned
+ | Status
+ | Produced
+ | Concluded
+ | Done
+)
diff --git a/marimo/_core/errors.py b/marimo/_core/errors.py
new file mode 100644
index 0000000000..19afd0b071
--- /dev/null
+++ b/marimo/_core/errors.py
@@ -0,0 +1,20 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Exceptions raised by host and notebook commands."""
+
+from __future__ import annotations
+
+
+class HostError(Exception):
+ """Base exception for host and notebook commands."""
+
+
+class NotFound(HostError):
+ """The requested object does not exist."""
+
+
+class Conflict(HostError):
+ """The command cannot run in the current state."""
+
+
+class NoRuntime(Conflict):
+ """The command requires a runtime, but the notebook has none."""
diff --git a/marimo/_core/host.py b/marimo/_core/host.py
new file mode 100644
index 0000000000..52a217fe5f
--- /dev/null
+++ b/marimo/_core/host.py
@@ -0,0 +1,201 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Projects, notebooks, and event subscriptions for a marimo host."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import TYPE_CHECKING
+
+from marimo._core import protocol
+from marimo._core.backend import Backend
+from marimo._core.errors import NotFound
+from marimo._core.notebook import Notebook
+from marimo._core.stream import Event, Listener, Stream, message
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, Collection, Iterator, Sequence
+
+
+class _NotebookRecords(Mapping[str, protocol.Notebook]):
+ """A catalog view whose readers own their copies of mutable records."""
+
+ def __init__(self, records: Mapping[str, protocol.Notebook]) -> None:
+ self._records = records
+
+ def __getitem__(self, key: str) -> protocol.Notebook:
+ return deepcopy(self._records[key])
+
+ def __iter__(self) -> Iterator[str]:
+ return iter(self._records)
+
+ def __len__(self) -> int:
+ return len(self._records)
+
+
+class Host:
+ """A host's project and notebook catalog, with events for changes."""
+
+ def __init__(
+ self,
+ *,
+ operations: Sequence[str],
+ history: int = 1000,
+ ) -> None:
+ self._host = protocol.Host(operations=list(operations))
+ self._stream = Stream(history=history)
+ # Lookups accept wire strings; stored objects carry branded IDs.
+ self._projects: dict[str, protocol.Project] = {}
+ self._records: dict[str, protocol.Notebook] = {}
+ self._notebooks: dict[str, Notebook] = {}
+
+ @property
+ def notebooks(self) -> Mapping[str, protocol.Notebook]:
+ """Catalog metadata, independent of each notebook's execution state."""
+ return _NotebookRecords(self._records)
+
+ @property
+ def operations(self) -> list[str]:
+ return list(self._host.operations)
+
+ def update_project(
+ self, project: protocol.Project, *, request_id: str | None = None
+ ) -> None:
+ """Store a project and publish an event if it changed."""
+ if self._projects.get(project.id) == project:
+ return
+ self._projects[project.id] = deepcopy(project)
+ self._stream.publish(project, request_id=request_id)
+
+ def add_notebook(
+ self,
+ record: protocol.Notebook,
+ backend: Backend,
+ *,
+ request_id: str | None = None,
+ ) -> Notebook:
+ """Register a notebook and the backend that runs it."""
+ if record.id in self._records:
+ raise ValueError(f"notebook {record.id} is already in the catalog")
+ if record.project_id not in self._projects:
+ raise ValueError(
+ f"project {record.project_id} is not in the catalog"
+ )
+ notebook = Notebook(record.id, backend, self._stream)
+ self._records[record.id] = deepcopy(record)
+ self._notebooks[record.id] = notebook
+ self._stream.publish(
+ record, notebook_id=record.id, request_id=request_id
+ )
+ return notebook
+
+ def update_notebook(
+ self, record: protocol.Notebook, *, request_id: str | None = None
+ ) -> None:
+ """Update catalog metadata without changing the notebook's state."""
+ if record.id not in self._records:
+ raise NotFound(f"no notebook {record.id}")
+ if record.project_id not in self._projects:
+ raise ValueError(
+ f"project {record.project_id} is not in the catalog"
+ )
+ if self._records[record.id] == record:
+ return
+ self._records[record.id] = deepcopy(record)
+ self._stream.publish(
+ record, notebook_id=record.id, request_id=request_id
+ )
+
+ def remove_notebook(
+ self, notebook_id: str, *, request_id: str | None = None
+ ) -> None:
+ """Remove a notebook, its runtime, attachments, and runs."""
+ notebook = self._notebooks.pop(notebook_id, None)
+ if notebook is None:
+ return
+ del self._records[notebook.id]
+ notebook._dispose(request_id=request_id)
+ self._stream.remove(
+ "notebook",
+ notebook.id,
+ notebook_id=notebook.id,
+ request_id=request_id,
+ )
+
+ def notebook(self, notebook_id: str) -> Notebook:
+ """Return a notebook or raise `NotFound`."""
+ notebook = self._notebooks.get(notebook_id)
+ if notebook is None:
+ raise NotFound(f"no notebook {notebook_id}")
+ return notebook
+
+ def _snapshot(
+ self, notebook_id: protocol.NotebookId | None = None
+ ) -> list[Event]:
+ """Return snapshot events for the catalog or a single notebook.
+
+ Catalog snapshots contain the host, projects, then notebooks with
+ their runtimes and attachments. Notebook snapshots also include
+ runs, executions, and outputs.
+ """
+ if notebook_id is not None:
+ records = [self._records[notebook_id]]
+ events: list[Event] = []
+ else:
+ records = list(self._records.values())
+ events = [Event("host", message(self._host))]
+ events.extend(
+ Event("project", message(p)) for p in self._projects.values()
+ )
+ for record in records:
+ events.append(
+ Event("notebook", message(record), notebook_id=record.id)
+ )
+ events.extend(
+ e
+ for e in self._notebooks[record.id]._snapshot()
+ if e.visible_in(notebook_id)
+ )
+ return events
+
+ def events(
+ self,
+ cursor: int | None = None,
+ *,
+ notebook_id: str | None = None,
+ types: Collection[str] | None = None,
+ run_id: str | None = None,
+ ) -> list[Event]:
+ """Return initial events followed by `ready` with the latest cursor.
+
+ Replay events after `cursor`, or return a snapshot if no cursor
+ is given. An unavailable cursor produces `reset` and a snapshot.
+ A run filter includes only that run, its executions, and their items.
+ """
+ scope = None if notebook_id is None else self.notebook(notebook_id).id
+ ready = Event("ready", id=self._stream.last_id)
+ if cursor is None:
+ events = self._snapshot(scope)
+ else:
+ missed = self._stream.since(cursor)
+ if missed is None:
+ events = [Event("reset"), *self._snapshot(scope)]
+ else:
+ events = [e for e in missed if e.visible_in(notebook_id)]
+ return [e for e in [*events, ready] if e.wanted(types, run_id)]
+
+ def subscribe(
+ self,
+ listener: Listener,
+ *,
+ notebook_id: str | None = None,
+ types: Collection[str] | None = None,
+ run_id: str | None = None,
+ ) -> Callable[[], None]:
+ """Subscribe to matching live events; return an unsubscribe function."""
+
+ def filtered(event: Event) -> None:
+ if event.visible_in(notebook_id) and event.wanted(types, run_id):
+ listener(event)
+
+ return self._stream.subscribe(filtered)
diff --git a/marimo/_core/ids.py b/marimo/_core/ids.py
new file mode 100644
index 0000000000..4ce8d6d796
--- /dev/null
+++ b/marimo/_core/ids.py
@@ -0,0 +1,19 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Mint opaque IDs; object owners determine whether an ID is still live."""
+
+from __future__ import annotations
+
+import secrets
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+_Id = TypeVar("_Id", bound=str)
+_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
+
+
+def mint(kind: Callable[[str], _Id], prefix: str) -> _Id:
+ """Create a typed ID with 80 random bits in Crockford Base32."""
+ body = "".join(secrets.choice(_ALPHABET) for _ in range(16))
+ return kind(f"{prefix}-{body}")
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.py
new file mode 100644
index 0000000000..63582a1703
--- /dev/null
+++ b/marimo/_core/notebook.py
@@ -0,0 +1,590 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Notebook runtimes, client attachments, and runs.
+
+Runtime and run commands call a backend. `Notebook.observe` applies
+backend updates and publishes events.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from msgspec.structs import replace
+
+from marimo._core import backend as be, protocol
+from marimo._core.errors import Conflict, NoRuntime, NotFound
+from marimo._core.ids import mint
+from marimo._core.stream import Event, kind_of, message, utcnow
+
+if TYPE_CHECKING:
+ from marimo._core.stream import Stream
+
+Item = protocol.Console | protocol.Display
+
+
+class Notebook:
+ """A notebook's state and commands.
+
+ Snapshots preserve insertion order for runs, executions, and items.
+ Completed results remain available across runtime stops and restarts.
+ Removing the notebook closes it; further commands raise `NotFound`.
+ """
+
+ def __init__(
+ self,
+ notebook_id: protocol.NotebookId,
+ backend: be.Backend,
+ stream: Stream,
+ ) -> None:
+ self._id = notebook_id
+ self._backend = backend
+ self._stream = stream
+ self._closed = False
+ self.runtime: protocol.Runtime | None = None
+ self._attachments: dict[str, protocol.Attachment] = {}
+ self._runs: dict[str, protocol.Run] = {}
+ self._run_requests: dict[str, str | None] = {}
+ self._executions: dict[protocol.ExecutionId, protocol.Execution] = {}
+ # Superseded results still contribute to their unfinished run.
+ self._retired_executions: dict[
+ protocol.ExecutionId, protocol.Execution
+ ] = {}
+ self._items: dict[protocol.ItemId, Item] = {}
+ self._replacement: protocol.Runtime | None = None
+ # Associate runtime events with the pending start, stop, or restart.
+ self._lifecycle_request: str | None = None
+
+ @property
+ def id(self) -> protocol.NotebookId:
+ return self._id
+
+ def _require_open(self) -> None:
+ if self._closed:
+ raise NotFound(f"no notebook {self.id}")
+
+ # ---- runtime -------------------------------------------------------
+
+ def start(
+ self, *, request_id: str | None = None
+ ) -> tuple[protocol.Runtime, bool]:
+ """Start a runtime if none exists.
+
+ Returns the runtime and whether a new runtime was created.
+ An existing runtime is returned unchanged, regardless of status.
+ """
+ self._require_open()
+ if self.runtime is not None:
+ return self.runtime, False
+ runtime = self._new_runtime("starting", None, None)
+ self._lifecycle_request = request_id
+ self._set_runtime(runtime)
+ self._backend.start(runtime.id)
+ return runtime, True
+
+ def stop(self, *, request_id: str | None = None) -> protocol.Runtime:
+ """Stop the runtime for all attached clients, retaining its results.
+
+ Removal waits for the backend to report that the kernel exited.
+ Failed runtimes are removed immediately. Returns the runtime
+ with status `terminating`.
+
+ Raises:
+ NoRuntime: If the notebook has no runtime.
+ """
+ self._require_open()
+ runtime = self._require_runtime()
+ self._lifecycle_request = request_id
+ self._replacement = None
+ if runtime.status == "terminating":
+ return runtime
+ terminating = replace(runtime, status="terminating")
+ self._set_runtime(terminating)
+ if runtime.status == "failed":
+ self._end_runtime()
+ else:
+ self._backend.stop()
+ return terminating
+
+ def restart(self, *, request_id: str | None = None) -> protocol.Runtime:
+ """Stop the runtime and start a replacement with a new ID.
+
+ Returns the replacement in its starting state. The replacement
+ appears on the stream after the old runtime is removed.
+
+ Raises:
+ NoRuntime: If the notebook has no runtime.
+ Conflict: If the runtime is not running.
+ """
+ self._require_open()
+ runtime = self._require_runtime()
+ if runtime.status != "running":
+ raise Conflict(
+ f"the runtime is {runtime.status}; only a running one restarts"
+ )
+ self._lifecycle_request = request_id
+ replacement = self._new_runtime("starting", None, None)
+ self._replacement = replacement
+ terminating = replace(runtime, status="terminating")
+ self._set_runtime(terminating)
+ self._backend.stop()
+ return replacement
+
+ def _require_runtime(self) -> protocol.Runtime:
+ if self.runtime is None:
+ raise NoRuntime(
+ f"notebook {self.id} has no runtime; start one first."
+ )
+ return self.runtime
+
+ def _set_runtime(self, runtime: protocol.Runtime) -> None:
+ self.runtime = runtime
+ self._publish(runtime, self._lifecycle_request)
+ if runtime.status in ("running", "failed"):
+ self._lifecycle_request = None
+
+ def _end_runtime(self) -> None:
+ assert self.runtime is not None
+ self._interrupt_in_flight()
+ runtime, self.runtime = self.runtime, None
+ self._remove("runtime", runtime.id, self._lifecycle_request)
+ self._lifecycle_request = None
+
+ # ---- runs ----------------------------------------------------------
+
+ def run(self, code: str, *, request_id: str) -> protocol.Run:
+ """Queue scratch code on the runtime.
+
+ The request ID identifies the run. Repeating a request returns
+ the existing run while it is retained.
+
+ Raises:
+ NoRuntime: If the notebook has no runtime.
+ Conflict: If the runtime is not running, or a run is in progress.
+ """
+ self._require_open()
+ run = self._runs.get(request_id)
+ if run is not None:
+ return run
+ runtime = self._require_runtime()
+ if runtime.status != "running":
+ raise Conflict(f"the runtime is {runtime.status}.")
+ in_flight = [r for r in self._runs.values() if r.status != "completed"]
+ if in_flight:
+ raise Conflict(f"run {in_flight[0].id} is in progress.")
+ run = protocol.Run(
+ id=protocol.RunId(request_id),
+ notebook_id=self.id,
+ caused_by=None,
+ status="queued",
+ outcome=None,
+ started_at=None,
+ completed_at=None,
+ )
+ self._run_requests[run.id] = request_id
+ self._set_run(run)
+ self._backend.run(run.id, code)
+ return run
+
+ def interrupt(self, run_id: str) -> protocol.Run:
+ """Request interruption of a run in progress.
+
+ Raises:
+ NotFound: If there is no such run.
+ Conflict: If the run is already completed.
+ """
+ self._require_open()
+ run = self._runs.get(run_id)
+ if run is None:
+ raise NotFound(f"notebook {self.id} has no run {run_id}.")
+ if run.status == "completed":
+ raise Conflict(f"run {run_id} has already ended.")
+ self._backend.interrupt(run.id)
+ return run
+
+ def _clear_runs(self) -> None:
+ self._retired_executions.clear()
+ for item in list(self._items.values()):
+ del self._items[item.id]
+ run_id = self._executions[item.execution_id].run_id
+ self._remove(kind_of(item), item.id, run_id, run_id=run_id)
+ for execution in list(self._executions.values()):
+ del self._executions[execution.id]
+ self._remove(
+ "execution",
+ execution.id,
+ execution.run_id,
+ run_id=execution.run_id,
+ )
+ for run in list(self._runs.values()):
+ del self._runs[run.id]
+ self._remove("run", run.id, run.id, run_id=run.id)
+ self._run_requests.pop(run.id, None)
+
+ def _set_run(self, run: protocol.Run) -> None:
+ self._runs[run.id] = run
+ self._publish(run, run.id)
+
+ def _set_execution(self, execution: protocol.Execution) -> None:
+ self._executions[execution.id] = execution
+ self._publish(execution, execution.run_id)
+
+ def _interrupt_in_flight(
+ self, outcome: protocol.RunOutcome = "interrupted"
+ ) -> None:
+ now = utcnow()
+ for execution in list(self._executions.values()):
+ if execution.status != "completed":
+ self._set_execution(
+ replace(
+ execution,
+ status="completed",
+ outcome=protocol.InterruptedOutcome(),
+ completed_at=now,
+ )
+ )
+ for run in list(self._runs.values()):
+ if run.status != "completed":
+ self._set_run(
+ replace(
+ run,
+ status="completed",
+ outcome=outcome,
+ completed_at=now,
+ )
+ )
+ self._retired_executions.clear()
+
+ # ---- attachments ---------------------------------------------------
+
+ def attach(self) -> protocol.Attachment:
+ """Record an attached host API client."""
+ self._require_open()
+ attachment = protocol.Attachment(
+ id=mint(protocol.AttachmentId, "att"),
+ notebook_id=self.id,
+ kind="client",
+ name=None,
+ since=utcnow(),
+ )
+ self._attachments[attachment.id] = attachment
+ self._publish(attachment, None)
+ return attachment
+
+ def detach(self, attachment_id: str) -> None:
+ attachment = self._attachments.pop(attachment_id, None)
+ if attachment is not None:
+ self._remove("attachment", attachment.id, None)
+
+ # ---- backend updates -----------------------------------------------
+
+ def observe(self, msg: be.Message) -> None:
+ """Apply a backend update and publish the resulting state changes."""
+ if self._closed:
+ return
+ match msg:
+ case be.Starting(message=text):
+ self._observe_starting(text)
+ case be.Running(marimo_version=version):
+ self._observe_running(version)
+ case be.Exited(reason=reason):
+ self._observe_exited(reason)
+ case be.Scheduled(run_id=run_id, caused_by=caused_by):
+ if run_id not in self._runs:
+ self._require_runtime()
+ self._run_requests[run_id] = None
+ self._set_run(
+ protocol.Run(
+ id=run_id,
+ notebook_id=self.id,
+ caused_by=caused_by,
+ status="queued",
+ outcome=None,
+ started_at=None,
+ completed_at=None,
+ )
+ )
+ case be.Planned(run_id=run_id, executions=planned):
+ self._observe_planned(run_id, planned)
+ case be.Status(execution_id=execution_id, status=status):
+ self._observe_status(execution_id, status)
+ case be.Produced(item=item):
+ if item.execution_id in self._executions:
+ self._items[item.id] = item
+ self._publish(
+ item, self._executions[item.execution_id].run_id
+ )
+ case be.Concluded(execution_id=execution_id, outcome=outcome):
+ if (
+ execution := self._executions.get(execution_id)
+ ) is not None and execution.status != "completed":
+ self._set_execution(replace(execution, outcome=outcome))
+ case be.Done(run_id=run_id, outcome=outcome):
+ if (
+ run := self._runs.get(run_id)
+ ) is not None and run.status != "completed":
+ members = [
+ execution
+ for execution in (
+ *self._executions.values(),
+ *self._retired_executions.values(),
+ )
+ if execution.run_id == run_id
+ ]
+ if any(
+ execution.status != "completed"
+ for execution in members
+ ):
+ raise ValueError(
+ "a run cannot complete with unfinished executions"
+ )
+ if outcome == "succeeded" and any(
+ not isinstance(
+ execution.outcome, protocol.ValueOutcome
+ )
+ for execution in members
+ ):
+ raise ValueError(
+ "a successful run cannot contain failed or interrupted executions"
+ )
+ self._set_run(
+ replace(
+ run,
+ status="completed",
+ outcome=outcome,
+ completed_at=utcnow(),
+ )
+ )
+ for member in members:
+ self._retired_executions.pop(member.id, None)
+
+ def _observe_starting(self, text: str | None) -> None:
+ if self.runtime is None:
+ # Track kernels started outside the host API.
+ self._set_runtime(self._new_runtime("starting", text, None))
+ elif self.runtime.status == "failed":
+ self._replace_runtime(text)
+ elif self.runtime.status == "starting":
+ self._set_runtime(replace(self.runtime, message=text))
+
+ def _observe_running(self, version: str | None) -> None:
+ if self.runtime is None:
+ self._set_runtime(self._new_runtime("running", None, version))
+ return
+ if self.runtime.status == "failed":
+ self._replace_runtime()
+ if self.runtime.status in ("starting", "running"):
+ self._set_runtime(
+ replace(
+ self.runtime,
+ status="running",
+ message=None,
+ marimo_version=version,
+ )
+ )
+
+ def _observe_exited(self, reason: str | None) -> None:
+ runtime = self.runtime
+ if runtime is None:
+ return
+ if runtime.status == "terminating" and self._replacement is not None:
+ replacement, self._replacement = self._replacement, None
+ request_id = self._lifecycle_request
+ self._end_runtime()
+ self._lifecycle_request = request_id
+ self._set_runtime(replacement)
+ assert self.runtime is not None
+ self._backend.start(self.runtime.id)
+ elif runtime.status == "terminating":
+ self._end_runtime()
+ else:
+ # Preserve results after an unexpected exit.
+ self._interrupt_in_flight("failed")
+ self._set_runtime(
+ replace(runtime, status="failed", message=reason)
+ )
+
+ def _replace_runtime(self, text: str | None = None) -> None:
+ request_id = self._lifecycle_request
+ self._end_runtime()
+ self._lifecycle_request = request_id
+ self._set_runtime(self._new_runtime("starting", text, None))
+
+ def _new_runtime(
+ self,
+ status: protocol.RuntimeStatus,
+ text: str | None,
+ version: str | None,
+ ) -> protocol.Runtime:
+ return protocol.Runtime(
+ id=mint(protocol.RuntimeId, "rt"),
+ notebook_id=self.id,
+ status=status,
+ message=text,
+ marimo_version=version,
+ started_at=utcnow(),
+ )
+
+ def _observe_planned(
+ self,
+ run_id: protocol.RunId,
+ planned: tuple[be.PlannedExecution, ...],
+ ) -> None:
+ if (
+ run := self._runs.get(run_id)
+ ) is None or run.status == "completed":
+ return
+ runtime = self._require_runtime()
+ for entry in planned:
+ if (
+ entry.id in self._executions
+ or entry.id in self._retired_executions
+ ):
+ continue
+ if entry.cell_id is not None:
+ for previous in list(self._executions.values()):
+ if previous.cell_id == entry.cell_id:
+ self._retire_execution(previous)
+ self._set_execution(
+ protocol.Execution(
+ id=entry.id,
+ run_id=run_id,
+ runtime_id=runtime.id,
+ caused_by=entry.caused_by,
+ cell_id=entry.cell_id,
+ code=entry.code,
+ code_hash=entry.code_hash,
+ bindings=[],
+ status="queued",
+ outcome=None,
+ stale=None,
+ started_at=None,
+ completed_at=None,
+ )
+ )
+
+ def _retire_execution(self, execution: protocol.Execution) -> None:
+ if execution.status != "completed":
+ raise ValueError("cannot replace an unfinished cell execution")
+ run_id = execution.run_id
+ run = self._runs.get(run_id) if run_id is not None else None
+ if run is not None and run.status != "completed":
+ self._retired_executions[execution.id] = execution
+ for item in list(self._items.values()):
+ if item.execution_id == execution.id:
+ del self._items[item.id]
+ self._remove(kind_of(item), item.id, run_id, run_id=run_id)
+ del self._executions[execution.id]
+ self._remove("execution", execution.id, run_id, run_id=run_id)
+
+ def _observe_status(
+ self, execution_id: protocol.ExecutionId, status: protocol.Lifecycle
+ ) -> None:
+ execution = self._executions.get(execution_id)
+ if execution is None or execution.status in (status, "completed"):
+ return
+ now = utcnow()
+ if status == "running":
+ execution = replace(execution, status=status, started_at=now)
+ assert execution.run_id is not None
+ run = self._runs[execution.run_id]
+ if run.status == "queued":
+ self._set_run(replace(run, status="running", started_at=now))
+ elif status == "completed":
+ if execution.outcome is None:
+ raise ValueError("a completed execution must have an outcome")
+ execution = replace(execution, status=status, completed_at=now)
+ else:
+ execution = replace(execution, status=status)
+ self._set_execution(execution)
+
+ # ---- stream --------------------------------------------------------
+
+ def _snapshot(self) -> list[Event]:
+ """Return notebook objects as snapshot events, parents first."""
+ bodies: list[
+ protocol.Runtime
+ | protocol.Attachment
+ | protocol.Run
+ | protocol.Execution
+ | Item
+ ] = []
+ if self.runtime is not None:
+ bodies.append(self.runtime)
+ bodies.extend(self._attachments.values())
+ bodies.extend(self._runs.values())
+ bodies.extend(self._executions.values())
+ bodies.extend(self._items.values())
+ return [
+ Event(
+ kind_of(body),
+ message(body),
+ notebook_id=self.id,
+ run_id=self._run_id(body),
+ )
+ for body in bodies
+ ]
+
+ def _dispose(self, *, request_id: str | None = None) -> None:
+ """Close the notebook and remove its state, children first.
+
+ The host must publish `notebook.removed` after disposing of its state.
+ """
+ self._closed = True
+ self._clear_runs()
+ for attachment_id in list(self._attachments):
+ self.detach(attachment_id)
+ if self.runtime is not None:
+ runtime, self.runtime = self.runtime, None
+ self._remove("runtime", runtime.id, request_id)
+
+ def _publish(
+ self,
+ body: protocol.Runtime
+ | protocol.Attachment
+ | protocol.Run
+ | protocol.Execution
+ | Item,
+ request_id: str | None,
+ ) -> None:
+ if (run_id := self._run_id(body)) is not None:
+ request_id = self._run_requests.get(run_id)
+ self._stream.publish(
+ body,
+ notebook_id=self.id,
+ request_id=request_id,
+ run_id=self._run_id(body),
+ )
+
+ def _run_id(
+ self,
+ body: protocol.Runtime
+ | protocol.Attachment
+ | protocol.Run
+ | protocol.Execution
+ | Item,
+ ) -> protocol.RunId | None:
+ if isinstance(body, protocol.Run):
+ return body.id
+ if isinstance(body, protocol.Execution):
+ return body.run_id
+ if isinstance(body, (protocol.Console, protocol.Display)):
+ return self._executions[body.execution_id].run_id
+ return None
+
+ def _remove(
+ self,
+ kind: str,
+ object_id: str,
+ request_id: str | None,
+ *,
+ run_id: protocol.RunId | None = None,
+ ) -> None:
+ if run_id is not None:
+ request_id = self._run_requests.get(run_id)
+ self._stream.remove(
+ kind,
+ object_id,
+ notebook_id=self.id,
+ request_id=request_id,
+ run_id=run_id,
+ )
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
new file mode 100644
index 0000000000..1f9f62d92f
--- /dev/null
+++ b/marimo/_core/protocol.py
@@ -0,0 +1,1012 @@
+# Copyright 2026 Marimo. All rights reserved.
+# AUTO-GENERATED FILE — DO NOT EDIT.
+# Generated from host-protocol/openapi.yaml in marimo-team/pair.
+# Regenerate with `cargo xtask generate-host-protocol`.
+# ruff: noqa: TC003 - msgspec resolves annotations at runtime
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Annotated, Literal, NewType, TypeAlias
+
+from msgspec import UNSET, Meta, Struct, UnsetType
+
+if TYPE_CHECKING:
+ AttachmentId = NewType("AttachmentId", str)
+else:
+ AttachmentId = NewType(
+ "AttachmentId",
+ Annotated[
+ str,
+ Meta(
+ description="Identifies an attachment. Unique within the host.",
+ min_length=1,
+ ),
+ ],
+ )
+
+
+class Binding(Struct):
+ name: str
+ preview: (
+ Annotated[
+ str,
+ Meta(
+ description="A short rendering of the value. A host may leave it null."
+ ),
+ ]
+ | None
+ )
+ type: (
+ Annotated[
+ str,
+ Meta(
+ description="The runtime's label for the value's type. A host may leave it null."
+ ),
+ ]
+ | None
+ )
+
+
+class DecisionOption(Struct):
+ id: Annotated[str, Meta(description="Identifies this answer.")]
+ label: Annotated[str, Meta(description="Text to show a person.")]
+
+
+class DisplayData(Struct):
+ data: Annotated[
+ str,
+ Meta(
+ description="The rendered value. JSON mimetypes are encoded as text; binary mimetypes are base64. Never a URL only the runtime can serve."
+ ),
+ ]
+ mimetype: Annotated[
+ str,
+ Meta(
+ description="The format of `data`, such as `text/html` or `image/png`."
+ ),
+ ]
+
+
+if TYPE_CHECKING:
+ ExecutionId = NewType("ExecutionId", str)
+else:
+ ExecutionId = NewType(
+ "ExecutionId",
+ Annotated[
+ str,
+ Meta(
+ description="Identifies an execution. Unique within the host.",
+ min_length=1,
+ ),
+ ],
+ )
+
+
+class Host(Struct):
+ operations: Annotated[
+ list[str],
+ Meta(
+ description="The operations this host implements, such as `runtime.start`. Whether a client may call one on a given project or notebook is that object's `operations`. Clients accept names they do not recognize."
+ ),
+ ]
+
+
+class HostMessage(Struct):
+ host: Host
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class InterruptedOutcome(Struct, tag_field="kind", tag="interrupted"):
+ pass
+
+
+if TYPE_CHECKING:
+ ItemId = NewType("ItemId", str)
+else:
+ ItemId = NewType(
+ "ItemId",
+ Annotated[
+ str,
+ Meta(
+ description="Identifies a console or display item. Unique within the host; sending an item again with the same id replaces it.",
+ min_length=1,
+ ),
+ ],
+ )
+
+
+Lifecycle: TypeAlias = Annotated[
+ Literal["queued", "running", "completed"],
+ Meta(
+ description="Where a run or execution is in its lifecycle. An execution is\n`queued` until it starts, `running` while code executes, and\n`completed` once it has ended. How it ended is its `outcome`.\n"
+ ),
+]
+
+
+if TYPE_CHECKING:
+ NotebookId = NewType("NotebookId", str)
+else:
+ NotebookId = NewType(
+ "NotebookId",
+ Annotated[
+ str,
+ Meta(
+ description="Identifies a notebook. Unique within the host and unchanged while the notebook exists.",
+ min_length=1,
+ ),
+ ],
+ )
+
+
+ObjectType: TypeAlias = Annotated[
+ Literal[
+ "host",
+ "project",
+ "notebook",
+ "runtime",
+ "attachment",
+ "run",
+ "execution",
+ "console",
+ "display",
+ ],
+ Meta(
+ description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, runtime,\nattachment, run, execution, console, and display.\n"
+ ),
+]
+
+
+class OpenNotebookResponse(Struct):
+ url: Annotated[
+ str,
+ Meta(
+ description="The URL the host used to show the notebook. It never contains the host's token."
+ ),
+ ]
+
+
+class Position(Struct):
+ character: Annotated[
+ int,
+ Meta(
+ description="Zero-based offset in the line, in UTF-16 code units.",
+ ge=0,
+ ),
+ ]
+ line: Annotated[
+ int, Meta(description="Zero-based line within the code.", ge=0)
+ ]
+
+
+class Process(Struct):
+ pid: Annotated[int, Meta(description="The process id.", ge=1)]
+ started_at: Annotated[
+ datetime, Meta(description="When the process started.")
+ ]
+
+
+if TYPE_CHECKING:
+ ProjectId = NewType("ProjectId", str)
+else:
+ ProjectId = NewType(
+ "ProjectId",
+ Annotated[
+ str,
+ Meta(
+ description="Identifies a project. Unique within the host and unchanged while the project exists.",
+ min_length=1,
+ ),
+ ],
+ )
+
+
+ProjectStatus: TypeAlias = Annotated[
+ Literal["indexing", "indexed", "partial"],
+ Meta(
+ description="How far a host has gotten finding the notebooks in a project.\nWhile it is `indexing`, more notebooks are coming. Once it is\n`indexed`, the host believes it has found every notebook under the\nroot. A `partial` project is one the host stopped scanning on\npurpose, or one with something it could not read.\n"
+ ),
+]
+
+
+class Range(Struct):
+ end: Annotated[
+ Position,
+ Meta(
+ description="Exclusive end. Equal to start when only a point is known."
+ ),
+ ]
+ start: Position
+
+
+class Related(Struct):
+ cell_id: str
+ message: Annotated[
+ str,
+ Meta(
+ description="What that cell contributes, such as `reads x from C`."
+ ),
+ ]
+ range: (
+ Annotated[Range, Meta(description="Where in that cell, when known.")]
+ | None
+ )
+
+
+class RemovedMessage(Struct):
+ id: Annotated[
+ str, Meta(description="The id of the object that was removed.")
+ ]
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+if TYPE_CHECKING:
+ RunId = NewType("RunId", str)
+else:
+ RunId = NewType(
+ "RunId",
+ Annotated[
+ str,
+ Meta(
+ description="Identifies a run. The request's `Idempotency-Key` for a client request; minted by the host when the runtime schedules a run.",
+ min_length=1,
+ ),
+ ],
+ )
+
+
+RunOutcome: TypeAlias = Annotated[
+ Literal["succeeded", "failed", "interrupted"],
+ Meta(
+ description="How a run ended. `succeeded` means its work settled without an\nexecution error or interruption. `failed` means an execution\nfailed or the host could not finish the cycle. `interrupted`\nmeans the cycle was cut short by interruption, even if an earlier\nexecution failed. Execution outcomes retain their individual results.\n"
+ ),
+]
+
+
+class RunRequest(Struct):
+ code: Annotated[
+ str, Meta(description="The Python code to run as scratch code.")
+ ]
+
+
+if TYPE_CHECKING:
+ RuntimeId = NewType("RuntimeId", str)
+else:
+ RuntimeId = NewType(
+ "RuntimeId",
+ Annotated[
+ str,
+ Meta(
+ description="Identifies a runtime. Unique within the host; every start and restart creates a new id.",
+ min_length=1,
+ ),
+ ],
+ )
+
+
+RuntimeStatus: TypeAlias = Annotated[
+ Literal["starting", "running", "terminating", "failed"],
+ Meta(
+ description="Where a runtime is in its life. A `starting` runtime is bringing\nits kernel up. A `running` runtime accepts work. A `terminating`\nruntime is shutting its kernel down. A `failed` runtime could not\nstart, or its kernel exited unexpectedly. A runtime that has\nended is removed rather than given a status.\n"
+ ),
+]
+
+
+class StartRuntimeRequest(Struct):
+ decisions: (
+ Annotated[
+ dict[str, str],
+ Meta(
+ description="Answers to the questions in a `decision-required` problem.\nEach key is a decision's `id` and each value is the `id` of\nthe chosen option. A client that already knows its choices can\nsend them the first time.\n"
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class UpdateNotebookRequest(Struct):
+ name: (
+ Annotated[str, Meta(description="The new label to show people.")]
+ | UnsetType
+ ) = UNSET
+ path: (
+ Annotated[
+ str,
+ Meta(
+ description="The new location, relative to the project root and written the way the host's operating system writes paths."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class ValueOutcome(Struct, tag_field="kind", tag="value"):
+ display: (
+ Annotated[
+ DisplayData,
+ Meta(
+ description="The value as last rendered. Replaced as it grows. Null when the code produced no value."
+ ),
+ ]
+ | None
+ )
+
+
+class Attachment(Struct):
+ id: AttachmentId
+ kind: Annotated[
+ str,
+ Meta(
+ description="What kind of thing is attached, such as `browser`, `editor`, or `agent`. Clients accept kinds they do not recognize."
+ ),
+ ]
+ name: (
+ Annotated[
+ str,
+ Meta(
+ description="A label to show people, such as the browser or editor's name. Null when there is none."
+ ),
+ ]
+ | None
+ )
+ notebook_id: NotebookId
+ since: Annotated[datetime, Meta(description="When it attached.")]
+
+
+class AttachmentMessage(Struct):
+ attachment: Attachment
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class Console(Struct):
+ execution_id: ExecutionId
+ id: ItemId
+ name: Annotated[
+ Literal["stdout", "stderr"],
+ Meta(description="Which stream the text went to."),
+ ]
+ seq: Annotated[
+ int,
+ Meta(
+ description="Position among the execution's items, increasing in the order they were produced.",
+ ge=0,
+ ),
+ ]
+ text: Annotated[str, Meta(description="The text, exactly as written.")]
+
+
+class ConsoleMessage(Struct):
+ console: Console
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class CreateNotebookRequest(Struct):
+ project_id: ProjectId
+ name: (
+ Annotated[
+ str,
+ Meta(
+ description="A label to show people. In a project with a root it defaults to the filename."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ path: (
+ Annotated[
+ str,
+ Meta(
+ description="Where to put the file, relative to the project root and written the way the host's operating system writes paths."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class Decision(Struct):
+ id: Annotated[
+ str,
+ Meta(
+ description="Identifies the question when the client answers it."
+ ),
+ ]
+ options: Annotated[
+ list[DecisionOption], Meta(description="The possible answers.")
+ ]
+ prompt: Annotated[
+ str, Meta(description="The question, worded for a person.")
+ ]
+
+
+class Display(Struct):
+ data: Annotated[
+ str,
+ Meta(
+ description="The rendered value. JSON mimetypes are encoded as text; binary mimetypes are base64. Never a URL only the runtime can serve."
+ ),
+ ]
+ execution_id: ExecutionId
+ id: ItemId
+ mimetype: Annotated[
+ str, Meta(description="The format of `data`, such as `image/png`.")
+ ]
+ seq: Annotated[
+ int,
+ Meta(
+ description="Position among the execution's items, increasing in the order they were produced.",
+ ge=0,
+ ),
+ ]
+
+
+class DisplayMessage(Struct):
+ display: Display
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class Error(Struct):
+ kind: Annotated[
+ str,
+ Meta(
+ description="The producer's identifier, scoped by source. Open; this RFC defines `exception`, `interrupted`, and `internal`. Clients show unrecognized kinds as plain errors."
+ ),
+ ]
+ message: Annotated[
+ str, Meta(description="A description of the error to show people.")
+ ]
+ name: (
+ Annotated[
+ str,
+ Meta(
+ description="The exception class, such as `ZeroDivisionError`. Set when kind is exception, null otherwise."
+ ),
+ ]
+ | None
+ )
+ range: (
+ Annotated[Range, Meta(description="Where in the code, when known.")]
+ | None
+ )
+ related: Annotated[
+ list[Related],
+ Meta(
+ description="Every involved cell, including this one, in canonical order. Each copy of a cross-cell error carries the same list; clients deduplicate on kind and related cell ids. Empty when the error involves this code alone."
+ ),
+ ]
+ severity: Annotated[
+ Literal["error", "warning", "information", "hint"],
+ Meta(
+ description="Error unless the producer says otherwise. Only error affects scheduling."
+ ),
+ ]
+ source: (
+ Annotated[
+ str,
+ Meta(
+ description="Who produced it, such as `marimo` or a SQL analyzer. Scopes kind."
+ ),
+ ]
+ | None
+ )
+ traceback: (
+ Annotated[
+ DisplayData,
+ Meta(
+ description="The traceback as rendered by the runtime, plain text or HTML by its mimetype. Null when unavailable or not shown."
+ ),
+ ]
+ | None
+ )
+
+
+class ErrorOutcome(Struct, tag_field="kind", tag="error"):
+ error: Error
+
+
+class HostRecord(Struct):
+ name: Annotated[
+ str,
+ Meta(
+ description="A label for the host to show people, such as `VS Code` or `marimo`. Two hosts can share a name; the filename is the identity."
+ ),
+ ]
+ process: Process
+ token: Annotated[
+ str,
+ Meta(
+ description="The secret a client sends to prove it read the record.",
+ min_length=1,
+ ),
+ ]
+ url: Annotated[
+ str,
+ Meta(
+ description="Where the host's API is. The scheme is `http`, and the host part is `127.0.0.1` or `[::1]`, written exactly that way."
+ ),
+ ]
+ version: Annotated[
+ Literal[1],
+ Meta(
+ description="The version of this record's format. This document describes version 1."
+ ),
+ ]
+
+
+class Notebook(Struct):
+ id: NotebookId
+ name: Annotated[
+ str,
+ Meta(
+ description="A label to show people. Derived from the filename when the host has nothing better."
+ ),
+ ]
+ operations: Annotated[
+ list[str],
+ Meta(
+ description="Operations this client may call on the notebook. A subset of `host.operations`, narrowed by permission and never by state; whether a runtime is attached shows in the `runtime` object, and preconditions still apply when an operation is called. The host sends the notebook again when it changes."
+ ),
+ ]
+ path: (
+ Annotated[
+ str,
+ Meta(
+ description="The file's path relative to the project root, written the way the host's operating system writes paths. Null when the notebook has no file, such as one not yet saved, or one deleted while a runtime still refers to it."
+ ),
+ ]
+ | None
+ )
+ project_id: ProjectId
+ updated_at: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the file was last modified, as of the host's last look at it. Null when the host does not know."
+ ),
+ ]
+ | None
+ )
+
+
+class NotebookMessage(Struct):
+ notebook: Notebook
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+Outcome: TypeAlias = Annotated[
+ ValueOutcome | ErrorOutcome | InterruptedOutcome,
+ Meta(
+ description="How an execution ended, tagged on `kind`. A `value` carries the\nexecution's value as last rendered; while the execution is\nrunning it is the value so far, and it is final once the\nexecution is `completed`. An `error` carries the error that ended it.\nAn `interrupted` execution was cancelled before or during execution. Other\nkinds are defined by later versions of this protocol.\n"
+ ),
+]
+
+
+class Problem(Struct):
+ status: Annotated[
+ int,
+ Meta(
+ description="The HTTP status code of the response.", ge=400, le=599
+ ),
+ ]
+ title: Annotated[
+ str,
+ Meta(
+ description="A short, human-readable name for the kind of problem."
+ ),
+ ]
+ type: Annotated[
+ str,
+ Meta(
+ description="What kind of problem this is, as a URI. The kinds this\nprotocol defines all start with `tag:marimo.io,2026:host/` and\nend with one of `invalid-request` (400), `unauthorized` (401),\n`forbidden` (403), `not-found` (404), `not-acceptable` (406),\n`conflict` (409), `no-runtime` (409), `decision-required`\n(409), `internal` (500), or `unsupported-operation` (501). A\nclient that sees a kind it does not recognize falls back to\n`status`.\n"
+ ),
+ ]
+ decisions: (
+ Annotated[
+ list[Decision],
+ Meta(
+ description="The choices the client has to make before the host can carry out the request. Only present for `decision-required`."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ detail: (
+ Annotated[
+ str,
+ Meta(
+ description="A human-readable explanation of what went wrong this time."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class Project(Struct):
+ id: ProjectId
+ message: (
+ Annotated[
+ str,
+ Meta(
+ description="Why the host stopped scanning. Null unless `status` is `partial`."
+ ),
+ ]
+ | None
+ )
+ name: Annotated[
+ str,
+ Meta(
+ description="A label to show people, usually the name of the root directory."
+ ),
+ ]
+ operations: Annotated[
+ list[str],
+ Meta(
+ description="Operations this client may call on the project, today `notebook.create`. A subset of `host.operations`, narrowed by permission and never by state. The host sends the project again when it changes."
+ ),
+ ]
+ root: (
+ Annotated[
+ str,
+ Meta(
+ description="The absolute path of the project's directory, written the way the host's operating system writes paths. Null when the project has no directory."
+ ),
+ ]
+ | None
+ )
+ status: ProjectStatus
+
+
+class ProjectMessage(Struct):
+ project: Project
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class Run(Struct):
+ caused_by: (
+ Annotated[
+ ExecutionId,
+ Meta(
+ description="The execution that caused this runtime-scheduled run. This records provenance, not membership in that execution's run, and does not extend the earlier run's lifetime. Null for a client request or when the runtime does not know the source."
+ ),
+ ]
+ | None
+ )
+ completed_at: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the run ended. Null until the run is `completed`."
+ ),
+ ]
+ | None
+ )
+ id: RunId
+ notebook_id: NotebookId
+ outcome: (
+ Annotated[
+ RunOutcome,
+ Meta(
+ description="Null until completed, then final. Published with the terminal status and completed_at. An execution failure does not complete a run while other work remains. Interruption must have taken effect, not merely been requested."
+ ),
+ ]
+ | None
+ )
+ started_at: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the first execution started. Null if none has started."
+ ),
+ ]
+ | None
+ )
+ status: Annotated[
+ Lifecycle,
+ Meta(
+ description="Queued until the first execution starts, running until the cycle has settled or been terminated, and completed once all member executions are terminal and no more can be scheduled in this run. A run can complete with no executions."
+ ),
+ ]
+
+
+class RunMessage(Struct):
+ run: Run
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class Runtime(Struct):
+ id: RuntimeId
+ marimo_version: (
+ Annotated[
+ str,
+ Meta(
+ description="The version of marimo running the kernel. Null until the host knows it."
+ ),
+ ]
+ | None
+ )
+ message: (
+ Annotated[
+ str,
+ Meta(
+ description="A note about the current status, such as progress while `starting` or the reason when `failed`. Null otherwise."
+ ),
+ ]
+ | None
+ )
+ notebook_id: NotebookId
+ started_at: Annotated[
+ datetime, Meta(description="When this runtime started.")
+ ]
+ status: RuntimeStatus
+
+
+class RuntimeMessage(Struct):
+ runtime: Runtime
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class Execution(Struct):
+ bindings: Annotated[
+ list[Binding],
+ Meta(
+ description="Names bound in the namespace, with a type and preview, stamped when the execution ends. Empty while running and for scratch code, whose bindings die with the execution."
+ ),
+ ]
+ caused_by: (
+ Annotated[
+ ExecutionId,
+ Meta(
+ description="The execution in the same run that caused this one. Null for executions requested directly."
+ ),
+ ]
+ | None
+ )
+ cell_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The cell this execution belongs to. Null for scratch code, a cell outside the document."
+ ),
+ ]
+ | None
+ )
+ code: (
+ Annotated[
+ str,
+ Meta(
+ description="The submitted code for an execution with no cell. Null for a cell's execution, since the cell holds its code."
+ ),
+ ]
+ | None
+ )
+ code_hash: Annotated[
+ str, Meta(description="A hash of the code that was evaluated.")
+ ]
+ completed_at: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the execution ended. Null until it is completed."
+ ),
+ ]
+ | None
+ )
+ id: ExecutionId
+ outcome: (
+ Annotated[
+ Outcome,
+ Meta(
+ description="How the execution ended. Null while queued; while running, a value carries the display so far; final once completed."
+ ),
+ ]
+ | None
+ )
+ run_id: (
+ Annotated[
+ RunId,
+ Meta(
+ description="The run that owns this execution. Every live execution belongs to exactly one run. May name a run the host has dropped. Null only for a restored result whose run is unknown."
+ ),
+ ]
+ | None
+ )
+ runtime_id: (
+ Annotated[
+ RuntimeId,
+ Meta(
+ description="The runtime that produced this execution. Live when it equals the current runtime's id. Null when the producer is unknown."
+ ),
+ ]
+ | None
+ )
+ stale: (
+ Annotated[
+ bool,
+ Meta(
+ description="Whether an input changed since this result was produced. Null for scratch code, which has no inputs in the graph."
+ ),
+ ]
+ | None
+ )
+ started_at: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the code started executing. Null while queued and for an execution that never ran."
+ ),
+ ]
+ | None
+ )
+ status: Lifecycle
+
+
+class ExecutionMessage(Struct):
+ execution: Execution
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
diff --git a/marimo/_core/stream.py b/marimo/_core/stream.py
new file mode 100644
index 0000000000..cbb545b7c2
--- /dev/null
+++ b/marimo/_core/stream.py
@@ -0,0 +1,232 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Ordered events with subscriptions and cursor-based replay.
+
+Catalog and notebook streams filter a shared log. Clients resume each
+stream from the last event id received on that stream.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import deque
+from collections.abc import Callable, Collection
+from copy import deepcopy
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TypeAlias
+
+import msgspec
+from msgspec import UNSET
+
+from marimo._core import protocol
+
+LOGGER = logging.getLogger(__name__)
+
+CATALOG_KINDS = frozenset(
+ {"host", "project", "notebook", "runtime", "attachment"}
+)
+NOTEBOOK_KINDS = frozenset(
+ {
+ "notebook",
+ "runtime",
+ "attachment",
+ "run",
+ "execution",
+ "console",
+ "display",
+ }
+)
+
+Body: TypeAlias = (
+ protocol.Host
+ | protocol.Project
+ | protocol.Notebook
+ | protocol.Runtime
+ | protocol.Attachment
+ | protocol.Run
+ | protocol.Execution
+ | protocol.Console
+ | protocol.Display
+)
+
+_WRAPPERS: dict[str, type[msgspec.Struct]] = {
+ "host": protocol.HostMessage,
+ "project": protocol.ProjectMessage,
+ "notebook": protocol.NotebookMessage,
+ "runtime": protocol.RuntimeMessage,
+ "attachment": protocol.AttachmentMessage,
+ "run": protocol.RunMessage,
+ "execution": protocol.ExecutionMessage,
+ "console": protocol.ConsoleMessage,
+ "display": protocol.DisplayMessage,
+}
+
+
+def kind_of(body: Body) -> str:
+ """Return the object's event kind, used by the `types` filter."""
+ return type(body).__name__.lower()
+
+
+def message(
+ body: Body,
+ *,
+ request_id: str | None = None,
+ time: datetime | None = None,
+) -> msgspec.Struct:
+ """Wrap an object in its protocol message."""
+ kind = kind_of(body)
+ return _WRAPPERS[kind](
+ **{kind: deepcopy(body)},
+ request_id=UNSET if request_id is None else request_id,
+ time=UNSET if time is None else time,
+ )
+
+
+def utcnow() -> datetime:
+ return datetime.now(timezone.utc)
+
+
+@dataclass(frozen=True)
+class Event:
+ """An event with an optional replay cursor and notebook scope.
+
+ Snapshot events have no `id`; `ready` and `reset` have no `data`.
+ """
+
+ name: str
+ data: msgspec.Struct | None = None
+ id: int | None = None
+ notebook_id: protocol.NotebookId | None = None
+ run_id: protocol.RunId | None = None
+
+ @property
+ def kind(self) -> str:
+ """The object kind without the `.removed` suffix."""
+ return self.name.partition(".")[0]
+
+ def visible_in(self, notebook_id: str | None) -> bool:
+ """Whether the event belongs in the catalog or notebook stream."""
+ if notebook_id is None:
+ return self.kind in CATALOG_KINDS
+ return self.notebook_id == notebook_id and self.kind in NOTEBOOK_KINDS
+
+ def wanted(
+ self, types: Collection[str] | None, run_id: str | None = None
+ ) -> bool:
+ """Apply kind and run filters, always including `ready` and `reset`."""
+ if self.name in ("ready", "reset"):
+ return True
+ return (types is None or self.kind in types) and (
+ run_id is None or self.run_id == run_id
+ )
+
+
+Listener = Callable[[Event], None]
+
+
+class Stream:
+ """An ordered event log with bounded history and live subscriptions.
+
+ Callers serialize access on one thread. Published objects and returned
+ events are copied so readers cannot mutate the log or each other's data.
+ """
+
+ def __init__(self, *, history: int = 1000) -> None:
+ self._last_id = 0
+ self._history: deque[Event] = deque(maxlen=history)
+ self._listeners: list[Listener] = []
+ self._pending: deque[tuple[Event, tuple[Listener, ...]]] = deque()
+ self._dispatching = False
+
+ @property
+ def last_id(self) -> int:
+ return self._last_id
+
+ def publish(
+ self,
+ body: Body,
+ *,
+ notebook_id: protocol.NotebookId | None = None,
+ request_id: str | None = None,
+ run_id: protocol.RunId | None = None,
+ ) -> Event:
+ """Publish a new or updated object."""
+ kind = kind_of(body)
+ data = message(body, request_id=request_id, time=utcnow())
+ return self._append(
+ Event(kind, data, notebook_id=notebook_id, run_id=run_id)
+ )
+
+ def remove(
+ self,
+ kind: str,
+ object_id: str,
+ *,
+ notebook_id: protocol.NotebookId | None = None,
+ request_id: str | None = None,
+ run_id: protocol.RunId | None = None,
+ ) -> Event:
+ """Publish an object's removal."""
+ data = protocol.RemovedMessage(
+ id=object_id,
+ request_id=UNSET if request_id is None else request_id,
+ time=utcnow(),
+ )
+ return self._append(
+ Event(
+ f"{kind}.removed", data, notebook_id=notebook_id, run_id=run_id
+ )
+ )
+
+ def since(self, cursor: int) -> list[Event] | None:
+ """Return events after `cursor`, or `None` for a stale or future cursor."""
+ if cursor == self._last_id:
+ return []
+ if cursor > self._last_id:
+ return None
+ oldest = self._history[0].id if self._history else self._last_id + 1
+ assert oldest is not None
+ if cursor < oldest - 1:
+ return None
+ return deepcopy(
+ [e for e in self._history if e.id is not None and e.id > cursor]
+ )
+
+ def subscribe(self, listener: Listener) -> Callable[[], None]:
+ """Deliver future events in order; return an unsubscribe function.
+
+ Subscriber exceptions are logged without interrupting publication.
+ Events published by a subscriber follow the event being delivered.
+ """
+ self._listeners.append(listener)
+
+ def unsubscribe() -> None:
+ if listener in self._listeners:
+ self._listeners.remove(listener)
+
+ return unsubscribe
+
+ def _append(self, event: Event) -> Event:
+ self._last_id += 1
+ stamped = Event(
+ event.name,
+ event.data,
+ self._last_id,
+ event.notebook_id,
+ event.run_id,
+ )
+ self._history.append(stamped)
+ self._pending.append((stamped, tuple(self._listeners)))
+ if not self._dispatching:
+ self._dispatching = True
+ try:
+ while self._pending:
+ pending, listeners = self._pending.popleft()
+ for listener in listeners:
+ try:
+ listener(deepcopy(pending))
+ except Exception:
+ LOGGER.exception("Error delivering host event")
+ finally:
+ self._dispatching = False
+ return deepcopy(stamped)
diff --git a/pyproject.toml b/pyproject.toml
index 68430d8ccd..badb23b9be 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -542,6 +542,9 @@ markers = [
"network: requires internet access to package indexes (deselect with '-m \"not network\"')",
]
+[tool.inline-snapshot]
+format-command = 'ruff format --stdin-filename "{filename}"'
+
[tool.coverage.run]
omit = ["marimo/_tutorials/*"]
diff --git a/scripts/check_core_imports.py b/scripts/check_core_imports.py
new file mode 100755
index 0000000000..6e39b4c83d
--- /dev/null
+++ b/scripts/check_core_imports.py
@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Check that `marimo._core` imports no other marimo modules.
+
+Includes imports inside functions and `TYPE_CHECKING` blocks.
+
+Usage: check_core_imports.py [FILE_OR_DIR ...]
+
+Defaults to the core package.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CORE = REPO_ROOT / "marimo" / "_core"
+PACKAGE = "marimo._core"
+
+
+def is_outside_core(module: str) -> bool:
+ """Whether `module` names a marimo module outside the core package."""
+ if module == PACKAGE or module.startswith(PACKAGE + "."):
+ return False
+ return module == "marimo" or module.startswith("marimo.")
+
+
+def offending_imports(path: Path) -> list[tuple[int, str]]:
+ """Return `(line, module)` pairs for disallowed imports."""
+ tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+ found: list[tuple[int, str]] = []
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Import):
+ found.extend(
+ (node.lineno, alias.name)
+ for alias in node.names
+ if is_outside_core(alias.name)
+ )
+ elif isinstance(node, ast.ImportFrom):
+ if node.level:
+ # Absolute imports make the target package explicit.
+ found.append(
+ (node.lineno, "." * node.level + (node.module or ""))
+ )
+ elif node.module is not None and is_outside_core(node.module):
+ found.append((node.lineno, node.module))
+ return found
+
+
+def python_files(targets: list[Path]) -> list[Path]:
+ files: list[Path] = []
+ for target in targets:
+ if target.is_dir():
+ files.extend(sorted(target.rglob("*.py")))
+ else:
+ files.append(target)
+ return files
+
+
+def main(argv: list[str]) -> int:
+ targets = [Path(arg) for arg in argv] or [CORE]
+ failures = 0
+ for path in python_files(targets):
+ for line, module in offending_imports(path):
+ print(f"{path}:{line}: imports {module}", file=sys.stderr)
+ failures += 1
+ if failures:
+ print(
+ f"\n{PACKAGE} must not import from the rest of marimo "
+ f"({failures} violation{'s' if failures != 1 else ''}).",
+ file=sys.stderr,
+ )
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/scripts/pycheck.sh b/scripts/pycheck.sh
index 694caaf205..15d59b7f86 100755
--- a/scripts/pycheck.sh
+++ b/scripts/pycheck.sh
@@ -6,6 +6,8 @@ echo "[check: copyright]"
./scripts/pycopyright.sh
echo "[check: lint]"
uv run ruff check --fix
+echo "[check: core imports]"
+uv run python scripts/check_core_imports.py || exit $?
echo "[check: format]"
uv run ruff format
echo "[check: typecheck]"
diff --git a/tests/_core/__init__.py b/tests/_core/__init__.py
new file mode 100644
index 0000000000..fe2d2e388e
--- /dev/null
+++ b/tests/_core/__init__.py
@@ -0,0 +1 @@
+# Copyright 2026 Marimo. All rights reserved.
diff --git a/tests/_core/conftest.py b/tests/_core/conftest.py
new file mode 100644
index 0000000000..92e592ac8b
--- /dev/null
+++ b/tests/_core/conftest.py
@@ -0,0 +1,88 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host fixtures with a backend that records commands."""
+
+from __future__ import annotations
+
+import pytest
+
+from marimo._core import protocol
+from marimo._core.host import Host
+from marimo._core.notebook import Notebook
+from marimo._core.stream import Event
+
+OPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]
+
+
+class ScriptedBackend:
+ """Records backend commands without executing them."""
+
+ def __init__(self) -> None:
+ self.calls: list[tuple[object, ...]] = []
+
+ def start(self, runtime_id: str) -> None:
+ self.calls.append(("start", runtime_id))
+
+ def stop(self) -> None:
+ self.calls.append(("stop",))
+
+ def run(self, run_id: str, code: str) -> None:
+ self.calls.append(("run", run_id, code))
+
+ def interrupt(self, run_id: str) -> None:
+ self.calls.append(("interrupt", run_id))
+
+
+def project(project_id: str = "p1") -> protocol.Project:
+ return protocol.Project(
+ id=protocol.ProjectId(project_id),
+ name="forecasting",
+ root="/Users/me/forecasting",
+ status="indexed",
+ message=None,
+ operations=["notebook.create"],
+ )
+
+
+def record(
+ notebook_id: str = "n1", path: str = "forecasts.py"
+) -> protocol.Notebook:
+ return protocol.Notebook(
+ id=protocol.NotebookId(notebook_id),
+ project_id=protocol.ProjectId("p1"),
+ path=path,
+ name=path.removesuffix(".py"),
+ operations=["runtime.start", "runtime.run"],
+ updated_at=None,
+ )
+
+
+def host() -> Host:
+ return Host(operations=OPERATIONS)
+
+
+def backend() -> ScriptedBackend:
+ return ScriptedBackend()
+
+
+def notebook(host: Host, backend: ScriptedBackend) -> Notebook:
+ host.update_project(project())
+ return host.add_notebook(record(), backend)
+
+
+def log(host: Host) -> list[Event]:
+ """Collect events published during the test."""
+ events: list[Event] = []
+ host.subscribe(events.append, notebook_id="n1")
+ return events
+
+
+def names(events: list[Event]) -> list[str]:
+ return [e.name for e in events]
+
+
+def request_ids(events: list[Event]) -> list[object]:
+ return [getattr(e.data, "request_id", None) for e in events]
diff --git a/tests/_core/test_core_imports.py b/tests/_core/test_core_imports.py
new file mode 100644
index 0000000000..9513fc731c
--- /dev/null
+++ b/tests/_core/test_core_imports.py
@@ -0,0 +1,92 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""`marimo._core` imports nothing from the rest of marimo."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CHECK = REPO_ROOT / "scripts" / "check_core_imports.py"
+
+
+def run_check(*args: str) -> subprocess.CompletedProcess[str]:
+ return subprocess.run(
+ [sys.executable, str(CHECK), *args],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+
+
+def test_static_check_allows_core_and_external_imports(tmp_path: Path) -> None:
+ module = tmp_path / "allowed.py"
+ module.write_text(
+ "import dataclasses\n"
+ "import msgspec\n"
+ "import marimo._core.protocol\n"
+ "from marimo._core import protocol\n"
+ )
+ result = run_check(str(module))
+ assert result.returncode == 0, result.stderr
+
+
+def test_static_check_sees_through_functions_and_type_checking(
+ tmp_path: Path,
+) -> None:
+ module = tmp_path / "leaky.py"
+ module.write_text(
+ "from typing import TYPE_CHECKING\n"
+ "from marimo._core import protocol\n"
+ "if TYPE_CHECKING:\n"
+ " from marimo._types.ids import NotebookId\n"
+ "def later():\n"
+ " import marimo._utils.code\n"
+ " from marimo import _loggers\n"
+ )
+ result = run_check(str(module))
+ assert result.returncode == 1
+ assert "leaky.py:4: imports marimo._types.ids" in result.stderr
+ assert "leaky.py:6: imports marimo._utils.code" in result.stderr
+ assert "leaky.py:7: imports marimo" in result.stderr
+
+
[email protected](sys.platform == "win32", reason="pycheck.sh uses POSIX sh")
+def test_pycheck_propagates_core_import_failure(tmp_path: Path) -> None:
+ module = tmp_path / "leaky.py"
+ module.write_text("from marimo import _loggers\n")
+ checker = shlex.join([sys.executable, str(CHECK), str(module)])
+ uv = tmp_path / "uv"
+ uv.write_text(
+ "#!/bin/sh\n"
+ 'case "$*" in\n'
+ f" *check_core_imports.py*) exec {checker};;\n"
+ " *) exit 0;;\n"
+ "esac\n"
+ )
+ uv.chmod(0o755)
+ scripts = tmp_path / "scripts"
+ scripts.mkdir()
+ copyright_check = scripts / "pycopyright.sh"
+ copyright_check.write_text("#!/bin/sh\nexit 0\n")
+ copyright_check.chmod(0o755)
+
+ result = subprocess.run(
+ ["sh", str(REPO_ROOT / "scripts" / "pycheck.sh")],
+ cwd=tmp_path,
+ env={
+ **os.environ,
+ "PATH": f"{tmp_path}{os.pathsep}{os.environ['PATH']}",
+ },
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+
+ assert result.returncode == 1
+ assert "imports marimo" in result.stderr
diff --git a/tests/_core/test_host.py b/tests/_core/test_host.py
new file mode 100644
index 0000000000..3d1512b127
--- /dev/null
+++ b/tests/_core/test_host.py
@@ -0,0 +1,293 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host catalogs, snapshots, and event subscriptions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from msgspec import UNSET
+from msgspec.structs import replace
+
+from marimo._core import backend as be, protocol
+from marimo._core.errors import NotFound
+from marimo._core.host import Host
+from marimo._core.stream import Event
+from tests._core.conftest import (
+ ScriptedBackend,
+ names,
+ project,
+ record,
+)
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+ from marimo._core.notebook import Notebook
+
+
+def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:
+ host.update_project(project())
+ notebook = host.add_notebook(record(), ScriptedBackend())
+ notebook.start()
+ notebook.observe(be.Running())
+ notebook.run("1", request_id="r1")
+ cursor = host.events()[-1].id
+ assert cursor is not None
+
+ notebook.observe(
+ be.Planned(
+ protocol.RunId("r1"),
+ (be.PlannedExecution(protocol.ExecutionId("e1"), None, "h", "1"),),
+ )
+ )
+ notebook.attach()
+
+ events = host.events()
+ assert names(events) == [
+ "host",
+ "project",
+ "notebook",
+ "runtime",
+ "attachment",
+ "ready",
+ ]
+ assert all(e.id is None for e in events[:-1])
+ assert events[-1].id == cursor + 2
+ assert all(getattr(e.data, "time", None) is UNSET for e in events[:-1])
+ assert names(host.events(cursor)) == ["attachment", "ready"]
+
+
+def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:
+ host.update_project(project())
+ first = host.add_notebook(record("n1", "a.py"), ScriptedBackend())
+ second = host.add_notebook(record("n2", "b.py"), ScriptedBackend())
+ first.start()
+ first.observe(be.Running())
+ first.run("1", request_id="r1")
+ first.observe(
+ be.Planned(
+ protocol.RunId("r1"),
+ (be.PlannedExecution(protocol.ExecutionId("e1"), None, "h", "1"),),
+ )
+ )
+ second.start()
+
+ events = host.events(notebook_id="n1")
+ assert names(events) == [
+ "notebook",
+ "runtime",
+ "run",
+ "execution",
+ "ready",
+ ]
+ assert all(e.notebook_id == "n1" for e in events[:-1])
+
+ # Replay includes both starting and running states for n1.
+ live = host.events(0, notebook_id="n1")
+ assert names(live) == [
+ "notebook",
+ "runtime",
+ "runtime",
+ "run",
+ "execution",
+ "ready",
+ ]
+ assert all(e.id is not None for e in live)
+
+ with pytest.raises(NotFound):
+ host.events(notebook_id="n3")
+
+
+def test_resume_replays_or_resets() -> None:
+ small = Host(operations=[], history=2)
+ small.update_project(project())
+ small.add_notebook(record(), ScriptedBackend())
+ cursor = small.events()[-1].id
+ assert cursor is not None
+
+ assert names(small.events(cursor)) == ["ready"]
+ small.update_project(project("p2"))
+ assert names(small.events(cursor)) == ["project", "ready"]
+ small.update_project(project("p3"))
+ small.update_project(project("p4"))
+ assert names(small.events(cursor))[0] == "reset"
+ assert names(small.events(10**6))[0] == "reset"
+
+
+def test_types_filter_keeps_ready_and_reset(host: Host) -> None:
+ host.update_project(project())
+ host.add_notebook(record(), ScriptedBackend())
+ assert names(host.events(types={"notebook"})) == ["notebook", "ready"]
+ assert names(host.events(10**6, types={"notebook"})) == [
+ "reset",
+ "notebook",
+ "ready",
+ ]
+
+
+def test_subscribe_filters_the_live_stream(host: Host) -> None:
+ host.update_project(project())
+ notebook = host.add_notebook(record(), ScriptedBackend())
+ catalog: list[Event] = []
+ mine: list[Event] = []
+ runtimes: list[Event] = []
+ host.subscribe(catalog.append)
+ host.subscribe(mine.append, notebook_id="n1")
+ unsubscribe = host.subscribe(runtimes.append, types={"runtime"})
+
+ notebook.start()
+ notebook.observe(be.Running())
+ notebook.run("1", request_id="r1")
+ unsubscribe()
+ host.update_project(project("p2"))
+
+ assert names(catalog) == ["runtime", "runtime", "project"]
+ assert names(mine) == ["runtime", "runtime", "run"]
+ assert names(runtimes) == ["runtime", "runtime"]
+
+
+def test_removing_a_notebook_removes_what_it_owns_first(host: Host) -> None:
+ host.update_project(project())
+ notebook = host.add_notebook(record(), ScriptedBackend())
+ notebook.start()
+ notebook.observe(be.Running())
+ notebook.attach()
+ notebook.run("1", request_id="r1")
+ log: list[Event] = []
+ host.subscribe(log.append, notebook_id="n1")
+
+ host.remove_notebook("n1", request_id="req-del")
+
+ assert names(log) == [
+ "run.removed",
+ "attachment.removed",
+ "runtime.removed",
+ "notebook.removed",
+ ]
+ assert getattr(log[-1].data, "request_id", None) == "req-del"
+ assert "n1" not in host.notebooks
+ with pytest.raises(NotFound):
+ host.notebook(notebook.id)
+ host.remove_notebook("n1") # Repeated removal is a no-op.
+
+
+def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:
+ host.update_project(project())
+ backend = ScriptedBackend()
+ notebook = host.add_notebook(record(), backend)
+ notebook.start()
+ notebook.observe(be.Running())
+ notebook.run("1", request_id="run")
+ runtime = notebook.runtime
+ backend.calls.clear()
+ log: list[Event] = []
+ host.subscribe(log.append, notebook_id="n1")
+
+ host.update_notebook(record())
+ host.update_project(project())
+ moved = record(path="moved.py")
+ host.update_notebook(moved, request_id="req-mv")
+
+ assert host.notebooks[notebook.id] == moved
+ assert host.notebook("n1") is notebook
+ assert notebook.runtime is runtime
+ assert backend.calls == []
+ assert notebook.run("1", request_id="run").id == "run"
+ assert host.events(notebook_id="n1")[0].data == protocol.NotebookMessage(
+ notebook=moved
+ )
+ assert host.events(types={"notebook"})[0].data == protocol.NotebookMessage(
+ notebook=moved
+ )
+ assert names(log) == ["notebook"]
+ assert getattr(log[0].data, "request_id", None) == "req-mv"
+ with pytest.raises(NotFound):
+ host.update_notebook(record("n9"))
+ with pytest.raises(ValueError, match="project"):
+ host.update_notebook(
+ replace(moved, project_id=protocol.ProjectId("missing"))
+ )
+ assert host.notebooks[notebook.id] == moved
+
+
+def test_removed_notebook_handles_cannot_be_reused(
+ host: Host,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+) -> None:
+ notebook.start()
+ notebook.observe(be.Running())
+ run = notebook.run("1", request_id="r1")
+ attachment = notebook.attach()
+ retained_id = notebook.id
+ host.remove_notebook(retained_id)
+ backend.calls.clear()
+ log.clear()
+
+ commands: list[Callable[[], object]] = [
+ notebook.start,
+ notebook.stop,
+ notebook.restart,
+ lambda: notebook.run("1", request_id=run.id),
+ lambda: notebook.interrupt(run.id),
+ notebook.attach,
+ ]
+ for command in commands:
+ with pytest.raises(NotFound, match="no notebook"):
+ command()
+
+ # Late backend updates and disconnect cleanup cannot revive the notebook.
+ notebook.observe(be.Starting("Late startup"))
+ notebook.observe(be.Running())
+ notebook.observe(be.Exited())
+ notebook.detach(attachment.id)
+ host.remove_notebook(retained_id)
+
+ assert backend.calls == []
+ assert log == []
+ assert notebook.runtime is None
+
+
+def test_catalog_requires_the_project(host: Host) -> None:
+ with pytest.raises(ValueError, match="project"):
+ host.add_notebook(record(), ScriptedBackend())
+ host.update_project(project())
+ host.add_notebook(record(), ScriptedBackend())
+ with pytest.raises(ValueError, match="already"):
+ host.add_notebook(record(), ScriptedBackend())
+
+
+def test_catalog_updates_do_not_share_mutable_records(host: Host) -> None:
+ source = project()
+ host.update_project(source)
+ source.name = "changed"
+ source.operations.clear()
+ host.update_project(source)
+
+ replay = host.events(0, types={"project"})
+ projects = [
+ e.data.project
+ for e in replay
+ if isinstance(e.data, protocol.ProjectMessage)
+ ]
+ assert projects == [
+ project(),
+ replace(project(), name="changed", operations=[]),
+ ]
+
+ original = record()
+ host.add_notebook(original, ScriptedBackend())
+ original.name = "caller mutation"
+ original.operations.clear()
+ view = host.notebooks[original.id]
+ view.name = "reader mutation"
+ view.operations.clear()
+ assert host.notebooks[original.id] == record()
+
+ host.update_notebook(original)
+ original.name = "another mutation"
+ assert host.notebooks[original.id] == replace(
+ record(), name="caller mutation", operations=[]
+ )
diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.py
new file mode 100644
index 0000000000..d51dcb95f1
--- /dev/null
+++ b/tests/_core/test_notebook.py
@@ -0,0 +1,838 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Notebook commands and state updates from backend messages."""
+
+from __future__ import annotations
+
+import pytest
+from dirty_equals import IsDatetime
+from inline_snapshot import snapshot
+from msgspec import UNSET
+
+from marimo._core import backend as be
+from marimo._core.errors import Conflict, NoRuntime, NotFound
+from marimo._core.host import Host
+from marimo._core.notebook import Notebook
+from marimo._core.protocol import (
+ Console,
+ ConsoleMessage,
+ DisplayData,
+ Error,
+ ErrorOutcome,
+ Execution,
+ ExecutionId,
+ ExecutionMessage,
+ InterruptedOutcome,
+ ItemId,
+ NotebookId,
+ Run,
+ RunId,
+ RunMessage,
+ RunOutcome,
+ Runtime,
+ ValueOutcome,
+)
+from marimo._core.stream import Event
+from tests._core.conftest import ScriptedBackend, names, request_ids
+
+
+def running(notebook: Notebook, backend: ScriptedBackend) -> Runtime:
+ notebook.start(request_id="req-start")
+ notebook.observe(be.Running(marimo_version="0.25.0"))
+ backend.calls.clear()
+ assert notebook.runtime is not None
+ return notebook.runtime
+
+
+def scratch(notebook: Notebook, run_id: str = "run-1") -> Run:
+ run = notebook.run("3 * 3", request_id=run_id)
+ notebook.observe(
+ be.Planned(
+ run.id,
+ (be.PlannedExecution(ExecutionId("e1"), None, "9f", "3 * 3"),),
+ )
+ )
+ notebook.observe(be.Status(ExecutionId("e1"), "running"))
+ return run
+
+
+class TestStart:
+ def test_starts_a_runtime_and_asks_the_backend(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ runtime, created = notebook.start(request_id="req-1")
+
+ assert created
+ assert runtime.status == "starting"
+ assert backend.calls == [("start", runtime.id)]
+ assert names(log) == ["runtime"]
+ assert request_ids(log) == ["req-1"]
+
+ def test_returns_an_existing_runtime_without_starting(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ first, _ = notebook.start()
+ again, created = notebook.start()
+
+ assert not created
+ assert again == first
+ assert backend.calls == [("start", first.id)]
+ assert names(log) == ["runtime"]
+
+ def test_request_follows_the_runtime_until_it_settles(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ notebook.start(request_id="req-1")
+ notebook.observe(be.Starting("Preparing the environment"))
+ notebook.observe(be.Running(marimo_version="0.25.0"))
+ notebook.attach()
+
+ assert names(log) == ["runtime", "runtime", "runtime", "attachment"]
+ assert request_ids(log) == ["req-1", "req-1", "req-1", UNSET]
+ assert notebook.runtime is not None
+ assert notebook.runtime.status == "running"
+ assert notebook.runtime.marimo_version == "0.25.0"
+ assert notebook.runtime.message is None
+
+ def test_a_kernel_that_never_comes_up_fails(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ notebook.start(request_id="req-1")
+ notebook.observe(be.Exited("No such environment"))
+
+ assert notebook.runtime is not None
+ assert notebook.runtime.status == "failed"
+ assert notebook.runtime.message == "No such environment"
+ assert request_ids(log) == ["req-1", "req-1"]
+
+
+class TestStop:
+ def test_stop_cancels_a_pending_restart(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ running(notebook, backend)
+ notebook.restart(request_id="restart")
+ notebook.stop(request_id="stop")
+ log.clear()
+
+ notebook.observe(be.Exited())
+
+ assert notebook.runtime is None
+ assert backend.calls == [("stop",)]
+ assert names(log) == ["runtime.removed"]
+ assert request_ids(log) == ["stop"]
+
+ def test_needs_a_runtime(self, notebook: Notebook) -> None:
+ with pytest.raises(NoRuntime):
+ notebook.stop()
+
+ def test_terminates_then_removes_once_the_kernel_is_gone(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ running(notebook, backend)
+ log.clear()
+
+ runtime = notebook.stop(request_id="req-stop")
+ assert runtime.status == "terminating"
+ assert backend.calls == [("stop",)]
+
+ notebook.observe(be.Exited("Stopped"))
+ assert notebook.runtime is None
+ assert names(log) == ["runtime", "runtime.removed"]
+ assert request_ids(log) == ["req-stop", "req-stop"]
+
+ def test_ends_runs_in_flight_and_retains_results(
+ self,
+ host: Host,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+ ) -> None:
+ running(notebook, backend)
+ scratch(notebook)
+ notebook.observe(be.Produced(console("o1", "e1", "hi\n")))
+ log.clear()
+
+ notebook.stop()
+ notebook.observe(be.Exited())
+
+ assert names(log) == [
+ "runtime",
+ "execution",
+ "run",
+ "runtime.removed",
+ ]
+ interrupted = log[1].data
+ assert isinstance(interrupted, ExecutionMessage)
+ assert interrupted.execution.status == "completed"
+ assert isinstance(interrupted.execution.outcome, InterruptedOutcome)
+ assert names(host.events(notebook_id=notebook.id)) == [
+ "notebook",
+ "run",
+ "execution",
+ "console",
+ "ready",
+ ]
+
+ def test_a_failed_runtime_is_removed_at_once(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ notebook.start()
+ notebook.observe(be.Exited("boom"))
+ backend.calls.clear()
+ log.clear()
+
+ terminating = notebook.stop()
+
+ assert terminating.status == "terminating"
+ assert notebook.runtime is None
+ assert backend.calls == []
+ assert names(log) == ["runtime", "runtime.removed"]
+
+ def test_keeps_completed_results_when_stopped(
+ self,
+ host: Host,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+ ) -> None:
+ running(notebook, backend)
+ scratch(notebook)
+ notebook.observe(be.Produced(console("o1", "e1", "x")))
+ notebook.observe(be.Concluded(ExecutionId("e1"), value("")))
+ notebook.observe(be.Status(ExecutionId("e1"), "completed"))
+ notebook.observe(be.Done(RunId("run-1"), "succeeded"))
+ log.clear()
+
+ notebook.stop(request_id="stop")
+ notebook.observe(be.Exited())
+
+ assert names(log) == [
+ "runtime",
+ "runtime.removed",
+ ]
+ assert request_ids(log) == ["stop", "stop"]
+ assert names(host.events(notebook_id=notebook.id)) == [
+ "notebook",
+ "run",
+ "execution",
+ "console",
+ "ready",
+ ]
+
+
+class TestRestart:
+ def test_only_a_running_runtime_restarts(self, notebook: Notebook) -> None:
+ with pytest.raises(NoRuntime):
+ notebook.restart()
+ notebook.start()
+ with pytest.raises(Conflict):
+ notebook.restart()
+
+ def test_replaces_the_runtime_and_keeps_old_results(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ before = running(notebook, backend)
+ scratch(notebook)
+ backend.calls.clear()
+ log.clear()
+
+ response = notebook.restart(request_id="req-restart")
+ assert response.id != before.id
+ assert response.status == "starting"
+ assert notebook.runtime is not None
+ assert notebook.runtime.id == before.id
+ assert notebook.runtime.status == "terminating"
+ assert backend.calls == [("stop",)]
+ notebook.observe(be.Exited())
+ assert notebook.runtime is not None
+ assert notebook.runtime.id == response.id
+ assert backend.calls == [("stop",), ("start", notebook.runtime.id)]
+ notebook.observe(be.Running(marimo_version="0.25.0"))
+
+ after = notebook.runtime
+ assert after is not None
+ assert after.id != before.id
+ assert after.status == "running"
+ assert after.started_at >= before.started_at
+ assert names(log) == [
+ "runtime",
+ "execution",
+ "run",
+ "runtime.removed",
+ "runtime",
+ "runtime",
+ ]
+ execution = log[1].data
+ assert isinstance(execution, ExecutionMessage)
+ assert execution.execution.runtime_id == before.id
+ assert request_ids(log)[0] == "req-restart"
+ assert request_ids(log)[-1] == "req-restart"
+
+
+class TestAdoption:
+ @pytest.mark.parametrize("reports_starting", [False, True])
+ def test_external_relaunch_recovers_a_failed_runtime(
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ host: Host,
+ reports_starting: bool,
+ ) -> None:
+ before = running(notebook, backend)
+ scratch(notebook)
+ notebook.observe(be.Exited("Kernel exited"))
+ backend.calls.clear()
+
+ if reports_starting:
+ notebook.observe(be.Starting("Relaunching"))
+ notebook.observe(be.Running("0.26.0"))
+
+ assert notebook.runtime is not None
+ assert notebook.runtime.id != before.id
+ assert notebook.runtime.marimo_version == "0.26.0"
+ assert names(host.events(notebook_id=notebook.id)) == [
+ "notebook",
+ "runtime",
+ "run",
+ "execution",
+ "ready",
+ ]
+ assert backend.calls == []
+ notebook.run("1", request_id="after-relaunch")
+ assert backend.calls == [("run", "after-relaunch", "1")]
+
+ def test_a_kernel_someone_else_started_is_published(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ notebook.observe(be.Starting("Starting the kernel"))
+ notebook.observe(be.Running(marimo_version="0.25.0"))
+
+ assert backend.calls == []
+ assert notebook.runtime is not None
+ assert notebook.runtime.status == "running"
+ assert names(log) == ["runtime", "runtime"]
+
+ def test_a_kernel_that_dies_on_its_own_fails_and_keeps_results(
+ self,
+ host: Host,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+ ) -> None:
+ running(notebook, backend)
+ scratch(notebook)
+ log.clear()
+
+ notebook.observe(be.Exited("killed"))
+
+ assert notebook.runtime is not None
+ assert notebook.runtime.status == "failed"
+ assert notebook.runtime.message == "killed"
+ assert names(log) == ["execution", "run", "runtime"]
+ [run] = [
+ event.data.run
+ for event in host.events(notebook_id=notebook.id)
+ if isinstance(event.data, RunMessage)
+ ]
+ assert run.status == "completed"
+
+
+def console(
+ item_id: str, execution_id: str, text: str, seq: int = 0
+) -> Console:
+ return Console(
+ id=ItemId(item_id),
+ execution_id=ExecutionId(execution_id),
+ seq=seq,
+ name="stdout",
+ text=text,
+ )
+
+
+def value(data: str) -> ValueOutcome:
+ return ValueOutcome(display=DisplayData(mimetype="text/html", data=data))
+
+
+class TestRun:
+ def test_run_filter_preserves_output_ownership_and_replay(
+ self, host: Host, notebook: Notebook, backend: ScriptedBackend
+ ) -> None:
+ running(notebook, backend)
+ run = scratch(notebook)
+ notebook.observe(be.Concluded(ExecutionId("e1"), value("9")))
+ notebook.observe(be.Status(ExecutionId("e1"), "completed"))
+ notebook.observe(be.Done(run.id, "succeeded"))
+ cursor = host.events()[-1].id
+ live: list[Event] = []
+ unsubscribe = host.subscribe(
+ live.append, notebook_id=notebook.id, run_id=run.id
+ )
+
+ notebook.run("2", request_id="next")
+ notebook.attach()
+ # Output can arrive after completed and while another run is active.
+ notebook.observe(be.Produced(console("late", "e1", "background")))
+ assert names(live) == ["console"]
+ assert names(
+ host.events(cursor, notebook_id=notebook.id, run_id=run.id)
+ ) == ["console", "ready"]
+ assert names(host.events(notebook_id=notebook.id, run_id=run.id)) == [
+ "run",
+ "execution",
+ "console",
+ "ready",
+ ]
+ assert names(
+ host.events(
+ notebook_id=notebook.id, run_id=run.id, types={"console"}
+ )
+ ) == ["console", "ready"]
+
+ host.remove_notebook(notebook.id)
+ assert names(live) == [
+ "console",
+ "console.removed",
+ "execution.removed",
+ "run.removed",
+ ]
+ unsubscribe()
+
+ def test_needs_a_running_runtime(self, notebook: Notebook) -> None:
+ with pytest.raises(NoRuntime):
+ notebook.run("1", request_id="r")
+ notebook.start()
+ with pytest.raises(Conflict, match="starting"):
+ notebook.run("1", request_id="r")
+
+ def test_a_scratch_run_from_queued_to_completed(
+ self,
+ host: Host,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+ ) -> None:
+ running(notebook, backend)
+ log.clear()
+ key = "7c1e9a3f"
+
+ run = notebook.run("3 * 3", request_id=key)
+ assert run.started_at is None
+
+ notebook.observe(
+ be.Planned(
+ run.id,
+ (be.PlannedExecution(ExecutionId("e7"), None, "9f", "3 * 3"),),
+ )
+ )
+ notebook.observe(be.Status(ExecutionId("e7"), "running"))
+ notebook.observe(be.Concluded(ExecutionId("e7"), value("working")))
+ notebook.observe(be.Produced(console("o3", "e7", "2\n")))
+ notebook.observe(
+ be.Concluded(ExecutionId("e7"), value("working<pre>9</pre>"))
+ )
+ notebook.observe(be.Status(ExecutionId("e7"), "completed"))
+ notebook.observe(be.Done(run.id, "succeeded"))
+
+ assert notebook.runtime is not None
+ assert backend.calls == [("run", key, "3 * 3")]
+ assert names(log) == [
+ "run",
+ "execution",
+ "run",
+ "execution",
+ "execution",
+ "console",
+ "execution",
+ "execution",
+ "run",
+ ]
+ assert set(request_ids(log)) == {key}
+ runs = [
+ data.run
+ for event in log
+ if isinstance(data := event.data, RunMessage)
+ ]
+ executions = [
+ data.execution
+ for event in log
+ if isinstance(data := event.data, ExecutionMessage)
+ ]
+ consoles = [
+ data.console
+ for event in log
+ if isinstance(data := event.data, ConsoleMessage)
+ ]
+ assert [run.status for run in runs] == [
+ "queued",
+ "running",
+ "completed",
+ ]
+ assert [(e.status, e.outcome) for e in executions] == [
+ ("queued", None),
+ ("running", None),
+ ("running", value("working")),
+ ("running", value("working<pre>9</pre>")),
+ ("completed", value("working<pre>9</pre>")),
+ ]
+ retained = [
+ event.data
+ for event in host.events(notebook_id=notebook.id)
+ if event.kind in {"run", "execution", "console"}
+ ]
+ assert retained == [
+ RunMessage(run=runs[-1]),
+ ExecutionMessage(execution=executions[-1]),
+ *(ConsoleMessage(console=item) for item in consoles),
+ ]
+ assert [runs[-1], executions[-1], *consoles] == snapshot(
+ [
+ Run(
+ caused_by=None,
+ completed_at=IsDatetime(),
+ id=RunId("7c1e9a3f"),
+ notebook_id=NotebookId("n1"),
+ outcome="succeeded",
+ started_at=IsDatetime(),
+ status="completed",
+ ),
+ Execution(
+ caused_by=None,
+ cell_id=None,
+ code="3 * 3",
+ code_hash="9f",
+ completed_at=IsDatetime(),
+ bindings=[],
+ id=ExecutionId("e7"),
+ outcome=ValueOutcome(
+ display=DisplayData(
+ data="working<pre>9</pre>", mimetype="text/html"
+ )
+ ),
+ run_id=RunId("7c1e9a3f"),
+ runtime_id=notebook.runtime.id,
+ stale=None,
+ started_at=IsDatetime(),
+ status="completed",
+ ),
+ Console(
+ execution_id=ExecutionId("e7"),
+ id=ItemId("o3"),
+ name="stdout",
+ seq=0,
+ text="2\n",
+ ),
+ ]
+ )
+
+ def test_repeating_the_request_returns_the_same_run(
+ self, notebook: Notebook, backend: ScriptedBackend
+ ) -> None:
+ running(notebook, backend)
+ first = notebook.run("1", request_id="same")
+ assert notebook.run("1", request_id="same") == first
+ assert backend.calls == [("run", "same", "1")]
+
+ def test_one_run_at_a_time(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ running(notebook, backend)
+ notebook.run("1", request_id="first")
+ with pytest.raises(Conflict, match="first"):
+ notebook.run("2", request_id="second")
+ notebook.observe(be.Done(RunId("first"), "succeeded"))
+ final = log[-1].data
+ assert isinstance(final, RunMessage)
+ assert final.run.status == "completed"
+ assert final.run.started_at is None
+ assert final.run.completed_at is not None
+ assert notebook.run("2", request_id="second").status == "queued"
+
+ def test_an_item_replaces_itself_by_id(
+ self, host: Host, notebook: Notebook, backend: ScriptedBackend
+ ) -> None:
+ running(notebook, backend)
+ scratch(notebook)
+ notebook.observe(be.Produced(console("o1", "e1", "0\n")))
+ notebook.observe(be.Produced(console("o1", "e1", "0\n1\n")))
+ items = [
+ event.data.console
+ for event in host.events(notebook_id=notebook.id)
+ if isinstance(event.data, ConsoleMessage)
+ ]
+ assert len(items) == 1
+ assert isinstance(items[0], Console)
+ assert items[0].text == "0\n1\n"
+
+ def test_messages_about_unknown_runs_are_ignored(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ running(notebook, backend)
+ log.clear()
+ notebook.observe(
+ be.Planned(
+ RunId("ghost"),
+ (be.PlannedExecution(ExecutionId("e9"), None, "x", "3 * 3"),),
+ )
+ )
+ notebook.observe(be.Status(ExecutionId("e9"), "running"))
+ notebook.observe(be.Produced(console("o9", "e9", "boo")))
+ notebook.observe(be.Done(RunId("ghost"), "succeeded"))
+ assert log == []
+
+
+class TestRunCompletion:
+ def test_later_work_gets_its_own_run(
+ self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ ) -> None:
+ running(notebook, backend)
+ original = scratch(notebook)
+ notebook.observe(be.Concluded(ExecutionId("e1"), value("9")))
+ notebook.observe(be.Status(ExecutionId("e1"), "completed"))
+ notebook.observe(be.Done(original.id, "succeeded"))
+ log.clear()
+ notebook.observe(be.Scheduled(RunId("later"), ExecutionId("e1")))
+ notebook.observe(be.Done(RunId("later"), "succeeded"))
+ assert request_ids(log) == [UNSET, UNSET]
+ assert all(event.run_id == "later" for event in log)
+ final = log[-1].data
+ assert isinstance(final, RunMessage)
+ assert final.run.caused_by == "e1"
+ assert (
+ notebook.run("3 * 3", request_id=original.id).status == "completed"
+ )
+
+ @pytest.mark.parametrize("outcome", ["failed", "interrupted"])
+ def test_can_end_before_any_execution(
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+ outcome: RunOutcome,
+ ) -> None:
+ running(notebook, backend)
+ run = notebook.run("pass", request_id="never-started")
+ assert run.outcome is None
+ notebook.observe(be.Done(run.id, outcome))
+ final = log[-1].data
+ assert isinstance(final, RunMessage)
+ assert final.run.status == "completed"
+ assert final.run.outcome == outcome
+ assert final.run.started_at is None
+ assert final.run.completed_at is not None
+
+ @pytest.mark.parametrize("outcome", ["failed", "interrupted"])
+ def test_downstream_work_outlives_the_root_execution(
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+ outcome: RunOutcome,
+ ) -> None:
+ running(notebook, backend)
+ run = scratch(notebook)
+ with pytest.raises(ValueError, match="unfinished"):
+ notebook.observe(be.Done(run.id, "succeeded"))
+ notebook.observe(be.Concluded(ExecutionId("e1"), value("9")))
+ notebook.observe(be.Status(ExecutionId("e1"), "completed"))
+ notebook.observe(
+ be.Planned(
+ run.id,
+ (
+ be.PlannedExecution(
+ ExecutionId("child"),
+ "cell",
+ "hash",
+ None,
+ ExecutionId("e1"),
+ ),
+ ),
+ )
+ )
+ notebook.observe(be.Status(ExecutionId("child"), "running"))
+ notebook.observe(
+ be.Concluded(
+ ExecutionId("child"),
+ ErrorOutcome(
+ Error(
+ kind="exception",
+ message="boom",
+ name="RuntimeError",
+ traceback=None,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
+ ),
+ )
+ )
+ notebook.observe(be.Status(ExecutionId("child"), "completed"))
+ # Even an empty execution queue is not an authoritative end to scheduling.
+ current = notebook.run("3 * 3", request_id=run.id)
+ assert current.status == "running"
+ assert current.outcome is None
+ with pytest.raises(ValueError, match="successful"):
+ notebook.observe(be.Done(run.id, "succeeded"))
+ notebook.observe(be.Done(run.id, outcome))
+ final = log[-1].data
+ assert isinstance(final, RunMessage)
+ assert final.run.outcome == outcome
+ assert final.run.status == "completed"
+ log.clear()
+ # Final records cannot reopen or acquire executions, but output keeps its origin.
+ notebook.observe(be.Status(ExecutionId("e1"), "running"))
+ notebook.observe(be.Concluded(ExecutionId("e1"), value("changed")))
+ notebook.observe(be.Done(run.id, "succeeded"))
+ notebook.observe(
+ be.Planned(
+ run.id,
+ (
+ be.PlannedExecution(
+ ExecutionId("late"), "late-cell", "hash", None
+ ),
+ ),
+ )
+ )
+ assert log == []
+ notebook.observe(
+ be.Produced(console("late-output", "e1", "still owned"))
+ )
+ assert names(log) == ["console"]
+
+
+class TestInterrupt:
+ def test_asks_the_backend_while_in_progress(
+ self, notebook: Notebook, backend: ScriptedBackend
+ ) -> None:
+ running(notebook, backend)
+ scratch(notebook)
+ backend.calls.clear()
+
+ notebook.interrupt("run-1")
+
+ assert backend.calls == [("interrupt", "run-1")]
+
+ def test_refuses_unknown_and_finished_runs(
+ self, notebook: Notebook, backend: ScriptedBackend
+ ) -> None:
+ running(notebook, backend)
+ with pytest.raises(NotFound):
+ notebook.interrupt("nope")
+ scratch(notebook)
+ notebook.observe(be.Concluded(ExecutionId("e1"), value("9")))
+ notebook.observe(be.Status(ExecutionId("e1"), "completed"))
+ notebook.observe(be.Done(RunId("run-1"), "succeeded"))
+ with pytest.raises(Conflict):
+ notebook.interrupt("run-1")
+
+
+class TestCellResults:
+ @pytest.mark.parametrize("same_run", [False, True])
+ def test_only_the_newest_cell_execution_remains_visible(
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[Event],
+ same_run: bool,
+ ) -> None:
+ running(notebook, backend)
+ first = notebook.run("pass", request_id="first")
+ old, new = ExecutionId("old"), ExecutionId("new")
+ notebook.observe(
+ be.Planned(
+ first.id, (be.PlannedExecution(old, "cell", "h1", None),)
+ )
+ )
+ notebook.observe(be.Status(old, "running"))
+ failed = ErrorOutcome(
+ Error(
+ kind="exception",
+ name="ValueError",
+ message="first attempt",
+ traceback=None,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
+ )
+ notebook.observe(be.Concluded(old, failed))
+ notebook.observe(be.Status(old, "completed"))
+ item = Console(
+ id=ItemId("o1"),
+ execution_id=old,
+ seq=0,
+ name="stdout",
+ text="old output",
+ )
+ notebook.observe(be.Produced(item))
+ if same_run:
+ second = first
+ else:
+ notebook.observe(be.Done(first.id, "failed"))
+ second = notebook.run("pass", request_id="second")
+ log.clear()
+ notebook.observe(
+ be.Planned(
+ second.id, (be.PlannedExecution(new, "cell", "h2", None),)
+ )
+ )
+ assert names(log) == [
+ "console.removed",
+ "execution.removed",
+ "execution",
+ ]
+ visible = [
+ event.data.execution.id
+ for event in notebook._snapshot()
+ if isinstance(event.data, ExecutionMessage)
+ ]
+ assert visible == [new]
+ notebook.observe(be.Concluded(new, ValueOutcome(None)))
+ notebook.observe(be.Status(new, "completed"))
+ if same_run:
+ with pytest.raises(ValueError, match="successful run"):
+ notebook.observe(be.Done(second.id, "succeeded"))
+ notebook.observe(
+ be.Done(second.id, "failed" if same_run else "succeeded")
+ )
+ assert not notebook._retired_executions
+ log.clear()
+ notebook.observe(be.Produced(item))
+ assert not log
+
+ def test_a_new_attempt_cannot_replace_unfinished_work(
+ self, notebook: Notebook, backend: ScriptedBackend
+ ) -> None:
+ running(notebook, backend)
+ run = notebook.run("pass", request_id="first")
+ notebook.observe(
+ be.Planned(
+ run.id,
+ (be.PlannedExecution(ExecutionId("old"), "cell", "h1", None),),
+ )
+ )
+ with pytest.raises(ValueError, match="unfinished cell execution"):
+ notebook.observe(
+ be.Planned(
+ run.id,
+ (
+ be.PlannedExecution(
+ ExecutionId("new"), "cell", "h2", None
+ ),
+ ),
+ )
+ )
+
+
+class TestAttachments:
+ def test_api_clients_attach_and_detach(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ att = notebook.attach()
+ notebook.detach(att.id)
+ notebook.detach(att.id)
+
+ assert att.kind == "client"
+ assert att.notebook_id == "n1"
+ assert names(log) == ["attachment", "attachment.removed"]
diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.py
new file mode 100644
index 0000000000..38be3228a9
--- /dev/null
+++ b/tests/_core/test_stream.py
@@ -0,0 +1,79 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Event delivery remains ordered and independent of subscribers."""
+
+from __future__ import annotations
+
+from marimo._core import protocol
+from marimo._core.host import Host
+from marimo._core.notebook import Notebook
+from marimo._core.stream import Event, Stream
+from tests._core.conftest import ScriptedBackend, project
+
+
+def test_subscriber_failure_does_not_prevent_startup(
+ host: Host,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+) -> None:
+ def fail(_event: Event) -> None:
+ raise RuntimeError("subscriber failed")
+
+ host.subscribe(fail)
+ delivered: list[Event] = []
+ host.subscribe(delivered.append)
+
+ runtime, created = notebook.start()
+
+ assert created
+ assert backend.calls == [("start", runtime.id)]
+ assert [e.name for e in delivered] == ["runtime"]
+
+
+def test_nested_publications_follow_the_current_event() -> None:
+ stream = Stream()
+
+ def publish_another(event: Event) -> None:
+ if event.id == 1:
+ stream.publish(project("p2"))
+
+ stream.subscribe(publish_another)
+ delivered: list[Event] = []
+ stream.subscribe(delivered.append)
+
+ stream.publish(project())
+
+ assert [e.id for e in delivered] == [1, 2]
+ assert delivered == stream.since(0)
+
+
+def test_readers_cannot_change_other_readers_or_replay() -> None:
+ stream = Stream()
+
+ def mutate(event: Event) -> None:
+ assert isinstance(event.data, protocol.ProjectMessage)
+ event.data.project.name = "subscriber mutation"
+ event.data.project.operations.clear()
+
+ stream.subscribe(mutate)
+ delivered: list[Event] = []
+ stream.subscribe(delivered.append)
+ original = project()
+ published = stream.publish(original)
+ original.name = "caller mutation"
+
+ assert isinstance(published.data, protocol.ProjectMessage)
+ assert published.data.project == project()
+ published.data.project.name = "return value mutation"
+ assert isinstance(delivered[0].data, protocol.ProjectMessage)
+ assert delivered[0].data.project == project()
+ delivered[0].data.project.name = "listener mutation"
+
+ replay = stream.since(0)
+ assert replay is not None
+ assert isinstance(replay[0].data, protocol.ProjectMessage)
+ assert replay[0].data.project == project()
+ replay[0].data.project.name = "replay mutation"
+ reread = stream.since(0)
+ assert reread is not None
+ assert isinstance(reread[0].data, protocol.ProjectMessage)
+ assert reread[0].data.project == project()