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
fix(document): reconcile inbound transactions so stale cell refs don't 500 (#10096)
Kiran Gadhave9df73e943f4a
diff --git a/marimo/_messaging/notebook/reconcile.py b/marimo/_messaging/notebook/reconcile.pynew file mode 100644index 0000000000..46df0494a3--- /dev/null+++ b/marimo/_messaging/notebook/reconcile.py@@ -0,0 +1,127 @@+# Copyright 2026 Marimo. All rights reserved.++from __future__ import annotations++from typing import TYPE_CHECKING++from msgspec.structs import replace as structs_replace++from marimo import _loggers+from marimo._messaging.notebook.changes import (+ CreateCell,+ DeleteCell,+ MoveCell,+ ReorderCells,+ SetCode,+ SetConfig,+ SetName,+)+from marimo._utils.assert_never import assert_never++LOGGER = _loggers.marimo_logger()++if TYPE_CHECKING:+ from marimo._messaging.notebook.changes import DocumentChange+ from marimo._messaging.notebook.document import NotebookDocument+ from marimo._types.ids import CellId_t+++def reconcile_transaction(+ changes: tuple[DocumentChange, ...],+ document: NotebookDocument,+) -> tuple[DocumentChange, ...]:+ """Rewrite `changes` so they apply cleanly to `document`.++ Resolves references in batch order against a shadow id-set seeded from+ the document and mutated per change, so a cell created earlier in the+ same batch satisfies a later anchor. A create with an unresolvable anchor+ is appended (its anchor stripped); a create whose id is already taken is+ dropped. Property updates targeting a missing cell, and moves that target+ a missing cell or lack a single resolvable anchor, are dropped.+ """+ # current cells in the document model+ live: set[CellId_t] = set(document.cell_ids)+ # ids a create can't reuse; grows but never shrinks, mirroring+ # `_validate` which never frees an id within a transaction+ claimed: set[CellId_t] = set(document.cell_ids)+ out: list[DocumentChange] = []++ # an anchor resolves when it is a live cell, or None (meaning no anchor)+ def resolve_anchor(anchor: CellId_t | None) -> bool:+ return anchor is None or anchor in live++ for change in changes:+ if isinstance(change, CreateCell):+ if change.cell_id in claimed:+ LOGGER.debug(+ "CreateCell: cannot create %s, id already exists",+ change.cell_id,+ )+ continue+ # if no anchor cell exists, just append the new cell+ if not resolve_anchor(change.after) or not resolve_anchor(+ change.before+ ):+ LOGGER.debug(+ "CreateCell: remove unresolvable anchor from create %s",+ change.cell_id,+ )+ change = structs_replace(change, after=None, before=None)+ live.add(change.cell_id)+ claimed.add(change.cell_id)+ out.append(change)+ elif isinstance(change, DeleteCell):+ if change.cell_id not in live:+ LOGGER.debug(+ "DeleteCell: missing cell %s",+ change.cell_id,+ )+ continue+ # track removal+ live.discard(change.cell_id)+ out.append(change)+ elif isinstance(change, MoveCell):+ if change.cell_id not in live:+ LOGGER.debug(+ "MoveCell: cannot move missing cell %s",+ change.cell_id,+ )+ continue+ # no anchor, or a self-anchor, has no valid destination+ if change.after is None and change.before is None:+ LOGGER.debug(+ "MoveCell: cannot move cell %s with no anchor",+ change.cell_id,+ )+ continue+ if change.cell_id in (change.after, change.before):+ LOGGER.debug(+ "MoveCell: cannot move cell %s that is anchored to itself",+ change.cell_id,+ )+ continue+ if not resolve_anchor(change.after) or not resolve_anchor(+ change.before+ ):+ LOGGER.debug(+ "MoveCell: unresolvable anchor for %s",+ change.cell_id,+ )+ continue+ out.append(change)+ elif isinstance(change, (SetCode, SetName, SetConfig)):+ if change.cell_id not in live:+ LOGGER.debug(+ "%s: cannot update missing cell %s",+ type(change).__name__,+ change.cell_id,+ )+ continue+ out.append(change)+ elif isinstance(change, ReorderCells):+ # already handles unknown/missing ids+ out.append(change)+ else:+ assert_never(change)++ return tuple(out)diff --git a/marimo/_server/api/endpoints/document.py b/marimo/_server/api/endpoints/document.pyindex 69f36307ac..2987dde7d7 100644--- a/marimo/_server/api/endpoints/document.py+++ b/marimo/_server/api/endpoints/document.py@@ -6,6 +6,7 @@ from typing import TYPE_CHECKINGfrom starlette.authentication import requiresfrom marimo._messaging.notebook.changes import Transaction+from marimo._messaging.notebook.reconcile import reconcile_transactionfrom marimo._messaging.notification import (NotebookDocumentTransactionNotification,)@@ -53,7 +54,8 @@ async def document_transaction(request: Request) -> BaseResponse:session = app_state.require_current_session()session_id = app_state.require_current_session_id()- transaction = Transaction(changes=tuple(body.changes), source="frontend")+ sanitized = reconcile_transaction(tuple(body.changes), session.document)+ transaction = Transaction(changes=sanitized, source="frontend")applied = session.document.apply(transaction)session.notify(NotebookDocumentTransactionNotification(transaction=applied),diff --git a/tests/_messaging/notebook/test_reconcile.py b/tests/_messaging/notebook/test_reconcile.pynew file mode 100644index 0000000000..e974b41188--- /dev/null+++ b/tests/_messaging/notebook/test_reconcile.py@@ -0,0 +1,211 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from marimo._ast.cell import CellConfig+from marimo._messaging.notebook.changes import (+ CreateCell,+ DeleteCell,+ MoveCell,+ ReorderCells,+ SetCode,+ SetConfig,+ SetName,+)+from marimo._messaging.notebook.document import (+ NotebookCell,+ NotebookDocument,+)+from marimo._messaging.notebook.reconcile import reconcile_transaction+from marimo._types.ids import CellId_t+++def _doc(*ids: str) -> NotebookDocument:+ return NotebookDocument(+ [+ NotebookCell(CellId_t(i), code="", name="__", config=CellConfig())+ for i in ids+ ]+ )+++def _create(+ cell_id: str, *, before: str | None = None, after: str | None = None+) -> CreateCell:+ return CreateCell(+ cell_id=CellId_t(cell_id),+ code="",+ name="__",+ config=CellConfig(),+ before=CellId_t(before) if before is not None else None,+ after=CellId_t(after) if after is not None else None,+ )+++class TestCleanTransaction:+ def test_clean_batch_unchanged(self) -> None:+ doc = _doc("a", "b")+ changes = (+ SetCode(cell_id=CellId_t("a"), code="x = 1"),+ _create("c", after="b"),+ DeleteCell(cell_id=CellId_t("b")),+ )+ sanitized = reconcile_transaction(changes, doc)+ assert sanitized == changes+++class TestCreateAnchor:+ def test_missing_after_anchor_is_stripped_and_appended(self) -> None:+ doc = _doc("a")+ sanitized = reconcile_transaction(+ (_create("new", after="ghost"),), doc+ )++ (result,) = sanitized+ assert isinstance(result, CreateCell)+ assert result.cell_id == CellId_t("new")+ assert result.after is None+ assert result.before is None++ def test_missing_before_anchor_is_stripped_and_appended(self) -> None:+ doc = _doc("a")+ sanitized = reconcile_transaction(+ (_create("new", before="ghost"),), doc+ )++ (result,) = sanitized+ assert isinstance(result, CreateCell)+ assert result.before is None+ assert result.after is None++ def test_anchor_created_earlier_in_batch_is_kept(self) -> None:+ doc = _doc("a")+ changes = (+ _create("x", after="a"),+ _create("y", after="x"),+ )+ sanitized = reconcile_transaction(changes, doc)+ assert sanitized == changes+++class TestCreateDuplicate:+ def test_create_of_existing_id_is_dropped(self) -> None:+ doc = _doc("a", "b")+ sanitized = reconcile_transaction((_create("a", after="b"),), doc)+ assert sanitized == ()+++class TestDelete:+ def test_delete_of_missing_cell_is_dropped(self) -> None:+ doc = _doc("a")+ sanitized = reconcile_transaction(+ (DeleteCell(cell_id=CellId_t("ghost")),), doc+ )+ assert sanitized == ()++ def test_recreate_of_deleted_existing_id_is_dropped(self) -> None:+ doc = _doc("a")+ delete = DeleteCell(cell_id=CellId_t("a"))+ sanitized = reconcile_transaction((delete, _create("a")), doc)+ assert sanitized == (delete,)++ def test_recreate_of_batch_created_id_is_dropped(self) -> None:+ doc = _doc("a")+ create = _create("x", after="a")+ delete = DeleteCell(cell_id=CellId_t("x"))+ sanitized = reconcile_transaction((create, delete, _create("x")), doc)+ assert sanitized == (create, delete)+++class TestSetProperties:+ def test_set_code_of_missing_cell_is_dropped(self) -> None:+ doc = _doc("a")+ sanitized = reconcile_transaction(+ (SetCode(cell_id=CellId_t("ghost"), code="x = 1"),), doc+ )+ assert sanitized == ()++ def test_set_name_of_missing_cell_is_dropped(self) -> None:+ doc = _doc("a")+ sanitized = reconcile_transaction(+ (SetName(cell_id=CellId_t("ghost"), name="renamed"),), doc+ )+ assert sanitized == ()++ def test_set_config_of_missing_cell_is_dropped(self) -> None:+ doc = _doc("a")+ sanitized = reconcile_transaction(+ (+ SetConfig(+ cell_id=CellId_t("ghost"),+ column=None,+ disabled=False,+ hide_code=False,+ ),+ ),+ doc,+ )+ assert sanitized == ()++ def test_set_code_of_present_cell_is_kept(self) -> None:+ doc = _doc("a")+ change = SetCode(cell_id=CellId_t("a"), code="x = 1")+ sanitized = reconcile_transaction((change,), doc)+ assert sanitized == (change,)+++class TestMove:+ def test_move_of_missing_cell_is_dropped(self) -> None:+ doc = _doc("a", "b")+ sanitized = reconcile_transaction(+ (MoveCell(cell_id=CellId_t("ghost"), after=CellId_t("a")),), doc+ )+ assert sanitized == ()++ def test_move_with_missing_anchor_is_dropped(self) -> None:+ doc = _doc("a", "b")+ sanitized = reconcile_transaction(+ (MoveCell(cell_id=CellId_t("a"), after=CellId_t("ghost")),), doc+ )+ assert sanitized == ()++ def test_move_with_live_anchor_is_kept(self) -> None:+ doc = _doc("a", "b")+ change = MoveCell(cell_id=CellId_t("a"), after=CellId_t("b"))+ sanitized = reconcile_transaction((change,), doc)+ assert sanitized == (change,)++ def test_move_with_no_anchor_is_dropped(self) -> None:+ doc = _doc("a", "b")+ sanitized = reconcile_transaction(+ (MoveCell(cell_id=CellId_t("a"), after=None, before=None),), doc+ )+ assert sanitized == ()++ def test_move_anchored_to_itself_is_dropped(self) -> None:+ doc = _doc("a", "b")+ sanitized = reconcile_transaction(+ (MoveCell(cell_id=CellId_t("a"), after=CellId_t("a")),), doc+ )+ assert sanitized == ()+++class TestReorder:+ def test_reorder_passes_through_untouched(self) -> None:+ doc = _doc("a", "b")+ change = ReorderCells(+ cell_ids=(CellId_t("b"), CellId_t("a"), CellId_t("ghost"))+ )+ sanitized = reconcile_transaction((change,), doc)+ assert sanitized == (change,)+++class TestOrderPreserved:+ def test_surviving_changes_keep_input_order(self) -> None:+ doc = _doc("a", "b")+ changes = (+ SetCode(cell_id=CellId_t("a"), code="1"),+ DeleteCell(cell_id=CellId_t("ghost")),+ SetCode(cell_id=CellId_t("b"), code="2"),+ )+ sanitized = reconcile_transaction(changes, doc)+ assert sanitized == (changes[0], changes[2])diff --git a/tests/_server/api/endpoints/test_document_endpoints.py b/tests/_server/api/endpoints/test_document_endpoints.pynew file mode 100644index 0000000000..4dc784d437--- /dev/null+++ b/tests/_server/api/endpoints/test_document_endpoints.py@@ -0,0 +1,75 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from typing import TYPE_CHECKING++from tests._server.api.endpoints.ws_helpers import (+ HEADERS as _HEADERS,+ assert_kernel_ready_response,+)++if TYPE_CHECKING:+ from starlette.testclient import TestClient++HEADERS = {+ **_HEADERS,+ "Marimo-Session-Id": "123",+}+++def test_create_cell_with_missing_anchor_is_appended(+ client: TestClient,+) -> None:+ with client.websocket_connect(+ "/ws?session_id=123", headers=_HEADERS+ ) as websocket:+ assert_kernel_ready_response(websocket.receive_json())++ response = client.post(+ "/api/document/transaction",+ headers=HEADERS,+ json={+ "changes": [+ {+ "type": "create-cell",+ "cellId": "new1",+ "code": "",+ "name": "_",+ "config": {+ "column": None,+ "disabled": False,+ "hideCode": False,+ },+ "after": "ghost_cell_xyz",+ }+ ],+ },+ )+ assert response.status_code == 200, response.text++ sm = client.app.state.session_manager+ session = next(iter(sm.sessions.values()))+ assert session.document.cell_ids[-1] == "new1"+++def test_delete_of_missing_cell_is_a_no_op(client: TestClient) -> None:+ with client.websocket_connect(+ "/ws?session_id=123", headers=_HEADERS+ ) as websocket:+ assert_kernel_ready_response(websocket.receive_json())++ sm = client.app.state.session_manager+ session = next(iter(sm.sessions.values()))+ cell_ids_before = session.document.cell_ids++ response = client.post(+ "/api/document/transaction",+ headers=HEADERS,+ json={+ "changes": [+ {"type": "delete-cell", "cellId": "ghost_cell_xyz"}+ ],+ },+ )+ assert response.status_code == 200, response.text+ assert session.document.cell_ids == cell_ids_before