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.

47.6 KB
Raw Blame
import {
    MakeLogicType,
    actions,
    afterMount,
    beforeUnmount,
    connect,
    kea,
    key,
    listeners,
    path,
    props,
    reducers,
    selectors,
} from 'kea'
import posthog from 'posthog-js'

import api from 'lib/api'
import { ApiError } from 'lib/api-error'
import { JSONContent } from 'lib/components/RichContentEditor/types'
import { FEATURE_FLAGS } from 'lib/constants'
import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
import { FeatureFlagsSet, featureFlagLogic } from 'lib/logic/featureFlagLogic'

import { notebookResultPreview } from 'products/notebooks/notebookResultPreview'

import { notebookJupyterLogic } from '../Notebook/notebookJupyterLogic'
import { notebookKernelInfoLogic } from '../Notebook/notebookKernelInfoLogic'
import {
    NotebookNodeRunTerminalStatus,
    NotebookStaleReason,
    notebookNodeStalenessLogic,
} from '../Notebook/notebookNodeStalenessLogic'
import { NotebookOperation, notebookOperationsLogic } from '../Notebook/notebookOperationsLogic'
import { notebookSettingsLogic } from '../Notebook/notebookSettingsLogic'
import { NotebookVariable } from '../Notebook/notebookVariables'
import { sandboxStartMessage } from '../Notebook/SandboxStartMessage'
import { NotebookNodeType } from '../types'
import {
    buildNotebookDependencyGraph,
    collectNotebookDataframeNodes,
    extractDuckSqlTables,
} from './notebookNodeContent'
import { NotebookNodeSQLV2Result } from './NotebookNodeSQLV2'

export type SqlV2RunRef = {
    node_id: string
    // 'hogql' is a SQL node's query definition; 'local' is a dataframe a Python cell bound in
    // the kernel namespace. The backend routes a SQL run to ClickHouse or the sandbox's DuckDB
    // based on which kinds the query actually references.
    kind: 'hogql' | 'local'
}

// Turn a run/result request failure into a message the user can act on. The browser endpoints
// render every 404 as DRF's generic {"detail": "Not found."}, so the response can't say what is
// gone — the caller does, via notFoundKind: a run dispatch that 404s means the notebook itself is
// gone, while a result poll or page fetch that 404s means that run's result is gone. Every other
// failure keeps its original message.
export function sqlV2RunErrorMessage(
    error: unknown,
    fallback: string,
    notFoundKind: 'notebook' | 'result' = 'result'
): string {
    if (error instanceof ApiError && error.status === 404) {
        return notFoundKind === 'notebook'
            ? 'This notebook could not be found. It may have been deleted.'
            : 'This query result is no longer available. Run the cell again.'
    }
    return error instanceof Error ? error.message : fallback
}

// Map every sibling cell's dataframe name -> {node id, kind}, excluding the running node itself.
// SQLV2 siblings delegate to collectSqlV2Nodes so duplicate names get the same disambiguated
// form the dependency graph shows (sql_df, sql_df_2, …) — raw attributes would let a later
// duplicate silently shadow the node the user actually referenced. Python siblings contribute
// their returnVariable verbatim (it IS the kernel variable); on a name collision the SQL ref
// wins, since SQL names are already disambiguated in the UI and kernel variables are not.
// The backend resolves each referenced hogql node to its last-run query — the frontend only
// supplies the wiring.
export function collectSqlV2Refs(doc: JSONContent | null | undefined, selfNodeId: string): Record<string, SqlV2RunRef> {
    const refs: Record<string, SqlV2RunRef> = {}
    for (const { node, nodeId, exportedName } of collectNotebookDataframeNodes(doc)) {
        if (nodeId !== selfNodeId && exportedName) {
            refs[exportedName] = { node_id: nodeId, kind: node.type === NotebookNodeType.PythonV2 ? 'local' : 'hogql' }
        }
    }
    return refs
}

// How often the poller re-checks a run, by how long it already waited. A cell that
// materializes a large frame can legitimately run for many minutes, and a flat one-second
// cadence across that window costs hundreds of requests for a single cell, so the interval
// widens once nobody is plausibly still watching the first result land.
const POLL_INTERVAL_STEPS_MS = [
    { afterMs: 120_000, intervalMs: 5_000 },
    { afterMs: 30_000, intervalMs: 2_000 },
    { afterMs: 0, intervalMs: 1_000 },
]

export function pollIntervalMs(waitedMs: number): number {
    return POLL_INTERVAL_STEPS_MS.find(({ afterMs }) => waitedMs >= afterMs)?.intervalMs ?? 1_000
}

// Must outlast every backend run budget, so the client reports the run's real outcome rather
// than inventing one. The backend expires a stalled run itself, and a kernel cell may execute
// for up to 6 hours. Under that, a run the backend goes on to finish still reads here as a
// client timeout, and the cell renders as errored while the server is still working on it.
export const MAX_POLL_WAIT_MS = 7 * 60 * 60 * 1000

export const SQL_V2_DEFAULT_PAGE_SIZE = 50

export type NotebookNodeSQLV2Page = {
    columns: string[]
    types: [string, string][]
    rows: (string | number | null)[][]
    has_more: boolean
}

