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.

Derive whether a result is current from the host stream (#11277)

Trevor Manza7cb6ba9e7d2
diff --git a/marimo/_core/executions.py b/marimo/_core/executions.py
index 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: str
run_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.py
index 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: AttachmentId
kind: 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: ExecutionId
outcome: (
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.py
index 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.py
index 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.md
index 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 accepted
state, 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.json
index 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.sse
index 190a7afcbb..a1a72aa39a 100644
--- a/protocols/host/fixtures/notebook-events.sse
+++ b/protocols/host/fixtures/notebook-events.sse
@@ -26,7 +26,7 @@ event: run
data: {"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: console
data: {"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: 96
event: 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: 97
event: run
diff --git a/protocols/host/fixtures/run-cells.sse b/protocols/host/fixtures/run-cells.sse
index 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: 101
event: 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: 102
event: 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: 103
event: run
@@ -16,21 +16,29 @@ data: {"run":{"id":"run-cells","notebook_id":"n1","status":"running","started_at
id: 104
event: 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: 106
event: 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: 107
event: 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: 110
event: run
data: {"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.sse
index 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_a
id: 121
event: 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: 122
event: console
@@ -12,7 +12,7 @@ data: {"console":{"id":"o4","execution_id":"e8","seq":0,"name":"stderr","text":"
id: 123
event: 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: 124
event: run
diff --git a/protocols/host/fixtures/run-interrupted.sse b/protocols/host/fixtures/run-interrupted.sse
index 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","star
id: 131
event: 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: 132
event: console
@@ -12,7 +12,7 @@ data: {"console":{"id":"o5","execution_id":"e9","seq":0,"name":"stdout","text":"
id: 133
event: 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: 134
event: run
diff --git a/protocols/host/fixtures/run.sse b/protocols/host/fixtures/run.sse
index 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: 92
event: 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: 93
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","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: 94
event: console
@@ -26,7 +26,7 @@ data: {"attachment":{"id":"a2","notebook_id":"n1","kind":"agent","name":"Noteboo
id: 96
event: 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: 97
event: run
diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yaml
index 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 says
which 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 named
after that kind; a CustomMessage for `custom`; a RemovedMessage
for an event ending in `.removed`; and an empty object
for `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's
stream 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` whose
status is `completed`. A client that wants to see all of it opens
the notebook's stream before sending the request.
@@ -769,7 +770,7 @@ components:
ItemId:
type: string
minLength: 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: string
minLength: 1
@@ -831,9 +832,9 @@ components:
catalog stream carries host, project, notebook, runtime, and
attachment. A notebook's stream carries notebook, document,
analysis, cell, runtime, attachment, run, execution, console,
- display, and custom. Custom events describe occurrences rather
- than object state.
- enum: [host, project, notebook, document, analysis, cell, runtime, attachment, run, execution, console, display, custom]
+ 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: object
description: |
@@ -929,8 +930,8 @@ components:
type: object
description: |
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 creates
a new runtime with a new id. Results carry their producer's runtime
id so clients can tell which are live.
required: [id, notebook_id, status, message, marimo_version, started_at]
@@ -1048,6 +1049,49 @@ components:
data:
type: string
description: 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: object
description: A position within code, using LSP coordinates.
@@ -1159,18 +1203,6 @@ components:
kind:
type: string
enum: [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: object
description: |
@@ -1179,7 +1211,7 @@ components:
one outcome. Side effects belong to the execution whose context
produced them; items can arrive after the execution is completed
while 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: string
enum: [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_id
time: *time
display: { $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: object
description: 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 this
id; the event name says which kind it is. Removing a notebook
removes its document and cells with it, without events of their
own; the document never has one.
diff --git a/protocols/host/spec.md b/protocols/host/spec.md
index 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 choose
how long to retain results and SHOULD keep ephemeral results briefly after
completion 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 API
Clients 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 under
the 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 on
the notebook stream for all attached clients. Clients that need to observe the
diff --git a/tests/_core/conftest.py b/tests/_core/conftest.py
index 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.py
index 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.py
index 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 None
if execution["status"] == "queued":
assert execution["outcome"] is None
assert 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 None
assert (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"]] = execution
elif 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 runs
assert 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 None
assert 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 None
assert restored["runtime_id"] is None
- assert restored["bindings"] == [
- {"name": "x", "type": "int", "preview": "21"}
- ]
@pytest.mark.parametrize(