@simtlix/simfinity-postgres 3.12.0 → 3.14.0

package/README.md

@@ -31,7 +31,7 @@ import { postgresPlugin } from '@simtlix/simfinity-postgres';
 const simfinity = createSQL({ plugin: postgresPlugin({ pool, schema: 'library' }) });
 ```
 
-Install `@simtlix/simfinity-sql@3.12.0` as a direct dependency when importing its factory. PostgreSQL 15 or later is the only supported SQL plugin. The [SQL package guide](https://github.com/simtlix/simfinity.js/tree/master/packages/sql) documents relational planning and the versioned plugin contract.
+Install `@simtlix/simfinity-sql@3.14.0` as a direct dependency when importing its factory. PostgreSQL 15 or later is the only supported SQL plugin. The [SQL package guide](https://github.com/simtlix/simfinity.js/tree/master/packages/sql) documents relational planning and the versioned plugin contract.
 
 Both factories permanently bind one pool and schema, and five optional settings: `multiRowInserts: false` keeps one `INSERT` per owned row instead of multi-row statements; `explicitNullsOrder: true` keeps the `NULLS` clause on sorts of `id` and required fields, as 3.5.9 did, instead of letting indexes serve them; `batchedCollections: true` reads the generated collection fields of the parents that share their arguments with one statement per 100 parents, in a transaction that turns JIT off for that transaction only, instead of one statement per field as 3.6.0 did and as the default still does, and can return unsorted and tied rows in another order; the opt-in `refreshTriggers: 'perRoot'` refreshes each changed root's owned shape and unique keys once per transaction, while its guard trigger stays deferred, instead of once per changed row; and the opt-in `ownerIndexes: 'minimal'` leaves out the `(__owner_id)` indexes that the primary key or a unique index covers on new owned and guard tables. An unknown `refreshTriggers` or `ownerIndexes` value throws `INVALID_DATABASE_SCHEMA` (400). Read the [upgrade notes](https://simtlix.github.io/simfinity.js/resources/compatibility.html#upgrade-to-3-6-0) before enabling the opt-ins: versions up to 3.5.9 cannot validate databases created with them. The returned runtime supports registration, generated queries and mutations, middleware and scopes, controllers and validators, custom queries and mutations, named views, state machines, nested relationship writes, embedded reconstruction, and native PostgreSQL model handles. Native handles expose `findById`, `find`, `create`, `update`, and `delete`; they are not Mongoose models. `find(args, { session })` accepts the generated GraphQL list query arguments. Existing `pg.Pool` configuration and `pg.PoolClient` query interfaces remain compatible across both factories. A custom pool or client wrapper should pass `pg`'s `command` through in query results: the plugin reads it from the `COMMIT` result to detect a transaction that PostgreSQL rolled back because one of its statements failed, and without it such a transaction reports success with nothing stored.
 
@@ -62,7 +62,7 @@ The module and every `createPostgres` instance expose the shared `auth`, `valida
 MCP integration is an independent opt-in and does not add MCP dependencies to PostgreSQL applications:
 
 ```sh
-npm install @simtlix/simfinity-mcp@3.12.0 @modelcontextprotocol/sdk@^1.31.0
+npm install @simtlix/simfinity-mcp@3.14.0 @modelcontextprotocol/sdk@^1.31.0
 ```
 
 ```javascript
@@ -79,7 +79,9 @@ Queries support nested scalar/reference paths, logical filter groups, scopes, so
 
 The text operators take literal values as bound parameters. `LIKE`, `STARTS_WITH` and `ENDS_WITH` compare code points, and `STARTS_WITH` can use a column's btree index. `ILIKE`, `ISTARTS_WITH`, `IENDS_WITH` and `IEQ` fold both sides with the Unicode simple case foldings that MongoDB's case-insensitive matching applies, through one expression, `translate(lower((x) COLLATE "pg_catalog"."und-x-icu"), from, to)`, where `translate()` maps the 22 lowercase variants that ICU `lower()` keeps, such as `ſ`, `µ` and the final sigma `ς`, to their usual letters; so each returns every row that its case-sensitive form returns, and `ISTARTS_WITH "ΚΑΣ"` finds `ΚΑΣΤΡΟ`. The first three match a `LIKE` pattern whose `%`, `_` and `\` are escaped. The two backends still differ on `İ`, which ICU lowers to `i` followed by U+0307, and on letters newer than one side's Unicode tables. The fold needs a `UTF8` database on a server built with ICU: on another, such as one in `LATIN1`, these four operators fail with `UNSUPPORTED_QUERY` (400), and every other operation works. Indexes serve them only on exactly the compiled expression, which the exported `caseFoldExpression(sqlExpression)` returns, such as `caseFoldExpression('"name"')`: a btree with `text_pattern_ops` on it serves `IEQ` and `ISTARTS_WITH`, and a `pg_trgm` GIN index with `gin_trgm_ops` serves `ILIKE`, `ISTARTS_WITH` and `IENDS_WITH`. The [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html#case-folding) gives the details and the index statements.
 
-`IS_EMPTY` and `IS_NOT_EMPTY` take no value and test the queried record's own fields: a missing, null or `""` String, a missing or null value of any other scalar, a missing, null or `[]` list, and an embedded object that is missing, null or has every stored member empty. They compile from where the path is stored and bind no parameters: `(c IS NULL OR c = '')` for a String column, so that a btree serves it through a `BitmapOr`, `c IS NULL` for any other column, including the uuid identity of a record whose `id` is declared `String`, and `COALESCE(cardinality(c), 0) = 0` for a native array, also on owned rows; a jsonb member is read as text with `->>` and never cast, a jsonb list through a `jsonb_typeof` guard, and a jsonb object as SQL `NULL`, JSON `null` or all of its members empty; an owned single object is empty when its state is not `present` or no owned row has a member that is not empty, and an owned list when its state is not `present` or it has no row, null items included, with a subquery alias of its own at each level of owned storage. `IS_NOT_EMPTY` is the positive form of a leaf and the `NOT` of an object or owned form, so every record matches exactly one of the two. A path that continues inside an embedded list or a collection, such as `lines.qty` or `seasons.year`, fails with the permanent `INVALID_FILTER_PATH` (400), since emptiness of a value inside a list is not defined. The [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html) describes the rules.
+`IS_EMPTY` and `IS_NOT_EMPTY` take no value and test the queried record's own fields: a missing, null or `""` String, a missing or null value of any other scalar, a missing, null or `[]` list, and an embedded object that is missing, null or has every stored member empty. They compile from where the path is stored and bind no parameters: `(c IS NULL OR c = '')` for a String column, so that a btree serves it through a `BitmapOr`, `c IS NULL` for any other column, including the uuid identity of a record whose `id` is declared `String`, and `COALESCE(cardinality(c), 0) = 0` for a native array, also on owned rows; a jsonb member is read as text with `->>` and never cast, a jsonb list through a `jsonb_typeof` guard, and a jsonb object as SQL `NULL`, JSON `null` or all of its members empty; an owned single object is empty when its state is not `present` or no owned row has a member that is not empty, and an owned list when its state is not `present` or it has no row, null items included, with a subquery alias of its own at each level of owned storage. `IS_NOT_EMPTY` is the positive form of a leaf and the `NOT` of an object or owned form, so every record matches exactly one of the two. An emptiness path that continues inside an embedded list, such as `lines.qty`, fails with `INVALID_FILTER_PATH` (400), since emptiness of an item inside that list is not defined. Through a collection, use an explicit frame and test the element's own field (for example `ANY seasons` with `year IS_EMPTY`); the flattened `seasons.year IS_EMPTY` shorthand is excluded. The [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html) describes the rules.
+
+The plugin declares `queryFeatures.quantifiers: true`: collection filter paths compile to correlated `EXISTS` frames, so lists, counts and pagination return each matching parent once. Terms on the same collection prefix in one filter group must match the same child; separate groups may match different children. Explicit `ANY`, `NONE` and `ALL` groups and relation filters' `quantifier` also support single references. `NONE` and `ALL` are true when there are no visible elements; `ALL` uses `NOT EXISTS` over a null-safe failing body, so a null operand fails an ordinary ordering condition. A frame without conditions is equivalent to collection emptiness (`ANY` to `IS_NOT_EMPTY`, `NONE` to `IS_EMPTY`); `ALL` without conditions is literal `TRUE`, including inside `OR`. Client frames and references inside them apply the target's `find` scope; trusted frames read stored data. A reference reached through an embedded list keeps its vector join when the target scope adds nothing, including after a restricted single-reference prefix; a target scope that adds conditions there is forbidden. Aggregate filters on collection prefixes already joined by groupId or facts keep those joins and their multiplicity, and later collection frames correlate to the joined alias. Sort paths cannot cross collections in any mode. Under a top-level `AND`, a frame can probe the child's connection index as a semi-join or anti-join; under `OR`, PostgreSQL may run a correlated or hashed subplan, so place selective record conditions in the top-level `AND`. Direct `createQueryPlan()` calls default to these frames; pass the plugin's declared flags when supplying operators. A plugin copy that overrides `compileQuery` must declare its own quantifier support. See the [query guide](https://simtlix.github.io/simfinity.js/guide/queries.html) for grouping and scope semantics.
 
 The plugin also declares `queryFeatures.referenceEmptiness`, so `IS_EMPTY` and `IS_NOT_EMPTY` cross single references and end at references and collections, such as `serie.name`, `serie` and `seasons`, and an embedded object's reference members count. A client's condition reads as missing every record that the target's `find` scope hides. The references it crosses share the plain `LEFT JOIN` of other conditions while the scopes crossed so far add nothing, as for an administrator or a target without a `find` scope; from the first scope that adds conditions on, each crossing is a `LEFT JOIN LATERAL (SELECT ... WHERE id = <reference> AND <scope> LIMIT 1)`, and later hops correlate to that join even when their own scope adds nothing. A reference end, and a reference member of an owned row, whose scope adds conditions is a `NOT EXISTS` subquery with the scope, `EXISTS` for `IS_NOT_EMPTY`, which probes the target's primary key; one whose scope adds nothing compiles to `"ref" IS NULL`, `IS NOT NULL` for `IS_NOT_EMPTY`, as a trusted one does, which the generated btree on the reference column serves. A collection end or member is always a `NOT EXISTS` subquery, `EXISTS` for `IS_NOT_EMPTY`, on the child's indexed connection column, with the scope when it adds conditions. So a client's condition whose scopes all add nothing compiles exactly as a trusted one. The target's `id` right after a reference is its uuid key, under the null rule, whatever scalar it is declared with. Scope values are bound parameters, and each subquery has aliases of its own, numbered across the statement. Conditions that middleware and scopes add read stored data: a reference is empty when its column is `NULL`, which a btree serves and which its foreign key, validated and not deferred, keeps exact, a collection when no child row points to the record, and a leaf through a reference reads the plain `LEFT JOIN` that other conditions on that path share. A transaction that defers the foreign keys with `SET CONSTRAINTS ... DEFERRED` can read a reference to a row it deleted as not empty in the `"ref" IS NULL` form, trusted or client, until it commits. A copy such as `{ ...postgresPlugin(options), compileQuery: myCompileQuery }` inherits a declaration that does not describe its compiler, so it gets `UNSUPPORTED_QUERY` (400) for these paths, as for the operators added after 3.7.0, until it declares its own.
 
@@ -93,6 +95,16 @@ Scalar-list leaves inside nested embedded lists support filters, sorts, ragged g
 
 The following mappings remain unsupported and fail explicitly: implicit many-to-many reciprocal lists, non-embedded collections inside embedded objects, embedded cycles, nested list wrappers, whole embedded-object uniqueness, conflicting relationship metadata, enum values that collide after text conversion, and stored custom scalars without a recognized base scalar. Query paths cannot sort or group whole embedded objects. Arbitrary MongoDB pipelines and Mongoose-native methods are outside the PostgreSQL contract.
 
+## Optimistic concurrency
+
+Declare `extensions: { concurrency: { mode: 'optimistic' } }` on an entity before building its schema to receive the managed `version` field. PostgreSQL stores it as `bigint NOT NULL DEFAULT 1`; migrating an existing table requires an explicit migration, such as `ALTER TABLE "library"."Book" ADD COLUMN "version" bigint NOT NULL DEFAULT 1;`. Updates atomically match the ID and expected version and advance it, including version-only updates. Those updates fire the touch and refresh triggers of maintained roots. Stale writes fail with `VERSION_CONFLICT` (409); an update at `MAX_RECORD_VERSION` fails with `VERSION_EXHAUSTED` (409), while a delete at that version remains valid. Valid bigint values from `pg`, including a custom BigInt parser, are decoded to numbers; unsafe stored values remain invalid rather than being rounded into valid versions. `RecordVersion` and `MAX_RECORD_VERSION` are shared core exports.
+
+Initialization in both `create` and `validate` modes rejects a missing or differently defined version column with `SCHEMA_MISMATCH`, explaining the required definition and, when absent, the qualified `ALTER TABLE ... ADD COLUMN` statement. An instance without the concurrency declaration also cannot initialize while its table retains the bigint version column: deploy the declaration on that instance, or stop every protected instance before dropping the column for a rollback. Run the adding migration immediately before the first protected instance starts; instances already running without the declaration can still write without advancing versions. Initialization never migrates the column automatically.
+
+Protected native handles initialize `model.create(data)` at version 1. Use `model.update(id, { ...changes, version: record.version }, { session })` and `model.delete(id, { session, version: record.version })`. The update captures the version once before transaction retries without mutating your changes. Missing versions fail with `REQUIRED_VALUE` (400) and a message explaining the handle protocol. For a derived value that a hook maintains in the same transaction, `model.update(id, changes, { session, version: false })` writes without checking or advancing the version and ignores `changes.version`; delete also accepts `version: false`. Handles still bypass validators, hooks, scopes and authorization. Unprotected handles keep their existing behavior and ignore the option. Native SQL writers must follow the same conditional-write protocol to participate; writes that bypass it are not detected.
+
+The plugin declares `optimisticConcurrency`. Copies overriding `compileRecord` must honor `operation.version` or delegate versioned updates and deletes to the original compiler. Versioned deletes use `RETURNING id`, including after the SQL runtime's locked read. Record-result checks report `DATABASE_ERROR` for inconsistent update versions or a missing delete result; they are defensive diagnostics and cannot prove that arbitrary overrides preserved the atomic condition.
+
 ## Low-level schema API
 
 The foundation API remains available independently of a runtime:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-postgres",
-  "version": "3.12.0",
+  "version": "3.14.0",
   "description": "PostgreSQL GraphQL runtime and schema generation with foreign keys for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -27,8 +27,8 @@
     "directory": "packages/postgres"
   },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.12.0",
-    "@simtlix/simfinity-sql": "3.12.0",
+    "@simtlix/simfinity-core": "3.14.0",
+    "@simtlix/simfinity-sql": "3.14.0",
     "pg": "^8.16.3"
   },
   "peerDependencies": {

package/src/codecs.js

@@ -2,7 +2,7 @@ import { getNamedType, isEnumType } from 'graphql';
 import { SimfinityError } from '@simtlix/simfinity-core';
 import { isCaseFoldUnsupported } from './query/case-fold.js';
 
-export const storageTypes = { ID: 'uuid', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone' };
+export const storageTypes = { ID: 'uuid', Version: 'bigint', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone' };
 export const invalidValue = (message) => { throw new SimfinityError(message, 'INVALID_FILTER_VALUE', 400); };
 export const castId = (value) => {
   const id = typeof value === 'object' && value ? value._id || value.id : value;
@@ -23,6 +23,7 @@ export const encodeScalar = (field, value) => {
     }
     case 'String': if (typeof value !== 'string') invalidValue(`Expected a string for ${field.name}`); break;
     case 'Boolean': if (typeof value !== 'boolean') invalidValue(`Expected a boolean for ${field.name}`); break;
+    case 'Version': if (!Number.isSafeInteger(value) || value < 1) invalidValue(`Expected a safe positive integer for ${field.name}`); break;
     case 'Int': if (!Number.isInteger(value) || value < -2147483648 || value > 2147483647) invalidValue(`Expected a 32-bit integer for ${field.name}`); break;
     case 'Float': if (typeof value !== 'number' || !Number.isFinite(value)) invalidValue(`Expected a finite number for ${field.name}`); break;
     case 'DateTime': {
@@ -37,6 +38,10 @@ export const encodeScalar = (field, value) => {
 
 export const decodeScalar = (field, value, gqlField) => {
   if (value == null) return value;
+  if (field.scalar === 'Version' && ['string', 'number', 'bigint'].includes(typeof value)) {
+    const version = Number(value);
+    return Number.isSafeInteger(version) && version >= 1 ? version : value;
+  }
   if (field.scalar === 'Enum' && gqlField) {
     const type = getNamedType(gqlField.type);
     if (isEnumType(type)) return type.getValues().find((item) => String(item.value) === value)?.value ?? value;

package/src/index.js

@@ -11,7 +11,9 @@ export {
   buildErrorFormatter,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
   plugins,
+  RecordVersion,
   scalars,
   SimfinityError,
   validators,

package/src/plugin.js

@@ -17,15 +17,16 @@ export const postgresPlugin = (options) => ({
   options: options || null,
   // singleStatementReads: one statement reads one snapshot at any isolation level, so a read without owned
   // tables needs no repeatable-read transaction.
-  capabilities: ['transactions', 'foreignKeys', 'deferredForeignKeys', 'embeddedValues', 'ownedRecords', 'scalarLists', 'uniqueValues', 'nullableUnique', 'singleStatementReads'],
+  capabilities: ['transactions', 'optimisticConcurrency', 'foreignKeys', 'deferredForeignKeys', 'embeddedValues', 'ownedRecords', 'scalarLists', 'uniqueValues', 'nullableUnique', 'singleStatementReads'],
   // Every filter operator compileQuery and compileChildrenQuery compile, listed one by one so that a later
   // QLOperator value is rejected until the compiler supports it, and emptiness through references and collections
   // (#108 part 2b): the scoped joins and frames of client constructs, and stored semantics for the others. The
   // declaration names the compileQuery it describes, so a copy of this plugin with another compileQuery compiles the
-  // operators of 3.7.0, without reference emptiness, until it declares its own.
+  // operators of 3.7.0, without reference emptiness or quantifiers, until it declares its own.
   queryFeatures: {
     operators: ['EQ', 'NE', 'LT', 'LTE', 'GT', 'GTE', 'BTW', 'IN', 'NIN', 'LIKE', 'ILIKE', 'STARTS_WITH', 'ISTARTS_WITH', 'ENDS_WITH', 'IENDS_WITH', 'IEQ', 'IS_EMPTY', 'IS_NOT_EMPTY'],
     referenceEmptiness: true,
+    quantifiers: true,
     compileQuery,
   },
   naming: { validateIdentifier: identifier, generatedName },

package/src/query/compiler.js

@@ -1,6 +1,6 @@
-import { resolveModelPath, SimfinityError } from '@simtlix/simfinity-core';
+import { QLQuantifier, resolveModelPath, SimfinityError } from '@simtlix/simfinity-core';
 import {
-  describeEmptiness, describeModelEmptiness, emptinessScopePaths, isEmptinessOperator, textQueryOperator, validateTextFilterValue,
+  crossingKeys, describeEmptiness, describeModelEmptiness, emptinessScopePaths, isEmptinessOperator, textQueryOperator, validateQuantifiedGroups, validateTextFilterValue,
 } from '@simtlix/simfinity-core/internal/query-operators';
 import { identifier as q, literal, qualified } from '../schema/sql.js';
 import { encodeScalar, storageTypes, invalidValue } from '../codecs.js';
@@ -13,9 +13,12 @@ const detached = (message) => {
   throw new SimfinityError(`${message}; only createQueryPlan writes the scopes of a predicate, from the client scope markers the runtime fills (docs/guide/middleware.md)`, 'DETACHED_CLIENT_FILTER', 500);
 };
 // The compiler compiles emptiness through single references and at references and collections (#108 part 2b), which
-// the PostgreSQL plugin declares as queryFeatures.referenceEmptiness.
+// the PostgreSQL plugin declares as queryFeatures.referenceEmptiness. Its quantifiers declaration additionally
+// enables correlated frames with element-relative conditions.
 const REFERENCE_EMPTINESS = true;
-const SCOPE_KINDS = ['predicate', 'and', 'or'];
+const SCOPE_KINDS = ['predicate', 'and', 'or', 'quantified'];
+// Entity identities use UUID operands even when GraphQL exposes id as String; embedded ids keep their scalar.
+const operandField = (field, identity) => (identity ? { ...field, scalar: 'ID' } : field);
 
 // The case-insensitive text operators compare the case fold of both sides (see case-fold.js), so an application
 // index serves them only on that expression, which caseFoldExpression writes.
@@ -127,6 +130,12 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
     return joins.get(key).alias;
   };
   const joinsOf = (frame) => [...frame.joins.values()].map((item) => item.sql).join(' ');
+  // One correlated truth value, even when its joins produce several witnesses for the containing row.
+  // The constant FROM row lets every join retain its original correlation to frame.alias outside this SELECT.
+  const witness = (frame, condition) => {
+    const joins = joinsOf(frame);
+    return `EXISTS (SELECT 1 FROM (SELECT 1) simfinity_witness${joins ? ` ${joins}` : ''} WHERE ${condition})`;
+  };
   // The owned table that stores `field` of the row `context`, or undefined when the row stores it; values inside
   // jsonb never own tables.
   const ownedOf = (context, field) => context.table && database.tables.find((item) => item.ownership?.ownerTable === context.table.name && item.ownership.field === field.name);
@@ -170,13 +179,22 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
     const child = project({ json: `${name}.value` }, rest);
     return `CASE WHEN jsonb_typeof(${value}) = 'array' THEN (SELECT COALESCE(jsonb_agg(${child} ORDER BY ${name}.ordinality) FILTER (WHERE ${child} IS NOT NULL), '[]'::jsonb) FROM ${jsonItems(value)} WITH ORDINALITY ${name}(value, ordinality)) END`;
   };
-  const path = (parts, usage = 'filter', frame = rootFrame) => {
+  const sortPath = (parts, frame = rootFrame) => {
     const steps = resolveModelPath(models, frame.entity, parts);
-    let context = { table: frame.table, alias: frame.alias, json: null, vector: null };
-    for (let index = 0; index < steps.length; index++) {
+    const index = steps.findIndex((field) => field.kind === 'collection');
+    if (index >= 0) throw new SimfinityError(`Sort path ${parts.join('.')} crosses the collection ${index ? steps[index - 1].target : frame.entity}.${steps[index].name}; a record has no single value there`, 'INVALID_FILTER_PATH', 400);
+    return steps;
+  };
+  const path = (parts, usage = 'filter', frame = rootFrame, joins = null) => {
+    const steps = usage === 'sort' ? sortPath(parts, frame) : resolveModelPath(models, frame.entity, parts);
+    let context = joins && usage !== 'cross' ? cross(frame, parts.slice(0, -1), joins) : { table: frame.table, alias: frame.alias, json: null, vector: null };
+    const chain = [];
+    let scoped = false;
+    const chainKey = (key) => `scoped ${key} ${scopeIdentity(chain, identities)}`;
+    for (let index = joins && usage !== 'cross' ? steps.length - 1 : 0; index < steps.length; index++) {
       const field = steps[index];
       const key = parts.slice(0, index + 1).join('.');
-      const last = index === steps.length - 1;
+      const last = usage !== 'cross' && index === steps.length - 1;
       if (usage === 'aggregate' && steps.slice(index).some((item) => item.list) && !steps.slice(index).some((item, offset, remaining) => item.target && offset < remaining.length - 1)) {
         const leaf = steps.at(-1);
         if (leaf.kind !== 'scalar') unsupported('Whole embedded objects cannot be sorted or aggregated');
@@ -191,7 +209,7 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
           const state = `${col(ownerAlias, owned.ownership.stateColumn)} = 'present'`;
           const presence = (name) => owned.ownership.nullableItems && usage !== 'sort' ? ` AND ${col(name, '__item_present')}` : '';
           if (!field.list && !context.vector) {
-            context = { table: owned, alias: joinOwned(frame, key, context, owned), json: null, vector: null };
+            context = { table: owned, alias: joinOwned(frame, scoped ? chainKey(key) : key, context, owned), json: null, vector: null };
           } else {
             const name = alias();
             const stored = alias();
@@ -223,13 +241,23 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
       } else if (field.target && !last) {
         if (context.json) unsupported('Unnormalized embedded reference');
         const source = context;
-        const joined = join(frame, key, field.target, (name) => {
+        const scope = field.kind === 'reference' ? scopeAt(joins, key) : null;
+        if (field.kind === 'reference') chain.push(scope);
+        scoped ||= scope !== null;
+        if (source.vector && scope !== null) throw new SimfinityError('A reference inside an embedded list cannot apply a target scope', 'FORBIDDEN_FILTER_PATH', 403);
+        if (source.vector) frame.multiplying = true;
+        const correlation = (name) => {
           if (field.kind === 'collection') return `${col(name, field.connectionField)} = ${col(source.alias, source.table.primaryKey.columns[0])}`;
           const reference = col(source.alias, field.storageName);
           return source.vector
             ? `${col(name, 'id')} = ANY (${arrayFrom(source.vector, reference)})`
             : `${col(name, 'id')} = ${reference}`;
-        });
+        };
+        // A vector with an empty target scope keeps every referenced row. Its restricted base and
+        // chain-isolated key still prevent sharing with trusted joins; LIMIT 1 would lose targets.
+        const joined = scoped && !source.vector
+          ? scopedJoin(frame, chainKey(key), field, context, scope, correlation)
+          : join(frame, scoped ? chainKey(key) : key, field.target, correlation);
         context = { table: tableByName(field.target), alias: joined, json: null, vector: null };
       } else {
         if (!last || (field.kind !== 'scalar' && !field.inferred)) unsupported('A query path must end at a scalar field');
@@ -267,9 +295,10 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
         // embedded paths can be NULL even for NOT NULL columns, so they keep the clause.
         const notNull = !context.json && !context.vector && !field.list && context.alias === frame.alias
           && context.table.columns.find((item) => item.name === (identity ? 'id' : field.storageName))?.nullable === false;
-        return { sql, uncollated, field: identity ? { ...field, scalar: 'ID' } : field, type: dateNumeric ? 'double precision' : type, list: field.list || !!context.vector, vector: !!context.vector, dateNumeric, sortKey, notNull };
+        return { sql, uncollated, field: operandField(field, identity), type: dateNumeric ? 'double precision' : type, list: field.list || !!context.vector, vector: !!context.vector, dateNumeric, sortKey, notNull };
       }
     }
+    if (usage === 'cross') return context;
     unsupported('Invalid query path');
   };
   /**
@@ -367,16 +396,17 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
    * A subquery on the entity `entity` in a frame of its own (#108 part 2b), as `{ alias, from }`, `from` being its
    * text from FROM to the end of its WHERE. `correlation(alias)` ties its rows to the enclosing row, and `scope`, a
    * predicate planned on the entity, or null, restricts them. The frame's alias comes first, then the scope's joins
-   * and conditions, which compile before the text is assembled so that the FROM holds their joins. A scope is trusted:
-   * it reads stored data through plain joins of its own frame.
+   * and conditions, followed by the optional body, compile before the text is assembled so that FROM holds their
+   * joins. A scope is trusted: it reads stored data in its own frame, with plain reference joins and collection frames.
    */
-  const subquery = (entity, correlation, scope) => {
+  const subquery = (entity, correlation, scope, body) => {
     const table = tableByName(entity);
     if (!table) unsupported(`Unknown persistent entity ${entity}`);
     const frame = { entity, table, alias: alias(), joins: new Map() };
     const restriction = scope ? ` AND ${where(scope, frame)}` : '';
+    const condition = body ? ` AND ${body(frame)}` : '';
     const joins = joinsOf(frame);
-    return { alias: frame.alias, from: `FROM ${qualified(database.schema, table.name)} ${frame.alias}${joins ? ` ${joins}` : ''} WHERE ${correlation(frame.alias)}${restriction}` };
+    return { alias: frame.alias, from: `FROM ${qualified(database.schema, table.name)} ${frame.alias}${joins ? ` ${joins}` : ''} WHERE ${correlation(frame.alias)}${restriction}${condition}` };
   };
   /**
    * The scoped join of a client construct's crossing (#108 part 2b): the record that the reference `field` of the row
@@ -384,10 +414,10 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
    * keeps one row whatever joins the scope makes. Its key, apart from those of plain joins, names the path and the
    * scopes of every reference crossed up to this one, so only constructs with the same chain share it.
    */
-  const scopedJoin = (frame, key, field, context, scope) => {
+  const scopedJoin = (frame, key, field, context, scope, correlation = (row) => `${col(row, 'id')} = ${col(context.alias, field.storageName)}`) => {
     if (!frame.joins.has(key)) {
       const name = alias();
-      const target = subquery(field.target, (row) => `${col(row, 'id')} = ${col(context.alias, field.storageName)}`, scope);
+      const target = subquery(field.target, correlation, scope);
       frame.joins.set(key, { alias: name, sql: `LEFT JOIN LATERAL (SELECT ${target.alias}.* ${target.from} LIMIT 1) ${name} ON TRUE` });
     }
     return frame.joins.get(key).alias;
@@ -411,6 +441,10 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
     }
     return scopes;
   };
+  // Reuse legacy vector/owned traversal while applying the validated scoped chain in this frame.
+  const cross = (frame, parts, joins) => (parts.length
+    ? path(parts, 'cross', frame, joins)
+    : { table: frame.table, alias: frame.alias, json: null, vector: null });
   /**
    * NONE over a reference or a collection (#108 part 2b), the IS_EMPTY form, or with `empty` false the IS_NOT_EMPTY
    * form, EXISTS: whether a record that `scope` admits is the one the reference `field` of the row `context` points
@@ -499,42 +533,93 @@ const compileSelect = (models, database, plan, extra, configuration, batched) =>
     const gqltype = models.entities.find((item) => item.name === frame.entity)?.gqltype;
     const shape = gqltype ? describeEmptiness(gqltype, parts, options) : describeModelEmptiness(steps, options);
     const scopes = scopesOf(node, shape, `${operator} on ${label}`);
-    let context = { table: frame.table, alias: frame.alias, json: null };
-    // The scopes of the references crossed so far; once one of them is not null, the chain is scoped.
-    const chain = [];
-    let scoped = false;
-    const chainKey = (key) => `scoped ${key} ${scopeIdentity(chain, identities)}`;
-    steps.slice(0, -1).forEach((field, index) => {
-      const key = parts.slice(0, index + 1).join('.');
-      if (field.kind === 'embedded' && !field.list) {
-        const owned = ownedOf(context, field);
-        context = owned
-          ? { table: owned, alias: joinOwned(frame, scoped ? chainKey(key) : key, context, owned), json: null }
-          : { table: null, alias: null, json: context.json ? `(${context.json} -> ${literal(field.storageName)})` : col(context.alias, field.storageName) };
-      } else if (field.kind === 'reference' && !field.inferred && context.table) {
-        const scope = scopeAt(scopes, key);
-        chain.push(scope);
-        scoped ||= scope !== null;
-        const joined = scoped
-          ? scopedJoin(frame, chainKey(key), field, context, scope)
-          : join(frame, key, field.target, (name) => `${col(name, 'id')} = ${col(context.alias, field.storageName)}`);
-        context = { table: tableByName(field.target), alias: joined, json: null };
-      } else unsupported('Invalid query path');
-    });
+    const context = cross(frame, parts.slice(0, -1), scopes);
     return emptyForm(context, steps.at(-1), shape, operator === 'IS_EMPTY', { path: label, scopes });
   };
+  const queryScope = (scope) => scope === null || (scope && typeof scope === 'object' && !Array.isArray(scope) && SCOPE_KINDS.includes(scope.kind));
+  const inspectJoins = (node, frame) => {
+    if (!Object.hasOwn(node, 'joins')) return { joins: null };
+    if (node.anchor) return { reason: 'A quantified anchor has joins' };
+    const { joins } = node;
+    if (!joins || typeof joins !== 'object' || Array.isArray(joins) || ![Object.prototype, null].includes(Object.getPrototypeOf(joins))) return { reason: 'A predicate has joins that are not a plain object' };
+    for (const key of crossingKeys(node.path, { models, entity: frame.entity })) {
+      if (!Object.hasOwn(joins, key) || !queryScope(joins[key])) return { reason: `A predicate has no valid join scope for ${key}` };
+    }
+    return { joins };
+  };
+  const joinsOfNode = (node, frame) => {
+    const result = inspectJoins(node, frame);
+    if (result.reason) detached(result.reason);
+    return result.joins;
+  };
+  const quantified = (node, frame) => {
+    const parts = node.path;
+    // Resolve before crossing so malformed client metadata cannot fall back to trusted joins.
+    const targetEntity = node.anchor ? resolveModelPath(models, frame.entity, node.anchor).at(-1).target : frame.entity;
+    const steps = resolveModelPath(models, targetEntity, parts);
+    const field = steps.at(-1);
+    if (field?.kind === 'embedded' && field.list) unsupported('Quantified groups over embedded lists are not supported by this query compiler');
+    if (!field || field.inferred || !['reference', 'collection'].includes(field.kind) || field.list && field.kind !== 'collection') {
+      throw new SimfinityError('A quantified path must end at a reference or collection', 'INVALID_FILTER_PATH', 400);
+    }
+    if (!QLQuantifier.getValue(node.quantifier)) throw new SimfinityError('Unknown quantifier', 'INVALID_FILTER_VALUE', 400);
+    if (node.anchor && parts.length !== 1) detached('An anchored quantified path must name the collection or reference alone');
+    const joins = joinsOfNode(node, frame);
+    if (Object.hasOwn(node, 'scope') && !queryScope(node.scope)) detached('A quantified predicate has an invalid scope');
+    if (node.quantifier === 'ALL' && node.where === null) return 'TRUE';
+    // An implicit vector prefix belongs to this predicate, never the containing record's outer row stream.
+    // Anchors deliberately retain the legacy joins/multiplicity of aggregate groupId and facts.
+    const isolatedPrefix = !node.anchor && steps.slice(0, -1).some((step) => step.list);
+    const prefix = isolatedPrefix ? { ...frame, joins: new Map(), multiplying: false } : frame;
+    const context = node.anchor ? cross(frame, node.anchor, null) : cross(prefix, parts.slice(0, -1), joins);
+    if (!context.table) unsupported('Unnormalized embedded reference');
+    const correlation = field.kind === 'reference'
+      ? (row) => `${col(row, 'id')} = ${col(context.alias, field.storageName)}`
+      : (row) => `${col(row, field.connectionField)} = ${col(context.alias, context.table.primaryKey.columns[0])}`;
+    const body = node.where === null ? undefined : (child) => {
+      // A scope admits the child independently of the body's vector witness. Otherwise retain shared
+      // nonmultiplying joins and their aliases; complete compounds within each body still share one map.
+      const scopedVector = child.multiplying === true;
+      const positiveFrame = { ...child, joins: new Map(scopedVector ? [] : child.joins), multiplying: false };
+      const positive = where(node.where, positiveFrame, node.quantifier === 'ALL');
+      if (scopedVector || (node.quantifier === 'ALL' && positiveFrame.multiplying)) {
+        const complete = witness(positiveFrame, positive);
+        return node.quantifier === 'ALL' ? `NOT ${complete}` : complete;
+      }
+      child.joins = positiveFrame.joins;
+      return node.quantifier === 'ALL' ? `NOT ${positive}` : positive;
+    };
+    const candidate = `EXISTS (SELECT 1 ${subquery(field.target, correlation, node.scope, body).from})`;
+    return `(${node.quantifier === 'ANY' ? '' : 'NOT '}${isolatedPrefix ? witness(prefix, candidate) : candidate})`;
+  };
   // A negation reaches every predicate below it, including those nested in AND/OR groups; the emptiness forms are
   // two-valued, so they need no null-safe form under it. A frame's scope is never negated.
   const where = (node, frame = rootFrame, negated = false) => {
     if (!node) return 'TRUE';
+    if (node.kind === 'quantified') return quantified(node, frame);
     if (node.kind === 'predicate' && isEmptinessOperator(node.operator)) return `(${emptiness(node, frame)})`;
     if (node.kind === 'predicate') {
-      const sql = predicate(path(node.path, 'filter', frame), node.operator, node.value, negated);
+      // Check ordinary paths and values before the new client metadata, without creating joins or aliases.
+      if (Object.hasOwn(node, 'joins')) validateQuantifiedGroups({ AND: [{ conditions: [{ field: node.path.join('.'), operator: node.operator, value: node.value }] }] }, { models, entity: frame.entity, referenceEmptiness: true, quantifiers: true });
+      const checked = inspectJoins(node, frame);
+      if (checked.reason) {
+        // Only this already-rejected request needs a non-crossing native-value checkpoint. Accepted
+        // requests retain path/scope compilation before encoding, including its bind order and single coercion.
+        const steps = resolveModelPath(models, frame.entity, node.path);
+        const leaf = steps.at(-1);
+        const identity = ['id', '_id'].includes(leaf.name) && (steps.length === 1 ? !frame.table.ownership : steps.at(-2).kind !== 'embedded');
+        const field = operandField(leaf, identity);
+        predicate({ field, type: storageTypes[field.scalar], list: field.list, sql: '', uncollated: '' }, node.operator, node.value, negated);
+        detached(checked.reason);
+      }
+      const sql = predicate(path(node.path, 'filter', frame, checked.joins), node.operator, node.value, negated);
       if (Object.hasOwn(node, 'scopes') && node.scopes !== undefined) detached(`${node.operator} on ${[].concat(node.path).join('.')} has scopes, but is not an emptiness condition`);
       return `(${sql})`;
     }
     return `(${node.terms.map((term) => where(term, frame, negated)).join(node.kind === 'and' ? ' AND ' : ' OR ')})`;
   };
+  // Count ignores valid ordering, but still rejects a collection sort without adding joins to its statement.
+  if (plan.mode === 'count') for (const term of plan.sort) sortPath(term.path);
   let condition = where(plan.where);
   if (extra) {
     const column = root.columns.find((item) => item.name === extra.column);

package/src/record-statements.js

@@ -7,6 +7,7 @@ export const compileRecord = (database, operation) => {
   const target = qualified(database.schema, storage.name);
   if (kind === 'selectById') return { text: `SELECT * FROM ${target} WHERE id = $1::uuid${operation.lock ? ' FOR UPDATE' : ''}`, values: [id] };
   if (kind === 'selectOwned') return { text: `SELECT * FROM ${target} WHERE "__owner_id" = ANY ($1::uuid[])${operation.ordered ? ' ORDER BY "__position"' : ''}`, values: [operation.ids] };
+  if (kind === 'deleteById' && operation.version) return { text: `DELETE FROM ${target} WHERE id = $1::uuid AND ${q(operation.version.column)} = $2::bigint RETURNING id`, values: [id, operation.version.expected] };
   if (kind === 'deleteById') return { text: `DELETE FROM ${target} WHERE id = $1::uuid`, values: [id] };
   if (kind === 'deleteOwned') return { text: `DELETE FROM ${target} WHERE "__owner_id" = $1::uuid`, values: [operation.ownerId] };
   if (kind === 'insert') {
@@ -16,6 +17,12 @@ export const compileRecord = (database, operation) => {
   }
   if (kind === 'update') {
     const entries = Object.entries(data);
+    if (operation.version) {
+      const column = q(operation.version.column);
+      const assignments = entries.map(([key], index) => `${q(key)} = $${index + 2}::${storage.columns.find((column) => column.name === key).type}`);
+      assignments.push(`${column} = ${column} + 1`);
+      return { text: `UPDATE ${target} SET ${assignments.join(', ')} WHERE id = $1::uuid AND ${column} = $${entries.length + 2}::bigint RETURNING *`, values: [id, ...entries.map(([, value]) => value), operation.version.expected] };
+    }
     return { text: `UPDATE ${target} SET ${entries.map(([key], index) => `${q(key)} = $${index + 2}::${storage.columns.find((column) => column.name === key).type}`).join(', ')} WHERE id = $1::uuid RETURNING *`, values: [id, ...entries.map(([, value]) => value)] };
   }
   throw new SimfinityError(`Unknown record operation ${kind}`, 'INVALID_RECORD_OPERATION', 400);

package/src/schema/describe.js

@@ -4,7 +4,7 @@ import { queryFunctions } from '../query/functions.js';
 import { constraintBuilder, withLayouts } from './constraints.js';
 import { identifier, literal, generatedName, invalid } from './sql.js';
 
-const scalarTypes = { ID: 'uuid', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone', Embedded: 'jsonb' };
+const scalarTypes = { ID: 'uuid', Version: 'bigint', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone', Embedded: 'jsonb' };
 const physicalType = (column) => `${scalarTypes[column.scalar]}${column.list ? '[]' : ''}`;
 const physicalDefault = (value) => value.kind === 'identity' ? 'gen_random_uuid()' : typeof value.value === 'string' ? `${literal(value.value)}::text` : String(value.value);
 // The first value is the default, which keeps the 3.5.9 description.

package/src/schema/initialize.js

@@ -560,14 +560,45 @@ const virtualLeftovers = (description, catalog, virtualFields) => {
   return `${series(fields)} ${many ? 'are' : 'is'} virtual (extensions.virtual), so ${many ? 'they are' : 'it is'} never stored, but this database still holds ${many ? 'their' : 'its'} `
     + `earlier storage. Once nothing reads that storage, migrate it: ${statements.join(' ')} See the upgrade notes at ${UPGRADE_NOTES}`;
 };
-// A SCHEMA_MISMATCH of a database that still holds storage of fields that are now virtual also names them.
+// Explain version-column drift from catalog contents, including when equal column counts hide a missing
+// or leftover version in the original mismatch. Private owned and auxiliary tables have no record version.
+const versionColumns = (description, catalog) => {
+  const explanations = [];
+  for (const table of description.tables) {
+    if (table.ownership || table.auxiliary) continue;
+    const actual = catalog.tables.get(table.name);
+    if (!actual) continue;
+    const column = table.columns.find((item) => item.name === 'version');
+    const stored = actual.columns.find((item) => item.name === 'version');
+    const target = qualified(description.schema, table.name);
+    if (column?.type === 'bigint') {
+      const declaration = `${table.name} declares optimistic concurrency (extensions.concurrency), so its table needs the version column`;
+      if (!stored) explanations.push(`${declaration}. Migrate it: ALTER TABLE ${target} ADD COLUMN "version" bigint NOT NULL DEFAULT 1;`);
+      else if (stored.type !== column.type || stored.nullable !== column.nullable
+        || (column.collation && (stored.collation !== column.collation || stored.collation_schema !== 'pg_catalog'))
+        || normalizeExpression(stored.default) !== normalizeExpression(column.default || null) || stored.attidentity || stored.attgenerated) {
+        explanations.push(`${declaration} defined as bigint NOT NULL DEFAULT 1.`);
+      }
+    } else if (!column && stored?.type === 'bigint') {
+      explanations.push(`${table.name} does not declare optimistic concurrency, but its table has the version column. `
+        + 'If other instances of this application declare it, deploy the declaration here: while the column exists, instances without it cannot start. '
+        + `Otherwise, once no instance declares it: ALTER TABLE ${target} DROP COLUMN "version";`);
+    }
+  }
+  return explanations.length ? explanations.join(' ') : null;
+};
+
+// A SCHEMA_MISMATCH also explains optimistic-concurrency columns and earlier storage of virtual fields.
 const explainMismatch = (error, description, catalog, layouts, virtualFields) => {
-  if (!virtualFields.length || !catalog || !(error instanceof SimfinityError) || error.extensions?.code !== 'SCHEMA_MISMATCH') return error;
+  if (!catalog || !(error instanceof SimfinityError) || error.extensions?.code !== 'SCHEMA_MISMATCH') return error;
   let resolved = description;
   // Refresh-trigger objects of two layouts in one root are themselves the mismatch; compare with the description.
   try { resolved = resolveLayouts(description, catalog, layouts); } catch { /* keep the description */ }
   try {
-    const explanation = virtualLeftovers(resolved, catalog, virtualFields);
+    const explanation = [
+      versionColumns(resolved, catalog),
+      virtualFields.length ? virtualLeftovers(resolved, catalog, virtualFields) : null,
+    ].filter(Boolean).join(' ');
     return explanation ? new SimfinityError(`${error.message} ${explanation}`, 'SCHEMA_MISMATCH', 409) : error;
   } catch {
     // An explanation never replaces the mismatch it explains.

package/types/index.d.ts

@@ -7,7 +7,9 @@ export {
   buildErrorFormatter,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
   plugins,
+  RecordVersion,
   scalars,
   SimfinityError,
   validators,
@@ -17,6 +19,7 @@ export type {
   AuthRule,
   AuthRuleFunction,
   AuthSchemaPlugin,
+  ConcurrencyDeclaration,
   CreateSchemaOptions,
   EntityController,
   EnvelopSchemaPlugin,
@@ -174,8 +177,10 @@ export interface PostgresModel {
   find(args?: Record<string, any>, options?: { session?: PostgresSession }): Promise<PostgresRecord[]>;
   /** Native helpers bypass GraphQL validators/controllers; references use storage column names. */
   create(data: Record<string, any>, options?: { session?: PostgresSession }): Promise<PostgresRecord>;
-  update(id: string, changes: Record<string, any>, options?: { session?: PostgresSession }): Promise<PostgresRecord | null>;
-  delete(id: string, options?: { session?: PostgresSession }): Promise<PostgresRecord | null>;
+  /** Protected entities require changes.version; version:false ignores that field and does not advance it. */
+  update(id: string, changes: Record<string, any>, options?: { session?: PostgresSession; version?: false }): Promise<PostgresRecord | null>;
+  /** Protected entities require the version read, or false to bypass the version precondition. */
+  delete(id: string, options?: { session?: PostgresSession; version?: number | false }): Promise<PostgresRecord | null>;
 }
 export interface PostgresConfiguration {
   pool: PostgresPool;
@@ -249,6 +254,15 @@ export interface PostgresRuntime extends Runtime<PostgresModel, PostgresSession>
  * state column and a `NOT EXISTS` subquery on the owned table, null list items counting as items. `IS_NOT_EMPTY` is
  * the positive form of a leaf, which a btree can serve, and the `NOT` of an object or owned form.
  *
+ * The plugin declares `queryFeatures.quantifiers: true`: collection filters become correlated EXISTS frames,
+ * preserving one parent row, and explicit ANY/NONE/ALL frames also admit single references. Client frames and
+ * crossings apply target find scopes; trusted frames read stored data. ALL uses NOT EXISTS with a two-valued
+ * failing body (null operands fail ordering comparisons), and an absent body is TRUE. A frame's aliases and
+ * scope/body joins are local to its subquery. Aggregate anchors share the joins of groupId and facts; filters
+ * whose collection prefixes are already joined keep their multiplicity. A reference reached through an embedded
+ * list keeps its vector join when the target scope is null, including after a restricted prefix; a non-null
+ * target scope there is FORBIDDEN_FILTER_PATH (403). Sorting through a collection is invalid.
+ *
  * The plugin also declares `queryFeatures.referenceEmptiness`. A client's condition reads as missing every record that
  * the target's `find` scope hides. The references it crosses share the plain `LEFT JOIN` of other conditions while
  * the scopes crossed so far add nothing; from the first scope that adds conditions on, each crossing is a