@fougere/core 0.12.4-alpha.0 → 0.12.5-alpha.0

package/src/boot/bootstrap.ts

@@ -568,16 +568,26 @@ function markLineCarriers(emissions: Emissions): void {
  * declares `product`.
  */
 function answerRemotes(
-  { container, routeRegistry, dispatcher, getMiddlewares }: Pick<Assembly, 'container' | 'routeRegistry' | 'dispatcher' | 'getMiddlewares'>,
+  { container, routeRegistry, dispatcher, getMiddlewares, options, state }: Pick<Assembly, 'container' | 'routeRegistry' | 'dispatcher' | 'getMiddlewares' | 'options' | 'state'>,
   remoteRouter: RemoteRouter,
+  fronds: Fronds,
 ): void {
-  container.setFallback((name) => (isFacadeKey(name) ? facadeOperations(dispatcher, addressOf(name)) : undefined));
+  // Only for what another process may serve: an entity a frond hosts HERE and gives no handler
+  // is served by nobody, and a stand-in for it had GraphQL project an entity with no operation.
+  const servedElsewhere = (address: string): boolean => {
+    const owner = fronds.owner(address);
+
+    return owner === undefined || owner.name in (options.remotes ?? {});
+  };
+  container.setFallback((name) => (isFacadeKey(name) && servedElsewhere(addressOf(name))
+    ? facadeOperations(dispatcher, addressOf(name))
+    : undefined));
 
   const remoteFacades = new Map<string, Record<string, Function>>();
   routeRegistry.addResolver(remoteRoutes((entity) => {
     const known = remoteFacades.get(entity);
     if (known) return known;
-    const facade = createRemoteFacade(entity, remoteRouter, getMiddlewares);
+    const facade = createRemoteFacade(entity, remoteRouter, getMiddlewares, state);
     remoteFacades.set(entity, facade);
 
     return facade;
@@ -650,6 +660,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     log.debug('builtins registered (Logger, Config)');
 
     const { fronds, operationModel } = await readFronds(options, log);
+    appLifecycle.add(...frondExtensions(fronds));
     const remoteRouter = remoteRouterOf(options);
     const { inflight, routeRegistry, dispatchLifecycle, dispatcher, localDispatcher, getMiddlewares, use } =
       dispatching(options, log, fronds, () => journalOf());
@@ -672,6 +683,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       container, routeRegistry, emissions, dispatcher, localDispatcher, effectiveByKey,
       boundPorts, refused, relations, hosting, operationModel, entityByName, frondOf, contractsOf,
       getMiddlewares, use, middlewaresOf: new Map(), seamsOf: new Map(), log, options,
+      state: appLifecycle.state(),
     };
     for (const frond of fronds) await installFrond(frond, assembly);
 
@@ -685,7 +697,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     refuseWhatDoesNotHold(refused);
     markLineCarriers(emissions);
 
-    if (remoteRouter) answerRemotes(assembly, remoteRouter);
+    if (remoteRouter) answerRemotes(assembly, remoteRouter, fronds);
 
     const { resolve, schemaFor, facadeFor, operationsFor, presenterFor } = readings({
       container, fronds, remoteRouter, localDispatcher, routeRegistry, effectiveByKey, log,
@@ -725,7 +737,6 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     serveCoreRpc(app, hosting, storageFor);
 
     built = app;
-    appLifecycle.add(...frondExtensions(fronds));
     await appLifecycle.up(app);
     stopAnnouncing = announceLines(emissions, container, carry);
 

package/src/boot/install.ts

@@ -1,5 +1,6 @@
 /** Putting one frond into the app being built: its scope, what it serves, what it takes. */
 import type { Container } from '@fougere/container';
+import type { StateShape } from '../wire/StateShape.js';
 import type { ProviderEntry } from '../descriptor/ProviderEntry.js';
 import type { PresenterEntry } from '../descriptor/PresenterEntry.js';
 import { lowerFirst, type Fields, type SchemaView } from '@fougere/schema';
@@ -85,6 +86,8 @@ export interface Assembly {
   seamsOf: Map<string, Map<string, ProviderEntry[]>>;
   log: Logger;
   options: CreateAppOptions;
+  /** What a call's `state` may hold, read off every extension this process mounts. */
+  state: StateShape;
 }
 
 /**
@@ -424,6 +427,7 @@ function buildFacadeInto(
     presenter: presenterMap.get(handler.address),
     presenterScope: scope,
     middlewares: () => getMiddlewares(handler.address),
+    state: assembly.state,
   });
 
   // Emissions use the same contracts and execution path as direct calls, and the terms sit

package/src/boot/nesting.ts

@@ -6,6 +6,7 @@
  * Documented: [fronds](https://fougere.dev/docs/infra/fronds).
  */
 import type { Diagnostic } from '../diagnostic.js';
+import { isFrondDescriptor } from '../descriptor/FrondDescriptor.js';
 import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
 import { Fronds } from '../descriptor/Fronds.js';
 import { statesModule, type FrondsStated } from '../FrondsStated.js';
@@ -102,7 +103,7 @@ export function nestingOf(
     if (frond === undefined) continue;
 
     const placed = stated[parent];
-    const address = typeof placed === 'string' ? placed : placed?.remote;
+    const address = typeof placed === 'string' ? placed : isFrondDescriptor(placed) ? undefined : placed?.remote;
     if (address !== undefined || (remotes && parent in remotes)) {
       refused.push({
         severity: 'blocking',

package/src/boot/remote.ts

@@ -4,6 +4,7 @@
  * Documented: [the gradient](https://fougere.dev/docs/infra/gradient).
  */
 import type { FrondCall } from '../wire/FrondCall.js';
+import type { StateShape } from '../wire/StateShape.js';
 import type { Transport } from '../wire/Transport.js';
 import { RPC_ENTITY } from '../wire/RpcAnswer.js';
 import { assertIdentityCard } from '../wire/card/IdentityCard.js';
@@ -103,15 +104,19 @@ export function createRemoteFacade(
   entity: string,
   router: RemoteRouter,
   middlewaresFor: (address: string) => AppMiddleware[],
+  shape: StateShape,
 ): Facade {
-  const opFn = (op: string) => async (invocation: InvocationContext = Invocation.empty) => {
+  const opFn = (op: string) => async (received: InvocationContext = Invocation.empty) => {
     const { frond, transport, schema } = await router.route(entity);
     const call: FrondCall = { frond, entity, op };
+    const state = received.crossed ? { ...received.state } : shape.judge(received.state, entity, op);
+    const invocation = { ...received, state };
+    const entered = { ...state };
     const ctx: OperationContext = {
-      entity, frond, operation: op, args: [], state: invocation.state, invocation,
+      entity, frond, operation: op, args: [], state, invocation,
     };
     const answer = await runMiddlewares(middlewaresFor(entity), ctx, () =>
-      transport(call, ctx.invocation ?? invocation));
+      transport(call, { ...(ctx.invocation ?? invocation), state: shape.judge(ctx.state, entity, op, entered) }));
 
     // The schema the card carried, put to work: a row crosses as data and comes back through
     // the same codecs a local facade applies, so a placement does not decide what a caller

package/src/boot/seed.ts

@@ -1,5 +1,5 @@
+import { pageOf } from '../wire/Page.js';
 import { Role } from '@fougere/schema';
-import { facadeKeyOf } from '../wire/Facade.js';
 import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
 import type { SeedEntry } from '../descriptor/SeedEntry.js';
 import type { SeedFactory } from '../descriptor/SeedFactory.js';
@@ -64,14 +64,9 @@ function whatEachWaitsFor(
   }));
 }
 
-/** Where a seed writes, and what it may skip — resolved per entity. */
-interface SeedFacade {
-  list(): Promise<unknown[]>;
-  write(item: Record<string, unknown>): Promise<unknown>;
-}
-
 /**
- * Plant a set of seeds, in the order given.
+ * Plant a set of seeds, in the order given — by the storage, as a handler writes: a seed is the
+ * frond's own code, not a client.
  *
  * Documented: [seeds](https://fougere.dev/docs/business/seeds).
  */
@@ -81,26 +76,26 @@ export async function runSeeds(
   report: (message: string) => void = () => {},
 ): Promise<void> {
   for (const seed of seeds) {
-    const resolve = <T>(name: string) => app.resolve<T>(name + 'Handler');
-    const data = typeof seed.data === 'function' ? await (seed.data as SeedFactory)(resolve) : seed.data;
-
-    const facade = facadeFor(app, seed.entityName);
-    if (!facade) {
-      report(`  ${seed.entityName}: no handler façade nor storage — skipping seed`);
+    const storage = app.storageFor(seed.entityName);
+    if (!storage) {
+      report(`  ${seed.entityName}: no storage in this process — skipping seed`);
       continue;
     }
 
-    const existing = await facade.list();
+    const existing = pageOf(await storage.list()).items;
     if (existing.length > 0) {
       report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
       continue;
     }
 
+    const resolve = <T>(name: string) => app.resolve<T>(name + 'Handler');
+    const data = typeof seed.data === 'function' ? await (seed.data as SeedFactory)(resolve) : seed.data;
+
     // The driver's error alone names neither the entity nor the row — and a foreign
     // key is exactly what a seed gets wrong.
     for (const item of data) {
       try {
-        await facade.write(item);
+        await storage.create(item);
       } catch (cause) {
         throw new Error(
           `Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${(cause as Error)?.message ?? cause}`,
@@ -112,26 +107,6 @@ export async function runSeeds(
   }
 }
 
-/** A seed is not a client. */
-function facadeFor(app: App, entityName: string): SeedFacade | undefined {
-  let handler: Record<string, Function> | undefined;
-  try { handler = app.resolve<Record<string, Function>>(facadeKeyOf(entityName)); } catch {}
-
-  const list = handler?.list;
-  const create = handler?.create;
-  if (typeof list === 'function' && typeof create === 'function') {
-    return {
-      list: () => list.call(handler) as Promise<unknown[]>,
-      write: (item) => create.call(handler, { params: {}, query: {}, input: item, state: {} }),
-    };
-  }
-
-  const storage = app.storageFor(entityName);
-  if (!storage) return undefined;
-
-  return { list: () => storage.list(), write: (item) => storage.create(item) };
-}
-
 /**
  * The framework's own ascent for rows, named — so a host can REPLACE it rather than take over the
  * whole post-boot to get its own.

package/src/descriptor/ExtensionEntry.ts

@@ -1,3 +1,5 @@
+import type { Field } from '@fougere/schema';
+
 /**
  * An extension this frond declares — what rises and falls with the process, written beside the
  * code it instruments.
@@ -10,6 +12,19 @@ export interface ExtensionEntry {
   /** Its own `name`, or the file's — the ascent REPLACES a name already declared. */
   name: string;
   /** The value handed to the ascent, the same shape `CreateAppOptions.extensions` takes. */
-  extension: { name?: string; up?: (app: never) => void | Promise<void>; down?: (app: never) => void | Promise<void> };
+  extension: {
+    name?: string;
+    state?: Readonly<Record<string, Field>>;
+    up?: (app: never) => void | Promise<void>;
+    down?: (app: never) => void | Promise<void>;
+  };
   filePath: string;
 }
+
+/** Recognized by its FORM: a value stating `up`, `down`, or the `state` members it declares. */
+export function isExtension(value: unknown): value is ExtensionEntry['extension'] {
+  const shape = value as { up?: unknown; down?: unknown; state?: unknown } | null;
+
+  return typeof shape?.up === 'function' || typeof shape?.down === 'function'
+    || (typeof shape?.state === 'object' && shape.state !== null);
+}

package/src/descriptor/FrondDescriptor.ts

@@ -63,3 +63,10 @@ export interface FrondDescriptor {
     rest?: { method?: string; path?: string; status?: number };
   }>;
 }
+
+/** Recognized by its FORM, like everything a config holds: a name and the lists every frond carries. */
+export function isFrondDescriptor(value: unknown): value is FrondDescriptor {
+  const shape = value as Partial<Record<keyof FrondDescriptor, unknown>> | null;
+
+  return typeof shape?.name === 'string' && Array.isArray(shape.entities) && Array.isArray(shape.handlers);
+}

package/src/dispatch/ArgumentResolver.ts

@@ -1,6 +1,7 @@
 import type { InvocationContext } from '../wire/InvocationContext.js';
 import type { BindingPlan } from '../wire/binding.js';
 import type { CollectorLookup } from './CollectorLookup.js';
+import { collectedAs } from '../prefab/collector.js';
 
 /** Resolves an operation's declared binding plan against one invocation. */
 export class ArgumentResolver {
@@ -13,7 +14,7 @@ export class ArgumentResolver {
       switch (binding.source.kind) {
         case 'collector': {
           const collector = this.collectors?.(binding.source.typeName);
-          args.push(collector ? await collector.collect(ctx) : undefined);
+          args.push(collector ? collectedAs(collector, await collector.collect(ctx)) : undefined);
           break;
         }
         case 'context': {

package/src/dispatch/Facade.ts

@@ -3,6 +3,7 @@ import { type AppMiddleware } from '../wire/AppMiddleware.js';
 import type { EffectiveOperationsMap } from '../EffectiveOperationsMap.js';
 import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
 import type { PresenterEntry } from '../descriptor/PresenterEntry.js';
+import type { StateShape } from '../wire/StateShape.js';
 
 /** What boot resolved around one handler, beyond the handler and the scope it resolves in. */
 export interface Facade {
@@ -22,4 +23,6 @@ export interface Facade {
   presenterScope: Container;
   /** The middlewares that apply to this address, read at call time and never at boot. */
   middlewares: () => AppMiddleware[];
+  /** What a call's `state` may hold in this process. */
+  state: StateShape;
 }

package/src/dispatch/HandlerFacade.ts

@@ -88,7 +88,10 @@ export class HandlerFacade {
       );
     }
 
-    const invocation = Invocation.from(input);
+    const received = Invocation.from(input);
+    const state = received.crossed ? { ...received.state } : this.facade.state.judge(received.state, entity, op);
+    const invocation = received.withState(state);
+    const entered = { ...state };
     const context: OperationContext = {
       entity,
       frond: this.facade.frond,
@@ -98,7 +101,7 @@ export class HandlerFacade {
       invocation,
     };
 
-    return runMiddlewares(this.facade.middlewares(), context, () => this.answer(op, contract, context, invocation));
+    return runMiddlewares(this.facade.middlewares(), context, () => this.answer(op, contract, context, invocation, entered));
   }
 
   /**
@@ -110,8 +113,10 @@ export class HandlerFacade {
     contract: OperationContract,
     context: OperationContext,
     invocation: Invocation,
+    entered: Record<string, unknown>,
   ): Promise<unknown> {
-    const validated = validateInput(contract.input, invocation, this.handler.address, op);
+    const state = this.facade.state.judge(context.state, this.handler.address, op, entered);
+    const validated = validateInput(contract.input, { ...invocation, state }, this.handler.address, op);
     context.invocation = validated;
 
     const args = contract.binding ? await this.arguments.resolve(contract.binding, validated) : [];

package/src/prefab/collector.ts

@@ -4,7 +4,9 @@
  * Documented: [collectors](https://fougere.dev/docs/business/collectors).
  */
 
-import { upperFirst } from '@fougere/schema';
+import { FieldValueValidator, dotted, json, upperFirst, type Field, type SchemaView } from '@fougere/schema';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 
 export function Collector<T extends abstract new (...args: any[]) => any>(target: T) {
   class CollectorBase {
@@ -18,3 +20,29 @@ export function Collector<T extends abstract new (...args: any[]) => any>(target
 export function collectorKeyOf(type: string): string {
   return `${upperFirst(type)}Collector`;
 }
+
+const readers = new WeakMap<object, Field>();
+
+/**
+ * What a collector answered, read by the entity it names — judged and rebuilt, so a `User` that
+ * crossed a process as JSON reaches the handler with its dates. A collector naming no entity
+ * answers what it built.
+ */
+export function collectedAs(collector: object, value: unknown): unknown {
+  const target = (collector.constructor as { __entity?: Partial<SchemaView> }).__entity;
+  if (value === null || value === undefined || typeof target?.getFields !== 'function') return value;
+
+  let reader = readers.get(target);
+  if (!reader) {
+    reader = json(target as SchemaView & (new () => unknown));
+    readers.set(target, reader);
+  }
+
+  const verdict = FieldValueValidator.of(reader).parse(value);
+  if ('value' in verdict) return verdict.value;
+
+  throw new FougereError({
+    code: ErrorCode.VALIDATION_FAILED,
+    message: `${collector.constructor.name}: ${verdict.path?.length ? `${dotted(verdict.path)}: ` : ''}${verdict.message}`,
+  });
+}

package/src/storage/Storage.ts

@@ -2,15 +2,21 @@ import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { ListOptions } from './ListOptions.js';
 import type { ListResult } from './ListResult.js';
 import type { SelectOption } from './SelectOption.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 
-/** The keys `list()` answers to. */
-const LIST_OPTION_KEYS = [
-  'limit', 'offset', 'page', 'after', 'orderBy', 'order', 'count', 'where', 'select',
-] as const;
+/** The keys `list()` answers to, checked against `ListOptions` so neither can drift. */
+const LIST_OPTION_KEYS = Object.keys({
+  limit: true, offset: true, page: true, after: true, orderBy: true, order: true, count: true, where: true, select: true,
+} satisfies Record<keyof (ListOptions & SelectOption), true>);
+
+/** What a count must be — a text that did not read as a number arrives as `NaN`. */
+const COUNTS = ['limit', 'offset', 'page'] as const;
 
 /**
- * Refuse an option the port does not answer to, and an order by a field the entity does not
- * declare — an unhonoured `orderBy` returns the page in whatever order the engine chose.
+ * Refuse an option the port does not answer to, a count that is not one, and an order by a
+ * field the entity does not declare — an unhonoured `orderBy` returns the page in whatever order
+ * the engine chose. Refused as BAD_REQUEST: a plain Error left as INTERNAL_ERROR, its message hidden.
  */
 export function assertListOptions(
   options: object | undefined,
@@ -18,21 +24,29 @@ export function assertListOptions(
   declared: readonly string[],
 ): void {
   if (!options) return;
-  const legal = new Set<string>(LIST_OPTION_KEYS);
-  const strangers = Object.keys(options).filter((key) => !legal.has(key));
+  const strangers = Object.keys(options).filter((key) => !LIST_OPTION_KEYS.includes(key));
   if (strangers.length > 0) {
-    throw new Error(
+    refuse(
       `${entity}.list(): unknown option ${strangers.map((s) => `\`${s}\``).join(', ')}. ` +
       `Known options are ${LIST_OPTION_KEYS.join(', ')} — to filter, pass \`where: { ${strangers[0]}: … }\`.`,
     );
   }
 
+  for (const count of COUNTS) {
+    const value = (options as ListOptions)[count];
+    if (value !== undefined && !(Number.isInteger(value) && value >= 0)) {
+      refuse(`${entity}.list(): \`${count}\` is ${typeof value === 'number' ? value : JSON.stringify(value)}, not a whole number.`);
+    }
+  }
+
   const { orderBy } = options as ListOptions;
   if (orderBy === undefined || declared.includes(orderBy)) return;
 
-  throw new Error(
-    `${entity}.list(): unknown orderBy \`${orderBy}\`. ${entity} declares ${declared.join(', ')}.`,
-  );
+  refuse(`${entity}.list(): unknown orderBy \`${orderBy}\`. ${entity} declares ${declared.join(', ')}.`);
+}
+
+function refuse(message: string): never {
+  throw new FougereError({ code: ErrorCode.BAD_REQUEST, message });
 }
 
 /** Per-entity storage — scoped CRUD operations on a single entity type. */

package/src/storage/Store.ts

@@ -1,6 +1,8 @@
 import { applyCreate, applyUpdate, Role, type SchemaView } from '@fougere/schema';
 import { comparisonOf, comparisonsIn, type Comparison } from './Comparison.js';
 import type { Storage } from './Storage.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 import type { StorageFactory } from './StorageFactory.js';
 import type { Values } from './Values.js';
 import type { ListResult } from './ListResult.js';
@@ -128,7 +130,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
           // constraint violation, and a store that loses data silently is worse than one
           // that fails.
           if (await store.has(keyOf(id))) {
-            throw new Error(`${name}.create: '${pk}' ${JSON.stringify(id)} already exists.`);
+            throw new FougereError({ code: ErrorCode.CONFLICT, message: `${name}.create: '${pk}' ${JSON.stringify(id)} already exists.` });
           }
           await store.set(keyOf(id), values);
 
@@ -136,7 +138,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
         },
         async update(id: string, input: Partial<Record<string, unknown>>) {
           const existing = await store.get(keyOf(id));
-          if (!existing) throw new Error(`Not found: ${id}`);
+          if (!existing) throw new FougereError({ code: ErrorCode.NOT_FOUND, message: `No row in ${name} for ${JSON.stringify(id)}.` });
           const updated = { ...existing, ...applyUpdate(fields, input), [pk]: existing[pk] };
           await store.set(keyOf(id), updated);
 

package/src/wire/Invocation.ts

@@ -36,8 +36,9 @@ export class Invocation implements InvocationContext {
   readonly identity?: string;
   readonly caller?: string;
   readonly runAt?: number;
+  readonly crossed?: true;
 
-  /** Gives every entry and every transport the same eight-member value, frozen. */
+  /** Gives every entry and every transport the same nine-member value, frozen. */
   private constructor(context: PartialInvocation) {
     this.params = canonicalRecord(context.params);
     this.query = canonicalRecord(context.query);
@@ -49,6 +50,7 @@ export class Invocation implements InvocationContext {
     if (context.identity !== undefined) this.identity = context.identity;
     if (context.caller !== undefined) this.caller = context.caller;
     if (context.runAt !== undefined) this.runAt = context.runAt;
+    if (context.crossed) this.crossed = true;
     Object.freeze(this);
   }
 

package/src/wire/InvocationContext.ts

@@ -8,4 +8,6 @@ export interface InvocationContext {
   caller?: string;
   /** Epoch milliseconds before which this call is not to run. */
   runAt?: number;
+  /** Written by the receiver of a call from another process, whose state was judged where it entered. */
+  crossed?: true;
 }

package/src/wire/StateShape.ts

@@ -0,0 +1,76 @@
+import { InputValidator, dotted, optional, type Field, type Fields } from '@fougere/schema';
+import { ErrorCode } from './ErrorCode.js';
+import { FougereError } from './FougereError.js';
+
+/** An extension and the members it puts on a call's `state`. */
+export interface StateDeclaration {
+  name: string;
+  state?: Readonly<Record<string, Field>>;
+}
+
+/**
+ * What a call's `state` may hold in this process: the members its extensions declare, each one
+ * absent until a host fills it. Judged at the facade, so a member arriving over the wire is
+ * rebuilt by its field exactly as it would have been handed over in-process.
+ *
+ * Documented: [collectors](https://fougere.dev/docs/business/collectors).
+ */
+export class StateShape {
+  static readonly empty = new StateShape({});
+
+  private readonly validator: InputValidator;
+
+  private constructor(private readonly fields: Fields) {
+    this.validator = InputValidator.of(fields);
+  }
+
+  /** Two extensions declaring one member refuse: the field that judges it would depend on wiring order. */
+  static of(declarations: readonly StateDeclaration[]): StateShape {
+    const fields: Fields = {};
+    const owners = new Map<string, string>();
+    for (const { name, state } of declarations) {
+      for (const [member, field] of Object.entries(state ?? {})) {
+        const owner = owners.get(member);
+        if (owner) {
+          throw new Error(
+            `[state] '${member}' is declared by two extensions, '${owner}' and '${name}'.\n`
+            + '  A member has one owner — keep one of them out of `extensions:`.',
+          );
+        }
+        owners.set(member, name);
+        fields[member] = optional(field);
+      }
+    }
+
+    return new StateShape(fields);
+  }
+
+  /**
+   * The members written since `entered` rebuilt by their fields, or a refusal naming the member
+   * and what this process declares. What `entered` already held was judged where it entered.
+   */
+  judge(
+    state: Record<string, unknown>,
+    entity: string,
+    operation: string,
+    entered: Record<string, unknown> = {},
+  ): Record<string, unknown> {
+    const written = Object.fromEntries(Object.entries(state).filter(([member, value]) => entered[member] !== value));
+    if (Object.keys(written).length === 0) return state;
+
+    const result = this.validator.validate(written);
+    if (result.success) return { ...state, ...result.data };
+
+    const declared = Object.keys(this.fields);
+    const errors = result.errors.map((error) => ({ ...error, path: ['state', ...error.path] }));
+
+    throw new FougereError({
+      code: ErrorCode.VALIDATION_FAILED,
+      message: errors.map((error) => `${dotted(error.path)}: ${error.message}`).join(', ')
+        + (declared.length ? ` — this process declares ${declared.join(', ')}` : ' — this process declares no state member'),
+      details: errors,
+      entity,
+      operation,
+    });
+  }
+}