turbine-orm 0.48.0 → 0.49.0

package/dist/index-stats.js

@@ -85,6 +85,14 @@ export const STATS_THRESHOLDS = {
      */
     heatMinQueriesPerMin: 1,
 };
+/**
+ * Placeholder for an index column that is an EXPRESSION, not a plain column
+ * (`pg_index.indkey` stores 0 for those, and no `pg_attribute` row has attnum 0).
+ * It keeps expression POSITIONS in `IndexStat.columns` instead of silently
+ * collapsing `(tenant_id, lower(email))` to `['tenant_id']`, which would make a
+ * functional index look like a droppable prefix of an unrelated plain index.
+ */
+export const EXPRESSION_COLUMN = '(expression)';
 /** Build an empty (fully unavailable) snapshot - the honest "no stats" baseline. */
 export function emptyStatsSnapshot(notices = []) {
     return {
@@ -289,6 +297,30 @@ export function findInvalidIndexes(snapshot) {
 function isConstraintBacking(idx) {
     return idx.isPrimary || idx.isUnique || idx.isExclusion === true || idx.isReplicaIdent;
 }
+/** The structured counterpart of {@link describeIndexShape}. */
+function indexShape(idx) {
+    const kinds = [];
+    if (idx.hasExpressions === true || idx.columns.includes(EXPRESSION_COLUMN))
+        kinds.push('expression');
+    if (idx.predicate != null)
+        kinds.push('partial');
+    if (idx.accessMethod !== undefined && idx.accessMethod !== 'btree')
+        kinds.push('non-btree');
+    return { kinds, accessMethod: idx.accessMethod ?? null, definition: idx.indexDef ?? null };
+}
+/** Describe an index's non-plain-btree properties, or null when it is plain. */
+function describeIndexShape(idx) {
+    const parts = [];
+    if (idx.hasExpressions === true || idx.columns.includes(EXPRESSION_COLUMN))
+        parts.push('expression index');
+    if (idx.predicate != null)
+        parts.push(`partial index (WHERE ${idx.predicate})`);
+    if (idx.accessMethod !== undefined && idx.accessMethod !== 'btree')
+        parts.push(`${idx.accessMethod} index`);
+    if (parts.length === 0)
+        return null;
+    return `${parts.join('; ')}${idx.indexDef ? `: ${idx.indexDef}` : ''}`;
+}
 /**
  * Indexes never (or barely) scanned since the last stats reset. Report-only:
  * counters reset on a crash/reset and REPLICA READS NEVER FEED PRIMARY COUNTERS,
@@ -298,9 +330,11 @@ function isConstraintBacking(idx) {
  */
 export function findUnusedIndexes(snapshot, options = {}) {
     const minScans = options.minScans ?? STATS_THRESHOLDS.unusedMinScans;
+    const probes = options.relationProbes ?? [];
     return snapshot.indexes
         .filter((idx) => idx.isValid && !isConstraintBacking(idx))
         .filter((idx) => idx.idxScan !== undefined && idx.idxScan < minScans)
+        .filter((idx) => !servesRelationProbe(idx, probes))
         .map((idx) => ({
         table: idx.table,
         indexName: idx.indexName,
@@ -308,6 +342,8 @@ export function findUnusedIndexes(snapshot, options = {}) {
         idxScan: idx.idxScan ?? 0,
         sizeBytes: idx.sizeBytes ?? null,
         dropSql: buildDropIndexSql(idx.indexName, { concurrently: true }),
+        caveat: describeIndexShape(idx),
+        shape: indexShape(idx),
     }))
         .sort((a, b) => (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0) || a.indexName.localeCompare(b.indexName));
 }
@@ -317,6 +353,52 @@ function isLeadingPrefix(prefix, columns) {
         return false;
     return prefix.every((c, i) => columns[i] === c);
 }
+/** Whether two column lists are identical, in order. */
+function sameColumns(a, b) {
+    return a.length === b.length && a.every((c, i) => b[i] === c);
+}
+/**
+ * Whether this index answers a relation probe Turbine actually issues: the
+ * probe's columns are the index's leading columns (an exact match, or a wider
+ * index whose prefix serves the probe). Such an index is never handed a DROP,
+ * because the missing-index half of the same report demands it.
+ */
+function servesRelationProbe(idx, probes) {
+    if (probes.length === 0)
+        return false;
+    if (idx.accessMethod !== undefined && idx.accessMethod !== 'btree')
+        return false;
+    if (idx.predicate != null)
+        return false;
+    return probes.some((p) => p.table === idx.table && (sameColumns(p.columns, idx.columns) || isLeadingPrefix(p.columns, idx.columns)));
+}
+/**
+ * Whether prefix coverage is even a meaningful question for this pair. Only a
+ * plain btree has leading-prefix semantics, and only two indexes of the SAME
+ * shape are interchangeable:
+ *
+ *   - access method must be btree on BOTH (a GIN index on a column answers
+ *     queries a btree cannot, and vice versa);
+ *   - neither may contain an expression column (`lower(email)` is a different
+ *     lookup from `email`, and an unresolved expression slot makes the column
+ *     list an unreliable basis for a drop verdict);
+ *   - the partial predicates must be IDENTICAL (both absent, or the same text).
+ *     A full index does technically answer a partial index's lookups, but it is
+ *     not the same object and the partial one exists to be small.
+ *
+ * Anything unknown (an access method or expression flag the collector could not
+ * read) answers "not comparable": doctor stays silent rather than suggesting a
+ * drop it cannot justify.
+ */
+function isCoverageComparable(narrow, wider) {
+    if (narrow.accessMethod !== 'btree' || wider.accessMethod !== 'btree')
+        return false;
+    if (narrow.hasExpressions !== false || wider.hasExpressions !== false)
+        return false;
+    if (narrow.columns.includes(EXPRESSION_COLUMN) || wider.columns.includes(EXPRESSION_COLUMN))
+        return false;
+    return (narrow.predicate ?? null) === (wider.predicate ?? null);
+}
 /**
  * Non-unique indexes whose column list is a leading prefix of a WIDER index on
  * the same table. A btree serves any leading-prefix lookup, so the narrow index
@@ -325,6 +407,9 @@ function isLeadingPrefix(prefix, columns) {
  * Uniqueness compatibility: only a NON-unique index is ever reported. A unique
  * or primary-key prefix is load-bearing (it enforces a constraint), so it is
  * never called redundant even when a wider index shares its leading columns.
+ *
+ * Shape compatibility: see {@link isCoverageComparable}. A functional, partial,
+ * or non-btree index is never reported as covered by a plain btree.
  */
 export function findRedundantIndexes(snapshot) {
     const byTable = new Map();
@@ -347,7 +432,18 @@ export function findRedundantIndexes(snapshot) {
                 continue;
             if (narrow.columns.length === 0)
                 continue;
-            const wider = list.find((w) => w.indexName !== narrow.indexName && isLeadingPrefix(narrow.columns, w.columns));
+            // Prefer a genuinely wider index; fall back to an exact duplicate, which
+            // is the most obvious index problem there is and which a strict
+            // leading-prefix test (prefix.length < columns.length) can never see. For
+            // a duplicate pair only ONE side is reported: the later name, so the
+            // report never tells you to drop both copies.
+            const wider = list.find((w) => w.indexName !== narrow.indexName &&
+                isCoverageComparable(narrow, w) &&
+                isLeadingPrefix(narrow.columns, w.columns)) ??
+                list.find((w) => w.indexName < narrow.indexName &&
+                    !isConstraintBacking(w) &&
+                    isCoverageComparable(narrow, w) &&
+                    sameColumns(narrow.columns, w.columns));
             if (!wider)
                 continue;
             out.push({
@@ -373,6 +469,7 @@ export function findRedundantIndexes(snapshot) {
  */
 export function auditDoctorIndexes(snapshot, doctorNames, options = {}) {
     const minScans = options.minScans ?? STATS_THRESHOLDS.unusedMinScans;
+    const probes = options.relationProbes ?? [];
     const out = [];
     for (const idx of snapshot.indexes) {
         if (!idx.isValid || isConstraintBacking(idx))
@@ -382,14 +479,16 @@ export function auditDoctorIndexes(snapshot, doctorNames, options = {}) {
             continue;
         if (idx.idxScan === undefined || idx.idxScan >= minScans)
             continue;
+        const stillProbed = servesRelationProbe(idx, probes);
         out.push({
             table: idx.table,
             indexName: idx.indexName,
             columns: idx.columns,
             idxScan: idx.idxScan,
             sizeBytes: idx.sizeBytes ?? null,
-            dropSql: buildDropIndexSql(idx.indexName, { concurrently: true }),
+            dropSql: stillProbed ? null : buildDropIndexSql(idx.indexName, { concurrently: true }),
             ambiguous: candidates.length > 1,
+            stillProbed,
         });
     }
     return out.sort((a, b) => a.indexName.localeCompare(b.indexName));
@@ -492,19 +591,28 @@ export async function collectStatsSnapshot(options) {
             }
         }
         // --- invalid + all indexes (whole schema, for invalid detection) -------
-        const indexRows = await run('pg_index', `SELECT c.relname AS table_name,
+        const indexRows = await run('pg_index', 
+        // The column list LEFT JOINs pg_attribute so an EXPRESSION slot (indkey = 0,
+        // which no pg_attribute row matches) survives as a marker instead of being
+        // dropped by an inner join, which silently shortened functional indexes.
+        `SELECT c.relname AS table_name,
               ic.relname AS index_name,
               i.indisvalid, i.indisunique, i.indisprimary, i.indisreplident,
               EXISTS (SELECT 1 FROM pg_constraint con
                        WHERE con.conindid = i.indexrelid AND con.contype = 'x') AS is_exclusion,
               s.idx_scan::text AS idx_scan,
               pg_relation_size(i.indexrelid)::text AS index_size,
-              (SELECT array_agg(a.attname::text ORDER BY k.ord)
+              am.amname AS access_method,
+              (i.indexprs IS NOT NULL) AS has_expressions,
+              pg_get_expr(i.indpred, i.indrelid) AS predicate,
+              pg_get_indexdef(i.indexrelid) AS index_def,
+              (SELECT array_agg(coalesce(a.attname::text, '${EXPRESSION_COLUMN}') ORDER BY k.ord)
                  FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
-                 JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum) AS columns
+                 LEFT JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum) AS columns
          FROM pg_index i
          JOIN pg_class c ON c.oid = i.indrelid
          JOIN pg_class ic ON ic.oid = i.indexrelid
+         JOIN pg_am am ON am.oid = ic.relam
          JOIN pg_namespace n ON n.oid = c.relnamespace
          LEFT JOIN pg_stat_user_indexes s ON s.indexrelid = i.indexrelid
         WHERE n.nspname = $1`, [options.schema]);
@@ -514,6 +622,10 @@ export async function collectStatsSnapshot(options) {
                     table: row.table_name,
                     indexName: row.index_name,
                     columns: row.columns ?? [],
+                    accessMethod: row.access_method,
+                    hasExpressions: row.has_expressions,
+                    predicate: row.predicate,
+                    indexDef: row.index_def ?? undefined,
                     idxScan: row.idx_scan == null ? undefined : Number(row.idx_scan),
                     isValid: row.indisvalid,
                     isUnique: row.indisunique,

package/dist/mssql.js

@@ -482,6 +482,11 @@ export const mssqlDialect = {
     supportsReturning: false,
     supportsILike: false,
     supportsVector: false,
+    // SQL Server full-text is `CONTAINS`/`FREETEXT` over a full-text catalog: a
+    // different surface with different semantics, not the emitted tsvector form.
+    supportsFullTextSearch: false,
+    // No array column type (a JSON column is not an array column).
+    supportsArrayColumns: false,
     supportsListenNotify: false,
     supportsRLS: false,
     // SQL Server has OUTER APPLY, not FROM-clause LATERAL: the lateral pick plan

package/dist/mysql.js

@@ -366,6 +366,11 @@ export const mysqlDialect = {
     supportsReturning: false,
     supportsILike: false,
     supportsVector: false,
+    // MySQL full-text is `MATCH(col) AGAINST(...)` over a FULLTEXT index: a
+    // different surface with different semantics, not the emitted tsvector form.
+    supportsFullTextSearch: false,
+    // No array column type (a JSON column is not an array column).
+    supportsArrayColumns: false,
     supportsListenNotify: false,
     supportsRLS: false,
     // MySQL 8.0.14+ supports LATERAL, but the opt-in lateral pick plan stays

package/dist/nested-write.js

@@ -11,7 +11,7 @@
  * `client.ts` directly — the transaction handle is passed in via
  * `NestedWriteContext`.
  */
-import { CircularRelationError, describeTargetForMessage, RelationError, ValidationError } from './errors.js';
+import { CircularRelationError, describeTargetForMessage, NotFoundError, RelationError, ValidationError, } from './errors.js';
 import { normalizeKeyColumns } from './schema.js';
 const MAX_DEPTH = 10;
 const CREATE_ONLY_OPS = new Set(['create', 'connect', 'connectOrCreate']);
@@ -111,6 +111,152 @@ function pkWhere(tableMeta, row) {
     }
     return where;
 }
+/**
+ * The child-side predicate that ties a hasMany/hasOne relation's rows to THIS
+ * parent: `child.foreignKey = parent.referenceKey`. This is the exact
+ * correlation the connect/connectOrCreate/set paths already write when they
+ * point a child AT the parent, read back here as a filter.
+ *
+ * Returns `null` when the parent's reference key is null/undefined: SQL
+ * equality never matches NULL, so no child can be related and every scoped
+ * operation must report not-found rather than run unscoped.
+ */
+function parentCorrelationWhere(ctx, rel, parentRow) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const childTable = ctx.schema.tables[rel.to];
+    const parentTable = ctx.schema.tables[rel.from];
+    const where = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = childTable?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = parentTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        const value = parentRow[refField];
+        if (value === null || value === undefined)
+            return null;
+        where[fkField] = value;
+    }
+    return where;
+}
+/**
+ * The related-side predicate for a belongsTo relation: the parent holds the
+ * foreign key, so the related row this parent points at satisfies
+ * `related.referenceKey = parent.foreignKey`. The mirror image of
+ * {@link parentCorrelationWhere}, which reads the hasMany/hasOne direction.
+ *
+ * Returns `null` when the parent's foreign key is null/undefined: the parent
+ * points at nothing, so no related row is in scope.
+ */
+function belongsToCorrelationWhere(ctx, rel, parentRow, parentTable) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    const where = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = parentMeta?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        const value = parentRow[fkField];
+        if (value === null || value === undefined)
+            return null;
+        where[refField] = value;
+    }
+    return where;
+}
+/**
+ * AND the caller-supplied child `where` with the parent correlation so a nested
+ * delete/update/disconnect can only ever touch rows that actually belong to the
+ * parent being written.
+ *
+ * The flat merge is used whenever the two predicates name disjoint fields (the
+ * overwhelmingly common case: the caller addresses the child by its primary
+ * key). It keeps every caller key at the top level, so compound-unique selector
+ * expansion still sees them. When the caller's `where` names a correlation
+ * field itself, the two are combined with `AND` instead, so neither predicate
+ * can silently overwrite the other.
+ */
+function scopeWhereToParent(target, correlation) {
+    for (const key of Object.keys(correlation)) {
+        if (Object.hasOwn(target, key))
+            return { AND: [target, correlation] };
+    }
+    return { ...target, ...correlation };
+}
+/**
+ * The caller's own selector must name at least one bound value.
+ *
+ * The parent correlation is ANDed onto every nested delete/update/disconnect
+ * target, which makes the merged predicate non-empty by construction. That
+ * defeats the empty-where guard downstream: `delete: {}` or
+ * `delete: { id: req.body.postId }` with an undefined body field would compile
+ * to `WHERE user_id = $1` and remove EVERY child of this parent instead of
+ * throwing. So the caller's half is checked here, before the merge.
+ *
+ * `true` is accepted only on a to-one relation, where it means "the single
+ * related row" and the correlation alone identifies it. On a to-many it would
+ * mean "all of them", which is never what a caller spelled `delete: true` for.
+ */
+function assertTargetSelectsSomething(target, op, relName, rel) {
+    const toOne = rel.type === 'hasOne' || rel.type === 'belongsTo';
+    if (target === true) {
+        if (toOne)
+            return;
+        throw new ValidationError(`[turbine] Nested ${op} on to-many relation "${relName}" needs a "where" selector: ` +
+            `"${op}: true" would ${op} every related "${rel.to}" row.`);
+    }
+    if (target && typeof target === 'object' && !Array.isArray(target)) {
+        const bound = Object.values(target).some((v) => v !== undefined);
+        if (bound)
+            return;
+    }
+    throw new ValidationError(`[turbine] Nested ${op} on relation "${relName}" requires a selector with at least one defined value. ` +
+        `An empty or all-undefined "where" would ${op} every related "${rel.to}" row of this parent.`);
+}
+/**
+ * many-to-many relations have no nested-write branch on any engine: the junction
+ * row would have to be written too, and there is no safe default for what to put
+ * in its extra columns. Refusing loudly is the only honest option, because the
+ * alternative (falling off the end of the dispatch) drops the write silently and
+ * reports success.
+ */
+function manyToManyUnsupported(relName, rel) {
+    return new ValidationError(`[turbine] Nested writes are not supported on the many-to-many relation "${relName}" ` +
+        `(via the "${rel.through?.table ?? 'junction'}" junction table). Write the junction rows directly ` +
+        `(db.${rel.through?.table ?? 'junction'}.create / createMany) inside the same $transaction.`);
+}
+/**
+ * The E001 raised when a nested delete/update/disconnect target is not a child
+ * of this parent (it belongs to another parent, or does not exist at all).
+ * Matches Prisma's behavior: the nested where is scoped to the relation, so a
+ * row outside the relation is simply "not found".
+ */
+function notRelatedToParent(op, relName, rel, target) {
+    // Object form, not the legacy string one: `err.table` / `err.where` /
+    // `err.operation` are a documented part of the NotFoundError contract, and a
+    // string-constructed error silently drops all three.
+    return new NotFoundError({
+        table: rel.to,
+        where: target,
+        operation: `nested ${op}`,
+        message: `[turbine] Nested ${op} on relation "${relName}": no "${rel.to}" record matching ` +
+            `${describeTargetForMessage(target)} is related to this parent. Either it does not exist, ` +
+            `or it belongs to a different parent (a nested ${op} can only touch this parent's rows).`,
+    });
+}
+/** Re-tag a NotFoundError from a scoped child write as a relation-scoped miss. */
+function rethrowAsNotRelated(err, op, relName, rel, target) {
+    if (err instanceof NotFoundError) {
+        // Only re-tag a miss on THIS relation's own write. A NotFoundError raised
+        // deeper in the tree already names its own relation, and re-tagging it here
+        // would rename someone else's failure; keep it, and preserve the original
+        // as `cause` in either direction.
+        if (err.operation?.startsWith('nested '))
+            throw err;
+        const tagged = notRelatedToParent(op, relName, rel, target);
+        tagged.cause ??= err;
+        throw tagged;
+    }
+    throw err;
+}
 // ---------------------------------------------------------------------------
 // executeNestedCreate
 // ---------------------------------------------------------------------------
@@ -148,6 +294,9 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
         if (rel.type === 'belongsTo') {
             Object.assign(belongsToFks, await resolveBelongsToForCreate(ctx, rel, ops, tableName, depth, path, relName));
         }
+        else if (rel.type === 'manyToMany') {
+            throw manyToManyUnsupported(relName, rel);
+        }
     }
     // Insert the parent row (scalars + resolved belongsTo foreign keys)
     const parentRow = (await ctx.tx.table(tableName).create({
@@ -218,7 +367,7 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
             await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
             // disconnect
             if (ops.disconnect !== undefined) {
-                await processDisconnect(ctx, rel, ops.disconnect, relName);
+                await processDisconnect(ctx, rel, ops.disconnect, relName, parentRow);
             }
             // set
             if (ops.set !== undefined) {
@@ -226,15 +375,15 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
             }
             // delete
             if (ops.delete !== undefined) {
-                await processDelete(ctx, rel, ops.delete);
+                await processDelete(ctx, rel, ops.delete, relName, parentRow);
             }
             // update
             if (ops.update !== undefined) {
-                await processNestedUpdate(ctx, rel, ops.update);
+                await processNestedUpdate(ctx, rel, ops.update, relName, parentRow);
             }
             // upsert
             if (ops.upsert !== undefined) {
-                await processNestedUpsert(ctx, rel, ops.upsert, parentRow);
+                await processNestedUpsert(ctx, rel, ops.upsert, parentRow, relName);
             }
         }
         else if (rel.type === 'belongsTo') {
@@ -268,6 +417,9 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
                 });
             }
         }
+        else {
+            throw manyToManyUnsupported(relName, rel);
+        }
     }
     // Final read with all touched relations
     const withClause = {};
@@ -474,7 +626,7 @@ async function connectOrCreate(ctx, rel, op, parentRow) {
         await ctx.tx.table(rel.to).update({ where: op.where, data: updateData });
     }
 }
-async function processDisconnect(ctx, rel, disconnectArg, relName) {
+async function processDisconnect(ctx, rel, disconnectArg, relName, parentRow) {
     const fks = normalizeKeyColumns(rel.foreignKey);
     const childTable = ctx.schema.tables[rel.to];
     if (!childTable)
@@ -488,13 +640,26 @@ async function processDisconnect(ctx, rel, disconnectArg, relName) {
         throw new ValidationError(`[turbine] Cannot disconnect "${relName}": foreign key column(s) ${fks.join(', ')} on "${rel.to}" are NOT NULL. Use delete instead.`);
     }
     const items = toArray(disconnectArg);
+    if (items.length === 0)
+        return;
     const nullData = {};
     for (const fk of fks) {
         const field = childTable.reverseColumnMap[fk] ?? fk;
         nullData[field] = null;
     }
+    // Disconnect nulls the child's FK, so an unscoped target would strip ANOTHER
+    // parent's child off that parent. Scope every target to this parent's rows.
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const target of items) {
-        await ctx.tx.table(rel.to).update({ where: target, data: nullData });
+        assertTargetSelectsSomething(target, 'disconnect', relName, rel);
+        if (!correlation)
+            throw notRelatedToParent('disconnect', relName, rel, target);
+        try {
+            await ctx.tx.table(rel.to).update({ where: scopeWhereToParent(target, correlation), data: nullData });
+        }
+        catch (err) {
+            rethrowAsNotRelated(err, 'disconnect', relName, rel, target);
+        }
     }
 }
 async function processSet(ctx, rel, setItems, parentRow) {
@@ -503,12 +668,23 @@ async function processSet(ctx, rel, setItems, parentRow) {
     const childTable = ctx.schema.tables[rel.to];
     if (!childTable)
         return;
-    // Build parent FK match for finding current children
+    // Build parent FK match for finding current children. `set` clears the
+    // current children with `allowFullTableScan: true`, which is exactly what
+    // disables the empty-where guard downstream, so a null/undefined reference
+    // key here would null the FK of EVERY row in the child table. Same guard as
+    // parentCorrelationWhere, spelled inline because `set` also needs the
+    // (identical) forward direction for the reconnect below.
     const parentWhere = {};
     for (let i = 0; i < fks.length; i++) {
         const fkField = childTable.reverseColumnMap[fks[i]] ?? fks[i];
         const refField = ctx.schema.tables[rel.from]?.reverseColumnMap[refs[i]] ?? refs[i];
-        parentWhere[fkField] = parentRow[refField];
+        const value = parentRow[refField];
+        if (value === null || value === undefined) {
+            throw new ValidationError(`[turbine] Nested set on relation "${rel.name}" cannot run: the parent's reference key ` +
+                `"${refField}" is ${value === null ? 'null' : 'missing from the loaded row'}, so no child rows ` +
+                `can be correlated to this parent.`);
+        }
+        parentWhere[fkField] = value;
     }
     // Disconnect all current children
     const nullData = {};
@@ -535,24 +711,49 @@ async function processSet(ctx, rel, setItems, parentRow) {
 // ---------------------------------------------------------------------------
 // update / upsert operations (update-context only)
 // ---------------------------------------------------------------------------
-async function processNestedUpdate(ctx, rel, updateArg) {
+async function processNestedUpdate(ctx, rel, updateArg, relName, parentRow) {
     const items = toArray(updateArg);
+    if (items.length === 0)
+        return;
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const item of items) {
         if (!item.where || !item.data) {
             throw new ValidationError(`[turbine] Nested update on "${rel.name}" requires both "where" and "data" fields.`);
         }
-        await ctx.tx.table(rel.to).update({ where: item.where, data: item.data });
+        assertTargetSelectsSomething(item.where, 'update', relName, rel);
+        if (!correlation)
+            throw notRelatedToParent('update', relName, rel, item.where);
+        try {
+            await ctx.tx.table(rel.to).update({ where: scopeWhereToParent(item.where, correlation), data: item.data });
+        }
+        catch (err) {
+            rethrowAsNotRelated(err, 'update', relName, rel, item.where);
+        }
     }
 }
-async function processNestedUpsert(ctx, rel, upsertArg, parentRow) {
+async function processNestedUpsert(ctx, rel, upsertArg, parentRow, relName) {
     const items = toArray(upsertArg);
+    if (items.length === 0)
+        return;
+    // The upsert's `where` is scoped to the relation, so a row that matches it but
+    // belongs to ANOTHER parent is not "existing" here: it is never updated, and
+    // the create branch runs instead (any resulting unique-constraint violation is
+    // surfaced to the caller rather than silently rewriting a stranger's row).
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const item of items) {
         if (!item.where || !item.create || !item.update) {
             throw new ValidationError(`[turbine] Nested upsert on "${rel.name}" requires "where", "create", and "update" fields.`);
         }
-        const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
-        if (existing) {
-            await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+        assertTargetSelectsSomething(item.where, 'upsert', relName, rel);
+        const scoped = correlation ? scopeWhereToParent(item.where, correlation) : null;
+        const existing = scoped ? await ctx.tx.table(rel.to).findUnique({ where: scoped }) : null;
+        if (existing && scoped) {
+            try {
+                await ctx.tx.table(rel.to).update({ where: scoped, data: item.update });
+            }
+            catch (err) {
+                rethrowAsNotRelated(err, 'upsert', relName, rel, item.where);
+            }
         }
         else {
             const injected = injectForeignKey(item.create, rel, parentRow, ctx.schema);
@@ -583,9 +784,25 @@ async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTabl
     if (!item.where || !item.create || !item.update) {
         throw new ValidationError(`[turbine] Nested upsert on belongsTo "${rel.name}" requires "where", "create", and "update" fields.`);
     }
-    const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+    // Scope the lookup to the row this parent actually points at. Without the
+    // correlation, a `where` naming any other row would update a record with no
+    // relationship to the parent being written. A miss falls through to the
+    // create branch (and re-points the parent's FK), which is the same choice the
+    // hasMany/hasOne nested upsert makes: an upsert whose target is out of the
+    // relation creates a row owned by this parent rather than rewriting a
+    // stranger's.
+    const correlation = belongsToCorrelationWhere(ctx, rel, parentRow, parentTable);
+    // findMany, not findUnique: the scoped where ANDs a non-unique-looking
+    // correlation onto the caller's selector. The correlation targets the
+    // relation's reference key (unique or the PK by construction), so at most one
+    // row can come back.
+    const existing = correlation
+        ? ((await ctx.tx.table(rel.to).findMany({ where: scopeWhereToParent(item.where, correlation) }))[0] ??
+            null)
+        : null;
     if (existing) {
-        await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+        const relatedMeta = ctx.schema.tables[rel.to];
+        await ctx.tx.table(rel.to).update({ where: pkWhere(relatedMeta, existing), data: item.update });
     }
     else {
         // Create the related row, then update parent's FK to point at it
@@ -606,9 +823,22 @@ async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTabl
         });
     }
 }
-async function processDelete(ctx, rel, deleteArg) {
+async function processDelete(ctx, rel, deleteArg, relName, parentRow) {
     const items = toArray(deleteArg);
+    if (items.length === 0)
+        return;
+    // Without the correlation this deletes ANY row the caller can name: a
+    // cross-tenant delete primitive for any endpoint that forwards a client id.
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const target of items) {
-        await ctx.tx.table(rel.to).delete({ where: target });
+        assertTargetSelectsSomething(target, 'delete', relName, rel);
+        if (!correlation)
+            throw notRelatedToParent('delete', relName, rel, target);
+        try {
+            await ctx.tx.table(rel.to).delete({ where: scopeWhereToParent(target, correlation) });
+        }
+        catch (err) {
+            rethrowAsNotRelated(err, 'delete', relName, rel, target);
+        }
     }
 }

package/dist/observe.d.ts

@@ -102,7 +102,6 @@ export declare class HttpJsonSink implements ObserveSink {
 export declare class ObserveEngine {
     private readonly sink;
     private readonly buffer;
-    private currentBucket;
     private readonly flushIntervalMs;
     private timer;
     private readonly listener;