turbine-orm 0.65.0 → 0.66.0

package/dist/cjs/cli/pii-predicate-guard.d.ts

@@ -0,0 +1,112 @@
+/**
+ * turbine-orm CLI: the PII predicate guard
+ *
+ * A pure leaf module, the same role `cli/rate-limit.ts` and `cli/destructive.ts`
+ * play: no I/O, no state, and no import from a sibling CLI module. The two
+ * local tools that compile CALLER-SUPPLIED `findMany` args, Studio's
+ * `/api/builder` and the MCP server's `explain_query`, both walk their args
+ * through this one walker before handing them to `QueryInterface`.
+ *
+ * It is one module because it was two. Studio and MCP each carried their own
+ * `assertNoPiiPredicates` with the same name and the same job, plus their own
+ * copy of `RELATION_FILTER_WRAPPERS` and `PII_GUARD_MAX_DEPTH`, and they drifted
+ * exactly the way two hand-synced implementations do: a hole opened in one and
+ * was present in the other, and closing it in one place would have left the
+ * other open. Both tools now share the walk and differ only in the two things
+ * that genuinely differ, WHY a column is hidden and HOW a refusal is thrown,
+ * which arrive as callbacks on {@link PiiGuardHost}.
+ *
+ * WHAT IT IS FOR. Redacting the cells of a hidden column is not enough on its
+ * own: `where: { email: { startsWith: 'a' } }` answers a question ABOUT the
+ * hidden value, and so does an `isNull`, an `orderBy`, a `cursor` (which
+ * compiles to a `"email" > $1` range comparison, i.e. a clean binary search over
+ * the byte range), and, more weakly, a `distinct` (the cardinality of the hidden
+ * values). `select` is deliberately NOT refused: it returns values, and the
+ * values are redacted on the way out.
+ *
+ * WHY IT FAILS CLOSED. Every branch here answers one question, "can this shape
+ * be shown not to name a hidden column", and the honest answer for a shape the
+ * walker does not recognize is no. Waving unrecognized shapes through is what
+ * produced the pick-row hole (`orderBy: { rel: { pick: {...}, by: 'phone' } }`):
+ * `pick` is neither a combinator nor a relation nor a column of the target, so
+ * the walker checked the literal string `pick` against the column list, found
+ * nothing, and moved on, while `by` named the hidden column in its VALUE rather
+ * than its key. The specific keys are handled below, but the FAIL-CLOSED rule is
+ * the actual fix: an unrecognized key carrying a structure is refused, so the
+ * next orderBy shape the query builder grows is refused here until someone
+ * teaches this walker about it. Over-refusing is a usability bug; under-refusing
+ * is a data leak.
+ */
+import type { SchemaMetadata, TableMetadata } from '../schema.js';
+/**
+ * Relation-filter wrappers whose body is a clause against the relation's target.
+ *
+ * THREE copies of this list exist in the tree, and they have to agree: a wrapper
+ * the compiler understands and this guard does not is a wrapper that reaches the
+ * builder unguarded.
+ *
+ *   1. this one, the only NAMED definition;
+ *   2. `query/where-compile.ts`, inlined as `'some' in x || 'every' in x || …`;
+ *   3. `prisma-compat.ts`, SPLIT across `RELATION_QUANTIFIERS`
+ *      (`some`/`every`/`none`) and two inline `k === 'is' || k === 'isNot'`
+ *      tests, which is the copy most likely to drift because half of it does
+ *      not look like a list at all.
+ *
+ * Copy 2 belongs to the SQL compiler and cannot import this one (a query-path
+ * module must not depend on `cli/`), so the deduplication has to go the other
+ * way: the list wants to live in `query/filters.ts` and be imported here, the
+ * way {@link COLUMN_REF_OPERATORS} above now is. Until that export exists this
+ * comment is the only thing holding the three in step.
+ */
+export declare const RELATION_FILTER_WRAPPERS: readonly ["some", "none", "every", "is", "isNot"];
+/**
+ * Recursion bound for the guard walk.
+ *
+ * This number is NOT the security boundary: reaching it REFUSES the request
+ * (`refuseDepth`). It only bounds the walk on a pathological payload. Returning
+ * quietly at the cap, which both copies of this walker once did, meant padding a
+ * payload with enough nested `NOT` wrappers walked the guard off the end of its
+ * own recursion and then handed the untouched predicate to the builder. It sits
+ * well above the query builder's own depth-10 relation cap
+ * (`CircularRelationError`) and far above any hand-composed boolean nesting, so
+ * nothing the builder would accept is refused here for depth alone.
+ */
+export declare const PII_GUARD_MAX_DEPTH = 32;
+/**
+ * The two things Studio and the MCP server genuinely do differently, plus the
+ * schema the walk resolves relation targets against.
+ *
+ * `hiddenReason` is the whole policy: Studio hides code-first `pii` tags unless
+ * `--show-pii`, the MCP server hides those AND secret-looking column names. The
+ * `refuse*` callbacks throw, they never return, because the two tools raise
+ * different error types (`ValidationError` vs a JSON-RPC error).
+ */
+export interface PiiGuardHost {
+    /** Schema the walk resolves relation targets against. */
+    metadata: SchemaMetadata;
+    /**
+     * Why `column` on `table` may not appear in a predicate, or `null` when it
+     * may. The string is interpolated into the refusal message, so it reads as a
+     * predicate: `"is PII-tagged and redacted"`.
+     */
+    hiddenReason(table: TableMetadata, column: string): string | null;
+    /** Refuse: the query names a hidden column. Must throw. */
+    refuseColumn(table: TableMetadata, column: string, reason: string): never;
+    /** Refuse: the query is nested past {@link PII_GUARD_MAX_DEPTH}. Must throw. */
+    refuseDepth(maxDepth: number): never;
+    /**
+     * Refuse: `key` on `table` is a query shape this walker does not recognize, so
+     * it cannot be shown not to name a hidden column. Must throw.
+     */
+    refuseShape(table: TableMetadata, key: string): never;
+}
+/**
+ * Walk one query level (`findMany` args, or one `with` entry's options) and
+ * refuse it if it filters, sorts, pages, or de-duplicates on a hidden column, or
+ * if it carries a shape that cannot be proven not to.
+ *
+ * `rootTable` may be `undefined` (the caller's table name did not resolve); the
+ * walk then does nothing, because the builder rejects the query a moment later
+ * by name and there is no metadata here to judge it against.
+ */
+export declare function assertNoPiiPredicates(args: Record<string, unknown>, rootTable: TableMetadata | undefined, host: PiiGuardHost): void;

