@fougere/schema 0.12.1-alpha.0 → 0.12.2-alpha.0

package/src/axis/shape/Shape.ts

@@ -4,27 +4,58 @@ import type { ShapeType } from './ShapeType.js';
 
 type Nullably<T extends string> = T | readonly [T, 'null'];
 
-interface StringConstraints { minLength?: number; maxLength?: number; pattern?: string; enum?: readonly (string | null)[]; format?: StringFormat }
+/** The sentence a field carries, where JSON Schema already holds one. */
+interface Documented {
+  description?: string;
+}
+
+interface StringConstraints extends Documented {
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  enum?: readonly (string | null)[];
+  format?: StringFormat;
+}
 
-interface NumericConstraints { minimum?: number; maximum?: number }
+interface NumericConstraints extends Documented {
+  minimum?: number;
+  maximum?: number;
+  enum?: readonly (number | null)[];
+}
 
-interface ArrayConstraints { items?: Shape; minItems?: number; maxItems?: number }
+interface ArrayConstraints extends Documented {
+  items?: Shape;
+  minItems?: number;
+  maxItems?: number;
+}
 
-interface ObjectConstraints { properties?: Record<string, unknown>; required?: readonly string[]; additionalProperties?: boolean | Shape; propertyNames?: Shape }
+interface ObjectConstraints extends Documented {
+  properties?: Record<string, unknown>;
+  required?: readonly string[];
+  additionalProperties?: boolean | Shape;
+  propertyNames?: Shape;
+}
 
 export type Shape =
   | ({ type: Nullably<'string'> } & StringConstraints)
   | ({ type: Nullably<'number'> | Nullably<'integer'> } & NumericConstraints)
-  | { type: Nullably<'boolean'> }
+  | ({ type: Nullably<'boolean'> } & Documented)
   | ({ type: Nullably<'array'> } & ArrayConstraints)
   | ({ type: Nullably<'object'> } & ObjectConstraints);
 
-const SHAPE_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'] as const;
+export const SHAPE_TYPES = [
+  'string',
+  'number',
+  'integer',
+  'boolean',
+  'array',
+  'object',
+] as const;
 
 type BaseShape =
   | ({ type: 'string' } & StringConstraints)
   | ({ type: 'number' | 'integer' } & NumericConstraints)
-  | { type: 'boolean' }
+  | ({ type: 'boolean' } & Documented)
   | ({ type: 'array' } & ArrayConstraints)
   | ({ type: 'object' } & ObjectConstraints);
 
@@ -42,26 +73,21 @@ type _ShapeConformsToJsonSchema = Assert<
 >;
 
 type _ShapeTypesAreTheStandardsLessNull = Assert<
-  [Exclude<Exclude<JSONSchema7TypeName, 'null'>, (typeof SHAPE_TYPES)[number]>] extends [never]
+  [Exclude<Exclude<JSONSchema7TypeName, 'null'>, (typeof SHAPE_TYPES)[number]>] extends [
+    never,
+  ]
     ? true
     : false
 >;
 
+/** Every type name a shape states, whether it states one or a union of them. */
+const typesOf = (shape: Shape): readonly string[] =>
+  (Array.isArray(shape.type) ? shape.type : [shape.type]) as readonly string[];
+
 export class Shapes {
   private static readonly cache = new WeakMap<object, ShapeParts>();
   private static readonly none: ShapeParts = { base: undefined, nullable: false };
 
-  static is(value: unknown): value is Shape {
-    if (typeof value !== 'object' || value === null) return false;
-    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))
-    );
-  }
-
   /**
    * Every `pattern` a shape states, the nested ones included — `items`, `properties`.
    *
@@ -89,11 +115,28 @@ export class Shapes {
     for (const member of Object.values(value)) Shapes.collectPatterns(member, found);
   }
 
+  /**
+   * `null` enters the grammar, and every constraint stays. It is added when it is ABSENT,
+   * read off the shape rather than assumed from its form — a shape already stating it comes
+   * back as itself, so `optional(nullable(text()))` does the work once.
+   *
+   * `enum` is widened TOO, because JSON Schema checks it apart from `type`: a shape saying
+   * `['string','null']` and `enum: ['draft','live']` calls null a legal type and not a legal
+   * value, and the engine answers `Instance does not match any of ["draft","live"]`.
+   *
+   * `{ type: 'string', minLength: 3 }`      → `{ type: ['string','null'], minLength: 3 }`
+   * `{ type: 'string', enum: ['draft'] }`   → `{ type: ['string','null'], enum: ['draft', null] }`
+   */
   static nullable(shape: Shape): Shape {
-    if (Array.isArray(shape.type)) return shape;
-    const nullable = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
+    const types = typesOf(shape);
+    if (types.includes('null')) return shape;
+
+    const nullable = { ...shape, type: [...types, '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];
+      (nullable as { enum: readonly (string | number | null)[] }).enum = [
+        ...nullable.enum,
+        null,
+      ];
     }
 
     return nullable;
@@ -107,7 +150,9 @@ export class Shapes {
         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);
+          (base as { enum: readonly (string | number | null)[] }).enum = base.enum.filter(
+            (v) => v !== null,
+          );
         }
         parts = { base, nullable: true };
       } else {
@@ -115,6 +160,7 @@ export class Shapes {
       }
       this.cache.set(shape, parts);
     }
