:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { MakeLogicType, actions, kea, key, listeners, path, props, reducers, selectors } from 'kea'
import { JSONContent } from 'lib/components/RichContentEditor/types'
import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
import {
NotebookDependencyGraph,
buildNotebookDependencyGraph,
collectDependencyNodeIds,
} from '../Nodes/notebookNodeContent'
import { NotebookNodeType } from '../types'
import { cellReadsNotebookVariable } from './notebookVariables'
export type NotebookNodeRunTerminalStatus = 'done' | 'failed' | 'interrupted'
/** Why a cell's stored result no longer reflects the notebook — drives the stale banner's wording. */
export type NotebookStaleReason = 'upstream' | 'variable'
export interface NotebookNodeStalenessLogicProps {
shortId: string
}
const V2_NODE_TYPES: string[] = [NotebookNodeType.SQLV2, NotebookNodeType.PythonV2]
/**
* Cells whose last result no longer reflects the notebook's variables: the ones that read a
* changed variable, plus everything transitively downstream of them (their inputs are now stale
* too). Same shape as `staleDownstreamNodeIds`, but rooted in a variable rather than a run.
*/
const variableDependentNodeIds = (graph: NotebookDependencyGraph, variableNames: string[]): string[] => {
const readers = graph.nodes.filter(
(node) =>
V2_NODE_TYPES.includes(node.nodeType) &&
variableNames.some((name) => cellReadsNotebookVariable(node.code ?? '', node.nodeType, name))
)
const affected = new Set<string>()
for (const reader of readers) {
for (const nodeId of collectDependencyNodeIds(graph, reader.nodeId, 'downstream')) {
affected.add(nodeId)
}
}
return graph.nodes
.filter((node) => affected.has(node.nodeId) && V2_NODE_TYPES.includes(node.nodeType))
.map((node) => node.nodeId)
}
const staleDownstreamNodeIds = (graph: NotebookDependencyGraph, nodeId: string): string[] => {
const downstream = collectDependencyNodeIds(graph, nodeId, 'downstream')
downstream.delete(nodeId)
// Only V2 cells participate: legacy cells have their own freshness system, and the
// chain runner only knows how to dispatch V2 runs.
return graph.nodes
.filter((node) => downstream.has(node.nodeId) && V2_NODE_TYPES.includes(node.nodeType))
.map((node) => node.nodeId)
}
// Stale V2 cells the chain can actually run, in document order (which is dependency order).
// Restricting to registered (mounted) cells matters: a dispatch to an unmounted cell is picked
// up by nobody, which would leave the chain queue wedged forever.
const runnableStaleNodeIds = (
graph: NotebookDependencyGraph,
staleNodeIds: Record<string, NotebookStaleReason>,
mountedNodeIds: Record<string, true>
): string[] =>
graph.nodes
.filter(
(node) => V2_NODE_TYPES.includes(node.nodeType) && staleNodeIds[node.nodeId] && mountedNodeIds[node.nodeId]
)
.map((node) => node.nodeId)
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeStalenessLogicValues {
chainQueue: string[]
chainRootNodeId: string | null
isChainRunning: boolean
lastRunDownstreamNodeIds: string[]
lastRunNodeId: string | null
lastRunStaleDownstreamNodeIds: string[]
mountedNodeIds: Record<string, true>
nodeRunStatuses: Record<string, NotebookNodeRunTerminalStatus>
staleCount: number
staleNodeIds: Record<string, NotebookStaleReason>
widgetDataChainCompletedNodeIds: string[]
widgetDataChainNodeIds: string[]
}
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeStalenessLogicActions {
abortChain: (reason: string | null) => {
reason: string | null
}
adoptChainRun: (
nodeId: string,
runId: string
) => {
nodeId: string
runId: string
}
clearNodeStale: (nodeId: string) => {
nodeId: string
}
dispatchChainRun: (nodeId: string) => {
nodeId: string
}
markStaleNodeIds: (
nodeIds: string[],
reason?: NotebookStaleReason
) => {
nodeIds: string[]
reason: NotebookStaleReason
}
nodeRunFinished: (
nodeId: string,
status: NotebookNodeRunTerminalStatus,
content: JSONContent | null
) => {
content: JSONContent | null
nodeId: string
status: NotebookNodeRunTerminalStatus
}
registerChainNode: (nodeId: string) => {
nodeId: string
}
runStaleChain: (
content: JSONContent | null,
rootNodeId?: string | null
) => {
content: JSONContent | null
rootNodeId: string | null
}
runWidgetDataChain: (
content: JSONContent | null,
nodeIds: string[]
) => {
content: JSONContent | null
nodeIds: string[]
}
setChainQueue: (nodeIds: string[]) => {
nodeIds: string[]
}
setChainRoot: (nodeId: string | null) => {
nodeId: string | null
}
setLastRun: (
nodeId: string,
downstreamNodeIds: string[]
) => {
downstreamNodeIds: string[]
nodeId: string
}
setWidgetDataChainCompletedNodeIds: (nodeIds: string[]) => {
nodeIds: string[]
}
setWidgetDataChainNodeIds: (nodeIds: string[]) => {
nodeIds: string[]
}
unregisterChainNode: (nodeId: string) => {
nodeId: string
}
variablesChanged: (
variableNames: string[],
content: JSONContent | null
) => {
content: JSONContent | null
variableNames: string[]
}
widgetDataChainFinished: (nodeIds: string[]) => {
nodeIds: string[]
}
}
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeStalenessLogicMeta {
key: string
__keaTypeGenInternalSelectorTypes: {
staleCount: (staleNodeIds: Record<string, NotebookStaleReason>) => number
isChainRunning: (chainQueue: string[]) => boolean
lastRunStaleDownstreamNodeIds: (
lastRunDownstreamNodeIds: string[],
staleNodeIds: Record<string, NotebookStaleReason>
) => string[]
}
}
export type notebookNodeStalenessLogicType = MakeLogicType<
notebookNodeStalenessLogicValues,
notebookNodeStalenessLogicActions,
NotebookNodeStalenessLogicProps,
notebookNodeStalenessLogicMeta
>
/**
* Journey 10: UI-only staleness for revamped (SQLV2/PythonV2) cells, plus the chain runner.
*
* When a cell's run lands, every transitive dependent is marked stale (its result now derives
* from outdated data). "Run stale cells" re-runs the stale set in document order — which IS
* dependency order, because a cell can only reference exports of earlier cells. Runs go
* through each cell's own notebookNodeSQLV2Logic (the node logics listen for
* `dispatchChainRun`), so operation serialization, polling, and interrupt all apply per link.
* Flags are session-local by design (walkthrough decision: UI-only, no backend call).
*/
export const notebookNodeStalenessLogic = kea<notebookNodeStalenessLogicType>([
path((key) => ['scenes', 'notebooks', 'Notebook', 'notebookNodeStalenessLogic', key]),
props({} as NotebookNodeStalenessLogicProps),
key((props) => props.shortId),
actions({
// Reported by every V2 node logic from each of its run's terminal paths, whether the
// run was user-clicked or chain-dispatched. `content` rides along on success so the
// downstream set is computed against the document as it was when the result landed.
nodeRunFinished: (nodeId: string, status: NotebookNodeRunTerminalStatus, content: JSONContent | null) => ({
nodeId,
status,
content,
}),
markStaleNodeIds: (nodeIds: string[], reason: NotebookStaleReason = 'upstream') => ({ nodeIds, reason }),
clearNodeStale: (nodeId: string) => ({ nodeId }),
// With a rootNodeId the chain is scoped to that cell's transitive downstream (the
// "run downstream cells" button on the cell that just ran); without one it runs
// every stale cell in the notebook.
runStaleChain: (content: JSONContent | null, rootNodeId: string | null = null) => ({ content, rootNodeId }),
runWidgetDataChain: (content: JSONContent | null, nodeIds: string[]) => ({ content, nodeIds }),
// Consumed by the matching notebookNodeSQLV2Logic, which builds refs and runs itself.
dispatchChainRun: (nodeId: string) => ({ nodeId }),
// A run the backend started for this cell, as part of a whole-notebook run. The
// matching cell adopts it and polls it as if it had dispatched it itself.
adoptChainRun: (nodeId: string, runId: string) => ({ nodeId, runId }),
setChainQueue: (nodeIds: string[]) => ({ nodeIds }),
setChainRoot: (nodeId: string | null) => ({ nodeId }),
setLastRun: (nodeId: string, downstreamNodeIds: string[]) => ({ nodeId, downstreamNodeIds }),
abortChain: (reason: string | null) => ({ reason }),
setWidgetDataChainNodeIds: (nodeIds: string[]) => ({ nodeIds }),
setWidgetDataChainCompletedNodeIds: (nodeIds: string[]) => ({ nodeIds }),
widgetDataChainFinished: (nodeIds: string[]) => ({ nodeIds }),
// Called by every V2 node logic on mount/unmount so the chain only ever dispatches
// to a cell whose logic is mounted and listening.
registerChainNode: (nodeId: string) => ({ nodeId }),
unregisterChainNode: (nodeId: string) => ({ nodeId }),
// A notebook variable was added, renamed, retyped, given a new value, or deleted.
// Reported by the Variables block; `content` is the document the change produced.
variablesChanged: (variableNames: string[], content: JSONContent | null) => ({ variableNames, content }),
}),
reducers({
staleNodeIds: [
{} as Record<string, NotebookStaleReason>,
{
markStaleNodeIds: (state, { nodeIds, reason }) => {
if (!nodeIds.length) {
return state
}
const next = { ...state }
nodeIds.forEach((nodeId) => {
next[nodeId] = reason
})
return next
},
clearNodeStale: (state, { nodeId }) => {
if (!(nodeId in state)) {
return state
}
const next = { ...state }
delete next[nodeId]
return next
},
},
],
// Stale cells still to run; the head is the one currently running.
chainQueue: [
[] as string[],
{
setChainQueue: (_, { nodeIds }) => nodeIds,
abortChain: () => [],
widgetDataChainFinished: () => [],
},
],
// The cell whose "run downstream cells" started the active chain; scopes the queue
// rebuild so unrelated stale cells are left alone.
chainRootNodeId: [
null as string | null,
{
setChainRoot: (_, { nodeId }) => nodeId,
abortChain: () => null,
widgetDataChainFinished: () => null,
},
],
// The last cell whose run landed, and the downstream set that run marked stale.
// Drives the "run downstream cells" affordance on that cell.
lastRunNodeId: [
null as string | null,
{
setLastRun: (_, { nodeId }) => nodeId,
},
],
lastRunDownstreamNodeIds: [
[] as string[],
{
setLastRun: (_, { downstreamNodeIds }) => downstreamNodeIds,
},
],
// How each cell's last run ended, so the cell's gutter can show the outcome. Session-local
// like the stale flags: a reload falls back to whether the cell has a persisted result.
nodeRunStatuses: [
{} as Record<string, NotebookNodeRunTerminalStatus>,
{
nodeRunFinished: (state, { nodeId, status }) => ({ ...state, [nodeId]: status }),
},
],
mountedNodeIds: [
{} as Record<string, true>,
{
registerChainNode: (state, { nodeId }) => ({ ...state, [nodeId]: true as const }),
unregisterChainNode: (state, { nodeId }) => {
if (!(nodeId in state)) {
return state
}
const next = { ...state }
delete next[nodeId]
return next
},
},
],
widgetDataChainNodeIds: [
[] as string[],
{
setWidgetDataChainNodeIds: (_, { nodeIds }) => nodeIds,
abortChain: () => [],
widgetDataChainFinished: () => [],
},
],
widgetDataChainCompletedNodeIds: [
[] as string[],
{
setWidgetDataChainCompletedNodeIds: (_, { nodeIds }) => nodeIds,
setWidgetDataChainNodeIds: () => [],
abortChain: () => [],
widgetDataChainFinished: () => [],
},
],
}),
selectors({
staleCount: [
(s) => [s.staleNodeIds],
(staleNodeIds: Record<string, NotebookStaleReason>): number => Object.keys(staleNodeIds).length,
],
isChainRunning: [(s) => [s.chainQueue], (chainQueue: string[]): boolean => chainQueue.length > 0],
// The still-stale part of the last run's downstream; empties as cells re-run, which
// is what hides the "run downstream cells" button once everything is fresh again.
lastRunStaleDownstreamNodeIds: [
(s) => [s.lastRunDownstreamNodeIds, s.staleNodeIds],
(lastRunDownstreamNodeIds: string[], staleNodeIds: Record<string, NotebookStaleReason>): string[] =>
lastRunDownstreamNodeIds.filter((nodeId) => staleNodeIds[nodeId]),
],
}),
listeners(({ actions, values }) => ({
nodeRunFinished: ({ nodeId, status, content }) => {
if (status === 'done') {
actions.clearNodeStale(nodeId)
const downstream = content ? staleDownstreamNodeIds(buildNotebookDependencyGraph(content), nodeId) : []
actions.markStaleNodeIds(downstream)
actions.setLastRun(nodeId, downstream)
}
if (values.chainQueue[0] !== nodeId) {
return
}
if (status !== 'done') {
actions.abortChain(nodeId)
return
}
const completedWidgetNodeIds = values.widgetDataChainNodeIds.length
? Array.from(new Set([...values.widgetDataChainCompletedNodeIds, nodeId]))
: []
if (completedWidgetNodeIds.length) {
actions.setWidgetDataChainCompletedNodeIds(completedWidgetNodeIds)
}
// Rebuild the queue from the live stale set instead of shifting the snapshot:
// cells marked stale while the chain ran (including by this very run) join in,
// and cells deleted or unmounted while queued drop out rather than receiving a
// dispatch nobody picks up. A rooted chain stays scoped to the root's downstream
// so unrelated stale cells are never run by it.
const graph = content ? buildNotebookDependencyGraph(content) : null
let queue = graph ? runnableStaleNodeIds(graph, values.staleNodeIds, values.mountedNodeIds) : []
if (graph && values.chainRootNodeId) {
const scope = collectDependencyNodeIds(graph, values.chainRootNodeId, 'downstream')
queue = queue.filter((queuedNodeId) => scope.has(queuedNodeId))
} else if (values.widgetDataChainNodeIds.length) {
const scope = new Set(values.widgetDataChainNodeIds)
queue = queue.filter((queuedNodeId) => scope.has(queuedNodeId))
}
actions.setChainQueue(queue)
if (queue.length) {
actions.dispatchChainRun(queue[0])
} else if (values.widgetDataChainNodeIds.length) {
const availableNodeIds = new Set(graph?.nodes.map((node) => node.nodeId) ?? [])
const completedNodeIds = new Set(completedWidgetNodeIds)
const missingNodeId = values.widgetDataChainNodeIds.find(
(widgetNodeId) =>
!availableNodeIds.has(widgetNodeId) ||
!values.mountedNodeIds[widgetNodeId] ||
!completedNodeIds.has(widgetNodeId)
)
if (missingNodeId) {
actions.abortChain(missingNodeId)
} else {
actions.widgetDataChainFinished(values.widgetDataChainNodeIds)
}
} else {
actions.setChainRoot(null)
lemonToast.success('Stale cells re-run.')
}
},
runStaleChain: ({ content, rootNodeId }) => {
if (values.isChainRunning) {
lemonToast.info('Stale cells are already being re-run.')
return
}
if (!content) {
return
}
const graph = buildNotebookDependencyGraph(content)
let queue = runnableStaleNodeIds(graph, values.staleNodeIds, values.mountedNodeIds)
if (rootNodeId) {
const scope = collectDependencyNodeIds(graph, rootNodeId, 'downstream')
queue = queue.filter((queuedNodeId) => scope.has(queuedNodeId))
}
if (!queue.length) {
lemonToast.info('No stale cells to run.')
return
}
actions.setWidgetDataChainNodeIds([])
actions.setChainRoot(rootNodeId)
actions.setChainQueue(queue)
actions.dispatchChainRun(queue[0])
},
runWidgetDataChain: ({ content, nodeIds }) => {
if (values.isChainRunning) {
lemonToast.info('Notebook data cells are already being re-run.')
return
}
if (!content || !nodeIds.length) {
return
}
const graph = buildNotebookDependencyGraph(content)
const requestedNodeIds = new Set(nodeIds)
const requestedNodes = graph.nodes.filter(
(node) => V2_NODE_TYPES.includes(node.nodeType) && requestedNodeIds.has(node.nodeId)
)
const allRequestedNodesAreMounted =
requestedNodes.length === requestedNodeIds.size &&
requestedNodes.every((node) => values.mountedNodeIds[node.nodeId])
if (!allRequestedNodesAreMounted) {
lemonToast.info(
'Some connected data cells are not available. Scroll through the notebook and try again.'
)
actions.abortChain(null)
return
}
const queue = requestedNodes.map((node) => node.nodeId)
actions.markStaleNodeIds(queue)
actions.setChainRoot(null)
actions.setWidgetDataChainNodeIds(queue)
actions.setChainQueue(queue)
actions.dispatchChainRun(queue[0])
},
widgetDataChainFinished: () => {
lemonToast.success('Widget data refreshed.')
},
variablesChanged: ({ variableNames, content }) => {
if (!variableNames.length || !content) {
return
}
actions.markStaleNodeIds(
variableDependentNodeIds(buildNotebookDependencyGraph(content), variableNames),
'variable'
)
},
abortChain: ({ reason }) => {
if (reason) {
lemonToast.warning('Stopped re-running stale cells: a cell did not finish successfully.')
}
},
})),
])