@simtlix/simfinity-core 3.5.8 → 3.5.9

package/README.md

@@ -16,13 +16,13 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 - `preventCreatingCollection` to pass validation-only storage setup to an adapter;
 - `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size and nested-operation limits.
 
-The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. The MongoDB adapter defines it.
+The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly`, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
 
 Entity types, those registered with `connect()` and the targets of non-embedded relations, resolve `id` to `_id`, falling back to `id`, whatever the `createSchema()` allowlists include; types used only as embedded values keep their declared `id`. Embedded copies of an entity type resolve the same way, so they return their declared `id` unless the adapter stores an `_id` for them, as MongoDB does for embedded list items. The resolver is set on the type object, so it applies in every runtime that shares the type. `createSchema()` marks these registrations with `storedIdentity: true` before calling `adapter.prepare()`.
 
 When a runtime first creates a schema, it binds each GraphQL object type whose non-embedded relation fields receive its generated resolvers. It also reserves each reachable object type that still has a non-embedded relation field without a resolver, such as an unregistered custom mutation result. Registering a bound or reserved type in another runtime, or building another runtime's schema that reaches it through fields, interfaces, union members or custom mutation results, throws `TYPE_BOUND_TO_OTHER_RUNTIME` (409). `createSchema()` also rejects a type with a relation field copied, by `toConfig()` or a field spread, after another runtime generated that field's resolver. Create type objects once per runtime, for example with a factory function. Types without non-embedded relation fields, and types whose relation fields all have application resolvers, can be shared, and another runtime can use a `toConfig()` copy made before the first runtime built its schema. A shared custom mutation result type with an unresolved relation field is rejected.
 
-Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime.
+Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime. Generated inputs that would have no fields are left out with a `Configuration issue` warning, with the collection operations, embedded fields and mutations that would take them; a non-null embedded field whose embedded type has no writable fields throws `INVALID_MODEL` (400) when generated mutations reach its owner. An application type named `FieldExtensionsType` or `RelationType` makes Simfinity rename its introspection metadata types to `SimfinityFieldExtensionsType` and `SimfinityRelationType` when it is in the process's first Simfinity schema. That schema fixes the names: in a later `createSchema()`, an application type with one of the current names, the original ones or the fallback names after a rename, throws `RESERVED_TYPE_NAME` (500), before `adapter.prepare()` when it is an included endpoint type, a registered mutation's input or output type, an output type they reach or a field argument's type, and when the schema is constructed otherwise, such as for a type inside an input object's fields.
 
 Generated and custom mutations run through `adapter.withTransaction`. Retried attempts receive fresh clones of GraphQL input objects, lists, and dates while enum values keep their identity. An adapter can define `stateValue` when its persisted enum representation differs from GraphQL enum names.
 
@@ -34,6 +34,6 @@ Importing the runtime installs Simfinity's `__Field.extensions` introspection fi
 
 `createQueryPlan` and `resolveModelPath` turn Simfinity filter, sort, pagination, and aggregation inputs into a driver-neutral plan resolved against that metadata.
 
