taurusdb-core 0.1.0

package/dist/engine/workflows/connection-spike.js

@@ -0,0 +1,316 @@
+import { clampInteger, countBy, evidenceRowLimit, metricSummaryText, metricsSourceLimitation, parseProcesslistRows, pickMetric, queryMetricsSafely, roundMetric, withDatasourceSummary, } from "../helpers.js";
+export async function diagnoseConnectionSpike(engine, input, ctx) {
+    const [processlist, metrics] = await Promise.all([
+        engine.showProcesslist({
+            user: input.user,
+            host: input.clientHost,
+            includeIdle: true,
+            includeSystem: false,
+            includeInfo: false,
+            maxRows: evidenceRowLimit(input.evidenceLevel),
+        }, ctx),
+        queryMetricsSafely(engine.metricsSource, [
+            "connection_count",
+            "active_connection_count",
+            "connection_usage",
+            "qps",
+        ], input, ctx),
+    ]);
+    const rows = parseProcesslistRows(processlist);
+    const connectionCountMetric = pickMetric(metrics, "connection_count");
+    const activeConnectionMetric = pickMetric(metrics, "active_connection_count");
+    const connectionUsageMetric = pickMetric(metrics, "connection_usage");
+    const qpsMetric = pickMetric(metrics, "qps");
+    const metricEvidence = metrics.map((metric) => ({
+        source: "ces_metrics",
+        title: `CES ${metric.alias}`,
+        summary: metricSummaryText(metric),
+    }));
+    if (rows.length === 0) {
+        const metricOnlySpike = (connectionUsageMetric?.max ?? 0) >= 80 ||
+            (connectionCountMetric?.max ?? 0) >= 100 ||
+            (activeConnectionMetric?.max ?? 0) >= 50;
+        if (metricOnlySpike) {
+            return {
+                tool: "diagnose_connection_spike",
+                status: "ok",
+                severity: (connectionUsageMetric?.max ?? 0) >= 90 ? "high" : "warning",
+                summary: withDatasourceSummary("Connection-spike diagnosis found CES connection pressure but no matching live sessions", ctx.datasource),
+                diagnosisWindow: {
+                    from: input.timeRange?.from,
+                    to: input.timeRange?.to,
+                    relative: input.timeRange?.relative,
+                },
+                rootCauseCandidates: [
+                    {
+                        code: "connection_spike_ces_connection_pressure",
+                        title: "Control-plane metrics show connection pressure",
+                        confidence: (connectionUsageMetric?.max ?? 0) >= 90 ? "high" : "medium",
+                        rationale: `CES connection metrics crossed the current thresholds${connectionUsageMetric?.max !== undefined ? `; max_connection_usage=${roundMetric(connectionUsageMetric.max)}` : ""}${connectionCountMetric?.max !== undefined ? `, max_connection_count=${roundMetric(connectionCountMetric.max)}` : ""}${activeConnectionMetric?.max !== undefined ? `, max_active_connections=${roundMetric(activeConnectionMetric.max)}` : ""}.`,
+                    },
+                ],
+                keyFindings: [
+                    "No matching processlist rows were available in the current snapshot.",
+                    connectionUsageMetric
+                        ? `CES connection usage: ${metricSummaryText(connectionUsageMetric)}.`
+                        : "CES connection usage metric was not returned.",
+                    connectionCountMetric
+                        ? `CES connection count: ${metricSummaryText(connectionCountMetric)}.`
+                        : "CES connection count metric was not returned.",
+                ],
+                suspiciousEntities: input.user
+                    ? {
+                        users: [
+                            {
+                                user: input.user,
+                                clientHost: input.clientHost,
+                                reason: "Provided as the diagnosis focus; CES showed connection pressure but the live snapshot did not contain matching sessions.",
+                            },
+                        ],
+                    }
+                    : undefined,
+                evidence: [
+                    {
+                        source: "processlist",
+                        title: "Current processlist snapshot",
+                        summary: "No matching sessions were returned from information_schema.PROCESSLIST.",
+                    },
+                    ...metricEvidence,
+                ],
+                recommendedActions: [
+                    "Re-run show_processlist during the spike window with include_idle=true and include_info=true.",
+                    "Correlate CES connection pressure with application deploys, retry storms, and pool-size settings.",
+                ],
+                limitations: [
+                    "Live processlist evidence was not available for the observed CES spike window.",
+                ],
+            };
+        }
+        return {
+            tool: "diagnose_connection_spike",
+            status: "inconclusive",
+            severity: "info",
+            summary: withDatasourceSummary("No matching processlist sessions were observed for connection-spike diagnosis", ctx.datasource),
+            diagnosisWindow: {
+                from: input.timeRange?.from,
+                to: input.timeRange?.to,
+                relative: input.timeRange?.relative,
+            },
+            rootCauseCandidates: [
+                {
+                    code: "connection_spike_no_matching_sessions",
+                    title: "No matching live sessions observed",
+                    confidence: "low",
+                    rationale: "The current processlist snapshot did not contain sessions matching the requested user or client-host filters.",
+                },
+            ],
+            keyFindings: [
+                input.user
+                    ? `No current processlist rows matched user ${input.user}.`
+                    : "No current processlist rows were returned.",
+                input.clientHost
+                    ? `No current processlist rows matched host prefix ${input.clientHost}.`
+                    : "No host filter was applied.",
+            ],
+            suspiciousEntities: input.user
+                ? {
+                    users: [
+                        {
+                            user: input.user,
+                            clientHost: input.clientHost,
+                            reason: "Provided as the diagnosis focus, but no matching live sessions were observed in the current snapshot.",
+                        },
+                    ],
+                }
+                : undefined,
+            evidence: [
+                {
+                    source: "processlist",
+                    title: "Current processlist snapshot",
+                    summary: "No matching sessions were returned from information_schema.PROCESSLIST.",
+                },
+                ...metricEvidence,
+            ],
+            recommendedActions: [
+                "Re-run the diagnostic during the spike window to capture live sessions.",
+                "Use show_processlist with broader filters or include_idle=true to inspect connection buildup.",
+            ],
+            limitations: [
+                "This diagnostic currently uses a point-in-time processlist snapshot only.",
+                ...metricsSourceLimitation(engine.metricsSource),
+            ],
+        };
+    }
+    const sleepSessions = rows.filter((row) => row.command === "Sleep");
+    const activeSessions = rows.filter((row) => row.command !== "Sleep");
+    const longRunningSessions = rows.filter((row) => (row.timeSeconds ?? 0) >= 60);
+    const userCounts = countBy(rows, (row) => row.user);
+    const hostCounts = countBy(rows, (row) => row.host);
+    const topUser = userCounts[0];
+    const topHost = hostCounts[0];
+    const longestSessions = [...rows]
+        .sort((left, right) => (right.timeSeconds ?? 0) - (left.timeSeconds ?? 0))
+        .slice(0, 3);
+    const rootCauseCandidates = [];
+    if (sleepSessions.length >= Math.max(5, Math.ceil(rows.length * 0.6))) {
+        rootCauseCandidates.push({
+            code: "connection_spike_idle_session_accumulation",
+            title: "Idle session accumulation",
+            confidence: rows.length >= 10 ? "high" : "medium",
+            rationale: `${sleepSessions.length} of ${rows.length} matching sessions are idle (Sleep), which usually points to pooling saturation or clients holding connections open.`,
+        });
+    }
+    if (activeSessions.length >= Math.max(3, Math.ceil(rows.length * 0.4))) {
+        rootCauseCandidates.push({
+            code: "connection_spike_active_query_backlog",
+            title: "Active query backlog",
+            confidence: activeSessions.length >= 8 ? "high" : "medium",
+            rationale: `${activeSessions.length} matching sessions are active, suggesting requests may be piling up behind slow or blocked work.`,
+        });
+    }
+    if (topUser && topUser.count >= Math.max(3, Math.ceil(rows.length * 0.5))) {
+        rootCauseCandidates.push({
+            code: "connection_spike_single_user_hotspot",
+            title: "Single-user hotspot",
+            confidence: topUser.count >= 8 ? "high" : "medium",
+            rationale: `User ${topUser.key} accounts for ${topUser.count} of ${rows.length} matching sessions, which suggests a concentrated source of connection growth.`,
+        });
+    }
+    if (longRunningSessions.length > 0) {
+        rootCauseCandidates.push({
+            code: "connection_spike_long_running_sessions",
+            title: "Long-running sessions are holding connections",
+            confidence: longRunningSessions.length >= 3 ? "high" : "medium",
+            rationale: `${longRunningSessions.length} matching sessions have been active for at least 60 seconds, which can reduce pool turnover and amplify connection growth.`,
+        });
+    }
+    if ((connectionUsageMetric?.max ?? 0) >= 80 ||
+        (connectionCountMetric?.max ?? 0) >= 100) {
+        rootCauseCandidates.push({
+            code: "connection_spike_ces_connection_pressure",
+            title: "CES metrics confirm connection pressure",
+            confidence: (connectionUsageMetric?.max ?? 0) >= 90 ? "high" : "medium",
+            rationale: `Cloud Eye connection metrics crossed the current pressure thresholds${connectionUsageMetric?.max !== undefined ? `; max_connection_usage=${roundMetric(connectionUsageMetric.max)}` : ""}${connectionCountMetric?.max !== undefined ? `, max_connection_count=${roundMetric(connectionCountMetric.max)}` : ""}.`,
+        });
+    }
+    if (rootCauseCandidates.length === 0) {
+        rootCauseCandidates.push({
+            code: "connection_spike_snapshot_collected",
+            title: "Connection spike snapshot collected",
+            confidence: "low",
+            rationale: "A live processlist snapshot was collected, but no single dominant pattern crossed the current heuristic thresholds.",
+        });
+    }
+    const maxCandidates = clampInteger(input.maxCandidates, 3, 1, 10);
+    const severity = rows.length >= 40 ||
+        activeSessions.length >= 15 ||
+        longRunningSessions.length >= 5
+        ? "high"
+        : rows.length >= 15 ||
+            activeSessions.length >= 5 ||
+            longRunningSessions.length >= 2
+            ? "warning"
+            : "info";
+    const suspiciousUsers = [];
+    if (input.user) {
+        suspiciousUsers.push({
+            user: input.user,
+            clientHost: input.clientHost,
+            reason: "Provided as the connection-spike focus.",
+        });
+    }
+    else if (topUser) {
+        suspiciousUsers.push({
+            user: topUser.key,
+            clientHost: topHost?.key,
+            reason: `Top user in current processlist snapshot with ${topUser.count} sessions.`,
+        });
+    }
+    const suspiciousSessions = longestSessions.map((row) => ({
+        sessionId: row.sessionId,
+        user: row.user,
+        state: row.state ?? row.command,
+        reason: row.timeSeconds !== undefined
+            ? `Observed in the longest-running processlist sessions (${row.timeSeconds}s).`
+            : "Observed in the current processlist snapshot.",
+    }));
+    const keyFindings = [
+        `Collected ${rows.length} matching processlist sessions (${activeSessions.length} active, ${sleepSessions.length} idle).`,
+        topUser
+            ? `Top user ${topUser.key} accounts for ${topUser.count} sessions.`
+            : "No dominant user was identified in the current snapshot.",
+        longRunningSessions.length > 0
+            ? `${longRunningSessions.length} sessions have been active for at least 60 seconds.`
+            : "No long-running sessions (>=60s) were observed in the current snapshot.",
+    ];
+    if (input.compareBaseline) {
+        keyFindings.push(engine.metricsSource
+            ? "Baseline comparison was requested; CES connection metrics were collected for the requested time window."
+            : "Baseline comparison was requested, but only a live processlist snapshot is currently available.");
+    }
+    if (connectionUsageMetric) {
+        keyFindings.push(`CES connection usage: ${metricSummaryText(connectionUsageMetric)}.`);
+    }
+    if (connectionCountMetric) {
+        keyFindings.push(`CES connection count: ${metricSummaryText(connectionCountMetric)}.`);
+    }
+    if (activeConnectionMetric) {
+        keyFindings.push(`CES active connections: ${metricSummaryText(activeConnectionMetric)}.`);
+    }
+    if (qpsMetric) {
+        keyFindings.push(`CES QPS: ${metricSummaryText(qpsMetric)}.`);
+    }
+    const recommendedActions = [
+        "Use show_processlist with include_info=true to inspect the longest-running sessions in more detail.",
+        "Correlate the snapshot with application deploys, retry storms, and pool-size settings.",
+    ];
+    if (sleepSessions.length >= Math.max(5, Math.ceil(rows.length * 0.6))) {
+        recommendedActions.push("Inspect client pooling, idle timeout, and connection reuse behavior for excessive Sleep sessions.");
+    }
+    if (activeSessions.length >= Math.max(3, Math.ceil(rows.length * 0.4))) {
+        recommendedActions.push("Review slow or blocked active sessions with explain_sql / explain_sql_enhanced and lock diagnostics.");
+    }
+    if ((connectionUsageMetric?.max ?? 0) >= 80) {
+        recommendedActions.push("Check configured max connections and application pool concurrency because CES connection usage crossed 80%.");
+    }
+    const evidence = [
+        {
+            source: "processlist",
+            title: "Current processlist snapshot",
+            summary: `Snapshot captured ${rows.length} matching sessions, including ${activeSessions.length} active and ${sleepSessions.length} idle sessions.`,
+        },
+        {
+            source: "processlist",
+            title: "Dominant user and host distribution",
+            summary: topUser || topHost
+                ? `Top user: ${topUser?.key ?? "n/a"} (${topUser?.count ?? 0}); top host: ${topHost?.key ?? "n/a"} (${topHost?.count ?? 0}).`
+                : "No dominant user or host distribution was identified.",
+        },
+        ...metricEvidence,
+    ];
+    return {
+        tool: "diagnose_connection_spike",
+        status: "ok",
+        severity,
+        summary: withDatasourceSummary(`Connection-spike diagnosis collected a live processlist snapshot with ${rows.length} matching sessions`, ctx.datasource),
+        diagnosisWindow: {
+            from: input.timeRange?.from,
+            to: input.timeRange?.to,
+            relative: input.timeRange?.relative,
+        },
+        rootCauseCandidates: rootCauseCandidates.slice(0, maxCandidates),
+        keyFindings,
+        suspiciousEntities: suspiciousUsers.length > 0 || suspiciousSessions.length > 0
+            ? {
+                users: suspiciousUsers.length > 0 ? suspiciousUsers : undefined,
+                sessions: suspiciousSessions.length > 0 ? suspiciousSessions : undefined,
+            }
+            : undefined,
+        evidence,
+        recommendedActions: [...new Set(recommendedActions)],
+        limitations: [
+            "This diagnostic currently relies on a point-in-time processlist snapshot only.",
+            ...metricsSourceLimitation(engine.metricsSource),
+        ],
+    };
+}