package/dist/cjs/cli/pii-predicate-guard.js

@@ -0,0 +1,390 @@
+"use strict";
+/**
+ * turbine-orm CLI: the PII predicate guard
+ *
+ * A pure leaf module, the same role `cli/rate-limit.ts` and `cli/destructive.ts`
+ * play: no I/O, no state, and no import from a sibling CLI module. The two
+ * local tools that compile CALLER-SUPPLIED `findMany` args, Studio's
+ * `/api/builder` and the MCP server's `explain_query`, both walk their args
+ * through this one walker before handing them to `QueryInterface`.
+ *
+ * It is one module because it was two. Studio and MCP each carried their own
+ * `assertNoPiiPredicates` with the same name and the same job, plus their own
+ * copy of `RELATION_FILTER_WRAPPERS` and `PII_GUARD_MAX_DEPTH`, and they drifted
+ * exactly the way two hand-synced implementations do: a hole opened in one and
+ * was present in the other, and closing it in one place would have left the
+ * other open. Both tools now share the walk and differ only in the two things
+ * that genuinely differ, WHY a column is hidden and HOW a refusal is thrown,
+ * which arrive as callbacks on {@link PiiGuardHost}.
+ *
+ * WHAT IT IS FOR. Redacting the cells of a hidden column is not enough on its
+ * own: `where: { email: { startsWith: 'a' } }` answers a question ABOUT the
+ * hidden value, and so does an `isNull`, an `orderBy`, a `cursor` (which
+ * compiles to a `"email" > $1` range comparison, i.e. a clean binary search over
+ * the byte range), and, more weakly, a `distinct` (the cardinality of the hidden
+ * values). `select` is deliberately NOT refused: it returns values, and the
+ * values are redacted on the way out.
+ *
+ * WHY IT FAILS CLOSED. Every branch here answers one question, "can this shape
+ * be shown not to name a hidden column", and the honest answer for a shape the
+ * walker does not recognize is no. Waving unrecognized shapes through is what
+ * produced the pick-row hole (`orderBy: { rel: { pick: {...}, by: 'phone' } }`):
+ * `pick` is neither a combinator nor a relation nor a column of the target, so
+ * the walker checked the literal string `pick` against the column list, found
+ * nothing, and moved on, while `by` named the hidden column in its VALUE rather
+ * than its key. The specific keys are handled below, but the FAIL-CLOSED rule is
+ * the actual fix: an unrecognized key carrying a structure is refused, so the
+ * next orderBy shape the query builder grows is refused here until someone
+ * teaches this walker about it. Over-refusing is a usability bug; under-refusing
+ * is a data leak.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PII_GUARD_MAX_DEPTH = exports.RELATION_FILTER_WRAPPERS = void 0;
+exports.assertNoPiiPredicates = assertNoPiiPredicates;
+const filters_js_1 = require("../query/filters.js");
+const utils_js_1 = require("../query/utils.js");
+/**
+ * Relation-filter wrappers whose body is a clause against the relation's target.
+ *
+ * THREE copies of this list exist in the tree, and they have to agree: a wrapper
+ * the compiler understands and this guard does not is a wrapper that reaches the
+ * builder unguarded.
+ *
+ *   1. this one, the only NAMED definition;
+ *   2. `query/where-compile.ts`, inlined as `'some' in x || 'every' in x || …`;
+ *   3. `prisma-compat.ts`, SPLIT across `RELATION_QUANTIFIERS`
+ *      (`some`/`every`/`none`) and two inline `k === 'is' || k === 'isNot'`
+ *      tests, which is the copy most likely to drift because half of it does
+ *      not look like a list at all.
+ *
+ * Copy 2 belongs to the SQL compiler and cannot import this one (a query-path
+ * module must not depend on `cli/`), so the deduplication has to go the other
+ * way: the list wants to live in `query/filters.ts` and be imported here, the
+ * way {@link COLUMN_REF_OPERATORS} above now is. Until that export exists this
+ * comment is the only thing holding the three in step.
+ */
+exports.RELATION_FILTER_WRAPPERS = ['some', 'none', 'every', 'is', 'isNot'];
+const RELATION_FILTER_WRAPPER_SET = new Set(exports.RELATION_FILTER_WRAPPERS);
+/**
+ * Recursion bound for the guard walk.
+ *
+ * This number is NOT the security boundary: reaching it REFUSES the request
+ * (`refuseDepth`). It only bounds the walk on a pathological payload. Returning
+ * quietly at the cap, which both copies of this walker once did, meant padding a
+ * payload with enough nested `NOT` wrappers walked the guard off the end of its
+ * own recursion and then handed the untouched predicate to the builder. It sits
+ * well above the query builder's own depth-10 relation cap
+ * (`CircularRelationError`) and far above any hand-composed boolean nesting, so
+ * nothing the builder would accept is refused here for depth alone.
+ */
+exports.PII_GUARD_MAX_DEPTH = 32;
+/**
+ * Query-level arg keys whose value is legitimately an object or an array.
+ *
+ * Everything else on `FindManyArgs` / `WithOptions` is a scalar (`limit`,
+ * `offset`, `take`, `timeout`, `relationLoadStrategy`, `stableRelationOrder`,
+ * `warnOnUnlimited`, `forceCustomPlan`, `includePii`), so an object-valued key
+ * outside this set is a structure the walker has never seen and is refused.
+ * `includePii` / `skipGlobalFilters` are gated by the `UNSAFE` symbol, which
+ * `JSON.parse` cannot produce, so neither can be forged over the wire.
+ */
+const LEVEL_OBJECT_KEYS = new Set([
+    'where',
+    'orderBy',
+    'cursor',
+    'distinct',
+    'with',
+    'select',
+    'omit',
+    'skipGlobalFilters',
+]);
+/**
+ * Every key a pick-row ordering (`RelationPickOrderBy`) may carry. Used only to
+ * recognize the shape, mirroring `isRelationPickOrderBy` in `query/filters.ts`,
+ * which is what the builder itself branches on.
+ */
+const RELATION_PICK_KEYS = new Set(['pick', 'by', 'direction', 'nulls', 'plan']);
+/** An object or array value, i.e. something that can carry a nested name. */
+function isObjectLike(value) {
+    return value !== null && typeof value === 'object';
+}
+/** A non-array object: the shape every clause / spec node in the arg tree uses. */
+function isPlainObject(value) {
+    return isObjectLike(value) && !Array.isArray(value);
+}
+/**
+ * The depth one element of an array is visited at: unchanged for an ordinary
+ * element, one level deeper for an element that is ITSELF an array.
+ *
+ * The distinction is the whole fix, and it is not the same as "arrays cost a
+ * level". Both array branches below deliberately did not increment, and the
+ * reason was right: an `OR: [a, b, c]` (or a Prisma-style `orderBy: [{…}, {…}]`)
+ * is ONE logical level however long the list is, and its elements are SIBLINGS,
+ * each visited from the same stack frame, so width costs no recursion. Charging
+ * a level per element would have refused a legal 40-condition `OR`.
+ *
+ * What that missed is that the array branch also recurses into an element that
+ * is another ARRAY, and there the frames DO stack. `{"orderBy":[[[…]]]}` walks
+ * one frame per bracket with the logical depth pinned at its starting value, so
+ * the cap never fires: measured, 1,000 levels (a 2 KB body) was allowed outright
+ * and 10,000 (20 KB) raised `RangeError: Maximum call stack size exceeded`
+ * inside the guard. That is the exact class the module header says was fixed by
+ * making the cap REFUSE instead of returning quietly, reintroduced through the
+ * one branch that never reaches the cap.
+ *
+ * So: nesting counts, iteration does not. No legal arg shape puts an array
+ * directly inside an array (`orderBy` is `X | X[]`, the combinators take `X[]`),
+ * so nothing the builder would accept is refused for depth by this rule, and it
+ * needs no second budget to reason about, the existing cap now simply sees the
+ * nesting it was already meant to be counting.
+ */
+function arrayItemDepth(item, depth) {
+    return Array.isArray(item) ? depth + 1 : depth;
+}
+/**
+ * Is this relation-keyed value a pick-row ordering rather than a relation filter
+ * or a to-one column ordering?
+ *
+ * Deliberately a MIRROR of `isRelationPickOrderBy` (`query/filters.ts`), down to
+ * requiring `pick` to be an object carrying `orderBy`: the builder branches on
+ * that predicate, so a guard that answered it differently would guard a
+ * different query than the one that runs. It matters in both directions. A
+ * target table with columns literally named `pick` and `by` produces
+ * `{ rel: { pick: 'asc', by: 'desc' } }`, which is an ordinary two-column to-one
+ * ordering to the builder and must be walked as two COLUMN names here. And a
+ * value with an object-valued `pick` that is not a full pick spec is not
+ * special-cased at all: it falls through to the fail-closed branch.
+ */
+function isPickShape(node) {
+    if (!Object.hasOwn(node, 'pick') || !Object.hasOwn(node, 'by'))
+        return false;
+    const pick = node.pick;
+    if (!isPlainObject(pick) || !Object.hasOwn(pick, 'orderBy'))
+        return false;
+    return Object.keys(node).every((key) => RELATION_PICK_KEYS.has(key));
+}
+/**
+ * Walk one query level (`findMany` args, or one `with` entry's options) and
+ * refuse it if it filters, sorts, pages, or de-duplicates on a hidden column, or
+ * if it carries a shape that cannot be proven not to.
+ *
+ * `rootTable` may be `undefined` (the caller's table name did not resolve); the
+ * walk then does nothing, because the builder rejects the query a moment later
+ * by name and there is no metadata here to judge it against.
+ */
+function assertNoPiiPredicates(args, rootTable, host) {
+    const assertWithinDepth = (depth) => {
+        if (depth <= exports.PII_GUARD_MAX_DEPTH)
+            return;
+        host.refuseDepth(exports.PII_GUARD_MAX_DEPTH);
+    };
+    /**
+     * Check one caller-supplied name against `table`. A predicate may name a
+     * column by its camelCase field OR by its real column name; both compile to
+     * the same SQL, so both have to resolve to the same check.
+     */
+    const checkColumnName = (table, name) => {
+        const column = (0, utils_js_1.ownLookup)(table.columnMap, name) ?? name;
+        const reason = host.hiddenReason(table, column);
+        if (reason)
+            host.refuseColumn(table, column, reason);
+    };
+    /**
+     * A column-keyed operator object (`{ gt: 5 }`, `{ sort, nulls }`, a JSON path,
+     * a vector distance) holds values, not names, with ONE exception: the
+     * comparison operators also accept `{ col: 'otherField' }`, which compiles to
+     * a column-to-column comparison in the same table. Scan for that.
+     *
+     * The operator list is IMPORTED from `query/filters.ts` rather than copied:
+     * that is the set the SQL compiler itself branches on, and a guard that
+     * disagreed with it would be guarding a different query than the one that
+     * runs. A copy that drifted short by one operator reopens the operand-position
+     * channel this scan exists to close, silently.
+     */
+    const checkColumnRefs = (table, operatorNode) => {
+        for (const opKey of filters_js_1.COLUMN_REF_OPERATORS) {
+            const operand = (0, utils_js_1.ownLookup)(operatorNode, opKey);
+            if (!isPlainObject(operand))
+                continue;
+            const ref = operand.col;
+            if (typeof ref === 'string')
+                checkColumnName(table, ref);
+        }
+    };
+    /**
+     * One `[key, value]` entry of a clause node.
+     *
+     * `scope` says which key vocabulary applies. `'clause'` is a where / orderBy /
+     * cursor object resolved against a table: combinators, relation names, column
+     * names. `'relation'` is the value SITTING UNDER a relation name, which also
+     * accepts the cardinality wrappers, and is where the fail-closed rule bites:
+     * an unrecognized key carrying a structure is refused rather than checked as
+     * if it were a column name and waved through when it is not one.
+     *
+     * `_count` needs no case of its own. It is walked as a column name, which
+     * clears it on every real schema, refuses it on the pathological one that has
+     * a hidden column with that name, and, since its value is a bare direction
+     * token, never reaches the fail-closed branch.
+     */
+    const visitEntry = (table, key, value, depth, scope) => {
+        if (key === 'AND' || key === 'OR' || key === 'NOT') {
+            visitClause(value, table, depth + 1);
+            return;
+        }
+        // `{ user: { is: {...} } }` / `{ posts: { some: {...} } }`: the wrapper's
+        // body is a clause against the SAME target. Handing the wrapper to the
+        // column walker instead walked `is` as if it were a column of the target,
+        // so the inner clause was never visited at all.
+        if (scope === 'relation' && RELATION_FILTER_WRAPPER_SET.has(key)) {
+            visitClause(value, table, depth + 1);
+            return;
+        }
+        const relation = (0, utils_js_1.ownLookup)(table.relations, key);
+        if (relation) {
+            const target = (0, utils_js_1.ownLookup)(host.metadata.tables, relation.to);
+            // A relation whose target is not in the metadata cannot be walked, and a
+            // walk that cannot see the target cannot clear it.
+            if (!target)
+                host.refuseShape(table, key);
+            visitRelationValue(value, target, depth + 1);
+            return;
+        }
+        checkColumnName(table, key);
+        if (!isObjectLike(value))
+            return;
+        const column = (0, utils_js_1.ownLookup)(table.columnMap, key) ?? key;
+        // FAIL CLOSED. Under a relation, a key that is neither a known relation-value
+        // keyword nor a real column of the target, yet carries an object or array, is
+        // a shape this walker has never been taught. At clause scope the same key is
+        // rejected by the builder by name (E003, "unknown column"), which keeps a
+        // plain typo reading like a typo.
+        if (scope === 'relation' && !table.allColumns.includes(column))
+            host.refuseShape(table, key);
+        if (isPlainObject(value))
+            checkColumnRefs(table, value);
+    };
+    /** A where / orderBy / cursor object (or a Prisma-style array of them). */
+    const visitClause = (node, table, depth) => {
+        assertWithinDepth(depth);
+        if (!table || !isObjectLike(node))
+            return;
+        // `orderBy` accepts a Prisma-style array of single-key objects, and so does
+        // a `NOT` list. ITERATING that list carries no nesting, so a list of any
+        // WIDTH stays at one depth. NESTING it does: see arrayItemDepth.
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visitClause(item, table, arrayItemDepth(item, depth));
+            return;
+        }
+        for (const [key, value] of Object.entries(node))
+            visitEntry(table, key, value, depth, 'clause');
+    };
+    /** The value sitting under a relation name, in a where OR an orderBy. */
+    const visitRelationValue = (value, target, depth) => {
+        assertWithinDepth(depth);
+        if (!target || !isObjectLike(value))
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visitRelationValue(item, target, arrayItemDepth(item, depth));
+            return;
+        }
+        const node = value;
+        // Pick-row ordering: `{ rel: { pick: { orderBy, where }, by, … } }`. THREE
+        // column-naming positions, none of them a key of the relation value, which
+        // is why key-only walking never saw any of them: `pick.orderBy` and
+        // `pick.where` are clauses two levels down, and `by` names the target column
+        // whose value the parents are sorted by, in its VALUE.
+        if (isPickShape(node)) {
+            visitPick(node.pick, target, depth + 1);
+            visitPickBy(node.by, target);
+            // `direction` / `nulls` / `plan` are single tokens. A token position
+            // holding a structure is not a token, and is refused rather than assumed
+            // inert.
+            for (const key of ['direction', 'nulls', 'plan']) {
+                if (isObjectLike((0, utils_js_1.ownLookup)(node, key)))
+                    host.refuseShape(target, key);
+            }
+            return;
+        }
+        for (const [key, member] of Object.entries(node))
+            visitEntry(target, key, member, depth, 'relation');
+    };
+    /** `pick: { orderBy, where }`: both are clauses against the relation target. */
+    const visitPick = (value, target, depth) => {
+        assertWithinDepth(depth);
+        if (!isPlainObject(value))
+            return;
+        for (const [key, member] of Object.entries(value)) {
+            if (key === 'orderBy' || key === 'where') {
+                visitClause(member, target, depth);
+                continue;
+            }
+            if (isObjectLike(member))
+                host.refuseShape(target, `pick.${key}`);
+        }
+    };
+    /**
+     * `by`: the value read off the picked row. Either a bare target column name,
+     * or `{ field, path }` extracting a JSON path out of a json/jsonb target
+     * column. Both name a column in the VALUE position, which is why key-only
+     * checking never saw them.
+     */
+    const visitPickBy = (value, target) => {
+        if (typeof value === 'string') {
+            checkColumnName(target, value);
+            return;
+        }
+        if (isPlainObject(value)) {
+            const field = value.field;
+            if (typeof field === 'string') {
+                checkColumnName(target, field);
+                return;
+            }
+            host.refuseShape(target, 'by');
+        }
+        // Any other `by` (number, null, array) names no column and the builder
+        // rejects the shape.
+    };
+    /** Field-name lists (`distinct`) name columns directly rather than in a clause. */
+    const visitFieldList = (value, table) => {
+        if (!Array.isArray(value))
+            return;
+        for (const field of value) {
+            if (typeof field === 'string')
+                checkColumnName(table, field);
+        }
+    };
+    const visitLevel = (level, table, depth) => {
+        assertWithinDepth(depth);
+        if (!table)
+            return;
+        visitClause(level.where, table, depth);
+        visitClause(level.orderBy, table, depth);
+        // `cursor` is a flat `{ field: value }` seek key that the builder turns into
+        // a WHERE range comparison against the sort key, so it reads exactly like a
+        // where on the same column.
+        visitClause(level.cursor, table, depth);
+        visitFieldList(level.distinct, table);
+        // FAIL CLOSED one level up: a query-level arg this walker does not know,
+        // carrying a structure, could name columns the same way `orderBy` does.
+        for (const [key, value] of Object.entries(level)) {
+            if (LEVEL_OBJECT_KEYS.has(key))
+                continue;
+            if (isObjectLike(value))
+                host.refuseShape(table, key);
+        }
+        const withClause = level.with;
+        if (!isPlainObject(withClause))
+            return;
+        for (const [relName, spec] of Object.entries(withClause)) {
+            const relation = (0, utils_js_1.ownLookup)(table.relations, relName);
+            // `_count` and an unknown relation name are not levels; the builder
+            // decides whether they are valid, and neither carries a column name.
+            if (!relation || spec === true || !isPlainObject(spec))
+                continue;
+            visitLevel(spec, (0, utils_js_1.ownLookup)(host.metadata.tables, relation.to), depth + 1);
+        }
+    };
+    visitLevel(args, rootTable, 0);
+}

