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
Publish a document's analysis as it becomes available (#11256)
Trevor Manz94736376074b
diff --git a/marimo/_core/analysis.py b/marimo/_core/analysis.pynew file mode 100644index 0000000000..0a6d2b05bc--- /dev/null+++ b/marimo/_core/analysis.py@@ -0,0 +1,31 @@+# Copyright 2026 Marimo. All rights reserved.+"""Document analysis for the host API."""++from __future__ import annotations++from typing import TYPE_CHECKING, Protocol++from marimo._core import protocol++if TYPE_CHECKING:+ from collections.abc import Mapping++ from marimo._core.document import DocumentSnapshot+++class Analyzer(Protocol):+ """Analysis of a document's cells.++ One instance belongs to one notebook. Calls are serialized, allowing+ implementations to cache compilation by cell ID and code hash.+ Results cover every cell in the snapshot, including syntax errors.+ Unexpected failures raise; they are not document diagnostics.++ Implementations must keep the event loop responsive. After cancelling+ a call, the notebook retires the instance: worker code may still run.+ """++ async def analyze(+ self, snapshot: DocumentSnapshot+ ) -> Mapping[protocol.CellId, protocol.CellAnalysis]:+ """Analyze a detached snapshot without modifying it."""diff --git a/marimo/_core/document.py b/marimo/_core/document.pyindex 978af39f68..8732dbfe62 100644--- a/marimo/_core/document.py+++ b/marimo/_core/document.py@@ -5,20 +5,14 @@ from __future__ import annotationsimport hashlibimport json-from collections.abc import Callable, Mappingfrom copy import deepcopyfrom dataclasses import dataclass, fieldfrom typing import TYPE_CHECKING, Any, Literal-from msgspec.structs import replace-from marimo._core import protocolif TYPE_CHECKING:- from collections.abc import Iterator, Sequence--Analyzer = Callable[[Mapping[str, str]], Mapping[str, protocol.Analysis]]-"""Derives every cell's analysis from the cells' code, keyed by id in document order."""+ from collections.abc import Iterator, Mapping, SequencePolicy = Literal["autorun", "lazy"]@@ -108,12 +102,20 @@ def revision()+@dataclass(frozen=True)+class DocumentSnapshot:+ """A detached document record and its cells in document order."""++ document: protocol.Document+ cells: tuple[protocol.Cell, ...]++@dataclass(frozen=True)class Changed:"""Changed cells, removed cell IDs, and the updated document."""cells: list[protocol.Cell]- """New cells, and cells whose etag or analysis changed."""+ """New cells, and cells whose etag changed."""removed: list[str]"""Ids of cells that no longer exist."""document: protocol.Document | None@@ -126,7 +128,7 @@ class Changed:class Document:"""A notebook document with content-derived revisions.- Cell source uses newline line endings. Analysis covers all cells.+ Cell source uses newline line endings."""def __init__(@@ -136,11 +138,9 @@ class Document:app_config: Mapping[str, Any],*,policy: Policy = "autorun",- analyzer: Analyzer | None = None,saved: bool = True,) -> None:self._id = notebook_id- self._analyzer = analyzerself._policy: Policy = policyself._cells: dict[str, protocol.Cell] = {}self._order: list[str] = []@@ -156,13 +156,11 @@ class Document:cls,document: protocol.Document,cells: Sequence[protocol.Cell],- *,- analyzer: Analyzer | None = None,) -> Document:"""Restore a document from its protocol records.- Cell identities, order, and revisions must agree. Analysis is kept- unless an analyzer is supplied. The saved revision is preserved.+ Cell identities, order, and revisions must agree. The saved+ revision is preserved."""document, cells = deepcopy((document, cells))by_id = {cell.id: cell for cell in cells}@@ -183,7 +181,6 @@ class Document:],document.app_config,policy=document.policy,- analyzer=analyzer,saved=False,)for cell in restored:@@ -193,10 +190,6 @@ class Document:or cell.code_hash != original.code_hash):raise ValueError("cell revisions must match their content")- if analyzer is None:- restored._cells[cell.id] = replace(- cell, analysis=original.analysis- )current = restored._recordif (current.etag != document.etag@@ -230,6 +223,10 @@ class Document:def cell(self, cell_id: str) -> protocol.Cell | None:return self._cells.get(cell_id)+ def snapshot(self) -> DocumentSnapshot:+ """Capture one revision without sharing mutable configuration."""+ return deepcopy(DocumentSnapshot(self._record, tuple(self)))+def replace(self, cells: Sequence[CellSource], app_config: Mapping[str, Any]) -> Changed:@@ -241,14 +238,6 @@ class Document:if len(set(order)) != len(order):raise ValueError("cell ids must be unique within the notebook")built = {source.id: self._build(source) for source in cells}- if self._analyzer is not None:- analyses = self._analyzer(- {cell_id: built[cell_id].code for cell_id in order}- )- for cell_id in order:- analysis = analyses.get(cell_id)- if analysis is not None:- built[cell_id] = replace(built[cell_id], analysis=analysis)changed = [built[cell_id]for cell_id in order@@ -282,7 +271,6 @@ class Document:config=source.config,etag=cell_etag(hashed, source.name, source.config),code_hash=hashed,- analysis=None,)def _refresh(self) -> protocol.Document | None:diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.pyindex 0b1aaed6f8..c458cddd61 100644--- a/marimo/_core/notebook.py+++ b/marimo/_core/notebook.py@@ -3,6 +3,8 @@from __future__ import annotations+import asyncio+import loggingfrom typing import TYPE_CHECKING, Anyimport msgspec@@ -17,11 +19,20 @@ from marimo._core.stream import Event, Kind, kind_of, message, utcnowif TYPE_CHECKING:from collections.abc import Callable, Mapping, Sequence- from marimo._core.document import CellSource, Changed, Document+ from marimo._core.analysis import Analyzer+ from marimo._core.document import (+ CellSource,+ Changed,+ Document,+ DocumentSnapshot,+ )from marimo._core.executions import Changefrom marimo._core.stream import Body, Sink+LOGGER = logging.getLogger(__name__)++class Notebook:"""A document, its execution results, and the runtime that produces them.@@ -29,6 +40,10 @@ class Notebook:Commands call the backend and publish changes through the sink.Change the document and executions through the notebook so eachchange reaches the sink.++ With an analyzer, the notebook requests analysis of each document+ revision and publishes the result when that revision is still+ current. The previous analysis stays until then."""def __init__(@@ -37,17 +52,26 @@ class Notebook:executions: Executions,backend: be.Backend,sink: Sink,+ *,+ analyzer: Analyzer | None = None,) -> None:self._document = documentself._executions = executionsself.backend = backendself.sink = sink+ self._analyzer = analyzerself._closed = Falseself._runtime: protocol.Runtime | None = Noneself._attachments: dict[str, protocol.Attachment] = {}self._replacement: protocol.Runtime | None = None# Correlate runtime events with the pending start, stop, or restart.self._runtime_request: str | None = None+ self._analysis: protocol.Analysis | None = None+ self._analysis_task: asyncio.Task[None] | None = None+ # Whether the document changed during analysis, and that request.+ self._reanalyze = False+ self._reanalyze_request: str | None = None+ self._request_analysis(None)@propertydef document(self) -> Document:@@ -68,6 +92,11 @@ class Notebook:"""The current runtime, if any."""return self._runtime+ @property+ def analysis(self) -> protocol.Analysis | None:+ """The latest analysis, which may describe an earlier revision."""+ return self._analysis+def _require_open(self) -> None:if self._closed:raise NotFound(f"no notebook {self.id}")@@ -85,6 +114,8 @@ class Notebook:self._require_open()changed = self.document.replace(cells, app_config)self._publish_changed(changed, request_id)+ if changed.document is not None:+ self._request_analysis(request_id)return changeddef mark_saved(self, *, request_id: str | None = None) -> None:@@ -108,6 +139,49 @@ class Notebook:if changed.document is not None:self._publish(changed.document, request_id)+ # ---- analysis ------------------------------------------------------++ def _request_analysis(self, request_id: str | None) -> None:+ """Analyze the current revision, or after the one in progress."""+ if self._analyzer is None or self._closed:+ return+ if self._analysis_task is not None:+ self._reanalyze, self._reanalyze_request = True, request_id+ return+ self._analysis_task = asyncio.create_task(+ self._analyze(self.document.snapshot(), request_id)+ )++ async def _analyze(+ self, snapshot: DocumentSnapshot, request_id: str | None+ ) -> None:+ assert self._analyzer is not None+ try:+ while not self._closed:+ etag = snapshot.document.etag+ try:+ cells = await self._analyzer.analyze(snapshot)+ except Exception:+ LOGGER.exception("Could not analyze document %s", etag)+ else:+ if not self._closed and etag == self.document._record.etag:+ self._analysis = protocol.Analysis(+ notebook_id=self.id,+ document_etag=etag,+ cells={+ cid: analysis+ for cid, analysis in cells.items()+ },+ )+ self._publish(self._analysis, request_id)+ if not self._reanalyze or self._closed:+ return+ request_id = self._reanalyze_request+ self._reanalyze, self._reanalyze_request = False, None+ snapshot = self.document.snapshot()+ finally:+ self._analysis_task = None+# ---- runtime -------------------------------------------------------def start(@@ -280,7 +354,7 @@ class Notebook:# ---- backend updates -----------------------------------------------def observe(self, msg: be.Message) -> None:- """Apply a backend update and publish the resulting state changes."""+ """Apply a backend report and publish what changed."""if self._closed:returnmatch msg:@@ -369,6 +443,8 @@ class Notebook:def _snapshot(self) -> list[Event]:"""Return current state as events in dependency order."""bodies: list[Body] = [*self.document, self.document._record]+ if self._analysis is not None:+ bodies.append(self._analysis)if self._runtime is not None:bodies.append(self._runtime)bodies.extend(self._attachments.values())@@ -397,6 +473,8 @@ class Notebook:The host publishes `notebook.removed` after disposing of this state."""self._closed = True+ if self._analysis_task is not None:+ self._analysis_task.cancel()self._apply(self.executions.interrupt())self._apply(self.executions.clear())for attachment_id in list(self._attachments):diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex f06910286d..b917016c5c 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -279,6 +279,7 @@ ObjectType: TypeAlias = Annotated["project","notebook","document",+ "analysis","cell","runtime","attachment",@@ -289,7 +290,7 @@ ObjectType: TypeAlias = Annotated["custom",],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, document, cell,\nruntime, attachment, run, execution, console, display, and custom.\nCustom events describe occurrences rather than object state.\n"+ 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, document,\nanalysis, cell, runtime, attachment, run, execution, console,\ndisplay, and custom. Custom events describe occurrences rather\nthan object state.\n"),]@@ -637,11 +638,63 @@ class AttachmentMessage(Struct, frozen=True):) = UNSET+class Cell(Struct, frozen=True):+ code: Annotated[+ str,+ Meta(+ description="The cell's source code, with newline line endings. A host normalizes other line endings when it loads a file."+ ),+ ]+ code_hash: Annotated[+ Etag,+ Meta(+ description="Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code."+ ),+ ]+ config: CellConfig+ etag: Annotated[+ Etag,+ Meta(+ description="Identifies code, name, and config together, and is the precondition for editing the cell. Its text is `code_hash`, `name`, and the config values `column`, `disabled`, `hide_code`, and `expand_output` in that order, each written as a JSON scalar such as `null`, `0`, or `true`."+ ),+ ]+ id: CellId+ name: Annotated[+ str,+ Meta(+ description="The cell's name. `_` for an anonymous cell; otherwise a Python identifier, unique within the notebook."+ ),+ ]+ notebook_id: NotebookId++class CellEtags(Struct, frozen=True):code_hash: Etagetag: Etag+class CellMessage(Struct, frozen=True):+ cell: Cell+ request_id: (+ Annotated[+ str,+ Meta(+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."+ ),+ ]+ | UnsetType+ ) = UNSET+ time: (+ Annotated[+ datetime,+ Meta(+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."+ ),+ ]+ | UnsetType+ ) = UNSET++Change: TypeAlias = Annotated[PutCell | DeleteCell | SetOrder | SetAppConfig,Meta(description="One change to the document, tagged on `kind`."),@@ -840,6 +893,26 @@ class DocumentMessage(Struct, frozen=True):) = UNSET+class EditConflict(Struct, frozen=True):+ cell: (+ Annotated[+ Cell,+ Meta(+ description="The cell the change named, as it now is. Null when the document does not have it, or when the change named the order or the app config."+ ),+ ]+ | None+ )+ change: Annotated[+ int,+ Meta(+ description="The index of the stale change in the request's `changes`, or of the stale cell in a run's `cells`. `0` for a save with a stale `If-Match`.",+ ge=0,+ ),+ ]+ document: Document++class EditRequest(Struct, frozen=True):changes: Annotated[tuple[Change, ...],@@ -1010,6 +1083,54 @@ Outcome: TypeAlias = Annotated[]+class Problem(Struct, frozen=True):+ 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), `method-not-allowed`\n(405), `not-acceptable` (406), `conflict` (409), `no-runtime`\n(409), `decision-required` (409), `internal` (500), or\n`unsupported-operation` (501). A client that sees a kind it\ndoes not recognize falls back to `status`.\n"+ ),+ ]+ decisions: (+ Annotated[+ tuple[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+ edit: (+ Annotated[+ EditConflict,+ Meta(+ description="Which change was stale and what the host holds instead. Only present for a `conflict` answering an edit, a save, or a run of cells."+ ),+ ]+ | UnsetType+ ) = UNSET++class Project(Struct, frozen=True):id: ProjectIdmessage: (@@ -1185,7 +1306,7 @@ class RuntimeMessage(Struct, frozen=True):) = UNSET-class Analysis(Struct, frozen=True):+class CellAnalysis(Struct, frozen=True):defs: Annotated[tuple[str, ...], Meta(description="Names this cell defines.")]@@ -1201,87 +1322,6 @@ class Analysis(Struct, frozen=True):]-class Cell(Struct, frozen=True):- analysis: (- Annotated[- Analysis,- Meta(- description="Derived from the code by the host. Null when the host has no analyzer."- ),- ]- | None- )- code: Annotated[- str,- Meta(- description="The cell's source code, with newline line endings. A host normalizes other line endings when it loads a file."- ),- ]- code_hash: Annotated[- Etag,- Meta(- description="Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code."- ),- ]- config: CellConfig- etag: Annotated[- Etag,- Meta(- description="Identifies code, name, and config together, and is the precondition for editing the cell. Its text is `code_hash`, `name`, and the config values `column`, `disabled`, `hide_code`, and `expand_output` in that order, each written as a JSON scalar such as `null`, `0`, or `true`."- ),- ]- id: CellId- name: Annotated[- str,- Meta(- description="The cell's name. `_` for an anonymous cell; otherwise a Python identifier, unique within the notebook."- ),- ]- notebook_id: NotebookId---class CellMessage(Struct, frozen=True):- cell: Cell- request_id: (- Annotated[- str,- Meta(- description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."- ),- ]- | 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 EditConflict(Struct, frozen=True):- cell: (- Annotated[- Cell,- Meta(- description="The cell the change named, as it now is. Null when the document does not have it, or when the change named the order or the app config."- ),- ]- | None- )- change: Annotated[- int,- Meta(- description="The index of the stale change in the request's `changes`, or of the stale cell in a run's `cells`. `0` for a save with a stale `If-Match`.",- ge=0,- ),- ]- document: Document--class Execution(Struct, frozen=True):bindings: Annotated[tuple[Binding, ...],@@ -1402,48 +1442,38 @@ class ExecutionMessage(Struct, frozen=True):) = UNSET-class Problem(Struct, frozen=True):- status: Annotated[- int,- Meta(- description="The HTTP status code of the response.", ge=400, le=599- ),+class Analysis(Struct, frozen=True):+ cells: Annotated[+ dict[str, CellAnalysis],+ Meta(description="Every cell of that revision, by id."),]- title: Annotated[- str,+ document_etag: Annotated[+ Etag,Meta(- description="A short, human-readable name for the kind of problem."+ description="The document revision this analysis describes. Equal to the document's `etag` while the analysis is current."),]- 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), `method-not-allowed`\n(405), `not-acceptable` (406), `conflict` (409), `no-runtime`\n(409), `decision-required` (409), `internal` (500), or\n`unsupported-operation` (501). A client that sees a kind it\ndoes not recognize falls back to `status`.\n"- ),+ notebook_id: Annotated[+ NotebookId, Meta(description="The notebook this analysis belongs to.")]- decisions: (- Annotated[- tuple[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: (+++class AnalysisMessage(Struct, frozen=True):+ analysis: Analysis+ request_id: (Annotated[str,Meta(- description="A human-readable explanation of what went wrong this time."+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."),]| UnsetType) = UNSET- edit: (+ time: (Annotated[- EditConflict,+ datetime,Meta(- description="Which change was stale and what the host holds instead. Only present for a `conflict` answering an edit, a save, or a run of cells."+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."),]| UnsetTypediff --git a/marimo/_core/stream.py b/marimo/_core/stream.pyindex 90adb0ea05..aecf205c18 100644--- a/marimo/_core/stream.py+++ b/marimo/_core/stream.py@@ -29,6 +29,7 @@ Body: TypeAlias = (| protocol.Project| protocol.Notebook| protocol.Document+ | protocol.Analysis| protocol.Cell| protocol.Runtime| protocol.Attachment@@ -47,6 +48,7 @@ Kind: TypeAlias = Literal["project","notebook","document",+ "analysis","cell","runtime","attachment",diff --git a/marimo/_runtime/dataflow/edges.py b/marimo/_runtime/dataflow/edges.pyindex 3778d9afa4..81c905c078 100644--- a/marimo/_runtime/dataflow/edges.py+++ b/marimo/_runtime/dataflow/edges.py@@ -136,51 +136,18 @@ def _resolve_variable_name(return name-def compute_edges_for_cell(+def resolve_cell_references(cell_id: CellId_t,cell: CellImpl,topology: GraphTopology,definitions: DefinitionRegistry,-) -> tuple[set[CellId_t], set[CellId_t]]:- """Compute parent and child edges for a cell being registered.+) -> dict[Name, set[CellId_t]]:+ """Resolve each reference to its defining cells using language semantics.- Args:- cell_id: The ID this cell is being registered with- cell: The cell to compute edges for- topology: The graph topology- definitions: The definition registry-- Returns:- Tuple of (parents, children) where:- - parents: cells that this cell depends on- - children: cells that depend on this cell+ Keys retain the reference as written, including SQL qualification.+ Unresolved names and references to the cell itself are excluded."""- parents: set[CellId_t] = set()- children: set[CellId_t] = set()-- # First, process the variables that this cell defines. Any cell- # that refers to a defined variable becomes a child of this cell.- for name, variable_data in cell.variable_data.items():- # NB. Only the last definition matters.- # Technically more nuanced with branching statements, but this is- # the best we can do with static analysis.- variable = variable_data[-1]-- # a cell can refer to its own defs, but that doesn't add an- # edge to the dependency graph- referring_cells = get_referring_cells(- name,- language=variable.language,- topology=topology,- ) - {cell_id}-- children.update(referring_cells)-- # Next, process the cells references. The cell becomes a child- # of cells that define its referenced variables. We also have- # special logic for handling references that are deleted by this cell,- # since cells that delete variables that were defined elsewhere- # are made children of cells that reference that variable.+ resolved: dict[Name, set[CellId_t]] = {}for name in cell.refs:# First, for each referenced variable, we add cells that define# that variable as parents@@ -242,8 +209,62 @@ def compute_edges_for_cell(kind=cast(SQLTypes, other_variable_data.kind),):continue- parents.add(other_id)+ resolved.setdefault(name, set()).add(other_id)++ return resolved+++def compute_edges_for_cell(+ cell_id: CellId_t,+ cell: CellImpl,+ topology: GraphTopology,+ definitions: DefinitionRegistry,+) -> tuple[set[CellId_t], set[CellId_t]]:+ """Compute parent and child edges for a cell being registered.++ Args:+ cell_id: The ID this cell is being registered with+ cell: The cell to compute edges for+ topology: The graph topology+ definitions: The definition registry++ Returns:+ Tuple of (parents, children) where:+ - parents: cells that this cell depends on+ - children: cells that depend on this cell+ """+ parents: set[CellId_t] = set()+ children: set[CellId_t] = set()++ # First, process the variables that this cell defines. Any cell+ # that refers to a defined variable becomes a child of this cell.+ for name, variable_data in cell.variable_data.items():+ # NB. Only the last definition matters.+ # Technically more nuanced with branching statements, but this is+ # the best we can do with static analysis.+ variable = variable_data[-1]++ # a cell can refer to its own defs, but that doesn't add an+ # edge to the dependency graph+ referring_cells = get_referring_cells(+ name,+ language=variable.language,+ topology=topology,+ ) - {cell_id}++ children.update(referring_cells)++ for defining_cells in resolve_cell_references(+ cell_id, cell, topology, definitions+ ).values():+ parents.update(defining_cells)+ # Next, process the cells references. The cell becomes a child+ # of cells that define its referenced variables. We also have+ # special logic for handling references that are deleted by this cell,+ # since cells that delete variables that were defined elsewhere+ # are made children of cells that reference that variable.+ for name in cell.refs:# Next, any cell that deletes this referenced variable is made# a child of this cell. In particular, if a cell deletes a# variable, it becomes a child of all other cells thatdiff --git a/marimo/_server/host/analysis.py b/marimo/_server/host/analysis.pyindex dc382b33a2..40246711ce 100644--- a/marimo/_server/host/analysis.py+++ b/marimo/_server/host/analysis.py@@ -1,84 +1,92 @@# Copyright 2026 Marimo. All rights reserved.-"""Cell definitions, references, and syntax errors.+"""Cell definitions, references, and syntax errors for the host protocol.-The kernel reports errors involving multiple cells, such as cycles-and multiple definitions.+The kernel reports errors involving multiple cells."""from __future__ import annotations+import asyncio+from dataclasses import dataclassfrom typing import TYPE_CHECKING+from marimo._ast.cell import CellImplfrom marimo._ast.compiler import compile_cellfrom marimo._core import protocol+from marimo._runtime.dataflow import DirectedGraph+from marimo._runtime.dataflow.edges import resolve_cell_referencesfrom marimo._types.ids import CellId_tif TYPE_CHECKING:- from collections.abc import Mapping-- from marimo._ast.cell import CellImpl+ from marimo._core.document import DocumentSnapshotSOURCE = "marimo"-class Analyzer:- """Incremental analysis for one document."""+class HostAnalyzer:+ """Analyze serialized document snapshots in a worker thread."""++ def __init__(self) -> None:+ self._cells = CellAnalyzer()++ async def analyze(+ self, snapshot: DocumentSnapshot+ ) -> dict[protocol.CellId, protocol.CellAnalysis]:+ return await asyncio.to_thread(self._cells, snapshot)+++@dataclass(frozen=True)+class _CachedCell:+ code_hash: protocol.Etag+ result: CellImpl | protocol.Error+++class CellAnalyzer:+ """Reuse compilation by cell identity and code hash across snapshots."""def __init__(self) -> None:- self._codes: dict[str, str] = {}- self._compiled: dict[str, CellImpl] = {}- self._syntax: dict[str, protocol.Error] = {}+ self._cache: dict[protocol.CellId, _CachedCell] = {}def __call__(- self, codes: Mapping[str, str]- ) -> dict[str, protocol.Analysis]:- self._update(codes)- definers: dict[str, int] = {}- for cell in self._compiled.values():- for name in cell.defs:- definers[name] = definers.get(name, 0) + 1- result: dict[str, protocol.Analysis] = {}- for cell_id in codes:- compiled = self._compiled.get(cell_id)- if compiled is None:- result[cell_id] = protocol.Analysis(- defs=(), refs=(), errors=(self._syntax[cell_id],)- )- continue- result[cell_id] = protocol.Analysis(- defs=tuple(sorted(compiled.defs)),- refs=tuple(- sorted(- name- for name in compiled.refs- if definers.get(name, 0) > (name in compiled.defs)+ self, snapshot: DocumentSnapshot+ ) -> dict[protocol.CellId, protocol.CellAnalysis]:+ cache: dict[protocol.CellId, _CachedCell] = {}+ graph = DirectedGraph()+ for cell in snapshot.cells:+ cached = self._cache.get(cell.id)+ if cached is None or cached.code_hash != cell.code_hash:+ try:+ result: CellImpl | protocol.Error = compile_cell(+ cell.code, CellId_t(cell.id))- ),- errors=(),- )- return result-- def _update(self, codes: Mapping[str, str]) -> None:- """Forget cells that are gone or changed, then compile what is new."""- for cell_id in list(self._codes):- if codes.get(cell_id) == self._codes[cell_id]:- continue- del self._codes[cell_id]- self._syntax.pop(cell_id, None)- self._compiled.pop(cell_id, None)- for cell_id, code in codes.items():- if cell_id in self._codes:- continue- try:- self._compiled[cell_id] = compile_cell(code, CellId_t(cell_id))- except (SyntaxError, ValueError) as error:- self._syntax[cell_id] = _syntax_error(code, error)- self._codes[cell_id] = code---def analyze(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:- """Analyze a document once."""- return Analyzer()(codes)+ except (SyntaxError, ValueError) as error:+ result = _syntax_error(cell.code, error)+ cached = _CachedCell(cell.code_hash, result)+ cache[cell.id] = cached+ if isinstance(cached.result, CellImpl):+ graph.register_cell(CellId_t(cell.id), cached.result)+ self._cache = cache++ analyses: dict[protocol.CellId, protocol.CellAnalysis] = {}+ for cell in snapshot.cells:+ compiled = cache[cell.id].result+ if isinstance(compiled, protocol.Error):+ analyses[cell.id] = protocol.CellAnalysis(+ defs=(), refs=(), errors=(compiled,)+ )+ else:+ refs = resolve_cell_references(+ CellId_t(cell.id),+ compiled,+ graph,+ graph.definition_registry,+ )+ analyses[cell.id] = protocol.CellAnalysis(+ defs=tuple(sorted(compiled.defs)),+ refs=tuple(sorted(refs)),+ errors=(),+ )+ return analysesdef _syntax_error(code: str, e: Exception) -> protocol.Error:diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex 4b24599b80..587dbe4b26 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -16,7 +16,7 @@ from marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._runtime.commands import RenameNotebookCommandfrom marimo._server.host import OPERATIONS-from marimo._server.host.analysis import Analyzer+from marimo._server.host.analysis import HostAnalyzerfrom marimo._server.host.backend import SessionBackendfrom marimo._server.host.index import WorkspaceIndexfrom marimo._session.events import SessionEventListener@@ -105,13 +105,18 @@ class SessionBridge(SessionEventListener):cells,app_config,policy=self._policy(file, session),- analyzer=Analyzer(),saved=session is None,)if session is not None and loaded is not None:document.mark_saved(revision(*loaded))backend = self._make_backend(record.id)- return Notebook(document, Executions(), backend, sink)+ return Notebook(+ document,+ Executions(),+ backend,+ sink,+ analyzer=HostAnalyzer(),+ )async def _load(self, file: Pathdiff --git a/protocols/host/conformance/contract.py b/protocols/host/conformance/contract.pyindex bd5f3eb60e..0ec407f3e5 100644--- a/protocols/host/conformance/contract.py+++ b/protocols/host/conformance/contract.py@@ -27,6 +27,7 @@ KINDS = ("project","notebook","document",+ "analysis","cell","runtime","attachment",diff --git a/protocols/host/conformance/test_contract.py b/protocols/host/conformance/test_contract.pyindex 829f2d86de..f8c996d06b 100644--- a/protocols/host/conformance/test_contract.py+++ b/protocols/host/conformance/test_contract.py@@ -25,6 +25,7 @@ FIXTURES = ROOT / "fixtures"MODELS = {"record.json": "HostRecord","cell.json": "Cell",+ "analysis.json": "Analysis","diagnostic.json": "Error","edit.json": "EditRequest","edit-conflict-request.json": "EditRequest",@@ -65,6 +66,18 @@ async def test_stream_examples(path):frame.message()[email protected]("message", [{}, {"analysis": {}}])+async def test_invalid_analysis_messages_are_rejected(message):+ data = json.dumps(message)+ with pytest.raises(ValidationError):+ Frame(event="analysis", data=data).message()++ stream = f"event: analysis\ndata: {data}\n\nevent: ready\ndata: {{}}\n\n"+ watch = Watch(frames(lines(stream)), timeout=1)+ with pytest.raises(ValidationError):+ await watch.ready()++async def test_sse_preserves_multiline_data_comments_and_explicit_ids():stream = ": ping\r\nid: 7\r\nevent: future\r\ndata: one\r\ndata: two\r\n\r\nevent: ready\ndata: {}\n\n"assert [frame async for frame in frames(lines(stream))] == [diff --git a/protocols/host/fixtures/README.md b/protocols/host/fixtures/README.mdindex 78bf82cf83..3127167794 100644--- a/protocols/host/fixtures/README.md+++ b/protocols/host/fixtures/README.md@@ -8,7 +8,8 @@ opaque. Gaps represent events outside an excerpt or its filter.`notebook-events.sse` opens a stream for notebook `n1` during the scratch runshown in `run.sse`. Its snapshot includes the display and console outputalready produced. Both streams end with the same execution and run completion-events, using the same cursors. `cell.json` is cell `c3` from that snapshot.+events, using the same cursors. `cell.json` is cell `c3` from that snapshot,+and `analysis.json` is the analysis of that document.`run-cells-request.json` requests `c3`, which defines `x`. In `run-cells.sse`,the runtime then evaluates `k7f2`, which defines `y` using `x`. The dependentdiff --git a/protocols/host/fixtures/analysis.json b/protocols/host/fixtures/analysis.jsonnew file mode 100644index 0000000000..6c108eeb19--- /dev/null+++ b/protocols/host/fixtures/analysis.json@@ -0,0 +1,29 @@+{+ "notebook_id": "n1",+ "document_etag": "e59d9c2af02f5814",+ "cells": {+ "c1": {+ "defs": [+ "mo"+ ],+ "refs": [],+ "errors": []+ },+ "c3": {+ "defs": [+ "x"+ ],+ "refs": [],+ "errors": []+ },+ "k7f2": {+ "defs": [+ "y"+ ],+ "refs": [+ "x"+ ],+ "errors": []+ }+ }+}diff --git a/protocols/host/fixtures/cell.json b/protocols/host/fixtures/cell.jsonindex dbebc929bd..5c3ad310cf 100644--- a/protocols/host/fixtures/cell.json+++ b/protocols/host/fixtures/cell.json@@ -10,12 +10,5 @@"expand_output": false},"etag": "5cf78587dcf22d8d",- "code_hash": "0f71456db2ea83f4",- "analysis": {- "defs": [- "x"- ],- "refs": [],- "errors": []- }+ "code_hash": "0f71456db2ea83f4"}diff --git a/protocols/host/fixtures/edits.sse b/protocols/host/fixtures/edits.sseindex 187986001d..7bd0343ec9 100644--- a/protocols/host/fixtures/edits.sse+++ b/protocols/host/fixtures/edits.sse@@ -1,10 +1,10 @@id: 110event: cell-data: {"cell":{"id":"c2","notebook_id":"n1","code":"print('hi')","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"ce27bab48d697cfc","code_hash":"c2d0a5e0790d97a0","analysis":{"defs":[],"refs":[],"errors":[]}},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}+data: {"cell":{"id":"c2","notebook_id":"n1","code":"print('hi')","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"ce27bab48d697cfc","code_hash":"c2d0a5e0790d97a0"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}id: 111event: cell-data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 22","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"dde89bbcc1863211","code_hash":"43e1a529dbae470b","analysis":{"defs":["x"],"refs":[],"errors":[]}},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}+data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 22","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"dde89bbcc1863211","code_hash":"43e1a529dbae470b"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}id: 112event: cell.removeddiff --git a/protocols/host/fixtures/notebook-events.sse b/protocols/host/fixtures/notebook-events.sseindex f79536dd5a..190a7afcbb 100644--- a/protocols/host/fixtures/notebook-events.sse+++ b/protocols/host/fixtures/notebook-events.sse@@ -2,17 +2,20 @@ event: notebookdata: {"notebook":{"id":"n1","project_id":"p1","path":"forecasts.py","name":"forecasts","operations":["notebook.update","notebook.delete","notebook.open","notebook.edit","notebook.save","runtime.start","runtime.stop","runtime.run","runtime.interrupt"],"updated_at":"2026-10-01T09:00:00Z"}}event: cell-data: {"cell":{"id":"c1","notebook_id":"n1","code":"import marimo as mo","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"48d6363150d6281c","code_hash":"f649a0b56c5c1966","analysis":{"defs":["mo"],"refs":[],"errors":[]}}}+data: {"cell":{"id":"c1","notebook_id":"n1","code":"import marimo as mo","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"48d6363150d6281c","code_hash":"f649a0b56c5c1966"}}event: cell-data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 21","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"5cf78587dcf22d8d","code_hash":"0f71456db2ea83f4","analysis":{"defs":["x"],"refs":[],"errors":[]}}}+data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 21","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"5cf78587dcf22d8d","code_hash":"0f71456db2ea83f4"}}event: cell-data: {"cell":{"id":"k7f2","notebook_id":"n1","code":"y = x * 2","name":"_","config":{"column":null,"disabled":false,"hide_code":true,"expand_output":false},"etag":"f199b5f48ae0aabb","code_hash":"db2b9ee97e1ecf4c","analysis":{"defs":["y"],"refs":["x"],"errors":[]}}}+data: {"cell":{"id":"k7f2","notebook_id":"n1","code":"y = x * 2","name":"_","config":{"column":null,"disabled":false,"hide_code":true,"expand_output":false},"etag":"f199b5f48ae0aabb","code_hash":"db2b9ee97e1ecf4c"}}event: documentdata: {"document":{"notebook_id":"n1","order":["c1","c3","k7f2"],"app_config":{"width":"full"},"policy":"autorun","etag":"e59d9c2af02f5814","saved_etag":"e59d9c2af02f5814","order_etag":"b9c412c2d7d63161","app_config_etag":"283513048dfeb45b"}}+event: analysis+data: {"analysis":{"notebook_id":"n1","document_etag":"e59d9c2af02f5814","cells":{"c1":{"defs":["mo"],"refs":[],"errors":[]},"c3":{"defs":["x"],"refs":[],"errors":[]},"k7f2":{"defs":["y"],"refs":["x"],"errors":[]}}}}+event: runtimedata: {"runtime":{"id":"r1","notebook_id":"n1","status":"running","message":null,"marimo_version":"0.25.0","started_at":"2026-10-01T09:14:02Z"}}diff --git a/protocols/host/fixtures/problems/edit-conflict.json b/protocols/host/fixtures/problems/edit-conflict.jsonindex 4a1a8c5a9a..6c9e3fffc0 100644--- a/protocols/host/fixtures/problems/edit-conflict.json+++ b/protocols/host/fixtures/problems/edit-conflict.json@@ -17,14 +17,7 @@"expand_output": false},"etag": "dde89bbcc1863211",- "code_hash": "43e1a529dbae470b",- "analysis": {- "defs": [- "x"- ],- "refs": [],- "errors": []- }+ "code_hash": "43e1a529dbae470b"},"document": {"notebook_id": "n1",diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex 53949b5a29..e157dc39e7 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -219,7 +219,8 @@ paths:that orders them, in the opening phase and after every change, soa client never holds a document whose `order` names a cell it hasnot received. The effects of one change to the document arrive- together, with no other event between them.+ together, with no other event between them. The analysis, when+ the host has one, follows the document it describes.parameters:- $ref: '#/components/parameters/NotebookId'- $ref: '#/components/parameters/Types'@@ -237,7 +238,7 @@ paths:description: |One event. `data` holds JSON, and the event name sayswhich shape: a NotebookMessage, DocumentMessage,- CellMessage, RuntimeMessage, AttachmentMessage,+ AnalysisMessage, CellMessage, RuntimeMessage, AttachmentMessage,RunMessage, ExecutionMessage, ConsoleMessage, orDisplayMessage for an event namedafter that kind; a CustomMessage for `custom`; a RemovedMessage@@ -292,7 +293,9 @@ paths:On success the document has changed, and every attachment seesthe effects on the notebook's stream with this request's key: thecells that changed, `cell.removed` for each deleted cell, and then- the document, with nothing in between. The response carries the+ the document, with nothing in between. The analysis of the new+ revision follows with the same key once the host has it. The+ response carries thenew etags, so a client keeps editing without reading again. Achange that changes nothing keeps its etags and sends no events.Whether the result has reached the store shows in the document's@@ -826,10 +829,11 @@ components:description: |The kinds a stream carries, and the values `types` accepts. Thecatalog stream carries host, project, notebook, runtime, and- attachment. A notebook's stream carries notebook, document, cell,- runtime, attachment, run, execution, console, display, and custom.- Custom events describe occurrences rather than object state.- enum: [host, project, notebook, document, cell, runtime, attachment, run, execution, console, display, custom]+ attachment. A notebook's stream carries notebook, document,+ analysis, cell, runtime, attachment, run, execution, console,+ display, and custom. Custom events describe occurrences rather+ than object state.+ enum: [host, project, notebook, document, analysis, cell, runtime, attachment, run, execution, console, display, custom]Custom:type: objectdescription: |@@ -1284,15 +1288,31 @@ components:type: booleandescription: Whether clients show the full output rather than a scrolled box.Analysis:+ type: object+ description: |+ What a document's cells imply, computed together over one+ revision of the document so that cross-cell errors agree. One+ per notebook, and removed with it. It follows the document it+ describes, and `document_etag` says which revision that is.+ required: [notebook_id, document_etag, cells]+ properties:+ notebook_id:+ $ref: '#/components/schemas/NotebookId'+ description: The notebook this analysis belongs to.+ document_etag:+ $ref: '#/components/schemas/Etag'+ description: The document revision this analysis describes. Equal to the document's `etag` while the analysis is current.+ cells:+ type: object+ additionalProperties: { $ref: '#/components/schemas/CellAnalysis' }+ description: Every cell of that revision, by id.+ CellAnalysis:type: objectdescription: |What a cell's text implies: the names it defines and reads, whichare the edges of the dependency graph, and the errors found in thetext alone or across the set of cells. A pure function of the- code, so two producers compute the same values. Cross-cell errors- need the whole set of cells and are reported as soon as the- document has them, in the same unit as the change that caused- them, without moving the etag of a cell whose code did not change.+ code, so two producers compute the same values.required: [defs, refs, errors]properties:defs:@@ -1311,10 +1331,10 @@ components:type: objectdescription: |A unit of code and configuration in the document. A cell event- fires when its code, name, config, or analysis changes. Only the- first three move its etag. Markdown and SQL cells are code that- calls `mo.md` or `mo.sql`; a client chooses the editor to show.- required: [id, notebook_id, code, name, config, etag, code_hash, analysis]+ fires when its code, name, or config changes. Markdown and SQL+ cells are code that calls `mo.md` or `mo.sql`; a client chooses+ the editor to show.+ required: [id, notebook_id, code, name, config, etag, code_hash]properties:id: { $ref: '#/components/schemas/CellId' }notebook_id: { $ref: '#/components/schemas/NotebookId' }@@ -1331,9 +1351,6 @@ components:code_hash:$ref: '#/components/schemas/Etag'description: Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code.- analysis:- oneOf: [{ $ref: '#/components/schemas/Analysis' }, { type: 'null' }]- description: Derived from the code by the host. Null when the host has no analyzer.Document:type: objectdescription: |@@ -1469,6 +1486,14 @@ components:request_id: *request_idtime: *timedocument: { $ref: '#/components/schemas/Document' }+ AnalysisMessage:+ type: object+ description: The data of an `analysis` event. The analysis as it now is.+ required: [analysis]+ properties:+ request_id: *request_id+ time: *time+ analysis: { $ref: '#/components/schemas/Analysis' }CellMessage:type: objectdescription: The data of a `cell` event. The cell as it now is.diff --git a/protocols/host/spec.md b/protocols/host/spec.mdindex 18bdcfea67..3b8e76a728 100644--- a/protocols/host/spec.md+++ b/protocols/host/spec.md@@ -76,13 +76,14 @@ across renames and moves.### Documents and cellsThe **document** is the notebook's editable source, organized into **cells**.-Each cell holds code and the information used to present and execute it. Cells-also MAY carry static analysis so clients can understand their role in the+Each cell holds code and the information used to present and execute it. A host+MAY also publish an **analysis** of the document: each cell's definitions,+references, and problems, so clients can understand a cell's role in thecomputation and identify problems before execution.Because cells share a dependency graph, editing one can affect the analysis of-others. Hosts MUST publish those changes together with the edit, giving clients-a consistent view of the document.+others. An analysis therefore covers the whole document and names the revision+it describes. Hosts publish it after that revision of the document.### Runtimes and attachmentsdiff --git a/tests/_core/conftest.py b/tests/_core/conftest.pyindex 5b2b42821a..c191aa0952 100644--- a/tests/_core/conftest.py+++ b/tests/_core/conftest.py@@ -3,10 +3,12 @@from __future__ import annotations+import asyncio+import pytestfrom marimo._core import backend as be, protocol-from marimo._core.document import Document, code_hash+from marimo._core.document import Document, DocumentSnapshot, code_hashfrom marimo._core.executions import CellExecution, Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook@@ -38,6 +40,37 @@ class ScriptedBackend:self.calls.append(("forget", run_id))+class ScriptedAnalyzer:+ """Expose snapshots and let tests complete analysis explicitly."""++ def __init__(self) -> None:+ self.requests: list[DocumentSnapshot] = []+ self.pending: asyncio.Queue[+ tuple[+ DocumentSnapshot,+ asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],+ ]+ ] = asyncio.Queue()++ async def analyze(+ self, snapshot: DocumentSnapshot+ ) -> dict[protocol.CellId, protocol.CellAnalysis]:+ result: asyncio.Future[+ dict[protocol.CellId, protocol.CellAnalysis]+ ] = asyncio.get_running_loop().create_future()+ self.requests.append(snapshot)+ self.pending.put_nowait((snapshot, result))+ return await result++ async def next_request(+ self,+ ) -> tuple[+ DocumentSnapshot,+ asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],+ ]:+ return await asyncio.wait_for(self.pending.get(), timeout=5)++def runtime_id_of(notebook: Notebook) -> protocol.RuntimeId:"""The current runtime's ID, for reports about it."""assert notebook.runtime is not None@@ -74,12 +107,14 @@ def make_notebook(backend: ScriptedBackend | None = None,*,document: Document | None = None,+ analyzer: ScriptedAnalyzer | None = None,) -> Notebook:return Notebook(document or Document(record.id, [], {}),Executions(),backend or ScriptedBackend(),sink,+ analyzer=analyzer,)@@ -89,11 +124,12 @@ async def add_notebook(backend: ScriptedBackend,*,document: Document | None = None,+ analyzer: ScriptedAnalyzer | None = None,) -> Notebook:host.add_notebook(record,lambda current, sink: make_notebook(- current, sink, backend, document=document+ current, sink, backend, document=document, analyzer=analyzer),)return await host.notebook(record.id)diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.pyindex 2465b7cbf2..4a826e8e1d 100644--- a/tests/_core/test_notebook.py+++ b/tests/_core/test_notebook.py@@ -19,7 +19,6 @@ from marimo._core.executions import CellExecution, Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.protocol import (- Analysis,AttachmentMessage,CellId,Console,@@ -1200,7 +1199,7 @@ async def test_current_cell_results_can_seed_another_notebook() -> None:@pytest.mark.parametrize("saved", [False, True])-def test_restoration_preserves_revisions_outputs_and_analysis(+def test_restoration_preserves_revisions_and_outputs(saved: bool,) -> None:document = Document(@@ -1209,9 +1208,6 @@ def test_restoration_preserves_revisions_outputs_and_analysis({"width": "full"},policy="lazy",saved=saved,- analyzer=lambda codes: {- cell_id: Analysis(defs=(), refs=(), errors=()) for cell_id in codes- },)# The output belongs to the previous source, and the saved revision can# precede the current one. Neither is rewritten during restoration.diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.pyindex cbed46aa17..56a283d097 100644--- a/tests/_core/test_notebook_document.py+++ b/tests/_core/test_notebook_document.py@@ -3,9 +3,10 @@from __future__ import annotations-from typing import TYPE_CHECKING+import asyncioimport pytest+from msgspec import UNSETfrom msgspec.structs import replacefrom marimo._core import protocol@@ -19,13 +20,20 @@ from marimo._core.document import (order_etag,revision,)+from marimo._core.executions import Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.stream import Event-from tests._core.conftest import make_notebook, names, project, record--if TYPE_CHECKING:- from collections.abc import Mapping+from tests._core.conftest import (+ ScriptedAnalyzer,+ ScriptedBackend,+ add_notebook,+ make_notebook,+ names,+ project,+ record,+ request_ids,+)NOTEBOOK = protocol.NotebookId("n1")HIDDEN = protocol.CellConfig(@@ -42,33 +50,6 @@ def fixture_cells() -> list[CellSource]:]-def defs_only(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:- """An analyzer that reports an error on every cell defining `x`."""- out = {}- definers = [cell_id for cell_id, code in codes.items() if "x =" in code]- for cell_id, code in codes.items():- errors = []- if cell_id in definers and len(definers) > 1:- errors.append(- protocol.Error(- kind="multiple-definitions",- message="x is defined twice",- source="marimo",- severity="error",- range=None,- name=None,- traceback=None,- related=[],- )- )- out[cell_id] = protocol.Analysis(- defs=[code.split(" =")[0]] if " =" in code else [],- refs=[],- errors=errors,- )- return out--class TestEtags:def test_reordering_cell_ids_with_newlines_changes_the_revision(self,@@ -204,54 +185,16 @@ class TestReplace:assert behind.saved_etag == saved.etag != behind.etag-class TestAnalysis:- def test_reruns_over_the_whole_document(self) -> None:- document = Document(- NOTEBOOK,- [CellSource("a", "x = 1"), CellSource("b", "y = 2")],- {},- analyzer=defs_only,- )- a, _ = document- assert a.analysis == protocol.Analysis(defs=["x"], refs=[], errors=[])-- changed = document.replace(- [CellSource("a", "x = 1"), CellSource("b", "x = 2")], {}- )-- # Both cells re-emit: b because its code changed, a because its- # analysis gained an error while its etag stayed put.- assert [cell.id for cell in changed.cells] == ["a", "b"]- new_a = changed.cells[0]- assert new_a.etag == a.etag- assert new_a.analysis is not None- assert [e.kind for e in new_a.analysis.errors] == [- "multiple-definitions"- ]-- def test_is_null_without_an_analyzer(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})- assert all(cell.analysis is None for cell in document)--class TestFromRecords:- def test_preserves_imported_analysis_and_saved_revision(self) -> None:+ def test_preserves_the_saved_revision(self) -> None:source = Document(- NOTEBOOK,- fixture_cells(),- {"width": "full"},- policy="lazy",- analyzer=lambda codes: {- cell_id: protocol.Analysis(defs=(), refs=(), errors=())- for cell_id in codes- },+ NOTEBOOK, fixture_cells(), {"width": "full"}, policy="lazy")# The saved revision precedes the current one; both survive.source.replace([CellSource("c1", "import marimo")], {"width": "full"})restored = Document.from_records(source._record, list(source))assert restored._record == source._recordassert list(restored) == list(source)- assert next(iter(restored)).analysis is not None@pytest.mark.parametrize("invalid", ["order", "notebook-id", "cell-etag", "document-etag"]@@ -272,26 +215,6 @@ class TestFromRecords:with pytest.raises(ValueError):Document.from_records(document, cells)- def test_analyzer_is_injected_for_restoration_and_later_edits(- self,- ) -> None:- observed: list[dict[str, str]] = []-- def analyze(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:- observed.append(dict(codes))- return {- cell_id: protocol.Analysis(defs=(), refs=(), errors=())- for cell_id in codes- }-- source = Document(NOTEBOOK, [CellSource("c1", "42")], {})- document = Document.from_records(- source._record, list(source), analyzer=analyze- )- document.replace([CellSource("c1", "43")], {})- assert observed == [{"c1": "42"}, {"c1": "43"}]- assert next(iter(document)).analysis is not None-class TestNotebook:async def test_initialization_publishes_cells_then_the_document(@@ -346,3 +269,208 @@ class TestNotebook:assert names(log) == ["cell", "cell.removed", "document"]assert all(e.data.request_id == "edit-1" for e in log) # type: ignore[union-attr]assert log[1].data.id == "k7f2" # type: ignore[union-attr]+++def cell_analyses(+ document: Document,+) -> dict[protocol.CellId, protocol.CellAnalysis]:+ """A placeholder analysis of every cell in the document."""+ return {+ cell.id: protocol.CellAnalysis(defs=(), refs=(), errors=())+ for cell in document+ }+++class TestAnalysis:+ async def test_the_initial_revision_is_analyzed_and_published_after_the_document(+ self, host: Host, log: list[Event]+ ) -> None:+ host.update_project(project())+ analyzer = ScriptedAnalyzer()+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})+ notebook = await add_notebook(+ host,+ record(),+ ScriptedBackend(),+ document=document,+ analyzer=analyzer,+ )+ snapshot, result = await analyzer.next_request()+ assert snapshot == document.snapshot()+ assert notebook.analysis is None++ log.clear()+ result.set_result(cell_analyses(document))+ await asyncio.sleep(0)++ assert names(log) == ["analysis"]+ assert request_ids(log) == [UNSET]+ assert notebook.analysis == protocol.Analysis(+ notebook_id=NOTEBOOK,+ document_etag=snapshot.document.etag,+ cells=cell_analyses(document),+ )+ assert names(host.events(notebook_id="n1")) == [+ "notebook",+ "cell",+ "cell",+ "cell",+ "document",+ "analysis",+ "ready",+ ]++ async def test_edits_during_analysis_are_analyzed_once_afterwards(+ self, host: Host, log: list[Event]+ ) -> None:+ host.update_project(project())+ analyzer = ScriptedAnalyzer()+ document = Document(NOTEBOOK, fixture_cells(), {})+ notebook = await add_notebook(+ host,+ record(),+ ScriptedBackend(),+ document=document,+ analyzer=analyzer,+ )+ first, result = await analyzer.next_request()+ first_analysis = cell_analyses(document)+ notebook.replace([CellSource("c1", "1")], {}, request_id="edit-1")+ notebook.replace(+ [CellSource("c1", "2", name="named", config=HIDDEN)],+ {"width": "full"},+ request_id="edit-2",+ )+ assert len(analyzer.requests) == 1+ assert first.document.etag != document._record.etag+ assert first.cells[0].code == "import marimo as mo"++ log.clear()+ result.set_result(first_analysis)+ latest, result = await analyzer.next_request()+ assert names(log) == []+ assert latest == document.snapshot()++ result.set_result(cell_analyses(document))+ await asyncio.sleep(0)+ assert names(log) == ["analysis"]+ assert request_ids(log) == ["edit-2"]+ assert notebook.analysis is not None+ assert notebook.analysis.document_etag == latest.document.etag++ async def test_the_previous_analysis_stays_until_the_next_arrives(+ self, host: Host+ ) -> None:+ host.update_project(project())+ analyzer = ScriptedAnalyzer()+ document = Document(NOTEBOOK, fixture_cells(), {})+ notebook = await add_notebook(+ host,+ record(),+ ScriptedBackend(),+ document=document,+ analyzer=analyzer,+ )+ first, result = await analyzer.next_request()+ result.set_result(cell_analyses(document))+ await asyncio.sleep(0)+ notebook.replace([CellSource("c1", "1")], {})+ _, result = await analyzer.next_request()++ assert notebook.analysis is not None+ assert (+ notebook.analysis.document_etag+ == first.document.etag+ != document._record.etag+ )+ assert names(host.events(notebook_id="n1")) == [+ "notebook",+ "cell",+ "document",+ "analysis",+ "ready",+ ]+ result.set_result(cell_analyses(document))+ await asyncio.sleep(0)++ @pytest.mark.parametrize("edit_while_running", [False, True])+ async def test_a_failed_analysis_leaves_the_notebook_ready_for_the_next(+ self, host: Host, log: list[Event], edit_while_running: bool+ ) -> None:+ host.update_project(project())+ analyzer = ScriptedAnalyzer()+ document = Document(NOTEBOOK, fixture_cells(), {})+ notebook = await add_notebook(+ host,+ record(),+ ScriptedBackend(),+ document=document,+ analyzer=analyzer,+ )+ _, result = await analyzer.next_request()+ if edit_while_running:+ notebook.replace([CellSource("c1", "1")], {})+ log.clear()+ result.set_exception(RuntimeError("compiler failed"))+ await asyncio.sleep(0)+ assert names(log) == []+ assert notebook.analysis is None+ if not edit_while_running:+ notebook.replace([CellSource("c1", "1")], {})+ snapshot, result = await analyzer.next_request()+ assert snapshot == document.snapshot()+ log.clear()+ result.set_result(cell_analyses(document))+ await asyncio.sleep(0)+ assert names(log) == ["analysis"]++ async def test_removal_discards_a_result_even_if_cancellation_is_suppressed(+ self, host: Host, log: list[Event]+ ) -> None:+ started, cancelled = asyncio.Event(), asyncio.Event()+ result = asyncio.get_running_loop().create_future()+ document = Document(NOTEBOOK, fixture_cells(), {})++ class Analyzer:+ async def analyze(self, _snapshot):+ started.set()+ try:+ return await asyncio.shield(result)+ except asyncio.CancelledError:+ cancelled.set()+ return await result++ host.update_project(project())+ host.add_notebook(+ record(),+ lambda _, sink: Notebook(+ document,+ Executions(),+ ScriptedBackend(),+ sink,+ analyzer=Analyzer(),+ ),+ )+ await host.notebook("n1")+ await asyncio.wait_for(started.wait(), timeout=5)+ host.remove_notebook("n1")+ await asyncio.wait_for(cancelled.wait(), timeout=5)+ log.clear()+ result.set_result(cell_analyses(document))+ await asyncio.sleep(0)+ assert names(log) == []+ assert "n1" not in host.notebooks+++def test_snapshot_preserves_order_metadata_and_nested_configuration() -> None:+ document = Document(NOTEBOOK, fixture_cells(), {"nested": {"items": [1]}})+ snapshot = document.snapshot()+ assert snapshot.cells == tuple(document)+ assert snapshot.document == document._record+ document._record.app_config["nested"]["items"].append(2)+ document.replace([CellSource("c1", "42", name="renamed")], {})+ assert snapshot.document.app_config == {"nested": {"items": [1]}}+ assert snapshot.cells[0].code == "import marimo as mo"+ assert snapshot.cells[-1].config == HIDDEN+ snapshot.document.app_config["another"] = True+ assert document._record.app_config == {}diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.pyindex 0df46b035f..4c625c83ec 100644--- a/tests/_core/test_protocol.py+++ b/tests/_core/test_protocol.py@@ -20,6 +20,7 @@ FIXTURES = (MODELS = {"record.json": protocol.HostRecord,"cell.json": protocol.Cell,+ "analysis.json": protocol.Analysis,"diagnostic.json": protocol.Error,"edit.json": protocol.EditRequest,"edit-conflict-request.json": protocol.EditRequest,diff --git a/tests/_server/host/test_host_analysis.py b/tests/_server/host/test_host_analysis.pyindex a6733fa25e..3651ccdee9 100644--- a/tests/_server/host/test_host_analysis.py+++ b/tests/_server/host/test_host_analysis.py@@ -3,10 +3,32 @@from __future__ import annotations+import asyncio+import threading+from unittest.mock import Mock+import pytest+from marimo._ast.cell import CellImpl+from marimo._ast.compiler import compile_cellfrom marimo._core import protocol-from marimo._server.host.analysis import Analyzer, analyze+from marimo._core.document import CellSource, Document, DocumentSnapshot+from marimo._server.host.analysis import CellAnalyzer, HostAnalyzer+from marimo._types.ids import CellId_t+++def snapshot(codes: dict[str, str]) -> DocumentSnapshot:+ return Document(+ protocol.NotebookId("n1"),+ [CellSource(cid, code) for cid, code in codes.items()],+ {},+ ).snapshot()+++def analyze(+ codes: dict[str, str],+) -> dict[protocol.CellId, protocol.CellAnalysis]:+ return CellAnalyzer()(snapshot(codes))def test_refs_are_names_other_cells_define() -> None:@@ -19,7 +41,9 @@ def test_refs_are_names_other_cells_define() -> None:)assert analyses["a"].defs == ("mo",)assert analyses["a"].refs == ("x",)- assert analyses["b"] == protocol.Analysis(defs=("x",), refs=(), errors=())+ assert analyses["b"] == protocol.CellAnalysis(+ defs=("x",), refs=(), errors=()+ )assert analyses["c"].refs == ("x",)@@ -55,7 +79,7 @@ def test_positions_count_utf16_code_units() -> None:def test_an_analyzer_kept_between_edits_matches_a_fresh_one() -> None:- analyzer = Analyzer()+ analyzer = CellAnalyzer()steps = [{"a": "x = 1", "b": "y = x"},{"a": "x = 1", "b": "y = x", "c": "x = 2"},@@ -65,14 +89,14 @@ def test_an_analyzer_kept_between_edits_matches_a_fresh_one() -> None:{"b": "def (:", "c": "z = y"},]for codes in steps:- assert analyzer(codes) == analyze(codes), codes+ assert analyzer(snapshot(codes)) == analyze(codes), codesdef test_analyzer_retries_after_an_unexpected_compiler_failure(monkeypatch: pytest.MonkeyPatch,) -> None:- analyzer = Analyzer()- analyzer({"a": "x = 1"})+ analyzer = CellAnalyzer()+ analyzer(snapshot({"a": "x = 1"}))codes = {"a": "y = 2", "b": "z = y"}def fail(*_args: object, **_kwargs: object) -> None:@@ -81,6 +105,119 @@ def test_analyzer_retries_after_an_unexpected_compiler_failure(with monkeypatch.context() as patch:patch.setattr("marimo._server.host.analysis.compile_cell", fail)with pytest.raises(RuntimeError, match="compiler failed"):- analyzer(codes)+ analyzer(snapshot(codes))++ assert analyzer(snapshot(codes)) == analyze(codes)+++async def test_host_analyzer_reports_each_revision_off_the_loop(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ loop = asyncio.get_running_loop()+ started = asyncio.Event()+ release = threading.Event()+ codes = {"a": "x = 1", "b": "y = x"}+ expected = analyze(codes)++ def blocked_compile(code: str, cell_id: CellId_t) -> CellImpl:+ loop.call_soon_threadsafe(started.set)+ if not release.wait(timeout=5):+ raise TimeoutError("the event loop did not release compilation")+ return compile_cell(code, cell_id)++ monkeypatch.setattr(+ "marimo._server.host.analysis.compile_cell", blocked_compile+ )+ analyzer = HostAnalyzer()+ reported = asyncio.create_task(analyzer.analyze(snapshot(codes)))+ try:+ await asyncio.wait_for(started.wait(), timeout=5)+ # The loop must resume while compilation is still blocked.+ assert not reported.done()+ finally:+ release.set()+ result = await asyncio.wait_for(reported, timeout=5)- assert analyzer(codes) == analyze(codes)+ assert result == expected+++async def test_host_analyzer_raises_unexpected_failures(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ analyzer = HostAnalyzer()++ def fail(*_: object, **__: object) -> None:+ raise RuntimeError("boom")++ monkeypatch.setattr("marimo._server.host.analysis.compile_cell", fail)+ with pytest.raises(RuntimeError, match="boom"):+ await analyzer.analyze(snapshot({"a": "x = 1"}))+++def test_compilation_cache_uses_identity_and_code_hash(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ compiler = Mock(wraps=compile_cell)+ monkeypatch.setattr("marimo._server.host.analysis.compile_cell", compiler)+ analyzer = CellAnalyzer()+ document = Document(+ protocol.NotebookId("n1"),+ [+ CellSource("a", "x = 1"),+ CellSource("b", "y = x"),+ CellSource("bad", "def (:"),+ ],+ {},+ )+ analyzer(document.snapshot())+ assert compiler.call_count == 3++ # Names, configuration, and order are visible without recompiling code.+ document.replace(+ [+ CellSource("b", "y = x", name="renamed"),+ CellSource("a", "x = 1"),+ CellSource("bad", "def (:"),+ ],+ {"width": "full"},+ )+ analyzer(document.snapshot())+ assert compiler.call_count == 3++ # An unchanged cell loses its reference when its provider changes.+ document.replace([CellSource("a", "z = 1"), CellSource("b", "y = x")], {})+ assert analyzer(document.snapshot())[protocol.CellId("b")].refs == ()+ assert compiler.call_count == 4++ document.replace([CellSource("b", "y = x")], {})+ analyzer(document.snapshot())+ document.replace([CellSource("a", "z = 1"), CellSource("c", "y = x")], {})+ analyzer(document.snapshot())+ assert compiler.call_count == 6++[email protected]("reverse", [False, True])+ ("provider", "consumer", "refs"),+ [+ ('mo.sql("CREATE TABLE t (id INT)")', "print(t)", ()),+ (+ 'mo.sql("CREATE TABLE s.t (id INT)")',+ 'mo.sql("SELECT * FROM s.t")',+ ("s.t",),+ ),+ (+ 'mo.sql("CREATE TABLE s.t (id INT)")',+ 'mo.sql("SELECT * FROM other.t")',+ (),+ ),+ ("t = 1", 'mo.sql("SELECT * FROM t")', ("t",)),+ ],+)+def test_references_follow_runtime_language_semantics(+ provider, consumer, refs, reverse+):+ cells = [("provider", provider), ("consumer", consumer)]+ if reverse:+ cells.reverse()+ assert analyze(dict(cells))[protocol.CellId("consumer")].refs == refsdiff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 4b64c2b822..bdb6768ca7 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -16,6 +16,7 @@ from starlette.routing import Routefrom marimo._core import backend as be, protocolfrom marimo._core.host import Host+from marimo._core.notebook import Notebookfrom marimo._core.protocol import ProjectMessagefrom marimo._core.run_log import RetentionPolicyfrom marimo._server.host import api as api_module@@ -45,6 +46,16 @@ TOKEN = "record-token"AUTH = {"Authorization": f"Bearer {TOKEN}"}+async def analyzed(notebook: Notebook) -> protocol.Analysis:+ """Wait for the notebook's analysis, which runs off the event loop."""+ deadline = asyncio.get_running_loop().time() + 5+ while notebook.analysis is None:+ if asyncio.get_running_loop().time() > deadline:+ raise TimeoutError("the notebook was not analyzed")+ await asyncio.sleep(0.01)+ return notebook.analysis++def key(value: str) -> dict[str, str]:return {**AUTH, "Idempotency-Key": value}@@ -469,6 +480,7 @@ async def test_types_and_cursors_apply_to_the_stream(harness: Harness) -> None:async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:notebook = await harness.host.notebook(harness.notebook_id)+ await analyzed(notebook)response, task, disconnect = request(harness.app, "GET", f"/notebooks/{notebook.id}/events", headers=AUTH)@@ -478,13 +490,14 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:"notebook","cell","document",+ "analysis","attachment","ready",]assert response.records[2]["data"]["document"]["order"] == [response.records[1]["data"]["cell"]["id"]]- assert response.records[3]["data"]["attachment"]["kind"] == "client"+ assert response.records[4]["data"]["attachment"]["kind"] == "client"disconnect()await asyncio.wait_for(task, 5)@@ -492,6 +505,7 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:"notebook","cell","document",+ "analysis","ready",]@@ -1437,9 +1451,10 @@ async def test_the_notebook_stream_carries_cells_then_the_document(f"/notebooks/{harness.notebook_id}/events",headers=AUTH,)- await wait_for(response, until_ready)+ await wait_for(response, lambda r: "analysis" in r.names())disconnect()+ # The document is served as soon as it is read; its analysis follows.assert response.names() == ["notebook","cell",@@ -1447,14 +1462,14 @@ async def test_the_notebook_stream_carries_cells_then_the_document("document","attachment","ready",+ "analysis",]first, second = (r["data"]["cell"] for r in response.records[1:3])document = response.records[3]["data"]["document"]+ analysis = response.records[6]["data"]["analysis"]assert first["code"] == "x = 21"- assert first["analysis"] == {"defs": ["x"], "refs": [], "errors": []}assert second["code"] == "y = x * 2"assert second["config"]["hide_code"] is True- assert second["analysis"]["refs"] == ["x"]assert document["order"] == [first["id"], second["id"]]assert document["app_config"] == {"width": "full"}assert document["policy"] == "autorun"@@ -1462,6 +1477,12 @@ async def test_the_notebook_stream_carries_cells_then_the_document(assert all(c["notebook_id"] == harness.notebook_id for c in (first, second))+ assert analysis["notebook_id"] == harness.notebook_id+ assert analysis["document_etag"] == document["etag"]+ assert analysis["cells"] == {+ first["id"]: {"defs": ["x"], "refs": [], "errors": []},+ second["id"]: {"defs": ["y"], "refs": ["x"], "errors": []},+ }# A filtered stream is a snapshot of the document alone, and a second# connection reuses the loaded document.