Preflight checklist
What problem does this solve?
The persistent kernels are a real strength — warm Python, R, and REPL state with durable run history. They also inherit the failure mode that makes notebooks unreproducible in practice: hidden state from out-of-order execution.
A user edits and re-runs cell 3. Cells 5 and 9 consumed the old value of a variable cell 3 defines. Nothing marks them as stale. The session looks consistent, the artifacts look finalized, and the recorded provenance is accurate about what ran while the result no longer reflects what the code now says. It is the single most common way a notebook-based analysis silently becomes wrong, and it is invisible to a run log.
Proposed solution
Deliberately not a reactive runtime. A full marimo-style reactive kernel would replace the execution semantics the artifact lineage is built on, which conflicts with the preservation contract in #917. This proposal gets most of the benefit without touching the kernel.
Add static dependency analysis over the existing linear execution history:
- Build the DAG. Parse each cell for defined and used names (Python via
ast, R via its parser) and derive the dependency graph from the run history that is already recorded.
- Mark staleness. When a cell re-runs, flag every downstream cell whose inputs it redefines: "stale — cell 3 was re-run after this."
- Re-run the affected subgraph on request, in dependency order, rather than making the user reason about it.
- Warn at artifact finalization when an artifact is produced by a run whose upstream cells have since changed. This is the highest-value part: it catches the wrong result before it is published, and it fits naturally alongside the existing reviewer findings.
The kernel, the run history, the artifact store, and provenance capture are all untouched. This is an analysis layer over records that already exist.
Alternatives considered
- Full reactive runtime. The strongest guarantee, and it replaces execution semantics that artifact lineage depends on. Would need a much larger conversation than this issue.
- Force top-to-bottom re-execution. Correct and unusable for analyses with expensive cells, which is most real scientific work.
- Do nothing and document it. The status quo. The failure is silent, so documentation does not reach the person it would help.
Additional context
The dependency graph is reusable: RO-Crate export wants it to express artifact lineage precisely, and parameterized sweeps want it to know which cells a parameter actually affects. Worth building even if staleness marking were the only immediate consumer.
Per CONTRIBUTING, notebook changes are owned by docs/PRD.md §8 and should run npm run typecheck:node plus targeted tests under src/main/notebook/.
Part of #917 (preserve-the-backend blend plan). This proposal is additive: it does not change the ACP runtime, artifact/provenance store, notebook execution semantics, or the Prisma schema.
Preflight checklist
What problem does this solve?
The persistent kernels are a real strength — warm Python, R, and REPL state with durable run history. They also inherit the failure mode that makes notebooks unreproducible in practice: hidden state from out-of-order execution.
A user edits and re-runs cell 3. Cells 5 and 9 consumed the old value of a variable cell 3 defines. Nothing marks them as stale. The session looks consistent, the artifacts look finalized, and the recorded provenance is accurate about what ran while the result no longer reflects what the code now says. It is the single most common way a notebook-based analysis silently becomes wrong, and it is invisible to a run log.
Proposed solution
Deliberately not a reactive runtime. A full marimo-style reactive kernel would replace the execution semantics the artifact lineage is built on, which conflicts with the preservation contract in #917. This proposal gets most of the benefit without touching the kernel.
Add static dependency analysis over the existing linear execution history:
ast, R via its parser) and derive the dependency graph from the run history that is already recorded.The kernel, the run history, the artifact store, and provenance capture are all untouched. This is an analysis layer over records that already exist.
Alternatives considered
Additional context
The dependency graph is reusable: RO-Crate export wants it to express artifact lineage precisely, and parameterized sweeps want it to know which cells a parameter actually affects. Worth building even if staleness marking were the only immediate consumer.
Per CONTRIBUTING, notebook changes are owned by
docs/PRD.md§8 and should runnpm run typecheck:nodeplus targeted tests undersrc/main/notebook/.Part of #917 (preserve-the-backend blend plan). This proposal is additive: it does not change the ACP runtime, artifact/provenance store, notebook execution semantics, or the Prisma schema.