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
Make the document a value and the notebook its owner (#11293)
Trevor Manzcc4d597a5568
diff --git a/marimo/_core/analysis.py b/marimo/_core/analysis.pyindex 0a6d2b05bc..cd3da838b0 100644--- a/marimo/_core/analysis.py+++ b/marimo/_core/analysis.py@@ -10,7 +10,7 @@ from marimo._core import protocolif TYPE_CHECKING:from collections.abc import Mapping- from marimo._core.document import DocumentSnapshot+ from marimo._core.document import Documentclass Analyzer(Protocol):@@ -18,7 +18,7 @@ class Analyzer(Protocol):One instance belongs to one notebook. Calls are serialized, allowingimplementations to cache compilation by cell ID and code hash.- Results cover every cell in the snapshot, including syntax errors.+ Results cover every cell in the document, including syntax errors.Unexpected failures raise; they are not document diagnostics.Implementations must keep the event loop responsive. After cancelling@@ -26,6 +26,6 @@ class Analyzer(Protocol):"""async def analyze(- self, snapshot: DocumentSnapshot+ self, document: Document) -> Mapping[protocol.CellId, protocol.CellAnalysis]:- """Analyze a detached snapshot without modifying it."""+ """Analyze one revision of the document."""diff --git a/marimo/_core/backend.py b/marimo/_core/backend.pyindex 1b90e43c2a..7b1c28b7cd 100644--- a/marimo/_core/backend.py+++ b/marimo/_core/backend.py@@ -2,7 +2,7 @@"""Kernel commands and updates for the host API.```python-notebook = Notebook(document, Executions(), backend, sink)+notebook = Notebook(notebook_id, document, Executions(), backend, sink)runtime, _ = notebook.start() # Calls backend.start(runtime.id).# The backend reports on that runtime through Notebook.observe.diff --git a/marimo/_core/document.py b/marimo/_core/document.pyindex ffe97693ed..7602c5319a 100644--- a/marimo/_core/document.py+++ b/marimo/_core/document.py@@ -1,5 +1,10 @@# Copyright 2026 Marimo. All rights reserved.-"""Notebook cells, order, configuration, and revisions."""+"""Notebook cells, order, configuration, and revisions.++A document is the notebook's content at one revision. It does not+change. Editing it returns the next document. The notebook holds the+current one.+"""from __future__ import annotations@@ -12,10 +17,10 @@ from typing import TYPE_CHECKING, Anyfrom msgspec import UNSETfrom marimo._core import protocol-from marimo._core.errors import EditConflict, Invalid+from marimo._core.errors import Invalidif TYPE_CHECKING:- from collections.abc import Iterator, Mapping, Sequence+ from collections.abc import Iterable, Iterator, Mapping, Sequencedef etag(text: str) -> protocol.Etag:@@ -76,54 +81,45 @@ def default_config() -> protocol.CellConfig:@dataclass(frozen=True)-class CellSource:- """Cell source and metadata supplied by a file or editor."""+class DocumentCell:+ """A cell and the hashes of its content.++ Line endings are normalized to newlines and the hashes computed when+ the cell is built, so they always match the content.+ """- id: str+ id: protocol.CellIdcode: strname: str = "_"config: protocol.CellConfig = field(default_factory=default_config)+ etag: protocol.Etag = field(init=False)+ """Identifies code, name, and config together."""+ code_hash: protocol.Etag = field(init=False)+ """Identifies the code alone."""--def revision(- cells: Sequence[CellSource], app_config: Mapping[str, Any]-) -> protocol.Etag:- """The document etag these sources produce."""- return document_etag(- order_etag([source.id for source in cells]),- app_config_etag(app_config),- [- cell_etag(- code_hash(normalize_code(source.code)),- source.name,- source.config,- )- for source in cells- ],- )---@dataclass(frozen=True)-class DocumentSnapshot:- """A detached document record and its cells in document order."""-- document: protocol.Document- cells: tuple[protocol.Cell, ...]+ def __post_init__(self) -> None:+ code = normalize_code(self.code)+ hashed = code_hash(code)+ object.__setattr__(self, "code", code)+ object.__setattr__(self, "code_hash", hashed)+ object.__setattr__(+ self, "etag", cell_etag(hashed, self.name, self.config)+ )@dataclass(frozen=True)class Changed:- """Changed cells, removed cell IDs, and the updated document."""+ """Changed cells, removed cell IDs, and the new revision."""- cells: list[protocol.Cell]+ cells: list[DocumentCell]"""New cells, and cells whose etag changed."""- removed: list[str]+ removed: list[protocol.CellId]"""Ids of cells that no longer exist."""- document: protocol.Document | None- """The document, when any of its fields changed."""+ etag: protocol.Etag | None+ """The document's etag, when it changed."""def __bool__(self) -> bool:- return bool(self.cells or self.removed or self.document)+ return bool(self.cells or self.removed or self.etag)@dataclass(frozen=True)@@ -131,47 +127,63 @@ class Applied:"""An edit's effects and the etags of the cells it touched."""changed: Changed- cells: dict[str, protocol.CellEtags | None]+ cells: dict[protocol.CellId, protocol.CellEtags | None]"""By id, for each cell the edit put, and `None` for each it deleted."""+@dataclass(frozen=True)+class Stale:+ """An edit named a state the document no longer has. Nothing applied."""++ change: int+ """The index of the first stale change."""+ cell_id: protocol.CellId | None+ """The cell that change named, if it named one."""++class Document:- """A notebook document with content-derived revisions.+ """The notebook's content at one revision.- Cell source uses newline line endings. Edits change cells and their- order. The app config comes from the store or the editor.+ Documents with the same etag are equal. Cell IDs must be unique."""+ __slots__ = (+ "_app_config",+ "_app_config_etag",+ "_cells",+ "_etag",+ "_order_etag",+ )+def __init__(- self,- notebook_id: protocol.NotebookId,- cells: Sequence[CellSource],- app_config: Mapping[str, Any],- *,- saved: bool = True,+ self, cells: Iterable[DocumentCell], app_config: Mapping[str, Any]) -> None:- self._id = notebook_id- self._cells: dict[str, protocol.Cell] = {}- self._order: list[str] = []- self._app_config: dict[str, Any] = {}- self._saved_etag: protocol.Etag | None = None- self._document: protocol.Document | None = None- self.replace(cells, app_config)- if saved:- self.mark_saved()+ held: dict[protocol.CellId, DocumentCell] = {}+ for cell in cells:+ if cell.id in held:+ raise ValueError("cell ids must be unique within the notebook")+ held[cell.id] = cell+ plain = deepcopy(dict(app_config))+ self._cells = held+ self._app_config: Mapping[str, Any] = plain+ self._order_etag = order_etag(list(held))+ self._app_config_etag = app_config_etag(plain)+ self._etag = document_etag(+ self._order_etag,+ self._app_config_etag,+ [cell.etag for cell in held.values()],+ )@classmethod- def from_records(+ def restore(cls,document: protocol.Document,cells: Sequence[protocol.Cell],) -> Document:- """Restore a document from its protocol records.+ """Rebuild a document from the records the notebook published.- Cell identities, order, and revisions must agree. The saved- revision is preserved.+ Cell identities, order, and revisions must agree."""- document, cells = deepcopy((document, cells))by_id = {cell.id: cell for cell in cells}if len(by_id) != len(cells) or (len(set(document.order)) != len(document.order)@@ -183,13 +195,11 @@ class Document:if any(cell.notebook_id != document.notebook_id for cell in cells):raise ValueError("cells must belong to the document")restored = cls(- document.notebook_id,[- CellSource(cell.id, cell.code, cell.name, cell.config)+ DocumentCell(cell.id, cell.code, cell.name, cell.config)for cell in (by_id[cell_id] for cell_id in document.order)],document.app_config,- saved=False,)for cell in restored:original = by_id[cell.id]@@ -198,126 +208,116 @@ class Document:or cell.code_hash != original.code_hash):raise ValueError("cell revisions must match their content")- current = restored._recordif (- current.etag != document.etag- or current.order_etag != document.order_etag- or current.app_config_etag != document.app_config_etag+ restored.etag != document.etag+ or restored.order_etag != document.order_etag+ or restored.app_config_etag != document.app_config_etag):raise ValueError("document revisions must match its content")- if document.saved_etag is not None:- restored.mark_saved(document.saved_etag)return restored+ # ---- reading --------------------------------------------------------++ def __iter__(self) -> Iterator[DocumentCell]:+ """Iterate over cells in document order."""+ return iter(self._cells.values())++ def cell(self, cell_id: protocol.CellId) -> DocumentCell | None:+ return self._cells.get(cell_id)+@property- def notebook_id(self) -> protocol.NotebookId:- """The notebook this document belongs to."""- return self._id+ def etag(self) -> protocol.Etag:+ """Identifies cells, order, and app config together."""+ return self._etag@property- def _record(self) -> protocol.Document:- assert self._document is not None- return self._document+ def order_etag(self) -> protocol.Etag:+ return self._order_etag- def __iter__(self) -> Iterator[protocol.Cell]:- """Iterate over cells in document order."""- for cell_id in self._order:- yield self._cells[cell_id]+ @property+ def app_config_etag(self) -> protocol.Etag:+ return self._app_config_etag@property- def order(self) -> list[str]:- return list(self._order)+ def app_config(self) -> Mapping[str, Any]:+ """The app config. Treat this mapping and nested values as read-only."""+ return self._app_config- def cell(self, cell_id: str) -> protocol.Cell | None:- return self._cells.get(cell_id)+ def __eq__(self, other: object) -> bool:+ return isinstance(other, Document) and other._etag == self._etag- def snapshot(self) -> DocumentSnapshot:- """Capture one revision without sharing mutable configuration."""- return deepcopy(DocumentSnapshot(self._record, tuple(self)))+ def __hash__(self) -> int:+ return hash(self._etag)- def replace(- self, cells: Sequence[CellSource], app_config: Mapping[str, Any]- ) -> Changed:- """Replace cells and configuration and return what changed.+ def __repr__(self) -> str:+ return f"Document(etag={self._etag!r}, cells={len(self._cells)})"- Cell IDs must be unique.- """- order = [source.id for source in cells]- 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}+ # ---- producing the next revision ------------------------------------++ def replace(+ self, cells: Iterable[DocumentCell], app_config: Mapping[str, Any]+ ) -> tuple[Document, Changed]:+ """The document with these cells and config, and what changed."""+ document = Document(cells, app_config)changed = [- built[cell_id]- for cell_id in order- if self._cells.get(cell_id) != built[cell_id]+ cell for cell in document if self._cells.get(cell.id) != cell]- removed = [cell_id for cell_id in self._order if cell_id not in built]- self._cells = built- self._order = order- self._app_config = dict(app_config)- return Changed(changed, removed, self._refresh())+ removed = [+ cell_id+ for cell_id in self._cells+ if cell_id not in document._cells+ ]+ revised = None if document._etag == self._etag else document._etag+ return document, Changed(changed, removed, revised)- def apply(self, changes: Sequence[protocol.Change]) -> Applied:+ def apply(+ self, changes: Sequence[protocol.Change]+ ) -> tuple[Document, Applied] | Stale:"""Apply `changes` in order as one unit, or none of them.- Every precondition is compared with the document as it was when- the request arrived, so one request can create a cell and then- place it with the order etag the client read.+ Preconditions are checked against this document, so one request+ can create a cell and then place it with the order etag the+ client read. A stale precondition returns `Stale`.Raises:- EditConflict: If a precondition names a state the document no- longer has. Nothing is applied.Invalid: If a change could not apply to any state."""- staged: dict[str, CellSource] = {- cell.id: CellSource(cell.id, cell.code, cell.name, cell.config)- for cell in self- }- order = list(self._order)- touched: dict[str, bool] = {}- before = self._record-- def matches(base: str, cell_id: str) -> bool:+ staged: dict[protocol.CellId, DocumentCell] = dict(self._cells)+ order: list[protocol.CellId] = list(self._cells)+ touched: dict[protocol.CellId, bool] = {}++ def matches(base: str, cell_id: protocol.CellId) -> bool:if base == "*":return Truecurrent = self._cells.get(cell_id)return current is not None and base == current.etag- def stale(index: int, cell_id: str | None) -> EditConflict:- return EditConflict(- f"change {index} names a state the document no longer has",- change=index,- cell=None if cell_id is None else self._cells.get(cell_id),- document=before,- )-for index, change in enumerate(changes):if isinstance(change, protocol.PutCell):- source = _source(change.cell)- cell_id = source.id+ cell = _cell(change.cell)if change.base_etag is None:# A cell deleted earlier in the batch still existed# when the client read, so creating it is a conflict.- if cell_id in self._cells or cell_id in staged:- raise stale(index, cell_id)- order.insert(_slot(order, change, index), cell_id)- elif cell_id not in staged or not matches(- change.base_etag, cell_id+ if cell.id in self._cells or cell.id in staged:+ return Stale(index, cell.id)+ order.insert(_slot(order, change, index), cell.id)+ elif cell.id not in staged or not matches(+ change.base_etag, cell.id):- raise stale(index, cell_id)- staged[cell_id] = source- touched[cell_id] = True+ return Stale(index, cell.id)+ staged[cell.id] = cell+ touched[cell.id] = Trueelif isinstance(change, protocol.DeleteCell):if change.id not in staged or not matches(change.base_etag, change.id):- raise stale(index, change.id)+ return Stale(index, change.id)del staged[change.id]order.remove(change.id)touched[change.id] = Falseelif isinstance(change, protocol.SetOrder):- if change.base_etag not in ("*", before.order_etag):- raise stale(index, None)+ if change.base_etag not in ("*", self._order_etag):+ return Stale(index, None)if sorted(change.order) != sorted(order) or len(set(change.order)) != len(change.order):@@ -328,69 +328,28 @@ class Document:else:raise Invalid(f"change {index} has an unknown kind")- changed = self.replace(+ document, changed = self.replace([staged[cell_id] for cell_id in order], self._app_config)- cells: dict[str, protocol.CellEtags | None] = {}+ cells: dict[protocol.CellId, protocol.CellEtags | None] = {}for cell_id, put in touched.items():if put:- cell = self._cells[cell_id]+ cell = document._cells[cell_id]cells[cell_id] = protocol.CellEtags(etag=cell.etag, code_hash=cell.code_hash)else:cells[cell_id] = None- return Applied(changed, cells)-- def mark_saved(- self, etag: protocol.Etag | None = None- ) -> protocol.Document | None:- """Record the persisted revision, which may precede the current one."""- self._saved_etag = self._record.etag if etag is None else etag- return self._refresh()-- def _build(self, source: CellSource) -> protocol.Cell:- code = normalize_code(source.code)- hashed = code_hash(code)- return protocol.Cell(- id=protocol.CellId(source.id),- notebook_id=self._id,- code=code,- name=source.name,- config=source.config,- etag=cell_etag(hashed, source.name, source.config),- code_hash=hashed,- )-- def _refresh(self) -> protocol.Document | None:- """Recompute the document and return it when it changed."""- order = order_etag(self._order)- app_config = app_config_etag(self._app_config)- document = protocol.Document(- notebook_id=self._id,- order=tuple(protocol.CellId(c) for c in self._order),- app_config=dict(self._app_config),- etag=document_etag(- order,- app_config,- [self._cells[cell_id].etag for cell_id in self._order],- ),- saved_etag=self._saved_etag,- order_etag=order,- app_config_etag=app_config,- )- if document == self._document:- return None- self._document = document- return document+ return document, Applied(changed, cells)-def _source(cell: protocol.CellInput) -> CellSource:+def _cell(cell: protocol.CellInput) -> DocumentCell:+ """The cell a client's input describes, with unset fields defaulted."""name = "_" if cell.name is UNSET else cell.nameconfig = cell.configif config is UNSET:- return CellSource(cell.id, cell.code, name)- return CellSource(+ return DocumentCell(cell.id, cell.code, name)+ return DocumentCell(cell.id,cell.code,name,@@ -405,7 +364,9 @@ def _source(cell: protocol.CellInput) -> CellSource:)-def _slot(order: list[str], change: protocol.PutCell, index: int) -> int:+def _slot(+ order: list[protocol.CellId], change: protocol.PutCell, index: int+) -> int:"""Where a created cell goes: after or before an anchor, or at the end."""after = None if change.after is UNSET else change.afterbefore = None if change.before is UNSET else change.beforediff --git a/marimo/_core/executions.py b/marimo/_core/executions.pyindex 0ff3803048..8c28c5ac38 100644--- a/marimo/_core/executions.py+++ b/marimo/_core/executions.py@@ -16,6 +16,8 @@ from marimo._core.stream import utcnowif TYPE_CHECKING:from collections.abc import Iterable, Mapping+ from marimo._core.document import DocumentCell+@dataclass(frozen=True)class CellExecution:@@ -92,7 +94,7 @@ class Executions:cls,executions: Mapping[protocol.CellId, CellExecution],*,- cells: Iterable[protocol.Cell],+ cells: Iterable[DocumentCell],) -> Executions:"""Restore completed executions for cells in the document.diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.pyindex 8d40b85479..59b9cf633b 100644--- a/marimo/_core/notebook.py+++ b/marimo/_core/notebook.py@@ -5,14 +5,15 @@ from __future__ import annotationsimport asyncioimport logging+from copy import deepcopyfrom typing import TYPE_CHECKING, Anyimport msgspecfrom msgspec.structs import replacefrom marimo._core import backend as be, protocol-from marimo._core.document import Changed-from marimo._core.errors import Conflict, NoRuntime, NotFound+from marimo._core.document import Stale+from marimo._core.errors import Conflict, EditConflict, NoRuntime, NotFoundfrom marimo._core.executions import Executions, Released, Removedfrom marimo._core.ids import mintfrom marimo._core.stream import Event, Kind, kind_of, message, utcnow@@ -21,7 +22,11 @@ if TYPE_CHECKING:from collections.abc import Callable, Mapping, Sequencefrom marimo._core.analysis import Analyzer- from marimo._core.document import CellSource, Document, DocumentSnapshot+ from marimo._core.document import (+ Changed,+ Document,+ DocumentCell,+ )from marimo._core.executions import Changefrom marimo._core.stream import Body, Sink@@ -32,10 +37,11 @@ LOGGER = logging.getLogger(__name__)class Notebook:"""A document, its execution results, and the runtime that produces them.- The document and cell results remain when the runtime stops.- Commands call the backend and publish changes through the sink.- Change the document and executions through the notebook so each- change reaches the sink.+ The notebook gives the document its identity and its saved revision,+ and publishes the records clients read. The document+ and cell results remain when the runtime stops. Commands call the+ backend and publish changes through the sink. Change the document+ and executions through the notebook so each change reaches the sink.With an analyzer, the notebook requests analysis of each documentrevision and publishes the result when that revision is still@@ -44,14 +50,21 @@ class Notebook:def __init__(self,+ notebook_id: protocol.NotebookId,document: Document,executions: Executions,backend: be.Backend,sink: Sink,*,+ saved_etag: protocol.Etag | None = None,analyzer: Analyzer | None = None,) -> None:+ self._id = notebook_idself._document = document+ self._saved_etag = saved_etag+ # The document record as last published, so a change that leaves+ # it the same publishes nothing.+ self._published: protocol.Document | None = self._document_recordself._executions = executionsself.backend = backendself.sink = sink@@ -71,7 +84,7 @@ class Notebook:@propertydef document(self) -> Document:- """The document owned by this notebook; change it through the notebook."""+ """The current revision. The notebook's commands produce the next."""return self._document@property@@ -81,7 +94,41 @@ class Notebook:@propertydef id(self) -> protocol.NotebookId:- return self.document.notebook_id+ return self._id++ @property+ def saved_etag(self) -> protocol.Etag | None:+ """The document revision the store holds, if known."""+ return self._saved_etag++ def require_revision(self, etags: Sequence[str]) -> None:+ """Check that the document is at one of `etags`.++ Raises:+ EditConflict: If it is not, carrying the document as it is.+ """+ self._require_open()+ if self.document.etag not in etags:+ raise EditConflict(+ "The document has changed since it was read",+ change=0,+ cell=None,+ document=self._document_record,+ )++ @property+ def _document_record(self) -> protocol.Document:+ """The document as clients read it, built from its current state."""+ document = self._document+ return protocol.Document(+ notebook_id=self._id,+ order=tuple(cell.id for cell in document),+ app_config=deepcopy(dict(document.app_config)),+ etag=document.etag,+ saved_etag=self._saved_etag,+ order_etag=document.order_etag,+ app_config_etag=document.app_config_etag,+ )@propertydef runtime(self) -> protocol.Runtime | None:@@ -101,23 +148,34 @@ class Notebook:def replace(self,- cells: Sequence[CellSource],+ cells: Sequence[DocumentCell],app_config: Mapping[str, object],*,saved: bool = False,request_id: str | None = None,- ) -> Changed:+ ) -> protocol.EditResponse:"""Replace the document and publish its changes.With `saved`, the new contents are also the persisted revision.+ The response carries etags for the cells that changed, and+ `None` for each cell that was removed."""self._require_open()- document = self.document- changed = document.replace(cells, app_config)- if saved and (published := document.mark_saved()) is not None:- changed = Changed(changed.cells, changed.removed, published)+ self._document, changed = self._document.replace(cells, app_config)+ if saved:+ self._saved_etag = self._document.etagself._publish_changed(changed, request_id)- return changed+ etags: dict[str, protocol.CellEtags | None] = {+ cell.id: protocol.CellEtags(+ etag=cell.etag, code_hash=cell.code_hash+ )+ for cell in changed.cells+ }+ for cell_id in changed.removed:+ etags[cell_id] = None+ return protocol.EditResponse(+ document=self._document_record, cells=etags+ )def edit(self, changes: Sequence[protocol.Change], *, request_id: str@@ -129,10 +187,25 @@ class Notebook:Invalid: If a change could not apply to any state."""self._require_open()- applied = self.document.apply(changes)+ result = self._document.apply(changes)+ if isinstance(result, Stale):+ cell = (+ None+ if result.cell_id is None+ else self._document.cell(result.cell_id)+ )+ raise EditConflict(+ f"change {result.change} names a state the document no "+ "longer has",+ change=result.change,+ cell=None if cell is None else self._cell_record(cell),+ document=self._document_record,+ )+ self._document, applied = resultself._publish_changed(applied.changed, request_id)return protocol.EditResponse(- document=self.document._record, cells=applied.cells+ document=self._document_record,+ cells=dict(applied.cells.items()),)def mark_saved(@@ -144,10 +217,30 @@ class Notebook:changed while it was being written."""self._require_open()- published = self.document.mark_saved(etag)+ self._saved_etag = etag+ published = self._refresh()if published is not None:self._publish(published, request_id)- return self.document._record+ return self._document_record++ def _cell_record(self, cell: DocumentCell) -> protocol.Cell:+ return protocol.Cell(+ id=cell.id,+ notebook_id=self._id,+ code=cell.code,+ name=cell.name,+ config=cell.config,+ etag=cell.etag,+ code_hash=cell.code_hash,+ )++ def _refresh(self) -> protocol.Document | None:+ """Return the document record when it differs from the last published."""+ record = self._document_record+ if record == self._published:+ return None+ self._published = record+ return recorddef _publish_changed(self, changed: Changed, request_id: str | None@@ -155,15 +248,16 @@ class Notebook:"""Publish a document change, then analyze the new revision."""with self.sink.deferred():for cell in changed.cells:- self._publish(cell, request_id)+ self._publish(self._cell_record(cell), request_id)for cell_id in changed.removed:self._apply(self.executions.remove_cell(protocol.CellId(cell_id)))self._remove("cell", cell_id, request_id)- if changed.document is not None:- self._publish(changed.document, request_id)- if changed.document is not None:+ record = self._refresh()+ if record is not None:+ self._publish(record, request_id)+ if changed.etag is not None:self._request_analysis(request_id)# ---- analysis ------------------------------------------------------@@ -176,22 +270,22 @@ class Notebook:self._reanalyze, self._reanalyze_request = True, request_idreturnself._analysis_task = asyncio.create_task(- self._analyze(self.document.snapshot(), request_id)+ self._analyze(self._document, request_id))async def _analyze(- self, snapshot: DocumentSnapshot, request_id: str | None+ self, document: Document, request_id: str | None) -> None:assert self._analyzer is not Nonetry:while not self._closed:- etag = snapshot.document.etag+ etag = document.etagtry:- cells = await self._analyzer.analyze(snapshot)+ cells = await self._analyzer.analyze(document)except Exception:LOGGER.exception("Could not analyze document %s", etag)else:- if not self._closed and etag == self.document._record.etag:+ if not self._closed and etag == self._document.etag:self._analysis = protocol.Analysis(notebook_id=self.id,document_etag=etag,@@ -205,7 +299,7 @@ class Notebook:returnrequest_id = self._reanalyze_requestself._reanalyze, self._reanalyze_request = False, None- snapshot = self.document.snapshot()+ document = self._documentfinally:self._analysis_task = None@@ -469,7 +563,10 @@ class Notebook:def _snapshot(self) -> list[Event]:"""Return current state as events in dependency order."""- bodies: list[Body] = [*self.document, self.document._record]+ bodies: list[Body] = [+ *(self._cell_record(cell) for cell in self.document),+ self._document_record,+ ]if self._analysis is not None:bodies.append(self._analysis)if self._runtime is not None:diff --git a/marimo/_server/host/analysis.py b/marimo/_server/host/analysis.pyindex 40246711ce..e84520dc76 100644--- a/marimo/_server/host/analysis.py+++ b/marimo/_server/host/analysis.py@@ -18,21 +18,21 @@ from marimo._runtime.dataflow.edges import resolve_cell_referencesfrom marimo._types.ids import CellId_tif TYPE_CHECKING:- from marimo._core.document import DocumentSnapshot+ from marimo._core.document import DocumentSOURCE = "marimo"class HostAnalyzer:- """Analyze serialized document snapshots in a worker thread."""+ """Analyze document revisions in a worker thread."""def __init__(self) -> None:self._cells = CellAnalyzer()async def analyze(- self, snapshot: DocumentSnapshot+ self, document: Document) -> dict[protocol.CellId, protocol.CellAnalysis]:- return await asyncio.to_thread(self._cells, snapshot)+ return await asyncio.to_thread(self._cells, document)@dataclass(frozen=True)@@ -42,17 +42,17 @@ class _CachedCell:class CellAnalyzer:- """Reuse compilation by cell identity and code hash across snapshots."""+ """Reuse compilation by cell identity and code hash across revisions."""def __init__(self) -> None:self._cache: dict[protocol.CellId, _CachedCell] = {}def __call__(- self, snapshot: DocumentSnapshot+ self, document: Document) -> dict[protocol.CellId, protocol.CellAnalysis]:cache: dict[protocol.CellId, _CachedCell] = {}graph = DirectedGraph()- for cell in snapshot.cells:+ for cell in document:cached = self._cache.get(cell.id)if cached is None or cached.code_hash != cell.code_hash:try:@@ -68,7 +68,7 @@ class CellAnalyzer:self._cache = cacheanalyses: dict[protocol.CellId, protocol.CellAnalysis] = {}- for cell in snapshot.cells:+ for cell in document:compiled = cache[cell.id].resultif isinstance(compiled, protocol.Error):analyses[cell.id] = protocol.CellAnalysis(diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex fb24ac2043..3c98b9726b 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -10,11 +10,10 @@ from typing import TYPE_CHECKING, Anyfrom marimo import _loggersfrom marimo._core import protocol-from marimo._core.document import CellSource, Document, revision+from marimo._core.document import Document, DocumentCellfrom marimo._core.errors import (Conflict,DecisionRequired,- EditConflict,Invalid,NotFound,)@@ -38,7 +37,6 @@ if TYPE_CHECKING:from marimo._config.manager import MarimoConfigManagerfrom marimo._core.backend import Message- from marimo._core.document import Changedfrom marimo._core.stream import Event, Sinkfrom marimo._messaging.notebook import NotebookCellfrom marimo._server.session_manager import SessionManager@@ -62,7 +60,7 @@ class _FileContents:"""A notebook file as read: its text and the document it parses to."""text: str- cells: list[CellSource]+ cells: list[DocumentCell]app_config: dict[str, Any]@@ -77,19 +75,6 @@ def _texts_differ(text: str, baseline: str) -> bool:return contents_differ_excluding_generated_with(text, baseline)-def _etags(- changed: Changed, document: protocol.Document-) -> protocol.EditResponse:- """An edit response for a replacement, with etags for what changed."""- cells: dict[str, protocol.CellEtags | None] = {- cell.id: protocol.CellEtags(etag=cell.etag, code_hash=cell.code_hash)- for cell in changed.cells- }- for cell_id in changed.removed:- cells[cell_id] = None- return protocol.EditResponse(document=document, cells=cells)--def _running_loop() -> asyncio.AbstractEventLoop | None:try:return asyncio.get_running_loop()@@ -118,6 +103,9 @@ class SessionBridge(SessionEventListener):"""Each file's text as the host last read or wrote it, without a session."""self._rebaselining: dict[protocol.NotebookId, asyncio.Task[None]] = {}self._adopting: dict[protocol.NotebookId, Session] = {}+ # TODO(MO-8005): The response to the session's latest mirror of its+ # app config, for the edit that caused it. Ends with the mirror.+ self._mirrored: dict[protocol.NotebookId, protocol.EditResponse] = {}self.host = Host(operations=OPERATIONS)self._backends: dict[protocol.NotebookId, SessionBackend] = {}self.index = WorkspaceIndex(@@ -169,20 +157,20 @@ class SessionBridge(SessionEventListener):raise Conflict("The notebook document could not be loaded")cells, app_config = loaded.cells, loaded.app_configself._file_texts[record.id] = loaded.text- document = Document(- record.id,- cells,- app_config,- saved=session is None,- )+ document = Document(cells, app_config)+ # Without a session the file is what was read. With one, the+ # editor's document may have moved on from the file.+ saved_etag = document.etag if session is None else Noneif session is not None and loaded is not None:- document.mark_saved(revision(loaded.cells, loaded.app_config))+ saved_etag = Document(loaded.cells, loaded.app_config).etagbackend = self._make_backend(record.id)return Notebook(+ record.id,document,Executions(),backend,sink,+ saved_etag=saved_etag,analyzer=HostAnalyzer(),)@@ -257,14 +245,9 @@ class SessionBridge(SessionEventListener):if file is None:raise Conflict("The notebook has no file to save to")# Check and snapshot only after waiting for the file lock.- snapshot = notebook.document.snapshot()- if if_match is not None and snapshot.document.etag not in if_match:- raise EditConflict(- "The document has changed since it was read",- change=0,- cell=None,- document=snapshot.document,- )+ if if_match is not None:+ notebook.require_revision(if_match)+ revision = notebook.documentsession = self._session_of(notebook.id)if session is None and await self._file_changed(notebook.id, file):answer = (decisions or {}).get(_FILE_CHANGED.id)@@ -275,7 +258,7 @@ class SessionBridge(SessionEventListener):)if answer == "reload":return await self._reload(- notebook, file, snapshot.document, request_id+ notebook, file, revision.etag, request_id)if answer != "overwrite":raise Invalid(@@ -287,7 +270,7 @@ class SessionBridge(SessionEventListener):# The notebook's writer must persist snapshots without mutating# the live document; cover attached-session edits during a save.if session is None:- cells = [documents.to_notebook_cell(c) for c in snapshot.cells]+ cells = [documents.to_notebook_cell(c) for c in revision]manager = Noneelse:cells = copy.deepcopy(session.document.cells)@@ -321,9 +304,9 @@ class SessionBridge(SessionEventListener):if manager is None:manager = self._file_manager(path)text = manager.save_from_cells(cells)- etag = revision(+ etag = Document(documents.sources(cells), manager.app.config.asdict_difference()- )+ ).etagreturn etag, textasync def _file_changed(@@ -351,7 +334,7 @@ class SessionBridge(SessionEventListener):self,notebook: Notebook,file: Path,- before: protocol.Document,+ before: protocol.Etag,request_id: str,) -> protocol.EditResponse:"""Replace the document with the file's contents as the saved revision."""@@ -360,18 +343,11 @@ class SessionBridge(SessionEventListener):raise Conflict("The notebook file could not be loaded")# An edit may have landed while the file was read. Replacing the# document now would lose it.- if notebook.document._record.etag != before.etag:- raise EditConflict(- "The document changed while the file was being read",- change=0,- cell=None,- document=notebook.document._record,- )+ notebook.require_revision([before])self._file_texts[notebook.id] = loaded.text- changed = notebook.replace(+ return notebook.replace(loaded.cells, loaded.app_config, saved=True, request_id=request_id)- return _etags(changed, notebook.document._record)async def edit(self,@@ -395,9 +371,13 @@ class SessionBridge(SessionEventListener):session = self._session_of(notebook.id)if session is None:return response+ self._mirrored.pop(notebook.id, None)documents.apply_to_session(session, notebook.document)+ mirrored = self._mirrored.pop(notebook.id, None)+ if mirrored is None:+ return responsereturn protocol.EditResponse(- cells=response.cells, document=notebook.document._record+ cells=response.cells, document=mirrored.document)def _session_of(self, notebook_id: protocol.NotebookId) -> Session | None:@@ -420,9 +400,8 @@ class SessionBridge(SessionEventListener):# host is no longer wanted.self._rebaselining.pop(notebook_id, None)self._follow_saves(notebook_id, session)- document = notebook.document- if document._record.saved_etag != document._record.etag:- documents.apply_to_session(session, document)+ if notebook.saved_etag != notebook.document.etag:+ documents.apply_to_session(session, notebook.document)returncells, app_config = documents.from_session(session)notebook.replace(cells, app_config, saved=True)@@ -446,7 +425,7 @@ class SessionBridge(SessionEventListener):def persisted(cells: Sequence[NotebookCell], app_config: dict[str, Any]) -> None:- etag = revision(documents.sources(cells), app_config)+ etag = Document(documents.sources(cells), app_config).etagif _running_loop() is loop:self._saved(notebook_id, etag)else:@@ -515,7 +494,7 @@ class SessionBridge(SessionEventListener):if session is None or notebook is None:returncells, app_config = documents.from_session(session)- notebook.replace(cells, app_config)+ self._mirrored[notebook_id] = notebook.replace(cells, app_config)def _project_path(self, path: Path) -> Path:root = self.index.root@@ -670,6 +649,7 @@ class SessionBridge(SessionEventListener):self._backends.pop(event.notebook_id, None)self._file_texts.pop(event.notebook_id, None)self._rebaselining.pop(event.notebook_id, None)+ self._mirrored.pop(event.notebook_id, None)async def _adopt(self, session: Session) -> None:path = session.app_file_manager.pathdiff --git a/marimo/_server/host/document.py b/marimo/_server/host/document.pyindex ceef792954..c4ea4b4c24 100644--- a/marimo/_server/host/document.py+++ b/marimo/_server/host/document.py@@ -22,7 +22,7 @@ from typing import TYPE_CHECKING, Anyfrom marimo._ast.cell import CellConfigfrom marimo._core import protocol-from marimo._core.document import CellSource+from marimo._core.document import DocumentCellfrom marimo._messaging.notebook import (CreateCell,DeleteCell,@@ -48,26 +48,38 @@ if TYPE_CHECKING:from marimo._session.session import Session-def from_session(session: Session) -> tuple[list[CellSource], dict[str, Any]]:+def from_session(+ session: Session,+) -> tuple[list[DocumentCell], dict[str, Any]]:return (sources(session.document.cells),session.app_file_manager.app.config.asdict_difference(),)-def sources(cells: Iterable[NotebookCell]) -> list[CellSource]:+def sources(cells: Iterable[NotebookCell]) -> list[DocumentCell]:"""The document sources for the editor's cells."""return [- CellSource(cell.id, cell.code, cell.name, _config(cell.config))+ DocumentCell(+ protocol.CellId(cell.id),+ cell.code,+ cell.name,+ _config(cell.config),+ )for cell in cells]def from_file_manager(manager: AppFileManager,-) -> tuple[list[CellSource], dict[str, Any]]:+) -> tuple[list[DocumentCell], dict[str, Any]]:cells = [- CellSource(data.cell_id, data.code, data.name, _config(data.config))+ DocumentCell(+ protocol.CellId(data.cell_id),+ data.code,+ data.name,+ _config(data.config),+ )for data in manager.app.cell_manager.cell_data()]return cells, manager.app.config.asdict_difference()@@ -91,7 +103,7 @@ def _cell_config(config: protocol.CellConfig) -> CellConfig:)-def to_notebook_cell(cell: protocol.Cell) -> NotebookCell:+def to_notebook_cell(cell: DocumentCell) -> NotebookCell:return NotebookCell(id=CellId_t(cell.id),code=cell.code,@@ -153,7 +165,7 @@ def apply_to_session(session: Session, document: Document) -> None:wanted = {CellId_t(cell.id) for cell in document}deleted = [c for c in current.cell_ids if c not in wanted]changes.extend(DeleteCell(cell_id=cell_id) for cell_id in deleted)- order = [CellId_t(c) for c in document.order]+ order = [CellId_t(c.id) for c in document]if current.cell_ids != order:changes.append(ReorderCells(cell_ids=tuple(order)))if not changes:diff --git a/tests/_core/conftest.py b/tests/_core/conftest.pyindex 98feaef598..4c66737dc3 100644--- a/tests/_core/conftest.py+++ b/tests/_core/conftest.py@@ -8,7 +8,7 @@ import asyncioimport pytestfrom marimo._core import backend as be, protocol-from marimo._core.document import Document, DocumentSnapshot, code_hash+from marimo._core.document import Document, code_hashfrom marimo._core.executions import CellExecution, Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook@@ -44,16 +44,16 @@ class ScriptedAnalyzer:"""Expose snapshots and let tests complete analysis explicitly."""def __init__(self) -> None:- self.requests: list[DocumentSnapshot] = []+ self.requests: list[Document] = []self.pending: asyncio.Queue[tuple[- DocumentSnapshot,+ Document,asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],]] = asyncio.Queue()async def analyze(- self, snapshot: DocumentSnapshot+ self, snapshot: Document) -> dict[protocol.CellId, protocol.CellAnalysis]:result: asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]@@ -65,7 +65,7 @@ class ScriptedAnalyzer:async def next_request(self,) -> tuple[- DocumentSnapshot,+ Document,asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],]:return await asyncio.wait_for(self.pending.get(), timeout=5)@@ -109,11 +109,14 @@ def make_notebook(document: Document | None = None,analyzer: ScriptedAnalyzer | None = None,) -> Notebook:+ document = document if document is not None else Document([], {})return Notebook(- document or Document(record.id, [], {}),+ record.id,+ document,Executions(),backend or ScriptedBackend(),sink,+ saved_etag=document.etag,analyzer=analyzer,)diff --git a/tests/_core/test_executions.py b/tests/_core/test_executions.pyindex f30d162532..baae72ac79 100644--- a/tests/_core/test_executions.py+++ b/tests/_core/test_executions.py@@ -7,7 +7,7 @@ import pytestfrom msgspec.structs import replacefrom marimo._core import backend as be, protocol-from marimo._core.document import CellSource, Document+from marimo._core.document import Document, DocumentCellfrom marimo._core.errors import NoRuntimefrom marimo._core.executions import (CellExecution,@@ -265,7 +265,7 @@ def test_removing_a_cell_drops_its_result_or_disowns_active_work() -> None:def test_restored_executions_are_current_until_replaced() -> None:- document = Document(NOTEBOOK, [CellSource("c1", "42")], {})+ document = Document([DocumentCell("c1", "42")], {})retained = retained_execution(run_id="old-run")executions = Executions.restore({protocol.CellId("c1"): retained}, cells=document@@ -300,7 +300,7 @@ def test_restored_executions_are_current_until_replaced() -> None:def test_restore_rejects_inconsistent_executions(invalid: str, message: str) -> None:- document = Document(NOTEBOOK, [CellSource("c1", "42")], {})+ document = Document([DocumentCell("c1", "42")], {})retained = retained_execution()execution, outputs = retained.execution, retained.outputskey = protocol.CellId("c1")diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.pyindex eec5161658..fd1f158e39 100644--- a/tests/_core/test_notebook.py+++ b/tests/_core/test_notebook.py@@ -12,8 +12,8 @@ from inline_snapshot import snapshotfrom msgspec import UNSETfrom msgspec.structs import replace-from marimo._core import backend as be-from marimo._core.document import CellSource, Document+from marimo._core import backend as be, protocol+from marimo._core.document import Document, DocumentCellfrom marimo._core.errors import Conflict, NoRuntime, NotFoundfrom marimo._core.executions import CellExecution, Executionsfrom marimo._core.host import Host@@ -61,6 +61,16 @@ from tests._core.conftest import ()+def published(+ notebook: Notebook,+) -> tuple[protocol.Document, list[protocol.Cell]]:+ """The document and cell records the notebook publishes."""+ events = notebook._snapshot()+ (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]+ cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]+ return document, cells++def running(notebook: Notebook, backend: ScriptedBackend) -> Runtime:notebook.start(request_id="req-start")notebook.observe(@@ -1134,16 +1144,18 @@ async def test_initial_results_are_published_and_replaced_by_live_execution(run_id: str | None,) -> None:retained = retained_execution(run_id=run_id)- document = Document(record().id, [CellSource(CellId("c1"), "42")], {})+ document = Document([DocumentCell(CellId("c1"), "42")], {})host = Host(operations=[])host.update_project(project())host.add_notebook(record(),lambda _, sink: Notebook(+ record().id,document,Executions.restore({CellId("c1"): retained}, cells=document),ScriptedBackend(),sink,+ saved_etag=document.etag,),)live: list[Event] = []@@ -1168,7 +1180,7 @@ async def test_initial_results_are_published_and_replaced_by_live_execution(async def test_current_cell_results_can_seed_another_notebook() -> None:_, notebook = await host_at(Clock())- notebook.replace([CellSource(CellId("c1"), "code")], {})+ notebook.replace([DocumentCell(CellId("c1"), "code")], {})run = notebook.run("code", request_id="request")execution = plan(notebook, run, "cell", "c1")notebook.observe(@@ -1176,18 +1188,22 @@ async def test_current_cell_results_can_seed_another_notebook() -> None:)finish(notebook, execution)notebook.observe(be.Done(run.id, "succeeded"))- document = Document.from_records(- notebook.document._record, list(notebook.document)- )+ document = Document.restore(*published(notebook))retained = notebook.executions.current(CellId("c1"))assert retained is not Nonerestored = Notebook(+ NotebookId("restored"),document,Executions.restore({CellId("c1"): retained}, cells=document),ScriptedBackend(),Stream(history=0),+ saved_etag=notebook.saved_etag,+ )+ source_record, source_cells = published(notebook)+ assert published(restored) == (+ replace(source_record, notebook_id=restored.id),+ [replace(cell, notebook_id=restored.id) for cell in source_cells],)- assert restored.document._record == notebook.document._recordassert list(restored.document) == list(notebook.document)assert restored.executions.current(CellId("c1")) == retainedassert fold(restored._snapshot()) == {@@ -1202,15 +1218,14 @@ def test_restoration_preserves_revisions_and_outputs(saved: bool,) -> None:document = Document(- record().id,- [CellSource(CellId("c2"), "pass"), CellSource(CellId("c1"), "42")],+ [DocumentCell(CellId("c2"), "pass"), DocumentCell(CellId("c1"), "42")],{"width": "full"},- saved=saved,)+ saved_etag = document.etag if saved else None# The output belongs to the previous source, and the saved revision can# precede the current one. Neither is rewritten during restoration.- document.replace(- [CellSource(CellId("c2"), "pass"), CellSource(CellId("c1"), "43")],+ document, _ = document.replace(+ [DocumentCell(CellId("c2"), "pass"), DocumentCell(CellId("c1"), "43")],{"width": "full"},)seed = retained_execution(run_id="historical-run")@@ -1228,16 +1243,26 @@ def test_restoration_preserves_revisions_and_outputs(replace(seed.outputs[0], id=ItemId("last"), seq=2),),)- document_record, cells = deepcopy((document._record, list(document)))- restored = Document.from_records(document_record, cells[::-1])+ original = Notebook(+ record().id,+ document,+ Executions(),+ ScriptedBackend(),+ Stream(history=0),+ saved_etag=saved_etag,+ )+ document_record, cells = deepcopy(published(original))+ restored = Document.restore(document_record, cells[::-1])backend = ScriptedBackend()notebook = Notebook(+ document_record.notebook_id,restored,Executions.restore({CellId("c1"): retained}, cells=restored),backend,Stream(history=0),+ saved_etag=document_record.saved_etag,)- assert notebook.document._record == document._record+ assert published(notebook) == published(original)assert list(notebook.document) == list(document)assert notebook.executions.current(CellId("c1")) == retainedassert backend.calls == []@@ -1247,25 +1272,27 @@ def test_restoration_preserves_revisions_and_outputs(assert [getattr(e.data, e.kind).seq for e in outputs] == [0, 1, 2]# Restoration copies the supplied records.document_record.app_config["width"] = "medium"- assert notebook.document._record == document._record+ assert published(notebook) == published(original)async def test_edits_preserve_results_and_deletion_removes_them() -> None:retained = retained_execution()- document = Document(record().id, [CellSource(CellId("c1"), "42")], {})+ document = Document([DocumentCell(CellId("c1"), "42")], {})host = Host(operations=[])host.update_project(project())host.add_notebook(record(),lambda _, sink: Notebook(+ record().id,document,Executions.restore({CellId("c1"): retained}, cells=document),ScriptedBackend(),sink,+ saved_etag=document.etag,),)notebook = await host.notebook(record().id)- notebook.replace([CellSource(CellId("c1"), "43")], {})+ notebook.replace([DocumentCell(CellId("c1"), "43")], {})assert notebook.executions.current(CellId("c1")) == retainedassert (next(iter(notebook.document)).code_hash != retained.execution.code_hash@@ -1288,7 +1315,7 @@ async def test_restoration_excludes_live_work_and_cleans_up_deleted_active_cellsNone):_, notebook = await host_at(Clock())- notebook.replace([CellSource(CellId("c1"), "code")], {})+ notebook.replace([DocumentCell(CellId("c1"), "code")], {})notebook.attach()run = notebook.run("code", request_id="request")execution = plan(notebook, run, "active", "c1")@@ -1296,9 +1323,7 @@ async def test_restoration_excludes_live_work_and_cleans_up_deleted_active_cellsbe.Produced(Console(execution, ItemId("out"), "stdout", 0, "x")))assert notebook.executions.current(CellId("c1")) is None- document = Document.from_records(- notebook.document._record, list(notebook.document)- )+ document = Document.restore(*published(notebook))executions = Executions.restore({cell.id: result@@ -1308,7 +1333,12 @@ async def test_restoration_excludes_live_work_and_cleans_up_deleted_active_cellscells=document,)restored = Notebook(- document, executions, ScriptedBackend(), Stream(history=0)+ notebook.id,+ document,+ executions,+ ScriptedBackend(),+ Stream(history=0),+ saved_etag=notebook.saved_etag,)assert names(restored._snapshot()) == ["cell", "document"]notebook.replace([], {})@@ -1322,7 +1352,7 @@ async def test_source_edits_keep_live_results_until_the_cell_is_deleted() -> (None):host, notebook = await host_at(Clock())- notebook.replace([CellSource("c1", "42")], {})+ notebook.replace([DocumentCell("c1", "42")], {})run = notebook.run("42", request_id="run")execution = plan(notebook, run, "result", "c1")notebook.observe(@@ -1332,7 +1362,7 @@ async def test_source_edits_keep_live_results_until_the_cell_is_deleted() -> (notebook.observe(be.Done(run.id, "succeeded"))retained = notebook.executions._records()- notebook.replace([CellSource("c1", "43")], {})+ notebook.replace([DocumentCell("c1", "43")], {})assert notebook.executions._records() == retainedlive: list[Event] = []@@ -1353,7 +1383,7 @@ async def test_deleting_an_active_cell_releases_its_result_when_the_run_ends() -None):host, notebook = await host_at(Clock())- notebook.replace([CellSource("c1", "42")], {})+ notebook.replace([DocumentCell("c1", "42")], {})run = notebook.run("42", request_id="run")execution = plan(notebook, run, "result", "c1")notebook.replace([], {})diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.pyindex 9981fe1c30..7ab2d5caee 100644--- a/tests/_core/test_notebook_document.py+++ b/tests/_core/test_notebook_document.py@@ -11,20 +11,20 @@ from msgspec.structs import replacefrom marimo._core import protocolfrom marimo._core.document import (- CellSource,Document,+ DocumentCell,+ Stale,app_config_etag,cell_etag,code_hash,document_etag,order_etag,- revision,)from marimo._core.errors import EditConflict, Invalidfrom marimo._core.executions import Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook-from marimo._core.stream import Event+from marimo._core.stream import Event, Streamfrom tests._core.conftest import (ScriptedAnalyzer,ScriptedBackend,@@ -42,15 +42,23 @@ HIDDEN = protocol.CellConfig()-def fixture_cells() -> list[CellSource]:+def fixture_cells() -> list[DocumentCell]:"""The cells in pair's `notebook-events.sse` fixture."""return [- CellSource("c1", "import marimo as mo"),- CellSource("c3", "x = 21"),- CellSource("k7f2", "y = x * 2", config=HIDDEN),+ DocumentCell(protocol.CellId("c1"), "import marimo as mo"),+ DocumentCell(protocol.CellId("c3"), "x = 21"),+ DocumentCell(protocol.CellId("k7f2"), "y = x * 2", config=HIDDEN),]+def cell(cell_id: str, code: str, **kwargs: object) -> DocumentCell:+ return DocumentCell(protocol.CellId(cell_id), code, **kwargs) # type: ignore[arg-type]+++def ids(document: Document) -> list[str]:+ return [c.id for c in document]++def put(cell_id: str,code: str,@@ -79,23 +87,51 @@ def set_order(base_etag: str, *cell_ids: str) -> protocol.SetOrder:)+def hosted(document: Document) -> Notebook:+ """A notebook around `document` with the revision saved."""+ return Notebook(+ NOTEBOOK,+ document,+ Executions(),+ ScriptedBackend(),+ Stream(history=0),+ saved_etag=document.etag,+ )+++def records(+ notebook: Notebook,+) -> tuple[protocol.Document, list[protocol.Cell]]:+ """The document and cell records the notebook publishes."""+ events = notebook._snapshot()+ (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]+ cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]+ return document, cells+++class TestCells:+ def test_normalizes_line_endings_and_compares_by_content(self) -> None:+ c = cell("a", "x = 1\r\ny = 2", name="named", config=HIDDEN)+ assert c.code == "x = 1\ny = 2"+ assert c == cell("a", "x = 1\ny = 2", name="named", config=HIDDEN)+ assert c != cell("a", "x = 1\ny = 2", name="other", config=HIDDEN)++class TestEtags:def test_reordering_cell_ids_with_newlines_changes_the_revision(self,) -> None:- cells = [CellSource("a", "x = 1"), CellSource("a\na", "x = 1")]- document = Document(NOTEBOOK, cells, {})- before = document._record+ cells = [cell("a", "x = 1"), cell("a\na", "x = 1")]+ before = Document(cells, {})- document.replace(list(reversed(cells)), {})+ document, _ = before.replace(list(reversed(cells)), {})- assert [cell.id for cell in document] == ["a\na", "a"]- assert document._record.order_etag != before.order_etag- assert document._record.etag != before.etag- assert document._record.saved_etag == before.etag+ assert ids(document) == ["a\na", "a"]+ assert document.order_etag != before.order_etag+ assert document.etag != before.etagdef test_match_the_values_pinned_in_the_fixtures(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})+ document = Document(fixture_cells(), {"width": "full"})c1, c3, k7f2 = documentassert (c3.code_hash, c3.etag) == (@@ -107,10 +143,10 @@ class TestEtags:"f199b5f48ae0aabb",)assert c1.etag == "48d6363150d6281c"- assert document._record.order_etag == "b9c412c2d7d63161"- assert document._record.app_config_etag == "283513048dfeb45b"- assert document._record.etag == "e59d9c2af02f5814"- assert document._record.saved_etag == "e59d9c2af02f5814"+ assert document.order_etag == "b9c412c2d7d63161"+ assert document.app_config_etag == "283513048dfeb45b"+ assert document.etag == "e59d9c2af02f5814"+ assert hosted(document).saved_etag == document.etagdef test_are_derived_from_their_parts(self) -> None:hashed = code_hash("x = 21")@@ -135,95 +171,96 @@ class TestEtags:order_etag(["a"]), app_config_etag({}), [hashed]) != (document_etag(order_etag(["a"]), app_config_etag({}), []))- def test_revision_matches_the_document_built_from_the_same_sources(++class TestValue:+ def test_config_is_detached_from_inputs_and_published_records(self,) -> None:- cells = [*fixture_cells(), CellSource("crlf", "x = 1\r\ny = 2")]- app_config = {"width": "full"}- document = Document(NOTEBOOK, cells, app_config)- assert revision(cells, app_config) == document._record.etag+ config = {"auto_download": ["html"]}+ document = Document(fixture_cells(), config)+ notebook = hosted(document)+ before, _ = records(notebook)- def test_normalizes_line_endings_before_hashing(self) -> None:- document = Document(NOTEBOOK, [CellSource("a", "x = 1\r\ny = 2")], {})- (cell,) = document- assert cell.code == "x = 1\ny = 2"- assert cell.code_hash == code_hash("x = 1\ny = 2")+ config["auto_download"].append("markdown")+ published, _ = records(notebook)+ published.app_config["auto_download"].clear()++ assert document.app_config == {"auto_download": ["html"]}+ assert records(notebook)[0] == before++ def test_documents_with_the_same_content_are_equal(self) -> None:+ assert Document(fixture_cells(), {"a": 1}) == Document(+ fixture_cells(), {"a": 1}+ )+ assert Document(fixture_cells(), {}) != Document(+ fixture_cells()[:2], {}+ )++ def test_changing_produces_a_new_document_and_keeps_the_old(self) -> None:+ before = Document(fixture_cells(), {"nested": {"items": [1]}})++ after, _ = before.replace([cell("c1", "42", name="renamed")], {})++ assert ids(before) == ["c1", "c3", "k7f2"]+ assert before.app_config == {"nested": {"items": [1]}}+ assert ids(after) == ["c1"]+ assert after.app_config == {}++ def test_rejects_duplicate_ids(self) -> None:+ with pytest.raises(ValueError, match="unique"):+ Document([cell("a", "1"), cell("a", "2")], {})class TestReplace:def test_reports_new_changed_and_removed_cells(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})- before = document._record+ before = Document(fixture_cells(), {"width": "full"})- changed = document.replace(+ document, changed = before.replace([- CellSource("c1", "import marimo as mo"),- CellSource("new", "z = 3"),- CellSource("k7f2", "y = x * 3", config=HIDDEN),+ cell("c1", "import marimo as mo"),+ cell("new", "z = 3"),+ cell("k7f2", "y = x * 3", config=HIDDEN),],{"width": "full"},)- assert [cell.id for cell in changed.cells] == ["new", "k7f2"]+ assert [c.id for c in changed.cells] == ["new", "k7f2"]assert changed.removed == ["c3"]- assert changed.document is not None- assert changed.document.order == ("c1", "new", "k7f2")- assert changed.document.order_etag != before.order_etag- assert changed.document.app_config_etag == before.app_config_etag- assert changed.document.saved_etag == before.etag+ assert changed.etag == document.etag != before.etag+ assert ids(document) == ["c1", "new", "k7f2"]+ assert document.order_etag != before.order_etag+ assert document.app_config_etag == before.app_config_etagdef test_a_change_that_changes_nothing_reports_nothing(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})+ before = Document(fixture_cells(), {"width": "full"})++ document, changed = before.replace(fixture_cells(), {"width": "full"})- assert not document.replace(fixture_cells(), {"width": "full"})+ assert not changed+ assert document == beforedef test_an_app_config_change_moves_only_its_etag(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})- before = document._record+ before = Document(fixture_cells(), {})- changed = document.replace(fixture_cells(), {"width": "full"})+ document, changed = before.replace(fixture_cells(), {"width": "full"})assert changed.cells == []assert changed.removed == []- assert changed.document is not None- assert changed.document.order_etag == before.order_etag- assert changed.document.app_config_etag != before.app_config_etag- assert changed.document.etag != before.etag-- def test_rejects_duplicate_ids(self) -> None:- with pytest.raises(ValueError, match="unique"):- Document(- NOTEBOOK, [CellSource("a", "1"), CellSource("a", "2")], {}- )-- def test_marks_saved_state_separately(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {}, saved=False)- assert document._record.saved_etag is None-- document.replace([CellSource("c1", "1")], {})- saved = document.mark_saved()-- assert saved is not None- assert saved.saved_etag == saved.etag- assert document.mark_saved() is None-- # A store may hold a revision other than the live one.- other = Document(NOTEBOOK, fixture_cells(), {}, saved=False)- behind = other.mark_saved(saved.etag)- assert behind is not None- assert behind.saved_etag == saved.etag != behind.etag+ assert changed.etag == document.etag+ assert document.order_etag == before.order_etag+ assert document.app_config_etag != before.app_config_etag+ assert document.etag != before.etagclass TestApply:def test_creates_replaces_deletes_and_reorders_as_one_unit(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})- before = document._record- c3 = document.cell("c3")- k7f2 = document.cell("k7f2")+ before = Document(fixture_cells(), {"width": "full"})+ c3 = before.cell("c3")+ k7f2 = before.cell("k7f2")assert c3 is not Noneassert k7f2 is not None- applied = document.apply(+ result = before.apply([put("c2", "print('hi')", None, after="c1"),put("c3", "x = 22", c3.etag),@@ -232,11 +269,13 @@ class TestApply:])- assert document.order == ["c3", "c2", "c1"]+ assert not isinstance(result, Stale)+ document, applied = result+ assert ids(document) == ["c3", "c2", "c1"]assert [c.id for c in applied.changed.cells] == ["c3", "c2"]assert applied.changed.removed == ["k7f2"]- assert applied.changed.document is not None- assert applied.changed.document.app_config == {"width": "full"}+ assert applied.changed.etag == document.etag+ assert document.app_config == {"width": "full"}assert set(applied.cells) == {"c2", "c3", "k7f2"}assert applied.cells["k7f2"] is Nonenew_c3 = document.cell("c3")@@ -247,66 +286,55 @@ class TestApply:assert new_c3.etag != c3.etagdef test_a_stale_etag_applies_nothing_and_names_the_change(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})- before = document._record+ document = Document(fixture_cells(), {})- with pytest.raises(EditConflict) as raised:- document.apply(- [- put("new", "z = 1", None),- put("c3", "x = 22", "0000000000000000"),- ]- )+ result = document.apply(+ [+ put("new", "z = 1", None),+ put("c3", "x = 22", "0000000000000000"),+ ]+ )- assert raised.value.change == 1- assert raised.value.cell == document.cell("c3")- assert raised.value.document == before- assert document._record == before- assert document.cell("new") is None+ assert result == Stale(change=1, cell_id="c3")def test_creating_an_existing_cell_or_replacing_a_missing_one_conflicts(self,) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})+ document = Document(fixture_cells(), {})c3 = document.cell("c3")assert c3 is not None- with pytest.raises(EditConflict) as raised:- document.apply([put("c3", "x = 1", None)])- assert raised.value.cell == c3-- with pytest.raises(EditConflict) as raised:- document.apply([put("nope", "x = 1", "*")])- assert raised.value.cell is None-+ assert document.apply([put("c3", "x = 1", None)]) == Stale(0, "c3")+ assert document.apply([put("nope", "x = 1", "*")]) == Stale(0, "nope")# The cell existed when the client read, even if the same batch# deletes it first.- with pytest.raises(EditConflict) as raised:- document.apply([delete("c3", c3.etag), put("c3", "x = 1", None)])- assert raised.value.change == 1- assert document.cell("c3") == c3+ assert document.apply(+ [delete("c3", c3.etag), put("c3", "x = 1", None)]+ ) == Stale(1, "c3")def test_star_skips_the_check(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})-- document.apply(+ result = Document(fixture_cells(), {}).apply([put("c3", "x = 23", "*"), set_order("*", "k7f2", "c3", "c1")])- assert document.order == ["k7f2", "c3", "c1"]+ assert not isinstance(result, Stale)+ assert ids(result[0]) == ["k7f2", "c3", "c1"]def test_placement_has_no_precondition(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})-- document.apply([put("a", "1", None, before="c1")])- document.apply([put("b", "2", None, after="c1")])- document.apply([put("c", "3", None)])-- assert document.order == ["a", "c1", "b", "c3", "k7f2", "c"]+ document = Document(fixture_cells(), {})+ for change in (+ put("a", "1", None, before="c1"),+ put("b", "2", None, after="c1"),+ put("c", "3", None),+ ):+ result = document.apply([change])+ assert not isinstance(result, Stale)+ document = result[0]++ assert ids(document) == ["a", "c1", "b", "c3", "k7f2", "c"]def test_malformed_changes_are_invalid(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})- before = document._record+ document = Document(fixture_cells(), {})with pytest.raises(Invalid):document.apply([set_order("*", "c1", "c3")])@@ -316,15 +344,17 @@ class TestApply:document.apply([put("a", "1", None, after="nope")])with pytest.raises(Invalid):document.apply([put("a", "1", None, after="c1", before="c3")])- assert document._record == beforedef test_an_edit_that_changes_nothing_reports_nothing(self) -> None:- document = Document(NOTEBOOK, fixture_cells(), {})- c3 = document.cell("c3")+ before = Document(fixture_cells(), {})+ c3 = before.cell("c3")assert c3 is not None- applied = document.apply([put("c3", "x = 21", c3.etag)])+ result = before.apply([put("c3", "x = 21", c3.etag)])+ assert not isinstance(result, Stale)+ document, applied = result+ assert document == beforeassert not applied.changedassert applied.cells["c3"] == protocol.CellEtags(etag=c3.etag, code_hash=c3.code_hash@@ -332,20 +362,23 @@ class TestApply:class TestFromRecords:- def test_preserves_the_saved_revision(self) -> None:- source = Document(NOTEBOOK, fixture_cells(), {"width": "full"})- # 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._record- assert list(restored) == list(source)+ def test_restores_the_content(self) -> None:+ notebook = hosted(Document(fixture_cells(), {"width": "full"}))+ # The saved revision precedes the current one. The content is+ # what is restored, and the notebook carries the rest.+ notebook.replace([cell("c1", "import marimo")], {"width": "full"})+ document, cells = records(notebook)++ restored = Document.restore(document, cells)++ assert restored == notebook.document+ assert document.saved_etag != restored.etag@pytest.mark.parametrize("invalid", ["order", "notebook-id", "cell-etag", "document-etag"])def test_rejects_inconsistent_records(self, invalid: str) -> None:- source = Document(NOTEBOOK, fixture_cells(), {})- document, cells = source._record, list(source)+ document, cells = records(hosted(Document(fixture_cells(), {})))if invalid == "order":document = replace(document, order=())elif invalid == "notebook-id":@@ -357,7 +390,76 @@ class TestFromRecords:else:document = replace(document, app_config={"width": "full"})with pytest.raises(ValueError):- Document.from_records(document, cells)+ Document.restore(document, cells)+++class TestNotebookRecords:+ def test_stamps_the_notebook_id_and_carries_the_saved_state(+ self,+ ) -> None:+ document = Document(fixture_cells(), {"width": "full"})+ notebook = Notebook(+ NOTEBOOK,+ document,+ Executions(),+ ScriptedBackend(),+ Stream(history=0),+ )+ record, cells = records(notebook)+ assert record.notebook_id == NOTEBOOK+ assert record.saved_etag is None+ assert record.etag == document.etag+ assert record.order == ("c1", "c3", "k7f2")+ assert record.app_config == {"width": "full"}+ assert [c.notebook_id for c in cells] == [NOTEBOOK] * 3+ assert [(c.id, c.etag) for c in cells] == [+ (c.id, c.etag) for c in document+ ]++ def test_marks_saved_state_separately(self) -> None:+ notebook = Notebook(+ NOTEBOOK,+ Document(fixture_cells(), {}),+ Executions(),+ ScriptedBackend(),+ Stream(history=0),+ )+ assert notebook.saved_etag is None++ notebook.replace([cell("c1", "1")], {})+ saved = notebook.mark_saved(notebook.document.etag)++ assert saved.saved_etag == saved.etag+ assert notebook.saved_etag == saved.etag++ # A store may hold a revision other than the live one.+ other = Notebook(+ NOTEBOOK,+ Document(fixture_cells(), {}),+ Executions(),+ ScriptedBackend(),+ Stream(history=0),+ )+ behind = other.mark_saved(saved.etag)+ assert behind.saved_etag == saved.etag != behind.etag++ def test_a_stale_edit_names_the_cell_and_document_as_they_are(+ self,+ ) -> None:+ document = Document(fixture_cells(), {})+ notebook = hosted(document)+ before, cells = records(notebook)+ (_, c3, _) = cells++ with pytest.raises(EditConflict) as raised:+ notebook.edit(+ [put("c3", "x = 22", "0000000000000000")], request_id="e"+ )++ assert raised.value.change == 0+ assert raised.value.cell == c3+ assert raised.value.document == before+ assert notebook.document is documentclass TestNotebook:@@ -370,9 +472,7 @@ class TestNotebook:lambda record, sink: make_notebook(record,sink,- document=Document(- NOTEBOOK, fixture_cells(), {"width": "full"}- ),+ document=Document(fixture_cells(), {"width": "full"}),),)log.clear()@@ -403,8 +503,8 @@ class TestNotebook:notebook.replace([- CellSource("c1", "import marimo as mo"),- CellSource("c3", "x = 22"),+ cell("c1", "import marimo as mo"),+ cell("c3", "x = 22"),],{},request_id="edit-1",@@ -420,26 +520,25 @@ class TestNotebook:notebook.replace(fixture_cells(), {})log.clear()- changed = notebook.replace(- [CellSource("c1", "x = 22")], {}, saved=True- )+ response = notebook.replace([cell("c1", "x = 22")], {}, saved=True)- assert changed.document is not None- assert changed.document.saved_etag == changed.document.etag+ assert response.document.saved_etag == response.document.etag+ assert set(response.cells) == {"c1", "c3", "k7f2"}+ assert response.cells["c3"] is Noneassert names(log) == ["cell","cell.removed","cell.removed","document",]- assert log[-1].data.document == changed.document # type: ignore[union-attr]+ assert log[-1].data.document == response.document # type: ignore[union-attr]def test_mark_saved_records_the_revision_that_was_written(self, notebook: Notebook, log: list[Event]) -> None:notebook.replace(fixture_cells(), {})- written = notebook.document._record.etag- notebook.replace([CellSource("c1", "x = 22")], {})+ written = notebook.document.etag+ notebook.replace([cell("c1", "x = 22")], {})log.clear()document = notebook.mark_saved(written, request_id="save-1")@@ -491,7 +590,7 @@ class TestAnalysis:) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})+ document = Document(fixture_cells(), {"width": "full"})notebook = await add_notebook(host,record(),@@ -499,8 +598,8 @@ class TestAnalysis:document=document,analyzer=analyzer,)- snapshot, result = await analyzer.next_request()- assert snapshot == document.snapshot()+ analyzed, result = await analyzer.next_request()+ assert analyzed is documentassert notebook.analysis is Nonelog.clear()@@ -511,7 +610,7 @@ class TestAnalysis:assert request_ids(log) == [UNSET]assert notebook.analysis == protocol.Analysis(notebook_id=NOTEBOOK,- document_etag=snapshot.document.etag,+ document_etag=document.etag,cells=cell_analyses(document),)assert names(host.events(notebook_id="n1")) == [@@ -529,7 +628,7 @@ class TestAnalysis:) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()- document = Document(NOTEBOOK, fixture_cells(), {})+ document = Document(fixture_cells(), {})notebook = await add_notebook(host,record(),@@ -539,35 +638,37 @@ class TestAnalysis:)first, result = await analyzer.next_request()first_analysis = cell_analyses(document)- notebook.replace([CellSource("c1", "1")], {}, request_id="edit-1")+ notebook.replace([cell("c1", "1")], {}, request_id="edit-1")notebook.replace(- [CellSource("c1", "2", name="named", config=HIDDEN)],+ [cell("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"+ # The analyzer holds the revision it was given.+ assert first is document+ assert first.etag != notebook.document.etag+ assert next(iter(first)).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()+ assert latest is notebook.document- result.set_result(cell_analyses(document))+ result.set_result(cell_analyses(latest))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+ assert notebook.analysis.document_etag == latest.etagasync def test_an_edit_is_analyzed_under_its_request_key(self, host: Host, log: list[Event]) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()- document = Document(NOTEBOOK, fixture_cells(), {})+ document = Document(fixture_cells(), {})notebook = await add_notebook(host,record(),@@ -581,11 +682,11 @@ class TestAnalysis:log.clear()notebook.edit([put("c9", "z = 1", None)], request_id="edit-1")- snapshot, result = await analyzer.next_request()- assert snapshot == document.snapshot()- assert [c.id for c in snapshot.cells] == ["c1", "c3", "k7f2", "c9"]+ analyzed, result = await analyzer.next_request()+ assert analyzed is notebook.document+ assert ids(analyzed) == ["c1", "c3", "k7f2", "c9"]- result.set_result(cell_analyses(document))+ result.set_result(cell_analyses(analyzed))await asyncio.sleep(0)assert names(log) == ["cell", "document", "analysis"]assert request_ids(log) == ["edit-1"] * 3@@ -595,7 +696,7 @@ class TestAnalysis:) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()- document = Document(NOTEBOOK, fixture_cells(), {})+ document = Document(fixture_cells(), {})notebook = await add_notebook(host,record(),@@ -606,14 +707,14 @@ class TestAnalysis:first, result = await analyzer.next_request()result.set_result(cell_analyses(document))await asyncio.sleep(0)- notebook.replace([CellSource("c1", "1")], {})+ notebook.replace([cell("c1", "1")], {})_, result = await analyzer.next_request()assert notebook.analysis is not Noneassert (notebook.analysis.document_etag- == first.document.etag- != document._record.etag+ == first.etag+ != notebook.document.etag)assert names(host.events(notebook_id="n1")) == ["notebook",@@ -622,7 +723,7 @@ class TestAnalysis:"analysis","ready",]- result.set_result(cell_analyses(document))+ result.set_result(cell_analyses(notebook.document))await asyncio.sleep(0)@pytest.mark.parametrize("edit_while_running", [False, True])@@ -631,7 +732,7 @@ class TestAnalysis:) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()- document = Document(NOTEBOOK, fixture_cells(), {})+ document = Document(fixture_cells(), {})notebook = await add_notebook(host,record(),@@ -641,18 +742,18 @@ class TestAnalysis:)_, result = await analyzer.next_request()if edit_while_running:- notebook.replace([CellSource("c1", "1")], {})+ notebook.replace([cell("c1", "1")], {})log.clear()result.set_exception(RuntimeError("compiler failed"))await asyncio.sleep(0)assert names(log) == []assert notebook.analysis is Noneif not edit_while_running:- notebook.replace([CellSource("c1", "1")], {})- snapshot, result = await analyzer.next_request()- assert snapshot == document.snapshot()+ notebook.replace([cell("c1", "1")], {})+ analyzed, result = await analyzer.next_request()+ assert analyzed is notebook.documentlog.clear()- result.set_result(cell_analyses(document))+ result.set_result(cell_analyses(analyzed))await asyncio.sleep(0)assert names(log) == ["analysis"]@@ -661,10 +762,10 @@ class TestAnalysis:) -> None:started, cancelled = asyncio.Event(), asyncio.Event()result = asyncio.get_running_loop().create_future()- document = Document(NOTEBOOK, fixture_cells(), {})+ document = Document(fixture_cells(), {})class Analyzer:- async def analyze(self, _snapshot):+ async def analyze(self, _document):started.set()try:return await asyncio.shield(result)@@ -676,10 +777,12 @@ class TestAnalysis:host.add_notebook(record(),lambda _, sink: Notebook(+ NOTEBOOK,document,Executions(),ScriptedBackend(),sink,+ saved_etag=document.etag,analyzer=Analyzer(),),)@@ -692,17 +795,3 @@ class TestAnalysis: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/_server/host/test_host_analysis.py b/tests/_server/host/test_host_analysis.pyindex 3651ccdee9..e5e502f967 100644--- a/tests/_server/host/test_host_analysis.py+++ b/tests/_server/host/test_host_analysis.py@@ -12,17 +12,16 @@ import pytestfrom marimo._ast.cell import CellImplfrom marimo._ast.compiler import compile_cellfrom marimo._core import protocol-from marimo._core.document import CellSource, Document, DocumentSnapshot+from marimo._core.document import Document, DocumentCellfrom marimo._server.host.analysis import CellAnalyzer, HostAnalyzerfrom marimo._types.ids import CellId_t-def snapshot(codes: dict[str, str]) -> DocumentSnapshot:+def snapshot(codes: dict[str, str]) -> Document:return Document(- protocol.NotebookId("n1"),- [CellSource(cid, code) for cid, code in codes.items()],+ [DocumentCell(cid, code) for cid, code in codes.items()],{},- ).snapshot()+ )def analyze(@@ -161,38 +160,41 @@ def test_compilation_cache_uses_identity_and_code_hash(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 (:"),+ DocumentCell("a", "x = 1"),+ DocumentCell("b", "y = x"),+ DocumentCell("bad", "def (:"),],{},)- analyzer(document.snapshot())+ analyzer(document)assert compiler.call_count == 3# Names, configuration, and order are visible without recompiling code.- document.replace(+ document, _ = document.replace([- CellSource("b", "y = x", name="renamed"),- CellSource("a", "x = 1"),- CellSource("bad", "def (:"),+ DocumentCell("b", "y = x", name="renamed"),+ DocumentCell("a", "x = 1"),+ DocumentCell("bad", "def (:"),],{"width": "full"},)- analyzer(document.snapshot())+ analyzer(document)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 == ()+ document, _ = document.replace(+ [DocumentCell("a", "z = 1"), DocumentCell("b", "y = x")], {}+ )+ assert analyzer(document)[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())+ document, _ = document.replace([DocumentCell("b", "y = x")], {})+ analyzer(document)+ document, _ = document.replace(+ [DocumentCell("a", "z = 1"), DocumentCell("c", "y = x")], {}+ )+ analyzer(document)assert compiler.call_count == 6diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 72edbdc281..0a069e1f06 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -1749,8 +1749,9 @@ async def test_save_writes_the_file_and_reports_the_saved_revision(async def test_edits_during_a_save_remain_unsaved(harness: Harness, monkeypatch: pytest.MonkeyPatch) -> None:- document = (await harness.host.notebook(harness.notebook_id)).document- written = document._record.etag+ notebook = await harness.host.notebook(harness.notebook_id)+ document = notebook.document+ written = document.etagstarted = asyncio.Event()release = threading.Event()loop = asyncio.get_running_loop()diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.pyindex 84eafe940b..ab8868743e 100644--- a/tests/_server/host/test_host_bridge.py+++ b/tests/_server/host/test_host_bridge.py@@ -28,7 +28,7 @@ if TYPE_CHECKING:from pathlib import Pathfrom typing import Any- from marimo._core.document import CellSource+ from marimo._core.document import DocumentCellfrom marimo._session.consumer import SessionConsumer@@ -80,15 +80,16 @@ async def test_an_adopted_document_is_saved_as_far_as_the_file_goes(for name in ("saved.py", "edited.py"):record = bridge.index.notebook_for(str(tmp_path / name))assert record is not None- document = (await bridge.host.notebook(record.id)).document- assert document is not None- documents[name] = document._record+ notebook = await bridge.host.notebook(record.id)+ documents[name] = (notebook.saved_etag, notebook.document.etag)# A session showing the file as it is on disk is saved.- assert documents["saved.py"].saved_etag == documents["saved.py"].etag+ saved, current = documents["saved.py"]+ assert saved == current# One with an edit the file lacks is not, and names the file's revision.- assert documents["edited.py"].saved_etag != documents["edited.py"].etag- assert documents["edited.py"].saved_etag == documents["saved.py"].etag+ saved, current = documents["edited.py"]+ assert saved != current+ assert saved == documents["saved.py"][1]bridge.close()@@ -143,7 +144,7 @@ async def test_delete_during_adoption_preserves_the_file_and_session(async def paused_load(file: Path,- ) -> tuple[list[CellSource], dict[str, Any]] | None:+ ) -> tuple[list[DocumentCell], dict[str, Any]] | None:started.set()await release.wait()return await load(file)@@ -402,8 +403,9 @@ async def test_editor_transactions_reach_the_host_document(bridge.host.subscribe(events.append, notebook_id=record.id)# The document comes from the session, ids included.- document = (await bridge.host.notebook(record.id)).document- assert document.order == ["Hbol"]+ notebook = await bridge.host.notebook(record.id)+ document = notebook.document+ assert [c.id for c in document] == ["Hbol"]# A frontend edit reaches the host document, and the app config as# the session reports it comes along.@@ -419,10 +421,10 @@ async def test_editor_transactions_reach_the_host_document(NotebookDocumentTransactionNotification(transaction=applied))- cell = document.cell("Hbol")+ cell = notebook.document.cell("Hbol")assert cell is not Noneassert cell.code == "x = 2"- assert document._record.app_config == {"width": "full"}+ assert notebook.document.app_config == {"width": "full"}assert names(events)[-2:] == ["cell", "document"]bridge.close()@@ -447,7 +449,8 @@ async def test_host_edits_reach_the_session_as_one_transaction(await bridge.open()record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.documentevents: list[Event] = []bridge.host.subscribe(events.append, notebook_id=record.id)@@ -471,7 +474,7 @@ async def test_host_edits_reach_the_session_as_one_transaction(assert notification.transaction.source == "host"# The backend saw its own edit come back and mirrored nothing new.assert names(events) == ["cell", "document"]- assert document._record.etag == response.document.etag+ assert notebook.document.etag == response.document.etagassert "y = x" not in (tmp_path / "a.py").read_text()bridge.close()@@ -510,9 +513,8 @@ async def test_edit_response_includes_app_config_mirrored_from_the_session(request_id="edit-1",)- current = notebook.document.snapshot().document- assert current.app_config == {"width": "full"}- assert response.document == current+ assert response.document.app_config == {"width": "full"}+ assert response.document.etag == notebook.document.etagfinally:bridge.close()@@ -529,7 +531,8 @@ async def test_a_new_session_replaces_a_read_without_host_edits(await bridge.open()record = bridge.index.notebook_for(str(path))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.documentevents: list[Event] = []bridge.host.subscribe(events.append, notebook_id=record.id)@@ -539,8 +542,8 @@ async def test_a_new_session_replaces_a_read_without_host_edits(session.document = AppFileManager(str(path)).app.cell_manager.documentawait manager.event_bus.emit_session_created(session) # type: ignore[arg-type]- assert [cell.code for cell in document] == ["x = 2"]- assert document._record.saved_etag == document._record.etag+ assert [cell.code for cell in notebook.document] == ["x = 2"]+ assert notebook.saved_etag == notebook.document.etagassert names(events)[-3:] == ["cell", "document", "runtime"]assert session.notifications == []bridge.close()@@ -563,7 +566,8 @@ async def test_a_new_session_adopts_unsaved_host_edits(await bridge.open()record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.documentsession = FakeSession(str(tmp_path / "a.py"))session.document = NotebookDocument(editor_cell(c) for c in document)await bridge.edit(@@ -582,9 +586,9 @@ async def test_a_new_session_adopts_unsaved_host_edits(await manager.event_bus.emit_session_created(session) # type: ignore[arg-type]assert [(c.id, c.code) for c in session.document.cells] == [- (c.id, c.code) for c in document+ (c.id, c.code) for c in notebook.document]- assert document._record.saved_etag != document._record.etag+ assert notebook.saved_etag != notebook.document.etagassert "unsaved" not in (tmp_path / "a.py").read_text()bridge.close()@@ -689,7 +693,8 @@ async def test_save_writes_the_cells_and_keeps_the_app_config(await bridge.open()record = bridge.index.notebook_for(str(path))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.document(cell,) = documentevents: list[Event] = []bridge.host.subscribe(events.append, notebook_id=record.id)@@ -734,9 +739,10 @@ async def test_saving_keeps_an_edit_made_while_the_file_is_written(await bridge.open()record = bridge.index.notebook_for(str(path))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.document(cell,) = document- written = document._record.etag+ written = notebook.document.etagstarted = asyncio.Event()release = threading.Event()@@ -764,7 +770,7 @@ async def test_saving_keeps_an_edit_made_while_the_file_is_written(# The file has the snapshot; the host keeps the edit, unsaved.assert saved.document.etag == edited.document.etagassert saved.document.saved_etag == written- assert document._record.saved_etag != document._record.etag+ assert notebook.saved_etag != notebook.document.etagassert "x = 1" in path.read_text()assert "x = 2" not in path.read_text()bridge.close()@@ -786,7 +792,8 @@ async def test_save_with_a_session_writes_through_the_editors_file_manager(await bridge.open()record = bridge.index.notebook_for(str(path))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.document(cell,) = document# The editor wrote once, so its manager remembers what is on disk.session.app_file_manager.save_from_cells(list(session.document.cells))@@ -820,7 +827,7 @@ async def test_the_editor_saving_marks_the_host_document_saved(manager: FakeManager, tmp_path: Path) -> None:from marimo._ast.cell import CellConfig- from marimo._core.document import revision+ from marimo._core.document import Documentfrom marimo._messaging.notebook import NotebookCellfrom marimo._server.host.document import from_file_managerfrom marimo._session.notebook import AppFileManager@@ -833,23 +840,24 @@ async def test_the_editor_saving_marks_the_host_document_saved(await bridge.open()record = bridge.index.notebook_for(str(path))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.documentsession = FakeSession(str(path))session.app_file_manager = AppFileManager(str(path))session.document = session.app_file_manager.app.cell_manager.documentmanager.sessions["browser-1"] = sessionawait manager.event_bus.emit_session_created(session) # type: ignore[arg-type](cell,) = session.document.cells- before = document._record.etag+ before = notebook.document.etag# The editor writes new content the host has not mirrored yet.session.app_file_manager.save_from_cells([NotebookCell(CellId_t(cell.id), "x = 2", cell.name, CellConfig())])- written = revision(*from_file_manager(session.app_file_manager))- assert document._record.saved_etag == written- assert document._record.etag == before != written+ written = Document(*from_file_manager(session.app_file_manager)).etag+ assert notebook.saved_etag == written+ assert notebook.document.etag == before != written# Once the session goes away, its writes are no longer the host's,# and the file as the editor left it is what the host compares to.@@ -879,7 +887,7 @@ async def test_save_refuses_to_overwrite_when_the_file_cannot_be_read(record = bridge.index.notebook_for(str(path))assert record is not Nonenotebook = await bridge.host.notebook(record.id)- before = notebook.document.snapshot()+ before = notebook.documentexternal = NOTEBOOK.replace("x = 1", "x = 2")path.write_text(external)@@ -891,7 +899,7 @@ async def test_save_refuses_to_overwrite_when_the_file_cannot_be_read(with pytest.raises(Conflict, match="could not be read"):await bridge.save(record.id, if_match=None, request_id="save-1")assert path.read_text() == external- assert notebook.document.snapshot() == before+ assert notebook.document == beforefinally:bridge.close()@@ -938,7 +946,8 @@ async def test_reloading_refuses_to_drop_an_edit_made_while_reading(await bridge.open()record = bridge.index.notebook_for(str(path))assert record is not None- document = (await bridge.host.notebook(record.id)).document+ notebook = await bridge.host.notebook(record.id)+ document = notebook.document(cell,) = documentpath.write_text(NOTEBOOK.replace("x = 1", "x = 2"))@@ -972,5 +981,5 @@ async def test_reloading_refuses_to_drop_an_edit_made_while_reading(with pytest.raises(EditConflict) as conflict:await asyncio.wait_for(reloading, 5)assert conflict.value.document == edited.document- assert document.cell(cell.id).code == "x = 3" # type: ignore[union-attr]+ assert notebook.document.cell(cell.id).code == "x = 3" # type: ignore[union-attr]bridge.close()diff --git a/tests/_server/host/test_host_document.py b/tests/_server/host/test_host_document.pyindex f744d575a0..93082aa28b 100644--- a/tests/_server/host/test_host_document.py+++ b/tests/_server/host/test_host_document.py@@ -7,7 +7,7 @@ import pytestfrom marimo._ast.cell import CellConfigfrom marimo._core import protocol-from marimo._core.document import CellSource, Document+from marimo._core.document import Document, DocumentCellfrom marimo._messaging.notebook import (NotebookCell,NotebookDocument,@@ -28,7 +28,7 @@ def test_deleting_all_cells_broadcasts_the_final_order() -> None:session.document = NotebookDocument([NotebookCell(CellId_t("a"), "x = 1", "_", CellConfig())])- document = Document(protocol.NotebookId("nb"), [], {})+ document = Document([], {})apply_to_session(session, document) # type: ignore[arg-type]@@ -46,9 +46,7 @@ async def test_enabling_an_edited_cell_does_not_run_old_code() -> None:session.document = NotebookDocument([NotebookCell(cell_id, old_code, "_", CellConfig(disabled=True))])- document = Document(- protocol.NotebookId("nb"), [CellSource(cell_id, new_code)], {}- )+ document = Document([DocumentCell(cell_id, new_code)], {})with mocked_kernel_session(configs={cell_id: CellConfig(disabled=True)}@@ -84,7 +82,7 @@ async def test_deleted_or_disabled_cells_do_not_run_during_an_edit([]if delete_dependentelse [- CellSource(+ DocumentCell(second,code,config=protocol.CellConfig(@@ -96,7 +94,7 @@ async def test_deleted_or_disabled_cells_do_not_run_during_an_edit()])- document = Document(protocol.NotebookId("nb"), cells, {})+ document = Document(cells, {})with mocked_kernel_session() as runtime:await runtime.kernel.run(