package/dist/cjs/cli/prisma-resolve.js

@@ -62,13 +62,24 @@ function tableCandidates(modelName) {
 // ---------------------------------------------------------------------------
 // Field/column resolution
 // ---------------------------------------------------------------------------
-/** The database column a Prisma field maps to (`@map` wins, else the field name). */
+/**
+ * The database column a Prisma field maps to (`@map` wins, else the field name).
+ *
+ * BOTH `@map("legacy_name")` and `@map(name: "legacy_name")` are valid Prisma
+ * and mean the same thing; the model-level `@@map` handler in prisma-schema.ts
+ * has always accepted both. Reading only the positional form here discarded the
+ * column name on every named-argument field, and the resolver then fell back to
+ * the Prisma FIELD name, which in a legacy database is frequently a real column
+ * of its own: the resolution reported CLEAN while every read returned another
+ * column's data, every write landed in the wrong column, and the Prisma-owned
+ * column was never touched again.
+ */
 function fieldColumn(model, fieldName) {
     const f = model.fields.find((x) => x.name === fieldName);
     if (!f)
         return fieldName;
     const mapAttr = f.attrs.find((a) => a.name === 'map');
-    const arg = mapAttr?.args.find((a) => a.key === undefined);
+    const arg = mapAttr?.args.find((a) => a.key === undefined || a.key === 'name');
     return arg?.kind === 'string' && arg.value ? arg.value : f.name;
 }
 /** True when a field's type names a parsed model (so it is a relation/object field). */
@@ -171,9 +182,51 @@ function resolvePrismaSchema(ast, schema, options = {}) {
         if (!noDb && r.status === 'resolved' && r.turbineName)
             result.map.enums[en.name] = r.turbineName;
     }
+    flagDuplicateTables(result);
     result.hasUnresolved = computeHasUnresolved(result);
     return result;
 }
