taurusdb-core 0.1.0

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

@@ -0,0 +1,104 @@
+import { isIdleTransactionBlocker, } from "../../helpers.js";
+export function buildLockContentionKeyFindings(input) {
+    const { rows, metadataLockRows, latestDeadlock, diagnosisInput, signals } = input;
+    const { blockerCounts, topBlocker, idleTransactionBlockers, topTable, longWaits, } = signals;
+    const keyFindings = [
+        rows.length > 0
+            ? `Collected ${rows.length} current InnoDB lock waits across ${blockerCounts.length} blocker sessions.`
+            : "No current InnoDB row-lock waits were captured.",
+    ];
+    if (topBlocker) {
+        keyFindings.push(`Blocking session ${topBlocker.key} accounts for ${topBlocker.count} waits in the current snapshot.`);
+    }
+    if (idleTransactionBlockers.length > 0) {
+        keyFindings.push(`${idleTransactionBlockers.length} waits are blocked by idle sessions with active transactions; an idle processlist state does not imply locks are released when the transaction remains uncommitted.`);
+    }
+    if (topTable) {
+        keyFindings.push(`Most waits are concentrated on ${topTable.key} (${topTable.count} waits).`);
+    }
+    if (longWaits.length > 0) {
+        keyFindings.push(`${longWaits.length} waits have been blocked for at least 60 seconds.`);
+    }
+    if (diagnosisInput.blockerSessionId) {
+        keyFindings.push(`Diagnosis was filtered to blocker session ${diagnosisInput.blockerSessionId}.`);
+    }
+    if (metadataLockRows.length > 0) {
+        keyFindings.push(`Collected ${metadataLockRows.length} current metadata-lock waits.`);
+    }
+    if (latestDeadlock) {
+        keyFindings.push(latestDeadlock.detectedAt
+            ? `Latest detected deadlock timestamp: ${latestDeadlock.detectedAt}.`
+            : "SHOW ENGINE INNODB STATUS returned a latest detected deadlock section.");
+    }
+    return keyFindings;
+}
+export function buildLockContentionRecommendedActions(input) {
+    const { latestDeadlock, metadataLockRows, signals } = input;
+    const { idleTransactionBlockers, topTable, tableLevelWaits } = signals;
+    const recommendedActions = [
+        "Inspect the blocker session in show_processlist with include_info=true before terminating it.",
+        "Review transaction scope and commit timing in the blocking application path to reduce lock hold time.",
+    ];
+    if (idleTransactionBlockers.length > 0) {
+        recommendedActions.push("For idle blocker sessions (Sleep or no active processlist state), verify whether the application left a transaction uncommitted; prefer COMMIT or ROLLBACK from the owning client before considering KILL.");
+    }
+    if (topTable) {
+        recommendedActions.push(`Review the access pattern and indexing on ${topTable.key} to reduce hot-row or hot-table conflicts.`);
+    }
+    if (tableLevelWaits.length > 0) {
+        recommendedActions.push("Check for DDL or explicit table-lock operations because TABLE-level waits are present in the snapshot.");
+    }
+    if (metadataLockRows.length > 0) {
+        recommendedActions.push("Review DDL, online schema change tooling, and long-running transactions because metadata-lock waits are present.");
+    }
+    if (latestDeadlock) {
+        recommendedActions.push("Inspect the latest deadlock section in SHOW ENGINE INNODB STATUS and correlate the involved statements before changing only timeout or retry settings.");
+    }
+    return [...new Set(recommendedActions)];
+}
+export function buildLockContentionEvidence(input) {
+    const { rows, metadataLockRows, latestDeadlock, signals } = input;
+    const { blockerCounts, tableCounts, topBlocker, topTable, topMetadataTable, topMetadataBlocker, } = signals;
+    const evidence = [
+        {
+            source: "lock_waits",
+            title: "Current InnoDB lock-wait snapshot",
+            summary: rows.length > 0
+                ? `${rows.length} waits observed across ${blockerCounts.length} blocker sessions and ${tableCounts.length} locked tables.`
+                : "No InnoDB row-lock waits were visible in the current snapshot.",
+        },
+    ];
+    if (topBlocker) {
+        const idleBlocker = rows.find((row) => row.blockingSessionId === topBlocker.key &&
+            isIdleTransactionBlocker(row));
+        evidence.push({
+            source: "lock_waits",
+            title: "Dominant blocker session",
+            summary: idleBlocker
+                ? `Session ${topBlocker.key} is blocking ${topBlocker.count} current waits while it has no active processlist state; its transaction is still ${idleBlocker.blockingTrxState}, so an uncommitted transaction can continue holding locks.`
+                : `Session ${topBlocker.key} is blocking ${topBlocker.count} current waits.`,
+        });
+    }
+    if (topTable) {
+        evidence.push({
+            source: "lock_waits",
+            title: "Hot locked table",
+            summary: `${topTable.key} appears in ${topTable.count} current waits.`,
+        });
+    }
+    if (metadataLockRows.length > 0) {
+        evidence.push({
+            source: "metadata_locks",
+            title: "Current metadata-lock snapshot",
+            summary: `Collected ${metadataLockRows.length} pending metadata locks${topMetadataTable ? `; hottest object=${topMetadataTable.key}` : ""}${topMetadataBlocker ? `, dominant blocker=${topMetadataBlocker.key}` : ""}.`,
+        });
+    }
+    if (latestDeadlock) {
+        evidence.push({
+            source: "deadlock_history",
+            title: "Latest detected deadlock",
+            summary: latestDeadlock.summary,
+        });
+    }
+    return evidence;
+}

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

