@simtlix/simfinity-core 3.11.0 → 3.13.0

package/src/runtime.js

@@ -6,7 +6,7 @@ import {
   GraphQLObjectType, GraphQLString, GraphQLID, GraphQLSchema, GraphQLList,
   GraphQLNonNull, GraphQLInputObjectType, GraphQLScalarType,
   GraphQLInt, GraphQLEnumType, GraphQLBoolean, GraphQLError, GraphQLInterfaceType, GraphQLUnionType,
-  Kind, getNamedType, isObjectType, isOutputType,
+  Kind, getNamedType, isEnumType, isListType, isNonNullType, isObjectType, isOutputType, isScalarType,
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.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,7 +566,11 @@ 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 = [];
 
   const operations = {
@@ -555,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) => {
@@ -573,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(
@@ -813,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;
     },
   });
@@ -1049,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`,
@@ -1221,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]) {
@@ -1338,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))) {
@@ -1352,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) => {
@@ -1427,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);
@@ -1441,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,
@@ -1476,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)]: '',
@@ -1491,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
@@ -1512,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;
@@ -1538,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);
@@ -1634,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) => {
@@ -1647,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);
@@ -1683,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 });
@@ -1700,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) {
@@ -1709,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);
     }
   }
 };
@@ -1813,7 +2044,9 @@ const copyClientFilters = (args, operation) => {
 // scope. When the adapter compiles reference emptiness (#108 part 2b), a client's emptiness term or
 // condition reads its references and collections through scoped joins and frames instead, so it
 // enters no joined scope either; every other entry, beside it or on the same path, records its own.
-const inspectClientPaths = (gqltype, args, operation) => {
+// Without `checkQueryable`, for a view's `where`, whose paths are the author's as a scope's are, a
+// non-queryable field is not rejected; a virtual one still is.
+const inspectClientPaths = (gqltype, args, operation, { checkQueryable = true } = {}) => {
   copyClientFilters(args, operation);
   const joinedScopes = new Map();
   const entries = collectQueryPathEntries(args, operation, { gqltype, expandMembers: true });
@@ -1827,7 +2060,7 @@ const inspectClientPaths = (gqltype, args, operation) => {
         throw forbiddenPath(`Query path ${path} uses the virtual field ${type.name}.${fieldName}, which is not stored`);
       }
       const queryable = field.extensions?.queryable;
-      if (queryable === false || (queryable !== true && hasApplicationResolver(type, fieldName))) {
+      if (checkQueryable && (queryable === false || (queryable !== true && hasApplicationResolver(type, fieldName)))) {
         throw forbiddenPath(`Query path ${path} uses the non-queryable field ${type.name}.${fieldName}`);
       }
       if (!joins) return;
@@ -2069,31 +2302,34 @@ const hasScopeMarker = (construct) => construct != null && Object.hasOwn(constru
 
 // Marks the client's constructs that read references or collections, from the gate's conditions on the
 // client's arguments, then applies maxReferenceFrames to the distinct (kind, path) pairs of their
-// scoped joins and frames in this call, so every 2a code comes first. Returns the issued markers, as
-// id -> the client's operator and path, or null when the adapter does not compile reference
-// emptiness. Ids are ordinals in the order of the conditions, so identical arguments get identical
-// markers and sibling collection reads keep one batch key.
-const markClientConstructs = (checked) => {
+// scoped joins and frames in these conditions, so every 2a code comes first. Returns the issued
+// markers, as id -> the client's operator and path, or null when the adapter does not compile
+// reference emptiness. Ids are ordinals in the order of the conditions, so identical arguments get
+// identical markers and sibling collection reads keep one batch key. With `issued`, the markers of
+// the call so far, the ids continue on that map, so that a view's `where`, marked after the client's
+// arguments, shares them; the limit still applies to each set of conditions on its own.
+const markClientConstructs = (checked, issued) => {
   if (!supportsReferenceEmptiness) return null;
-  const issued = new Map();
+  const markers = issued ?? new Map();
   const pairs = new Set();
   for (const { entry, shape } of checked) {
     const { construct } = entry;
     if (!shape || !construct || hasScopeMarker(construct)) continue;
     const { joins, frames } = emptinessScopePaths(shape, entry.segments);
     if (!joins.length && !frames.length) continue;
-    const id = issued.size;
+    const id = markers.size;
     construct[SCOPE_MARKER] = { id };
-    issued.set(id, { operator: entry.operator, path: entry.path });
+    markers.set(id, { operator: entry.operator, path: entry.path });
     for (const path of joins) pairs.add(`join ${path}`);
     for (const path of frames) pairs.add(`frame ${path}`);
   }
   const limit = getQueryMaxReferenceFrames();
   if (pairs.size > limit) {
     throw new SimfinityError(`Emptiness conditions through references and collections need ${pairs.size} scoped joins and `
-      + `frames in one query field, more than the limit of ${limit} (maxReferenceFrames)`, 'FILTER_DEPTH_EXCEEDED', 400);
+      + 'frames in one set of conditions (the client\'s arguments of a query field, or a view\'s where), more than the limit '
+      + `of ${limit} (maxReferenceFrames)`, 'FILTER_DEPTH_EXCEEDED', 400);
   }
-  return issued;
+  return markers;
 };
 
 // The detach check: every marker issued in this call sits, well formed (an object whose only own key
@@ -2298,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.
@@ -2311,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
@@ -2707,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 = {
@@ -2721,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);
           },
         };
       }
@@ -2805,6 +3064,170 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
   return new GraphQLObjectType(rootQueryArgs);
 };
 
+// The prefix every generated read shares, for the list and aggregate roots, the collection fields and
+// the views: the client's paths and conditions are inspected and marked, middleware runs, with `entry`
+// when one is given, `extend` adds the caller's own constructs and returns their joined scopes, the
+// type's scope runs, the client's joined scopes and then the extension's are applied, and the final
+// arguments are settled. Returns the params, whose args the adapter reads. An empty map of the
+// client's joined scopes is not awaited, so that, with the caller's await of this function, a read
+// without one still reaches the adapter after as many promise jobs as before it was shared.
+const prepareRead = async (type, args, context, operation, { entry, extend } = {}) => {
+  const joinedScopes = inspectClientPaths(type.gqltype, args, operation);
+  const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, operation));
+  const params = entry === undefined
+    ? { type, args, operation, context }
+    : { type, args, operation, entry, context };
+  await executeMiddleware(params);
+  const extended = extend ? await extend(params, issued) : null;
+  await executeScope(params);
+  if (joinedScopes.size) await applyJoinedScopes(joinedScopes, params);
+  if (extended) await applyJoinedScopes(extended, params);
+  const filling = settleClientArgs(type.gqltype, params, operation, issued);
+  if (filling) await filling;
+  return params;
+};
+
+// The tail of a list read, shared by the generated list root and the views: the rows and, when the
+// client asks for pagination.count and something can receive it, the count, reported through the sink.
+const readList = async (type, params, parent, info, context) => {
+  const queryArgs = params.args;
+  const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
+    && canReportCount(parent, info, context);
+
+  const dataPromise = adapter.find(type.model, type.gqltype, queryArgs, null);
+  const countPromise = wantsCount
+    ? adapter.count(type.model, type.gqltype, queryArgs, null)
+    : null;
+
+  const [result, resultCount] = await Promise.all([dataPromise, countPromise]);
+  if (wantsCount && !reportCount(parent, info, context, resultCount)) {
+    warnOnce(runtimeIdentity, 'count-context', 'Configuration issue: the GraphQL context does not accept '
+      + 'a count property (it is frozen, sealed or has a read-only count), so pagination counts are not '
+      + 'reported; pass a fresh mutable context object for each request.');
+  }
+  return result;
+};
+
+// Separates a view's params, named by `paramNames`, from the rest of its arguments, which are exactly
+// a generated list's.
+const splitViewArgs = (paramNames, args) => {
+  const params = {};
+  const rest = {};
+  for (const [name, value] of Object.entries(args)) {
+    if (paramNames.has(name)) params[name] = value;
+    else rest[name] = value;
+  }
+  return { params, args: rest };
+};
+
+const invalidWhere = (view, detail) => new SimfinityError(`View ${view.name} where ${detail}`, 'INVALID_VIEW', 500);
+
+// The groups a view's `where` returned are plain objects whose `conditions`, `AND` and `OR`, when set,
+// are arrays: of plain objects with a field name, and of groups like these. collectQueryPathEntries
+// skips anything else silently, so this comes before their paths are read. Only the GraphQL input
+// fields are structural keys; condition values stay opaque. A condition never carries a client scope
+// marker key: only the runtime writes one. Active ancestors reject cycles without rejecting reuse.
+const assertViewGroupShapes = (view, groups, ancestors = new Set()) => {
+  const groupFields = QLFilterGroup.getFields();
+  const conditionFields = QLFilterCondition.getFields();
+  for (const group of groups) {
+    if (!isNonNullPlainObject(group)) throw invalidWhere(view, 'returned a group that is not a plain object');
+    if (ancestors.has(group)) throw invalidWhere(view, 'returned a cyclic group');
+    for (const key of Object.keys(group)) {
+      if (!Object.hasOwn(groupFields, key)) throw invalidWhere(view, `returned a group with unknown key ${key}`);
+    }
+    for (const key of Object.keys(groupFields)) {
+      if (group[key] != null && !Array.isArray(group[key])) throw invalidWhere(view, `returned a group whose ${key} is not an array`);
+    }
+    for (const condition of group.conditions ?? []) {
+      if (!isNonNullPlainObject(condition) || typeof condition.field !== 'string' || condition.field === '') {
+        throw invalidWhere(view, 'returned a condition that is not a plain object with a field name');
+      }
+      if (hasScopeMarker(condition)) {
+        throw invalidWhere(view, `condition on ${condition.field} carries a ${SCOPE_MARKER} key, which Simfinity reserves`);
+      }
+      for (const key of Object.keys(condition)) {
+        if (!Object.hasOwn(conditionFields, key)) throw invalidWhere(view, `condition on ${condition.field} has unknown key ${key}`);
+      }
+    }
+    ancestors.add(group);
+    assertViewGroupShapes(view, [...(group.AND ?? []), ...(group.OR ?? [])], ancestors);
+    ancestors.delete(group);
+  }
+};
+
+// A `where` that does not return an array of groups, or names a field its type does not have, a path
+// past a field without fields, or a virtual field, is the author's bug: INVALID_VIEW (500), never the
+// FORBIDDEN_FILTER_PATH (403) that inspectClientPaths gives a client for a virtual field. Each path is
+// walked here, since walkQueryPath stops silently at an unknown segment.
+const assertViewGroups = (view, groups) => {
+  if (!Array.isArray(groups)) throw invalidWhere(view, 'must return an array of AND groups');
+  assertViewGroupShapes(view, groups);
+  for (const { segments } of collectQueryPathEntries({ AND: groups }, 'find', { gqltype: view.type })) {
+    let type = view.type;
+    let parent = null;
+    for (const [index, segment] of segments.entries()) {
+      const names = (detail) => invalidWhere(view, `names ${segments.slice(0, index + 1).join('.')}, which is ${detail}`);
+      if (typeof type.getFields !== 'function') throw names(`past ${parent}, whose type ${type.name} has no fields`);
+      const fields = type.getFields();
+      if (!Object.hasOwn(fields, segment)) throw names(`not a field of ${type.name}`);
+      if (isVirtualField(fields[segment])) throw names(`the virtual field ${type.name}.${segment}`);
+      parent = `${type.name}.${segment}`;
+      type = unwrapListAndNonNull(fields[segment].type);
+    }
+  }
+};
+
+// The `extend` of a view's read (see prepareRead). After middleware, the groups of `where` are read as
+// the client's constructs on a probe, whose AND holds copies of them (inspectClientPaths), so the
+// author's objects are never touched: their paths are inspected, their conditions checked and marked,
+// with ids that continue the client's, then the copies are appended to the top-level AND, where no
+// middleware can drop them. Returns their joined scopes, which attach to the appended copies. Their
+// paths are the author's, as a scope's are, so a non-queryable field is not rejected.
+const viewExtension = (view, viewParams) => async (params, issued) => {
+  const groups = await view.where({ params: viewParams, context: params.context });
+  assertViewGroups(view, groups);
+  const probe = { AND: groups };
+  const scopes = inspectClientPaths(view.type, probe, 'find', { checkQueryable: false });
+  const checked = assertQueryConditions(view.type, probe, 'find');
+  markClientConstructs(checked, issued);
+  appendAndGroups(params.args, probe.AND);
+  return scopes;
+};
+
+// A view's root field: the generated list of its type, with the view's params before the generated
+// arguments. Each call reads the type's registration, whose model createSchema prepares, strips the
+// params, by the names the field was built with, before the list pipeline runs, and has the pipeline
+// append the view's `where` after middleware (viewExtension).
+const buildViewField = (view) => {
+  const paramArgs = {};
+  for (const [paramName, param] of Object.entries(view.params)) {
+    const arg = { type: param.type };
+    if (Object.hasOwn(param, 'description')) arg.description = param.description;
+    if (Object.hasOwn(param, 'defaultValue')) arg.defaultValue = param.defaultValue;
+    paramArgs[paramName] = arg;
+  }
+  const paramNames = new Set(Object.keys(paramArgs));
+  return {
+    type: new GraphQLList(view.type),
+    description: view.description,
+    args: { ...paramArgs, ...createArgsForQuery(view.type) },
+    extensions: {
+      simfinityQuery: {
+        typeName: view.type.name, operation: 'find', countSink: true, view: { name: view.name },
+      },
+    },
+    async resolve(parent, args, context, info) {
+      const registration = typesDict.types[view.type.name];
+      const split = splitViewArgs(paramNames, args);
+      const params = await prepareRead(registration, split.args, context, 'find', {
+        entry: view.name, extend: viewExtension(view, split.params),
+      });
+      return readList(registration, params, parent, info, context);
+    },
+  };
+};
+
 const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggregationResult, includedCustomQueries = null) => {
   const rootQueryArgs = {};
   rootQueryArgs.name = name;
@@ -2831,35 +3254,8 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           // that supplies a root-value sink can pass its context unchanged.
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'find', countSink: true } },
           async resolve(parent, args, context, info) {
-            const joinedScopes = inspectClientPaths(type.gqltype, args, 'find');
-            const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, 'find'));
-            const params = {
-              type,
-              args,
-              operation: 'find',
-              context,
-            };
-            await executeMiddleware(params);
-            await executeScope(params);
-            await applyJoinedScopes(joinedScopes, params);
-            const filling = settleClientArgs(type.gqltype, params, 'find', issued);
-            if (filling) await filling;
-            const queryArgs = params.args;
-            const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
-              && canReportCount(parent, info, context);
-
-            const dataPromise = adapter.find(type.model, type.gqltype, queryArgs, null);
-            const countPromise = wantsCount
-              ? adapter.count(type.model, type.gqltype, queryArgs, null)
-              : null;
-
-            const [result, resultCount] = await Promise.all([dataPromise, countPromise]);
-            if (wantsCount && !reportCount(parent, info, context, resultCount)) {
-              warnOnce(runtimeIdentity, 'count-context', 'Configuration issue: the GraphQL context does not accept '
-                + 'a count property (it is frozen, sealed or has a read-only count), so pagination counts are not '
-                + 'reported; pass a fresh mutable context object for each request.');
-            }
-            return result;
+            const params = await prepareRead(type, args, context, 'find');
+            return readList(type, params, parent, info, context);
           },
         };
 
@@ -2879,19 +3275,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           args: aggregateArgsObject,
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'aggregate' } },
           async resolve(parent, args, context) {
-            const joinedScopes = inspectClientPaths(type.gqltype, args, 'aggregate');
-            const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, 'aggregate'));
-            const params = {
-              type,
-              args,
-              operation: 'aggregate',
-              context,
-            };
-            await executeMiddleware(params);
-            await executeScope(params);
-            await applyJoinedScopes(joinedScopes, params);
-            const filling = settleClientArgs(type.gqltype, params, 'aggregate', issued);
-            if (filling) await filling;
+            const params = await prepareRead(type, args, context, 'aggregate');
             return adapter.aggregate(type.model, type.gqltype, params.args, null);
           },
         };
@@ -2906,6 +3290,13 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
     }
   }
 
+  // A view is in the schema exactly when its type is; assertViewsAvailable has checked its name.
+  for (const view of Object.values(registeredViews)) {
+    if (!shouldNotBeIncludedInSchema(includedTypes, view.type)) {
+      rootQueryArgs.fields[view.name] = buildViewField(view);
+    }
+  }
+
   return new GraphQLObjectType(rootQueryArgs);
 };
 
@@ -3179,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)
@@ -3186,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
@@ -3195,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(
@@ -3202,14 +3699,53 @@ const queryNameConflict = (name) => new SimfinityError(
   'QUERY_NAME_CONFLICT', 500,
 );
 
+// The root names of the generated queries of the endpoint types a schema includes.
+const generatedQueryNames = (includedQueryTypes) => Object.values(typesDict.types)
+  .filter((type) => type.simpleEntityEndpointName && !shouldNotBeIncludedInSchema(includedQueryTypes, type.gqltype))
+  .flatMap((type) => [type.simpleEntityEndpointName, type.listEntitiesEndpointName, `${type.listEntitiesEndpointName}_aggregate`]);
+
+const isIncludedCustomQuery = (name, includedCustomQueries) => Object.hasOwn(registeredQueries, name)
+  && !shouldNotBeIncludedInSchema(includedCustomQueries, name);
+
 const assertQueryNamesAvailable = (includedQueryTypes, includedCustomQueries) => {
-  for (const type of Object.values(typesDict.types)) {
-    if (!type.simpleEntityEndpointName || shouldNotBeIncludedInSchema(includedQueryTypes, type.gqltype)) continue;
-    for (const name of [type.simpleEntityEndpointName, type.listEntitiesEndpointName, `${type.listEntitiesEndpointName}_aggregate`]) {
-      if (Object.hasOwn(registeredQueries, name) && !shouldNotBeIncludedInSchema(includedCustomQueries, name)) {
-        throw queryNameConflict(name);
+  for (const name of generatedQueryNames(includedQueryTypes)) {
+    if (isIncludedCustomQuery(name, includedCustomQueries)) throw queryNameConflict(name);
+  }
+};
+
+// Every registered view, whether or not the schema includes it: its type is an endpoint type of this
+// runtime, and its params are valid argument names that are neither fields of the type, which covers
+// stored, reference, collection and virtual fields, nor the generated list arguments. A view that the
+// schema includes, because it includes the view's type, also needs a name that no included generated
+// query or custom query takes.
+const assertViewsAvailable = (includedQueryTypes, includedCustomQueries) => {
+  const views = Object.values(registeredViews);
+  if (!views.length) return;
+  const generatedNames = new Set(generatedQueryNames(includedQueryTypes));
+  for (const { name, type, params } of views) {
+    const registration = typesDict.types[type.name];
+    if (!registration || registration.gqltype !== type || registration.endpoint !== true
+      || !registration.simpleEntityEndpointName) {
+      throw invalidView(`${name} needs a type registered with connect() in this runtime`);
+    }
+    const fields = type.getFields();
+    for (const paramName of Object.keys(params)) {
+      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 __`);
+      }
+      // 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)) {
+        throw invalidView(`${name} param ${paramName} has the name of a generated list query argument`);
       }
     }
