turbine-orm 0.81.0 → 0.90.0

package/dist/cli/local-server-guard.d.ts

@@ -0,0 +1,53 @@
+/**
+ * turbine-orm CLI: shared guards for the local servers
+ *
+ * A leaf module (Node's crypto and nothing else), the same role as
+ * `cli/rate-limit.ts`: Studio and Observe both bind a loopback port behind a
+ * random token, and the checks below are the parts of that perimeter that are
+ * identical for both, so neither server grows its own copy.
+ *
+ *  - {@link isAllowedHostHeader}: a request whose `Host` names anything but this
+ *    server is refused. This is what stops DNS rebinding: a page on an attacker's
+ *    domain that re-resolves to 127.0.0.1 still sends `Host: attacker.example`.
+ *  - {@link createTicketGate} / {@link redeemTicket}: the URL printed in the
+ *    terminal carries a ONE-TIME login token, separate from the credential the
+ *    session then uses, so a URL that lands in browser history, a process
+ *    listing or a log is a spent ticket and not a standing key.
+ *  - {@link constantTimeEqual}: the one token comparison.
+ */
+/**
+ * Compare two secrets without leaking length or content through timing. Both
+ * sides are hashed to fixed-length digests first, so `timingSafeEqual` never
+ * throws on a length mismatch.
+ */
+export declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * Is this `Host` header one this server should answer to?
+ *
+ * Allowed: the loopback names (`127.0.0.1`, `localhost`, `[::1]`) and the host
+ * the server was bound to, each on the bound port. A server bound to a wildcard
+ * address (`0.0.0.0`, `::`) also accepts an IP literal, because it has no single
+ * name and a literal address cannot be rebound: rebinding needs a DNS name the
+ * attacker controls.
+ *
+ * An ABSENT header is allowed. HTTP/1.1 requires it and Node answers 400 itself
+ * when it is missing, so the only request that reaches this check without one is
+ * an HTTP/1.0 client, which is not a browser and can say anything anyway. The
+ * attack this refuses needs a browser, and a browser always sends one.
+ */
+export declare function isAllowedHostHeader(header: string | string[] | undefined, boundHost: string, port: number): boolean;
+/** The one-time ticket carried by the URL a server prints. */
+export interface TicketGate {
+    /** The value in the printed URL's `?token=`. Never a session credential. */
+    readonly token: string;
+    /** True once a GET carrying the token has been exchanged for a session cookie. */
+    used: boolean;
+}
+export type TicketOutcome = 'granted' | 'used' | 'invalid';
+/** Mint a gate. `token` is only passed by a caller that has no separate one to give. */
+export declare function createTicketGate(token?: string): TicketGate;
+/**
+ * Try to exchange `candidate` for a session. `granted` happens at most once per
+ * gate; afterwards the same token reports `used`, which a server must refuse.
+ */
+export declare function redeemTicket(gate: TicketGate, candidate: string): TicketOutcome;

package/dist/cli/local-server-guard.js