@@ -0,0 +1,4 @@
+import type { DiagnosticRootCauseCandidate } from "../../../diagnostics/types.js";
+import type { DeadlockSummary } from "../../helpers.js";
+import type { LockContentionSignals } from "./signals.js";
+export declare function buildLockContentionRootCauseCandidates(signals: LockContentionSignals, latestDeadlock?: DeadlockSummary): DiagnosticRootCauseCandidate[];

package/dist/engine/workflows/lock-contention-helpers/root-cause.js

@@ -0,0 +1,79 @@
+export function buildLockContentionRootCauseCandidates(signals, latestDeadlock) {
+    const candidates = [];
+    const { idleTransactionBlockers, topBlocker, longWaits, tableLevelWaits, topTable, topMetadataBlocker, topMetadataTable, } = signals;
+    if (idleTransactionBlockers.length > 0) {
+        candidates.push({
+            code: "lock_contention_idle_transaction_blocker",
+            title: "Idle transaction blocker is holding locks",
+            confidence: idleTransactionBlockers.length >= 2 ? "high" : "medium",
+            rationale: `${idleTransactionBlockers.length} current waits are blocked by sessions with no active processlist state while their transaction is still active; an idle session can continue holding row locks until COMMIT or ROLLBACK.`,
+        });
+    }
+    if (topBlocker && topBlocker.count >= 2) {
+        candidates.push({
+            code: "lock_contention_single_blocker_hotspot",
+            title: "A single blocker session is holding up multiple waiters",
+            confidence: topBlocker.count >= 3 ? "high" : "medium",
+            rationale: `Blocking session ${topBlocker.key} appears in ${topBlocker.count} current lock waits.`,
+        });
+    }
+    if (longWaits.length > 0) {
+        candidates.push({
+            code: "lock_contention_long_wait_chain",
+            title: "Long lock waits indicate a stuck or slow blocker transaction",
+            confidence: longWaits.length >= 2 ? "high" : "medium",
+            rationale: `${longWaits.length} current lock waits have been blocked for at least 60 seconds.`,
+        });
+    }
+    if (tableLevelWaits.length > 0) {
+        candidates.push({
+            code: "lock_contention_table_level_locking",
+            title: "Table-level locking is amplifying the wait chain",
+            confidence: tableLevelWaits.length >= 2 ? "medium" : "low",
+            rationale: "At least one current wait involves a TABLE lock, which often points to broader blocking impact than a single row conflict.",
+        });
+    }
+    if (topTable && topTable.count >= 2) {
+        candidates.push({
+            code: "lock_contention_hot_table",
+            title: "Contention is concentrated on a single table",
+            confidence: topTable.count >= 3 ? "high" : "medium",
+            rationale: `${topTable.key} appears in ${topTable.count} current lock waits.`,
+        });
+    }
+    if (topMetadataBlocker && topMetadataBlocker.count >= 1) {
+        candidates.push({
+            code: "lock_contention_metadata_lock_blocker",
+            title: "Metadata lock waits point to a blocker session",
+            confidence: topMetadataBlocker.count >= 2 ? "high" : "medium",
+            rationale: `Blocking session ${topMetadataBlocker.key} appears in ${topMetadataBlocker.count} current metadata-lock waits.`,
+        });
+    }
+    if (topMetadataTable) {
+        candidates.push({
+            code: "lock_contention_metadata_lock_hot_object",
+            title: "Metadata lock contention is concentrated on one object",
+            confidence: topMetadataTable.count >= 2 ? "medium" : "low",
+            rationale: `${topMetadataTable.key} appears in ${topMetadataTable.count} current metadata-lock waits.`,
+        });
+    }
+    if (latestDeadlock) {
+        candidates.push({
+            code: "lock_contention_recent_deadlock_detected",
+            title: "A recent deadlock was detected by InnoDB",
+            confidence: "medium",
+            rationale: latestDeadlock.detectedAt
+                ? `SHOW ENGINE INNODB STATUS reports a latest detected deadlock at ${latestDeadlock.detectedAt}.`
+                : "SHOW ENGINE INNODB STATUS reports a recent deadlock in the latest deadlock section.",
+        });
+    }
+    if (candidates.length === 0) {
+        candidates.push({
+            code: "lock_contention_snapshot_collected",
+            title: "Lock waits are present but no dominant blocker pattern was isolated",
+            confidence: "low",
+            rationale: "A live lock-wait snapshot was collected, but the current wait chain does not show one dominant blocker, table, or long-wait pattern.",
+        });
+    }
+    return candidates;
+}

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

