turbine-orm 0.67.0 → 0.70.0

package/dist/cjs/query/filters.js

@@ -10,7 +10,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_NAMED_ORDER_KEYS = exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSON_FILTER_KEYS = exports.JSON_STRING_OPERATORS = exports.JSON_RANGE_OPERATORS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = exports.RELATION_FILTER_WRAPPER_SET = exports.RELATION_FILTER_WRAPPERS = exports.COLUMN_REF_OPERATORS = void 0;
 exports.isWhereOperator = isWhereOperator;
 exports.isUnmatchedPlainObject = isUnmatchedPlainObject;
-exports.hasRelationFilterWrapper = hasRelationFilterWrapper;
 exports.isColumnRef = isColumnRef;
 exports.fingerprintOperatorShape = fingerprintOperatorShape;
 exports.assertBindableEqualsOperand = assertBindableEqualsOperand;
@@ -96,23 +95,23 @@ exports.COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte
  * dependency is fixed: `cli/` and the prisma-compat shim may import from the
  * query path, and the query path may never import from `cli/`
  * (`scripts/check-import-cycles.mjs`).
+ *
+ * ## STATUS: a landing spot, not yet a deduplication. Read this before trusting it.
+ *
+ * NOTHING IMPORTS THIS YET. The three copies listed above are all still in
+ * place and still hand-synced; declaring the canonical home did not by itself
+ * move any of them onto it. It is kept, rather than deleted as unused, because
+ * `cli/pii-predicate-guard.ts` names this module as where its own copy wants to
+ * go, and deleting the destination is the one change that makes converging
+ * harder. Wiring the copies up is a separate change: each one sits on a
+ * different walk, so each has to be re-tested on its own.
+ *
+ * So do not read this constant as evidence that the walkers agree. The comment
+ * on each copy is still the only thing holding them in step.
  */
 exports.RELATION_FILTER_WRAPPERS = ['some', 'none', 'every', 'is', 'isNot'];
 /** {@link RELATION_FILTER_WRAPPERS} as a membership set, for the walkers. */
 exports.RELATION_FILTER_WRAPPER_SET = new Set(exports.RELATION_FILTER_WRAPPERS);
-/**
- * True when a normalized relation-filter body carries at least one cardinality
- * wrapper. THE predicate the SQL compiler branches on: a key that names a
- * relation but whose value is not one of these falls through to the scalar
- * path.
- */
-function hasRelationFilterWrapper(filterObj) {
-    for (const wrapper of exports.RELATION_FILTER_WRAPPERS) {
-        if (wrapper in filterObj)
-            return true;
-    }
-    return false;
-}
 /**
  * Check if an operator value is a column reference: a plain object whose ONLY
  * key is `col` with a string value. Anything else (extra keys, non-string

package/dist/cjs/query/where.d.ts

@@ -10,9 +10,9 @@
  * instance (built once in its constructor) exposing exactly the class-resident
  * primitives this module needs. See builder.ts for the thin delegating methods.
  */
-import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
 import { ValidationError } from '../errors.js';
+import type { PgCompatQueryResult } from '../pg-types.js';
 import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
 import type { TemporalInfinityReading } from './deferred.js';
 import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, ResolvedSkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
