@marimo-team/islands 0.25.3-dev275 → 0.25.3-dev279

package/src/core/executions/freshness.ts

@@ -0,0 +1,164 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Whether each cell's result still reflects the document and the values
+ * it read, by the host protocol's rules.
+ *
+ * A completed execution is current when its code fingerprint equals the
+ * cell's, every variable it depends on still holds the recorded revision,
+ * every name it depends on that was unbound is still unbound, and the
+ * executions that bound those variables are current. See the freshness
+ * section of `protocols/host/spec.md`.
+ *
+ * The protocol also ranks why a result is outdated. The editor asks two
+ * questions of its own, so that is what this reports; the ranked reason
+ * can come back with a reader. Two editor concerns are folded in: a name
+ * bound only by an earlier runtime is unbound in this one, and a queued or
+ * running execution for the cell's current source already covers it.
+ */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { Executions, Results } from "@/core/notebook/replica";
+
+export interface CellFreshness {
+  /** This cell's source changed since its result. */
+  readonly sourceChanged: boolean;
+  /**
+   * A value the result read changed since, by a rerun or an update, here
+   * or upstream. An ancestor that was only edited does not count: its
+   * values are still the ones this result read.
+   */
+  readonly inputsChanged: boolean;
+}
+
+/** Current, and also a cell with no completed execution to compare. */
+const CURRENT: CellFreshness = { sourceChanged: false, inputsChanged: false };
+
+/** What freshness is derived from. */
+export interface CellFreshnessInputs {
+  /** The document's cells, for the fingerprint of each cell's source. */
+  readonly cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>;
+  /** The stream's executions, for the variables currently bound. */
+  readonly executions: Executions;
+  /** Each cell's last completed record, the result being compared. */
+  readonly results: Results;
+}
+
+/** Freshness by cell id, as `freshnessOf` builds it. */
+export type CellFreshnessLookup = (id: Protocol.CellId) => CellFreshness;
+
+/** The variables bound in the namespace right now, by name. */
+function boundVariables(
+  executions: Executions,
+): ReadonlyMap<string, Protocol.Variable[]> {
+  const byName = new Map<string, Protocol.Variable[]>();
+  for (const execution of executions.executions.values()) {
+    for (const variable of execution.variables.values()) {
+      const bound = byName.get(variable.name);
+      if (bound === undefined) {
+        byName.set(variable.name, [variable]);
+      } else {
+        bound.push(variable);
+      }
+    }
+  }
+  return byName;
+}
+
+/**
+ * Compares results against the document and the namespace.
+ *
+ * Build one per set of inputs and ask it about each cell, since the
+ * bound variables are indexed once and a binding execution's freshness is
+ * computed once however many results depend on it.
+ */
+export function freshnessOf(inputs: CellFreshnessInputs): CellFreshnessLookup {
+  const bound = boundVariables(inputs.executions);
+  const memo = new Map<Protocol.ExecutionId, CellFreshness>();
+  const recordOf = (id: Protocol.ExecutionId) =>
+    inputs.executions.executions.get(id)?.record;
+
+  /** Whether a value the record read has changed, or one upstream has. */
+  function inputsChanged(
+    record: Protocol.Execution,
+    visiting: ReadonlySet<Protocol.ExecutionId>,
+  ): boolean {
+    const path = new Set(visiting).add(record.id);
+    for (const [name, revision] of Object.entries(record.depends_on)) {
+      const variables = bound.get(name) ?? [];
+      if (revision === null) {
+        // A result retained from an earlier runtime binds nothing here.
+        if (
+          variables.some(
+            (v) => recordOf(v.execution_id)?.runtime_id === record.runtime_id,
+          )
+        ) {
+          return true;
+        }
+        continue;
+      }
+      const variable = variables.find(
+        (candidate) => candidate.revision.execution === revision.execution,
+      );
+      if (
+        variable === undefined ||
+        variable.revision.update !== revision.update
+      ) {
+        return true;
+      }
+      const binder = recordOf(variable.execution_id);
+      if (binder === undefined) {
+        return true;
+      }
+      if (!path.has(binder.id) && ofRecord(binder, path).inputsChanged) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Whether a newer execution of the cell already runs its current source. */
+  function coveredByPending(
+    cell: Protocol.Cell,
+    record: Protocol.Execution,
+  ): boolean {
+    const latest = inputs.executions.latest.get(cell.id);
+    if (latest === undefined || latest === record.id) {
+      return false;
+    }
+    const pending = recordOf(latest);
+    return (
+      pending !== undefined &&
+      pending.status !== "completed" &&
+      pending.code_fingerprint === cell.code_fingerprint
+    );
+  }
+
+  function ofRecord(
+    record: Protocol.Execution,
+    visiting: ReadonlySet<Protocol.ExecutionId>,
+  ): CellFreshness {
+    const known = memo.get(record.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const cell =
+      record.cell_id === null ? undefined : inputs.cells.get(record.cell_id);
+    const freshness: CellFreshness = {
+      sourceChanged:
+        cell === undefined ||
+        (cell.code_fingerprint !== record.code_fingerprint &&
+          !coveredByPending(cell, record)),
+      inputsChanged: inputsChanged(record, visiting),
+    };
+    memo.set(record.id, freshness);
+    return freshness;
+  }
+
+  return (id) => {
+    const result = inputs.results.get(id);
+    return result === null || result === undefined
+      ? CURRENT
+      : ofRecord(result, new Set());
+  };
+}

package/src/core/executions/hooks.ts

@@ -5,7 +5,8 @@ import { dequal } from "dequal";
 import { useAtomValue } from "jotai";
 import { selectAtom } from "jotai/utils";
 import { useMemo } from "react";
-import { cellExecutionInputsAtom } from "./atoms";
+import { cellExecutionInputsAtom, cellFreshnessAtom } from "./atoms";
+import type { CellFreshness } from "./freshness";
 import { type CellExecutionView, cellExecutionView } from "./select";
 
 /**
@@ -29,3 +30,18 @@ export function useCellExecution(id: Protocol.CellId): CellExecutionView {
   );
   return useAtomValue(cellAtom);
 }
+
+/**
+ * Whether a cell's result is current, by the host protocol's rules over
+ * the confirmed document and the executions mirror.
+ *
+ * The confirmed document is what the host has accepted, so an edit reads
+ * as such once the model has flushed it, not on the keystroke.
+ */
+export function useCellFreshness(id: Protocol.CellId): CellFreshness {
+  const cellAtom = useMemo(
+    () => selectAtom(cellFreshnessAtom, (freshness) => freshness(id), dequal),
+    [id],
+  );
+  return useAtomValue(cellAtom);
+}

package/src/core/executions/index.ts

@@ -10,6 +10,7 @@
 
 export {
   cellExecutionInputsAtom,
+  cellFreshnessAtom,
   notebookIsRunningAtom,
   notebookQueuedOrRunningCountAtom,
   observeCellMessage,
@@ -18,7 +19,8 @@ export {
   waitForRuntimeRunning,
   withdrawCells,
 } from "./atoms";
-export { useCellExecution } from "./hooks";
+export type { CellFreshness, CellFreshnessLookup } from "./freshness";
+export { useCellExecution, useCellFreshness } from "./hooks";
 export {
   type CellExecutionInputs,
   type CellExecutionView,

package/src/core/islands/bootstrap.ts

@@ -221,7 +221,6 @@ function handleNotification(
         handleKernelReady(msg, {
           autoInstantiate: true,
           cells: notebookCells(store.get(notebookAtom)),
-          setLastRun: actions.setLastRun,
           resetCellRuntimes: actions.resetCellRuntimes,
           setLayoutData: Functions.NOOP,
           setCapabilities: Functions.NOOP,

package/src/core/kernel/handlers.ts

@@ -60,7 +60,6 @@ export function handleKernelReady(
     autoInstantiate: boolean;
     /** The notebook's cells, as the host document provided them. */
     cells: CellData[];
-    setLastRun: ReducerCellActions["setLastRun"];
     resetCellRuntimes: ReducerCellActions["resetCellRuntimes"];
     setLayoutData: (payload: {
       layoutView: LayoutType;
@@ -73,7 +72,6 @@ export function handleKernelReady(
   const {
     autoInstantiate,
     cells,
-    setLastRun,
     resetCellRuntimes,
     setLayoutData,
     setCapabilities,
@@ -82,8 +80,6 @@ export function handleKernelReady(
   const { resumed, ui_values, capabilities, auto_instantiated } = data;
 
   resetCellRuntimes();
-  // TODO(MO-8403): Delete with `lastCodeRun`.
-  setLastRun({ lastCodeRun: data.last_executed_code ?? {} });
   const layoutState = buildLayoutState(data, cells, setLayoutData);
 
   setCapabilities(capabilities);

package/src/core/session/useNotebookSession.tsx

@@ -92,12 +92,8 @@ export function useNotebookSession(opts: {
   const { showBoundary } = useErrorBoundary();
   const store = useStore();
 
-  const {
-    handleCellMessage,
-    reconcileDocument,
-    setLastRun,
-    resetCellRuntimes,
-  } = useReducerActions();
+  const { handleCellMessage, reconcileDocument, resetCellRuntimes } =
+    useReducerActions();
   const { reconcileStagedCells } = useStagedAICellsActions();
   const { addCellNotification } = useRunsActions();
   const setInitialRunCompleted = useSetAtom(initialRunCompletedAtom);
@@ -154,7 +150,6 @@ export function useNotebookSession(opts: {
         const layout = handleKernelReady(msg.data, {
           autoInstantiate,
           cells: notebookCells(store.get(notebookAtom)),
-          setLastRun,
           resetCellRuntimes,
           setLayoutData,
           setCapabilities,

package/src/stories/cell-status.stories.tsx

@@ -27,7 +27,7 @@ export const Idle = Template.bind({});
 Idle.args = {
   editing: true,
   status: "idle",
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: false },
   interrupted: false,
   disabled: false,
   elapsedTime: null,
@@ -37,7 +37,7 @@ export const Edited = Template.bind({});
 Edited.args = {
   editing: true,
   status: "idle",
-  edited: true,
+  freshness: { sourceChanged: true, inputsChanged: false },
   interrupted: false,
   disabled: false,
   elapsedTime: 100 as Milliseconds,
@@ -47,7 +47,7 @@ export const Interrupted = Template.bind({});
 Interrupted.args = {
   editing: true,
   status: "idle",
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: false },
   interrupted: true,
   disabled: false,
   elapsedTime: 50 as Milliseconds,
@@ -57,7 +57,7 @@ export const Running = Template.bind({});
 Running.args = {
   editing: true,
   status: "running",
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: false },
   interrupted: true,
   disabled: false,
   elapsedTime: 50 as Milliseconds,
@@ -67,7 +67,7 @@ export const Queued = Template.bind({});
 Queued.args = {
   editing: true,
   status: "queued",
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: false },
   interrupted: true,
   disabled: false,
   elapsedTime: 50 as Milliseconds,
@@ -77,7 +77,7 @@ export const Disabled = Template.bind({});
 Disabled.args = {
   editing: true,
   status: "idle",
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: false },
   interrupted: false,
   disabled: true,
   elapsedTime: null,
@@ -88,7 +88,7 @@ DisabledTransitively.args = {
   editing: true,
   status: "idle",
   blocked: true,
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: false },
   interrupted: false,
   disabled: false,
   elapsedTime: null,
@@ -99,7 +99,7 @@ DisabledTransitivelyAndEdited.args = {
   editing: true,
   status: "idle",
   blocked: true,
-  edited: true,
+  freshness: { sourceChanged: true, inputsChanged: false },
   interrupted: false,
   disabled: false,
   elapsedTime: null,
@@ -110,8 +110,7 @@ Stale.args = {
   editing: true,
   status: "idle",
   blocked: true,
-  staleInputs: true,
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: true },
   interrupted: false,
   disabled: false,
   elapsedTime: null,
@@ -122,8 +121,7 @@ StaleAndDisabled.args = {
   editing: true,
   status: "idle",
   blocked: true,
-  staleInputs: true,
-  edited: false,
+  freshness: { sourceChanged: false, inputsChanged: true },
   interrupted: false,
   disabled: true,
   elapsedTime: null,
@@ -134,7 +132,7 @@ EditedStaleAndDisabled.args = {
   editing: true,
   status: "idle",
   blocked: true,
-  staleInputs: true,
+  freshness: { sourceChanged: false, inputsChanged: true },
   interrupted: false,
   disabled: true,
   elapsedTime: null,
@@ -145,7 +143,7 @@ EditedAndStale.args = {
   editing: true,
   status: "idle",
   blocked: true,
-  edited: true,
+  freshness: { sourceChanged: true, inputsChanged: false },
   interrupted: false,
   disabled: false,
   elapsedTime: null,

package/src/stories/cell.stories.tsx

@@ -3,7 +3,14 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { createStore, Provider } from "jotai";
 import { createRef } from "react";
+import { MockExecutions } from "@/__mocks__/executions";
 import { cellId } from "@/__tests__/branded";
+import type { CellId } from "@/core/cells/ids";
+import {
+  cell,
+  document as documentOf,
+  withCells,
+} from "@/core/notebook/document/__tests__/fixtures";
 import { type NotebookState, notebookAtom } from "@/core/cells/cells";
 import {
   type CellRuntimeState,
@@ -22,13 +29,41 @@ type Story = StoryObj<typeof Cell>;
 
 interface CellOverrides {
   output?: CellRuntimeState["output"];
-  edited?: boolean;
-  staleInputs?: boolean;
+  /** How the cell's result is outdated, as the host would report it. */
+  freshness?: "edited" | "replaced" | "both";
   config?: CellConfig;
 }
 
 const EMPTY_OVERRIDES: Readonly<CellOverrides> = {};
 
+/**
+ * Give the replica a completed execution whose source was edited since,
+ * whose input a newer execution replaced, or both.
+ */
+function seedFreshness(
+  store: ReturnType<typeof createStore>,
+  cid: CellId,
+  freshness: NonNullable<CellOverrides["freshness"]>,
+) {
+  const ran = MockExecutions.completed(cid, {
+    code_fingerprint: "ran",
+    depends_on:
+      freshness === "edited" ? {} : { x: { execution: "gone", update: 0 } },
+  });
+  const document = withCells(
+    documentOf(),
+    {
+      c1: null,
+      c2: null,
+      [cid]: cell(cid, "import marimo as mo", {
+        code_fingerprint: freshness === "replaced" ? "ran" : "edited",
+      }),
+    },
+    [cid],
+  );
+  MockExecutions.seed(store, [ran], null, document);
+}
+
 const Cell: React.FC<{
   overrides?: CellOverrides;
 }> = ({ overrides = EMPTY_OVERRIDES }) => {
@@ -39,13 +74,11 @@ const Cell: React.FC<{
         id: cid,
         name: "cell_1",
         code: "import marimo as mo",
-        edited: overrides.edited ?? false,
         config: {
           hide_code: overrides.config?.hide_code ?? false,
           disabled: overrides.config?.disabled ?? false,
           column: null,
         },
-        lastCodeRun: null,
       },
     },
     cellIds: [cid],
@@ -53,7 +86,6 @@ const Cell: React.FC<{
       [cid]: createCellRuntimeState({
         output: overrides.output ?? null,
         consoleOutputs: [],
-        staleInputs: overrides.staleInputs ?? false,
         debuggerActive: false,
         outline: null,
       }),
@@ -68,6 +100,9 @@ const Cell: React.FC<{
 
   const store = createStore();
   store.set(notebookAtom, notebook);
+  if (overrides.freshness !== undefined) {
+    seedFreshness(store, cid, overrides.freshness);
+  }
   store.set(connectionAtom, { state: ConnectionState.OPEN });
   store.set(requestClientAtom, resolveRequestClient());
   return (
@@ -145,7 +180,7 @@ export const UnsavedEditsOutput: Story = {
       <TooltipProvider>
         <Cell
           overrides={{
-            edited: true,
+            freshness: "edited",
             output: {
               channel: "output",
               data: "<span class='markdown'><h1>Layout</h1>\n<p><code>marimo</code> provides functions to help you lay out your output, such as\nin rows and columns, accordions, tabs, and callouts. This tutorial\nshows some examples.</p></span>",
@@ -239,7 +274,7 @@ export const StaleStatus: Story = {
     <div className="p-20 max-w-4xl">
       <Cell
         overrides={{
-          staleInputs: true,
+          freshness: "replaced",
           output: {
             channel: "output",
             data: "This data is stale because a parent is disabled",
@@ -257,8 +292,7 @@ export const StaleAndEditedStatus: Story = {
     <div className="p-20 max-w-4xl">
       <Cell
         overrides={{
-          staleInputs: true,
-          edited: true,
+          freshness: "both",
           output: {
             channel: "output",
             data: "This data is stale because a parent is disabled, but this cell has been edited since.",
@@ -281,7 +315,7 @@ export const DisabledAndStaleStatus: Story = {
             disabled: true,
             hide_code: false,
           },
-          staleInputs: true,
+          freshness: "replaced",
           output: {
             channel: "output",
             data: "<span class='markdown'><h1>Layout</h1>\n<p><code>marimo</code> provides functions to help you lay out your output, such as\nin rows and columns, accordions, tabs, and callouts. This tutorial\nshows some examples.</p></span>",

package/src/stories/layout/vertical/one-column.stories.tsx

@@ -35,20 +35,11 @@ const createLongReprNotebook = (
 
 print('hello')
 LongReprA()`,
-      edited: false,
       config: {
         hide_code: hideCode,
         disabled: false,
         column: null,
       },
-      lastCodeRun: `class LongReprA:
-    def __repr__(self):
-        return "<dlt.Relation(dataset='" + ("jaffle_ingest_dataset_" * 80) + \\
-            "', destination='<dlt.destinations.duckdb(destination_type=\\'duckdb\\'," + \\
-            " credentials=\\'local_jaffle.duckdb\\')>')>"
-
-print('hello')
-LongReprA()`,
     },
   },
   cellIds: [cellId],
@@ -68,7 +59,6 @@ LongReprA()`,
           timestamp: 1_686_863_705,
         },
       ],
-      staleInputs: false,
       debuggerActive: false,
       outline: null,
     }),

package/src/components/editor/cell/__tests__/useRunCells.test.ts

@@ -1,45 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import { describe, expect, it, vi } from "vitest";
-import { MockExecutions } from "@/__mocks__/executions";
-import { MockNotebook } from "@/__mocks__/notebook";
-import { cellId } from "@/__tests__/branded";
-import {
-  cellExecutionInputsAtom,
-  cellExecutionView,
-  notebookQueuedOrRunningCountAtom,
-} from "@/core/executions";
-import { store } from "@/core/state/jotai";
-import { runCells } from "../useRunCells";
-
-const ENABLED = cellId("enabled");
-const DISABLED = cellId("disabled");
-
-describe("runCells", () => {
-  it("sends a disabled cell to the kernel without reading it as queued", async () => {
-    MockExecutions.seed(store, []);
-    const notebook = MockNotebook.notebookState({
-      cellData: {
-        [ENABLED]: { code: "x = 1" },
-        [DISABLED]: { code: "y = 2", config: { disabled: true } },
-      },
-    });
-    const sendRun = vi.fn(async () => null);
-
-    await runCells({
-      cellIds: [ENABLED, DISABLED],
-      sendRun,
-      prepareForRun: vi.fn(),
-      notebook,
-    });
-
-    expect(sendRun).toHaveBeenCalledWith({
-      cellIds: [ENABLED, DISABLED],
-      codes: ["x = 1", "y = 2"],
-    });
-    const inputs = store.get(cellExecutionInputsAtom);
-    expect(cellExecutionView(inputs, ENABLED).status).toBe("queued");
-    expect(cellExecutionView(inputs, DISABLED).status).toBe("idle");
-    expect(store.get(notebookQueuedOrRunningCountAtom)).toBe(1);
-  });
-});