+/**
+ * Two Prisma models must not resolve to ONE table.
+ *
+ * Nothing downstream can survive it: `prisma-compat` builds its
+ * table-to-model index last-writer-wins, so nested relation reshaping silently
+ * picks whichever model happened to be declared last, and the two models'
+ * field maps are different. The two ways to get here are a `@@map` typo (two
+ * models pointing at the same table by accident) and a genuine multi-schema
+ * setup, where `@@schema` is what distinguishes `auth.users` from
+ * `public.users` and this parser does not represent it.
+ *
+ * Both models are marked UNRESOLVED and dropped from the map. Guessing between
+ * them is not available: the resolver has no evidence for which one the call
+ * site meant, and a wrong pick reads and writes another model's columns.
+ */
+function flagDuplicateTables(result) {
+    const byTable = new Map();
+    for (const m of result.models) {
+        if (m.status !== 'resolved' || !m.table)
+            continue;
+        const list = byTable.get(m.table);
+        if (list)
+            list.push(m);
+        else
+            byTable.set(m.table, [m]);
+    }
+    for (const [table, models] of byTable) {
+        if (models.length < 2)
+            continue;
+        const names = models.map((m) => m.prismaName).join(', ');
+        for (const m of models) {
+            m.status = 'unresolved';
+            m.reason =
+                `${models.length} models resolve to table "${table}" (${names}). ` +
+                    `The compat layer indexes relation targets BY TABLE, so it cannot tell them apart. ` +
+                    `Fix the @@map, or, if these models live in different Postgres schemas (@@schema), ` +
+                    `run migrate-from-prisma once per schema: this parser resolves one namespace at a time.`;
+            delete result.map.models[m.prismaName];
+        }
+    }
+}
 // ---------------------------------------------------------------------------
 // Per-construct resolvers
 // ---------------------------------------------------------------------------
