turbine-orm 0.65.0 → 0.66.0

package/dist/cjs/errors.js

@@ -1,16 +1,22 @@
 "use strict";
-/**
- * turbine-orm, Error types
- *
- * Typed errors with error codes for programmatic handling.
- * All Turbine errors extend TurbineError which includes a `code` property.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadOnlyError = exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.REDACTED_DETAIL = exports.TurbineError = exports.TurbineErrorCode = void 0;
+exports.registerClientErrorMessageMode = registerClientErrorMessageMode;
+exports.errorMessageModesDiverged = errorMessageModesDiverged;
+exports.runWithErrorMessageMode = runWithErrorMessageMode;
 exports.setErrorMessageMode = setErrorMessageMode;
 exports.getErrorMessageMode = getErrorMessageMode;
+exports.markValueBearingMessage = markValueBearingMessage;
 exports.describeTargetForMessage = describeTargetForMessage;
+exports.malformedConnectionStringMessage = malformedConnectionStringMessage;
 exports.wrapPgError = wrapPgError;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * turbine-orm, Error types
+ *
+ * Typed errors with error codes for programmatic handling.
+ * All Turbine errors extend TurbineError which includes a `code` property.
+ */
 /** Error codes for all Turbine errors */
 exports.TurbineErrorCode = {
     NOT_FOUND: 'TURBINE_E001',
@@ -85,6 +91,76 @@ class TurbineError extends Error {
 }
 exports.TurbineError = TurbineError;
 let errorMessageMode = 'safe';
+/**
+ * The mode in force for the operation currently executing, when a client has
+ * established one. See {@link runWithErrorMessageMode}.
+ */
+const errorMessageModeScope = new node_async_hooks_1.AsyncLocalStorage();
+/** The first mode a TurbineClient registered, used to detect divergence. */
+let firstRegisteredClientMode;
+let clientModesDiverged = false;
+/**
+ * The mode that applies right now: the scope a client established for this
+ * operation, else the process-wide default.
+ *
+ * The default is the fallback rather than the authority, which is the whole
+ * point. `errorMessageMode` is a module-level `let` that every TurbineClient
+ * constructor overwrote, so in a process with a primary client and an analytics
+ * or replica client, or a test harness building one client per suite, the LAST
+ * client constructed decided the mode for ALL of them, order-dependently. A
+ * client asking for `'safe'` could silently be running in `'verbose'`, which is
+ * the direction that leaks. (The dual ESM+CJS build makes it worse: the two
+ * copies hold separate `let`s.)
+ *
+ * An error constructed outside any client, directly or via
+ * {@link setErrorMessageMode}, still formats by the default, unchanged.
+ */
+function currentErrorMessageMode() {
+    return errorMessageModeScope.getStore() ?? errorMessageMode;
+}
+/**
+ * Register a client's configured mode and report whether per-operation scoping
+ * is now required.
+ *
+ * The gate is DIVERGENCE, not "has a client been built": while every client in
+ * the process agrees (the overwhelmingly common case, including every
+ * single-client app), the module default is already the right answer for all of
+ * them and no scope has to be established, so the query path pays exactly
+ * nothing. The moment two clients disagree, every client starts scoping, which
+ * is why this is read per call rather than latched per client.
+ *
+ * @internal Used by TurbineClient; not part of the public surface.
+ */
+function registerClientErrorMessageMode(mode) {
+    if (firstRegisteredClientMode === undefined)
+        firstRegisteredClientMode = mode;
+    else if (firstRegisteredClientMode !== mode)
+        clientModesDiverged = true;
+}
+/**
+ * Whether any two clients in this process have registered different modes, so
+ * the module default can no longer speak for all of them.
+ *
+ * @internal
+ */
+function errorMessageModesDiverged() {
+    return clientModesDiverged;
+}
+/**
+ * Run `fn` with `mode` in force for everything it does, awaits included.
+ *
+ * Establishing the scope around the call (rather than threading a mode
+ * parameter into every error constructor) is what makes this reachable at all:
+ * the mode-sensitive errors are built deep inside the query executor, the write
+ * builders and the nested-write engine, none of which are handed the client.
+ * The async context is captured when the operation's promise chain is created
+ * INSIDE this call, so every continuation of it resolves the same mode.
+ *
+ * @internal
+ */
+function runWithErrorMessageMode(mode, fn) {
+    return errorMessageModeScope.run(mode, fn);
+}
 /**
  * Set the global NotFoundError message mode. Called from the TurbineClient
  * constructor when `TurbineConfig.errorMessages` is provided.
@@ -110,9 +186,16 @@ let errorMessageMode = 'safe';
 function setErrorMessageMode(mode) {
     errorMessageMode = mode;
 }
-/** Returns the current NotFoundError message mode. Exported for tests. */
+/**
+ * Returns the NotFoundError message mode in effect right now.
+ *
+ * Called inside an operation issued through a client whose mode differs from
+ * another client's in the same process, that is THAT client's mode; anywhere
+ * else it is the process default {@link setErrorMessageMode} last set, which is
+ * what it has always returned. Exported for tests.
+ */
 function getErrorMessageMode() {
-    return errorMessageMode;
+    return currentErrorMessageMode();
 }
 /**
  * The marker left where a driver `detail` string was removed in 'safe' mode.
@@ -120,6 +203,69 @@ function getErrorMessageMode() {
  * assertions can match on it without hardcoding the wording.
  */
 exports.REDACTED_DETAIL = '[redacted by turbine errorMessages:"safe"]';
+/**
+ * Marks a driver error whose `message` (not only its `detail`) embeds row
+ * VALUES, so 'safe' mode has to withhold the message text too.
+ *
+ * Postgres splits this cleanly: `message` carries relation / constraint /
+ * column NAMES and `detail` carries the conflicting values, so redacting
+ * `detail` was enough. MySQL and SQL Server do not split it at all. mysql2's
+ * ER_DUP_ENTRY reads `Duplicate entry 'alice@example.com' for key
+ * 'users.email'` and SQL Server's 2627 ends `The duplicate key value is
+ * (alice@example.com).`, both on `message`, with no `detail` field anywhere.
+ * So `redactCauseForMode` took its "nothing value-bearing to remove" early
+ * return and handed back the driver error untouched, and the row value reached
+ * every log line, Sentry event and uncaught-rejection dump that renders the
+ * cause chain, in the mode whose entire job is to prevent exactly that.
+ *
+ * A flag rather than a code list, and set by the ENGINE that knows its own
+ * message grammar, for two reasons. It keeps Postgres byte-identical (pg never
+ * sets it, so its cause is returned exactly as before), and it puts "this
+ * engine's message embeds values" next to the code that reads that engine's
+ * messages instead of in a table here that would silently rot.
+ *
+ * `Symbol.for` so the ESM and CJS copies of this module agree on the key: a
+ * dual-package consumer can hand an error marked by one build to the other.
+ */
+const VALUE_BEARING_MESSAGE = Symbol.for('turbine.error.valueBearingMessage');
+/**
+ * Mark a driver error as carrying row values in its `message` (see
+ * {@link VALUE_BEARING_MESSAGE}). Called by the engine error augmenters for the
+ * exact driver codes whose message grammar embeds a value; every other code is
+ * left alone so nothing is withheld that did not need to be.
+ *
+ * Non-enumerable so the flag itself never shows up in a serialized error, and
+ * best-effort so a frozen or exotic driver error cannot turn a constraint
+ * violation into a TypeError.
+ */
+function markValueBearingMessage(err) {
+    if (!err || typeof err !== 'object')
+        return err;
+    try {
+        Object.defineProperty(err, VALUE_BEARING_MESSAGE, {
+            value: true,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+    }
+    catch {
+        /* a frozen driver error keeps its message; the Turbine message is still safe */
+    }
+    return err;
+}
+/**
+ * The replacement for a withheld driver message. The whole message goes, not a
+ * pattern-matched part of it: three engines with three grammars and no
+ * guarantee a future driver keeps either, so "withhold it" is the only rule
+ * that stays true. Nothing diagnostic is lost, the constraint/column/table
+ * names are already on the typed Turbine error as structured fields and in its
+ * own message, and `errorMessages: 'verbose'` returns the driver text in full.
+ */
+function redactedDriverMessage(code) {
+    const codePart = typeof code === 'string' && code.length > 0 ? ` (driver code ${code})` : '';
+    return `${exports.REDACTED_DETAIL}${codePart}: this engine reports the conflicting row values in the message text, so errorMessages:"safe" withholds it. Use errorMessages:"verbose" to see it.`;
+}
 /**
  * Postgres puts the CONFLICTING ROW VALUES in the `detail` field of a
  * constraint error, and nowhere else: `Key (email)=(alice@example.com) already
@@ -156,17 +302,29 @@ exports.REDACTED_DETAIL = '[redacted by turbine errorMessages:"safe"]';
  *
  * In 'verbose' mode the cause passes through untouched: that mode's documented
  * job is full-fidelity debugging.
+ *
+ * ENGINES WHOSE MESSAGE CARRIES THE VALUE. MySQL and SQL Server do not have a
+ * `detail` field at all and put the conflicting value in `message`, so the
+ * early return below used to hand the raw driver error straight back (see
+ * {@link markValueBearingMessage}). When the engine set that flag the clone
+ * also withholds `message`, `sqlMessage` (mysql2's copy, which is the field
+ * mysql2 formats `message` FROM, so leaving it would put the value straight
+ * back) and the message text embedded in the rendered `stack` string. The stack
+ * substitution is an exact replacement of the known message string, never a
+ * grammar guess, so the frames survive intact.
  */
 function redactCauseForMode(cause) {
-    if (errorMessageMode === 'verbose')
+    if (currentErrorMessageMode() === 'verbose')
         return cause;
     if (!cause || typeof cause !== 'object')
         return cause;
     const detail = cause.detail;
+    const hasDetail = typeof detail === 'string' && detail.length > 0;
+    const valueBearingMessage = cause[VALUE_BEARING_MESSAGE] === true;
     // Nothing value-bearing to remove: return the original object so the common
     // case (a non-pg cause, or a pg error without a detail) allocates nothing and
     // keeps object identity with what the driver threw.
-    if (typeof detail !== 'string' || detail.length === 0)
+    if (!hasDetail && !valueBearingMessage)
         return cause;
     try {
         const descriptors = Object.getOwnPropertyDescriptors(cause);
@@ -174,12 +332,36 @@ function redactCauseForMode(cause) {
         // non-writable `detail` would make the assignment throw in strict mode
         // (every module here is ESM, so it always would), and losing the cause is
         // worse than paying for one descriptor literal.
-        descriptors.detail = {
-            value: exports.REDACTED_DETAIL,
-            writable: true,
-            enumerable: descriptors.detail?.enumerable ?? true,
-            configurable: true,
-        };
+        if (hasDetail) {
+            descriptors.detail = {
+                value: exports.REDACTED_DETAIL,
+                writable: true,
+                enumerable: descriptors.detail?.enumerable ?? true,
+                configurable: true,
+            };
+        }
+        // The exact message strings to scrub out of the rendered stack, collected
+        // BEFORE the descriptors are overwritten.
+        const withheldTexts = [];
+        if (valueBearingMessage) {
+            const code = cause.code;
+            const replacement = redactedDriverMessage(code);
+            for (const key of ['message', 'sqlMessage']) {
+                const current = cause[key];
+                if (typeof current !== 'string' || current.length === 0)
+                    continue;
+                withheldTexts.push(current);
+                descriptors[key] = {
+                    value: replacement,
+                    writable: true,
+                    // `message` is non-enumerable on a native Error and mysql2's
+                    // `sqlMessage` is enumerable; keep whichever the driver chose so the
+                    // clone serializes with the same key set as the original.
+                    enumerable: descriptors[key]?.enumerable ?? false,
+                    configurable: true,
+                };
+            }
+        }
         // Brand check rather than `instanceof Error`, so a driver error thrown from
         // another realm (a worker, a bundled duplicate of pg) is still recognized.
         const isError = Object.prototype.toString.call(cause) === '[object Error]';
@@ -197,7 +379,14 @@ function redactCauseForMode(cause) {
         // own descriptor rather than having a lie written over it.
         const originalStack = cause.stack;
         if (typeof originalStack === 'string') {
-            descriptors.stack = { value: originalStack, writable: true, enumerable: false, configurable: true };
+            // V8 renders the stack as `<name>: <message>\n    at …`, so a withheld
+            // message is still sitting in it. Substitute the exact strings that were
+            // withheld (split/join, so a message repeated in a nested frame goes
+            // too); everything else, the frames included, is untouched.
+            let stackText = originalStack;
+            for (const text of withheldTexts)
+                stackText = stackText.split(text).join(exports.REDACTED_DETAIL);
+            descriptors.stack = { value: stackText, writable: true, enumerable: false, configurable: true };
         }
         else if (descriptors.stack && typeof descriptors.stack.get === 'function') {
             // An own accessor bound to the ORIGINAL receiver would return undefined
@@ -226,7 +415,7 @@ function redactCauseForMode(cause) {
  * connect/update failures which historically embedded the raw values.
  */
 function describeTargetForMessage(target) {
-    if (errorMessageMode === 'verbose') {
+    if (currentErrorMessageMode() === 'verbose') {
         try {
             return JSON.stringify(target);
         }
@@ -300,11 +489,11 @@ class NotFoundError extends TurbineError {
         let message = input.message;
         if (!message) {
             if (operation && table) {
-                const wherePart = where !== undefined ? ` matching where: ${renderWhereForMessage(where, errorMessageMode)}` : '';
+                const wherePart = where !== undefined ? ` matching where: ${renderWhereForMessage(where, currentErrorMessageMode())}` : '';
                 message = `[turbine] ${operation} on "${table}" found no record${wherePart}`;
             }
             else if (table) {
-                const wherePart = where !== undefined ? ` matching where ${renderWhereForMessage(where, errorMessageMode)}` : '';
+                const wherePart = where !== undefined ? ` matching where ${renderWhereForMessage(where, currentErrorMessageMode())}` : '';
                 message = `[turbine] No record found in "${table}"${wherePart}`;
             }
             else {
@@ -374,6 +563,31 @@ class ConnectionError extends TurbineError {
     }
 }
 exports.ConnectionError = ConnectionError;
+/**
+ * The message for "this engine's connection string could not be parsed".
+ *
+ * The one rule it exists to enforce: NEVER echo the value. A DSN carries a
+ * password, and the trigger for this error is a MALFORMED DSN, which is exactly
+ * when someone pastes the failure into a bug report, a CI log, or an error
+ * tracker. No redaction written against the URL grammar can be trusted on a
+ * string that just failed to parse as a URL, so the only safe amount of it to
+ * include is none: not the password, not the host, not a prefix.
+ *
+ * This mirrors the Postgres path (`assertUsableConnectionString` in client.ts),
+ * which reached the same conclusion first and stated the same reason; the
+ * engines used to interpolate the raw string instead, so SECURITY.md's claim of
+ * redaction "in all CLI error output" was true for one engine out of four.
+ * Shared rather than copied so the three engines cannot drift back apart.
+ *
+ * @param engine  the human engine label ("MySQL", "SQL Server", "PowDB").
+ * @param example a well-formed connection string for that engine, with a
+ *   placeholder password. Never derived from the caller's value.
+ */
+function malformedConnectionStringMessage(engine, example) {
+    return (`[turbine] The ${engine} connection string could not be parsed as a URL. Expected something like "${example}". ` +
+        '(Check for a missing "//", a stray quote copied out of a .env file, or a shell-truncated value.) ' +
+        'The value is not included here because it may contain a password.');
+}
 /** Thrown when a relation reference is invalid */
 class RelationError extends TurbineError {
     constructor(message) {
@@ -434,7 +648,7 @@ class UniqueConstraintError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -465,7 +679,7 @@ class ForeignKeyError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -495,7 +709,7 @@ class NotNullViolationError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -592,7 +806,7 @@ class CheckConstraintError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -621,7 +835,7 @@ class ExclusionConstraintError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }

package/dist/cjs/index-advisor.d.ts

@@ -46,7 +46,19 @@ export interface CreateIndexSqlOptions {
      * it must also carry the `-- turbine:no-transaction` directive.
      */
     concurrently?: boolean;
-    /** Emit `IF NOT EXISTS` (default true, required for idempotent no-transaction migrations). */
+    /**
+     * Emit `IF NOT EXISTS`. Defaults to true for the plain (in-transaction) form
+     * and FALSE when `concurrently` is set.
+     *
+     * `IF NOT EXISTS` matches on the index NAME, never on its validity, so over
+     * the INVALID index a failed concurrent build leaves behind it silently
+     * no-ops: the migration records as applied, the index doctor reported is
+     * still missing, and the documented remedy (DROP INDEX CONCURRENTLY, then
+     * rerun) is unreachable through `migrate up` because the rerun no-ops too.
+     * The concurrent form gets its idempotency from a preceding
+     * `DROP INDEX CONCURRENTLY IF EXISTS` instead; see
+     * {@link buildCreateIndexStatements}, which is what the CLI emits.
+     */
     ifNotExists?: boolean;
     /**
      * Emit a partial index `... WHERE <col> IS NOT NULL`. Only applied for a
@@ -63,6 +75,26 @@ export interface CreateIndexSqlOptions {
  * module topology-only.
  */
 export declare function buildCreateIndexSql(table: string, columns: string[], indexName: string, options?: CreateIndexSqlOptions): string;
+/**
+ * The statement SEQUENCE that builds one fix index and converges on a VALID
+ * index however many times it is rerun.
+ *
+ * A no-transaction migration is recorded only after ALL its statements succeed,
+ * so a mid-file failure leaves earlier indexes built and the migration
+ * unrecorded: a rerun must be safe. The old answer was `CREATE INDEX
+ * CONCURRENTLY IF NOT EXISTS`, which is safe but not CONVERGENT: a concurrent
+ * build that fails partway leaves an INVALID index with the right name, and
+ * every subsequent run skips it. Measured: the index was INVALID before the fix
+ * migration, `migrate up` reported 1 applied and 0 errors, and the index was
+ * still INVALID after.
+ *
+ * So the concurrent form drops first instead. `DROP INDEX CONCURRENTLY IF
+ * EXISTS` is a no-op on the first run (the index is missing, which is why
+ * doctor proposed it), and on a rerun it clears the corpse so the CREATE
+ * actually rebuilds. Neither statement takes a blocking lock, and both are
+ * legal only outside a transaction, which this file already is.
+ */
+export declare function buildCreateIndexStatements(table: string, columns: string[], indexName: string, options?: CreateIndexSqlOptions): string[];
 /** Build the matching `DROP INDEX` statement. `concurrently` requires no-transaction execution. */
 export declare function buildDropIndexSql(indexName: string, options?: {
     concurrently?: boolean;

package/dist/cjs/index-advisor.js

@@ -18,6 +18,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildCreateIndexSql = buildCreateIndexSql;
+exports.buildCreateIndexStatements = buildCreateIndexStatements;
 exports.buildDropIndexSql = buildDropIndexSql;
 exports.isProbeIndexed = isProbeIndexed;
 exports.doctorIndexName = doctorIndexName;
@@ -36,7 +37,12 @@ const schema_js_1 = require("./schema.js");
  */
 function buildCreateIndexSql(table, columns, indexName, options = {}) {
     const concurrently = options.concurrently ? 'CONCURRENTLY ' : '';
-    const ifNotExists = options.ifNotExists === false ? '' : 'IF NOT EXISTS ';
+    // Default differs by form: the plain statement runs inside a transaction and
+    // can never leave an INVALID corpse, so IF NOT EXISTS is a pure win there.
+    // The CONCURRENTLY form can, and IF NOT EXISTS would then match that corpse
+    // by name and skip the rebuild forever (see CreateIndexSqlOptions).
+    const wantIfNotExists = options.ifNotExists ?? !options.concurrently;
+    const ifNotExists = wantIfNotExists ? 'IF NOT EXISTS ' : '';
     const cols = columns.map(utils_js_1.quoteIdent).join(', ');
     let sql = `CREATE INDEX ${concurrently}${ifNotExists}${(0, utils_js_1.quoteIdent)(indexName)} ON ${(0, utils_js_1.quoteIdent)(table)} (${cols})`;
     if (options.partialNotNull && columns.length === 1 && columns[0] !== undefined) {
@@ -44,6 +50,31 @@ function buildCreateIndexSql(table, columns, indexName, options = {}) {
     }
     return `${sql};`;
 }
+/**
+ * The statement SEQUENCE that builds one fix index and converges on a VALID
+ * index however many times it is rerun.
+ *
+ * A no-transaction migration is recorded only after ALL its statements succeed,
+ * so a mid-file failure leaves earlier indexes built and the migration
+ * unrecorded: a rerun must be safe. The old answer was `CREATE INDEX
+ * CONCURRENTLY IF NOT EXISTS`, which is safe but not CONVERGENT: a concurrent
+ * build that fails partway leaves an INVALID index with the right name, and
+ * every subsequent run skips it. Measured: the index was INVALID before the fix
+ * migration, `migrate up` reported 1 applied and 0 errors, and the index was
+ * still INVALID after.
+ *
+ * So the concurrent form drops first instead. `DROP INDEX CONCURRENTLY IF
+ * EXISTS` is a no-op on the first run (the index is missing, which is why
+ * doctor proposed it), and on a rerun it clears the corpse so the CREATE
+ * actually rebuilds. Neither statement takes a blocking lock, and both are
+ * legal only outside a transaction, which this file already is.
+ */
+function buildCreateIndexStatements(table, columns, indexName, options = {}) {
+    const create = buildCreateIndexSql(table, columns, indexName, options);
+    if (!options.concurrently)
+        return [create];
+    return [buildDropIndexSql(indexName, { concurrently: true, ifExists: true }), create];
+}
 /** Build the matching `DROP INDEX` statement. `concurrently` requires no-transaction execution. */
 function buildDropIndexSql(indexName, options = {}) {
     const concurrently = options.concurrently ? 'CONCURRENTLY ' : '';

package/dist/cjs/introspect.d.ts

@@ -283,6 +283,54 @@ export declare function buildRelationsFromForeignKeys(foreignKeys: ForeignKeyEnt
  *     instead of silently dropping the relation.
  */
 export declare function addAutoManyToManyRelations(tableNames: Iterable<string>, foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnNamesByTable: Map<string, string[]>, relationsByTable: Map<string, Record<string, RelationDef>>, columnFieldsByTable?: Map<string, Set<string>>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueIndexColsByTable?: Map<string, string[][]>): void;
+/** Everything the catalog relation derivation reads. See {@link deriveCatalogRelations}. */
+export interface CatalogRelationInputs {
+    /** The introspected table set, post include/exclude filtering. */
+    tableNames: string[];
+    /** FK rows already grouped per constraint (one entry per declared constraint). */
+    foreignKeys: ForeignKeyEntry[];
+    /** Primary-key columns per table. */
+    pkByTable: Map<string, string[]>;
+    /** Column metadata per table (only name/field/tsType/pgType are read). */
+    columnsByTable: Map<string, Pick<ColumnMetadata, 'name' | 'field' | 'tsType' | 'pgType'>[]>;
+    /** UNIQUE-constraint column sets per table. */
+    uniqueByTable: Map<string, string[][]>;
+    /** Indexes per table, `definition` must be the raw `pg_indexes.indexdef`. */
+    indexesByTable: Map<string, IndexMetadata[]>;
+    /** Enum types in the schema, so an enum column is not mistaken for a json shadow. */
+    enums: Record<string, string[]>;
+    /** Referential actions keyed "<table>::<constraint>". Optional. */
+    fkActions?: Map<string, {
+        onDelete: ReferentialAction;
+        onUpdate: ReferentialAction;
+    }>;
+    /** Opt out of the unique-FK → `hasOne` flip (F2), see {@link IntrospectOptions.legacyToManyUniques}. */
+    legacyToManyUniques?: boolean;
+}
+/**
+ * One-stop relation derivation for every surface that reads a live PostgreSQL
+ * CATALOG: `turbine generate` (via {@link introspectPostgresCatalog}) and the
+ * MCP server, which introspects for itself because it cannot assume generated
+ * metadata exists.
+ *
+ * THE REASON THIS IS ONE FUNCTION and not two call sites: the pipeline it drives
+ * is `buildRelationsFromForeignKeys` (five parameters, two optional) plus
+ * `addAutoManyToManyRelations` (eight parameters, three optional), and every
+ * optional one CHANGES THE ANSWER while omitting it stays silently type-correct.
+ * Hand-mirroring them drifted exactly that way: MCP passed four arguments and so
+ * never received `uniqueSetsByTable`, which meant a UNIQUE foreign key produced
+ * `users.profile` (hasOne) under `turbine generate` and `users.profiles`
+ * (hasMany) under `turbine mcp`, against the same database. An MCP client
+ * following its own schema tool then queried `with: { profiles: true }` and got
+ * `TURBINE_E005 Unknown relation`. MCP also omitted `uniqueIndexColsByTable`,
+ * losing every auto-m2m relation through a Prisma-style PK-less junction. Adding
+ * an argument here now reaches both surfaces or neither.
+ *
+ * The engine introspectors (SQLite / MySQL / MSSQL) keep their own
+ * {@link deriveEngineRelations} because they deliberately do NOT do the
+ * unique-FK → `hasOne` flip.
+ */
+export declare function deriveCatalogRelations(inputs: CatalogRelationInputs): Map<string, Record<string, RelationDef>>;
 /**
  * One-stop relation derivation for the engine introspectors (SQLite / MySQL /
  * MSSQL): filters the FK list to the introspected table set, seeds the