+
     return parts;
   }
 
@@ -122,6 +168,26 @@ export class Shapes {
     return this.of(shape).nullable;
   }
 
+  /**
+   * A value that came in as text — a form control, a command-line flag — read as the shape
+   * declares it. What does not read that way stays as it came, for the judge to refuse by name.
+   * `fromText({ type: 'integer' }, '12')` → `12`, and `fromText({ type: 'integer' }, 'abc')` → `'abc'`
+   */
+  static fromText(shape: Shape | undefined, value: unknown): unknown {
+    const type = this.of(shape).base?.type;
+
+    if (
+      (type !== 'number' && type !== 'integer') ||
+      typeof value !== 'string' ||
+      value === ''
+    )
+      return value;
+
+    const number = Number(value);
+
+    return Number.isFinite(number) ? number : value;
+  }
+
   /**
    * `shape.type` read off the base, except that a `string` answers `date` or `choice`.
    * FR : `shape.type` lu sur la base, sauf qu'une chaîne répond `date` ou `choice`.

package/src/axis/shape/ShapeFormat.ts

@@ -0,0 +1,37 @@
+import { Format } from '../../lib/Format.js';
+import { SHAPE_TYPES, type Shape } from './Shape.js';
+
+const SHAPE = 'field/shape';
+
+/** A word, or that word beside `null` — the second place is what makes a shape nullable. */
+const TYPE = Format.either(
+  Format.tokens(SHAPE_TYPES),
+  Format.tuple(Format.tokens(SHAPE_TYPES), Format.tokens(['null'])),
+);
+
+/**
+ * What a shape may state — JSON Schema's own keywords, less the ones this package has no word
+ * for. `shape` used to be the one key of a field declaration nothing judged, so `minLenght: 1`
+ * passed and was dropped where `lifecycle: { craete: 'now' }` had been refused since `Format`.
+ * `properties` stays open because a projection folds `meta.description` into it.
+ */
+export const SHAPE_FORMAT = Format.of(SHAPE)
+  .key('type', TYPE)
+  .key('description', Format.text)
+  .key('minLength', Format.count)
+  .key('maxLength', Format.count)
+  .key('pattern', Format.text)
+  .key('format', Format.text)
+  .key('enum', Format.listOf(Format.anything))
+  .key('minimum', Format.number)
+  .key('maximum', Format.number)
+  .key('items', Format.ref(SHAPE))
+  .key('minItems', Format.count)
+  .key('maxItems', Format.count)
+  .key('properties', Format.anything)
+  .key('required', Format.listOf(Format.text))
+  .key('additionalProperties', Format.anything)
+  .key('propertyNames', Format.ref(SHAPE))
+  .needs('type')
+  .closed()
+  .as<Shape>();

package/src/entity/EntityDeclarations.ts

@@ -1,10 +1,11 @@
 import type { Fields } from '../field/Fields.js';
 import type { EntityAdapters } from './EntityAdapters.js';