@@ -0,0 +1,22 @@
+import type { DiagnosticSeverity } from "../../../diagnostics/types.js";
+import { type LockWaitRow, type MetadataLockRow } from "../../helpers.js";
+type CountEntry = {
+    key: string;
+    count: number;
+};
+export type LockContentionSignals = {
+    blockerCounts: CountEntry[];
+    tableCounts: CountEntry[];
+    metadataTables: CountEntry[];
+    metadataBlockers: CountEntry[];
+    longWaits: LockWaitRow[];
+    tableLevelWaits: LockWaitRow[];
+    idleTransactionBlockers: LockWaitRow[];
+    topBlocker?: CountEntry;
+    topTable?: CountEntry;
+    topMetadataTable?: CountEntry;
+    topMetadataBlocker?: CountEntry;
+};
+export declare function buildLockContentionSignals(rows: LockWaitRow[], metadataLockRows: MetadataLockRow[]): LockContentionSignals;
+export declare function severityFromLockContentionSignals(rows: LockWaitRow[], signals: Pick<LockContentionSignals, "longWaits">): DiagnosticSeverity;
+export {};

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

@@ -0,0 +1,34 @@
+import { countBy, isIdleTransactionBlocker, } from "../../helpers.js";
+export function buildLockContentionSignals(rows, metadataLockRows) {
+    const blockerCounts = countBy(rows, (row) => row.blockingSessionId);
+    const tableCounts = countBy(rows, (row) => row.lockedSchema && row.lockedTable
+        ? `${row.lockedSchema}.${row.lockedTable}`
+        : row.lockedTable);
+    const metadataTables = countBy(metadataLockRows, (row) => row.objectSchema && row.objectName
+        ? `${row.objectSchema}.${row.objectName}`
+        : row.objectName);
+    const metadataBlockers = countBy(metadataLockRows, (row) => row.blockingSessionId);
+    const longWaits = rows.filter((row) => (row.waitAgeSeconds ?? 0) >= 60);
+    const tableLevelWaits = rows.filter((row) => row.waitingLockType === "TABLE" || row.blockingLockType === "TABLE");
+    const idleTransactionBlockers = rows.filter(isIdleTransactionBlocker);
+    return {
+        blockerCounts,
+        tableCounts,
+        metadataTables,
+        metadataBlockers,
+        longWaits,
+        tableLevelWaits,
+        idleTransactionBlockers,
+        topBlocker: blockerCounts[0],
+        topTable: tableCounts[0],
+        topMetadataTable: metadataTables[0],
+        topMetadataBlocker: metadataBlockers[0],
+    };
+}
+export function severityFromLockContentionSignals(rows, signals) {
+    return rows.length >= 10 || signals.longWaits.length >= 3
+        ? "high"
+        : rows.length >= 3 || signals.longWaits.length >= 1
+            ? "warning"
+            : "info";
+}

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