+    if (!shouldNotBeIncludedInSchema(includedQueryTypes, type)
+      && (generatedNames.has(name) || isIncludedCustomQuery(name, includedCustomQueries))) {
+      throw queryNameConflict(name);
+    }
   }
 };
 
@@ -3241,6 +3777,7 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   // Reject before models, resolvers or roots are built, so a rejected schema changes nothing.
   const { includedCustomQueries } = readSchemaOptions(options);
   assertQueryNamesAvailable(includedQueryTypes, includedCustomQueries);
+  assertViewsAvailable(includedQueryTypes, includedCustomQueries);
   Object.values(typesDict.types).forEach(({ gqltype }) => validateScope(gqltype));
   const schemaTypes = collectSchemaOutputTypes();
   schemaTypes.forEach(assertNotBoundElsewhere);
@@ -3252,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) {
@@ -3272,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);
     }
   });
 
@@ -3316,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) => {
@@ -3324,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;
 };
 
@@ -3385,6 +3933,64 @@ const registerCustomQuery = (name, description, inputModel, outputModel, callbac
   registeredQueries[name] = registration;
 };
 
+const invalidView = (detail) => new SimfinityError(`registerView ${detail}`, 'INVALID_VIEW', 500);
+
+// A view parameter is a value the client sends as a variable or a literal: a scalar, an enum or a list
+// of them, each possibly NonNull. An input object is never one, wherever it is nested.
+const isViewParamType = (type) => {
+  if (isNonNullType(type) || isListType(type)) return isViewParamType(type.ofType);
+  return isScalarType(type) || isEnumType(type);
+};
+
+const isNonNullPlainObject = (value) => value !== null && typeof value === 'object' && isPlainObject(value);
+
+const VIEW_OPTION_KEYS = new Set(['type', 'description', 'params', 'where']);
+const VIEW_PARAM_KEYS = new Set(['type', 'description', 'defaultValue']);
+
+const validateViewParams = (params) => {
+  if (params === undefined) return;
+  if (!isNonNullPlainObject(params)) throw invalidView('params must be an object');
+  for (const [paramName, param] of Object.entries(params)) {
+    if (!isNonNullPlainObject(param)) throw invalidView(`param ${paramName} must be an object`);
+    for (const key of Object.keys(param)) {
+      if (!VIEW_PARAM_KEYS.has(key)) throw invalidView(`param ${paramName} has an unknown key ${key}`);
+    }
+    if (!isViewParamType(param.type)) {
+      throw invalidView(`param ${paramName} type must be a scalar, an enum or a list of them, not an input object`);
+    }
+    if (param.description !== undefined && typeof param.description !== 'string') {
+      throw invalidView(`param ${paramName} description must be a string`);
+    }
+  }
+};
+
+const validateViewRegistration = (name, options) => {
+  if (typeof name !== 'string' || !/^[_A-Za-z][_0-9A-Za-z]*$/.test(name) || name.startsWith('__')) {
+    throw invalidView('requires a valid GraphQL field name that does not start with __');
+  }
+  if (name.endsWith('_aggregate')) {
+    throw invalidView(`name ${name} must not end with _aggregate, which the generated aggregate queries use`);
+  }
+  if (!isNonNullPlainObject(options)) throw invalidView('requires an options object');
+  for (const key of Object.keys(options)) {
+    if (!VIEW_OPTION_KEYS.has(key)) throw invalidView(`has an unknown option ${key}`);
+  }
+  if (!(options.type instanceof GraphQLObjectType)) throw invalidView('type must be a GraphQLObjectType');
+  if (typeof options.description !== 'string' || options.description === '') {
+    throw invalidView('requires a non-empty description');
+  }
+  validateViewParams(options.params);
+  if (typeof options.where !== 'function') throw invalidView('where must be a function');
+};
+
+const registerView = (name, options) => {
+  validateViewRegistration(name, options);
+  if (Object.hasOwn(registeredViews, name)) throw queryNameConflict(name);
+  registeredViews[name] = {
+    name, type: options.type, description: options.description, params: options.params ?? {}, where: options.where,
+  };
+};
+
 // Gives the field a new extensions object as well as the resolver, so a copy made before keeps
 // untagged extensions. It has a null prototype because graphql-js keeps such an object, rather than
 // copying it, when a type is rebuilt from toConfig().
