@zmdb/schema 1.0.0-beta.1

package/src/ir/validation-shape.ts

@@ -0,0 +1,145 @@
+// The facts about an IR node that the emitted code and the runtime walker must agree on.
+//
+// REQ-AV-4 asks for identical accept/reject sets *and* identical issue paths from the
+// emitted validator and the fallback walker. That is a property of two independent
+// walks over the same IR, so anything both of them decide lives here rather than being
+// written twice: what an `expected` string reads, and whether a union has a
+// discriminant worth switching on.
+//
+// Nothing in this file builds JavaScript, so the runtime path can import it without
+// dragging the emitter into a browser bundle.
+
+import { type Constraints, type ObjectIR, type TypeIR } from './index.js';
+
+/**
+ * What a value at this position was supposed to be, as the `expected` field of a
+ * `ValidationIssue`. Structural only — a bound that a value of the right *shape*
+ * violated gets its own issue via `expectedForConstraint`.
+ */
+export function expectedOf(node: TypeIR): string {
+  switch (node.kind) {
+    case 'scalar':
+      return node.scalar === 'date' ? 'Date' : node.scalar;
+    case 'literal':
+      return JSON.stringify(node.value);
+    case 'null':
+      return 'null';
+    case 'undefined':
+      return 'undefined';
+    case 'unknown':
+      return 'anything';
+    case 'union':
+      return node.members.map(expectedOf).join(' | ');
+    case 'array':
+      return 'array';
+    case 'tuple':
+      return `tuple of length ${node.elements.length}`;
+    case 'object':
+      return node.name ?? 'object';
+    case 'ref':
+      return node.name;
+    case 'unsupported':
+      // Reachable only through a bug: the emitter refuses an `unsupported` node
+      // before any issue text is needed (plan D4). Naming it beats `undefined`.
+      return `an unsupported type (${node.reason})`;
+  }
+}
+
+export type ConstraintKeyword = keyof Constraints;
+
+/** `minLength`, `3` → `'minLength 3'`. One spelling, used by both walks. */
+export function expectedForConstraint(keyword: ConstraintKeyword, value: number | string): string {
+  return `${keyword} ${value}`;
+}
+
+/** The `message` of an issue is always derived from its `expected`. */
+export function messageFor(expected: string): string {
+  return `expected ${expected}`;
+}
+
+export interface DiscriminantArm {
+  readonly value: string | number | boolean;
+  readonly node: ObjectIR;
+}
+
+export interface Discriminant {
+  readonly key: string;
+  readonly arms: readonly DiscriminantArm[];
+}
+
+/**
+ * The property to switch on for a union of objects, when there is one.
+ *
+ * A union is discriminated when every member is an object and some property is
+ * present, required and a distinct literal on all of them. The reflection deliberately
+ * records no strategy (`reflect/SPEC.md` §10) — it says "this property is a literal",
+ * and choosing what to do about that is this function's job.
+ *
+ * Worth doing for more than speed. Without a discriminant, a failing union can only
+ * say "none of these arms matched" at the union's own path; with one, the failure is
+ * reported *inside* the arm the value was clearly trying to be, so `input.radius` gets
+ * named instead of the whole shape.
+ *
+ * The first qualifying key in the first member's declaration order wins, so the answer
+ * does not depend on property iteration order elsewhere.
+ */
+export function discriminantOf(members: readonly TypeIR[]): Discriminant | undefined {
+  if (members.length < 2) return undefined;
+  const objects: ObjectIR[] = [];
+  for (const member of members) {
+    if (member.kind !== 'object') return undefined;
+    objects.push(member);
+  }
+
+  const first = objects[0];
+  if (!first) return undefined;
+
+  for (const candidate of first.properties) {
+    if (candidate.optional || candidate.type.kind !== 'literal') continue;
+    const arms: DiscriminantArm[] = [];
+    const seen = new Set<string>();
+    let usable = true;
+    for (const object of objects) {
+      const property = object.properties.find(p => p.name === candidate.name);
+      if (!property || property.optional || property.type.kind !== 'literal') {
+        usable = false;
+        break;
+      }
+      // `JSON.stringify` rather than the raw value so `1` and `'1'` are two arms
+      // rather than one collision — the emitted switch compares with `===`.
+      const key = JSON.stringify(property.type.value);
+      if (seen.has(key)) {
+        usable = false;
+        break;
+      }
+      seen.add(key);
+      arms.push({ value: property.type.value, node: object });
+    }
+    if (usable) return { key: candidate.name, arms };
+  }
+  return undefined;
+}
+
+/** `'circle' | 'square'`, for the message when no arm's discriminant matched. */
+export function expectedForDiscriminant(discriminant: Discriminant): string {
+  return discriminant.arms.map(arm => JSON.stringify(arm.value)).join(' | ');
+}
+
+/**
+ * Whether excess properties are even defined for this node. A value can satisfy
+ * several arms of an undiscriminated union, so "which arm's property list is the
+ * declared one" has no answer there and neither walk checks it — see `emit/SPEC.md`.
+ */
+export function hasExcessCheck(node: TypeIR): boolean {
+  switch (node.kind) {
+    case 'object':
+    case 'ref':
+    case 'array':
+    case 'tuple':
+      return true;
+    case 'union':
+      return discriminantOf(node.members) !== undefined;
+    default:
+      return false;
+  }
+}