-The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `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 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.5.8",
+  "version": "3.5.9",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -13,6 +13,9 @@ export { default as QLValue } from './const/QLValue.js';
 export { configureQueryLimits, paginationStages } from './query-limits.js';
 export { configureMutationLimits } from './mutation-limits.js';
 export { default as auth } from './auth/index.js';
+// The same classes as auth.UnauthenticatedError and auth.ForbiddenError; types/index.d.ts has
+// always declared them as root exports.
+export { UnauthenticatedError, ForbiddenError } from './auth/errors.js';
 export { default as plugins } from './plugins.js';
 export { default as scalars } from './scalars.js';
 export { default as validators } from './validators.js';

package/src/introspection.js

@@ -5,12 +5,11 @@ import {
   __Field,
 } from 'graphql';
 
-// getFields() supports both lazy and already materialized introspection fields.
-// Reuse the shared field on repeated module evaluation to preserve type identity.
-const introspectionFields = __Field.getFields();
-if (!introspectionFields.extensions) {
+// The object types of `__Field.extensions`: FieldExtensionsType and the RelationType of its
+// `relation` field, under the given names.
+const createFieldMetadataType = (extensionsName, relationName) => {
   const RelationType = new GraphQLObjectType({
-    name: 'RelationType',
+    name: relationName,
     fields: () => ({
       embedded: { type: GraphQLBoolean },
       connectionField: { type: GraphQLString },
@@ -18,20 +17,55 @@ if (!introspectionFields.extensions) {
     }),
   });
 
-  const FieldExtensionsType = new GraphQLObjectType({
-    name: 'FieldExtensionsType',
+  return new GraphQLObjectType({
+    name: extensionsName,
     fields: () => ({
       relation: { type: RelationType },
       stateMachine: { type: GraphQLBoolean },
       readOnly: { type: GraphQLBoolean },
     }),
   });
+};
 
+// getFields() supports both lazy and already materialized introspection fields.
+// Reuse the shared field on repeated module evaluation to preserve type identity.
+const introspectionFields = __Field.getFields();
+if (!introspectionFields.extensions) {
   introspectionFields.extensions = {
-    type: FieldExtensionsType,
+    type: createFieldMetadataType('FieldExtensionsType', 'RelationType'),
     name: 'extensions',
     resolve: (obj) => obj.extensions,
     args: [],
     isDeprecated: false,
   };
 }
+
+// Set on the shared extensions field, by any evaluation of this module, once a Simfinity schema
+// contains the metadata types; their names do not change after that.
+const NAMES_FIXED = Symbol.for('simfinity.fieldMetadataNamesFixed');
+const extensionsField = () => __Field.getFields().extensions;
+
+/** The metadata types `__Field.extensions` returns now: [FieldExtensionsType, RelationType]. */
+export const fieldMetadataTypes = () => {
+  const extensionsType = extensionsField().type;
+  return [extensionsType, extensionsType.getFields().relation.type];
+};
+
+export const fieldMetadataNamesFixed = () => extensionsField()[NAMES_FIXED] === true;
+
+export const fixFieldMetadataNames = () => {
+  extensionsField()[NAMES_FIXED] = true;
+};
+
+// Every schema constructed afterwards, in the whole process, contains the metadata types under the
+// new names. The extensions field object keeps its identity, so other evaluations of this module and
+// the auth plugin, which read its type when they need it, follow the change. Returns a function that
+// puts the previous type objects back, for a schema whose construction fails.
+export const renameFieldMetadataTypes = (extensionsName, relationName) => {
+  const field = extensionsField();
+  const previous = field.type;
+  field.type = createFieldMetadataType(extensionsName, relationName);
+  return () => {
+    field.type = previous;
+  };
+};

package/src/runtime.js

@@ -19,7 +19,9 @@ import { isThenable } from './auth/thenable.js';
 import {
   getFieldStorageName, getListShape, markStoredIdentity, normalizeConnectionField,
 } from './relation-storage.js';
-import './introspection.js';
+import {
+  fieldMetadataNamesFixed, fieldMetadataTypes, fixFieldMetadataNames, renameFieldMetadataTypes,
+} from './introspection.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
@@ -212,8 +214,9 @@ const GraphQLJSON = new GraphQLScalarType({
 
 // The type called `name` that a schema built from these roots would contain, other than through
 // `skip`, following the references GraphQLSchema collects: fields, arguments, interfaces, union
-// members and input fields.
-const findSchemaType = (roots, name, skip) => {
+// members and input fields. With `inputFields` false, input objects are matched by their own name
+// only, and their fields are never read.
+const findSchemaType = (roots, name, skip, { inputFields = true } = {}) => {
   const visited = new Set();
   const pending = [...roots];
   while (pending.length) {
@@ -228,13 +231,75 @@ const findSchemaType = (roots, name, skip) => {
         pending.push(field.type, ...field.args.map((arg) => arg.type));
       }
     }
-    if (type instanceof GraphQLInputObjectType) {
+    if (inputFields && type instanceof GraphQLInputObjectType) {
       for (const field of Object.values(type.getFields())) pending.push(field.type);
     }
   }
   return null;
 };
 
+// Every schema contains Simfinity's field metadata types, the types of `__Field.extensions`, named
+// FieldExtensionsType and RelationType unless a clash renamed them. Returns the type of a schema built
+// from these roots that has the name of one of them, or null (#162).
+const fieldMetadataClash = (roots, options) => fieldMetadataTypes()
+  .map((own) => findSchemaType(roots, own.name, own, options)).find(Boolean) || null;
+
+// The first schema that contains the metadata types fixes their names for the process, so a later
+// schema with a type of the same name is rejected.
+const reservedTypeNameError = (clash) => new SimfinityError(
+  `Type ${clash.name} has the name of a type that Simfinity adds to every schema for __Field.extensions, `
+    + 'and a schema created earlier in this process already contains that type under this name. Rename '
+    + `${clash.name}, or create this schema first, so that Simfinity gives its types other names, such as `
+    + 'SimfinityFieldExtensionsType and SimfinityRelationType',
+  'RESERVED_TYPE_NAME',
+  500,
+);
+// The check before anything is built reads only what the output type check before it reads: output
+// types, their fields, arguments, interfaces and union members. Input objects, a registered
+// mutation's input among them, are checked by their own name, because their fields function may read
+// generated inputs (getInputType) that do not exist yet, and graphql-js keeps what it returns. A clash
+// inside an input's fields is found when the schema is constructed.
+const assertFieldMetadataNamesFree = (roots) => {
+  const clash = fieldMetadataNamesFixed() && fieldMetadataClash(roots, { inputFields: false });
+  if (clash) throw reservedTypeNameError(clash);
+};
+
+// Constructs the schema of these roots. When one of its types has the name of a field metadata type,
+// 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) => {
+  const roots = [query, mutation];
+  const clash = fieldMetadataClash(roots);
+  if (clash && fieldMetadataNamesFixed()) throw reservedTypeNameError(clash);
+  let names = null;
+  if (clash) {
+    const taken = (name) => findSchemaType(roots, name) !== null;
+    let suffix = '';
+    for (let n = 2; taken(`SimfinityFieldExtensionsType${suffix}`) || taken(`SimfinityRelationType${suffix}`); n += 1) {
+      suffix = String(n);
+    }
+    names = [`SimfinityFieldExtensionsType${suffix}`, `SimfinityRelationType${suffix}`];
+  }
+  const restore = names ? renameFieldMetadataTypes(...names) : null;
+  let schema;
+  try {
+    schema = new GraphQLSchema({ query, mutation });
+  } catch (error) {
+    if (restore) restore();
+    throw error;
+  }
+  fixFieldMetadataNames();
+  if (names) {
+    console.warn(`Configuration issue: the schema has a type named ${clash.name}, the name of a type that `
+      + `Simfinity adds to every schema for __Field.extensions, so Simfinity names its types ${names[0]} and `
+      + `${names[1]} in every schema this process creates from now on. Use these names in named fragments `
+      + 'and permission maps.');
+  }
+  return schema;
+};
+
 // graphql-js wraps a value thrown while resolving a field (locatedError): the wrapper has the field
 // path and repeats the thrown error's message. A thrown non-Error becomes a NonErrorThrown whose
 // message prints the value.
@@ -609,6 +674,10 @@ const wrapListInputType = (itemType, listShape, preserveOuterNonNull) => {
 
 const capitalize = (name) => name.charAt(0).toUpperCase() + name.slice(1);
 
+// A GraphQL input object needs at least one field, so a generated input that would have none is
+// left out, together with the operations, fields and mutations that would take it (#161).
+const hasInputFields = (inputType) => Object.keys(inputType.getFields()).length > 0;
+
 /**
  * The `added` item input of a referenced collection: the item type's create input without the
  * back-reference that the parent supplies. Its fields are read from the item's create input when
@@ -649,9 +718,11 @@ const createTypeWithExcludedField = (inputNamePrefix, itemType, fieldToExclude,
 };
 
 // A referenced collection's operation input. The item inputs are read when the schema is built, so
-// the item type's inputs need not exist yet.
+// the item type's inputs need not exist yet. `added` or `updated` is left out when its item input
+// would have no fields, such as `added` for a child whose only writable field is the back-reference;
+// `deleted` always remains. `owner` names the collection, as `Type.field`, in the warning.
 const createOneToManyInputType = (name, inputNamePrefix, itemType, connection,
-  itemNonNull = false, optionalFields = []) => {
+  itemNonNull = false, optionalFields = [], owner = name) => {
   const inputTypeForAdd = connection.declaredFieldName
     ? createTypeWithExcludedField(
       inputNamePrefix,
@@ -663,17 +734,40 @@ const createOneToManyInputType = (name, inputNamePrefix, itemType, connection,
     : null;
   const listOf = (type) => new GraphQLList(itemNonNull ? new GraphQLNonNull(type) : type);
 
+  const omittedOperation = {
+    added: () => `because ${itemType.name} has no writable fields`
+      + `${connection.declaredFieldName ? ` besides its connectionField ${connection.declaredFieldName}` : ''}; `
+      + `create ${itemType.name} records with its own mutations or a registered mutation.`,
+    updated: () => `because ${itemType.name} has no writable fields and no writable id; update `
+      + `${itemType.name} records with a registered mutation.`,
+  };
+
   return new GraphQLInputObjectType({
     name,
-    fields: () => ({
-      added: { type: listOf(inputTypeForAdd || getInputType(itemType)) },
-      updated: { type: listOf(typesDictForUpdate.types[itemType.name].inputType) },
+    fields: () => {
+      const fields = {};
+      const itemInputs = {
+        added: inputTypeForAdd || getInputType(itemType),
+        updated: typesDictForUpdate.types[itemType.name].inputType,
+      };
+      for (const [operation, itemInput] of Object.entries(itemInputs)) {
+        if (hasInputFields(itemInput)) {
+          fields[operation] = { type: listOf(itemInput) };
+        } else {
+          warnOnce(itemType, `emptyItemInput:${owner}:${operation}`, `Configuration issue: ${owner} has no `
+            + `\`${operation}\` operation in generated inputs, ${omittedOperation[operation]()}`);
+        }
+      }
       // Null IDs are skipped, so `deleted` accepts them whatever the collection's item nullability.
