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

package/src/axis/role/RoleAxis.ts

@@ -0,0 +1,115 @@
+import type { Axis, Resolver } from '../Axis.js';
+import { refuse } from '../../card/admission.js';
+import { isObject, oneOfTokens } from '../../judge/ValueForm.js';
+import type { ValidationError } from '../../judge/result.js';
+import { ON_DELETE, RELATION_KINDS, type EntityConstructor, type Relation } from './Relation.js';
+import { type RoleRules } from './Role.js';
+import { FieldGroup } from '../../constraint/FieldGroup.js';
+import { Unique } from '../../constraint/Unique.js';
+import type { RoleDescriptor } from '../../card/Descriptor.js';
+import { lowerFirst } from '../../utils.js';
+
+export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
+  slot: 'role',
+
+  judge(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) {
+      if (value[flag] !== undefined && typeof value[flag] !== 'boolean') {
+        errors.push({
+          path: `role.${flag}`,
+          message: `Expected a boolean — got ${JSON.stringify(value[flag])}`,
+        });
+      }
+    }
+    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);
+  },
+
+  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;
+    if (role.relation) {
+      const target = role.relation.to() as { name?: string };
+      out.relation = {
+        to: lowerFirst(target.name ?? ''),
+        kind: role.relation.kind,
+        ...(role.relation.onDelete ? { onDelete: role.relation.onDelete } : {}),
+      };
+    }
+    return Object.keys(out).length ? out : 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;
+    if (wire.relation) {
+      // `judge` cannot serve here: it demands a thunk where a card carries a name.
+      if (!oneOfTokens(wire.relation.kind, RELATION_KINDS)) {
+        refuse(
+          `role.relation.kind is ${JSON.stringify(wire.relation.kind)}`,
+          `Expected one of ${RELATION_KINDS.join(', ')}.`,
+        );
+      }
+      if (wire.relation.onDelete !== undefined && !oneOfTokens(wire.relation.onDelete, ON_DELETE)) {
+        refuse(
+          `role.relation.onDelete is ${JSON.stringify(wire.relation.onDelete)}`,
+          `Expected one of ${ON_DELETE.join(', ')}.`,
+        );
+      }
+      const name = wire.relation.to;
+      out.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;
+  },
+};
+
+function judgeRelation(relation: unknown, errors: ValidationError[]): void {
+  if (!isObject(relation)) {
+    errors.push({ path: 'role.relation', message: `Expected an object — got ${JSON.stringify(relation)}` });
+    return;
+  }
+  if (!oneOfTokens(relation.kind, RELATION_KINDS)) {
+    errors.push({
+      path: 'role.relation.kind',
+      message: `Expected 'one' or 'many' — got ${JSON.stringify(relation.kind)}`,
+    });
+  }
+  if (typeof relation.to !== 'function') {
+    errors.push({ path: 'role.relation.to', message: 'Expected a thunk returning the target entity' });
+  }
+  if (relation.onDelete !== undefined && !oneOfTokens(relation.onDelete, ON_DELETE)) {
+    errors.push({
+      path: 'role.relation.onDelete',
+      message: `Expected 'cascade', 'restrict' or 'set null' — got ${JSON.stringify(relation.onDelete)}`,
+    });
+  }
+}
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };

package/src/axis/shape/Formats.ts

@@ -0,0 +1,22 @@
+export type StringFormat =
+  | 'date-time'
+  | 'date'
+  | 'time'
+  | 'email'
+  | 'uuid'
+  | 'uri'
+  | (string & {});
+
+export type FormatPredicate = (value: string) => boolean;
+
+export class Formats {
+  private static readonly registry = new Map<string, FormatPredicate>();
+
+  static register(name: string, predicate: FormatPredicate): void {
+    this.registry.set(name, predicate);
+  }
+
+  static resolve(name: string): FormatPredicate | undefined {
+    return this.registry.get(name);
+  }
+}