-import type { CompositeUnique } from './CompositeUnique.js';
+import type { FieldGroups } from './FieldGroups.js';
 import type { PreviousNames } from './PreviousNames.js';
 
 export interface EntityDeclarations<TFields extends Fields> {
   adapters?: EntityAdapters<TFields>;
   previous?: PreviousNames<TFields>;
-  unique?: CompositeUnique<TFields>;
+  unique?: FieldGroups<TFields>;
+  index?: FieldGroups<TFields>;
 }

package/src/entity/FieldGroups.ts

@@ -0,0 +1,9 @@
+import type { FieldName } from '../field/FieldName.js';
+import type { Fields } from '../field/Fields.js';
+
+/**
+ * Field names grouped, as `unique` and `index` both are — `[['listId', 'docId'], ['slug']]`.
+ * The ORDER inside a group counts for both: a unique constraint on `(a, b)` is not the one on
+ * `(b, a)`, and an index on `(a, b)` serves a filter on `a` alone and never on `b` alone.
+ */
+export type FieldGroups<TFields extends Fields> = readonly (readonly FieldName<TFields>[])[];

package/src/field/Field.ts

@@ -1,31 +1,49 @@
 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 './Meta.js';
 import { Axes } from '../axis/Axes.js';
-import type { FougereFieldAxes } from './FougereFieldAxes.js';
+import type { FougereFieldAxes } from '../FougereFieldAxes.js';
 import { FieldDeclarationValidator } from '../validator/FieldDeclarationValidator.js';
 import { FieldValueValidator } from '../validator/FieldValueValidator.js';
+import { isObject } from '../lib/utils.js';
 import { dotted } from '../lib/ValidationResult.js';
 import { SchemaError } from '../SchemaError.js';
 