package/src/ir/vocabulary.ts

@@ -0,0 +1,56 @@
+/**
+ * `ValidationRule.kind` is an open `string`, so this is the set any back-end
+ * interprets rather than the set a consumer may write. Anything else is a named
+ * custom rule and lands in `ColumnIR.rules`.
+ */
+export const KNOWN_CONSTRAINT_KINDS = ['minimum', 'maximum', 'minLength', 'maxLength', 'pattern'] as const;
+
+export type ConstraintKind = (typeof KNOWN_CONSTRAINT_KINDS)[number];
+
+/**
+ * The tag vocabulary as data: **IR field → the tag name the reflection recognises**.
+ * `../tags` is types-only and must stay that way, so the reflection cannot import the
+ * tags themselves. It matches the escaped unique-symbol name the checker reports
+ * (`__@zmdbSerial@1`), except for `Ext`'s frozen structural `__zmdbExt` marker.
+ *
+ * Keyed by the IR field rather than by the tag's public name because that is the
+ * mapping every consumer actually wants, and because keeping it in one table is what
+ * lets `vocabulary.type-test.ts` prove the two vocabularies line up. A tag added to
+ * `../tags` without an entry here is invisible to the reflection, which is precisely
+ * the silent-gap failure the whole IR exists to prevent.
+ */
+export const TAG_NAMES = {
+  table: 'zmdbTable',
+  ftsTable: 'zmdbFts',
+  shardKey: 'zmdbShardKey',
+  sortKey: 'zmdbSortKey',
+  rowstore: 'zmdbRowstore',
+  softDelete: 'zmdbSoftDelete',
+  sql: 'zmdbSqlType',
+  extension: 'zmdbExt',
+  primaryKey: 'zmdbPrimaryKey',
+  serial: 'zmdbSerial',
+  unique: 'zmdbUnique',
+  hasDefault: 'zmdbDefault',
+  sensitive: 'zmdbSensitive',
+  references: 'zmdbReferences',
+  onDelete: 'zmdbOnDelete',
+  onUpdate: 'zmdbOnUpdate',
+  foreignKeys: 'zmdbForeignKey',
+  length: 'zmdbLength',
+  precision: 'zmdbNumeric',
+  codec: 'zmdbCodec',
+  wire: 'zmdbWire',
+  relation: 'zmdbRelation',
+  minimum: 'zmdbMin',
+  maximum: 'zmdbMax',
+  minLength: 'zmdbMinLength',
+  maxLength: 'zmdbMaxLength',
+  pattern: 'zmdbPattern',
+  rules: 'zmdbRule',
+  protoField: 'zmdbProtoField',
+  protoScalar: 'zmdbProtoScalar',
+} as const;
+
+/** An IR field a tag can set. */
+export type TagField = keyof typeof TAG_NAMES;

package/src/naming/index.ts