@@ -0,0 +1,113 @@
+/**
+ * turbine-orm CLI: shared guards for the local servers
+ *
+ * A leaf module (Node's crypto and nothing else), the same role as
+ * `cli/rate-limit.ts`: Studio and Observe both bind a loopback port behind a
+ * random token, and the checks below are the parts of that perimeter that are
+ * identical for both, so neither server grows its own copy.
+ *
+ *  - {@link isAllowedHostHeader}: a request whose `Host` names anything but this
+ *    server is refused. This is what stops DNS rebinding: a page on an attacker's
+ *    domain that re-resolves to 127.0.0.1 still sends `Host: attacker.example`.
+ *  - {@link createTicketGate} / {@link redeemTicket}: the URL printed in the
+ *    terminal carries a ONE-TIME login token, separate from the credential the
+ *    session then uses, so a URL that lands in browser history, a process
+ *    listing or a log is a spent ticket and not a standing key.
+ *  - {@link constantTimeEqual}: the one token comparison.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+/**
+ * Compare two secrets without leaking length or content through timing. Both
+ * sides are hashed to fixed-length digests first, so `timingSafeEqual` never
+ * throws on a length mismatch.
+ */
+export function constantTimeEqual(a, b) {
+    const ah = createHash('sha256').update(a).digest();
+    const bh = createHash('sha256').update(b).digest();
+    return timingSafeEqual(ah, bh);
+}
+// ---------------------------------------------------------------------------
+// Host header allowlist
+// ---------------------------------------------------------------------------
+const LOOPBACK_HOSTNAMES = ['127.0.0.1', 'localhost', '[::1]'];
+const WILDCARD_HOSTNAMES = new Set(['0.0.0.0', '[::]', '::']);
+const IPV4_LITERAL = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+/** `host`, `host:port`, `[v6]` or `[v6]:port`, or null when it is none of those. */
+function parseHostHeader(value) {
+    const trimmed = value.trim().toLowerCase();
+    if (trimmed === '')
+        return null;
+    if (trimmed.startsWith('[')) {
+        const end = trimmed.indexOf(']');
+        if (end < 0)
+            return null;
+        const rest = trimmed.slice(end + 1);
+        if (rest === '')
+            return { hostname: trimmed.slice(0, end + 1), port: null };
+        if (!/^:\d+$/.test(rest))
+            return null;
+        return { hostname: trimmed.slice(0, end + 1), port: rest.slice(1) };
+    }
+    const colon = trimmed.indexOf(':');
+    if (colon < 0)
+        return { hostname: trimmed, port: null };
+    // A bare name never contains a second colon: that would be an unbracketed IPv6.
+    if (trimmed.indexOf(':', colon + 1) >= 0)
+        return null;
+    const port = trimmed.slice(colon + 1);
+    if (!/^\d+$/.test(port))
+        return null;
+    return { hostname: trimmed.slice(0, colon), port };
+}
+function bracketIfIpv6(host) {
+    const lower = host.toLowerCase();
+    return lower.includes(':') && !lower.startsWith('[') ? `[${lower}]` : lower;
+}
+/**
+ * Is this `Host` header one this server should answer to?
+ *
+ * Allowed: the loopback names (`127.0.0.1`, `localhost`, `[::1]`) and the host
+ * the server was bound to, each on the bound port. A server bound to a wildcard
+ * address (`0.0.0.0`, `::`) also accepts an IP literal, because it has no single
+ * name and a literal address cannot be rebound: rebinding needs a DNS name the
+ * attacker controls.
+ *
+ * An ABSENT header is allowed. HTTP/1.1 requires it and Node answers 400 itself
+ * when it is missing, so the only request that reaches this check without one is
+ * an HTTP/1.0 client, which is not a browser and can say anything anyway. The
+ * attack this refuses needs a browser, and a browser always sends one.
+ */
+export function isAllowedHostHeader(header, boundHost, port) {
+    if (header === undefined)
+        return true;
+    if (typeof header !== 'string')
+        return false;
+    const parsed = parseHostHeader(header);
+    if (!parsed)
+        return false;
+    if (parsed.port === null ? port !== 80 : parsed.port !== String(port))
+        return false;
+    const bound = bracketIfIpv6(boundHost);
+    if (parsed.hostname === bound || LOOPBACK_HOSTNAMES.includes(parsed.hostname))
+        return true;
+    if (WILDCARD_HOSTNAMES.has(boundHost.toLowerCase()) || WILDCARD_HOSTNAMES.has(bound)) {
+        return IPV4_LITERAL.test(parsed.hostname) || parsed.hostname.startsWith('[');
+    }
+    return false;
+}
+/** Mint a gate. `token` is only passed by a caller that has no separate one to give. */
+export function createTicketGate(token = randomBytes(24).toString('hex')) {
+    return { token, used: false };
+}
+/**
+ * Try to exchange `candidate` for a session. `granted` happens at most once per
+ * gate; afterwards the same token reports `used`, which a server must refuse.
+ */
+export function redeemTicket(gate, candidate) {
+    if (!constantTimeEqual(candidate, gate.token))
+        return 'invalid';
+    if (gate.used)
+        return 'used';
+    gate.used = true;
+    return 'granted';
+}

