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

package/src/axis/role/Role.ts

@@ -0,0 +1,52 @@
+import type { EntityConstructor, Relation } from './Relation.js';
+
+export interface RoleRules {
+  primary?: boolean;
+  index?: boolean;
+  unique?: boolean;
+  relation?: Relation;
+}
+
+export class Role implements RoleRules {
+  readonly primary?: boolean;
+  readonly index?: boolean;
+  readonly unique?: boolean;
+  readonly relation?: Relation;
+
+  private constructor(rules: RoleRules = {}) {
+    this.primary = rules.primary;
+    this.index = rules.index;
+    this.unique = rules.unique;
+    this.relation = rules.relation;
+  }
+
+  static of(field: { role?: RoleRules }): Role {
+    return new Role(field.role);
+  }
+
+  get isPrimary(): boolean {
+    return this.primary === true;
+  }
+
+  get isIndexed(): boolean {
+    return this.index === true;
+  }
+
+  /** A field unique on its own. A group spanning several belongs to the schema. */
+  get isUnique(): boolean {
+    return this.unique === true;
+  }
+
+  get isCollection(): boolean {
+    return this.relation?.kind === 'many';
+  }
+
+  get isReference(): boolean {
+    return this.relation?.kind === 'one';
+  }
+
+  /** Calls `() => Post` so no caller has to. */
+  get target(): EntityConstructor | undefined {
+    return this.relation?.to();
+  }
+}

package/src/{schema/axis → axis}/role/RoleAxis.ts

@@ -1,22 +1,20 @@
 import type { Axis, Resolver } from '../Axis.js';
-import { refuse, oneOfTokens } from '../../../projection/card/admission.js';
-import { isObject, lowerFirst } from '../../../utils.js';
-import type { ValidationError } from '../../../judge/result.js';
+import { refuse, oneOfTokens } from '../../projection/card/admission.js';
+import { isObject, lowerFirst } from '../../lib/utils.js';
+import type { ValidationError } from '../../validation.js';
 import { ON_DELETE, RELATION_KINDS, type EntityConstructor, type Relation } from './Relation.js';
 import { type RoleRules } from './Role.js';
-import { FieldGroup } from '../../fields/constraint/FieldGroup.js';
-import { Unique } from '../../fields/constraint/Unique.js';
-import type { RoleDescriptor } from '../../../projection/card/Descriptor.js';
+import type { RoleDescriptor } from '../../projection/card/Descriptor.js';
 
 export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
   slot: 'role',
 