-interface FieldDeclaration extends FougereFieldAxes {
+/** The sentence any word admits, whatever it shapes — a relation and a date carry one too. */
+export interface Described {
+  description?: string;
+}
+
+/** And a value it is born with, for the words that shape one. `many()` has none to hold. */
+export interface Shared<T> extends Described {
+  default?: T;
+}
+
+export interface FieldDeclaration extends FougereFieldAxes {
   shape: Shape;
-  role?: RoleRules;
-  lifecycle?: LifecycleRules;
-  boundary?: BoundaryRef;
-  meta?: Meta;
+}
+
+/**
+ * Every word ends on `setShared`, so the options are read in ONE place and refused there.
+ * `text(42)` used to pass for a bare `text()`, and nine of the twelve words took it.
+ */
+const refuseLooseOptions = (opts: unknown): void => {
+  if (!isObject(opts))
+    throw new SchemaError('Options must go in an object, like { max: 200 }', { received: opts });
+};
+
+/** The registry answers strings, and a member of a declaration is what they name. */
+const registered = (): (keyof FieldDeclaration)[] => Axes.names as (keyof FieldDeclaration)[];
+
+/**
+ * The axes it carries are `FougereFieldAxes`, which each axis writes its own line in — so the
+ * three of the core are typed the way a fourth declared outside is, and the class names what
+ * the registry decides only once, in the constructor.
+ */
+export interface Field<T = unknown> extends FougereFieldAxes {
+  readonly _type?: T;
 }
 
 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;
@@ -38,12 +56,11 @@ export class Field<T = unknown> {
     }
 
     this.shape = init.shape;
-    this.meta = init.meta;
 
-    const stated = init as unknown as Record<string, unknown>;
-
-    for (const slot of Axes.names) {
-      (this as unknown as Record<string, unknown>)[slot] = stated[slot];
+    for (const name of registered()) {
+      Object.defineProperty(this, name, {
+        value: init[name], writable: true, enumerable: true, configurable: true,
+      });
     }
 
     const create = this.lifecycle?.create;
@@ -61,7 +78,53 @@ export class Field<T = unknown> {
     return FieldDeclarationValidator.of(value).verdict.success;
   }
 
+  /**
+   * What this field declares on ONE axis, a fourth one registered outside included. An axis is
+   * a member, so it is read by NAME, and three callers reached for it through a cast of their
+   * own before this existed.
+   */
+  axis(name: keyof FieldDeclaration): unknown {
+    return (this satisfies FieldDeclaration)[name];
+  }
+
+  /** Every axis it declares, and nothing for the ones it says nothing on. */
+  get axes(): Record<string, unknown> {
+    return Object.fromEntries(
+      registered()
+        .map((name) => [name, this.axis(name)])
+        .filter(([, declared]) => declared !== undefined),
+    );
+  }
+
+  /** Whether it states anything at all beside its shape. */
+  hasAxes(): boolean {
+    return registered().some((name) => this.axis(name) !== undefined);
+  }
+
   with<U = T>(overrides: Partial<FieldDeclaration>): Field<U> {
     return new Field<U>({ ...this, ...overrides });
   }
+
+  /**
+   * What a word admits whatever its shape, and where it lands: `description` IS a JSON Schema
+   * keyword, `default` IS a lifecycle rule. Stated here alone, so no word writes the conversion.
+   * FR : ce que tout mot admet quelle que soit sa forme, et où ça atterrit.
+   * `text({ max: 200 }).setShared({ description: 'The title' })` → `shape.description`
+   */
+  setShared(opts?: Shared<T>): Field<T> {
+    if (opts === undefined) return this;
+
+    refuseLooseOptions(opts);
+
+    const overrides: Partial<FieldDeclaration> = {
+      ...(opts.description !== undefined
+        ? { shape: { ...this.shape, description: opts.description } }
+        : {}),
+      ...(opts.default !== undefined
+        ? { lifecycle: { ...this.lifecycle, create: { value: opts.default } } }
+        : {}),
+    };
+
+    return Object.keys(overrides).length ? this.with<T>(overrides) : this;
+  }
 }

package/src/field/FieldFormat.ts

@@ -1,18 +1,18 @@
 import type { Axis } from '../axis/Axis.js';
 import { Format } from '../lib/Format.js';
 import type { JsonSchema } from '../lib/JsonSchema.js';
-import { META_FORMAT } from './Meta.js';
+import { SHAPE_FORMAT } from '../axis/shape/ShapeFormat.js';
 
 /**
  * What a field may state, composed from the keys that state a format: each is carried whole and
  * cited by its `$id`, so the document travels alone and a key keeps its own identity. `shape` is
- * JSON Schema itself, and `Shapes.is` is what reads it.
+ * cited like the rest — it is JSON Schema, and JSON Schema is what states its keywords.
  */
 export function fieldFormat(axes: readonly [string, Axis][]): JsonSchema {
   const document = axes.reduce(
-    (held, [slot, axis]) => held.cites(slot, axis.format),
-    Format.of('field').key('shape', Format.anything),
+    (held, [name, axis]) => held.cites(name, axis.format),
+    Format.of('field').cites('shape', SHAPE_FORMAT),
   );
 
-  return document.cites('meta', META_FORMAT).closed().schema as JsonSchema;
+  return document.closed().schema as JsonSchema;
 }

package/src/field/FieldSet.ts

@@ -1,5 +1,5 @@
 import { Role } from '../axis/role/Role.js';
-import type { CompositeUnique } from '../entity/CompositeUnique.js';
+import type { FieldGroups } from '../entity/FieldGroups.js';
 import { Field } from './Field.js';
 import { type FieldName } from './FieldName.js';
 import { type Fields } from './Fields.js';
@@ -17,39 +17,47 @@ export class FieldSet<TFields extends Fields = Fields> {
    * FR : partage un `unique` déclaré : un groupe d'un va au champ, plusieurs restent au schéma.
    * `declaring(fields, [['email'], ['listId', 'docId']])` → `email` carries it, the pair is a group
    */
+  /**
+   * A group of ONE is the word on the field — `unique: [['slug']]` is `unique(text())` — so it
+   * is written there and never kept as a group, which is what lets a derivation drop it with
+   * its field. A group of several is what no single field can state, and it is kept whole.
+   */
   static declaring<TFields extends Fields>(
     declared: TFields,
-    unique?: CompositeUnique<TFields>,
-  ): { fields: TFields; groups: CompositeUnique<TFields> } {
+    groups: { unique?: FieldGroups<TFields>; index?: FieldGroups<TFields> } = {},
+  ): { fields: TFields; unique: FieldGroups<TFields>; index: FieldGroups<TFields> } {
     const fields: Fields = {};
     for (const [key, field] of Object.entries(declared))
       fields[key] = new Field(field, key);
 
-    const composite: FieldName<TFields>[][] = [];
-    for (const group of unique ?? []) {
-      const missing = group.filter((key) => !Object.hasOwn(fields, key));
-      if (missing.length)
-        throw new SchemaError(
-          `unique: [${group.join(', ')}] names ` +
-            `${missing.map((key) => `'${key}'`).join(', ')}, which the entity does not declare.`,
-        );
+    const composite = { unique: [] as FieldName<TFields>[][], index: [] as FieldName<TFields>[][] };
+
+    for (const kind of ['unique', 'index'] as const) {
+      for (const group of groups[kind] ?? []) {
+        const missing = group.filter((key) => !Object.hasOwn(fields, key));
+        if (missing.length)
+          throw new SchemaError(
+            `${kind}: [${group.join(', ')}] names ` +
+              `${missing.map((key) => `'${key}'`).join(', ')}, which the entity does not declare.`,
+          );
 
-      if (group.length === 1) {
-        const key = group[0]!;
-        const alone = fields[key]!;
-        fields[key] = alone.with({ role: { ...alone.role, unique: true } });
-        continue;
+        if (group.length === 1) {
+          const key = group[0]!;
+          const alone = fields[key]!;
+          fields[key] = alone.with({ role: { ...alone.role, [kind]: true } });
+          continue;
+        }
+        composite[kind].push([...group]);
       }
-      composite.push([...group]);
     }
 
-    return { fields: fields as TFields, groups: composite };
+    return { fields: fields as TFields, unique: composite.unique, index: composite.index };
   }
 
   /** 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)
+      .filter(([, field]) => Role.of(field).isPrimary())
       .map(([name]) => name);
 
     if (primaries.length > 1) {

package/src/index.ts

@@ -41,6 +41,7 @@ export { StringFormats } from './axis/shape/StringFormats.js';
 export { Generators } from './axis/lifecycle/Generators.js';
 export { Boundaries } from './axis/boundary/Decoder.js';
 export { type FougereEntityAdapters } from './entity/FougereEntityAdapters.js';
+export { type FougereFieldAxes } from './FougereFieldAxes.js';
 export { InputValidator } from './validator/InputValidator.js';
 export { FieldValueValidator } from './validator/FieldValueValidator.js';
 export { JsonSchemaValidator } from './validator/JsonSchemaValidator.js';

package/src/lib/Format.ts

@@ -21,6 +21,8 @@ export class Format<T = unknown> {
   static readonly anything = new Format<unknown>(true);
   static readonly text = new Format<string>({ type: 'string' });
   static readonly flag = new Format<boolean>({ type: 'boolean' });
+  static readonly number = new Format<number>({ type: 'number' });
+  static readonly count = new Format<number>({ type: 'integer', minimum: 0 });
 
   declare readonly _admits?: T;
 
@@ -34,12 +36,43 @@ export class Format<T = unknown> {
     return new Format({ enum: [...words] });
   }
 
-  /** A word or a shape, told apart by TYPE, so a refusal names the half the value belongs to. */
-  static either<Word, Shape>(word: Format<Word>, shape: Format<Shape>): Format<Word | Shape> {
+  /** `enum`, `required` — a list of one format, so `enum: 'draft'` is refused as the scalar it is. */
+  static listOf<Value>(format: Format<Value>): Format<Value[]> {
+    return new Format({ type: 'array', items: format.schema });
+  }
+
+  /**
+   * A list of a FIXED length, each place stating its own format — `['string', 'null']` and
+   * never `['string', 'number']`, which a list of one format cannot tell apart.
+   */
+  static tuple<const Places extends readonly Format<unknown>[]>(
+    ...places: Places
+  ): Format<{ -readonly [K in keyof Places]: Accepted<Places[K]> }> {
+    return new Format({
+      type: 'array',
+      prefixItems: places.map((place) => place.schema),
+      minItems: places.length,
+      maxItems: places.length,
+    });
+  }
+
+  /**
+   * A format naming ITSELF, which no value can do while it is being built: `items` holds a shape,
+   * and the shape is what declares `items`. The `$id` `of()` already posts is what it points at.
+   */
+  static ref(id: string): Format<unknown> {
+    return new Format({ $ref: absolute(id) as string });
+  }
+
+  /**
+   * A word or anything else, told apart by TYPE, so a refusal names the half the value belongs
+   * to — `create: 'nawak'` reads against the words, `type: ['string', 'null']` against the list.
+   */
+  static either<Word, Other>(word: Format<Word>, otherwise: Format<Other>): Format<Word | Other> {
     return new Format({
       if: { type: 'string' },
       then: word.schema as JsonSchema,
-      else: shape.schema as JsonSchema,
+      else: otherwise.schema as JsonSchema,
     });
   }
 

package/src/lib/UnionToIntersection.ts

@@ -0,0 +1,10 @@
+/**
+ * What a union becomes when every member must hold at once — `A | B` → `A & B`, through the
+ * contravariance of a parameter position, which is the only place TypeScript folds a union.
+ * `Merged<[Post, Draft]>` and `ShapeKeywords` both need it, and each had written it out.
+ */
+export type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (
+  member: infer Held,
+) => void
+  ? Held
+  : never;

package/src/lib/utils.ts

@@ -15,4 +15,8 @@ export function clean<T extends Record<string, unknown>>(obj: T): T {
 export const isObject = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
-export const shown = (value: unknown): string => JSON.stringify(value) ?? typeof value;
+export const isArrayOf = <T>(
+  values: readonly unknown[],
+  is: (value: unknown) => value is T,
+): values is readonly T[] => values.every(is);
+

package/src/projection/Cases.ts

@@ -16,6 +16,7 @@ import type { ValidationCase } from './ValidationCase.js';
 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';
 }
 
@@ -42,6 +43,11 @@ function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
       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.enum) {
+      const members = shape.enum.filter((value) => typeof value === 'number');
+
+      cases.push({ why: 'outside the stated set', value: Math.max(...members) + 1 });
+    }
   }
   if (shape?.type === 'array') {
     if (typeof shape.minItems === 'number' && shape.minItems > 0)
@@ -52,6 +58,7 @@ function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
         value: Array.from({ length: shape.maxItems + 1 }, () => null),
       });
   }
+
   return cases;
 }
 
