taurusdb-core 0.1.0

package/dist/diagnostics/types.d.ts

@@ -0,0 +1,189 @@
+export type DiagnosticToolName = "diagnose_service_latency" | "diagnose_db_hotspot" | "find_top_slow_sql" | "diagnose_slow_query" | "diagnose_connection_spike" | "diagnose_lock_contention" | "diagnose_storage_pressure";
+export type DiagnosticStatus = "ok" | "inconclusive" | "not_applicable";
+export type DiagnosticSeverity = "info" | "warning" | "high" | "critical";
+export type DiagnosticEvidenceLevel = "basic" | "standard" | "full";
+export type DiagnosticConfidence = "low" | "medium" | "high";
+export interface DiagnosisWindow {
+    from?: string;
+    to?: string;
+    relative?: string;
+}
+export interface DiagnosticBaseInput {
+    datasource?: string;
+    database?: string;
+    timeRange?: DiagnosisWindow;
+    evidenceLevel?: DiagnosticEvidenceLevel;
+    includeRawEvidence?: boolean;
+    maxCandidates?: number;
+}
+export interface DiagnoseSlowQueryInput extends DiagnosticBaseInput {
+    sql?: string;
+    sqlHash?: string;
+    digestText?: string;
+}
+export interface DiagnoseServiceLatencyInput extends DiagnosticBaseInput {
+    user?: string;
+    clientHost?: string;
+    symptom?: "latency" | "timeout" | "cpu" | "connection_growth";
+}
+export interface DiagnoseDbHotspotInput extends DiagnosticBaseInput {
+    scope?: "sql" | "table" | "session";
+}
+export interface FindTopSlowSqlInput extends DiagnosticBaseInput {
+    topN?: number;
+    sortBy?: "avg_latency" | "total_latency" | "exec_count" | "lock_time";
+}
+export interface DiagnoseConnectionSpikeInput extends DiagnosticBaseInput {
+    user?: string;
+    clientHost?: string;
+    compareBaseline?: boolean;
+}
+export interface DiagnoseLockContentionInput extends DiagnosticBaseInput {
+    table?: string;
+    blockerSessionId?: string;
+}
+export interface DiagnoseStoragePressureInput extends DiagnosticBaseInput {
+    scope?: "instance" | "database" | "table";
+    table?: string;
+}
+export interface DiagnosticRootCauseCandidate {
+    code: string;
+    title: string;
+    confidence: DiagnosticConfidence;
+    rationale: string;
+}
+export interface DiagnosticSuspiciousSql {
+    sqlHash?: string;
+    digestText?: string;
+    reason: string;
+}
+export interface DiagnosticSuspiciousSession {
+    sessionId?: string;
+    user?: string;
+    state?: string;
+    reason: string;
+}
+export interface DiagnosticSuspiciousTable {
+    table: string;
+    reason: string;
+}
+export interface DiagnosticSuspiciousUser {
+    user: string;
+    clientHost?: string;
+    reason: string;
+}
+export interface DiagnosticSuspiciousEntities {
+    sqls?: DiagnosticSuspiciousSql[];
+    sessions?: DiagnosticSuspiciousSession[];
+    tables?: DiagnosticSuspiciousTable[];
+    users?: DiagnosticSuspiciousUser[];
+}
+export interface DiagnosticEvidenceItem {
+    source: string;
+    title: string;
+    summary: string;
+    rawRef?: string;
+}
+export interface TopSlowSqlItem {
+    sqlHash?: string;
+    digestText?: string;
+    sampleSql?: string;
+    avgLatencyMs?: number;
+    totalLatencyMs?: number;
+    execCount?: number;
+    avgLockTimeMs?: number;
+    avgRowsExamined?: number;
+    evidenceSources: string[];
+    recommendation?: string;
+}
+export interface DiagnosticNextToolInput {
+    tool: DiagnosticToolName | "show_processlist";
+    input: Record<string, unknown>;
+    rationale: string;
+}
+export type ServiceLatencySuspectedCategory = "slow_sql" | "lock_contention" | "connection_spike" | "resource_pressure" | "mixed";
+export interface ServiceLatencyCandidate {
+    type: "sql" | "session" | "table";
+    title: string;
+    confidence: DiagnosticConfidence;
+    sqlHash?: string;
+    digestText?: string;
+    sampleSql?: string;
+    sessionId?: string;
+    table?: string;
+    rationale: string;
+}
+export interface DbHotspotItem {
+    type: "sql" | "session" | "table";
+    title: string;
+    confidence: DiagnosticConfidence;
+    sqlHash?: string;
+    digestText?: string;
+    sampleSql?: string;
+    sessionId?: string;
+    table?: string;
+    rationale: string;
+    evidenceSources: string[];
+    recommendation?: string;
+}
+export interface DiagnosticResult {
+    tool: DiagnosticToolName;
+    status: DiagnosticStatus;
+    severity: DiagnosticSeverity;
+    summary: string;
+    diagnosisWindow: DiagnosisWindow;
+    rootCauseCandidates: DiagnosticRootCauseCandidate[];
+    keyFindings: string[];
+    suspiciousEntities?: DiagnosticSuspiciousEntities;
+    evidence: DiagnosticEvidenceItem[];
+    recommendedActions: string[];
+    recommendedNextTools?: string[];
+    nextToolInputs?: DiagnosticNextToolInput[];
+    limitations?: string[];
+}
+export interface ServiceLatencyResult {
+    tool: "diagnose_service_latency";
+    status: DiagnosticStatus;
+    summary: string;
+    diagnosisWindow: DiagnosisWindow;
+    suspectedCategory: ServiceLatencySuspectedCategory;
+    topCandidates: ServiceLatencyCandidate[];
+    evidence: DiagnosticEvidenceItem[];
+    recommendedNextTools: string[];
+    nextToolInputs: DiagnosticNextToolInput[];
+    limitations?: string[];
+}
+export interface DbHotspotResult {
+    tool: "diagnose_db_hotspot";
+    status: DiagnosticStatus;
+    summary: string;
+    diagnosisWindow: DiagnosisWindow;
+    scope: "sql" | "table" | "session" | "all";
+    hotspots: DbHotspotItem[];
+    evidence: DiagnosticEvidenceItem[];
+    recommendedNextTools: string[];
+    nextToolInputs: DiagnosticNextToolInput[];
+    limitations?: string[];
+}
+export interface FindTopSlowSqlResult {
+    tool: "find_top_slow_sql";
+    status: DiagnosticStatus;
+    summary: string;
+    diagnosisWindow: DiagnosisWindow;
+    topSqls: TopSlowSqlItem[];
+    evidence: DiagnosticEvidenceItem[];
+    limitations?: string[];
+}
+export interface PlaceholderDiagnosticOptions {
+    summary: string;
+    candidateTitle: string;
+    candidateRationale: string;
+    keyFindings?: string[];
+    suspiciousEntities?: DiagnosticSuspiciousEntities;
+    recommendedActions?: string[];
+    limitations?: string[];
+    evidence?: DiagnosticEvidenceItem[];
+    status?: DiagnosticStatus;
+    severity?: DiagnosticSeverity;
+}
+export declare function createPlaceholderDiagnosticResult(tool: DiagnosticToolName, input: DiagnosticBaseInput, options: PlaceholderDiagnosticOptions): DiagnosticResult;