package/dist/engine/workflows/db-hotspot.d.ts

@@ -0,0 +1,4 @@
+import type { SessionContext } from "../../context/session-context.js";
+import { type DbHotspotResult, type DiagnoseDbHotspotInput } from "../../diagnostics/types.js";
+import type { TaurusDBEngine } from "../../engine.js";
+export declare function diagnoseDbHotspot(engine: TaurusDBEngine, input: DiagnoseDbHotspotInput, ctx: SessionContext): Promise<DbHotspotResult>;

package/dist/engine/workflows/db-hotspot.js

@@ -0,0 +1,182 @@
+import { buildConnectionSpikeNextToolInput, buildLockContentionNextToolInput, buildShowProcesslistNextToolInput, buildSlowQueryNextToolInput, clampInteger, confidenceWeight, dedupeNextToolInputs, hotspotTypePriority, withDatasourceSummary, } from "../helpers.js";
+export async function diagnoseDbHotspot(engine, input, ctx) {
+    const maxCandidates = clampInteger(input.maxCandidates, 5, 1, 10);
+    const scope = input.scope ?? "all";
+    const hotspots = [];
+    const evidence = [];
+    const recommendedNextTools = new Set();
+    const nextToolInputs = [];
+    const limitations = new Set();
+    if (scope === "all" || scope === "sql") {
+        const topSlowSql = await engine.findTopSlowSql({
+            ...input,
+            topN: Math.min(maxCandidates, 5),
+            sortBy: "total_latency",
+        }, ctx);
+        for (const limitation of topSlowSql.limitations ?? []) {
+            limitations.add(limitation);
+        }
+        if (topSlowSql.status === "ok") {
+            for (const sql of topSlowSql.topSqls.slice(0, Math.min(maxCandidates, 3))) {
+                hotspots.push({
+                    type: "sql",
+                    title: sql.digestText
+                        ? `Top SQL hotspot: ${sql.digestText}`
+                        : "Top SQL hotspot",
+                    confidence: (sql.totalLatencyMs ?? 0) >= 1000 ||
+                        (sql.avgLatencyMs ?? 0) >= 100
+                        ? "high"
+                        : (sql.totalLatencyMs ?? 0) > 0 || (sql.avgLatencyMs ?? 0) > 0
+                            ? "medium"
+                            : "low",
+                    sqlHash: sql.sqlHash,
+                    digestText: sql.digestText,
+                    sampleSql: sql.sampleSql,
+                    rationale: `Ranked in digest summaries${sql.totalLatencyMs !== undefined ? `; total_latency_ms=${sql.totalLatencyMs}` : ""}${sql.avgLatencyMs !== undefined ? `, avg_latency_ms=${sql.avgLatencyMs}` : ""}${sql.execCount !== undefined ? `, exec_count=${sql.execCount}` : ""}${sql.avgRowsExamined !== undefined ? `, avg_rows_examined=${sql.avgRowsExamined}` : ""}.`,
+                    evidenceSources: sql.evidenceSources,
+                    recommendation: sql.recommendation ??
+                        "Use diagnose_slow_query to inspect the SQL hotspot in more detail.",
+                });
+                const slowQueryInput = buildSlowQueryNextToolInput(sql, input, "Analyze this SQL hotspot from database-hotspot aggregation.");
+                if (slowQueryInput) {
+                    nextToolInputs.push(slowQueryInput);
+                }
+            }
+            evidence.push(...topSlowSql.evidence.slice(0, 1));
+            recommendedNextTools.add("find_top_slow_sql");
+            recommendedNextTools.add("diagnose_slow_query");
+        }
+    }
+    if (scope === "all" || scope === "table" || scope === "session") {
+        const lockContention = await engine.diagnoseLockContention({
+            ...input,
+            maxCandidates: Math.min(maxCandidates, 3),
+        }, ctx);
+        for (const limitation of lockContention.limitations ?? []) {
+            limitations.add(limitation);
+        }
+        if (lockContention.status === "ok") {
+            if (scope === "all" || scope === "session") {
+                for (const session of lockContention.suspiciousEntities?.sessions?.slice(0, 2) ?? []) {
+                    hotspots.push({
+                        type: "session",
+                        title: session.sessionId
+                            ? `Blocking session hotspot ${session.sessionId}`
+                            : "Blocking session hotspot",
+                        confidence: lockContention.rootCauseCandidates.some((candidate) => candidate.code === "lock_contention_single_blocker_hotspot")
+                            ? "high"
+                            : "medium",
+                        sessionId: session.sessionId,
+                        rationale: session.reason,
+                        evidenceSources: ["lock_waits"],
+                        recommendation: "Use diagnose_lock_contention and show_processlist to inspect blocker SQL and transaction age.",
+                    });
+                    nextToolInputs.push(buildLockContentionNextToolInput({ blockerSessionId: session.sessionId }, input, "Inspect this blocking-session hotspot with lock-wait context."), buildShowProcesslistNextToolInput({
+                        command: "Query",
+                        includeIdle: false,
+                        includeInfo: true,
+                    }, input, "Review live running sessions around this blocking-session hotspot."));
+                }
+            }
+            if (scope === "all" || scope === "table") {
+                for (const table of lockContention.suspiciousEntities?.tables?.slice(0, 2) ?? []) {
+                    hotspots.push({
+                        type: "table",
+                        title: `Locked table hotspot ${table.table}`,
+                        confidence: lockContention.rootCauseCandidates.some((candidate) => candidate.code === "lock_contention_hot_table")
+                            ? "high"
+                            : "medium",
+                        table: table.table,
+                        rationale: table.reason,
+                        evidenceSources: ["lock_waits"],
+                        recommendation: "Use diagnose_lock_contention to inspect wait chains and reduce lock hold time on this table.",
+                    });
+                    nextToolInputs.push(buildLockContentionNextToolInput({ table: table.table }, input, "Inspect this locked-table hotspot with lock-wait context."));
+                }
+            }
+            evidence.push(...lockContention.evidence.slice(0, 2));
+            recommendedNextTools.add("diagnose_lock_contention");
+            recommendedNextTools.add("show_processlist");
+        }
+    }
+    if (scope === "all" || scope === "session") {
+        const connectionSpike = await engine.diagnoseConnectionSpike({
+            ...input,
+            compareBaseline: false,
+            maxCandidates: Math.min(maxCandidates, 3),
+        }, ctx);
+        for (const limitation of connectionSpike.limitations ?? []) {
+            limitations.add(limitation);
+        }
+        if (connectionSpike.status === "ok") {
+            const focusUser = connectionSpike.suspiciousEntities?.users?.[0];
+            const focusSession = connectionSpike.suspiciousEntities?.sessions?.[0];
+            hotspots.push({
+                type: "session",
+                title: focusUser?.user
+                    ? `Connection hotspot around user ${focusUser.user}`
+                    : focusSession?.sessionId
+                        ? `Connection hotspot around session ${focusSession.sessionId}`
+                        : "Connection hotspot",
+                confidence: connectionSpike.rootCauseCandidates.some((candidate) => candidate.code === "connection_spike_idle_session_accumulation")
+                    ? "high"
+                    : "medium",
+                sessionId: focusSession?.sessionId,
+                rationale: focusUser?.reason ??
+                    focusSession?.reason ??
+                    "A live processlist snapshot suggests a session-level hotspot around connection growth.",
+                evidenceSources: ["processlist"],
+                recommendation: "Use diagnose_connection_spike and show_processlist to inspect idle buildup and long-running sessions.",
+            });
+            nextToolInputs.push(buildConnectionSpikeNextToolInput({
+                user: focusUser?.user,
+                clientHost: focusUser?.clientHost,
+            }, input, "Inspect this connection hotspot with connection-growth diagnostics."), buildShowProcesslistNextToolInput({
+                user: focusUser?.user,
+                host: focusUser?.clientHost,
+                includeIdle: true,
+                includeInfo: true,
+            }, input, "Review live sessions for this connection hotspot."));
+            evidence.push(...connectionSpike.evidence.slice(0, 2));
+            recommendedNextTools.add("diagnose_connection_spike");
+            recommendedNextTools.add("show_processlist");
+        }
+    }
+    const dedupedHotspots = hotspots
+        .filter((item, index, allItems) => {
+        const key = `${item.type}:${item.sqlHash ?? ""}:${item.digestText ?? ""}:${item.sessionId ?? ""}:${item.table ?? ""}:${item.title}`;
+        return (allItems.findIndex((candidate) => {
+            const candidateKey = `${candidate.type}:${candidate.sqlHash ?? ""}:${candidate.digestText ?? ""}:${candidate.sessionId ?? ""}:${candidate.table ?? ""}:${candidate.title}`;
+            return candidateKey === key;
+        }) === index);
+    })
+        .sort((left, right) => confidenceWeight(right.confidence) -
+        confidenceWeight(left.confidence) ||
+        hotspotTypePriority(right.type) - hotspotTypePriority(left.type) ||
+        left.title.localeCompare(right.title))
+        .slice(0, maxCandidates);
+    if (scope === "table") {
+        limitations.add("Table hotspots currently rely on lock-wait evidence only; no table-level IO, scan, or storage metric collector is connected yet.");
+    }
+    if (scope === "session") {
+        limitations.add("Session hotspots currently rely on processlist and lock-wait snapshots only; no CPU or per-session resource metric collector is connected yet.");
+    }
+    return {
+        tool: "diagnose_db_hotspot",
+        status: dedupedHotspots.length > 0 ? "ok" : "inconclusive",
+        summary: withDatasourceSummary(dedupedHotspots.length > 0
+            ? `Database hotspot diagnosis collected ${dedupedHotspots.length} hotspot candidates`
+            : "Database hotspot diagnosis did not isolate a hotspot from current SQL, lock, or processlist evidence", ctx.datasource),
+        diagnosisWindow: {
+            from: input.timeRange?.from,
+            to: input.timeRange?.to,
+            relative: input.timeRange?.relative,
+        },
+        scope,
+        hotspots: dedupedHotspots,
+        evidence: evidence.slice(0, 5),
+        recommendedNextTools: [...recommendedNextTools],
+        nextToolInputs: dedupeNextToolInputs(nextToolInputs).slice(0, maxCandidates),
+        limitations: [...limitations].slice(0, 5),
+    };
+}