-      deleted: { type: new GraphQLList(GraphQLID) },
-    }),
+      fields.deleted = { type: new GraphQLList(GraphQLID) };
+      return fields;
+    },
   });
 };
 
+// What graphQLListInputType returns for a list of an embedded type whose input has no fields.
+const NO_INPUT_FIELDS = Symbol('no input fields');
+
 const graphQLListInputType = (dict, fieldEntry, fieldEntryName,
   inputNamePrefix, connectionField, preserveOuterNonNull, ownerName) => {
   const listShape = getListShape(fieldEntry.type);
@@ -686,13 +780,15 @@ const graphQLListInputType = (dict, fieldEntry, fieldEntryName,
     if (!fieldEntry.extensions?.relation?.embedded) {
       const oneToMany = createOneToManyInputType(`OneToMany${inputNamePrefix}${fieldEntryName}`,
         inputNamePrefix, itemType, normalizeConnectionField(itemType, connectionField),
-        listShape.itemNonNull);
+        listShape.itemNonNull, [], `${ownerName}.${fieldEntryName}`);
       return preserveOuterNonNull && listShape.outerNonNull
         ? new GraphQLNonNull(oneToMany)
         : oneToMany;
     }
     if (registration.inputType) {
-      return wrapListInputType(registration.inputType, listShape, preserveOuterNonNull);
+      return hasInputFields(registration.inputType)
+        ? wrapListInputType(registration.inputType, listShape, preserveOuterNonNull)
+        : NO_INPUT_FIELDS;
     }
   } else if (itemType instanceof GraphQLScalarType || itemType instanceof GraphQLEnumType) {
     return wrapListInputType(itemType, listShape, preserveOuterNonNull);
@@ -725,14 +821,47 @@ const selfCollectionInputType = (gqltype, fieldEntryName, fieldEntry, forUpdate,
     // optional there, as such items had no such fields before; items added by an update keep them
     // as the type declares them.
     forUpdate ? [] : selfFields,
+    `${gqltype.name}.${fieldEntryName}`,
   );
   return !forUpdate && listShape.outerNonNull ? new GraphQLNonNull(oneToMany) : oneToMany;
 };
 