package/src/axis/shape/Shape.ts

@@ -0,0 +1,91 @@
+import type { JSONSchema7 } from 'json-schema';
+import type { StringFormat } from './Formats.js';
+
+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[] }
+
+export type Shape =
+  | ({ type: Nullably<'string'> } & StringConstraints)
+  | ({ type: Nullably<'number'> | Nullably<'integer'> } & NumericConstraints)
+  | { type: Nullably<'boolean'> }
+  | ({ type: Nullably<'array'> } & ArrayConstraints)
+  | ({ type: Nullably<'object'> } & ObjectConstraints);
+
+const SHAPE_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'] as const;
+
+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];
+  return (
+    names.some((name) => (SHAPE_TYPES as readonly unknown[]).includes(name)) &&
+    names.every((name) => name === 'null' || (SHAPE_TYPES as readonly unknown[]).includes(name))
+  );
+}
+
+type BaseShape =
+  | ({ type: 'string' } & StringConstraints)
+  | ({ type: 'number' | 'integer' } & NumericConstraints)
+  | { type: 'boolean' }
+  | ({ type: 'array' } & ArrayConstraints)
+  | ({ type: 'object' } & ObjectConstraints);
+
+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];
+  }
+  return out;
+}
+
+interface ShapeAnatomy {
+  base?: BaseShape;
+  nullable: boolean;
+}
+
+export class Anatomy {
+  static is(value: unknown): value is Shape {
+    return isShapeImpl(value);
+  }
+
+  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 };
+
+  static of(shape?: Shape): ShapeAnatomy {
+    if (!shape) return this.none;
+    let a = this.cache.get(shape);
+    if (!a) {
+      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 };
+      } else {
+        a = { base: shape as BaseShape, nullable: false };
+      }
+      this.cache.set(shape, a);
+    }
+    return a;
+  }
+
+  static isNullable(shape?: Shape): boolean {
+    return this.of(shape).nullable;
+  }
+}
+
+type Assert<T extends true> = T;
+type ShapeKeys<T> = T extends unknown ? keyof T : never;
+type _ShapeConformsToJsonSchema = Assert<
+  [Exclude<ShapeKeys<Shape>, keyof JSONSchema7>] extends [never] ? true : false
+>;

package/src/card/Bundle.ts

