Diagnostics

RunTypes derives every type query from your project tsconfig, the same
file your build uses. A tsconfig that was named (or found next to your
project) but is missing or does not parse stops the operation, exactly
like `tsc --project` would, instead of silently falling back to defaults
that could resolve your types differently.

Fix — repair the tsconfig (the message names the first parse problem),
or point the tooling at the right file (the plugin/lint `tsconfig`
setting, or the CLI `--tsconfig` flag).

The build resolves the argument before running, so it needs to read its
value from the source. Function-call results, property accesses, ternary
expressions, and `let`/`var` bindings can't be evaluated at build time.
Accepted: an inline literal, or a `const` whose initializer is itself
fully literal — including a `const` imported from another module. (An
object `const` must be `as const` so its members stay literal; see CTA004.)

Fix — inline at the call site:
-  const opts = getOpts();
-  const isUser = createValidateFn<User>(undefined, opts);
+  const isUser = createValidateFn<User>(undefined, {mode: 'unsafe'});

Fix — use a const of literals (here or in another module):
  const opts = {mode: 'unsafe'} as const;   // literal initializer ✓
  const isUser = createValidateFn<User>(undefined, opts);

Deeply nested literal walks are capped at 16 levels to keep the build
predictable. If you hit this, the value is almost certainly not what
you want at compile time — split it across multiple smaller
`CompTimeArgs<T>` arguments, or flatten the nesting.

The Go scanner cannot statically evaluate computed property names,
function calls, ternary expressions, or template-string substitutions.
Inside a `CompTimeArgs<T>` literal every node must be a direct literal
(string / number / bigint / boolean / null / undefined / regex / arrow /
object literal / array literal) or a const-traced identifier that
resolves to one.

Spread IS allowed when its operand resolves to a literal container of the
matching kind — a `const`-bound (or imported) object literal for an
object spread, an array literal for an array spread:
  const base = {strict: true};
  const a = {...base, mode: 'unsafe'};        // ok — merges a const fragment

A spread is still rejected when the operand can't be statically merged —
a dynamic value, or a shape mismatch:
  -  const a = {...getDefaults(), mode: 'unsafe'};   // dynamic operand
  -  const a = {...[1, 2], mode: 'unsafe'};          // object spread of an array

A `const` used as a CompTimeArgs / CompTimeFnArgs argument (a whole option
bag, or a builder child) must carry LITERAL value types, so the value the
build reads matches the type TypeScript resolves the call against. Without
`as const`, an object literal's members widen — `{strategy: 'mutate'}`
becomes `{strategy: string}` — which can let the type system select one
function variant while the build injects another.

Whole imported consts now resolve cross-module (like a spread fragment), so
this rule keeps that path sound.

Fix — add `as const`:
-  const preset = {strategy: 'mutate'};
+  const preset = {strategy: 'mutate'} as const;
   createJsonEncoderFn(undefined, preset);

Reflect-form markers (`createValidateFn(value)`, `getRunTypeId(value)`)
invoke their argument expression at runtime; the value is then discarded —
only its inferred type is used.

Fix — use the static form with `ReturnType<>`:
  -  const isUser = createValidateFn({0}());
+  const isUser = createValidateFn<ReturnType<typeof {0}>>();

Fix — pass an existing value of the desired type:
  const existingUser: User = ...;
  const isUser = getRunTypeId(existingUser);

The build can only compute an id for a concrete type (`User`,
`{name: string}`, etc.). A type parameter like `T` is abstract — it
takes a different value at each call site of the surrounding function,
so a single id can't represent it.

Fix — inline the marker at each concrete call site:
  function isUser(value: unknown) {
    return createValidateFn<User>()(value);
  }

Fix — accept a pre-computed id from the caller:
  function makeChecker<T>(id: InjectRunTypeId<T>) {
    return createValidateFn<T>(id);
  }
  const isUser = makeChecker<User>(getRunTypeId<User>());

The `noLiterals` validate option skips the exact-value check that literal
types (`'admin'`, `42`, `true`) compile to. This call's type argument
resolves to a non-literal type, so there is no literal check to skip and
the option is a silent no-op.

Fix — drop the option:
-  const isRole = createValidateFn<string>({noLiterals: true});
+  const isRole = createValidateFn<string>();

Or, if you meant to relax a literal union, point the option at the type
that actually carries the literals:
  const isRole = createValidateFn<'admin' | 'user'>({noLiterals: true});

The `noIsArrayCheck` validate option skips the `Array.isArray` guard that
array types compile to. This call's type argument resolves to a non-array
type, so there is no guard to skip and the option is a silent no-op.

Fix — drop the option:
-  const isUser = createValidateFn<User>({noIsArrayCheck: true});
+  const isUser = createValidateFn<User>();

Or point it at the array type you meant:
  const isUsers = createValidateFn<User[]>({noIsArrayCheck: true});

An `InjectTypeFnArgs<T, …>` marker names each function family it needs for
`T` once, in declaration order; the build injects one entry-module tuple
per name and the wrapper forwards each to its factory. Naming a family
twice would inject a redundant identical tuple with no consumer, so it is
almost always a copy-paste slip and the build stops.