package/dist/cli/local-server-output.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What the two local servers (Studio and Observe) send OUT of the process: the
+ * text of an error response, and the command that opens a browser. A leaf that
+ * imports only `node:child_process`, so both servers share one copy.
+ *
+ * Both exist because the input to them is not entirely ours. A caught value can
+ * be anything a dependency threw, and the host in the printed URL comes from a
+ * command-line flag.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * The text a Studio or Observe error response may carry for a caught value.
+ *
+ * An `Error` contributes its own message, and only that: never `stack`, and
+ * never the result of stringifying the object (a `toString` on a foreign error
+ * type is free to print one). When the message is empty, which is what Node's
+ * `AggregateError` has for a refused connection, the messages of the errors it
+ * aggregates or its `cause` are used, then its `code`, then its name. A thrown
+ * value that is not an `Error` has nothing safe to say, so it gets a fixed
+ * sentence rather than a rendering of whatever it was.
+ */
+export declare function responseErrorText(err: unknown): string;
+/** @internal exported for tests. */
+export declare function isLaunchableUrl(url: string): boolean;
+/** @internal the seams the tests replace; production passes neither. */
+export interface BrowserLaunch {
+    platform: string;
+    spawn: typeof spawn;
+}
+/**
+ * Open `url` in the user's browser. Best effort: false when the URL is not one
+ * of ours to launch or the launcher could not be started, and the caller has
+ * already printed the URL either way.
+ *
+ * The launcher is started directly with an argument list and no shell
+ * (`xdg-open <url>`, `open <url>`, and on Windows `cmd /c start "" <url>`).
+ * A launcher that is not installed is reported as an 'error' EVENT rather than
+ * a throw, and with no listener Node turns it into an uncaught exception that
+ * ends the server right after it printed its address.
+ */
+export declare function openInBrowser(url: string, launch?: BrowserLaunch): boolean;

package/dist/cli/local-server-output.js