package/dist/engine/workflows/lock-contention-helpers/entities.d.ts

@@ -0,0 +1,9 @@
+import type { DiagnosticResult } from "../../../diagnostics/types.js";
+import { type DeadlockSummary, type LockWaitRow, type MetadataLockRow } from "../../helpers.js";
+import type { LockContentionSignals } from "./signals.js";
+export declare function buildLockContentionSuspiciousEntities(input: {
+    rows: LockWaitRow[];
+    metadataLockRows: MetadataLockRow[];
+    latestDeadlock?: DeadlockSummary;
+    signals: LockContentionSignals;
+}): DiagnosticResult["suspiciousEntities"];

package/dist/engine/workflows/lock-contention-helpers/entities.js

@@ -0,0 +1,58 @@
+import { isIdleTransactionBlocker, } from "../../helpers.js";
+export function buildLockContentionSuspiciousEntities(input) {
+    const { rows, metadataLockRows, latestDeadlock, signals } = input;
+    const { tableCounts, metadataTables, topBlocker } = signals;
+    const blockerDetails = rows
+        .filter((row, index, allRows) => row.blockingSessionId !== undefined &&
+        allRows.findIndex((candidate) => candidate.blockingSessionId === row.blockingSessionId) === index)
+        .slice(0, 3);
+    const suspiciousSessions = blockerDetails.map((row) => ({
+        sessionId: row.blockingSessionId,
+        user: row.blockingUser,
+        state: row.blockingState ?? row.blockingTrxState,
+        reason: isIdleTransactionBlocker(row)
+            ? `Observed as a blocker with no active processlist state; the transaction is still ${row.blockingTrxState}${row.blockingTrxAgeSeconds !== undefined ? ` and has been open for ${row.blockingTrxAgeSeconds}s` : ""}, so it can keep row locks until COMMIT or ROLLBACK.`
+            : topBlocker && row.blockingSessionId === topBlocker.key
+                ? `Top blocker in the current snapshot with ${topBlocker.count} waiting sessions.`
+                : `Observed as a blocker in the current lock-wait snapshot${row.blockingTrxAgeSeconds !== undefined ? `; transaction age ${row.blockingTrxAgeSeconds}s` : ""}.`,
+    }));
+    const suspiciousTables = tableCounts
+        .slice(0, 3)
+        .map((entry) => ({
+        table: entry.key,
+        reason: `Observed in ${entry.count} current lock waits.`,
+    }));
+    for (const row of metadataLockRows.slice(0, 2)) {
+        if (row.blockingSessionId &&
+            !suspiciousSessions.some((item) => item.sessionId === row.blockingSessionId)) {
+            suspiciousSessions.push({
+                sessionId: row.blockingSessionId,
+                user: row.blockingUser,
+                state: row.blockingState,
+                reason: `Observed as a metadata-lock blocker${row.objectSchema || row.objectName ? ` on ${(row.objectSchema ? `${row.objectSchema}.` : "") + (row.objectName ?? "unknown")}` : ""}.`,
+            });
+        }
+    }
+    for (const entry of metadataTables.slice(0, 2)) {
+        if (!suspiciousTables.some((item) => item.table === entry.key)) {
+            suspiciousTables.push({
+                table: entry.key,
+                reason: `Observed in ${entry.count} current metadata-lock waits.`,
+            });
+        }
+    }
+    for (const table of latestDeadlock?.waitingTables.slice(0, 2) ?? []) {
+        if (!suspiciousTables.some((item) => item.table === table)) {
+            suspiciousTables.push({
+                table,
+                reason: "Referenced in the latest deadlock section from SHOW ENGINE INNODB STATUS.",
+            });
+        }
+    }
+    return suspiciousSessions.length > 0 || suspiciousTables.length > 0
+        ? {
+            sessions: suspiciousSessions.length > 0 ? suspiciousSessions : undefined,
+            tables: suspiciousTables.length > 0 ? suspiciousTables : undefined,
+        }
+        : undefined;
+}

