fastify-auto-sqlapi 0.2.4 → 0.4.0

package/dist/lib/engine/write-helpers.js

@@ -1,7 +1,41 @@
 import { camelcaseObject, snakecaseRecord } from '../naming.js';
 import { runValidation } from './validate.js';
 import { removeWriteExcluded } from '../write-access.js';
+import { httpError } from '../errors.js';
 import { tenantForTable, buildTenantRowGuard, enforceTenantOnWrites, assertTenantOwnsConflicts, tenantImmutableColumns, } from '../tenant.js';
+/**
+ * Every upserted record must carry its key (ADR 0021), checked on the record as it reaches the
+ * database — after hooks, tenant injection and the FK auto-fill of secondaries:
+ * - a natural key needs every field present and not null: a NULL never conflicts, so the row
+ *   could only be inserted and never found again by its key;
+ * - on the primary key, a record naming no PK field at all is a plain insert with a generated
+ *   key; one naming it only in part, or as null, is refused like a natural key;
+ * - two records of one request with the same key are refused: PostgreSQL cannot affect a row
+ *   twice in one statement, MySQL would let the last one win.
+ * Throws 400 before any SQL runs. Column names and record keys are DB column names.
+ */
+export function assertUpsertKeys(schema, conflictCols, pkCols, records) {
+    const isPrimaryKey = conflictCols.length === pkCols.length
+        && conflictCols.every((c) => pkCols.includes(c));
+    const fieldOf = (col) => Object.keys(schema.fields).find((f) => schema.col(f) === col) ?? col;
+    const rule = `Upsert on "${schema.tableName}" by (${conflictCols.map(fieldOf).join(', ')})`;
+    const seen = new Map();
+    records.forEach((record, i) => {
+        if (isPrimaryKey && conflictCols.every((c) => record[c] === undefined))
+            return;
+        const missing = conflictCols.filter((c) => record[c] == null);
+        if (missing.length) {
+            throw httpError(400, `${rule}: the row at index ${i} has no value for ${missing.map(fieldOf).join(', ')} — ` +
+                `an upserted row must carry its whole key`);
+        }
+        const key = JSON.stringify(conflictCols.map((c) => record[c]));
+        const first = seen.get(key);
+        if (first !== undefined) {
+            throw httpError(400, `${rule}: the rows at index ${first} and ${i} have the same key`);
+        }
+        seen.set(key, i);
+    });
+}
 /**
  * Resolve the write join an alias names, or undefined when the table does not declare it.
  *
@@ -144,6 +178,7 @@ export function processSecondaries(pass, secondaries) {
         let pkRows;
         if (upsertKeys) {
             const conflictCols = upsertKeys.map((k) => joinSchema.col(k));
+            assertUpsertKeys(joinSchema, conflictCols, (joinSchema.primaryKey ?? [childPk].flat()).map((f) => joinSchema.col(f)), preparedRecords);
             // A conflicting upsert must not overwrite — or re-parent — a child row owned by
             // another tenant, which the ON CONFLICT key alone would happily match.
             await assertTenantOwnsConflicts(db, childTenant, joinSchema.tableName, conflictCols, preparedRecords);

package/dist/lib/schema/helpers.d.ts

@@ -5,6 +5,13 @@ import type { ITable, SchemaDefinition, DbTables, JoinDefinition } from '../../t
  * Falls back to `fallback` field if tableConf is undefined.
  */
 export declare function pkSchema(tableConf: ITable | undefined, schema: SchemaDefinition, fallback: string): Record<string, TSchema>;