@@ -0,0 +1,98 @@
+/**
+ * What the two local servers (Studio and Observe) send OUT of the process: the
+ * text of an error response, and the command that opens a browser. A leaf that
+ * imports only `node:child_process`, so both servers share one copy.
+ *
+ * Both exist because the input to them is not entirely ours. A caught value can
+ * be anything a dependency threw, and the host in the printed URL comes from a
+ * command-line flag.
+ */
+import { spawn } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Error text for an HTTP response
+// ---------------------------------------------------------------------------
+const UNEXPECTED_ERROR = 'unexpected error';
+/**
+ * The text a Studio or Observe error response may carry for a caught value.
+ *
+ * An `Error` contributes its own message, and only that: never `stack`, and
+ * never the result of stringifying the object (a `toString` on a foreign error
+ * type is free to print one). When the message is empty, which is what Node's
+ * `AggregateError` has for a refused connection, the messages of the errors it
+ * aggregates or its `cause` are used, then its `code`, then its name. A thrown
+ * value that is not an `Error` has nothing safe to say, so it gets a fixed
+ * sentence rather than a rendering of whatever it was.
+ */
+export function responseErrorText(err) {
+    return err instanceof Error ? errorMessage(err, 0) : UNEXPECTED_ERROR;
+}
+function errorMessage(err, depth) {
+    if (err.message)
+        return err.message;
+    if (depth < 4) {
+        const inner = err.errors;
+        if (Array.isArray(inner)) {
+            const parts = new Set();
+            for (const e of inner) {
+                const text = e instanceof Error ? errorMessage(e, depth + 1) : '';
+                if (text !== '')
+                    parts.add(text);
+            }
+            if (parts.size > 0)
+                return [...parts].join('; ');
+        }
+        if (err.cause instanceof Error) {
+            const cause = errorMessage(err.cause, depth + 1);
+            if (cause !== '')
+                return cause;
+        }
+    }
+    const code = err.code;
+    if (typeof code === 'string' && code !== '')
+        return code;
+    return err.name || 'Error';
+}
+// ---------------------------------------------------------------------------
+// Browser launch
+// ---------------------------------------------------------------------------
+/**
+ * The only URL shape a server launches: plain `http`, a host name or IP
+ * literal, a port, and optionally the one-time `?token=`. The host comes from
+ * `--host`, and on Windows the URL is an argument of `cmd /c start`, where `&`,
+ * `|`, `^`, `%` and `"` are command syntax rather than data, so anything outside
+ * this set is not handed to a launcher at all. The URL is still printed.
+ */
+const LAUNCHABLE_URL = /^http:\/\/(?:[A-Za-z0-9._-]+|\[[0-9A-Fa-f:.]+\]):\d{1,5}\/(?:\?token=[A-Za-z0-9_-]+)?$/;
+/** @internal exported for tests. */
+export function isLaunchableUrl(url) {
+    return LAUNCHABLE_URL.test(url);
+}
+/**
+ * Open `url` in the user's browser. Best effort: false when the URL is not one
+ * of ours to launch or the launcher could not be started, and the caller has
+ * already printed the URL either way.
+ *
+ * The launcher is started directly with an argument list and no shell
+ * (`xdg-open <url>`, `open <url>`, and on Windows `cmd /c start "" <url>`).
+ * A launcher that is not installed is reported as an 'error' EVENT rather than
+ * a throw, and with no listener Node turns it into an uncaught exception that
+ * ends the server right after it printed its address.
+ */
+export function openInBrowser(url, launch = { platform: process.platform, spawn }) {
+    if (!isLaunchableUrl(url))
+        return false;
+    const [command, args] = launch.platform === 'darwin'
+        ? ['open', [url]]
+        : launch.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = launch.spawn(command, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/mcp.d.ts

@@ -43,6 +43,14 @@ export interface McpServerHandle {
      */
     closed: Promise<McpCloseReason>;
 }
+/**
+ * Split an identifier into lowercase words on separators, case changes
+ * (`refreshToken`), acronym edges (`APIKey` -> `api`, `key`) and letter/digit
+ * edges (`token2`).
+ */
+export declare function secretNameWords(name: string): string[];
+/** True when `name` looks like it holds a credential. See {@link SECRET_WORDS}. */
+export declare function looksLikeSecretName(name: string): boolean;
 /**
  * The most bytes the stdio reader will hold WITHOUT seeing a newline.
  *

package/dist/cli/mcp.js

@@ -5,14 +5,14 @@ import pg from 'pg';
 import { absorbCheckedOutErrors } from '../connection-guard.js';
 import { findMissingRelationIndexes } from '../index-advisor.js';
 import { formatBytes } from '../index-stats.js';
-import { deriveCatalogRelations, indexKeyColumn, parseIndexKeyEntries } from '../introspect.js';
+import { deriveCatalogRelations, indexKeyColumn, parseIndexKeyEntries, printableCatalogName, } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
 import { ownLookup, registerUtcTemporalParsers } from '../query/utils.js';
 import { isDateType, pgArrayType, pgTypeToTs, snakeToCamel, } from '../schema.js';
 import { COMPILE_OPERATIONS, carriesColumnNamingArg, collectAggregateColumnNames, compileQueryPlan, isAggregateShaped, } from './compile-query.js';
 import { CATALOGUED_ERROR_CODES, explainErrorCode } from './error-catalog.js';
 import { listMigrationFiles } from './migrate.js';
-import { assertNoPiiPredicates as assertNoPiiPredicatesShared } from './pii-predicate-guard.js';
+import { assertNoPiiPredicates as assertNoPiiPredicatesShared, findRowLockOption, rowLockRefusalMessage, } from './pii-predicate-guard.js';
 import { applyPiiTags, loadPiiTags } from './pii-tags.js';
 import { redactUrl } from './ui.js';
 /**
@@ -51,6 +51,12 @@ function readOwnVersion() {
 const PROTOCOL_VERSION = '2025-06-18';
 const STATEMENT_TIMEOUT = '30s';
 const TRACKING_TABLE = '_turbine_migrations';
+/**
+ * A name made safe to quote in a message. Catalog names can carry control or
+ * bidi characters, and an error message or stderr line can reach a terminal or
+ * a log. Same helper `generate`, `status` and `doctor` print through.
+ */
+const shown = printableCatalogName;
 /**
  * Marker written in place of a hidden cell. Never `null` and never the value,
  * so the agent can tell "hidden" from "empty" (same string Studio uses).
@@ -78,36 +84,93 @@ const REDACTED = '•• redacted ••';
 /**
  * Column names that look like they hold a credential.
  *
- * Anchored to IDENTIFIER SEGMENT boundaries (start, end, or an underscore), not
- * a bare substring. Unanchored, `secret` matched `secretary_id` and `token`
- * matched a perfectly ordinary `token_count`, so the guard refused legitimate
- * queries: a false refusal is not free here, it degrades the tool and trains
- * people to route around it.
+ * A name is split into WORDS (see {@link secretNameWords}) and tested by word
+ * membership, never by substring. Unanchored, `secret` matched `secretary_id`
+ * and `token` matched a perfectly ordinary `token_count`, so the guard refused
+ * legitimate queries: a false refusal is not free here, it degrades the tool
+ * and trains people to route around it. Word splitting reads snake_case,
+ * kebab-case, camelCase, PascalCase and SCREAMING_CASE the same way, which the
+ * earlier underscore-anchored pattern did not: on a camelCase database (the
+ * default naming of a Prisma-created one) it caught `apiKey` only by accident
+ * of the whole name being a listed word and returned `refreshToken`,
+ * `passwordHash` and `clientSecret` verbatim.
  *
  * Deliberately still conservative in the other direction. A column whose name
- * genuinely carries a segment like `token` or `secret` is refused even when it
+ * genuinely carries a word like `token` or `secret` is refused even when it
  * holds nothing sensitive, because this gate decides whether raw bytes, or a
  * row-count oracle over them, reach an LLM context. Renaming the column is a
  * cheaper fix than the disclosure it prevents.
  */
-const SECRET_WORDS = [
+const SECRET_WORDS = new Set([
     'passwd',
     'password',
+    'passphrase',
+    'passcode',
     'secret',
     'token',
     'apikey',
-    'api_key',
     'privatekey',
-    'private_key',
+    'accesskey',
     'credential',
-    'credentials',
     'sessionid',
-    'session_id',
     'otp',
     'mfa',
     'totp',
-];
-const SECRET_NAME_PATTERN = new RegExp(`(^|_)(${SECRET_WORDS.join('|')})(_|$)`, 'i');
+    'jwt',
+    'salt',
+]);
+/** Word pairs that are secret only together (`api` + `key`), as one joined string. */
+const SECRET_WORD_PAIRS = new Set(['apikey', 'privatekey', 'accesskey', 'sessionid']);
+/**
+ * Suffixes and prefixes for a name that arrives as ONE lowercase word
+ * (`refreshtoken`, `passwordhash`), where there is no boundary left to split
+ * on. Suffix-only for the short, common words so `secretary` and `tokenizer`
+ * stay unflagged; the prefix list is limited to words nothing else starts with.
+ */
+const SECRET_SUFFIXES = ['token', 'secret', 'password', 'passwd', 'passphrase', 'apikey', 'privatekey', 'sessionid'];
+const SECRET_PREFIXES = ['password', 'passwd', 'passphrase', 'apikey', 'privatekey', 'accesskey'];
+/**
+ * Split an identifier into lowercase words on separators, case changes
+ * (`refreshToken`), acronym edges (`APIKey` -> `api`, `key`) and letter/digit
+ * edges (`token2`).
+ */
+export function secretNameWords(name) {
+    return name
+        .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/([A-Za-z])(\d)/g, '$1 $2')
+        .replace(/(\d)([A-Za-z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word !== '');
+}
+function isSecretWord(word) {
+    if (SECRET_WORDS.has(word))
+        return true;
+    // Plural (`tokens`, `api_keys` via the pair join, `credentials`).
+    return word.length > 3 && word.endsWith('s') && SECRET_WORDS.has(word.slice(0, -1));
+}
+/** True when `name` looks like it holds a credential. See {@link SECRET_WORDS}. */
+export function looksLikeSecretName(name) {
+    const words = secretNameWords(name);
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        if (isSecretWord(word))
+            return true;
+        const next = words[i + 1];
+        if (next !== undefined && SECRET_WORD_PAIRS.has(`${word}${next.replace(/s$/, '')}`))
+            return true;
+        // One unsplittable lowercase word: only worth a second look when it is long
+        // enough to be a compound, and only against the safe suffix/prefix lists.
+        if (word.length > 5 && /^[a-z]+$/.test(word)) {
+            if (SECRET_SUFFIXES.some((suffix) => word.length > suffix.length && word.endsWith(suffix)))
+                return true;
+            if (SECRET_PREFIXES.some((prefix) => word.length > prefix.length && word.startsWith(prefix)))
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * The most bytes the stdio reader will hold WITHOUT seeing a newline.
  *
@@ -149,7 +212,7 @@ const TOOLS = [
     },
     {
         name: 'explain_query',
-        description: 'Run EXPLAIN (FORMAT JSON) for a schema-validated findMany query. Pass table + optional where/orderBy/limit/select, free-form SQL is rejected. A where or orderBy on a PII-tagged or secret-named column is refused: the planner row estimate would leak the value. Naming such a column in select is allowed, since EXPLAIN returns no rows.',
+        description: 'Run EXPLAIN (FORMAT JSON) for a schema-validated findMany query. Pass table + optional where/orderBy/limit/select, free-form SQL is rejected. A where or orderBy on a PII-tagged or secret-named column is refused: the planner row estimate would leak the value. Naming a PII-tagged column in select is refused, as it is in the library without includePii: UNSAFE, which this server cannot pass. A `lock` option is refused: this server is read-only and a locking read needs a write-capable transaction in your application.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -174,7 +237,7 @@ const TOOLS = [
     },
     {
         name: 'compile_query',
-        description: 'Compile a Turbine read query to the EXACT SQL it would send, WITHOUT running it: no statement is executed and no row is read, so this is safe to call on production and safe to call in a loop. Use it before you write the query into code. Pass `table`, an `operation` (findMany / findUnique / findFirst / count / aggregate / groupBy, default findMany) and `args`, the same object you would pass to that method. Returns the SQL, the bound parameters, how many STATEMENTS the query costs at execution (a `with` clause can be one join or one follow-up per relation), which relation-load strategy it takes, whether it is bounded by a LIMIT or reads the whole table, the relation depth, and warnings such as a relation whose correlation column has no index. A query that FAILS to compile is a successful answer, not an error: an unknown column (TURBINE_E003), an unknown relation (TURBINE_E005) or the empty-where guard comes back as `ok: false` with the code, the message and how to fix it. READ OPERATIONS ONLY, deliberately: this server has no write surface and compiling one would be the first. A where or orderBy on a PII-tagged or secret-named column is refused, exactly as in explain_query.',
+        description: 'Compile a Turbine read query to the EXACT SQL it would send, WITHOUT running it: no statement is executed and no row is read, so this is safe to call on production and safe to call in a loop. Use it before you write the query into code. Pass `table`, an `operation` (findMany / findUnique / findFirst / count / aggregate / groupBy, default findMany) and `args`, the same object you would pass to that method. Returns the SQL, the bound parameters, how many STATEMENTS the query costs at execution (a `with` clause can be one join or one follow-up per relation), which relation-load strategy it takes, whether it is bounded by a LIMIT or reads the whole table, the relation depth, and warnings such as a relation whose correlation column has no index. A query that FAILS to compile is a successful answer, not an error: an unknown column (TURBINE_E003), an unknown relation (TURBINE_E005) or the empty-where guard comes back as `ok: false` with the code, the message and how to fix it. READ OPERATIONS ONLY, deliberately: this server has no write surface and compiling one would be the first. A where or orderBy on a PII-tagged or secret-named column is refused, exactly as in explain_query, and so is a `lock` option (on the query or on any `with` entry): compile the query without it.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -753,6 +816,9 @@ async function explainQuery(ctx, args) {
         throw jsonRpcError(-32602, 'explain_query no longer accepts free-form SQL; pass table + findMany-style args (where/orderBy/limit/select)');
     }
     const tableName = requiredString(args, 'table');
+    // Before the allowlist below, which would otherwise drop `lock` unseen and
+    // plan an UNLOCKED query for a caller who asked for a locking one.
+    assertNoLockingRead(args, 'explain_query');
     const findManyArgs = parseExplainFindManyArgs(args);
     return withReadOnly(ctx, async (client) => {
         const { metadata, piiTags } = await loadSchemaMetadata(client, ctx.options);
@@ -789,7 +855,7 @@ async function explainQuery(ctx, args) {
 }
 /**
  * Refuse an `explain_query` that filters or sorts on a hidden column: one that
- * is PII-tagged, or one whose NAME matches {@link SECRET_NAME_PATTERN}.
+ * is PII-tagged, or one whose NAME matches {@link looksLikeSecretName}.
  *
  * The name half is not a second-best approximation of the tag half, it is the
  * same rule `sample_rows` applies, applied to the other value-bearing path.
@@ -815,8 +881,10 @@ async function explainQuery(ctx, args) {
  * What stays here is the part that is genuinely the MCP server's: the two
  * reasons a column is hidden, and a JSON-RPC refusal.
  *
- * `select` is NOT refused: explain returns no rows, and naming a column reveals
- * nothing about its contents.
+ * `select` is not judged HERE: explain returns no rows, and naming a column reveals
+ * nothing about its contents. The library itself refuses a PII-tagged column in
+ * `select` without `includePii: UNSAFE`, which no JSON-RPC caller can supply, so
+ * the builder's own E003 reaches the caller as an invalid-params error.
  *
  * FAILS CLOSED when the tag scan failed: with no trustworthy tag list, no
  * column can be shown to be safe, so every where/orderBy is refused rather than
@@ -839,7 +907,7 @@ async function explainQuery(ctx, args) {
 function hiddenColumnReason(owner, column) {
     if (owner.columns.some((col) => col.name === column && col.pii === true))
         return 'is PII-tagged';
-    if (SECRET_NAME_PATTERN.test(column))
+    if (looksLikeSecretName(column))
         return 'has a secret-looking name';
     return null;
 }
@@ -854,7 +922,7 @@ function assertNoPiiPredicates(args, table, metadata, piiTags) {
         metadata,
         hiddenReason: hiddenColumnReason,
         refuseColumn: (owner, column, why) => {
-            throw jsonRpcError(-32602, `Column "${column}" on "${owner.name}" ${why}, so it cannot be used in a where or orderBy here: ` +
+            throw jsonRpcError(-32602, `Column "${shown(column)}" on "${shown(owner.name)}" ${why}, so it cannot be used in a where or orderBy here: ` +
                 `EXPLAIN reports the planner's row estimate, and the estimate for a predicate on a hidden value ` +
                 `reveals that value one character at a time. Filter on a visible column instead.`);
         },
@@ -863,7 +931,7 @@ function assertNoPiiPredicates(args, table, metadata, piiTags) {
                 `prove it does not filter or sort on a tagged column, so it is refused. Flatten the query.`);
         },
         refuseShape: (owner, key) => {
-            throw jsonRpcError(-32602, `The PII guard does not recognize "${key}" in a query on "${owner.name}", so it cannot prove the ` +
+            throw jsonRpcError(-32602, `The PII guard does not recognize "${shown(key)}" in a query on "${shown(owner.name)}", so it cannot prove the ` +
                 `query does not filter or sort on a hidden column, and refuses it rather than guessing. ` +
                 `Remove it and explain the query without it.`);
         },
@@ -909,6 +977,10 @@ async function compileQuery(ctx, args) {
     const tableName = requiredString(args, 'table');
     const operation = parseCompileOperation(args.operation);
     const queryArgs = parseCompileArgs(args.args);
+    // Whatever the operation: count / aggregate / groupBy take no `lock`, and
+    // compiling them would drop it unseen, so the SQL shown would not be the
+    // query the caller wrote. Refused before the catalog read.
+    assertNoLockingRead(queryArgs, 'compile_query');
     const { metadata, piiTags } = await withReadOnly(ctx, (client) => loadSchemaMetadata(client, ctx.options));
     const table = requireTable(metadata, tableName);
     assertCompileHidesNothing(queryArgs, operation, table, metadata, piiTags);
@@ -986,7 +1058,7 @@ function assertCompileHidesNothing(args, operation, table, metadata, piiTags) {
         metadata,
         hiddenReason: hiddenColumnReason,
         refuseColumn: (owner, column, why) => {
-            throw jsonRpcError(-32602, `Column "${column}" on "${owner.name}" ${why}, so compile_query will not build a statement that filters, ` +
+            throw jsonRpcError(-32602, `Column "${shown(column)}" on "${shown(owner.name)}" ${why}, so compile_query will not build a statement that filters, ` +
                 `sorts, pages or groups on it. This server does not author queries that interrogate a hidden value, ` +
                 `wherever that statement would eventually run. Use a visible column.`);
         },
@@ -995,7 +1067,7 @@ function assertCompileHidesNothing(args, operation, table, metadata, piiTags) {
                 `not name a hidden column, so it is refused. Flatten the query.`);
         },
         refuseShape: (owner, key) => {
-            throw jsonRpcError(-32602, `The PII guard does not recognize "${key}" in a query on "${owner.name}", so it cannot prove the query ` +
+            throw jsonRpcError(-32602, `The PII guard does not recognize "${shown(key)}" in a query on "${shown(owner.name)}", so it cannot prove the query ` +
                 `does not name a hidden column, and refuses it rather than guessing. Remove it and compile without it.`);
         },
     });
@@ -1015,11 +1087,26 @@ function assertCompileHidesNothing(args, operation, table, metadata, piiTags) {
         const why = hiddenColumnReason(table, column);
         if (!why)
             continue;
-        throw jsonRpcError(-32602, `Column "${column}" on "${table.name}" ${why}, so it cannot be used as a group key, an aggregate target, a ` +
+        throw jsonRpcError(-32602, `Column "${shown(column)}" on "${shown(table.name)}" ${why}, so it cannot be used as a group key, an aggregate target, a ` +
             `HAVING term or an ordering in compile_query. _count over the table is unaffected; group and aggregate on ` +
             `a visible column instead.`);
     }
 }
+/**
+ * Refuse a `lock` option, at the top level or on any `with` entry, by name.
+ *
+ * Both tools that take query args are read-only, and a locking read takes row
+ * locks, which needs a write-capable transaction in the application. The search
+ * and the wording are the shared ones in `cli/pii-predicate-guard.ts`, the same
+ * pair Studio's Query tab uses, so the rule is stated once. It runs on the RAW
+ * args, ahead of every parser and guard that might drop or reshape the key.
+ */
+function assertNoLockingRead(args, tool) {
+    const locked = findRowLockOption(args);
+    if (locked === null)
+        return;
+    throw jsonRpcError(-32602, rowLockRefusalMessage(shown(locked), tool));
+}
 /**
  * Extract the allowed findMany subset for explain_query (no `with` / raw SQL).
  * Returns a plain object cast at the buildFindMany call site, same pattern as Studio.
@@ -1074,7 +1161,7 @@ function classifyHiddenColumns(table, piiTags) {
             ? 'tags-unreadable'
             : col.pii === true
                 ? 'pii'
-                : SECRET_NAME_PATTERN.test(col.name)
+                : looksLikeSecretName(col.name)
                     ? 'secret-name'
                     : null;
         if (reason) {
@@ -1469,7 +1556,7 @@ async function findJoinPath(ctx, args) {
                 paths,
                 pathsTruncated: false,
                 notes: [
-                    `"${fromTable.name}" is both ends of this query, so no join is needed to read its own columns.`,
+                    `"${shown(fromTable.name)}" is both ends of this query, so no join is needed to read its own columns.`,
                     paths.length > 0
                         ? 'The paths below are its SELF-relations: a relation whose target is the same table, which is the only way to join it to itself.'
                         : 'It declares no self-relation, so there is nothing to join it to itself through.',
@@ -1491,12 +1578,12 @@ async function findJoinPath(ctx, args) {
                 pathsTruncated: false,
                 searchExhausted: exhausted,
                 reason: exhausted
-                    ? `The search for a chain from "${fromTable.name}" to "${toTable.name}" hit this tool's node budget before ` +
+                    ? `The search for a chain from "${shown(fromTable.name)}" to "${shown(toTable.name)}" hit this tool's node budget before ` +
                         `it finished, so this is NOT an answer that they are unconnected. Lower maxDepth (it is ${maxDepth}) to ` +
-                        `bound the search, or call relation_graph on "${fromTable.name}" and walk it a hop at a time.`
-                    : `No relation chain connects "${fromTable.name}" to "${toTable.name}" within ${maxDepth} hop(s). Either the ` +
+                        `bound the search, or call relation_graph on "${shown(fromTable.name)}" and walk it a hop at a time.`
+                    : `No relation chain connects "${shown(fromTable.name)}" to "${shown(toTable.name)}" within ${maxDepth} hop(s). Either the ` +
                         `schema declares no foreign key path between them, or the path is longer than the search depth. Raise ` +
-                        `maxDepth, or call relation_graph on "${fromTable.name}" to see what it does reach.`,
+                        `maxDepth, or call relation_graph on "${shown(fromTable.name)}" to see what it does reach.`,
                 notes: exhausted
                     ? ['The search did not complete. Do not report these tables as unconnected on the strength of this reply.']
                     : [
@@ -2016,8 +2103,8 @@ function estimatedRowCount(stats) {
 function requireTable(metadata, tableName) {
     const table = ownLookup(metadata.tables, tableName);
     if (!table) {
-        const available = Object.keys(metadata.tables).join(', ') || '(none)';
-        throw jsonRpcError(-32602, `Unknown table "${tableName}". Available: ${available}`);
+        const available = Object.keys(metadata.tables).map(shown).join(', ') || '(none)';
+        throw jsonRpcError(-32602, `Unknown table "${shown(tableName)}". Available: ${available}`);
     }
     return table;
 }