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
Derive whether a result is current from the host stream (#11277)
Trevor Manza7cb6ba9e7d2
diff --git a/marimo/_core/executions.py b/marimo/_core/executions.pyindex cf3ca9d34f..0ff3803048 100644--- a/marimo/_core/executions.py+++ b/marimo/_core/executions.py@@ -54,7 +54,7 @@ class _Result:class Removed:"""A current record that a transition removed."""- kind: Literal["execution", "console", "display"]+ kind: Literal["execution", "console", "display", "variable"]id: strrun_id: protocol.RunId | None@@ -390,10 +390,9 @@ class Executions:else None,code=entry.code,code_hash=entry.code_hash,- bindings=(),+ depends_on={},status="queued",outcome=None,- stale=None,started_at=None,completed_at=None,)diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex b917016c5c..ee3378a6e9 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -27,28 +27,6 @@ else:)-class Binding(Struct, frozen=True):- name: str- preview: (- Annotated[- str,- Meta(- description="A short rendering of the value. A host may leave it null."- ),- ]- | None- )- type: (- Annotated[- str,- Meta(- description="The runtime's label for the value's type. A host may leave it null."- ),- ]- | None- )--class CellConfig(Struct, frozen=True):column: (Annotated[@@ -243,7 +221,7 @@ else:Annotated[str,Meta(- description="Identifies a console or display item. Unique within the host; sending an item again with the same id replaces it.",+ description="Identifies a console, display, or variable item. Unique within the host; sending an item again with the same id replaces it.",min_length=1,),],@@ -287,10 +265,11 @@ ObjectType: TypeAlias = Annotated["execution","console","display",+ "variable","custom",],Meta(- description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, document,\nanalysis, cell, runtime, attachment, run, execution, console,\ndisplay, and custom. Custom events describe occurrences rather\nthan object state.\n"+ description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, document,\nanalysis, cell, runtime, attachment, run, execution, console,\ndisplay, variable, and custom. Custom events describe occurrences\nrather than object state.\n"),]@@ -439,6 +418,22 @@ class RequestedCell(Struct, frozen=True):) = UNSET+class Revision(Struct, frozen=True):+ execution: Annotated[+ ExecutionId,+ Meta(+ description="The execution whose evaluation produced the value. Usually the variable's `execution_id`, and earlier when the runtime carried the value forward."+ ),+ ]+ update: Annotated[+ int,+ Meta(+ description="How many times the value has been updated since it was produced. Zero at binding.",+ ge=0,+ ),+ ]++if TYPE_CHECKING:RunId = NewType("RunId", str)else:@@ -581,6 +576,55 @@ class ValueOutcome(Struct, frozen=True, tag_field="kind", tag="value"):)+class Variable(Struct, frozen=True):+ execution_id: Annotated[+ ExecutionId, Meta(description="The execution that bound the name.")+ ]+ id: ItemId+ name: Annotated[str, Meta(description="The name in the namespace.")]+ preview: (+ Annotated[+ str,+ Meta(+ description="A short rendering of the value. A host may leave it null."+ ),+ ]+ | None+ )+ revision: Revision+ type: (+ Annotated[+ str,+ Meta(+ description="The runtime's label for the value's type. A host may leave it null."+ ),+ ]+ | None+ )+++class VariableMessage(Struct, frozen=True):+ variable: Variable+ request_id: (+ Annotated[+ str,+ Meta(+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."+ ),+ ]+ | UnsetType+ ) = UNSET+ time: (+ Annotated[+ datetime,+ Meta(+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."+ ),+ ]+ | UnsetType+ ) = UNSET++class Attachment(Struct, frozen=True):id: AttachmentIdkind: Annotated[@@ -857,7 +901,7 @@ class Document(Struct, frozen=True):policy: Annotated[Literal["autorun", "lazy"],Meta(- description="When dependents of an evaluated cell run. `autorun` runs them on every change; `lazy` marks them stale and runs them when asked. Set by the host."+ description="When dependents of an evaluated cell run. `autorun` runs them on every change; `lazy` leaves them for a later run. Set by the host."),]saved_etag: (@@ -1323,12 +1367,6 @@ class CellAnalysis(Struct, frozen=True):class Execution(Struct, frozen=True):- bindings: Annotated[- tuple[Binding, ...],- Meta(- description="Names bound in the namespace, with a type and preview, stamped when the execution ends. Empty while running and for scratch code, whose bindings die with the execution."- ),- ]caused_by: (Annotated[ExecutionId,@@ -1371,6 +1409,12 @@ class Execution(Struct, frozen=True):]| None)+ depends_on: Annotated[+ dict[str, Revision | None],+ Meta(+ description="The variables the execution used, by name, each at the revision the runtime holds its result valid against. Null for a name no retained cell execution had bound. Empty while queued, stamped as the execution ends, and final from then on."+ ),+ ]id: ExecutionIdoutcome: (Annotated[@@ -1399,15 +1443,6 @@ class Execution(Struct, frozen=True):]| None)- stale: (- Annotated[- bool,- Meta(- description="Whether an input changed since this result was produced. Null for scratch code, which has no inputs in the graph."- ),- ]- | None- )started_at: (Annotated[datetime,diff --git a/marimo/_core/stream.py b/marimo/_core/stream.pyindex aecf205c18..187dd51757 100644--- a/marimo/_core/stream.py+++ b/marimo/_core/stream.py@@ -37,6 +37,7 @@ Body: TypeAlias = (| protocol.Execution| protocol.Console| protocol.Display+ | protocol.Variable| protocol.Custom)"""Every object a stream carries. The wrapper map and the notebook kinds@@ -56,6 +57,7 @@ Kind: TypeAlias = Literal["execution","console","display",+ "variable","custom",]"""The kinds of object a stream carries, one per `Body` type."""diff --git a/protocols/host/conformance/contract.py b/protocols/host/conformance/contract.pyindex 0ec407f3e5..8a3e5781b8 100644--- a/protocols/host/conformance/contract.py+++ b/protocols/host/conformance/contract.py@@ -35,6 +35,7 @@ KINDS = ("execution","console","display",+ "variable",)diff --git a/protocols/host/fixtures/README.md b/protocols/host/fixtures/README.mdindex 3127167794..4d86e6b4af 100644--- a/protocols/host/fixtures/README.md+++ b/protocols/host/fixtures/README.md@@ -13,8 +13,10 @@ and `analysis.json` is the analysis of that document.`run-cells-request.json` requests `c3`, which defines `x`. In `run-cells.sse`,the runtime then evaluates `k7f2`, which defines `y` using `x`. The dependent-execution identifies the first execution as its cause. Both cells end with-bindings and no displayed value because their code consists of assignments.+execution identifies the first execution as its cause and depends on the+revision of `x` it used. Each cell publishes+the variable it bound before it completes, and neither displays a value,+because their code consists of assignments.`edit.json` edits that document. `edit-response.json` contains the acceptedstate, and `edits.sse` shows the cell and document events followed by a save.diff --git a/protocols/host/fixtures/execution-restored.json b/protocols/host/fixtures/execution-restored.jsonindex a6d473795f..1bbaddad42 100644--- a/protocols/host/fixtures/execution-restored.json+++ b/protocols/host/fixtures/execution-restored.json@@ -6,19 +6,12 @@"cell_id": "c3","code": null,"code_hash": "0f71456db2ea83f4",- "bindings": [- {- "name": "x",- "type": "int",- "preview": "21"- }- ],+ "depends_on": {},"status": "completed","outcome": {"kind": "value","display": null},- "stale": false,"started_at": "2026-09-30T09:20:01Z","completed_at": "2026-09-30T09:20:02Z"}diff --git a/protocols/host/fixtures/notebook-events.sse b/protocols/host/fixtures/notebook-events.sseindex 190a7afcbb..a1a72aa39a 100644--- a/protocols/host/fixtures/notebook-events.sse+++ b/protocols/host/fixtures/notebook-events.sse@@ -26,7 +26,7 @@ event: rundata: {"run":{"id":"run-scratch","notebook_id":"n1","status":"running","started_at":"2026-10-01T09:20:01Z","completed_at":null,"caused_by":null,"outcome":null},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b"}event: execution-data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","status":"running","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span>"}},"stale":null,"started_at":"2026-10-01T09:20:01Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3","bindings":[]},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b"}+data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","depends_on":{},"status":"running","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span>"}},"started_at":"2026-10-01T09:20:01Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3"},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b"}event: consoledata: {"console":{"id":"o3","execution_id":"e7","seq":0,"name":"stdout","text":"2\n"},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b"}@@ -42,7 +42,7 @@ data: {}id: 96event: execution-data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","status":"completed","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span><pre>9</pre>"}},"stale":null,"started_at":"2026-10-01T09:20:01Z","completed_at":"2026-10-01T09:20:04Z","runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3","bindings":[]},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:04Z"}+data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","depends_on":{},"status":"completed","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span><pre>9</pre>"}},"started_at":"2026-10-01T09:20:01Z","completed_at":"2026-10-01T09:20:04Z","runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3"},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:04Z"}id: 97event: rundiff --git a/protocols/host/fixtures/run-cells.sse b/protocols/host/fixtures/run-cells.sseindex 30495ce40d..ed588c2246 100644--- a/protocols/host/fixtures/run-cells.sse+++ b/protocols/host/fixtures/run-cells.sse@@ -4,11 +4,11 @@ data: {"run":{"id":"run-cells","notebook_id":"n1","status":"queued","started_at"id: 101event: execution-data: {"execution":{"id":"e12","run_id":"run-cells","cell_id":"c3","code_hash":"0f71456db2ea83f4","status":"queued","outcome":null,"stale":null,"started_at":null,"completed_at":null,"runtime_id":"r1","caused_by":null,"code":null,"bindings":[]},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:10Z"}+data: {"execution":{"id":"e12","run_id":"run-cells","cell_id":"c3","code_hash":"0f71456db2ea83f4","depends_on":{},"status":"queued","outcome":null,"started_at":null,"completed_at":null,"runtime_id":"r1","caused_by":null,"code":null},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:10Z"}id: 102event: execution-data: {"execution":{"id":"e13","run_id":"run-cells","cell_id":"k7f2","code_hash":"db2b9ee97e1ecf4c","status":"queued","outcome":null,"stale":null,"started_at":null,"completed_at":null,"runtime_id":"r1","caused_by":"e12","code":null,"bindings":[]},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:10Z"}+data: {"execution":{"id":"e13","run_id":"run-cells","cell_id":"k7f2","code_hash":"db2b9ee97e1ecf4c","depends_on":{},"status":"queued","outcome":null,"started_at":null,"completed_at":null,"runtime_id":"r1","caused_by":"e12","code":null},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:10Z"}id: 103event: run@@ -16,21 +16,29 @@ data: {"run":{"id":"run-cells","notebook_id":"n1","status":"running","started_atid: 104event: execution-data: {"execution":{"id":"e12","run_id":"run-cells","cell_id":"c3","code_hash":"0f71456db2ea83f4","status":"running","outcome":null,"stale":null,"started_at":"2026-10-01T09:20:11Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":null,"bindings":[]},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:11Z"}+data: {"execution":{"id":"e12","run_id":"run-cells","cell_id":"c3","code_hash":"0f71456db2ea83f4","depends_on":{},"status":"running","outcome":null,"started_at":"2026-10-01T09:20:11Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":null},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:11Z"}id: 105-event: execution-data: {"execution":{"id":"e12","run_id":"run-cells","cell_id":"c3","code_hash":"0f71456db2ea83f4","status":"completed","outcome":{"kind":"value","display":null},"stale":false,"started_at":"2026-10-01T09:20:11Z","completed_at":"2026-10-01T09:20:11Z","runtime_id":"r1","caused_by":null,"code":null,"bindings":[{"name":"x","type":"int","preview":"21"}]},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:11Z"}+event: variable+data: {"variable":{"id":"e12-x","execution_id":"e12","name":"x","revision":{"execution":"e12","update":0},"type":"int","preview":"21"},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:11Z"}id: 106event: execution-data: {"execution":{"id":"e13","run_id":"run-cells","cell_id":"k7f2","code_hash":"db2b9ee97e1ecf4c","status":"running","outcome":null,"stale":null,"started_at":"2026-10-01T09:20:11Z","completed_at":null,"runtime_id":"r1","caused_by":"e12","code":null,"bindings":[]},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:11Z"}+data: {"execution":{"id":"e12","run_id":"run-cells","cell_id":"c3","code_hash":"0f71456db2ea83f4","depends_on":{},"status":"completed","outcome":{"kind":"value","display":null},"started_at":"2026-10-01T09:20:11Z","completed_at":"2026-10-01T09:20:11Z","runtime_id":"r1","caused_by":null,"code":null},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:11Z"}id: 107event: execution-data: {"execution":{"id":"e13","run_id":"run-cells","cell_id":"k7f2","code_hash":"db2b9ee97e1ecf4c","status":"completed","outcome":{"kind":"value","display":null},"stale":false,"started_at":"2026-10-01T09:20:11Z","completed_at":"2026-10-01T09:20:12Z","runtime_id":"r1","caused_by":"e12","code":null,"bindings":[{"name":"y","type":"int","preview":"42"}]},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:12Z"}+data: {"execution":{"id":"e13","run_id":"run-cells","cell_id":"k7f2","code_hash":"db2b9ee97e1ecf4c","depends_on":{"x":{"execution":"e12","update":0}},"status":"running","outcome":null,"started_at":"2026-10-01T09:20:11Z","completed_at":null,"runtime_id":"r1","caused_by":"e12","code":null},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:11Z"}id: 108+event: variable+data: {"variable":{"id":"e13-y","execution_id":"e13","name":"y","revision":{"execution":"e13","update":0},"type":"int","preview":"42"},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:12Z"}++id: 109+event: execution+data: {"execution":{"id":"e13","run_id":"run-cells","cell_id":"k7f2","code_hash":"db2b9ee97e1ecf4c","depends_on":{"x":{"execution":"e12","update":0}},"status":"completed","outcome":{"kind":"value","display":null},"started_at":"2026-10-01T09:20:11Z","completed_at":"2026-10-01T09:20:12Z","runtime_id":"r1","caused_by":"e12","code":null},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:12Z"}++id: 110event: rundata: {"run":{"id":"run-cells","notebook_id":"n1","status":"completed","started_at":"2026-10-01T09:20:11Z","completed_at":"2026-10-01T09:20:12Z","caused_by":null,"outcome":"succeeded"},"request_id":"2b7d4e9c-1a3f-4c5d-8e6f-7a8b9c0d1e2f","time":"2026-10-01T09:20:12Z"}diff --git a/protocols/host/fixtures/run-failed.sse b/protocols/host/fixtures/run-failed.sseindex 0c9bed4aca..ce5b5a8756 100644--- a/protocols/host/fixtures/run-failed.sse+++ b/protocols/host/fixtures/run-failed.sse@@ -4,7 +4,7 @@ data: {"run":{"id":"run-failed","notebook_id":"n1","status":"running","started_aid: 121event: execution-data: {"execution":{"id":"e8","run_id":"run-failed","cell_id":null,"code_hash":"a32ab03f8d972266","status":"running","outcome":null,"stale":null,"started_at":"2026-10-01T09:21:10Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import sys\nprint(\"dividing\", file=sys.stderr)\n1 / 0","bindings":[]},"request_id":"0f4b2c1d-8e7a-4b6c-a5d4-1e2f3a4b5c6d","time":"2026-10-01T09:21:10Z"}+data: {"execution":{"id":"e8","run_id":"run-failed","cell_id":null,"code_hash":"a32ab03f8d972266","depends_on":{},"status":"running","outcome":null,"started_at":"2026-10-01T09:21:10Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import sys\nprint(\"dividing\", file=sys.stderr)\n1 / 0"},"request_id":"0f4b2c1d-8e7a-4b6c-a5d4-1e2f3a4b5c6d","time":"2026-10-01T09:21:10Z"}id: 122event: console@@ -12,7 +12,7 @@ data: {"console":{"id":"o4","execution_id":"e8","seq":0,"name":"stderr","text":"id: 123event: execution-data: {"execution":{"id":"e8","run_id":"run-failed","cell_id":null,"code_hash":"a32ab03f8d972266","status":"completed","outcome":{"kind":"error","error":{"kind":"exception","message":"division by zero","name":"ZeroDivisionError","traceback":{"mimetype":"text/plain","data":"Traceback (most recent call last):\n File \"<scratch>\", line 3, in <module>\nZeroDivisionError: division by zero\n"},"source":"marimo","severity":"error","range":null,"related":[]}},"stale":null,"started_at":"2026-10-01T09:21:10Z","completed_at":"2026-10-01T09:21:11Z","runtime_id":"r1","caused_by":null,"code":"import sys\nprint(\"dividing\", file=sys.stderr)\n1 / 0","bindings":[]},"request_id":"0f4b2c1d-8e7a-4b6c-a5d4-1e2f3a4b5c6d","time":"2026-10-01T09:21:11Z"}+data: {"execution":{"id":"e8","run_id":"run-failed","cell_id":null,"code_hash":"a32ab03f8d972266","depends_on":{},"status":"completed","outcome":{"kind":"error","error":{"kind":"exception","message":"division by zero","name":"ZeroDivisionError","traceback":{"mimetype":"text/plain","data":"Traceback (most recent call last):\n File \"<scratch>\", line 3, in <module>\nZeroDivisionError: division by zero\n"},"source":"marimo","severity":"error","range":null,"related":[]}},"started_at":"2026-10-01T09:21:10Z","completed_at":"2026-10-01T09:21:11Z","runtime_id":"r1","caused_by":null,"code":"import sys\nprint(\"dividing\", file=sys.stderr)\n1 / 0"},"request_id":"0f4b2c1d-8e7a-4b6c-a5d4-1e2f3a4b5c6d","time":"2026-10-01T09:21:11Z"}id: 124event: rundiff --git a/protocols/host/fixtures/run-interrupted.sse b/protocols/host/fixtures/run-interrupted.sseindex 718b00adcd..4c07091a54 100644--- a/protocols/host/fixtures/run-interrupted.sse+++ b/protocols/host/fixtures/run-interrupted.sse@@ -4,7 +4,7 @@ data: {"run":{"id":"run-interrupted","notebook_id":"n1","status":"running","starid: 131event: execution-data: {"execution":{"id":"e9","run_id":"run-interrupted","cell_id":null,"code_hash":"6579899a00aac8fe","status":"running","outcome":null,"stale":null,"started_at":"2026-10-01T09:22:00Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import itertools, time\nfor i in itertools.count():\n print(i)\n time.sleep(1)","bindings":[]},"request_id":"9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","time":"2026-10-01T09:22:00Z"}+data: {"execution":{"id":"e9","run_id":"run-interrupted","cell_id":null,"code_hash":"6579899a00aac8fe","depends_on":{},"status":"running","outcome":null,"started_at":"2026-10-01T09:22:00Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import itertools, time\nfor i in itertools.count():\n print(i)\n time.sleep(1)"},"request_id":"9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","time":"2026-10-01T09:22:00Z"}id: 132event: console@@ -12,7 +12,7 @@ data: {"console":{"id":"o5","execution_id":"e9","seq":0,"name":"stdout","text":"id: 133event: execution-data: {"execution":{"id":"e9","run_id":"run-interrupted","cell_id":null,"code_hash":"6579899a00aac8fe","status":"completed","outcome":{"kind":"interrupted"},"stale":null,"started_at":"2026-10-01T09:22:00Z","completed_at":"2026-10-01T09:22:03Z","runtime_id":"r1","caused_by":null,"code":"import itertools, time\nfor i in itertools.count():\n print(i)\n time.sleep(1)","bindings":[]},"request_id":"9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","time":"2026-10-01T09:22:03Z"}+data: {"execution":{"id":"e9","run_id":"run-interrupted","cell_id":null,"code_hash":"6579899a00aac8fe","depends_on":{},"status":"completed","outcome":{"kind":"interrupted"},"started_at":"2026-10-01T09:22:00Z","completed_at":"2026-10-01T09:22:03Z","runtime_id":"r1","caused_by":null,"code":"import itertools, time\nfor i in itertools.count():\n print(i)\n time.sleep(1)"},"request_id":"9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","time":"2026-10-01T09:22:03Z"}id: 134event: rundiff --git a/protocols/host/fixtures/run.sse b/protocols/host/fixtures/run.sseindex 383fcc159d..ac792c1a94 100644--- a/protocols/host/fixtures/run.sse+++ b/protocols/host/fixtures/run.sse@@ -8,11 +8,11 @@ data: {"run":{"id":"run-scratch","notebook_id":"n1","status":"running","started_id: 92event: execution-data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","status":"running","outcome":null,"stale":null,"started_at":"2026-10-01T09:20:01Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3","bindings":[]},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:01Z"}+data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","depends_on":{},"status":"running","outcome":null,"started_at":"2026-10-01T09:20:01Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3"},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:01Z"}id: 93event: execution-data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","status":"running","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span>"}},"stale":null,"started_at":"2026-10-01T09:20:01Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3","bindings":[]},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:01Z"}+data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","depends_on":{},"status":"running","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span>"}},"started_at":"2026-10-01T09:20:01Z","completed_at":null,"runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3"},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:01Z"}id: 94event: console@@ -26,7 +26,7 @@ data: {"attachment":{"id":"a2","notebook_id":"n1","kind":"agent","name":"Notebooid: 96event: execution-data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","status":"completed","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span><pre>9</pre>"}},"stale":null,"started_at":"2026-10-01T09:20:01Z","completed_at":"2026-10-01T09:20:04Z","runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3","bindings":[]},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:04Z"}+data: {"execution":{"id":"e7","run_id":"run-scratch","cell_id":null,"code_hash":"cebd60abaf00acdc","depends_on":{},"status":"completed","outcome":{"kind":"value","display":{"mimetype":"text/html","data":"<span class=\"markdown\">working…</span><pre>9</pre>"}},"started_at":"2026-10-01T09:20:01Z","completed_at":"2026-10-01T09:20:04Z","runtime_id":"r1","caused_by":null,"code":"import marimo as mo\nmo.output.append(mo.md(\"working…\"))\nprint(1 + 1)\n3 * 3"},"request_id":"7c1e9a3f-5b2d-4e8a-9f10-3c6d7e8f9a0b","time":"2026-10-01T09:20:04Z"}id: 97event: rundiff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex e157dc39e7..4e99d0dd68 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -239,8 +239,8 @@ paths:One event. `data` holds JSON, and the event name sayswhich shape: a NotebookMessage, DocumentMessage,AnalysisMessage, CellMessage, RuntimeMessage, AttachmentMessage,- RunMessage, ExecutionMessage, ConsoleMessage, or- DisplayMessage for an event named+ RunMessage, ExecutionMessage, ConsoleMessage,+ DisplayMessage, or VariableMessage for an event namedafter that kind; a CustomMessage for `custom`; a RemovedMessagefor an event ending in `.removed`; and an empty objectfor `ready` and `reset`.@@ -510,7 +510,8 @@ paths:id independent of the request's `Idempotency-Key` and answers `202`with the run `queued` or `running`. The rest arrives on the notebook'sstream with this request's key: executions as they start, console- and display items, and a final execution whose `outcome` is+ and display items, the variables each cell execution bound, and a+ final execution whose `outcome` is`value`, `error`, or `interrupted`, and a final `run` whosestatus is `completed`. A client that wants to see all of it opensthe notebook's stream before sending the request.@@ -769,7 +770,7 @@ components:ItemId:type: stringminLength: 1- description: Identifies a console or display item. Unique within the host; sending an item again with the same id replaces it.+ description: Identifies a console, display, or variable item. Unique within the host; sending an item again with the same id replaces it.CellId:type: stringminLength: 1@@ -831,9 +832,9 @@ components:catalog stream carries host, project, notebook, runtime, andattachment. A notebook's stream carries notebook, document,analysis, cell, runtime, attachment, run, execution, console,- display, and custom. Custom events describe occurrences rather- than object state.- enum: [host, project, notebook, document, analysis, cell, runtime, attachment, run, execution, console, display, custom]+ display, variable, and custom. Custom events describe occurrences+ rather than object state.+ enum: [host, project, notebook, document, analysis, cell, runtime, attachment, run, execution, console, display, variable, custom]Custom:type: objectdescription: |@@ -929,8 +930,8 @@ components:type: objectdescription: |A runtime is a kernel attached to one notebook, and a notebook has- at most one. It ends when a client or the host stops it, and the- host then sends `runtime.removed`. Every start and restart creates+ at most one. It ends when a client or the host stops it or its+ process exits, and the host then sends `runtime.removed`. Every start and restart createsa new runtime with a new id. Results carry their producer's runtimeid so clients can tell which are live.required: [id, notebook_id, status, message, marimo_version, started_at]@@ -1048,6 +1049,49 @@ components:data:type: stringdescription: The rendered value. JSON mimetypes are encoded as text; binary mimetypes are base64. Never a URL only the runtime can serve.+ Variable:+ type: object+ description: |+ A name a cell's execution bound in the notebook's namespace, with+ the revision of its value. The execution binds it as it ends, and+ the item is removed with the execution. An update, as when a+ state setter runs or a client sets a value, advances the revision+ without binding again, and the producer sends the item again with+ the same id. Hosts publish a cell execution's variables before its+ `completed` status, and remove a cell's previous execution and+ its items before publishing the next one. A scratch execution's+ names live only while it runs, so it publishes no variables.+ required: [id, execution_id, name, revision, type, preview]+ properties:+ id: { $ref: '#/components/schemas/ItemId' }+ execution_id:+ $ref: '#/components/schemas/ExecutionId'+ description: The execution that bound the name.+ name:+ type: string+ description: The name in the namespace.+ revision: { $ref: '#/components/schemas/Revision' }+ type:+ type: [string, 'null']+ description: The runtime's label for the value's type. A host may leave it null.+ preview:+ type: [string, 'null']+ description: A short rendering of the value. A host may leave it null.+ Revision:+ type: object+ description: |+ A variable's value at a point in time. Two revisions are equal+ when `execution` and `update` are equal. Clients compare+ revisions for equality.+ required: [execution, update]+ properties:+ execution:+ $ref: '#/components/schemas/ExecutionId'+ description: The execution whose evaluation produced the value. Usually the variable's `execution_id`, and earlier when the runtime carried the value forward.+ update:+ type: integer+ minimum: 0+ description: How many times the value has been updated since it was produced. Zero at binding.Position:type: objectdescription: A position within code, using LSP coordinates.@@ -1159,18 +1203,6 @@ components:kind:type: stringenum: [interrupted]- Binding:- type: object- description: A name an execution binds in the namespace.- required: [name, type, preview]- properties:- name: { type: string }- type:- type: [string, 'null']- description: The runtime's label for the value's type. A host may leave it null.- preview:- type: [string, 'null']- description: A short rendering of the value. A host may leave it null.Execution:type: objectdescription: |@@ -1179,7 +1211,7 @@ components:one outcome. Side effects belong to the execution whose contextproduced them; items can arrive after the execution is completedwhile it remains retained.- required: [id, run_id, runtime_id, caused_by, cell_id, code, code_hash, bindings, status, outcome, stale, started_at, completed_at]+ required: [id, run_id, runtime_id, caused_by, cell_id, code, code_hash, depends_on, status, outcome, started_at, completed_at]properties:id: { $ref: '#/components/schemas/ExecutionId' }run_id:@@ -1200,17 +1232,15 @@ components:code_hash:$ref: '#/components/schemas/Etag'description: The `code_hash` of the code that was evaluated, computed as a cell's is.- bindings:- type: array- items: { $ref: '#/components/schemas/Binding' }- description: Names bound in the namespace, with a type and preview, stamped when the execution ends. Empty while running and for scratch code, whose bindings die with the execution.+ depends_on:+ type: object+ additionalProperties:+ oneOf: [{ $ref: '#/components/schemas/Revision' }, { type: 'null' }]+ description: The variables the execution used, by name, each at the revision the runtime holds its result valid against. Null for a name no retained cell execution had bound. Empty while queued, stamped as the execution ends, and final from then on.status: { $ref: '#/components/schemas/Lifecycle' }outcome:oneOf: [{ $ref: '#/components/schemas/Outcome' }, { type: 'null' }]description: How the execution ended. Null while queued; while running, a value carries the display so far; final once completed.- stale:- type: [boolean, 'null']- description: Whether an input changed since this result was produced. Null for scratch code, which has no inputs in the graph.started_at:type: [string, 'null']format: date-time@@ -1377,7 +1407,7 @@ components:policy:type: stringenum: [autorun, lazy]- description: When dependents of an evaluated cell run. `autorun` runs them on every change; `lazy` marks them stale and runs them when asked. Set by the host.+ description: When dependents of an evaluated cell run. `autorun` runs them on every change; `lazy` leaves them for a later run. Set by the host.etag:$ref: '#/components/schemas/Etag'description: Identifies the document as currently applied. Its text is `order_etag`, `app_config_etag`, and every cell's `etag` in order, so it changes when any of them does.@@ -1478,6 +1508,14 @@ components:request_id: *request_idtime: *timedisplay: { $ref: '#/components/schemas/Display' }+ VariableMessage:+ type: object+ description: The data of a `variable` event. The item as it now is.+ required: [variable]+ properties:+ request_id: *request_id+ time: *time+ variable: { $ref: '#/components/schemas/Variable' }DocumentMessage:type: objectdescription: The data of a `document` event. The document as it now is.@@ -1507,8 +1545,8 @@ components:description: |The data of a `project.removed`, `notebook.removed`,`cell.removed`, `runtime.removed`, `attachment.removed`,- `run.removed`, `execution.removed`, `console.removed`, or- `display.removed` event. The client deletes the object with this+ `run.removed`, `execution.removed`, `console.removed`,+ `display.removed`, or `variable.removed` event. The client deletes the object with thisid; the event name says which kind it is. Removing a notebookremoves its document and cells with it, without events of theirown; the document never has one.diff --git a/protocols/host/spec.md b/protocols/host/spec.mdindex 3b8e76a728..e71d94c883 100644--- a/protocols/host/spec.md+++ b/protocols/host/spec.md@@ -151,13 +151,73 @@ Notebook└── Cell execution · another dependent cell```-Results include an execution's outcome, **console** output, and **display**-items. They can remain available after the runtime stops or be restored from-storage. Clients use the available provenance and staleness information to-distinguish saved results from results of the current computation. Hosts choose+Results include an execution's outcome, **console** output, **display**+items, and the **variables** a cell's execution bound. They can remain+available after the runtime stops or be restored from storage. Hosts choosehow long to retain results and SHOULD keep ephemeral results briefly aftercompletion to allow reconnection.+A **variable** is a name in the notebook's namespace whose value varies over+time. A cell's execution **binds** variables as it ends, each with a+**revision** of its value. An **update** advances a revision without binding+again, as when a state setter runs or a client sets a value. A revision names+the execution whose evaluation produced the value and counts the updates+since. Clients compare revisions for equality.++ Variable { id, execution_id, name, revision, type, preview }+ Revision { execution, update }++Hosts MUST publish a cell execution's variables before its `completed` status,+and MUST remove a cell's previous execution and its items before publishing+the next one. A cell has one latest execution on the stream.++An execution **depends on** the variables it used, each at the revision the+runtime holds its result valid against. A name that no retained cell+execution had bound is recorded as null.++ Execution { ..., depends_on: Record<Name, Revision | null> }++A completed cell execution is **current** when:++- its `code_hash` equals the cell's,+- each variable it depends on still holds the recorded revision,+- each name it depends on that was unbound is still unbound,+- the execution that bound each of those variables is current.++A client finds a variable by the recorded revision's `execution` and the name.+If none exists, that execution was replaced or removed. If its `update` is+higher, the value was updated. If that execution's `code_hash` differs from+its cell's, the cell was edited. The first that applies is why the result is+**outdated**. A cell with no execution has no result to compare. Scratch+executions have no cell and are not compared.++For example, cell `k7f2` reads `x`, which cell `c3` binds:++ Cell c3 code_hash 0f71… Execution e12 code_hash 0f71… depends_on {}+ Variable x revision {e12, 0} bound by e12+ Cell k7f2 code_hash db2b… Execution e13 code_hash db2b… depends_on {x: {e12, 0}}++Both executions are current. An update that advances `x` to `{e12, 1}` makes+`e13` outdated because a value it depends on was updated. Editing `c3` makes+`e12` outdated because its code changed, and `e13` because the execution that+bound `x` is. Running `c3` again removes `e12` and binds `x` under a new+execution, so `e13` is outdated because the execution it depends on was+replaced.++The runtime stamps `depends_on` as the execution ends, from its own namespace+and rules:++- a value the execution itself updated is recorded at the revision it set,+- a name bound only by a result from an earlier runtime is recorded as+ unbound,+- a value carried forward unchanged, such as an import, keeps its revision,+ so a revision's `execution` can be earlier than the variable's+ `execution_id`.++Updates are published before any execution that depends on them. The host+removes the runtime when its process ends, so a result is **live** when its+`runtime_id` is the notebook's runtime.+## Connecting to the host APIClients connect using the host API's base URL and bearer token, whether@@ -264,9 +324,11 @@ formatting, MUST reach clients through the document stream as well.Clients can request document cells or submit scratch code. Cells execute underthe runtime's execution configuration, which determines how dependent cells-are scheduled. Scratch code runs against a copy of the runtime namespace-outside the document's dependency graph. A client can ask the host to verify-that a cell's code still matches what it read before executing it.+are scheduled. A dependent the configuration leaves out keeps its execution,+which is outdated once a new execution replaces the one it depends on. Scratch+code runs against a copy of the runtime namespace outside the document's+dependency graph. A client can ask the host to verify that a cell's code still+matches what it read before executing it.An accepted execution request starts a run whose progress and results arrive onthe notebook stream for all attached clients. Clients that need to observe thediff --git a/tests/_core/conftest.py b/tests/_core/conftest.pyindex c191aa0952..98feaef598 100644--- a/tests/_core/conftest.py+++ b/tests/_core/conftest.py@@ -246,12 +246,11 @@ def retained_execution(cell_id=None if cell_id is None else protocol.CellId(cell_id),code="42" if cell_id is None else None,code_hash=code_hash("42"),- bindings=(),+ depends_on={},status="completed",outcome=protocol.ValueOutcome(protocol.DisplayData(mimetype="text/plain", data="42")),- stale=False if cell_id is not None else None,started_at=None,completed_at=None,),diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.pyindex 4a826e8e1d..5e4498acaf 100644--- a/tests/_core/test_notebook.py+++ b/tests/_core/test_notebook.py@@ -599,7 +599,7 @@ class TestRun:code="3 * 3",code_hash="9f",completed_at=IsDatetime(),- bindings=(),+ depends_on={},id=ExecutionId("e7"),outcome=ValueOutcome(display=DisplayData(@@ -608,7 +608,6 @@ class TestRun:),run_id=run.id,runtime_id=notebook.runtime.id,- stale=None,started_at=IsDatetime(),status="completed",),diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.pyindex 4c625c83ec..c8fff3ce95 100644--- a/tests/_core/test_protocol.py+++ b/tests/_core/test_protocol.py@@ -377,16 +377,17 @@ def test_run_lifecycles(name: str, outcome: str) -> None:)if execution["cell_id"] is None:assert execution["code"] is not None- assert execution["stale"] is None- assert execution["bindings"] == []else:assert execution["code"] is Noneif execution["status"] == "queued":assert execution["outcome"] is Noneassert execution["started_at"] is None- if execution["status"] != "completed":- assert execution["bindings"] == []- else:+ assert execution["depends_on"] == {}+ elif previous is not None and previous["status"] != "queued":+ assert execution["depends_on"] == previous["depends_on"]+ for revision in execution["depends_on"].values():+ assert revision is None or revision["update"] >= 0+ if execution["status"] == "completed":assert execution["outcome"] is not Noneassert (execution["completed_at"] is not None) == (execution["status"] == "completed"@@ -394,6 +395,17 @@ def test_run_lifecycles(name: str, outcome: str) -> None:executions[execution["id"]] = executionelif kind in {"console", "display"}:assert data[kind]["execution_id"] in executions+ elif kind == "variable":+ variable = data["variable"]+ execution = executions[variable["execution_id"]]+ assert execution["cell_id"] is not None+ if variable["revision"]["update"] == 0:+ # Bound before the execution completes.+ assert execution["status"] == "running"+ assert (+ variable["revision"]["execution"]+ == variable["execution_id"]+ )assert runsassert all(r["status"] == "completed" for r in runs.values())@@ -417,17 +429,37 @@ def test_cell_run_request_and_results() -> None:assert cells["k7f2"]["code"] == "y = x * 2"assert executions["e12"]["caused_by"] is Noneassert executions["e13"]["caused_by"] == "e12"+ assert executions["e12"]["depends_on"] == {}+ assert executions["e13"]["depends_on"] == {+ "x": {"execution": "e12", "update": 0}+ }for execution in executions.values():assert (execution["code_hash"] == cells[execution["cell_id"]]["code_hash"])assert execution["outcome"] == {"kind": "value", "display": None}- assert executions["e12"]["bindings"] == [- {"name": "x", "type": "int", "preview": "21"}- ]- assert executions["e13"]["bindings"] == [- {"name": "y", "type": "int", "preview": "42"}- ]+ variables = {+ m["variable"]["name"]: m["variable"]+ for m in messages("run-cells.sse", "variable")+ }+ assert variables == {+ "x": {+ "id": "e12-x",+ "execution_id": "e12",+ "name": "x",+ "revision": {"execution": "e12", "update": 0},+ "type": "int",+ "preview": "21",+ },+ "y": {+ "id": "e13-y",+ "execution_id": "e13",+ "name": "y",+ "revision": {"execution": "e13", "update": 0},+ "type": "int",+ "preview": "42",+ },+ }assert not messages("run-cells.sse", "console")@@ -516,9 +548,6 @@ def test_restored_result_matches_source() -> None:assert restored["code_hash"] == content_hash(source["code"])assert restored["run_id"] is Noneassert restored["runtime_id"] is None- assert restored["bindings"] == [- {"name": "x", "type": "int", "preview": "21"}- ]@pytest.mark.parametrize(