@@ -0,0 +1,159 @@
+/**
+ * A build-time mapping from declared TypeScript names to physical SQL names.
+ *
+ * The reflector calls these functions once and stores their answers in `SchemaIR`.
+ * Query compilation and row handling never receive a strategy.
+ */
+export interface NamingStrategy {
+  readonly column?: (property: string, context: { readonly table: string }) => string;
+  readonly table?: (declared: string) => string;
+  readonly index?: (table: string, columns: readonly string[], unique: boolean) => string;
+}
+
+export type NamingStrategyName = 'snake_case' | 'snake_case_plural';
+export type NamingStrategyConfig = NamingStrategy | NamingStrategyName | undefined;
+
+const IRREGULAR_PLURALS = new Map([
+  ['child', 'children'],
+  ['index', 'indices'],
+  ['man', 'men'],
+  ['matrix', 'matrices'],
+  ['person', 'people'],
+  ['woman', 'women'],
+]);
+const IRREGULAR_PLURAL_FORMS = new Set(IRREGULAR_PLURALS.values());
+const UNINFLECTED = new Set([
+  'data',
+  'equipment',
+  'fish',
+  'information',
+  'metadata',
+  'news',
+  'series',
+  'sheep',
+  'species',
+]);
+
+function toSnakeCase(value: string): string {
+  return value
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .replaceAll(/([a-z\d])([A-Z])/g, '$1_$2')
+    .replaceAll(/[-\s]+/g, '_')
+    .toLowerCase();
+}
+
+function pluralizeWord(word: string): string {
+  const lower = word.toLowerCase();
+  if (word.length === 0 || UNINFLECTED.has(lower) || IRREGULAR_PLURAL_FORMS.has(lower)) return word;
+
+  const irregular = IRREGULAR_PLURALS.get(lower);
+  if (irregular !== undefined) return irregular;
+
+  // Keep an already-plural declaration stable. The guarded endings are singular
+  // words that happen to end in `s` and still need the explicit `-es` rule below.
+  if (
+    lower.endsWith('s') &&
+    !lower.endsWith('ss') &&
+    !lower.endsWith('us') &&
+    !lower.endsWith('is') &&
+    !lower.endsWith('as') &&
+    !lower.endsWith('os') &&
+    lower !== 'status' &&
+    lower !== 'alias'
+  ) {
+    return word;
+  }
+
+  if (/[^aeiou]y$/i.test(word)) return `${word.slice(0, -1)}ies`;
+  if (/(?:s|x|z|ch|sh)$/i.test(word)) return `${word}es`;
+  return `${word}s`;
+}
+
+function pluralizeTable(value: string): string {
+  const words = value.split('_');
+  const last = words.at(-1);
+  if (last === undefined) return value;
+  words[words.length - 1] = pluralizeWord(last);
+  return words.join('_');
+}
+
+function indexName(table: string, columns: readonly string[], unique: boolean): string {
+  return `${toSnakeCase(table)}_${columns.map(toSnakeCase).join('_')}_${unique ? 'uniq' : 'idx'}`;
+}
+
+export const snakeCase: NamingStrategy = Object.freeze({
+  column: toSnakeCase,
+  table: toSnakeCase,
+  index: indexName,
+});
+
+export const snakeCasePlural: NamingStrategy = Object.freeze({
+  column: toSnakeCase,
+  table: (declared: string) => pluralizeTable(toSnakeCase(declared)),
+  index: (table: string, columns: readonly string[], unique: boolean) =>
+    indexName(pluralizeTable(toSnakeCase(table)), columns, unique),
+});
+
+const IDENTITY: NamingStrategy = Object.freeze({});
+
+/** Resolve a config spelling once, before reflection begins. */
+export function resolveNaming(config: NamingStrategyConfig): NamingStrategy {
+  if (config === undefined) return IDENTITY;
+  if (typeof config !== 'string') return config;
+  if (config === 'snake_case') return snakeCase;
+  if (config === 'snake_case_plural') return snakeCasePlural;
+  throw new TypeError(`Unknown naming strategy ${JSON.stringify(config)}`);
+}
+
+function singularizeWord(word: string): string {
+  if (!word) return word;
+  const lower = word.toLowerCase();
+
+  if (
+    lower.endsWith('ss') ||
+    lower.endsWith('us') ||
+    lower.endsWith('is') ||
+    lower.endsWith('as') ||
+    lower.endsWith('os') ||
+    lower === 'series' ||
+    lower === 'species' ||
+    lower === 'news' ||
+    lower === 'lens'
+  ) {
+    return word;
+  }
+
+  if (lower === 'people') return 'person';
+  if (lower === 'children') return 'child';
+  if (lower === 'men') return 'man';
+  if (lower === 'women') return 'woman';
+  if (lower === 'matrices') return 'matrix';
+  if (lower === 'indices') return 'index';
+
+  if (/([^aeiou])ies$/i.test(word)) return `${word.slice(0, -3)}y`;
+  if (/lves$/i.test(word)) return `${word.slice(0, -4)}lf`;
+  if (/(kn|w)ives$/i.test(word)) return `${word.slice(0, -4)}ife`;
+  if (/eaves$/i.test(word)) return `${word.slice(0, -5)}eaf`;
+
+  if (/sses$/i.test(word) || /statuses$/i.test(word) || /aliases$/i.test(word)) {
+    return word.slice(0, -2);
+  }
+  if (/ises$/i.test(word)) return `${word.slice(0, -4)}is`;
+  if (/(xes|ches|shes|zzes)$/i.test(word)) return word.slice(0, -2);
+  if (/([aeiou])zes$/i.test(word)) return word.slice(0, -1);
+  if (word.endsWith('s') && !word.endsWith('ss')) return word.slice(0, -1);
+  return word;
+}
+
+/**
+ * Singularize each physical-name word through the repository's explicit rule set and
+ * PascalCase the result. The physical table remains on `Table<'...'>`; this name is only
+ * the generated TypeScript identifier.
+ */
+export function singularPascalCase(value: string): string {
+  return value
+    .split(/[-_]+/)
+    .map(word => singularizeWord(word))
+    .map(word => (word ? `${word.charAt(0).toUpperCase()}${word.slice(1)}` : ''))
+    .join('');
+}