+/**
+ * Make the tenant column(s) of a scoped table Optional in a write body. The engine injects the
+ * value for a single-tenant caller and validates the one a multi-tenant or `anyOf` caller sends,
+ * so the body must offer the field without demanding it — the same reason a secondary's FK is
+ * Optional. `tenantScope` names real DB columns; the schema field is found through `col()`.
+ */
+export declare function relaxTenantColumns(fields: Record<string, TSchema>, tableConf: ITable | undefined, schema: SchemaDefinition): void;
 /** The same schema without the Optional modifier, i.e. as a required property. */
 export declare function asRequired(schema: TSchema): TSchema;
 /**

package/dist/lib/schema/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKzF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ3H;AAiCD,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAGnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,KAAK,iBAAiB,GAAG,CACvB,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,MAAM,GAAG,SAAS,KAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwB7B;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,iBAAiB,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7F,IAAI,CA8BN;AAED,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,iBACmB,CAAC;AAEtD,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,iBACG,CAAC;AAE1C,4DAA4D;AAC5D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAMzF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ3H;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,GACvB,IAAI,CAMN;AAoCD,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAGnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,KAAK,iBAAiB,GAAG,CACvB,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,MAAM,GAAG,SAAS,KAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwB7B;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,iBAAiB,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7F,IAAI,CA8BN;AAED,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,iBACmB,CAAC;AAEtD,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,iBACG,CAAC;AAE1C,4DAA4D;AAC5D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/dist/lib/schema/helpers.js

@@ -1,6 +1,7 @@
 import { Type, OptionalKind } from '@sinclair/typebox';
 import { readableFieldNames } from '../read-access.js';
 import { writableFields } from '../write-access.js';
+import { tenantOwnColumns } from '../tenant.js';
 import { findSecondaryTableConf } from '../engine/write-helpers.js';
 /**
  * Build a PK-only schema for response shapes (single or composite PK).
@@ -15,10 +16,26 @@ export function pkSchema(tableConf, schema, fallback) {
     }
     return result;
 }
+/**
+ * Make the tenant column(s) of a scoped table Optional in a write body. The engine injects the
+ * value for a single-tenant caller and validates the one a multi-tenant or `anyOf` caller sends,
+ * so the body must offer the field without demanding it — the same reason a secondary's FK is
+ * Optional. `tenantScope` names real DB columns; the schema field is found through `col()`.
+ */
+export function relaxTenantColumns(fields, tableConf, schema) {
+    const columns = tenantOwnColumns(tableConf?.tenantScope);
+    if (columns.length === 0)
+        return;
+    for (const field of Object.keys(fields)) {
+        if (columns.includes(schema.col(field)))
+            fields[field] = Type.Optional(fields[field]);
+    }
+}
 /**
  * Build secondary table fields for body schemas:
  * - FK field becomes Optional (auto-filled from main)
  * - excludeFromCreation fields become Optional
+ * - tenant column(s) become Optional (injected or validated by the engine)
  */
 function buildSecondaryFields(joinSchema, joinField, secondaryTableConf) {
     const fields = writableFields({ ...joinSchema.fields }, secondaryTableConf, joinSchema);
@@ -32,6 +49,7 @@ function buildSecondaryFields(joinSchema, joinField, secondaryTableConf) {
             }
         }
     }
+    relaxTenantColumns(fields, secondaryTableConf, joinSchema);
     return fields;
 }
 /** The same schema without the Optional modifier, i.e. as a required property. */

