@marimo-team/islands 0.25.3-dev29 → 0.25.3-dev290

package/src/core/executions/__tests__/select.test.ts

@@ -0,0 +1,268 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import { describe, expect, it } from "vitest";
+import type { Execution, Executions, Results } from "@/core/notebook/replica";
+import {
+  anyRunning,
+  type CellExecutionInputs,
+  cellExecutionView,
+  onlyScratchRunning,
+  queuedOrRunningCount,
+  runningCellIds,
+} from "../select";
+
+const T0 = "2026-10-01T09:20:11Z";
+const T1 = "2026-10-01T09:20:12.500Z";
+const T2 = "2026-10-01T09:20:20Z";
+
+function record(
+  overrides: Partial<Protocol.Execution> & { id: string },
+): Protocol.Execution {
+  return {
+    run_id: "run-1",
+    runtime_id: "r1",
+    caused_by: null,
+    cell_id: "c1",
+    code: null,
+    code_fingerprint: "0f71456db2ea83f4",
+    depends_on: {},
+    status: "completed",
+    outcome: { kind: "value", display: null },
+    started_at: T0,
+    completed_at: T1,
+    ...overrides,
+  };
+}
+
+function execution(overrides: Partial<Protocol.Execution> & { id: string }) {
+  return { record: record(overrides), items: new Map(), variables: new Map() };
+}
+
+function inputs({
+  executions = [],
+  results = new Map(),
+  submissions = new Map(),
+  blocked = new Set(),
+}: {
+  executions?: Execution[];
+  results?: Results;
+  submissions?: ReadonlyMap<string, string | null>;
+  blocked?: ReadonlySet<string>;
+}): CellExecutionInputs {
+  const stream: Executions = {
+    runs: new Map(),
+    executions: new Map(executions.map((e) => [e.record.id, e])),
+    latest: new Map(
+      executions.flatMap((e) =>
+        e.record.cell_id === null ? [] : [[e.record.cell_id, e.record.id]],
+      ),
+    ),
+  };
+  return { executions: stream, results, submissions, blocked };
+}
+
+describe("cellExecutionView", () => {
+  it("is idle with no outcome before a cell runs", () => {
+    expect(cellExecutionView(inputs({}), "c1")).toEqual({
+      status: "idle",
+      blocked: false,
+      outcome: null,
+      startedAt: null,
+      duration: null,
+      rendered: false,
+    });
+  });
+
+  it("follows the execution on the stream while it is unfinished", () => {
+    const queued = inputs({
+      executions: [
+        execution({
+          id: "e1",
+          status: "queued",
+          outcome: null,
+          started_at: null,
+          completed_at: null,
+        }),
+      ],
+    });
+    expect(cellExecutionView(queued, "c1").status).toBe("queued");
+    const running = inputs({
+      executions: [
+        execution({
+          id: "e1",
+          status: "running",
+          outcome: null,
+          started_at: T2,
+          completed_at: null,
+        }),
+      ],
+      results: new Map([["c1", record({ id: "e0" })]]),
+    });
+    expect(cellExecutionView(running, "c1")).toEqual({
+      status: "running",
+      blocked: false,
+      outcome: null,
+      startedAt: Date.parse(T2),
+      duration: null,
+      rendered: false,
+    });
+  });
+
+  it("notes when a running execution has shown a value so far", () => {
+    const showing = inputs({
+      executions: [
+        execution({
+          id: "e1",
+          status: "running",
+          outcome: { kind: "value", display: null },
+          completed_at: null,
+        }),
+      ],
+    });
+    expect(cellExecutionView(showing, "c1").rendered).toBe(true);
+  });
+
+  it("reports how the last completed execution ended, with its timing", () => {
+    const ended = (outcome: Protocol.Outcome) =>
+      cellExecutionView(
+        inputs({
+          executions: [execution({ id: "e1", outcome })],
+          results: new Map([["c1", record({ id: "e1", outcome })]]),
+        }),
+        "c1",
+      );
+    const value = ended({ kind: "value", display: null });
+    expect(value).toEqual({
+      status: "idle",
+      blocked: false,
+      outcome: "value",
+      startedAt: Date.parse(T0),
+      duration: 1500,
+      rendered: false,
+    });
+    const error = (kind: string): Protocol.Outcome => ({
+      kind: "error",
+      error: {
+        kind,
+        message: "",
+        name: null,
+        traceback: null,
+        source: "marimo",
+        severity: "error",
+        range: null,
+        related: [],
+      },
+    });
+    expect(ended(error("exception")).outcome).toBe("error");
+    const skipped: Protocol.Outcome = {
+      kind: "skipped",
+      reason: "ancestor-stopped",
+      message: "",
+      related: [],
+    };
+    expect(ended(skipped).outcome).toBe("skipped");
+    expect(ended({ kind: "interrupted" }).outcome).toBe("interrupted");
+  });
+
+  it("reads as queued from a submission until the host shows a newer execution", () => {
+    const before = inputs({
+      executions: [execution({ id: "e1" })],
+      results: new Map([["c1", record({ id: "e1" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(before, "c1").status).toBe("queued");
+    expect(cellExecutionView(before, "c1").outcome).toBeNull();
+
+    // The stream let e1 go while the request was in flight; its result remains.
+    const forgotten = inputs({
+      results: new Map([["c1", record({ id: "e1" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(forgotten, "c1").status).toBe("queued");
+
+    const shown = inputs({
+      executions: [
+        execution({ id: "e2", status: "running", completed_at: null }),
+      ],
+      results: new Map([["c1", record({ id: "e1" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(shown, "c1").status).toBe("running");
+
+    const done = inputs({
+      executions: [execution({ id: "e2" })],
+      results: new Map([["c1", record({ id: "e2" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(done, "c1").status).toBe("idle");
+
+    const fresh = inputs({ submissions: new Map([["c1", null]]) });
+    expect(cellExecutionView(fresh, "c1").status).toBe("queued");
+  });
+
+  it("shows a blocked cell as disabled transitively, with its last outcome", () => {
+    const view = cellExecutionView(
+      inputs({
+        results: new Map([["c1", record({ id: "e1" })]]),
+        blocked: new Set(["c1"]),
+      }),
+      "c1",
+    );
+    expect(view.status).toBe("idle");
+    expect(view.blocked).toBe(true);
+    expect(view.outcome).toBe("value");
+  });
+});
+
+describe("notebook-level views", () => {
+  const stream = inputs({
+    executions: [
+      execution({ id: "e1", status: "running", completed_at: null }),
+      execution({
+        id: "e2",
+        cell_id: "c2",
+        status: "queued",
+        started_at: null,
+        completed_at: null,
+      }),
+      execution({ id: "e3", cell_id: "c3" }),
+      execution({
+        id: "s1",
+        cell_id: null,
+        status: "running",
+        completed_at: null,
+      }),
+    ],
+    results: new Map([["c5", record({ id: "e5", cell_id: "c5" })]]),
+    submissions: new Map([
+      ["c2", "e2"],
+      ["c4", null],
+      ["c5", "e5"],
+    ]),
+  });
+
+  it("counts unfinished executions and submissions the host has not shown", () => {
+    expect(anyRunning(stream.executions)).toBe(true);
+    expect(queuedOrRunningCount(stream)).toBe(5);
+    expect(runningCellIds(stream.executions)).toEqual(["c1"]);
+    expect(onlyScratchRunning(stream.executions)).toBe(false);
+  });
+
+  it("tells scratch work apart from cells", () => {
+    const scratch = inputs({
+      executions: [
+        execution({
+          id: "s1",
+          cell_id: null,
+          status: "running",
+          completed_at: null,
+        }),
+        execution({ id: "e3", cell_id: "c3" }),
+      ],
+    });
+    expect(anyRunning(scratch.executions)).toBe(true);
+    expect(onlyScratchRunning(scratch.executions)).toBe(true);
+    expect(queuedOrRunningCount(scratch)).toBe(1);
+  });
+});

package/src/core/executions/atoms.ts

@@ -0,0 +1,228 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** The active notebook's executions and runtime as the editor reads them. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import { atom, type createStore } from "jotai";
+import type { CellMessage } from "@/core/kernel/messages";
+import type {
+  Executions,
+  NotebookReplica,
+  Results,
+} from "@/core/notebook/replica";
+import { activeNotebookReplicaAtom } from "@/core/session/active-notebook";
+import { waitFor } from "@/core/state/jotai";
+import { type CellFreshnessInputs, freshnessOf } from "./freshness";
+import {
+  anyRunning,
+  type CellExecutionInputs,
+  latestExecutionId,
+  queuedOrRunningCount,
+} from "./select";
+
+type Store = ReturnType<typeof createStore>;
+
+const NO_EXECUTIONS: Executions = {
+  runs: new Map(),
+  executions: new Map(),
+  latest: new Map(),
+};
+const NO_RESULTS: Results = new Map();
+const NO_CELLS: ReadonlyMap<Protocol.CellId, Protocol.Cell> = new Map();
+const NO_SUBMISSIONS: ReadonlyMap<
+  Protocol.CellId,
+  Protocol.ExecutionId | null
+> = new Map();
+const NO_BLOCKED: ReadonlySet<Protocol.CellId> = new Set();
+
+/**
+ * What the editor marks about cells of one replica's notebook.
+ *
+ * The marks are keyed by cell id, which another notebook, or the same one
+ * after a reconnect, reuses with different executions behind it. They
+ * therefore count only for the replica and host notebook they belong to.
+ */
+type Marks<T> = {
+  readonly notebook: {
+    readonly replica: NotebookReplica;
+    readonly id: Protocol.NotebookId;
+  };
+  readonly value: T;
+} | null;
+
+/**
+ * Cells a run was requested for, with the execution each had at the time.
+ *
+ * The host shows a queued execution once the kernel plans the run. Until
+ * then the cell reads as queued from this record. The host's newer
+ * execution supersedes it; a rejected request, a cell the kernel will not
+ * run, or the cell leaving the document withdraws it. Written only by
+ * `submitCells`, `withdrawCells`, and `observeCellMessage`.
+ */
+const submissionsAtom =
+  atom<Marks<ReadonlyMap<Protocol.CellId, Protocol.ExecutionId | null>>>(null);
+
+/**
+ * Cells the kernel reports as blocked by a disabled ancestor. Written only
+ * by `observeCellMessage`.
+ *
+ * TODO(MO-8463): Derive from the document and the analysis stream.
+ */
+const blockedCellsAtom = atom<Marks<ReadonlySet<Protocol.CellId>>>(null);
+
+function current<T>(
+  marks: Marks<T>,
+  replica: NotebookReplica | null,
+  notebookId: Protocol.NotebookId | null,
+  empty: T,
+): T {
+  return marks !== null &&
+    marks.notebook.replica === replica &&
+    marks.notebook.id === notebookId
+    ? marks.value
+    : empty;
+}
+
+function mark<T>(store: Store, value: T): Marks<T> {
+  const replica = store.get(activeNotebookReplicaAtom);
+  const notebook = replica === null ? null : store.get(replica.notebookAtom);
+  return replica === null || notebook === null
+    ? null
+    : { notebook: { replica, id: notebook.id }, value };
+}
+
+/** What every cell's view derives from. Pair with `cellExecutionView`. */
+export const cellExecutionInputsAtom = atom((get): CellExecutionInputs => {
+  const replica = get(activeNotebookReplicaAtom);
+  const notebookId =
+    replica === null ? null : (get(replica.notebookAtom)?.id ?? null);
+  return {
+    executions: replica === null ? NO_EXECUTIONS : get(replica.executionsAtom),
+    results: replica === null ? NO_RESULTS : get(replica.resultsAtom),
+    submissions: current(
+      get(submissionsAtom),
+      replica,
+      notebookId,
+      NO_SUBMISSIONS,
+    ),
+    blocked: current(get(blockedCellsAtom), replica, notebookId, NO_BLOCKED),
+  };
+});
+
+const cellFreshnessInputsAtom = atom((get): CellFreshnessInputs => {
+  const replica = get(activeNotebookReplicaAtom);
+  const document = replica === null ? null : get(replica.documentAtom);
+  // Results can arrive before the confirmed document on a snapshot. Until
+  // the document is ready there is nothing to compare them against.
+  if (replica === null || document === null) {
+    return { cells: NO_CELLS, executions: NO_EXECUTIONS, results: NO_RESULTS };
+  }
+  return {
+    cells: document.cells,
+    executions: get(replica.executionsAtom),
+    results: get(replica.resultsAtom),
+  };
+});
+
+/** Freshness by cell id, indexed once per change to its inputs. */
+export const cellFreshnessAtom = atom((get) =>
+  freshnessOf(get(cellFreshnessInputsAtom)),
+);
+
+/** The runtime's status, null while the notebook has none or the stream is not ready. */
+export const runtimeStatusAtom = atom((get) => {
+  const replica = get(activeNotebookReplicaAtom);
+  return replica === null ? null : (get(replica.runtimeAtom)?.status ?? null);
+});
+
+export const notebookIsRunningAtom = atom((get) =>
+  anyRunning(get(cellExecutionInputsAtom).executions),
+);
+
+export const notebookQueuedOrRunningCountAtom = atom((get) =>
+  queuedOrRunningCount(get(cellExecutionInputsAtom)),
+);
+
+/** Resolve once the host reports the runtime running. */
+export async function waitForRuntimeRunning(): Promise<void> {
+  await waitFor(runtimeStatusAtom, (status) => status === "running");
+}
+
+/**
+ * Record a run request for `cellIds` so they read as queued at once.
+ *
+ * Cells blocked by a disabled ancestor stay blocked: the kernel will not
+ * queue them. A disabled cell is not queued either; the caller leaves it
+ * out, since its configuration lives in the notebook state.
+ */
+export function submitCells(
+  store: Store,
+  cellIds: readonly Protocol.CellId[],
+): void {
+  const inputs = store.get(cellExecutionInputsAtom);
+  const next = new Map(inputs.submissions);
+  for (const cellId of cellIds) {
+    if (!inputs.blocked.has(cellId)) {
+      next.set(cellId, latestExecutionId(inputs, cellId));
+    }
+  }
+  setSubmissions(store, next);
+}
+
+function setSubmissions(
+  store: Store,
+  value: ReadonlyMap<Protocol.CellId, Protocol.ExecutionId | null>,
+): void {
+  store.set(submissionsAtom, mark(store, value));
+}
+
+/** Forget a run request the host rejected. */
+export function withdrawCells(
+  store: Store,
+  cellIds: readonly Protocol.CellId[],
+): void {
+  const next = new Map(store.get(cellExecutionInputsAtom).submissions);
+  for (const cellId of cellIds) {
+    next.delete(cellId);
+  }
+  setSubmissions(store, next);
+}
+
+function setCellBlocked(
+  store: Store,
+  cellId: Protocol.CellId,
+  blocked: boolean,
+): void {
+  const known = store.get(cellExecutionInputsAtom).blocked;
+  if (known.has(cellId) === blocked) {
+    return;
+  }
+  const next = new Set(known);
+  if (blocked) {
+    next.add(cellId);
+  } else {
+    next.delete(cellId);
+  }
+  store.set(blockedCellsAtom, mark(store, next));
+}
+
+/**
+ * Keep the blocked set and the submissions in step with a cell-op.
+ *
+ * A status names whether the cell is blocked. A blocked cell and one whose
+ * output is an error will not run, so a submission that never became an
+ * execution is withdrawn, as it was when the editor set status itself.
+ *
+ * TODO(MO-8407): Delete with the cell-op case. The blocked read goes with
+ * MO-8463, the error read with MO-8346.
+ */
+export function observeCellMessage(store: Store, message: CellMessage): void {
+  const cellId = message.cell_id;
+  const blocked = message.status === "disabled-transitively";
+  if (message.status != null) {
+    setCellBlocked(store, cellId, blocked);
+  }
+  if (blocked || message.output?.mimetype === "application/vnd.marimo+error") {
+    withdrawCells(store, [cellId]);
+  }
+}

package/src/core/executions/freshness.ts

@@ -0,0 +1,171 @@
+/* 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 differs from its pending execution, or its last 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) {
+        // Older runtimes bind nothing here, but a later binding invalidates
+        // the result even if its runtime has since stopped.
+        if (
+          variables.some((v) => {
+            const binder = recordOf(v.execution_id);
+            if (binder === undefined) {
+              return false;
+            }
+            if (binder.runtime_id === record.runtime_id) {
+              return true;
+            }
+            const boundAt = binder.completed_at ?? binder.started_at;
+            return (
+              boundAt !== null &&
+              record.completed_at !== null &&
+              Date.parse(boundAt) > Date.parse(record.completed_at)
+            );
+          })
+        ) {
+          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;
+  }
+
+  /** Compare against pending work before the result it will replace. */
+  function sourceChanged(
+    cell: Protocol.Cell,
+    result: Protocol.Execution,
+  ): boolean {
+    const latest = inputs.executions.latest.get(cell.id);
+    const pending = latest === undefined ? undefined : recordOf(latest);
+    const source =
+      pending !== undefined && pending.status !== "completed"
+        ? pending
+        : result;
+    return cell.code_fingerprint !== source.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 || sourceChanged(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());
+  };
+}