@fougere/schema 0.2.0-alpha.2 → 0.4.0-alpha.0

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';
+}

package/src/card/EntityTypeSource.ts

@@ -0,0 +1,90 @@
+import { upperFirst } from '../utils.js';
+import type { FieldDescriptor, SchemaDescriptor } from './Descriptor.js';
+
+function typeOf(field: FieldDescriptor): string {
+  const types = Array.isArray(field.type) ? field.type : field.type ? [field.type] : [];
+  const nullable = types.includes('null');
+  const base = types.find((t) => t !== 'null');
+  const inner = baseTypeOf(base, field);
+  return nullable ? `${inner} | null` : inner;
+}
+
+function baseTypeOf(base: string | undefined, field: FieldDescriptor): string {
+  if (field.enum?.length) {
+    return field.enum.map((v) => (v === null ? 'null' : JSON.stringify(v))).join(' | ');
+  }
+  switch (base) {
+    case 'string':
+      return field.format === 'date-time' ? 'Date' : 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'array':
+      return field.items ? `${typeOf(field.items)}[]` : 'string[]';
+    case 'object':
+      return field.properties ? objectTypeOf(field.properties, field.required ?? []) : 'Record<string, unknown>';
+    default:
+      return 'unknown';
+  }
+}
+
+function objectTypeOf(properties: Record<string, FieldDescriptor>, required: readonly string[]): string {
+  const members = Object.entries(properties).map(([name, field]) => {
+    const optional = required.includes(name) ? '' : '?';
+    return `${propertyKey(name)}${optional}: ${typeOf(field)}`;
+  });
+  return `{ ${members.join('; ')} }`;
+}
+
+function propertyKey(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+function docCommentOf(text: string | undefined, indent: string): string {
+  if (!text) return '';
+  return `${indent}/** ${text.replace(/\*\//g, '*\\/')} */\n`;
+}
+
+export interface EntityTypeSourceOptions {
+  name?: string;
+  exported?: boolean;
+}
+
+function shapeTypeOf(descriptor: SchemaDescriptor, indent = ''): string {
+  const entries = Object.entries(descriptor.properties ?? {});
+  if (entries.length === 0) return '{}';
+
+  const lines = entries.map(([key, field]) => {
+    const doc = docCommentOf(field.description, `${indent}  `);
+    return `${doc}${indent}  ${propertyKey(key)}: ${typeOf(field)};`;
+  });
+  return `{\n${lines.join('\n')}\n${indent}}`;
+}
+
+export class EntityTypeSource {
+  private constructor(private readonly descriptor: SchemaDescriptor) {}
+
+  static of(descriptor: SchemaDescriptor): EntityTypeSource {
+    return new EntityTypeSource(descriptor);
+  }
+
+  render(options: EntityTypeSourceOptions = {}): string {
+    const name = identifierOf(options.name ?? upperFirst(this.descriptor.title ?? 'Schema'));
+    const exported = options.exported === false ? '' : 'export ';
+    const card = JSON.stringify(this.descriptor, null, 2)
+      .split('\n')
+      .map((line, i) => (i === 0 ? line : `  ${line}`))
+      .join('\n');
+
+    return `${exported}class ${name} extends Card.fromDescriptor<${shapeTypeOf(this.descriptor)}>(${card}).toSchema() {}`;
+  }
+}
+
+function identifierOf(name: string): string {
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
+    throw new Error(`'${name}' is not a TypeScript identifier — it cannot name a generated declaration`);
+  }
+  return name;
+}

package/src/card/FacadeTypeSource.ts

