@carllee1983/dbcli 7.0.0 → 8.0.0

package/dist/core.mjs

@@ -1,5 +1,35 @@
 // @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
   this[name] = __returnValue.bind(null, newValue);
@@ -16,6 +46,76 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
+// node_modules/picocolors/picocolors.js
+var require_picocolors = __commonJS((exports, module) => {
+  var p = process || {};
+  var argv = p.argv || [];
+  var env = p.env || {};
+  var isColorSupported = !(!!env.NO_COLOR || argv.includes("--no-color")) && (!!env.FORCE_COLOR || argv.includes("--color") || p.platform === "win32" || (p.stdout || {}).isTTY && env.TERM !== "dumb" || !!env.CI);
+  var formatter = (open, close, replace = open) => (input) => {
+    let string = "" + input, index = string.indexOf(close, open.length);
+    return ~index ? open + replaceClose(string, close, replace, index) + close : open + string + close;
+  };
+  var replaceClose = (string, close, replace, index) => {
+    let result = "", cursor = 0;
+    do {
+      result += string.substring(cursor, index) + replace;
+      cursor = index + close.length;
+      index = string.indexOf(close, cursor);
+    } while (~index);
+    return result + string.substring(cursor);
+  };
+  var createColors = (enabled = isColorSupported) => {
+    let f = enabled ? formatter : () => String;
+    return {
+      isColorSupported: enabled,
+      reset: f("\x1B[0m", "\x1B[0m"),
+      bold: f("\x1B[1m", "\x1B[22m", "\x1B[22m\x1B[1m"),
+      dim: f("\x1B[2m", "\x1B[22m", "\x1B[22m\x1B[2m"),
+      italic: f("\x1B[3m", "\x1B[23m"),
+      underline: f("\x1B[4m", "\x1B[24m"),
+      inverse: f("\x1B[7m", "\x1B[27m"),
+      hidden: f("\x1B[8m", "\x1B[28m"),
+      strikethrough: f("\x1B[9m", "\x1B[29m"),
+      black: f("\x1B[30m", "\x1B[39m"),
+      red: f("\x1B[31m", "\x1B[39m"),
+      green: f("\x1B[32m", "\x1B[39m"),
+      yellow: f("\x1B[33m", "\x1B[39m"),
+      blue: f("\x1B[34m", "\x1B[39m"),
+      magenta: f("\x1B[35m", "\x1B[39m"),
+      cyan: f("\x1B[36m", "\x1B[39m"),
+      white: f("\x1B[37m", "\x1B[39m"),
+      gray: f("\x1B[90m", "\x1B[39m"),
+      bgBlack: f("\x1B[40m", "\x1B[49m"),
+      bgRed: f("\x1B[41m", "\x1B[49m"),
+      bgGreen: f("\x1B[42m", "\x1B[49m"),
+      bgYellow: f("\x1B[43m", "\x1B[49m"),
+      bgBlue: f("\x1B[44m", "\x1B[49m"),
+      bgMagenta: f("\x1B[45m", "\x1B[49m"),
+      bgCyan: f("\x1B[46m", "\x1B[49m"),
+      bgWhite: f("\x1B[47m", "\x1B[49m"),
+      blackBright: f("\x1B[90m", "\x1B[39m"),
+      redBright: f("\x1B[91m", "\x1B[39m"),
+      greenBright: f("\x1B[92m", "\x1B[39m"),
+      yellowBright: f("\x1B[93m", "\x1B[39m"),
+      blueBright: f("\x1B[94m", "\x1B[39m"),
+      magentaBright: f("\x1B[95m", "\x1B[39m"),
+      cyanBright: f("\x1B[96m", "\x1B[39m"),
+      whiteBright: f("\x1B[97m", "\x1B[39m"),
+      bgBlackBright: f("\x1B[100m", "\x1B[49m"),
+      bgRedBright: f("\x1B[101m", "\x1B[49m"),
+      bgGreenBright: f("\x1B[102m", "\x1B[49m"),
+      bgYellowBright: f("\x1B[103m", "\x1B[49m"),
+      bgBlueBright: f("\x1B[104m", "\x1B[49m"),
+      bgMagentaBright: f("\x1B[105m", "\x1B[49m"),
+      bgCyanBright: f("\x1B[106m", "\x1B[49m"),
+      bgWhiteBright: f("\x1B[107m", "\x1B[49m")
+    };
+  };
+  module.exports = createColors();
+  module.exports.createColors = createColors;
+});
+
 // node_modules/lru-cache/dist/esm/node/index.min.js
 import { tracingChannel as j, channel as G } from "diagnostics_channel";
 var w, W, C, D = () => w.hasSubscribers || W.hasSubscribers, I, L, P = (u, e, t2, i) => {
@@ -988,15 +1088,26 @@ var init_schema_loader = __esm(() => {
 });
 
 // src/adapters/types.ts
+var DATABASE_SYSTEMS = Object.freeze([
+  "postgresql",
+  "mysql",
+  "mariadb",
+  "mongodb",
+  "redis",
+  "elasticsearch"
+]);
+
 class ConnectionError extends Error {
   code;
   hints;
   limitMs;
-  constructor(code, message, hints, limitMs) {
+  retrySafe;
+  constructor(code, message, hints, limitMs, retrySafe = true) {
     super(message);
     this.code = code;
     this.hints = hints;
     this.limitMs = limitMs;
+    this.retrySafe = retrySafe;
     this.name = "ConnectionError";
     Object.setPrototypeOf(this, ConnectionError.prototype);
   }
@@ -1036,7 +1147,26 @@ var COMMAND_CAPABILITY_KEYS = Object.freeze([
   "auditTail",
   "auditShow",
   "auditClear",
-  "auditHealth"
+  "auditHealth",
+  "explain",
+  "plan",
+  "impactAssess",
+  "assert",
+  "snapshot",
+  "verify",
+  "semantic",
+  "design",
+  "proxy",
+  "proxyAnalyze",
+  "verification",
+  "verificationPrune",
+  "evidence",
+  "contract",
+  "recovery",
+  "backfillArtifact",
+  "password",
+  "capabilityDiscover",
+  "capabilityCheck"
 ]);
 function cap(status, tier, note) {
   return Object.freeze({ status, tier, note });
@@ -1078,8 +1208,40 @@ var SQL_BASE = {
   inspect: cap("supported", "readonly", "Agent context snapshot is supported."),
   report: cap("supported", "readonly", "Diagnostic report is supported."),
   guide: cap("supported", "readonly", "Deterministic next-command planner is supported."),
+  explain: cap("supported", "readonly", "EXPLAIN plans are read from SQL engines."),
+  plan: cap("supported", "readonly", "Offline write-risk analysis of SQL against the schema cache."),
+  impactAssess: cap("supported", "local-write", "Offline impact assessment of a SQL schema change; writes its report locally."),
+  assert: cap("supported", "local-write", "Data assertions over SQL results; optionally writes a verification artifact."),
+  snapshot: cap("supported", "local-write", "Captures a SQL result fingerprint under .dbcli/snapshots/."),
+  verify: cap("supported", "local-write", "Scenario verification over SQL; writes a verification artifact."),
+  semantic: cap("supported", "readonly", "Governed semantic context and drift over a SQL schema cache."),
+  design: cap("supported", "local-write", "Schema design authoring and comparison for SQL dialects; init writes a template."),
+  proxy: cap("supported", "interactive", "Local observing proxy for the MySQL, MariaDB and PostgreSQL wire protocols."),
+  password: cap("supported", "interactive", "Rotates the stored connection credential; refused under agent mode."),
+  proxyAnalyze: cap("not-applicable", "readonly", "Reads locally recorded proxy events; never contacts an engine."),
+  verification: cap("not-applicable", "readonly", "Inspects verification artifacts under .dbcli/verification/."),
+  verificationPrune: cap("not-applicable", "local-write", "Deletes local verification artifacts; dry-run unless --execute --force."),
+  evidence: cap("not-applicable", "local-write", "Composes, validates and renders evidence packs from local artifacts."),
+  contract: cap("not-applicable", "readonly", "Validates and inspects governed semantic contracts offline."),
+  recovery: cap("not-applicable", "readonly", "Renders recovery codes and their remediation steps from a static table."),
+  backfillArtifact: cap("not-applicable", "local-write", "Builds a backfill artifact from a source manifest and v2 connection identity."),
+  capabilityDiscover: cap("not-applicable", "readonly", "Emits the static capability catalog; opens no connection."),
+  capabilityCheck: cap("not-applicable", "readonly", "Evaluates required capability ids against the local configuration only."),
   ...ENGINE_INDEPENDENT
 };
+var SQL_ONLY_UNSUPPORTED = {
+  explain: cap("unsupported", "none", "src/commands/explain.ts refuses a non-SQL connection."),
+  plan: cap("unsupported", "none", "Risk analysis is SQL-dialect based; toSqlDialect resolves no dialect here."),
+  assert: cap("unsupported", "none", "src/commands/assert.ts refuses a non-SQL connection."),
+  snapshot: cap("unsupported", "none", "src/commands/snapshot.ts refuses a non-SQL connection."),
+  verify: cap("unsupported", "none", "src/commands/verify.ts refuses a non-SQL connection."),
+  proxy: cap("unsupported", "none", "The proxy speaks the MySQL and PostgreSQL wire protocols only.")
+};
+var SQL_MODE_LIMITED = {
+  impactAssess: cap("limited", "local-write", "Runs against an ORM artifact; --against-cache needs a SQL connection."),
+  semantic: cap("limited", "readonly", "Governed context, search and drift work; draft validate needs a SQL connection."),
+  design: cap("limited", "local-write", "Authoring and ORM comparison work; --against-cache needs a SQL connection.")
+};
 var ENGINE_CAPABILITIES = Object.freeze({
   postgresql: Object.freeze({
     ...SQL_BASE,
@@ -1089,6 +1251,10 @@ var ENGINE_CAPABILITIES = Object.freeze({
   mariadb: Object.freeze(SQL_BASE),
   mongodb: Object.freeze({
     ...SQL_BASE,
+    ...SQL_ONLY_UNSUPPORTED,
+    ...SQL_MODE_LIMITED,
+    ...SQL_MODE_LIMITED,
+    ...SQL_MODE_LIMITED,
     lint: cap("unsupported", "none", "Static lint accepts SQL connections only."),
     schemaSingle: cap("limited", "readonly", "MongoDB schema is sampled from documents."),
     schemaFullScan: cap("limited", "readonly", "Full scan is sampled and document-oriented."),
@@ -1108,6 +1274,7 @@ var ENGINE_CAPABILITIES = Object.freeze({
   }),
   redis: Object.freeze({
     ...SQL_BASE,
+    ...SQL_ONLY_UNSUPPORTED,
     lint: cap("unsupported", "none", "Static lint accepts SQL connections only."),
     schemaSingle: cap("limited", "readonly", "Per-key synthetic schema only."),
     schemaFullScan: cap("unsupported", "none", "Redis has no full schema cache scan."),
@@ -1127,6 +1294,7 @@ var ENGINE_CAPABILITIES = Object.freeze({
   }),
   elasticsearch: Object.freeze({
     ...SQL_BASE,
+    ...SQL_ONLY_UNSUPPORTED,
     lint: cap("unsupported", "none", "Static lint accepts SQL connections only."),
     schemaSingle: cap("limited", "readonly", "Schema flattens index mappings."),
     schemaFullScan: cap("supported", "readonly", "Full scan iterates non-system indices."),
@@ -1145,8 +1313,272 @@ var ENGINE_CAPABILITIES = Object.freeze({
     shell: cap("limited", "interactive", "Dedicated Kibana Dev Tools-style REPL (method/path + JSON body, blank-line submit); read-focused.")
   })
 });
+// src/adapters/error-mapper.ts
+var TRANSPORT_CODES = {
+  ECONNREFUSED: "ECONNREFUSED",
+  ETIMEDOUT: "ETIMEDOUT",
+  ESOCKETTIMEDOUT: "ETIMEDOUT",
+  ENOTFOUND: "ENOTFOUND",
+  EAI_AGAIN: "ENOTFOUND",
+  PROTOCOL_CONNECTION_LOST: "CONNECTION_LOST",
+  PROTOCOL_SEQUENCE_TIMEOUT: "ETIMEDOUT",
+  ECONNRESET: "CONNECTION_LOST",
+  EPIPE: "CONNECTION_LOST",
+  ECONNABORTED: "CONNECTION_LOST",
+  EHOSTUNREACH: "EHOSTUNREACH",
+  ENETUNREACH: "EHOSTUNREACH",
+  ENETDOWN: "EHOSTUNREACH"
+};
+function isTransportDriverCode(code) {
+  return TLS_CODE_PREFIX.test(code) || TRANSPORT_CODES[code] !== undefined;
+}
+var TLS_CODE_PREFIX = /^(CERT_|SELF_SIGNED_|DEPTH_ZERO_|UNABLE_TO_(?:GET|VERIFY)_|ERR_TLS_|ERR_SSL_)/;
+var MYSQL_CODES = {
+  ER_NO_SUCH_TABLE: "TABLE_NOT_FOUND",
+  ER_BAD_FIELD_ERROR: "COLUMN_NOT_FOUND",
+  ER_PARSE_ERROR: "SQL_SYNTAX_ERROR",
+  ER_ACCESS_DENIED_ERROR: "AUTH_FAILED",
+  ER_DBACCESS_DENIED_ERROR: "AUTH_FAILED",
+  ER_NOT_SUPPORTED_AUTH_MODE: "AUTH_FAILED",
+  ER_MUST_CHANGE_PASSWORD_LOGIN: "AUTH_FAILED",
+  ER_QUERY_TIMEOUT: "STATEMENT_TIMEOUT",
+  ER_STATEMENT_TIMEOUT: "STATEMENT_TIMEOUT",
+  ER_CON_COUNT_ERROR: "TOO_MANY_CONNECTIONS",
+  ER_SERVER_SHUTDOWN: "CONNECTION_LOST"
+};
+var MYSQL_ERRNOS = {
+  1045: "AUTH_FAILED",
+  1044: "AUTH_FAILED",
+  1054: "COLUMN_NOT_FOUND",
+  1064: "SQL_SYNTAX_ERROR",
+  1146: "TABLE_NOT_FOUND",
+  1251: "AUTH_FAILED",
+  1698: "AUTH_FAILED",
+  1040: "TOO_MANY_CONNECTIONS",
+  1053: "CONNECTION_LOST",
+  2006: "CONNECTION_LOST",
+  2013: "CONNECTION_LOST",
+  1969: "STATEMENT_TIMEOUT",
+  3024: "STATEMENT_TIMEOUT"
+};
+var SQLSTATES = {
+  "28000": "AUTH_FAILED",
+  "28P01": "AUTH_FAILED",
+  "42601": "SQL_SYNTAX_ERROR",
+  "42P01": "TABLE_NOT_FOUND",
+  "42703": "COLUMN_NOT_FOUND",
+  "57014": "STATEMENT_TIMEOUT",
+  "08000": "CONNECTION_LOST",
+  "08003": "CONNECTION_LOST",
+  "08006": "CONNECTION_LOST",
+  "08001": "ECONNREFUSED",
+  "08004": "CONNECTION_REJECTED",
+  "53300": "TOO_MANY_CONNECTIONS",
+  "57P01": "CONNECTION_LOST",
+  "57P02": "CONNECTION_LOST",
+  "57P03": "SERVER_NOT_READY"
+};
+var REDIS_PREFIXES = {
+  NOAUTH: "AUTH_FAILED",
+  WRONGPASS: "AUTH_FAILED"
+};
+var FALLBACK_PATTERNS = [
+  [/connection refused/i, "ECONNREFUSED"],
+  [/\bECONNREFUSED\b/, "ECONNREFUSED"],
+  [/connect(?:ion)? time(?:d )?out/i, "ETIMEDOUT"],
+  [/timeout exceeded/i, "ETIMEDOUT"],
+  [/timed out/i, "ETIMEDOUT"],
+  [/connection terminated/i, "CONNECTION_LOST"],
+  [/server closed the connection/i, "CONNECTION_LOST"],
+  [/server has gone away/i, "CONNECTION_LOST"],
+  [/lost connection to \S+ server/i, "CONNECTION_LOST"],
+  [/getaddrinfo/i, "ENOTFOUND"],
+  [/authentication failed/i, "AUTH_FAILED"],
+  [/access denied for user/i, "AUTH_FAILED"],
+  [/no pg_hba\.conf entry/i, "AUTH_FAILED"],
+  [/role\s+".*?"\s+does not exist/i, "AUTH_FAILED"],
+  [/password supplied/i, "AUTH_FAILED"]
+];
+var PG_CANCEL_BY_TIMEOUT = /statement timeout/i;
+function categorize(errCode, errno, errMsg, system) {
+  if (errCode) {
+    if (TLS_CODE_PREFIX.test(errCode))
+      return "TLS_ERROR";
+    const known = TRANSPORT_CODES[errCode] ?? MYSQL_CODES[errCode] ?? SQLSTATES[errCode] ?? REDIS_PREFIXES[errCode];
+    if (known === "STATEMENT_TIMEOUT" && errCode === "57014" && !PG_CANCEL_BY_TIMEOUT.test(errMsg)) {
+      return null;
+    }
+    if (known)
+      return known;
+  }
+  const isMysqlFamily = system === "mysql" || system === "mariadb";
+  if (isMysqlFamily && typeof errno === "number" && MYSQL_ERRNOS[errno]) {
+    return MYSQL_ERRNOS[errno];
+  }
+  const redisPrefix = errMsg.match(/^([A-Z]+)\s/)?.[1];
+  if (redisPrefix && REDIS_PREFIXES[redisPrefix])
+    return REDIS_PREFIXES[redisPrefix];
+  if (errCode || isMysqlFamily && typeof errno === "number")
+    return null;
+  for (const [pattern, category] of FALLBACK_PATTERNS) {
+    if (pattern.test(errMsg))
+      return category;
+  }
+  return null;
+}
+var SYSTEM_FACTS = {
+  postgresql: {
+    serviceCheck: "systemctl status postgresql",
+    defaultPort: "default 5432",
+    firewallRule: "allow TCP 5432",
+    client: "psql",
+    logFile: "postgresql.log"
+  },
+  mysql: {
+    serviceCheck: "systemctl status mysql",
+    defaultPort: "default 3306",
+    firewallRule: "allow TCP 3306",
+    client: "mysql",
+    logFile: "mysql.log"
+  },
+  mariadb: {
+    serviceCheck: "systemctl status mariadb",
+    defaultPort: "default 3306",
+    firewallRule: "allow TCP 3306",
+    client: "mariadb",
+    logFile: "mariadb.log"
+  },
+  redis: {
+    serviceCheck: "redis-cli ping",
+    defaultPort: "default 6379",
+    firewallRule: "allow TCP 6379",
+    client: "redis-cli",
+    logFile: "redis.log"
+  }
+};
+function serviceHints(system, options) {
+  const facts = SYSTEM_FACTS[system];
+  return [
+    `Check that the ${system} service is running: ${facts.serviceCheck}`,
+    `Verify the port is correct: ${facts.defaultPort}`,
+    `Check that ${options.host} is reachable: ping ${options.host} or telnet ${options.host} ${options.port}`
+  ];
+}
+function mapError(error, system, options) {
+  if (error instanceof ConnectionError)
+    return error;
+  const err = error;
+  const errMsg = String(err?.message || String(error));
+  const errCode = String(err?.code || "");
+  const errno = err?.errno;
+  switch (categorize(errCode, errno, errMsg, system)) {
+    case "ECONNREFUSED":
+      return new ConnectionError("ECONNREFUSED", `Cannot connect to ${options.host}:${options.port} \u2014 server is not running or not listening on this port`, serviceHints(system, options));
+    case "ETIMEDOUT":
+      return new ConnectionError("ETIMEDOUT", `Connection timed out (${options.timeout || 5000}ms) \u2014 may be blocked by a firewall or slow network`, [
+        `Check firewall rules: ${SYSTEM_FACTS[system].firewallRule}`,
+        `Increase timeout: edit .dbcli and add "timeout": 15000`,
+        `Verify network connectivity: ping ${options.host} -c 3`
+      ]);
+    case "CONNECTION_LOST":
+      return new ConnectionError("CONNECTION_LOST", `Connection to ${options.host}:${options.port} was lost mid-session \u2014 the server closed it or the network dropped`, [
+        "Re-run the command: a dropped connection is often transient",
+        `Check whether the server restarted or is cycling: ${SYSTEM_FACTS[system].logFile}`,
+        "If it happens on long-running work, look at the server idle/wait timeout"
+      ]);
+    case "SERVER_NOT_READY":
+      return new ConnectionError("SERVER_NOT_READY", `${options.host}:${options.port} is not accepting connections yet \u2014 the server is starting up or recovering`, [
+        "Retry shortly: this clears on its own once startup or recovery finishes",
+        `Watch progress in the server log: ${SYSTEM_FACTS[system].logFile}`,
+        "On a replica, this also appears while it catches up with the primary"
+      ]);
+    case "CONNECTION_REJECTED":
+      return new ConnectionError("CONNECTION_REJECTED", `${options.host}:${options.port} answered but rejected the connection attempt`, [
+        "Check the server access rules (pg_hba.conf) for this user, database, and client address",
+        "If a pooler (pgbouncer / ProxySQL) sits in front, check its own rules and limits",
+        "Check whether the connection limit for this user or database is exhausted"
+      ]);
+    case "TOO_MANY_CONNECTIONS":
+      return new ConnectionError("TOO_MANY_CONNECTIONS", `${options.host}:${options.port} refused the connection \u2014 the server has no connection slots left`, [
+        "Wait and retry: the limit is on concurrent connections, not on you",
+        system === "postgresql" ? "Inspect usage: SELECT count(*) FROM pg_stat_activity \u2014 compare against max_connections" : 'Inspect usage: SHOW STATUS LIKE "Threads_connected" \u2014 compare against max_connections',
+        "Close idle sessions, or raise max_connections if the load is legitimate"
+      ]);
+    case "EHOSTUNREACH":
+      return new ConnectionError("EHOSTUNREACH", `No route to ${options.host} \u2014 the name resolved, but the host or network is unreachable`, [
+        "Check that you are on the right network or VPN",
+        `Check routing and firewall between here and ${options.host}`,
+        `Confirm the address is the one you meant: ${options.host}:${options.port}`
+      ]);
+    case "TLS_ERROR":
+      return new ConnectionError("TLS_ERROR", `TLS handshake failed: ${errMsg}`, [
+        'Point the connection at the right CA bundle: set "caPath" in .dbcli',
+        'For a self-signed certificate in a trusted network, set "rejectUnauthorized": false',
+        `Confirm the certificate covers the host you connected to: ${options.host}`
+      ]);
+    case "ENOTFOUND":
+      return new ConnectionError("ENOTFOUND", `Host not found: ${options.host}`, [
+        `Check the hostname spelling: ${options.host}`,
+        `Verify DNS resolution: nslookup ${options.host}`,
+        `If using localhost, try 127.0.0.1 (IPv4 vs IPv6 issue)`
+      ]);
+    case "AUTH_FAILED":
+      return new ConnectionError("AUTH_FAILED", `Authentication failed \u2014 check your username or password`, [
+        `Verify credentials: ${SYSTEM_FACTS[system].client} ${system === "postgresql" ? "-U" : "-u"} ${options.user} -h ${options.host}`,
+        `Check pg_hba.conf (PostgreSQL) or user privileges (MySQL)`,
+        `Re-run dbcli init to update credentials`
+      ]);
+    case "TABLE_NOT_FOUND": {
+      const mysqlMatch = errMsg.match(/Table\s+'(?:[^.']+\.)?([^']+)'/i);
+      const pgMatch = errMsg.match(/relation\s+"([^"]+)"/i);
+      const tableName = mysqlMatch?.[1] || pgMatch?.[1] || "unknown";
+      return new ConnectionError("TABLE_NOT_FOUND", `Table '${tableName}' not found in database '${options.database || "unknown"}'`, [
+        "Run `dbcli list` to see available tables",
+        "Run `dbcli schema <table>` to confirm the exact name (ORM export names may differ from DB table names)"
+      ]);
+    }
+    case "COLUMN_NOT_FOUND": {
+      const mysqlMatch = errMsg.match(/Unknown column\s+'([^']+)'/i);
+      const pgMatch = errMsg.match(/column\s+"([^"]+)"\s+does not exist/i);
+      const columnName = mysqlMatch?.[1] || pgMatch?.[1] || "unknown";
+      return new ConnectionError("COLUMN_NOT_FOUND", `Column '${columnName}' not found`, [
+        "Run `dbcli schema <table>` to see the actual column names",
+        "Column names are case-sensitive on some databases (PostgreSQL with quoted identifiers)"
+      ]);
+    }
+    case "STATEMENT_TIMEOUT": {
+      const limitMs = options.statementTimeout ?? options.timeout;
+      return new ConnectionError("STATEMENT_TIMEOUT", `Statement timed out${limitMs ? ` (${limitMs}ms)` : ""} \u2014 the server canceled this query before it finished`, [
+        'Inspect the query plan: dbcli explain "<sql>"',
+        "Raise the ceiling for this run: dbcli --statement-timeout <ms> \u2026 (0 removes it)",
+        "Narrow the query: add WHERE filters, reduce the LIMIT, or index the scanned columns"
+      ], limitMs);
+    }
+    case "SQL_SYNTAX_ERROR":
+      return new ConnectionError("SQL_SYNTAX_ERROR", `SQL syntax error: ${errMsg}`, [
+        "Check your SQL syntax near the position reported above",
+        "In query-only mode, dbcli auto-appends LIMIT 1000; use --no-limit to disable",
+        "For SHOW/DESCRIBE/EXPLAIN statements, LIMIT is not allowed \u2014 these are not auto-limited"
+      ]);
+  }
+  const reportedCode = errCode || (typeof errno === "number" ? String(errno) : "");
+  if (reportedCode) {
+    return new ConnectionError("UNKNOWN", `Database error (${reportedCode}): ${errMsg}`, [
+      "Run `dbcli schema <table>` to confirm the objects referenced by this statement",
+      `Look up ${reportedCode} in the ${system} error reference for the exact cause`
+    ]);
+  }
+  return new ConnectionError("UNKNOWN", `Connection failed: ${errMsg}`, [
+    `Check connection parameters: host=${options.host}, port=${options.port}, user=${options.user}`,
+    `View server logs: ${SYSTEM_FACTS[system].logFile}`,
+    `Try connecting directly with the ${SYSTEM_FACTS[system].client} command-line tool`
+  ]);
+}
 // resources/lang/en/messages.json
 var messages_default = {
+  cli: {
+    agent_output_option: "Emit one Operation Envelope v1 (capabilities and capabilities check only)"
+  },
   init: {
     description: "Initialize dbcli configuration with .env parsing and interactive prompts",
     welcome: "Welcome to dbcli",
@@ -1155,6 +1587,9 @@ var messages_default = {
     prompt_port: "Database port: ",
     prompt_user: "Database user: ",
     prompt_password: "Database password: ",
+    secret_alternatives_sql: "pass --password, supply the credential through .env or the process environment, or store a reference with --use-env-refs",
+    secret_alternatives_mongo_password: "pass --password, supply the credential through .env or the process environment, or paste the connection string with --uri",
+    secret_alternatives_mongo_uri: "pass the connection string with --uri",
     prompt_name: "Database name: ",
     prompt_permission: "Permission level (query-only, read-write, data-admin, admin): ",
     env_parse_note: "Note: Unable to parse .env configuration, using interactive prompts",
@@ -1310,6 +1745,14 @@ var messages_default = {
   },
   errors: {
     message: "Error: {message}",
+    query_only_boundary_failed: "Could not establish the query-only database boundary for {system}: {detail}",
+    query_only_boundary_verify: "Verify that {system} supports read-only transactions and that this account may start one",
+    query_only_boundary_not_executed: "The target statement was not executed; fix the database setting or connection before retrying",
+    query_only_cleanup_completed: "The query-only target completed, but transaction cleanup failed for {system}: {detail}",
+    query_only_cleanup_uncertain: "The query-only target failed and its outcome is uncertain because transaction cleanup also failed for {system}: {detail}",
+    query_only_cleanup_completed_retry: "The target statement ran; do not retry it unless repeating its external effects is safe",
+    query_only_cleanup_uncertain_retry: "The target may have produced effects before failing; do not retry it unless repeating them is safe",
+    query_only_cleanup_reconnect: "Reconnect before running another statement because this connection was discarded",
     invalid_config: "Invalid configuration: {field}",
     connection_failed: "Failed to connect to database: {message}",
     permission_denied: "Permission denied (required: {required})",
@@ -1463,6 +1906,9 @@ Reference: {referencePath}`,
 };
 // resources/lang/zh-TW/messages.json
 var messages_default2 = {
+  cli: {
+    agent_output_option: "\u8F38\u51FA\u4E00\u4EFD Operation Envelope v1\uFF08\u50C5\u652F\u63F4 capabilities \u8207 capabilities check\uFF09"
+  },
   init: {
     description: "\u521D\u59CB\u5316 dbcli \u914D\u7F6E\uFF0C\u89E3\u6790 .env \u4E26\u9032\u884C\u4E92\u52D5\u5F0F\u63D0\u793A",
     welcome: "\u6B61\u8FCE\u4F7F\u7528 dbcli",
@@ -1471,6 +1917,9 @@ var messages_default2 = {
     prompt_port: "\u8CC7\u6599\u5EAB\u57E0\u865F\uFF1A",
     prompt_user: "\u8CC7\u6599\u5EAB\u4F7F\u7528\u8005\uFF1A",
     prompt_password: "\u8CC7\u6599\u5EAB\u5BC6\u78BC\uFF1A",
+    secret_alternatives_sql: "\u6539\u7528 --password\u3001\u628A\u6191\u8B49\u653E\u9032 .env \u6216\u884C\u7A0B\u74B0\u5883\u8B8A\u6578\uFF0C\u6216\u4EE5 --use-env-refs \u5B58\u6210\u53C3\u7167",
+    secret_alternatives_mongo_password: "\u6539\u7528 --password\u3001\u628A\u6191\u8B49\u653E\u9032 .env \u6216\u884C\u7A0B\u74B0\u5883\u8B8A\u6578\uFF0C\u6216\u4EE5 --uri \u8CBC\u4E0A\u9023\u7DDA\u5B57\u4E32",
+    secret_alternatives_mongo_uri: "\u4EE5 --uri \u50B3\u5165\u9023\u7DDA\u5B57\u4E32",
     prompt_name: "\u8CC7\u6599\u5EAB\u540D\u7A31\uFF1A",
     prompt_permission: "\u6B0A\u9650\u7B49\u7D1A\uFF08query-only, read-write, data-admin, admin\uFF09\uFF1A",
     env_parse_note: "\u63D0\u793A\uFF1A\u7121\u6CD5\u89E3\u6790 .env \u914D\u7F6E\uFF0C\u4F7F\u7528\u4E92\u52D5\u5F0F\u63D0\u793A",
@@ -1626,6 +2075,14 @@ var messages_default2 = {
   },
   errors: {
     message: "\u932F\u8AA4\uFF1A{message}",
+    query_only_boundary_failed: "\u7121\u6CD5\u70BA {system} \u5EFA\u7ACB query-only \u8CC7\u6599\u5EAB\u908A\u754C\uFF1A{detail}",
+    query_only_boundary_verify: "\u8ACB\u78BA\u8A8D {system} \u652F\u63F4\u552F\u8B80\u4EA4\u6613\uFF0C\u4E14\u6B64\u5E33\u865F\u53EF\u4EE5\u555F\u52D5\u4EA4\u6613",
+    query_only_boundary_not_executed: "\u76EE\u6A19\u8A9E\u53E5\u5C1A\u672A\u57F7\u884C\uFF1B\u8ACB\u4FEE\u6B63\u8CC7\u6599\u5EAB\u8A2D\u5B9A\u6216\u9023\u7DDA\u5F8C\u518D\u8A66",
+    query_only_cleanup_completed: "query-only \u76EE\u6A19\u5DF2\u5B8C\u6210\uFF0C\u4F46 {system} \u7684\u4EA4\u6613\u6E05\u7406\u5931\u6557\uFF1A{detail}",
+    query_only_cleanup_uncertain: "query-only \u76EE\u6A19\u5931\u6557\uFF0C\u4E14 {system} \u7684\u4EA4\u6613\u6E05\u7406\u4E5F\u5931\u6557\uFF0C\u56E0\u6B64\u7D50\u679C\u4E0D\u78BA\u5B9A\uFF1A{detail}",
+    query_only_cleanup_completed_retry: "\u76EE\u6A19\u8A9E\u53E5\u5DF2\u57F7\u884C\uFF1B\u9664\u975E\u53EF\u5B89\u5168\u91CD\u8907\u5176\u5916\u90E8\u526F\u4F5C\u7528\uFF0C\u5426\u5247\u4E0D\u8981\u91CD\u8A66",
+    query_only_cleanup_uncertain_retry: "\u76EE\u6A19\u8A9E\u53E5\u53EF\u80FD\u5728\u5931\u6557\u524D\u7522\u751F\u526F\u4F5C\u7528\uFF1B\u9664\u975E\u53EF\u5B89\u5168\u91CD\u8907\u9019\u4E9B\u526F\u4F5C\u7528\uFF0C\u5426\u5247\u4E0D\u8981\u91CD\u8A66",
+    query_only_cleanup_reconnect: "\u6B64\u9023\u7DDA\u5DF2\u4E1F\u68C4\uFF1B\u57F7\u884C\u4E0B\u4E00\u53E5\u524D\u8ACB\u5148\u91CD\u65B0\u9023\u7DDA",
     invalid_config: "\u914D\u7F6E\u7121\u6548\uFF1A{field}",
     connection_failed: "\u7121\u6CD5\u9023\u63A5\u5230\u8CC7\u6599\u5EAB\uFF1A{message}",
     permission_denied: "\u6B0A\u9650\u88AB\u62D2\uFF08\u9700\u8981\uFF1A{required}\uFF09",
@@ -2028,6 +2485,495 @@ var messageLoader = MessageLoader.getInstance();
 var t = (key) => messageLoader.t(key);
 var t_vars = (key, vars) => messageLoader.interpolate(key, vars);
 
+// src/adapters/sql-adapter-utils.ts
+function queryOnlyBoundaryError(system, error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  return new ConnectionError("QUERY_ONLY_BOUNDARY_FAILED", t_vars("errors.query_only_boundary_failed", { system, detail }), [
+    t_vars("errors.query_only_boundary_verify", { system }),
+    t_vars("errors.query_only_boundary_not_executed", {})
+  ]);
+}
+function queryOnlyCleanupError(system, error, targetCompleted) {
+  const detail = error instanceof Error ? error.message : String(error);
+  return new ConnectionError("CONNECTION_LOST", targetCompleted ? t_vars("errors.query_only_cleanup_completed", { system, detail }) : t_vars("errors.query_only_cleanup_uncertain", { system, detail }), [
+    targetCompleted ? t_vars("errors.query_only_cleanup_completed_retry", {}) : t_vars("errors.query_only_cleanup_uncertain_retry", {}),
+    t_vars("errors.query_only_cleanup_reconnect", {})
+  ], undefined, false);
+}
+function requireConnected(connection) {
+  if (!connection) {
+    throw new ConnectionError("UNKNOWN", "Database connection not established", [
+      "Call connect() to establish a connection"
+    ]);
+  }
+  return connection;
+}
+async function withMappedConnectionError(system, options, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    throw mapError(error, system, options);
+  }
+}
+
+// src/utils/colors.ts
+var import_picocolors = __toESM(require_picocolors(), 1);
+var colors = {
+  success: (text) => import_picocolors.default.green(text),
+  error: (text) => import_picocolors.default.red(text),
+  warn: (text) => import_picocolors.default.yellow(text),
+  info: (text) => import_picocolors.default.blue(text),
+  dim: (text) => import_picocolors.default.dim(text),
+  bold: (text) => import_picocolors.default.bold(text),
+  keyword: (text) => import_picocolors.default.blue(import_picocolors.default.bold(text))
+};
+
+// src/utils/db-version-check.ts
+var MIN_SUPPORTED_VERSIONS = {
+  postgresql: "12.0",
+  mysql: "8.0",
+  mariadb: "10.5",
+  elasticsearch: "7.10"
+};
+function parseVersionSegments(version) {
+  const match = version.match(/^(\d+(?:\.\d+)*)/);
+  if (!match)
+    return [];
+  return (match[1] ?? "").split(".").map(Number);
+}
+function isMariaDBVersion(versionString) {
+  return /mariadb/i.test(versionString);
+}
+function extractMariaDBVersion(versionString) {
+  const match = versionString.match(/(\d+\.\d+\.\d+)-MariaDB/i);
+  if (match)
+    return match[1] ?? versionString;
+  const prefixMatch = versionString.match(/^5\.5\.5-(\d+\.\d+\.\d+)/);
+  if (prefixMatch)
+    return prefixMatch[1] ?? versionString;
+  return versionString;
+}
+function compareVersions(a, b) {
+  const segA = parseVersionSegments(a);
+  const segB = parseVersionSegments(b);
+  const len = Math.max(segA.length, segB.length);
+  for (let i = 0;i < len; i++) {
+    const diff = (segA[i] ?? 0) - (segB[i] ?? 0);
+    if (diff !== 0)
+      return diff;
+  }
+  return 0;
+}
+function checkDbVersion(rawVersion, declaredSystem) {
+  const isMariaDB = isMariaDBVersion(rawVersion);
+  const system = isMariaDB ? "mariadb" : declaredSystem;
+  const serverVersion = isMariaDB ? extractMariaDBVersion(rawVersion) : rawVersion;
+  const minVersion = MIN_SUPPORTED_VERSIONS[system];
+  const supported = compareVersions(serverVersion, minVersion ?? "0") >= 0;
+  return {
+    serverVersion,
+    system,
+    supported,
+    minVersion: minVersion ?? "0"
+  };
+}
+function warnIfUnsupported(result) {
+  if (result.supported)
+    return;
+  const message = t_vars("version.unsupported_warning", {
+    system: result.system,
+    version: result.serverVersion,
+    minVersion: result.minVersion
+  });
+  process.stderr.write(colors.warn(`\u26A0 ${message}`) + `
+`);
+}
+
+// src/utils/encoding.ts
+var CP1252_REVERSE = {
+  8364: 128,
+  8218: 130,
+  402: 131,
+  8222: 132,
+  8230: 133,
+  8224: 134,
+  8225: 135,
+  710: 136,
+  8240: 137,
+  352: 138,
+  8249: 139,
+  338: 140,
+  381: 142,
+  8216: 145,
+  8217: 146,
+  8220: 147,
+  8221: 148,
+  8226: 149,
+  8211: 150,
+  8212: 151,
+  732: 152,
+  8482: 153,
+  353: 154,
+  8250: 155,
+  339: 156,
+  382: 158,
+  376: 159
+};
+function fixDoubleEncodedUtf8(str) {
+  if (!str)
+    return str;
+  const bytes = [];
+  for (const char of str) {
+    const code = char.codePointAt(0);
+    if (code < 128) {
+      bytes.push(code);
+    } else if (code <= 255) {
+      bytes.push(code);
+    } else {
+      const cp1252Byte = CP1252_REVERSE[code];
+      if (cp1252Byte !== undefined) {
+        bytes.push(cp1252Byte);
+      } else {
+        return str;
+      }
+    }
+  }
+  try {
+    const decoded = new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(bytes));
+    if (decoded !== str) {
+      return decoded;
+    }
+  } catch {}
+  return str;
+}
+
+// src/adapters/identifier-quote.ts
+function quoteCharFor(dialect) {
+  return dialect === "postgresql" ? '"' : "`";
+}
+function assertQuotable(name, what) {
+  if (name.length === 0) {
+    throw new Error(`${what} must not be empty`);
+  }
+  if (name.includes(String.fromCharCode(0))) {
+    throw new Error(`${what} must not contain a NUL character`);
+  }
+}
+function quoteIdentifier(name, dialect) {
+  assertQuotable(name, "identifier");
+  const q = quoteCharFor(dialect);
+  return `${q}${name.split(q).join(q + q)}${q}`;
+}
+
+// src/adapters/timeout-policy.ts
+var DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+function resolveTimeoutPolicy(options) {
+  return {
+    connectMs: options.timeout ?? DEFAULT_CONNECT_TIMEOUT_MS,
+    statementMs: options.statementTimeout ?? options.timeout
+  };
+}
+function statementTimeoutSql(system, ms) {
+  if (system === "mariadb") {
+    return `SET SESSION max_statement_time = ${ms / 1000}`;
+  }
+  return `SET SESSION max_execution_time = ${Math.round(ms)}`;
+}
+
+// src/utils/connection-error-message.ts
+var IS_TRANSPORT_FAILURE = {
+  ECONNREFUSED: true,
+  ETIMEDOUT: true,
+  AUTH_FAILED: true,
+  ENOTFOUND: true,
+  EHOSTUNREACH: true,
+  CONNECTION_LOST: true,
+  TOO_MANY_CONNECTIONS: true,
+  TLS_ERROR: true,
+  SERVER_NOT_READY: true,
+  CONNECTION_REJECTED: true,
+  STATEMENT_TIMEOUT: false,
+  SQL_SYNTAX_ERROR: false,
+  TABLE_NOT_FOUND: false,
+  COLUMN_NOT_FOUND: false,
+  QUERY_ONLY_BOUNDARY_FAILED: false,
+  UNKNOWN: false
+};
+function isTransportFailure(error) {
+  if (error instanceof ConnectionError)
+    return IS_TRANSPORT_FAILURE[error.code];
+  const raw = error?.code;
+  return typeof raw === "string" && isTransportDriverCode(raw);
+}
+
+// src/adapters/mysql-adapter.ts
+function parseEnumValues(columnType) {
+  const match = columnType.match(/^enum\((.+)\)$/i);
+  if (!match)
+    return;
+  return (match[1] ?? "").split(",").map((v) => v.trim().replace(/^'|'$/g, ""));
+}
+
+class MySQLAdapter {
+  db = null;
+  executionTail = Promise.resolve();
+  options;
+  system;
+  constructor(options) {
+    this.options = options;
+    this.system = options.system === "mariadb" ? "mariadb" : "mysql";
+    if (options.port < 1 || options.port > 65535) {
+      throw new Error(`Invalid port number: ${options.port}`);
+    }
+  }
+  async connect() {
+    await withMappedConnectionError(this.system, this.options, async () => {
+      const timeouts = resolveTimeoutPolicy(this.options);
+      const { default: driver } = await import("mysql2/promise");
+      this.db = await driver.createConnection({
+        host: this.options.host,
+        port: this.options.port,
+        user: this.options.user,
+        password: this.options.password || undefined,
+        database: this.options.database,
+        charset: "utf8mb4",
+        connectTimeout: timeouts.connectMs
+      });
+      await this.db.execute("SET NAMES utf8mb4");
+      if (timeouts.statementMs !== undefined) {
+        try {
+          await this.db.query(statementTimeoutSql(this.system, timeouts.statementMs));
+        } catch {}
+      }
+      await this.testConnection();
+      try {
+        const rawVersion = await this.getServerVersion();
+        const result = checkDbVersion(rawVersion, this.system);
+        warnIfUnsupported(result);
+      } catch {}
+    });
+  }
+  async disconnect() {
+    try {
+      if (this.db) {
+        await this.db.end();
+        this.db = null;
+      }
+    } catch {}
+  }
+  async testConnection() {
+    requireConnected(this.db);
+    return withMappedConnectionError(this.system, this.options, async () => {
+      const result = await this.execute("SELECT 1 as count");
+      return result.rows.length > 0;
+    });
+  }
+  async execute(sql, params, options) {
+    const db = requireConnected(this.db);
+    return withMappedConnectionError(this.system, this.options, async () => {
+      const execution = this.executionTail.then(async () => {
+        if (options?.sqlMode === "native-read-only") {
+          return this.executeReadOnly(db, sql, params);
+        }
+        const [result] = params ? await db.execute(sql, params) : await db.execute(sql);
+        if (Array.isArray(result)) {
+          return {
+            rows: result,
+            affectedRows: result.length
+          };
+        }
+        const header = result;
+        return {
+          rows: [],
+          affectedRows: header.affectedRows || 0,
+          lastInsertId: header.insertId
+        };
+      });
+      this.executionTail = execution.then(() => {
+        return;
+      }, () => {
+        return;
+      });
+      return execution;
+    });
+  }
+  async executeReadOnly(db, sql, params) {
+    let primaryError;
+    let cleanupError;
+    let executionResult;
+    let transactionStarted = false;
+    try {
+      try {
+        await db.query("START TRANSACTION READ ONLY");
+        transactionStarted = true;
+      } catch (error) {
+        const mapped = mapError(error, this.system, this.options);
+        if (isTransportFailure(mapped))
+          throw mapped;
+        throw queryOnlyBoundaryError(this.system, error);
+      }
+      const [result] = params ? await db.execute(sql, params) : await db.execute(sql);
+      if (Array.isArray(result)) {
+        executionResult = { rows: result, affectedRows: result.length };
+      } else {
+        const header = result;
+        executionResult = {
+          rows: [],
+          affectedRows: header.affectedRows || 0,
+          lastInsertId: header.insertId
+        };
+      }
+    } catch (error) {
+      primaryError = error;
+    } finally {
+      if (transactionStarted) {
+        try {
+          await db.query("ROLLBACK");
+        } catch (error) {
+          db.destroy();
+          this.db = null;
+          cleanupError = error;
+        }
+      }
+    }
+    if (cleanupError !== undefined) {
+      throw queryOnlyCleanupError(this.system, cleanupError, primaryError === undefined);
+    }
+    if (primaryError !== undefined)
+      throw primaryError;
+    return executionResult;
+  }
+  async getServerVersion() {
+    const result = await this.execute("SELECT VERSION() as version");
+    return result.rows[0]?.version ?? "unknown";
+  }
+  async listTables() {
+    requireConnected(this.db);
+    return withMappedConnectionError(this.system, this.options, async () => {
+      const query = `
+        SELECT
+          t.TABLE_NAME as table_name,
+          t.TABLE_ROWS as row_count,
+          t.ENGINE as engine,
+          t.TABLE_TYPE as table_type,
+          COUNT(c.COLUMN_NAME) as column_count
+        FROM information_schema.TABLES t
+        LEFT JOIN information_schema.COLUMNS c
+          ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME
+        WHERE t.TABLE_SCHEMA = DATABASE()
+        GROUP BY t.TABLE_NAME, t.TABLE_ROWS, t.ENGINE, t.TABLE_TYPE
+        ORDER BY t.TABLE_NAME
+      `;
+      const result = await this.execute(query);
+      return result.rows.map((row) => ({
+        name: row.table_name,
+        columns: [],
+        columnCount: row.column_count,
+        rowCount: row.row_count || 0,
+        engine: row.engine,
+        estimatedRowCount: row.row_count || 0,
+        tableType: row.table_type === "VIEW" ? "view" : "table"
+      }));
+    });
+  }
+  async getTableSchema(tableName, options) {
+    requireConnected(this.db);
+    return withMappedConnectionError(this.system, this.options, async () => {
+      const columnQuery = `
+        SELECT
+          COLUMN_NAME as name,
+          COLUMN_TYPE as type,
+          IS_NULLABLE = 'YES' as nullable,
+          COLUMN_DEFAULT as default_value,
+          COLUMN_KEY = 'PRI' as is_primary_key,
+          EXTRA LIKE '%auto_increment%' as auto_increment,
+          COLUMN_COMMENT as comment
+        FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = DATABASE()
+          AND TABLE_NAME = ?
+        ORDER BY ORDINAL_POSITION
+      `;
+      const columnResult = await this.execute(columnQuery, [tableName]);
+      const columns = columnResult.rows;
+      const fkQuery = `
+        SELECT
+          rc.CONSTRAINT_NAME as name,
+          GROUP_CONCAT(kcu.COLUMN_NAME) as columns,
+          rc.REFERENCED_TABLE_NAME as ref_table,
+          GROUP_CONCAT(kcu.REFERENCED_COLUMN_NAME) as ref_columns
+        FROM information_schema.REFERENTIAL_CONSTRAINTS rc
+        JOIN information_schema.KEY_COLUMN_USAGE kcu
+          ON rc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME AND rc.TABLE_NAME = kcu.TABLE_NAME
+        WHERE kcu.TABLE_NAME = ? AND rc.CONSTRAINT_SCHEMA = DATABASE()
+        GROUP BY rc.CONSTRAINT_NAME, rc.REFERENCED_TABLE_NAME
+      `;
+      const fkResult = await this.execute(fkQuery, [tableName]);
+      const fkResults = fkResult.rows;
+      const fkMap = new Map;
+      for (const fk of fkResults) {
+        const cols = fk.columns.split(",").map((c) => c.trim());
+        const refCols = fk.ref_columns.split(",").map((c) => c.trim());
+        if (cols.length === 1 && refCols.length === 1) {
+          fkMap.set(cols[0], { table: fk.ref_table, column: refCols[0] });
+        }
+      }
+      const primaryKeyColumns = columns.filter((col) => col.is_primary_key).map((col) => col.name);
+      const indexQuery = `
+        SELECT
+          INDEX_NAME as name,
+          GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) as columns,
+          NOT NON_UNIQUE as is_unique
+        FROM information_schema.STATISTICS
+        WHERE TABLE_SCHEMA = DATABASE()
+          AND TABLE_NAME = ?
+          AND INDEX_NAME != 'PRIMARY'
+        GROUP BY INDEX_NAME, NON_UNIQUE
+      `;
+      const indexResult = await this.execute(indexQuery, [tableName]);
+      const indexResults = indexResult.rows;
+      const tableMetaQuery = `
+        SELECT ENGINE as engine, TABLE_ROWS as estimated_rows
+        FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?
+      `;
+      const tableMetaResult = await this.execute(tableMetaQuery, [tableName]);
+      const tableMeta = tableMetaResult.rows[0];
+      const estimatedRowCount = Math.max(0, tableMeta?.estimated_rows || 0);
+      const exactRowCount = options?.exactRowCount === false ? undefined : (await this.execute(`SELECT COUNT(*) as count FROM ${quoteIdentifier(tableName, this.system)}`)).rows[0]?.count;
+      const schema = {
+        name: tableName,
+        columns: columns.map((col) => ({
+          name: col.name,
+          type: col.type,
+          nullable: col.nullable,
+          default: col.default_value || undefined,
+          primaryKey: col.is_primary_key,
+          foreignKey: fkMap.get(col.name),
+          autoIncrement: col.auto_increment,
+          comment: col.comment ? fixDoubleEncodedUtf8(col.comment) : null,
+          enumValues: parseEnumValues(col.type)
+        })),
+        rowCount: exactRowCount ?? estimatedRowCount,
+        engine: tableMeta?.engine || "MySQL",
+        primaryKey: primaryKeyColumns,
+        foreignKeys: fkResults.map((fk) => ({
+          name: fk.name,
+          columns: fk.columns.split(",").map((c) => c.trim()),
+          refTable: fk.ref_table,
+          refColumns: fk.ref_columns.split(",").map((c) => c.trim())
+        })),
+        indexes: indexResults.map((idx) => ({
+          name: idx.name,
+          columns: idx.columns.split(",").map((c) => c.trim()),
+          unique: idx.is_unique
+        })),
+        estimatedRowCount
+      };
+      return schema;
+    });
+  }
+}
+
 // src/utils/case-fold.ts
 function foldCase(text) {
   const lowered = (text.includes("\u0130") ? text.replaceAll("\u0130", "i") : text).toLowerCase();
@@ -3177,6 +4123,17 @@ function removeParameterMarkers(sql) {
   return sql.replace(/\$\d+/g, "").replace(/\?/g, "");
 }
 
+// src/core/permission/rank.ts
+var PERMISSION_RANK = Object.freeze({
+  "query-only": 1,
+  "read-write": 2,
+  "data-admin": 3,
+  admin: 4
+});
+function permissionAtLeast(actual, required) {
+  return PERMISSION_RANK[actual] >= PERMISSION_RANK[required];
+}
+
 // src/core/permission-guard.ts
 class PermissionError extends Error {
   classification;
@@ -4172,7 +5129,9 @@ class QueryExecutor {
       if (this.blacklistValidator && referencedTables.length > 0) {
         this.blacklistValidator.checkTablesBlacklist(classification.type, referencedTables);
       }
-      const resultData = await this.adapter.execute(executeSql);
+      const resultData = await this.adapter.execute(executeSql, undefined, {
+        sqlMode: this.permission === "query-only" ? "native-read-only" : "normal"
+      });
       const executionTimeMs = Math.round(performance.now() - start);
       const limitedResult = appliedLimit === undefined ? undefined : trimAppliedLimit(resultData.rows, appliedLimit);
       const rows = limitedResult?.rows ?? resultData.rows;
@@ -9590,6 +10549,1106 @@ DBCLI_PASSWORD=${password}
     }
   }
 };
+// src/core/capabilities/types.ts
+var CAPABILITY_CONTRACT_SCHEMA_VERSION = 1;
+// src/core/capabilities/registry.ts
+var DECLARATIONS = [
+  {
+    id: "connection.init",
+    key: "init",
+    command: "init",
+    description: "Create or update a local connection configuration interactively.",
+    permission: "query-only",
+    requiresConnection: true,
+    mutatesConfiguration: true
+  },
+  {
+    id: "connection.select",
+    key: "use",
+    command: "use",
+    description: "Switch the default named connection in a v2 configuration.",
+    permission: "query-only",
+    requiresConnection: false,
+    mutatesConfiguration: true
+  },
+  {
+    id: "connection.status",
+    key: "status",
+    command: "status",
+    description: "Report the configured engine, permission and blacklist counts without credentials.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "connection.diagnose",
+    key: "doctor",
+    command: "doctor",
+    description: "Run engine-specific connectivity and configuration diagnostics.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "schema.list-tables",
+    key: "list",
+    command: "list",
+    description: "List the tables, collections or indices visible to the connection.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "schema.read",
+    key: "schema",
+    command: "schema",
+    description: "Read visible schema metadata for one object or the whole database.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "schema.read-object",
+    key: "schemaSingle",
+    command: "schema",
+    description: "Read the column or field structure of a single named object.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "schema.scan",
+    key: "schemaFullScan",
+    command: "schema",
+    description: "Scan every visible object and refresh the local schema cache.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "schema.diff",
+    key: "diff",
+    command: "diff",
+    description: "Compare schema snapshots and report structural differences.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "schema.migrate",
+    key: "migrate",
+    command: "migrate",
+    description: "Apply guarded DDL changes such as columns, indexes and constraints.",
+    statementType: "ALTER",
+    requiresConnection: true
+  },
+  {
+    id: "query.read",
+    key: "query",
+    command: "query",
+    description: "Run a read query through the permission, blacklist and audit gates.",
+    statementType: "SELECT",
+    requiresConnection: true
+  },
+  {
+    id: "query.lint",
+    key: "lint",
+    command: "lint",
+    description: "Statically analyse SQL without connecting to the database.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "query.format",
+    key: "queryOutput",
+    command: "query",
+    description: "Render query results as a table, JSON or CSV.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "query.limit-guard",
+    key: "queryLimitGuard",
+    command: "query",
+    description: "Bound result size automatically and report the limit that was applied.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "query.shell",
+    key: "shell",
+    command: "shell",
+    description: "Open an interactive gated query shell.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "snippet.run",
+    key: "q",
+    command: "q",
+    description: "Execute a saved read-only query snippet with parameters.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "snippet.manage",
+    key: "queries",
+    command: "queries",
+    description: "Create, edit, search and validate saved query snippets.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "data.insert",
+    key: "insert",
+    command: "insert",
+    description: "Insert rows or documents through the write gate.",
+    statementType: "INSERT",
+    requiresConnection: true
+  },
+  {
+    id: "data.update",
+    key: "update",
+    command: "update",
+    description: "Update rows or documents through the write gate.",
+    statementType: "UPDATE",
+    requiresConnection: true
+  },
+  {
+    id: "data.delete",
+    key: "delete",
+    command: "delete",
+    description: "Delete rows or documents through the write gate.",
+    statementType: "DELETE",
+    requiresConnection: true
+  },
+  {
+    id: "data.export",
+    key: "export",
+    command: "export",
+    description: "Export query or object contents to a file, subject to the blacklist.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "data.health-check",
+    key: "check",
+    command: "check",
+    description: "Check data health: nulls, orphans, duplicates and empty strings.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "blacklist.manage",
+    key: "blacklist",
+    command: "blacklist",
+    description: "Inspect and edit the table, column and key rules that hide sensitive data.",
+    permission: "query-only",
+    requiresConnection: false,
+    mutatesConfiguration: true
+  },
+  {
+    id: "context.inspect",
+    key: "inspect",
+    command: "inspect",
+    description: "Produce a bounded agent context snapshot of the configured database.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "diagnostic.report",
+    key: "report",
+    command: "report",
+    description: "Produce a diagnostic report about the configured database.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "guide.plan",
+    key: "guide",
+    command: "guide",
+    description: "Suggest the next deterministic command for a stated goal.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "recovery.plan",
+    key: "recover",
+    command: "recover",
+    description: "Read the saved recovery envelope and plan or apply safe remediation steps.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "audit.tail",
+    key: "auditTail",
+    command: "audit tail",
+    description: "Read recent audit entries from the local log.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "audit.show",
+    key: "auditShow",
+    command: "audit show",
+    description: "Look up one audit entry by id prefix or recovery reference.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "audit.health",
+    key: "auditHealth",
+    command: "audit health",
+    description: "Report audit log health and rotation state.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "audit.clear",
+    key: "auditClear",
+    command: "audit clear",
+    description: "Remove the local audit log files for a connection.",
+    permission: "admin",
+    requiresConnection: false
+  },
+  {
+    id: "skill.install",
+    key: "skill",
+    command: "skill",
+    description: "Write the dbcli skill and task-pack assets into a platform directory.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "shell-completion.generate",
+    key: "completion",
+    command: "completion",
+    description: "Emit a shell completion script for the current command tree.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "package.upgrade-check",
+    key: "upgrade",
+    command: "upgrade",
+    description: "Check whether a newer dbcli release is available.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "query.explain",
+    key: "explain",
+    command: "explain",
+    description: "Read the engine execution plan for a statement without running it as a write.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "query.plan-risk",
+    key: "plan",
+    command: "plan",
+    description: "Assess the write risk of a statement offline, against the cached schema.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "schema.impact-assess",
+    key: "impactAssess",
+    command: "impact assess",
+    description: "Assess the known effects of a proposed schema change offline.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "data.assert",
+    key: "assert",
+    command: "assert",
+    description: "Check a data expectation and report a pass or fail verdict.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "data.snapshot",
+    key: "snapshot",
+    command: "snapshot",
+    description: "Capture a result fingerprint for later comparison.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "verification.run",
+    key: "verify",
+    command: "verify",
+    description: "Verify a named change scenario and record the outcome.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "verification.inspect",
+    key: "verification",
+    command: "verification",
+    description: "Inspect locally stored verification artifacts.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "verification.prune",
+    key: "verificationPrune",
+    command: "verification prune",
+    description: "Delete locally stored verification artifacts by age or subject.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "evidence.pack",
+    key: "evidence",
+    command: "evidence",
+    description: "Compose, validate and render an evidence pack from local artifacts.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "semantic.context",
+    key: "semantic",
+    command: "semantic",
+    description: "Author and validate governed semantic context over the cached schema.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "semantic.contract",
+    key: "contract",
+    command: "contract",
+    description: "Validate and search governed business contracts offline.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "schema.design",
+    key: "design",
+    command: "design",
+    description: "Author a schema design and compare it against the database or an ORM.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "diagnostic.proxy",
+    key: "proxy",
+    command: "proxy",
+    description: "Run a local observing proxy in front of a supported SQL engine.",
+    permission: "query-only",
+    requiresConnection: true
+  },
+  {
+    id: "diagnostic.proxy-analyze",
+    key: "proxyAnalyze",
+    command: "proxy analyze",
+    description: "Analyse locally recorded proxy events without contacting an engine.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "recovery.codes",
+    key: "recovery",
+    command: "recovery",
+    description: "Describe a recovery code and its remediation steps.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "data.backfill-artifact",
+    key: "backfillArtifact",
+    command: "backfill artifact",
+    description: "Build a backfill artifact from a source manifest and a connection identity.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "connection.rotate-credential",
+    key: "password",
+    command: "password",
+    description: "Change the stored credential for a single connection.",
+    permission: "query-only",
+    requiresConnection: true,
+    mutatesConfiguration: true
+  },
+  {
+    id: "capability.discover",
+    key: "capabilityDiscover",
+    command: "capabilities",
+    description: "List the static capability catalog this build publishes.",
+    permission: "query-only",
+    requiresConnection: false
+  },
+  {
+    id: "capability.check",
+    key: "capabilityCheck",
+    command: "capabilities check",
+    description: "Check whether required capability ids are available in this project.",
+    permission: "query-only",
+    requiresConnection: false
+  }
+];
+function riskForSideEffect(tier) {
+  switch (tier) {
+    case "readonly":
+    case "none":
+      return "readonly";
+    case "dry-run":
+      return "dry-run";
+    case "local-write":
+    case "db-write":
+    case "interactive":
+      return "write";
+    default:
+      return "unknown";
+  }
+}
+function enginesFor(key) {
+  const statuses = DATABASE_SYSTEMS.map((system) => ({
+    system,
+    status: ENGINE_CAPABILITIES[system][key].status
+  }));
+  if (statuses.every((entry) => entry.status === "not-applicable")) {
+    return { engines: [...DATABASE_SYSTEMS], limitedEngines: [], engineIndependent: true };
+  }
+  return {
+    engines: statuses.filter((entry) => entry.status === "supported" || entry.status === "limited").map((entry) => entry.system),
+    limitedEngines: statuses.filter((entry) => entry.status === "limited").map((entry) => entry.system),
+    engineIndependent: false
+  };
+}
+var TIER_SEVERITY = Object.freeze({
+  none: 0,
+  readonly: 1,
+  "dry-run": 2,
+  "local-write": 3,
+  interactive: 4,
+  "db-write": 5
+});
+function sideEffectFor(key, engines) {
+  const considered = engines.length > 0 ? engines : DATABASE_SYSTEMS;
+  let worst = "none";
+  for (const system of considered) {
+    const tier = ENGINE_CAPABILITIES[system][key].tier;
+    if (TIER_SEVERITY[tier] > TIER_SEVERITY[worst])
+      worst = tier;
+  }
+  return worst;
+}
+var COMMAND_SURFACE = Object.freeze({
+  jsonCommands: Object.freeze(new Set([
+    "use",
+    "status",
+    "doctor",
+    "list",
+    "schema",
+    "diff",
+    "query",
+    "lint",
+    "q",
+    "insert",
+    "update",
+    "delete",
+    "export",
+    "check",
+    "inspect",
+    "report",
+    "guide",
+    "recover",
+    "audit tail",
+    "audit show",
+    "audit health",
+    "explain",
+    "plan",
+    "impact assess",
+    "assert",
+    "snapshot",
+    "verification prune",
+    "proxy",
+    "proxy analyze",
+    "recovery",
+    "password",
+    "capabilities",
+    "capabilities check"
+  ])),
+  evidenceCommands: Object.freeze(new Set([
+    "assert",
+    "insert",
+    "update",
+    "delete",
+    "verify",
+    "recover",
+    "evidence",
+    "inspect",
+    "report",
+    "schema",
+    "plan",
+    "lint",
+    "explain",
+    "impact assess"
+  ]))
+});
+function minimumPermissionOf(declaration) {
+  if (declaration.statementType)
+    return minimumPermissionFor(declaration.statementType);
+  if (declaration.permission)
+    return declaration.permission;
+  throw new Error(`capability ${declaration.id} declares neither statementType nor permission`);
+}
+function build(declaration, surface) {
+  const { engines, limitedEngines, engineIndependent } = enginesFor(declaration.key);
+  const sideEffect = sideEffectFor(declaration.key, engines);
+  return Object.freeze({
+    id: declaration.id,
+    description: declaration.description,
+    command: declaration.command,
+    risk: riskForSideEffect(sideEffect),
+    sideEffect,
+    engines: Object.freeze([...engines]),
+    limitedEngines: Object.freeze([...limitedEngines]),
+    engineIndependent,
+    minimumPermission: minimumPermissionOf(declaration),
+    requiresConnection: declaration.requiresConnection,
+    mutatesConfiguration: declaration.mutatesConfiguration ?? false,
+    supportsJson: surface.jsonCommands.has(declaration.command),
+    supportsEvidence: surface.evidenceCommands.has(declaration.command)
+  });
+}
+var CAPABILITIES = Object.freeze(DECLARATIONS.map((declaration) => build(declaration, COMMAND_SURFACE)).sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+var BY_ID = new Map(CAPABILITIES.map((capability) => [capability.id, capability]));
+function findCapability(id) {
+  return BY_ID.get(id);
+}
+function listCapabilityIds() {
+  return CAPABILITIES.map((capability) => capability.id);
+}
+function buildCapabilityCatalog() {
+  return { schemaVersion: CAPABILITY_CONTRACT_SCHEMA_VERSION, capabilities: CAPABILITIES };
+}
+var DECLARED_CAPABILITY_KEYS = Object.freeze(COMMAND_CAPABILITY_KEYS);
+// src/core/capabilities/check.ts
+class CapabilityRequirementError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CapabilityRequirementError";
+    Object.setPrototypeOf(this, CapabilityRequirementError.prototype);
+  }
+}
+function parseRequirements(raw) {
+  const parts = raw.split(",").map((part) => part.trim());
+  if (parts.some((part) => part === "")) {
+    throw new CapabilityRequirementError('--require contains an empty capability id; give a comma-separated list such as "schema.read,query.read"');
+  }
+  const ids = [];
+  const duplicates = [];
+  for (const part of parts) {
+    if (ids.includes(part)) {
+      if (!duplicates.includes(part))
+        duplicates.push(part);
+      continue;
+    }
+    ids.push(part);
+  }
+  return {
+    ids,
+    warnings: duplicates.map((id) => `Duplicate capability id '${id}' in --require was ignored.`)
+  };
+}
+function evaluate(id, context, failure) {
+  const capability = findCapability(id);
+  if (!capability)
+    return { id, status: "unknown", reason: "unknown-capability" };
+  if (!context) {
+    return {
+      id,
+      status: "unavailable",
+      reason: failure === "absent" ? "context-unavailable" : "context-unresolvable"
+    };
+  }
+  if (!capability.engineIndependent && !capability.engines.includes(context.engine)) {
+    return { id, status: "unavailable", reason: "engine" };
+  }
+  if (context.agentMode && capability.mutatesConfiguration) {
+    return { id, status: "unavailable", reason: "agent-mode" };
+  }
+  if (!permissionAtLeast(context.permission, capability.minimumPermission)) {
+    return { id, status: "unavailable", reason: "permission" };
+  }
+  return { id, status: "available", reason: null };
+}
+function checkCapabilities(required, context, warnings = [], contextFailure = "absent") {
+  const results = required.map((id) => evaluate(id, context, contextFailure));
+  const allWarnings = [...warnings];
+  if (!context) {
+    allWarnings.push(contextFailure === "absent" ? "No dbcli configuration was found here, so engine and permission could not be evaluated." : "A dbcli configuration exists here but could not be resolved into an engine and a permission, so nothing was evaluated against it.");
+  } else if (context.agentMode) {
+    allWarnings.push("Agent mode is active (DBCLI_AGENT_MODE=1): configuration, permission and credential changes are refused regardless of permission level.");
+  }
+  return {
+    schemaVersion: CAPABILITY_CONTRACT_SCHEMA_VERSION,
+    ok: results.every((result) => result.status === "available"),
+    required: [...required],
+    context,
+    results,
+    warnings: allWarnings
+  };
+}
+// src/core/capabilities/schema.ts
+class CapabilityContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CapabilityContractError";
+    Object.setPrototypeOf(this, CapabilityContractError.prototype);
+  }
+}
+var PermissionSchema2 = exports_external.enum(["query-only", "read-write", "data-admin", "admin"]);
+var EngineSchema = exports_external.enum(DATABASE_SYSTEMS);
+var RiskSchema = exports_external.enum(["readonly", "dry-run", "write", "unknown"]);
+var SideEffectSchema = exports_external.enum([
+  "readonly",
+  "dry-run",
+  "local-write",
+  "db-write",
+  "interactive",
+  "none"
+]);
+var CAPABILITY_ID_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+var CapabilityIdSchema = exports_external.string().regex(CAPABILITY_ID_PATTERN, {
+  message: "capability id must be dotted lower-case segments, e.g. schema.read"
+});
+var CAPABILITY_COMMAND_PATTERN = /^[a-z][a-z0-9]*(?: [a-z][a-z0-9]*)*$/;
+var CapabilityCommandSchema = exports_external.string().regex(CAPABILITY_COMMAND_PATTERN, {
+  message: "capability command must be space-separated lower-case CLI command segments"
+});
+var CapabilitySchema = exports_external.object({
+  id: CapabilityIdSchema,
+  description: exports_external.string().min(1),
+  command: CapabilityCommandSchema,
+  risk: RiskSchema,
+  sideEffect: SideEffectSchema,
+  engines: exports_external.array(EngineSchema),
+  limitedEngines: exports_external.array(EngineSchema),
+  engineIndependent: exports_external.boolean(),
+  minimumPermission: PermissionSchema2,
+  requiresConnection: exports_external.boolean(),
+  mutatesConfiguration: exports_external.boolean(),
+  supportsJson: exports_external.boolean(),
+  supportsEvidence: exports_external.boolean()
+}).strict();
+var CapabilityCatalogSchema = exports_external.object({
+  schemaVersion: exports_external.literal(CAPABILITY_CONTRACT_SCHEMA_VERSION),
+  capabilities: exports_external.array(CapabilitySchema)
+}).strict();
+var CheckContextSchema = exports_external.object({
+  engine: EngineSchema,
+  permission: PermissionSchema2,
+  connectionName: exports_external.string().max(200).nullable(),
+  agentMode: exports_external.boolean()
+}).strict();
+var CheckResultSchema = exports_external.object({
+  id: exports_external.string().min(1),
+  status: exports_external.enum(["available", "unavailable", "unknown"]),
+  reason: exports_external.enum([
+    "unknown-capability",
+    "context-unavailable",
+    "context-unresolvable",
+    "engine",
+    "agent-mode",
+    "permission"
+  ]).nullable()
+}).strict();
+var CapabilityCheckReportSchema = exports_external.object({
+  schemaVersion: exports_external.literal(CAPABILITY_CONTRACT_SCHEMA_VERSION),
+  ok: exports_external.boolean(),
+  required: exports_external.array(exports_external.string().min(1)),
+  context: CheckContextSchema.nullable(),
+  results: exports_external.array(CheckResultSchema),
+  warnings: exports_external.array(exports_external.string())
+}).strict();
+function parse(schema, value, what) {
+  const result = schema.safeParse(value);
+  if (result.success)
+    return result.data;
+  throw new CapabilityContractError(`${what} does not match capability contract v${CAPABILITY_CONTRACT_SCHEMA_VERSION}: ${result.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ")}`);
+}
+function parseCapabilityCatalog(value) {
+  return parse(CapabilityCatalogSchema, value, "capability catalog");
+}
+function parseCapabilityCheckReport(value) {
+  return parse(CapabilityCheckReportSchema, value, "capability check report");
+}
+// src/core/recovery/types.ts
+var RECOVERY_CODES = [
+  "CONFIG_MISSING",
+  "CONN_REFUSED",
+  "CONN_AUTH_FAILED",
+  "CONN_TIMEOUT",
+  "CONN_HOST_NOT_FOUND",
+  "CONN_UNKNOWN",
+  "PERMISSION_DENIED",
+  "BLACKLIST_TABLE",
+  "BLACKLIST_COLUMN_WRITE",
+  "SNIPPET_NOT_FOUND",
+  "SNIPPET_AMBIGUOUS",
+  "SNIPPET_PARAM_MISSING",
+  "SCHEMA_CACHE_MISSING",
+  "UNKNOWN"
+];
+var MAX_BRANCH_STEPS = 6;
+var MAX_BRANCH_COUNT = 8;
+
+// src/core/recovery/envelope-schema.ts
+var recoveryCodeSchema = exports_external.enum(RECOVERY_CODES);
+var recoveryCategorySchema = exports_external.enum([
+  "config",
+  "connection",
+  "permission",
+  "blacklist",
+  "snippet",
+  "schema-cache",
+  "unknown"
+]);
+var guideRiskSchema = exports_external.enum(["readonly", "dry-run", "write", "unknown"]);
+var branchIdSchema = exports_external.string().min(1).max(64).regex(/^[a-z0-9-]+$/, "branchId must match /^[a-z0-9-]+$/");
+var guideStepSchema = exports_external.object({
+  order: exports_external.number().int(),
+  command: exports_external.string().min(1),
+  rationale: exports_external.string(),
+  risk: guideRiskSchema,
+  expects: exports_external.string(),
+  snippet: exports_external.string().optional(),
+  intent: exports_external.string().optional(),
+  interactive: exports_external.boolean().optional(),
+  dbWrite: exports_external.boolean().optional(),
+  placeholders: exports_external.array(exports_external.string()).optional(),
+  branchId: branchIdSchema.optional()
+}).strict();
+var branchPlanSchema = exports_external.object({
+  description: exports_external.string().min(1),
+  steps: exports_external.array(guideStepSchema).min(1).max(MAX_BRANCH_STEPS)
+}).strict();
+var branchesSchema = exports_external.record(branchIdSchema, branchPlanSchema).superRefine((map, ctx) => {
+  const keys = Object.keys(map);
+  if (keys.length > MAX_BRANCH_COUNT) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: `branches has ${keys.length} entries; cap is ${MAX_BRANCH_COUNT}`
+    });
+  }
+  for (const [id, plan] of Object.entries(map)) {
+    for (const step of plan.steps) {
+      if (step.branchId !== undefined && step.branchId !== id) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: `step.branchId '${step.branchId}' does not match enclosing key '${id}'`
+        });
+      }
+    }
+  }
+});
+var branchForkSchema = exports_external.object({
+  after: exports_external.number().int().min(1),
+  branchIds: exports_external.array(branchIdSchema).min(1)
+}).strict();
+var recoveryEnvelopeSchema = exports_external.object({
+  schemaVersion: exports_external.literal(1),
+  generatedAt: exports_external.string().min(1),
+  ok: exports_external.literal(false),
+  error: exports_external.object({
+    code: recoveryCodeSchema,
+    category: recoveryCategorySchema,
+    message: exports_external.string(),
+    details: exports_external.object({
+      table: exports_external.string().optional(),
+      columns: exports_external.string().optional(),
+      requiredPermission: exports_external.string().optional(),
+      connectionCode: exports_external.string().optional(),
+      snippet: exports_external.string().optional(),
+      intent: exports_external.string().optional(),
+      paramName: exports_external.string().optional()
+    }).strict().optional()
+  }).strict(),
+  recovery: exports_external.array(guideStepSchema),
+  verify: guideStepSchema.optional(),
+  branches: branchesSchema.optional(),
+  branchFork: branchForkSchema.optional()
+}).strict().superRefine((env, ctx) => {
+  const hasBranches = env.branches !== undefined;
+  const hasFork = env.branchFork !== undefined;
+  if (hasBranches !== hasFork) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "branches and branchFork must be set together (or both omitted)"
+    });
+    return;
+  }
+  if (hasBranches && hasFork) {
+    const keys = Object.keys(env.branches).sort();
+    const ids = [...env.branchFork.branchIds].sort();
+    if (keys.length !== ids.length || keys.some((k, i) => k !== ids[i])) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        message: "branchFork.branchIds must equal Object.keys(branches)"
+      });
+    }
+  }
+});
+var savedRecoveryEnvelopeSchema = exports_external.object({
+  schemaVersion: exports_external.literal(1),
+  id: exports_external.string().optional(),
+  audit_ref: exports_external.string().optional(),
+  savedAt: exports_external.string().min(1),
+  command: exports_external.string(),
+  cwd: exports_external.string().min(1),
+  envelope: recoveryEnvelopeSchema
+}).strict();
+
+// src/core/correlation-id.ts
+var CORRELATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/;
+
+// src/core/operation-envelope.ts
+var OPERATION_ENVELOPE_SCHEMA_VERSION = 1;
+var MAX_OPERATION_ENVELOPE_BYTES = 65536;
+var MAX_OPERATION_ENVELOPE_IDENTIFIER_LENGTH = 160;
+var MAX_OPERATION_ENVELOPE_ITEMS = 128;
+var MAX_MESSAGE_LENGTH = 2000;
+var MAX_EVIDENCE_ITEMS = 16;
+var OPERATION_ID = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/;
+var CODE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/;
+var EVIDENCE_ID = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,159}$/;
+var SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+var identifierSchema = exports_external.string().min(1).max(MAX_OPERATION_ENVELOPE_IDENTIFIER_LENGTH);
+var capabilityIdSchema = identifierSchema.regex(CAPABILITY_ID_PATTERN, "capability id must be dotted lower-case segments");
+var codeSchema = identifierSchema.regex(CODE, "code must be an uppercase snake-case identifier");
+var messageSchema = exports_external.string().min(1).max(MAX_MESSAGE_LENGTH);
+var contextSchema = exports_external.object({
+  engine: exports_external.enum(DATABASE_SYSTEMS),
+  permission: exports_external.enum(["query-only", "read-write", "data-admin", "admin"]),
+  connectionName: identifierSchema.nullable(),
+  agentMode: exports_external.boolean(),
+  correlationId: exports_external.string().regex(CORRELATION_ID_PATTERN, "invalid correlation id").optional()
+}).strict();
+var resultSchema = exports_external.object({
+  id: capabilityIdSchema,
+  status: exports_external.enum(["available", "unavailable", "unknown"]),
+  reason: exports_external.enum([
+    "unknown-capability",
+    "context-unavailable",
+    "context-unresolvable",
+    "engine",
+    "agent-mode",
+    "permission"
+  ]).nullable()
+}).strict().superRefine((result, ctx) => {
+  if (result.status === "available" && result.reason !== null) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "available results require reason null"
+    });
+  }
+  if (result.status === "unknown" && result.reason !== "unknown-capability") {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "unknown results require reason unknown-capability"
+    });
+  }
+  if (result.status === "unavailable" && (result.reason === null || result.reason === "unknown-capability")) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "unavailable results require an availability reason"
+    });
+  }
+});
+var capabilitiesCheckDataSchema = exports_external.object({
+  required: exports_external.array(capabilityIdSchema).min(1).max(MAX_OPERATION_ENVELOPE_ITEMS),
+  results: exports_external.array(resultSchema).min(1).max(MAX_OPERATION_ENVELOPE_ITEMS)
+}).strict().superRefine((data, ctx) => {
+  if (new Set(data.required).size !== data.required.length) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "required capability ids must be unique"
+    });
+  }
+  if (data.required.length !== data.results.length || data.required.some((id, index) => data.results[index]?.id !== id)) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "results must match required capability ids in order"
+    });
+  }
+});
+var warningSchema = exports_external.object({
+  code: codeSchema,
+  message: messageSchema
+}).strict();
+var evidenceSchema = exports_external.object({
+  kind: exports_external.enum(["receipt", "audit", "verification-artifact"]),
+  id: exports_external.string().regex(EVIDENCE_ID, "invalid evidence id"),
+  digest: exports_external.string().regex(SHA256_DIGEST, "invalid evidence digest").optional()
+}).strict();
+var errorSchema = exports_external.object({
+  code: codeSchema,
+  message: messageSchema
+}).strict();
+function hasOversizedRecoveryString(value) {
+  if (typeof value === "string")
+    return value.length > MAX_MESSAGE_LENGTH;
+  if (Array.isArray(value))
+    return value.some(hasOversizedRecoveryString);
+  if (value === null || typeof value !== "object")
+    return false;
+  return Object.values(value).some(hasOversizedRecoveryString);
+}
+var operationEnvelopeFieldSchema = exports_external.object({
+  schemaVersion: exports_external.literal(OPERATION_ENVELOPE_SCHEMA_VERSION),
+  ok: exports_external.boolean(),
+  operation: exports_external.enum(["capabilities.check", "capabilities.list"]).refine((value) => value.length <= MAX_OPERATION_ENVELOPE_IDENTIFIER_LENGTH && OPERATION_ID.test(value)),
+  status: exports_external.enum(["succeeded", "failed"]),
+  context: contextSchema.nullable(),
+  data: exports_external.union([capabilitiesCheckDataSchema, CapabilityCatalogSchema]).nullable(),
+  warnings: exports_external.array(warningSchema).max(MAX_OPERATION_ENVELOPE_ITEMS),
+  evidence: exports_external.array(evidenceSchema).max(MAX_EVIDENCE_ITEMS),
+  recovery: recoveryEnvelopeSchema.nullable(),
+  error: errorSchema.nullable()
+}).strict().superRefine((envelope, ctx) => {
+  if (envelope.ok !== (envelope.status === "succeeded")) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: 'ok must equal (status === "succeeded")'
+    });
+  }
+  if (envelope.operation === "capabilities.check") {
+    if (envelope.status === "succeeded") {
+      if (envelope.error !== null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful envelopes require error null"
+        });
+      }
+      if (envelope.data === null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful capabilities.check envelopes require data"
+        });
+      } else if ("results" in envelope.data) {
+        if (envelope.data.results.some((result) => result.status !== "available")) {
+          ctx.addIssue({
+            code: exports_external.ZodIssueCode.custom,
+            message: "successful capabilities.check results must all be available"
+          });
+        }
+      } else {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "capabilities.check requires capabilitiesCheckDataSchema shape"
+        });
+      }
+    } else if (envelope.error === null) {
+      ctx.addIssue({ code: exports_external.ZodIssueCode.custom, message: "failed envelopes require an error" });
+    }
+    const completedNegative = envelope.error?.code === "CAPABILITY_REQUIREMENTS_UNMET";
+    if (envelope.status === "failed" && completedNegative !== (envelope.data !== null)) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        message: "only completed negative capability results retain data"
+      });
+    }
+    if (completedNegative && envelope.data !== null && "results" in envelope.data && envelope.data.results.every((result) => result.status === "available")) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        message: "completed negative capability results require an unmet result"
+      });
+    }
+  } else if (envelope.operation === "capabilities.list") {
+    if (envelope.status === "succeeded") {
+      if (envelope.context !== null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful capabilities.list envelopes require context null"
+        });
+      }
+      if (envelope.warnings.length !== 0) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful capabilities.list envelopes require warnings empty"
+        });
+      }
+      if (envelope.evidence.length !== 0) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful capabilities.list envelopes require evidence empty"
+        });
+      }
+      if (envelope.recovery !== null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful capabilities.list envelopes require recovery null"
+        });
+      }
+      if (envelope.error !== null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful envelopes require error null"
+        });
+      }
+      if (envelope.data === null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "successful capabilities.list envelopes require data"
+        });
+      } else if (!("capabilities" in envelope.data)) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "capabilities.list requires CapabilityCatalogSchema shape"
+        });
+      }
+    } else {
+      if (envelope.error === null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "failed envelopes require an error"
+        });
+      }
+      if (envelope.data !== null) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          message: "failed capabilities.list envelopes require data null"
+        });
+      }
+    }
+  }
+  if (envelope.recovery !== null) {
+    if (envelope.error === null || envelope.recovery.error.code !== envelope.error.code || envelope.recovery.error.message !== envelope.error.message) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        message: "recovery error code and message must match the envelope error"
+      });
+    }
+    if (hasOversizedRecoveryString(envelope.recovery)) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        message: `recovery strings must be at most ${MAX_MESSAGE_LENGTH} characters`
+      });
+    }
+  }
+});
+function summarize(error) {
+  return error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+}
+function encode(envelope) {
+  return `${JSON.stringify(envelope)}
+`;
+}
+function byteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+function parseOperationEnvelope(input) {
+  const parsed = operationEnvelopeFieldSchema.safeParse(input);
+  if (!parsed.success)
+    return { ok: false, reason: summarize(parsed.error) };
+  const value = parsed.data;
+  const size = byteLength(encode(value));
+  if (size > MAX_OPERATION_ENVELOPE_BYTES) {
+    return {
+      ok: false,
+      reason: `<root>: serialized envelope is ${size} bytes; cap is ${MAX_OPERATION_ENVELOPE_BYTES}`
+    };
+  }
+  return { ok: true, value };
+}
 // src/utils/es-index-target.ts
 var MAX_DECODE_PASSES = 4;
 function unwrap(target) {
@@ -9954,19 +12013,32 @@ export {
   removeConnection,
   readV2Config,
   readConfig,
+  parseRequirements,
+  parseOperationEnvelope,
+  parseCapabilityCheckReport,
+  parseCapabilityCatalog,
   migrateV1ToV2,
   loadConnectionEnv,
   listConnections,
+  listCapabilityIds,
   isGlobalConfigPath,
   getProjectStoragePath,
   getGlobalConfigPath,
   getDbcliConfigHome,
+  findCapability,
   envVarNameFor,
   detectConfigVersion,
+  checkCapabilities,
+  buildCapabilityCatalog,
   SchemaLayeredLoader,
   QueryExecutor,
+  OPERATION_ENVELOPE_SCHEMA_VERSION,
   DataExecutor,
   ConnectionError,
+  CapabilityRequirementError,
+  CapabilityContractError,
+  CAPABILITY_CONTRACT_SCHEMA_VERSION,
+  CAPABILITIES,
   BlacklistValidator,
   BlacklistManager,
   BlacklistError