@@ -0,0 +1,5 @@
+export * from "./lock-contention-helpers/entities.js";
+export * from "./lock-contention-helpers/no-match.js";
+export * from "./lock-contention-helpers/report.js";
+export * from "./lock-contention-helpers/root-cause.js";
+export * from "./lock-contention-helpers/signals.js";

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

@@ -0,0 +1,5 @@
+export * from "./lock-contention-helpers/entities.js";
+export * from "./lock-contention-helpers/no-match.js";
+export * from "./lock-contention-helpers/report.js";
+export * from "./lock-contention-helpers/root-cause.js";
+export * from "./lock-contention-helpers/signals.js";

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

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

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

@@ -0,0 +1,67 @@
+import { clampInteger, lockEvidenceRowLimit, parseLockWaitRows, withDatasourceSummary } from "../helpers.js";
+import { buildLockContentionEvidence, buildLockContentionKeyFindings, buildLockContentionRecommendedActions, buildLockContentionRootCauseCandidates, buildLockContentionSignals, buildLockContentionSuspiciousEntities, buildNoMatchingLockContentionResult, severityFromLockContentionSignals, } from "./lock-contention-helpers.js";
+export async function diagnoseLockContention(engine, input, ctx) {
+    const [lockWaits, metadataLockRows, latestDeadlock] = await Promise.all([
+        engine.showLockWaits({
+            table: input.table,
+            blockerSessionId: input.blockerSessionId,
+            includeSql: false,
+            maxRows: lockEvidenceRowLimit(input.evidenceLevel),
+        }, ctx),
+        engine.findMetadataLockWaits(input, ctx),
+        engine.findLatestDeadlock(ctx),
+    ]);
+    const rows = parseLockWaitRows(lockWaits);
+    const signals = buildLockContentionSignals(rows, metadataLockRows);
+    if (rows.length === 0 &&
+        metadataLockRows.length === 0 &&
+        latestDeadlock === undefined) {
+        return buildNoMatchingLockContentionResult(input, ctx);
+    }
+    const maxCandidates = clampInteger(input.maxCandidates, 3, 1, 10);
+    const severity = severityFromLockContentionSignals(rows, signals);
+    const rootCauseCandidates = buildLockContentionRootCauseCandidates(signals, latestDeadlock);
+    const suspiciousEntities = buildLockContentionSuspiciousEntities({
+        rows,
+        metadataLockRows,
+        latestDeadlock,
+        signals,
+    });
+    return {
+        tool: "diagnose_lock_contention",
+        status: "ok",
+        severity,
+        summary: withDatasourceSummary(`Lock-contention diagnosis collected a live InnoDB lock-wait snapshot with ${rows.length} matching waits`, ctx.datasource),
+        diagnosisWindow: {
+            from: input.timeRange?.from,
+            to: input.timeRange?.to,
+            relative: input.timeRange?.relative,
+        },
+        rootCauseCandidates: rootCauseCandidates.slice(0, maxCandidates),
+        keyFindings: buildLockContentionKeyFindings({
+            rows,
+            metadataLockRows,
+            latestDeadlock,
+            diagnosisInput: input,
+            signals,
+        }),
+        suspiciousEntities,
+        evidence: buildLockContentionEvidence({
+            rows,
+            metadataLockRows,
+            latestDeadlock,
+            signals,
+        }),
+        recommendedActions: buildLockContentionRecommendedActions({
+            latestDeadlock,
+            metadataLockRows,
+            signals,
+        }),
+        limitations: [
+            "Live lock evidence remains point-in-time; waits that finish before collection will not appear.",
+            latestDeadlock
+                ? "Deadlock history currently uses the latest deadlock section only and does not yet parse a longer deadlock archive."
+                : "Deadlock history was not available from SHOW ENGINE INNODB STATUS in this run.",
+        ],
+    };
+}

