pgexplain 0.1.0 → 0.3.0

package/dist/server.js

@@ -0,0 +1,4166 @@
+import { fileURLToPath } from 'url';
+import { serve } from '@hono/node-server';
+import { readFile, stat, mkdir, writeFile } from 'fs/promises';
+import { resolve, join, normalize, extname } from 'path';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import pc from 'picocolors';
+import { mkdirSync } from 'fs';
+import { homedir } from 'os';
+import Database from 'better-sqlite3';
+
+// src/server/start.ts
+
+// src/diagnostics/diagnostic.ts
+var AppError = class extends Error {
+  diagnostic;
+  exitCode;
+  constructor(diagnostic, exitCode, cause) {
+    super(diagnostic.title);
+    this.name = "AppError";
+    this.diagnostic = diagnostic;
+    this.exitCode = exitCode;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+function finding(code, severity, parts) {
+  return { code, domain: "plan", severity, ...parts };
+}
+var SEVERITY_RANK = { error: 0, warn: 1, info: 2 };
+function bySeverity(a, b) {
+  return SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+}
+function maxSeverity(a, b) {
+  return SEVERITY_RANK[a] <= SEVERITY_RANK[b] ? a : b;
+}
+function scrubCredentials(input) {
+  if (!input) return input;
+  return input.replace(/(\b[a-z][a-z0-9+.-]*:\/\/[^:/?#@\s]+:)([^@\s]+)(@)/gi, "$1***$3").replace(/\bpassword\s*=\s*'[^']*'/gi, "password='***'").replace(/(\bpassword\s*=\s*)([^\s&'"]+)/gi, "$1***").replace(/(\bPGPASSWORD\s*=\s*)([^\s&'"]+)/gi, "$1***");
+}
+
+// package.json
+var package_default = {
+  version: "0.3.0"};
+
+// src/diagnostics/catalog.ts
+var DOCS = "https://www.postgresql.org/docs/current";
+var CATALOG = {
+  PGX_AUTH_FAILED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Authentication failed",
+    detail: "The server rejected the supplied credentials.",
+    cause: "The password or role is wrong, or pg_hba.conf does not permit this role from your host.",
+    remediation: {
+      summary: "Verify the credentials and supply the password safely (never on the command line).",
+      steps: [
+        "Confirm the username and password are correct.",
+        "Provide the password via PGPASSWORD or ~/.pgpass instead of the command line.",
+        "Check that pg_hba.conf allows this role from your client host."
+      ],
+      commands: [
+        { label: "Set password via env", shell: "export PGPASSWORD=<password>" },
+        {
+          label: "Or store it (chmod 600)",
+          shell: 'echo "<host>:<port>:<db>:<user>:<password>" >> ~/.pgpass && chmod 600 ~/.pgpass'
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/auth-pg-hba-conf.html`
+  },
+  PGX_HOST_UNREACHABLE: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Cannot reach the PostgreSQL server",
+    detail: "DNS resolution failed or the TCP connection was refused.",
+    cause: "Wrong host/port, the server is down, or a firewall/VPN/security group is blocking the port.",
+    remediation: {
+      summary: "Verify the host and port, then probe reachability.",
+      steps: [
+        "Double-check --host and --port (or the DSN) for typos.",
+        "Confirm the server is running and accepts TCP connections.",
+        "Check VPN, firewall, and cloud security-group rules for the port."
+      ],
+      commands: [{ label: "Probe reachability", shell: "pg_isready -h <host> -p <port>" }]
+    },
+    docsUrl: `${DOCS}/libpq-connect.html`
+  },
+  PGX_DB_NOT_FOUND: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Database does not exist",
+    detail: "The named database was not found on the server.",
+    cause: "The database name is misspelled or the database has not been created.",
+    remediation: {
+      summary: "List the available databases and correct the name.",
+      commands: [
+        { label: "List databases", shell: "psql -h <host> -U <user> -l" },
+        { label: "Re-run with the right name", shell: "pg-explain run --dbname <name> ..." }
+      ]
+    }
+  },
+  PGX_SSL_REQUIRED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Server requires SSL",
+    detail: "The server requires an encrypted connection but a plaintext one was offered.",
+    cause: "pg_hba.conf mandates SSL (e.g. `hostssl`) for this role/host.",
+    remediation: {
+      summary: "Enable SSL on the connection.",
+      commands: [
+        { label: "Require encryption", shell: "pg-explain run --sslmode require ..." },
+        {
+          label: "Or verify the certificate too",
+          shell: "pg-explain run --sslmode verify-full --sslrootcert <ca.pem> ..."
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/libpq-ssl.html`
+  },
+  PGX_SSL_VERIFY_FAILED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "TLS certificate verification failed",
+    detail: "Under verify-full the certificate chain is untrusted or the hostname does not match.",
+    cause: "The CA is not trusted locally, or the certificate's CN/SAN does not match the host you connect to.",
+    remediation: {
+      summary: "Point at the CA bundle and confirm the hostname matches the certificate.",
+      steps: [
+        "Provide the CA certificate the server's cert chains to.",
+        "Confirm the certificate CN/SAN matches the --host value.",
+        "Only fall back to `--sslmode require` (encryption without identity check) if you accept the risk."
+      ],
+      commands: [
+        {
+          label: "Trust a CA",
+          shell: "pg-explain run --sslmode verify-full --sslrootcert <ca.pem> ..."
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/libpq-ssl.html`
+  },
+  PGX_CONN_TIMEOUT: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Connection timed out",
+    detail: "The connect handshake did not complete within the connect deadline.",
+    cause: "High network latency, an overloaded server, or a firewall silently dropping packets.",
+    remediation: {
+      summary: "Raise the connect budget and investigate the network path.",
+      commands: [
+        { label: "Increase connect timeout", shell: "pg-explain run --connect-timeout 30s ..." }
+      ]
+    },
+    docsUrl: `${DOCS}/libpq-connect.html`
+  },
+  PGX_PERMISSION_DENIED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Permission denied",
+    detail: "The connecting role lacks a privilege the query needs.",
+    cause: "EXPLAIN must plan the query, which requires SELECT (and any referenced privileges) on the relations.",
+    remediation: {
+      summary: "Grant the missing privilege, or connect with a role that already has it.",
+      commands: [
+        { label: "Grant SELECT (run as owner)", sql: "GRANT SELECT ON <table> TO <role>;" }
+      ]
+    },
+    docsUrl: `${DOCS}/sql-grant.html`
+  },
+  PGX_RELATION_NOT_FOUND: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Relation does not exist",
+    detail: "A table or view referenced by the query was not found.",
+    cause: "The name is misspelled, or it lives in a schema that is not on the search_path.",
+    remediation: {
+      summary: "Schema-qualify the relation or set the search_path.",
+      steps: ["Check spelling and the schema.", "List tables with `\\dt` in psql."],
+      commands: [{ label: "Set the search path", sql: "SET search_path = <schema>, public;" }]
+    }
+  },
+  PGX_STATEMENT_TIMEOUT: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Statement timeout reached",
+    detail: "statement_timeout fired while EXPLAIN ANALYZE was executing the query.",
+    cause: "The query genuinely takes longer than the configured statement_timeout to run.",
+    remediation: {
+      summary: "Raise the timeout, or avoid executing the query at all.",
+      steps: [
+        "Raise the per-run statement timeout.",
+        "Or get an estimate-only plan that never executes (drop --analyze).",
+        "Or reduce measurement overhead with --timing off."
+      ],
+      commands: [
+        { label: "Raise the timeout", shell: "pg-explain run --statement-timeout 60s ..." }
+      ]
+    },
+    docsUrl: `${DOCS}/runtime-config-client.html#GUC-STATEMENT-TIMEOUT`
+  },
+  PGX_LOCK_TIMEOUT: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Lock timeout reached",
+    detail: "lock_timeout elapsed while waiting to acquire a lock on a relation.",
+    cause: "Another transaction holds a conflicting lock on a relation the query touches.",
+    remediation: {
+      summary: "Raise the lock timeout, identify the blocker, or retry off-peak.",
+      commands: [
+        { label: "Raise the lock timeout", shell: "pg-explain run --lock-timeout 30s ..." },
+        {
+          label: "Find blockers",
+          sql: "SELECT * FROM pg_locks l JOIN pg_stat_activity a USING (pid) WHERE NOT l.granted;"
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/runtime-config-client.html#GUC-LOCK-TIMEOUT`
+  },
+  PGX_QUERY_CANCELED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Query was canceled",
+    detail: "The query was canceled by an administrator or a signal before completing.",
+    cause: "An admin pg_cancel_backend call, a resource group, or a pool limit canceled the statement.",
+    remediation: {
+      summary: "Re-run the command; if it recurs, check for admin cancellation or pool limits."
+    }
+  },
+  PGX_UNSUPPORTED_PG_VERSION: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "EXPLAIN option not supported by this server",
+    detail: "A requested EXPLAIN option requires a newer PostgreSQL major version.",
+    cause: "Options are version-gated (e.g. SETTINGS\u226512, WAL\u226513, GENERIC_PLAN\u226516, SERIALIZE/MEMORY\u226517).",
+    remediation: {
+      summary: "Drop the unsupported option, target a newer server, or let pg-explain auto-omit it.",
+      commands: [{ label: "Auto-omit unsupported options", shell: "pg-explain run --compat ..." }]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_INVALID_EXPLAIN_OPTION: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "Invalid EXPLAIN option combination",
+    detail: "The server rejected an EXPLAIN option or a mutually-exclusive combination.",
+    cause: "Some options require ANALYZE (WAL, SERIALIZE, TIMING) and GENERIC_PLAN is incompatible with ANALYZE.",
+    remediation: {
+      summary: "Fix the option combination; see `pg-explain --help` for valid combinations.",
+      steps: [
+        "WAL/SERIALIZE/TIMING require --analyze.",
+        "GENERIC_PLAN cannot be combined with --analyze."
+      ]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_MALFORMED_JSON: {
+    severity: "error",
+    exit: 4 /* Parse */,
+    title: "Input is not valid JSON",
+    detail: "The plan input could not be parsed as JSON.",
+    cause: "The input was truncated when captured, or it is not EXPLAIN (FORMAT JSON) output.",
+    remediation: {
+      summary: "Validate the input and make sure it is FORMAT JSON output.",
+      commands: [{ label: "Validate JSON", shell: "jq . plan.json" }]
+    }
+  },
+  PGX_UNEXPECTED_PLAN_SHAPE: {
+    severity: "error",
+    exit: 4 /* Parse */,
+    title: "Input is not an EXPLAIN plan",
+    detail: "The JSON parsed but does not contain a recognizable EXPLAIN plan tree.",
+    cause: "The 'Plan' node is missing \u2014 this may be query result rows rather than a plan.",
+    remediation: {
+      summary: "Regenerate the plan with FORMAT JSON and pipe that in.",
+      commands: [
+        { label: "Capture a plan", sql: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <your query>;" }
+      ]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_EMPTY_INPUT: {
+    severity: "error",
+    exit: 3 /* Input */,
+    title: "No plan input received",
+    detail: "stdin and the named file were both empty.",
+    cause: "No plan was piped in and no query/file was provided.",
+    remediation: {
+      summary: "Pipe a plan, or provide SQL to run.",
+      commands: [
+        { label: "Analyze a saved plan", shell: "pg-explain < plan.json" },
+        { label: "Or run a query", shell: 'pg-explain run --query "<sql>" --dsn <dsn>' }
+      ]
+    }
+  },
+  PGX_NON_SELECT_REFUSED: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "Refusing to ANALYZE a data-modifying statement",
+    detail: "EXPLAIN ANALYZE executes the statement, and this one would modify data.",
+    cause: "INSERT/UPDATE/DELETE/MERGE/DDL run for real under ANALYZE; running it could change your data.",
+    remediation: {
+      summary: "Use --force to run it inside an automatically rolled-back transaction, or drop --analyze.",
+      steps: [
+        "With --force, pg-explain wraps it as `BEGIN; <stmt>; ROLLBACK;` so nothing is committed.",
+        "Without --analyze you get an estimate-only plan that never executes."
+      ],
+      commands: [
+        {
+          label: "Run safely (auto-rollback)",
+          shell: "pg-explain run --force --file mutation.sql --dsn <dsn>"
+        }
+      ]
+    }
+  },
+  PGX_MULTIPLE_STATEMENTS: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "Multiple SQL statements found",
+    detail: "The input contains more than one statement; pg-explain analyzes one at a time.",
+    cause: "A .sql file or --query string contained several semicolon-separated statements.",
+    remediation: {
+      summary: "Select one statement, or split them into separate invocations.",
+      commands: [
+        {
+          label: "Pick the Nth statement (1-based)",
+          shell: "pg-explain run --statement 2 --file queries.sql --dsn <dsn>"
+        }
+      ]
+    }
+  },
+  PGX_COST_ONLY_PLAN: {
+    severity: "info",
+    exit: 0 /* Success */,
+    title: "Cost-only plan \u2014 estimate-vs-actual checks unavailable",
+    detail: "This plan has cost estimates but no actual row/time data.",
+    cause: "It was produced by plain EXPLAIN (without ANALYZE), so runtime behavior is unknown.",
+    remediation: {
+      summary: "Re-run with ANALYZE to unlock estimate-vs-actual, timing, and spill findings.",
+      commands: [
+        { label: "Capture actuals", sql: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>;" }
+      ]
+    },
+    docsUrl: `${DOCS}/using-explain.html#USING-EXPLAIN-ANALYZE`
+  },
+  PGX_NO_BUFFERS: {
+    severity: "info",
+    exit: 0 /* Success */,
+    title: "No BUFFERS data \u2014 cache/I/O analysis skipped",
+    detail: "Buffer counters are absent, so cache-hit ratio and I/O findings cannot be computed.",
+    cause: "The plan was captured without BUFFERS.",
+    remediation: {
+      summary: "Add BUFFERS to surface shared/temp block usage and the cache-hit ratio.",
+      commands: [
+        { label: "Capture buffers", sql: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>;" }
+      ]
+    }
+  },
+  PGX_EMPTY_PLAN: {
+    severity: "info",
+    exit: 0 /* Success */,
+    title: "Nothing to analyze",
+    detail: "The plan has no scans or joins to evaluate (e.g. a bare Result node).",
+    cause: "The query is trivial and has no tuning surface.",
+    remediation: { summary: "Confirm this is the query you intended to profile." }
+  },
+  PGX_PG_DRIVER_MISSING: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "The 'pg' driver is not installed",
+    detail: "The run command needs the PostgreSQL driver, which is an optional dependency.",
+    cause: "pgexplain ships 'pg' as optional so plan-only use stays dependency-free; it isn't installed here.",
+    remediation: {
+      summary: "Install the pg driver, then re-run. (Plan-only analysis from a file/stdin needs no driver.)",
+      commands: [
+        { label: "with pnpm", shell: "pnpm add pg" },
+        { label: "with npm", shell: "npm install pg" }
+      ]
+    }
+  },
+  PGX_QUERY_FAILED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "The query could not be planned or executed",
+    detail: "PostgreSQL returned an error while running EXPLAIN.",
+    cause: "The statement has a syntax error, references something invalid, or hit a server-side limit.",
+    remediation: {
+      summary: "Read the server message below, fix the statement, and re-run. Test it in psql first if unsure.",
+      commands: [{ label: "Try it directly", shell: 'psql "<dsn>" -c "EXPLAIN <your statement>"' }]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_INTERNAL: {
+    severity: "error",
+    exit: 70 /* Internal */,
+    title: "pg-explain hit an unexpected error",
+    detail: "This is a bug in pg-explain, not in your query or plan.",
+    cause: "An unhandled condition was reached.",
+    remediation: {
+      summary: "Re-run with --debug for a credential-scrubbed stack trace, then file an issue.",
+      commands: [
+        { label: "Show the trace", shell: "pg-explain --debug ..." },
+        { label: "Report your version", shell: "pg-explain --version" }
+      ]
+    }
+  }
+};
+function opDiagnostic(code, overrides = {}) {
+  const spec = CATALOG[code];
+  const diag = {
+    code,
+    domain: "operational",
+    severity: spec.severity,
+    title: spec.title,
+    detail: overrides.detail ?? spec.detail,
+    cause: spec.cause,
+    remediation: spec.remediation
+  };
+  if (spec.docsUrl) diag.docsUrl = spec.docsUrl;
+  if (overrides.location) diag.location = overrides.location;
+  if (overrides.meta) diag.meta = overrides.meta;
+  return diag;
+}
+function opError(code, overrides = {}, cause) {
+  return new AppError(opDiagnostic(code, overrides), CATALOG[code].exit, cause);
+}
+function logVerbose(msg) {
+}
+
+// src/db/version.ts
+function capabilities(versionNum) {
+  const major = Math.floor(versionNum / 1e4);
+  return {
+    versionNum,
+    major,
+    summary: major >= 10,
+    settings: major >= 12,
+    wal: major >= 13,
+    genericPlan: major >= 16,
+    serialize: major >= 17,
+    memory: major >= 17
+  };
+}
+function versionLabel(versionNum) {
+  const major = Math.floor(versionNum / 1e4);
+  const minor = versionNum % 100;
+  return `${major}.${minor}`;
+}
+
+// src/db/explain.ts
+var DEFAULT_EXPLAIN_FLAGS = {
+  analyze: true,
+  buffers: true,
+  verbose: false,
+  settings: false,
+  wal: false,
+  timing: true,
+  costs: true,
+  summary: true,
+  genericPlan: false,
+  compat: false
+};
+function buildExplain(flags, caps) {
+  if (flags.genericPlan && flags.analyze) {
+    throw opError("PGX_INVALID_EXPLAIN_OPTION", {
+      detail: "GENERIC_PLAN cannot be combined with ANALYZE (GENERIC_PLAN does not execute the query)."
+    });
+  }
+  if (flags.wal && !flags.analyze) {
+    throw opError("PGX_INVALID_EXPLAIN_OPTION", { detail: "WAL requires ANALYZE." });
+  }
+  const opts = ["FORMAT JSON"];
+  const omitted = [];
+  const gate = (label, supported, requiredMajor) => {
+    if (supported) return true;
+    if (flags.compat) {
+      omitted.push(label);
+      return false;
+    }
+    throw opError("PGX_UNSUPPORTED_PG_VERSION", {
+      detail: `EXPLAIN (${label}) requires PostgreSQL ${requiredMajor}; server is ${versionLabel(caps.versionNum)}.`,
+      meta: { option: label, requiredMajor, serverVersion: caps.versionNum }
+    });
+  };
+  if (flags.genericPlan && gate("GENERIC_PLAN", caps.genericPlan, 16)) opts.push("GENERIC_PLAN");
+  if (flags.analyze) opts.push("ANALYZE");
+  if (flags.buffers) opts.push("BUFFERS");
+  if (flags.verbose) opts.push("VERBOSE");
+  if (flags.settings && gate("SETTINGS", caps.settings, 12)) opts.push("SETTINGS");
+  if (flags.wal && gate("WAL", caps.wal, 13)) opts.push("WAL");
+  if (!flags.costs) opts.push("COSTS OFF");
+  if (flags.analyze && !flags.timing) opts.push("TIMING OFF");
+  if (!flags.summary && caps.summary) opts.push("SUMMARY OFF");
+  return { prefix: `EXPLAIN (${opts.join(", ")})`, omitted };
+}
+function leadingKeyword(sql) {
+  const cleaned = sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n]*/g, " ").trim();
+  return (cleaned.split(/\s+/)[0] ?? "").toUpperCase();
+}
+function isReadOnlyStatement(sql) {
+  const kw = leadingKeyword(sql);
+  if (["SELECT", "TABLE", "VALUES", "SHOW", "EXPLAIN"].includes(kw)) return true;
+  if (kw === "WITH") return !/\b(INSERT|UPDATE|DELETE|MERGE)\b/i.test(sql);
+  return false;
+}
+function splitStatements(sql) {
+  const out = [];
+  let buf = "";
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const ch = sql[i];
+    const two = sql.slice(i, i + 2);
+    if (two === "--") {
+      const nl = sql.indexOf("\n", i);
+      const end = nl === -1 ? n : nl;
+      buf += sql.slice(i, end);
+      i = end;
+    } else if (two === "/*") {
+      const close = sql.indexOf("*/", i + 2);
+      const end = close === -1 ? n : close + 2;
+      buf += sql.slice(i, end);
+      i = end;
+    } else if (ch === "'" || ch === '"') {
+      const end = scanQuoted(sql, i, ch);
+      buf += sql.slice(i, end);
+      i = end;
+    } else if (ch === "$") {
+      const tag = matchDollarTag(sql, i);
+      if (tag) {
+        const close = sql.indexOf(tag, i + tag.length);
+        const end = close === -1 ? n : close + tag.length;
+        buf += sql.slice(i, end);
+        i = end;
+      } else {
+        buf += ch;
+        i++;
+      }
+    } else if (ch === ";") {
+      if (buf.trim()) out.push(buf.trim());
+      buf = "";
+      i++;
+    } else {
+      buf += ch;
+      i++;
+    }
+  }
+  if (buf.trim()) out.push(buf.trim());
+  return out;
+}
+function scanQuoted(sql, start, quote) {
+  let i = start + 1;
+  while (i < sql.length) {
+    if (sql[i] === quote) {
+      if (sql[i + 1] === quote)
+        i += 2;
+      else return i + 1;
+    } else {
+      i++;
+    }
+  }
+  return sql.length;
+}
+function matchDollarTag(sql, start) {
+  const m = /^\$[A-Za-z_]*\$/.exec(sql.slice(start));
+  return m ? m[0] : null;
+}
+
+// src/db/client.ts
+async function newClient(config) {
+  let mod;
+  try {
+    mod = await import('pg');
+  } catch (err) {
+    throw opError("PGX_PG_DRIVER_MISSING", {}, err);
+  }
+  const lib = mod.default ?? mod;
+  return new lib.Client(config);
+}
+function buildClientConfig(c, ca) {
+  const config = { connectionTimeoutMillis: c.connectTimeoutMs };
+  if (c.dsn) {
+    config.connectionString = c.dsn;
+  } else {
+    if (c.host) config.host = c.host;
+    if (c.port) config.port = c.port;
+    if (c.database) config.database = c.database;
+    if (c.user) config.user = c.user;
+    if (c.password) config.password = c.password;
+  }
+  if (c.sslmode && c.sslmode !== "disable" && c.sslmode !== "prefer") {
+    const verify = c.sslmode === "verify-ca" || c.sslmode === "verify-full";
+    config.ssl = ca ? { rejectUnauthorized: verify, ca } : { rejectUnauthorized: verify };
+  } else if (c.sslmode === "disable") {
+    config.ssl = false;
+  }
+  return config;
+}
+async function runExplain(opts) {
+  const ca = opts.connection.sslrootcert ? await readFile(opts.connection.sslrootcert, "utf8").catch((err) => {
+    throw opError("PGX_SSL_VERIFY_FAILED", {
+      detail: `Could not read --sslrootcert '${opts.connection.sslrootcert}': ${err instanceof Error ? err.message : String(err)}`
+    });
+  }) : void 0;
+  const client = await newClient(buildClientConfig(opts.connection, ca));
+  try {
+    await client.connect();
+  } catch (err) {
+    throw mapConnectError(err);
+  }
+  try {
+    const verNum = await fetchVersionNum(client);
+    const caps = capabilities(verNum);
+    const built = buildExplain(opts.flags, caps);
+    const explainSql = `${built.prefix} ${opts.statement}`;
+    logVerbose(`server_version_num=${verNum}; ${built.prefix}`);
+    const useTxn = opts.rollback;
+    if (useTxn) await client.query("BEGIN");
+    try {
+      if (useTxn) {
+        await client.query(`SET LOCAL statement_timeout = ${msInt(opts.statementTimeoutMs)}`);
+        await client.query(`SET LOCAL lock_timeout = ${msInt(opts.lockTimeoutMs)}`);
+        if (!opts.forceWrite) await client.query("SET LOCAL transaction_read_only = on");
+      }
+      const res = await client.query({
+        text: explainSql,
+        values: opts.params ?? []
+      });
+      return { json: extractPlanJson(res.rows), caps, omitted: built.omitted };
+    } catch (err) {
+      throw mapQueryError(err);
+    } finally {
+      if (useTxn) await client.query("ROLLBACK").catch(() => {
+      });
+    }
+  } finally {
+    await client.end().catch(() => {
+    });
+  }
+}
+function msInt(ms) {
+  return Math.max(0, Math.floor(ms));
+}
+async function queryReadOnly(connection, sql, params = [], timeoutMs = 1e4) {
+  const ca = connection.sslrootcert ? await readFile(connection.sslrootcert, "utf8").catch(() => void 0) : void 0;
+  const client = await newClient(buildClientConfig(connection, ca));
+  try {
+    await client.connect();
+  } catch (err) {
+    throw mapConnectError(err);
+  }
+  try {
+    await client.query(`SET statement_timeout = ${msInt(timeoutMs)}`);
+    const res = await client.query({ text: sql, values: params });
+    return res.rows;
+  } catch (err) {
+    throw mapQueryError(err);
+  } finally {
+    await client.end().catch(() => {
+    });
+  }
+}
+async function explainScript(connection, units, opts) {
+  const ca = connection.sslrootcert ? await readFile(connection.sslrootcert, "utf8").catch(() => void 0) : void 0;
+  const client = await newClient(buildClientConfig(connection, ca));
+  try {
+    await client.connect();
+  } catch (err) {
+    throw mapConnectError(err);
+  }
+  try {
+    const caps = capabilities(await fetchVersionNum(client));
+    await client.query("BEGIN");
+    const results = [];
+    try {
+      await client.query(`SET LOCAL statement_timeout = ${msInt(opts.statementTimeoutMs)}`);
+      await client.query(`SET LOCAL lock_timeout = ${msInt(opts.lockTimeoutMs)}`);
+      await client.query("SET LOCAL transaction_read_only = on");
+      for (const unit of units) {
+        const flags = {
+          analyze: false,
+          // never execute
+          buffers: false,
+          // BUFFERS requires ANALYZE pre-16
+          verbose: opts.verbose ?? false,
+          settings: opts.settings ?? false,
+          wal: false,
+          timing: false,
+          costs: true,
+          summary: false,
+          genericPlan: caps.genericPlan && /\$\d+/.test(unit.sql),
+          compat: true
+          // auto-omit anything the server is too old for
+        };
+        try {
+          const { prefix } = buildExplain(flags, caps);
+          const res = await client.query(`${prefix} ${unit.sql}`);
+          const r = { label: unit.label, planJson: extractPlanJson(res.rows) };
+          if (unit.loopNote) r.loopNote = unit.loopNote;
+          results.push(r);
+        } catch (err) {
+          const diag = err instanceof AppError ? err.diagnostic : mapQueryError(err).diagnostic;
+          const r = { label: unit.label, error: diag };
+          if (unit.loopNote) r.loopNote = unit.loopNote;
+          results.push(r);
+          await client.query("ROLLBACK").catch(() => {
+          });
+          await client.query("BEGIN").catch(() => {
+          });
+          await client.query("SET LOCAL transaction_read_only = on").catch(() => {
+          });
+        }
+      }
+      return { units: results, caps };
+    } finally {
+      await client.query("ROLLBACK").catch(() => {
+      });
+    }
+  } finally {
+    await client.end().catch(() => {
+    });
+  }
+}
+async function fetchVersionNum(client) {
+  try {
+    const res = await client.query("SHOW server_version_num");
+    return Number(res.rows[0]?.server_version_num ?? 0);
+  } catch (err) {
+    throw mapQueryError(err);
+  }
+}
+function extractPlanJson(rows) {
+  const value = rows[0]?.["QUERY PLAN"];
+  if (value === void 0) {
+    throw opError("PGX_UNEXPECTED_PLAN_SHAPE", {
+      detail: "The server returned no plan rows for EXPLAIN."
+    });
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function asPgError(err) {
+  if (err && typeof err === "object") return err;
+  return { message: String(err) };
+}
+function mapConnectError(err) {
+  if (err instanceof AppError) return err;
+  const e = asPgError(err);
+  const msg = e.message ?? "";
+  switch (e.code) {
+    case "28P01":
+    case "28000":
+      return opError("PGX_AUTH_FAILED", { detail: msg }, err);
+    case "3D000":
+      return opError("PGX_DB_NOT_FOUND", { detail: msg }, err);
+    case "ECONNREFUSED":
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+    case "EHOSTUNREACH":
+      return opError("PGX_HOST_UNREACHABLE", { detail: msg }, err);
+    case "ETIMEDOUT":
+      return opError("PGX_CONN_TIMEOUT", { detail: msg }, err);
+  }
+  if (/timeout/i.test(msg)) return opError("PGX_CONN_TIMEOUT", { detail: msg }, err);
+  if (/self.signed|certificate|verify|CERT_/i.test(msg))
+    return opError("PGX_SSL_VERIFY_FAILED", { detail: msg }, err);
+  if (/SSL|encryption/i.test(msg)) return opError("PGX_SSL_REQUIRED", { detail: msg }, err);
+  return opError("PGX_HOST_UNREACHABLE", { detail: msg }, err);
+}
+function mapQueryError(err) {
+  if (err instanceof AppError) return err;
+  const e = asPgError(err);
+  const msg = e.message ?? "";
+  const meta = {};
+  if (e.code) meta.sqlState = e.code;
+  if (e.position) meta.position = Number(e.position);
+  switch (e.code) {
+    case "57014":
+      return /statement timeout/i.test(msg) ? opError("PGX_STATEMENT_TIMEOUT", { detail: msg, meta }, err) : opError("PGX_QUERY_CANCELED", { detail: msg, meta }, err);
+    case "55P03":
+      return opError("PGX_LOCK_TIMEOUT", { detail: msg, meta }, err);
+    case "42501":
+      return opError("PGX_PERMISSION_DENIED", { detail: msg, meta }, err);
+    case "42P01":
+      return opError("PGX_RELATION_NOT_FOUND", { detail: msg, meta }, err);
+    case "28P01":
+    case "28000":
+      return opError("PGX_AUTH_FAILED", { detail: msg, meta }, err);
+    case "3D000":
+      return opError("PGX_DB_NOT_FOUND", { detail: msg, meta }, err);
+    default:
+      return opError("PGX_QUERY_FAILED", { detail: msg, meta }, err);
+  }
+}
+var DEFAULT_THRESHOLDS = {
+  seqScanRows: 1e5,
+  nestedLoopOuterRows: 1e4,
+  filterDiscardRatio: 0.9,
+  filterRemovedAbs: 1e4,
+  misestimateFactor: 10,
+  heapFetchRatio: 0.1,
+  heapFetchAbs: 1e3,
+  correlatedLoops: 1e3,
+  jitPct: 25,
+  triggerPct: 10,
+  lowCacheHitRatio: 0.9,
+  limitDiscardRows: 1e4,
+  staleStatsModRatio: 0.2
+};
+var DEFAULT_CONFIG = {
+  thresholds: { ...DEFAULT_THRESHOLDS },
+  rules: {}
+};
+
+// src/core/parse-text.ts
+var cap = (w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase();
+var numeric = (v) => {
+  const t = v.trim();
+  return /^-?\d+(\.\d+)?$/.test(t) ? Number(t) : t;
+};
+function splitList(s) {
+  const out = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of s) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      if (cur.trim()) out.push(cur.trim());
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+function splitIntoLines(text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  const count = (s, re) => (s.match(re) || []).length;
+  const closingFirst = (s) => {
+    const c = s.indexOf(")");
+    const o = s.indexOf("(");
+    return c !== -1 && c < o;
+  };
+  const sameIndent = (a, b) => a.search(/\S/) === b.search(/\S/);
+  for (const line of lines) {
+    const prev = out[out.length - 1];
+    if (prev && count(prev, /\)/g) !== count(prev, /\(/g)) {
+      out[out.length - 1] += line;
+    } else if (/^(?:Total\s+runtime|Planning(\s+time)?|Execution\s+time|Time|Filter|Output|JIT|Trigger|Settings|Serialization)/i.test(
+      line
+    )) {
+      out.push(line);
+    } else if (/^\S/.test(line) || /^\s*\(/.test(line) || closingFirst(line)) {
+      if (prev) out[out.length - 1] += line;
+      else out.push(line);
+    } else if (prev && /,\s*$/.test(prev) && !sameIndent(prev, line) && !/^\s*->/i.test(line)) {
+      out[out.length - 1] += line;
+    } else {
+      out.push(line);
+    }
+  }
+  return out;
+}
+var estimation = String.raw`\(cost=(\d+\.\d+)\.\.(\d+\.\d+)\s+rows=(\d+)\s+width=(\d+)\)`;
+var actual = String.raw`(?:actual(?:\stime=(\d+\.\d+)\.\.(\d+\.\d+))?\srows=(\d+(?:\.\d+)?)\sloops=(\d+)|(never\s+executed))`;
+var nodeRe = new RegExp(
+  String.raw`^(\s*->\s*|\s*)(Finalize|Simple|Partial)*\s*([^\r\n\t\f\v(]*?)\s*` + String.raw`(?:(?:${estimation}\s+\(${actual}\))|(?:${estimation})|(?:\(${actual}\)))\s*$`
+);
+var subRe = /^((?:Sub|Init)Plan)\s*(?:\d+\s*)?(?:\(returns.*\))?\s*$/;
+var cteRe = /^CTE\s+(\S+)\s*$/;
+var workerRe = /^Worker\s+(\d+):\s+(?:actual(?:\stime=(\d+\.\d+)\.\.(\d+\.\d+))?\srows=(\d+(?:\.\d+)?)\sloops=(\d+)|never\s+executed)(.*)$/;
+var triggerRe = /^Trigger\s+(.*):\s+time=(\d+\.\d+)\s+calls=(\d+)\s*$/;
+var headerRe = /^(QUERY PLAN|-{2,}|#|\(\d+ rows?\))/;
+function splitNodeType(text) {
+  let s = text.trim();
+  let indexName;
+  let relationName;
+  let schema;
+  let alias;
+  const using = s.match(/\susing (\S+)/);
+  if (using?.[1]) {
+    indexName = using[1];
+    s = s.replace(using[0] ?? "", "");
+  }
+  const on = s.match(/\son (\S+?)(?:\s+(\S+))?\s*$/);
+  if (on?.[1]) {
+    let rel = on[1];
+    alias = on[2];
+    const dot = rel.lastIndexOf(".");
+    if (dot !== -1) {
+      schema = rel.slice(0, dot);
+      rel = rel.slice(dot + 1);
+    }
+    relationName = rel;
+    s = s.slice(0, on.index).trim();
+  }
+  const nodeType = s.replace(/^Parallel\s+/, "").trim();
+  if (nodeType === "Bitmap Index Scan" && relationName && !indexName) {
+    indexName = relationName;
+    relationName = void 0;
+    schema = void 0;
+    alias = void 0;
+  }
+  const out = { "Node Type": nodeType };
+  if (relationName) out["Relation Name"] = relationName;
+  if (indexName) out["Index Name"] = indexName;
+  if (schema) out.Schema = schema;
+  if (alias && alias !== relationName) out.Alias = alias;
+  return out;
+}
+function parseSort(text, node) {
+  const m = text.match(/^Sort Method:\s+(.*?)\s+(Memory|Disk):\s+(\S+)kB\s*$/);
+  if (!m?.[1] || !m[2] || m[3] === void 0) return false;
+  node["Sort Method"] = m[1].trim();
+  node["Sort Space Type"] = m[2];
+  node["Sort Space Used"] = Number(m[3]);
+  return true;
+}
+function parseBuffers(text, node) {
+  const m = text.match(/^Buffers:\s+(.*)$/);
+  if (!m?.[1]) return false;
+  for (const group of m[1].split(/,\s+/)) {
+    const g = group.match(/^(shared|temp|local)\s+(.*)$/);
+    if (!g?.[1] || g[2] === void 0) continue;
+    const type = cap(g[1]);
+    for (const kv of g[2].trim().split(/\s+/)) {
+      const [method, value] = kv.split("=");
+      if (method && value !== void 0) node[`${type} ${cap(method)} Blocks`] = Number(value);
+    }
+  }
+  return true;
+}
+function parseWal(text, node) {
+  const m = text.match(/^WAL:\s+(.*)$/);
+  if (!m?.[1]) return false;
+  for (const kv of m[1].trim().split(/\s+/)) {
+    const [k, value] = kv.split("=");
+    if (!k || value === void 0) continue;
+    node[`WAL ${k === "fpi" ? "FPI" : cap(k)}`] = Number(value);
+  }
+  return true;
+}
+function parseIoTimings(text, node) {
+  const m = text.match(/^I\/O Timings:\s+(.*)$/);
+  if (!m?.[1]) return false;
+  const read = m[1].match(/(?:^|\s)read=(\d+(?:\.\d+)?)/);
+  const write2 = m[1].match(/(?:^|\s)write=(\d+(?:\.\d+)?)/);
+  if (read?.[1]) node["I/O Read Time"] = Number(read[1]);
+  if (write2?.[1]) node["I/O Write Time"] = Number(write2[1]);
+  return true;
+}
+function parseSettings(text) {
+  const out = {};
+  for (const pair of splitList(text)) {
+    const m = pair.match(/^(\S+)\s*=\s*(.*)$/);
+    if (m?.[1] && m[2] !== void 0) out[m[1]] = m[2].replace(/^'|'$/g, "");
+  }
+  return out;
+}
+var LIST_KEYS = /* @__PURE__ */ new Set(["Output", "Sort Key", "Presorted Key", "Group Key"]);
+function parseTextToStatements(input) {
+  const statements = [];
+  let stmt = null;
+  let stack = [];
+  let current = null;
+  let jit = null;
+  const finish = () => {
+    if (stmt?.Plan) statements.push(stmt);
+    stmt = null;
+    stack = [];
+    current = null;
+    jit = null;
+  };
+  for (let raw of splitIntoLines(input)) {
+    raw = raw.replace(/"\s*$/, "").replace(/^\s*"/, "").replace(/\t/g, "    ");
+    const depth = raw.match(/^\s*/)?.[0].length ?? 0;
+    const line = raw.slice(depth);
+    if (line === "" || headerRe.test(line)) {
+      if (line === "" && stmt?.Plan) finish();
+      continue;
+    }
+    const nodeM = nodeRe.exec(line);
+    const subM = subRe.exec(line);
+    const cteM = cteRe.exec(line);
+    if (nodeM && !subM && !cteM) {
+      if (!stmt) stmt = {};
+      jit = null;
+      const node = { ...splitNodeType(nodeM[3] ?? "") };
+      if (nodeM[2]) node["Partial Mode"] = nodeM[2];
+      const startup = nodeM[4] ?? nodeM[13];
+      const total = nodeM[5] ?? nodeM[14];
+      if (startup && total) {
+        node["Startup Cost"] = Number(startup);
+        node["Total Cost"] = Number(total);
+        node["Plan Rows"] = Number(nodeM[6] ?? nodeM[15]);
+        node["Plan Width"] = Number(nodeM[7] ?? nodeM[16]);
+      }
+      const st = nodeM[8] ?? nodeM[17];
+      const tt = nodeM[9] ?? nodeM[18];
+      if (st && tt) {
+        node["Actual Startup Time"] = Number(st);
+        node["Actual Total Time"] = Number(tt);
+      }
+      const rows = nodeM[10] ?? nodeM[19];
+      const loops = nodeM[11] ?? nodeM[20];
+      if (rows && loops) {
+        node["Actual Rows"] = Number(rows);
+        node["Actual Loops"] = Number(loops);
+      }
+      if (nodeM[12] ?? nodeM[21]) {
+        node["Actual Loops"] = 0;
+        node["Actual Rows"] = 0;
+      }
+      stack = stack.filter((f) => f.depth < depth);
+      const parent = stack[stack.length - 1];
+      if (!parent) {
+        stmt.Plan = node;
+      } else {
+        if (parent.rel) {
+          node["Parent Relationship"] = parent.rel;
+          if (parent.name) node["Subplan Name"] = parent.name;
+        }
+        const parentNode = parent.node;
+        if (!parentNode.Plans) parentNode.Plans = [];
+        parentNode.Plans.push(node);
+      }
+      stack.push({ depth, node });
+      current = node;
+      continue;
+    }
+    if (subM || cteM) {
+      stack = stack.filter((f) => f.depth < depth);
+      const parent = stack[stack.length - 1];
+      if (!parent) continue;
+      if (cteM?.[1])
+        stack.push({ depth, node: parent.node, rel: "InitPlan", name: `CTE ${cteM[1]}` });
+      else if (subM?.[1])
+        stack.push({
+          depth,
+          node: parent.node,
+          rel: subM[1],
+          name: (subM[0] ?? "").trim()
+        });
+      continue;
+    }
+    const workerM = workerRe.exec(line);
+    if (workerM && current) {
+      const worker = { "Worker Number": Number(workerM[1]) };
+      if (workerM[2] && workerM[3]) {
+        worker["Actual Startup Time"] = Number(workerM[2]);
+        worker["Actual Total Time"] = Number(workerM[3]);
+      }
+      if (workerM[4] && workerM[5]) {
+        worker["Actual Rows"] = Number(workerM[4]);
+        worker["Actual Loops"] = Number(workerM[5]);
+      }
+      if (!Array.isArray(current.Workers)) current.Workers = [];
+      current.Workers.push(worker);
+      continue;
+    }
+    const trigM = triggerRe.exec(line);
+    if (trigM && stmt) {
+      if (!Array.isArray(stmt.Triggers)) stmt.Triggers = [];
+      stmt.Triggers.push({
+        "Trigger Name": trigM[1],
+        Time: Number(trigM[2]),
+        Calls: Number(trigM[3])
+      });
+      continue;
+    }
+    const kv = line.match(/^([^:]+):\s*(.*)$/);
+    if (!kv?.[1]) continue;
+    const key = kv[1].trim();
+    const value = (kv[2] ?? "").trim();
+    if (key === "JIT") {
+      jit = {};
+      if (stmt) stmt.JIT = jit;
+      continue;
+    }
+    if (jit) {
+      if (key === "Functions") jit.Functions = Number(value);
+      else if (key === "Timing") {
+        const timing = {};
+        for (const part of value.split(/,\s*/)) {
+          const t = part.match(/^(\S+)\s+(\d+\.\d+)\s*ms/);
+          if (t?.[1]) timing[t[1]] = Number(t[2]);
+        }
+        jit.Timing = timing;
+      }
+      continue;
+    }
+    if (key === "Planning Time") {
+      if (stmt) stmt["Planning Time"] = parseFloat(value);
+      continue;
+    }
+    if (key === "Execution Time" || key === "Total runtime") {
+      if (stmt) stmt["Execution Time"] = parseFloat(value);
+      continue;
+    }
+    if (key === "Settings") {
+      if (stmt) stmt.Settings = parseSettings(value);
+      continue;
+    }
+    if (!current) continue;
+    if (parseSort(line, current) || parseBuffers(line, current) || parseWal(line, current) || parseIoTimings(line, current)) {
+      continue;
+    }
+    current[key] = LIST_KEYS.has(key) ? splitList(value) : numeric(value);
+  }
+  finish();
+  return statements;
+}
+var PlanNodeSchema = z.looseObject({
+  "Node Type": z.string(),
+  get Plans() {
+    return z.array(PlanNodeSchema).optional();
+  }
+});
+var StatementSchema = z.looseObject({
+  Plan: PlanNodeSchema,
+  "Planning Time": z.number().optional(),
+  "Execution Time": z.number().optional(),
+  Triggers: z.array(z.looseObject({})).optional(),
+  JIT: z.looseObject({}).optional(),
+  Settings: z.record(z.string(), z.unknown()).optional()
+});
+var ExplainOutputSchema = z.array(StatementSchema).min(1);
+
+// src/core/parse.ts
+function num(raw, key) {
+  const v = raw[key];
+  return typeof v === "number" ? v : void 0;
+}
+function str(raw, key) {
+  const v = raw[key];
+  return typeof v === "string" ? v : void 0;
+}
+function strArray(raw, key) {
+  const v = raw[key];
+  if (Array.isArray(v) && v.every((x) => typeof x === "string")) return v;
+  if (typeof v === "string") return [v];
+  return void 0;
+}
+function parseJsonWithLocation(input) {
+  try {
+    return JSON.parse(input);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    let line;
+    let col;
+    const lc = message.match(/line (\d+) column (\d+)/i);
+    if (lc?.[1] && lc[2]) {
+      line = Number(lc[1]);
+      col = Number(lc[2]);
+    } else {
+      const pos = message.match(/position (\d+)/i);
+      if (pos?.[1]) {
+        const offset = Number(pos[1]);
+        const before = input.slice(0, offset);
+        line = before.split("\n").length;
+        col = offset - before.lastIndexOf("\n");
+      }
+    }
+    const where = line && col ? ` (line ${line}, col ${col})` : "";
+    throw opError(
+      "PGX_MALFORMED_JSON",
+      {
+        detail: `The plan input could not be parsed as JSON${where}: ${message}`,
+        location: line && col ? { kind: "input", line, col } : { kind: "input" }
+      },
+      err
+    );
+  }
+}
+function normalizeNode(raw, nextId) {
+  const node = {
+    id: nextId(),
+    nodeType: raw["Node Type"],
+    planRows: num(raw, "Plan Rows") ?? 0,
+    children: [],
+    metrics: {},
+    raw
+  };
+  assign(node, {
+    parentRelationship: str(raw, "Parent Relationship"),
+    subplanName: str(raw, "Subplan Name"),
+    relationName: str(raw, "Relation Name"),
+    schema: str(raw, "Schema"),
+    alias: str(raw, "Alias"),
+    indexName: str(raw, "Index Name"),
+    planWidth: num(raw, "Plan Width"),
+    startupCost: num(raw, "Startup Cost"),
+    totalCost: num(raw, "Total Cost"),
+    actualRows: num(raw, "Actual Rows"),
+    actualLoops: num(raw, "Actual Loops"),
+    actualStartupTime: num(raw, "Actual Startup Time"),
+    actualTotalTime: num(raw, "Actual Total Time"),
+    filter: str(raw, "Filter"),
+    rowsRemovedByFilter: num(raw, "Rows Removed by Filter"),
+    indexCond: str(raw, "Index Cond"),
+    recheckCond: str(raw, "Recheck Cond"),
+    rowsRemovedByIndexRecheck: num(raw, "Rows Removed by Index Recheck"),
+    heapFetches: num(raw, "Heap Fetches"),
+    hashCond: str(raw, "Hash Cond"),
+    joinType: str(raw, "Join Type"),
+    joinFilter: str(raw, "Join Filter"),
+    rowsRemovedByJoinFilter: num(raw, "Rows Removed by Join Filter"),
+    output: strArray(raw, "Output"),
+    sortMethod: str(raw, "Sort Method"),
+    sortSpaceType: str(raw, "Sort Space Type"),
+    sortSpaceUsed: num(raw, "Sort Space Used"),
+    sortKey: strArray(raw, "Sort Key"),
+    hashBuckets: num(raw, "Hash Buckets"),
+    originalHashBuckets: num(raw, "Original Hash Buckets"),
+    hashBatches: num(raw, "Hash Batches"),
+    originalHashBatches: num(raw, "Original Hash Batches"),
+    peakMemoryUsage: num(raw, "Peak Memory Usage"),
+    diskUsage: num(raw, "Disk Usage"),
+    exactHeapBlocks: num(raw, "Exact Heap Blocks"),
+    lossyHeapBlocks: num(raw, "Lossy Heap Blocks"),
+    cacheHits: num(raw, "Cache Hits"),
+    cacheMisses: num(raw, "Cache Misses"),
+    cacheEvictions: num(raw, "Cache Evictions"),
+    cacheOverflows: num(raw, "Cache Overflows"),
+    sharedHitBlocks: num(raw, "Shared Hit Blocks"),
+    sharedReadBlocks: num(raw, "Shared Read Blocks"),
+    sharedDirtiedBlocks: num(raw, "Shared Dirtied Blocks"),
+    sharedWrittenBlocks: num(raw, "Shared Written Blocks"),
+    localHitBlocks: num(raw, "Local Hit Blocks"),
+    localReadBlocks: num(raw, "Local Read Blocks"),
+    tempReadBlocks: num(raw, "Temp Read Blocks"),
+    tempWrittenBlocks: num(raw, "Temp Written Blocks"),
+    ioReadTime: num(raw, "I/O Read Time"),
+    ioWriteTime: num(raw, "I/O Write Time"),
+    workersPlanned: num(raw, "Workers Planned"),
+    workersLaunched: num(raw, "Workers Launched"),
+    walRecords: num(raw, "WAL Records"),
+    walBytes: num(raw, "WAL Bytes"),
+    walFpi: num(raw, "WAL FPI")
+  });
+  const workers = parseWorkers(raw.Workers);
+  if (workers.length) node.workers = workers;
+  const childPlans = raw.Plans;
+  if (Array.isArray(childPlans)) {
+    for (const child of childPlans) {
+      node.children.push(normalizeNode(child, nextId));
+    }
+  }
+  return node;
+}
+function assign(target, fields) {
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== void 0) target[k] = v;
+  }
+}
+function parseWorkers(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const w of raw) {
+    const r = w;
+    const number = num(r, "Worker Number");
+    if (number === void 0) continue;
+    const stat2 = { number };
+    assign(stat2, {
+      actualRows: num(r, "Actual Rows"),
+      actualLoops: num(r, "Actual Loops"),
+      actualStartupTime: num(r, "Actual Startup Time"),
+      actualTotalTime: num(r, "Actual Total Time")
+    });
+    out.push(stat2);
+  }
+  return out;
+}
+function parseTriggers(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((t) => {
+    const r = t;
+    const info = {};
+    assign(info, {
+      name: str(r, "Trigger Name"),
+      constraintName: str(r, "Constraint Name"),
+      relation: str(r, "Relation"),
+      calls: num(r, "Calls"),
+      time: num(r, "Time")
+    });
+    return info;
+  });
+}
+function parseJit(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const r = raw;
+  const timing = r.Timing;
+  const jit = {};
+  const functions = num(r, "Functions");
+  if (functions !== void 0) jit.functions = functions;
+  if (timing && typeof timing === "object") {
+    jit.timing = {
+      total: num(timing, "Total"),
+      generation: num(timing, "Generation"),
+      inlining: num(timing, "Inlining"),
+      optimization: num(timing, "Optimization"),
+      emission: num(timing, "Emission")
+    };
+  }
+  return jit;
+}
+function statementToTree(stmt) {
+  let id = 0;
+  const root = normalizeNode(stmt.Plan, () => id++);
+  const hasAnalyze = root.actualLoops !== void 0 || stmt["Execution Time"] !== void 0;
+  const hasBuffers = root.sharedHitBlocks !== void 0 || root.sharedReadBlocks !== void 0;
+  const tree = {
+    root,
+    triggers: parseTriggers(stmt.Triggers),
+    hasAnalyze,
+    hasBuffers,
+    raw: stmt.Plan
+  };
+  if (typeof stmt["Planning Time"] === "number") tree.planningTime = stmt["Planning Time"];
+  if (typeof stmt["Execution Time"] === "number") tree.executionTime = stmt["Execution Time"];
+  const serialization = stmt.Serialization;
+  if (serialization && typeof serialization === "object") {
+    const t = num(serialization, "Time");
+    if (t !== void 0) tree.serializationTime = t;
+  }
+  const jit = parseJit(stmt.JIT);
+  if (jit) tree.jit = jit;
+  if (stmt.Settings) tree.settings = stmt.Settings;
+  return tree;
+}
+function parseExplain(input) {
+  return /^\s*[[{]/.test(input) ? parseExplainJson(input) : parseExplainText(input);
+}
+function parseExplainText(input) {
+  return parseTextToStatements(input).map(statementToTree);
+}
+function parseExplainJson(input) {
+  const json = parseJsonWithLocation(input);
+  let candidate = json;
+  if (json && typeof json === "object" && !Array.isArray(json)) {
+    const obj = json;
+    candidate = "Plan" in obj ? [obj] : "Node Type" in obj ? [{ Plan: obj }] : json;
+  }
+  const result = ExplainOutputSchema.safeParse(candidate);
+  if (!result.success) {
+    throw opError("PGX_UNEXPECTED_PLAN_SHAPE", {
+      detail: `The JSON is valid but is not an EXPLAIN plan: ${result.error.issues[0]?.message ?? "missing 'Plan' node"}.`,
+      location: { kind: "input" }
+    });
+  }
+  return result.data.map((stmt) => statementToTree(stmt));
+}
+function walk(node, visit) {
+  visit(node);
+  for (const child of node.children) walk(child, visit);
+}
+function flatten(node) {
+  const out = [];
+  walk(node, (n) => out.push(n));
+  return out;
+}
+
+// src/core/metrics.ts
+function computeMetrics(tree) {
+  walk(tree.root, (node) => {
+    const { actualRows, actualLoops, actualTotalTime } = node;
+    if (actualRows !== void 0 && actualLoops !== void 0) {
+      node.metrics.totalRows = actualRows * actualLoops;
+    }
+    if (actualTotalTime !== void 0 && actualLoops !== void 0) {
+      node.metrics.inclusiveMs = actualTotalTime * actualLoops;
+    }
+    if (node.metrics.totalRows !== void 0) {
+      const est = Math.max(node.planRows, 1);
+      const act = Math.max(node.metrics.totalRows, 1);
+      node.metrics.estimateFactor = est >= act ? est / act : act / est;
+      node.metrics.estimateDirection = node.planRows > node.metrics.totalRows ? "over" : node.metrics.totalRows > node.planRows ? "under" : "accurate";
+    }
+    const hit = node.sharedHitBlocks ?? 0;
+    const read = node.sharedReadBlocks ?? 0;
+    node.metrics.cacheHitRatio = hit + read > 0 ? hit / (hit + read) : null;
+    if (node.rowsRemovedByFilter !== void 0 && actualLoops !== void 0) {
+      const removed = node.rowsRemovedByFilter * actualLoops;
+      const kept = node.metrics.totalRows ?? 0;
+      const denom = removed + kept;
+      if (denom > 0) node.metrics.filterDiscardRatio = removed / denom;
+    }
+    if (node.lossyHeapBlocks !== void 0) {
+      const lossy = node.lossyHeapBlocks;
+      const exact = node.exactHeapBlocks ?? 0;
+      const denom = lossy + exact;
+      if (denom > 0) node.metrics.lossyRatio = lossy / denom;
+    }
+  });
+  walk(tree.root, (node) => {
+    if (node.metrics.inclusiveMs === void 0) return;
+    let childrenMs = 0;
+    for (const child of node.children) childrenMs += child.metrics.inclusiveMs ?? 0;
+    node.metrics.selfMs = Math.max(node.metrics.inclusiveMs - childrenMs, 0);
+  });
+  const totalMs = executionMs(tree);
+  if (totalMs && totalMs > 0) {
+    walk(tree.root, (node) => {
+      if (node.metrics.selfMs !== void 0) {
+        node.metrics.pctOfTotal = 100 * node.metrics.selfMs / totalMs;
+      }
+    });
+  }
+}
+function executionMs(tree) {
+  return tree.executionTime ?? tree.root.metrics.inclusiveMs;
+}
+function bottlenecks(tree, n = 5) {
+  return flatten(tree.root).filter((node) => node.metrics.selfMs !== void 0).sort((a, b) => (b.metrics.selfMs ?? 0) - (a.metrics.selfMs ?? 0)).slice(0, n);
+}
+function aggregateStats(tree) {
+  const total = executionMs(tree) ?? 0;
+  const groupBy = (keyOf) => {
+    const acc = /* @__PURE__ */ new Map();
+    for (const n of flatten(tree.root)) {
+      const key = keyOf(n);
+      if (!key) continue;
+      const e = acc.get(key) ?? { count: 0, selfMs: 0 };
+      e.count++;
+      e.selfMs += n.metrics.selfMs ?? 0;
+      acc.set(key, e);
+    }
+    return [...acc.entries()].map(([key, e]) => ({
+      key,
+      count: e.count,
+      selfMs: e.selfMs,
+      pctOfTotal: total > 0 ? 100 * e.selfMs / total : 0
+    })).sort((a, b) => b.selfMs - a.selfMs || b.count - a.count);
+  };
+  return {
+    byNodeType: groupBy((n) => n.nodeType),
+    byRelation: groupBy((n) => n.relationName),
+    byIndex: groupBy((n) => n.indexName)
+  };
+}
+function nodeLabel(node) {
+  let label = node.nodeType;
+  if (node.indexName && node.relationName)
+    label += ` using ${node.indexName} on ${node.relationName}`;
+  else if (node.relationName) label += ` on ${node.relationName}`;
+  if (node.alias && node.alias !== node.relationName) label += ` (${node.alias})`;
+  return label;
+}
+
+// src/util/format.ts
+var BLOCK_BYTES = 8192;
+function fmtInt(n) {
+  return Math.round(n).toLocaleString("en-US");
+}
+function fmtMs(ms) {
+  if (ms < 1) return `${ms.toFixed(3)} ms`;
+  if (ms < 1e3) return `${ms.toFixed(1)} ms`;
+  if (ms < 6e4) return `${(ms / 1e3).toFixed(2)} s`;
+  const min = Math.floor(ms / 6e4);
+  const sec = (ms % 6e4 / 1e3).toFixed(0);
+  return `${min}m ${sec}s`;
+}
+function fmtPct(fraction0to100) {
+  return `${fraction0to100.toFixed(1)}%`;
+}
+function fmtKiB(kib) {
+  return fmtBytes(kib * 1024);
+}
+function fmtBlocks(blocks) {
+  return `${fmtInt(blocks)} blk (${fmtBytes(blocks * BLOCK_BYTES)})`;
+}
+function fmtBytes(bytes) {
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let v = bytes;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  const s = i === 0 ? String(Math.round(v)) : v.toFixed(1);
+  return `${s} ${units[i]}`;
+}
+function roundUpMiB(kib, stepMiB = 4) {
+  const mib = Math.ceil(kib / 1024 / stepMiB) * stepMiB;
+  return `${Math.max(mib, stepMiB)}MB`;
+}
+var UNICODE_TREE = { branch: "\u251C\u2500 ", last: "\u2514\u2500 ", vert: "\u2502  ", space: "   " };
+var ASCII_TREE = { branch: "+- ", last: "`- ", vert: "|  ", space: "   " };
+
+// src/advisor/rules/util.ts
+var DOCS2 = "https://www.postgresql.org/docs/current";
+function locationOf(node) {
+  const loc = { kind: "node", nodeId: node.id, nodeType: node.nodeType };
+  if (node.relationName) loc.relation = node.relationName;
+  return loc;
+}
+function makeFinding(rule, ctx, node, parts) {
+  const d = {
+    code: rule.id,
+    domain: "plan",
+    severity: ctx.severityOf(rule.id, parts.severity ?? rule.defaultSeverity),
+    title: parts.title,
+    detail: parts.detail,
+    cause: parts.cause,
+    remediation: parts.remediation,
+    location: locationOf(node)
+  };
+  if (parts.docsUrl) d.docsUrl = parts.docsUrl;
+  if (parts.meta) d.meta = parts.meta;
+  return d;
+}
+function outerChild(node) {
+  return node.children[0];
+}
+
+// src/advisor/rules/bitmap-lossy.ts
+var bitmapLossy = {
+  id: "PGX_BITMAP_LOSSY",
+  title: "Lossy bitmap heap scan",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Bitmap Heap Scan") return [];
+    const lossy = node.lossyHeapBlocks ?? 0;
+    if (lossy <= 0) return [];
+    const exact = node.exactHeapBlocks ?? 0;
+    const rel = node.relationName ?? "the table";
+    const rechecked = node.rowsRemovedByIndexRecheck ?? 0;
+    const recheckNote = rechecked > 0 ? ` The recheck discarded ${fmtInt(rechecked)} extra rows that the lossy bitmap could not exclude.` : "";
+    return [
+      makeFinding(bitmapLossy, ctx, node, {
+        title: `Lossy bitmap heap scan on ${rel} (${fmtInt(lossy)} lossy blocks)`,
+        detail: `The bitmap for ${rel} held ${fmtInt(lossy)} lossy (page-granularity) blocks alongside ${fmtInt(
+          exact
+        )} exact blocks, so Postgres re-checked the index condition against every tuple on the lossy pages.${recheckNote}`,
+        cause: "The exact (per-tuple) bitmap did not fit in work_mem, so Postgres fell back to storing whole heap pages and recheck the index condition while reading them \u2014 more heap I/O and CPU than an exact bitmap.",
+        remediation: {
+          summary: `Raise work_mem for this session so the bitmap stays exact (no lossy blocks, no rechecks) on ${rel}; alternatively make the index condition more selective or add a composite index so the bitmap is smaller.`,
+          steps: [
+            "Increase work_mem for the session, then re-run EXPLAIN (ANALYZE) and confirm Lossy Heap Blocks drops to 0.",
+            "If raising work_mem is undesirable, make the index condition more selective (a more selective leading column or a composite index over the filtered columns) so fewer heap pages enter the bitmap."
+          ],
+          commands: [
+            {
+              label: "Give this session more work_mem",
+              sql: "SET work_mem = '<X>MB';"
+            },
+            {
+              label: "Or shrink the bitmap with a more selective index",
+              sql: `CREATE INDEX ON ${rel} (<more selective / composite columns>);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-WORK-MEM`,
+        meta: { lossyBlocks: lossy, exactBlocks: exact }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/cartesian-product.ts
+function rowsOf(node) {
+  return node.metrics.totalRows ?? node.planRows;
+}
+var cartesianProduct = {
+  id: "PGX_CARTESIAN_PRODUCT",
+  title: "Cartesian product (missing join condition)",
+  defaultSeverity: "error",
+  check(node, ctx) {
+    if (node.nodeType !== "Nested Loop") return [];
+    if (node.joinFilter) return [];
+    let inner = node.children[1];
+    if (!inner) return [];
+    while ((inner.nodeType === "Memoize" || inner.nodeType === "Materialize") && inner.children[0]) {
+      inner = inner.children[0];
+    }
+    if (inner.indexCond || inner.recheckCond) return [];
+    const outer = node.children[0];
+    if (!outer) return [];
+    const outerRows = rowsOf(outer);
+    const innerRows = rowsOf(inner);
+    if (outerRows <= 1 || innerRows <= 1) return [];
+    const estimated = node.metrics.totalRows === void 0;
+    const product = fmtInt(outerRows * innerRows);
+    return [
+      makeFinding(cartesianProduct, ctx, node, {
+        title: `Cartesian product: Nested Loop with no join condition (~${product}${estimated ? " est." : ""} rows)`,
+        detail: `The Nested Loop has no Join Filter and the inner side has no Index Cond or Recheck Cond, so each of ${fmtInt(
+          outerRows
+        )} outer rows is paired with every one of ${fmtInt(innerRows)} inner rows${estimated ? " (estimated \u2014 run with ANALYZE for actuals)" : ""}.`,
+        cause: "No predicate links the two relations, so Postgres can only emit the full cross product. This usually means an ON or WHERE join condition was omitted (e.g. a comma join across tables).",
+        remediation: {
+          summary: "Add the missing join condition linking the two tables on their key columns (e.g. ON a.id = b.a_id). If a cross product is truly intended, make it explicit with CROSS JOIN and bound it with a LIMIT or aggregation.",
+          steps: [
+            "Find the two relations feeding this Nested Loop in your query.",
+            "Add an ON (or WHERE) clause matching their key columns so the loop becomes selective.",
+            "If you really want every combination, write CROSS JOIN explicitly and cap the size with LIMIT or an aggregate."
+          ],
+          commands: [
+            {
+              label: "Add the join predicate",
+              sql: "SELECT ...\nFROM <outer_table> a\nJOIN <inner_table> b ON a.<key> = b.<key>;"
+            },
+            {
+              label: "Or make the cross join explicit and bounded",
+              sql: "SELECT ...\nFROM <outer_table> a\nCROSS JOIN <inner_table> b\nLIMIT <n>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/queries-table-expressions.html#QUERIES-JOIN`,
+        meta: { outerRows: Math.round(outerRows), innerRows: Math.round(innerRows) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/correlated-subplan.ts
+var correlatedSubplan = {
+  id: "PGX_CORRELATED_SUBPLAN",
+  title: "Correlated subplan re-executed per row",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const isSubplan = node.parentRelationship === "SubPlan" || (node.subplanName?.startsWith("SubPlan") ?? false);
+    if (!isSubplan) return [];
+    const loops = node.actualLoops ?? 0;
+    if (loops <= ctx.thresholds.correlatedLoops) return [];
+    const name = node.subplanName ?? "the subplan";
+    return [
+      makeFinding(correlatedSubplan, ctx, node, {
+        title: `Correlated ${name} re-executed ${fmtInt(loops)} times`,
+        detail: `${name} ran ${fmtInt(loops)} times \u2014 once per outer row \u2014 instead of being evaluated a single time.`,
+        cause: "The subquery references a column from the enclosing query, so the planner cannot pull it out of the per-row loop and re-runs the whole subplan for every outer row.",
+        remediation: {
+          summary: `De-correlate the subquery: rewrite it as a JOIN or LATERAL join, or hoist it into a CTE/derived table evaluated once, then index the correlation key so the rewrite stays cheap.`,
+          steps: [
+            "Identify the outer column the subquery references (the correlation key).",
+            "For a scalar subquery in SELECT/WHERE, rewrite it as a LEFT JOIN to a grouped derived table, or a LATERAL join when it returns per-row results.",
+            "For EXISTS/IN, prefer the semi-join form (EXISTS / = ANY) the planner can de-correlate into a single hash/merge join.",
+            "Add an index on the correlation key so the resulting JOIN does not fall back to the same per-row cost.",
+            // Before (correlated, runs once per outer row):
+            //   SELECT o.id, (SELECT count(*) FROM events e WHERE e.order_id = o.id) AS n FROM orders o;
+            // After (evaluated once, joined):
+            //   SELECT o.id, COALESCE(e.n, 0) AS n
+            //   FROM orders o
+            //   LEFT JOIN (SELECT order_id, count(*) AS n FROM events GROUP BY order_id) e
+            //     ON e.order_id = o.id;
+            "See the before/after sketch: SELECT (SELECT count(*) FROM events e WHERE e.order_id = o.id) becomes a LEFT JOIN to (SELECT order_id, count(*) FROM events GROUP BY order_id)."
+          ],
+          commands: [
+            {
+              label: "Index the correlation key so the de-correlated JOIN stays cheap",
+              sql: "CREATE INDEX ON <subquery table> (<correlation key column>);"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/queries-table-expressions.html#QUERIES-LATERAL`,
+        meta: { loops }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/could-be-index-only.ts
+var couldBeIndexOnly = {
+  id: "PGX_COULD_BE_INDEX_ONLY",
+  title: "Index scan may be eligible for index-only",
+  defaultSeverity: "info",
+  check(node, ctx) {
+    if (node.nodeType !== "Index Scan") return [];
+    if (!node.indexName) return [];
+    if (node.filter) return [];
+    if (!node.output || node.output.length === 0) return [];
+    if (node.output.length > 4) return [];
+    const rel = node.relationName ?? "the table";
+    const cols = node.output;
+    const colList = cols.join(", ");
+    const includeCols = cols.join(", ");
+    return [
+      makeFinding(couldBeIndexOnly, ctx, node, {
+        title: `Index Scan using ${node.indexName} on ${rel} may be eligible for index-only`,
+        detail: `This Index Scan projects only ${cols.length} column${cols.length === 1 ? "" : "s"} (${colList}) and applies no residual filter, so its predicate is fully resolved by ${node.indexName}. If that index also covers the selected columns, Postgres could use an Index Only Scan and skip the heap entirely.`,
+        cause: "An Index Scan still visits the table heap to fetch the projected columns. When every selected column is contained in the index (as a key or INCLUDE column) and the visibility map is current, Postgres can answer from the index alone (Index Only Scan).",
+        remediation: {
+          summary: `Add the selected columns (${includeCols}) to ${node.indexName} as INCLUDE columns so it covers the query, then keep the visibility map current with VACUUM so Postgres can switch ${rel} to an Index Only Scan.`,
+          steps: [
+            "Confirm which columns the index already covers (\\d <index> in psql) \u2014 this hint assumes VERBOSE Output and cannot read the index definition.",
+            "If any projected column is missing, recreate the index with those columns as INCLUDE (non-key) columns.",
+            "Run VACUUM so the visibility map is set; Index Only Scans fall back to heap fetches on pages not marked all-visible."
+          ],
+          commands: [
+            {
+              label: "Create a covering index",
+              sql: `CREATE INDEX ON ${rel} (<key columns from the Index Cond>) INCLUDE (${includeCols});`
+            },
+            {
+              label: "Keep the visibility map current",
+              sql: `VACUUM ${rel};`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-index-only-scans.html`,
+        meta: { outputColumns: cols.length }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/filter-could-be-index-cond.ts
+var filterCouldBeIndexCond = {
+  id: "PGX_FILTER_COULD_BE_INDEX_COND",
+  title: "Filter could be an index condition",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const indexed = node.nodeType === "Index Scan" || node.nodeType === "Index Only Scan" || node.nodeType === "Bitmap Heap Scan";
+    if (!indexed) return [];
+    if (!node.filter) return [];
+    if (!node.indexCond && !node.recheckCond) return [];
+    if ((node.rowsRemovedByFilter ?? 0) <= 0) return [];
+    const rel = node.relationName ?? "the table";
+    const cond = node.indexCond ?? node.recheckCond ?? "";
+    const loops = node.actualLoops ?? 1;
+    const removed = (node.rowsRemovedByFilter ?? 0) * loops;
+    return [
+      makeFinding(filterCouldBeIndexCond, ctx, node, {
+        title: `Residual filter on ${rel} could be an index condition`,
+        detail: `${node.nodeType} on ${rel} used the index for ${cond} but then applied Filter ${node.filter} to the fetched rows, discarding ${fmtInt(removed)} of them.`,
+        cause: `The Filter columns are not part of the index, so Postgres must fetch each row the index matched and re-check the predicate in the executor instead of skipping non-matching entries during the index traversal.`,
+        remediation: {
+          summary: `Extend the index on ${rel} to include the Filter columns from ${node.filter} as trailing key columns, so the predicate is applied as an Index Cond during traversal instead of as a post-fetch Filter.`,
+          steps: [
+            `Confirm the Filter ${node.filter} is sargable \u2014 no functions or implicit casts wrapping the column.`,
+            "Append the filter columns after the existing key columns so the index still serves the original lookup.",
+            "Re-run EXPLAIN (ANALYZE) and check the Filter moved into the Index Cond with no Rows Removed by Filter."
+          ],
+          commands: [
+            {
+              label: "Extend the index with the filter columns",
+              sql: `CREATE INDEX ON ${rel} (<existing key columns>, <filter columns>);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-multicolumn.html`,
+        meta: { rowsRemovedByFilter: Math.round(removed) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/hash-spill-disk.ts
+var hashSpillDisk = {
+  id: "PGX_HASH_SPILL_DISK",
+  title: "Hash join spilled to disk",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Hash") return [];
+    const hashBatches = node.hashBatches ?? 1;
+    if (hashBatches <= 1) return [];
+    const originalHashBatches = node.originalHashBatches ?? hashBatches;
+    const repartitioned = hashBatches > originalHashBatches;
+    const peakKiB = node.peakMemoryUsage ?? 0;
+    const diskKiB = node.diskUsage ?? 0;
+    const workMemRecommended = roundUpMiB((peakKiB + diskKiB) * 1.2);
+    return [
+      makeFinding(hashSpillDisk, ctx, node, {
+        title: `Hash build side spilled to disk (${fmtInt(hashBatches)} batches)`,
+        detail: `The hash table was split into ${fmtInt(hashBatches)} batches${repartitioned ? ` (up from ${fmtInt(originalHashBatches)} planned)` : ""}, so the build side did not fit in work_mem and overflowed to temporary files${diskKiB > 0 ? ` (${fmtKiB(diskKiB)} written to disk)` : ""}.`,
+        cause: repartitioned ? "Postgres had to add batches at runtime because the build side was larger than estimated \u2014 usually a row underestimate sized work_mem too small." : "The build (hash) side was larger than work_mem, forcing the hash join to partition it across disk-backed batches.",
+        remediation: {
+          summary: `Raise work_mem to about ${workMemRecommended} so the build side fits in a single batch, and make sure the SMALLER input is the hash/build side (a wrong build side usually comes from a row underestimate \u2014 fix the stats). Reducing build-side rows also avoids the spill.`,
+          steps: [
+            `Set work_mem high enough to hold the build side in one batch (~${workMemRecommended} here) at session or role scope, not globally \u2014 every sort/hash node can use work_mem, so a global bump can exhaust memory.`,
+            "Confirm the smaller relation is on the build (Hash) side; if Postgres chose the larger side, a row underestimate is likely \u2014 re-run ANALYZE or raise statistics targets so the planner picks the smaller build side.",
+            "Alternatively, filter or aggregate the build side earlier so fewer rows need to be hashed."
+          ],
+          commands: [
+            {
+              label: "Raise work_mem for this session",
+              sql: `SET work_mem = '${workMemRecommended}';`
+            },
+            {
+              label: "Or set it for a specific role",
+              sql: `ALTER ROLE <role> SET work_mem = '${workMemRecommended}';`
+            },
+            {
+              label: "Refresh planner statistics on the build-side table",
+              sql: "ANALYZE <build_side_table>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-WORK-MEM`,
+        meta: { hashBatches, workMemRecommended }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/high-filter-discard.ts
+var highFilterDiscard = {
+  id: "PGX_HIGH_FILTER_DISCARD",
+  title: "Filter discards most rows read",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const ratio = node.metrics.filterDiscardRatio;
+    if (ratio === void 0 || ratio <= ctx.thresholds.filterDiscardRatio) return [];
+    const removed = (node.rowsRemovedByFilter ?? 0) * (node.actualLoops ?? 1);
+    if (removed <= ctx.thresholds.filterRemovedAbs) return [];
+    const rel = node.relationName ?? "the table";
+    const kept = node.metrics.totalRows ?? 0;
+    const discardPct = ratio * 100;
+    const filter = node.filter ?? "the filter predicate";
+    return [
+      makeFinding(highFilterDiscard, ctx, node, {
+        title: `Filter on ${rel} discards ${fmtPct(discardPct)} of rows read`,
+        detail: `Postgres read this node's rows then dropped ${fmtInt(removed)} of them (${fmtPct(
+          discardPct
+        )}), keeping only ${fmtInt(kept)}, via the post-read filter ${filter}.`,
+        cause: `The predicate ${filter} is evaluated as a Filter after the rows are fetched, so every discarded row was still read and examined \u2014 work no index condition narrowed.`,
+        remediation: {
+          summary: `Move ${filter} into an index on ${rel} so the predicate becomes an Index Cond instead of a post-read Filter, letting Postgres skip the non-matching rows. For a low-cardinality predicate, a partial index keyed on the discarded condition is smaller and faster.`,
+          steps: [
+            "Identify the column(s) referenced by the filter above.",
+            "Ensure the predicate is sargable (no function-wrapping or implicit casts on the indexed column).",
+            "Use a plain index when the columns are selective across queries; use a partial index when the same constant predicate is always applied."
+          ],
+          commands: [
+            {
+              label: "Index the filter columns",
+              sql: `CREATE INDEX ON ${rel} (<filter columns>);`
+            },
+            {
+              label: "Or a partial index for a fixed low-cardinality predicate",
+              sql: `CREATE INDEX ON ${rel} (<filter columns>) WHERE <predicate>;`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-partial.html`,
+        meta: { discardPct: Math.round(discardPct) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/index-only-heap-fetches.ts
+var indexOnlyHeapFetches = {
+  id: "PGX_INDEX_ONLY_HEAP_FETCHES",
+  title: "Index-only scan with heap fetches",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Index Only Scan") return [];
+    const heapFetches = node.heapFetches ?? 0;
+    if (heapFetches <= 0) return [];
+    const rows = Math.max(node.metrics.totalRows ?? 1, 1);
+    const ratio = heapFetches / rows;
+    if (ratio <= ctx.thresholds.heapFetchRatio && heapFetches <= ctx.thresholds.heapFetchAbs) {
+      return [];
+    }
+    const rel = node.relationName ?? "the table";
+    return [
+      makeFinding(indexOnlyHeapFetches, ctx, node, {
+        title: `Index-only scan on ${rel} did ${fmtInt(heapFetches)} heap fetches`,
+        detail: `The index-only scan on ${rel} fell back to the heap ${fmtInt(heapFetches)} times for ${fmtInt(
+          rows
+        )} rows produced. Each fetch is an extra table page read the index-only path was meant to avoid.`,
+        cause: `Heap fetches happen when the visibility map does not mark the pages as all-visible, so Postgres must read the table row to confirm visibility. This usually means ${rel} has not been vacuumed recently enough for its write/update rate.`,
+        remediation: {
+          summary: `Run VACUUM (or VACUUM ANALYZE) on ${rel} to refresh the visibility map so the index-only scan can skip the heap. For a high-churn table, lower autovacuum_vacuum_scale_factor so autovacuum keeps the map current.`,
+          steps: [
+            `VACUUM ${rel} to update the visibility map; add ANALYZE if statistics are also stale.`,
+            "If heap fetches keep returning, the table is updated faster than autovacuum runs \u2014 make autovacuum more aggressive on it.",
+            "Confirm the scan stays index-only afterwards by re-running EXPLAIN (ANALYZE) and checking Heap Fetches drops toward 0."
+          ],
+          commands: [
+            {
+              label: "Refresh the visibility map",
+              sql: `VACUUM (ANALYZE) ${rel};`
+            },
+            {
+              label: "Keep the map current on a high-churn table",
+              sql: `ALTER TABLE ${rel} SET (autovacuum_vacuum_scale_factor = 0.02);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-index-only-scans.html`,
+        meta: { heapFetches }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/limit-large-offset.ts
+var limitLargeOffset = {
+  id: "PGX_LIMIT_LARGE_OFFSET",
+  title: "LIMIT discards a large prefix (OFFSET pagination)",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Limit") return [];
+    const child = outerChild(node);
+    const emitted = node.metrics.totalRows;
+    const produced = child?.metrics.totalRows;
+    if (emitted === void 0 || produced === void 0) return [];
+    const discarded = produced - emitted;
+    if (discarded < ctx.thresholds.limitDiscardRows) return [];
+    const rel = child?.relationName ?? "the input";
+    return [
+      makeFinding(limitLargeOffset, ctx, node, {
+        title: `LIMIT discarded ${fmtInt(discarded)} rows before returning ${fmtInt(emitted)}`,
+        detail: `The plan produced ${fmtInt(produced)} rows from ${rel} but the Limit node returned only ${fmtInt(emitted)} \u2014 ${fmtInt(discarded)} rows were generated just to be skipped.`,
+        cause: "OFFSET-style pagination makes Postgres compute and discard every row before the requested page, so deep pages get progressively slower (page N costs O(N)).",
+        remediation: {
+          summary: "Switch to keyset (seek) pagination: filter on the last-seen sort key instead of skipping rows, and keep an index on the sort key so each page is a direct index seek.",
+          steps: [
+            "Order by a unique (or tie-broken) key, e.g. ORDER BY created_at, id.",
+            "Pass the last row's key from the previous page instead of an OFFSET.",
+            "Index the sort key so the WHERE clause seeks directly to the page start."
+          ],
+          commands: [
+            {
+              label: "Keyset pagination instead of OFFSET",
+              sql: "SELECT \u2026 FROM t WHERE (created_at, id) > ($last_created_at, $last_id) ORDER BY created_at, id LIMIT 50;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/queries-limit.html`,
+        meta: { discarded: Math.round(discarded), emitted: Math.round(emitted) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/low-cache-hit.ts
+var MIN_READ_BLOCKS = 1e3;
+var lowCacheHit = {
+  id: "PGX_LOW_CACHE_HIT",
+  title: "Low cache hit ratio (heavy disk reads)",
+  defaultSeverity: "info",
+  requiresBuffers: true,
+  check(node, ctx) {
+    const ratio = node.metrics.cacheHitRatio;
+    const readBlocks = node.sharedReadBlocks ?? 0;
+    if (ratio == null) return [];
+    if (ratio >= ctx.thresholds.lowCacheHitRatio) return [];
+    if (readBlocks <= MIN_READ_BLOCKS) return [];
+    const label = nodeLabel(node);
+    const rel = node.relationName;
+    const ratioPct = ratio * 100;
+    return [
+      makeFinding(lowCacheHit, ctx, node, {
+        title: `Low cache hit ratio at ${label} (${fmtPct(ratioPct)})`,
+        detail: `${label} served only ${fmtPct(ratioPct)} of its shared-buffer accesses from cache, reading ${fmtBlocks(readBlocks)} from disk.`,
+        cause: "The pages this node needed were not resident in shared_buffers, so PostgreSQL had to read them from disk. On a first run this is an expected cold cache; if it persists, the working set is larger than the cache or the scan touches more pages than necessary.",
+        remediation: {
+          summary: `Re-run the query to check whether this is just a cold cache \u2014 the ratio should climb on a warm run. If it stays low, the working set exceeds shared_buffers: size shared_buffers/effective_cache_size to your RAM, or add a selective index on ${rel ?? "the scanned relation"} so far fewer pages are read.`,
+          steps: [
+            "Run the same EXPLAIN (ANALYZE, BUFFERS) a second time; a much higher hit ratio means the first run was a cold cache and no action is needed.",
+            "If the ratio stays low, check whether shared_buffers (and effective_cache_size for planner costing) are sized to the machine's RAM.",
+            "If the node reads far more pages than the rows it returns, add a selective index so only matching pages are fetched."
+          ],
+          commands: [
+            {
+              label: "Inspect current buffer-cache sizing",
+              sql: "SHOW shared_buffers; SHOW effective_cache_size;"
+            },
+            {
+              label: "Reduce pages read with a selective index",
+              sql: `CREATE INDEX ON ${rel ?? "<table>"} (<predicate columns>);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-SHARED-BUFFERS`,
+        meta: { cacheHitPct: Math.round(ratioPct * 10) / 10, readBlocks }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/memoize-evictions.ts
+var memoizeEvictions = {
+  id: "PGX_MEMOIZE_EVICTIONS",
+  title: "Memoize cache is thrashing",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Memoize") return [];
+    const hits = node.cacheHits ?? 0;
+    const evictions = node.cacheEvictions ?? 0;
+    const overflows = node.cacheOverflows ?? 0;
+    const thrashing = evictions > hits;
+    if (!thrashing && overflows === 0) return [];
+    return [
+      makeFinding(memoizeEvictions, ctx, node, {
+        title: overflows > 0 ? `Memoize cache overflowed ${fmtInt(overflows)} time(s)` : `Memoize evicted ${fmtInt(evictions)} entries against ${fmtInt(hits)} hits`,
+        detail: `The Memoize cache recorded ${fmtInt(hits)} hits, ${fmtInt(node.cacheMisses ?? 0)} misses, ${fmtInt(evictions)} evictions, and ${fmtInt(overflows)} overflows \u2014 entries are being thrown away before they can be reused.`,
+        cause: "The distinct key values do not fit in the memory Memoize is allowed (derived from work_mem \xD7 hash_mem_multiplier), so the cache churns and the node degenerates into a slower re-executing inner side.",
+        remediation: {
+          summary: "Give the session more cache memory (work_mem / hash_mem_multiplier) so the key space fits, or reduce the number of distinct keys flowing into the Memoize.",
+          steps: [
+            "Estimate the distinct keys: the planner sizes the cache from ndistinct of the join key.",
+            "Raise work_mem (or hash_mem_multiplier on PG 15+) for this workload and re-run.",
+            "If the key space is genuinely huge, an index on the inner side may beat Memoize \u2014 compare with enable_memoize = off."
+          ],
+          commands: [
+            { label: "More cache memory for this session", sql: "SET work_mem = '64MB';" },
+            {
+              label: "Compare the plan without Memoize",
+              sql: "SET enable_memoize = off; EXPLAIN ANALYZE <query>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html`,
+        meta: { hits, evictions, overflows }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/nested-loop-large-outer.ts
+var nestedLoopLargeOuter = {
+  id: "PGX_NESTED_LOOP_LARGE_OUTER",
+  title: "Nested loop with a large outer side",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Nested Loop") return [];
+    const outer = outerChild(node);
+    const outerRows = outer?.metrics.totalRows;
+    if (outerRows === void 0 || outerRows <= ctx.thresholds.nestedLoopOuterRows) return [];
+    const outerLabel = outer ? nodeLabel(outer) : "the outer side";
+    const inner = node.children[1];
+    const innerLabel = inner ? nodeLabel(inner) : "the inner side";
+    const innerCond = inner?.indexCond ?? inner?.joinFilter ?? inner?.filter ?? node.joinFilter;
+    const misestimated = outer?.metrics.estimateDirection === "under";
+    return [
+      makeFinding(nestedLoopLargeOuter, ctx, node, {
+        title: `Nested loop driven by ${fmtInt(outerRows)} outer rows (${outerLabel})`,
+        detail: `The nested loop's outer side (${outerLabel}) produced ${fmtInt(
+          outerRows
+        )} rows, so its inner side (${innerLabel}) is re-executed roughly that many times.`,
+        cause: misestimated ? `The planner expected far fewer outer rows than the ${fmtInt(
+          outerRows
+        )} that actually came back, so it chose a per-row nested loop where a single hash/merge join would have been cheaper.` : `A nested loop probes the inner side once per outer row; with ${fmtInt(
+          outerRows
+        )} outer rows that is ${fmtInt(outerRows)} inner executions.`,
+        remediation: {
+          summary: `Fix the outer-side row estimate first \u2014 re-ANALYZE ${outer?.relationName ?? "the driving table"}, raise its column statistics, or add extended statistics \u2014 so the planner switches to a hash or merge join. If the estimate is already accurate, add an index on the inner join key (${innerCond ?? "<inner join column>"}) so each of the ${fmtInt(outerRows)} probes is cheap.`,
+          steps: [
+            "Compare the outer node's estimated vs actual rows: a large gap means the estimate is the real problem.",
+            "Refresh statistics so the planner sees the true cardinality and can prefer a hash/merge join.",
+            "If columns are correlated, create extended (multivariate) statistics on them.",
+            "If estimates are already correct, index the inner join key so each probe is an index lookup, not a scan.",
+            "As a last resort to confirm the diagnosis, test with `SET enable_nestloop = off` for this query only."
+          ],
+          commands: [
+            {
+              label: "Refresh planner statistics on the driving table",
+              sql: `ANALYZE ${outer?.relationName ?? "<outer table>"};`
+            },
+            {
+              label: "Increase statistics target on the misestimated column, then re-ANALYZE",
+              sql: `ALTER TABLE ${outer?.relationName ?? "<outer table>"} ALTER COLUMN <column> SET STATISTICS 1000;
+ANALYZE ${outer?.relationName ?? "<outer table>"};`
+            },
+            {
+              label: "Add extended statistics for correlated columns",
+              sql: `CREATE STATISTICS ${outer?.relationName ?? "<outer table>"}_stats (dependencies, ndistinct) ON <col_a>, <col_b> FROM ${outer?.relationName ?? "<outer table>"};
+ANALYZE ${outer?.relationName ?? "<outer table>"};`
+            },
+            {
+              label: "If estimates are correct, index the inner join key",
+              sql: `CREATE INDEX ON ${inner?.relationName ?? "<inner table>"} (<inner join column>);`
+            },
+            {
+              label: "Confirm the diagnosis by disabling nested loops for this query only",
+              sql: "SET enable_nestloop = off;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-query.html`,
+        meta: { outerRows: Math.round(outerRows) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/row-misestimate.ts
+var rowMisestimate = {
+  id: "PGX_ROW_MISESTIMATE",
+  title: "Row count misestimate",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const { estimateFactor, estimateDirection, totalRows } = node.metrics;
+    if (estimateFactor === void 0) return [];
+    if (estimateFactor < ctx.thresholds.misestimateFactor) return [];
+    if (estimateDirection === void 0 || estimateDirection === "accurate") return [];
+    const rows = Math.max(totalRows ?? 0, node.planRows);
+    if (rows < 100) return [];
+    const factor = Math.round(estimateFactor);
+    const rel = node.relationName;
+    const onRel = rel ? ` on ${rel}` : "";
+    const target = rel ?? "the underlying table";
+    const under = estimateDirection === "under";
+    const direction = under ? "underestimate" : "overestimate";
+    const actual2 = totalRows ?? 0;
+    const detail = `Postgres estimated ${fmtInt(node.planRows)} rows but ${fmtInt(actual2)} were produced \u2014 a ${fmtInt(factor)}x ${direction}${onRel}.`;
+    return [
+      makeFinding(rowMisestimate, ctx, node, {
+        // Severity: underestimates are the dangerous ones (under-sized joins/memory).
+        severity: under ? "warn" : "info",
+        title: `${fmtInt(factor)}x row ${direction}${onRel}`,
+        detail,
+        cause: "The planner's row estimate is based on statistics that are stale, missing, or too coarse for this predicate (e.g. correlated columns the planner treats as independent).",
+        remediation: {
+          summary: `Refresh and sharpen statistics for ${target}: run ANALYZE ${rel ?? "<relation>"}, raise per-column statistics targets on the predicate columns, and add extended statistics for correlated columns so the planner estimates rows correctly.${under ? " Underestimates feeding a nested loop or hash join are the highest priority \u2014 fix these first." : ""}`,
+          steps: [
+            `Refresh table statistics first; this alone often fixes the estimate.`,
+            `If the column has a skewed/uneven distribution, raise its statistics target and re-ANALYZE.`,
+            `If the predicate spans multiple correlated columns, create extended statistics so the planner stops assuming independence.`
+          ],
+          commands: [
+            {
+              label: "Refresh statistics",
+              sql: `ANALYZE ${rel ?? "<relation>"};`
+            },
+            {
+              label: "Raise per-column statistics target",
+              sql: `ALTER TABLE ${rel ?? "<relation>"} ALTER COLUMN <column> SET STATISTICS 1000;
+ANALYZE ${rel ?? "<relation>"};`
+            },
+            {
+              label: "Add extended statistics for correlated columns",
+              sql: `CREATE STATISTICS <stats_name> (dependencies, ndistinct) ON <col_a>, <col_b> FROM ${rel ?? "<relation>"};
+ANALYZE ${rel ?? "<relation>"};`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/planner-stats.html`,
+        meta: {
+          estimatedRows: Math.round(node.planRows),
+          actualRows: Math.round(actual2),
+          factor,
+          direction: estimateDirection
+        }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/seq-scan-large.ts
+var seqScanLarge = {
+  id: "PGX_SEQ_SCAN_LARGE",
+  title: "Sequential scan on a large table",
+  defaultSeverity: "warn",
+  check(node, ctx) {
+    if (node.nodeType !== "Seq Scan") return [];
+    const rows = node.metrics.totalRows ?? node.planRows;
+    if (rows < ctx.thresholds.seqScanRows) return [];
+    const rel = node.relationName ?? "the table";
+    const estimated = node.metrics.totalRows === void 0;
+    const filterCols = node.filter ? ` matching ${node.filter}` : "";
+    return [
+      makeFinding(seqScanLarge, ctx, node, {
+        title: `Sequential scan on ${rel} (${fmtInt(rows)}${estimated ? " est." : ""} rows)`,
+        detail: `Postgres read ${rel} sequentially, scanning roughly ${fmtInt(rows)} rows${estimated ? " (estimated \u2014 run with ANALYZE for actuals)" : ""}.`,
+        cause: node.filter ? `A row filter (${node.filter}) is applied after reading every row, so no index narrowed the scan.` : "No index condition narrowed the scan, so the whole relation was read.",
+        remediation: {
+          summary: `Add an index covering the WHERE/JOIN predicate on ${rel} so Postgres can skip non-matching rows. If the query genuinely needs most of the table, the seq scan is correct \u2014 reduce the rows touched instead.`,
+          steps: [
+            "Identify the selective columns in the WHERE/JOIN predicate.",
+            "Ensure they are sargable (no function-wrapping or implicit casts on the column).",
+            "If selectivity is low, a partial index (WHERE \u2026) may be better."
+          ],
+          commands: [
+            {
+              label: "Index the predicate columns",
+              sql: `CREATE INDEX ON ${rel} (<predicate columns>)${filterCols ? " -- columns from the filter above" : ""};`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-intro.html`,
+        meta: { rows: Math.round(rows) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/significant-jit.ts
+var significantJit = {
+  id: "PGX_SIGNIFICANT_JIT",
+  title: "JIT compilation dominates execution",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node !== ctx.tree.root) return [];
+    const t = ctx.tree.jit?.timing;
+    const jitTotal = t?.total ?? (t?.generation ?? 0) + (t?.inlining ?? 0) + (t?.optimization ?? 0) + (t?.emission ?? 0);
+    const execMs = executionMs(ctx.tree);
+    if (!execMs || jitTotal <= 0) return [];
+    const jitPct = 100 * jitTotal / execMs;
+    if (jitPct <= ctx.thresholds.jitPct) return [];
+    return [
+      makeFinding(significantJit, ctx, node, {
+        title: `JIT compilation took ${fmtMs(jitTotal)} (${fmtPct(jitPct)} of execution)`,
+        detail: `JIT spent ${fmtMs(jitTotal)} generating, optimizing, and emitting machine code, out of ${fmtMs(
+          execMs
+        )} total execution time. The compilation overhead outweighs the runtime it saved.`,
+        cause: "The plan's estimated cost crossed jit_above_cost, so Postgres JIT-compiled the query \u2014 but the query is too short for compilation to pay off, often because a row overestimate inflated the cost.",
+        remediation: {
+          summary: "Raise jit_above_cost (and jit_inline_above_cost / jit_optimize_above_cost) so short queries skip JIT, or disable JIT for this session with SET jit = off. Then investigate why the cost estimate is high enough to trigger JIT \u2014 frequently a row overestimate fixable with ANALYZE.",
+          steps: [
+            "Confirm the query is consistently short-running before tuning \u2014 JIT pays off on long, CPU-bound queries.",
+            "Raise jit_above_cost above this plan's total cost so similar queries skip JIT entirely.",
+            "If only inlining/optimization are expensive, raise jit_inline_above_cost / jit_optimize_above_cost instead of disabling JIT.",
+            "Check the planner's row estimates against actuals \u2014 an overestimate that inflates cost is the usual reason a cheap query triggers JIT; run ANALYZE on the relations involved."
+          ],
+          commands: [
+            { label: "Disable JIT for this session", sql: "SET jit = off;" },
+            {
+              label: "Raise the JIT cost thresholds",
+              sql: "SET jit_above_cost = <above this plan's total cost>;\nSET jit_inline_above_cost = <higher>;\nSET jit_optimize_above_cost = <higher>;"
+            },
+            {
+              label: "Refresh statistics if the cost is driven by a row overestimate",
+              sql: "ANALYZE <table>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-query.html#GUC-JIT-ABOVE-COST`,
+        meta: { jitMs: Math.round(jitTotal), jitPct: Math.round(jitPct) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/sort-spill-disk.ts
+var sortSpillDisk = {
+  id: "PGX_SORT_SPILL_DISK",
+  title: "Sort spilled to disk",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Sort") return [];
+    const onDisk = node.sortSpaceType === "Disk" || node.sortMethod !== void 0 && /external/i.test(node.sortMethod);
+    if (!onDisk) return [];
+    const usedKiB = node.sortSpaceUsed ?? 0;
+    const workMemRecommended = roundUpMiB(usedKiB > 0 ? usedKiB * 2.2 : 0);
+    const usedText = usedKiB > 0 ? ` using ${fmtKiB(usedKiB)} of temp space` : "";
+    const method = node.sortMethod ? ` (${node.sortMethod})` : "";
+    const orderBy = node.sortKey && node.sortKey.length > 0 ? node.sortKey.join(", ") : "<ORDER BY columns>";
+    const summary = usedKiB > 0 ? `Raise work_mem for this query so the sort stays in memory, e.g. SET work_mem = '${workMemRecommended}' at session or role scope (do NOT raise it globally without accounting for max_connections \u2014 each connection can allocate work_mem several times over). Alternatively, add an index on (${orderBy}) so rows arrive pre-sorted and the Sort node disappears.` : `Raise work_mem for this query so the sort stays in memory, e.g. SET work_mem = '64MB' at session or role scope (do NOT raise it globally without accounting for max_connections \u2014 each connection can allocate work_mem several times over). Alternatively, add an index on (${orderBy}) so rows arrive pre-sorted and the Sort node disappears.`;
+    return [
+      makeFinding(sortSpillDisk, ctx, node, {
+        title: `Sort spilled to disk${usedText}`,
+        detail: `The Sort node ran an external merge sort on disk${method}${usedText}, because the data exceeded work_mem.`,
+        cause: "work_mem was too small to hold the sort set, so Postgres wrote sorted runs to temporary files and merged them \u2014 adding temp-file I/O that an in-memory sort avoids.",
+        remediation: {
+          summary,
+          steps: [
+            "Set work_mem at session or role scope for this workload, not cluster-wide.",
+            `Size it above the spilled footprint${usedKiB > 0 ? ` (~${fmtKiB(usedKiB)}); ${workMemRecommended} leaves headroom` : ""}.`,
+            `Or add an index on (${orderBy}) so the sort is satisfied by an ordered scan and removed entirely.`
+          ],
+          commands: [
+            {
+              label: "Raise work_mem for this session",
+              sql: `SET work_mem = '${usedKiB > 0 ? workMemRecommended : "64MB"}';`
+            },
+            {
+              label: "Or set it per role",
+              sql: `ALTER ROLE <role> SET work_mem = '${usedKiB > 0 ? workMemRecommended : "64MB"}';`
+            },
+            {
+              label: "Or add an index matching the sort key",
+              sql: `CREATE INDEX ON <table> (${orderBy});`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-WORK-MEM`,
+        meta: { sortSpaceUsedKiB: Math.round(usedKiB), workMemRecommended }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/trigger-time.ts
+var triggerTime = {
+  id: "PGX_TRIGGER_TIME",
+  title: "Triggers consume significant time",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node !== ctx.tree.root) return [];
+    const triggers = ctx.tree.triggers;
+    const execMs = executionMs(ctx.tree);
+    const triggerTotal = triggers.reduce((s, t) => s + (t.time ?? 0), 0);
+    if (!triggers.length || !execMs || triggerTotal <= 0) return [];
+    const pct = 100 * triggerTotal / execMs;
+    if (pct <= ctx.thresholds.triggerPct) return [];
+    const worst = triggers.reduce((a, b) => (b.time ?? 0) > (a.time ?? 0) ? b : a);
+    const worstLabel = worst.name ?? worst.constraintName ?? "a trigger";
+    const onRel = worst.relation ? ` on ${worst.relation}` : "";
+    return [
+      makeFinding(triggerTime, ctx, node, {
+        title: `Triggers consumed ${fmtMs(triggerTotal)} (${fmtPct(pct)} of execution)`,
+        detail: `Trigger execution took ${fmtMs(triggerTotal)} of the ${fmtMs(
+          execMs
+        )} total \u2014 ${fmtPct(pct)} of the time is spent outside the plan tree (heaviest: "${worstLabel}"${onRel}).`,
+        cause: "Time spent firing triggers (often foreign-key constraint checks or AFTER triggers) is not attributed to any plan node, so it is invisible in the node timings even though it dominates the statement.",
+        remediation: {
+          summary: `Index the foreign-key columns involved in the constraint checks so each row's lookup is cheap, and review the trigger function bodies for per-row inefficiency. For bulk loads, defer constraints (SET CONSTRAINTS ALL DEFERRED) or disable and replay triggers around the batch.`,
+          steps: [
+            "Confirm both the referencing and referenced FK columns are indexed \u2014 an FK check does a lookup on the referenced key for every row, and a missing index makes it a full scan per row.",
+            "Inspect each trigger function body for per-row work that could be batched or removed.",
+            "For bulk INSERT/UPDATE/COPY, defer FK constraints until commit, or temporarily disable user triggers and replay the work once after the batch."
+          ],
+          commands: [
+            {
+              label: "Index the referencing FK column(s) so constraint checks are cheap",
+              sql: `CREATE INDEX ON <referencing_table> (<fk_columns>);`
+            },
+            {
+              label: "Defer FK constraint checks to commit for a bulk load",
+              sql: `BEGIN;
+SET CONSTRAINTS ALL DEFERRED;
+-- bulk INSERT/UPDATE/COPY here
+COMMIT;`
+            },
+            {
+              label: "Disable user triggers around a batch, then re-enable",
+              sql: `ALTER TABLE <table> DISABLE TRIGGER USER;
+-- bulk work here
+ALTER TABLE <table> ENABLE TRIGGER USER;`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/sql-createtrigger.html`,
+        meta: { triggerMs: Math.round(triggerTotal), triggerPct: Math.round(pct) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/workers-not-launched.ts
+var workersNotLaunched = {
+  id: "PGX_WORKERS_NOT_LAUNCHED",
+  title: "Parallel workers planned but not launched",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Gather" && node.nodeType !== "Gather Merge") return [];
+    if (node.workersPlanned === void 0 || node.workersLaunched === void 0) return [];
+    if (node.workersLaunched >= node.workersPlanned) return [];
+    const planned = node.workersPlanned;
+    const launched = node.workersLaunched;
+    const shortfall = planned - launched;
+    return [
+      makeFinding(workersNotLaunched, ctx, node, {
+        title: `${node.nodeType} got ${fmtInt(launched)} of ${fmtInt(planned)} planned workers`,
+        detail: `This ${node.nodeType} planned for ${fmtInt(planned)} parallel worker${planned === 1 ? "" : "s"} but only ${fmtInt(launched)} were launched (${fmtInt(shortfall)} short), so part of the work ran serially.`,
+        cause: "The global background-worker pool was exhausted: max_worker_processes or max_parallel_workers was already saturated (often by other concurrent parallel queries) when this node tried to start its workers.",
+        remediation: {
+          summary: `Raise max_parallel_workers and max_worker_processes so the pool can supply the ${fmtInt(
+            planned
+          )} workers this query plans for, and confirm max_parallel_workers_per_gather permits them. If parallelism is not actually speeding this query up, the shortfall is harmless.`,
+          steps: [
+            "Check current limits: max_worker_processes, max_parallel_workers, max_parallel_workers_per_gather.",
+            "max_parallel_workers must be <= max_worker_processes; raise both together (max_worker_processes change needs a restart).",
+            "Look for other concurrent parallel queries saturating the shared pool during peak load.",
+            "If a serial plan is no slower here, leave the settings alone \u2014 this is informational."
+          ],
+          commands: [
+            {
+              label: "Enlarge the global parallel-worker pool",
+              sql: "ALTER SYSTEM SET max_parallel_workers = '<N>';\nALTER SYSTEM SET max_worker_processes = '<N+>';\nSELECT pg_reload_conf();"
+            },
+            {
+              label: "Allow more workers per Gather",
+              sql: "ALTER SYSTEM SET max_parallel_workers_per_gather = '<N>';\nSELECT pg_reload_conf();"
+            },
+            {
+              label: "Inspect the current settings",
+              sql: "SELECT name, setting FROM pg_settings WHERE name IN ('max_worker_processes', 'max_parallel_workers', 'max_parallel_workers_per_gather');"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS`,
+        meta: { planned, launched }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/index.ts
+var ALL_RULES = [
+  cartesianProduct,
+  seqScanLarge,
+  nestedLoopLargeOuter,
+  highFilterDiscard,
+  limitLargeOffset,
+  sortSpillDisk,
+  hashSpillDisk,
+  memoizeEvictions,
+  correlatedSubplan,
+  rowMisestimate,
+  filterCouldBeIndexCond,
+  couldBeIndexOnly,
+  indexOnlyHeapFetches,
+  bitmapLossy,
+  workersNotLaunched,
+  lowCacheHit,
+  significantJit,
+  triggerTime
+];
+
+// src/advisor/index.ts
+function runAdvisor(tree, config = DEFAULT_CONFIG) {
+  const ctx = {
+    tree,
+    thresholds: config.thresholds,
+    severityOf: (id, fallback) => config.rules[id]?.severity ?? fallback,
+    isEnabled: (id) => config.rules[id]?.enabled !== false
+  };
+  const nodes = flatten(tree.root);
+  const diagnostics = [];
+  for (const rule of ALL_RULES) {
+    if (!ctx.isEnabled(rule.id)) continue;
+    if (rule.requiresAnalyze && !tree.hasAnalyze) continue;
+    if (rule.requiresBuffers && !tree.hasBuffers) continue;
+    for (const node of nodes) {
+      for (const finding2 of rule.check(node, ctx)) diagnostics.push(finding2);
+    }
+  }
+  diagnostics.sort(bySeverity);
+  let worst = null;
+  for (const d of diagnostics) worst = worst === null ? d.severity : maxSeverity(worst, d.severity);
+  const bn = bottlenecks(tree, 5);
+  return {
+    tree,
+    diagnostics,
+    bottlenecks: bn,
+    verdict: buildVerdict(tree, diagnostics, bn),
+    worstSeverity: worst
+  };
+}
+function buildVerdict(tree, diagnostics, bn) {
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const d of diagnostics) counts[d.severity]++;
+  const parts = [];
+  if (counts.error) parts.push(`${counts.error} critical`);
+  if (counts.warn) parts.push(`${counts.warn} warning${counts.warn > 1 ? "s" : ""}`);
+  if (counts.info) parts.push(`${counts.info} note${counts.info > 1 ? "s" : ""}`);
+  const findings = parts.length ? parts.join(", ") : "no issues found";
+  const top = bn[0];
+  let bottleneck = "";
+  if (top?.metrics.selfMs !== void 0) {
+    const pct = top.metrics.pctOfTotal !== void 0 ? ` (${top.metrics.pctOfTotal.toFixed(0)}% of time)` : "";
+    bottleneck = ` \u2014 top cost: ${nodeLabel(top)}${pct}`;
+  }
+  const ms = executionMs(tree);
+  const timing = ms !== void 0 ? ` Total ${fmtMs(ms)}.` : " Cost-only plan (no timing).";
+  return `${findings}${bottleneck}.${timing}`;
+}
+
+// src/input/redact.ts
+function redactExpression(expr) {
+  return expr.replace(/'(?:[^']|'')*'/g, "'?'").replace(/\b\d+(?:\.\d+)?\b/g, "N");
+}
+var EXPR_FIELDS = [
+  "filter",
+  "indexCond",
+  "recheckCond",
+  "hashCond",
+  "joinFilter"
+];
+function redactNode(node) {
+  for (const field of EXPR_FIELDS) {
+    const value = node[field];
+    if (typeof value === "string") node[field] = redactExpression(value);
+  }
+  if (node.output) node.output = node.output.map(redactExpression);
+  if (node.sortKey) node.sortKey = node.sortKey.map(redactExpression);
+}
+function redactPlanTree(tree) {
+  walk(tree.root, redactNode);
+}
+
+// src/locks/advisor.ts
+var DOCS3 = "https://www.postgresql.org/docs/current";
+function analyzeLocks(sql, tree) {
+  const code = stripSql(sql);
+  const upper = code.toUpperCase();
+  const kw = (code.trim().split(/\s+/)[0] ?? "").toUpperCase();
+  const out = [];
+  const add = (id, severity, parts) => {
+    out.push({
+      code: id,
+      domain: "plan",
+      severity,
+      title: parts.title,
+      detail: parts.detail,
+      cause: parts.cause,
+      remediation: { summary: parts.fix, commands: parts.commands },
+      docsUrl: `${DOCS3}/explicit-locking.html`
+    });
+  };
+  if (/\bVACUUM\s+FULL\b/.test(upper) || /\bCLUSTER\b/.test(upper) || /\bALTER\s+TABLE\b[\s\S]*\b(TYPE|SET\s+DATA\s+TYPE)\b/.test(upper)) {
+    add("PGX_LOCK_TABLE_REWRITE", "error", {
+      title: "Operation rewrites the table under an ACCESS EXCLUSIVE lock",
+      detail: "VACUUM FULL / CLUSTER / a column-type change rewrites the whole table and holds ACCESS EXCLUSIVE for the duration.",
+      cause: "ACCESS EXCLUSIVE blocks every reader and writer until the rewrite finishes \u2014 an outage on a busy table.",
+      fix: "Avoid the full rewrite: use pg_repack for bloat instead of VACUUM FULL/CLUSTER; for type changes, add a new column, backfill in batches, and swap. Always do rewrites off-peak with a lock_timeout.",
+      commands: [{ label: "Bound the wait", sql: "SET lock_timeout = '3s';" }]
+    });
+  }
+  if (/\bCREATE\s+(UNIQUE\s+)?INDEX\b/.test(upper) && !/\bCONCURRENTLY\b/.test(upper)) {
+    add("PGX_DDL_NO_CONCURRENTLY", "warn", {
+      title: "CREATE INDEX without CONCURRENTLY blocks writes",
+      detail: "A plain CREATE INDEX takes a SHARE lock, blocking all writes to the table until the build completes.",
+      cause: "On a large or busy table the build can take minutes, during which inserts/updates/deletes are blocked.",
+      fix: "Build the index online with CONCURRENTLY (note: it cannot run inside a transaction and may leave an INVALID index on failure, which you then drop and recreate).",
+      commands: [{ label: "Build online", sql: "CREATE INDEX CONCURRENTLY ON <table> (<cols>);" }]
+    });
+  }
+  if (/\bDROP\s+INDEX\b/.test(upper) && !/\bCONCURRENTLY\b/.test(upper)) {
+    add("PGX_DROP_INDEX_NO_CONCURRENTLY", "warn", {
+      title: "DROP INDEX without CONCURRENTLY takes ACCESS EXCLUSIVE",
+      detail: "A plain DROP INDEX locks the table with ACCESS EXCLUSIVE.",
+      cause: "Readers and writers block until the drop completes.",
+      fix: "Use DROP INDEX CONCURRENTLY to avoid blocking.",
+      commands: [{ label: "Drop online", sql: "DROP INDEX CONCURRENTLY <index>;" }]
+    });
+  }
+  if (/\bTRUNCATE\b/.test(upper)) {
+    add("PGX_LOCK_TRUNCATE", "info", {
+      title: "TRUNCATE takes an ACCESS EXCLUSIVE lock",
+      detail: "TRUNCATE briefly locks the table with ACCESS EXCLUSIVE.",
+      cause: "It is fast (no row scan) but still blocks all access while it runs and is transactional.",
+      fix: "Fine for maintenance windows; on a hot table, set a lock_timeout so it fails fast instead of queueing behind/ahead of other transactions.",
+      commands: [{ label: "Bound the wait", sql: "SET lock_timeout = '3s';" }]
+    });
+  }
+  if (/\bLOCK\s+TABLE\b/.test(upper)) {
+    add("PGX_LOCK_TABLE_EXPLICIT", "info", {
+      title: "Explicit LOCK TABLE",
+      detail: "An explicit LOCK TABLE acquires the named lock mode for the rest of the transaction.",
+      cause: "Holding a strong lock longer than necessary blocks other sessions.",
+      fix: "Use the lowest lock mode that suffices and keep the transaction short."
+    });
+  }
+  if (/\bFOR\s+(UPDATE|SHARE|NO\s+KEY\s+UPDATE|KEY\s+SHARE)\b/.test(upper) && !/\bLIMIT\b/.test(upper)) {
+    add("PGX_SELECT_FOR_UPDATE_UNBOUNDED", "warn", {
+      title: "Row-locking SELECT without a LIMIT",
+      detail: "SELECT \u2026 FOR UPDATE/SHARE locks every row it matches, held until the transaction ends.",
+      cause: "Locking an unbounded set increases contention and deadlock risk with concurrent updaters.",
+      fix: "Bound the set with a deterministic ORDER BY + LIMIT (and process in batches); a consistent lock order also avoids deadlocks.",
+      commands: [{ label: "Bound + order", sql: "SELECT \u2026 ORDER BY id FOR UPDATE LIMIT 100;" }]
+    });
+  }
+  if (kw === "UPDATE" || kw === "DELETE") {
+    if (!/\bWHERE\b/.test(upper)) {
+      add("PGX_WRITE_NO_WHERE", "warn", {
+        title: `${kw} without a WHERE clause locks every row`,
+        detail: `This ${kw} touches the whole table, taking a row lock on every row until commit.`,
+        cause: "All rows are locked for the transaction's duration, blocking concurrent writers and bloating the table.",
+        fix: "Add a WHERE clause; for large rewrites, update in batches (e.g. by primary-key ranges) and commit between batches."
+      });
+    } else if (tree && hasSeqScanOnTarget(tree, targetTable(code, kw))) {
+      const rel = targetTable(code, kw);
+      add("PGX_UPDATE_UNINDEXED_PREDICATE", "warn", {
+        title: `${kw} scans ${rel ?? "the table"} sequentially to find rows`,
+        detail: `The plan uses a Seq Scan on ${rel ?? "the target table"}, so the ${kw} reads (and locks the touched rows of) the whole table.`,
+        cause: "An unindexed predicate means more rows scanned and locked, and the locks are held until commit.",
+        fix: `Index the ${kw}'s WHERE columns so it finds rows via an index and locks only what it changes.`,
+        commands: [
+          {
+            label: "Index the predicate",
+            sql: `CREATE INDEX ON ${rel ?? "<table>"} (<where columns>);`
+          }
+        ]
+      });
+    }
+  }
+  if (/^(ALTER|CREATE|DROP)\b/.test(kw) && !/\bCONCURRENTLY\b/.test(upper) && !/\bSET\s+LOCK_TIMEOUT\b/.test(upper)) {
+    add("PGX_DDL_NO_LOCK_TIMEOUT", "warn", {
+      title: "DDL without a lock_timeout can stall the whole table",
+      detail: "This DDL needs a strong lock; if it waits behind a long transaction, every query that arrives after it also queues behind the DDL.",
+      cause: "A blocked ACCESS EXCLUSIVE request sits at the head of the lock queue and blocks new readers/writers too.",
+      fix: "Set a short lock_timeout before the DDL and retry, so it fails fast instead of forming a queue.",
+      commands: [
+        {
+          label: "Fail fast, then retry",
+          sql: "SET lock_timeout = '3s';\n-- run the DDL; on timeout, retry later"
+        }
+      ]
+    });
+  }
+  return out;
+}
+function stripSql(sql) {
+  return sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n]*/g, " ").replace(/'(?:[^']|'')*'/g, "''").replace(/"(?:[^"]|"")*"/g, '"x"');
+}
+function targetTable(code, kw) {
+  const re = kw === "DELETE" ? /\bDELETE\s+FROM\s+([A-Za-z_][\w.]*)/i : /\bUPDATE\s+(?:ONLY\s+)?([A-Za-z_][\w.]*)/i;
+  const m = re.exec(code);
+  return m?.[1];
+}
+function hasSeqScanOnTarget(tree, table) {
+  let found = false;
+  walk(tree.root, (n) => {
+    if (n.nodeType === "Seq Scan" && (!table || n.relationName === bareName(table))) found = true;
+  });
+  return found;
+}
+function bareName(qualified) {
+  const parts = qualified.split(".");
+  return parts[parts.length - 1] ?? qualified;
+}
+
+// src/report/tree.ts
+function treeLines(tree, glyphs) {
+  const lines = [];
+  const recurse = (node, indent, isLast, isRoot) => {
+    const connector = isRoot ? "" : isLast ? glyphs.last : glyphs.branch;
+    lines.push({ node, prefix: indent + connector });
+    const childIndent = isRoot ? "" : indent + (isLast ? glyphs.space : glyphs.vert);
+    node.children.forEach((child, i) => {
+      recurse(child, childIndent, i === node.children.length - 1, false);
+    });
+  };
+  recurse(tree.root, "", true, true);
+  return lines;
+}
+function nodeSummary(node) {
+  const m = node.metrics;
+  const parts = [];
+  if (m.totalRows !== void 0) {
+    let rows = `rows=${fmtInt(m.totalRows)}`;
+    if (m.estimateFactor !== void 0 && m.estimateFactor >= 2 && m.estimateDirection !== "accurate") {
+      rows += ` (est ${fmtInt(node.planRows)}, ${m.estimateFactor.toFixed(0)}\xD7 ${m.estimateDirection})`;
+    }
+    parts.push(rows);
+  } else {
+    parts.push(`rows\u2248${fmtInt(node.planRows)} est`);
+  }
+  if (m.selfMs !== void 0) {
+    let t = `self ${fmtMs(m.selfMs)}`;
+    if (m.pctOfTotal !== void 0 && m.pctOfTotal >= 1) t += ` (${m.pctOfTotal.toFixed(0)}%)`;
+    parts.push(t);
+  }
+  if (node.metrics.cacheHitRatio != null) {
+    parts.push(`cache ${(node.metrics.cacheHitRatio * 100).toFixed(0)}%`);
+  }
+  return parts.join(" \xB7 ");
+}
+
+// src/report/json.ts
+var JSON_SCHEMA_VERSION = 1;
+function renderJson(result, pretty = true) {
+  return JSON.stringify(buildReport(result), null, pretty ? 2 : 0);
+}
+function buildReport(result) {
+  const { tree, diagnostics, bottlenecks: bottlenecks2 } = result;
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const d of diagnostics) counts[d.severity]++;
+  return {
+    schemaVersion: JSON_SCHEMA_VERSION,
+    verdict: result.verdict,
+    worstSeverity: result.worstSeverity,
+    summary: {
+      planningTimeMs: tree.planningTime ?? null,
+      executionTimeMs: executionMs(tree) ?? null,
+      serializationTimeMs: tree.serializationTime ?? null,
+      hasAnalyze: tree.hasAnalyze,
+      hasBuffers: tree.hasBuffers,
+      nodeCount: flatten(tree.root).length,
+      findings: counts
+    },
+    triggers: tree.triggers,
+    jit: tree.jit ?? null,
+    settings: tree.settings ?? null,
+    diagnostics,
+    bottlenecks: bottlenecks2.filter((n) => (n.metrics.selfMs ?? 0) > 0).map((n) => ({
+      id: n.id,
+      label: nodeLabel(n),
+      nodeType: n.nodeType,
+      relation: n.relationName ?? null,
+      selfMs: n.metrics.selfMs ?? null,
+      pctOfTotal: n.metrics.pctOfTotal ?? null,
+      totalRows: n.metrics.totalRows ?? null
+    })),
+    stats: aggregateStats(tree),
+    plan: serializeNode(tree.root)
+  };
+}
+function serializeNode(node) {
+  const { children, metrics, raw, ...fields } = node;
+  return { ...fields, metrics, children: children.map(serializeNode) };
+}
+
+// src/report/html.ts
+var SEV = {
+  error: { label: "Critical", cls: "sev-error" },
+  warn: { label: "Warning", cls: "sev-warn" },
+  info: { label: "Note", cls: "sev-info" }
+};
+function esc(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderHtml(result) {
+  const { tree, diagnostics } = result;
+  const ms = executionMs(tree);
+  const treeHtml = treeLines(tree, UNICODE_TREE).map(({ node, prefix }) => {
+    const pct = node.metrics.pctOfTotal ?? 0;
+    const heat2 = pct >= 50 ? "hot" : pct >= 20 ? "warm" : pct >= 5 ? "" : "cold";
+    return `<div class="node ${heat2}"><span class="glyph">${esc(prefix)}</span><span class="label">${esc(nodeLabel(node))}</span> <span class="meta">${esc(nodeSummary(node))}</span></div>`;
+  }).join("\n");
+  const findingsHtml = diagnostics.length ? diagnostics.map(findingHtml).join("\n") : '<p class="ok">No anti-patterns detected. \u{1F389}</p>';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>pg-explain report</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 -apple-system, system-ui, sans-serif; margin: 0; padding: 2rem; max-width: 980px; margin-inline: auto; }
+  h1 { font-size: 1.4rem; } h2 { font-size: 1.1rem; margin-top: 2rem; border-bottom: 1px solid #8884; padding-bottom: .3rem; }
+  .verdict { padding: .75rem 1rem; border-left: 4px solid #888; background: #8881; border-radius: 4px; }
+  .verdict.sev-error { border-color: #e5484d; } .verdict.sev-warn { border-color: #f5a623; } .verdict.sev-info { border-color: #4493f8; }
+  table { border-collapse: collapse; width: 100%; } td, th { text-align: left; padding: .3rem .6rem; border-bottom: 1px solid #8883; }
+  .tree { overflow-x: auto; } .node { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre; font-size: 13px; }
+  .glyph { color: #8888; } .meta { color: #888; }
+  .node.hot .label { color: #e5484d; font-weight: 700; } .node.warm .label { color: #f5a623; } .node.cold .label { opacity: .6; }
+  .finding { border: 1px solid #8883; border-radius: 6px; padding: 1rem; margin: 1rem 0; }
+  .finding .tag { font-size: .75rem; font-weight: 700; padding: .1rem .5rem; border-radius: 3px; color: #fff; }
+  .sev-error .tag { background: #e5484d; } .sev-warn .tag { background: #f5a623; } .sev-info .tag { background: #4493f8; }
+  .finding code, pre { font-family: ui-monospace, monospace; font-size: 13px; }
+  pre { background: #8881; padding: .6rem .8rem; border-radius: 4px; overflow-x: auto; }
+  .label-cmd { color: #888; font-size: .85rem; margin-top: .5rem; }
+  .ok { color: #2e7d32; }
+</style>
+</head>
+<body>
+<h1>pg-explain report</h1>
+<div class="verdict ${result.worstSeverity ? SEV[result.worstSeverity].cls : ""}">${esc(result.verdict)}</div>
+
+<h2>Summary</h2>
+<table>
+  ${tree.planningTime !== void 0 ? `<tr><th>Planning time</th><td>${esc(fmtMs(tree.planningTime))}</td></tr>` : ""}
+  ${ms !== void 0 ? `<tr><th>Execution time</th><td>${esc(fmtMs(ms))}</td></tr>` : ""}
+  ${!tree.hasAnalyze ? "<tr><th>Mode</th><td>cost-only (no ANALYZE)</td></tr>" : ""}
+  <tr><th>Findings</th><td>${diagnostics.length}</td></tr>
+</table>
+
+<h2>Plan tree</h2>
+<div class="tree">
+${treeHtml}
+</div>
+
+<h2>Findings</h2>
+${findingsHtml}
+</body>
+</html>
+`;
+}
+function findingHtml(d) {
+  const sev = SEV[d.severity];
+  const steps = d.remediation.steps?.length ? `<ul>${d.remediation.steps.map((s) => `<li>${esc(s)}</li>`).join("")}</ul>` : "";
+  const cmds = (d.remediation.commands ?? []).map((c) => {
+    const body = c.sql ?? c.shell ?? "";
+    const label = c.label ? `<div class="label-cmd">${esc(c.label)}</div>` : "";
+    return `${label}<pre><code>${esc(body)}</code></pre>`;
+  }).join("");
+  const docs = d.docsUrl ? `<p>\u{1F4D6} <a href="${esc(d.docsUrl)}">PostgreSQL docs</a></p>` : "";
+  const meta = d.location?.relation ? ` <span class="meta">on ${esc(d.location.relation)}</span>` : "";
+  return `<div class="finding ${sev.cls}">
+  <p><span class="tag">${sev.label}</span> <strong>${esc(d.title)}</strong> <code>${esc(d.code)}</code>${meta}</p>
+  <p><strong>What:</strong> ${esc(d.detail)}</p>
+  <p><strong>Why:</strong> ${esc(d.cause)}</p>
+  <p><strong>Fix:</strong> ${esc(d.remediation.summary)}</p>
+  ${steps}
+  ${cmds}
+  ${docs}
+</div>`;
+}
+
+// src/report/markdown.ts
+var SEV_LABEL = {
+  error: "\u{1F534} Critical",
+  warn: "\u{1F7E0} Warning",
+  info: "\u{1F535} Note"
+};
+function renderMarkdown(result, opts = {}) {
+  const { tree, diagnostics, bottlenecks: bottlenecks2 } = result;
+  const out = [];
+  out.push("# pg-explain report", "");
+  out.push(`> **Verdict:** ${result.verdict}`, "");
+  out.push("## Summary", "");
+  const ms = executionMs(tree);
+  out.push("| Metric | Value |", "| --- | --- |");
+  if (tree.planningTime !== void 0) out.push(`| Planning time | ${fmtMs(tree.planningTime)} |`);
+  if (ms !== void 0) out.push(`| Execution time | ${fmtMs(ms)} |`);
+  if (!tree.hasAnalyze) out.push("| Mode | cost-only (no ANALYZE) |");
+  out.push(`| Findings | ${summarizeCounts(diagnostics)} |`, "");
+  if (opts.tldr) {
+    out.push(...renderFindings(diagnostics, true));
+    return `${out.join("\n").trimEnd()}
+`;
+  }
+  out.push("## Plan tree", "", "```");
+  for (const { node, prefix } of treeLines(tree, UNICODE_TREE)) {
+    out.push(`${prefix}${nodeLabel(node)}  \u2014  ${nodeSummary(node)}`);
+  }
+  out.push("```", "");
+  const ranked = bottlenecks2.filter((n) => (n.metrics.selfMs ?? 0) > 0);
+  if (ranked.length) {
+    out.push("## Bottlenecks (by self time)", "");
+    out.push("| # | Node | Self time | % of total | Rows |", "| --- | --- | --- | --- | --- |");
+    ranked.forEach((node, i) => {
+      const pct = node.metrics.pctOfTotal !== void 0 ? `${node.metrics.pctOfTotal.toFixed(1)}%` : "\u2014";
+      const rows = node.metrics.totalRows !== void 0 ? fmtInt(node.metrics.totalRows) : "\u2014";
+      out.push(
+        `| ${i + 1} | ${nodeLabel(node)} | ${fmtMs(node.metrics.selfMs ?? 0)} | ${pct} | ${rows} |`
+      );
+    });
+    out.push("");
+  }
+  out.push(...renderFindings(diagnostics, false));
+  return `${out.join("\n").trimEnd()}
+`;
+}
+function renderFindings(diagnostics, tldr) {
+  const out = ["## Findings", ""];
+  if (diagnostics.length === 0) {
+    out.push("No anti-patterns detected. \u{1F389}", "");
+    return out;
+  }
+  for (const d of diagnostics) {
+    out.push(`### ${SEV_LABEL[d.severity]} \u2014 ${d.title}`, "");
+    out.push(`\`${d.code}\``, "");
+    out.push(`**What:** ${d.detail}`, "");
+    out.push(`**Why:** ${d.cause}`, "");
+    out.push(`**Fix:** ${d.remediation.summary}`, "");
+    if (!tldr) {
+      if (d.remediation.steps?.length) {
+        for (const step of d.remediation.steps) out.push(`- ${step}`);
+        out.push("");
+      }
+      for (const cmd of d.remediation.commands ?? []) {
+        const body = cmd.sql ?? cmd.shell ?? "";
+        const lang = cmd.sql ? "sql" : "sh";
+        if (cmd.label) out.push(`_${cmd.label}:_`);
+        out.push("```" + lang, body, "```", "");
+      }
+      if (d.docsUrl) out.push(`\u{1F4D6} [PostgreSQL docs](${d.docsUrl})`, "");
+    }
+  }
+  return out;
+}
+function summarizeCounts(diagnostics) {
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const d of diagnostics) counts[d.severity]++;
+  if (diagnostics.length === 0) return "none";
+  return `${counts.error} critical, ${counts.warn} warning(s), ${counts.info} note(s)`;
+}
+var { createColors, isColorSupported } = pc;
+var active = createColors(isColorSupported);
+function colors() {
+  return active;
+}
+
+// src/report/terminal.ts
+var SEV_TAG = { error: "CRITICAL", warn: "WARNING", info: "NOTE" };
+function sevColor(sev, text) {
+  const c = colors();
+  if (sev === "error") return c.red(c.bold(text));
+  if (sev === "warn") return c.yellow(text);
+  return c.cyan(text);
+}
+function heat(node, text) {
+  const c = colors();
+  const pct = node.metrics.pctOfTotal;
+  if (pct === void 0) return text;
+  if (pct >= 50) return c.red(c.bold(text));
+  if (pct >= 20) return c.yellow(text);
+  if (pct >= 5) return text;
+  return c.dim(text);
+}
+function bar(pct, width = 8) {
+  const filled = Math.round(pct / 100 * width);
+  return "\u2587".repeat(Math.min(filled, width)) + "\u2581".repeat(Math.max(width - filled, 0));
+}
+function renderTerminal(result, opts = {}) {
+  const c = colors();
+  const { tree, diagnostics, bottlenecks: bottlenecks2 } = result;
+  const glyphs = opts.ascii ? ASCII_TREE : UNICODE_TREE;
+  const out = [];
+  out.push(c.bold("pg-explain report"));
+  out.push(`${c.bold("Verdict:")} ${verdictColored(result)}`);
+  out.push("");
+  if (opts.tldr) {
+    out.push(...findingsBlock(diagnostics, opts));
+    return `${out.join("\n").trimEnd()}
+`;
+  }
+  out.push(c.bold("Plan tree"));
+  for (const { node, prefix } of treeLines(tree, glyphs)) {
+    const heatBar = opts.bars !== false && node.metrics.pctOfTotal !== void 0 ? ` ${c.dim(bar(node.metrics.pctOfTotal))}` : "";
+    out.push(
+      `${c.dim(prefix)}${heat(node, nodeLabel(node))}${heatBar}  ${c.dim(nodeSummary(node))}`
+    );
+  }
+  out.push("");
+  const ranked = bottlenecks2.filter((n) => (n.metrics.selfMs ?? 0) > 0);
+  if (ranked.length) {
+    out.push(c.bold("Bottlenecks (by self time)"));
+    ranked.forEach((node, i) => {
+      const pct = node.metrics.pctOfTotal !== void 0 ? `${node.metrics.pctOfTotal.toFixed(0)}%` : "\u2014";
+      out.push(
+        `  ${i + 1}. ${heat(node, nodeLabel(node))} \u2014 ${fmtMs(node.metrics.selfMs ?? 0)} (${pct})`
+      );
+    });
+    out.push("");
+  }
+  out.push(...findingsBlock(diagnostics, opts));
+  const ms = executionMs(tree);
+  if (ms !== void 0) out.push(c.dim(`Total execution time: ${fmtMs(ms)}`));
+  return `${out.join("\n").trimEnd()}
+`;
+}
+function verdictColored(result) {
+  if (result.worstSeverity === null) return colors().green(result.verdict);
+  return sevColor(result.worstSeverity, result.verdict);
+}
+function findingsBlock(diagnostics, opts) {
+  const c = colors();
+  const out = [c.bold("Findings")];
+  if (diagnostics.length === 0) {
+    out.push(`  ${c.green("No anti-patterns detected.")}`, "");
+    return out;
+  }
+  for (const d of diagnostics) {
+    out.push("");
+    out.push(
+      `${sevColor(d.severity, `[${SEV_TAG[d.severity]}]`)} ${c.bold(d.title)} ${c.dim(d.code)}`
+    );
+    out.push(`  ${c.dim("What:")} ${d.detail}`);
+    out.push(`  ${c.dim("Why: ")} ${d.cause}`);
+    out.push(`  ${c.dim("Fix: ")} ${d.remediation.summary}`);
+    if (!opts.tldr) {
+      for (const step of d.remediation.steps ?? []) out.push(`        - ${step}`);
+      for (const cmd of d.remediation.commands ?? []) {
+        const body = cmd.sql ?? cmd.shell ?? "";
+        const label = cmd.label ? `${c.dim(`${cmd.label}:`)} ` : "";
+        out.push(`        ${label}${c.green(body)}`);
+      }
+      if (d.docsUrl) out.push(`        ${c.dim(`docs: ${d.docsUrl}`)}`);
+    }
+  }
+  out.push("");
+  return out;
+}
+
+// src/report/render.ts
+var FORMATS = ["terminal", "markdown", "json", "html", "text"];
+function render(result, opts) {
+  switch (opts.format) {
+    case "markdown":
+      return renderMarkdown(result, { tldr: opts.tldr });
+    case "json":
+      return renderJson(result, opts.pretty ?? true);
+    case "html":
+      return renderHtml(result);
+    case "text":
+      return renderTerminal(result, { ascii: true, bars: false, tldr: opts.tldr });
+    default:
+      return renderTerminal(result, { ascii: opts.ascii, tldr: opts.tldr });
+  }
+}
+
+// src/index.ts
+function analyze(input, options = {}) {
+  const trees = parseExplain(input);
+  const tree = selectStatement(trees, options.statement);
+  if (options.redact) redactPlanTree(tree);
+  computeMetrics(tree);
+  const result = runAdvisor(tree, options.config ?? DEFAULT_CONFIG);
+  const extra = planNotices(tree);
+  if (options.sql) extra.push(...analyzeLocks(options.sql, tree));
+  if (extra.length) {
+    result.diagnostics = [...result.diagnostics, ...extra].sort(bySeverity);
+    result.worstSeverity = result.diagnostics.reduce(
+      (worst, d) => worst === null ? d.severity : maxSeverity(worst, d.severity),
+      null
+    );
+  }
+  return result;
+}
+function selectStatement(trees, statement) {
+  if (statement !== void 0) {
+    const tree = trees[statement - 1];
+    if (!tree) {
+      throw opError("PGX_MULTIPLE_STATEMENTS", {
+        detail: `--statement ${statement} is out of range; the input has ${trees.length} statement(s).`
+      });
+    }
+    return tree;
+  }
+  const first = trees[0];
+  if (!first) throw opError("PGX_UNEXPECTED_PLAN_SHAPE");
+  return first;
+}
+function planNotices(tree) {
+  const notices = [];
+  if (!tree.hasAnalyze) notices.push(opDiagnostic("PGX_COST_ONLY_PLAN"));
+  else if (!tree.hasBuffers) notices.push(opDiagnostic("PGX_NO_BUFFERS"));
+  const nodes = flatten(tree.root);
+  const trivial = nodes.length === 1 && /^(Result|Values? Scan)$/.test(tree.root.nodeType);
+  if (trivial) notices.push(opDiagnostic("PGX_EMPTY_PLAN"));
+  return notices;
+}
+
+// src/sql/extract.ts
+var DML = /* @__PURE__ */ new Set(["SELECT", "INSERT", "UPDATE", "DELETE", "MERGE", "VALUES", "TABLE", "WITH"]);
+function classifyStatement(sql) {
+  const kw = firstKeyword(sql);
+  if (!kw) return "empty";
+  if (kw === "DO") return "do-block";
+  if (DML.has(kw) || kw === "EXECUTE") return "explainable";
+  return "utility";
+}
+function extractAnalyzableUnits(sql) {
+  const units = [];
+  for (const stmt of splitStatements(sql)) {
+    const cls = classifyStatement(stmt);
+    if (cls === "empty") continue;
+    if (cls === "explainable") {
+      units.push({ kind: "explainable", label: unitLabel(stmt), sql: stmt });
+    } else if (cls === "do-block") {
+      units.push(...extractFromDo(stmt));
+    } else {
+      const kw = firstKeyword(stmt);
+      units.push({
+        kind: "skipped",
+        label: `${kw} \u2026`,
+        reason: `EXPLAIN cannot analyze a ${kw} statement (it is a utility/transaction-control command, not an optimizable query).`
+      });
+    }
+  }
+  return units;
+}
+function extractFromDo(doSql) {
+  const body = dollarBody(doSql);
+  if (body === null) {
+    return [
+      { kind: "skipped", label: "DO block", reason: "Could not find the block body ($$ \u2026 $$)." }
+    ];
+  }
+  const out = [];
+  for (const frag of splitStatements(body)) {
+    const stripped = stripControl(frag);
+    if (!stripped) continue;
+    const kw = firstKeyword(stripped.sql);
+    if (kw === "EXECUTE") {
+      out.push({
+        kind: "skipped",
+        label: `${stripped.context}EXECUTE (dynamic SQL)`,
+        reason: "Dynamic SQL built at runtime \u2014 the statement text isn't known statically, so it can't be analyzed."
+      });
+      continue;
+    }
+    if (DML.has(kw)) {
+      const unit = {
+        kind: "explainable",
+        label: stripped.context + unitLabel(stripped.sql),
+        sql: stripped.sql
+      };
+      if (stripped.loop) unit.loopNote = "runs once per loop iteration in the block";
+      out.push(unit);
+    }
+  }
+  if (out.length === 0) {
+    out.push({
+      kind: "skipped",
+      label: "DO block",
+      reason: "No top-level DML statements found to analyze."
+    });
+  }
+  return out;
+}
+function stripControl(frag) {
+  let rest = frag;
+  let context = "";
+  let loop = false;
+  for (let guard = 0; guard < 8; guard++) {
+    rest = rest.replace(/^\s+/, "");
+    const masked = maskNonCode(rest);
+    const kw2 = (/^[A-Za-z_]+/.exec(masked)?.[0] ?? "").toUpperCase();
+    if (kw2 === "IF" || kw2 === "ELSIF") {
+      const then = /\bTHEN\b/i.exec(masked);
+      if (!then) break;
+      context += kw2 === "IF" ? "IF-branch \u203A " : "ELSIF-branch \u203A ";
+      rest = rest.slice(then.index + 4);
+    } else if (kw2 === "ELSE") {
+      context += "ELSE-branch \u203A ";
+      rest = rest.replace(/^\s*ELSE\b/i, "");
+    } else if (kw2 === "FOR" || kw2 === "WHILE") {
+      const lp = /\bLOOP\b/i.exec(masked);
+      if (!lp) break;
+      loop = true;
+      context += "loop \u203A ";
+      rest = rest.slice(lp.index + 4);
+    } else if (kw2 === "LOOP") {
+      loop = true;
+      context += "loop \u203A ";
+      rest = rest.replace(/^\s*LOOP\b/i, "");
+    } else if (kw2 === "BEGIN" || kw2 === "THEN") {
+      rest = rest.replace(/^\s*(BEGIN|THEN)\b/i, "");
+    } else {
+      break;
+    }
+  }
+  rest = rest.replace(/^\s+/, "").replace(/;\s*$/, "").trim();
+  if (!rest) return null;
+  const kw = firstKeyword(rest);
+  if (kw === "PERFORM") return { context, sql: rest.replace(/^\s*PERFORM\b/i, "SELECT"), loop };
+  if (DML.has(kw) || kw === "EXECUTE") return { context, sql: rest, loop };
+  return null;
+}
+function firstKeyword(sql) {
+  const m = /^[A-Za-z_]+/.exec(maskNonCode(sql).trim());
+  return m ? m[0].toUpperCase() : "";
+}
+function unitLabel(stmt) {
+  const kw = firstKeyword(stmt);
+  const t = targetTable2(stmt, kw);
+  return t ? `${kw} ${t}` : kw || "statement";
+}
+function targetTable2(stmt, kw) {
+  const re = kw === "DELETE" ? /\bDELETE\s+FROM\s+([A-Za-z_][\w.]*)/i : kw === "INSERT" ? /\bINSERT\s+INTO\s+([A-Za-z_][\w.]*)/i : kw === "UPDATE" ? /\bUPDATE\s+(?:ONLY\s+)?([A-Za-z_][\w.]*)/i : void 0;
+  return re ? re.exec(stmt)?.[1] ?? void 0 : void 0;
+}
+function dollarBody(doSql) {
+  const m = /\$([A-Za-z_]*)\$/.exec(doSql);
+  if (!m) return null;
+  const tag = m[0];
+  const start = m.index + tag.length;
+  const end = doSql.indexOf(tag, start);
+  return end < 0 ? null : doSql.slice(start, end);
+}
+function maskNonCode(sql) {
+  const out = sql.split("");
+  const n = sql.length;
+  let i = 0;
+  const blank = (a, b) => {
+    for (let k = a; k < b && k < n; k++) if (out[k] !== "\n") out[k] = " ";
+  };
+  while (i < n) {
+    const two = sql.slice(i, i + 2);
+    if (two === "--") {
+      let j = sql.indexOf("\n", i);
+      if (j < 0) j = n;
+      blank(i, j);
+      i = j;
+    } else if (two === "/*") {
+      let j = sql.indexOf("*/", i + 2);
+      j = j < 0 ? n : j + 2;
+      blank(i, j);
+      i = j;
+    } else if (sql[i] === "'" || sql[i] === '"') {
+      const q = sql[i];
+      let j = i + 1;
+      while (j < n) {
+        if (sql[j] === q) {
+          if (sql[j + 1] === q) j += 2;
+          else {
+            j++;
+            break;
+          }
+        } else j++;
+      }
+      blank(i, j);
+      i = j;
+    } else if (sql[i] === "$") {
+      const m = /^\$[A-Za-z_]*\$/.exec(sql.slice(i));
+      if (m) {
+        const tag = m[0];
+        let j = sql.indexOf(tag, i + tag.length);
+        j = j < 0 ? n : j + tag.length;
+        blank(i, j);
+        i = j;
+      } else i++;
+    } else i++;
+  }
+  return out.join("");
+}
+
+// src/commands/script.ts
+async function analyzeScript(connection, sql, opts) {
+  const units = extractAnalyzableUnits(sql);
+  const explainable = units.filter((u) => u.kind === "explainable");
+  const exec = explainable.length ? await explainScript(
+    connection,
+    explainable.map((u) => ({
+      label: u.label,
+      sql: u.sql,
+      ...u.loopNote ? { loopNote: u.loopNote } : {}
+    })),
+    {
+      statementTimeoutMs: opts.statementTimeoutMs,
+      lockTimeoutMs: opts.lockTimeoutMs,
+      verbose: opts.verbose,
+      settings: opts.settings
+    }
+  ) : null;
+  let ei = 0;
+  const out = units.map((u) => {
+    if (u.kind === "skipped") return { label: u.label, status: "skipped", reason: u.reason };
+    const r = exec?.units[ei++];
+    if (!r) return { label: u.label, status: "skipped", reason: "not analyzed" };
+    if (r.error) {
+      return {
+        label: u.label,
+        status: "error",
+        reason: r.error.detail,
+        errorCode: r.error.code,
+        ...r.loopNote ? { loopNote: r.loopNote } : {}
+      };
+    }
+    const result = analyze(r.planJson, {
+      sql: u.sql,
+      config: opts.config,
+      redact: opts.redact
+    });
+    return {
+      label: u.label,
+      status: "analyzed",
+      result,
+      report: buildReport(result),
+      ...r.loopNote ? { loopNote: r.loopNote } : {}
+    };
+  });
+  return { executed: false, units: out, ...exec ? { serverMajor: exec.caps.major } : {} };
+}
+
+// src/core/diff.ts
+function weight(node) {
+  if (node.metrics.selfMs !== void 0) return node.metrics.selfMs;
+  const own = node.totalCost ?? 0;
+  let children = 0;
+  for (const c of node.children) children += c.totalCost ?? 0;
+  return Math.max(own - children, 0);
+}
+function signature(node) {
+  return nodeLabel(node);
+}
+function weightBySignature(result) {
+  const map = /* @__PURE__ */ new Map();
+  walk(result.tree.root, (node) => {
+    const key = signature(node);
+    map.set(key, (map.get(key) ?? 0) + weight(node));
+  });
+  return map;
+}
+function findingKey(d) {
+  return `${d.code}|${d.location?.relation ?? ""}`;
+}
+function diffAnalyses(before, after) {
+  const beforeMs = executionMs(before.tree);
+  const afterMs = executionMs(after.tree);
+  const timed = before.tree.hasAnalyze && after.tree.hasAnalyze;
+  let execDeltaMs;
+  let execDeltaPct;
+  if (beforeMs !== void 0 && afterMs !== void 0) {
+    execDeltaMs = afterMs - beforeMs;
+    execDeltaPct = beforeMs > 0 ? 100 * execDeltaMs / beforeMs : void 0;
+  }
+  const beforeMap = weightBySignature(before);
+  const afterMap = weightBySignature(after);
+  const keys = /* @__PURE__ */ new Set([...beforeMap.keys(), ...afterMap.keys()]);
+  const regressed = [];
+  const improved = [];
+  const added = [];
+  const removed = [];
+  for (const key of keys) {
+    const b = beforeMap.get(key);
+    const a = afterMap.get(key);
+    const beforeVal = b ?? 0;
+    const afterVal = a ?? 0;
+    const deltaMs = afterVal - beforeVal;
+    const deltaPct = beforeVal > 0 ? 100 * deltaMs / beforeVal : null;
+    const entry = {
+      signature: key,
+      beforeMs: beforeVal,
+      afterMs: afterVal,
+      deltaMs,
+      deltaPct
+    };
+    if (b === void 0) added.push(entry);
+    else if (a === void 0) removed.push(entry);
+    else if (deltaMs > 1e-4) regressed.push(entry);
+    else if (deltaMs < -1e-4) improved.push(entry);
+  }
+  regressed.sort((x, y) => y.deltaMs - x.deltaMs);
+  improved.sort((x, y) => x.deltaMs - y.deltaMs);
+  added.sort((x, y) => y.afterMs - x.afterMs);
+  removed.sort((x, y) => y.beforeMs - x.beforeMs);
+  const beforeKeys = new Set(before.diagnostics.map(findingKey));
+  const afterKeys = new Set(after.diagnostics.map(findingKey));
+  const newFindings = after.diagnostics.filter((d) => !beforeKeys.has(findingKey(d)));
+  const resolvedFindings = before.diagnostics.filter((d) => !afterKeys.has(findingKey(d)));
+  return {
+    beforeMs,
+    afterMs,
+    execDeltaMs,
+    execDeltaPct,
+    timed,
+    regressed,
+    improved,
+    added,
+    removed,
+    newFindings,
+    resolvedFindings
+  };
+}
+
+// src/server/schema.ts
+var CATALOG_SQL = `
+SELECT n.nspname                                   AS schema,
+       c.relname                                   AS name,
+       array_agg(a.attname::text ORDER BY a.attnum) AS columns
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+WHERE c.relkind IN ('r', 'p', 'v', 'm', 'f')
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+GROUP BY n.nspname, c.relname
+ORDER BY n.nspname, c.relname;
+`;
+async function catalog(connection) {
+  const rows = await queryReadOnly(
+    connection,
+    CATALOG_SQL
+  );
+  return rows.map((r) => ({ schema: r.schema, name: r.name, columns: r.columns ?? [] }));
+}
+var SQL = `
+SELECT c.relname                                    AS relation,
+       c.reltuples::bigint                          AS "estRows",
+       pg_total_relation_size(c.oid)                AS "totalBytes",
+       pg_relation_size(c.oid)                      AS "tableBytes",
+       (SELECT array_agg(ir.relname::text ORDER BY ir.relname)
+          FROM pg_index i JOIN pg_class ir ON ir.oid = i.indexrelid
+         WHERE i.indrelid = c.oid)                  AS indexes,
+       s.last_vacuum                                AS "lastVacuum",
+       s.last_autovacuum                            AS "lastAutovacuum",
+       s.last_analyze                               AS "lastAnalyze",
+       s.last_autoanalyze                           AS "lastAutoanalyze",
+       s.n_mod_since_analyze                        AS "modSinceAnalyze",
+       s.n_live_tup                                 AS "liveTup"
+FROM pg_class c
+LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+WHERE c.relkind IN ('r', 'p') AND c.relname = ANY($1);
+`;
+var toNum = (v) => v == null ? null : Number(v);
+async function relationStats(connection, relations) {
+  const names = [...new Set(relations.filter(Boolean))];
+  if (names.length === 0) return [];
+  const rows = await queryReadOnly(connection, SQL, [names]);
+  return rows.map((r) => ({
+    relation: r.relation,
+    estRows: toNum(r.estRows),
+    totalBytes: toNum(r.totalBytes),
+    tableBytes: toNum(r.tableBytes),
+    indexes: r.indexes ?? [],
+    lastVacuum: r.lastVacuum,
+    lastAutovacuum: r.lastAutovacuum,
+    lastAnalyze: r.lastAnalyze,
+    lastAutoanalyze: r.lastAutoanalyze,
+    modSinceAnalyze: toNum(r.modSinceAnalyze),
+    liveTup: toNum(r.liveTup)
+  }));
+}
+
+// src/diagnostics/stale-stats.ts
+var RULE_ID = "PGX_STALE_STATISTICS";
+var DOCS4 = "https://www.postgresql.org/docs/current/routine-vacuuming.html#VACUUM-FOR-STATISTICS";
+var MIN_ROWS = 1e3;
+function staleStatsFindings(stats, config) {
+  if (config.rules[RULE_ID]?.enabled === false) return [];
+  const severity = config.rules[RULE_ID]?.severity ?? "warn";
+  const ratioLimit = config.thresholds.staleStatsModRatio;
+  const out = [];
+  for (const s of stats) {
+    const rows = s.liveTup ?? s.estRows ?? 0;
+    if (rows < MIN_ROWS) continue;
+    const neverAnalyzed = !s.lastAnalyze && !s.lastAutoanalyze;
+    const modRatio = s.modSinceAnalyze != null && rows > 0 ? s.modSinceAnalyze / rows : 0;
+    if (!neverAnalyzed && modRatio < ratioLimit) continue;
+    out.push(
+      finding(RULE_ID, severity, {
+        title: neverAnalyzed ? `Table ${s.relation} has never been analyzed` : `Planner statistics on ${s.relation} are stale`,
+        detail: neverAnalyzed ? `${s.relation} (~${Math.round(rows).toLocaleString()} rows) has no planner statistics \u2014 pg_stat_user_tables shows no manual or auto ANALYZE.` : `${s.modSinceAnalyze?.toLocaleString()} rows of ${s.relation} changed since its last ANALYZE (${(modRatio * 100).toFixed(0)}% of ~${Math.round(rows).toLocaleString()} live rows).`,
+        cause: "The planner chooses plans from per-table statistics. When they are missing or stale, row estimates drift, which cascades into bad join orders, wrong scan types, and misestimates like PGX_ROW_MISESTIMATE.",
+        remediation: {
+          summary: `Run ANALYZE on ${s.relation}, and if it keeps going stale, lower its autovacuum analyze threshold.`,
+          steps: [
+            "ANALYZE the table now to refresh statistics.",
+            "If the table churns heavily, tune per-table autovacuum settings so auto-analyze keeps up."
+          ],
+          commands: [
+            { label: "Refresh statistics", sql: `ANALYZE ${s.relation};` },
+            {
+              label: "Analyze more eagerly on churny tables",
+              sql: `ALTER TABLE ${s.relation} SET (autovacuum_analyze_scale_factor = 0.02);`
+            }
+          ]
+        },
+        docsUrl: DOCS4,
+        meta: {
+          relation: s.relation,
+          modSinceAnalyze: s.modSinceAnalyze ?? 0,
+          liveTup: s.liveTup ?? 0
+        }
+      })
+    );
+  }
+  return out;
+}
+async function checkStaleStats(connection, result, config) {
+  try {
+    const relations = [
+      ...new Set(
+        flatten(result.tree.root).map((n) => n.relationName).filter((r) => !!r)
+      )
+    ];
+    if (!relations.length) return;
+    appendFindings(result, staleStatsFindings(await relationStats(connection, relations), config));
+  } catch {
+  }
+}
+function appendFindings(result, extra) {
+  if (!extra.length) return;
+  result.diagnostics = [...result.diagnostics, ...extra].sort(bySeverity);
+  result.worstSeverity = result.diagnostics.reduce(
+    (worst, d) => worst === null ? d.severity : maxSeverity(worst, d.severity),
+    null
+  );
+}
+
+// src/locks/live.ts
+var SQL2 = `
+SELECT a.pid,
+       a.usename                                        AS "user",
+       a.state,
+       a.wait_event_type                                AS "waitEventType",
+       a.wait_event                                     AS "waitEvent",
+       EXTRACT(EPOCH FROM (now() - a.query_start))      AS "ageSeconds",
+       a.query,
+       pg_blocking_pids(a.pid)                          AS "blockedBy"
+FROM pg_stat_activity a
+WHERE a.backend_type = 'client backend' AND a.pid <> pg_backend_pid()
+ORDER BY cardinality(pg_blocking_pids(a.pid)) DESC, a.query_start NULLS LAST;
+`;
+async function liveLocks(connection, capturedAt) {
+  const rows = await queryReadOnly(connection, SQL2);
+  const sessions = rows.map((r) => ({
+    pid: r.pid,
+    user: r.user,
+    state: r.state,
+    waitEventType: r.waitEventType,
+    waitEvent: r.waitEvent,
+    ageSeconds: r.ageSeconds == null ? null : Number(r.ageSeconds),
+    query: r.query,
+    blockedBy: r.blockedBy ?? []
+  }));
+  return { sessions, blocked: sessions.filter((s) => s.blockedBy.length > 0), capturedAt };
+}
+function dataDir() {
+  return process.env.PGEXPLAIN_DATA_DIR ?? join(homedir(), ".pgexplain");
+}
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS connections (
+  id TEXT PRIMARY KEY, name TEXT NOT NULL, dsn TEXT, host TEXT, port INTEGER,
+  database TEXT, "user" TEXT, password TEXT, sslmode TEXT, sslrootcert TEXT,
+  created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS runs (
+  id TEXT PRIMARY KEY, created_at INTEGER NOT NULL, kind TEXT NOT NULL,
+  connection_id TEXT, label TEXT, starred INTEGER NOT NULL DEFAULT 0,
+  baseline INTEGER NOT NULL DEFAULT 0, sql TEXT, verdict TEXT,
+  worst_severity TEXT, exec_ms REAL, counts TEXT NOT NULL, report TEXT NOT NULL,
+  plan_text TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_runs_created ON runs(created_at DESC);
+`;
+function openStore(file) {
+  const dir = dataDir();
+  mkdirSync(dir, { recursive: true });
+  const db = new Database(join(dir, "studio.db"));
+  db.pragma("journal_mode = WAL");
+  db.exec(SCHEMA);
+  const runCols = db.prepare("PRAGMA table_info(runs)").all();
+  if (!runCols.some((c) => c.name === "plan_text"))
+    db.exec("ALTER TABLE runs ADD COLUMN plan_text TEXT");
+  const connToPublic = (r) => ({
+    id: r.id,
+    name: r.name,
+    dsn: r.dsn ?? void 0,
+    host: r.host ?? void 0,
+    port: r.port ?? void 0,
+    database: r.database ?? void 0,
+    user: r.user ?? void 0,
+    sslmode: r.sslmode ?? void 0,
+    sslrootcert: r.sslrootcert ?? void 0,
+    hasPassword: !!r.password,
+    createdAt: r.created_at
+  });
+  const runToSummary = (r) => ({
+    id: r.id,
+    createdAt: r.created_at,
+    kind: r.kind,
+    connectionId: r.connection_id ?? null,
+    label: r.label ?? null,
+    starred: !!r.starred,
+    baseline: !!r.baseline,
+    sql: r.sql ?? null,
+    verdict: r.verdict ?? "",
+    worstSeverity: r.worst_severity ?? null,
+    execMs: r.exec_ms ?? null,
+    counts: JSON.parse(r.counts ?? '{"error":0,"warn":0,"info":0}')
+  });
+  return {
+    listConnections: () => db.prepare("SELECT * FROM connections ORDER BY created_at DESC").all().map(
+      connToPublic
+    ),
+    getConnection: (id) => {
+      const r = db.prepare("SELECT * FROM connections WHERE id = ?").get(id);
+      if (!r) return null;
+      return {
+        id: r.id,
+        name: r.name,
+        dsn: r.dsn ?? void 0,
+        host: r.host ?? void 0,
+        port: r.port ?? void 0,
+        database: r.database ?? void 0,
+        user: r.user ?? void 0,
+        password: r.password ?? void 0,
+        sslmode: r.sslmode ?? void 0,
+        sslrootcert: r.sslrootcert ?? void 0
+      };
+    },
+    createConnection: (input) => {
+      const id = crypto.randomUUID();
+      const createdAt = Date.now();
+      db.prepare(
+        `INSERT INTO connections (id,name,dsn,host,port,database,"user",password,sslmode,sslrootcert,created_at)
+         VALUES (@id,@name,@dsn,@host,@port,@database,@user,@password,@sslmode,@sslrootcert,@createdAt)`
+      ).run(normalizeConn({ id, createdAt, ...input }));
+      return connToPublic(db.prepare("SELECT * FROM connections WHERE id = ?").get(id));
+    },
+    updateConnection: (id, input) => {
+      const exists = db.prepare("SELECT id FROM connections WHERE id = ?").get(id);
+      if (!exists) return null;
+      db.prepare(
+        `UPDATE connections SET name=@name,dsn=@dsn,host=@host,port=@port,database=@database,
+         "user"=@user,password=@password,sslmode=@sslmode,sslrootcert=@sslrootcert WHERE id=@id`
+      ).run(normalizeConn({ id, createdAt: 0, ...input }));
+      return connToPublic(db.prepare("SELECT * FROM connections WHERE id = ?").get(id));
+    },
+    deleteConnection: (id) => db.prepare("DELETE FROM connections WHERE id = ?").run(id).changes > 0,
+    insertRun: (input) => {
+      const id = crypto.randomUUID();
+      const createdAt = Date.now();
+      db.prepare(
+        `INSERT INTO runs (id,created_at,kind,connection_id,label,starred,baseline,sql,verdict,worst_severity,exec_ms,counts,report,plan_text)
+         VALUES (@id,@createdAt,@kind,@connectionId,NULL,0,0,@sql,@verdict,@worstSeverity,@execMs,@counts,@report,@planText)`
+      ).run({
+        id,
+        createdAt,
+        kind: input.kind,
+        connectionId: input.connectionId ?? null,
+        sql: input.sql ?? null,
+        verdict: input.verdict,
+        worstSeverity: input.worstSeverity,
+        execMs: input.execMs,
+        counts: JSON.stringify(input.counts),
+        report: JSON.stringify(input.report),
+        planText: input.planText ?? null
+      });
+      return getRun(db, id);
+    },
+    listRuns: (limit = 200) => db.prepare("SELECT * FROM runs ORDER BY created_at DESC LIMIT ?").all(limit).map(
+      runToSummary
+    ),
+    getRun: (id) => getRun(db, id),
+    deleteRun: (id) => db.prepare("DELETE FROM runs WHERE id = ?").run(id).changes > 0,
+    updateRun: (id, patch) => {
+      const r = db.prepare("SELECT * FROM runs WHERE id = ?").get(id);
+      if (!r) return null;
+      if (patch.baseline === true) db.prepare("UPDATE runs SET baseline = 0").run();
+      db.prepare(
+        "UPDATE runs SET starred = COALESCE(@starred, starred), label = COALESCE(@label, label), baseline = COALESCE(@baseline, baseline) WHERE id = @id"
+      ).run({
+        id,
+        starred: patch.starred === void 0 ? null : patch.starred ? 1 : 0,
+        label: patch.label === void 0 ? null : patch.label,
+        baseline: patch.baseline === void 0 ? null : patch.baseline ? 1 : 0
+      });
+      return runToSummary(db.prepare("SELECT * FROM runs WHERE id = ?").get(id));
+    },
+    close: () => db.close()
+  };
+  function getRun(database, id) {
+    const r = database.prepare("SELECT * FROM runs WHERE id = ?").get(id);
+    if (!r) return null;
+    return {
+      ...runToSummary(r),
+      report: JSON.parse(r.report),
+      planText: r.plan_text ?? null
+    };
+  }
+}
+function normalizeConn(c) {
+  return {
+    id: c.id,
+    name: c.name,
+    dsn: c.dsn ?? null,
+    host: c.host ?? null,
+    port: c.port ?? null,
+    database: c.database ?? null,
+    user: c.user ?? null,
+    password: c.password ?? null,
+    sslmode: c.sslmode ?? null,
+    sslrootcert: c.sslrootcert ?? null,
+    createdAt: c.createdAt
+  };
+}
+
+// src/server/settings.ts
+function configPath() {
+  return join(dataDir(), "config.json");
+}
+function merge(raw) {
+  return {
+    thresholds: { ...DEFAULT_THRESHOLDS, ...raw.thresholds ?? {} },
+    rules: raw.rules ?? {}
+  };
+}
+async function readStudioConfig() {
+  try {
+    return merge(JSON.parse(await readFile(configPath(), "utf8")));
+  } catch {
+    return merge({});
+  }
+}
+async function writeStudioConfig(raw) {
+  const cfg = merge(raw);
+  await mkdir(dataDir(), { recursive: true });
+  await writeFile(configPath(), JSON.stringify(cfg, null, 2));
+  return cfg;
+}
+function validate(schema, data) {
+  const result = schema.safeParse(data);
+  if (result.success) return result.data;
+  const issues = result.error.issues.map((i) => `${i.path.join(".") || "body"}: ${i.message}`).join("; ");
+  const diagnostic = {
+    code: "PGX_BAD_REQUEST",
+    domain: "operational",
+    severity: "error",
+    title: "Invalid request",
+    detail: issues,
+    cause: "The request body did not match the expected shape.",
+    remediation: { summary: "Correct the highlighted fields and resend the request." }
+  };
+  throw new AppError(diagnostic, 2 /* Usage */);
+}
+var ConnectionInputSchema = z.object({
+  dsn: z.string().optional(),
+  host: z.string().optional(),
+  port: z.number().int().positive().optional(),
+  database: z.string().optional(),
+  user: z.string().optional(),
+  password: z.string().optional(),
+  sslmode: z.enum(["disable", "prefer", "require", "verify-ca", "verify-full"]).optional(),
+  sslrootcert: z.string().optional(),
+  connectTimeoutMs: z.number().int().positive().optional()
+});
+var AnalyzeBodySchema = z.object({
+  plan: z.string().min(1, "a plan (EXPLAIN FORMAT JSON) is required"),
+  sql: z.string().optional(),
+  statement: z.number().int().min(1).optional(),
+  redact: z.boolean().optional()
+});
+var ExplainFlagsSchema = z.object({
+  analyze: z.boolean(),
+  buffers: z.boolean(),
+  verbose: z.boolean(),
+  settings: z.boolean(),
+  wal: z.boolean(),
+  timing: z.boolean(),
+  costs: z.boolean(),
+  summary: z.boolean(),
+  genericPlan: z.boolean(),
+  compat: z.boolean()
+}).partial();
+var RunBodySchema = z.object({
+  connection: ConnectionInputSchema.optional(),
+  connectionId: z.string().optional(),
+  sql: z.string().min(1, "SQL is required"),
+  statement: z.number().int().min(1).optional(),
+  params: z.array(z.string()).optional(),
+  flags: ExplainFlagsSchema.optional(),
+  redact: z.boolean().optional(),
+  statementTimeoutMs: z.number().int().positive().optional(),
+  lockTimeoutMs: z.number().int().positive().optional(),
+  force: z.boolean().optional()
+}).refine((b) => b.connection || b.connectionId, {
+  message: "provide a connection or a connectionId",
+  path: ["connection"]
+});
+var AnalyzeSqlBodySchema = z.object({
+  connection: ConnectionInputSchema.optional(),
+  connectionId: z.string().optional(),
+  sql: z.string().min(1, "SQL is required"),
+  redact: z.boolean().optional()
+}).refine((b) => b.connection || b.connectionId, {
+  message: "provide a connection or connectionId"
+});
+var CatalogBodySchema = z.object({
+  connection: ConnectionInputSchema.optional(),
+  connectionId: z.string().optional()
+}).refine((b) => b.connection || b.connectionId, {
+  message: "provide a connection or connectionId"
+});
+var LiveLocksBodySchema = z.object({
+  connection: ConnectionInputSchema.optional(),
+  connectionId: z.string().optional()
+}).refine((b) => b.connection || b.connectionId, {
+  message: "provide a connection or connectionId"
+});
+var SchemaBodySchema = z.object({
+  connection: ConnectionInputSchema.optional(),
+  connectionId: z.string().optional(),
+  relations: z.array(z.string()).min(1)
+}).refine((b) => b.connection || b.connectionId, {
+  message: "provide a connection or connectionId"
+});
+var ConnectionCreateSchema = z.object({
+  name: z.string().min(1, "a name is required"),
+  dsn: z.string().optional(),
+  host: z.string().optional(),
+  port: z.number().int().positive().optional(),
+  database: z.string().optional(),
+  user: z.string().optional(),
+  password: z.string().optional(),
+  sslmode: z.enum(["disable", "prefer", "require", "verify-ca", "verify-full"]).optional(),
+  sslrootcert: z.string().optional()
+});
+var SettingsBodySchema = z.object({
+  thresholds: z.record(z.string(), z.number()).optional(),
+  rules: z.record(
+    z.string(),
+    z.object({
+      enabled: z.boolean().optional(),
+      severity: z.enum(["error", "warn", "info"]).optional()
+    })
+  ).optional()
+});
+var ExportBodySchema = z.object({
+  runId: z.string().optional(),
+  plan: z.string().optional(),
+  format: z.enum(["markdown", "html", "text", "json"]),
+  sql: z.string().optional(),
+  redact: z.boolean().optional()
+}).refine((b) => b.runId || b.plan, { message: "provide runId or plan" });
+var RunPatchSchema = z.object({
+  starred: z.boolean().optional(),
+  label: z.string().nullable().optional(),
+  baseline: z.boolean().optional()
+});
+var DiffBodySchema = z.object({
+  beforePlan: z.string().optional(),
+  afterPlan: z.string().optional(),
+  beforeId: z.string().optional(),
+  afterId: z.string().optional(),
+  redact: z.boolean().optional()
+}).refine((b) => b.beforePlan && b.afterPlan || b.beforeId && b.afterId, {
+  message: "provide beforePlan+afterPlan or beforeId+afterId"
+});
+
+// src/server/routes/index.ts
+function apiRoutes(store, config) {
+  const api = new Hono();
+  api.get(
+    "/api/meta",
+    (c) => c.json({
+      app: "pgexplain",
+      version: package_default.version,
+      node: process.version,
+      formats: FORMATS,
+      defaults: { thresholds: DEFAULT_THRESHOLDS }
+    })
+  );
+  api.get("/api/health", (c) => c.json({ ok: true }));
+  api.get("/api/settings", (c) => c.json(config.current));
+  api.put("/api/settings", async (c) => {
+    const body = validate(SettingsBodySchema, await c.req.json().catch(() => ({})));
+    config.current = await writeStudioConfig(body);
+    return c.json(config.current);
+  });
+  api.post("/api/analyze", async (c) => {
+    const body = validate(AnalyzeBodySchema, await c.req.json().catch(() => ({})));
+    const result = analyze(body.plan, {
+      statement: body.statement,
+      redact: body.redact,
+      sql: body.sql,
+      config: config.current
+    });
+    const report = buildReport(result);
+    const run = store.insertRun(
+      saveFields("analyze", body.sql ?? null, null, result, report, body.plan)
+    );
+    return c.json({ ...report, runId: run.id });
+  });
+  api.post("/api/run", async (c) => {
+    const body = validate(RunBodySchema, await c.req.json().catch(() => ({})));
+    const { connection, connectionId } = resolveConnection(
+      store,
+      body.connection,
+      body.connectionId
+    );
+    const statement = pickStatement(splitStatements(body.sql), body.statement);
+    const flags = { ...DEFAULT_EXPLAIN_FLAGS, ...body.flags ?? {} };
+    if (flags.analyze && !flags.genericPlan && !isReadOnlyStatement(statement) && !body.force) {
+      const verb = statement.trim().split(/\s+/)[0]?.toUpperCase() ?? "statement";
+      throw opError("PGX_NON_SELECT_REFUSED", {
+        detail: `Refusing to ANALYZE a non-SELECT (${verb}) \u2014 it would modify data.`
+      });
+    }
+    const exec = await runExplain({
+      connection,
+      statement,
+      params: body.params,
+      flags,
+      statementTimeoutMs: body.statementTimeoutMs ?? 3e4,
+      lockTimeoutMs: body.lockTimeoutMs ?? 5e3,
+      forceWrite: !!body.force,
+      rollback: true
+    });
+    const result = analyze(exec.json, {
+      redact: body.redact,
+      sql: statement,
+      config: config.current
+    });
+    await checkStaleStats(connection, result, config.current);
+    const report = {
+      ...buildReport(result),
+      server: { major: exec.caps.major, omitted: exec.omitted }
+    };
+    const run = store.insertRun(
+      saveFields("run", statement, connectionId, result, report, exec.json)
+    );
+    return c.json({ ...report, runId: run.id });
+  });
+  api.post("/api/diff", async (c) => {
+    const body = validate(DiffBodySchema, await c.req.json().catch(() => ({})));
+    const beforePlan = body.beforePlan ?? planTextOf(store, body.beforeId);
+    const afterPlan = body.afterPlan ?? planTextOf(store, body.afterId);
+    const before = analyze(beforePlan, { redact: body.redact });
+    const after = analyze(afterPlan, { redact: body.redact });
+    return c.json({
+      ...diffAnalyses(before, after),
+      beforePlan: serializeNode(before.tree.root),
+      afterPlan: serializeNode(after.tree.root)
+    });
+  });
+  api.post("/api/export", async (c) => {
+    const body = validate(ExportBodySchema, await c.req.json().catch(() => ({})));
+    const planText = body.plan ?? planTextOf(store, body.runId);
+    const result = analyze(planText, { redact: body.redact, sql: body.sql });
+    const content = render(result, { format: body.format });
+    const types = {
+      markdown: "text/markdown",
+      html: "text/html",
+      text: "text/plain",
+      json: "application/json"
+    };
+    return c.body(content, 200, { "Content-Type": `${types[body.format]}; charset=utf-8` });
+  });
+  api.post("/api/catalog", async (c) => {
+    const body = validate(CatalogBodySchema, await c.req.json().catch(() => ({})));
+    const { connection } = resolveConnection(store, body.connection, body.connectionId);
+    return c.json({ tables: await catalog(connection) });
+  });
+  api.post("/api/schema", async (c) => {
+    const body = validate(SchemaBodySchema, await c.req.json().catch(() => ({})));
+    const { connection } = resolveConnection(store, body.connection, body.connectionId);
+    return c.json({ relations: await relationStats(connection, body.relations) });
+  });
+  api.post("/api/analyze-sql", async (c) => {
+    const body = validate(AnalyzeSqlBodySchema, await c.req.json().catch(() => ({})));
+    const { connection } = resolveConnection(store, body.connection, body.connectionId);
+    const analysis = await analyzeScript(connection, body.sql, {
+      config: config.current,
+      redact: body.redact,
+      statementTimeoutMs: 3e4,
+      lockTimeoutMs: 5e3
+    });
+    return c.json({
+      executed: false,
+      serverMajor: analysis.serverMajor ?? null,
+      units: analysis.units.map((u) => ({
+        label: u.label,
+        status: u.status,
+        loopNote: u.loopNote ?? null,
+        report: u.report ?? null,
+        reason: u.reason ?? null,
+        errorCode: u.errorCode ?? null
+      }))
+    });
+  });
+  api.post("/api/locks/live", async (c) => {
+    const body = validate(LiveLocksBodySchema, await c.req.json().catch(() => ({})));
+    const { connection } = resolveConnection(store, body.connection, body.connectionId);
+    return c.json(await liveLocks(connection, Date.now()));
+  });
+  api.get("/api/history", (c) => c.json({ runs: store.listRuns() }));
+  api.get("/api/history/:id", (c) => {
+    const run = store.getRun(c.req.param("id"));
+    return run ? c.json(run) : c.json({ error: { code: "PGX_NOT_FOUND", title: "No such run" } }, 404);
+  });
+  api.delete(
+    "/api/history/:id",
+    (c) => store.deleteRun(c.req.param("id")) ? c.json({ ok: true }) : c.json({ error: { code: "PGX_NOT_FOUND" } }, 404)
+  );
+  api.patch("/api/history/:id", async (c) => {
+    const patch = validate(RunPatchSchema, await c.req.json().catch(() => ({})));
+    const run = store.updateRun(c.req.param("id"), patch);
+    return run ? c.json(run) : c.json({ error: { code: "PGX_NOT_FOUND" } }, 404);
+  });
+  api.get("/api/connections", (c) => c.json({ connections: store.listConnections() }));
+  api.post("/api/connections", async (c) => {
+    const input = validate(ConnectionCreateSchema, await c.req.json().catch(() => ({})));
+    return c.json(store.createConnection(input), 201);
+  });
+  api.put("/api/connections/:id", async (c) => {
+    const input = validate(ConnectionCreateSchema, await c.req.json().catch(() => ({})));
+    const updated = store.updateConnection(c.req.param("id"), input);
+    return updated ? c.json(updated) : c.json({ error: { code: "PGX_NOT_FOUND" } }, 404);
+  });
+  api.delete(
+    "/api/connections/:id",
+    (c) => store.deleteConnection(c.req.param("id")) ? c.json({ ok: true }) : c.json({ error: { code: "PGX_NOT_FOUND" } }, 404)
+  );
+  return api;
+}
+function resolveConnection(store, inline, connectionId) {
+  if (inline) return { connection: toConnectionOptions(inline), connectionId: null };
+  if (connectionId) {
+    const saved = store.getConnection(connectionId);
+    if (!saved)
+      throw opError("PGX_EMPTY_INPUT", { detail: `No saved connection ${connectionId}.` });
+    return { connection: toConnectionOptions(saved), connectionId };
+  }
+  throw opError("PGX_EMPTY_INPUT", { detail: "Provide a connection or a connectionId." });
+}
+function toConnectionOptions(input) {
+  const c = {
+    connectTimeoutMs: "connectTimeoutMs" in input && input.connectTimeoutMs || 1e4
+  };
+  if (input.dsn) c.dsn = input.dsn;
+  if (input.host) c.host = input.host;
+  if (input.port) c.port = input.port;
+  if (input.database) c.database = input.database;
+  if (input.user) c.user = input.user;
+  if ("password" in input && input.password) c.password = input.password;
+  if (input.sslmode) c.sslmode = input.sslmode;
+  if (input.sslrootcert) c.sslrootcert = input.sslrootcert;
+  return c;
+}
+function saveFields(kind, sql, connectionId, result, report, planText) {
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const d of result.diagnostics) counts[d.severity]++;
+  return {
+    kind,
+    sql,
+    connectionId,
+    planText,
+    verdict: result.verdict,
+    worstSeverity: result.worstSeverity,
+    execMs: executionMs(result.tree) ?? null,
+    counts,
+    report
+  };
+}
+function planTextOf(store, id) {
+  if (!id)
+    throw opError("PGX_EMPTY_INPUT", {
+      detail: "Provide beforePlan/afterPlan or beforeId/afterId."
+    });
+  const run = store.getRun(id);
+  if (!run?.planText) {
+    throw opError("PGX_EMPTY_INPUT", { detail: `Run ${id} has no stored plan to diff.` });
+  }
+  return run.planText;
+}
+function pickStatement(statements, index) {
+  if (statements.length === 0)
+    throw opError("PGX_EMPTY_INPUT", { detail: "No SQL statement found." });
+  if (index !== void 0) {
+    const stmt = statements[index - 1];
+    if (!stmt) {
+      throw opError("PGX_MULTIPLE_STATEMENTS", {
+        detail: `statement ${index} is out of range; found ${statements.length}.`
+      });
+    }
+    return stmt;
+  }
+  if (statements.length > 1) {
+    throw opError("PGX_MULTIPLE_STATEMENTS", {
+      detail: `Found ${statements.length} statements; pass a 1-based "statement" index.`
+    });
+  }
+  return statements[0];
+}
+
+// src/server/app.ts
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".map": "application/json"
+};
+function createApp(opts) {
+  const app = new Hono();
+  const webRoot = resolve(opts.webRoot);
+  app.route("/", apiRoutes(opts.store, { current: opts.config }));
+  app.onError((err, c) => {
+    if (err instanceof AppError) {
+      const status = httpStatusFor(err.exitCode);
+      return c.json({ error: scrubDiagnostic(err.diagnostic) }, status);
+    }
+    return c.json(
+      {
+        error: {
+          code: "PGX_INTERNAL",
+          severity: "error",
+          title: "pgexplain hit an unexpected error",
+          detail: scrubCredentials(err instanceof Error ? err.message : String(err)),
+          remediation: {
+            summary: "Retry; if it recurs, file an issue with the steps to reproduce."
+          }
+        }
+      },
+      500
+    );
+  });
+  app.notFound((c) => {
+    if (c.req.path.startsWith("/api")) {
+      return c.json(
+        { error: { code: "PGX_NOT_FOUND", title: "No such API route", detail: c.req.path } },
+        404
+      );
+    }
+    return serveSpa(c, webRoot);
+  });
+  app.get("*", async (c) => {
+    if (c.req.path.startsWith("/api")) return c.notFound();
+    const file = await resolveStatic(webRoot, c.req.path);
+    if (file) {
+      return c.body(toBytes(file.body), 200, {
+        "Content-Type": MIME[file.ext] ?? "application/octet-stream"
+      });
+    }
+    return serveSpa(c, webRoot);
+  });
+  return app;
+}
+async function serveSpa(c, webRoot) {
+  const index = await readFileSafe(join(webRoot, "index.html"));
+  if (index) return c.body(toBytes(index), 200, { "Content-Type": "text/html; charset=utf-8" });
+  return c.html(
+    `<!doctype html><meta charset="utf-8"><title>pgexplain studio</title>
+     <body style="font:15px system-ui;padding:3rem;max-width:40rem;margin:auto">
+     <h1>UI not built</h1>
+     <p>The studio UI bundle is missing at <code>${webRoot}</code>.</p>
+     <p>Build it with <code>pnpm run build:web</code>, then restart <code>pg-explain studio</code>.</p>
+     </body>`,
+    200
+  );
+}
+async function resolveStatic(webRoot, urlPath) {
+  const rel = normalize(decodeURIComponent(urlPath)).replace(/^(\.\.[/\\])+/, "");
+  const full = join(webRoot, rel);
+  if (!full.startsWith(webRoot)) return null;
+  try {
+    if (!(await stat(full)).isFile()) return null;
+  } catch {
+    return null;
+  }
+  const body = await readFileSafe(full);
+  return body ? { body, ext: extname(full) } : null;
+}
+function toBytes(u8) {
+  return u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+}
+async function readFileSafe(path) {
+  try {
+    return await readFile(path);
+  } catch {
+    return null;
+  }
+}
+function httpStatusFor(exitCode) {
+  switch (exitCode) {
+    case 2:
+      return 400;
+    case 3:
+    case 4:
+      return 422;
+    case 5:
+      return 502;
+    default:
+      return 500;
+  }
+}
+function scrubDiagnostic(d) {
+  const json = JSON.stringify(d);
+  return JSON.parse(scrubCredentials(json));
+}
+
+// src/server/start.ts
+async function startStudio(opts) {
+  const webRoot = opts.webRoot ?? fileURLToPath(new URL("./web", import.meta.url));
+  const app = createApp({ webRoot, store: openStore(), config: await readStudioConfig() });
+  return new Promise((resolvePromise) => {
+    const server = serve({ fetch: app.fetch, hostname: opts.host, port: opts.port }, (info) => {
+      resolvePromise({
+        url: `http://${displayHost(opts.host)}:${info.port}`,
+        port: info.port,
+        close: () => new Promise((res) => server.close(() => res()))
+      });
+    });
+  });
+}
+function displayHost(host) {
+  return host === "0.0.0.0" || host === "::" ? "localhost" : host;
+}
+
+export { startStudio };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map