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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Move notebook operations into core (#11485)
Trevor Manz8685346ecbc9
diff --git a/marimo/_core/calls.py b/marimo/_core/calls.pynew file mode 100644index 0000000000..24f42e997a--- /dev/null+++ b/marimo/_core/calls.py@@ -0,0 +1,235 @@+# Copyright 2026 Marimo. All rights reserved.+"""Requests for notebook operations, each with the handler that serves it.++A call has the parts of an HTTP request, as the client sends them. Its+`params` are the path parameters, its `headers` the request headers it+reads, and its `body` the decoded request body. A call also gives its place+in the HTTP API, and its `handle` method does the work and declares the+successful status and response in its return type.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, ClassVar, Literal++import msgspec++from marimo._core import protocol+from marimo._core.errors import Conflict, HostError, Invalid, NotFound+from marimo._core.operations import Reply, problem_for++if TYPE_CHECKING:+ from marimo._core.operations import Mutations, NotebookBridge+++class NotebookParams(msgspec.Struct, frozen=True):+ notebook_id: protocol.NotebookId+++class RunParams(NotebookParams, frozen=True):+ run_id: protocol.RunId+++class MutationHeaders(msgspec.Struct, frozen=True):+ idempotency_key: str = msgspec.field(name="idempotency-key", default="")+++class SaveHeaders(MutationHeaders, frozen=True):+ if_match: str | None = msgspec.field(name="if-match", default=None)+++class _Call(msgspec.Struct, frozen=True, tag_field="operation"):+ METHOD: ClassVar[str]+ PATH: ClassVar[str]+++class EditCall(_Call, frozen=True, tag="notebook.edit"):+ """Change parts of the document."""++ METHOD = "POST"+ PATH = "/notebooks/{notebook_id}/edits"++ params: NotebookParams+ headers: MutationHeaders+ body: protocol.EditRequest++ async def handle(+ self, bridge: NotebookBridge+ ) -> tuple[Literal[200], protocol.EditResponse]:+ return 200, await bridge.edit(+ self.params.notebook_id,+ self.body.changes,+ request_id=self.headers.idempotency_key,+ )+++class SaveCall(_Call, frozen=True, tag="notebook.save"):+ """Write the document to the host's store."""++ METHOD = "POST"+ PATH = "/notebooks/{notebook_id}/save"++ params: NotebookParams+ headers: SaveHeaders+ body: protocol.SaveRequest++ async def handle(+ self, bridge: NotebookBridge+ ) -> tuple[Literal[200], protocol.EditResponse]:+ decisions = self.body.decisions+ return 200, await bridge.save(+ self.params.notebook_id,+ if_match=_if_match(self.headers.if_match),+ decisions={} if decisions is msgspec.UNSET else decisions,+ request_id=self.headers.idempotency_key,+ )+++class StartCall(_Call, frozen=True, tag="runtime.start"):+ """Start the notebook's runtime, or find the one it has."""++ METHOD = "PUT"+ PATH = "/notebooks/{notebook_id}/runtime"++ params: NotebookParams+ headers: MutationHeaders+ body: protocol.StartRuntimeRequest++ async def handle(+ self, bridge: NotebookBridge+ ) -> tuple[Literal[200, 202], protocol.Runtime]:+ notebook = await bridge.host.notebook(self.params.notebook_id)+ runtime, created = notebook.start(+ request_id=self.headers.idempotency_key+ )+ return (202 if created else 200), runtime+++class StopCall(_Call, frozen=True, tag="runtime.stop"):+ """Stop the notebook's runtime."""++ METHOD = "DELETE"+ PATH = "/notebooks/{notebook_id}/runtime"++ params: NotebookParams+ headers: MutationHeaders++ async def handle(+ self, bridge: NotebookBridge+ ) -> tuple[Literal[202], protocol.Runtime]:+ notebook = await bridge.host.notebook(self.params.notebook_id)+ return 202, notebook.stop(request_id=self.headers.idempotency_key)+++class RestartCall(_Call, frozen=True, tag="runtime.restart"):+ """Restart the notebook's kernel."""++ METHOD = "POST"+ PATH = "/notebooks/{notebook_id}/runtime/restart"++ params: NotebookParams+ headers: MutationHeaders++ async def handle(+ self, bridge: NotebookBridge+ ) -> tuple[Literal[202], protocol.Runtime]:+ notebook = await bridge.host.notebook(self.params.notebook_id)+ return 202, notebook.restart(request_id=self.headers.idempotency_key)+++class RunCall(_Call, frozen=True, tag="runtime.run"):+ """Run code or cells against the notebook's runtime."""++ METHOD = "POST"+ PATH = "/notebooks/{notebook_id}/runtime/runs"++ params: NotebookParams+ headers: MutationHeaders+ body: protocol.RunRequest++ async def handle(+ self, bridge: NotebookBridge+ ) -> tuple[Literal[202], protocol.Run]:+ notebook = await bridge.host.notebook(self.params.notebook_id)+ key = self.headers.idempotency_key+ code, cells = self.body.code, self.body.cells+ if isinstance(code, str) and cells is msgspec.UNSET:+ return 202, notebook.run(code, request_id=key)+ if code is msgspec.UNSET and isinstance(cells, tuple):+ return 202, notebook.run(cells=cells, request_id=key)+ raise Invalid("A run names code or cells, not both")+++class InterruptCall(_Call, frozen=True, tag="runtime.interrupt"):+ """Interrupt a run."""++ METHOD = "DELETE"+ PATH = "/notebooks/{notebook_id}/runtime/runs/{run_id}"++ params: RunParams+ headers: MutationHeaders++ async def handle(+ self, bridge: NotebookBridge+ ) -> tuple[Literal[202], protocol.Run]:+ notebook_id, run_id = self.params.notebook_id, self.params.run_id+ notebook = await bridge.host.notebook(notebook_id)+ try:+ return 202, notebook.interrupt(run_id)+ except NotFound:+ run = bridge.host.run(notebook_id, run_id)+ if run is not None and run.status == "completed":+ raise Conflict(f"run {run_id} has already ended.") from None+ raise+++OperationCall = (+ EditCall+ | SaveCall+ | StartCall+ | StopCall+ | RestartCall+ | RunCall+ | InterruptCall+)+"""A request for any notebook operation, tagged by its operation id."""++# The same members as `OperationCall`, as values to build routes from.+# `typing.get_args` would return them untyped.+CALLS: tuple[type[OperationCall], ...] = (+ EditCall,+ SaveCall,+ StartCall,+ StopCall,+ RestartCall,+ RunCall,+ InterruptCall,+)+++async def dispatch(+ mutations: Mutations, bridge: NotebookBridge, call: OperationCall+) -> Reply:+ """Serve a call once per idempotency key and describe a failure as a problem."""+ try:+ return await mutations.execute(+ str(call.__struct_config__.tag),+ notebook_id=call.params.notebook_id,+ key=call.headers.idempotency_key,+ payload=call,+ call=lambda: call.handle(bridge),+ )+ except HostError as e:+ failure = problem_for(e)+ return failure.status, failure+++def _if_match(header: str | None) -> tuple[str, ...] | None:+ """Parse strong entity tags; weak tags never satisfy an If-Match check."""+ if header is None or header.strip() == "*":+ return None+ return tuple(+ part.strip().strip('"')+ for part in header.split(",")+ if part.strip() and not part.strip().startswith("W/")+ )diff --git a/marimo/_core/errors.py b/marimo/_core/errors.pyindex a86a04bbb9..27ab622a2b 100644--- a/marimo/_core/errors.py+++ b/marimo/_core/errors.py@@ -29,6 +29,14 @@ class Invalid(HostError):"""The request could not apply to any state."""+class Forbidden(HostError):+ """The notebook does not allow the command."""+++class Unsupported(HostError):+ """The host does not offer the command."""++class EditConflict(Conflict):"""A change named a state the document no longer has.diff --git a/marimo/_core/operations.py b/marimo/_core/operations.pynew file mode 100644index 0000000000..397bdfeccc--- /dev/null+++ b/marimo/_core/operations.py@@ -0,0 +1,322 @@+# Copyright 2026 Marimo. All rights reserved.+"""Retry receipts and problems shared by every transport."""++from __future__ import annotations++import asyncio+import hashlib+from dataclasses import dataclass+from time import monotonic+from typing import TYPE_CHECKING, Protocol++import msgspec++from marimo._core import protocol+from marimo._core.errors import (+ Conflict,+ DecisionRequired,+ EditConflict,+ Forbidden,+ HostError,+ Invalid,+ NoRuntime,+ NotFound,+ Unsupported,+)+from marimo._core.host import Host+from marimo._core.stream import RoutedEvent++if TYPE_CHECKING:+ from collections.abc import Awaitable, Callable, Mapping, Sequence++Reply = tuple[int, msgspec.Struct | None]+"""A status and body, for a transport to encode."""+++class NotebookBridge(Protocol):+ @property+ def host(self) -> Host: ...++ async def edit(+ self,+ notebook_id: str,+ changes: Sequence[protocol.Change],+ *,+ request_id: str,+ ) -> protocol.EditResponse: ...++ async def save(+ self,+ notebook_id: str,+ *,+ if_match: Sequence[str] | None,+ decisions: Mapping[str, str],+ request_id: str,+ ) -> protocol.EditResponse: ...+++_TITLES = {+ "invalid-request": "Invalid request",+ "unauthorized": "Unauthorized",+ "forbidden": "Forbidden",+ "not-found": "Not found",+ "method-not-allowed": "Method not allowed",+ "conflict": "Conflict",+ "no-runtime": "No runtime",+ "decision-required": "Decision required",+ "unsupported-operation": "Unsupported operation",+ "internal": "Internal error",+}+++def problem(+ status: int,+ kind: str,+ detail: str | None = None,+ *,+ edit: protocol.EditConflict | None = None,+ decisions: tuple[protocol.Decision, ...] | None = None,+) -> protocol.Problem:+ return protocol.Problem(+ type="tag:marimo.io,2026:host/" + kind,+ title=_TITLES[kind],+ status=status,+ detail=msgspec.UNSET if detail is None else detail,+ edit=msgspec.UNSET if edit is None else edit,+ decisions=msgspec.UNSET if decisions is None else decisions,+ )+++def problem_for(error: HostError) -> protocol.Problem:+ """Describe a failed command the same way on every transport."""+ detail = str(error)+ match error:+ case NoRuntime():+ return problem(409, "no-runtime", detail)+ case DecisionRequired():+ return problem(+ 409, "decision-required", detail, decisions=error.decisions+ )+ case EditConflict():+ return problem(+ 409,+ "conflict",+ detail,+ edit=protocol.EditConflict(+ change=error.change,+ cell=error.cell,+ document=error.document,+ ),+ )+ case Conflict():+ return problem(409, "conflict", detail)+ case Invalid():+ return problem(400, "invalid-request", detail)+ case NotFound():+ return problem(404, "not-found", detail)+ case Forbidden():+ return problem(403, "forbidden", detail)+ case Unsupported():+ return problem(501, "unsupported-operation", detail)+ return problem(500, "internal", "The host failed")+++@dataclass+class CachedMutation:+ """An accepted request, including its in-flight or completed result."""++ fingerprint: str+ task: asyncio.Future[Reply]+ run: protocol.Run | None = None+ expires_at: float | None = None+++class Mutations:+ """Share capability checks and retry semantics across all host mutations."""++ def __init__(+ self,+ host: Host,+ *,+ receipt_seconds: float = 300.0,+ clock: Callable[[], float] = monotonic,+ ) -> None:+ self.host = host+ # A receipt covers a client's retry loop after a lost response, so it+ # outlasts retry backoff rather than a person's absence.+ self.receipt_seconds = receipt_seconds+ self.clock = clock+ self.replies: dict[str, CachedMutation] = {}++ def remembered(self, key: str) -> CachedMutation | None:+ """Return the receipt for a key, dropping it if it has expired."""+ reply = self.replies.get(key)+ if reply is not None and self._expired(reply):+ del self.replies[key]+ return None+ return reply++ def settle(self, mutation: CachedMutation) -> None:+ """Start the receipt's retention window once its work is complete."""+ mutation.expires_at = self.clock() + self.receipt_seconds++ def expire(self) -> None:+ """Sweep expired receipts and the host's results."""+ self.host.expire()+ for key, reply in list(self.replies.items()):+ if self._expired(reply):+ del self.replies[key]++ def _expired(self, reply: CachedMutation) -> bool:+ return (+ reply.expires_at is not None and self.clock() >= reply.expires_at+ )++ async def execute(+ self,+ operation: str,+ *,+ notebook_id: str | None,+ key: str,+ payload: object,+ call: Callable[[], Awaitable[Reply]],+ ) -> Reply:+ """Run `call` once per idempotency key, and answer retries with its reply."""+ capability = (+ "runtime.run" if operation == "runtime.interrupt" else operation+ )+ if capability not in self.host.operations:+ raise Unsupported(f"This host does not offer {capability}")+ record = self.host.notebooks.get(notebook_id) if notebook_id else None+ if record is not None and capability not in record.operations:+ raise Forbidden(f"This notebook does not allow {capability}")+ if not key:+ raise Invalid("Idempotency-Key is required")+ fingerprint = hashlib.sha256(+ msgspec.json.encode((operation, notebook_id, payload))+ ).hexdigest()+ remembered = self.remembered(key)+ if remembered is not None:+ if remembered.fingerprint != fingerprint:+ raise Conflict(+ f"Idempotency-Key {key} was used for another request"+ )+ reply = await asyncio.shield(remembered.task)+ # A retried run answers with the run as it is now.+ return reply if remembered.run is None else (202, remembered.run)++ task = asyncio.ensure_future(call())+ mutation = CachedMutation(fingerprint, task)+ self.replies[key] = mutation+ unsubscribe: Callable[[], None] | None = None+ lifecycle_accepted: Callable[[Reply], None] | None = None+ if operation == "runtime.run":+ # Retain the latest run without retaining its output payloads.+ def updated(event: RoutedEvent) -> None:+ if isinstance(event.event, protocol.RunEvent):+ run = event.event.data.run+ if event.event.data.request_id == key:+ mutation.run = run+ if (+ run.status == "completed"+ and unsubscribe is not None+ ):+ self.settle(mutation)+ unsubscribe()++ unsubscribe = self.host.subscribe(+ updated, notebook_id=notebook_id, types={"run"}+ )+ elif operation in {"runtime.start", "runtime.stop", "runtime.restart"}:+ assert notebook_id is not None+ lifecycle_accepted, unsubscribe = _watch_lifecycle(+ self,+ mutation,+ operation=operation,+ notebook_id=notebook_id,+ request_id=key,+ )++ def completed(task: asyncio.Future[Reply]) -> None:+ if task.cancelled() or task.exception() is not None:+ self.replies.pop(key, None)+ if unsubscribe is not None:+ unsubscribe()+ elif lifecycle_accepted is not None:+ lifecycle_accepted(task.result())+ elif mutation.expires_at is None and (+ mutation.run is None or mutation.run.status == "completed"+ ):+ self.settle(mutation)++ task.add_done_callback(completed)+ # A disconnected waiter must not cancel a shared mutation.+ return await asyncio.shield(task)+++def _watch_lifecycle(+ context: Mutations,+ mutation: CachedMutation,+ *,+ operation: str,+ notebook_id: str,+ request_id: str,+) -> tuple[Callable[[Reply], None], Callable[[], None]]:+ runtime_id: protocol.RuntimeId | None = None+ previous_id: protocol.RuntimeId | None = None+ early: list[RoutedEvent] = []++ def settle() -> None:+ context.settle(mutation)+ unsubscribe()++ def updated(event: RoutedEvent) -> None:+ nonlocal previous_id+ if mutation.expires_at is not None:+ return+ if runtime_id is None:+ # A backend can finish synchronously, before the response exists.+ early.append(event)+ return+ if isinstance(event.event, protocol.NotebookRemovedEvent):+ settle()+ elif isinstance(event.event, protocol.RuntimeEvent):+ runtime = event.event.data.runtime+ if (+ operation == "runtime.restart"+ and event.event.data.request_id == request_id+ and runtime.status == "terminating"+ and runtime.id != runtime_id+ ):+ previous_id = runtime.id+ if (+ operation != "runtime.stop"+ and runtime.id == runtime_id+ and runtime.status in ("running", "failed")+ ):+ settle()+ elif isinstance(event.event, protocol.RuntimeRemovedEvent):+ if event.event.data.id == runtime_id or (+ event.event.data.id == previous_id+ and event.event.data.request_id != request_id+ ):+ # A later stop can cancel a restart before its replacement starts.+ settle()++ unsubscribe = context.host.subscribe(+ updated, notebook_id=notebook_id, types={"runtime", "notebook"}+ )++ def accepted(reply: Reply) -> None:+ nonlocal runtime_id+ match reply:+ # A 202 changes a runtime, and a 200 found the one already running.+ case (202, protocol.Runtime(id=accepted_id)):+ runtime_id = accepted_id+ for event in early:+ updated(event)+ case _:+ settle()+ early.clear()++ return accepted, unsubscribediff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.pyindex c1d1e7f608..1cc42ada38 100644--- a/marimo/_server/host/api.py+++ b/marimo/_server/host/api.py@@ -4,13 +4,10 @@from __future__ import annotationsimport asyncio-import hashlibimport threading-from collections.abc import Awaitable, Callablefrom contextlib import contextmanager-from functools import wrapsfrom pathlib import Path-from typing import TYPE_CHECKING, TypeAlias, TypeVar+from typing import TYPE_CHECKINGfrom urllib.parse import quoteimport msgspec@@ -24,12 +21,9 @@ from marimo import _loggersfrom marimo._core import protocolfrom marimo._core.errors import (Conflict,- DecisionRequired,- EditConflict,- Invalid,- NoRuntime,NotFound,)+from marimo._core.operations import Replyfrom marimo._server.api.auth import TOKEN_QUERY_PARAM, validate_authfrom marimo._server.api.deps import AppState, AppStateBasefrom marimo._server.api.endpoints.ws.ws_connection_validator import (@@ -45,14 +39,20 @@ from marimo._server.host import (HOST_API_PATH,stream_options,)-from marimo._server.host.context import CachedMutationfrom marimo._server.host.events import serialize_event, serialize_sse_event+from marimo._server.host.notebook_api import (+ _context,+ _decode,+ _mutation,+ notebook_routes,+ problem,+)from marimo._server.host.session import SessionEventStreamfrom marimo._server.sse import SSE_HEADERSfrom marimo._server.tokens import AuthTokenif TYPE_CHECKING:- from collections.abc import AsyncIterator, Iterator+ from collections.abc import AsyncIterator, Callable, Iteratorfrom anyio import CancelScopefrom starlette.requests import HTTPConnection, Request@@ -64,12 +64,6 @@ if TYPE_CHECKING:LOGGER = _loggers.marimo_logger()-_Endpoint: TypeAlias = Callable[["Request"], Awaitable[Response]]-_Body = TypeVar("_Body", bound=msgspec.Struct)--PROBLEM_TYPE_PREFIX = "tag:marimo.io,2026:host/"-"""Prefix for host protocol problem types."""-_ATTACHMENT_HEADERS = {"identity": ATTACHMENT_IDENTITY,@@ -82,88 +76,27 @@ PING = b": ping\n\n"PING_SECONDS = 15.0-_TITLES = {- "invalid-request": "Invalid request",- "unauthorized": "Unauthorized",- "forbidden": "Forbidden",- "not-found": "Not found",- "method-not-allowed": "Method not allowed",- "conflict": "Conflict",- "no-runtime": "No runtime",- "decision-required": "Decision required",- "unsupported-operation": "Unsupported operation",- "internal": "Internal error",-}---_HTTP_KINDS = {- 400: "invalid-request",- 404: "not-found",- 405: "method-not-allowed",- 409: "conflict",-}---def problem(- status: int,- kind: str | None = None,- detail: str | None = None,- *,- edit: protocol.EditConflict | None = None,- decisions: tuple[protocol.Decision, ...] | None = None,-) -> Response:- """Return a protocol error as an HTTP problem response.-- Without a kind, the status picks one. A status this protocol does- not name is a server bug, so it becomes a 500 rather than a problem- of an unknown kind. A conflict over an edit carries `edit`, and a- request that needs a choice first carries `decisions`.- """- kind = _HTTP_KINDS.get(status) if kind is None else kind-- if kind is None:- LOGGER.error("The host API raised an unmapped status %s", status)- status, kind, detail = 500, "internal", "The host failed"- body = protocol.Problem(- type=PROBLEM_TYPE_PREFIX + kind,- title=_TITLES[kind],- status=status,- detail=msgspec.UNSET if detail is None else detail,- edit=msgspec.UNSET if edit is None else edit,- decisions=msgspec.UNSET if decisions is None else decisions,- )- return Response(- msgspec.json.encode(body),- status_code=status,- media_type="application/problem+json",- )--def build_app() -> Router:"""Build the host API router."""routes = [Route("/events", _events, methods=["GET"]),Route("/notebooks", _create_notebook, methods=["POST"]),- Route("/notebooks/{id}", _update_notebook, methods=["PATCH"]),- Route("/notebooks/{id}", _delete_notebook, methods=["DELETE"]),- Route("/notebooks/{id}/events", _notebook_events, methods=["GET"]),- WebSocketRoute("/notebooks/{id}/events/ws", _notebook_events_ws),- Route("/notebooks/{id}/edits", _edit_notebook, methods=["POST"]),- Route("/notebooks/{id}/save", _save_notebook, methods=["POST"]),- Route("/notebooks/{id}/open", _open_notebook, methods=["POST"]),- Route("/notebooks/{id}/runtime", _start_runtime, methods=["PUT"]),- Route("/notebooks/{id}/runtime", _stop_runtime, methods=["DELETE"]),+ Route("/notebooks/{notebook_id}", _update_notebook, methods=["PATCH"]),Route(- "/notebooks/{id}/runtime/restart",- _restart_runtime,- methods=["POST"],+ "/notebooks/{notebook_id}", _delete_notebook, methods=["DELETE"]),- Route("/notebooks/{id}/runtime/runs", _run, methods=["POST"]),Route(- "/notebooks/{id}/runtime/runs/{run_id}",- _interrupt,- methods=["DELETE"],+ "/notebooks/{notebook_id}/events",+ _notebook_events,+ methods=["GET"],+ ),+ WebSocketRoute(+ "/notebooks/{notebook_id}/events/ws", _notebook_events_ws),+ Route(+ "/notebooks/{notebook_id}/open", _open_notebook, methods=["POST"]+ ),+ *notebook_routes(),]for route in routes:# Starlette implies HEAD for every GET route, but a HEAD here would@@ -187,20 +120,14 @@ async def _not_found(scope, receive, send) -> None: # type: ignore[no-untyped-dawait problem(404, "not-found", "No such route")(scope, receive, send)-def _context(request: HTTPConnection) -> HostContext:- context = getattr(request.app.state, "host_context", None)- assert context is not None, "HostApiMiddleware admits requests only then"- return context # type: ignore[no-any-return]--async def _notebook(request: HTTPConnection) -> Notebook:return await _context(request).bridge.host.notebook(- request.path_params["id"]+ request.path_params["notebook_id"])def _record(request: Request) -> protocol.Notebook:- notebook_id = request.path_params["id"]+ notebook_id = request.path_params["notebook_id"]host = _context(request).bridge.hostrecord = host.notebooks.get(notebook_id)if record is None:@@ -208,214 +135,6 @@ def _record(request: Request) -> protocol.Notebook:return record-def _mutation(operation: str) -> Callable[[_Endpoint], _Endpoint]:- """Apply capability checks, idempotency, and protocol errors to a command."""-- def decorate(endpoint: _Endpoint) -> _Endpoint:- @wraps(endpoint)- async def handle(request: Request) -> Response:- context = _context(request)- if operation not in context.bridge.host.operations:- return problem(- 501,- "unsupported-operation",- f"This host does not offer {operation}",- )- key = request.headers.get("Idempotency-Key", "")- if not key:- return problem(- 400, "invalid-request", "Idempotency-Key is required"- )- digest = hashlib.sha256(await request.body()).hexdigest()- # A precondition is part of the request, so a retry that- # names another revision is another request.- if_match = request.headers.get("If-Match", "")- fingerprint = (- f"{request.method} {request.url.path} {digest} {if_match}"- )- remembered = context.remembered(key)- if remembered is not None:- if remembered.fingerprint != fingerprint:- return problem(- 409,- "conflict",- f"Idempotency-Key {key} was used for another request",- )- response = await asyncio.shield(remembered.task)- if remembered.run is not None:- return _reply(202, remembered.run)- return response-- task = asyncio.create_task(_execute_mutation(endpoint, request))- mutation = CachedMutation(fingerprint, task)- context.replies[key] = mutation- unsubscribe: Callable[[], None] | None = None- lifecycle_accepted: Callable[[Response], None] | None = None- if operation == "runtime.run" and request.method == "POST":- # The receipt outlives results without retaining their payloads.- def updated(event: RoutedEvent) -> None:- if isinstance(event.event, protocol.RunEvent):- run = event.event.data.run- if event.event.data.request_id == key:- mutation.run = run- if (- run.status == "completed"- and unsubscribe is not None- ):- context.settle(mutation)- unsubscribe()-- unsubscribe = context.bridge.host.subscribe(- updated,- notebook_id=request.path_params["id"],- types={"run"},- )- elif operation in {- "runtime.start",- "runtime.stop",- "runtime.restart",- }:- lifecycle_accepted, unsubscribe = _watch_lifecycle(- context,- mutation,- operation=operation,- notebook_id=request.path_params["id"],- request_id=key,- )-- def completed(task: asyncio.Task[Response]) -> None:- if (- task.cancelled()- or task.exception() is not None- or task.result().status_code >= 400- ):- context.replies.pop(key, None)- if unsubscribe is not None:- unsubscribe()- elif lifecycle_accepted is not None:- lifecycle_accepted(task.result())- elif mutation.expires_at is None and (- mutation.run is None or mutation.run.status == "completed"- ):- context.settle(mutation)-- task.add_done_callback(completed)- # A disconnected waiter must not cancel a shared mutation.- return await asyncio.shield(task)-- return handle-- return decorate---def _watch_lifecycle(- context: HostContext,- mutation: CachedMutation,- *,- operation: str,- notebook_id: str,- request_id: str,-) -> tuple[Callable[[Response], None], Callable[[], None]]:- runtime_id: protocol.RuntimeId | None = None- previous_id: protocol.RuntimeId | None = None- early: list[RoutedEvent] = []-- def settle() -> None:- context.settle(mutation)- unsubscribe()-- def updated(event: RoutedEvent) -> None:- nonlocal previous_id- if mutation.expires_at is not None:- return- if runtime_id is None:- # A backend can finish synchronously, before the response exists.- early.append(event)- return- if isinstance(event.event, protocol.NotebookRemovedEvent):- settle()- elif isinstance(event.event, protocol.RuntimeEvent):- runtime = event.event.data.runtime- if (- operation == "runtime.restart"- and event.event.data.request_id == request_id- and runtime.status == "terminating"- and runtime.id != runtime_id- ):- previous_id = runtime.id- if (- operation != "runtime.stop"- and runtime.id == runtime_id- and runtime.status in ("running", "failed")- ):- settle()- elif isinstance(event.event, protocol.RuntimeRemovedEvent):- if event.event.data.id == runtime_id or (- event.event.data.id == previous_id- and event.event.data.request_id != request_id- ):- # A later stop can cancel a restart before its replacement starts.- settle()-- unsubscribe = context.bridge.host.subscribe(- updated, notebook_id=notebook_id, types={"runtime", "notebook"}- )-- def accepted(response: Response) -> None:- nonlocal runtime_id- if response.status_code == 202:- runtime_id = msgspec.json.decode(- response.body, type=protocol.Runtime- ).id- for event in early:- updated(event)- else:- settle()- early.clear()-- return accepted, unsubscribe---async def _execute_mutation(endpoint: _Endpoint, request: Request) -> Response:- try:- return await endpoint(request)- except NoRuntime as e:- return problem(409, "no-runtime", str(e))- except DecisionRequired as e:- return problem(409, "decision-required", str(e), decisions=e.decisions)- except EditConflict as e:- return problem(- 409,- "conflict",- str(e),- edit=protocol.EditConflict(- change=e.change, cell=e.cell, document=e.document- ),- )- except Conflict as e:- return problem(409, "conflict", str(e))- except Invalid as e:- return problem(400, "invalid-request", str(e))- except NotFound as e:- return problem(404, "not-found", str(e))- except msgspec.DecodeError as e:- return problem(400, "invalid-request", str(e))- except HTTPException as e:- return problem(e.status_code, detail=e.detail)---def _reply(status: int, body: msgspec.Struct | None = None) -> Response:- return Response(- b"" if body is None else msgspec.json.encode(body),- status_code=status,- media_type="application/json" if body is not None else None,- )---async def _decode(request: Request, kind: type[_Body]) -> _Body:- return msgspec.json.decode(await request.body() or b"{}", type=kind)--# ---- streams -------------------------------------------------------------------@@ -475,7 +194,7 @@ async def _notebook_events(request: Request) -> Response:def editor_events_route(base_url: str = "") -> WebSocketRoute:"""Expose the notebook event socket through editor authentication."""return WebSocketRoute(- f"{base_url}{HOST_API_PATH}/notebooks/{{id}}/events/ws",+ f"{base_url}{HOST_API_PATH}/notebooks/{{notebook_id}}/events/ws",_editor_events_ws,)@@ -772,7 +491,7 @@ def _inside_project(path: str) -> Path:@_mutation("notebook.create")-async def _create_notebook(request: Request) -> Response:+async def _create_notebook(request: Request) -> Reply:"""Create an empty notebook in the project."""context = _context(request)key = request.headers["Idempotency-Key"]@@ -790,11 +509,11 @@ async def _create_notebook(request: Request) -> Response:name=None if body.name is msgspec.UNSET else body.name,request_id=key,)- return _reply(201, notebook)+ return 201, notebook@_mutation("notebook.update")-async def _update_notebook(request: Request) -> Response:+async def _update_notebook(request: Request) -> Reply:"""Change a notebook's path or display name, preserving its runtime."""context = _context(request)key = request.headers["Idempotency-Key"]@@ -816,66 +535,20 @@ async def _update_notebook(request: Request) -> Response:name=None if body.name is msgspec.UNSET else body.name,request_id=key,)- return _reply(200, notebook)+ return 200, notebook@_mutation("notebook.delete")-async def _delete_notebook(request: Request) -> Response:+async def _delete_notebook(request: Request) -> Reply:"""Delete the notebook and its file if it has no runtime."""context = _context(request)key = request.headers["Idempotency-Key"]await context.bridge.delete(_record(request).id, request_id=key)- return _reply(204, None)---@_mutation("notebook.edit")-async def _edit_notebook(request: Request) -> Response:- """Apply an edit as one unit; 409 with `edit` when a precondition is stale."""- context = _context(request)- key = request.headers["Idempotency-Key"]- notebook = await _notebook(request)- body = await _decode(request, protocol.EditRequest)- response = await context.bridge.edit(- notebook.id, body.changes, request_id=key- )- return _reply(200, response)---@_mutation("notebook.save")-async def _save_notebook(request: Request) -> Response:- """Write the document to its file; 409 with `edit` when `If-Match` is stale."""- context = _context(request)- key = request.headers["Idempotency-Key"]- notebook = await _notebook(request)- body = await _decode(request, protocol.SaveRequest)- response = await context.bridge.save(- notebook.id,- if_match=_if_match(request.headers.get("If-Match")),- decisions={} if body.decisions is msgspec.UNSET else body.decisions,- request_id=key,- )- return _reply(200, response)---def _if_match(header: str | None) -> tuple[str, ...] | None:- """The etags an `If-Match` header accepts, or `None` when it accepts any.-- The header is `*` or a comma-separated list of entity tags, each- optionally quoted. `If-Match` compares strongly (RFC 9110, 13.1.1),- so a tag marked weak with `W/` never matches and is left out.- """- if header is None or header.strip() == "*":- return None- tags = []- for part in header.split(","):- tag = part.strip()- if tag and not tag.startswith("W/"):- tags.append(tag.strip('"'))- return tuple(tags)+ return 204, None@_mutation("notebook.open")-async def _open_notebook(request: Request) -> Response:+async def _open_notebook(request: Request) -> Reply:"""Open the notebook in the configured browser."""record = _record(request)file = _context(request).bridge.index.file_of(record.id)@@ -893,7 +566,7 @@ async def _open_notebook(request: Request) -> Response:threading.Thread(target=_open_quietly, args=(browser, url), daemon=True).start()- return _reply(200, protocol.OpenNotebookResponse(url=url))+ return 200, protocol.OpenNotebookResponse(url=url)def _open_quietly(browser: str, url: str) -> None:@@ -906,65 +579,4 @@ def _open_quietly(browser: str, url: str) -> None:# ---- runtimes -------------------------------------------------------------------@_mutation("runtime.start")-async def _start_runtime(request: Request) -> Response:- """Start a runtime and return 202, or 200 if it already exists."""- key = request.headers["Idempotency-Key"]- notebook = await _notebook(request)- await _decode(request, protocol.StartRuntimeRequest)- runtime, created = notebook.start(request_id=key)- return _reply(202 if created else 200, runtime)---@_mutation("runtime.stop")-async def _stop_runtime(request: Request) -> Response:- """Request shutdown and return 202 with the runtime marked terminating."""- key = request.headers["Idempotency-Key"]- notebook = await _notebook(request)- runtime = notebook.stop(request_id=key)- return _reply(202, runtime)---@_mutation("runtime.restart")-async def _restart_runtime(request: Request) -> Response:- """Return 202 with the replacement runtime in its starting state."""- key = request.headers["Idempotency-Key"]- notebook = await _notebook(request)- runtime = notebook.restart(request_id=key)- return _reply(202, runtime)--# ---- runs -------------------------------------------------------------------------@_mutation("runtime.run")-async def _run(request: Request) -> Response:- """Queue a run and return 202. Results arrive through notebook events."""- key = request.headers["Idempotency-Key"]- notebook = await _notebook(request)- body = await _decode(request, protocol.RunRequest)- if isinstance(body.code, str) and body.cells is msgspec.UNSET:- started = notebook.run(body.code, request_id=key)- elif body.code is msgspec.UNSET and isinstance(body.cells, tuple):- started = notebook.run(cells=body.cells, request_id=key)- else:- return problem(- 400, "invalid-request", "A run names code or cells, not both"- )- return _reply(202, started)---@_mutation("runtime.run")-async def _interrupt(request: Request) -> Response:- """Interrupt an active run and return 202, or 409 if it has completed."""- notebook = await _notebook(request)- run_id = request.path_params["run_id"]- try:- interrupted = notebook.interrupt(run_id)- except NotFound:- # A completed scratch run is host history, not notebook state.- run = _context(request).bridge.host.run(notebook.id, run_id)- if run is not None and run.status == "completed":- raise Conflict(f"run {run_id} has already ended.") from None- raise- return _reply(202, interrupted)diff --git a/marimo/_server/host/context.py b/marimo/_server/host/context.pyindex 07dcf4860f..3c00f9463f 100644--- a/marimo/_server/host/context.py+++ b/marimo/_server/host/context.py@@ -4,62 +4,22 @@from __future__ import annotationsfrom dataclasses import dataclass, field-from time import monotonicfrom typing import TYPE_CHECKING-if TYPE_CHECKING:- import asyncio- from collections.abc import Callable-- from starlette.responses import Response+from marimo._core.operations import Mutations- from marimo._core import protocol+if TYPE_CHECKING:from marimo._server.host.bridge import SessionBridge-@dataclass-class CachedMutation:- """One accepted request, including its in-flight or completed reply."""-- fingerprint: str- task: asyncio.Task[Response]- run: protocol.Run | None = None- expires_at: float | None = None--@dataclassclass HostContext:- """Host API token, address, session bridge, and cached replies."""+ """Host API token, address, session bridge, and retry receipts."""bridge: SessionBridgetoken: strport: int- replies: dict[str, CachedMutation] = field(default_factory=dict)- # A receipt covers a client's retry loop after a lost response, so it- # outlasts retry backoff rather than a person's absence.- receipt_seconds: float = 300.0- clock: Callable[[], float] = monotonic-- def remembered(self, key: str) -> CachedMutation | None:- """Return the receipt for a key, dropping it if it has expired."""- reply = self.replies.get(key)- if reply is not None and self._expired(reply):- del self.replies[key]- return None- return reply-- def settle(self, mutation: CachedMutation) -> None:- """Start the receipt's retention window once its work is complete."""- mutation.expires_at = self.clock() + self.receipt_seconds-- def expire(self) -> None:- """Sweep expired receipts and the host's results."""- self.bridge.host.expire()- for key, reply in list(self.replies.items()):- if self._expired(reply):- del self.replies[key]+ mutations: Mutations = field(init=False)- def _expired(self, reply: CachedMutation) -> bool:- return (- reply.expires_at is not None and self.clock() >= reply.expires_at- )+ def __post_init__(self) -> None:+ self.mutations = Mutations(self.bridge.host)diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.pyindex 32134b16bd..36399e3cf3 100644--- a/marimo/_server/host/lifespan.py+++ b/marimo/_server/host/lifespan.py@@ -89,7 +89,7 @@ async def host(app: Starlette) -> AsyncIterator[None]:async def maintain() -> None:while True:await asyncio.sleep(1)- context.expire()+ context.mutations.expire()maintenance = asyncio.create_task(maintain(), name="host.retention")record = Nonediff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.pyindex 9c25e294a1..0554dce4ea 100644--- a/marimo/_server/host/middleware.py+++ b/marimo/_server/host/middleware.py@@ -20,7 +20,8 @@ from starlette.websockets import WebSocketfrom marimo import _loggersfrom marimo._server.host import HOST_API_PATH-from marimo._server.host.api import build_app, editor_events_route, problem+from marimo._server.host.api import build_app, editor_events_route+from marimo._server.host.notebook_api import problemif TYPE_CHECKING:from collections.abc import Sequencediff --git a/marimo/_server/host/notebook_api.py b/marimo/_server/host/notebook_api.pynew file mode 100644index 0000000000..4b9aa86d64--- /dev/null+++ b/marimo/_server/host/notebook_api.py@@ -0,0 +1,142 @@+# Copyright 2026 Marimo. All rights reserved.+"""HTTP routes for the notebook operations, and problem responses."""++from __future__ import annotations++from functools import wraps+from typing import TYPE_CHECKING, TypeVar++import msgspec+from starlette.exceptions import HTTPException+from starlette.responses import Response+from starlette.routing import Route++from marimo import _loggers+from marimo._core import operations, protocol+from marimo._core.calls import CALLS, dispatch+from marimo._core.errors import HostError+from marimo._core.operations import Reply++if TYPE_CHECKING:+ from collections.abc import Awaitable, Callable++ from starlette.requests import HTTPConnection, Request++ from marimo._core.calls import OperationCall+ from marimo._server.host.context import HostContext++LOGGER = _loggers.marimo_logger()+_Body = TypeVar("_Body", bound=msgspec.Struct)+++def _context(request: HTTPConnection) -> HostContext:+ context = getattr(request.app.state, "host_context", None)+ assert context is not None, "HostApiMiddleware admits requests only then"+ return context # type: ignore[no-any-return]+++def _response(status: int, body: msgspec.Struct | None) -> Response:+ media_type = (+ "application/problem+json"+ if isinstance(body, protocol.Problem)+ else "application/json"+ if body is not None+ else None+ )+ return Response(+ b"" if body is None else msgspec.json.encode(body),+ status_code=status,+ media_type=media_type,+ )+++def problem(+ status: int, kind: str | None = None, detail: str | None = None+) -> Response:+ if kind is None:+ kind = {+ 400: "invalid-request",+ 404: "not-found",+ 405: "method-not-allowed",+ 409: "conflict",+ }.get(status)+ if kind is None:+ LOGGER.error("The host API raised an unmapped status %s", status)+ status, kind, detail = 500, "internal", "The host failed"+ return _response(status, operations.problem(status, kind, detail))+++async def _decode(request: Request, kind: type[_Body]) -> _Body:+ return msgspec.json.decode(await request.body() or b"{}", type=kind)+++def _mutation(+ operation: str,+) -> Callable[+ [Callable[[Request], Awaitable[Reply]]],+ Callable[[Request], Awaitable[Response]],+]:+ """Use the same receipt store for catalog operations implemented by the server."""++ def decorate(+ endpoint: Callable[[Request], Awaitable[Reply]],+ ) -> Callable[[Request], Awaitable[Response]]:+ @wraps(endpoint)+ async def handle(request: Request) -> Response:+ try:+ status, body = await _context(request).mutations.execute(+ operation,+ notebook_id=request.path_params.get("notebook_id"),+ key=request.headers.get("Idempotency-Key", ""),+ payload=(+ request.method,+ request.url.path,+ await request.body(),+ request.headers.get("If-Match", ""),+ ),+ call=lambda: endpoint(request),+ )+ except msgspec.DecodeError as e:+ return problem(400, "invalid-request", str(e))+ except HTTPException as e:+ return problem(e.status_code, detail=e.detail)+ except HostError as e:+ failure = operations.problem_for(e)+ return _response(failure.status, failure)+ return _response(status, body)++ return handle++ return decorate+++def _endpoint(+ kind: type[OperationCall],+) -> Callable[[Request], Awaitable[Response]]:+ async def handle(request: Request) -> Response:+ # Assemble the call from the request's parts, the shape the client+ # sends to any transport, so every call passes the same validation.+ parts: dict[str, object] = {+ "operation": kind.__struct_config__.tag,+ "params": request.path_params,+ "headers": dict(request.headers),+ }+ if "body" in kind.__struct_fields__:+ parts["body"] = msgspec.Raw(await request.body() or b"{}")+ try:+ call = msgspec.json.decode(msgspec.json.encode(parts), type=kind)+ except msgspec.DecodeError as e:+ return problem(400, "invalid-request", str(e))+ context = _context(request)+ status, body = await dispatch(context.mutations, context.bridge, call)+ return _response(status, body)++ return handle+++def notebook_routes() -> list[Route]:+ """Serve each notebook operation at its path in the spec."""+ return [+ Route(kind.PATH, _endpoint(kind), methods=[kind.METHOD])+ for kind in CALLS+ ]diff --git a/tests/_core/conftest.py b/tests/_core/conftest.pyindex 92397a0c86..e1241c41bf 100644--- a/tests/_core/conftest.py+++ b/tests/_core/conftest.py@@ -6,10 +6,11 @@ from __future__ import annotationsimport asynciofrom typing import TYPE_CHECKING+import msgspecimport pytestfrom marimo._core import backend as be, protocol, protocol_events-from marimo._core.document import Document, code_hash+from marimo._core.document import Document, DocumentCell, code_hashfrom marimo._core.executions import CellExecution, Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook@@ -17,7 +18,7 @@ from marimo._core.run_log import RetentionPolicyfrom marimo._core.stream import RoutedEvent, Sink, event_nameif TYPE_CHECKING:- from collections.abc import Sequence+ from collections.abc import Mapping, SequenceOPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]@@ -173,6 +174,64 @@ def log(host: Host) -> list[RoutedEvent]:return events+class RecordingBridge:+ """A notebook bridge that counts edits and can hold one in flight."""++ def __init__(self, host: Host) -> None:+ self.host = host+ self.edits = 0+ self.started = asyncio.Event()+ self.release = asyncio.Event()+ self.release.set()+ self.preconditions: list[Sequence[str] | None] = []++ async def edit(+ self,+ notebook_id: str,+ changes: Sequence[protocol.Change],+ *,+ request_id: str,+ ) -> protocol.EditResponse:+ self.edits += 1+ self.started.set()+ await self.release.wait()+ notebook = await self.host.notebook(notebook_id)+ return notebook.edit(changes, request_id=request_id)++ async def save(+ self,+ notebook_id: str,+ *,+ if_match: Sequence[str] | None,+ decisions: Mapping[str, str],+ request_id: str,+ ) -> protocol.EditResponse:+ del decisions+ self.preconditions.append(if_match)+ notebook = await self.host.notebook(notebook_id)+ return notebook.edit((), request_id=request_id)+++async def bridge() -> RecordingBridge:+ host = Host(+ operations=(+ "notebook.edit",+ "notebook.save",+ "runtime.start",+ "runtime.run",+ )+ )+ host.update_project(project())+ await add_notebook(+ host,+ msgspec.structs.replace(record(), operations=tuple(host.operations)),+ ScriptedBackend(),+ document=Document([DocumentCell(protocol.CellId("c1"), "x = 1")], {}),+ )+ return RecordingBridge(host)++def names(events: list[RoutedEvent]) -> list[str]:return [event_name(e.event) for e in events]diff --git a/tests/_core/test_calls.py b/tests/_core/test_calls.pynew file mode 100644index 0000000000..90af6ef0e9--- /dev/null+++ b/tests/_core/test_calls.py@@ -0,0 +1,121 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from typing import Any, get_args, get_type_hints++import msgspec+import pytest++from marimo._core import calls, protocol+from marimo._core.calls import (+ CALLS,+ InterruptCall,+ MutationHeaders,+ OperationCall,+ RunParams,+)+from marimo._core.operations import NotebookBridge+from protocols.host.generate import compose++NOTEBOOK = protocol.NotebookId("n1")+++def test_calls_decode_from_request_parts() -> None:+ def decode(**parts: object) -> OperationCall:+ return msgspec.json.decode(+ msgspec.json.encode(parts), type=OperationCall+ )++ headers = {"idempotency-key": "k", "authorization": "Bearer t"}+ assert decode(+ operation="runtime.interrupt",+ params={"notebook_id": "n1", "run_id": "r1"},+ headers=headers,+ ) == InterruptCall(+ RunParams(NOTEBOOK, protocol.RunId("r1")), MutationHeaders("k")+ )+ for invalid in (+ {"operation": "runtime.interrupt", "params": {"notebook_id": "n1"}},+ {"operation": "notebook.missing", "params": {"notebook_id": "n1"}},+ ):+ with pytest.raises(msgspec.ValidationError):+ decode(**invalid, headers=headers)+++def test_calls_match_the_spec() -> None:+ document = compose()++ def resolve(value: dict[str, Any]) -> dict[str, Any]:+ if "$ref" not in value:+ return value+ target = document+ for part in value["$ref"].removeprefix("#/").split("/"):+ target = target[part]+ return target++ def schema_name(content: dict[str, Any]) -> str:+ reference: str = content["application/json"]["schema"]["$ref"]+ return reference.rsplit("/", 1)[1]++ def names(kind: type[msgspec.Struct]) -> set[str]:+ return {field.encode_name for field in msgspec.structs.fields(kind)}++ specified = {+ operation["operationId"]: (method.upper(), path, item, operation)+ for path, item in document["paths"].items()+ for method, operation in item.items()+ if isinstance(operation, dict) and "operationId" in operation+ }+ assert set(get_args(OperationCall)) == set(CALLS)+ assert {kind.__struct_config__.tag for kind in CALLS} == {+ operation_id+ for operation_id in specified+ if operation_id.startswith("runtime.")+ or operation_id in {"notebook.edit", "notebook.save"}+ }++ for kind in CALLS:+ method, path, item, operation = specified[+ str(kind.__struct_config__.tag)+ ]+ assert (kind.METHOD, kind.PATH) == (method, path)++ parameters = [+ resolve(parameter)+ for parameter in [+ *item.get("parameters", []),+ *operation.get("parameters", []),+ ]+ ]+ fields = {field.name: field for field in msgspec.structs.fields(kind)}+ assert names(fields["params"].type) == {+ parameter["name"]+ for parameter in parameters+ if parameter["in"] == "path"+ }+ assert names(fields["headers"].type) == {+ parameter["name"].lower()+ for parameter in parameters+ if parameter["in"] == "header"+ }+ body = operation.get("requestBody")+ if body is None:+ assert set(fields) == {"params", "headers"}+ else:+ assert set(fields) == {"params", "headers", "body"}+ assert fields["body"].type.__name__ == schema_name(+ resolve(body)["content"]+ )++ hints = get_type_hints(+ kind.handle, {**vars(calls), "NotebookBridge": NotebookBridge}+ )+ statuses, response = get_args(hints["return"])+ success = {+ int(status): resolve(value)+ for status, value in operation["responses"].items()+ if status.startswith("2")+ }+ assert set(get_args(statuses)) == set(success)+ for value in success.values():+ assert schema_name(value["content"]) == response.__name__diff --git a/tests/_core/test_mutations.py b/tests/_core/test_mutations.pynew file mode 100644index 0000000000..186f66757d--- /dev/null+++ b/tests/_core/test_mutations.py@@ -0,0 +1,123 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import asyncio++import msgspec+import pytest++from marimo._core import protocol+from marimo._core.calls import (+ EditCall,+ MutationHeaders,+ NotebookParams,+ OperationCall,+ SaveCall,+ SaveHeaders,+ StopCall,+ dispatch,+)+from marimo._core.operations import Mutations, Reply+from tests._core.test_notebook_document import put++NOTEBOOK = protocol.NotebookId("n1")+PARAMS = NotebookParams(NOTEBOOK)+++def edit(key: str, *changes: protocol.Change) -> EditCall:+ return EditCall(+ PARAMS, MutationHeaders(key), protocol.EditRequest(changes)+ )+++def save(key: str, if_match: str | None = None) -> SaveCall:+ return SaveCall(PARAMS, SaveHeaders(key, if_match), protocol.SaveRequest())+++def serve(bridge):+ mutations = Mutations(bridge.host)++ async def serve(call: OperationCall) -> Reply:+ return await dispatch(mutations, bridge, call)++ return serve+++def kind(reply: Reply) -> str:+ _, body = reply+ assert isinstance(body, protocol.Problem)+ return body.type.rsplit("/", 1)[1]+++async def test_edit_retry_and_atomic_conflict(bridge, serve):+ events = []+ bridge.host.subscribe(events.append, notebook_id=NOTEBOOK)+ call = edit("edit", put("c1", "x = 2", "*"))+ status, result = await serve(call)+ assert status == 200+ assert isinstance(result, protocol.EditResponse)+ event_count = len(events)+ assert event_count > 0+ assert await serve(call) == (200, result)+ assert (bridge.edits, len(events)) == (1, event_count)++ conflict = await serve(+ edit(+ "conflict", put("new", "y = 1", None), put("c1", "x = 3", "stale")+ )+ )+ assert conflict[0] == 409+ assert isinstance(conflict[1], protocol.Problem)+ assert conflict[1].edit.change == 1+ assert conflict[1].edit.cell.code == "x = 2"+ assert len(events) == event_count+ notebook = await bridge.host.notebook(NOTEBOOK)+ assert [cell.id for cell in notebook.document] == ["c1"]+++async def test_cancellation_and_concurrent_retry(bridge, serve):+ bridge.release.clear()+ call = edit("edit", put("c1", "x = 2", "*"))+ first = asyncio.create_task(serve(call))+ await asyncio.wait_for(bridge.started.wait(), 5)+ try:+ first.cancel()+ with pytest.raises(asyncio.CancelledError):+ await first+ retry = asyncio.create_task(serve(call))+ bridge.release.set()+ status, result = await asyncio.wait_for(retry, 5)+ assert status == 200+ assert isinstance(result, protocol.EditResponse)+ assert bridge.edits == 1+ finally:+ bridge.release.set()+++async def test_receipts_include_operation_and_preconditions(bridge, serve):+ saved = await serve(save("save", '"a", W/"weak", "b"'))+ assert saved[0] == 200+ assert await serve(save("save", '"a", W/"weak", "b"')) == saved+ assert kind(await serve(save("save", '"c"'))) == "conflict"+ assert kind(await serve(edit("save"))) == "conflict"+ assert bridge.preconditions == [("a", "b")]+++async def test_rejected_calls_do_not_reserve_keys(serve):+ assert kind(await serve(edit("edit", put("c1", "x = 2", "stale")))) == (+ "conflict"+ )+ status, _ = await serve(edit("edit", put("c1", "x = 2", "*")))+ assert status == 200+++async def test_calls_check_capabilities_and_keys(bridge, serve):+ stop = StopCall(PARAMS, MutationHeaders("stop"))+ assert kind(await serve(stop)) == "unsupported-operation"+ assert kind(await serve(edit(""))) == "invalid-request"+ bridge.host.update_notebook(+ msgspec.structs.replace(bridge.host.notebooks[NOTEBOOK], operations=())+ )+ assert kind(await serve(edit("edit"))) == "forbidden"+ assert bridge.edits == 0diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 61475b95bc..404a1a844d 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -148,13 +148,10 @@ def harness(monkeypatch.setattr(bridge, "_make_backend", make)bridge.index.refresh()- app.state.host_context = HostContext(- bridge=bridge,- token=TOKEN,- port=PORT,- receipt_seconds=30,- clock=lambda: harness.now,- )+ context = HostContext(bridge=bridge, token=TOKEN, port=PORT)+ context.mutations.receipt_seconds = 30+ context.mutations.clock = lambda: harness.now+ app.state.host_context = contextreturn harness@@ -339,6 +336,21 @@ async def test_an_empty_cursor_is_a_400_problem(harness: Harness) -> None:assert response.json()["type"].endswith("/invalid-request")+async def test_a_call_reads_only_its_own_parts(harness: Harness) -> None:+ nid = await harness.running()+ stopped = await finished(+ harness.app,+ "DELETE",+ f"/notebooks/{nid}/runtime",+ # A header cannot stand in for a path parameter, and a call without+ # a body ignores the one it is sent.+ headers={**key("stop"), "Notebook-Id": "missing", "Params": "{}"},+ body=b"not json",+ )+ assert stopped.status == 202, stopped.body+ assert stopped.json()["notebook_id"] == nid++async def test_a_nul_byte_in_a_path_is_a_400_problem(harness: Harness) -> None:response = await finished(harness.app,@@ -762,7 +774,7 @@ async def test_slow_restart_keeps_its_receipt(harness: Harness) -> None:# The receipt's 30-second window must not begin during shutdown/startup.harness.now = 100- harness.app.state.host_context.expire()+ harness.app.state.host_context.mutations.expire()notebook.observe(be.Exited(runtime_id_of(notebook)))notebook.observe(be.Running(runtime_id_of(notebook), "0.25.0"))calls = list(harness.backend().calls)@@ -816,7 +828,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(assert accepted.status == 202for now in (100, 200):harness.now = now- context.expire()+ context.mutations.expire()calls = list(harness.backend().calls)replayed = await finished(harness.app, method, path, headers=key("lifecycle")@@ -837,7 +849,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(assert harness.host._stream._listeners == listenerscalls = list(harness.backend().calls)harness.now = 229- context.expire()+ context.mutations.expire()replayed = await finished(harness.app, method, path, headers=key("lifecycle"))@@ -847,7 +859,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(calls,)harness.now = 230- assert context.remembered("lifecycle") is None+ assert context.mutations.remembered("lifecycle") is None@pytest.mark.parametrize(@@ -882,7 +894,7 @@ async def test_stop_settles_superseded_lifecycle_receipts(assert harness.host._stream._listeners == listenerscalls = list(harness.backend().calls)harness.now = 229- context.expire()+ context.mutations.expire()for request_id, verb, url, response in [("pending", method, pending_path, accepted),("stop-1", "DELETE", path, stops[0]),@@ -898,7 +910,7 @@ async def test_stop_settles_superseded_lifecycle_receipts()harness.now = 230assert [- context.remembered(request_id)+ context.mutations.remembered(request_id)for request_id in ("pending", "stop-1", "stop-2")] == [None, None, None]@@ -949,7 +961,10 @@ async def test_synchronous_lifecycle_completion(calls,)harness.now = 30- assert harness.app.state.host_context.remembered("immediate") is None+ assert (+ harness.app.state.host_context.mutations.remembered("immediate")+ is None+ )async def test_noop_and_rejected_lifecycle_requests_release_their_listeners(@@ -968,10 +983,10 @@ async def test_noop_and_rejected_lifecycle_requests_release_their_listeners(harness.app, "PUT", path, headers=key("invalid"), body=b"{")assert rejected.status == 400- assert context.remembered("invalid") is None+ assert context.mutations.remembered("invalid") is Noneassert harness.host._stream._listeners == listenersharness.now = 30- assert context.remembered("existing") is None+ assert context.mutations.remembered("existing") is Noneasync def test_run_filter_over_http(harness: Harness) -> None:@@ -1404,6 +1419,9 @@ async def test_operations_the_host_does_not_offer_are_501(host.update_project(project)host.add_notebook(harness.host.notebooks[notebook.id], make_notebook)harness.bridge.host = host+ harness.app.state.host_context = HostContext(+ bridge=harness.bridge, token=TOKEN, port=PORT+ )response = await finished(harness.app,"PUT",diff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.pyindex 3680c94e1f..1824a03b7f 100644--- a/tests/_server/host/test_host_record.py+++ b/tests/_server/host/test_host_record.py@@ -162,7 +162,7 @@ async def test_idle_host_expires_results_and_stops_maintenance(context = app.state.host_contexthost = context.bridge.hostnow = 0.0- host.clock = context.clock = lambda: now+ host.clock = context.mutations.clock = lambda: nowhost.update_project(project())notebook = await add_notebook(host, record(), ScriptedBackend())notebook.adopt(lambda _: None)@@ -203,6 +203,6 @@ async def test_idle_host_expires_results_and_stops_maintenance(]now = 300await asyncio.wait_for(removed.wait(), timeout=5)- assert context.replies == {}+ assert context.mutations.replies == {}assert maintenance.done()assert app.state.host_context is None