# Contract > The contract & validation surface — runtime type guards, guard combinators, flat parsers, and a shape DSL. Narrow `unknown` safely, compose guards, coerce-and-extract a field, or declare a value's shape once and compile it into a guard, parser, JSON Schema, and generator that can never drift. Source: [`src/core`](../../src/core). Surfaced through the `@src/core` barrel. Validation is where untrusted data — an HTTP body, a parsed JSON blob, a tool argument — crosses into typed code. This module is that crossing: it turns `unknown` into a narrowed `T` (or a clean `undefined`) without ever throwing, so a hostile input becomes a `false`, not a crash. It deliberately ships **flat, total primitives** instead of a full schema framework — every guard is a one-argument pure function, the parsers coerce-or-bail rather than collect errors, and the JSON surface is the lazy boundary, not a recursive validator. The one place recursion is needed (a contract over a nested shape) is opt-in through the shape DSL, where the tree is finite and developer-authored. The payoff: nothing here can hang on a cycle, blow the stack on adversarial depth, or silently let a bad value through. ## Surface A guard is the `Guard` type from [`types.ts`](../../src/core/types.ts): ```ts type Guard = (value: unknown) => value is T ``` Every guard takes one `unknown`, returns a `boolean` TypeScript reads as a type predicate, and **never throws** — a value that doesn't fit is simply `false`, even on adversarial input (cycles, hostile prototypes). They are total, pure functions of their argument (AGENTS §14), so they are safe to call on anything, in any order, at any trust boundary. Three sibling families, three jobs: - **Validators** (`is*`) answer "_is_ this value a `T`?" — a boolean predicate that narrows in place. No coercion, no transform. - **Combinators** (`*Of`) build a fresh `Guard<…>` out of existing guards (and accept any bare `(value: unknown) => boolean` predicate), so a complex guard is composed, never hand-written. - **Parsers** (`parse*`) answer "give me a `T` _or_ `undefined`" — they coerce (`'36'` → `36`) and return the typed value or `undefined`, never throwing. Each parser forms a **sound** pair with the guard for its output type (AGENTS §14): a guard-valid input is returned unchanged, and every non-`undefined` output satisfies that guard, so you can parse-then-trust. The `*Field` parsers read a (possibly nested) record field via a `FieldPath` (`string | readonly string[]`, in [`src/core/types.ts`](../../src/core/types.ts)) — a single string is **one** key (no dot-splitting); an array descends nested objects/arrays through the `resolveField` core helper. The `whereOf` / `lazyOf` / `transformOf` combinators run caller-supplied callbacks _inside_ a guard body; they contain any throw via the core `attempt` helper, so even a guard that runs your code stays total and returns `false` rather than propagating. ### Primitive & null-ish guards | Guard | Kind | Narrows to | Behavior | | ------------------- | -------- | ----------------- | ------------------------------------------------------------------------------------ | | `isNull` | function | `null` | Strict `value === null`. | | `isUndefined` | function | `undefined` | Strict `value === undefined`. | | `isDefined` | function | `T` | True unless `null` _or_ `undefined` — `0`, `''`, `false` are defined. | | `isString` | function | `string` | `typeof === 'string'`. | | `isNumber` | function | `number` | `typeof === 'number'` — **`NaN` / `±Infinity` pass** (they are numbers). | | `isFiniteNumber` | function | `number` | `isNumber` refined by `Number.isFinite` — rejects `NaN` / `±Infinity`. | | `isInteger` | function | `number` | `isFiniteNumber` refined by `Number.isInteger`; the sound partner of `parseInteger`. | | `isBoolean` | function | `boolean` | `typeof === 'boolean'`; `0` / `1` do **not** pass. | | `isTrue` | function | `true` | Strict `value === true`. | | `isFalse` | function | `false` | Strict `value === false`. | | `isBigInt` | function | `bigint` | `typeof === 'bigint'`. | | `isSymbol` | function | `symbol` | `typeof === 'symbol'`. | | `isNullableString` | function | `string \| null` | `null`, or a `string`. | | `isNullableNumber` | function | `number \| null` | `null`, or a `number` (`NaN` / `±Infinity` pass). | | `isNullableBoolean` | function | `boolean \| null` | `null`, or a `boolean`. | ### Structural & collection guards | Guard | Kind | Narrows to | Behavior | | --------------------- | -------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isObject` | function | `object` | `typeof === 'object' && !== null` — **arrays and class instances pass**, `null` does not. | | `isRecord` | function | `Record` | Plain objects only: rejects arrays / `null`; realm-agnostic prototype-chain test (prototype is `null`, or its own prototype is `null`) so a plain object from another realm still passes while `Date` / class instances fail. | | `isMap` | function | `ReadonlyMap` | `instanceof Map`. | | `isSet` | function | `ReadonlySet` | `instanceof Set`. | | `isWeakMap` | function | `WeakMap` | `instanceof WeakMap`. | | `isWeakSet` | function | `WeakSet