Skip to content

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

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.py
new file mode 100644
index 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.py
index 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_CHECKING
from starlette.authentication import requires
from marimo._messaging.notebook.changes import Transaction
+from marimo._messaging.notebook.reconcile import reconcile_transaction
from 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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