@@ -0,0 +1,80 @@
+import type { Resolver } from '../axis/Axis.js';
+import type { EntityConstructor } from '../axis/role/Relation.js';
+import { lowerFirst } from '../utils.js';
+import type { SchemaView } from '../schema/SchemaView.js';
+import { Card } from './Card.js';
+import type { SchemaBundle, SchemaDescriptor } from './Descriptor.js';
+import type { Diff, SetDiff, SetDiffOptions } from './diff.js';
+
+type SchemaSet = Record<string, SchemaView> | SchemaView[];
+
+/** A portable schema map and the decisions that only a map can make. */
+export class Bundle {
+  private constructor(readonly descriptor: SchemaBundle) {}
+
+  static fromSchemas(schemas: SchemaSet): Bundle {
+    const definitions: Record<string, SchemaDescriptor> = {};
+    const claimedBy = new Map<string, string>();
+    const entries = Array.isArray(schemas)
+      ? schemas.map((schema) => {
+          const card = Card.fromSchema(schema);
+          return { name: card.descriptor.title ?? '', schema };
+        })
+      : Object.entries(schemas).map(([name, schema]) => ({ name, schema }));
+
+    for (const entry of entries) {
+      const key = lowerFirst(entry.name);
+      const previous = claimedBy.get(key);
+      if (previous !== undefined) {
+        throw new Error(
+          `Schemas '${previous}' and '${entry.name}' both claim bundle key '${key}'. `
+          + 'Each schema in a bundle must have a distinct registration key.',
+        );
+      }
+      claimedBy.set(key, entry.name);
+      definitions[key] = Card.fromSchema(entry.schema, key).descriptor;
+    }
+
+    return new Bundle({
+      $defs: definitions,
+      'x-fougere-version': 1,
+      'x-fougere-vendor': 'fougere',
+    });
+  }
+
+  static fromDescriptor(descriptor: SchemaBundle): Bundle {
+    return new Bundle(descriptor);
+  }
+
+  toSchemas(): Record<string, SchemaView> {
+    const map: Record<string, EntityConstructor> = {};
+    const resolve: Resolver = (name) => map[name.toLowerCase()];
+    const schemas: Record<string, SchemaView> = {};
+    for (const [name, descriptor] of Object.entries(this.descriptor.$defs)) {
+      const schema = Card.fromDescriptor(descriptor).toSchema(resolve, name);
+      map[name.toLowerCase()] = schema as unknown as EntityConstructor;
+      schemas[name] = schema;
+    }
+    return schemas;
+  }
+
+  diff(other: Bundle, options: SetDiffOptions = {}): SetDiff {
+    const before = this.descriptor.$defs ?? {};
+    const after = other.descriptor.$defs ?? {};
+    const entities: Record<string, Diff> = {};
+    for (const [name, descriptor] of Object.entries(before)) {
+      const target = after[name];
+      if (target === undefined) continue;
+      const answer = Card.fromDescriptor(descriptor).diff(
+        Card.fromDescriptor(target),
+        { renamed: options.renamed?.[name] ?? {} },
+      );
+      if (answer.changes.length > 0 || answer.ambiguous.length > 0) entities[name] = answer;
+    }
+    return {
+      entitiesAdded: Object.keys(after).filter((name) => !(name in before)),
+      entitiesRemoved: Object.keys(before).filter((name) => !(name in after)),
+      entities,
+    };
+  }
+}

package/src/card/Card.ts