package/dist/engine/workflows/service-latency.d.ts

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

package/dist/engine/workflows/service-latency.js

@@ -0,0 +1,262 @@
+import { buildConnectionSpikeNextToolInput, buildLockContentionNextToolInput, buildShowProcesslistNextToolInput, buildSlowQueryNextToolInput, clampInteger, confidenceWeight, dedupeNextToolInputs, metricSummaryText, metricsSourceLimitation, pickMetric, queryMetricsSafely, roundMetric, serviceCategoryPriority, withDatasourceSummary, } from "../helpers.js";
+export async function diagnoseServiceLatency(engine, input, ctx) {
+    const maxCandidates = clampInteger(input.maxCandidates, 5, 1, 10);
+    const [topSlowSql, lockContention, connectionSpike, metrics] = await Promise.all([
+        engine.findTopSlowSql({
+            ...input,
+            topN: Math.min(maxCandidates, 5),
+            sortBy: input.symptom === "latency" || input.symptom === "timeout"
+                ? "avg_latency"
+                : "total_latency",
+        }, ctx),
+        input.symptom === "connection_growth"
+            ? Promise.resolve(undefined)
+            : engine.diagnoseLockContention({
+                ...input,
+                maxCandidates: Math.min(maxCandidates, 3),
+            }, ctx),
+        engine.diagnoseConnectionSpike({
+            ...input,
+            user: input.user,
+            clientHost: input.clientHost,
+            compareBaseline: false,
+            maxCandidates: Math.min(maxCandidates, 3),
+        }, ctx),
+        queryMetricsSafely(engine.metricsSource, [
+            "cpu_util",
+            "mem_util",
+            "connection_usage",
+            "qps",
+            "slow_queries",
+            "storage_write_delay",
+            "storage_read_delay",
+        ], input, ctx),
+    ]);
+    const cpuMetric = pickMetric(metrics, "cpu_util");
+    const memMetric = pickMetric(metrics, "mem_util");
+    const connectionUsageMetric = pickMetric(metrics, "connection_usage");
+    const slowQueriesMetric = pickMetric(metrics, "slow_queries");
+    const writeDelayMetric = pickMetric(metrics, "storage_write_delay");
+    const readDelayMetric = pickMetric(metrics, "storage_read_delay");
+    const topCandidates = [];
+    const evidence = [];
+    const recommendedNextTools = new Set();
+    const nextToolInputs = [];
+    const limitations = new Set();
+    const categoryScores = new Map();
+    const scoreCategory = (category, score) => {
+        categoryScores.set(category, Math.max(categoryScores.get(category) ?? 0, score));
+    };
+    if (topSlowSql.status === "ok" && topSlowSql.topSqls.length > 0) {
+        const leadSql = topSlowSql.topSqls[0];
+        const sqlConfidence = (leadSql.totalLatencyMs ?? 0) >= 1000 ||
+            (leadSql.avgLatencyMs ?? 0) >= 100
+            ? "high"
+            : (leadSql.totalLatencyMs ?? 0) > 0 || (leadSql.avgLatencyMs ?? 0) > 0
+                ? "medium"
+                : "low";
+        topCandidates.push({
+            type: "sql",
+            title: leadSql.digestText
+                ? `Top ranked SQL digest: ${leadSql.digestText}`
+                : "Top ranked SQL digest",
+            confidence: sqlConfidence,
+            sqlHash: leadSql.sqlHash,
+            digestText: leadSql.digestText,
+            sampleSql: leadSql.sampleSql,
+            rationale: `Ranked near the top of statement digest summaries${leadSql.avgLatencyMs !== undefined ? `; avg_latency_ms=${leadSql.avgLatencyMs}` : ""}${leadSql.totalLatencyMs !== undefined ? `, total_latency_ms=${leadSql.totalLatencyMs}` : ""}${leadSql.execCount !== undefined ? `, exec_count=${leadSql.execCount}` : ""}${leadSql.avgRowsExamined !== undefined ? `, avg_rows_examined=${leadSql.avgRowsExamined}` : ""}.`,
+        });
+        const slowQueryInput = buildSlowQueryNextToolInput(leadSql, input, "Analyze the top-ranked SQL candidate from the service-latency symptom route.");
+        if (slowQueryInput) {
+            nextToolInputs.push(slowQueryInput);
+        }
+        evidence.push(...topSlowSql.evidence.slice(0, 1));
+        recommendedNextTools.add("diagnose_slow_query");
+        if ((leadSql.avgLockTimeMs ?? 0) >= 10) {
+            recommendedNextTools.add("diagnose_lock_contention");
+        }
+        scoreCategory("slow_sql", input.symptom === "cpu"
+            ? 4
+            : input.symptom === "latency" || input.symptom === "timeout"
+                ? 3
+                : 2);
+    }
+    for (const limitation of topSlowSql.limitations ?? []) {
+        limitations.add(limitation);
+    }
+    if (lockContention) {
+        for (const limitation of lockContention.limitations ?? []) {
+            limitations.add(limitation);
+        }
+        if (lockContention.status === "ok") {
+            const leadBlocker = lockContention.suspiciousEntities?.sessions?.[0];
+            const leadTable = lockContention.suspiciousEntities?.tables?.[0];
+            const leadRootCause = lockContention.rootCauseCandidates[0];
+            if (leadBlocker) {
+                topCandidates.push({
+                    type: "session",
+                    title: leadBlocker.sessionId
+                        ? `Blocking session ${leadBlocker.sessionId}`
+                        : "Blocking session hotspot",
+                    confidence: leadRootCause?.confidence ?? "medium",
+                    sessionId: leadBlocker.sessionId,
+                    rationale: leadBlocker.reason,
+                });
+            }
+            if (leadTable) {
+                topCandidates.push({
+                    type: "table",
+                    title: `Hot locked table ${leadTable.table}`,
+                    confidence: lockContention.rootCauseCandidates.some((candidate) => candidate.code === "lock_contention_hot_table")
+                        ? "high"
+                        : (leadRootCause?.confidence ?? "medium"),
+                    table: leadTable.table,
+                    rationale: leadTable.reason,
+                });
+            }
+            evidence.push(...lockContention.evidence.slice(0, 2));
+            recommendedNextTools.add("diagnose_lock_contention");
+            recommendedNextTools.add("show_processlist");
+            nextToolInputs.push(buildLockContentionNextToolInput({
+                table: leadTable?.table,
+                blockerSessionId: leadBlocker?.sessionId,
+            }, input, "Inspect the lock-wait candidate identified by the service-latency symptom route."), buildShowProcesslistNextToolInput({
+                command: "Query",
+                includeIdle: false,
+                includeInfo: true,
+            }, input, "Review live running sessions around the lock-contention signal."));
+            const lockScoreBase = input.symptom === "timeout" ? 5 : input.symptom === "latency" ? 4 : 2;
+            scoreCategory("lock_contention", lockContention.rootCauseCandidates.some((candidate) => candidate.code === "lock_contention_single_blocker_hotspot")
+                ? lockScoreBase + 1
+                : lockScoreBase);
+        }
+    }
+    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];
+        const leadRootCause = connectionSpike.rootCauseCandidates[0];
+        topCandidates.push({
+            type: "session",
+            title: focusUser?.user
+                ? `Connection growth around user ${focusUser.user}`
+                : focusSession?.sessionId
+                    ? `Connection growth around session ${focusSession.sessionId}`
+                    : "Connection growth hotspot",
+            confidence: leadRootCause?.confidence ?? "medium",
+            sessionId: focusSession?.sessionId,
+            rationale: focusUser?.reason ??
+                focusSession?.reason ??
+                "A live processlist snapshot suggests connection growth around a focused user or long-running sessions.",
+        });
+        evidence.push(...connectionSpike.evidence.slice(0, 2));
+        recommendedNextTools.add("diagnose_connection_spike");
+        recommendedNextTools.add("show_processlist");
+        nextToolInputs.push(buildConnectionSpikeNextToolInput({
+            user: focusUser?.user ?? input.user,
+            clientHost: focusUser?.clientHost ?? input.clientHost,
+        }, input, "Inspect the connection-growth candidate identified by the service-latency symptom route."), buildShowProcesslistNextToolInput({
+            user: focusUser?.user ?? input.user,
+            host: focusUser?.clientHost ?? input.clientHost,
+            includeIdle: true,
+            includeInfo: true,
+        }, input, "Review live sessions for idle buildup or long-running queries around the connection signal."));
+        const connectionScoreBase = input.symptom === "connection_growth"
+            ? 5
+            : input.symptom === "latency" || input.symptom === "timeout"
+                ? 2
+                : 1;
+        scoreCategory("connection_spike", connectionSpike.rootCauseCandidates.some((candidate) => candidate.code === "connection_spike_idle_session_accumulation")
+            ? connectionScoreBase + 1
+            : connectionScoreBase);
+    }
+    if (metrics.length > 0) {
+        evidence.push(...metrics.slice(0, 4).map((metric) => ({
+            source: "ces_metrics",
+            title: `CES ${metric.alias}`,
+            summary: metricSummaryText(metric),
+        })));
+        if ((cpuMetric?.max ?? 0) >= 80 || (memMetric?.max ?? 0) >= 90) {
+            topCandidates.push({
+                type: "session",
+                title: "Instance resource pressure from CES metrics",
+                confidence: (cpuMetric?.max ?? 0) >= 90 || (memMetric?.max ?? 0) >= 95
+                    ? "high"
+                    : "medium",
+                rationale: `Cloud Eye metrics show instance resource pressure${cpuMetric?.max !== undefined ? `; max_cpu=${roundMetric(cpuMetric.max)}` : ""}${memMetric?.max !== undefined ? `, max_mem=${roundMetric(memMetric.max)}` : ""}.`,
+            });
+            recommendedNextTools.add("diagnose_storage_pressure");
+            scoreCategory("resource_pressure", input.symptom === "cpu" ? 6 : 3);
+        }
+        if ((writeDelayMetric?.max ?? 0) >= 50 ||
+            (readDelayMetric?.max ?? 0) >= 50) {
+            recommendedNextTools.add("diagnose_storage_pressure");
+            scoreCategory("resource_pressure", 4);
+        }
+        if ((connectionUsageMetric?.max ?? 0) >= 80) {
+            recommendedNextTools.add("diagnose_connection_spike");
+            scoreCategory("connection_spike", input.symptom === "connection_growth" ? 6 : 3);
+        }
+        if ((slowQueriesMetric?.max ?? 0) > 0) {
+            recommendedNextTools.add("find_top_slow_sql");
+            recommendedNextTools.add("diagnose_slow_query");
+            scoreCategory("slow_sql", input.symptom === "latency" ? 4 : 2);
+        }
+    }
+    else {
+        for (const limitation of metricsSourceLimitation(engine.metricsSource)) {
+            limitations.add(limitation);
+        }
+    }
+    const scoredCategories = [...categoryScores.entries()]
+        .filter(([, score]) => score > 0)
+        .sort((left, right) => right[1] - left[1] ||
+        serviceCategoryPriority(right[0]) - serviceCategoryPriority(left[0]));
+    const fallbackCategory = input.symptom === "cpu"
+        ? "resource_pressure"
+        : input.symptom === "connection_growth"
+            ? "connection_spike"
+            : input.symptom === "timeout"
+                ? "lock_contention"
+                : "slow_sql";
+    const suspectedCategory = scoredCategories.length === 0
+        ? fallbackCategory
+        : scoredCategories.length > 1 &&
+            scoredCategories[0][1] === scoredCategories[1][1]
+            ? "mixed"
+            : scoredCategories[0][0];
+    if (suspectedCategory === "resource_pressure") {
+        recommendedNextTools.add("diagnose_storage_pressure");
+        if (!engine.metricsSource) {
+            limitations.add("Resource-pressure routing is heuristic because no CPU, IOPS, or instance-metric collector is configured yet.");
+        }
+    }
+    const sortedCandidates = [...topCandidates]
+        .sort((left, right) => confidenceWeight(right.confidence) -
+        confidenceWeight(left.confidence) ||
+        left.title.localeCompare(right.title))
+        .slice(0, maxCandidates);
+    const summary = sortedCandidates.length > 0
+        ? suspectedCategory === "mixed"
+            ? "Service-latency diagnosis found mixed SQL, lock, or connection signals"
+            : `Service-latency diagnosis points to ${suspectedCategory.replace(/_/g, " ")} as the dominant suspect`
+        : "Service-latency diagnosis did not isolate a dominant suspect from current SQL, lock, or connection evidence";
+    return {
+        tool: "diagnose_service_latency",
+        status: sortedCandidates.length > 0 ? "ok" : "inconclusive",
+        summary: withDatasourceSummary(summary, ctx.datasource),
+        diagnosisWindow: {
+            from: input.timeRange?.from,
+            to: input.timeRange?.to,
+            relative: input.timeRange?.relative,
+        },
+        suspectedCategory,
+        topCandidates: sortedCandidates,
+        evidence: evidence.slice(0, 5),
+        recommendedNextTools: [...recommendedNextTools],
+        nextToolInputs: dedupeNextToolInputs(nextToolInputs).slice(0, maxCandidates),
+        limitations: [...limitations].slice(0, 5),
+    };
+}