@@ -3429,14 +4035,7 @@ const autoGenerateResolvers = (gqltype) => {
         if (!relatedTypeInfo || !relatedTypeInfo.model) {
           throw new Error(`Related type ${relatedType.name} not found or not connected. Make sure it's connected with simfinity.connect() or simfinity.addNoEndpointType().`);
         }
-        const joinedScopes = inspectClientPaths(relatedType, args, 'find');
-        const issued = markClientConstructs(assertQueryConditions(relatedType, args, 'find'));
-        const params = { type: relatedTypeInfo, args, operation: 'find', context };
-        await executeMiddleware(params);
-        await executeScope(params);
-        await applyJoinedScopes(joinedScopes, params);
-        const filling = settleClientArgs(relatedType, params, 'find', issued);
-        if (filling) await filling;
+        const params = await prepareRead(relatedTypeInfo, args, context, 'find');
         return loadChildren(relatedTypeInfo, connection, parent._id ?? parent.id, params.args, context);
       }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
       runtimeBoundTypes.set(gqltype, runtimeIdentity);
@@ -3494,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);
@@ -3524,6 +4125,7 @@ const addNoEndpointType = (gqltype) => {
     gqltype, endpoint: false, model: null, needsModel,
   };
   validateScope(gqltype);
+  concurrencyDeclared(gqltype);
   if (adapter.validateRegistration) adapter.validateRegistration(registration);
 
   invalidateCollectionInputs(gqltype);
@@ -3537,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();
@@ -3550,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
@@ -3622,6 +4226,7 @@ function formatArgs(argsArray) {
     use,
     registerMutation,
     registerCustomQuery,
+    registerView,
     saveObject,
     preventCreatingCollection,
   };