@@ -0,0 +1,256 @@
+import { EXTENSION_AXES, EXTENSION_SLOTS, type Resolver } from '../axis/Axis.js';
+import { dequal } from 'dequal';
+import { clean } from '../utils.js';
+import { Field, type Fields } from '../fields/Field.js';
+import { isObject } from '../judge/ValueForm.js';
+import { RowJudge } from '../judge/RowJudge.js';
+import { Schema, type SchemaConstructor } from '../schema/Schema.js';
+import type { Row, SchemaView } from '../schema/SchemaView.js';
+import { refuse } from './admission.js';
+import type {
+  DerivedFrom,
+  FieldDescriptor,
+  FieldExtension,
+  SchemaDescriptor,
+} from './Descriptor.js';
+import type { Change, Diff, DiffOptions, RenameCandidate, TypeSet } from './diff.js';
+
+type FieldsOf<T> = { [K in keyof T]-?: Field<T[K]> };
+
+/** One portable schema description and every decision made about that description. */
+export class Card<T = Row<Fields>> {
+  private constructor(readonly descriptor: SchemaDescriptor) {}
+
+  static fromSchema<TFields extends Fields>(schema: SchemaView<TFields>, name?: string): Card<Row<TFields>> {
+    const fields = schema.getFields();
+    const judge = RowJudge.of(fields);
+    const properties: Record<string, FieldDescriptor> = {};
+    const required: string[] = [];
+    for (const [key, field] of Object.entries(fields)) {
+      properties[key] = describeField(field, key);
+      if (judge.onAbsent(field) === null) required.push(key);
+    }
+
+    const descriptor: SchemaDescriptor = {
+      type: 'object',
+      properties,
+      'x-fougere-version': 1,
+      'x-fougere-vendor': 'fougere',
+    };
+    const title = name ?? schema.derivation?.sourceName ?? schema.name;
+    if (title) descriptor.title = title;
+    if (required.length) descriptor.required = required;
+
+    const origin = originOf(schema);
+    if (origin) descriptor['x-fougere-derived'] = origin;
+    return new Card<Row<TFields>>(descriptor);
+  }
+
+  static fromDescriptor<T = Row<Fields>>(descriptor: SchemaDescriptor): Card<T> {
+    return new Card<T>(descriptor);
+  }
+
+  /** The root derivation recorded by this card, when its schema was cut from another. */
+  get origin(): DerivedFrom | undefined {
+    return this.descriptor['x-fougere-derived'];
+  }
+
+  /**
+   * Rebuild the live schema. A bundle supplies `resolve` so relation thunks can find the
+   * other reconstructed cards; a lone card deliberately falls back to a name stand-in.
+   */
+  toSchema(resolve?: Resolver, name?: string): SchemaConstructor<FieldsOf<T>> {
+    const descriptor = this.descriptor;
+    const where = name ? `schema '${name}'` : 'this schema';
+    if (!isObject(descriptor)) refuse(`${where} is not an object`, 'A card carries one JSON Schema per door.');
+    const version = descriptor['x-fougere-version'];
+    if (version !== 1) {
+      refuse(
+        `${where} states \`x-fougere-version: ${JSON.stringify(version)}\` and this reader speaks 1`,
+        'A producer and its readers move together: re-sync the consumer, or serve the version it speaks.',
+      );
+    }
+    if (!isObject(descriptor.properties)) {
+      refuse(`${where} carries no \`properties\` object`, 'A schema is its fields; there is nothing to rebuild.');
+    }
+
+    const fields: Fields = {};
+    for (const [key, property] of Object.entries(descriptor.properties)) {
+      fields[key] = reconstructField(property, key, resolve);
+    }
+    const schema = Schema.of({ fields });
+    const title = name ?? descriptor.title;
+    if (title) Object.defineProperty(schema, 'name', { value: title, configurable: true });
+    return schema as unknown as SchemaConstructor<FieldsOf<T>>;
+  }
+
+  /** What must change to turn this card into `other`. */
+  diff(other: Card, options: DiffOptions = {}): Diff {
+    const changes: Change[] = [];
+    const renamed = options.renamed ?? {};
+    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) };
+  }
+}
+
+function describeExtension(field: Field, key: string): FieldExtension | undefined {
+  const extension: Record<string, unknown> = {};
+  for (const axis of EXTENSION_AXES) {
+    const declared = (field as unknown as Record<string, unknown>)[axis.slot];
+    if (declared === undefined) continue;
+    const wire = axis.describe(declared, key);
+    if (wire !== undefined) extension[axis.slot] = wire;
+  }
+  clean(extension);
+  return Object.keys(extension).length ? (extension as FieldExtension) : undefined;
+}
+
+function describeField(field: Field, key: string): FieldDescriptor {
+  const descriptor: FieldDescriptor = {};
+  for (const [shapeKey, value] of Object.entries(field.shape)) {
+    if (value !== undefined) (descriptor as Record<string, unknown>)[shapeKey] = value;
+  }
+  if (field.meta?.description) descriptor.description = field.meta.description;
+  const extension = describeExtension(field, key);
+  if (extension) descriptor['x-fougere'] = extension;
+  return descriptor;
+}
+
+function originOf(schema: SchemaView): DerivedFrom | undefined {
+  const { derivation } = schema;
+  if (!derivation) return undefined;
+  const survived = Object.fromEntries(Object.entries(derivation.survived).map(([key, value]) => [key, value ?? null]));
+  return { from: derivation.sourceName, survived };
+}
+
+function reconstructShape(property: FieldDescriptor): Field['shape'] | undefined {
+  const types = Array.isArray(property.type) ? property.type : property.type ? [property.type] : [];
+  const base = types.find((type) => type !== 'null');
+  if (base === undefined) return undefined;
+  const type = property.type as Field['shape']['type'];
+  if (base === 'array') {
+    const items = property.items ? reconstructShape(property.items) : undefined;
+    return clean({ type, items, minItems: property.minItems, maxItems: property.maxItems }) as Field['shape'];
+  }
+  switch (base) {
+    case 'string':
+      return clean({
+        type,
+        minLength: property.minLength,
+        maxLength: property.maxLength,
+        pattern: property.pattern,
+        enum: property.enum,
+        format: property.format,
+      }) as Field['shape'];
+    case 'number':
+    case 'integer':
+      return clean({ type, minimum: property.minimum, maximum: property.maximum }) as Field['shape'];
+    case 'boolean':
+      return { type } as Field['shape'];
+    default:
+      return clean({ type, properties: property.properties, required: property.required }) as Field['shape'];
+  }
+}
+
+function reconstructField(property: FieldDescriptor, key: string, resolve?: Resolver): Field {
+  const shape = reconstructShape(property);
+  if (!shape) {
+    throw new Error(
+      `Field '${key}': the card carries no \`type\` for it, so there is no shape to rebuild. `
+      + 'A field always states one.',
+    );
+  }
+  const extension = property['x-fougere'];
+  const axes: Record<string, unknown> = {};
+  for (const axis of EXTENSION_AXES) {
+    const wire = (extension as Record<string, unknown> | undefined)?.[axis.slot];
+    if (wire !== undefined) axes[axis.slot] = axis.reconstruct(wire, resolve);
+  }
+  return new Field({
+    shape,
+    ...axes,
+    meta: property.description !== undefined ? { description: property.description } : undefined,
+  } as never);
+}
+
+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, ...shape } = descriptor;
+  return shape as Record<string, unknown>;
+}
+
+function typesOf(descriptor: FieldDescriptor): TypeSet {
+  const type = descriptor.type;
+  if (type === undefined) return [];
+  return (Array.isArray(type) ? [...type] : [type]).sort();
+}
+
+function boundsOf(descriptor: FieldDescriptor): Record<string, unknown> {
+  const { type: _type, ...rest } = shapeOf(descriptor);
+  return rest;
+}
+
+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/card/Descriptor.ts

