Skip to content

: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.

20.0 KB
Raw Blame
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.')
            }
        },
    })),
])