@fougere/schema 0.8.2-alpha.0 → 0.8.4-alpha.0

package/src/projection/card/Card.ts

@@ -1,8 +1,7 @@
-import { EXTENSION_AXES, EXTENSION_SLOTS, type Resolver } from '../../axis/Axis.js';
-import { dequal } from 'dequal';
+import { EXTENSION_AXES, type Resolver } from '../../axis/Axis.js';
 import { clean, isObject } from '../../lib/utils.js';
 import { Field, type Fields } from '../../field/Field.js';
-import { deduplicated } from '../../field/FieldSet.js';
+import { SchemaConstraints } from '../../SchemaDefinition.js';
 import { InputValidator } from '../../validator/InputValidator.js';
 import { Schema, type SchemaConstructor } from '../../Schema.js';
 import type { Values, SchemaView } from '../../SchemaView.js';
@@ -13,7 +12,7 @@ import type {
   FieldExtension,
   SchemaDescriptor,
 } from './Descriptor.js';
-import type { Change, Diff, DiffOptions, RenameCandidate, TypeSet } from './diff.js';
+import { compare, type Diff, type DiffOptions } from './diff.js';
 
 type FieldsOf<T> = { [K in keyof T]-?: Field<T[K]> };
 
@@ -42,7 +41,7 @@ export class Card<T = Values<Fields>> {
       'x-fougere-version': 1,
       'x-fougere-vendor': 'fougere',
     };
-    const title = name ?? schema.derivation?.sourceName ?? schema.name;
+    const title = name ?? Card.titleOf(schema);
     if (title) descriptor.title = title;
     if (required.length) descriptor.required = required;
 
@@ -55,6 +54,14 @@ export class Card<T = Values<Fields>> {
     return new Card<T>(descriptor);
   }
 
+  /**
+   * A derivation answers the name it was cut from — `Post.pick('title')` is `Post`, since
+   * a derived class carries `Schema`.
+   */
+  static titleOf(schema: SchemaView): string {
+    return schema.derivation?.sourceName ?? schema.name;
+  }
+
   get origin(): DerivedFrom | undefined {
     return this.descriptor['x-fougere-derived'];
   }
@@ -91,79 +98,22 @@ export class Card<T = Values<Fields>> {
       for (const group of property['x-fougere']?.role?.unique ?? [])
         if (group.length > 1) groups.push([...group]);
     }