@@ -0,0 +1,68 @@
+import type { BoundaryRef } from '../axis/boundary/Boundary.js';
+import type { LifecycleRules } from '../axis/lifecycle/Lifecycle.js';
+import type { Relation } from '../axis/role/Relation.js';
+import type { RoleRules } from '../axis/role/Role.js';
+import type { Shape } from '../axis/shape/Shape.js';
+
+type JsonSchemaType =
+  | 'string'
+  | '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[];
+  items?: FieldDescriptor;
+  properties?: Record<string, FieldDescriptor>;
+  description?: string;
+  'x-fougere'?: FieldExtension;
+};
+
+export interface FieldExtension {
+  role?: RoleDescriptor;
+  lifecycle?: LifecycleRules;
+  boundary?: BoundaryRef;
+}
+
+export type RoleDescriptor = Pick<RoleRules, 'primary' | 'index'> & {
+  unique?: string[][];
+  relation?: RelationDescriptor;
+};
+
+export type RelationDescriptor = Pick<Relation, 'kind' | 'onDelete'> & { to: string };
+
+/**
+ * What a derivation was cut from, and what the cut left — `survived` keyed by the
+ * ORIGIN's field names. Absent on a declaration that derives from nothing.
+ *
+ * A dropped field is `null` and never `undefined`: JSON.stringify erases the second,
+ * which would leave the card saying only what remains — what `properties` already says.
+ */
+export interface DerivedFrom {
+  from: string;
+  survived: Record<string, string | null>;
+}
+
+export interface SchemaDescriptor {
+  title?: string;
+  type: 'object';
+  properties: Record<string, FieldDescriptor>;
+  required?: string[];
+  'x-fougere-derived'?: DerivedFrom;
+  'x-fougere-version': 1;
+  'x-fougere-vendor': 'fougere';
+}
+
+export interface SchemaBundle {
+  $defs: Record<string, SchemaDescriptor>;
+  'x-fougere-version': 1;
+  'x-fougere-vendor': 'fougere';
+}