@fougere/schema 0.9.2-alpha.0 → 0.10.0-alpha.0

package/src/axis/shape/Shape.ts

@@ -1,22 +1,15 @@
 import type { JSONSchema7, JSONSchema7TypeName } from 'json-schema';
-import type { StringFormat } from './Formats.js';
-
-/**
- * The standard's own list, less `null` — a shape states that as the `[T,'null']` union —
- * and with `string` in the three forms every projection here tells apart: a `date()`, a
- * bounded set, and everything else. Those three are the whole of what this package adds.
- */
-export type ShapeType =
-  | Exclude<JSONSchema7TypeName, 'null' | 'string'>
-  | 'text'
-  | 'date'
-  | 'choice';
+import type { StringFormat } from './StringFormat.js';
+import type { ShapeType } from './ShapeType.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[]; additionalProperties?: boolean | Shape; propertyNames?: Shape }
 
 export type Shape =
@@ -40,6 +33,20 @@ interface ShapeParts {
   nullable: boolean;
 }
 
+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
+>;
+
+type _ShapeTypesAreTheStandardsLessNull = Assert<
+  [Exclude<Exclude<JSONSchema7TypeName, 'null'>, (typeof SHAPE_TYPES)[number]>] extends [never]
+    ? true
+    : false
+>;
+
 export class Shapes {
   static is(value: unknown): value is Shape {
     if (typeof value !== 'object' || value === null) return false;
@@ -55,7 +62,7 @@ export class Shapes {
   /**
    * Every `pattern` a shape states, the nested ones included — `items`, `properties`.
    *
-   * Two readers ask two questions of the same list: the card door asks whether each one
+   * Two readers ask two questions of the same list: the card facade asks whether each one
    * compiles, `fougere check` whether each one backtracks. Neither owns the walk.
    */
   static patterns(shape: unknown): string[] {
@@ -129,14 +136,3 @@ export class Shapes {
     return base.enum?.length ? 'choice' : 'text';
   }
 }
-
-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
->;
-type _ShapeTypesAreTheStandardsLessNull = Assert<
-  [Exclude<Exclude<JSONSchema7TypeName, 'null'>, (typeof SHAPE_TYPES)[number]>] extends [never]
-    ? true
-    : false
->;

package/src/axis/shape/ShapeType.ts

@@ -0,0 +1,12 @@
+import type { JSONSchema7TypeName } from 'json-schema';
+
+/**
+ * The standard's own list, less `null` — a shape states that as the `[T,'null']` union —
+ * and with `string` in the three forms every projection here tells apart: a `date()`, a
+ * bounded set, and everything else. Those three are the whole of what this package adds.
+ */
+export type ShapeType =
+  | Exclude<JSONSchema7TypeName, 'null' | 'string'>
+  | 'text'
+  | 'date'
+  | 'choice';

package/src/axis/shape/StringFormat.ts

@@ -0,0 +1,8 @@
+export type StringFormat =
+  | 'date-time'
+  | 'date'
+  | 'time'
+  | 'email'
+  | 'uuid'
+  | 'uri'
+  | (string & {});

package/src/entity/CompositeUnique.ts

@@ -0,0 +1,6 @@
+import type { FieldName } from '../field/FieldName.js';
+import type { Fields } from '../field/Fields.js';
+
+// Ex: [['title', 'name'], ['id']]
+export type CompositeUnique<TFields extends Fields> =
+  readonly (readonly FieldName<TFields>[])[];

package/src/entity/EntityAdapterSet.ts

@@ -1,4 +1,4 @@
-import type { Fields } from '../field/Field.js';
+import type { Fields } from '../field/Fields.js';
 import { isObject } from '../lib/utils.js';
 import type { EntityAdapters } from './EntityAdapters.js';
 

package/src/entity/EntityAdapters.ts

@@ -1,7 +1,6 @@
-import type { FieldName, Fields } from '../field/Field.js';
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-empty-object-type
-export interface FougereEntityAdapters<K extends string> {}
+import type { FieldName } from '../field/FieldName.js';
+import type { Fields } from '../field/Fields.js';
+import type { FougereEntityAdapters } from './FougereEntityAdapters.js';
 
 export type EntityAdapters<TFields extends Fields> = Readonly<
   Partial<FougereEntityAdapters<FieldName<TFields>>>

package/src/entity/EntityDeclarations.ts

@@ -1,13 +1,7 @@
-import type { FieldName, Fields } from '../field/Field.js';
+import type { Fields } from '../field/Fields.js';
 import type { EntityAdapters } from './EntityAdapters.js';
-
-// Ex: [['title', 'name'], ['id']]
-export type CompositeUnique<TFields extends Fields> =
-  readonly (readonly FieldName<TFields>[])[];
-
-export type PreviousNames<TFields extends Fields> = Readonly<
-  Partial<Record<FieldName<TFields>, string>>
->;
+import type { CompositeUnique } from './CompositeUnique.js';
+import type { PreviousNames } from './PreviousNames.js';
 
 export interface EntityDeclarations<TFields extends Fields> {
   adapters?: EntityAdapters<TFields>;

package/src/entity/FougereEntityAdapters.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-empty-object-type
+export interface FougereEntityAdapters<K extends string> {}

package/src/entity/PreviousNames.ts

@@ -0,0 +1,6 @@
+import type { FieldName } from '../field/FieldName.js';
+import type { Fields } from '../field/Fields.js';
+
+export type PreviousNames<TFields extends Fields> = Readonly<
+  Partial<Record<FieldName<TFields>, string>>
+>;

package/src/entity.ts

@@ -1,6 +1,7 @@
-import { type Fields } from './field/Field.js';
+import { type Fields } from './field/Fields.js';
 import { type EntityDeclarations } from './entity/EntityDeclarations.js';
-import { Schema, type SchemaConstructor } from './Schema.js';
+import { Schema } from './Schema.js';
+import { type SchemaConstructor } from './SchemaConstructor.js';
 
 /**
  * The one call everything derives from: the fields, and what the entity states about them.

package/src/field/Field.ts

@@ -1,16 +1,12 @@
 import type { Shape } from '../axis/shape/Shape.js';
-import type { RoleRules } from '../axis/role/Role.js';
-import type { LifecycleRules } from '../axis/lifecycle/Lifecycle.js';
-import type { BoundaryRef } from '../axis/boundary/Boundary.js';
+import type { RoleRules } from '../axis/role/RoleRules.js';
+import type { LifecycleRules } from '../axis/lifecycle/LifecycleRules.js';
+import type { BoundaryRef } from '../axis/boundary/BoundaryRef.js';
 import type { Meta } from './Meta.js';
 import type { Axis } from '../axis/Axis.js';
 import { FieldDeclarationValidator } from '../validator/FieldDeclarationValidator.js';
 import { FieldValueValidator } from '../validator/FieldValueValidator.js';
-import { dotted } from '../lib/validation.js';
-
-export type Fields = Record<string, Field>;
-
-export type FieldName<TFields extends Fields> = Extract<keyof TFields, string>;
+import { dotted } from '../lib/ValidationResult.js';
 
 type FieldDeclaration = Pick<Field, 'shape' | Axis['slot'] | 'meta'>;
 

package/src/field/FieldName.ts

@@ -0,0 +1,3 @@
+import type { Fields } from './Fields.js';
+
+export type FieldName<TFields extends Fields> = Extract<keyof TFields, string>;

package/src/field/FieldSet.ts

@@ -1,6 +1,8 @@
 import { Role } from '../axis/role/Role.js';
-import type { CompositeUnique } from '../entity/EntityDeclarations.js';
-import { Field, type FieldName, type Fields } from './Field.js';
+import type { CompositeUnique } from '../entity/CompositeUnique.js';
+import { Field } from './Field.js';
+import { type FieldName } from './FieldName.js';
+import { type Fields } from './Fields.js';
 
 export class FieldSet<TFields extends Fields = Fields> {
   private constructor(private readonly fields: TFields) {}

package/src/field/Fields.ts

@@ -0,0 +1,3 @@
+import type { Field } from './Field.js';
+
+export type Fields = Record<string, Field>;

package/src/index.ts

@@ -2,41 +2,43 @@ export { entity } from './entity.js';
 
 export * from './vocabulary/index.js';
 
-export { Schema, ANONYMOUS_SCHEMA_NAME, type SchemaConstructor } from './Schema.js';
+export { ANONYMOUS_SCHEMA_NAME, Schema } from './Schema.js';
+export { type SchemaConstructor } from './SchemaConstructor.js';
 export { type SchemaView } from './SchemaView.js';
-export { Field, type Fields } from './field/Field.js';
+export { Field } from './field/Field.js';
+export { type Fields } from './field/Fields.js';
 export { FieldSet } from './field/FieldSet.js';
-export { type Shape, type ShapeType, Shapes } from './axis/shape/Shape.js';
+export { type Shape } from './axis/shape/Shape.js';
+export { type ShapeType } from './axis/shape/ShapeType.js';
+export { Shapes } from './axis/shape/Shape.js';
 export { Role } from './axis/role/Role.js';
-export { type EntityConstructor } from './axis/role/Relation.js';
+export { type EntityConstructor } from './axis/role/EntityConstructor.js';
 export { Lifecycle } from './axis/lifecycle/Lifecycle.js';
 export { Boundary } from './axis/boundary/Boundary.js';
 export { applyCreate, applyUpdate } from './axis/lifecycle/apply.js';
 export { InputRefusal } from './validator/InputRefusal.js';
-export { dotted, type ValidationError, type ValidationResult } from './lib/validation.js';
+export { type ValidationError } from './lib/ValidationError.js';
+export { dotted, type ValidationResult } from './lib/ValidationResult.js';
 
 export { Card } from './projection/card/Card.js';
 export { Bundle } from './projection/card/Bundle.js';
 export { Visibility } from './projection/Visibility.js';
-export { Cases, type ValidationCase } from './projection/Cases.js';
-export type {
-  SchemaBundle,
-  SchemaDescriptor,
-  FieldDescriptor,
-} from './projection/card/Descriptor.js';
-export type {
-  Change,
-  Diff,
-  SetDiff,
-  SetDiffOptions,
-} from './projection/card/diff.js';
+export { Cases } from './projection/Cases.js';
+export { type ValidationCase } from './projection/ValidationCase.js';
+export type { FieldDescriptor } from './projection/card/FieldDescriptor.js';
+export type { SchemaBundle } from './projection/card/SchemaBundle.js';
+export type { SchemaDescriptor } from './projection/card/SchemaDescriptor.js';
+export type { Change } from './projection/card/Change.js';
+export type { Diff } from './projection/card/Diff.js';
+export type { SetDiff } from './projection/card/SetDiff.js';
+export type { SetDiffOptions } from './projection/card/SetDiffOptions.js';
 
 export * from './lib/index.js';
 export { Formats } from './axis/shape/Formats.js';
 export { Generators } from './axis/lifecycle/Generators.js';
-export { Boundaries } from './axis/boundary/Boundaries.js';
+export { Boundaries } from './axis/boundary/Decoder.js';
 export { Clock } from './axis/lifecycle/Clock.js';
-export { type FougereEntityAdapters } from './entity/EntityAdapters.js';
+export { type FougereEntityAdapters } from './entity/FougereEntityAdapters.js';
 export { InputValidator } from './validator/InputValidator.js';
 export { FieldValueValidator } from './validator/FieldValueValidator.js';
 export { AdapterFieldValidator } from './validator/AdapterFieldValidator.js';

package/src/lib/Checked.ts

@@ -0,0 +1,5 @@
+/**
+ * A field's verdict. `path` is where INSIDE the value the refusal happened — empty when the
+ * field itself is refused, `['street']` when the shape below it is.
+ */
+export type Checked = { value: unknown } | { error: string; path?: readonly string[] };

package/src/lib/ValidationError.ts

@@ -0,0 +1,9 @@
+export interface ValidationError {
+  /**
+   * Where the refusal happened: the field, then where under it the shape refused.
+   * Empty when the input itself is refused. Segments, never a sentence — a field may
+   * legally be named `a.b`, and re-parsing a joined path invents a segment it never had.
+   */
+  path: readonly string[];
+  message: string;
+}

package/src/lib/ValidationResult.ts

@@ -0,0 +1,11 @@
+import type { ValidationError } from './ValidationError.js';
+
+export type ValidationResult<T> =
+  | { success: true; data: T }
+  | { success: false; errors: ValidationError[] };
+
+/**
+ * A path as a message writes it — `addr.street`. One rendering among others, and the
+ * reason the value stays segmented: this one cannot be read back.
+ */
+export const dotted = (path: readonly string[]): string => path.join('.');

package/src/projection/Cases.ts

@@ -6,23 +6,7 @@ import type { Field } from '../field/Field.js';
 import type { SchemaView } from '../SchemaView.js';
 import { InputValidator } from '../validator/InputValidator.js';
 import { InputRefusal } from '../validator/InputRefusal.js';
-
-/**
- * One input, and what the validator must answer.
- *
- * `expect` carries the PATH of the field at fault and never the message. We know which
- * field must be refused because we are the ones who broke it; naming the message would
- * make this list a second validator, and the two would then have to be kept in step by hand —
- * which is the duplication the whole thing exists to remove.
- */
-export interface ValidationCase {
-  /** What this input does, in one clause — carried into the assertion so a failure reads. */
-  why: string;
-  input: unknown;
-  /** Judged as an update rather than a creation. */
-  patch: boolean;
-  expect: 'accept' | { reject: string };
-}
+import type { ValidationCase } from './ValidationCase.js';
 
 /**
  * A value of the wrong type, so every field yields at least one case whatever it declares.

package/src/projection/ValidationCase.ts

@@ -0,0 +1,16 @@
+/**
+ * One input, and what the validator must answer.
+ *
+ * `expect` carries the PATH of the field at fault and never the message. We know which
+ * field must be refused because we are the ones who broke it; naming the message would
+ * make this list a second validator, and the two would then have to be kept in step by hand —
+ * which is the duplication the whole thing exists to remove.
+ */
+export interface ValidationCase {
+  /** What this input does, in one clause — carried into the assertion so a failure reads. */
+  why: string;
+  input: unknown;
+  /** Judged as an update rather than a creation. */
+  patch: boolean;
+  expect: 'accept' | { reject: string };
+}

package/src/projection/Visibility.ts

@@ -1,7 +1,7 @@
 import { Boundary } from '../axis/boundary/Boundary.js';
 import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
 import { Role } from '../axis/role/Role.js';
-import type { Fields } from '../field/Field.js';
+import type { Fields } from '../field/Fields.js';
 
 export class Visibility {
   private constructor(private readonly fields: Fields) {}

package/src/projection/card/Bundle.ts

@@ -1,10 +1,13 @@
-import type { Resolver } from '../../axis/Axis.js';
-import type { EntityConstructor } from '../../axis/role/Relation.js';
+import type { Resolver } from '../../axis/Resolver.js';
+import type { EntityConstructor } from '../../axis/role/EntityConstructor.js';
 import { lowerFirst } from '../../lib/utils.js';
 import type { SchemaView } from '../../SchemaView.js';
 import { Card } from './Card.js';
-import type { SchemaBundle, SchemaDescriptor } from './Descriptor.js';
-import type { Diff, SetDiff, SetDiffOptions } from './diff.js';
+import type { SchemaBundle } from './SchemaBundle.js';
+import type { SchemaDescriptor } from './SchemaDescriptor.js';
+import type { Diff } from './Diff.js';
+import type { SetDiff } from './SetDiff.js';
+import type { SetDiffOptions } from './SetDiffOptions.js';
 
 type SchemaSet = Record<string, SchemaView> | SchemaView[];
 

package/src/projection/card/Card.ts

@@ -1,18 +1,21 @@
-import { EXTENSION_AXES, type Resolver } from '../../axis/Axis.js';
+import { EXTENSION_AXES } from '../../axis/Axis.js';
+import { type Resolver } from '../../axis/Resolver.js';
 import { clean, isObject } from '../../lib/utils.js';
-import { Field, type Fields } from '../../field/Field.js';
-import { SchemaConstraints } from '../../SchemaDefinition.js';
+import { Field } from '../../field/Field.js';
+import { type Fields } from '../../field/Fields.js';
+import { SchemaConstraints } from '../../SchemaConstraints.js';
 import { InputValidator } from '../../validator/InputValidator.js';
-import { Schema, type SchemaConstructor } from '../../Schema.js';
-import type { Values, SchemaView } from '../../SchemaView.js';
+import { Schema } from '../../Schema.js';
+import { type SchemaConstructor } from '../../SchemaConstructor.js';
+import type { SchemaView } from '../../SchemaView.js';
+import type { Values } from '../../Values.js';
 import { admitPatterns, refuse } from './admission.js';
-import type {
-  DerivedFrom,
-  FieldDescriptor,
-  FieldExtension,
-  SchemaDescriptor,
-} from './Descriptor.js';
-import { compare, type Diff, type DiffOptions } from './diff.js';
+import type { DerivedFrom } from './DerivedFrom.js';
+import type { FieldDescriptor } from './FieldDescriptor.js';
+import type { FieldExtension } from './FieldExtension.js';
+import type { SchemaDescriptor } from './SchemaDescriptor.js';
+import { compare, type Diff } from './Diff.js';
+import { type DiffOptions } from './DiffOptions.js';
 
 type FieldsOf<T> = { [K in keyof T]-?: Field<T[K]> };
 
@@ -74,7 +77,7 @@ export class Card<T = Values<Fields>> {
     const descriptor = this.descriptor;
     const subject = name ? `schema '${name}'` : 'this schema';
     if (!isObject(descriptor))
-      refuse(`${subject} is not an object`, 'A card carries one JSON Schema per door.');
+      refuse(`${subject} is not an object`, 'A card carries one JSON Schema per facade.');
     const version = descriptor['x-fougere-version'];
     if (version !== 1) {
       refuse(

package/src/projection/card/Change.ts

@@ -0,0 +1,24 @@
+import type { BoundaryRef } from '../../axis/boundary/BoundaryRef.js';
+import type { LifecycleRules } from '../../axis/lifecycle/LifecycleRules.js';
+import type { FieldDescriptor } from './FieldDescriptor.js';
+import type { RoleDescriptor } from './RoleDescriptor.js';
+import type { TypeSet } from './TypeSet.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 storage: 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 };

package/src/projection/card/DerivedFrom.ts

@@ -0,0 +1,11 @@
+/**
+ * What a derivation was cut from, and what the cut left — `nameOf` 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;
+  nameOf: Record<string, string | null>;
+}

package/src/projection/card/{diff.ts → Diff.ts}

@@ -1,36 +1,13 @@
-import type { BoundaryRef } from '../../axis/boundary/Boundary.js';
-import type { LifecycleRules } from '../../axis/lifecycle/Lifecycle.js';
 import { dequal } from 'dequal';
 import { EXTENSION_SLOTS } from '../../axis/Axis.js';
-import type { FieldDescriptor, FieldExtension, RoleDescriptor, SchemaDescriptor } from './Descriptor.js';
+import type { FieldDescriptor } from './FieldDescriptor.js';
+import type { FieldExtension } from './FieldExtension.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 storage: 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;
-}
+import type { SchemaDescriptor } from './SchemaDescriptor.js';
+import type { Change } from './Change.js';
+import type { TypeSet } from './TypeSet.js';
+import type { RenameCandidate } from './RenameCandidate.js';
+import type { DiffOptions } from './DiffOptions.js';
 
 export interface Diff {
   changes: Change[];
@@ -38,25 +15,6 @@ export interface Diff {
   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>>;
-}
-
 /**
  * What changed between two descriptions of the same entity, read from the wire form alone.
  * FR : ce qui a changé entre deux descriptions d'une même entité, lu du seul format du fil.

package/src/projection/card/DiffOptions.ts

@@ -0,0 +1,4 @@
+export interface DiffOptions {
+  /** Renames as declared at the time: old name to new name. */
+  renamed?: Record<string, string>;
+}

package/src/projection/card/FieldDescriptor.ts

@@ -0,0 +1,11 @@
+import type { ShapeKeywords } from './ShapeKeywords.js';
+import type { JSONSchema7TypeName } from 'json-schema';
+import type { FieldExtension } from './FieldExtension.js';
+
+export type FieldDescriptor = ShapeKeywords & {
+  type?: JSONSchema7TypeName | JSONSchema7TypeName[];
+  items?: FieldDescriptor;
+  properties?: Record<string, FieldDescriptor>;
+  description?: string;
+  'x-fougere'?: FieldExtension;
+};

package/src/projection/card/FieldExtension.ts

@@ -0,0 +1,9 @@
+import type { BoundaryRef } from '../../axis/boundary/BoundaryRef.js';
+import type { LifecycleRules } from '../../axis/lifecycle/LifecycleRules.js';
+import type { RoleDescriptor } from './RoleDescriptor.js';
+
+export interface FieldExtension {
+  role?: RoleDescriptor;
+  lifecycle?: LifecycleRules;
+  boundary?: BoundaryRef;
+}

package/src/projection/card/RelationDescriptor.ts

@@ -0,0 +1,3 @@
+import type { Relation } from '../../axis/role/Relation.js';
+
+export type RelationDescriptor = Pick<Relation, 'kind' | 'onDelete'> & { to: string };

package/src/projection/card/RenameCandidate.ts

@@ -0,0 +1,5 @@
+/** A removal and an addition that could be one rename: same shape, different name. */
+export interface RenameCandidate {
+  removed: string;
+  added: string;
+}

package/src/projection/card/RoleDescriptor.ts

@@ -0,0 +1,7 @@
+import type { RoleRules } from '../../axis/role/RoleRules.js';
+import type { RelationDescriptor } from './RelationDescriptor.js';
+
+export type RoleDescriptor = Pick<RoleRules, 'primary' | 'index'> & {
+  unique?: string[][];
+  relation?: RelationDescriptor;
+};

package/src/projection/card/SchemaBundle.ts

@@ -0,0 +1,7 @@
+import type { SchemaDescriptor } from './SchemaDescriptor.js';
+
+export interface SchemaBundle {
+  $defs: Record<string, SchemaDescriptor>;
+  'x-fougere-version': 1;
+  'x-fougere-vendor': 'fougere';
+}

package/src/projection/card/SchemaDescriptor.ts

@@ -0,0 +1,12 @@
+import type { FieldDescriptor } from './FieldDescriptor.js';
+import type { DerivedFrom } from './DerivedFrom.js';
+
+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';
+}

package/src/projection/card/SetDiff.ts

@@ -0,0 +1,10 @@
+import type { Diff } from './Diff.js';
+
+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>;
+}

package/src/projection/card/SetDiffOptions.ts

@@ -0,0 +1,4 @@
+export interface SetDiffOptions {
+  /** Declared renames, per entity: `{ post: { body: 'content' } }`. */
+  renamed?: Record<string, Record<string, string>>;
+}

package/src/projection/card/ShapeKeywords.ts

@@ -0,0 +1,7 @@
+import type { Shape } from '../../axis/shape/Shape.js';
+
+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;
+
+/** Every keyword any shape may carry, flattened — what a descriptor records of one. */
+export type ShapeKeywords = UnionToIntersection<KeywordsOf<Shape>>;