@simtlix/simfinity-core 3.12.0 → 3.13.0

package/README.md

@@ -45,3 +45,11 @@ Importing the runtime installs Simfinity's `__Field.extensions` introspection fi
 The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `UnauthenticatedError` and `ForbiddenError` (the same classes as `auth.UnauthenticatedError` and `auth.ForbiddenError`), `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
 
 The same helpers are available from the `@simtlix/simfinity-core/auth`, `/auth/errors`, `/auth/expressions`, `/auth/rules`, `/plugins`, `/scalars` and `/validators` subpaths, each with TypeScript declarations whose types match the root namespaces. `moduleResolution` `node16`, `nodenext` and `bundler` read them through the export map, and `node10` through `typesVersions`. The `internal/*` subpaths are not public API and have no declarations.
+
+## Optimistic concurrency
+
+`extensions: { concurrency: { mode: 'optimistic' } }` opts an entity into the managed `version: RecordVersion!` field. Core exports `RecordVersion` and `MAX_RECORD_VERSION` (`9007199254740991`); import from the application's facade to share their identity. See the [concurrency guide](https://simtlix.github.io/simfinity.js/guide/concurrency.html).
+
+An adapter advertises `writeFeatures: { optimisticConcurrency: true }`; `createRuntime()` snapshots/freezes this declaration and rejects invalid shapes with `INVALID_WRITE_FEATURES` (500). A protected schema rejects an adapter without support. `update(model, id, changes, session, { expectedVersion })` must atomically match ID/version, apply changes and set `expectedVersion + 1`, returning the updated record; `delete(model, id, session, { expectedVersion })` must atomically match both and return the deleted record. An update at the maximum skips the write. After no match, read the same cast key in the same session: return `null` if absent, report `VERSION_CONFLICT` if stale or `VERSION_EXHAUSTED` for an equal maximum on update, otherwise return `null`. MongoDB missing/null versions count as 1. Without `expectedVersion`, existing writes and call paths remain unchanged.
+
+Support also requires `find(model, type, args, session, { requiredId, context })` to honor the session, required key and context for scoped visibility checks. Wrappers must forward every argument, including options. Core's update result diagnostic requires `expected + 1` and advancement beyond its immutable pre-read version; delete results must carry the expected version. These diagnostics raise `DATABASE_ERROR` for inconsistent results but cannot prove arbitrary wrappers kept the atomic predicate. They retain supplied-session ownership; adapters must preserve their own guarded-write abort semantics. The `get_by_id` scope defers stale/exhausted errors for hidden callers until write hooks authorize the operation, but malformed stored versions can fail before hooks. Protected writes always perform their required pre-read, regardless of `readByIdIsInert`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -53,6 +53,7 @@
     },
     "./internal/object-id": "./src/auth/object-id.js",
     "./internal/query-operators": "./src/query-operators.js",
+    "./internal/record-version": "./src/record-version.js",
     "./internal/relation-storage": "./src/relation-storage.js",
     "./plugins": {
       "types": "./types/plugins.d.ts",

package/src/index.js

@@ -1,5 +1,6 @@
 export { describeModels } from './metadata.js';
 export { isVirtualField, virtualFieldOptions } from './relation-storage.js';
+export { MAX_RECORD_VERSION, RecordVersion } from './record-version.js';
 export { default as SimfinityError } from './errors/simfinity.error.js';
 export { createValidatedScalar } from './scalars/factory.js';
 export {

package/src/metadata.js

@@ -6,6 +6,10 @@ import {
   assertVirtualConnection, assertVirtualDeclaration, assertVirtualIndexes, assertVirtualStateField,
 } from './virtual-fields.js';
 import { assertPlainConnectionField } from './relation-storage.js';
+import {
+  isProtectedType, isVersionField, recordVersionFieldMisuse, versionConnectionCollision, versionEmbeddedMisuse,
+  versionFieldCollision,
+} from './record-version.js';
 
 const invalid = (message) => {
   throw new SimfinityError(message, 'INVALID_MODEL', 400);
@@ -62,10 +66,20 @@ const scalarDescription = (type) => {
   return { scalar };
 };
 
+// The version field of a protected entity, described the same way whether the type carries Simfinity's
+// injected field or only declares the extension and createSchema() has not injected it yet.
+const versionDescription = () => ({
+  name: 'version', storageName: 'version', kind: 'scalar', scalar: 'Version', required: true,
+  list: false, itemRequired: false, unique: false, readOnly: true, version: true,
+});
+
 /**
  * Describe persistent entities without importing a database driver or mutating GraphQL types.
  * Virtual fields (`extensions.virtual`) store nothing, so they are left out of every entity and
  * embedded type, and their result types are neither described nor required to declare a relation.
+ * An entity that declares optimistic concurrency (`extensions.concurrency`), or already carries its
+ * injected field, ends with the version field. A field that would collide with it, any other field
+ * typed RecordVersion, and a protected type used as an embedded value throw INVALID_MODEL.
  */
 export const describeModels = (registrations) => {
   if (!Array.isArray(registrations)) invalid('registrations must be an array');
@@ -91,10 +105,17 @@ export const describeModels = (registrations) => {
   const fieldsOf = (type, ancestors, path, embedded = false) => {
     if (ancestors.includes(type)) invalid(`Embedded cycle at ${path}`);
     registerType(type);
+    const isProtected = isProtectedType(type);
+    if (isProtected && embedded) invalid(versionEmbeddedMisuse(type.name, path));
+    const collision = isProtected ? versionFieldCollision(type) : null;
+    if (collision) invalid(collision);
+    const misuse = recordVersionFieldMisuse(type);
+    if (misuse) invalid(misuse);
     const stored = Object.values(type.getFields()).filter((field) => !assertVirtualDeclaration(
       type.name, field.name, field, () => typeof field.resolve === 'function',
     ));
     const fields = stored.map((field) => {
+      if (isVersionField(field)) return versionDescription();
       const { named, ...wrappers } = unwrap(field.type);
       const extensions = field.extensions || {};
       const descriptor = {
@@ -117,12 +138,15 @@ export const describeModels = (registrations) => {
       assertPlainConnectionField(type.name, field.name, field);
       addEntity(named);
       if (wrappers.list) {
+        const connectionCollision = versionConnectionCollision(type, field.name, field);
+        if (connectionCollision) invalid(connectionCollision);
         if (!relation.connectionField) invalid(`${path}.${field.name} requires a child connectionField`);
         if (embedded) invalid(`Non-embedded collections inside embedded objects are not supported: ${path}.${field.name}`);
         return { ...descriptor, kind: 'collection', target: named.name, connectionField: relation.connectionField };
       }
       return { ...descriptor, kind: 'reference', target: named.name, storageName: relation.connectionField || field.name };
     });
+    if (isProtected && !fields.some((item) => item.version)) fields.push(versionDescription());
     const storage = new Set();
     for (const field of fields.filter((item) => item.kind !== 'collection')) {
       if (storage.has(field.storageName)) invalid(`Storage collision at ${path}.${field.storageName}`);

package/src/record-version.js

@@ -0,0 +1,235 @@
+import {
+  GraphQLError, GraphQLID, GraphQLInputObjectType, GraphQLNonNull, GraphQLScalarType, Kind, getNamedType, isObjectType,
+} from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { getFieldStorageName, getListShape } from './relation-storage.js';
+
+// Everything about declarative optimistic concurrency (`extensions.concurrency`) that does not depend
+// on a runtime: the RecordVersion scalar, the version field Simfinity injects into a protected type,
+// how version values are read and checked, the errors that report them and the collision rules that
+// createSchema() and describeModels() share. The scalar and its maximum are public root exports of the
+// core package; the rest reaches the adapters through the `./internal/record-version` subpath, which
+// is not public API.
+
+/** The highest version. A record at it cannot be updated again, because its version cannot advance. */
+export const MAX_RECORD_VERSION = Number.MAX_SAFE_INTEGER;
+
+const RANGE = `an integer from 1 to ${MAX_RECORD_VERSION}`;
+
+const isVersionNumber = (value) => Number.isSafeInteger(value) && value >= 1;
+
+// A stored or serialized version as a number: a safe integer from 1 to MAX_RECORD_VERSION, given as a
+// number or as a bigint (a PostgreSQL driver may return one for a bigint column). Null for anything else.
+const asVersion = (value) => {
+  if (typeof value === 'bigint') return value >= 1n && value <= BigInt(MAX_RECORD_VERSION) ? Number(value) : null;
+  return isVersionNumber(value) ? value : null;
+};
+
+// The value as an error message shows it. A string is quoted; a value that cannot be converted to
+// text, such as an object without a prototype, shows its type.
+const show = (value) => {
+  try {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+  } catch {
+    return typeof value;
+  }
+};
+
+export const RecordVersion = new GraphQLScalarType({
+  name: 'RecordVersion',
+  description: 'Revision of a record with optimistic concurrency. Send it back unchanged in updates and deletes; Simfinity advances it.',
+  serialize(value) {
+    const version = asVersion(value);
+    if (version === null) throw new GraphQLError(`RecordVersion cannot represent ${show(value)}`);
+    return version;
+  },
+  // Input is a JSON number only: a string, a float or a bigint is never a version a client read.
+  parseValue(value) {
+    if (!isVersionNumber(value)) throw new TypeError(`RecordVersion must be ${RANGE}`);
+    return value;
+  },
+  parseLiteral(ast) {
+    // An IntValue beyond the safe integers rounds to an unsafe number, so the same check rejects it.
+    const version = ast.kind === Kind.INT ? Number(ast.value) : Number.NaN;
+    if (!isVersionNumber(version)) throw new GraphQLError(`RecordVersion must be ${RANGE}`, { nodes: ast });
+    return version;
+  },
+});
+
+/** A record of a protected collection, named by its ID and the version the client read. */
+export const RecordVersionRef = new GraphQLInputObjectType({
+  name: 'RecordVersionRef',
+  fields: {
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    version: { type: new GraphQLNonNull(RecordVersion) },
+  },
+});
+
+// The marker of the injected field. Symbol.for gives every copy of the core code the same key, and a
+// null-prototype extensions object keeps it through toConfig() copies and extensions spreads.
+export const RECORD_VERSION_FIELD = Symbol.for('simfinity.recordVersionField');
+// Invalid raw storage values survive native hydration without mutating returned records.
+// Weak keys also support frozen documents and do not keep query results alive.
+const retainedVersions = new WeakMap();
+// Undefined clears metadata when a later query reuses the same result object.
+export const retainStoredVersion = (record, value) => {
+  if (value === undefined) retainedVersions.delete(record);
+  else retainedVersions.set(record, value);
+};
+export const retainedStoredVersion = (record) => retainedVersions.get(record);
+
+/** Whether a field is the version field that Simfinity injected into a protected type. */
+export const isVersionField = (field) => field?.extensions?.[RECORD_VERSION_FIELD] === true;
+
+const VERSION_FIELD_TYPE = new GraphQLNonNull(RecordVersion);
+
+/**
+ * The graphql-js field object that createSchema() puts into a protected type's `getFields()` map, with
+ * `resolve` as its resolver. `readOnly: true` keeps it out of the create input and `queryable: false`
+ * out of filters, sorts and aggregations; the marker tells it from an application field.
+ */
+export const createVersionFieldConfig = (resolve) => ({
+  name: 'version',
+  description: 'Revision of this record. Send it back unchanged in updates and deletes; Simfinity advances it.',
+  type: VERSION_FIELD_TYPE,
+  args: [],
+  resolve,
+  deprecationReason: undefined,
+  extensions: Object.assign(Object.create(null), { readOnly: true, queryable: false, [RECORD_VERSION_FIELD]: true }),
+  astNode: undefined,
+});
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+/**
+ * Whether the type declares optimistic concurrency. `extensions.concurrency` is either absent or a plain
+ * object whose only key is `mode`, with the value 'optimistic'; any other value throws INVALID_MODEL
+ * (400), whatever the key (own, hidden or a symbol) that makes it so.
+ */
+export const concurrencyDeclared = (gqltype) => {
+  const declaration = gqltype.extensions?.concurrency;
+  if (declaration === undefined) return false;
+  const keys = isPlainObject(declaration) ? Reflect.ownKeys(declaration) : [];
+  if (keys.length !== 1 || keys[0] !== 'mode' || declaration.mode !== 'optimistic') {
+    throw new SimfinityError(`${gqltype.name} extensions.concurrency must be { mode: 'optimistic' }`, 'INVALID_MODEL', 400);
+  }
+  return true;
+};
+
+/**
+ * A stored version as a number. A missing or null one is 1 (a MongoDB document written before the type
+ * was protected); anything but a safe integer from 1 to MAX_RECORD_VERSION, given as a number or a
+ * bigint, throws DATABASE_ERROR (500): the stored data is wrong, not the request.
+ */
+export const readStoredVersion = (value, { typeName, id } = {}) => {
+  if (value === undefined || value === null) return 1;
+  const version = asVersion(value);
+  if (version === null) {
+    const record = [typeName ?? 'Record', id].filter((part) => part !== undefined && part !== null).join(' ');
+    throw new SimfinityError(`${record} stores an invalid version`, 'DATABASE_ERROR', 500);
+  }
+  return version;
+};
+
+/**
+ * Checks a version that did not come through GraphQL coercion (middleware, saveObject(), a programmatic
+ * caller): a missing or null one throws REQUIRED_VALUE and one that is not a number from 1 to
+ * MAX_RECORD_VERSION throws INVALID_VERSION, both 400. Returns the version.
+ */
+export const assertVersionInput = (value) => {
+  if (value === undefined || value === null) throw new SimfinityError('Required value version is missing', 'REQUIRED_VALUE', 400);
+  if (!isVersionNumber(value)) throw new SimfinityError(`Invalid value for version: expected ${RANGE}`, 'INVALID_VERSION', 400);
+  return value;
+};
+
+// None of these messages carries the stored version or other data of the record.
+export const versionConflictError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} was modified by another operation`, 'VERSION_CONFLICT', 409,
+);
+
+export const versionExhaustedError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} has reached the maximum version`, 'VERSION_EXHAUSTED', 409,
+);
+
+/** `hook` is the name of the hook that set the managed field, such as 'onUpdating'. */
+export const versionManagedError = (typeName, hook) => new SimfinityError(
+  `${typeName}.version is managed by Simfinity; ${hook} cannot set it`, 'VERSION_MANAGED', 500,
+);
+
+export const unadvancedVersionError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} was written without advancing its version`, 'DATABASE_ERROR', 500,
+);
+
+export const unexpectedDeleteError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} was deleted at another version`, 'DATABASE_ERROR', 500,
+);
+
+/**
+ * Whether the type is protected: it declares the extension, whose shape this checks (INVALID_MODEL), or
+ * already carries the injected field. describeModels() and the checks of createSchema() ask this, since
+ * they run before the field is injected.
+ */
+export const isProtectedType = (gqltype) => concurrencyDeclared(gqltype) || Object.values(gqltype.getFields()).some(isVersionField);
+
+/**
+ * The INVALID_MODEL message for a protected type used as an embedded value at `path`, such as
+ * `Pedido.items`: an embedded value's changes belong to the revision of the record that embeds it.
+ */
+export const versionEmbeddedMisuse = (typeName, path) => `${typeName} declares optimistic concurrency, so it cannot be embedded (${path})`;
+
+const collisionPrefix = (typeName) => `${typeName} declares optimistic concurrency, so Simfinity adds its version field, but`;
+
+/**
+ * For a type that declares optimistic concurrency: the INVALID_MODEL message for the first field that
+ * would collide with the version field, or null. That is a field named `version` that Simfinity did not
+ * add, or a reference stored under `version` (`connectionField: 'version'`). The injected field itself
+ * is never a collision. A field named `version` typed RecordVersion is almost always the injected field
+ * copied without its marker, as a spread of its extensions passed to a graphql-js constructor does, so
+ * the message says how to keep it.
+ */
+export const versionFieldCollision = (gqltype) => {
+  for (const [name, field] of Object.entries(gqltype.getFields())) {
+    if (isVersionField(field)) continue;
+    if (name === 'version') {
+      const copied = getNamedType(field.type) === RecordVersion
+        ? '. It is typed RecordVersion, so it was probably copied from a protected type without its marker: keep '
+          + 'the field\'s extensions object as it is, for example with toConfig()'
+        : '';
+      return `${collisionPrefix(gqltype.name)} ${gqltype.name} already has a field named version; rename that field${copied}`;
+    }
+    if (getFieldStorageName(name, field) === 'version') {
+      return `${collisionPrefix(gqltype.name)} ${gqltype.name}.${name} uses version as its connectionField; choose another one`;
+    }
+  }
+  return null;
+};
+
+/**
+ * For a collection (a list relation that is not embedded) of `ownerType.fieldName` whose item type
+ * declares optimistic concurrency: the INVALID_MODEL message when the collection links its items through
+ * `version`, by its connectionField or, without one, by its own field name; otherwise null. The link
+ * would resolve to the injected version field instead of a field of the application.
+ */
+export const versionConnectionCollision = (ownerType, fieldName, field) => {
+  const relation = field.extensions?.relation;
+  const itemType = getListShape(field.type)?.itemType;
+  if (!relation || relation.embedded || !isObjectType(itemType)) return null;
+  if ((relation.connectionField || fieldName) !== 'version' || !isProtectedType(itemType)) return null;
+  return `${collisionPrefix(itemType.name)} ${ownerType.name}.${fieldName} links its items through version; use another connectionField`;
+};
+
+/**
+ * The INVALID_MODEL message for the first field of the type that is typed RecordVersion (the instance
+ * this module exports, single or list, required or not) without being the injected version field, or
+ * null. Only the managed field may use the scalar in a type; a registered mutation or custom query may
+ * still use it in its own input and output types.
+ */
+export const recordVersionFieldMisuse = (gqltype) => {
+  for (const [name, field] of Object.entries(gqltype.getFields())) {
+    if (getNamedType(field.type) === RecordVersion && !isVersionField(field)) {
+      return `${gqltype.name}.${name} uses RecordVersion, which only the managed version field may use`;
+    }
+  }
+  return null;
+};

package/src/runtime.js

@@ -33,6 +33,12 @@ import {
 import {
   fieldMetadataNamesFixed, fieldMetadataTypes, fixFieldMetadataNames, renameFieldMetadataTypes,
 } from './introspection.js';
+import {
+  MAX_RECORD_VERSION, RecordVersion, RecordVersionRef, assertVersionInput, concurrencyDeclared, createVersionFieldConfig,
+  isProtectedType, isVersionField, readStoredVersion, recordVersionFieldMisuse, retainedStoredVersion, unadvancedVersionError,
+  unexpectedDeleteError, versionConflictError, versionConnectionCollision, versionEmbeddedMisuse, versionExhaustedError,
+  versionFieldCollision, versionManagedError,
+} from './record-version.js';
 
 // Resolvers Simfinity generates. Any other resolver on a registered type when its schema is first
 // created is application code, such as a masking resolver, recorded once per type so later
@@ -85,6 +91,33 @@ const forbiddenPath = (message) => new SimfinityError(message, 'FORBIDDEN_FILTER
 // Generated inputs never write a readOnly field, nor a virtual one, which virtual implies.
 const isReadOnlyField = (field) => !!field.extensions?.readOnly || isVirtualField(field);
 
+// Optimistic concurrency (#98). A type is protected once it carries the version field createSchema()
+// injects, which it keeps for good, so code that builds schemas and runs requests asks this instead of
+// reading the live `extensions.concurrency`.
+const isProtected = (gqltype) => isVersionField(gqltype.getFields().version);
+// Whether each registered type was protected when the first createSchema() that contained it returned,
+// for every runtime of this copy of the core code. A failed createSchema() records nothing.
+const protectionStatus = new WeakMap();
+
+const invalidWriteFeatures = (message) => {
+  throw new SimfinityError(`DatabaseAdapter writeFeatures ${message}`, 'INVALID_WRITE_FEATURES', 500);
+};
+
+// Reads an adapter's `writeFeatures` declaration once, into a frozen copy. Undefined or null declares
+// nothing; a plain object may declare `optimisticConcurrency` as a boolean, and its other members are
+// left for later features. Anything else throws INVALID_WRITE_FEATURES (500).
+const resolveWriteFeatures = (writeFeatures) => {
+  if (writeFeatures == null) return Object.freeze({ optimisticConcurrency: false });
+  if (typeof writeFeatures !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(writeFeatures))) {
+    invalidWriteFeatures('must be a plain object');
+  }
+  const { optimisticConcurrency } = writeFeatures;
+  if (optimisticConcurrency !== undefined && typeof optimisticConcurrency !== 'boolean') {
+    invalidWriteFeatures('optimisticConcurrency must be a boolean');
+  }
+  return Object.freeze({ optimisticConcurrency: optimisticConcurrency === true });
+};
+
 // Query scopes restrict reads, so a scope Simfinity cannot run must fail rather than be skipped.
 const SCOPE_OPERATIONS = ['find', 'get_by_id', 'aggregate'];
 const invalidScope = (typeName, detail) => new SimfinityError(
@@ -280,6 +313,24 @@ const assertFieldMetadataNamesFree = (roots) => {
   if (clash) throw reservedTypeNameError(clash);
 };
 
+// A schema with protected types contains RecordVersion, and RecordVersionRef whenever a generated input
+// reaches a collection of protected items, so an application type with either name, other than the
+// instances this module exports, is rejected there (#98). Like the field metadata names, they are first
+// checked before anything is built, reading input objects by their own name only, and then in the whole
+// schema when it is constructed.
+const versionTypeClash = (roots, options) => [RecordVersion, RecordVersionRef]
+  .map((own) => findSchemaType(roots, own.name, own, options)).find(Boolean) || null;
+// A scalar named RecordVersion with core's own description is almost always core's scalar from a
+// second copy of this package, which protected types cannot work with.
+const reservedVersionTypeNameError = (clash) => new SimfinityError(
+  clash instanceof GraphQLScalarType && clash.name === RecordVersion.name && clash.description === RecordVersion.description
+    ? 'RecordVersion is reserved for optimistic concurrency, and this RecordVersion comes from another copy of '
+      + '@simtlix/simfinity-core: two copies of the package are loaded; import RecordVersion from the facade the '
+      + 'application uses'
+    : `${clash.name} is reserved for optimistic concurrency; rename the application type`,
+  'RESERVED_TYPE_NAME', 500,
+);
+
 const buildSchemaConfig = (query, mutation) => {
   const config = { query };
   if (Object.keys(mutation.getFields()).length > 0) {
@@ -292,12 +343,15 @@ const buildSchemaConfig = (query, mutation) => {
 // those are renamed SimfinityFieldExtensionsType and SimfinityRelationType, with a number appended
 // when the schema also has those names, in every schema the process constructs from then on. A
 // construction that fails puts the previous metadata types back, so only a schema that exists fixes
-// the names.
-const constructSchema = (query, mutation) => {
+// the names. With `reserveVersionTypeNames`, for a schema with protected types, an application type
+// named RecordVersion or RecordVersionRef fails, even one that only an input field reaches.
+const constructSchema = (query, mutation, reserveVersionTypeNames = false) => {
   const config = buildSchemaConfig(query, mutation);
   const roots = Object.values(config);
   const clash = fieldMetadataClash(roots);
   if (clash && fieldMetadataNamesFixed()) throw reservedTypeNameError(clash);
+  const versionClash = reserveVersionTypeNames && versionTypeClash(roots);
+  if (versionClash) throw reservedVersionTypeNameError(versionClash);
   let names = null;
   if (clash) {
     const taken = (name) => findSchemaType(roots, name) !== null;
@@ -431,6 +485,21 @@ const readOwnField = markGenerated((parent, args, context, info) => {
   return typeof property === 'function' ? property.call(parent, args, context, info) : property;
 });
 
+// Puts the version field into a protected type's getFields() map, after the type's own fields, unless
+// the type carries it already: from an earlier schema, another runtime of this core copy that shares
+// the type, or the type it was copied from. The resolver reads only the parent, so it binds the type to
+// no runtime, and a record without a stored version, such as a MongoDB document written before the
+// type was protected, reads as version 1. An invalid stored version is reported under the type being
+// resolved, which a renamed copy shares the resolver with, or under the type it was injected into.
+const injectVersionField = (gqltype) => {
+  if (isProtected(gqltype)) return;
+  const typeName = gqltype.name;
+  gqltype.getFields().version = createVersionFieldConfig(markGenerated((parent, args, context, info) => readStoredVersion(
+    retainedStoredVersion(parent) ?? ownValue(parent, 'version'),
+    { typeName: info?.parentType?.name ?? typeName, id: ownValue(parent, '_id') ?? ownValue(parent, 'id') },
+  )));
+};
+
 const cloneInput = (value, type) => {
   if (value === null || value === undefined || !type) return value;
   if (type instanceof GraphQLNonNull) return cloneInput(value, type.ofType);
@@ -479,6 +548,9 @@ export const createRuntime = (adapter) => {
     operators: supportedOperators, referenceEmptiness: supportsReferenceEmptiness,
   } = resolveQueryFeatures(adapter.queryFeatures);
   const supportsEveryOperator = QUERY_OPERATORS.every((operator) => supportedOperators.has(operator));
+  // The write features the adapter implements, read once: with optimisticConcurrency, schemas may
+  // contain protected types (#98).
+  const writeFeatures = resolveWriteFeatures(adapter.writeFeatures);
 
   const stateValue = adapter.stateValue || ((state) => state.name);
   const runtimeIdentity = {};
@@ -494,6 +566,9 @@ export const createRuntime = (adapter) => {
   const selfCollectionNameHolders = new Map();
   const qualifiedSelfCollections = new Map();
   const registeredMutations = {};
+  // Models createModel() returned for this runtime, as opposed to models supplied to connect(). A type
+  // with one was built for storage without a version field, even by a createSchema() that failed later.
+  const generatedModels = new WeakSet();
   const registeredQueries = {};
   const registeredViews = {};
   const middlewares = [];
@@ -556,9 +631,9 @@ export const createRuntime = (adapter) => {
     }
   };
 
-  // Object and interface types a schema of this runtime can reach from its registered types and
-  // custom operation results, following the same references as GraphQLSchema.
-  const collectSchemaOutputTypes = () => {
+  // Object and interface types reachable from these roots, following the output references of
+  // GraphQLSchema: fields, interfaces and union members. Input objects cannot hold either.
+  const collectOutputTypes = (roots) => {
     const visited = new Set();
     const outputTypes = [];
     const visit = (type) => {
@@ -574,14 +649,20 @@ export const createRuntime = (adapter) => {
       named.getInterfaces().forEach(visit);
       for (const field of Object.values(named.getFields())) visit(field.type);
     };
+    roots.forEach(visit);
+    return outputTypes;
+  };
+
+  // Object and interface types a schema of this runtime can reach from its registered types and
+  // custom operation results, following the same references as GraphQLSchema.
+  const collectSchemaOutputTypes = () => {
     const registeredTypes = Object.values(typesDict.types).map(({ gqltype }) => gqltype);
     const customOperations = [
       ...Object.values(registeredMutations),
       ...Object.values(registeredQueries),
     ];
     const customOutputTypes = customOperations.map(({ outputModel }) => outputModel);
-    [...registeredTypes, ...customOutputTypes].forEach(visit);
-    return outputTypes;
+    return collectOutputTypes([...registeredTypes, ...customOutputTypes]);
   };
 
   const hasUnresolvedRelation = (gqltype) => Object.values(gqltype.getFields()).some(
@@ -814,8 +895,10 @@ const createOneToManyInputType = (name, inputNamePrefix, itemType, connection,
             + `\`${operation}\` operation in generated inputs, ${omittedOperation[operation]()}`);
         }
       }
-      // Null IDs are skipped, so `deleted` accepts them whatever the collection's item nullability.
-      fields.deleted = { type: new GraphQLList(GraphQLID) };
+      // Null entries are skipped, so `deleted` accepts them whatever the collection's item nullability.
+      // A protected item is deleted at the version the client read, whether or not the parent is
+      // protected (#98).
+      fields.deleted = { type: new GraphQLList(isProtected(itemType) ? RecordVersionRef : GraphQLID) };
       return fields;
     },
   });
@@ -1050,6 +1133,14 @@ const buildInputType = (gqltype, reachable) => {
       description: fieldEntry.description,
     };
   }
+  // The version field is readOnly, so only this adds it, last and required, to a protected type's
+  // update input, which updates, state actions and nested `updated` entries take (#98). Create inputs,
+  // and the `added` items built from them, never get it. An update input that would hold only the
+  // version, with no writable id or other field, is left without fields as before (#161), so the type
+  // has no update mutation, state actions or nested `updated` entries, and keeps its delete mutation.
+  if (isProtected(gqltype) && Object.keys(fieldsArgForUpdate).length > 0) {
+    fieldsArgForUpdate.version = { type: new GraphQLNonNull(RecordVersion), description: argTypes.version.description };
+  }
 
   const inputTypeForAdd = new GraphQLInputObjectType({
     name: `${gqltype.name}Input`,
@@ -1222,8 +1313,9 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
   const collectionFields = {};
 
   for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
-    // A virtual field stores nothing, whatever middleware or saveObject() passes for it.
-    if (isVirtualField(fieldEntry)) continue;
+    // A virtual field stores nothing, whatever middleware or saveObject() passes for it, and Simfinity
+    // writes the version field of a protected type itself (#98).
+    if (isVirtualField(fieldEntry) || isVersionField(fieldEntry)) continue;
     const fieldValue = ownValue(args, fieldEntryName);
     if (fieldEntry.extensions && fieldEntry.extensions.validations
       && fieldEntry.extensions.validations[operation]) {
@@ -1339,10 +1431,58 @@ const iterateOnCollectionFields = async (materializedModel, gqltype, objectId, s
 const readByIdIsInert = (Model) => typeof adapter.readByIdIsInert === 'function'
   && adapter.readByIdIsInert(Model) === true;
 
+// Optimistic concurrency (#98). Every update, state action, delete and nested entry of a protected
+// type first reads its record whole, plain and locked: the pre-read, which also serves the embedded
+// merge, the from-state check and onDelete. Its version is normalized before any hook sees it, so a
+// MongoDB document stored before the type was protected shows 1, as on PostgreSQL.
+const normalizeProtectedVersion = (record, gqltype, id) => {
+  record.version = readStoredVersion(record.version,
+    { typeName: gqltype.name, id: ownValue(record, '_id') ?? ownValue(record, 'id') ?? id });
+  return record.version;
+};
+
+const readProtectedRecord = async (Model, gqltype, id, session) => {
+  const record = await adapter.getById(Model, id, session, { plain: true, lock: true });
+  if (record) normalizeProtectedVersion(record, gqltype, id);
+  return record;
+};
+
+// Whether a stale or exhausted version that the pre-read found is reported at once, before the
+// record's validators, hooks and action run (decision 9): to every caller of a type without a
+// get_by_id scope, and to a caller who can read the record through that scope. The record is read as
+// a by-ID read does, in the operation's session and by its stored key, not the client's spelling of
+// the ID. A scope function that throws counts as hiding the record; errors of the gates and of
+// adapter.find propagate.
+const reportEarlyConflict = async (type, record, context, session) => {
+  if (!getScope(type.gqltype, 'get_by_id')) return true;
+  const key = String(record._id ?? record.id);
+  const args = { id: { operator: 'EQ', value: key } };
+  try {
+    return await findVisibleById(type, args, session, context, key) !== null;
+  } catch (error) {
+    if (failedByIdScopes.has(args)) return false;
+    throw error;
+  }
+};
+
+// Outcome 3 of the pre-read: the stored version is not the expected one, or an update or a state
+// action (`advances`) would take it past MAX_RECORD_VERSION; a delete does not advance it. When the
+// conflict is not reported early, the operation continues exactly as with a matching version, and the
+// conditional write reports it.
+const assertRecordVersion = async (gqltype, id, record, expectedVersion, advances, context, session) => {
+  let error = null;
+  if (record.version !== expectedVersion) error = versionConflictError(gqltype.name, id);
+  else if (advances && expectedVersion === MAX_RECORD_VERSION) error = versionExhaustedError(gqltype.name, id);
+  if (error && await reportEarlyConflict(typesDict.types[gqltype.name], record, context, session)) throw error;
+};
+
 // The record is read for the onDelete hook; adapter.delete casts the ID, deletes and returns the
 // record itself. Without a hook, the read is skipped when it is inert. A nested delete passes the
-// child it has already read as `current`.
-const onDelete = async (Model, controller, id, session, context, current) => {
+// child it has already read as `current`, and a protected delete its pre-read record, null when it is
+// missing, with `precondition`: the type and the version the record must still have. The adapter then
+// deletes it only at that version, and a record it deleted at another one, which an adapter wrapper
+// that drops the options would delete, fails with DATABASE_ERROR and rolls back with the transaction.
+const onDelete = async (Model, controller, id, session, context, current, precondition = null) => {
   const hasHook = !!(controller && controller.onDelete);
   let currentObject = current;
   if (currentObject === undefined && (hasHook || !readByIdIsInert(Model))) {
@@ -1353,7 +1493,13 @@ const onDelete = async (Model, controller, id, session, context, current) => {
     await controller.onDelete(currentObject, session, context);
   }
 
-  return adapter.delete(Model, id, session);
+  if (!precondition) return adapter.delete(Model, id, session);
+  const { gqltype, expectedVersion } = precondition;
+  const deleted = await adapter.delete(Model, id, session, { expectedVersion });
+  if (deleted && readStoredVersion(deleted.version, { typeName: gqltype.name, id }) !== expectedVersion) {
+    throw unexpectedDeleteError(gqltype.name, id);
+  }
+  return deleted;
 };
 
 const getEmbeddedFieldNames = (gqltype) => {
@@ -1428,7 +1574,7 @@ const clearNullEmbeddedMembers = (merged, fieldEntry, patch) => {
 // onUpdating, so that a malformed ID fails before the hook, and before nested collection items, so
 // that the SQL adapter locks the parent row before child writes; otherwise it skips the read only
 // when it is inert. A state action or a nested update has already read and checked the record
-// (`recordChecked`).
+// (`recordChecked`). A protected type never reads here: its pre-read record serves the merge (#98).
 const readsStoredEmbedded = (Model, controller, materializedModel, embeddedFieldNames, recordChecked) => {
   const usesStored = embeddedFieldNames.some((name) => {
     const value = ownValue(materializedModel.modelArgs, name);
@@ -1442,17 +1588,29 @@ const readsStoredEmbedded = (Model, controller, materializedModel, embeddedField
     || !readByIdIsInert(Model);
 };
 
+// Whether an update sets the version field, at the top level or inside an operator such as $set or
+// $unset. The adapter writes the version of a protected type (#98).
+const setsVersion = (update) => [update, ...Object.entries(update)
+  .filter(([key]) => key.startsWith('$')).map(([, value]) => value)]
+  .some((target) => target !== null && typeof target === 'object' && Object.hasOwn(target, 'version'));
+
+// The update of a protected type (#98) takes from its caller the version captured before the
+// pre-read, `expectedVersion`, the immutable observed version, and the pre-read record (null when
+// missing). It merges embedded values from that record and writes only at the expected version,
+// which the adapter advances; onUpdating
+// cannot set the version, and a result that did not advance it fails with DATABASE_ERROR.
 const onUpdateSubject = async (Model, gqltype, controller, args, session, linkToParent, context,
-  recordChecked = false) => {
+  recordChecked = false, { expectedVersion, observedVersion, record } = {}) => {
+  const versioned = isProtected(gqltype);
   const materializedModel = await materializeModel(args, gqltype, linkToParent, 'UPDATE', session);
   const objectId = args.id;
   const argTypes = gqltype.getFields();
   const embeddedFieldNames = getEmbeddedFieldNames(gqltype);
 
   if (embeddedFieldNames.length > 0
-    && readsStoredEmbedded(Model, controller, materializedModel, embeddedFieldNames, recordChecked)) {
+    && (versioned || readsStoredEmbedded(Model, controller, materializedModel, embeddedFieldNames, recordChecked))) {
     const projection = Object.fromEntries(embeddedFieldNames.map((name) => [name, 1]));
-    const currentObject = await adapter.getById(Model, objectId, session, {
+    const currentObject = versioned ? record : await adapter.getById(Model, objectId, session, {
       projection,
       plain: true,
       lock: true,
@@ -1477,7 +1635,8 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
   }
 
   for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
-    if (args[fieldEntryName] === null && !(fieldEntry.type instanceof GraphQLNonNull) && !isVirtualField(fieldEntry)) {
+    if (args[fieldEntryName] === null && !(fieldEntry.type instanceof GraphQLNonNull) && !isVirtualField(fieldEntry)
+      && !isVersionField(fieldEntry)) {
       materializedModel.modelArgs.$unset = {
         ...materializedModel.modelArgs.$unset,
         [getFieldStorageName(fieldEntryName, fieldEntry)]: '',
@@ -1492,11 +1651,24 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
 
   if (controller && controller.onUpdating) {
     await controller.onUpdating(objectId, update, session, context);
+    if (versioned && setsVersion(update)) throw versionManagedError(gqltype.name, 'onUpdating');
   }
 
   if (linkToParent) linkToParent(update);
-  const result = await adapter.update(Model, objectId, update, session);
+  const result = versioned
+    ? await adapter.update(Model, objectId, update, session, { expectedVersion })
+    : await adapter.update(Model, objectId, update, session);
   if (!result) throw new SimfinityError(`${gqltype.name} ${objectId} is not valid`, 'NOT_VALID_ID', 404);
+  // Diagnose a result that did not advance beyond the pre-read, including a dropped precondition
+  // when the caller sent one revision less. This cannot prove arbitrary wrappers honored the atomic
+  // condition: they must still forward it. The observation is captured before application code runs.
+  if (versioned) {
+    const returnedVersion = readStoredVersion(result.version, { typeName: gqltype.name, id: objectId });
+    if (returnedVersion !== expectedVersion + 1
+      || (observedVersion !== undefined && returnedVersion <= observedVersion)) {
+      throw unadvancedVersionError(gqltype.name, objectId);
+    }
+  }
 
   if (materializedModel.collectionFields) {
     // Children link to, and are owned through, the parent's stored key, as when a new parent is
@@ -1513,18 +1685,27 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
   return result;
 };
 
+// A protected type's version is captured before the action can change `args`, and checked on the
+// plain pre-read record before the from-state check, which reads `state` from that record (#98).
 const onStateChanged = async (Model, gqltype, controller, args, session, actionField, context) => {
-  const storedModel = await adapter.getById(Model, args.id, session, { lock: true });
+  const versioned = isProtected(gqltype);
+  const expectedVersion = versioned ? assertVersionInput(args.version) : undefined;
+  const storedModel = versioned
+    ? await readProtectedRecord(Model, gqltype, args.id, session)
+    : await adapter.getById(Model, args.id, session, { lock: true });
+  const observedVersion = versioned ? storedModel?.version : undefined;
   if (!storedModel) {
     throw new SimfinityError(`${gqltype.name} ${args.id} is not valid`, 'NOT_VALID_ID', 404);
   }
+  if (versioned) await assertRecordVersion(gqltype, args.id, storedModel, expectedVersion, true, context, session);
   if (storedModel.state === stateValue(actionField.from)) {
     if (actionField.action) {
       await actionField.action(args, session);
     }
 
     args.state = stateValue(actionField.to);
-    let result = await onUpdateSubject(Model, gqltype, controller, args, session, null, context, true);
+    let result = await onUpdateSubject(Model, gqltype, controller, args, session, null, context, true,
+      versioned ? { expectedVersion, observedVersion, record: storedModel } : undefined);
     result = adapter.toObject(result);
     result.state = actionField.to.value;
     return result;
@@ -1539,11 +1720,15 @@ const onSaveObject = async (Model, gqltype, controller, args, session, linkToPar
       typesDict.types[gqltype.name].stateMachine.initialState,
     );
   }
+  // A protected record starts at version 1, whatever saveObject() or middleware supplied (#98).
+  const versioned = isProtected(gqltype);
+  if (versioned) materializedModel.modelArgs.version = 1;
 
   const newObject = adapter.newRecord(Model, materializedModel.modelArgs, session);
 
   if (controller && controller.onSaving) {
     await controller.onSaving(newObject, args, session, context);
+    if (versioned && newObject.version !== 1) throw versionManagedError(gqltype.name, 'onSaving');
   }
 
   if (linkToParent) linkToParent(newObject);
@@ -1635,12 +1820,30 @@ const assertCollectionWrites = (gqltype, input) => {
   }
 };
 
+// The capture and the pre-read of a protected top-level update or delete (#98): the version the
+// client sent is checked before anything is read, then against the pre-read record. A missing record
+// is not reported here; the update fails at its write with NOT_VALID_ID and the delete returns null,
+// as for an unprotected type.
+const preReadTopLevel = async (Model, gqltype, { id, version }, advances, context, session) => {
+  const expectedVersion = assertVersionInput(version);
+  const record = await readProtectedRecord(Model, gqltype, id, session);
+  const observedVersion = record?.version;
+  if (record) await assertRecordVersion(gqltype, id, record, expectedVersion, advances, context, session);
+  return { expectedVersion, observedVersion, record };
+};
+
+// A delete passes the ID, or { id, version } for a protected type, which each attempt copies; every
+// other operation passes its input, which attemptInputs copies. Either way, a retry checks the version
+// the request sent.
 const executeOperation = (Model, gqltype, controller, args, operation, actionField,
   session, context, inputType) => {
   const limit = getMaxNestedOperations();
   if (limit !== null && operation !== operations.DELETE) assertNestedOperations(gqltype, args, limit);
   if (operation !== operations.DELETE) assertCollectionWrites(gqltype, args);
-  const nextInput = operation === operations.DELETE ? () => args : attemptInputs(args, inputType);
+  const versioned = isProtected(gqltype);
+  let nextInput = () => args;
+  if (operation !== operations.DELETE) nextInput = attemptInputs(args, inputType);
+  else if (versioned) nextInput = () => ({ ...args });
   return adapter.withTransaction(
     session,
     async (mySession) => {
@@ -1648,10 +1851,17 @@ const executeOperation = (Model, gqltype, controller, args, operation, actionFie
       switch (operation) {
         case operations.SAVE:
           return onSaveObject(Model, gqltype, controller, attemptArgs, mySession, null, context);
-        case operations.UPDATE:
-          return onUpdateSubject(Model, gqltype, controller, attemptArgs, mySession, null, context);
-        case operations.DELETE:
-          return onDelete(Model, controller, attemptArgs, mySession, context);
+        case operations.UPDATE: {
+          const precondition = versioned
+            ? await preReadTopLevel(Model, gqltype, attemptArgs, true, context, mySession) : undefined;
+          return onUpdateSubject(Model, gqltype, controller, attemptArgs, mySession, null, context, false, precondition);
+        }
+        case operations.DELETE: {
+          if (!versioned) return onDelete(Model, controller, attemptArgs, mySession, context);
+          const { expectedVersion, record } = await preReadTopLevel(Model, gqltype, attemptArgs, false, context,
+            mySession);
+          return onDelete(Model, controller, attemptArgs.id, mySession, context, record, { gqltype, expectedVersion });
+        }
         case operations.STATE_CHANGED:
           return onStateChanged(Model, gqltype, controller,
             attemptArgs, mySession, actionField, context);
@@ -1684,14 +1894,28 @@ const executeItemFunction = async (gqltype, collectionField, parentKey, session,
     if (item.$set) delete item.$set[connection.storageFieldName];
   };
 
+  // A protected child is updated or deleted at the version its entry carries (#98). A deleted entry is
+  // { id, version } for item middleware; one that is not an object, such as a string ID, has no version.
+  const versioned = isProtected(collectionGQLType) && operationType !== operations.SAVE;
   for (const element of collectionFieldsList) {
     if (element === null) continue;
-    const args = operationType === operations.DELETE ? { id: element } : { input: element };
+    let args = { input: element };
+    if (operationType === operations.DELETE) {
+      args = versioned ? { id: element?.id, version: element?.version } : { id: element };
+    }
     await executeMiddleware({ type, args, operation: operationType, context });
 
+    // Captured after the item's middleware, before the child is read.
+    let expectedVersion;
+    if (versioned) {
+      expectedVersion = assertVersionInput(operationType === operations.DELETE ? args.version : args.input.version);
+    }
+
     // The ownership check reads the child (the SQL adapter locks its row). onDelete receives this
-    // record, and an update reads the child again only to merge embedded values.
+    // record, and an update reads the child again only to merge embedded values, unless the child is
+    // protected: then this is its pre-read, whose version is checked after ownership.
     let child;
+    let observedVersion;
     if (operationType === operations.UPDATE || operationType === operations.DELETE) {
       const id = operationType === operations.DELETE ? args.id : args.input.id;
       child = await adapter.getById(type.model, id, session, { plain: true, lock: true });
@@ -1701,6 +1925,11 @@ const executeItemFunction = async (gqltype, collectionField, parentKey, session,
       if (String(child[connection.storageFieldName]) !== String(parentKey)) {
         throw new ForbiddenError('Child does not belong to this parent');
       }
+      if (versioned) {
+        observedVersion = normalizeProtectedVersion(child, collectionGQLType, id);
+        await assertRecordVersion(collectionGQLType, id, child, expectedVersion, operationType === operations.UPDATE,
+          context, session);
+      }
     }
 
     switch (operationType) {
@@ -1710,10 +1939,11 @@ const executeItemFunction = async (gqltype, collectionField, parentKey, session,
         break;
       case operations.UPDATE:
         await onUpdateSubject(type.model, collectionGQLType, type.controller,
-          args.input, session, linkToParent, context, true);
+          args.input, session, linkToParent, context, true, versioned ? { expectedVersion, observedVersion, record: child } : undefined);
         break;
       case operations.DELETE:
-        await onDelete(type.model, type.controller, args.id, session, context, child);
+        await onDelete(type.model, type.controller, args.id, session, context, child,
+          versioned ? { gqltype: collectionGQLType, expectedVersion } : null);
     }
   }
 };
@@ -2304,6 +2534,29 @@ const loadReference = (type, id, requiredId, context) => {
   });
 };
 
+// The query arguments whose get_by_id scope function threw in findVisibleById. The error propagates
+// as it was thrown; the conflict path (reportEarlyConflict) tells it from errors of the gates and of
+// adapter.find this way. Each caller (resolveById and reportEarlyConflict) allocates fresh args
+// and calls findVisibleById exactly once with that object; never reuse marked args for another read.
+const failedByIdScopes = new WeakSet();
+
+// The record that the type's get_by_id scope shows the caller, or null. `args` holds an `id` EQ
+// condition, to which the scope adds its own; the gates check them as for every read, and adapter.find
+// reads in `session`, pinned to `requiredId`. get_by_id middleware is not run here; resolveById runs it
+// first.
+const findVisibleById = async (type, args, session, context, requiredId) => {
+  try {
+    await executeScope({ type, args, operation: 'get_by_id', context });
+  } catch (error) {
+    failedByIdScopes.add(args);
+    throw error;
+  }
+  assertStoredQueryPaths(type.gqltype, args, 'find');
+  assertQueryConditions(type.gqltype, args, 'find');
+  const results = await adapter.find(type.model, type.gqltype, args, session, { requiredId, context });
+  return results[0] || null;
+};
+
 // `requiredId` marks a generated single-reference read. Middleware still runs per call; then, when the
 // adapter reads by ID in batches, and unless the type has a get_by_id scope or middleware changed the
 // ID, the read joins the request's batch.
@@ -2317,12 +2570,7 @@ const resolveById = async (type, args, context, requiredId) => {
     }
     return adapter.getById(type.model, args.id, null, { requiredId, context });
   }
-  const queryArgs = { id: { operator: 'EQ', value: args.id } };
-  await executeScope({ type, args: queryArgs, operation: 'get_by_id', context });
-  assertStoredQueryPaths(type.gqltype, queryArgs, 'find');
-  assertQueryConditions(type.gqltype, queryArgs, 'find');
-  const results = await adapter.find(type.model, type.gqltype, queryArgs, null, { requiredId, context });
-  return results[0] || null;
+  return findVisibleById(type, { id: { operator: 'EQ', value: args.id } }, null, context, requiredId);
 };
 
 // Batched collection reads. A generated collection field reads its children with one
@@ -2713,10 +2961,13 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
               : `mutation that takes no input or an input of its own, since getInputType(${type.gqltype.name}) `
                 + 'has no fields.'));
         }
+        // A protected type is deleted at the version the client read (#98).
+        const deleteArgs = { id: { type: new GraphQLNonNull(GraphQLID) } };
+        if (isProtected(type.gqltype)) deleteArgs.version = { type: new GraphQLNonNull(RecordVersion) };
         rootQueryArgs.fields[`delete${type.simpleEntityEndpointName}`] = {
           type: type.gqltype,
           description: 'delete',
-          args: { id: { type: new GraphQLNonNull(GraphQLID) } },
+          args: deleteArgs,
           extensions: { simfinityMutation: { typeName: type.gqltype.name, operation: operations.DELETE } },
           async resolve(parent, args, context) {
             const params = {
@@ -2727,8 +2978,10 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
             };
 
             await executeMiddleware(params);
+            // A protected delete takes the version as middleware left it.
+            const target = isProtected(type.gqltype) ? { id: args.id, version: args.version } : args.id;
             return executeOperation(type.model, type.gqltype, type.controller,
-              args.id, operations.DELETE, null, null, context, null);
+              target, operations.DELETE, null, null, context, null);
           },
         };
       }
@@ -3317,6 +3570,108 @@ const warnUndeclaredVirtualFields = () => {
   }
 };
 
+// The types a model stores: the registered types and the embedded types they reach at any depth,
+// readOnly fields included, as assertPlainConnectionFields visits them.
+const collectStoredTypes = () => {
+  const stored = new Set();
+  const visit = (gqltype) => {
+    if (stored.has(gqltype)) return;
+    stored.add(gqltype);
+    for (const field of Object.values(gqltype.getFields())) {
+      const named = field.extensions?.relation?.embedded && getNamedType(field.type);
+      if (named instanceof GraphQLObjectType) visit(named);
+    }
+  };
+  for (const { gqltype } of Object.values(typesDict.types)) visit(gqltype);
+  return [...stored];
+};
+
+const invalidModel = (message) => new SimfinityError(message, 'INVALID_MODEL', 400);
+
+// Optimistic concurrency (#98), declared per type with `extensions.concurrency`. These checks run in
+// this order, after stored identities are known and before adapter.prepare(), so a rejected schema
+// changes nothing. `applicationTypes` are the roots of the schema's types. Returns the registrations of
+// the protected types and whether the included roots reserve the version names.
+const assertConcurrencyDeclarations = (applicationTypes) => {
+  const registrations = Object.values(typesDict.types);
+  // The shape of every declaration.
+  const protectedTypes = registrations.filter(({ gqltype }) => concurrencyDeclared(gqltype));
+  // Generated inputs, models and stored data follow the protection a type had when the first schema
+  // containing it was created, and an injected field is never removed, so neither can change later.
+  // Inputs or a model that an earlier createSchema() built without the field also fix protection,
+  // even if the call failed afterwards; a model supplied to connect() does not.
+  for (const registration of registrations) {
+    const { gqltype } = registration;
+    const declared = protectedTypes.includes(registration);
+    const builtWithoutField = !isProtected(gqltype)
+      && (!!registration.inputType || generatedModels.has(registration.model));
+    if (declared && protectionStatus.get(gqltype) === false) {
+      throw invalidModel(`${gqltype.name} declares optimistic concurrency after a schema was created without it; `
+        + `declare it before the first createSchema() that contains ${gqltype.name}`);
+    }
+    if (declared && builtWithoutField) {
+      throw invalidModel(`${gqltype.name} declares optimistic concurrency after its inputs or generated model were built without it; `
+        + `declare it before the first createSchema() attempt that builds ${gqltype.name}`);
+    }
+    if (!declared && isProtected(gqltype)) {
+      throw invalidModel(`${gqltype.name} no longer declares optimistic concurrency, but Simfinity already added its `
+        + 'version field; keep extensions.concurrency on a type once it has that field');
+    }
+  }
+  // Another runtime that registers a protected type injects its field when that runtime creates a
+  // schema, which would change a schema already built here, so this schema must register every
+  // protected type it contains, whatever the adapter supports.
+  const reachedTypes = collectOutputTypes(applicationTypes);
+  for (const type of reachedTypes) {
+    if (type instanceof GraphQLObjectType && typesDict.types[type.name]?.gqltype !== type && isProtectedType(type)) {
+      throw invalidModel(`${type.name} declares optimistic concurrency, so a schema that contains it must register it `
+        + 'in this runtime, with connect() or as a relation target');
+    }
+  }
+  // An embedded value's changes belong to the revision of the record that embeds it, wherever a model
+  // stores it.
+  const storedTypes = collectStoredTypes();
+  const storedFields = storedTypes.flatMap((gqltype) => Object.entries(gqltype.getFields())
+    .map(([fieldName, field]) => ({ gqltype, fieldName, field })));
+  for (const { gqltype, fieldName, field } of storedFields) {
+    const named = field.extensions?.relation?.embedded && getNamedType(field.type);
+    if (named instanceof GraphQLObjectType && isProtectedType(named)) {
+      throw invalidModel(versionEmbeddedMisuse(named.name, `${gqltype.name}.${fieldName}`));
+    }
+  }
+  // Only an entity has a record of its own whose version can advance.
+  const nonEntity = protectedTypes.find(({ storedIdentity }) => storedIdentity !== true);
+  if (nonEntity) {
+    throw invalidModel(`${nonEntity.gqltype.name} declares optimistic concurrency, so it must be an entity: register it `
+      + 'with connect() or make it a relation target');
+  }
+  // Nothing else may be stored, or link records, under the version field's name.
+  for (const { gqltype } of protectedTypes) {
+    const collision = versionFieldCollision(gqltype);
+    if (collision) throw invalidModel(collision);
+  }
+  for (const { gqltype, fieldName, field } of storedFields) {
+    const collision = versionConnectionCollision(gqltype, fieldName, field);
+    if (collision) throw invalidModel(collision);
+  }
+  // RecordVersion types managed version fields only, with or without protected types; registered
+  // operations may still use it in their own input and output types.
+  for (const gqltype of storedTypes) {
+    const misuse = recordVersionFieldMisuse(gqltype);
+    if (misuse) throw invalidModel(misuse);
+  }
+  const reserveVersionNames = protectedTypes.some(({ gqltype }) => reachedTypes.includes(gqltype));
+  if (protectedTypes.length && !writeFeatures.optimisticConcurrency) {
+    throw invalidModel(`The database adapter does not support optimistic concurrency, which ${protectedTypes[0].gqltype.name} `
+      + 'declares (extensions.concurrency)');
+  }
+  // A clash that only generated types or the fields of an input object reach is found when the schema
+  // is constructed.
+  const clash = reserveVersionNames && versionTypeClash(applicationTypes, { inputFields: false });
+  if (clash) throw reservedVersionTypeNameError(clash);
+  return { protectedTypes, reserveVersionNames };
+};
+
 const getRegistrations = () => Object.values(typesDict.types);
 
 const includedOperationTypes = (registrations, includedOperations) => Object.entries(registrations)
@@ -3324,7 +3679,8 @@ const includedOperationTypes = (registrations, includedOperations) => Object.ent
   .flatMap(([, { inputModel, outputModel }]) => [inputModel, outputModel].filter(Boolean));
 
 // Application types that a schema with these allowlists contains, whatever else it reaches: the
-// endpoint types of its queries and mutations, and the input and output types of its custom operations.
+// endpoint types of its queries and mutations, the input and output types of its custom operations,
+// and the scalar/enum parameters of included named views.
 const includedApplicationTypes = (includedQueryTypes, includedMutationTypes, includedCustomMutations, includedCustomQueries) => [
   ...Object.values(typesDict.types)
     .filter((type) => type.endpoint
@@ -3333,6 +3689,9 @@ const includedApplicationTypes = (includedQueryTypes, includedMutationTypes, inc
     .map((type) => type.gqltype),
   ...includedOperationTypes(registeredMutations, includedCustomMutations),
   ...includedOperationTypes(registeredQueries, includedCustomQueries),
+  ...Object.values(registeredViews)
+    .filter(({ type }) => !shouldNotBeIncludedInSchema(includedQueryTypes, type))
+    .flatMap(({ params }) => Object.values(params).map(({ type }) => getNamedType(type))),
 ];
 
 const queryNameConflict = (name) => new SimfinityError(
@@ -3374,7 +3733,9 @@ const assertViewsAvailable = (includedQueryTypes, includedCustomQueries) => {
       if (!/^[_A-Za-z][_0-9A-Za-z]*$/.test(paramName) || paramName.startsWith('__')) {
         throw invalidView(`${name} param ${paramName} requires a valid GraphQL name that does not start with __`);
       }
-      if (Object.hasOwn(fields, paramName)) {
+      // A protected type's managed version is injected later in createSchema(), but its name is
+      // already unavailable to view params on the first schema, as on every subsequent schema.
+      if (Object.hasOwn(fields, paramName) || (paramName === 'version' && isProtectedType(type))) {
         throw invalidView(`${name} param ${paramName} has the name of a field of ${type.name}`);
       }
       if (LIST_QUERY_ARGS.includes(paramName)) {
@@ -3428,16 +3789,21 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   // An application type with the name of a field metadata type that an earlier schema fixed; one that
   // only generated types or the fields of an input object reach is found when the schema is
   // constructed.
-  assertFieldMetadataNamesFree(includedApplicationTypes(includedQueryTypes, includedMutationTypes,
-    includedCustomMutations, includedCustomQueries));
+  const applicationTypes = includedApplicationTypes(includedQueryTypes, includedMutationTypes,
+    includedCustomMutations, includedCustomQueries);
+  assertFieldMetadataNamesFree(applicationTypes);
   const referencedTypes = markReferencedTypesForModelGeneration();
   // Entities, which keep their own stored identity: connect() types and relation targets.
   Object.values(typesDict.types).forEach((typeInfo) => {
     typeInfo.storedIdentity = typeInfo.endpoint === true || referencedTypes.has(typeInfo);
   });
+  const { protectedTypes, reserveVersionNames } = assertConcurrencyDeclarations(applicationTypes);
   if (adapter.prepare) {
     adapter.prepare(getRegistrations(), { createCollection: !preventCollectionCreation });
   }
+  // prepare() describes protected types from their declaration. Models, inputs, resolvers and query
+  // arguments are built from here on, so they all see the field.
+  protectedTypes.forEach(({ gqltype }) => injectVersionField(gqltype));
 
   Object.values(typesDict.types).forEach((typeInfo) => {
     if (typeInfo.gqltype && !typeInfo.model) {
@@ -3448,6 +3814,8 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
       } else if (typeInfo.needsModel) {
         typeInfo.model = adapter.createModel(typeInfo.gqltype, null, { createCollection: false });
       }
+      const { model } = typeInfo;
+      if (model !== null && (typeof model === 'object' || typeof model === 'function')) generatedModels.add(model);
     }
   });
 
@@ -3492,7 +3860,7 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
       includedCustomQueries);
   }
 
-  const schema = constructSchema(query, mutation);
+  const schema = constructSchema(query, mutation, reserveVersionNames);
   // Reserve reachable types whose relation fields still have no resolver, such as an unregistered
   // custom operation result, so another runtime cannot later generate resolvers this schema executes.
   schemaTypes.forEach((type) => {
@@ -3500,6 +3868,10 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
       runtimeBoundTypes.set(type, runtimeIdentity);
     }
   });
+  // The schema exists, so each registered type's protection is fixed from now on.
+  Object.values(typesDict.types).forEach(({ gqltype }) => {
+    if (!protectionStatus.has(gqltype)) protectionStatus.set(gqltype, isProtected(gqltype));
+  });
   return schema;
 };
 
@@ -3721,6 +4093,8 @@ const connect = (model, gqltype, simpleEntityEndpointName,
   };
   assertNotBoundElsewhere(gqltype);
   validateScope(gqltype);
+  // The declaration's shape only; it reads extensions, never the fields (#98).
+  concurrencyDeclared(gqltype);
   if (adapter.validateRegistration) adapter.validateRegistration(registration);
 
   invalidateCollectionInputs(gqltype);
@@ -3751,6 +4125,7 @@ const addNoEndpointType = (gqltype) => {
     gqltype, endpoint: false, model: null, needsModel,
   };
   validateScope(gqltype);
+  concurrencyDeclared(gqltype);
   if (adapter.validateRegistration) adapter.validateRegistration(registration);
 
   invalidateCollectionInputs(gqltype);
@@ -3764,7 +4139,9 @@ const LIST_QUERY_ARGS = ['pagination', 'sort', 'AND', 'OR'];
 
 // `omit` is a collection's back-reference field, which its parent supplies, so it gets no filter.
 // A field named like a generated argument gets no top-level filter either; it is reported once.
-// A virtual field is not part of the query language, so it gets no filter at all.
+// A virtual field is not part of the query language, so it gets no filter at all, and neither does the
+// version field of a protected type (#98): a MongoDB record without a stored version reads as 1, which
+// a filter could not match.
 const createArgsForQuery = (gqltype, omit = null) => {
     const argsObject = {};
     const argTypes = gqltype.getFields();
@@ -3777,7 +4154,7 @@ const createArgsForQuery = (gqltype, omit = null) => {
     }
 
     for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
-      if (fieldEntryName === omit || isVirtualField(fieldEntry)) continue;
+      if (fieldEntryName === omit || isVirtualField(fieldEntry) || isVersionField(fieldEntry)) continue;
       let filterType = null;
 
       if (fieldEntry.type instanceof GraphQLScalarType

package/types/index.d.ts

@@ -15,6 +15,20 @@ export const QLOperator: GraphQLEnumType;
 export const QLSort: GraphQLInputObjectType;
 export const QLValue: GraphQLScalarType<unknown, unknown>;
 
+/**
+ * The scalar of the `version` field that Simfinity adds to a type that declares optimistic
+ * concurrency (see {@link ConcurrencyDeclaration}). It holds safe integers from 1 to
+ * {@link MAX_RECORD_VERSION}, a JSON number on the wire: a string, a float, 0, a negative number and an
+ * unsafe integer fail GraphQL coercion. A client sends the version it read back unchanged in updates
+ * and deletes, and Simfinity advances it. Only the managed field may use it in a type, which
+ * `createSchema()` and `describeModels()` enforce with `INVALID_MODEL` (400); a registered mutation or
+ * custom query may use it in its own input and output types. Import it from the facade the application
+ * uses: the protection depends on one copy of core per process.
+ */
+export const RecordVersion: GraphQLScalarType;
+/** The highest version, `Number.MAX_SAFE_INTEGER`. The version of a record never goes past it. */
+export const MAX_RECORD_VERSION: number;
+
 /**
  * A `QLOperator` value. The operators of 3.7.0 are `EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`,
  * `NIN` and `LIKE`. The literal text operators take a non-null string without U+0000 on a `String`
@@ -99,7 +113,8 @@ export interface FieldDescription {
   itemRequired: boolean;
   unique: boolean;
   readOnly: boolean;
-  scalar?: 'ID' | 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Enum';
+  /** `'Version'` is the managed version field of a type that declares optimistic concurrency (`version: true`). */
+  scalar?: 'ID' | 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Enum' | 'Version';
   values?: string[];
   enumValues?: { name: string; value: unknown }[];
   target?: string;
@@ -107,6 +122,12 @@ export interface FieldDescription {
   fields?: FieldDescription[];
   private?: boolean;
   inferred?: boolean;
+  /**
+   * Set on the managed version field of a type that declares optimistic concurrency, which
+   * `describeModels()` appends after the type's own fields: `{ name: 'version', scalar: 'Version',
+   * required: true, readOnly: true, version: true }`.
+   */
+  version?: true;
 }
 export interface ModelDescription {
   entities: Array<{
@@ -121,6 +142,13 @@ export interface ModelDescription {
  * fields are left out of every entity and embedded type, and the types only they reach are not
  * described. Throws `INVALID_MODEL` (400) for an invalid `extensions.virtual` declaration, as
  * `createSchema()` does (see {@link VirtualFieldOptions}).
+ *
+ * A type that declares optimistic concurrency (see {@link ConcurrencyDeclaration}) is described with
+ * its version field last, before `createSchema()` has added it and after, and the call throws
+ * `INVALID_MODEL` (400) for an invalid declaration, for a field named `version` that Simfinity did not
+ * add, for a reference stored under `version` (`connectionField: 'version'`), for a collection of
+ * such items that links through `version`, for such a type used as an embedded value, and for any
+ * other field typed {@link RecordVersion}.
  */
 export function describeModels(registrations: ModelRegistration[]): ModelDescription;
 /**
@@ -312,6 +340,19 @@ export type ScopeFunction<Model = any, Session = any> = (params: ScopeParams<Mod
  * was changed.
  */
 export type TypeScopes<Model = any, Session = any> = Partial<Record<ScopeOperation, ScopeFunction<Model, Session>>>;
+/**
+ * Value of a type's `extensions.concurrency`: the entity is protected by optimistic concurrency.
+ * Simfinity adds a read-only `version: RecordVersion!` field to the type, which starts at 1 and grows
+ * by 1 with each accepted write; a client sends the version it read back in updates and deletes, and a
+ * write at another version fails with `VERSION_CONFLICT` (409). The only valid value is
+ * `{ mode: 'optimistic' }`: `null`, an array, another mode or an extra key throws `INVALID_MODEL`
+ * (400). So does a type that is not an entity, one used as an embedded value, one that already has a
+ * field named `version` (or a field stored under that name), and an adapter that does not declare
+ * `writeFeatures.optimisticConcurrency`.
+ */
+export interface ConcurrencyDeclaration {
+  mode: 'optimistic';
+}
 
 /**
  * Process-wide limits for generated add, update and state-action mutations. Any other option,
@@ -501,6 +542,15 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * collections also needs `referenceEmptiness: true`, and fails with `UNSUPPORTED_QUERY` without it.
    */
   queryFeatures?: QueryFeatures | null | undefined;
+  /**
+   * Optional. Declares the write features this adapter implements. `createRuntime` reads it once and
+   * throws `INVALID_WRITE_FEATURES` (500) unless it is undefined, null or an object whose
+   * `optimisticConcurrency`, if present, is a boolean. A schema with a type that declares
+   * `extensions.concurrency` (see {@link ConcurrencyDeclaration}) throws `INVALID_MODEL` (400) unless
+   * the adapter declares `optimisticConcurrency: true`, which commits it to the `options.expectedVersion`
+   * contract of `update` and `delete` and to the requirements on `find` below.
+   */
+  writeFeatures?: { optimisticConcurrency?: boolean } | null | undefined;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
   /**
@@ -509,10 +559,16 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * must never be stored: an adapter that builds storage from a type's fields skips each field for
    * which {@link isVirtualField} returns true, on the types its embedded fields reach as well, or
    * builds it from `describeModels(registrations)`, which leaves them out. Generated writes, filters,
-   * sorts and aggregations never name a virtual field; a controller hook can still assign one.
+   * sorts and aggregations never name a virtual field; a controller hook can still assign one. The
+   * version field of a type that declares optimistic concurrency is injected after `prepare()`, so a
+   * type here may not have it yet; `describeModels(registrations)` describes it either way.
    */
   prepare?(registrations: RuntimeRegistration<Model, Session>[], options: { createCollection: boolean }): void;
-  /** Creates the model of a registered type. Its fields include virtual fields; see `prepare()`. */
+  /**
+   * Creates the model of a registered type. Its fields include virtual fields; see `prepare()`. A type
+   * that declares optimistic concurrency already has its injected version field here, which
+   * `describeModels(registrations)` describes as well.
+   */
   createModel(type: GraphQLObjectType, callback: ((model: Model) => void) | null | undefined, options: { createCollection: boolean }): Model;
   /**
    * Casts a reference or batch key to the stored identifier type. Throw a `SimfinityError` with
@@ -574,8 +630,31 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    */
   readByIdIsInert?(model: Model): boolean;
   prepareUpdate(set: Record<string, any>, unset: Record<string, string>): any;
-  update(model: Model, id: any, changes: any, session?: Session): any;
-  delete(model: Model, id: any, session?: Session): any;
+  /**
+   * With `options.expectedVersion`, one atomic write that matches the ID and a stored version equal to
+   * it (on MongoDB a missing or null stored version counts as 1), applies `changes`, sets the version
+   * to `expectedVersion + 1` and returns the updated record. When nothing matches, or when
+   * `expectedVersion >= MAX_RECORD_VERSION` and the write is skipped, it reads the record by ID in the
+   * same session: it returns null for a missing one, throws `VERSION_CONFLICT` (409) when the stored
+   * version differs, `VERSION_EXHAUSTED` (409) when stored and expected are `MAX_RECORD_VERSION`, and
+   * returns null otherwise. Without `options.expectedVersion` it behaves as before. A wrapper must
+   * forward every argument, `options` included.
+   */
+  update(model: Model, id: any, changes: any, session?: Session, options?: { expectedVersion?: number }): any;
+  /**
+   * With `options.expectedVersion`, one atomic delete that matches the ID and the version, and returns
+   * the deleted record. When nothing matches, it decides as `update` does, without the exhausted case:
+   * a delete does not advance the version, so a record at `MAX_RECORD_VERSION` is deleted like any
+   * other. Without it, it behaves as before. A wrapper must forward every argument, `options`
+   * included.
+   */
+  delete(model: Model, id: any, session?: Session, options?: { expectedVersion?: number }): any;
+  /**
+   * An adapter that declares `writeFeatures.optimisticConcurrency` must run `find` inside the given
+   * `session`, honor `options.requiredId` and accept `options.context`: the runtime reads through
+   * `find` with the caller's session to check, before a hook runs, whether the caller can read a
+   * record whose version is stale.
+   */
   find(model: Model, type: GraphQLObjectType, args: any, session?: Session | null, options?: { requiredId?: any; context?: any }): any;
   count(model: Model, type: GraphQLObjectType, args: any, session?: Session | null): Promise<number> | number;
   aggregate(model: Model, type: GraphQLObjectType, args: any, session?: Session | null): any;