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

package/dist/vocabulary/vocabulary.js

@@ -1,43 +1,39 @@
 import { Axes } from '../axis/Axes.js';
 import { dequal } from 'dequal';
 import { SchemaError } from '../SchemaError.js';
-const memberSlots = () => [...Axes.names, 'meta'];
 /**
- * Builds a `rule/` word, which states members on the field it receives.
- * FR : fabrique un mot de `rule/`, qui énonce des membres sur le champ reçu.
+ * Builds a `rule/` word
  * `vocabulary('indexed', () => ({ role: { index: true } }))`
  */
-export function vocabulary(name, states) {
-    return (field) => field.with(merge(name, field, states(field)));
+export function vocabulary(word, states) {
+    return (field) => field.with(merge(word, field, states(field)));
 }
 /**
- * Refuses two words stating one member differently, rather than letting the outer win.
- * FR : refuse deux mots qui énoncent un même membre différemment.
- * `readOnly(writeOnly(text()))` → both apply; `immutable(created())` → throws
+ * Refuses two words stating one member DIFFERENTLY, rather than letting the outer win.
+ * `readOnly(writeOnly(text()))` → both apply, they write two members; `immutable(created())`
+ * too, since both say `update: 'forbidden'`; `immutable(updated())` → throws.
  */
-function merge(name, field, given) {
+function merge(word, field, changes) {
     const merged = {};
-    const stated = given;
-    const held = field;
-    if ('shape' in given)
-        merged.shape = given.shape;
-    for (const slot of memberSlots()) {
-        const members = stated[slot];
+    if ('shape' in changes)
+        merged.shape = changes.shape;
+    for (const name of Axes.names) {
+        const members = changes[name];
         if (members === undefined)
             continue;
-        const already = held[slot];
-        if (typeof members !== 'object' || members === null || typeof already !== 'object') {
-            merged[slot] = members;
+        const already = field.axis(name);
+        if (typeof members !== 'object' || members === null || typeof already !== 'object' || already === null) {
+            merged[name] = members;
             continue;
         }
         for (const [member, value] of Object.entries(members)) {
-            const previous = already?.[member];
+            const previous = already[member];
             if (previous === undefined || dequal(previous, value))
                 continue;
-            throw new SchemaError(`vocabulary: \`${name}\` states ${slot}.${member} = ${JSON.stringify(value)}, but the ` +
+            throw new SchemaError(`vocabulary: \`${word}\` states ${name}.${member} = ${JSON.stringify(value)}, but the ` +
                 `field already states ${JSON.stringify(previous)}. Apply one or the other, not both.`);
         }
-        merged[slot] = { ...already, ...members };
+        merged[name] = { ...already, ...members };
     }
     return merged;
 }

package/dist/vocabulary/vocabulary.js.map

@@ -1 +1 @@
-{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../src/vocabulary/vocabulary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,GAAG,GAAa,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,MAAwC;IAExC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAID;;;;GAIG;AACH,SAAS,KAAK,CAAC,IAAY,EAAE,KAAY,EAAE,KAAqB;IAC9D,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,IAAI,GAAG,KAA2C,CAAC;IACzD,IAAI,OAAO,IAAI,KAAK;QAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAEjD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAwC,CAAC;QAClE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACnF,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;YACvB,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;YACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC;gBAAE,SAAS;YAChE,MAAM,IAAI,WAAW,CACnB,iBAAiB,IAAI,aAAa,IAAI,IAAI,MAAM,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY;gBACrF,wBAAwB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,qCAAqC,CACxF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IAC5C,CAAC;IACD,OAAO,MAAwB,CAAC;AAClC,CAAC"}
+{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../src/vocabulary/vocabulary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,MAAwC;IAExC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAID;;;;GAIG;AACH,SAAS,KAAK,CAAC,IAAY,EAAE,KAAY,EAAE,OAAkC;IAC3E,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,IAAI,OAAO,IAAI,OAAO;QAAE,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAErD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAmC,EAAE,CAAC;QAC5D,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACvG,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;YACvB,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,MAAM,QAAQ,GAAI,OAAmC,CAAC,MAAM,CAAC,CAAC;YAC9D,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC;gBAAE,SAAS;YAChE,MAAM,IAAI,WAAW,CACnB,iBAAiB,IAAI,aAAa,IAAI,IAAI,MAAM,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY;gBACrF,wBAAwB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,qCAAqC,CACxF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IAC5C,CAAC;IAED,OAAO,MAAwB,CAAC;AAClC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/schema",
-  "version": "0.12.1-alpha.0",
+  "version": "0.12.2-alpha.0",
   "description": "The entity and its 4 axes — shape, role, lifecycle, boundary. Subject-owned judgments, edge-safe.",
   "keywords": [
     "fougere",

package/src/Schema.ts

@@ -2,7 +2,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
 
 import { Boundary } from './axis/boundary/Boundary.js';
 import { type Fields } from './field/Fields.js';
-import { type CompositeUnique } from './entity/CompositeUnique.js';
+import { type FieldGroups } from './entity/FieldGroups.js';
 import { type EntityDeclarations } from './entity/EntityDeclarations.js';
 import { type PreviousNames } from './entity/PreviousNames.js';
 import { type EntityAdapters } from './entity/EntityAdapters.js';
@@ -16,6 +16,7 @@ import type { SchemaView } from './SchemaView.js';
 
 import type { SchemaConstructor } from './SchemaConstructor.js';
 import { SchemaError } from './SchemaError.js';
+import type { UnionToIntersection } from './lib/UnionToIntersection.js';
 
 export const ANONYMOUS_SCHEMA_NAME = 'Schema';
 
@@ -53,9 +54,13 @@ export class Schema {
   static getAdapters(): EntityAdapters<Fields> {
     return this.definition.adapterSet.adapters;
   }
-  static getUnique(): CompositeUnique<Fields> | undefined {
+  static getUnique(): FieldGroups<Fields> | undefined {
     return this.definition.constraints.unique;
   }
+
+  static getIndex(): FieldGroups<Fields> | undefined {
+    return this.definition.constraints.index;
+  }
   static getOpts(): ValidateOptions {
     return this.definition.opts;
   }
@@ -78,6 +83,7 @@ export class Schema {
       const decoded = Boundary.of(field).decode(value);
       row[key] = 'message' in decoded ? value : decoded.value;
     }
+
     return row;
   }
 
@@ -90,6 +96,7 @@ export class Schema {
       validate(value: unknown) {
         const verdict = InputValidator.of(fields, opts).validate(value);
         if (verdict.success) return { value: verdict.data };
+
         return {
           issues: verdict.errors.map((e) => ({
             message: e.message,
@@ -138,6 +145,7 @@ export class Schema {
       );
     }
     Object.defineProperty(this, 'name', { value: name, configurable: true });
+
     return this;
   }
 
@@ -168,16 +176,11 @@ export class Schema {
       value: ANONYMOUS_SCHEMA_NAME,
       configurable: true,
     });
+
     return Derived as unknown as SchemaConstructor<Fields>;
   }
 }
 
-type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
-  k: infer I,
-) => void
-  ? I
-  : never;
-
 type Merged<T extends SchemaView[]> = UnionToIntersection<
   T[number] extends { getFields(): infer F } ? F : Fields
 > &

package/src/SchemaConstraints.ts

@@ -1,19 +1,21 @@
 import { type FieldName } from './field/FieldName.js';
 import { type Fields } from './field/Fields.js';
-import { type CompositeUnique } from './entity/CompositeUnique.js';
+import { type FieldGroups } from './entity/FieldGroups.js';
 
 /**
- * What a schema constrains beyond any single field.
- *
- * `unique` is the one member today. It sits under an owner rather than beside `fields`
- * and `opts` because the next rule spanning two fields — a check, an exclusion — is a
- * member here, not an eighth positional argument in a list that has already lost one.
+ * What a schema states beyond any single field: groups of names. `unique` constrains the
+ * rows, `index` says how they are reached — two decisions, and neither implies the other.
+ * They sit under an owner rather than beside `fields` and `opts` because the next rule
+ * spanning two fields — a check, an exclusion — is a member here, not an eighth positional
+ * argument in a list that has already lost one.
  */
 export class SchemaConstraints<TFields extends Fields = Fields> {
-  readonly unique?: CompositeUnique<TFields>;
+  readonly unique?: FieldGroups<TFields>;
+  readonly index?: FieldGroups<TFields>;
 
-  private constructor(unique?: CompositeUnique<TFields>) {
+  private constructor(unique?: FieldGroups<TFields>, index?: FieldGroups<TFields>) {
     if (unique) this.unique = unique;
+    if (index) this.index = index;
   }
 
   static readonly none = new SchemaConstraints();
@@ -24,23 +26,39 @@ export class SchemaConstraints<TFields extends Fields = Fields> {
    * `SchemaConstraints.of([['a','b'], ['a','b']])` → `unique` holds one group
    */
   static of<TFields extends Fields>(
-    groups: readonly (readonly FieldName<TFields>[])[],
+    groups: { unique?: FieldGroups<TFields>; index?: FieldGroups<TFields> },
   ): SchemaConstraints<TFields> {
-    const seen = new Map<string, readonly FieldName<TFields>[]>();
-    for (const group of groups) seen.set(JSON.stringify(group), group);
-
-    return new SchemaConstraints(seen.size ? [...seen.values()] : undefined);
+    return new SchemaConstraints(deduped(groups.unique), deduped(groups.index));
   }
 
-  /** One member gone and the group is gone: it constrained a pair that no longer exists. */
+  /** One member gone and the group is gone: it named a pair that no longer exists. */
   renamed(transform: (key: string) => string | undefined): SchemaConstraints {
-    if (!this.unique) return SchemaConstraints.none;
-    const kept: string[][] = [];
-    for (const group of this.unique) {
-      const renamed = group.map(transform);
-      if (renamed.every((key): key is string => key !== undefined)) kept.push(renamed);
-    }
-
-    return SchemaConstraints.of(kept);
+    return SchemaConstraints.of({
+      unique: survivors(this.unique, transform),
+      index: survivors(this.index, transform),
+    });
   }
 }
+
+const deduped = <TFields extends Fields>(
+  groups?: FieldGroups<TFields>,
+): FieldGroups<TFields> | undefined => {
+  if (!groups) return undefined;
+  const seen = new Map<string, readonly FieldName<TFields>[]>();
+  for (const group of groups) seen.set(JSON.stringify(group), group);
+
+  return seen.size ? [...seen.values()] : undefined;
+};
+
+const survivors = (
+  groups: FieldGroups<Fields> | undefined,
+  transform: (key: string) => string | undefined,
+): string[][] => {
+  const kept: string[][] = [];
+  for (const group of groups ?? []) {
+    const renamed = group.map(transform);
+    if (renamed.every((key): key is string => key !== undefined)) kept.push(renamed);
+  }
+
+  return kept;
+};

package/src/SchemaDefinition.ts

@@ -113,7 +113,7 @@ export class SchemaDefinition {
       ...addressed,
       ...Object.keys(declarations.previous ?? {}),
     ]);
-    const declared = FieldSet.declaring(this.fields, declarations.unique);
+    const declared = FieldSet.declaring(this.fields, declarations);
 
     return this.restated({
       fields: declared.fields,
@@ -123,9 +123,9 @@ export class SchemaDefinition {
       ]),
       previous: declarations.previous ?? this.previous,
       constraints:
-        declarations.unique === undefined
+        declarations.unique === undefined && declarations.index === undefined
           ? this.constraints
-          : SchemaConstraints.of(declared.groups),
+          : SchemaConstraints.of(declared),
     });
   }
 
@@ -199,11 +199,13 @@ export class SchemaDefinition {
   static merged(views: readonly SchemaView[]): SchemaDefinition {
     const fields: Fields = {};
     let opts: ValidateOptions = {};
-    const groups: (readonly string[])[] = [];
+    const groups: { unique: (readonly string[])[]; index: (readonly string[])[] } =
+      { unique: [], index: [] };
     for (const view of views) {
       Object.assign(fields, view.getFields());
       opts = { ...opts, ...view.getOpts() };
-      groups.push(...(view.getUnique() ?? []));
+      groups.unique.push(...(view.getUnique() ?? []));
+      groups.index.push(...(view.getIndex() ?? []));
     }
 
     return SchemaDefinition.derived({

package/src/SchemaError.ts

@@ -1,7 +1,13 @@
 export class SchemaError extends Error {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: { received: unknown }) {
+    super(
+      options ? `${message} — got ${SchemaError.inspect(options.received)}` : message,
+    );
 
     this.name = 'SchemaError';
   }
+
+  static inspect(value: unknown): string {
+    return JSON.stringify(value) ?? typeof value;
+  }
 }

package/src/SchemaView.ts

@@ -1,5 +1,5 @@
 import type { Fields } from './field/Fields.js';
-import type { CompositeUnique } from './entity/CompositeUnique.js';
+import type { FieldGroups } from './entity/FieldGroups.js';
 import type { PreviousNames } from './entity/PreviousNames.js';
 import type { EntityAdapters } from './entity/EntityAdapters.js';
 import type { ValidationResult } from './lib/ValidationResult.js';
@@ -17,7 +17,8 @@ export interface SchemaView<TFields extends Fields = Fields> {
   readonly anchored?: boolean;
   getFields(): TFields;
   getAdapters(): EntityAdapters<TFields>;
-  getUnique(): CompositeUnique<TFields> | undefined;
+  getUnique(): FieldGroups<TFields> | undefined;
+  getIndex(): FieldGroups<TFields> | undefined;
   getOpts(): ValidateOptions;
   validate(input: unknown): ValidationResult<Values<TFields>>;
 }

package/src/axis/Axes.ts

@@ -9,10 +9,10 @@ import { Role } from './role/Role.js';
 class AxisRegistry extends Registry<Axis> {
   private composed?: JsonSchema;
 
-  register(slot: string, axis: Axis): Axis {
+  register(name: string, axis: Axis): Axis {
     this.composed = undefined;
 
-    return super.register(slot, axis);
+    return super.register(name, axis);
   }
 
   /** The document a field declaration is judged against, rebuilt the next time one arrives. */
@@ -27,7 +27,7 @@ class AxisRegistry extends Registry<Axis> {
  * The axes this process reads, and the door an axis declared elsewhere comes through.
  * `Axes.register('tenancy', Tenancy)` — from a `vocabulary/` file, read before `entities/`
  */
-export const Axes = new AxisRegistry('axis', 'call Axes.register(slot, axis)', [
+export const Axes = new AxisRegistry('axis', 'call Axes.register(name, axis)', [
   ['role', Role],
   ['lifecycle', Lifecycle],
   ['boundary', Boundary],

package/src/axis/Axis.ts

@@ -1,9 +1,20 @@
 import type { Format } from '../lib/Format.js';
+import type { Field } from '../field/Field.js';
 import type { ValidationError } from '../lib/ValidationError.js';
 
 export interface Axis {
   readonly format: Format;
 
-  /** What a format cannot state: `role.relation.to` is a function, and JSON holds none. */
-  refusals?(value: unknown): ValidationError[];
+  /**
+   * What a format cannot state: `role.relation.to` is a function, and JSON holds none.
+   * The whole declaration comes with the name, because a contradiction is a PAIR — a
+   * primary key that admits null states one legal `role` beside one legal `shape`.
+   */
+  refusals?(value: unknown, declaration: Record<string, unknown>): ValidationError[];
+
+  /**
+   * Whether this axis alone lets the field be absent from what a caller sends. Asked of every
+   * REGISTERED axis, so a fourth one weighs on it without the validator naming it.
+   */
+  admitsAbsence?(field: Field): boolean;
 }

package/src/axis/boundary/Boundary.ts

@@ -47,9 +47,15 @@ export class Boundary {
 
     const alias = Boundaries.aliases.find(ref);
     if (!alias) throw new SchemaError(`Unknown boundary alias: '${ref}'`);
+
     return new Boundary(alias);
   }
 
+  /** The server fills it, so a caller never sends it. */
+  static admitsAbsence(field: Field): boolean {
+    return this.of(field).readOnly();
+  }
+
   static of(field: Field): Boundary {
     const declared = Boundary.declared(field);
     const derived = Boundary.forShape(field.shape);
@@ -57,6 +63,7 @@ export class Boundary {
       in: declared.rules.in ?? derived.rules.in,
       out: declared.rules.out ?? derived.rules.out,
     };
+
     return new Boundary(rules, {
       decode:
         typeof rules.in === 'object'
@@ -72,6 +79,7 @@ export class Boundary {
   /** `date-time` means a `Date` on both sides, without a word in the entity. */
   static forShape(shape: Shape | undefined): Boundary {
     if (Shapes.typeOf(shape) === 'date') return new Boundary(Boundaries.aliases.resolve('isoDate'));
+
     return new Boundary();
   }
 
@@ -80,11 +88,17 @@ export class Boundary {
     return { in: overrides.in ?? this.rules.in, out: overrides.out ?? this.rules.out };
   }
 
-  get readOnly(): boolean {
+  readOnly(): boolean {
     return this.rules.in === 'closed';
   }
 
-  get writeOnly(): boolean {
+  writeOnly(): boolean {
     return this.rules.out === 'closed';
   }
 }
+
+declare module '../../FougereFieldAxes.js' {
+  interface FougereFieldAxes {
+    readonly boundary?: BoundaryRef;
+  }
+}

package/src/axis/boundary/Decoder.ts

@@ -33,8 +33,10 @@ Boundaries.decoders.register('isoDate', (value) => {
   if (value instanceof Date) return { value };
   if (typeof value === 'string') {
     const date = new Date(value);
+
     return Number.isNaN(date.getTime()) ? { message: 'Invalid date' } : { value: date };
   }
+
   return { message: 'Expected a date' };
 });
 Boundaries.encoders.register('isoDate', (value) =>

package/src/axis/lifecycle/Lifecycle.ts

@@ -23,6 +23,11 @@ export class Lifecycle {
 
   private constructor(private readonly rules: LifecycleRules = {}) {}
 
+  /** `optional()`, a default, a generator: the rule says the value need not arrive. */
+  static admitsAbsence(field: { lifecycle?: LifecycleRules }): boolean {
+    return !this.of(field).requiredAtCreate();
+  }
+
   static of(field: { lifecycle?: LifecycleRules }): Lifecycle {
     return new Lifecycle(field.lifecycle);
   }
@@ -47,19 +52,19 @@ export class Lifecycle {
     return { value: Generators.resolve(rule.generate)() };
   }
 
-  get requiredAtCreate(): boolean {
+  requiredAtCreate(): boolean {
     return this.create === undefined;
   }
 
-  get stampedAtCreate(): boolean {
+  stampedAtCreate(): boolean {
     return this.create === 'now';
   }
 
-  get immutable(): boolean {
+  immutable(): boolean {
     return this.update === 'forbidden';
   }
 
-  get stampedOnUpdate(): boolean {
+  stampedOnUpdate(): boolean {
     return this.update === 'now';
   }
 
@@ -71,3 +76,9 @@ export class Lifecycle {
       : undefined;
   }
 }
+
+declare module '../../FougereFieldAxes.js' {
+  interface FougereFieldAxes {
+    readonly lifecycle?: LifecycleRules;
+  }
+}

package/src/axis/lifecycle/apply.ts

@@ -39,7 +39,7 @@ export function applyUpdate(
   const instant = Date.now();
 
   for (const [name, field] of Object.entries(fields) as [string, Field][]) {
-    if (Lifecycle.of(field).stampedOnUpdate && !(name in values))
+    if (Lifecycle.of(field).stampedOnUpdate() && !(name in values))
       values[name] = new Date(instant);
   }
 

package/src/axis/role/Role.ts

@@ -1,6 +1,8 @@
 import type { Relation } from './Relation.js';
 import type { EntityConstructor } from './EntityConstructor.js';
 import { isObject } from '../../lib/utils.js';
+import { Shapes, type Shape } from '../shape/Shape.js';
+import type { ValidationError } from '../../lib/ValidationError.js';
 import { Format, type Accepted } from '../../lib/Format.js';
 import { ON_DELETE, RELATION_KINDS } from './Relation.js';
 
@@ -20,42 +22,66 @@ export class Role {
     )
     .closed();
 
-  static refusals(value: unknown) {
+  static refusals(value: unknown, declaration: Record<string, unknown> = {}): ValidationError[] {
+    const role = Role.of({ role: isObject(value) ? (value as RoleRules) : undefined });
+    const errors: ValidationError[] = [];
     const relation = isObject(value) ? value.relation : undefined;
-    if (!isObject(relation) || !('to' in relation) || typeof relation.to === 'function') return [];
 
-    return [{ path: ['role', 'relation', 'to'], message: 'Expected a function returning the target entity, such as () => Post' }];
+    if (isObject(relation) && 'to' in relation && typeof relation.to !== 'function')
+      errors.push({
+        path: ['role', 'relation', 'to'],
+        message: 'Expected a function returning the target entity, such as () => Post',
+      });
+
+    if (role.isPrimary() && Shapes.isNullable(declaration.shape as Shape))
+      errors.push({
+        path: ['role', 'primary'],
+        message: 'A primary key admits no null — a row is addressed by it',
+      });
+
+    if (role.isCollection() && (role.isUnique() || role.isIndexed()))
+      errors.push({
+        path: ['role', role.isUnique() ? 'unique' : 'index'],
+        message: 'A collection has no column of its own, so there is nothing to index',
+      });
+
+    return errors;
   }
 
   private constructor(private readonly rules: RoleRules = {}) {}
 
+  /** A collection has no column: the far side of the relation carries the key. */
+  static admitsAbsence(field: { role?: RoleRules }): boolean {
+    return this.of(field).isCollection();
+  }
+
   static of(field: { role?: RoleRules }): Role {
     return new Role(field.role);
   }
 
-  get isPrimary(): boolean {
+  isPrimary(): boolean {
     return this.rules.primary === true;
   }
 
-  get isIndexed(): boolean {
+  isIndexed(): boolean {
     return this.rules.index === true;
   }
 
   /** A field unique on its own. A group spanning several belongs to the schema. */
-  get isUnique(): boolean {
+  isUnique(): boolean {
     return this.rules.unique === true;
   }
 
-  get isCollection(): boolean {
+  isCollection(): boolean {
     return this.rules.relation?.kind === 'many';
   }
 
-  get isReference(): boolean {
+  isReference(): boolean {
     return this.rules.relation?.kind === 'one';
   }
 
   /** Either kind — what a CLI flag and a GraphQL selection both leave out. */
-  get isRelation(): boolean {
+  isRelation(): boolean {
     return this.rules.relation !== undefined;
   }
 
@@ -70,3 +96,9 @@ export class Role {
 }
 
 export type RoleRules = Accepted<typeof Role.format>;
+
+declare module '../../FougereFieldAxes.js' {
+  interface FougereFieldAxes {
+    readonly role?: RoleRules;
+  }
+}