@fougere/schema 0.3.0-alpha.0 → 0.4.0-alpha.0

package/dist/vocabulary/vocabulary.js

@@ -1,6 +1,6 @@
-import { EXTENSION_AXES } from '../axis/Axis.js';
-import { same } from '../same.js';
-const MEMBER_SLOTS = [...EXTENSION_AXES.map((axis) => axis.slot), 'meta'];
+import { EXTENSION_SLOTS } from '../axis/Axis.js';
+import { dequal } from 'dequal';
+const MEMBER_SLOTS = [...EXTENSION_SLOTS, 'meta'];
 export function vocabulary(name, states) {
     return (field) => field.with(merge(name, field, states(field)));
 }
@@ -19,7 +19,7 @@ function merge(name, field, stated) {
         }
         for (const [member, value] of Object.entries(members)) {
             const previous = held?.[member];
-            if (previous === undefined || same(previous, value))
+            if (previous === undefined || dequal(previous, value))
                 continue;
             throw new Error(`vocabulary: \`${name}\` states ${slot}.${member} = ${JSON.stringify(value)}, but the ` +
                 `field already states ${JSON.stringify(previous)}. Apply one or the other, not both.`);

package/dist/vocabulary/vocabulary.js.map

@@ -1 +1 @@
-{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../src/vocabulary/vocabulary.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,YAAY,GAAG,CAAC,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAU,CAAC;AAEnF,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,MAA4C;IAE5C,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,SAAS,KAAK,CAAC,IAAY,EAAE,KAAY,EAAE,MAA0B;IACnE,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,OAAO,IAAI,MAAM;QAAE,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAEhD,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAwC,CAAC;QAChE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAChF,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;YACpB,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,MAAM,QAAQ,GAAG,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC;gBAAE,SAAS;YAC9D,MAAM,IAAI,KAAK,CACb,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,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,GAAyB,CAAC;AACnC,CAAC"}
+{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../src/vocabulary/vocabulary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,YAAY,GAAG,CAAC,GAAG,eAAe,EAAE,MAAM,CAAU,CAAC;AAE3D,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,SAAS,KAAK,CAAC,IAAY,EAAE,KAAY,EAAE,MAAsB;IAC/D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,OAAO,IAAI,MAAM;QAAE,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAEhD,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAwC,CAAC;QAChE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAChF,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;YACpB,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,MAAM,QAAQ,GAAG,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC;gBAAE,SAAS;YAChE,MAAM,IAAI,KAAK,CACb,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,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,GAAqB,CAAC;AAC/B,CAAC"}

package/dist/vocabulary/writeOnly.d.ts

@@ -1,3 +1,3 @@
-import { Field } from '../Field.js';
+import { Field } from '../fields/Field.js';
 export declare const writeOnly: <T>(field: Field<T>) => Field<T>;
 //# sourceMappingURL=writeOnly.d.ts.map

package/dist/vocabulary/writeOnly.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeOnly.d.ts","sourceRoot":"","sources":["../../src/vocabulary/writeOnly.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAEpD,CAAC"}
+{"version":3,"file":"writeOnly.d.ts","sourceRoot":"","sources":["../../src/vocabulary/writeOnly.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAEpD,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fougere/schema",
-  "version": "0.3.0-alpha.0",
-  "description": "The entity and its 4 axes — shape, role, lifecycle, boundary. One judge, edge-safe.",
+  "version": "0.4.0-alpha.0",
+  "description": "The entity and its 4 axes — shape, role, lifecycle, boundary. Subject-owned judgments, edge-safe.",
   "keywords": [
     "fougere",
     "typescript",
@@ -29,13 +29,17 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@paralleldrive/cuid2": "^3.3.0"
+    "@paralleldrive/cuid2": "^3.3.0",
+    "dequal": "^2.0.3"
   },
   "devDependencies": {
+    "@tanstack/form-core": "^1.33.5",
+    "@trpc/server": "^11.18.0",
     "@types/json-schema": "^7.0.15"
   },
   "publishConfig": {

package/src/EntityAdapters.ts

@@ -0,0 +1,95 @@
+import type { FieldName, Fields } from './fields/Field.js';
+import { isObject } from './judge/ValueForm.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> = 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);
+  }
+
+  /** 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;
+  }
+}

package/src/EntityDeclarations.ts

@@ -0,0 +1,19 @@
+import type { FieldName, Fields } from './fields/Field.js';
+import type { EntityAdapters } from './EntityAdapters.js';
+
+export type CompositeUnique<TFields extends Fields> = readonly (readonly FieldName<TFields>[])[];
+
+/** New name to old name: the field states what it WAS, which is how a human writes it. */
+export type PreviousNames<TFields extends Fields> = Partial<
+  Record<FieldName<TFields>, string>
+>;
+
+export interface EntityDeclarations<TFields extends Fields> {
+  unique?: CompositeUnique<TFields>;
+  adapters?: EntityAdapters<TFields>;
+  /**
+   * What a field used to be called — read by `fougere freeze` and by nothing else.
+   * It answers the one question two shapes cannot, and is meant to be deleted after.
+   */
+  previous?: PreviousNames<TFields>;
+}

package/src/axis/Axis.ts

@@ -0,0 +1,25 @@
+import { roleAxis } from './role/RoleAxis.js';
+import { lifecycleAxis } from './lifecycle/LifecycleAxis.js';
+import { boundaryAxis } from './boundary/BoundaryAxis.js';
+import type { ValidationError } from '../judge/result.js';
+
+export interface Axis<Declared = unknown, Wire = unknown> {
+  readonly slot: 'role' | 'lifecycle' | 'boundary';
+
+  judge(value: unknown, errors: ValidationError[]): void;
+
+  describe(value: Declared, key: string): Wire | undefined;
+
+  reconstruct(wire: Wire, resolve?: Resolver): Declared;
+}
+
+export type Resolver = (name: string) => (abstract new (...args: never[]) => unknown) | undefined;
+
+export const EXTENSION_AXES: readonly Axis[] = [
+  roleAxis,
+  lifecycleAxis,
+  boundaryAxis,
+];
+
+/** The slots they occupy: the keys of `x-fougere` on a field descriptor. */
+export const EXTENSION_SLOTS = EXTENSION_AXES.map((axis) => axis.slot);

package/src/axis/Meta.ts

@@ -0,0 +1,3 @@
+export interface Meta {
+  description?: string;
+}

package/src/axis/boundary/Boundaries.ts

@@ -0,0 +1,44 @@
+import type { BoundaryRules } from './Boundary.js';
+
+export type Decoder = (value: unknown) => { value: unknown } | { error: string };
+export type Encoder = (value: unknown) => unknown;
+
+export class Boundaries {
+  private static readonly decoders = new Map<string, Decoder>();
+  private static readonly encoders = new Map<string, Encoder>();
+  private static readonly aliases = new Map<string, BoundaryRules>();
+
+  static registerDecoder(name: string, fn: Decoder): void { this.decoders.set(name, fn); }
+  static registerEncoder(name: string, fn: Encoder): void { this.encoders.set(name, fn); }
+
+  static registerAlias(name: string, boundary: BoundaryRules): void { this.aliases.set(name, boundary); }
+
+  static alias(name: string): BoundaryRules | undefined { return this.aliases.get(name); }
+
+  static decoder(name: string): Decoder { return this.named(this.decoders, name, 'decoder'); }
+  static encoder(name: string): Encoder { return this.named(this.encoders, name, 'encoder'); }
+
+  private static named<T>(registry: Map<string, T>, name: string, kind: string): T {
+    const fn = registry.get(name);
+    if (!fn) {
+      throw new Error(
+        `Unknown boundary ${kind}: '${name}'. Register it with ` +
+          `Boundaries.register${kind[0].toUpperCase()}${kind.slice(1)}('${name}', …).`,
+      );
+    }
+    return fn;
+  }
+}
+
+Boundaries.registerDecoder('isoDate', (value) => {
+  if (value instanceof Date) return { value };
+  if (typeof value === 'string') {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? { error: 'Invalid date' } : { value: d };
+  }
+  return { error: 'Expected a date' };
+});
+Boundaries.registerEncoder('isoDate', (value) =>
+  value instanceof Date ? value.toISOString() : value,
+);
+Boundaries.registerAlias('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } });

package/src/axis/boundary/Boundary.ts

@@ -0,0 +1,69 @@
+import type { Decoder, Encoder } from './Boundaries.js';
+import { Boundaries } from './Boundaries.js';
+import type { Field } from '../../fields/Field.js';
+import { Anatomy, type Shape } from '../shape/Shape.js';
+
+export interface BoundaryRules {
+  in?: 'closed' | { decode: string };
+  out?: 'closed' | { encode: string };
+}
+
+export type BoundaryRef = 'isoDate' | (string & {}) | BoundaryRules;
+
+const identityDecoder: Decoder = (value) => ({ value });
+const identityEncoder: Encoder = (value) => value;
+
+export class Boundary implements BoundaryRules {
+  readonly in?: BoundaryRules['in'];
+  readonly out?: BoundaryRules['out'];
+  readonly decode: Decoder;
+  readonly encode: Encoder;
+
+  private constructor(rules: BoundaryRules = {}, codecs?: { decode: Decoder; encode: Encoder }) {
+    this.in = rules.in;
+    this.out = rules.out;
+    this.decode = codecs?.decode ?? identityDecoder;
+    this.encode = codecs?.encode ?? identityEncoder;
+  }
+
+  static declared(field: Field): Boundary {
+    const ref = field.boundary;
+    if (ref === undefined) return new Boundary();
+    if (typeof ref !== 'string') return new Boundary(ref);
+
+    const alias = Boundaries.alias(ref);
+    if (!alias) throw new Error(`Unknown boundary alias: '${ref}'`);
+    return new Boundary(alias);
+  }
+
+  static of(field: Field): Boundary {
+    const declared = Boundary.declared(field);
+    const derived = Boundary.forShape(field.shape);
+    const rules: BoundaryRules = { in: declared.in ?? derived.in, out: declared.out ?? derived.out };
+    return new Boundary(rules, {
+      decode: typeof rules.in === 'object' ? Boundaries.decoder(rules.in.decode) : identityDecoder,
+      encode: typeof rules.out === 'object' ? Boundaries.encoder(rules.out.encode) : identityEncoder,
+    });
+  }
+
+  static forShape(shape: Shape | undefined): Boundary {
+    const base = Anatomy.of(shape).base;
+    if (base?.type === 'string' && base.format === 'date-time') {
+      return new Boundary(Boundaries.alias('isoDate')!);
+    }
+    return new Boundary();
+  }
+
+  with(overrides: BoundaryRules): Boundary {
+    return new Boundary({ in: overrides.in ?? this.in, out: overrides.out ?? this.out });
+  }
+
+  get readOnly(): boolean {
+    return this.in === 'closed';
+  }
+
+  get writeOnly(): boolean {
+    return this.out === 'closed';
+  }
+
+}

package/src/axis/boundary/BoundaryAxis.ts

@@ -0,0 +1,32 @@
+import type { Axis } from '../Axis.js';
+import { admitWire } from '../../card/admission.js';
+import { isObject } from '../../judge/ValueForm.js';
+import type { BoundaryRef } from './Boundary.js';
+
+export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
+  slot: 'boundary',
+
+  judge(value, errors) {
+    if (typeof value === 'string') return; 
+    if (!isObject(value)) {
+      errors.push({
+        path: 'boundary',
+        message: `Expected an alias name or { in, out } — got ${JSON.stringify(value)}`,
+      });
+      return;
+    }
+    for (const [side, verb] of [['in', 'decode'], ['out', 'encode']] as const) {
+      const rule = value[side];
+      if (rule === undefined || rule === 'closed') continue;
+      if (!isObject(rule) || typeof rule[verb] !== 'string') {
+        errors.push({ path: `boundary.${side}`, message: `Expected 'closed' or { ${verb}: <name> }` });
+      }
+    }
+  },
+
+  describe: (value) => value,
+  reconstruct: (wire) => {
+    admitWire(boundaryAxis.judge, wire, 'boundary');
+    return wire;
+  },
+};

package/src/axis/lifecycle/Clock.ts

@@ -0,0 +1,26 @@
+/**
+ * What "now" means, for the two functions that stamp it.
+ *
+ * The ONE place either of them reads the time, which is what makes it substitutable at
+ * all: `created()`, `updated()` and `create: 'now'` are realized through this and nowhere
+ * else, so a test that needs a stable instant sets it here instead of intercepting `Date`
+ * globally — where Rails had to build `travel_to` over the language.
+ *
+ * A value rather than a mock: nothing here is a channel, and a frozen clock is a fact
+ * about the run, not an interception of a call.
+ */
+export class Clock {
+  private static reading: () => number = Date.now;
+
+  static now(): number {
+    return this.reading();
+  }
+
+  /** Freeze the instant this clock reads. Returns the gesture that restores it. */
+  static freeze(at: number | Date): () => void {
+    const previous = this.reading;
+    const instant = at instanceof Date ? at.getTime() : at;
+    this.reading = () => instant;
+    return () => { this.reading = previous; };
+  }
+}

package/src/axis/lifecycle/Generators.ts

@@ -0,0 +1,46 @@
+import { createId } from '@paralleldrive/cuid2';
+
+export type GeneratorRef = 'cuid2' | 'uuid' | 'nanoid' | (string & {});
+
+const NANOID_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function nanoid(): string {
+  const bytes = new Uint8Array(21);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => NANOID_ALPHABET[byte & 63]).join('');
+}
+
+/**
+ * Who answers a `generate` by name — one registry per process, like `Formats` and
+ * `Boundaries`.
+ *
+ * The three builtins are REGISTERED rather than switched on, which is what brings the
+ * refusal back inside: a registry whose unknown name is refused by a `default:` branch in
+ * its caller does not know what it holds, so it cannot say so.
+ */
+export class Generators {
+  private static readonly registry = new Map<string, () => string>([
+    ['cuid2', createId],
+    ['uuid', () => globalThis.crypto.randomUUID()],
+    ['nanoid', nanoid],
+  ]);
+
+  static register(name: string, fn: () => string): void {
+    this.registry.set(name, fn);
+  }
+
+  /** The generator this name stands for, refused by name when nothing does. */
+  static resolve(ref: GeneratorRef): () => string {
+    const found = this.registry.get(ref);
+    if (found) return found;
+    throw new Error(
+      `Unknown generator '${ref}' — register it with Generators.register('${ref}', fn). ` +
+      `This process answers ${[...this.registry.keys()].join(', ')}.`,
+    );
+  }
+
+  /** Whether a name is answered, for a caller that must not throw to find out. */
+  static answers(ref: GeneratorRef): boolean {
+    return this.registry.has(ref);
+  }
+}

package/src/axis/lifecycle/Lifecycle.ts

@@ -0,0 +1,53 @@
+import type { GeneratorRef } from './Generators.js';
+
+export const CREATE_TOKENS = ['now', 'optional'] as const;
+export const UPDATE_TOKENS = ['now', 'forbidden'] as const;
+
+export interface LifecycleRules {
+  create?: { value: unknown } | { generate: GeneratorRef } | (typeof CREATE_TOKENS)[number];
+  update?: (typeof UPDATE_TOKENS)[number];
+}
+
+export class Lifecycle implements LifecycleRules {
+  readonly create?: LifecycleRules['create'];
+  readonly update?: LifecycleRules['update'];
+
+  private constructor(rules: LifecycleRules = {}) {
+    this.create = rules.create;
+    this.update = rules.update;
+  }
+
+  static of(field: { lifecycle?: LifecycleRules }): Lifecycle {
+    return new Lifecycle(field.lifecycle);
+  }
+
+  get requiredAtCreate(): boolean {
+    return this.create === undefined;
+  }
+
+  get stampedOnce(): boolean {
+    return this.create === 'now' && this.update !== 'now';
+  }
+
+  get immutable(): boolean {
+    return this.update === 'forbidden';
+  }
+
+  get stampedOnUpdate(): boolean {
+    return this.update === 'now';
+  }
+
+  get literal(): { value: unknown } | undefined {
+    const rule = this.create;
+    return typeof rule === 'object' && rule !== null && 'value' in rule
+      ? { value: (rule as { value: unknown }).value }
+      : undefined;
+  }
+
+  get generator(): GeneratorRef | undefined {
+    const rule = this.create;
+    return typeof rule === 'object' && rule !== null && 'generate' in rule
+      ? (rule as { generate: GeneratorRef }).generate
+      : undefined;
+  }
+}

package/src/axis/lifecycle/LifecycleAxis.ts

@@ -0,0 +1,49 @@
+import type { Axis } from '../Axis.js';
+import type { ValidationError } from '../../judge/result.js';
+import { admitWire } from '../../card/admission.js';
+import { isObject, oneOfTokens } from '../../judge/ValueForm.js';
+import { CREATE_TOKENS, UPDATE_TOKENS, type LifecycleRules } from './Lifecycle.js';
+
+export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
+  slot: 'lifecycle',
+
+  judge(value, errors) {
+    if (!isObject(value)) {
+      errors.push({ path: 'lifecycle', message: `Expected an object — got ${JSON.stringify(value)}` });
+      return;
+    }
+    if (value.create !== undefined) judgeCreate(value.create, errors);
+    if (value.update !== undefined && !oneOfTokens(value.update, UPDATE_TOKENS)) {
+      errors.push({
+        path: 'lifecycle.update',
+        message: `Expected 'now' or 'forbidden' — got ${JSON.stringify(value.update)}`,
+      });
+    }
+  },
+
+  describe: (value) => value,
+  reconstruct: (wire) => {
+    admitWire(lifecycleAxis.judge, wire, 'lifecycle');
+    return wire;
+  },
+};
+
+function judgeCreate(rule: unknown, errors: ValidationError[]): void {
+  if (oneOfTokens(rule, CREATE_TOKENS)) return;
+  if (isObject(rule)) {
+    if ('value' in rule) return;
+    if ('generate' in rule) {
+      if (typeof rule.generate !== 'string') {
+        errors.push({
+          path: 'lifecycle.create.generate',
+          message: `Expected a generator name — got ${JSON.stringify(rule.generate)}`,
+        });
+      }
+      return;
+    }
+  }
+  errors.push({
+    path: 'lifecycle.create',
+    message: `Expected 'now', 'optional', { value } or { generate } — got ${JSON.stringify(rule)}`,
+  });
+}

package/src/axis/lifecycle/apply.ts

@@ -0,0 +1,38 @@
+import { Lifecycle } from './Lifecycle.js';
+import { Generators } from './Generators.js';
+import { Clock } from './Clock.js';
+import { type Field, type Fields } from '../../fields/Field.js';
+
+type Row = Record<string, unknown>;
+
+export function applyCreate(fields: Fields, input: Row): Row {
+  const out: Row = { ...input };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (name in out) continue;
+    const rule = Lifecycle.of(field);
+
+    if (rule.create === 'now') out[name] = new Date(instant);
+    else if (rule.literal) out[name] = freshValue(rule.literal.value);
+    else if (rule.generator) out[name] = Generators.resolve(rule.generator)();
+  }
+
+  return out;
+}
+
+function freshValue(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  return structuredClone(value);
+}
+
+export function applyUpdate(fields: Fields, patch: Row): Row {
+  const out: Row = { ...patch };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (Lifecycle.of(field).stampedOnUpdate && !(name in out)) out[name] = new Date(instant);
+  }
+
+  return out;
+}

package/src/axis/role/Relation.ts

@@ -0,0 +1,31 @@
+export type EntityConstructor = abstract new (...args: any[]) => any;
+
+export const RELATION_KINDS = ['one', 'many'] as const;
+export const ON_DELETE = ['cascade', 'restrict', 'set null'] as const;
+
+export interface Relation {
+  to: () => EntityConstructor;
+  kind: (typeof RELATION_KINDS)[number];
+  onDelete?: (typeof ON_DELETE)[number];
+}
+
+/**
+ * How a relation is built — the one place a target becomes a thunk.
+ *
+ * A target arrives as the class or as a function returning it, because a cycle between two
+ * entities can only be written the second way. Recognised by FORM, `getFields` on the
+ * value: a class answers it, a thunk does not.
+ */
+export const Relation = {
+  one(target: EntityConstructor | (() => EntityConstructor), cascade?: boolean): Relation {
+    return { to: thunk(target), kind: 'one', onDelete: cascade ? 'cascade' : undefined };
+  },
+
+  many(target: EntityConstructor | (() => EntityConstructor)): Relation {
+    return { to: thunk(target), kind: 'many' };
+  },
+};
+
+function thunk<E extends EntityConstructor>(target: E | (() => E)): () => E {
+  return 'getFields' in target ? () => target as E : (target as () => E);
+}

package/src/axis/role/Role.ts

@@ -0,0 +1,56 @@
+import { FieldGroup } from "../../constraint/FieldGroup.js";
+import { Unique } from "../../constraint/Unique.js";
+import type { EntityConstructor, Relation } from "./Relation.js";
+
+export interface RoleRules {
+  primary?: boolean;
+  index?: boolean;
+  relation?: Relation;
+  rules?: readonly FieldGroup[];
+}
+
+export class Role implements RoleRules {
+  readonly primary?: boolean;
+  readonly index?: boolean;
+  readonly relation?: Relation;
+  readonly rules?: readonly FieldGroup[];
+
+  private constructor(declared: RoleRules = {}) {
+    this.primary = declared.primary;
+    this.index = declared.index;
+    this.relation = declared.relation;
+    this.rules = declared.rules;
+  }
+
+  static of(field: { role?: RoleRules }): Role {
+    return new Role(field.role);
+  }
+
+  /** A group written with no members means "this field": only the key it is declared under resolves it. */
+  static resolvedOn(role: RoleRules | undefined, key?: string): RoleRules | undefined {
+    let rules = FieldGroup.normalize(role?.rules, (members) => new Unique(members));
+    if (rules && key !== undefined && rules.some((group) => group.isSelf))
+      rules = rules.map((group) => group.resolvedOn(key));
+    return rules === role?.rules ? role : { ...role, rules };
+  }
+
+  get isPrimary(): boolean {
+    return this.primary === true;
+  }
+
+  get isIndexed(): boolean {
+    return this.index === true;
+  }
+
+  get isCollection(): boolean {
+    return this.relation?.kind === "many";
+  }
+
+  get isReference(): boolean {
+    return this.relation?.kind === "one";
+  }
+
+  get target(): EntityConstructor | undefined {
+    return this.relation?.to();
+  }
+}