package/src/openapi/index.ts

@@ -0,0 +1,133 @@
+import { type CoreSchema } from '../index.js';
+import { jsonSchemaFromIR, type JsonSchemaObject, type Variant } from '../ir/index.js';
+// JSON Schema / OpenAPI generation — implementation.
+// #64 toJsonSchema scalar/enum/nullable (+ tag mapping and variant/aggregation
+// logic that the shared golden suite exercises). Build-time, no reflection.
+//
+// The scalar/variant walk used to live here as `scalarSchema` — one of the four
+// independent walkers over column metadata catalogued in `PLAN-type-first.md` §1.
+// It now delegates to `../ir`, so naming a variant and naming a derived type cannot
+// produce different documents: both are read off the same `SchemaIR`, and the emitter is
+// a pure function of it (REQ-TF-7). What is left in this file is the OpenAPI framing —
+// components, list/search envelopes, naming — which is genuinely its own concern.
+import { singularPascalCase } from '../naming/index.js';
+
+export type { JsonSchemaObject, Variant };
+
+/**
+ * The document for a type, computed at build time (REQ-TF-7).
+ *
+ * `toJsonSchema<ReadDTO<User>>()` is replaced by the document itself — an object
+ * literal, frozen, with no schema value and no reflection left in the bundle. The
+ * variant is the type argument rather than a string, so `toJsonSchema<CreateDTO<User>>()`
+ * is the create body and `toJsonSchema<Pick<Entity<User>, 'id' | 'email'>>()` is a
+ * projection nothing in the string-variant vocabulary could express.
+ *
+ * Untransformed it throws, and that is the design (plan D4). There is no honest
+ * fallback: the document is a function of a type, types do not exist at runtime, and the
+ * alternatives are to return something wrong or to ask the caller to hand over the very
+ * thing the call exists to compute. A build that skipped the transform should fail
+ * loudly at the first call, not serve a plausible document.
+ */
+// oxlint-disable-next-line no-unused-vars -- `T` is the whole input; it has nowhere else to appear
+export function toJsonSchema<T>(): JsonSchemaObject;
+/** The document for a schema value and a named variant. */
+export function toJsonSchema(schema: CoreSchema<string>, variant?: Variant): JsonSchemaObject;
+export function toJsonSchema(schema?: CoreSchema<string>, variant: Variant = 'entity'): JsonSchemaObject {
+  if (!schema) {
+    throw new Error(
+      'toJsonSchema<T>() was not replaced at build time. It is compiled away by @zmdb/compiler ' +
+        '(the unplugin, Metro adapter, or project compiler), which did not run over this file — a type argument cannot ' +
+        'be read at runtime, so there is nothing to fall back to.',
+    );
+  }
+  return jsonSchemaFromIR(schema.ir, variant);
+}
+
+/**
+ * The `components.schemas` key for a table, and the target of every `$ref` that points at
+ * it: singularized, then PascalCase. `user_addresses` → `UserAddress`.
+ *
+ * Exported because it is the only way to write a `$ref` by hand that resolves against a
+ * document this module produced, and because it is the whole subject of
+ * `singularization.spec.ts` — which used to reach it by declaring twenty schemas whose only
+ * distinguishing feature was the table name.
+ */
+export function componentName(table: string): string {
+  return singularPascalCase(table);
+}
+
+/**
+ * The entity schema with a `$ref` per relation: a to-one refs the target component, a to-many
+ * is an array of them.
+ *
+ * Relations reach the `entity` (response) variant only. A create or update body is columns,
+ * and a `$ref` to a whole entity in one would say the client may post a nested graph, which
+ * no write path here accepts.
+ *
+ * There used to be a second parameter — a `Record<string, RelationLike>` naming each relation
+ * and its target table — because a schema value carried no relations for this to read. It
+ * carries them now, on `schema.ir`, so a document generated from a set of schemas can no
+ * longer disagree with the tables about which relations exist. The kinds are the IR's
+ * (`oneToMany`, not `one-to-many`).
+ */
+export function toJsonSchemaWithRelations(schema: CoreSchema<string>, variant: Variant = 'entity'): JsonSchemaObject {
+  const base = toJsonSchema(schema, variant);
+  if (variant !== 'entity') return base; // input bodies exclude relations
+  const properties: Record<string, unknown> = { ...base.properties };
+  for (const rel of schema.ir.relations) {
+    const ref = { $ref: `#/components/schemas/${componentName(rel.target)}` };
+    const toMany = rel.relation === 'oneToMany' || rel.relation === 'manyToMany';
+    properties[rel.name] = toMany ? { type: 'array', items: ref } : ref;
+  }
+  return { type: 'object', properties, required: base.required };
+}
+
+export function toOpenApiComponents(schemas: readonly CoreSchema<string>[]): {
+  schemas: Record<string, JsonSchemaObject>;
+} {
+  const out: Record<string, JsonSchemaObject> = {};
+  for (const s of [...schemas].toSorted((a, b) => a.ir.table.localeCompare(b.ir.table))) {
+    out[componentName(s.ir.table)] = toJsonSchema(s, 'entity');
+  }
+  return { schemas: out };
+}
+
+// #175 — read-variant envelopes. list wraps the entity in a paged envelope;
+// search adds an optional _score to each item. Build-time, deterministic.
+export interface EnvelopeSchema {
+  readonly type: 'object';
+  readonly properties: Readonly<Record<string, unknown>>;
+  readonly required: readonly string[];
+}
+export function toListSchema(schema: CoreSchema<string>): EnvelopeSchema {
+  const entity = toJsonSchema(schema, 'entity');
+  return {
+    type: 'object',
+    properties: {
+      items: { type: 'array', items: entity },
+      total: { type: 'integer' },
+      hasMore: { type: 'boolean' },
+      cursor: { type: 'string' },
+    },
+    required: ['hasMore', 'items'],
+  };
+}
+export function toSearchSchema(schema: CoreSchema<string>): EnvelopeSchema {
+  const entity = toJsonSchema(schema, 'entity');
+  const hit = {
+    type: 'object',
+    properties: { ...entity.properties, _score: { type: 'number' } },
+    required: entity.required,
+  };
+  return {
+    type: 'object',
+    properties: {
+      items: { type: 'array', items: hit },
+      total: { type: 'integer' },
+      hasMore: { type: 'boolean' },
+      cursor: { type: 'string' },
+    },
+    required: ['hasMore', 'items'],
+  };
+}