package/dist/lib/schema/insert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/insert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAgB,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAU/C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CA+B9E;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAalF"}
+{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/insert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAgB,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAW/C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAiC9E;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAalF"}

package/dist/lib/schema/insert.js

@@ -1,7 +1,7 @@
 import { Type } from '@sinclair/typebox';
 import { primaryAsString } from '../../types.js';
 import { writableFields } from '../write-access.js';
-import { pkSchema, applySchemaOverrides, attachWriteJoinSections, writeJoinBodyFields, writeJoinResponseFields, } from './helpers.js';
+import { pkSchema, applySchemaOverrides, attachWriteJoinSections, relaxTenantColumns, writeJoinBodyFields, writeJoinResponseFields, } from './helpers.js';
 export function InsertTableBody(dbTables, tableName) {
     const tableConf = dbTables[tableName];
     const schema = tableConf.Schema;
@@ -15,6 +15,8 @@ export function InsertTableBody(dbTables, tableName) {
                 mainFields[field] = Type.Optional(mainFields[field]);
         }
     }
+    // The tenant column is the engine's to fill or check, never the client's to be forced to send.
+    relaxTenantColumns(mainFields, tableConf, schema);
     const bodyProperties = {
         // additionalProperties:false makes the schema the real write whitelist — unknown keys are
         // rejected (400) instead of silently reaching the INSERT as columns (mass assignment).

package/dist/lib/table-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/table-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,yBAAyB,EAAiC,MAAM,wBAAwB,CAAC;AACzH,OAAO,EAAQ,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,MAAM,EAEP,MAAM,aAAa,CAAC;AAcrB,KAAK,UAAU,CAAC,EAAE,IAAI,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAExH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,EAAE,SAAS,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAErE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,YAAY,GAAE,EAAa,EAC3B,iBAAiB,CAAC,EAAE,CAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yBAAyB;CAAE,KAC3E,IAAI,GACR;IAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAsChG;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,CAAC,CAAC,CAWX;AAiSD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAgDD,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,EAClD,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAWhB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAE9B;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,KAAK,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,GACvC,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAEjC"}
+{"version":3,"file":"table-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/table-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,yBAAyB,EAAiC,MAAM,wBAAwB,CAAC;AACzH,OAAO,EAAQ,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,MAAM,EAEP,MAAM,aAAa,CAAC;AAcrB,KAAK,UAAU,CAAC,EAAE,IAAI,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAExH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,EAAE,SAAS,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAErE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,YAAY,GAAE,EAAa,EAC3B,iBAAiB,CAAC,EAAE,CAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yBAAyB;CAAE,KAC3E,IAAI,GACR;IAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAsChG;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,CAAC,CAAC,CAYX;AAmVD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAgDD,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,EAClD,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAWhB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAE9B;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,KAAK,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,GACvC,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAEjC"}

package/dist/lib/table-helpers.js

@@ -55,6 +55,7 @@ export function defineTable(config) {
     validateWriteExclude(config);
     validateTenantScope(config);
     validateTenantColumnNames(config);
+    validateUpsertMap(config);
     return config;
 }
 /**
@@ -255,6 +256,46 @@ function validateWriteExclude(config) {
         }
     }
 }
+const formatKey = (fields) => `(${fields.join(', ')})`;
+const sameFieldSet = (a, b) => a.length === b.length && a.every((f) => b.includes(f));
+/**
+ * An `upsertMap` rule must name a unique key the database enforces — the Schema's
+ * `primaryKey` or one of its `uniqueKeys`, as a set: same fields, any order, nothing extra
+ * (ADR 0021). Anything else fails every write on PostgreSQL, and on MySQL duplicates rows or
+ * updates a row matched through another key, in silence.
+ *
+ * Fail-closed: a rule the Schema cannot vouch for is refused. The Schema is what is read, not
+ * a table config, so a child written only through a write join needs no `defineTable`.
+ */
+function validateUpsertMap(config) {
+    for (const [schema, keys] of config.upsertMap ?? []) {
+        const problem = upsertKeyProblem(schema, keys);
+        if (problem) {
+            throw new Error(`defineTable: upsertMap rule on '${schema.tableName}' ${formatKey(keys)} ${problem} (ADR 0021).`);
+        }
+    }
+}
+/** Why `keys` is not a verified unique key of `schema`, or null when it is one. */
+function upsertKeyProblem(schema, keys) {
+    if (schema.isView)
+        return 'targets a view — a view has no unique key to upsert on';
+    const primaryKey = schema.primaryKey ?? [];
+    if (primaryKey.length && sameFieldSet(keys, primaryKey))
+        return null;
+    if (schema.uniqueKeys === undefined) {
+        return (`cannot be verified: the Schema of '${schema.tableName}' carries no uniqueKeys` +
+            `${primaryKey.length ? '' : ' and no primaryKey'} — regenerate the schemas with ` +
+            `sqlapi-generate-schema, an upsert must target a unique key the database enforces`);
+    }
+    if (schema.uniqueKeys.some((unique) => sameFieldSet(keys, unique)))
+        return null;
+    const available = [
+        ...(primaryKey.length ? [`${formatKey(primaryKey)} primary key`] : []),
+        ...schema.uniqueKeys.map(formatKey),
+    ];
+    return (`is not a unique key of the table. An upsert must target exactly one: ` +
+        `${available.length ? available.join(', ') : 'the table has none'}`);
+}
 function validateComputedFields(config) {
     const computed = config.computedFields;
     if (!computed)

package/dist/lib/tenant.d.ts

@@ -2,6 +2,12 @@ import type { ApiRequest } from '../types/request.js';
 import type { QueryClient } from './db.js';
 import { ConditionBuilder, type ConditionValue, type ConditionValueOrUndefined } from 'node-condition-builder';
 import type { ITable, SqlApiPluginOptions, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantScopeAnyOf, TenantContext } from '../types.js';
+/**
+ * The columns of a scoped table that the engine fills or validates on insert, i.e. the ones a
+ * write body must offer without requiring: the own column of a direct scope, every column of an
+ * `anyOf` scope. An indirect scope names no column of its own — its FK is an ordinary field.
+ */
+export declare function tenantOwnColumns(scope: TenantScope | undefined): string[];
 export declare function resolveTenant(options: SqlApiPluginOptions, tableConf: ITable, request: ApiRequest): Promise<TenantContext | undefined>;
 /**
  * The read predicate for a scope, as a fragment every caller appends to its own WHERE.

package/dist/lib/tenant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/lib/tenant.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/lib/tenant.ts"],"names":[],"mappings":"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"}

package/dist/lib/tenant.js

@@ -14,6 +14,16 @@ function isAnyOf(scope) {
 function ownColumns(scope) {
     return isAnyOf(scope) ? scope.anyOf : [scope.column];
 }
+/**
+ * The columns of a scoped table that the engine fills or validates on insert, i.e. the ones a
+ * write body must offer without requiring: the own column of a direct scope, every column of an
+ * `anyOf` scope. An indirect scope names no column of its own — its FK is an ordinary field.
+ */
+export function tenantOwnColumns(scope) {
+    if (!scope || isIndirect(scope))
+        return [];
+    return ownColumns(scope);
+}
 /**
  * Whether this request could touch a scoped row at all: the addressed table is scoped, or one of
  * the tables it can reach through a declared relation is.
@@ -44,6 +54,12 @@ export async function resolveTenant(options, tableConf, request) {
     if (raw == null)
         return undefined; // admin
     const ids = Array.isArray(raw) ? raw : [raw];
+    // An empty list is a caller with no tenant at all — not an admin. Every consumer of `ids`
+    // would emit `IN ()` (a syntax error on both dialects) or, worse, a builder could drop the
+    // empty predicate and open the table. Refuse here, once, before any SQL exists.
+    if (ids.length === 0) {
+        throw httpError(403, 'Tenant required: the caller belongs to no tenant');
+    }
     // `scope` stays undefined for an unscoped host: the ids still travel, so the tables it reaches
     // enforce their own scopes, while the host itself keeps no filter.
     return { ids, scope: tableConf.tenantScope };

package/dist/routes/auto/bulk-delete.routes.js

@@ -7,7 +7,7 @@ export default async function bulkDeleteRoutes(fastify, options) {
         operation: 'bulkDelete',
         singlePkOnly: true,
         method: 'POST',
-        url: (tc) => `/bulk/${tc.Schema.tableName}/delete`,
+        url: (tableName) => `/bulk/${tableName}/delete`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: BulkDeleteTableBody(db, table, options.maxBulkItems ?? DEFAULT_MAX_BULK_ITEMS),

package/dist/routes/auto/bulk-upsert.routes.js

@@ -5,7 +5,7 @@ export default async function bulkUpsertRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'bulkUpsert',
         method: 'PUT',
-        url: (tc) => `/bulk/${tc.Schema.tableName}`,
+        url: (tableName) => `/bulk/${tableName}`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: BulkUpsertTableBody(db, table, options.maxBulkItems ?? DEFAULT_MAX_BULK_ITEMS),

package/dist/routes/auto/delete.routes.js

@@ -6,7 +6,7 @@ export default async function deleteRoutes(fastify, options) {
         operation: 'delete',
         singlePkOnly: true,
         method: 'DELETE',
-        url: (tc) => `/rest/${tc.Schema.tableName}/:id`,
+        url: (tableName) => `/rest/${tableName}/:id`,
         successStatus: 200,
         schemas: (_db, _table, tc) => {
             const pkField = primaryAsString(tc.primary);

package/dist/routes/auto/get.routes.js

@@ -6,7 +6,7 @@ export default async function getRoutes(fastify, options) {
         operation: 'get',
         singlePkOnly: true,
         method: 'GET',
-        url: (tc) => `/rest/${tc.Schema.tableName}/:id`,
+        url: (tableName) => `/rest/${tableName}/:id`,
         successStatus: 200,
         schemas: (db, table) => ({
             params: Type.Object({ id: Type.String() }),

package/dist/routes/auto/insert.routes.js

@@ -4,7 +4,7 @@ export default async function insertRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'insert',
         method: 'POST',
-        url: (tc) => `/rest/${tc.Schema.tableName}`,
+        url: (tableName) => `/rest/${tableName}`,
         successStatus: 201,
         schemas: (db, table) => ({
             body: InsertTableBody(db, table),

package/dist/routes/auto/route-helpers.d.ts

@@ -18,8 +18,11 @@ export interface AutoRouteSpec {
      */
     singlePkOnly?: boolean;
     method: 'GET' | 'POST' | 'PUT' | 'DELETE';
-    /** URL builder receiving the table configuration to read `Schema.tableName`. */
-    url: (tableConf: ITable) => string;
+    /**
+     * URL builder receiving the `DbTables` key — never `Schema.tableName`: several table
+     * configs may expose the same physical table, and each key needs its own route.
+     */
+    url: (tableName: string) => string;
     successStatus: 200 | 201;
     /** Build per-table schemas (body, params, querystring, response). Response is wrapped with `{ [successStatus]: ... }` automatically. */
     schemas: (dbTables: DbTables, tableName: string, tableConf: ITable) => RouteSchema;

package/dist/routes/auto/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ5F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AA6DD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Bf"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ5F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C;;;OAGG;IACH,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AA6DD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Bf"}

package/dist/routes/auto/route-helpers.js

@@ -72,7 +72,7 @@ export async function registerForAllTables(fastify, options, spec) {
         const schemas = spec.schemas(DbTables, tableName, tableConf);
         fastify.route({
             method: spec.method,
-            url: spec.url(tableConf),
+            url: spec.url(tableName),
             schema: buildRouteSchema(tableName, tableConf, spec, schemas),
             onRequest: mergeOnRequests(options, tableConf),
             handler: async (request, reply) => {

package/dist/routes/auto/search.routes.js

@@ -6,7 +6,7 @@ export default async function searchRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'search',
         method: 'POST',
-        url: (tc) => `/search/${tc.Schema.tableName}`,
+        url: (tableName) => `/search/${tableName}`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: SearchTableBodyPost(db, table),
@@ -24,7 +24,7 @@ export default async function searchRoutes(fastify, options) {
                 leftAliases.length && `Available joinLeft aliases: ${leftAliases.join(', ')}`,
             ].filter(Boolean).join('. ');
         },
-        handle: async (fastify, tableName, tc, request) => {
+        handle: async (fastify, tableName, _tc, request) => {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const body = request.body;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -52,7 +52,7 @@ export default async function searchRoutes(fastify, options) {
                 computeAvg: query.computeAvg,
                 maxRows,
             }, request);
-            return { table: tc.Schema.tableName, ...result };
+            return { table: tableName, ...result };
         },
     });
 }

package/dist/routes/auto/update.routes.js

@@ -4,7 +4,7 @@ export default async function updateRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'update',
         method: 'PUT',
-        url: (tc) => `/rest/${tc.Schema.tableName}`,
+        url: (tableName) => `/rest/${tableName}`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: UpdateTableBody(db, table),

package/dist/types/cli.d.ts

@@ -53,6 +53,12 @@ export interface ColumnInfo {
      * simple enough for the engine to make updatable accepts a write.
      */
     is_view?: boolean;
+    /**
+     * Names of the unique indexes (constraints included) this column belongs to, the primary key
+     * excluded. Only indexes over plain columns with no predicate: a partial or expression index
+     * cannot be named by a column list, so it cannot be an upsert key (ADR 0021).
+     */
+    unique_keys?: string[];
 }
 export interface TableMap {
     [schemaName: string]: {
@@ -65,6 +71,11 @@ export interface TableMap {
         generated: string[];
         /** True when this relation is a view (or a materialized view), not a base table. */
         isView: boolean;
+        /**
+         * Unique keys other than the primary key, each as its fields (camelCase). Always set by
+         * `buildTableMap`; absent only on a map built by hand.
+         */
+        uniqueKeys?: string[][];
     };
 }
 //# sourceMappingURL=cli.d.ts.map

package/dist/types/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mFAAmF;QACnF,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,oFAAoF;QACpF,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mFAAmF;QACnF,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,oFAAoF;QACpF,MAAM,EAAE,OAAO,CAAC;QAChB;;;WAGG;QACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;KACzB,CAAC;CACH"}

package/dist/types/schema.d.ts

@@ -15,6 +15,13 @@ export interface SchemaDefinition<T = Record<string, TSchema>> {
      * turn a client mistake into a driver error.
      */
     generatedFields?: string[];
+    /**
+     * The table's unique keys other than the primary key, each as its fields (camelCase), as
+     * introspected from the DB. Set by generated schemas — always, even when empty, so an absent
+     * property means "not known" rather than "none". `defineTable` verifies every `upsertMap`
+     * rule against `primaryKey` and these (ADR 0021).
+     */
+    uniqueKeys?: string[][];
     /**
      * True when the underlying relation is a view. Set by generated schemas.
      *

package/dist/types/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/types/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/types/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/docs/adr/0020-no-conditional-or-mass-update-route.md

@@ -0,0 +1,68 @@
+# 0020. No conditional or mass update route — a predicate write is a custom route
+
+- **Status**: accepted
+- **Date**: 2026-09-24
+
+## Context
+
+The `update` route addresses exactly one row: its `WHERE` is every primary key column plus
+the tenant scope, and nothing the client sends can add to it. Two real needs fall outside
+that shape:
+
+- **Compare-and-set.** Claiming a row so that two clients cannot both claim it
+  (`UPDATE … SET in_progress_since = now() WHERE id = ? AND in_progress_since IS NULL`),
+  guarded state transitions (`… AND status = 'draft'`), optimistic locking on a `version`
+  column. Correctness depends on the check and the write being one statement; a
+  `beforeUpdate` that reads first and writes after is exactly the race it is meant to
+  prevent.
+- **Mass update by predicate.** Setting a value on every row matching a filter.
+
+A route was designed to cover both: a new `updateWhere` operation, opt-in (registered only
+when listed in `operations`), `PUT {p}/update/{key}` with `{ where: { filters, conditions },
+fields }` reusing the search grammar, the tenant guard injected, `validate`/`beforeUpdate`
+run on `fields`, `{ affected }` in response. Compare-and-set is then a `where` that includes
+the primary key.
+
+## Decision
+
+The plugin does not expose a conditional or mass update route, and the single-row `update`
+does not accept a precondition. A write whose target is a predicate is built as a custom
+route on `QueryClient.update(table, fields, where, extraCondition)`, which already takes a
+`ConditionBuilder` and returns the number of rows it changed.
+
+The design was sound; the cost was not worth it. It is the first route that writes N rows
+chosen by the client, so a defect in it is destructive and tenant-crossing rather than a
+wrong answer. Building it touches several security-sensitive pieces at once:
+
+- `QueryClient.update`, which today assumes an equality `where` and would emit `WHERE  AND …`
+  for a condition-only one;
+- the search condition builder, shared with every read;
+- the tenant guards, which on update are keyed on a primary key (`assertTenantOwnership`)
+  and would need the row-guard form for indirect scopes instead;
+- the meaning of `validate`, `beforeUpdate` and `afterUpdate`, whose `record` would no longer
+  carry a primary key — breaking any existing hook that reads one.
+
+Against that, the need is narrow and the custom route is a few lines, owned by the consumer
+who knows the predicate it must enforce.
+
+## Alternatives considered
+
+- **`updateWhere` operation, opt-in** — the design above. Rejected for the risk and blast
+  radius described in the decision, not for a flaw in its shape.
+- **`expect` on the single-row `update`** (a precondition next to the primary key, `409` when
+  it fails) — rejected: it narrows the write instead of widening it, so the blast radius is
+  small, but it still reopens the update `WHERE` to client-supplied predicates, and it needs
+  a readability rule to avoid an oracle (see Consequences). One custom route covers it.
+- **Read-then-write in `beforeUpdate`** — not an alternative: two concurrent requests both
+  pass the read.
+
+## Consequences
+
+- Compare-and-set and predicate updates are custom routes. [AGENTS_BACKEND.md](../../AGENTS_BACKEND.md)
+  carries the pattern ("Conditional update — claim a row atomically").
+- Everything the auto routes do for free is the custom route's job there: `QueryClient` runs
+  no hooks, no validation and **no tenant scoping**, so the route must add its own tenant
+  predicate and must not let a client-chosen predicate reach a column the caller cannot read —
+  otherwise `affected: 0 | 1` becomes an oracle on its value.
+- Revisit only with a concrete, repeated need that a custom route serves badly; the design
+  notes above are the starting point.