package/dist/engine/workflows/slow-query-helpers.d.ts

@@ -0,0 +1,41 @@
+import type { SessionContext } from "../../context/session-context.js";
+import type { DiagnosticResult, DiagnosticRootCauseCandidate } from "../../diagnostics/types.js";
+import type { ExternalSlowSqlSample } from "../../diagnostics/slow-sql-source.js";
+import type { TaurusDBEngine } from "../../engine.js";
+import type { EnhancedExplainResult } from "../types.js";
+import type { ExplainResult } from "../../executor/sql-executor.js";
+import { type PlanTableStats, type StatementDigestRow, type StatementWaitEventRow } from "../helpers.js";
+export declare function collectPlanTableStats(engine: TaurusDBEngine, ctx: SessionContext, plan: ExplainResult["plan"]): Promise<PlanTableStats[]>;
+export declare function buildSlowQueryRootCauseCandidates(input: {
+    riskSummary: ExplainResult["riskSummary"];
+    explain: EnhancedExplainResult;
+    digestSample?: StatementDigestRow;
+    runtimeLockTimeMs?: number;
+    waitEventRows: StatementWaitEventRow[];
+}): DiagnosticRootCauseCandidate[];
+export declare function buildSlowQueryKeyFindings(input: {
+    riskSummary: ExplainResult["riskSummary"];
+    resolvedPlanTables: PlanTableStats[];
+    digestSample?: StatementDigestRow;
+    externalSlowSqlSample?: ExternalSlowSqlSample;
+    runtimeRowsExamined?: number;
+    runtimeLockTimeMs?: number;
+    waitEventRows: StatementWaitEventRow[];
+}): string[];
+export declare function buildSlowQueryRecommendedActions(input: {
+    standardPlan: ExplainResult;
+    explain: EnhancedExplainResult;
+    riskSummary: ExplainResult["riskSummary"];
+    resolvedPlanTables: PlanTableStats[];
+    digestSample?: StatementDigestRow;
+    runtimeLockTimeMs?: number;
+    topWaitEvent?: StatementWaitEventRow;
+}): string[];
+export declare function buildSlowQueryEvidence(input: {
+    standardPlan: ExplainResult;
+    riskSummary: ExplainResult["riskSummary"];
+    resolvedPlanTables: PlanTableStats[];
+    digestSample?: StatementDigestRow;
+    externalSlowSqlSample?: ExternalSlowSqlSample;
+    waitEventRows: StatementWaitEventRow[];
+}): DiagnosticResult["evidence"];