package/dist/engine/workflows/lock-contention-helpers/no-match.d.ts

@@ -0,0 +1,3 @@
+import type { SessionContext } from "../../../context/session-context.js";
+import type { DiagnoseLockContentionInput, DiagnosticResult } from "../../../diagnostics/types.js";
+export declare function buildNoMatchingLockContentionResult(input: DiagnoseLockContentionInput, ctx: SessionContext): DiagnosticResult;

package/dist/engine/workflows/lock-contention-helpers/no-match.js

@@ -0,0 +1,65 @@
+import { withDatasourceSummary } from "../../helpers.js";
+export function buildNoMatchingLockContentionResult(input, ctx) {
+    return {
+        tool: "diagnose_lock_contention",
+        status: "inconclusive",
+        severity: "info",
+        summary: withDatasourceSummary("No matching InnoDB lock waits were observed for lock-contention diagnosis", ctx.datasource),
+        diagnosisWindow: {
+            from: input.timeRange?.from,
+            to: input.timeRange?.to,
+            relative: input.timeRange?.relative,
+        },
+        rootCauseCandidates: [
+            {
+                code: "lock_contention_no_matching_waits",
+                title: "No matching live lock waits observed",
+                confidence: "low",
+                rationale: "The current InnoDB lock-wait snapshot did not contain rows matching the requested table or blocker-session filters.",
+            },
+        ],
+        keyFindings: [
+            input.table
+                ? `No current lock waits matched table ${ctx.database ? `${ctx.database}.` : ""}${input.table}.`
+                : "No current InnoDB lock waits were returned.",
+            input.blockerSessionId
+                ? `No current lock waits matched blocker session ${input.blockerSessionId}.`
+                : "No blocker session filter was applied.",
+        ],
+        suspiciousEntities: input.table || input.blockerSessionId
+            ? {
+                sessions: input.blockerSessionId
+                    ? [
+                        {
+                            sessionId: input.blockerSessionId,
+                            reason: "Provided as the diagnosis focus, but no matching live lock waits were observed in the current snapshot.",
+                        },
+                    ]
+                    : undefined,
+                tables: input.table
+                    ? [
+                        {
+                            table: input.table,
+                            reason: "Provided as the diagnosis focus, but no matching live lock waits were observed in the current snapshot.",
+                        },
+                    ]
+                    : undefined,
+            }
+            : undefined,
+        evidence: [
+            {
+                source: "lock_waits",
+                title: "Current InnoDB lock-wait snapshot",
+                summary: "No matching rows were returned from performance_schema.data_lock_waits for the current snapshot.",
+            },
+        ],
+        recommendedActions: [
+            "Rerun the diagnosis while the lock wait is active so the blocker and waiter chain is still visible.",
+            "Inspect blocker sessions with show_processlist and widen filters if the contention spans multiple tables or users.",
+        ],
+        limitations: [
+            "This diagnostic currently uses a point-in-time InnoDB lock-wait snapshot only.",
+            "No metadata-lock or deadlock-history evidence was available for this run.",
+        ],
+    };
+}

package/dist/engine/workflows/lock-contention-helpers/report.d.ts

@@ -0,0 +1,21 @@
+import type { DiagnoseLockContentionInput, DiagnosticEvidenceItem } from "../../../diagnostics/types.js";
+import { type DeadlockSummary, type LockWaitRow, type MetadataLockRow } from "../../helpers.js";
+import type { LockContentionSignals } from "./signals.js";
+export declare function buildLockContentionKeyFindings(input: {
+    rows: LockWaitRow[];
+    metadataLockRows: MetadataLockRow[];
+    latestDeadlock?: DeadlockSummary;
+    diagnosisInput: DiagnoseLockContentionInput;
+    signals: LockContentionSignals;
+}): string[];
+export declare function buildLockContentionRecommendedActions(input: {
+    latestDeadlock?: DeadlockSummary;
+    metadataLockRows: MetadataLockRow[];
+    signals: LockContentionSignals;
+}): string[];
+export declare function buildLockContentionEvidence(input: {
+    rows: LockWaitRow[];
+    metadataLockRows: MetadataLockRow[];
+    latestDeadlock?: DeadlockSummary;
+    signals: LockContentionSignals;
+}): DiagnosticEvidenceItem[];