package/src/relations/index.ts

@@ -0,0 +1,134 @@
+import { type SchemaIR } from '../ir/index.js';
+
+export interface ResolvedRelation {
+  readonly name: string;
+  /** Where the related rows live. */
+  readonly targetTable: string;
+  /** Ordered columns on the declaring table whose values the join matches. */
+  readonly parentKey: readonly string[];
+  /** Ordered columns on the target table, positionally paired with `parentKey`. */
+  readonly targetKey: readonly string[];
+  /** `true` for `oneToMany`: the relation attaches an array, empty where nothing matched. */
+  readonly toMany: boolean;
+}
+
+/**
+ * Resolve one relation of a table by name.
+ *
+ * Throws for a name the type does not declare — naming the ones it does, because a
+ * misspelled `populate` is the common case — and for `manyToMany`, whose `via` is a join
+ * table rather than a column: two hops cannot be expressed as one `IN`, and guessing the
+ * join table's two foreign keys from the table names either side is how a wrong query gets
+ * built quietly.
+ */
+export function resolveRelation(ir: SchemaIR, name: string): ResolvedRelation {
+  const declared = ir.relations;
+  const rel = declared.find(candidate => candidate.name === name);
+  if (!rel) {
+    const known = declared.map(candidate => candidate.name);
+    throw new Error(
+      `unknown relation "${name}" on ${ir.table}: ` +
+        (known.length > 0 ? `the type declares ${known.join(', ')}` : 'the type declares none'),
+    );
+  }
+  if (rel.relation === 'manyToMany') {
+    throw new Error(
+      `relation "${name}" on ${ir.table} is many-to-many through "${rel.via}", which populate ` +
+        'does not resolve — join the two tables explicitly',
+    );
+  }
+  if (rel.relation === 'oneToMany') {
+    // The inverse side: the foreign key is a column of the *target*, holding this row's key.
+    return inverseRelation(ir, name, rel, true);
+  }
+  const via = relationColumns(ir, name, rel.via);
+  if (rel.relation === 'oneToOne' && !via.every(column => ir.columns.some(candidate => candidate.name === column))) {
+    // A one-to-one pair is symmetric, so `OneToOne<'profiles', 'userId'>` does not say which
+    // of the two tables holds the key — and the answer is "the one with the column". Declared
+    // on `users`, which has no `userId`, it is the inverse side, joined from the primary key
+    // exactly as a to-many is; it just cannot match twice.
+    return inverseRelation(ir, name, rel, false);
+  }
+  // The owning side: this row holds the foreign key, and the column it points at is written
+  // down on that column, as `References<'users.id'>`.
+  return {
+    name,
+    targetTable: rel.target,
+    parentKey: via,
+    targetKey: via.map(column => referencedColumn(ir, name, rel.target, column, via.length > 1)),
+    toMany: false,
+  };
+}
+
+function relationColumns(ir: SchemaIR, relation: string, via: string): readonly string[] {
+  const columns = via.split(',').map(column => column.trim());
+  if (columns.some(column => column.length === 0)) {
+    throw new Error(`${ir.table}.${relation}: relation via "${via}" contains an empty column name`);
+  }
+  return columns;
+}
+
+/** The column a foreign key points at, per its `References<'table.column'>`; `id` without one. */
+function referencedColumn(
+  ir: SchemaIR,
+  relation: string,
+  target: string,
+  fk: string,
+  requireReference: boolean,
+): string {
+  const reference = ir.columns.find(col => col.name === fk)?.references;
+  const separator = reference?.lastIndexOf('.') ?? -1;
+  if (reference !== undefined && separator > 0 && separator < reference.length - 1) {
+    return reference.slice(separator + 1);
+  }
+  if (requireReference) {
+    throw new Error(
+      `${ir.table}.${relation}: composite relation via column "${fk}" must carry ` +
+        `References<'${target}.column'>; every via column must name its target`,
+    );
+  }
+  return 'id';
+}
+
+function primaryKeyOf(ir: SchemaIR): readonly string[] {
+  if (ir.primaryKey.length === 0) {
+    throw new Error(`schema ${ir.table} has no primary key, so its relations have nothing to join from`);
+  }
+  return ir.primaryKey;
+}
+
+function relationTag(relation: 'manyToOne' | 'oneToMany' | 'oneToOne'): string {
+  switch (relation) {
+    case 'manyToOne':
+      return 'ManyToOne';
+    case 'oneToMany':
+      return 'OneToMany';
+    case 'oneToOne':
+      return 'OneToOne';
+  }
+}
+
+function inverseRelation(
+  ir: SchemaIR,
+  name: string,
+  rel: SchemaIR['relations'][number],
+  toMany: boolean,
+): ResolvedRelation {
+  if (rel.relation !== 'oneToMany' && rel.relation !== 'oneToOne') {
+    throw new Error(`${ir.table}.${name}: ${rel.relation} is not an inverse relation`);
+  }
+  const parentKey = primaryKeyOf(ir);
+  const targetKey = relationColumns(ir, name, rel.via);
+  if (parentKey.length !== targetKey.length) {
+    const tag = relationTag(rel.relation);
+    const missing = Math.max(0, parentKey.length - targetKey.length);
+    const suggestedVia = [...parentKey.slice(0, missing), ...targetKey].join(',');
+    const targetLabel = targetKey.length === 1 ? 'column' : 'columns';
+    throw new Error(
+      `${ir.table}.${name}: ${tag}<'${rel.target}', '${rel.via}'> supplies ${String(targetKey.length)} target ` +
+        `${targetLabel} for a ${String(parentKey.length)}-column parent key (${parentKey.join(', ')}); ` +
+        `name every column, in key order — ${tag}<'${rel.target}', '${suggestedVia}'>`,
+    );
+  }
+  return { name, targetTable: rel.target, parentKey, targetKey, toMany };
+}