Fix — name each family at most once:
-  id?: InjectTypeFnArgs<T, 'verr', 'jsonDecoder', 'verr'>;
+  id?: InjectTypeFnArgs<T, 'verr', 'jsonDecoder', 'jsonEncoder'>;

TypeScript could not resolve the import, so the type it should have
provided checked as `any` at this marker call. A validator over `any` is
the always-true identity, a mock over `any` is `undefined`, and encoders
pass values through untouched — with no runtime signal that anything is
wrong. This usually means the build tool and the type scanner resolve
modules differently (e.g. an extensionless relative import under
`moduleResolution: NodeNext`, a missing dependency, or a `paths` alias the
scan tsconfig doesn't declare).

Fix — make the import resolve for the type scanner:
-  import {User} from './user.runtype';
+  import {User} from './user.runtype.ts';

Or align the tsconfig the plugin scans with the one your bundler uses.
If the `any` is genuinely intentional, write the marker over an alias
declared in resolving code (e.g. `type Loose = any`) in a file with no
failing imports.

The build computes a structural id by walking the type, and the walk is
capped at a depth far beyond any realistic shape. Hitting the cap with no
single recurring type on the path means literally written (or generated)
nesting hundreds of levels deep.

Fix — reflect a concrete, bounded projection of the type (e.g. the element
or data type you actually send), or restructure the recursion so the same
named type recurs by reference (a plain recursive interface is fine).

A generic method's own type parameters (the `U` in `map<U>(fn: (x: T) => U):
Iter<U>`) are bound at each CALL of the method, so they can never be resolved
while reflecting the containing type — and when such a method returns a fresh
instantiation of its own container, the type graph grows a new level forever.
Renaming the type parameters does not resolve them; the fix is a monomorphic
(fully resolved) recursive shape, which closes by reference:

-  interface Iter<T> { map<U>(fn: (x: T) => U): Iter<U> }
+  interface NumberIter { map(fn: (x: string) => number): NumberIter }

Ordinary generics are unaffected: instantiated types (Map<string, User>, a
concrete Iter<string>'s data members) and generic methods that do not
re-instantiate their container reflect fine. Validators also drop methods
entirely (methods aren't data), so reflecting just the data shape usually
sidesteps the problem.

The build can only compute an id for a fully concrete type. `{0}` is a type
parameter of the surrounding generic — it takes a different type at each call
site, so a single build-time id would alias every instantiation onto one
(wrong) shape. A parameter DEFAULT does not help here: defaults resolve where
a caller omits the argument, never inside the generic's own body.

Fix — resolve the generic before reflecting it:
  interface Box<T> { value: T }
  type BoxString = Box<string>;
  const isBoxString = createValidateFn<BoxString>();   // resolved — ok

Fix — or accept a pre-computed id from the caller and inline the marker at
each concrete call site (same patterns as MKR003):
  function makeChecker<T>(id: InjectRunTypeId<T>) {
    return createValidateFn<T>(id);
  }
  const isBox = makeChecker<Box<string>>(getRunTypeId<Box<string>>());

Generic METHODS on a concrete type (`find<T>(query: string): T[]`) are
unaffected — their own type parameters are bound per call of the method and
methods aren't data.

TypeScript itself rejects this usage (TS2314), but dev-server builds don't
run the type checker, so the scan reads the written type arguments and stops
the build here instead of silently reflecting `any` (a validator over `any`
accepts everything).

Fix — pass the missing type argument:
-  const isA = createValidateFn<A>();
+  const isA = createValidateFn<A<string>>();

Fix — or give the parameter a default, which the compiler resolves at every
bare use site:
-  interface A<S extends string> { a: S }
+  interface A<S extends string = string> { a: S }
   const isA = createValidateFn<A>();   // now resolves to A<string>

The build extracts and AOT-compiles the function body, so it must see the
literal inline at the call site. A named reference — even a module-private
`const f = …` or `function f(){}` — is not accepted, because the literal
must have no handle anything else can reach; the compiled copy is then the
only one that can run. (An imported or exported literal is rejected as PFN002.)

Fix — inline the function at the call site:
-  const validate = (v: unknown) => typeof v === 'string';
-  registerValidator(validate);
+  registerValidator((v: unknown) => typeof v === 'string');

The build extracts and AOT-compiles the function body, and the compiled
copy is the single source of truth. If the original literal stays reachable
as a value — imported from another module, or exported so another module can
import it — a caller could invoke the un-compiled function and diverge from
the compiled behaviour.

Under the literal-only rule a named binding isn't allowed at all (see PFN001),
so the fix is to inline the function at the call site:
-  import {validate} from './validators';   // imported — rejected
-  export const validate = (v) => …;        // exported — rejected
+  registerValidator((v: unknown) => typeof v === 'string');   // inline — ok

ts-runtypes reads types through TypeScript's lib definitions, so it
can only validate `Temporal.*` types when the Temporal namespace is loaded.
With the lib missing, `{0}` silently degrades to `any` and the validator
becomes a no-op that accepts everything — almost never what you intended.

Fix — add "ESNext.Temporal" to your tsconfig:
  {
    "compilerOptions": {
      "lib": ["ES2023", "ESNext.Temporal"]
    }
  }

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`validationErrors` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`validationErrors` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`validationErrors` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `validationErrors` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

`validationErrors` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `validationErrors` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

Same reason as VL021: `any` and `unknown` describe "anything", so the
checker has no structure to compare against. The returned error array
will always be empty.

Fix — narrow the type to the actual shape you expect:
  -  const errors = createGetValidationErrorsFn<unknown>()(value);
+  const errors = createGetValidationErrorsFn<User>()(value);

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`validate` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`validate` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`validate` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `validate` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

A union projects to its serialisable members only: `DataOnly<Date | symbol>`
is `Date`. The dropped member(s) ({0}) carry no JSON-shaped value (symbol,
function, Promise, or a non-serialisable built-in like `Map` / `Set` /
typed arrays), so `validate` validated only the members that remain.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If EVERY member of the union is non-serialisable the
projection is `never`, and `validate` throws at build time instead.

`validate` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `validate` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

`any` and `unknown` describe "anything", so a structural validator has
nothing to check. The resulting function passes for every input —
including the ones you probably wanted to reject.

Fix — narrow the type to the actual shape you expect:
  -  const isUser = createValidateFn<unknown>();
+  const isUser = createValidateFn<User>();

By default a user class is serialized by its declared properties and
decoded back to a prototype-less plain object — `instanceof {0}` is
false on the decoded value, and any class methods / getters are gone.
This is fine when you only care about the data.

To round-trip a real `{0}` instance, register it once, passing the class
itself (not a name string):
  import {registerClassSerializer} from '@ts-runtypes/core';

  // zero-arg constructor: nothing else needed
  registerClassSerializer({0});

  // non-empty constructor: only `deserialize` is required
  registerClassSerializer({0}, {
    deserialize: (data) => new {0}(/* rebuild from data */),
  });

`serialize` is optional (default: structural, same as any interface);
`deserialize` is optional for a zero-arg class (default:
`Object.assign(new {0}(), data)`). The same registration is used by the
JSON and binary families. `validate` / `getValidationErrors` are
unaffected — they always validate structurally.

`never` is the empty type — no value can ever inhabit it. A field
typed `never` cannot carry a runtime value, so there is nothing to
encode/decode/validate.

Fix — use `unknown` if you really want to accept any value:
  interface User {
-   tag: never;
+   tag: unknown;  // narrow before use
  }

Fix — pick a concrete type matching your real data:
  interface User {
-   tag: never;
+   tag: 'pending' | 'active' | 'done';
  }

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Functions have no value form to serialise — their closure, prototype,
and bound state aren't representable in JSON or binary.

Fix — drop the function from your type, or replace it with the data the
function would produce:
  interface User {
-   getName: () => string;
+   name: string;
  }

Arrays of un-serialisable elements (`symbol[]`, `(() => void)[]`,
`Map<K, V>[]`, etc.) can't be encoded — every element would need to be
representable, and these aren't. Dropping individual elements would
change the array length, so the encoder refuses rather than silently
shipping a different shape.

Fix — change the element type to something serialisable:
  -  type Items = (() => void)[];
+  type Items = string[];

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`fromBinary` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`fromBinary` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`fromBinary` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `fromBinary` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

A union projects to its serialisable members only: `DataOnly<Date | symbol>`
is `Date`. The dropped member(s) ({0}) carry no JSON-shaped value (symbol,
function, Promise, or a non-serialisable built-in like `Map` / `Set` /
typed arrays), so `fromBinary` deserialised only the members that remain.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If EVERY member of the union is non-serialisable the
projection is `never`, and `fromBinary` throws at build time instead.

`fromBinary` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `fromBinary` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

The runtime enumerability guard (which lets a value omit a property from
the wire when it isn't an enumerable own property) is applied ONLY to
optional properties. That keeps the decoder's `DataOnly<T>` return type
honest: a guarded property is always one the type already allows to be
absent. A `@nonEnumerable` tag on a REQUIRED property is therefore ignored
— the property still serializes unconditionally.

Fix — make the property optional:
-  /** @nonEnumerable */ token: string;
+  /** @nonEnumerable */ token?: string;

`never` is the empty type — no value can ever inhabit it. A field
typed `never` cannot carry a runtime value, so there is nothing to
encode/decode/validate.

Fix — use `unknown` if you really want to accept any value:
  interface User {
-   tag: never;
+   tag: unknown;  // narrow before use
  }

Fix — pick a concrete type matching your real data:
  interface User {
-   tag: never;
+   tag: 'pending' | 'active' | 'done';
  }

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Functions have no value form to serialise — their closure, prototype,
and bound state aren't representable in JSON or binary.

Fix — drop the function from your type, or replace it with the data the
function would produce:
  interface User {
-   getName: () => string;
+   name: string;
  }

Arrays of un-serialisable elements (`symbol[]`, `(() => void)[]`,
`Map<K, V>[]`, etc.) can't be encoded — every element would need to be
representable, and these aren't. Dropping individual elements would
change the array length, so the encoder refuses rather than silently
shipping a different shape.

Fix — change the element type to something serialisable:
  -  type Items = (() => void)[];
+  type Items = string[];

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`prepareForJson` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`prepareForJson` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`prepareForJson` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `prepareForJson` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

A union projects to its serialisable members only: `DataOnly<Date | symbol>`
is `Date`. The dropped member(s) ({0}) carry no JSON-shaped value (symbol,
function, Promise, or a non-serialisable built-in like `Map` / `Set` /
typed arrays), so `prepareForJson` encoded only the members that remain.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If EVERY member of the union is non-serialisable the
projection is `never`, and `prepareForJson` throws at build time instead.

`prepareForJson` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `prepareForJson` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

`never` is the empty type — no value can ever inhabit it. A field
typed `never` cannot carry a runtime value, so there is nothing to
encode/decode/validate.

Fix — use `unknown` if you really want to accept any value:
  interface User {
-   tag: never;
+   tag: unknown;  // narrow before use
  }

Fix — pick a concrete type matching your real data:
  interface User {
-   tag: never;
+   tag: 'pending' | 'active' | 'done';
  }

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Functions have no value form to serialise — their closure, prototype,
and bound state aren't representable in JSON or binary.

Fix — drop the function from your type, or replace it with the data the
function would produce:
  interface User {
-   getName: () => string;
+   name: string;
  }

Arrays of un-serialisable elements (`symbol[]`, `(() => void)[]`,
`Map<K, V>[]`, etc.) can't be encoded — every element would need to be
representable, and these aren't. Dropping individual elements would
change the array length, so the encoder refuses rather than silently
shipping a different shape.

Fix — change the element type to something serialisable:
  -  type Items = (() => void)[];
+  type Items = string[];

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`prepareForJsonSafe` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`prepareForJsonSafe` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`prepareForJsonSafe` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `prepareForJsonSafe` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

A union projects to its serialisable members only: `DataOnly<Date | symbol>`
is `Date`. The dropped member(s) ({0}) carry no JSON-shaped value (symbol,
function, Promise, or a non-serialisable built-in like `Map` / `Set` /
typed arrays), so `prepareForJsonSafe` encoded only the members that remain.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If EVERY member of the union is non-serialisable the
projection is `never`, and `prepareForJsonSafe` throws at build time instead.

`prepareForJsonSafe` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `prepareForJsonSafe` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

`never` is the empty type — no value can ever inhabit it. A field
typed `never` cannot carry a runtime value, so there is nothing to
encode/decode/validate.

Fix — use `unknown` if you really want to accept any value:
  interface User {
-   tag: never;
+   tag: unknown;  // narrow before use
  }

Fix — pick a concrete type matching your real data:
  interface User {
-   tag: never;
+   tag: 'pending' | 'active' | 'done';
  }

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Functions have no value form to serialise — their closure, prototype,
and bound state aren't representable in JSON or binary.

Fix — drop the function from your type, or replace it with the data the
function would produce:
  interface User {
-   getName: () => string;
+   name: string;
  }

Arrays of un-serialisable elements (`symbol[]`, `(() => void)[]`,
`Map<K, V>[]`, etc.) can't be encoded — every element would need to be
representable, and these aren't. Dropping individual elements would
change the array length, so the encoder refuses rather than silently
shipping a different shape.

Fix — change the element type to something serialisable:
  -  type Items = (() => void)[];
+  type Items = string[];

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`restoreFromJson` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`restoreFromJson` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`restoreFromJson` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `restoreFromJson` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

A union projects to its serialisable members only: `DataOnly<Date | symbol>`
is `Date`. The dropped member(s) ({0}) carry no JSON-shaped value (symbol,
function, Promise, or a non-serialisable built-in like `Map` / `Set` /
typed arrays), so `restoreFromJson` decoded only the members that remain.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If EVERY member of the union is non-serialisable the
projection is `never`, and `restoreFromJson` throws at build time instead.

`restoreFromJson` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `restoreFromJson` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

`never` is the empty type — no value can ever inhabit it. A field
typed `never` cannot carry a runtime value, so there is nothing to
encode/decode/validate.

Fix — use `unknown` if you really want to accept any value:
  interface User {
-   tag: never;
+   tag: unknown;  // narrow before use
  }

Fix — pick a concrete type matching your real data:
  interface User {
-   tag: never;
+   tag: 'pending' | 'active' | 'done';
  }

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Functions have no value form to serialise — their closure, prototype,
and bound state aren't representable in JSON or binary.

Fix — drop the function from your type, or replace it with the data the
function would produce:
  interface User {
-   getName: () => string;
+   name: string;
  }

Arrays of un-serialisable elements (`symbol[]`, `(() => void)[]`,
`Map<K, V>[]`, etc.) can't be encoded — every element would need to be
representable, and these aren't. Dropping individual elements would
change the array length, so the encoder refuses rather than silently
shipping a different shape.

Fix — change the element type to something serialisable:
  -  type Items = (() => void)[];
+  type Items = string[];

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`stringifyJson` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`stringifyJson` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`stringifyJson` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `stringifyJson` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

A union projects to its serialisable members only: `DataOnly<Date | symbol>`
is `Date`. The dropped member(s) ({0}) carry no JSON-shaped value (symbol,
function, Promise, or a non-serialisable built-in like `Map` / `Set` /
typed arrays), so `stringifyJson` stringified only the members that remain.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If EVERY member of the union is non-serialisable the
projection is `never`, and `stringifyJson` throws at build time instead.

`stringifyJson` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `stringifyJson` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

`never` is the empty type — no value can ever inhabit it. A field
typed `never` cannot carry a runtime value, so there is nothing to
encode/decode/validate.

Fix — use `unknown` if you really want to accept any value:
  interface User {
-   tag: never;
+   tag: unknown;  // narrow before use
  }

Fix — pick a concrete type matching your real data:
  interface User {
-   tag: never;
+   tag: 'pending' | 'active' | 'done';
  }

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Functions have no value form to serialise — their closure, prototype,
and bound state aren't representable in JSON or binary.

Fix — drop the function from your type, or replace it with the data the
function would produce:
  interface User {
-   getName: () => string;
+   name: string;
  }

Arrays of un-serialisable elements (`symbol[]`, `(() => void)[]`,
`Map<K, V>[]`, etc.) can't be encoded — every element would need to be
representable, and these aren't. Dropping individual elements would
change the array length, so the encoder refuses rather than silently
shipping a different shape.

Fix — change the element type to something serialisable:
  -  type Items = (() => void)[];
+  type Items = string[];

Built-in classes like `Map`, `Set`, `WeakMap`, `WeakSet`, `Int8Array`,
`Uint8Array`, `Buffer`, and `Promise` carry runtime state that doesn't
survive a JSON or binary round-trip. Their instance identity is lost the
moment they're serialised.

Fix — convert to a plain object/array before serialising:
  // for Map<K, V>:
  const data = Object.fromEntries(yourMap);
  // for Set<T>:
  const data = [...yourSet];
  // for typed arrays:
  const data = Array.from(yourBuffer);

Fix — change the field type to a serialisable shape:
  interface User {
-   tags: Set<string>;
+   tags: string[];
  }

Every `symbol` value carries a unique runtime identity (`Symbol() !==
Symbol()` even with the same description). That identity disappears the
moment it's serialised, and two symbols can't be compared across realms,
workers, or process boundaries. A validator that asserts "this is a
symbol" gives a false sense of safety — the value can't actually
round-trip.

Fix — use a stable string key (often a literal union):
  -  type Status = symbol;
+  type Status = 'pending' | 'active' | 'done';

`toBinary` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

Class and object methods aren't part of the serialisable shape, so
`toBinary` excludes them. The rest of the type still works.

If you wanted the method's return value validated/serialised, expose it
as a data property instead.

Class static members live on the class, not on individual instances.
`toBinary` operates on instance shape, so statics are excluded.

JSON only supports string keys; symbol-keyed properties are dropped
from the serialised form. `toBinary` follows the same rule.

Fix — use a string key:
  -  [Symbol.for('id')]: string;
+  id: string;

A union projects to its serialisable members only: `DataOnly<Date | symbol>`
is `Date`. The dropped member(s) ({0}) carry no JSON-shaped value (symbol,
function, Promise, or a non-serialisable built-in like `Map` / `Set` /
typed arrays), so `toBinary` serialised only the members that remain.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If EVERY member of the union is non-serialisable the
projection is `never`, and `toBinary` throws at build time instead.

`toBinary` works on JSON-shaped data. A property whose value is a symbol,
a Promise, or a non-serialisable built-in (typed array, ArrayBuffer, …) carries
no JSON-shaped value, so it is dropped: `DataOnly<{ {0}: symbol }>` is `{}`.
The rest of the object's behaviour is unaffected.

Note the difference from a property that is only STRUCTURALLY unserialisable —
`{0}: symbol[]` or `{0}: Map<string, symbol>` — which CANNOT be safely
dropped (DataOnly keeps it as `never[]`): there `toBinary` throws at build
time instead.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md.

A clone built from the declared shape needs to know WHICH union arm the
runtime value matches; v1 has no arm discrimination, and silently keeping
unknown keys would defeat the strip guarantee, so the build fails instead.

Workarounds: narrow the value to one arm before cloning (one
`createCloneExactShapeFn<Arm>()` per arm), or restructure the union into a
single object with optional properties.

Functions aren't data — there is no declared shape to rebuild. Function-typed
PROPERTIES are dropped from the clone (CES010/CES011); a function at the root
or a propagating position fails the build.

Declared members are never dropped (only UNDECLARED keys are — that is the
strip guarantee). Functions cannot be rebuilt from a declared shape, so the
clone's property points at the SAME function as the input's. Class METHODS
differ: they ride the shared prototype and are not copied as own props
(CES011).

For a plain class instance the clone preserves the PROTOTYPE
(`Object.create(Object.getPrototypeOf(v))`), so methods keep working via the
prototype chain; they are simply not copied as own properties. For object
literals a method-typed member is omitted like any function value.

Statics live on the class, not the instance; the clone rebuilds instance
data only.

Declared members are never dropped (only UNDECLARED keys are — that is the
strip guarantee). A value the emitter cannot rebuild passes through by
reference instead: the clone's property points at the SAME handle as the
input's, so mutations through it are visible on both sides. Register
`overrideCloneExactShape<T>()` if this type needs custom copying.

`hasUnknownKeys` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

`unknownKeyErrors` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

`unknownKeysToUndefined` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

`unknownKeysToUndefinedWire` works on JSON-shaped data; functions don't survive JSON, so
the emitter drops them. The rest of the object's behaviour is unaffected.

This is by design — see the "validate contract — serializable data only"
section in CLAUDE.md. If you need a stricter checker that fails on
missing/extra function-typed members, watch the project roadmap.

A mockSample is meant to be a canonical VALID value for the format, so it
must satisfy the format's own statically checkable siblings (length /
minLength / maxLength, and the plain-string allowedChars / disallowedChars /
disallowedValues ops). A sample that its siblings reject means
`createMockDataFn` would either produce an invalid value or filter every
sample out and throw at mock time.

Lengths are counted in UTF-16 code units, exactly as the emitted validator's
`.length` check counts them.

Fix — adjust the offending sample(s), or relax the constraint:
  -  String<{minLength: 5; pattern: {source: '^b+$'; mockSamples: ['b', 'bb']}}>
+  String<{minLength: 1; pattern: {source: '^b+$'; mockSamples: ['b', 'bb']}}>

The build-time sample check compiles the pattern with Go's RE2 engine, which
doesn't support JS-only features (lookarounds, backreferences). The build
fails closed rather than ship samples it can't verify.

Fix — set `allowUncheckedPatterns` (plugin option / tsconfig plugin key)
to assert that the JS linter owns the check, then wire the ts-runtypes lint
plugin into your editor + CI: it evaluates the real `RegExp.test(sample)` and
reports any mismatch (as FMT001) at the definition site.

Fix — or rewrite the pattern using RE2-compatible syntax so the fast
build-time check can run (no lookarounds / backreferences).

Two calls register the same `namespace::functionId` key but the factory
bodies differ. The cache can only hold one definition, so one call site
silently loses its version at runtime.

Fix — make all registrations identical, or pick one canonical site and
delete the others. The Related: line above points at the first
registration the extractor saw.

The build inlines parameter references by name when it materialises the
factory. Destructuring patterns (`({a, b})`, `([x, y])`) don't have a
single name to substitute.

Fix — destructure inside the body:
  -  registerPureFnFactory('ns::fn', (utl) => ({a, b}) => ...);
+  registerPureFnFactory('ns::fn', (utl) => (params) => {
+    const {a, b} = params;
+    return ...;
+  });

Pure functions are materialised standalone at build time; there's no
`this` to bind to.

Fix — replace `this` with an explicit parameter, or move the function
out of the class/object method that owns the `this`:
  registerPureFnFactory('ns::fn', (utl) => (self, input) => {
    return self.field + input;
  });

Pure functions must run synchronously so the build can call them at
compile time. `async` introduces a Promise that won't resolve until
runtime.

Fix — make the factory synchronous; move async work to the caller:
  registerPureFnFactory('ns::fn', (utl) => {
-   return async (input) => { const r = await heavy(); return r; };
+   return (resolvedValue) => transform(resolvedValue);
  });

Generators carry resumption state that can't be materialised
statically.

Fix — return an array or a plain iterable instead:
  registerPureFnFactory('ns::fn', (utl) => (input) => {
    return [...computeAll(input)];
  });

Dynamic imports load modules at runtime — the build needs every
dependency available statically.

Fix — use a top-level `import` statement, or pass the imported module
in as a parameter.

Globals like `eval`, `Function`, `fetch`, `XMLHttpRequest`, `require`,
`process`, `globalThis`, `window`, `document` are blocked from pure-fn
bodies — they either execute arbitrary code or depend on a runtime
environment the build can't reproduce.

Fix — remove the reference, or pass the needed value in as a parameter.

The build inlines factory bodies without their lexical environment, so
any free variable becomes `undefined` at runtime.

Fix — pass `{0}` in as a parameter:
  registerPureFnFactory('ns::fn', (utl) => ({0}, value) => ...);

Fix — inline its value if it's a known constant:
  registerPureFnFactory('ns::fn', (utl) => (value) => {
    const {0} = 42;
    ...
  });

Fix — import `{0}` directly inside the factory if it's a module export.

A RT validator/encoder calls `utl.usePureFn('{0}')` (or similar) but
no `registerPureFnFactory` call with that namespace+function pair was
found in any scanned source file.

Fix — register the function in the expected location ({3}, if known).
Make sure the file is included in the scan set.

`utl.usePureFn` / `utl.getPureFn` need a static key so the build can
verify the referenced pure-fn is registered.

Fix:
  -  const key = buildKey();
-  return utl.usePureFn(key)(input);
+  return utl.usePureFn('rt::myFn')(input);

Two `overrideX<T>()` declarations target the same type and the same
function family. Which one wins would depend on scan order, so a second
override is rejected regardless of its body. The Related: line above
points at the override that was registered first.

Fix — keep one canonical override and delete the other:
-  overrideValidate<User>((utl) => (value) => checkA(value));  // first
-  overrideValidate<User>((utl) => (value) => checkB(value));  // duplicate
+  overrideValidate<User>((utl) => (value) => checkA(value) && checkB(value));

An override redirect body loads its compiled function from the cache
(`usePureFn('cfn::…')`), but that module never rendered into the entry
graph. Calling the override would throw at runtime, so the build surfaces
the miss now. This is an internal emitter tripwire and should never fire
in normal operation.

Fix — re-run with a clean cache first (delete the .runtypes cache dir /
restart the dev server). If it persists, the emitter dropped a module it
should have rendered: please open an issue with the type + override that
triggers it.

`validate` is a shared dependency across function families: JSON and
binary union decoders call the member validators to pick the matching
branch. An `overrideValidate<T>()` therefore reaches past
`createValidateFn<T>()` — decoders of any union containing T now narrow
with YOUR function.

This is informational; the build proceeds. If the override should only
affect direct validation, give the union members a discriminant so
decoders never fall back to member validation:
  type Event = {kind: 'click'; x: number} | {kind: 'key'; code: string};

The FriendlyText map names a field the source type does not have
(removed, renamed, or a typo). Its labels and messages can never be
used.

Example — `nick` no longer exists on the type:
  interface User { name: string }
  export const friendlyUser: FriendlyText<User> = {
    name: {rt$label: 'Name'},
-   nick: {rt$label: 'Nickname'},
  };

Fix — remove the entry, or re-run the reconcile so the mirror follows
the type (a renamed field carries its authored values along):
  ts-runtypes enrich <source.ts> <Type> --update

`rt$errors` keys must name a failure the field can actually produce:
`type`, `rt$default`, or one of the field's declared format constraints
(`minLength`, `pattern`, `min`, …). An undeclared key is dead
configuration.

Example — the field has no `maxLength` constraint:
  interface User { name: string & FormatString<{minLength: 2}> }
  export const friendlyUser: FriendlyText<User> = {
    name: {
      rt$errors: {
        minLength: 'Name needs at least 2 characters',
-       maxLength: 'Name is too long',
      },
    },
  };

Fix — remove the key, or declare the matching constraint on the field's
TypeFormat so the message has a failure to describe.

Error-message templates substitute a fixed placeholder set; an unknown
name renders literally instead of substituting.

Example:
- rt$errors: {minLength: '$[name] is too short'}
+ rt$errors: {minLength: '$[label] is too short'}

Fix — use one of the recognised placeholders, or write the literal text
without the `$[…]` wrapper.

Plural templates render the CLDR arm matching the count, and `other` is
the arm every locale falls back to. Without it some counts have no
message at all.

Example:
  rt$errors: {
    minLength: {
      one: 'Needs one more character',
+     other: 'Needs $[val] more characters',
    },
  }

Fix — add the `other` arm to the plural object.

Plural template keys must be CLDR plural categories; anything else can
never be selected by any locale's plural rules.

Example:
  rt$errors: {
    minLength: {
-     single: 'Needs one more character',
+     one: 'Needs one more character',
      other: 'Needs $[val] more characters',
    },
  }

Fix — rename the arm to one of the six categories, or remove it.

Only count-bearing constraints (`minLength`, `maxLength`, `min`, `max`,
…) can select a plural arm. On a non-count constraint only `other` ever
renders, so the remaining arms are dead configuration.

Example — `pattern` has no count:
  rt$errors: {
-   pattern: {one: 'One bad character', other: 'Invalid characters'},
+   pattern: 'Only letters and numbers are allowed',
  }

Fix — replace the plural object with a plain string message.

An `rt$errors` record is either ONE `rt$default` catch-all or a set of
per-constraint keys, mirroring the TypeScript union. Mixing them makes
the intent ambiguous (which message wins?).

Example:
  rt$errors: {
-   rt$default: 'Invalid name',
    minLength: 'Name is too short',
  }

Fix — keep `{rt$default: '…'}` alone, or keep the per-constraint keys
and drop `rt$default`.

`rt$`-prefixed keys are reserved for enrichment meta (`rt$label`,
`rt$errors`, `rt$items`, …); a source property with that prefix is
indistinguishable from node meta, so gen refuses the type and the
FriendlyType checker reports it here.

Fix — rename the property (a plain `$` prefix is fine; only `rt$` is
reserved):
  interface Config {
-   rt$mode: string;
+   $mode: string;
  }

The generator stamps a `@todo` line on every freshly-scaffolded const in
a FriendlyText mirror file. It means "this skeleton still carries
generated blanks". A clean, committed mirror has none.

Example — a fresh scaffold:
  /** @rtType User#a1b2c3 @rtIds {name: d4e5f6} */
- // @todo: generated skeleton — fill in real data, then delete this line
  export const friendlyUser: FriendlyText<User> = {
-   name: {rt$label: ''},
+   name: {rt$label: 'Name'},
  };

Fix — author the real labels and error messages for the const, then
delete the whole `@todo` line (the compiler never removes it for you).

The reconcile commented this FriendlyText const out because its source
type was deleted or renamed. The carcass preserves your authored labels
and messages so a reappearing type can restore them — but a clean,
committed mirror has none.

Fix — if the type is really gone, prune the carcass:
  ts-runtypes enrich --prune

Fix — if the type was renamed, re-run the reconcile; a matching carcass
is restored with your values intact:
  ts-runtypes enrich <source.ts> <NewName> --update

The reconcile commented this field out because the source type no longer
declares it. The carcass preserves your authored value inline — but a
clean, committed mirror has none.

Example:
  export const friendlyUser: FriendlyText<User> = {
-   /* @rtOrphanChild nick: {rt$label: 'Nickname'}, */
    name: {rt$label: 'Name'},
  };

Fix — if the field is really gone: `ts-runtypes enrich --prune`.
Fix — if the field was renamed, re-run `--update`; the authored value
moves to the renamed field when the ids match.

An empty string (`''`) at a `rt$label` / `rt$errors` slot is a generated
blank that never got authored — it ships blank to the UI wherever the
friendly text is shown, so it is exactly as incomplete as a `@todo`
marker. This is why removing the `@todo` line without filling the values
is not "done".

Example:
  export const friendlyUser: FriendlyText<User> = {
-   name: {rt$label: ''},
+   name: {rt$label: 'Name'},
  };

Fix — author the real label / message. Only the completeness gate
(`ts-runtypes enrich --require-complete`) fails on it; a plain
`--no-emit` health check reports it without failing.

The drift check could not read this mirror file (permissions, a broken
symlink, or a race with a concurrent write).

Fix — make the file readable and re-run `ts-runtypes enrich --no-emit`.

Each source file mirrors to ONE computed path per family under the
enrich root (friendly/… and mock/…, plus per-locale translation twins).
This file is not at its computed location — usually after a source move,
a genDir change, or a pre-split combined mirror that still needs
migrating.

Fix — re-run the generator; it writes the per-family files at the right
paths and migrates a legacy combined mirror:
  ts-runtypes enrich <source.ts> <Type> --update

The mirror's `import type { … } from '<source>'` breadcrumb resolves to
a file that is gone. Its consts describe types that no longer exist
anywhere.

Fix — if the source was deleted, delete the mirror file (both family
files and any translation twins).
Fix — if the source moved, re-run the generator from the new location
and prune the old mirror.

The mirror imports a type name its source file no longer declares (the
type was renamed or removed). The reconcile turns its consts into
`@rtOrphan` carcasses so your authored values survive.

Fix — re-run the reconcile against the current source, then prune any
carcasses that should not come back:
  ts-runtypes enrich <source.ts> <Type> --update
  ts-runtypes enrich --prune

The MockData map names a field the source type does not have (removed,
renamed, or a typo). Its pool/range can never feed a generated mock.

Example — `nick` no longer exists on the type:
  interface User { name: string }
  export const mockUser: MockData<User> = {
    name: {pool: ['Ada', 'Linus']},
-   nick: {pool: ['ada99']},
  };

Fix — remove the entry, or re-run the reconcile so the mirror follows
the type:
  ts-runtypes enrich <source.ts> <Type> --update

`rt$`-prefixed keys are reserved for enrichment meta (`rt$items`,
`rt$length`, `rt$optional`, …); a source property with that prefix is
indistinguishable from node meta, so gen refuses the type and the
MockData checker reports it here.

Fix — rename the property (a plain `$` prefix is fine; only `rt$` is
reserved):
  interface Config {
-   rt$size: number;
+   $size: number;
  }

The generator stamps a `@todo` line on every freshly-scaffolded const in
a MockData mirror file. It means "this skeleton still carries generated
blanks". A clean, committed mirror has none.

Example — a fresh scaffold:
  /** @rtType User#a1b2c3 @rtIds {name: d4e5f6} */
- // @todo: generated skeleton — fill in real data, then delete this line
  export const mockUser: MockData<User> = {
-   name: {pool: []},
+   name: {pool: ['Ada Lovelace', 'Linus Torvalds']},
  };

Fix — author realistic sample pools/ranges for the const, then delete
the whole `@todo` line (the compiler never removes it for you).

The reconcile commented this MockData const out because its source type
was deleted or renamed. The carcass preserves your authored pools and
ranges so a reappearing type can restore them — but a clean, committed
mirror has none.

Fix — if the type is really gone, prune the carcass:
  ts-runtypes enrich --prune

Fix — if the type was renamed, re-run the reconcile; a matching carcass
is restored with your values intact:
  ts-runtypes enrich <source.ts> <NewName> --update

The reconcile commented this field out because the source type no longer
declares it. The carcass preserves your authored value inline — but a
clean, committed mirror has none.

Example:
  export const mockUser: MockData<User> = {
-   /* @rtOrphanChild nick: {pool: ['ada99']}, */
    name: {pool: ['Ada', 'Linus']},
  };

Fix — if the field is really gone: `ts-runtypes enrich --prune`.
Fix — if the field was renamed, re-run `--update`; the authored value
moves to the renamed field when the ids match.

An empty pool (`pool: []`) is a generated blank that never got authored —
it mocks nothing, so it is exactly as incomplete as a `@todo` marker.
This is why removing the `@todo` line without filling the values is not
"done".

Example:
  export const mockUser: MockData<User> = {
-   name: {pool: []},
+   name: {pool: ['Ada Lovelace', 'Linus Torvalds']},
  };

Fix — author realistic sample data. Only the completeness gate
(`ts-runtypes enrich --require-complete`) fails on it; a plain
`--no-emit` health check reports it without failing.