package/dist/diagnostics/types.js

@@ -0,0 +1,39 @@
+export function createPlaceholderDiagnosticResult(tool, input, options) {
+    return {
+        tool,
+        status: options.status ?? "inconclusive",
+        severity: options.severity ?? "info",
+        summary: options.summary,
+        diagnosisWindow: {
+            from: input.timeRange?.from,
+            to: input.timeRange?.to,
+            relative: input.timeRange?.relative,
+        },
+        rootCauseCandidates: [
+            {
+                code: `${tool}_pending`,
+                title: options.candidateTitle,
+                confidence: "low",
+                rationale: options.candidateRationale,
+            },
+        ],
+        keyFindings: options.keyFindings ?? [
+            "The diagnostic contract is available, but evidence collectors have not been wired yet.",
+            "No live control-plane or data-plane evidence was collected in this run.",
+        ],
+        suspiciousEntities: options.suspiciousEntities,
+        evidence: options.evidence ?? [
+            {
+                source: "diagnostics_scaffold",
+                title: "Diagnostic scaffold active",
+                summary: "Typed inputs, outputs, and engine entrypoints are in place, but collectors and analyzers are pending.",
+            },
+        ],
+        recommendedActions: options.recommendedActions ?? [
+            "Implement the required collectors before relying on this tool for production diagnosis.",
+        ],
+        limitations: options.limitations ?? [
+            "This diagnostic currently returns a scaffolded result instead of live evidence-backed analysis.",
+        ],
+    };
+}