-  judge(value, errors) {
+  validator(value, errors) {
     if (!isObject(value)) {
       errors.push({ path: 'role', message: `Expected an object — got ${JSON.stringify(value)}` });
       return;
     }
-    for (const flag of ['primary', 'index'] as const) {
+    for (const flag of ['primary', 'index', 'unique'] as const) {
       if (value[flag] !== undefined && typeof value[flag] !== 'boolean') {
         errors.push({
           path: `role.${flag}`,
@@ -24,48 +22,33 @@ export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
         });
       }
     }
-    if (value.rules !== undefined) {
-      const legal =
-        Array.isArray(value.rules) &&
-        value.rules.every(
-          (rule) =>
-            rule instanceof FieldGroup ||
-            (Array.isArray(rule) && rule.every((member) => typeof member === 'string')),
-        );
-      if (!legal) {
-        errors.push({
-          path: 'role.rules',
-          message: 'Expected field groups, or the member lists they denote — string[][]',
-        });
-      }
-    }
-    if (value.relation !== undefined) judgeRelation(value.relation, errors);
+    if (value.relation !== undefined) validateRelation(value.relation, errors);
   },
 
+  /** A card carries the target's NAME: a class cannot cross a process boundary. */
   describe(role, key) {
-    const out: Mutable<RoleDescriptor> = {};
-    if (role.primary) out.primary = true;
-    const unique = (role.rules ?? []).filter((rule) => rule instanceof Unique);
-    if (unique.length) out.unique = unique.map((rule) => [...rule.resolvedOn(key).members]);
-    if (role.index) out.index = true;
+    const descriptor: Mutable<RoleDescriptor> = {};
+    if (role.primary) descriptor.primary = true;
+    if (role.unique) descriptor.unique = [[key]];
+    if (role.index) descriptor.index = true;
     if (role.relation) {
       const target = role.relation.to() as { name?: string };
-      out.relation = {
+      descriptor.relation = {
         to: lowerFirst(target.name ?? ''),
         kind: role.relation.kind,
         ...(role.relation.onDelete ? { onDelete: role.relation.onDelete } : {}),
       };
     }
-    return Object.keys(out).length ? out : undefined;
+    return Object.keys(descriptor).length ? descriptor : undefined;
   },
 
   reconstruct(wire, resolve?: Resolver) {
-    const out: RoleRules = {};
-    if (wire.primary) out.primary = true;
-    if (wire.unique?.length) out.rules = wire.unique.map((group) => new Unique(group));
-    if (wire.index) out.index = true;
+    const rules: RoleRules = {};
+    if (wire.primary) rules.primary = true;
+    if (wire.unique?.some((group) => group.length === 1)) rules.unique = true;
+    if (wire.index) rules.index = true;
     if (wire.relation) {
-      // `judge` cannot serve here: it demands a thunk where a card carries a name.
+      // `validator` cannot serve here: it demands `() => Post` where a card carries a name.
       if (!oneOfTokens(wire.relation.kind, RELATION_KINDS)) {
         refuse(
           `role.relation.kind is ${JSON.stringify(wire.relation.kind)}`,
@@ -79,17 +62,22 @@ export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
         );
       }
       const name = wire.relation.to;
-      out.relation = {
+      rules.relation = {
         to: () => (resolve?.(name) ?? ({ name } as unknown)) as EntityConstructor,
         kind: wire.relation.kind as Relation['kind'],
         ...(wire.relation.onDelete ? { onDelete: wire.relation.onDelete as Relation['onDelete'] } : {}),
       } as RoleRules['relation'];
     }
-    return out;
+    return rules;
   },
 };
 
-function judgeRelation(relation: unknown, errors: ValidationError[]): void {
+/**
+ * So a relation is validated where `() => Post` is required — a card carries a name.
+ * FR : pour qu'une relation soit jugée là où `() => Post` est exigé, contrairement à une carte.
+ * `{ to: User, kind: 'one' }` → error `Expected a function returning the target entity, such as () => Post`
+ */
+function validateRelation(relation: unknown, errors: ValidationError[]): void {
   if (!isObject(relation)) {
     errors.push({ path: 'role.relation', message: `Expected an object — got ${JSON.stringify(relation)}` });
     return;
@@ -101,7 +89,7 @@ function judgeRelation(relation: unknown, errors: ValidationError[]): void {
     });
   }
   if (typeof relation.to !== 'function') {
-    errors.push({ path: 'role.relation.to', message: 'Expected a thunk returning the target entity' });
+    errors.push({ path: 'role.relation.to', message: 'Expected a function returning the target entity, such as () => Post' });
   }
   if (relation.onDelete !== undefined && !oneOfTokens(relation.onDelete, ON_DELETE)) {
     errors.push({

package/src/axis/shape/Formats.ts

@@ -0,0 +1,20 @@
+import { Registry } from '../../lib/Registry.js';
+
+export type StringFormat =
+  | 'date-time'
+  | 'date'
+  | 'time'
+  | 'email'
+  | 'uuid'
+  | 'uri'
+  | (string & {});
+
+export type FormatPredicate = (value: string) => boolean;
+
+/**
+ * String formats the JSON Schema engine does not know. `find` answers `undefined` for
+ * `email` or `uuid`, which it validates on its own.
+ * FR : les formats de chaîne que le moteur ignore ; `find` rend `undefined` pour les siens.
+ * `Formats.register('siret', (v) => /^\d{14}$/.test(v))`
+ */
+export const Formats = new Registry<FormatPredicate>('format');

package/src/{schema/axis → 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,47 +36,74 @@ 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 {
+function collectPatterns(value: unknown, found: string[]): void {
+  if (Array.isArray(value)) {
+    for (const member of value) collectPatterns(member, found);
+
+    return;
+  }
+  if (typeof value !== 'object' || value === null) return;
+
+  const { pattern } = value as { pattern?: unknown };
+  if (typeof pattern === 'string') found.push(pattern);
+
+  for (const member of Object.values(value)) collectPatterns(member, found);
+}
+
+export class Shapes {
   static is(value: unknown): value is Shape {
     return isShapeImpl(value);
   }
 
+  /**
+   * Every `pattern` a shape states, the nested ones included — `items`, `properties`.
+   *
+   * Two readers ask two questions of the same list: the card door asks whether each one
+   * compiles, `fougere check` whether each one backtracks. Neither owns the walk.
+   */
+  static patterns(shape: unknown): string[] {
+    const found: string[] = [];
+    collectPatterns(shape, found);
+
+    return found;
+  }
+
   static nullable(shape: Shape): Shape {
     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

@@ -1,100 +1,8 @@
-import type { FieldName, Fields } from '../schema/fields/Field.js';
-import { isObject } from '../utils.js';
+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>>>>;
-
-/** What `cut` REQUIRES of an augmentation, and the open registry cannot state: addressed by field. */
-type FieldEntries = Record<FieldName<Fields>, unknown>;
-
-type AdapterEntries = Record<string, FieldEntries>;
-
-/**
- * What one schema states per adapter: an adapter name, a field name, then that adapter's own value.
- */
-export class EntityAdapterSet {
-  private constructor(private readonly byAdapter: AdapterEntries) {}
-
-  static of(declared: EntityAdapters<Fields> | undefined): EntityAdapterSet | undefined {
-    if (declared === undefined) return undefined;
-
-    if (!isObject(declared)) {
-      throw new Error(
-        `adapters: expected an object keyed by adapter name, got ${typeof declared}.`,
-      );
-    }
-
-    const byAdapter: AdapterEntries = {};
-
-    for (const [adapter, perField] of Object.entries(declared as AdapterEntries)) {
-      if (perField === undefined) continue;
-
-      if (!isObject(perField)) {
-        throw new Error(
-          `adapters.${adapter}: expected an object keyed by field name, got ${typeof perField}. ` +
-            `What an adapter is handed is addressed by the field it applies to.`,
-        );
-      }
-
-      if (Object.keys(perField).length) byAdapter[adapter] = perField;
-    }
-
-    return EntityAdapterSet.made(byAdapter);
-  }
-
-  /** Several schemas folded into one set; a later source wins, per adapter and per field. */
-  static merged(sources: readonly (EntityAdapters<Fields> | undefined)[]): EntityAdapterSet | undefined {
-    const out: AdapterEntries = {};
-
-    for (const source of sources) {
-      const set = EntityAdapterSet.of(source);
-      if (!set) continue;
-
-      for (const [adapter, perField] of Object.entries(set.byAdapter)) {
-        out[adapter] = { ...out[adapter], ...perField };
-      }
-    }
-
-    return EntityAdapterSet.made(out);
-  }
-
-  /** Every field name these entries address — what a caller checks against its own shape. */
-  get fieldNames(): string[] {
-    return [...new Set(Object.values(this.byAdapter).flatMap((perField) => Object.keys(perField)))];
-  }
-
-  /** The plain object, which is what a reader outside this package receives. */
-  get stated(): EntityAdapters<Fields> {
-    return this.byAdapter as EntityAdapters<Fields>;
-  }
-
-  /**
-   * The entries whose field survives a cut, re-addressed by that field's new name.
-   *
-   * The adapter name is not a field and does not move; only the level below it does. An
-   * entry left on the old name is not an error anywhere downstream — `adapter/sql` looks
-   * it up by the field it is iterating and simply finds nothing.
-   */
-  cut(survives: (key: string) => string | undefined): EntityAdapterSet | undefined {
-    const out: AdapterEntries = {};
-
-    for (const [adapter, perField] of Object.entries(this.byAdapter)) {
-      const mapped: FieldEntries = {};
-
-      for (const [key, entry] of Object.entries(perField)) {
-        const next = survives(key);
-        if (next !== undefined) mapped[next] = entry;
-      }
-
-      if (Object.keys(mapped).length) out[adapter] = mapped;
-    }
-
-    return EntityAdapterSet.made(out);
-  }
-
-  private static made(byAdapter: AdapterEntries): EntityAdapterSet | undefined {
-    return Object.keys(byAdapter).length ? new EntityAdapterSet(byAdapter) : undefined;
-  }
-}
+export type EntityAdapters<TFields extends Fields> = Readonly<
+  Partial<FougereEntityAdapters<FieldName<TFields>>>
+>;

package/src/entity/EntityDeclarations.ts

@@ -1,4 +1,4 @@
-import type { FieldName, Fields } from '../schema/fields/Field.js';
+import type { FieldName, Fields } from '../field/Field.js';
 import type { EntityAdapters } from './EntityAdapters.js';
 
 // Ex: [['title', 'name'], ['id']]

package/src/entity.ts

@@ -1,7 +1,12 @@
-import { type Fields } from './schema/fields/Field.js';
+import { type Fields } from './field/Field.js';
 import { type EntityDeclarations } from './entity/EntityDeclarations.js';
-import { Schema, type SchemaConstructor } from './schema/Schema.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/{schema/fields → field}/Field.ts

@@ -1,19 +1,17 @@
 import type { Shape } from '../axis/shape/Shape.js';
-import { Role, type RoleRules } from '../axis/role/Role.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 { FieldJudge } from '../../judge/FieldJudge.js';
-import { ValueJudge } from '../../judge/ValueJudge.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 judge reads. */
-export type FieldDeclaration = Pick<Field, 'shape' | Axis['slot'] | 'meta'>;
+type FieldDeclaration = Pick<Field, 'shape' | Axis['slot'] | 'meta'>;
 
 export class Field<T = unknown> {
   readonly shape: Shape;
@@ -25,7 +23,7 @@ export class Field<T = unknown> {
   declare readonly _type?: T;
 
   constructor(init: FieldDeclaration, key?: string) {
-    const verdict = FieldJudge.of(init).verdict;
+    const verdict = FieldDeclarationValidator.of(init).verdict;
 
     if (!verdict.success) {
       throw new Error(
@@ -35,14 +33,14 @@ export class Field<T = unknown> {
     }
 
     this.shape = init.shape;
-    this.role = Role.resolvedOn(init.role, key);
+    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 = ValueJudge.of(this).check(create.value);
+      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)} ` +
@@ -52,28 +50,10 @@ export class Field<T = unknown> {
   }
 
   static is(value: unknown): value is Field {
-    return FieldJudge.of(value).verdict.success;
+    return FieldDeclarationValidator.of(value).verdict.success;
   }
 
   with<U = T>(overrides: Partial<FieldDeclaration>): Field<U> {
     return new Field<U>({ ...this, ...overrides });
   }
-
-  rename(map: (key: string) => string | undefined): Field<T> {
-    const rules = this.role?.rules;
-    if (!rules?.length) return this;
-
-    const carried = rules
-      .map((group) => group.rename(map))
-      .filter((group) => group !== null);
-    const unchanged =
-      carried.length === rules.length &&
-      carried.every((group, i) => group.equals(rules[i]!));
-    if (unchanged) return this;
-
-    const { rules: _dropped, ...rest } = this.role!;
-    return this.with({
-      role: carried.length ? { ...rest, rules: carried } : rest,
-    });
-  }
 }

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) => !Object.hasOwn(fields, key));
+      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;
+}