@fougere/schema 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/axis/shape/Shape.ts

@@ -6,7 +6,7 @@ type Nullably<T extends string> = T | readonly [T, 'null'];
 interface StringConstraints { minLength?: number; maxLength?: number; pattern?: string; enum?: readonly (string | null)[]; format?: StringFormat }
 interface NumericConstraints { minimum?: number; maximum?: number }
 interface ArrayConstraints { items?: Shape; minItems?: number; maxItems?: number }
-interface ObjectConstraints { properties?: Record<string, unknown>; required?: readonly string[] }
+interface ObjectConstraints { properties?: Record<string, unknown>; required?: readonly string[]; additionalProperties?: boolean | Shape; propertyNames?: Shape }
 
 export type Shape =
   | ({ type: Nullably<'string'> } & StringConstraints)
@@ -19,8 +19,8 @@ const SHAPE_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'
 
 function isShapeImpl(value: unknown): value is Shape {
   if (typeof value !== 'object' || value === null) return false;
-  const declared = (value as Shape).type;
-  const names = Array.isArray(declared) ? declared : [declared];
+  const type = (value as Shape).type;
+  const names = Array.isArray(type) ? type : [type];
   return (
     names.some((name) => (SHAPE_TYPES as readonly unknown[]).includes(name)) &&
     names.every((name) => name === 'null' || (SHAPE_TYPES as readonly unknown[]).includes(name))
@@ -36,19 +36,19 @@ type BaseShape =
 
 function nullableShapeImpl(shape: Shape): Shape {
   if (Array.isArray(shape.type)) return shape;
-  const out = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
-  if ('enum' in out && out.enum && !out.enum.includes(null)) {
-    (out as { enum: readonly (string | null)[] }).enum = [...out.enum, null];
+  const nullable = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
+  if ('enum' in nullable && nullable.enum && !nullable.enum.includes(null)) {
+    (nullable as { enum: readonly (string | null)[] }).enum = [...nullable.enum, null];
   }
-  return out;
+  return nullable;
 }
 
-interface ShapeAnatomy {
+interface ShapeParts {
   base?: BaseShape;
   nullable: boolean;
 }
 
-export class Anatomy {
+export class Shapes {
   static is(value: unknown): value is Shape {
     return isShapeImpl(value);
   }
@@ -57,26 +57,26 @@ export class Anatomy {
     return nullableShapeImpl(shape);
   }
 
-  private static readonly cache = new WeakMap<object, ShapeAnatomy>();
-  private static readonly none: ShapeAnatomy = { base: undefined, nullable: false };
+  private static readonly cache = new WeakMap<object, ShapeParts>();
+  private static readonly none: ShapeParts = { base: undefined, nullable: false };
 
-  static of(shape?: Shape): ShapeAnatomy {
+  static of(shape?: Shape): ShapeParts {
     if (!shape) return this.none;
-    let a = this.cache.get(shape);
-    if (!a) {
+    let parts = this.cache.get(shape);
+    if (!parts) {
       if (Array.isArray(shape.type)) {
         const baseType = shape.type.find((t) => t !== 'null');
         const base = { ...shape, type: baseType } as BaseShape;
         if ('enum' in base && base.enum) {
           (base as { enum: readonly (string | null)[] }).enum = base.enum.filter((v) => v !== null);
         }
-        a = { base, nullable: true };
+        parts = { base, nullable: true };
       } else {
-        a = { base: shape as BaseShape, nullable: false };
+        parts = { base: shape as BaseShape, nullable: false };
       }
-      this.cache.set(shape, a);
+      this.cache.set(shape, parts);
     }
-    return a;
+    return parts;
   }
 
   static isNullable(shape?: Shape): boolean {

package/src/entity/EntityAdapterSet.ts

@@ -0,0 +1,81 @@
+import type { Fields } from '../field/Field.js';
+import { isObject } from '../lib/utils.js';
+import type { EntityAdapters } from './EntityAdapters.js';
+
+type AdapterConfiguration = Record<string, unknown>;
+type AdapterConfigurations = Record<string, AdapterConfiguration>;
+
+export class EntityAdapterSet {
+  /**
+   * `{ sql: { body: { columnType: { pg: 'tsvector' } } } }`
+   */
+  private constructor(readonly adapters: EntityAdapters<Fields>) {}
+
+  /**
+   * Stops a malformed declaration from propagating, by checking its two levels.
+   * `of({ sql: { body: 3 } })` → passes; `of({ sql: 'oops' })` → throws, naming `adapters.sql`
+   */
+  static of(adapters?: EntityAdapters<Fields>): EntityAdapterSet {
+    if (!adapters) return new EntityAdapterSet({});
+
+    if (!isObject(adapters)) {
+      throw new Error(
+        `adapters: expected an object keyed by adapter name, got ${typeof adapters}.`,
+      );
+    }
+
+    for (const [adapter, fields] of Object.entries(adapters)) {
+      if (!isObject(fields)) {
+        throw new Error(
+          `adapters.${adapter}: expected an object keyed by field name, got ${typeof fields}. ` +
+            `What an adapter is handed is addressed by the field it applies to.`,
+        );
+      }
+    }
+
+    return new EntityAdapterSet(adapters);
+  }
+
+  /** Folds several into one, a later field entry replacing the earlier. Takes sets only, so */
+  static merged(adapterSets: readonly EntityAdapterSet[]): EntityAdapterSet {
+    const configurations: AdapterConfigurations = {};
+
+    for (const adapterSet of adapterSets)
+      for (const [adapter, configuration] of adapterSet.entries)
+        configurations[adapter] = { ...configurations[adapter], ...configuration };
+
+    return new EntityAdapterSet(configurations);
+  }
+
+  private get entries(): [string, AdapterConfiguration][] {
+    return Object.entries(this.adapters);
+  }
+
+  /** Collects every field addressed, so a declaration aimed at a missing field is caught. */
+  get fieldNames(): string[] {
+    return [
+      ...new Set(this.entries.flatMap(([, configuration]) => Object.keys(configuration))),
+    ];
+  }
+
+  /** Follows a derivation — `pick`, `omit` and `rename` are one gesture: what remains, and */
+  rename(transform: (key: string) => string | undefined): EntityAdapterSet {
+    const renamed: AdapterConfigurations = {};
+
+    for (const [adapter, configuration] of this.entries) {
+      const mapped: AdapterConfiguration = {};
+
+      for (const [key, entry] of Object.entries(configuration)) {
+        const newName = transform(key);
+
+        if (newName !== undefined) mapped[newName] = entry;
+      }
+
+      // Drop an adapter left with no field. `Post.pick('id')` would otherwise answer
+      // `{ sql: {} }` — a line the entity never wrote.
+      if (Object.keys(mapped).length) renamed[adapter] = mapped;
+    }
+
+    return new EntityAdapterSet(renamed);
+  }
+}

package/src/entity/EntityAdapters.ts

@@ -0,0 +1,8 @@
+import type { FieldName, Fields } from '../field/Field.js';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-empty-object-type
+export interface FougereEntityAdapters<K extends string> {}
+
+export type EntityAdapters<TFields extends Fields> = Readonly<
+  Partial<FougereEntityAdapters<FieldName<TFields>>>
+>;

package/src/entity/EntityDeclarations.ts

@@ -0,0 +1,16 @@
+import type { FieldName, Fields } from '../field/Field.js';
+import type { EntityAdapters } from './EntityAdapters.js';
+
+// Ex: [['title', 'name'], ['id']]
+export type CompositeUnique<TFields extends Fields> =
+  readonly (readonly FieldName<TFields>[])[];
+
+export type PreviousNames<TFields extends Fields> = Readonly<
+  Partial<Record<FieldName<TFields>, string>>
+>;
+
+export interface EntityDeclarations<TFields extends Fields> {
+  adapters?: EntityAdapters<TFields>;
+  previous?: PreviousNames<TFields>;
+  unique?: CompositeUnique<TFields>;
+}

package/src/entity.ts

@@ -1,7 +1,12 @@
-import { type Fields } from './fields/Field.js';
-import { type EntityDeclarations } from './EntityDeclarations.js';
-import { Schema, type SchemaConstructor } from './schema/Schema.js';
+import { type Fields } from './field/Field.js';
+import { type EntityDeclarations } from './entity/EntityDeclarations.js';
+import { Schema, type SchemaConstructor } from './Schema.js';
 
+/**
+ * So the whole framework starts from one call: fields, and what they say about themselves.
+ * FR : pour que tout parte d'un appel : les champs, et ce qu'ils disent d'eux-mêmes.
+ * `class Post extends entity({ id: primary(), title: text() }, { unique: [['title']] }) {}`
+ */
 export function entity<TFields extends Fields>(
   fields: TFields,
   declarations: EntityDeclarations<TFields> = {},

package/src/field/Field.ts

@@ -0,0 +1,61 @@
+import type { Shape } from '../axis/shape/Shape.js';
+import type { RoleRules } from '../axis/role/Role.js';
+import type { LifecycleRules } from '../axis/lifecycle/Lifecycle.js';
+import type { BoundaryRef } from '../axis/boundary/Boundary.js';
+import type { Meta } from '../axis/Meta.js';
+import type { Axis } from '../axis/Axis.js';
+import { FieldDeclarationValidator } from '../validator/FieldDeclarationValidator.js';
+import { FieldValueValidator } from '../validator/FieldValueValidator.js';
+
+export type Fields = Record<string, Field>;
+
+/** A key of a field set — the name a declaration addresses a field by. */
+export type FieldName<TFields extends Fields> = Extract<keyof TFields, string>;
+
+/** The carrier, the three extension axes, the annotation — the five the validator reads. */
+export type FieldDeclaration = Pick<Field, 'shape' | Axis['slot'] | 'meta'>;
+
+export class Field<T = unknown> {
+  readonly shape: Shape;
+  readonly role?: RoleRules;
+  readonly lifecycle?: LifecycleRules;
+  readonly boundary?: BoundaryRef;
+  readonly meta?: Meta;
+
+  declare readonly _type?: T;
+
+  constructor(init: FieldDeclaration, key?: string) {
+    const verdict = FieldDeclarationValidator.of(init).verdict;
+
+    if (!verdict.success) {
+      throw new Error(
+        `${key ? `Field '${key}': ` : ''}` +
+          verdict.errors.map((e) => `${e.path}: ${e.message}`).join('; '),
+      );
+    }
+
+    this.shape = init.shape;
+    this.role = init.role;
+    this.lifecycle = init.lifecycle;
+    this.boundary = init.boundary;
+    this.meta = init.meta;
+
+    const create = this.lifecycle?.create;
+    if (typeof create === 'object' && create !== null && 'value' in create) {
+      const checked = FieldValueValidator.of(this).validate(create.value);
+      if ('error' in checked)
+        throw new Error(
+          `${key ? `Field '${key}': ` : ''}the declared default ${JSON.stringify(create.value)} ` +
+            `is not a legal value for it — ${checked.error}.`,
+        );
+    }
+  }
+
+  static is(value: unknown): value is Field {
+    return FieldDeclarationValidator.of(value).verdict.success;
+  }
+
+  with<U = T>(overrides: Partial<FieldDeclaration>): Field<U> {
+    return new Field<U>({ ...this, ...overrides });
+  }
+}

package/src/field/FieldSet.ts

@@ -0,0 +1,75 @@
+import { Role } from '../axis/role/Role.js';
+import type { CompositeUnique } from '../entity/EntityDeclarations.js';
+import { Field, type FieldName, type Fields } from './Field.js';
+
+export class FieldSet<TFields extends Fields = Fields> {
+  private constructor(private readonly fields: TFields) {}
+
+  static of<TFields extends Fields>(fields: TFields): FieldSet<TFields> {
+    return new FieldSet(fields);
+  }
+
+  /**
+   * So a declared unique lands where it belongs: on the field, or on the schema.
+   * FR : pour qu'une unicité déclarée atterrisse sur le champ ou sur le schéma.
+   * `declaring(fields, [['email'], ['listId', 'docId']])`
+   * → `email` carries `role.unique`, the pair becomes a schema constraint
+   */
+  static declaring<TFields extends Fields>(
+    declared: TFields,
+    unique?: CompositeUnique<TFields>,
+  ): { fields: TFields; unique: CompositeUnique<TFields> | undefined } {
+    const fields: Fields = {};
+    for (const [key, field] of Object.entries(declared))
+      fields[key] = new Field(field, key);
+
+    const composite: string[][] = [];
+    for (const group of unique ?? []) {
+      const missing = group.filter((key) => !(key in fields));
+      if (missing.length)
+        throw new Error(
+          `unique: [${group.join(', ')}] names ` +
+            `${missing.map((key) => `'${key}'`).join(', ')}, which the entity does not declare.`,
+        );
+
+      if (group.length === 1) {
+        const key = group[0]!;
+        fields[key] = fields[key]!.with({ role: { ...fields[key]!.role, unique: true } });
+        continue;
+      }
+      composite.push([...group]);
+    }
+
+    return {
+      fields: fields as TFields,
+      unique: deduplicated(composite) as CompositeUnique<TFields> | undefined,
+    };
+  }
+
+  /** A second `primary` is refused, naming both, rather than the first winning silently. */
+  get primary(): FieldName<TFields> | undefined {
+    const primaries = Object.entries(this.fields)
+      .filter(([, field]) => Role.of(field).isPrimary)
+      .map(([name]) => name);
+
+    if (primaries.length > 1) {
+      throw new Error(
+        `FieldSet.primary: ${primaries.map((name) => JSON.stringify(name)).join(', ')} all declare ` +
+          '`primary`; a field set can have only one primary field.',
+      );
+    }
+
+    return primaries[0] as FieldName<TFields> | undefined;
+  }
+
+}
+
+/** The order is part of a group: `['a','b']` and `['b','a']` are two constraints. */
+export function deduplicated(
+  groups: readonly (readonly string[])[],
+): readonly (readonly string[])[] | undefined {
+  const seen = new Map<string, readonly string[]>();
+  for (const group of groups) seen.set(JSON.stringify(group), group);
+
+  return seen.size ? [...seen.values()] : undefined;
+}

package/src/index.ts

@@ -1,31 +1,39 @@
-export { Field, type Fields } from './fields/Field.js';
-export { FieldSet } from './fields/FieldSet.js';
-export { type Shape, Anatomy } from './axis/shape/Shape.js';
-export { type StringFormat, type FormatPredicate, Formats } from './axis/shape/Formats.js';
+export { Field, type Fields } from './field/Field.js';
+export { FieldSet } from './field/FieldSet.js';
+export { type Shape, Shapes } from './axis/shape/Shape.js';
+export {
+  type StringFormat,
+  type FormatPredicate,
+  Formats,
+} from './axis/shape/Formats.js';
 export { Role, type RoleRules } from './axis/role/Role.js';
 export { type Relation, type EntityConstructor } from './axis/role/Relation.js';
 export { Lifecycle, type LifecycleRules } from './axis/lifecycle/Lifecycle.js';
 export { type GeneratorRef, Generators } from './axis/lifecycle/Generators.js';
 export { Clock } from './axis/lifecycle/Clock.js';
-export { Boundary, type BoundaryRules, type BoundaryRef } from './axis/boundary/Boundary.js';
+export {
+  Boundary,
+  type BoundaryRules,
+  type BoundaryRef,
+} from './axis/boundary/Boundary.js';
 export { type Decoder, type Encoder, Boundaries } from './axis/boundary/Boundaries.js';
 export { type Meta } from './axis/Meta.js';
-export { FieldGroup } from './constraint/FieldGroup.js';
-export { Unique } from './constraint/Unique.js';
 
-export { Schema, ANONYMOUS_SCHEMA_NAME, type SchemaConstructor } from './schema/Schema.js';
-export { SchemaDerivation } from './schema/SchemaDerivation.js';
-export { isObject } from './judge/ValueForm.js';
-export { Cases, type Case } from './judge/Cases.js';
-export { RowRefusal } from './judge/RowRefusal.js';
-export { type SchemaView, type Row, type PartialRow } from './schema/SchemaView.js';
-export { type FougereEntityAdapters, type EntityAdapters } from './EntityAdapters.js';
+export { Schema, ANONYMOUS_SCHEMA_NAME, type SchemaConstructor } from './Schema.js';
+export { SchemaDerivation } from './SchemaDerivation.js';
+export { Cases, type ValidationCase } from './projection/Cases.js';
+export { InputRefusal } from './validator/InputRefusal.js';
+export { type SchemaView, type Values, type PartialValues } from './SchemaView.js';
+export {
+  type FougereEntityAdapters,
+  type EntityAdapters,
+} from './entity/EntityAdapters.js';
 export {
   type EntityDeclarations,
   type CompositeUnique,
   type PreviousNames,
-} from './EntityDeclarations.js';
-export { lowerFirst, upperFirst } from './utils.js';
+} from './entity/EntityDeclarations.js';
+export { lowerFirst, upperFirst, isObject } from './lib/utils.js';
 
 export { primary } from './vocabulary/primary.js';
 export { text } from './vocabulary/text.js';
@@ -51,19 +59,33 @@ export { json } from './vocabulary/json.js';
 
 export { applyCreate, applyUpdate } from './axis/lifecycle/apply.js';
 export { Visibility } from './projection/Visibility.js';
-export { Card } from './card/Card.js';
-export { Bundle } from './card/Bundle.js';
-export type { Change, Diff, DiffOptions, SetDiff, SetDiffOptions, RenameCandidate, TypeSet } from './card/diff.js';
-export { EntityTypeSource, type EntityTypeSourceOptions } from './card/EntityTypeSource.js';
-export { FacadeTypeSource, type FacadeTypeSourceOptions, type OpDescriptor } from './card/FacadeTypeSource.js';
-export { type SchemaBundle, type SchemaDescriptor, type FieldDescriptor, type FieldExtension, type RoleDescriptor, type RelationDescriptor } from './card/Descriptor.js';
-export { type SchemaOrCard, schemaOf, fieldsOf } from './projection/SchemaOrCard.js';
+export { Card } from './projection/card/Card.js';
+export { Bundle } from './projection/card/Bundle.js';
+export type {
+  Change,
+  Diff,
+  DiffOptions,
+  SetDiff,
+  SetDiffOptions,
+  RenameCandidate,
+  TypeSet,
+} from './projection/card/diff.js';
+export {
+  type SchemaBundle,
+  type SchemaDescriptor,
+  type FieldDescriptor,
+  type FieldExtension,
+  type RoleDescriptor,
+  type RelationDescriptor,
+} from './projection/card/Descriptor.js';
 export type { StandardSchemaV1 } from './projection/standard.js';
 
 export { entity } from './entity.js';
 
-export { FieldJudge } from './judge/FieldJudge.js';
-export { ValueJudge } from './judge/ValueJudge.js';
-export { RowJudge } from './judge/RowJudge.js';
-export { type ValidateOptions } from './judge/options.js';
-export { type ValidationError, type ValidationResult, type Checked } from './judge/result.js';
+export { FieldDeclarationValidator } from './validator/FieldDeclarationValidator.js';
+export { FieldValueValidator } from './validator/FieldValueValidator.js';
+export { InputValidator } from './validator/InputValidator.js';
+export { AdapterFieldValidator } from './validator/AdapterFieldValidator.js';
+export { Registry } from './lib/Registry.js';
+export { type ValidateOptions } from './validator/InputValidator.js';
+export { type ValidationError, type ValidationResult, type Checked } from './validation.js';

package/src/lib/Registry.ts

@@ -0,0 +1,37 @@
+export class Registry<T> {
+  private readonly entries: Map<string, T>;
+
+  /** `Unknown boundary decoder 'celsius' — call Boundaries.decoders.register(name, fn).` */
+  constructor(
+    private readonly label: string,
+    private readonly hint?: string,
+    builtins?: Iterable<readonly [string, T]>,
+  ) {
+    this.entries = new Map(builtins);
+  }
+
+  register(name: string, value: T): T {
+    this.entries.set(name, value);
+
+    return value;
+  }
+
+  find(name: string): T | undefined {
+    return this.entries.get(name);
+  }
+
+  resolve(name: string, path?: string): T {
+    const found = this.find(name);
+
+    if (found !== undefined) return found;
+
+    throw new Error(
+      `${path ? `${path}: ` : ''}Unknown ${this.label} '${name}'${this.hint ? ` — ${this.hint}` : ''}. ` +
+        `This process answers ${this.names.join(', ') || 'nothing yet'}.`,
+    );
+  }
+
+  private get names(): string[] {
+    return [...this.entries.keys()];
+  }
+}

package/src/{utils.ts → lib/utils.ts}

@@ -11,3 +11,6 @@ export function clean<T extends Record<string, unknown>>(obj: T): T {
 
   return obj;
 }
+
+export const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);

package/src/projection/Cases.ts

@@ -0,0 +1,176 @@
+import { Shapes } from '../axis/shape/Shape.js';
+import { Boundary } from '../axis/boundary/Boundary.js';
+import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
+import { Role } from '../axis/role/Role.js';
+import type { Field } from '../field/Field.js';
+import type { SchemaView } from '../SchemaView.js';
+import { InputValidator } from '../validator/InputValidator.js';
+import { InputRefusal } from '../validator/InputRefusal.js';
+
+/**
+ * One input, and what the validator must answer.
+ *
+ * `expect` carries the PATH of the field at fault and never the message. We know which
+ * field must be refused because we are the ones who broke it; naming the message would
+ * make this list a second validator, and the two would then have to be kept in step by hand —
+ * which is the duplication the whole thing exists to remove.
+ */
+export interface ValidationCase {
+  /** What this input does, in one clause — carried into the assertion so a failure reads. */
+  why: string;
+  input: unknown;
+  /** Judged as an update rather than a creation. */
+  patch: boolean;
+  expect: 'accept' | { reject: string };
+}
+
+/**
+ * So every field has at least one case, whatever else it declares.
+ * FR : pour que chaque champ ait un cas, quoi qu'il déclare par ailleurs.
+ * `text()` → `42`; `number()` → `'not-a-value-of-this-shape'`
+ */
+function wrongTypeFor(field: Field): unknown {
+  const declared = (field.shape as { type?: string | readonly string[] }).type;
+  const names = Array.isArray(declared) ? declared : [declared];
+  return names.includes('string') ? 42 : 'not-a-value-of-this-shape';
+}
+
+/**
+ * So a bound stated in a shape produces the case that breaks it, and none is invented.
+ * FR : pour qu'une borne énoncée produise le cas qui la casse, et aucun autre.
+ * `text({ maxLength: 3 })` → one case with `'xxxx'`; `text()` → no case
+ */
+function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
+  // Through `Shapes`, not a cast: the cast admitted any keyword, and it declared
+  // `maxItems` — which no branch below ever produced. In the one function whose job is
+  // to be exhaustive, a bound the type does not carry is a case nobody notices missing.
+  const shape = Shapes.of(field.shape).base;
+  const cases: { why: string; value: unknown }[] = [];
+  if (shape?.type === 'string') {
+    if (typeof shape.minLength === 'number' && shape.minLength > 0)
+      cases.push({ why: 'shorter than min', value: 'x'.repeat(shape.minLength - 1) });
+    if (typeof shape.maxLength === 'number')
+      cases.push({ why: 'longer than max', value: 'x'.repeat(shape.maxLength + 1) });
+    if (shape.enum) cases.push({ why: 'outside the stated set', value: '__not-in-enum__' });
+  }
+  if (shape?.type === 'number' || shape?.type === 'integer') {
+    if (typeof shape.minimum === 'number')
+      cases.push({ why: 'below minimum', value: shape.minimum - 1 });
+    if (typeof shape.maximum === 'number')
+      cases.push({ why: 'above maximum', value: shape.maximum + 1 });
+  }
+  if (shape?.type === 'array') {
+    if (typeof shape.minItems === 'number' && shape.minItems > 0)
+      cases.push({ why: 'fewer items than min', value: [] });
+    if (typeof shape.maxItems === 'number')
+      cases.push({
+        why: 'more items than max',
+        value: Array.from({ length: shape.maxItems + 1 }, () => null),
+      });
+  }
+  return cases;
+}
+
+/**
+ * The decision table, enumerated on the entity's own fields.
+ *
+ * Use the complete entity so a derived view cannot hide a divergent field. The caller
+ * supplies a valid row; generating data belongs to the testing package.
+ */
+export class Cases {
+  private constructor(readonly all: readonly ValidationCase[]) {}
+
+  static of(entity: SchemaView, valid: Record<string, unknown>): Cases {
+    return new Cases(enumerate(entity, valid));
+  }
+
+  static holds(
+    expected: ValidationCase['expect'],
+    result: { success: boolean; errors?: { path: string }[] },
+  ): boolean {
+    if (expected === 'accept') return result.success;
+    if (result.success) return false;
+    return (result.errors ?? []).some((error) => error.path === expected.reject);
+  }
+
+  static get refusals(): string[] {
+    return Object.values(InputRefusal);
+  }
+
+  [Symbol.iterator](): Iterator<ValidationCase> {
+    return this.all[Symbol.iterator]();
+  }
+}
+
+/**
+ * So the four axes decide which cases exist, and no list of them is maintained by hand.
+ * FR : pour que les axes décident des cas, sans liste tenue à la main.
+ */
+function enumerate(entity: SchemaView, valid: Record<string, unknown>): ValidationCase[] {
+  const fields = entity.getFields();
+  const validator = InputValidator.of(fields);
+  const cases: ValidationCase[] = [];
+  const withField = (name: string, value: unknown) => ({ ...valid, [name]: value });
+
+  cases.push({ why: 'a valid input', input: valid, patch: false, expect: 'accept' });
+  cases.push({
+    why: 'a key outside the contract',
+    input: { ...valid, __unknown__: 'x' },
+    patch: false,
+    expect: { reject: '__unknown__' },
+  });
+  cases.push({
+    why: 'not an object at all',
+    input: 'a string',
+    patch: false,
+    expect: { reject: '.' },
+  });
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    // A reference names a row that must exist; the caller supplied its id and we do not
+    // get to invent a second one, so the only case we can state about it is the bound one.
+    const isRef = Role.of(field).isReference;
+
+    if (validator.onAbsent(field) === null && name in valid) {
+      const input = { ...valid };
+      delete input[name];
+      cases.push({ why: `${name} absent`, input, patch: false, expect: { reject: name } });
+    }
+
+    if (Boundary.of(field).readOnly) {
+      cases.push({
+        why: `${name} supplied although read-only`,
+        input: withField(name, wrongTypeFor(field)),
+        patch: false,
+        expect: { reject: name },
+      });
+    }
+
+    if (Lifecycle.of(field).immutable && !Role.of(field).isPrimary) {
+      cases.push({
+        why: `${name} supplied on an update`,
+        input: { [name]: valid[name] ?? wrongTypeFor(field) },
+        patch: true,
+        expect: { reject: name },
+      });
+    }
+
+    if (name in valid && !isRef) {
+      cases.push({
+        why: `${name} of the wrong type`,
+        input: withField(name, wrongTypeFor(field)),
+        patch: false,
+        expect: { reject: name },
+      });
+      for (const { why, value } of outOfBoundsFor(field))
+        cases.push({
+          why: `${name} ${why}`,
+          input: withField(name, value),
+          patch: false,
+          expect: { reject: name },
+        });
+    }
+  }
+
+  return cases;
+}