+// An embedded field, single or list, whose embedded type's create or update input has no fields is
+// left out of that input of its owner. Only the create input is empty when the type's writable fields
+// hold only ids, which create inputs leave out; generated updates still set the field then.
+const warnEmptyEmbeddedInputs = (gqltype, fieldName, embeddedTypeName, noCreate, noUpdate) => {
+  if (!noCreate && !noUpdate) return;
+  const field = `Configuration issue: ${gqltype.name}.${fieldName} `;
+  if (!noUpdate) {
+    warnOnce(gqltype, `emptyEmbeddedInput:${fieldName}`, `${field}is left out of generated create inputs, because `
+      + `the create input of its embedded type ${embeddedTypeName} would have no fields (create inputs leave out `
+      + 'ids), so generated creates cannot set it, while generated updates still can; to set it on create, use a '
+      + 'controller or a registered mutation.');
+    return;
+  }
+  const inputs = [noCreate && 'create', 'update'].filter(Boolean).join(' and ');
+  warnOnce(gqltype, `emptyEmbeddedInput:${fieldName}`, `${field}is left out of generated ${inputs} inputs, because `
+    + `its embedded type ${embeddedTypeName} has no writable fields, so generated mutations cannot set it; set it `
+    + 'in a controller or a registered mutation, and mark it readOnly to state that it is output-only.');
+};
+
+// A non-null embedded field, single or list, that generated create inputs cannot set. Generated
+// mutations that reach the owner's create input would store records without it, so such a schema is
+// rejected; one whose generated mutations cannot reach that input only leaves the field out.
+const requiredEmbeddedWithoutInputError = (gqltype, { field, embeddedTypeName }) => new SimfinityError(
+  `${gqltype.name}.${field} is non-null but its embedded type ${embeddedTypeName} has no writable fields, so `
+    + 'generated create inputs cannot set it; mark it readOnly and set it in a controller, or make it nullable',
+  'INVALID_MODEL',
+  400,
+);
+// Registration -> the non-null embedded fields its create input left out.
+const requiredFieldsWithoutCreateInput = new WeakMap();
+
 // Builds a type's create and update inputs, or returns every field whose input cannot be built yet:
 // `{ unresolvedFields: [{ field, waitsFor }] }`, where `waitsFor` names the embedded type whose
