@fougere/schema 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/projection/Visibility.ts

@@ -1,7 +1,7 @@
-import { Boundary } from '../schema/axis/boundary/Boundary.js';
-import { Lifecycle } from '../schema/axis/lifecycle/Lifecycle.js';
-import { Role } from '../schema/axis/role/Role.js';
-import type { Fields } from '../schema/fields/Field.js';
+import { Boundary } from '../axis/boundary/Boundary.js';
+import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
+import { Role } from '../axis/role/Role.js';
+import type { Fields } from '../field/Field.js';
 
 export class Visibility {
   private constructor(private readonly fields: Fields) {}
@@ -10,6 +10,7 @@ export class Visibility {
     return new Visibility(fields);
   }
 
+  /** A write-only secret is absent from the type, not just from the value. */
   get input(): Fields {
     const result: Fields = {};
     for (const [name, field] of Object.entries(this.fields)) {

package/src/projection/card/Bundle.ts

@@ -1,7 +1,7 @@
-import type { Resolver } from '../../schema/axis/Axis.js';
-import type { EntityConstructor } from '../../schema/axis/role/Relation.js';
-import { lowerFirst } from '../../utils.js';
-import type { SchemaView } from '../../schema/SchemaView.js';
+import type { Resolver } from '../../axis/Axis.js';
+import type { EntityConstructor } from '../../axis/role/Relation.js';
+import { lowerFirst } from '../../lib/utils.js';
+import type { SchemaView } from '../../SchemaView.js';
 import { Card } from './Card.js';
 import type { SchemaBundle, SchemaDescriptor } from './Descriptor.js';
 import type { Diff, SetDiff, SetDiffOptions } from './diff.js';
@@ -47,12 +47,12 @@ export class Bundle {
   }
 
   toSchemas(): Record<string, SchemaView> {
-    const map: Record<string, EntityConstructor> = {};
-    const resolve: Resolver = (name) => map[name.toLowerCase()];
+    const byName: Record<string, EntityConstructor> = {};
+    const resolve: Resolver = (name) => byName[name.toLowerCase()];
     const schemas: Record<string, SchemaView> = {};
     for (const [name, descriptor] of Object.entries(this.descriptor.$defs)) {
       const schema = Card.fromDescriptor(descriptor).toSchema(resolve, name);
-      map[name.toLowerCase()] = schema as unknown as EntityConstructor;
+      byName[name.toLowerCase()] = schema as unknown as EntityConstructor;
       schemas[name] = schema;
     }
     return schemas;
@@ -65,11 +65,11 @@ export class Bundle {
     for (const [name, descriptor] of Object.entries(before)) {
       const target = after[name];
       if (target === undefined) continue;
-      const answer = Card.fromDescriptor(descriptor).diff(
+      const diff = Card.fromDescriptor(descriptor).diff(
         Card.fromDescriptor(target),
         { renamed: options.renamed?.[name] ?? {} },
       );
-      if (answer.changes.length > 0 || answer.ambiguous.length > 0) entities[name] = answer;
+      if (diff.changes.length > 0 || diff.ambiguous.length > 0) entities[name] = diff;
     }
     return {
       entitiesAdded: Object.keys(after).filter((name) => !(name in before)),

package/src/projection/card/Card.ts

@@ -1,10 +1,11 @@
-import { EXTENSION_AXES, EXTENSION_SLOTS, type Resolver } from '../../schema/axis/Axis.js';
+import { EXTENSION_AXES, EXTENSION_SLOTS, type Resolver } from '../../axis/Axis.js';
 import { dequal } from 'dequal';
-import { clean, isObject } from '../../utils.js';
-import { Field, type Fields } from '../../schema/fields/Field.js';
-import { RowJudge } from '../../judge/RowJudge.js';
-import { Schema, type SchemaConstructor } from '../../schema/Schema.js';
-import type { Row, SchemaView } from '../../schema/SchemaView.js';
+import { clean, isObject } from '../../lib/utils.js';
+import { Field, type Fields } from '../../field/Field.js';
+import { deduplicated } from '../../field/FieldSet.js';
+import { InputValidator } from '../../validator/InputValidator.js';
+import { Schema, type SchemaConstructor } from '../../Schema.js';
+import type { Values, SchemaView } from '../../SchemaView.js';
 import { refuse } from './admission.js';
 import type {
   DerivedFrom,
@@ -17,21 +18,23 @@ import type { Change, Diff, DiffOptions, RenameCandidate, TypeSet } from './diff
 type FieldsOf<T> = { [K in keyof T]-?: Field<T[K]> };
 
 /** One portable schema description and every decision made about that description. */
-export class Card<T = Row<Fields>> {
+export class Card<T = Values<Fields>> {
   private constructor(readonly descriptor: SchemaDescriptor) {}
 
   static fromSchema<TFields extends Fields>(
     schema: SchemaView<TFields>,
     name?: string,
-  ): Card<Row<TFields>> {
+  ): Card<Values<TFields>> {
     const fields = schema.getFields();
-    const judge = RowJudge.of(fields);
+    const validator = InputValidator.of(fields);
     const properties: Record<string, FieldDescriptor> = {};
     const required: string[] = [];
     for (const [key, field] of Object.entries(fields)) {
       properties[key] = describeField(field, key);
-      if (judge.onAbsent(field) === null) required.push(key);
+      if (validator.onAbsent(field) === null) required.push(key);
     }
+    for (const group of schema.getUnique() ?? [])
+      for (const member of group) carryGroup(properties[member], group);
 
     const descriptor: SchemaDescriptor = {
       type: 'object',
@@ -45,53 +48,50 @@ export class Card<T = Row<Fields>> {
 
     const origin = originOf(schema);
     if (origin) descriptor['x-fougere-derived'] = origin;
-    return new Card<Row<TFields>>(descriptor);
+    return new Card<Values<TFields>>(descriptor);
   }
 
-  static fromDescriptor<T = Row<Fields>>(descriptor: SchemaDescriptor): Card<T> {
+  static fromDescriptor<T = Values<Fields>>(descriptor: SchemaDescriptor): Card<T> {
     return new Card<T>(descriptor);
   }
 
-  /** The root derivation recorded by this card, when its schema was cut from another. */
   get origin(): DerivedFrom | undefined {
     return this.descriptor['x-fougere-derived'];
   }
 
-  /**
-   * Rebuild the live schema. A bundle supplies `resolve` so relation thunks can find the
-   * other reconstructed cards; a lone card deliberately falls back to a name stand-in.
-   */
   toSchema(resolve?: Resolver, name?: string): SchemaConstructor<FieldsOf<T>> {
     const descriptor = this.descriptor;
-    const where = name ? `schema '${name}'` : 'this schema';
+    const subject = name ? `schema '${name}'` : 'this schema';
     if (!isObject(descriptor))
-      refuse(`${where} is not an object`, 'A card carries one JSON Schema per door.');
+      refuse(`${subject} is not an object`, 'A card carries one JSON Schema per door.');
     const version = descriptor['x-fougere-version'];
     if (version !== 1) {
       refuse(
-        `${where} states \`x-fougere-version: ${JSON.stringify(version)}\` and this reader speaks 1`,
+        `${subject} states \`x-fougere-version: ${JSON.stringify(version)}\` and this reader speaks 1`,
         'A producer and its readers move together: re-sync the consumer, or serve the version it speaks.',
       );
     }
     if (!isObject(descriptor.properties)) {
       refuse(
-        `${where} carries no \`properties\` object`,
+        `${subject} carries no \`properties\` object`,
         'A schema is its fields; there is nothing to rebuild.',
       );
     }
 
     const fields: Fields = {};
+    const groups: string[][] = [];
     for (const [key, property] of Object.entries(descriptor.properties)) {
       fields[key] = reconstructField(property, key, resolve);
+      for (const group of property['x-fougere']?.role?.unique ?? [])
+        if (group.length > 1) groups.push([...group]);
     }
-    const schema = Schema.of({ fields });
+    const schema = Schema.of({ fields, constraints: { unique: deduplicated(groups) } });
     const title = name ?? descriptor.title;
     if (title)
       Object.defineProperty(schema, 'name', { value: title, configurable: true });
     return schema as unknown as SchemaConstructor<FieldsOf<T>>;
   }
 
-  /** What must change to turn this card into `other`. */
   diff(other: Card, options: DiffOptions = {}): Diff {
     const changes: Change[] = [];
     const renamed = options.renamed ?? {};
@@ -155,6 +155,11 @@ export class Card<T = Row<Fields>> {
   }
 }
 
+/**
+ * So the three axes write themselves under `x-fougere`, each by its own hand.
+ * FR : pour que les trois axes s'écrivent sous `x-fougere`, chacun de sa main.
+ * `ref(User)` → `{ role: { relation: { to: 'user', kind: 'one' } } }`
+ */
 function describeExtension(field: Field, key: string): FieldExtension | undefined {
   const extension: Record<string, unknown> = {};
   for (const axis of EXTENSION_AXES) {
@@ -167,72 +172,57 @@ function describeExtension(field: Field, key: string): FieldExtension | undefine
   return Object.keys(extension).length ? (extension as FieldExtension) : undefined;
 }
 
+/**
+ * So the shape stays plain JSON Schema, and what is ours sits under one key.
+ * FR : pour que la forme reste du JSON Schema, ce qui est à nous tenant sous une clé.
+ * `text({ max: 200 })` → `{ type: 'string', maxLength: 200 }`
+ */
 function describeField(field: Field, key: string): FieldDescriptor {
-  const descriptor: FieldDescriptor = {};
-  for (const [shapeKey, value] of Object.entries(field.shape)) {
-    if (value !== undefined) (descriptor as Record<string, unknown>)[shapeKey] = value;
-  }
+  // The shape IS JSON Schema, so it lands whole rather than key by key — which is what let
+  // it be copied under a computed key into a type that names its own.
+  const descriptor: FieldDescriptor = clean({ ...field.shape }) as FieldDescriptor;
   if (field.meta?.description) descriptor.description = field.meta.description;
   const extension = describeExtension(field, key);
   if (extension) descriptor['x-fougere'] = extension;
   return descriptor;
 }
 
+/**
+ * So a derived card names its root and what became of each field.
+ * FR : pour qu'une carte dérivée nomme sa racine et le sort de chaque champ.
+ * `Post.pick('title')` → `{ from: 'Post', nameOf: { title: 'title' } }`
+ */
 function originOf(schema: SchemaView): DerivedFrom | undefined {
   const { derivation } = schema;
   if (!derivation) return undefined;
-  const survived = Object.fromEntries(
-    Object.entries(derivation.survived).map(([key, value]) => [key, value ?? null]),
+  const nameOf = Object.fromEntries(
+    Object.entries(derivation.nameOf).map(([key, value]) => [key, value ?? null]),
   );
-  return { from: derivation.sourceName, survived };
+  return { from: derivation.sourceName, nameOf };
 }
 
+/**
+ * So a shape read back is the shape that was written, and an unknown type is refused.
+ * FR : pour qu'une forme relue soit celle qui a été écrite, un type inconnu étant refusé.
+ * `{ type: 'string', maxLength: 200 }` → the same shape a `text({ max: 200 })` states
+ */
 function reconstructShape(property: FieldDescriptor): Field['shape'] | undefined {
-  const types = Array.isArray(property.type)
-    ? property.type
-    : property.type
-      ? [property.type]
-      : [];
-  const base = types.find((type) => type !== 'null');
-  if (base === undefined) return undefined;
-  const type = property.type as Field['shape']['type'];
-  if (base === 'array') {
-    const items = property.items ? reconstructShape(property.items) : undefined;
-    return clean({
-      type,
-      items,
-      minItems: property.minItems,
-      maxItems: property.maxItems,
-    }) as Field['shape'];
-  }
-  switch (base) {
-    case 'string':
-      return clean({
-        type,
-        minLength: property.minLength,
-        maxLength: property.maxLength,
-        pattern: property.pattern,
-        enum: property.enum,
-        format: property.format,
-      }) as Field['shape'];
-    case 'number':
-    case 'integer':
-      return clean({
-        type,
-        minimum: property.minimum,
-        maximum: property.maximum,
-      }) as Field['shape'];
-    case 'boolean':
-      return { type } as Field['shape'];
-    default:
-      return clean({
-        type,
-        properties: property.properties,
-        required: property.required,
-      }) as Field['shape'];
-  }
+  const types = Array.isArray(property.type) ? property.type : property.type ? [property.type] : [];
+  if (!types.some((type) => type !== 'null')) return undefined;
+
+  // `describeField` writes the shape whole, so it is read whole: a list of keywords here
+  // would be a second inventory, and the one that forgets a keyword loses it in silence.
+  const { 'x-fougere': _extension, description: _description, ...shape } = property;
+  if (shape.items) shape.items = reconstructShape(shape.items) as FieldDescriptor;
+
+  return clean(shape) as Field['shape'];
 }
 
+/**
+ * So a field read back carries its axes, rebuilt by the axes themselves.
+ * FR : pour qu'un champ relu porte ses axes, reconstruits par les axes eux-mêmes.
+ * `{ 'x-fougere': { lifecycle: { create: 'now' } } }` → a field stamped at create
+ */
 function reconstructField(
   property: FieldDescriptor,
   key: string,
@@ -261,6 +251,11 @@ function reconstructField(
   } as never);
 }
 
+/**
+ * So an axis that changed is one named difference, not a whole field marked dirty.
+ * FR : pour qu'un axe modifié soit une différence nommée, pas un champ entier marqué.
+ * `{ kind: 'restated', field: 'body', axis: 'boundary', … }`
+ */
 function restated(
   field: string,
   before: FieldExtension | undefined,
@@ -278,22 +273,42 @@ function restated(
   );
 }
 
+/**
+ * So two shapes are compared without what is not shape getting in the way.
+ * FR : pour que deux formes se comparent sans que le reste s'en mêle.
+ * `{ type: 'string', description: 'x' }` → `{ type: 'string' }`
+ */
 function shapeOf(descriptor: FieldDescriptor): Record<string, unknown> {
-  const { 'x-fougere': _extension, ...shape } = descriptor;
+  const { 'x-fougere': _extension, description: _description, ...shape } = descriptor;
   return shape as Record<string, unknown>;
 }
 
+/**
+ * So `['string','null']` and `['null','string']` are the same type, not a change.
+ * FR : pour que `['string','null']` et `['null','string']` soient un même type.
+ * `typesOf({ type: ['null', 'string'] })` → `['null', 'string']`
+ */
 function typesOf(descriptor: FieldDescriptor): TypeSet {
   const type = descriptor.type;
   if (type === undefined) return [];
   return (Array.isArray(type) ? [...type] : [type]).sort();
 }
 
+/**
+ * So a bound that moved is a `reshaped`, told apart from a type that changed.
+ * FR : pour qu'une borne déplacée soit un `reshaped`, distinct d'un type changé.
+ * `maxLength: 200` → `maxLength: 100` → one `reshaped`, never a `retyped`
+ */
 function boundsOf(descriptor: FieldDescriptor): Record<string, unknown> {
   const { type: _type, ...rest } = shapeOf(descriptor);
   return rest;
 }
 
+/**
+ * So a removal plus an addition of the same shape is a question, never a guess.
+ * FR : pour qu'une suppression plus un ajout de même forme soit une question, pas un pari.
+ * `body` gone, `content` appeared → `ambiguous: [{ removed: 'body', added: 'content' }]`
+ */
 function candidates(
   removed: string[],
   added: string[],
@@ -313,3 +328,15 @@ function candidates(
     Math.abs(now.indexOf(appeared) - was.indexOf(gone));
   return found.sort((a, b) => apart(a) - apart(b));
 }
+
+/**
+ * So a group spanning several fields reaches a reader that only ever sees one field.
+ * FR : pour qu'un groupe couvrant plusieurs champs atteigne un lecteur qui n'en voit qu'un.
+ * `carryGroup(properties.listId, ['listId', 'docId'])` → the pair lands under its `role`
+ */
+function carryGroup(property: FieldDescriptor | undefined, group: readonly string[]): void {
+  if (!property) return;
+  const extension = (property['x-fougere'] ??= {}) as { role?: { unique?: string[][] } };
+  const role = (extension.role ??= {});
+  (role.unique ??= []).push([...group]);
+}

package/src/projection/card/Descriptor.ts

@@ -1,8 +1,8 @@
-import type { BoundaryRef } from '../../schema/axis/boundary/Boundary.js';
-import type { LifecycleRules } from '../../schema/axis/lifecycle/Lifecycle.js';
-import type { Relation } from '../../schema/axis/role/Relation.js';
-import type { RoleRules } from '../../schema/axis/role/Role.js';
-import type { Shape } from '../../schema/axis/shape/Shape.js';
+import type { BoundaryRef } from '../../axis/boundary/Boundary.js';
+import type { LifecycleRules } from '../../axis/lifecycle/Lifecycle.js';
+import type { Relation } from '../../axis/role/Relation.js';
+import type { RoleRules } from '../../axis/role/Role.js';
+import type { Shape } from '../../axis/shape/Shape.js';
 
 type JsonSchemaType =
   | 'string'
@@ -40,7 +40,7 @@ export type RoleDescriptor = Pick<RoleRules, 'primary' | 'index'> & {
 export type RelationDescriptor = Pick<Relation, 'kind' | 'onDelete'> & { to: string };
 
 /**
- * What a derivation was cut from, and what the cut left — `survived` keyed by the
+ * What a derivation was cut from, and what the cut left — `nameOf` keyed by the
  * ORIGIN's field names. Absent on a declaration that derives from nothing.
  *
  * A dropped field is `null` and never `undefined`: JSON.stringify erases the second,
@@ -48,7 +48,7 @@ export type RelationDescriptor = Pick<Relation, 'kind' | 'onDelete'> & { to: str
  */
 export interface DerivedFrom {
   from: string;
-  survived: Record<string, string | null>;
+  nameOf: Record<string, string | null>;
 }
 
 export interface SchemaDescriptor {

package/src/projection/card/admission.ts

@@ -1,21 +1,26 @@
-import type { ValidationError } from '../../judge/result.js';
+import type { ValidationError } from '../../validation.js';
 
-/** A card is refused by naming what is wrong AND the remedy — never by a bare throw. */
+/**
+ * So a card that cannot be read says what is wrong and what to write instead.
+ * FR : pour qu'une carte illisible dise ce qui cloche et quoi écrire.
+ * `refuse('role.relation.kind is "maybe"', 'Expected one of one, many.')`
+ */
 export function refuse(what: string, fix: string): never {
   throw new Error(`This card cannot be read: ${what}.\n  ${fix}`);
 }
 
 /**
- * A wire value admitted by the axis's OWN judge — legal only where its declared and wire
- * forms are the same value, which `describe: v => v` states.
+ * So a card's axis passes the same validator as a hand-written one, and no second validator exists.
+ * FR : pour qu'un axe d'une carte passe le juge des autres, sans second juge.
+ * `{ update: 'maybe' }` on a card → `lifecycle is malformed — lifecycle.update: Expected 'now' or 'forbidden'`
  */
 export function admitWire(
-  judge: (value: unknown, errors: ValidationError[]) => void,
+  validator: (value: unknown, errors: ValidationError[]) => void,
   value: unknown,
   slot: string,
 ): void {
   const errors: ValidationError[] = [];
-  judge(value, errors);
+  validator(value, errors);
   if (errors.length) {
     refuse(
       `${slot} is malformed — ${errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`,
@@ -24,6 +29,11 @@ export function admitWire(
   }
 }
 
+/**
+ * So a closed set is checked against the list that declares it, never against a copy.
+ * FR : pour qu'un ensemble fermé soit vérifié contre la liste qui le déclare.
+ * `oneOfTokens('many', RELATION_KINDS)` → `true`
+ */
 export const oneOfTokens = <T extends readonly string[]>(
   value: unknown,
   tokens: T,

package/src/projection/card/diff.ts

@@ -1,5 +1,5 @@
-import type { BoundaryRef } from '../../schema/axis/boundary/Boundary.js';
-import type { LifecycleRules } from '../../schema/axis/lifecycle/Lifecycle.js';
+import type { BoundaryRef } from '../../axis/boundary/Boundary.js';
+import type { LifecycleRules } from '../../axis/lifecycle/Lifecycle.js';
 import type { FieldDescriptor, RoleDescriptor } from './Descriptor.js';
 
 /** One named difference, at one place. Each kind exists because a reader asks for it. */

package/src/validator/AdapterFieldValidator.ts

@@ -0,0 +1,40 @@
+import { Validator } from '@cfworker/json-schema';
+import type { Shape } from '../axis/shape/Shape.js';
+import { isObject } from '../lib/utils.js';
+
+/**
+ * The format is DATA, not a TypeScript interface: an interface is erased before a JS
+ * caller, a config or a card from another language could be measured against it.
+ */
+export class AdapterFieldValidator {
+  private constructor(private readonly validator: Validator) {}
+
+  /** Compiled once, at the adapter's own module load. */
+  static of(format: Shape): AdapterFieldValidator {
+    return new AdapterFieldValidator(new Validator(format as object, '2020-12', true));
+  }
+
+  /** `Post.adapters.sql.body.columnType: Property "postgre" does not match …` */
+  assert(entries: unknown, path: string): void {
+    if (entries === undefined) return;
+
+    if (!isObject(entries)) {
+      throw new Error(
+        `${path}: expected an object keyed by field name, got ${typeof entries}.`,
+      );
+    }
+
+    for (const [field, entry] of Object.entries(entries)) {
+      const verdict = this.validator.validate(entry);
+      if (verdict.valid) continue;
+
+      // The engine reports outermost first and ends on `False boolean schema`, which names
+      // nothing. The last unit above that one is the one carrying the offending key.
+      const units = verdict.errors.filter((unit) => unit.keyword !== 'false');
+      const failure = units[units.length - 1] ?? verdict.errors[0];
+      const nested = (failure?.instanceLocation ?? '#').slice(1).replaceAll('/', '.');
+
+      throw new Error(`${path}.${field}${nested}: ${failure?.error ?? 'does not match the format'}`);
+    }
+  }
+}

package/src/{judge/FieldJudge.ts → validator/FieldDeclarationValidator.ts}

@@ -1,14 +1,14 @@
-import { EXTENSION_AXES } from '../schema/axis/Axis.js';
-import { Anatomy } from '../schema/axis/shape/Shape.js';
-import type { Field } from '../schema/fields/Field.js';
-import { isObject } from '../utils.js';
-import type { ValidationError, ValidationResult } from './result.js';
+import { EXTENSION_AXES } from '../axis/Axis.js';
+import { Shapes } from '../axis/shape/Shape.js';
+import type { Field } from '../field/Field.js';
+import { isObject } from '../lib/utils.js';
+import type { ValidationError, ValidationResult } from '../validation.js';
 
-export class FieldJudge {
+export class FieldDeclarationValidator {
   private constructor(private readonly declaration: unknown) {}
 
-  static of(declaration: unknown): FieldJudge {
-    return new FieldJudge(declaration);
+  static of(declaration: unknown): FieldDeclarationValidator {
+    return new FieldDeclarationValidator(declaration);
   }
 
   get verdict(): ValidationResult<Field> {
@@ -28,7 +28,7 @@ export class FieldJudge {
 
     const errors: ValidationError[] = [];
 
-    if (!Anatomy.is(declaration.shape)) {
+    if (!Shapes.is(declaration.shape)) {
       errors.push({
         path: 'shape',
         message: `Every field states a shape — got ${JSON.stringify(declaration.shape)}`,
@@ -37,7 +37,7 @@ export class FieldJudge {
 
     for (const axis of EXTENSION_AXES) {
       const declared = declaration[axis.slot];
-      if (declared !== undefined) axis.judge(declared, errors);
+      if (declared !== undefined) axis.validator(declared, errors);
     }
 
     if (declaration.meta !== undefined) {

package/src/{judge/ValueJudge.ts → validator/FieldValueValidator.ts}

@@ -1,8 +1,8 @@
 import { Validator, format as engineFormats } from '@cfworker/json-schema';
-import { Formats, type FormatPredicate } from '../schema/axis/shape/Formats.js';
-import { Anatomy, type Shape } from '../schema/axis/shape/Shape.js';
-import type { Field } from '../schema/fields/Field.js';
-import type { Checked } from './result.js';
+import { Formats, type FormatPredicate } from '../axis/shape/Formats.js';
+import { Shapes, type Shape } from '../axis/shape/Shape.js';
+import type { Field } from '../field/Field.js';
+import type { Checked } from '../validation.js';
 
 interface ShapePlan {
   validator: Validator;
@@ -10,18 +10,19 @@ interface ShapePlan {
   formatName?: string;
 }
 
-export class ValueJudge {
+export class FieldValueValidator {
   private static readonly plans = new WeakMap<object, ShapePlan>();
 
   private constructor(private readonly field: Field) {}
 
-  static of(field: Field): ValueJudge {
-    return new ValueJudge(field);
+  /** The shape is compiled once and reused, not rebuilt per value. */
+  static of(field: Field): FieldValueValidator {
+    return new FieldValueValidator(field);
   }
 
-  check(value: unknown): Checked {
+  validate(value: unknown): Checked {
     const shape = this.field.shape;
-    const base = Anatomy.of(shape).base;
+    const base = Shapes.of(shape).base;
     if (value !== null) {
       if (base?.type === 'object' && !base.properties) return { value };
       if (
@@ -39,7 +40,7 @@ export class ValueJudge {
         return { error: 'Expected a number' };
       }
     }
-    const plan = ValueJudge.planFor(shape);
+    const plan = FieldValueValidator.planFor(shape);
     const result = plan.validator.validate(value);
     if (!result.valid) return { error: result.errors[0]?.error ?? 'Invalid value' };
     if (plan.custom && typeof value === 'string' && !plan.custom(value)) {
@@ -51,7 +52,7 @@ export class ValueJudge {
   private static planFor(shape: Shape): ShapePlan {
     let plan = this.plans.get(shape);
     if (!plan) {
-      const base = Anatomy.of(shape).base;
+      const base = Shapes.of(shape).base;
       const formatName = base?.type === 'string' ? base.format : undefined;
       plan = {
         validator: new Validator(shape as object, '2020-12', true),
@@ -64,11 +65,11 @@ export class ValueJudge {
   }
 
   private static customFormatOf(name: string): FormatPredicate | undefined {
-    const custom = Formats.resolve(name);
+    const custom = Formats.find(name);
     if (!custom && !(name in engineFormats)) {
       throw new Error(
         `Unknown format: '${name}'. Register it with Formats.register('${name}', …) — ` +
-          `the engine judges ${Object.keys(engineFormats).length} formats natively and this is not one of them.`,
+          `the engine validates ${Object.keys(engineFormats).length} formats natively and this is not one of them.`,
       );
     }
     return custom;

package/src/{judge/RowRefusal.ts → validator/InputRefusal.ts}

@@ -3,15 +3,13 @@
  *
  * A value refused by its own shape carries the engine's message and a decoder refused by
  * user code carries that code's; neither is structural and neither belongs here. These
- * five are `RowJudge`'s own, and a table of cases enumerates them instead of reading the
+ * five are `InputValidator`'s own, and a table of cases enumerates them instead of reading the
  * text of a function — which a minifier rewrites without a word.
  */
-export const RowRefusal = {
+export const InputRefusal = {
   notAnObject: 'Expected an object',
   unknownField: 'Unknown field',
   required: 'Required',
   readOnly: 'Read-only',
   immutable: 'Immutable',
 } as const;
-
-export type RowRefusal = (typeof RowRefusal)[keyof typeof RowRefusal];