@@ -127,7 +127,7 @@ export interface BuilderCtx {
     resolveOrderByColumn(table: string, meta: TableMetadata, key: string): string;
     buildJsonPathOrderEntry(table: string, meta: TableMetadata, field: string, spec: JsonPathOrderBy, prefix: string, params?: unknown[]): string;
     toSqlColumn(field: string): string;
-    mutationInsertId(result: pg.QueryResult): unknown;
+    mutationInsertId(result: PgCompatQueryResult): unknown;
     acquireSql(cacheKey: string, build: (params: unknown[]) => string): SqlCacheEntry;
     crossCheckCache(op: string, cacheKey: string, entry: SqlCacheEntry, build: (params: unknown[]) => string, collectedParams: unknown[]): void;
     readonly jsonEncoding: 'object' | 'positional';

package/dist/cjs/schema-sql.d.ts

@@ -35,6 +35,24 @@ export declare function schemaToSQL(schema: SchemaDef, options?: SchemaSqlOption
  * column list), or null when the definitions agree. Expression/partial indexes
  * in the DB never structurally match a plain column list, which is the
  * intended outcome: the operator gets a warning rather than a silent skip.
+ *
+ * ## Parser 3 of 3, and what it is safe for
+ *
+ * THREE indexdef parsers coexist in this repo, catalogued on
+ * `parseIndexKeyEntries` in introspect.ts: that character-by-character scanner
+ * (the one to prefer for new callers), `parsePlainUniqueIndexColumns` in the
+ * same file, and this one. The two in introspect.ts do NOT feed this function
+ * and a fix to either does not reach it.
+ *
+ * This still uses the `USING \w+ \(([^)]*)\)` regex the scanner was written to
+ * replace, so it inherits the same weaknesses: it stops at the FIRST `)`, and it
+ * splits on every comma, which misreads an expression key (`lower(email)`), a
+ * quoted identifier containing a comma or a paren, and an opclass'd key. Safe
+ * here because every outcome of a misread is the SAME outcome as a genuine
+ * mismatch: a string describing the difference, which the caller turns into a
+ * warning for a human to read. It never drops or alters an index, and it is
+ * never consulted about whether a column set is unique. Do not reuse it
+ * anywhere those two properties stop holding.
  */
 export declare function describeIndexDefMismatch(idx: ColumnIndexDef, indexdef: string): string | null;
 /**

package/dist/cjs/schema-sql.js

@@ -403,6 +403,24 @@ function declaredIndexName(tableName, idx) {
  * column list), or null when the definitions agree. Expression/partial indexes
  * in the DB never structurally match a plain column list, which is the
  * intended outcome: the operator gets a warning rather than a silent skip.
+ *
+ * ## Parser 3 of 3, and what it is safe for
+ *
+ * THREE indexdef parsers coexist in this repo, catalogued on
+ * `parseIndexKeyEntries` in introspect.ts: that character-by-character scanner
+ * (the one to prefer for new callers), `parsePlainUniqueIndexColumns` in the
+ * same file, and this one. The two in introspect.ts do NOT feed this function
+ * and a fix to either does not reach it.
+ *
+ * This still uses the `USING \w+ \(([^)]*)\)` regex the scanner was written to
+ * replace, so it inherits the same weaknesses: it stops at the FIRST `)`, and it
+ * splits on every comma, which misreads an expression key (`lower(email)`), a
+ * quoted identifier containing a comma or a paren, and an opclass'd key. Safe
+ * here because every outcome of a misread is the SAME outcome as a genuine
+ * mismatch: a string describing the difference, which the caller turns into a
+ * warning for a human to read. It never drops or alters an index, and it is
+ * never consulted about whether a column set is unique. Do not reuse it
+ * anywhere those two properties stop holding.
  */
 function describeIndexDefMismatch(idx, indexdef) {
     const dbUnique = /^\s*CREATE\s+UNIQUE\s+INDEX\b/i.test(indexdef);

package/dist/cli/error-catalog.d.ts

@@ -0,0 +1,77 @@
+/**
+ * turbine-orm CLI: the error-code catalog behind `explain_error`.
+ *
+ * A pure leaf module, the same role `cli/rate-limit.ts`, `cli/destructive.ts`
+ * and `cli/pii-predicate-guard.ts` play: no I/O, no state, and no import from a
+ * sibling CLI module. Its ONE dependency is `../errors.js`, which is where the
+ * codes and the docs URL actually live.
+ *
+ * WHY IT EXISTS. An agent that catches `[TURBINE_E003] Unknown column "titel"`
+ * has the code and nothing else. `errors.ts` knows the class and the docs
+ * anchor but carries no prose about causes or repairs, and the prose that does
+ * exist lives on the docs site, which an offline agent cannot read and which a
+ * `WebFetch` of a marketing page is a poor way to consult. This turns "I got
+ * E015" into "this is an OptimisticLockError, here is why it fired, here is what
+ * to do", with no database, no network, and no tokens spent re-deriving it.
+ *
+ * TWO RULES KEEP IT HONEST.
+ *
+ *  1. `docsUrl` is NEVER written out here. It is read off a real
+ *     {@link TurbineError} instance, so the URL an agent is handed is
+ *     byte-identical to the one on the error it actually caught. A second
+ *     hand-maintained copy of `docsUrlForCode` is exactly the drift this repo
+ *     has been bitten by before.
+ *  2. The catalog is keyed by `TurbineErrorCode`, exhaustively. Adding a code to
+ *     `errors.ts` without adding a row here FAILS THE BUILD (the mapped type
+ *     below requires every key), and a row for a code that no longer exists
+ *     fails as an excess property. Same stance as `query/option-surface.ts`:
+ *     a human classifies the new thing, the compiler notices when nobody did.
+ */
+import { type TurbineErrorCode } from '../errors.js';
+/** One code's explanation, as `explain_error` returns it. */
+export interface ErrorExplanation {
+    /** The canonical code, e.g. `TURBINE_E003`. */
+    code: TurbineErrorCode;
+    /** The exported class name, e.g. `ValidationError`. */
+    className: string;
+    /** Anchor into the published error table. Sourced from a real error instance. */
+    docsUrl: string;
+    /** True only for the two errors carrying `isRetryable: true as const`. */
+    retryable: boolean;
+    /**
+     * How the error reaches you: raised by Turbine itself, or translated from a
+     * PostgreSQL SQLSTATE by `wrapPgError()`. An agent chasing a `wrapped` error
+     * should be reading the database's constraint, not Turbine's call site.
+     */
+    origin: 'turbine' | 'wrapped-pg';
+    /** The SQLSTATE `wrapPgError()` maps, for `origin: 'wrapped-pg'`. */
+    sqlstate?: string;
+    /** One sentence: the condition that raises it. */
+    whenThrown: string;
+    /** The concrete situations that produce it, most common first. */
+    likelyCauses: string[];
+    /** What to change, in the same order. */
+    howToFix: string[];
+    /** Extra own properties the error carries beyond `code` / `message` / `docsUrl`. */
+    properties: string[];
+}
+/** Every code in the catalog, in code order. */
+export declare const CATALOGUED_ERROR_CODES: TurbineErrorCode[];
+/**
+ * Accept the spellings a caller actually types and return the canonical code,
+ * or `null`.
+ *
+ * A code arrives from a log line (`TURBINE_E003`), from a docs anchor (`e003`),
+ * from prose ("E3"), or as a bare number. All of them mean the same code, and
+ * refusing three of the four teaches an agent to give up rather than to
+ * normalize. What is NOT accepted is anything that resolves to no code at all:
+ * the caller gets `null` and a list, never a guess.
+ */
+export declare function normalizeErrorCode(input: string): TurbineErrorCode | null;
+/**
+ * The full explanation for a code, or `null` when the input names no code.
+ *
+ * `docsUrl` is read off a real {@link TurbineError} rather than formatted here,
+ * so it cannot drift from the URL on the error an agent actually caught.
+ */
+export declare function explainErrorCode(input: string): ErrorExplanation | null;

package/dist/cli/error-catalog.js

@@ -0,0 +1,383 @@
+/**
+ * turbine-orm CLI: the error-code catalog behind `explain_error`.
+ *
+ * A pure leaf module, the same role `cli/rate-limit.ts`, `cli/destructive.ts`
+ * and `cli/pii-predicate-guard.ts` play: no I/O, no state, and no import from a
+ * sibling CLI module. Its ONE dependency is `../errors.js`, which is where the
+ * codes and the docs URL actually live.
+ *
+ * WHY IT EXISTS. An agent that catches `[TURBINE_E003] Unknown column "titel"`
+ * has the code and nothing else. `errors.ts` knows the class and the docs
+ * anchor but carries no prose about causes or repairs, and the prose that does
+ * exist lives on the docs site, which an offline agent cannot read and which a
+ * `WebFetch` of a marketing page is a poor way to consult. This turns "I got
+ * E015" into "this is an OptimisticLockError, here is why it fired, here is what
+ * to do", with no database, no network, and no tokens spent re-deriving it.
+ *
+ * TWO RULES KEEP IT HONEST.
+ *
+ *  1. `docsUrl` is NEVER written out here. It is read off a real
+ *     {@link TurbineError} instance, so the URL an agent is handed is
+ *     byte-identical to the one on the error it actually caught. A second
+ *     hand-maintained copy of `docsUrlForCode` is exactly the drift this repo
+ *     has been bitten by before.
+ *  2. The catalog is keyed by `TurbineErrorCode`, exhaustively. Adding a code to
+ *     `errors.ts` without adding a row here FAILS THE BUILD (the mapped type
+ *     below requires every key), and a row for a code that no longer exists
+ *     fails as an excess property. Same stance as `query/option-surface.ts`:
+ *     a human classifies the new thing, the compiler notices when nobody did.
+ */
+import { TurbineError } from '../errors.js';
+/**
+ * Every code, explained. Exhaustive by construction: `Record<TurbineErrorCode,
+ * …>` means a new code in `errors.ts` does not compile until it is written up
+ * here, and a code removed there leaves an excess property that also does not
+ * compile.
+ */
+const CATALOG = {
+    TURBINE_E001: {
+        className: 'NotFoundError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A query that promises a row did not find one.',
+        likelyCauses: [
+            '`findUniqueOrThrow` / `findFirstOrThrow` matched no row.',
+            '`update` / `delete` addressed a row that does not exist, or that a global filter excludes.',
+            'The where clause names the right column but the wrong value (a stale id, a string/number mismatch on the key).',
+            'A tenant/global filter configured on the client narrowed the query to zero rows without the caller knowing.',
+        ],
+        howToFix: [
+            'Use `findUnique` / `findFirst` and branch on `null` when absence is a normal outcome.',
+            'Read `err.table`, `err.where` and `err.operation` to see exactly what was addressed; the message redacts the VALUES unless the client is on `errorMessages: "verbose"`.',
+            'If a global filter is in play, re-run the same query with `skipGlobalFilters: UNSAFE` to confirm the row exists but is filtered.',
+        ],
+        properties: ['table', 'where', 'operation'],
+    },
+    TURBINE_E002: {
+        className: 'TimeoutError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A query or transaction ran past its configured timeout.',
+        likelyCauses: [
+            'A missing index turned a relation probe or a where clause into a sequential scan.',
+            'A transaction held a lock another transaction was waiting on.',
+            'The timeout is simply lower than the work (a large `createMany`, an unbounded `findMany`).',
+        ],
+        howToFix: [
+            'Run `doctor_report` for missing relation indexes, and `explain_query` on the shape that timed out.',
+            'Read `err.timeoutMs` for the limit that was hit; raise it per query with the `timeout` option rather than globally.',
+            'Bound the read: add a `limit`, or paginate.',
+        ],
+        properties: ['timeoutMs'],
+    },
+    TURBINE_E003: {
+        className: 'ValidationError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'The query args were rejected before any SQL ran.',
+        likelyCauses: [
+            'A name that resolves to no column: in `where`, `orderBy`, `distinct`, a `groupBy` `by` key, an aggregate target, create/update `data`, or (since 0.64) `select` / `omit` at any depth.',
+            'A relation named in `select` or `omit`. Relations load through `with`, which is a SIBLING of `select`, not a member of it.',
+            'A projection shape that selects nothing: an empty or all-false `select`, or `select` and `omit` on the same query.',
+            'The empty-where guard: `update` / `delete` / `updateMany` / `deleteMany` with `{}` or an all-undefined where.',
+            'An aggregate over a PII-tagged column (`_min` / `_max`, or a PII column as a `groupBy` key) with no `includePii`.',
+            'A privilege option (`includePii`, `skipGlobalFilters`, `allowFullTableScan`) passed `true` instead of the `UNSAFE` symbol.',
+            '`forceCustomPlan` against a client pinned to `planCacheMode: "force_generic_plan"`.',
+        ],
+        howToFix: [
+            'Read the message: it names the table and, where it can, the column you probably meant.',
+            'For a relation, move it out of `select` and into `with: { name: true }`.',
+            'For a mass mutation you really do want, pass `allowFullTableScan: UNSAFE` explicitly.',
+            'Import `UNSAFE` from the package root for any privilege option; `JSON.parse` cannot produce a symbol, which is the point.',
+        ],
+        properties: [],
+    },
+    TURBINE_E004: {
+        className: 'ConnectionError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'The pool could not establish or keep a connection.',
+        likelyCauses: [
+            'Nothing is listening (ECONNREFUSED), DNS failed (ENOTFOUND / EAI_AGAIN), or the connect timed out (ETIMEDOUT).',
+            'TLS: a self-signed or expired certificate, or a hostname the certificate does not cover.',
+            'The connection string is malformed, or points at a pooler port the server is not on.',
+            'The server closed an idle pooled connection (proxy idle timeout, restart, failover).',
+        ],
+        howToFix: [
+            'Read `err.sqlstate` and the hint in the message: each driver code carries its own next step.',
+            'Check the host, port and database name; for TLS, supply the CA via `ssl: { ca }` rather than disabling verification.',
+            'For a serverless driver, pass the external pool on `TurbineConfig.pool` instead of a connection string.',
+        ],
+        properties: ['sqlstate'],
+    },
+    TURBINE_E005: {
+        className: 'RelationError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A `with` clause named a relation the schema does not declare.',
+        likelyCauses: [
+            'A typo, or a Prisma-style name that Turbine derives differently.',
+            'The generated metadata is stale: the relation exists in the database but `turbine generate` has not been re-run.',
+            'A UNIQUE foreign key, which Turbine derives as a singular `hasOne` (`user.profile`) rather than a plural `hasMany` (`user.profiles`).',
+        ],
+        howToFix: [
+            'Call `relation_graph` (optionally scoped with `table`) and read the relation names Turbine actually derived, rather than guessing them.',
+            'Call `find_join_path` for the `with` clause to write, instead of assembling one by hand.',
+            'Re-run `turbine generate` if the database has changed.',
+        ],
+        properties: [],
+    },
+    TURBINE_E006: {
+        className: 'MigrationError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A migration could not be parsed, verified, or applied.',
+        likelyCauses: [
+            'A checksum mismatch: an already-applied migration file was edited after the fact.',
+            'A migration file with no `-- UP` section, or an unparseable one.',
+            'The advisory migration lock was already held by a concurrent runner.',
+            'The SQL itself failed; the migration is rolled back, and the underlying error is the `cause`.',
+        ],
+        howToFix: [
+            'Run `migrate_status` to see applied / pending / drifted counts and which file drifted.',
+            'Never edit an applied migration. Write a new one that makes the correction.',
+            'For lock contention, wait for the other runner; `migrate deploy` is the no-prompt CI form.',
+        ],
+        properties: [],
+    },
+    TURBINE_E007: {
+        className: 'CircularRelationError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A `with` clause nested more than 10 relation levels deep.',
+        likelyCauses: [
+            'A back-reference walked in a loop: `user -> posts -> user -> posts -> …`.',
+            'A genuinely deep tree built by concatenating `with` fragments programmatically.',
+        ],
+        howToFix: [
+            'Read `err.path` for the exact trail that hit the cap.',
+            'Back-references are legal; the cap is on DEPTH, so re-root the query at the level you actually need instead of walking back up.',
+            'Split one very deep read into two shallower queries.',
+        ],
+        properties: ['path'],
+    },
+    TURBINE_E008: {
+        className: 'UniqueConstraintError',
+        retryable: false,
+        origin: 'wrapped-pg',
+        sqlstate: '23505',
+        whenThrown: 'A write violated a unique constraint or unique index.',
+        likelyCauses: [
+            'An insert of a value that already exists (the classic duplicate email).',
+            'An update that moved a row onto an existing key.',
+            'A race: two concurrent inserts of the same key, where a read-then-insert check passed in both.',
+        ],
+        howToFix: [
+            'Read `err.constraint`, `err.columns` and `err.table` and map the constraint to a user-facing message (HTTP 409).',
+            'Use `upsert`, or `createMany({ skipDuplicates: true })`, instead of check-then-insert.',
+            'Never branch on the message text; branch on `err.code` or `instanceof UniqueConstraintError`.',
+        ],
+        properties: ['constraint', 'columns', 'table'],
+    },
+    TURBINE_E009: {
+        className: 'ForeignKeyError',
+        retryable: false,
+        origin: 'wrapped-pg',
+        sqlstate: '23503',
+        whenThrown: 'A write violated a foreign key constraint.',
+        likelyCauses: [
+            'An insert or update pointing a foreign key at a parent row that does not exist.',
+            'A delete of a parent row that still has children, where the constraint is `NO ACTION` / `RESTRICT`.',
+            'Rows written in the wrong order inside a transaction.',
+        ],
+        howToFix: [
+            'Read `err.constraint` and `err.table` to see which side failed.',
+            'Use a nested write (`data: { child: { create: … } }`), which orders the inserts for you inside one transaction.',
+            'To delete a parent, delete or re-point its children first, or declare `ON DELETE CASCADE`.',
+        ],
+        properties: ['constraint', 'table'],
+    },
+    TURBINE_E010: {
+        className: 'NotNullViolationError',
+        retryable: false,
+        origin: 'wrapped-pg',
+        sqlstate: '23502',
+        whenThrown: 'A write left a NOT NULL column with no value.',
+        likelyCauses: [
+            'A required column omitted from `data`.',
+            'An explicit `null` written to a NOT NULL column.',
+            'A migration that added a NOT NULL column with no default while old code still inserts without it.',
+        ],
+        howToFix: [
+            'Read `err.column` and `err.table` for the exact column.',
+            'Supply the value, or give the column a database default.',
+            'For an existing table, add the column nullable, backfill, then `SET NOT NULL` (`turbine migrate create <name> --recipe backfill` scaffolds this).',
+        ],
+        properties: ['column', 'table'],
+    },
+    TURBINE_E011: {
+        className: 'CheckConstraintError',
+        retryable: false,
+        origin: 'wrapped-pg',
+        sqlstate: '23514',
+        whenThrown: 'A write violated a CHECK constraint.',
+        likelyCauses: [
+            'A value outside the range the constraint allows (a negative quantity, an out-of-set status string).',
+            'An atomic update operator (`decrement`) driving a column past a bound the constraint enforces.',
+        ],
+        howToFix: [
+            'Read `err.constraint` and `err.table`, then read the constraint body: `table_detail` reports named check constraints where the schema declares them.',
+            'Validate in application code before the write, so the user gets a field-level message rather than a 500.',
+        ],
+        properties: ['constraint', 'table'],
+    },
+    TURBINE_E012: {
+        className: 'DeadlockError',
+        retryable: true,
+        origin: 'wrapped-pg',
+        sqlstate: '40P01',
+        whenThrown: 'PostgreSQL detected a deadlock and cancelled this transaction.',
+        likelyCauses: [
+            'Two transactions locking the same rows in opposite order.',
+            'A long transaction holding a lock while doing unrelated work.',
+        ],
+        howToFix: [
+            'Retry. `err.isRetryable === true`, and `withRetry(fn)` / `db.$retry(fn)` retries exactly the errors carrying that flag.',
+            'Lock rows in a consistent order across code paths (for example, always ascending by primary key).',
+            'Shorten transactions: do the I/O and the computation outside, the writes inside.',
+        ],
+        properties: ['isRetryable', 'constraint'],
+    },
+    TURBINE_E013: {
+        className: 'SerializationFailureError',
+        retryable: true,
+        origin: 'wrapped-pg',
+        sqlstate: '40001',
+        whenThrown: 'A SERIALIZABLE or REPEATABLE READ transaction could not be serialized.',
+        likelyCauses: [
+            'Concurrent transactions at `Serializable` touching an overlapping row set.',
+            'A read-modify-write on a hot row under `Repeatable Read`.',
+        ],
+        howToFix: [
+            'Retry: this is the expected, designed outcome at these isolation levels, not a bug. `withRetry(fn)` / `db.$retry(fn)` handles it.',
+            'Where the operation is a pure increment, use an atomic update operator (`{ increment: 1 }`) instead of read-then-write.',
+            'Consider whether the transaction genuinely needs `Serializable`.',
+        ],
+        properties: ['isRetryable'],
+    },
+    TURBINE_E014: {
+        className: 'PipelineError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A non-transactional pipeline (`{ transactional: false }`) had at least one failing query.',
+        likelyCauses: ['One query in the batch failed while others succeeded, so there is no single error to throw.'],
+        howToFix: [
+            'Read `err.results`: one slot per query, each `{ status: "ok", value }` or `{ status: "error", error }`, with the real typed error inside.',
+            '`err.failedIndex` and `err.failedTag` point at the first failure.',
+            'If partial success is not acceptable, drop `transactional: false`; a transactional pipeline either fully succeeds or rolls back.',
+        ],
+        properties: ['results', 'failedIndex', 'failedTag'],
+    },
+    TURBINE_E015: {
+        className: 'OptimisticLockError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'An `optimisticLock` update found no row at the expected version.',
+        likelyCauses: [
+            'Another transaction updated the row between your read and your write. This is the mechanism working.',
+            'The version value passed was stale (held across a user interaction, or cached).',
+            'The row was deleted.',
+        ],
+        howToFix: [
+            'Re-read the row, re-apply the change to the fresh values, and write again. Do NOT blindly retry the same payload: the point of the check is that the underlying data moved.',
+            'Read `err.table`, `err.versionField` and `err.expectedVersion` to report the conflict to the user.',
+            'It is deliberately NOT flagged retryable: an automatic retry would defeat the guard.',
+        ],
+        properties: ['table', 'versionField', 'expectedVersion'],
+    },
+    TURBINE_E016: {
+        className: 'ExclusionConstraintError',
+        retryable: false,
+        origin: 'wrapped-pg',
+        sqlstate: '23P01',
+        whenThrown: 'A write violated an EXCLUDE constraint.',
+        likelyCauses: [
+            'Overlapping ranges where the constraint forbids overlap (the canonical booking / reservation clash).',
+        ],
+        howToFix: [
+            'Read `err.constraint` and `err.table`, then translate the clash into a domain message ("that slot is taken").',
+            'Query for the conflicting row with a range-overlap filter so the user can be shown WHAT it clashes with.',
+        ],
+        properties: ['constraint', 'table'],
+    },
+    TURBINE_E017: {
+        className: 'UnsupportedFeatureError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'This build cannot do that: a capability flag on the active dialect reports the feature unsupported, so Turbine refuses instead of emitting broken SQL.',
+        likelyCauses: [
+            'A Postgres-only feature on another engine: pgvector distance operators, `$listen` / `$notify`, RLS `sessionContext` / `$withSession`, `planCacheMode`.',
+            'NOT only a wrong-engine error, and reading it that way sends you looking in the wrong place. PostgreSQL raises it too: `relationLoadStrategy: "batched"` on a COMPOSITE-key relation refuses rather than loading a wrong set.',
+            'On PowDB: a nested `$transaction`, a re-entrant `$transaction`, or a feature above the connected engine version (the message carries the upgrade hint).',
+            '`limit` on `updateMany` / `deleteMany` through the prisma-compat adapter.',
+        ],
+        howToFix: [
+            'Read `err.feature` and `err.dialect`: together they say exactly what was refused and by which engine.',
+            'For a composite-key relation, use the default join plan rather than `batched`.',
+            'For a version gate, upgrade the engine to the version named in the hint.',
+        ],
+        properties: ['feature', 'dialect'],
+    },
+    TURBINE_E018: {
+        className: 'ReadOnlyError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A write was refused because the database or the connection is read-only.',
+        likelyCauses: [
+            '`reason: "snapshot"`: the client was opened `readonly: true`, or PowDB is serving a read-only snapshot.',
+            '`reason: "rbac"`: the connected role has no write privilege.',
+        ],
+        howToFix: [
+            'Read `err.reason` first: the two causes have nothing in common except the refusal.',
+            'For `snapshot`, open a writable client; the read-only one is doing its job.',
+            'For `rbac`, grant the role the privilege, or connect as one that has it.',
+        ],
+        properties: ['reason'],
+    },
+};
+/** Every code in the catalog, in code order. */
+export const CATALOGUED_ERROR_CODES = Object.keys(CATALOG).sort();
+/**
+ * Accept the spellings a caller actually types and return the canonical code,
+ * or `null`.
+ *
+ * A code arrives from a log line (`TURBINE_E003`), from a docs anchor (`e003`),
+ * from prose ("E3"), or as a bare number. All of them mean the same code, and
+ * refusing three of the four teaches an agent to give up rather than to
+ * normalize. What is NOT accepted is anything that resolves to no code at all:
+ * the caller gets `null` and a list, never a guess.
+ */
+export function normalizeErrorCode(input) {
+    const trimmed = input.trim().toUpperCase().replace(/\s+/g, '');
+    // `TURBINE_E003` / `TURBINE-E003` / `TURBINEE003` / `E003` / `E3` / `003` / `3`
+    const match = /^(?:TURBINE[_-]?)?E?(\d{1,4})$/.exec(trimmed);
+    if (!match)
+        return null;
+    const n = Number(match[1]);
+    if (!Number.isInteger(n) || n < 1)
+        return null;
+    const code = `TURBINE_E${String(n).padStart(3, '0')}`;
+    return Object.hasOwn(CATALOG, code) ? code : null;
+}
+/**
+ * The full explanation for a code, or `null` when the input names no code.
+ *
+ * `docsUrl` is read off a real {@link TurbineError} rather than formatted here,
+ * so it cannot drift from the URL on the error an agent actually caught.
+ */
+export function explainErrorCode(input) {
+    const code = normalizeErrorCode(input);
+    if (!code)
+        return null;
+    return { code, docsUrl: new TurbineError(code, '').docsUrl, ...CATALOG[code] };
+}

package/dist/cli/index.js

@@ -3862,8 +3862,9 @@ function showMcpHelp() {
     console.log(`  ${bold('Usage:')}`);
     console.log(`    npx turbine mcp ${dim('[options]')}`);
     newline();
-    console.log(`  Speaks newline-delimited JSON-RPC 2.0 on stdin/stdout and exposes`);
-    console.log(`  schema, migration status, doctor, EXPLAIN, and sample-row tools.`);
+    console.log(`  Speaks newline-delimited JSON-RPC 2.0 on stdin/stdout and exposes ten`);
+    console.log(`  read-only tools: schema, relation graph, join paths, migration status,`);
+    console.log(`  doctor, EXPLAIN, table stats, sample rows, and error lookup.`);
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}       Postgres connection string`);

package/dist/cli/mcp.d.ts

@@ -1,6 +1,6 @@
 import type { Readable, Writable } from 'node:stream';
-import pg from 'pg';
-import { type ColumnMetadata, type IndexMetadata, type RelationDef } from '../schema.js';
+import type { PgCompatPool } from '../pg-types.js';
+import { type ColumnMetadata, type IndexMetadata, type RelationDef, type SchemaMetadata } from '../schema.js';
 export interface McpServerOptions {
     url: string;
     schema: string;
@@ -24,12 +24,28 @@ export interface McpTransport {
      * reason Studio exports `handleRequest`). Production never sets it: the
      * server builds its own pool from `options.url`.
      */
-    pool?: pg.Pool;
+    pool?: PgCompatPool;
 }
 export interface McpServerHandle {
     dispose(): Promise<void>;
 }
 export declare function startMcpServer(options: McpServerOptions, transport?: McpTransport): McpServerHandle;
+/**
+ * Every SHORTEST relation chain from `from` to `to`, in deterministic order.
+ *
+ * Enumerated over BFS distances rather than by depth-first search with a visited
+ * set: only edges that advance the distance by exactly one are followed, so
+ * every chain returned is the same (minimum) length and no chain revisits a
+ * table. Two foreign keys to the same table therefore come back as two paths of
+ * equal length, which is the case the caller most needs to see, because picking
+ * one arbitrarily is how you silently join through `editor` when you meant
+ * `author`.
+ */
+export declare function shortestJoinPaths(metadata: SchemaMetadata, from: string, to: string, maxDepth: number, maxPaths: number, nodeBudget?: number): {
+    paths: RelationDef[][];
+    truncated: boolean;
+    exhausted: boolean;
+};
 interface ForeignKeyRow {
     /**
      * `pg_constraint.oid` as text. THE grouping key: a constraint NAME is unique