// The full capped row set a direct (ClickHouse, no-sandbox) run returns with its result,
// held in memory for client-side paging — never persisted into the document.
export type NotebookNodeSQLV2DirectRows = {
    columns: string[]
    types: [string, string][]
    rows: (string | number | null)[][]
}

export interface RunQueryOptions {
    nodeType?: 'hogql' | 'python'
    outputName?: string
    // SQL cells only: the data source to run against instead of PostHog, and whether to send the
    // code to it verbatim. Absent means PostHog's own ClickHouse.
    connectionId?: string | null
    sendRawQuery?: boolean
}

// What an open editor holds right now, for the callers that can read it — the document only
// catches up to a keystroke or a just-picked connection on a later render.
export interface RunNodeOverrides {
    code?: string
    connectionId?: string | null
    sendRawQuery?: boolean
}

export interface NotebookNodeSQLV2LogicProps {
    nodeId: string
    notebookShortId: string
    // Current node attributes, so a fresh mount can recover an in-flight/finished run by its runId.
    runId?: string | null
    hasResult?: boolean
    hasResultMetadata?: boolean
    prepareInsightDataframes?: (code: string, nodeType: 'python' | 'hogql') => Promise<void>
    updateAttributes: (attrs: {
        nodeId?: string
        returnVariable?: string
        runId?: string | null
        result?: NotebookNodeSQLV2Result | null
        runStatus?: NotebookNodeRunTerminalStatus | null
    }) => void
    // The live notebook document, for staleness marking and chain-dispatched runs (Journey 10).
    getContent?: () => JSONContent | null
    // The notebook's variables, already filtered to the valid ones. A notebook property rather
    // than document content, so it does not come out of getContent.
    getVariables?: () => NotebookVariable[]
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeSQLV2LogicValues {
    featureFlags: FeatureFlagsSet // featureFlagLogic
    isJupyterModeActive: boolean // notebookJupyterLogic
    chainQueue: string[] // notebookNodeStalenessLogic
    isChainRunning: boolean // notebookNodeStalenessLogic
    lastRunNodeId: string | null // notebookNodeStalenessLogic
    lastRunStaleDownstreamNodeIds: string[] // notebookNodeStalenessLogic
    staleNodeIds: Record<string, NotebookStaleReason> // notebookNodeStalenessLogic
    activeOperation: NotebookOperation | null // notebookOperationsLogic
    isBusy: boolean // notebookOperationsLogic
    runQueue: string[] // notebookOperationsLogic
    directRows: NotebookNodeSQLV2DirectRows | null
    isInterrupting: boolean
    isQueued: boolean
    isRestoringResult: boolean
    isRunning: boolean
    isSandboxComputeFree: boolean
    isStale: boolean
    operationBlockReason: string | null
    page: number
    pageLoading: boolean
    pageResult: NotebookNodeSQLV2Page | null
    pageSize: number
    pendingKernelStart: boolean
    result: NotebookNodeSQLV2Result | null
    resultRestoreUnavailable: boolean
    runError: string | null
    staleDownstreamCount: number
    staleReason: NotebookStaleReason | null
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeSQLV2LogicActions {
    adoptChainRun: (
        nodeId: string,
        runId: string
    ) => {
        nodeId: string
        runId: string
    } // notebookNodeStalenessLogic
    dispatchChainRun: (nodeId: string) => {
        nodeId: string
    } // notebookNodeStalenessLogic
    nodeRunFinished: (
        nodeId: string,
        status: NotebookNodeRunTerminalStatus,
        content: JSONContent | null
    ) => {
        content: JSONContent | null
        nodeId: string
        status: NotebookNodeRunTerminalStatus
    } // notebookNodeStalenessLogic
    registerChainNode: (nodeId: string) => {
        nodeId: string
    } // notebookNodeStalenessLogic
    runStaleChain: (
        content: JSONContent | null,
        rootNodeId?: string | null | undefined
    ) => {
        content: JSONContent | null
        rootNodeId: string | null
    } // notebookNodeStalenessLogic
    unregisterChainNode: (nodeId: string) => {
        nodeId: string
    } // notebookNodeStalenessLogic
    dequeueRun: (nodeId: string) => {
        nodeId: string
    } // notebookOperationsLogic
    enqueueRun: (nodeId: string) => {
        nodeId: string
    } // notebookOperationsLogic
    finishNodeOperations: (nodeId: string) => {
        nodeId: string
    } // notebookOperationsLogic
    finishOperation: (id: string) => {
        id: string
    } // notebookOperationsLogic
    releaseQueuedRun: (nodeId: string) => {
        nodeId: string
    } // notebookOperationsLogic
    settleReleasedRun: (nodeId: string) => {
        nodeId: string
    } // notebookOperationsLogic
    startOperation: (operation: NotebookOperation) => {
        operation: NotebookOperation
    } // notebookOperationsLogic
    setShowKernelInfo: (showKernelInfo: boolean) => {
        showKernelInfo: boolean
    } // notebookSettingsLogic
    announceSandboxStart: (hourlyPrice: number | null) => {
        hourlyPrice: number | null
    }
    interruptRun: () => {
        value: true
    }
    pollResult: (runId: string) => {
        runId: string
    }
    resetPaging: () => {
        value: true
    }
    resultRestoreFailed: () => {
        value: true
    }
    runNode: (overrides?: RunNodeOverrides) => {
        overrides: RunNodeOverrides
    }
    runQuery: (
        code: string,
        refs?: Record<string, SqlV2RunRef>,
        opts?: RunQueryOptions
    ) => {
        code: string
        opts: RunQueryOptions
        refs: Record<string, SqlV2RunRef>
    }
    setDirectRows: (directRows: NotebookNodeSQLV2DirectRows | null) => {
        directRows: NotebookNodeSQLV2DirectRows | null
    }
    setIsInterrupting: (isInterrupting: boolean) => {
        isInterrupting: boolean
    }
    setIsRunning: (isRunning: boolean) => {
        isRunning: boolean
    }
    setPage: (page: number) => {
        page: number
    }
    setPageLoading: (pageLoading: boolean) => {
        pageLoading: boolean
    }
    setPageResult: (pageResult: NotebookNodeSQLV2Page | null) => {
        pageResult: NotebookNodeSQLV2Page | null
    }
    setPageSize: (pageSize: number) => {
        pageSize: number
    }
    setPendingKernelStart: (pendingKernelStart: boolean) => {
        pendingKernelStart: boolean
    }
    setResult: (result: NotebookNodeSQLV2Result | null) => {
        result: NotebookNodeSQLV2Result | null
    }
    setRunError: (runError: string | null) => {
        runError: string | null
    }
    startPolling: (
        runId: string,
        restoring?: boolean
    ) => {
        restoring: boolean
        runId: string
    }
    stopPolling: () => {
        value: true
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeSQLV2LogicMeta {
    key: string
    __keaTypeGenInternalSelectorTypes: {
        isSandboxComputeFree: (featureFlags: FeatureFlagsSet) => boolean
        isQueued: (runQueue: string[]) => boolean
        operationBlockReason: (activeOperation: NotebookOperation | null) => string | null
        isStale: (staleNodeIds: Record<string, NotebookStaleReason>) => boolean
        staleReason: (staleNodeIds: Record<string, NotebookStaleReason>) => NotebookStaleReason | null
        staleDownstreamCount: (lastRunNodeId: string | null, lastRunStaleDownstreamNodeIds: string[]) => number
    }
}

export type notebookNodeSQLV2LogicType = MakeLogicType<
    notebookNodeSQLV2LogicValues,
    notebookNodeSQLV2LogicActions,
    NotebookNodeSQLV2LogicProps,
    notebookNodeSQLV2LogicMeta
>

export const notebookNodeSQLV2Logic = kea<notebookNodeSQLV2LogicType>([
    path((key) => ['scenes', 'notebooks', 'Nodes', 'notebookNodeSQLV2Logic', key]),
    props({} as NotebookNodeSQLV2LogicProps),
    key((props) => props.nodeId),
    connect((props: NotebookNodeSQLV2LogicProps) => ({
        values: [
            featureFlagLogic,
            ['featureFlags'],
            notebookOperationsLogic({ shortId: props.notebookShortId }),
            ['activeOperation', 'isBusy', 'runQueue'],
            notebookJupyterLogic({ shortId: props.notebookShortId }),
            ['isActive as isJupyterModeActive'],
            notebookNodeStalenessLogic({ shortId: props.notebookShortId }),
            ['staleNodeIds', 'chainQueue', 'isChainRunning', 'lastRunNodeId', 'lastRunStaleDownstreamNodeIds'],
        ],
        actions: [
            notebookOperationsLogic({ shortId: props.notebookShortId }),
            [
                'startOperation',
                'finishOperation',
                'finishNodeOperations',
                'enqueueRun',
                'dequeueRun',
                'releaseQueuedRun',
                'settleReleasedRun',
            ],
            notebookNodeStalenessLogic({ shortId: props.notebookShortId }),
            [
                'nodeRunFinished',
                'dispatchChainRun',
                'adoptChainRun',
                'runStaleChain',
                'registerChainNode',
                'unregisterChainNode',
            ],
            notebookSettingsLogic,
            ['setShowKernelInfo'],
        ],
    })),
    actions({
        setResult: (result: NotebookNodeSQLV2Result | null) => ({ result }),
        // refs maps each named sibling cell's dataframe name to {node id, kind}. A SQL node
        // inlines referenced hogql refs as CTEs (Journey 3) — or runs locally in DuckDB when
        // it references a local frame (Journey 5); a python node materializes the hogql refs
        // its code reads as pandas frames (Journey 4).
        runQuery: (code: string, refs: Record<string, SqlV2RunRef> = {}, opts: RunQueryOptions = {}) => ({
            code,
            refs,
            opts,
        }),
        // Run this cell the way its own Run button does, deriving the code, the refs and the run
        // options from the live document rather than from the caller. The single entry point for
        // every run trigger — the toolbar button, Cmd+Enter, a chain dispatch — so a cell runs the
        // same way whether or not its editor is on screen.
        runNode: (overrides: RunNodeOverrides = {}) => ({ overrides }),
        startPolling: (runId: string, restoring: boolean = false) => ({ runId, restoring }),
        resultRestoreFailed: true,
        pollResult: (runId: string) => ({ runId }),
        stopPolling: true,
        interruptRun: true,
        setIsInterrupting: (isInterrupting: boolean) => ({ isInterrupting }),
        setIsRunning: (isRunning: boolean) => ({ isRunning }),
        setRunError: (runError: string | null) => ({ runError }),
        setPage: (page: number) => ({ page }),
        setPageSize: (pageSize: number) => ({ pageSize }),
        setPageResult: (pageResult: NotebookNodeSQLV2Page | null) => ({ pageResult }),
        setPageLoading: (pageLoading: boolean) => ({ pageLoading }),
        resetPaging: true,
        setDirectRows: (directRows: NotebookNodeSQLV2DirectRows | null) => ({ directRows }),
        setPendingKernelStart: (pendingKernelStart: boolean) => ({ pendingKernelStart }),
        announceSandboxStart: (hourlyPrice: number | null) => ({ hourlyPrice }),
    }),
    reducers({
        isRestoringResult: [
            false,
            { startPolling: (_, { restoring }) => restoring, stopPolling: () => false, runQuery: () => false },
        ],
        resultRestoreUnavailable: [
            false,
            { resultRestoreFailed: () => true, runQuery: () => false, startPolling: () => false },
        ],
        result: [
            null as NotebookNodeSQLV2Result | null,
            {
                runQuery: () => null,
                setResult: (_, { result }) => result,
            },
        ],
        // Tracks the run being in progress; driven by the run's status, not a socket lifecycle.
        isRunning: [
            false,
            {
                runQuery: () => true,
                startPolling: (_, { restoring }) => !restoring,
                setIsRunning: (_, { isRunning }) => isRunning,
            },
        ],
        runError: [
            null as string | null,
            {
                runQuery: () => null,
                startPolling: () => null,
                setRunError: (_, { runError }) => runError,
            },
        ],
        // The interrupt POST (or the wait for its effect) is in flight; guards the Cancel
        // button against double submission; any terminal poll state resets it.
        isInterrupting: [
            false,
            {
                interruptRun: () => true,
                setIsInterrupting: (_, { isInterrupting }) => isInterrupting,
                stopPolling: () => false,
                runQuery: () => false,
            },
        ],
        page: [
            1,
            {
                setPage: (_, { page }) => Math.max(1, page),
                setPageSize: () => 1,
                resetPaging: () => 1,
                runQuery: () => 1,
            },
        ],
        pageSize: [
            SQL_V2_DEFAULT_PAGE_SIZE as number,
            {
                setPageSize: (_, { pageSize }) => pageSize,
                resetPaging: () => SQL_V2_DEFAULT_PAGE_SIZE,
            },
        ],
        // Rows fetched for the current page; null means "show the envelope's first page".
        pageResult: [
            null as NotebookNodeSQLV2Page | null,
            {
                setPageResult: (_, { pageResult }) => pageResult,
                resetPaging: () => null,
                runQuery: () => null,
            },
        ],
        pageLoading: [
            false,
            {
                setPageLoading: (_, { pageLoading }) => pageLoading,
                resetPaging: () => false,
            },
        ],
        // Session-local rows for client-side paging of direct runs; a new run invalidates them.
        directRows: [
            null as NotebookNodeSQLV2DirectRows | null,
            {
                setDirectRows: (_, { directRows }) => directRows,
                runQuery: () => null,
            },
        ],
        // A kernel-lane run was submitted while no kernel was known to be up: the backend is
        // provisioning the sandbox; drives the "Starting compute sandbox…" caption.
        pendingKernelStart: [
            false,
            {
                setPendingKernelStart: (_, { pendingKernelStart }) => pendingKernelStart,
                stopPolling: () => false,
            },
        ],
    }),
    listeners(({ props, actions, cache, values }) => {
        // One operation at a time across the whole notebook (see notebookOperationsLogic);
        // ids are per node + kind so re-registering our own operation stays idempotent.
        const runOperation: NotebookOperation = { id: `${props.nodeId}:run`, nodeId: props.nodeId, kind: 'run' }
        const pageOperation: NotebookOperation = { id: `${props.nodeId}:page`, nodeId: props.nodeId, kind: 'page' }

        // Slice a page out of the in-memory direct-run rows — no network, no operation lock.
        const sliceDirectRows = (rows: NotebookNodeSQLV2DirectRows, page: number, pageSize: number): void => {
            const start = (page - 1) * pageSize
            actions.setPageResult({
                columns: rows.columns,
                types: rows.types,
                rows: rows.rows.slice(start, start + pageSize),
                has_more: start + pageSize < rows.rows.length,
            })
        }

        const loadCurrentPage = async (): Promise<void> => {
            const { page, pageSize } = values
            const runId = props.runId
            if (!runId) {
                return
            }
            if (page === 1 && pageSize === SQL_V2_DEFAULT_PAGE_SIZE) {
                // The envelope already carries this page — no round trip.
                actions.setPageResult(null)
                return
            }
            if (values.directRows) {
                sliceDirectRows(values.directRows, page, pageSize)
                return
            }
            // The pagination UI is disabled while the notebook is busy; this guards the
            // programmatic path. A same-node re-page supersedes (stale response discarded below).
            if (values.isBusy && values.activeOperation?.id !== pageOperation.id) {
                lemonToast.info('Another operation is running in this notebook — wait for it to finish.')
                actions.resetPaging()
                return
            }
            actions.startOperation(pageOperation)
            const fetchId = (cache.pageFetchId = (cache.pageFetchId ?? 0) + 1)
            actions.setPageLoading(true)
            try {
                // A direct run keeps its full row set on the result endpoint while the backend's
                // query result is alive — recover it once (e.g. after a reload) and page locally
                // from then on. Kernel runs return no rows here and fall through to server paging.
                try {
                    const recovered = await api.notebooks.sqlV2RunResult(props.notebookShortId, runId)
                    if (recovered.status === 'done' && recovered.rows) {
                        const directRows: NotebookNodeSQLV2DirectRows = {
                            columns: recovered.result?.columns ?? [],
                            types: recovered.result?.types ?? [],
                            rows: recovered.rows,
                        }
                        actions.setDirectRows(directRows)
                        if (cache.pageFetchId === fetchId) {
                            sliceDirectRows(directRows, page, pageSize)
                        }
                        return
                    }
                } catch {
                    // Recovery is best-effort; the server page below reports real errors.
                }
                const pageResult = await api.notebooks.sqlV2RunPage(props.notebookShortId, runId, {
                    offset: (page - 1) * pageSize,
                    limit: pageSize,
                })
                if (cache.pageFetchId === fetchId) {
                    actions.setPageResult(pageResult)
                }
            } catch (error: any) {
                if (cache.pageFetchId !== fetchId) {
                    return
                }
                if (error?.status === 409) {
                    lemonToast.info('This result was replaced by a newer run — showing the latest first page.')
                } else {
                    lemonToast.error(sqlV2RunErrorMessage(error, 'Failed to fetch page'))
                }
                // Either way the requested page never arrived — fall back to the envelope's
                // first page rather than showing old rows under a new page number.
                actions.resetPaging()
            } finally {
                // A superseding fetch re-registered the same operation id — leave the release to it.
                if (cache.pageFetchId === fetchId) {
                    actions.setPageLoading(false)
                    actions.finishOperation(pageOperation.id)
                }
            }
        }

        return {
            setPage: loadCurrentPage,
            setPageSize: loadCurrentPage,
            runQuery: async ({ code, refs, opts }) => {
                if (cache.preparingInputs) {
                    return
                }
                cache.isRestoringResult = false
                cache.activeRunId = null
                cache.disposables.dispose('pollResult')
                if (!code.trim()) {
                    actions.setRunError('Nothing to run — type some code first.')
                    actions.setIsRunning(false)
                    actions.nodeRunFinished(props.nodeId, 'failed', null)
                    return
                }
                // The run button is disabled while the notebook is busy; this guards Cmd+Enter
                // and programmatic dispatch. Re-running our own node supersedes as before.
                if (values.isBusy && values.activeOperation?.nodeId !== props.nodeId) {
                    actions.setIsRunning(false)
                    if (values.isJupyterModeActive) {
                        // Jupyter queues a cell behind a busy kernel, so the cell waits its turn.
                        cache.queuedRun = { code, refs, opts }
                        actions.enqueueRun(props.nodeId)
                        return
                    }
                    lemonToast.info('Another operation is running in this notebook — wait for it to finish.')
                    actions.nodeRunFinished(props.nodeId, 'failed', null)
                    return
                }
                cache.queuedRun = null
                // Which lane will this run take? Mirrors the backend's routing: python always
                // needs the kernel; SQL needs it only when it reads a local (python-made) frame,
                // and never when it targets an external connection (the sandbox can't reach one).
                // The backend stays authoritative — this only drives the kernel panel, never
                // dispatch.
                if (props.prepareInsightDataframes) {
                    cache.preparingInputs = true
                    try {
                        await props.prepareInsightDataframes(code, opts.nodeType ?? 'hogql')
                        refs = collectSqlV2Refs(props.getContent?.() ?? null, props.nodeId)
                    } catch (error) {
                        actions.setRunError(sqlV2RunErrorMessage(error, 'Could not prepare insight dataframes'))
                        actions.setIsRunning(false)
                        // A run the queue released never took the notebook, so the next queued cell must not keep waiting for it.
                        actions.settleReleasedRun(props.nodeId)
                        actions.nodeRunFinished(props.nodeId, 'failed', null)
                        return
                    } finally {
                        cache.preparingInputs = false
                    }
                }
                const isKernelLane =
                    opts.nodeType === 'python' ||
                    (!opts.connectionId && extractDuckSqlTables(code).some((name) => refs[name]?.kind === 'local'))
                if (isKernelLane) {
                    // The backend provisions the sandbox itself when none is running; open the
                    // kernel panel so the user can watch it come up instead of guessing.
                    const kernelKnownRunning =
                        notebookKernelInfoLogic.findMounted({ shortId: props.notebookShortId })?.values.isRunning ??
                        false
                    if (!kernelKnownRunning) {
                        actions.setShowKernelInfo(true)
                        actions.setPendingKernelStart(true)
                    }
                }
                // Read from the notebook rather than the caller: every run path (Run button,
                // Cmd+Enter, chain dispatch) needs the same notebook-level values.
                const variables = props.getVariables?.() ?? []
                actions.startOperation(runOperation)
                try {
                    const runResponse = await api.notebooks.sqlV2Run(props.notebookShortId, {
                        node_id: props.nodeId,
                        code,
                        refs,
                        // Omitted when the notebook declares none, so an unchanged notebook's
                        // run body stays byte-identical to before.
                        ...(variables.length ? { variables } : {}),
                        node_type: opts.nodeType,
                        output_name: opts.outputName,
                        // Omitted entirely for a PostHog cell — the backend's defaults say the same
                        // thing, and every existing run body stays byte-identical.
                        ...(opts.connectionId
                            ? { connection_id: opts.connectionId, send_raw_query: !!opts.sendRawQuery }
                            : {}),
                    })
                    // Mark this as the active run so a still-in-flight poll from a previous run
                    // can't overwrite this result or stop this run's poller once it resolves.
                    const run_id = runResponse.run_id
                    cache.activeRunId = run_id
                    // The backend decides this at dispatch, so it is the only accurate source.
                    // A kernel poll is up to ten seconds old, which is long enough to miss a
                    // sandbox that stopped inside that window and start paid compute silently.
                    if (runResponse.starts_sandbox) {
                        actions.announceSandboxStart(runResponse.sandbox_hourly_price ?? null)
                    }
                    // Persisting nodeId pins the cell's identity: markdown-notebook cell ids are
                    // content fingerprints otherwise, so without the pin any later prop change
                    // would orphan this run's node_id and break refs to this cell.
                    props.updateAttributes({
                        nodeId: props.nodeId,
                        ...(opts.outputName !== undefined ? { returnVariable: opts.outputName } : {}),
                        runId: run_id,
                        result: null,
                        runStatus: null,
                    })
                    actions.startPolling(run_id)
                } catch (error) {
                    actions.setRunError(sqlV2RunErrorMessage(error, 'Failed to run query', 'notebook'))
                    actions.setIsRunning(false)
                    actions.finishOperation(runOperation.id)
                    actions.nodeRunFinished(props.nodeId, 'failed', null)
                }
            },
            announceSandboxStart: ({ hourlyPrice }) => {
                // The panel that shows the price is only just opening, so say the rate in the
                // toast too. A user who runs a Python cell never opens the panel deliberately and
                // would otherwise start paid compute without being told what it costs. The price
                // is null for a local docker kernel, which is free.
                lemonToast.info(sandboxStartMessage(hourlyPrice, values.isSandboxComputeFree))
            },
            runNode: ({ overrides }) => {
                const content = props.getContent?.() ?? null
                const self = content ? buildNotebookDependencyGraph(content).nodesById[props.nodeId] : null
                if (!content || !self) {
                    // A cell the document no longer holds can never report a result, so tell the
                    // staleness chain now rather than leave it waiting on this node.
                    actions.nodeRunFinished(props.nodeId, 'failed', null)
                    return
                }
                // The graph's returnVariable is the disambiguated frame name (sql_df, sql_df_2, …)
                // downstream cells reference, which is what a rerouted run has to bind.
                const opts: RunQueryOptions =
                    self.nodeType === NotebookNodeType.PythonV2
                        ? { nodeType: 'python', outputName: self.returnVariable }
                        : {
                              outputName: self.returnVariable,
                              connectionId:
                                  overrides.connectionId !== undefined
                                      ? overrides.connectionId
                                      : (self.connectionId ?? null),
                              sendRawQuery: overrides.sendRawQuery ?? !!self.sendRawQuery,
                          }
                actions.runQuery(overrides.code ?? self.code ?? '', collectSqlV2Refs(content, props.nodeId), opts)
            },
            // A chain-dispatched run (Journey 10): only the matching node acts, and it runs itself
            // exactly as its own Run button would.
            dispatchChainRun: ({ nodeId }) => {
                if (nodeId === props.nodeId) {
                    actions.runNode()
                }
            },
            // A run the backend started for this cell as part of a whole-notebook run. The cell
            // did not dispatch it, so it pins the run id into the document and picks up the
            // existing poll path, which writes the result and reports the outcome as usual.
            // A cell that is not mounted adopts nothing; its runId reaches the document on the
            // next poll that still sees the run, and afterMount recovers it from there.
            adoptChainRun: ({ nodeId, runId }) => {
                if (nodeId !== props.nodeId || cache.activeRunId === runId) {
                    return
                }
                cache.activeRunId = runId
                props.updateAttributes({ nodeId: props.nodeId, runId, result: null, runStatus: null })
                actions.startPolling(runId)
            },
            startPolling: ({ runId, restoring }) => {
                cache.isRestoringResult = restoring
                // Idempotent re-register: also covers a remount resuming a persisted in-flight run.
                if (!cache.isRestoringResult) {
                    actions.startOperation(runOperation)
                }
                cache.activeRunId = runId
                cache.pollWaitedMs = 0
                actions.pollResult(runId)
                // Same key auto-disposes any previous poller; disposables clean up on unmount and pause on hidden tab.
                cache.disposables.add(() => {
                    // Reschedules itself rather than using setInterval, because the cadence
                    // widens as the wait grows.
                    let timeoutId = 0
                    const scheduleNext = (): void => {
                        timeoutId = window.setTimeout(
                            () => {
                                actions.pollResult(runId)
                                // pollResult can stop the poller synchronously when it reaches the
                                // budget, which disposes this entry. Re-arm only while it still
                                // owns a live poller, or the new timer would outlive the disposable
                                // and loop the failure forever.
                                if (cache.disposables.registry.has('pollResult')) {
                                    scheduleNext()
                                }
                            },
                            pollIntervalMs(cache.pollWaitedMs ?? 0)
                        )
                    }
                    scheduleNext()
                    return () => clearTimeout(timeoutId)
                }, 'pollResult')
            },
            pollResult: async ({ runId }) => {
                const restoring = !!cache.isRestoringResult
                if (cache.pollInFlight) {
                    return
                }
                // Accumulated from the intervals the poller actually used, not from the clock:
                // it pauses while the tab is hidden, so a clock-based budget would burn down
                // during a pause the user never spent waiting.
                cache.pollWaitedMs = (cache.pollWaitedMs ?? 0) + pollIntervalMs(cache.pollWaitedMs ?? 0)
                if (cache.pollWaitedMs > MAX_POLL_WAIT_MS) {
                    // Past every backend budget, so the server is unreachable rather than slow.
                    // The run keeps whatever outcome the server gave it; only this client gave up.
                    if (restoring) {
                        actions.resultRestoreFailed()
                    } else {
                        actions.setRunError(
                            'Stopped checking for a result. Reload the page to see if the run finished.'
                        )
                    }
                    actions.stopPolling()
                    if (!restoring) {
                        actions.nodeRunFinished(props.nodeId, 'failed', null)
                    }
                    return
                }
                cache.pollInFlight = true
                try {
                    const { status, result, error, rows } = await api.notebooks.sqlV2RunResult(
                        props.notebookShortId,
                        runId
                    )
                    // A newer run started while this poll was in flight — its result and poller
                    // must win, so drop this stale response instead of overwriting/stopping it.
                    if (runId !== cache.activeRunId) {
                        return
                    }
                    // Once the kernel panel reports the sandbox up, the wait is execution, not startup.
                    if (
                        values.pendingKernelStart &&
                        notebookKernelInfoLogic.findMounted({ shortId: props.notebookShortId })?.values.isRunning
                    ) {
                        actions.setPendingKernelStart(false)
                    }
                    const envelopeResult: NotebookNodeSQLV2Result | null = result
                        ? {
                              columns: result.columns ?? [],
                              types: result.types ?? [],
                              row_count: result.row_count ?? 0,
                              first_page: result.first_page ?? [],
                              has_more: result.has_more ?? false,
                              stdout: result.stdout ?? '',
                              stderr: result.stderr ?? '',
                              media: result.media ?? [],
                              ...(result.result_text ? { result_text: result.result_text } : {}),
                          }
                        : null
                    const resultMetadata = envelopeResult ? notebookResultPreview(envelopeResult) : null
                    if (status === 'done') {
                        // A direct run's full capped row set arrives with the result — keep it
                        // in memory for client-side paging (kernel runs return no rows here).
                        actions.setDirectRows(
                            rows
                                ? {
                                      columns: result?.columns ?? [],
                                      types: result?.types ?? [],
                                      rows,
                                  }
                                : null
                        )
                        // The outcome rides along with the result so a reload can tell a completed
                        // run from an interrupted one — both leave a result behind.
                        actions.setResult(envelopeResult)
                        if (!restoring) {
                            props.updateAttributes({ result: resultMetadata, runStatus: 'done' })
                        }
                        // A fresh envelope replaces whatever page the user had drilled into.
                        actions.resetPaging()
                        actions.stopPolling()
                        // Downstream cells now derive from outdated data — mark them stale
                        // against the document as it stands now (Journey 10).
                        if (!restoring) {
                            actions.nodeRunFinished(props.nodeId, 'done', props.getContent?.() ?? null)
                        }
                    } else if (status === 'interrupted') {
                        // A user-requested stop: the envelope still carries whatever stdout,
                        // stderr, and figures the cell produced before the interrupt landed.
                        actions.setResult(envelopeResult)
                        if (!restoring) {
                            props.updateAttributes({ result: resultMetadata, runStatus: 'interrupted' })
                        }
                        if (!restoring) {
                            actions.setRunError(error ?? 'Run interrupted.')
                        }
                        actions.resetPaging()
                        actions.stopPolling()
                        if (!restoring) {
                            actions.nodeRunFinished(props.nodeId, 'interrupted', null)
                        }
                    } else if (status === 'failed') {
                        if (restoring) {
                            actions.resultRestoreFailed()
                        } else {
                            actions.setRunError(error ?? 'Run failed')
                        }
                        actions.stopPolling()
                        if (!restoring) {
                            actions.nodeRunFinished(props.nodeId, 'failed', null)
                        }
                    }
                    // 'running' → keep polling
                } catch (error) {
                    if (runId !== cache.activeRunId) {
                        return
                    }
                    if (restoring) {
                        actions.resultRestoreFailed()
                    } else {
                        actions.setRunError(sqlV2RunErrorMessage(error, 'Failed to fetch result'))
                    }
                    actions.stopPolling()
                    if (!restoring) {
                        actions.nodeRunFinished(props.nodeId, 'failed', null)
                    }
                } finally {
                    cache.pollInFlight = false
                }
            },
            releaseQueuedRun: ({ nodeId }) => {
                if (nodeId === props.nodeId && cache.queuedRun) {
                    const { code, refs, opts } = cache.queuedRun
                    cache.queuedRun = null
                    actions.runQuery(code, refs, opts)
                }
            },
            interruptRun: async () => {
                if (values.isQueued) {
                    // Never sent to the server, so stopping it only takes it out of the queue.
                    cache.queuedRun = null
                    actions.dequeueRun(props.nodeId)
                    actions.setIsInterrupting(false)
                    // Only a waiting chain needs to hear about it. Reporting it otherwise would give
                    // a cell that never ran an execution count.
                    if (values.chainQueue[0] === props.nodeId) {
                        actions.nodeRunFinished(props.nodeId, 'interrupted', null)
                    }
                    return
                }
                const runId = cache.activeRunId ?? props.runId
                if (!runId || !values.isRunning) {
                    actions.setIsInterrupting(false)
                    return
                }
                try {
                    const response = await api.notebooks.sqlV2RunInterrupt(props.notebookShortId, runId)
                    if (response.detail) {
                        // Nothing was stopped (e.g. the run hasn't reached the kernel yet), so
                        // let the user retry instead of wedging the button in loading.
                        lemonToast.info(response.detail)
                        actions.setIsInterrupting(false)
                    }
                    // Otherwise stay interrupting until the poll observes the terminal state.
                } catch (error: any) {
                    actions.setIsInterrupting(false)
                    lemonToast.error(error?.detail || error?.message || 'Failed to stop the run')
                }
            },
            resultRestoreFailed: () => {
                posthog.capture('notebook result restore failed', {
                    notebook_short_id: props.notebookShortId,
                    node_id: props.nodeId,
                })
            },
            stopPolling: () => {
                cache.isRestoringResult = false
                cache.disposables.dispose('pollResult')
                actions.setIsRunning(false)
                actions.finishOperation(runOperation.id)
            },
        }
    }),
    selectors(({ props }) => ({
        isSandboxComputeFree: [
            (s) => [s.featureFlags],
            (featureFlags: FeatureFlagsSet): boolean => !!featureFlags[FEATURE_FLAGS.NOTEBOOK_SANDBOX_FREE_COMPUTE],
        ],
        isQueued: [(s) => [s.runQueue], (runQueue: string[]): boolean => runQueue.includes(props.nodeId)],
        // Set while another node's operation is in flight — wire into disabledReason props.
        operationBlockReason: [
            (s) => [s.activeOperation],
            (activeOperation: NotebookOperation | null): string | null =>
                activeOperation && activeOperation.nodeId !== props.nodeId
                    ? (activeOperation.label ?? 'Another operation is running in this notebook')
                    : null,
        ],
        // An upstream cell's run landed after this cell last ran (Journey 10).
        isStale: [
            (s) => [s.staleNodeIds],
            (staleNodeIds: Record<string, NotebookStaleReason>): boolean => !!staleNodeIds[props.nodeId],
        ],
        // What made it stale, so the banner names the actual cause.
        staleReason: [
            (s) => [s.staleNodeIds],
            (staleNodeIds: Record<string, NotebookStaleReason>): NotebookStaleReason | null =>
                staleNodeIds[props.nodeId] ?? null,
        ],
        // Non-zero only on the cell whose run most recently landed: how many of its
        // downstream cells are still stale. Drives the "run downstream cells" button.
        staleDownstreamCount: [
            (s) => [s.lastRunNodeId, s.lastRunStaleDownstreamNodeIds],
            (lastRunNodeId: string | null, lastRunStaleDownstreamNodeIds: string[]): number =>
                lastRunNodeId === props.nodeId ? lastRunStaleDownstreamNodeIds.length : 0,
        ],
    })),
    afterMount(({ props, actions }) => {
        // Only registered cells are eligible for chain dispatch — a dispatch to an unmounted
        // cell would be picked up by nobody and wedge the chain.
        actions.registerChainNode(props.nodeId)
        // Recover after a reload/remount: a persisted runId with no result means the run may still be
        // in flight or already finished — poll to catch up rather than lose the result.
        if (props.runId && !props.hasResult) {
            actions.startPolling(props.runId, !!props.hasResultMetadata)
        }
    }),
    beforeUnmount(({ props, actions, values }) => {
        actions.unregisterChainNode(props.nodeId)
        // A deleted or unmounted cell must never leave the notebook wedged as busy.
        actions.finishNodeOperations(props.nodeId)
        // Nor leave a stale-cell chain waiting forever on a run that can no longer report.
        if (values.chainQueue[0] === props.nodeId) {
            actions.nodeRunFinished(props.nodeId, 'failed', null)
        }
    }),
])