-    const schema = Schema.of({ fields, constraints: { unique: deduplicated(groups) } });
+    const schema = Schema.of({ fields, constraints: SchemaConstraints.of(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 changed between two descriptions of the same entity — see {@link compare}. */
   diff(other: Card, options: DiffOptions = {}): Diff {
-    const changes: Change[] = [];
-    const renamed = options.renamed ?? {};
-    const before = this.descriptor.properties ?? {};
-    const after = other.descriptor.properties ?? {};
-    const requiredBefore = new Set(this.descriptor.required ?? []);
-    const requiredAfter = new Set(other.descriptor.required ?? []);
-
-    // Apply a declared rename first so subsequent differences use the new field name.
-    const nameAfter = (field: string): string => renamed[field] ?? field;
-    const removed: string[] = [];
-    for (const [field, descriptor] of Object.entries(before)) {
-      const now = nameAfter(field);
-      const target = after[now];
-      if (target === undefined) {
-        removed.push(field);
-        continue;
-      }
-
-      if (now !== field)
-        changes.push({ kind: 'renamed', from: field, to: now, field: target });
-
-      const wasType = typesOf(descriptor);
-      const isType = typesOf(target);
-      if (!dequal(wasType, isType))
-        changes.push({ kind: 'retyped', field: now, from: wasType, to: isType });
-      else if (!dequal(boundsOf(descriptor), boundsOf(target))) {
-        changes.push({ kind: 'reshaped', field: now, from: descriptor, to: target });
-      }
-
-      const wasRequired = requiredBefore.has(field);
-      const isRequired = requiredAfter.has(now);
-      if (wasRequired !== isRequired) {
-        changes.push({ kind: 'required', field: now, from: wasRequired, to: isRequired });
-      }
-      changes.push(...restated(now, descriptor['x-fougere'], target['x-fougere']));
-    }
-
-    const claimed = new Set(Object.values(renamed));
-    const added = Object.keys(after).filter(
-      (field) => !(field in before) && !claimed.has(field),
-    );
-    for (const field of removed) {
-      changes.push({
-        kind: 'removed',
-        field,
-        from: before[field],
-        required: requiredBefore.has(field),
-      });
-    }
-    for (const field of added) {
-      changes.push({
-        kind: 'added',
-        field,
-        to: after[field],
-        required: requiredAfter.has(field),
-      });
-    }
-
-    return { changes, ambiguous: candidates(removed, added, before, after) };
+    return compare(this.descriptor, other.descriptor, options);
   }
 }
 
 /**
- * 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.
+ * Each axis writes its own wire form under `x-fougere`; `shape` stays outside, plain.
+ * FR : chaque axe écrit sa forme de fil sous `x-fougere` ; `shape` reste dehors, nu.
  * `ref(User)` → `{ role: { relation: { to: 'user', kind: 'one' } } }`
  */
 function describeExtension(field: Field, key: string): FieldExtension | undefined {
@@ -178,11 +128,6 @@ 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 {
   // 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.
@@ -194,8 +139,8 @@ function describeField(field: Field, key: string): FieldDescriptor {
 }
 
 /**
- * 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.
+ * What a derived card says of its root, and of every field the cut kept or dropped.
+ * FR : ce qu'une carte dérivée dit de sa racine, et de chaque champ gardé ou perdu.
  * `Post.pick('title')` → `{ from: 'Post', nameOf: { title: 'title' } }`
  */
 function originOf(schema: SchemaView): DerivedFrom | undefined {
@@ -208,9 +153,9 @@ function originOf(schema: SchemaView): DerivedFrom | undefined {
 }
 
 /**
- * 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
+ * Rebuilds the shape a card carries, refusing a type the standard does not name.
+ * FR : reconstruit la forme que porte une carte, refusant un type hors du standard.
+ * `{ type: 'string', maxLength: 200 }` → the same shape `text({ max: 200 })` states
  */
 function reconstructShape(property: FieldDescriptor): Field['shape'] | undefined {
   const types = Array.isArray(property.type) ? property.type : property.type ? [property.type] : [];
@@ -225,8 +170,8 @@ function reconstructShape(property: FieldDescriptor): Field['shape'] | undefined
 }
 
 /**
- * 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.
+ * Rebuilds a field, each axis reading back what it wrote — the dual of `describeField`.
+ * FR : reconstruit un champ, chaque axe relisant ce qu'il a écrit — le dual de `describeField`.
  * `{ 'x-fougere': { lifecycle: { create: 'now' } } }` → a field stamped at create
  */
 function reconstructField(
@@ -259,86 +204,8 @@ function reconstructField(
 }
 
 /**
- * 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,
-  after: FieldExtension | undefined,
-): Change[] {
-  return EXTENSION_SLOTS.filter((axis) => !dequal(before?.[axis], after?.[axis])).map(
-    (axis) =>
-      ({
-        kind: 'restated',
-        field,
-        axis,
-        from: before?.[axis],
-        to: after?.[axis],
-      }) as Change,
-  );
-}
-
-/**
- * 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, 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[],
-  before: Record<string, FieldDescriptor>,
-  after: Record<string, FieldDescriptor>,
-): RenameCandidate[] {
-  const found: RenameCandidate[] = [];
-  for (const gone of removed) {
-    for (const appeared of added) {
-      if (dequal(shapeOf(before[gone]), shapeOf(after[appeared])))
-        found.push({ removed: gone, added: appeared });
-    }
-  }
-  const was = Object.keys(before);
-  const now = Object.keys(after);
-  const apart = ({ removed: gone, added: appeared }: RenameCandidate): number =>
-    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.
+ * Writes a group onto EVERY member — a wire reader sees one field at a time.
+ * FR : écrit un groupe sur CHAQUE membre — un lecteur du fil ne voit qu'un champ.
  * `carryGroup(properties.listId, ['listId', 'docId'])` → the pair lands under its `role`
  */
 function carryGroup(property: FieldDescriptor | undefined, group: readonly string[]): void {

package/src/projection/card/Descriptor.ts

@@ -2,24 +2,16 @@ 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 { JSONSchema7TypeName } from 'json-schema';
 import type { Shape } from '../../axis/shape/Shape.js';
 
-type JsonSchemaType =
-  | 'string'
-  | 'number'
-  | 'integer'
-  | 'boolean'
-  | 'object'
-  | 'array'
-  | 'null';
-
 type ShapeKeywords = UnionToIntersection<KeywordsOf<Shape>>;
 
 type KeywordsOf<S> = S extends unknown ? Partial<Omit<S, 'type' | 'items' | 'properties'>> : never;
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 
 export type FieldDescriptor = ShapeKeywords & {
-  type?: JsonSchemaType | JsonSchemaType[];
+  type?: JSONSchema7TypeName | JSONSchema7TypeName[];
   items?: FieldDescriptor;
   properties?: Record<string, FieldDescriptor>;
   description?: string;

package/src/projection/card/admission.ts

@@ -1,9 +1,10 @@
-import type { ValidationError } from '../../validation.js';
+import type { ValidationError } from '../../lib/validation.js';
 import { Shapes } from '../../axis/shape/Shape.js';
+import { dotted } from '../../lib/validation.js';
 
 /**
- * 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.
+ * Throws with what is wrong AND what to write: a card's author is in another process.
+ * FR : lève avec ce qui cloche ET quoi écrire : l'auteur d'une carte est ailleurs.
  * `refuse('role.relation.kind is "maybe"', 'Expected one of one, many.')`
  */
 export function refuse(what: string, fix: string): never {
@@ -11,9 +12,10 @@ export function refuse(what: string, fix: string): never {
 }
 
 /**
- * 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'`
+ * Runs a card's axis through the validator a hand-written field goes through, so there is
+ * one judge and not two.
+ * FR : passe l'axe d'une carte par le juge d'un champ écrit à la main : un juge, pas deux.
+ * `{ update: 'maybe' }` → `lifecycle is malformed — lifecycle.update: Expected 'now' or 'forbidden'`
  */
 export function admitWire(
   validator: (value: unknown, errors: ValidationError[]) => void,
@@ -24,15 +26,15 @@ export function admitWire(
   validator(value, errors);
   if (errors.length) {
     refuse(
-      `${slot} is malformed — ${errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`,
+      `${slot} is malformed — ${errors.map((e) => `${dotted(e.path)}: ${e.message}`).join('; ')}`,
       'A card states an axis the way a declaration does.',
     );
   }
 }
 
 /**
- * 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.
+ * Checks a token against the list that declares it, never against a copy written here.
+ * FR : vérifie un mot contre la liste qui le déclare, jamais contre une copie locale.
  * `oneOfTokens('many', RELATION_KINDS)` → `true`
  */
 export const oneOfTokens = <T extends readonly string[]>(
@@ -41,9 +43,9 @@ export const oneOfTokens = <T extends readonly string[]>(
 ): value is T[number] => typeof value === 'string' && (tokens as readonly string[]).includes(value);
 
 /**
- * So a `pattern` the engine cannot compile is refused where the card is read, not at the first row.
- * FR : pour qu'un `pattern` incompilable soit refusé à la lecture de la carte, pas au premier row.
- * `{ type: 'string', pattern: '(' }` → Field 'code' states `pattern: "("`, which is not a regular expression
+ * Compiles every `pattern` at the door, so a bad one is refused here and not at the first row.
+ * FR : compile chaque `pattern` à la porte : un mauvais est refusé ici, pas au premier row.
+ * `{ type: 'string', pattern: '(' }` → `Field 'code' states pattern: "(", which is not a regular expression`
  */
 export function admitPatterns(shape: unknown, subject: string): void {
   for (const pattern of Shapes.patterns(shape)) {

package/src/projection/card/diff.ts

@@ -1,6 +1,8 @@
 import type { BoundaryRef } from '../../axis/boundary/Boundary.js';
 import type { LifecycleRules } from '../../axis/lifecycle/Lifecycle.js';
-import type { FieldDescriptor, RoleDescriptor } from './Descriptor.js';
+import { dequal } from 'dequal';
+import { EXTENSION_SLOTS } from '../../axis/Axis.js';
+import type { FieldDescriptor, FieldExtension, RoleDescriptor, SchemaDescriptor } from './Descriptor.js';
 
 /** One named difference, at one place. Each kind exists because a reader asks for it. */
 export type Change =
@@ -54,3 +56,142 @@ export interface SetDiffOptions {
   /** Declared renames, per entity: `{ post: { body: 'content' } }`. */
   renamed?: Record<string, Record<string, string>>;
 }
+
+/**
+ * What changed between two descriptions of the same entity, read from the wire form alone.
+ * FR : ce qui a changé entre deux descriptions d'une même entité, lu du seul format du fil.
+ * `compare(v1, v2, { renamed: { body: 'content' } })` → one `renamed`, no `ambiguous`
+ */
+export function compare(
+  was: SchemaDescriptor,
+  is: SchemaDescriptor,
+  options: DiffOptions = {},
+): Diff {
+  const changes: Change[] = [];
+  const renamed = options.renamed ?? {};
+  const before = was.properties ?? {};
+  const after = is.properties ?? {};
+  const requiredBefore = new Set(was.required ?? []);
+  const requiredAfter = new Set(is.required ?? []);
+
+  // Apply a declared rename first so subsequent differences use the new field name.
+  const nameAfter = (field: string): string => renamed[field] ?? field;
+  const removed: string[] = [];
+  for (const [field, descriptor] of Object.entries(before)) {
+    const now = nameAfter(field);
+    const target = after[now];
+    if (target === undefined) {
+      removed.push(field);
+      continue;
+    }
+
+    if (now !== field)
+      changes.push({ kind: 'renamed', from: field, to: now, field: target });
+
+    const wasType = typesOf(descriptor);
+    const isType = typesOf(target);
+    if (!dequal(wasType, isType))
+      changes.push({ kind: 'retyped', field: now, from: wasType, to: isType });
+    else if (!dequal(boundsOf(descriptor), boundsOf(target))) {
+      changes.push({ kind: 'reshaped', field: now, from: descriptor, to: target });
+    }
+
+    const wasRequired = requiredBefore.has(field);
+    const isRequired = requiredAfter.has(now);
+    if (wasRequired !== isRequired) {
+      changes.push({ kind: 'required', field: now, from: wasRequired, to: isRequired });
+    }
+    changes.push(...restated(now, descriptor['x-fougere'], target['x-fougere']));
+  }
+
+  const claimed = new Set(Object.values(renamed));
+  const added = Object.keys(after).filter(
+    (field) => !(field in before) && !claimed.has(field),
+  );
+  for (const field of removed) {
+    changes.push({
+      kind: 'removed',
+      field,
+      from: before[field],
+      required: requiredBefore.has(field),
+    });
+  }
+  for (const field of added) {
+    changes.push({
+      kind: 'added',
+      field,
+      to: after[field],
+      required: requiredAfter.has(field),
+    });
+  }
+
+  return { changes, ambiguous: candidates(removed, added, before, after) };
+}
+
+function restated(
+  field: string,
+  before: FieldExtension | undefined,
+  after: FieldExtension | undefined,
+): Change[] {
+  return EXTENSION_SLOTS.filter((axis) => !dequal(before?.[axis], after?.[axis])).map(
+    (axis) =>
+      ({
+        kind: 'restated',
+        field,
+        axis,
+        from: before?.[axis],
+        to: after?.[axis],
+      }) as Change,
+  );
+}
+
+function shapeOf(descriptor: FieldDescriptor): Record<string, unknown> {
+  const { 'x-fougere': _extension, description: _description, ...shape } = descriptor;
+  return shape as Record<string, unknown>;
+}
+
+/**
+ * Sorted, so `['string','null']` and `['null','string']` compare equal, not as a change.
+ * FR : trié, pour que `['string','null']` et `['null','string']` soient égaux.
+ * `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();
+}
+
+/**
+ * The shape without its type, which is what tells a `reshaped` from a `retyped`.
+ * FR : la forme sans son type, ce qui distingue un `reshaped` d'un `retyped`.
+ * `maxLength: 200` → `maxLength: 100` → one `reshaped`, never a `retyped`
+ */
+function boundsOf(descriptor: FieldDescriptor): Record<string, unknown> {
+  const { type: _type, ...rest } = shapeOf(descriptor);
+  return rest;
+}
+
+/**
+ * A removal plus an addition of one shape is REPORTED, never resolved — only `renamed` decides.
+ * FR : une suppression plus un ajout de même forme est RAPPORTÉE, jamais résolue.
+ * `body` gone, `content` appeared → `ambiguous: [{ removed: 'body', added: 'content' }]`
+ */
+function candidates(
+  removed: string[],
+  added: string[],
+  before: Record<string, FieldDescriptor>,
+  after: Record<string, FieldDescriptor>,
+): RenameCandidate[] {
+  const found: RenameCandidate[] = [];
+  for (const gone of removed) {
+    for (const appeared of added) {
+      if (dequal(shapeOf(before[gone]), shapeOf(after[appeared])))
+        found.push({ removed: gone, added: appeared });
+    }
+  }
+  const was = Object.keys(before);
+  const now = Object.keys(after);
+  const apart = ({ removed: gone, added: appeared }: RenameCandidate): number =>
+    Math.abs(now.indexOf(appeared) - was.indexOf(gone));
+  return found.sort((a, b) => apart(a) - apart(b));
+}

package/src/validator/FieldDeclarationValidator.ts

@@ -2,7 +2,7 @@ import { EXTENSION_AXES } from '../axis/Axis.js';
 import { Shapes } from '../axis/shape/Shape.js';
 import type { Field } from '../field/Field.js';
 import { isObject, shown } from '../lib/utils.js';
-import type { ValidationError, ValidationResult } from '../validation.js';
+import type { ValidationError, ValidationResult } from '../lib/validation.js';
 
 export class FieldDeclarationValidator {
   private constructor(private readonly declaration: unknown) {}
@@ -19,7 +19,7 @@ export class FieldDeclarationValidator {
         success: false,
         errors: [
           {
-            path: '.',
+            path: [],
             message: `Expected an object — got ${shown(declaration)}`,
           },
         ],
@@ -30,7 +30,7 @@ export class FieldDeclarationValidator {
 
     if (!Shapes.is(declaration.shape)) {
       errors.push({
-        path: 'shape',
+        path: ['shape'],
         message: `Every field states a shape — got ${shown(declaration.shape)}`,
       });
     }
@@ -43,14 +43,14 @@ export class FieldDeclarationValidator {
     if (declaration.meta !== undefined) {
       if (!isObject(declaration.meta)) {
         errors.push({
-          path: 'meta',
+          path: ['meta'],
           message: `Expected an object — got ${shown(declaration.meta)}`,
         });
       } else if (
         declaration.meta.description !== undefined &&
         typeof declaration.meta.description !== 'string'
       ) {
-        errors.push({ path: 'meta.description', message: 'Expected a string' });
+        errors.push({ path: ['meta', 'description'], message: 'Expected a string' });
       }
     }
 

package/src/validator/FieldValueValidator.ts

@@ -1,8 +1,10 @@
 import { Validator, format as engineFormats } from '@cfworker/json-schema';
+import { Boundary } from '../axis/boundary/Boundary.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';
+import type { Checked } from '../lib/validation.js';
+import type { OutputUnit } from '@cfworker/json-schema';
 
 interface ShapePlan {
   validator: Validator;
@@ -22,33 +24,38 @@ export class FieldValueValidator {
 
   validate(value: unknown): Checked {
     const shape = this.field.shape;
+    const type = Shapes.typeOf(shape);
     const base = Shapes.of(shape).base;
     if (value !== null) {
       if (base?.type === 'object' && !base.properties) return { value };
-      if (
-        base?.type === 'string' &&
-        base.format === 'date-time' &&
-        value instanceof Date
-      ) {
+      if (type === 'date' && value instanceof Date) {
         return Number.isNaN(value.getTime()) ? { error: 'Invalid date' } : { value };
       }
-      if (
-        (base?.type === 'number' || base?.type === 'integer') &&
-        typeof value === 'number' &&
-        Number.isNaN(value)
-      ) {
+      if ((type === 'number' || type === 'integer') && typeof value === 'number' && Number.isNaN(value)) {
         return { error: 'Expected a number' };
       }
     }
     const plan = FieldValueValidator.planFor(shape);
     const result = plan.validator.validate(value);
-    if (!result.valid) return { error: result.errors[0]?.error ?? 'Invalid value' };
+    if (!result.valid) return refusalOf(result.errors);
     if (plan.custom && typeof value === 'string' && !plan.custom(value)) {
       return { error: `String does not match format "${plan.formatName}".` };
     }
     return { value };
   }
 
+  /**
+   * The value admitted, then handed back in the form the domain writes — an ISO string
+   * arrives as a `Date`. `null` passes untouched, and a refusal stops before the codec.
+   */
+  parse(value: unknown): Checked {
+    const checked = this.validate(value);
+    if ('error' in checked) return checked;
+    if (checked.value === null) return { value: null };
+
+    return Boundary.of(this.field).decode(checked.value);
+  }
+
   private static planFor(shape: Shape): ShapePlan {
     let plan = this.plans.get(shape);
     if (!plan) {
@@ -75,3 +82,29 @@ export class FieldValueValidator {
     return custom;
   }
 }
+
+/**
+ * The engine states its refusals outermost first, so `errors[0]` on a nested shape is the
+ * parent's `Property "street" does not match schema.` — true, and never the reason. The
+ * DEEPEST one is the reason, and it is the one that says where.
+ */
+function refusalOf(errors: readonly OutputUnit[]): Checked {
+  const deepest = errors.reduce<OutputUnit | undefined>(
+    (held, one) => (held && depthOf(held) >= depthOf(one) ? held : one),
+    undefined,
+  );
+  if (!deepest) return { error: 'Invalid value' };
+  const path = locationOf(deepest.instanceLocation);
+
+  return path.length > 0 ? { error: deepest.error, path } : { error: deepest.error };
+}
+
+const depthOf = (unit: OutputUnit): number => locationOf(unit.instanceLocation).length;
+
+/** `#/city/zip` — a JSON Pointer fragment, and `~1`/`~0` are how it spells `/` and `~`. */
+const locationOf = (instanceLocation: string): string[] =>
+  instanceLocation
+    .replace(/^#/, '')
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));