package/dist/engine/data-access/locks.d.ts

@@ -0,0 +1,8 @@
+import type { SessionContext } from "../../context/session-context.js";
+import type { DiagnoseLockContentionInput } from "../../diagnostics/types.js";
+import type { QueryResult } from "../../executor/sql-executor.js";
+import type { ShowLockWaitsInput, TaurusDBEngine } from "../../engine.js";
+import { type DeadlockSummary, type MetadataLockRow } from "../helpers.js";
+export declare function showLockWaits(engine: TaurusDBEngine, input: ShowLockWaitsInput, ctx: SessionContext): Promise<QueryResult>;
+export declare function findMetadataLockWaits(engine: TaurusDBEngine, input: DiagnoseLockContentionInput, ctx: SessionContext): Promise<MetadataLockRow[]>;
+export declare function findLatestDeadlock(engine: TaurusDBEngine, ctx: SessionContext): Promise<DeadlockSummary | undefined>;

package/dist/engine/data-access/locks.js

@@ -0,0 +1,146 @@
+import { clampInteger, lockEvidenceRowLimit, parseDeadlockSummary, parseMetadataLockRows, quoteLiteral, } from "../helpers.js";
+export async function showLockWaits(engine, input, ctx) {
+    const maxRows = clampInteger(input.maxRows, 20, 1, 100);
+    const includeSql = input.includeSql === true;
+    const sqlMaxChars = clampInteger(input.sqlMaxChars, 256, 32, 2048);
+    const selectedColumns = [
+        "CAST(waiting_thread.PROCESSLIST_ID AS CHAR) AS waiting_session_id",
+        "waiting_thread.PROCESSLIST_USER AS waiting_user",
+        "waiting_thread.PROCESSLIST_STATE AS waiting_state",
+        "waiting_trx.TRX_STATE AS waiting_trx_state",
+        "TIMESTAMPDIFF(SECOND, waiting_trx.TRX_WAIT_STARTED, CURRENT_TIMESTAMP) AS wait_age_seconds",
+        "CAST(blocking_thread.PROCESSLIST_ID AS CHAR) AS blocking_session_id",
+        "blocking_thread.PROCESSLIST_USER AS blocking_user",
+        "blocking_thread.PROCESSLIST_STATE AS blocking_state",
+        "blocking_trx.TRX_STATE AS blocking_trx_state",
+        "TIMESTAMPDIFF(SECOND, blocking_trx.TRX_STARTED, CURRENT_TIMESTAMP) AS blocking_trx_age_seconds",
+        "requesting_lock.OBJECT_SCHEMA AS locked_schema",
+        "requesting_lock.OBJECT_NAME AS locked_table",
+        "requesting_lock.INDEX_NAME AS locked_index",
+        "requesting_lock.LOCK_TYPE AS waiting_lock_type",
+        "requesting_lock.LOCK_MODE AS waiting_lock_mode",
+        "blocking_lock.LOCK_TYPE AS blocking_lock_type",
+        "blocking_lock.LOCK_MODE AS blocking_lock_mode",
+    ];
+    if (includeSql) {
+        selectedColumns.push("waiting_thread.PROCESSLIST_INFO AS waiting_query", "blocking_thread.PROCESSLIST_INFO AS blocking_query");
+    }
+    const whereClauses = ["waits.ENGINE = 'INNODB'"];
+    const targetSchema = ctx.database;
+    if (targetSchema) {
+        whereClauses.push(`requesting_lock.OBJECT_SCHEMA = ${quoteLiteral(targetSchema)}`);
+    }
+    if (input.table) {
+        whereClauses.push(`requesting_lock.OBJECT_NAME = ${quoteLiteral(input.table)}`);
+    }
+    if (input.blockerSessionId) {
+        whereClauses.push(`CAST(blocking_thread.PROCESSLIST_ID AS CHAR) = ${quoteLiteral(input.blockerSessionId)}`);
+    }
+    const sql = `
+      SELECT ${selectedColumns.join(", ")}
+      FROM performance_schema.data_lock_waits AS waits
+      INNER JOIN performance_schema.data_locks AS requesting_lock
+        ON requesting_lock.ENGINE = waits.ENGINE
+        AND requesting_lock.ENGINE_LOCK_ID = waits.REQUESTING_ENGINE_LOCK_ID
+      INNER JOIN performance_schema.data_locks AS blocking_lock
+        ON blocking_lock.ENGINE = waits.ENGINE
+        AND blocking_lock.ENGINE_LOCK_ID = waits.BLOCKING_ENGINE_LOCK_ID
+      LEFT JOIN information_schema.INNODB_TRX AS waiting_trx
+        ON waiting_trx.TRX_ID = waits.REQUESTING_ENGINE_TRANSACTION_ID
+      LEFT JOIN information_schema.INNODB_TRX AS blocking_trx
+        ON blocking_trx.TRX_ID = waits.BLOCKING_ENGINE_TRANSACTION_ID
+      LEFT JOIN performance_schema.threads AS waiting_thread
+        ON waiting_thread.THREAD_ID = waits.REQUESTING_THREAD_ID
+      LEFT JOIN performance_schema.threads AS blocking_thread
+        ON blocking_thread.THREAD_ID = waits.BLOCKING_THREAD_ID
+      WHERE ${whereClauses.join(" AND ")}
+      ORDER BY wait_age_seconds DESC, blocking_trx_age_seconds DESC, blocking_session_id DESC
+      LIMIT ${maxRows}
+    `.trim();
+    return engine.executor.executeReadonly(sql, ctx, {
+        maxRows,
+        maxColumns: selectedColumns.length,
+        maxFieldChars: includeSql ? sqlMaxChars : 256,
+        timeoutMs: ctx.limits.timeoutMs,
+    });
+}
+export async function findMetadataLockWaits(engine, input, ctx) {
+    const maxRows = lockEvidenceRowLimit(input.evidenceLevel);
+    const whereClauses = [
+        "waiting.LOCK_STATUS = 'PENDING'",
+        "blocking.LOCK_STATUS = 'GRANTED'",
+        "waiting.OWNER_THREAD_ID <> blocking.OWNER_THREAD_ID",
+    ];
+    const focusedTable = input.table?.includes(".")
+        ? {
+            schema: input.table.split(".")[0],
+            table: input.table.split(".").slice(1).join("."),
+        }
+        : {
+            schema: ctx.database,
+            table: input.table,
+        };
+    if (focusedTable.schema) {
+        whereClauses.push(`waiting.OBJECT_SCHEMA = ${quoteLiteral(focusedTable.schema)}`);
+    }
+    if (focusedTable.table) {
+        whereClauses.push(`waiting.OBJECT_NAME = ${quoteLiteral(focusedTable.table)}`);
+    }
+    if (input.blockerSessionId) {
+        whereClauses.push(`blocking_threads.PROCESSLIST_ID = ${quoteLiteral(input.blockerSessionId)}`);
+    }
+    const sql = `
+      SELECT
+        waiting_threads.PROCESSLIST_ID AS waiting_session_id,
+        waiting_threads.PROCESSLIST_USER AS waiting_user,
+        waiting_threads.PROCESSLIST_STATE AS waiting_state,
+        blocking_threads.PROCESSLIST_ID AS blocking_session_id,
+        blocking_threads.PROCESSLIST_USER AS blocking_user,
+        blocking_threads.PROCESSLIST_STATE AS blocking_state,
+        waiting.OBJECT_TYPE AS object_type,
+        waiting.OBJECT_SCHEMA AS object_schema,
+        waiting.OBJECT_NAME AS object_name,
+        waiting.LOCK_TYPE AS waiting_lock_type,
+        waiting.LOCK_DURATION AS waiting_lock_duration,
+        blocking.LOCK_TYPE AS blocking_lock_type,
+        blocking.LOCK_DURATION AS blocking_lock_duration
+      FROM performance_schema.metadata_locks AS waiting
+      INNER JOIN performance_schema.threads AS waiting_threads
+        ON waiting_threads.THREAD_ID = waiting.OWNER_THREAD_ID
+      INNER JOIN performance_schema.metadata_locks AS blocking
+        ON blocking.OBJECT_TYPE = waiting.OBJECT_TYPE
+        AND COALESCE(blocking.OBJECT_SCHEMA, '') = COALESCE(waiting.OBJECT_SCHEMA, '')
+        AND COALESCE(blocking.OBJECT_NAME, '') = COALESCE(waiting.OBJECT_NAME, '')
+      INNER JOIN performance_schema.threads AS blocking_threads
+        ON blocking_threads.THREAD_ID = blocking.OWNER_THREAD_ID
+      WHERE ${whereClauses.join(" AND ")}
+      ORDER BY waiting.OBJECT_SCHEMA ASC, waiting.OBJECT_NAME ASC, blocking_threads.PROCESSLIST_ID ASC
+      LIMIT ${maxRows}
+    `.trim();
+    try {
+        const result = await engine.executor.executeReadonly(sql, ctx, {
+            maxRows,
+            maxColumns: 13,
+            maxFieldChars: 512,
+            timeoutMs: ctx.limits.timeoutMs,
+        });
+        return parseMetadataLockRows(result);
+    }
+    catch {
+        return [];
+    }
+}
+export async function findLatestDeadlock(engine, ctx) {
+    try {
+        const result = await engine.executor.executeReadonly("SHOW ENGINE INNODB STATUS", ctx, {
+            maxRows: 1,
+            maxColumns: 3,
+            maxFieldChars: 32768,
+            timeoutMs: ctx.limits.timeoutMs,
+        });
+        return parseDeadlockSummary(result);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/engine/data-access/processlist.d.ts

@@ -0,0 +1,4 @@
+import type { SessionContext } from "../../context/session-context.js";
+import type { QueryResult } from "../../executor/sql-executor.js";
+import type { ShowProcesslistInput, TaurusDBEngine } from "../../engine.js";
+export declare function showProcesslist(engine: TaurusDBEngine, input: ShowProcesslistInput, ctx: SessionContext): Promise<QueryResult>;

package/dist/engine/data-access/processlist.js

@@ -0,0 +1,56 @@
+import { clampInteger, escapeLikePrefix, quoteLiteral, } from "../helpers.js";
+export async function showProcesslist(engine, input, ctx) {
+    const maxRows = clampInteger(input.maxRows, 20, 1, 100);
+    const minTimeSeconds = clampInteger(input.minTimeSeconds, 0, 0, 86_400);
+    const includeIdle = input.includeIdle === true;
+    const includeSystem = input.includeSystem === true;
+    const includeInfo = input.includeInfo === true;
+    const infoMaxChars = clampInteger(input.infoMaxChars, 256, 32, 2048);
+    const selectedColumns = [
+        "ID AS session_id",
+        "USER AS user",
+        "HOST AS host",
+        "DB AS database_name",
+        "COMMAND AS command",
+        "TIME AS time_seconds",
+        "STATE AS state",
+    ];
+    if (includeInfo) {
+        selectedColumns.push("INFO AS info_preview");
+    }
+    const whereClauses = [];
+    if (!includeIdle) {
+        whereClauses.push("COMMAND <> 'Sleep'");
+    }
+    if (!includeSystem) {
+        whereClauses.push("USER <> 'system user'");
+    }
+    if (input.user) {
+        whereClauses.push(`USER = ${quoteLiteral(input.user)}`);
+    }
+    if (input.host) {
+        whereClauses.push(`HOST LIKE ${quoteLiteral(`${escapeLikePrefix(input.host)}%`)} ESCAPE '\\'`);
+    }
+    if (input.sessionDatabase) {
+        whereClauses.push(`DB = ${quoteLiteral(input.sessionDatabase)}`);
+    }
+    if (input.command) {
+        whereClauses.push(`COMMAND = ${quoteLiteral(input.command)}`);
+    }
+    if (minTimeSeconds > 0) {
+        whereClauses.push(`TIME >= ${minTimeSeconds}`);
+    }
+    const sql = `
+      SELECT ${selectedColumns.join(", ")}
+      FROM information_schema.PROCESSLIST
+      ${whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : ""}
+      ORDER BY TIME DESC, ID DESC
+      LIMIT ${maxRows}
+    `.trim();
+    return engine.executor.executeReadonly(sql, ctx, {
+        maxRows,
+        maxColumns: selectedColumns.length,
+        maxFieldChars: includeInfo ? infoMaxChars : 256,
+        timeoutMs: ctx.limits.timeoutMs,
+    });
+}

package/dist/engine/data-access/statements.d.ts

@@ -0,0 +1,10 @@
+import type { SessionContext } from "../../context/session-context.js";
+import type { FindTopSlowSqlInput } from "../../diagnostics/types.js";
+import type { TaurusDBEngine } from "../../engine.js";
+import { type StatementDigestRow, type StatementWaitEventRow } from "../helpers.js";
+export declare function findStatementDigestSample(engine: TaurusDBEngine, digestText: string, ctx: SessionContext): Promise<StatementDigestRow | undefined>;
+export declare function findStatementDigestSampleForSql(engine: TaurusDBEngine, sql: string, ctx: SessionContext): Promise<StatementDigestRow | undefined>;
+export declare function findStatementDigestCandidatesForSqlHints(engine: TaurusDBEngine, sqlText: string, ctx: SessionContext): Promise<StatementDigestRow[]>;
+export declare function findTopStatementDigests(engine: TaurusDBEngine, input: FindTopSlowSqlInput, ctx: SessionContext): Promise<StatementDigestRow[]>;
+export declare function isPerformanceSchemaEnabled(engine: TaurusDBEngine, ctx: SessionContext): Promise<boolean | undefined>;
+export declare function findStatementWaitEvents(engine: TaurusDBEngine, digestText: string, ctx: SessionContext): Promise<StatementWaitEventRow[]>;

package/dist/engine/data-access/statements.js

@@ -0,0 +1,203 @@
+import { clampInteger, digestMatchScore, escapeLikePrefix, extractSqlTableNameHints, parseStatementDigestRows, parseStatementWaitEventRows, quoteLiteral, topSlowSqlOrderBy, } from "../helpers.js";
+export async function findStatementDigestSample(engine, digestText, ctx) {
+    const whereClauses = [`DIGEST_TEXT = ${quoteLiteral(digestText)}`];
+    if (ctx.database) {
+        whereClauses.push(`SCHEMA_NAME = ${quoteLiteral(ctx.database)}`);
+    }
+    const sql = `
+      SELECT
+        SCHEMA_NAME AS schema_name,
+        DIGEST AS digest,
+        DIGEST_TEXT AS digest_text,
+        QUERY_SAMPLE_TEXT AS query_sample_text,
+        COUNT_STAR AS exec_count,
+        ROUND(AVG_TIMER_WAIT / 1000000000, 3) AS avg_latency_ms,
+        ROUND(SUM_TIMER_WAIT / 1000000000, 3) AS total_latency_ms,
+        ROUND(MAX_TIMER_WAIT / 1000000000, 3) AS max_latency_ms,
+        ROUND(SUM_LOCK_TIME / 1000000000 / NULLIF(COUNT_STAR, 0), 3) AS avg_lock_time_ms,
+        ROUND(SUM_ROWS_EXAMINED / NULLIF(COUNT_STAR, 0), 3) AS avg_rows_examined,
+        ROUND(SUM_SORT_ROWS / NULLIF(COUNT_STAR, 0), 3) AS avg_sort_rows,
+        ROUND(SUM_CREATED_TMP_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_tables,
+        ROUND(SUM_CREATED_TMP_DISK_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_disk_tables,
+        SUM_SELECT_SCAN AS select_scan_count,
+        SUM_NO_INDEX_USED AS no_index_used_count
+      FROM performance_schema.events_statements_summary_by_digest
+      WHERE ${whereClauses.join(" AND ")}
+      ORDER BY SUM_TIMER_WAIT DESC, COUNT_STAR DESC
+      LIMIT 1
+    `.trim();
+    const result = await engine.executor.executeReadonly(sql, ctx, {
+        maxRows: 1,
+        maxColumns: 15,
+        maxFieldChars: 2048,
+        timeoutMs: ctx.limits.timeoutMs,
+    });
+    return parseStatementDigestRows(result)[0];
+}
+export async function findStatementDigestSampleForSql(engine, sql, ctx) {
+    const candidates = await engine.findTopStatementDigests({
+        database: ctx.database,
+        topN: 20,
+        sortBy: "total_latency",
+    }, ctx);
+    const ranked = candidates
+        .map((candidate) => ({
+        candidate,
+        score: digestMatchScore(sql, candidate),
+    }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score ||
+        (right.candidate.totalLatencyMs ?? 0) -
+            (left.candidate.totalLatencyMs ?? 0) ||
+        (right.candidate.execCount ?? 0) - (left.candidate.execCount ?? 0));
+    if (ranked[0]?.candidate) {
+        return ranked[0].candidate;
+    }
+    const hintCandidates = await engine.findStatementDigestCandidatesForSqlHints(sql, ctx).catch(() => []);
+    return hintCandidates
+        .map((candidate) => ({
+        candidate,
+        score: digestMatchScore(sql, candidate),
+    }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score ||
+        (right.candidate.totalLatencyMs ?? 0) -
+            (left.candidate.totalLatencyMs ?? 0) ||
+        (right.candidate.execCount ?? 0) - (left.candidate.execCount ?? 0))[0]?.candidate;
+}
+export async function findStatementDigestCandidatesForSqlHints(engine, sqlText, ctx) {
+    const tableHints = extractSqlTableNameHints(sqlText).slice(0, 3);
+    if (tableHints.length === 0) {
+        return [];
+    }
+    const whereClauses = ["DIGEST_TEXT IS NOT NULL", "DIGEST_TEXT <> 'NULL'"];
+    if (ctx.database) {
+        whereClauses.push(`SCHEMA_NAME = ${quoteLiteral(ctx.database)}`);
+    }
+    const tableClauses = tableHints.map((table) => {
+        const tableLike = quoteLiteral(`%${escapeLikePrefix(table)}%`);
+        return `(DIGEST_TEXT LIKE ${tableLike} ESCAPE '\\\\' OR QUERY_SAMPLE_TEXT LIKE ${tableLike} ESCAPE '\\\\')`;
+    });
+    whereClauses.push(`(${tableClauses.join(" OR ")})`);
+    const sql = `
+      SELECT
+        SCHEMA_NAME AS schema_name,
+        DIGEST AS digest,
+        DIGEST_TEXT AS digest_text,
+        QUERY_SAMPLE_TEXT AS query_sample_text,
+        COUNT_STAR AS exec_count,
+        ROUND(AVG_TIMER_WAIT / 1000000000, 3) AS avg_latency_ms,
+        ROUND(SUM_TIMER_WAIT / 1000000000, 3) AS total_latency_ms,
+        ROUND(MAX_TIMER_WAIT / 1000000000, 3) AS max_latency_ms,
+        ROUND(SUM_LOCK_TIME / 1000000000 / NULLIF(COUNT_STAR, 0), 3) AS avg_lock_time_ms,
+        ROUND(SUM_ROWS_EXAMINED / NULLIF(COUNT_STAR, 0), 3) AS avg_rows_examined,
+        ROUND(SUM_SORT_ROWS / NULLIF(COUNT_STAR, 0), 3) AS avg_sort_rows,
+        ROUND(SUM_CREATED_TMP_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_tables,
+        ROUND(SUM_CREATED_TMP_DISK_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_disk_tables,
+        SUM_SELECT_SCAN AS select_scan_count,
+        SUM_NO_INDEX_USED AS no_index_used_count
+      FROM performance_schema.events_statements_summary_by_digest
+      WHERE ${whereClauses.join(" AND ")}
+      ORDER BY SUM_TIMER_WAIT DESC, AVG_TIMER_WAIT DESC, COUNT_STAR DESC
+      LIMIT 50
+    `.trim();
+    const result = await engine.executor.executeReadonly(sql, ctx, {
+        maxRows: 50,
+        maxColumns: 15,
+        maxFieldChars: 4096,
+        timeoutMs: ctx.limits.timeoutMs,
+    });
+    return parseStatementDigestRows(result);
+}
+export async function findTopStatementDigests(engine, input, ctx) {
+    const maxRows = clampInteger(input.topN, 5, 1, 20);
+    const whereClauses = ["DIGEST_TEXT IS NOT NULL", "DIGEST_TEXT <> 'NULL'"];
+    if (ctx.database) {
+        whereClauses.push(`SCHEMA_NAME = ${quoteLiteral(ctx.database)}`);
+    }
+    const sql = `
+      SELECT
+        SCHEMA_NAME AS schema_name,
+        DIGEST AS digest,
+        DIGEST_TEXT AS digest_text,
+        QUERY_SAMPLE_TEXT AS query_sample_text,
+        COUNT_STAR AS exec_count,
+        ROUND(AVG_TIMER_WAIT / 1000000000, 3) AS avg_latency_ms,
+        ROUND(SUM_TIMER_WAIT / 1000000000, 3) AS total_latency_ms,
+        ROUND(MAX_TIMER_WAIT / 1000000000, 3) AS max_latency_ms,
+        ROUND(SUM_LOCK_TIME / 1000000000 / NULLIF(COUNT_STAR, 0), 3) AS avg_lock_time_ms,
+        ROUND(SUM_ROWS_EXAMINED / NULLIF(COUNT_STAR, 0), 3) AS avg_rows_examined,
+        ROUND(SUM_SORT_ROWS / NULLIF(COUNT_STAR, 0), 3) AS avg_sort_rows,
+        ROUND(SUM_CREATED_TMP_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_tables,
+        ROUND(SUM_CREATED_TMP_DISK_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_disk_tables,
+        SUM_SELECT_SCAN AS select_scan_count,
+        SUM_NO_INDEX_USED AS no_index_used_count
+      FROM performance_schema.events_statements_summary_by_digest
+      WHERE ${whereClauses.join(" AND ")}
+      ORDER BY ${topSlowSqlOrderBy(input.sortBy)}
+      LIMIT ${maxRows}
+    `.trim();
+    const result = await engine.executor.executeReadonly(sql, ctx, {
+        maxRows,
+        maxColumns: 15,
+        maxFieldChars: 4096,
+        timeoutMs: ctx.limits.timeoutMs,
+    });
+    return parseStatementDigestRows(result);
+}
+export async function isPerformanceSchemaEnabled(engine, ctx) {
+    try {
+        const result = await engine.executor.executeReadonly("SELECT @@performance_schema AS performance_schema_enabled", ctx, {
+            maxRows: 1,
+            maxColumns: 1,
+            maxFieldChars: 64,
+            timeoutMs: ctx.limits.timeoutMs,
+        });
+        const value = result.rows?.[0]?.[0];
+        if (typeof value === "number") {
+            return value === 1;
+        }
+        if (typeof value === "string") {
+            return value === "1" || value.toLowerCase() === "on";
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function findStatementWaitEvents(engine, digestText, ctx) {
+    const whereClauses = [`stmt.DIGEST_TEXT = ${quoteLiteral(digestText)}`];
+    if (ctx.database) {
+        whereClauses.push(`stmt.CURRENT_SCHEMA = ${quoteLiteral(ctx.database)}`);
+    }
+    const sql = `
+      SELECT
+        waits.EVENT_NAME AS event_name,
+        COUNT(*) AS sample_count,
+        COUNT(DISTINCT CONCAT(stmt.THREAD_ID, ':', stmt.EVENT_ID)) AS statement_count,
+        ROUND(SUM(waits.TIMER_WAIT) / 1000000000, 3) AS total_wait_ms,
+        ROUND(AVG(waits.TIMER_WAIT) / 1000000000, 3) AS avg_wait_ms
+      FROM performance_schema.events_statements_history_long AS stmt
+      INNER JOIN performance_schema.events_waits_history_long AS waits
+        ON waits.THREAD_ID = stmt.THREAD_ID
+        AND waits.NESTING_EVENT_ID = stmt.EVENT_ID
+        AND waits.NESTING_EVENT_TYPE = 'STATEMENT'
+      WHERE ${whereClauses.join(" AND ")}
+      GROUP BY waits.EVENT_NAME
+      ORDER BY total_wait_ms DESC, sample_count DESC, event_name ASC
+      LIMIT 3
+    `.trim();
+    try {
+        const result = await engine.executor.executeReadonly(sql, ctx, {
+            maxRows: 3,
+            maxColumns: 5,
+            maxFieldChars: 256,
+            timeoutMs: ctx.limits.timeoutMs,
+        });
+        return parseStatementWaitEventRows(result);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/engine/data-access/storage.d.ts

@@ -0,0 +1,6 @@
+import type { SessionContext } from "../../context/session-context.js";
+import type { DiagnoseStoragePressureInput } from "../../diagnostics/types.js";
+import type { TaurusDBEngine } from "../../engine.js";
+import { type StatementDigestRow, type TableStorageRow } from "../helpers.js";
+export declare function findStorageStatementDigests(engine: TaurusDBEngine, input: DiagnoseStoragePressureInput, ctx: SessionContext): Promise<StatementDigestRow[]>;
+export declare function findTableStorageStats(engine: TaurusDBEngine, input: DiagnoseStoragePressureInput, ctx: SessionContext): Promise<TableStorageRow[]>;