@@ -64,8 +71,8 @@ function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
 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 of(schema: SchemaView, valid: Record<string, unknown>): Cases {
+    return new Cases(enumerate(schema, valid));
   }
 
   static holds(
@@ -74,6 +81,7 @@ export class Cases {
   ): boolean {
     if (expected === 'accept') return result.success;
     if (result.success) return false;
+
     return (result.errors ?? []).some((error) => rejected(error.path) === expected.reject);
   }
 
@@ -92,8 +100,8 @@ export class Cases {
  * FR : lit les quatre axes plutôt qu'une liste tenue à la main : un cas existe parce qu'un
  * champ déclare la règle qu'il casse.
  */
-function enumerate(entity: SchemaView, valid: Record<string, unknown>): ValidationCase[] {
-  const fields = entity.getFields();
+function enumerate(schema: SchemaView, valid: Record<string, unknown>): ValidationCase[] {
+  const fields = schema.getFields();
   const validator = InputValidator.of(fields);
 
   return [
@@ -124,13 +132,13 @@ function aboutField(
   const withField = (value: unknown) => ({ ...valid, [name]: value });
   const cases: ValidationCase[] = [];
 
-  if (validator.onAbsent(field) === null && name in valid) {
+  if (validator.requires(field) && 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) {
+  if (Boundary.of(field).readOnly()) {
     cases.push({
       why: `${name} supplied although read-only`,
       input: withField(wrongTypeFor(field)),
@@ -139,7 +147,16 @@ function aboutField(
     });
   }
 
-  if (Lifecycle.of(field).immutable && !Role.of(field).isPrimary) {
+  if (Role.of(field).isCollection()) {
+    cases.push({
+      why: `${name} supplied although the other side carries it`,
+      input: withField([]),
+      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) },
@@ -150,7 +167,7 @@ function aboutField(
 
   // 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.
-  if (name in valid && !Role.of(field).isReference) {
+  if (name in valid && !Role.of(field).isReference()) {
     cases.push({
       why: `${name} of the wrong type`,
       input: withField(wrongTypeFor(field)),