@@ -336,8 +389,26 @@ function resolveRelation(model, fieldName, targetModelName, isList, modelTable,
             const fk = Array.isArray(def.foreignKey) ? def.foreignKey : [def.foreignKey];
             return [...fk].sort().join(',') === want;
         });
-        if (byFk.length > 0)
-            picked = byFk;
+        if (byFk.length === 0) {
+            // The schema PINNED the foreign-key columns and no relation in the
+            // database uses them. That is positive evidence of DISAGREEMENT, not a
+            // missing hint: falling through to "there is one candidate, take it" bound
+            // the field to an unrelated relation and reported the whole model clean.
+            // The shape is common: `relationMode = "prisma"` declares relations Prisma
+            // enforces in the client with no database constraint behind them, so a
+            // model can name FK columns that the catalog has never heard of, while a
+            // DIFFERENT column on the same table does carry a real FK. `include:
+            // { editor: true }` then returned the author.
+            return {
+                ...base,
+                reason: `@relation(fields: [${fkColumns.join(', ')}]) names foreign-key column(s) that no relation on table ` +
+                    `"${tableMeta.name}" uses. Candidates in the database: ` +
+                    `${candidates.map((d) => `${d.name} (${Array.isArray(d.foreignKey) ? d.foreignKey.join('+') : d.foreignKey})`).join(', ') || '(none)'}. ` +
+                    `If this relation is enforced only in Prisma (relationMode = "prisma"), the database has no foreign key ` +
+                    `to resolve it against; add one, or map this field by hand.`,
+            };
+        }
+        picked = byFk;
     }
     if (picked.length === 1) {
         const def = picked[0];

package/dist/cjs/cli/prisma-schema.d.ts

@@ -32,6 +32,16 @@ export interface PrismaAttrArg {
 export interface PrismaAttr {
     /** Attribute name without the leading `@`/`@@` (e.g. `map`, `relation`, `id`, `unique`). */
     name: string;
+    /**
+     * The part after the dot in a namespaced attribute: `VarChar` for
+     * `@db.VarChar(320)`, `Text` for `@db.Text`.
+     *
+     * Kept because the head alone throws the native type away, and the arguments
+     * do not carry it back: `@db.VarChar(320)` retained only `320`, and
+     * `@db.Text` retained nothing at all, so `Text`, `Uuid`, `Money`, and
+     * `Citext` were indistinguishable from each other and from a bare `String`.
+     */
+    nativeType?: string;
     /** Parsed argument list (empty when the attribute took no parens). */
     args: PrismaAttrArg[];
     /** True for a block attribute (`@@name`), false for a field attribute (`@name`). */
@@ -43,8 +53,14 @@ export interface PrismaAttr {
 export interface PrismaField {
     /** Field name as declared (the Prisma API name). */
     name: string;
-    /** Base type with `[]` / `?` stripped (a scalar, enum, or model name). */
+    /**
+     * Base type with `[]` / `?` stripped (a scalar, enum, or model name).
+     * `Unsupported("...")` is normalized to the literal `Unsupported`, with the
+     * database type kept in {@link PrismaField.unsupported}.
+     */
     type: string;
+    /** The database type inside `Unsupported("...")`, when the field used that form. */
+    unsupported?: string;
     /** Trailing `?` - the field is optional/nullable. */
     optional: boolean;
     /** Trailing `[]` - the field is a list. */