-// inputs the field waits for, and is absent when the field can have no generated input.
-const buildInputType = (gqltype) => {
+// inputs the field waits for, and is absent when the field can have no generated input. `reachable`
+// holds the types whose inputs the generated mutations of the schema reach.
+const buildInputType = (gqltype, reachable) => {
   const argTypes = gqltype.getFields();
 
   const fieldsArgs = {};
@@ -740,6 +869,13 @@ const buildInputType = (gqltype) => {
 
   const selfReferenceCollections = {};
   const unresolvedFields = [];
+  const requiredWithoutCreateInput = [];
+  // Leaves a non-null embedded field without a create input out, or rejects the schema.
+  const omitRequiredEmbedded = (field, embeddedTypeName) => {
+    const omitted = { field, embeddedTypeName };
+    if (reachable.has(gqltype)) throw requiredEmbeddedWithoutInputError(gqltype, omitted);
+    requiredWithoutCreateInput.push(omitted);
+  };
 
   for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
     const fieldArg = {};
@@ -774,8 +910,17 @@ const buildInputType = (gqltype) => {
             } else if (requireRegisteredType(typesDict, unwrapNonNull(fieldEntry.type), fieldEntryName,
               gqltype.name).inputType
               && typesDictForUpdate.types[fieldEntryNameValue].inputType) {
-              fieldArg.type = typesDict.types[fieldEntryNameValue].inputType;
-              fieldArgForUpdate.type = typesDictForUpdate.types[fieldEntryNameValue].inputType;
+              // Create and update inputs are decided apart: an embedded type whose only writable
+              // field is `id` has one only for updates.
+              const embeddedCreate = typesDict.types[fieldEntryNameValue].inputType;
+              const embeddedUpdate = typesDictForUpdate.types[fieldEntryNameValue].inputType;
+              if (hasInputFields(embeddedCreate)) fieldArg.type = embeddedCreate;
+              else if (fieldEntry.type instanceof GraphQLNonNull) {
+                omitRequiredEmbedded(fieldEntryName, fieldEntryNameValue);
+              }
+              if (hasInputFields(embeddedUpdate)) fieldArgForUpdate.type = embeddedUpdate;
+              warnEmptyEmbeddedInputs(gqltype, fieldEntryName, fieldEntryNameValue,
+                !fieldArg.type, !fieldArgForUpdate.type);
             } else {
               unresolvedFields.push({ field: fieldEntryName, waitsFor: fieldEntryNameValue });
             }
@@ -802,8 +947,11 @@ const buildInputType = (gqltype) => {
               fieldEntryName, `${gqltype.name}U`,
               fieldEntry.extensions?.relation?.connectionField, false, gqltype.name);
             if (listInputTypeForAdd && listInputTypeForUpdate) {
-              fieldArg.type = listInputTypeForAdd;
-              fieldArgForUpdate.type = listInputTypeForUpdate;
+              if (listInputTypeForAdd !== NO_INPUT_FIELDS) fieldArg.type = listInputTypeForAdd;
+              else if (listShape.outerNonNull) omitRequiredEmbedded(fieldEntryName, listShape.itemType.name);
+              if (listInputTypeForUpdate !== NO_INPUT_FIELDS) fieldArgForUpdate.type = listInputTypeForUpdate;
+              warnEmptyEmbeddedInputs(gqltype, fieldEntryName, listShape.itemType.name,
+                listInputTypeForAdd === NO_INPUT_FIELDS, listInputTypeForUpdate === NO_INPUT_FIELDS);
             } else {
               // An object item here is embedded and its inputs are not built yet; any other item,
               // such as a list, has no generated input.
@@ -858,7 +1006,9 @@ const buildInputType = (gqltype) => {
     fields: fieldsArgForUpdate,
   });
 
-  return { inputTypeBody: inputTypeForAdd, inputTypeBodyForUpdate: inputTypeForUpdate };
+  return {
+    inputTypeBody: inputTypeForAdd, inputTypeBodyForUpdate: inputTypeForUpdate, requiredWithoutCreateInput,
+  };
 };
 
 const getInputType = (type) => typesDict.types[type.name].inputType;
@@ -964,6 +1114,14 @@ const unresolvedInputTypesMessage = (pendingTypeNames, unresolvedByType) => {
 
 const buildPendingInputTypes = (waitingForInputType, includedMutationTypes) => {
   claimSelfCollectionNames(waitingForInputType, includedMutationTypes);
+  // Inputs built for an earlier schema, which did not reach them, may leave out a non-null embedded
+  // field that this schema's generated mutations would need; inputs built now are checked as built.
+  const reachable = typesWithReachableInputs(includedMutationTypes);
+  for (const gqltype of reachable) {
+    const registration = typesDict.types[gqltype.name];
+    const [omitted] = (registration.inputType && requiredFieldsWithoutCreateInput.get(registration)) || [];
+    if (omitted) throw requiredEmbeddedWithoutInputError(gqltype, omitted);
+  }
   let pending = waitingForInputType;
   let previousPendingCount = Object.keys(pending).length + 1;
   // Type name -> the fields whose input could not be built in the last pass.
@@ -983,10 +1141,11 @@ const buildPendingInputTypes = (waitingForInputType, includedMutationTypes) => {
       const { gqltype } = value;
       if (typesDict.types[gqltype.name].inputType) continue;
 
-      const result = buildInputType(gqltype);
+      const result = buildInputType(gqltype, reachable);
       if (result.inputTypeBody && result.inputTypeBodyForUpdate) {
         typesDict.types[gqltype.name].inputType = result.inputTypeBody;
         typesDictForUpdate.types[gqltype.name].inputType = result.inputTypeBodyForUpdate;
+        requiredFieldsWithoutCreateInput.set(typesDict.types[gqltype.name], result.requiredWithoutCreateInput);
       } else {
         stillWaiting[key] = value;
         unresolvedFields[gqltype.name] = result.unresolvedFields;
@@ -1707,9 +1866,22 @@ const resolveById = async (type, args, context, requiredId) => {
   return results[0] || null;
 };
 
+// Why a type's generated create or update input has no fields, for the warnings of buildMutation. An
+// update input also needs a writable id.
+const withoutWritableFields = (type, { noWritableId = false } = {}) => {
+  const stateField = type.gqltype.getFields().state;
+  const managedState = type.stateMachine && stateField && !stateField.extensions?.readOnly;
+  const state = managedState ? ' besides its state, which its state machine manages' : '';
+  const id = noWritableId ? `${state ? ',' : ''} and no writable id` : '';
+  return `${type.gqltype.name} has no writable fields${state}${id}`;
+};
+
 // Every generated mutation field carries extensions.simfinityMutation with its operation (and, for
 // a state-machine action, the action and its from/to states), so tools such as the MCP package can
 // classify it without guessing from its name. Extensions do not appear in SDL or introspection.
+// An input object needs a field, so a type whose create input has none gets no add mutation, and
+// one whose update input has none, which only a type without a writable id can have, gets no update
+// mutation or state machine actions either (#161).
 const buildMutation = (name, includedMutationTypes, includedCustomMutations) => {
   const rootQueryArgs = {};
   rootQueryArgs.name = name;
@@ -1722,24 +1894,33 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
       if (type.endpoint) {
         const argsObject = { input: { type: new GraphQLNonNull(type.inputType) } };
 
-        rootQueryArgs.fields[`add${type.simpleEntityEndpointName}`] = {
-          type: type.gqltype,
-          description: 'add',
-          args: argsObject,
-          extensions: { simfinityMutation: { typeName: type.gqltype.name, operation: operations.SAVE } },
-          async resolve(parent, args, context) {
-            const params = {
-              type,
-              args,
-              operation: operations.SAVE,
-              context,
-            };
+        if (hasInputFields(type.inputType)) {
+          rootQueryArgs.fields[`add${type.simpleEntityEndpointName}`] = {
+            type: type.gqltype,
+            description: 'add',
+            args: argsObject,
+            extensions: { simfinityMutation: { typeName: type.gqltype.name, operation: operations.SAVE } },
+            async resolve(parent, args, context) {
+              const params = {
+                type,
+                args,
+                operation: operations.SAVE,
+                context,
+              };
 
-            await executeMiddleware(params);
-            return executeOperation(type.model, type.gqltype, type.controller,
-              args.input, operations.SAVE, null, null, context, type.inputType);
-          },
-        };
+              await executeMiddleware(params);
+              return executeOperation(type.model, type.gqltype, type.controller,
+                args.input, operations.SAVE, null, null, context, type.inputType);
+            },
+          };
+        } else {
+          warnOnce(type.gqltype, 'emptyCreateInput', `Configuration issue: ${withoutWritableFields(type)}, so the `
+            + `schema has no add${type.simpleEntityEndpointName} mutation; create its records with a registered `
+            + (type.stateMachine
+              ? 'mutation, which must set the initial state (saveObject() sets it).'
+              : `mutation that takes no input or an input of its own, since getInputType(${type.gqltype.name}) `
+                + 'has no fields.'));
+        }
         rootQueryArgs.fields[`delete${type.simpleEntityEndpointName}`] = {
           type: type.gqltype,
           description: 'delete',
@@ -1764,7 +1945,12 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
 
   for (const type of Object.values(typesDictForUpdate.types)) {
     if (!shouldNotBeIncludedInSchema(includedMutationTypes, type.gqltype)) {
-      if (type.endpoint) {
+      if (type.endpoint && !hasInputFields(type.inputType)) {
+        const reason = withoutWritableFields(type, { noWritableId: true });
+        warnOnce(type.gqltype, 'emptyUpdateInput', `Configuration issue: ${reason}, so its generated update input `
+          + `would have no fields and the schema has no update${type.simpleEntityEndpointName} mutation`
+          + `${type.stateMachine ? ' and no state machine actions' : ''}.`);
+      } else if (type.endpoint) {
         const argsObject = { input: { type: new GraphQLNonNull(type.inputType) } };
         rootQueryArgs.fields[`update${type.simpleEntityEndpointName}`] = {
           type: type.gqltype,
@@ -1967,6 +2153,102 @@ const installIdResolver = (gqltype) => {
   if (idField && !idField.resolve) idField.resolve = markGenerated((parent) => parent._id ?? parent.id);
 };
 
+// A rendered embedded value that may hold no data: a plain object, or a hydrated record, which
+// converts itself with toObject() (MongoDB documents and their nested paths do). Promises, arrays,
+// functions and other objects, such as dates or identifiers, are values.
+const isRecordObject = (value) => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || isThenable(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null || typeof value.toObject === 'function';
+};
+const isPlainObject = (value) => {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+// The members an embedded value stores. The rule below reads them instead of the value, so no getter
+// or virtual of the application runs, whatever the selection. An adapter that hydrates records
+// returns their stored data through rawEmbeddedValue (MongoDB: a nested path's raw value, a
+// subdocument's _doc); an absent stored value has no members. A plain object is read as it is.
+// Returns null for anything else, such as a record the adapter does not convert, which counts as data.
+const storedMembersOf = (value) => {
+  if (!isRecordObject(value)) return null;
+  const stored = typeof adapter.rawEmbeddedValue === 'function' ? adapter.rawEmbeddedValue(value) : value;
+  if (stored === null || stored === undefined) return {};
+  return typeof stored === 'object' && !Array.isArray(stored) && !isThenable(stored) && isPlainObject(stored)
+    ? stored : null;
+};
+
+// A stored member: an own data property, read without calling accessors. An accessor is present,
+// whatever it would return.
+const PRESENT = Symbol('present');
+const ownStoredValue = (stored, key) => {
+  const descriptor = Object.getOwnPropertyDescriptor(stored, key);
+  if (!descriptor) return undefined;
+  if (!('value' in descriptor)) return PRESENT;
+  return isObjectMember(key, descriptor.value) ? undefined : descriptor.value;
+};
+// A referenced collection stores nothing in the object. `id` reads the stored identity, `_id` before
+// `id`, as the generated entity resolver (installIdResolver) and Mongoose's id virtual do. Every other
+// member is stored under its storage name.
+const isReferencedCollection = (member) => {
+  const relation = member.extensions?.relation;
+  return Boolean(relation && !relation.embedded && getListShape(member.type));
+};
+const storedMemberValue = (stored, memberName, member) => {
+  if (isReferencedCollection(member)) return undefined;
+  const identity = memberName === 'id' ? ownStoredValue(stored, '_id') : undefined;
+  return identity ?? ownStoredValue(stored, getFieldStorageName(memberName, member));
+};
+
+// Whether stored members hold no data: every member is null or undefined, an empty list, or a
+// singular embedded object that holds no data. Any other value, a promise or an accessor included,
+// is data. An object that contains itself, which only a custom result can, holds data.
+const holdsNoData = (stored, type, ancestors = []) => !ancestors.includes(stored)
+  && Object.entries(type.getFields()).every(([memberName, member]) => {
+    const value = storedMemberValue(stored, memberName, member);
+    if (value === null || value === undefined) return true;
+    if (Array.isArray(value)) return value.length === 0;
+    const memberType = unwrapNonNull(member.type);
+    if (member.extensions?.relation?.embedded !== true || !(memberType instanceof GraphQLObjectType)) return false;
+    const nested = storedMembersOf(value);
+    return nested !== null && holdsNoData(nested, memberType, [...ancestors, stored]);
+  });
+
+// The members that count: non-null members that generated inputs accept. As on writes
+// (completeEmbeddedValue), `id` and readOnly members do not; nor do interface and union members,
+// which buildInputType leaves out; nor do referenced collections or members with an application
+// resolver, which may compute a value.
+const countsAsRequired = (type, memberName, member) => member.type instanceof GraphQLNonNull
+  && !isReferencedCollection(member) && memberName !== 'id' && !member.extensions?.readOnly
+  && !isAbstractOutputType(unwrapListAndNonNull(member.type)) && !hasApplicationResolver(type, memberName);
+const hasRequiredMember = (type) => Object.entries(type.getFields())
+  .some(([memberName, member]) => countsAsRequired(type, memberName, member));
+
+// Whether rendering such an object fails: a member that counts is null or undefined, or is a singular
+// embedded object that misses one of its own. A promise or an accessor counts as present.
+const missesRequiredMember = (stored, type) => Object.entries(type.getFields()).some(([memberName, member]) => {
+  if (!countsAsRequired(type, memberName, member)) return false;
+  const value = storedMemberValue(stored, memberName, member);
+  if (value === null || value === undefined) return true;
+  if (member.extensions?.relation?.embedded !== true || !(member.type.ofType instanceof GraphQLObjectType)) return false;
+  const nested = storedMembersOf(value);
+  return nested !== null && missesRequiredMember(nested, member.type.ofType);
+});
+
+// A type without a member that counts never reads as null, so its values are returned untouched,
+// with no member read. Reading stored members never changes the result otherwise: a value whose
+// members cannot be read, because an adapter hook or a property read throws, is returned as it is.
+const readEmbeddedObject = (value, type) => {
+  if (!(type instanceof GraphQLObjectType) || !hasRequiredMember(type)) return value;
+  try {
+    const stored = storedMembersOf(value);
+    return stored !== null && holdsNoData(stored, type) && missesRequiredMember(stored, type) ? null : value;
+  } catch {
+    return value;
+  }
+};
+
 // An adapter that hydrates stored records may render an explicitly null singular embedded object as
 // an object (MongoDB nested paths do); readEmbeddedValue returns null for it. Nullable singular
 // embedded fields of registered types, and of the embedded types they reach, read through it. The
@@ -1975,11 +2257,24 @@ const installIdResolver = (gqltype) => {
 // The value is read as graphql's default resolver reads it, so a method on the parent, such as one a
 // custom mutation result supplies, is still called; a promise it returns is read once it settles.
 // Only a field named like an Object.prototype member that reads as that member reads as null.
+// Such an adapter may also render an absent object, or store an omitted one, as an object that holds
+// nothing but its list defaults (MongoDB nested paths do). An object that holds no data and misses a
+// required member (see missesRequiredMember) cannot be rendered, so it reads as null, as an absent
+// object does on other read paths, whatever the selection. The rule reads the stored members
+// (storedMembersOf), never running a getter or virtual, and depends only on the value and its type,
+// so runtimes that share the type, with or without the hook, read the same. An object a
+// generated create or update writes does not read as null, since those writes require the members
+// counted, with one exception: Mongoose minimizes empty objects when it saves a new document, so a
+// create that writes an empty object for a required embedded member (`geo: {}`) stores that member
+// as absent. An object that holds nothing else then reads as null, as an omitted one does, except
+// where Mongoose hydrates the document (by-ID and reference reads, update responses) and the member is
+// a nested path, which it renders as `{}`. Generated models declare every embedded member as a nested
+// path except one named `type`, a single nested subdocument. PostgreSQL rejects such a create
+// (REQUIRED_VALUE).
 const readEmbeddedField = markGenerated((parent, args, context, info) => {
   const value = readOwnField(parent, args, context, info);
-  return isThenable(value)
-    ? value.then((resolved) => adapter.readEmbeddedValue(resolved))
-    : adapter.readEmbeddedValue(value);
+  const read = (resolved) => readEmbeddedObject(adapter.readEmbeddedValue(resolved), getNamedType(info.returnType));
+  return isThenable(value) ? value.then(read) : read(value);
 });
 
 const installEmbeddedValueResolvers = (gqltype, visited) => {
@@ -2042,6 +2337,20 @@ const assertCollectionConnections = () => {
 
 const getRegistrations = () => Object.values(typesDict.types);
 
+// 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 registered
+// mutations.
+const includedApplicationTypes = (includedQueryTypes, includedMutationTypes, includedCustomMutations) => [
+  ...Object.values(typesDict.types)
+    .filter((type) => type.endpoint
+      && ((type.simpleEntityEndpointName && !shouldNotBeIncludedInSchema(includedQueryTypes, type.gqltype))
+        || !shouldNotBeIncludedInSchema(includedMutationTypes, type.gqltype)))
+    .map((type) => type.gqltype),
+  ...Object.entries(registeredMutations)
+    .filter(([entry]) => !shouldNotBeIncludedInSchema(includedCustomMutations, entry))
+    .flatMap(([, { inputModel, outputModel }]) => [inputModel, outputModel].filter(Boolean)),
+];
+
 const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomMutations) => {
   // Reject before models, resolvers or roots are built, so a rejected schema changes nothing.
   Object.values(typesDict.types).forEach(({ gqltype }) => validateScope(gqltype));
@@ -2049,6 +2358,11 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   schemaTypes.forEach(assertNotBoundElsewhere);
   schemaTypes.forEach(assertFieldsNotBoundElsewhere);
   assertCollectionConnections();
+  // 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));
   const referencedTypes = markReferencedTypesForModelGeneration();
   // Entities, which keep their own stored identity: connect() types and relation targets.
   Object.values(typesDict.types).forEach((typeInfo) => {
@@ -2110,7 +2424,7 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
     query = buildRootQuery('RootQueryType', includedQueryTypes, aggregationResultTypeFor(applicationJSON));
   }
 
-  const schema = new GraphQLSchema({ query, mutation });
+  const schema = constructSchema(query, mutation);
   // Reserve reachable types whose relation fields still have no resolver, such as an unregistered
   // custom mutation result, so another runtime cannot later generate resolvers this schema executes.
   schemaTypes.forEach((type) => {

package/types/auth/errors.d.ts

@@ -4,12 +4,8 @@
  */
 import { auth } from '../index.js';
 
-/** Authentication error: code `UNAUTHENTICATED`, status 401. */
-export const UnauthenticatedError: typeof auth.UnauthenticatedError;
-export type UnauthenticatedError = InstanceType<typeof auth.UnauthenticatedError>;
-/** Authorization error: code `FORBIDDEN`, status 403. */
-export const ForbiddenError: typeof auth.ForbiddenError;
-export type ForbiddenError = InstanceType<typeof auth.ForbiddenError>;
+// The root classes themselves, which `auth.UnauthenticatedError` and `auth.ForbiddenError` also are.
+export { UnauthenticatedError, ForbiddenError } from '../index.js';
 export const createAuthError: typeof auth.createAuthError;
 
 declare const errors: Pick<typeof auth, 'UnauthenticatedError' | 'ForbiddenError' | 'createAuthError'>;

package/types/index.d.ts

@@ -227,11 +227,30 @@ export interface Runtime<Model = any, Session = any> {
    * reserves reachable types that still have a
    * non-embedded relation field without a resolver, such as an unregistered custom mutation result.
    * Every entity type resolves `id` to `_id ?? id`, whatever the allowlists include.
+   *
+   * A generated input that would have no fields is left out, with a `Configuration issue`
+   * warning: the `added` or `updated` operation of a collection whose child has no writable fields
+   * for it, an embedded field whose embedded type has none, `add<type>` for a type without
+   * writable fields, and `update<type>` and its state actions for a type without writable fields
+   * and without a writable `id`. A non-null embedded field whose embedded type has no writable
+   * fields throws `INVALID_MODEL` (400) while inputs are built when the generated mutations reach
+   * its owner's create input. When the process's first Simfinity schema has an application type
+   * named `FieldExtensionsType` or `RelationType`, Simfinity renames its `__Field.extensions`
+   * metadata types `SimfinityFieldExtensionsType` and `SimfinityRelationType` (numbered when
+   * taken) for every later schema and logs a warning; once those names are fixed, a type with one
+   * of them throws `RESERVED_TYPE_NAME` (500), before `adapter.prepare()` when it is an included
+   * endpoint type, a registered mutation's input or output type, an output type they reach or a
+   * field argument's type, and when the schema is constructed otherwise, such as for a type inside
+   * an input object's fields. The check before `adapter.prepare()` never reads an input object's
+   * fields, so a registered input's `fields` function may call `getInputType()`.
    */
   createSchema(includedQueryTypes?: GraphQLObjectType[] | null, includedMutationTypes?: GraphQLObjectType[] | null, includedCustomMutations?: string[] | null): GraphQLSchema;
   getModel(type: GraphQLObjectType | { name: string }): Model | null | undefined;
   getType(name: string | { name: string }): GraphQLObjectType | null | undefined;
-  /** Available after createSchema has built input types. */
+  /**
+   * Available after createSchema has built input types. It has no fields for a type without
+   * writable fields; such inputs are not part of generated schemas.
+   */
   getInputType(type: GraphQLObjectType | { name: string }): GraphQLInputObjectType | undefined;
   getRegistrations(): RuntimeRegistration<Model, Session>[];
   /**
@@ -276,8 +295,31 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * record renders as an object although the stored value is an explicit null; return any other
    * value unchanged. It must depend only on the value: these resolvers read no data and do not bind
    * their types, so a runtime that reaches a shared type may read through another runtime's hook.
+   * Simfinity then reads as null an object that holds no data when a non-null member would read as
+   * null, whatever the selection. These members do not count: `id`, readOnly members, interface and
+   * union members, members with their own resolver and referenced collections. An object whose type
+   * has no member that counts is returned untouched. Otherwise Simfinity reads the stored members
+   * (see `rawEmbeddedValue`), never calling a getter, and counts a stored `_id` as `id`; an error
+   * while reading them returns the object unchanged. Runtimes that share the type read through the
+   * same resolver, with or without the hook. On MongoDB, a create that writes an empty object for a
+   * required embedded member stores it as absent (Mongoose minimizes it), so an object that holds
+   * nothing else reads as null too, except in by-ID and reference reads and update responses where
+   * the member is a nested path, as generated models declare every embedded member except one named
+   * `type`.
    */
   readEmbeddedValue?(value: any): any;
+  /**
+   * Optional, used with `readEmbeddedValue`. Returns the stored data of a hydrated embedded value
+   * as a plain object, without running getters or virtuals, such as a document's raw data; returns
+   * any other value unchanged. Return a hydrated value unchanged when its stored data does not show
+   * what it renders, such as one whose schema supplies members through getters, virtuals, methods
+   * or aliases: a value that is not a plain object counts as data, so Simfinity keeps it as it is.
+   * Simfinity calls it on the embedded objects it checks for data, including those it finds inside
+   * the returned data, and reads only own data properties of the result; a null or undefined result
+   * has no members. Without it, a plain object is read as it is, an accessor property counts as
+   * present without being called, and a value that is not a plain object counts as data.
+   */
+  rawEmbeddedValue?(value: any): any;
   getById(model: Model, id: any, session?: Session | null, options?: { projection?: Record<string, number>; plain?: boolean; lock?: boolean; requiredId?: any; context?: any }): any;
   /** Optional batch read: the records found for `ids`, in getById shape and any order. After a failure, the runtime reads each ID with getById. */
   getByIds?(model: Model, ids: any[], options?: { context?: any }): any;
@@ -430,11 +472,19 @@ export interface AuthPluginOptions {
   debug?: boolean;
 }
 
-declare class UnauthenticatedError extends SimfinityError {
+/**
+ * Authentication error: code `UNAUTHENTICATED`, status 401, default message `Authentication required`.
+ * The same class as `auth.UnauthenticatedError` and the `/auth` and `/auth/errors` subpath exports.
+ */
+export class UnauthenticatedError extends SimfinityError {
   constructor(message?: string);
 }
 
-declare class ForbiddenError extends SimfinityError {
+/**
+ * Authorization error: code `FORBIDDEN`, status 403, default message `Access denied`.
+ * The same class as `auth.ForbiddenError` and the `/auth` and `/auth/errors` subpath exports.
+ */
+export class ForbiddenError extends SimfinityError {
   constructor(message?: string);
 }
 

package/types/plugins.d.ts

@@ -5,7 +5,9 @@
 import { plugins } from './index.js';
 
 export type { AuthPluginOptions, EnvelopSchemaPlugin, PermissionSchema } from './index.js';
-export const createAuthPlugin: typeof plugins.createAuthPlugin;
+// The /auth declaration itself, as the runtime re-exports that binding, so the two subpaths can be
+// re-exported together.
+export { createAuthPlugin } from './auth/index.js';
 export const apolloCountPlugin: typeof plugins.apolloCountPlugin;
 export const envelopCountPlugin: typeof plugins.envelopCountPlugin;