@@ -0,0 +1,55 @@
+import type { SchemaDescriptor } from './Descriptor.js';
+
+export interface FacadeTypeSourceOptions {
+  name?: string;
+  exported?: boolean;
+  rowType?: string;
+}
+
+export interface OpDescriptor {
+  name: string;
+  description?: string;
+  output?: SchemaDescriptor;
+  cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
+}
+
+function propertyKey(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+function docCommentOf(text: string | undefined, indent: string): string {
+  if (!text) return '';
+  return `${indent}/** ${text.replace(/\*\//g, '*\\/')} */\n`;
+}
+
+function returnTypeOf(op: OpDescriptor, rowType: string): string {
+  switch (op.cardinality) {
+    case 'many': return `${rowType}[]`;
+    case 'page': return `${rowType}[] & { total?: number; endCursor?: string; hasMore?: boolean }`;
+    case 'maybe': return `${rowType} | undefined`;
+    case 'one': return rowType;
+    case 'none': return 'unknown';
+    default: return 'unknown';
+  }
+}
+
+export class FacadeTypeSource {
+  private constructor(private readonly operations: readonly OpDescriptor[]) {}
+
+  static of(operations: readonly OpDescriptor[]): FacadeTypeSource {
+    return new FacadeTypeSource(operations);
+  }
+
+  render(options: FacadeTypeSourceOptions = {}): string {
+    const name = options.name ?? 'Facade';
+    const exported = options.exported === false ? '' : 'export ';
+    const rowType = options.rowType ?? 'unknown';
+    const members = this.operations.map((operation) => {
+      const doc = docCommentOf(operation.description, '  ');
+      return `${doc}  ${propertyKey(operation.name)}(invocation?: Invocation): Promise<${returnTypeOf(operation, rowType)}>;`;
+    });
+
+    if (members.length === 0) return `${exported}interface ${name} {}`;
+    return `${exported}interface ${name} {\n${members.join('\n')}\n}`;
+  }
+}

package/src/card/admission.ts

@@ -0,0 +1,25 @@
+import type { ValidationError } from '../judge/result.js';
+
+/** A card is refused by naming what is wrong AND the remedy — never by a bare throw. */
+export function refuse(what: string, fix: string): never {
+  throw new Error(`This card cannot be read: ${what}.\n  ${fix}`);
+}
+
+/**
+ * A wire value admitted by the axis's OWN judge — legal only where its declared and wire
+ * forms are the same value, which `describe: v => v` states.
+ */
+export function admitWire(
+  judge: (value: unknown, errors: ValidationError[]) => void,
+  value: unknown,
+  slot: string,
+): void {
+  const errors: ValidationError[] = [];
+  judge(value, errors);
+  if (errors.length) {
+    refuse(
+      `${slot} is malformed — ${errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`,
+      'A card states an axis the way a declaration does.',
+    );
+  }
+}

package/src/card/diff.ts

@@ -0,0 +1,56 @@
+import type { BoundaryRef } from '../axis/boundary/Boundary.js';
+import type { LifecycleRules } from '../axis/lifecycle/Lifecycle.js';
+import type { FieldDescriptor, RoleDescriptor } from './Descriptor.js';
+
+/** One named difference, at one place. Each kind exists because a reader asks for it. */
+export type Change =
+  /** DDL: add the column. Codec: the old caller never sends it. Boot: refuse when required. */
+  | { kind: 'added'; field: string; to: FieldDescriptor; required: boolean }
+  /** DDL: drop the column. Codec: the old caller still sends it, and it goes nowhere. */
+  | { kind: 'removed'; field: string; from: FieldDescriptor; required: boolean }
+  /** DDL: rename the column. Codec and ORM: one more entry in the field-to-column map. */
+  | { kind: 'renamed'; from: string; to: string; field: FieldDescriptor }
+  /** DDL: alter the type. Codec: convert the value, when it can. */
+  | { kind: 'retyped'; field: string; from: TypeSet; to: TypeSet }
+  /** Same type, different bounds: a CHECK moves, and a value legal yesterday may not be. */
+  | { kind: 'reshaped'; field: string; from: FieldDescriptor; to: FieldDescriptor }
+  /** NOT NULL in either direction. Boot: an old writer cannot fill what it never knew. */
+  | { kind: 'required'; field: string; from: boolean; to: boolean }
+  /** An axis other than shape was restated. */
+  | { kind: 'restated'; field: string; axis: 'role'; from?: RoleDescriptor; to?: RoleDescriptor }
+  | { kind: 'restated'; field: string; axis: 'lifecycle'; from?: LifecycleRules; to?: LifecycleRules }
+  | { kind: 'restated'; field: string; axis: 'boundary'; from?: BoundaryRef; to?: BoundaryRef };
+
+/** A field's declared types, always represented as a set. */
+export type TypeSet = string[];
+
+/** A removal and an addition that could be one rename: same shape, different name. */
+export interface RenameCandidate {
+  removed: string;
+  added: string;
+}
+
+export interface Diff {
+  changes: Change[];
+  /** Questions the comparison refuses to decide without an explicit rename declaration. */
+  ambiguous: RenameCandidate[];
+}
+
+export interface DiffOptions {
+  /** Renames as declared at the time: old name to new name. */
+  renamed?: Record<string, string>;
+}
+
+export interface SetDiff {
+  /** Entities the target bundle has and the source bundle had not. */
+  entitiesAdded: string[];
+  /** Entities the source bundle had and the target bundle has not. */
+  entitiesRemoved: string[];
+  /** Differences for entities present in both bundles; unchanged entities are absent. */
+  entities: Record<string, Diff>;
+}
+
+export interface SetDiffOptions {
+  /** Declared renames, per entity: `{ post: { body: 'content' } }`. */
+  renamed?: Record<string, Record<string, string>>;
+}