# `schemas`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Owns the Zod boundary schemas that every public generator function uses to validate its `opts` argument. Schema mismatch throws `PwgenError(PWGEN.INVALID_OPTIONS)` with the original `ZodError` attached as `cause`, so callers can introspect the failing field path while keeping the typed error code stable for logging.

Strict-mode schemas reject unknown fields rather than silently dropping them — typos like `requrieDigits` (with a transposed `i`) surface immediately instead of being ignored at runtime. Three schemas are exported: `GeneratePasswordOptionsSchema`, `GeneratePassphraseOptionsSchema`, and `EntropyOptionsSchema`.

## Features

- Strict-object schemas reject unknown fields.
- Positive-integer guards on `length`-shaped fields.
- Discriminated `wordlist` accepts `"long"`, `"short"`, an inline `string[]`, or any registry name.
- All three schemas are invoked from at least one production call site (the conformance script verifies this).

## Usage: Basic Example

```ts
import { GeneratePasswordOptionsSchema } from "@suaveplan/password-generator/schemas";

const result = GeneratePasswordOptionsSchema.safeParse({ length: 16 });
if (!result.success) throw result.error;
```

## Usage: Advanced Example

```ts
import {
 EntropyOptionsSchema,
 GeneratePassphraseOptionsSchema,
} from "@suaveplan/password-generator/schemas";

// Pre-validate user-supplied JSON before forwarding to the generator
function fromJson(raw: unknown) {
 const parsed = GeneratePassphraseOptionsSchema.parse(raw);
 return parsed;
}

// Compose with downstream schemas
import z from "zod";
const apiBody = z.object({
 mode: z.literal("passphrase"),
 opts: GeneratePassphraseOptionsSchema,
});
```

## API Reference

- `GeneratePasswordOptionsSchema` — strict object mirroring `GeneratePasswordOptions`.
- `GeneratePassphraseOptionsSchema` — strict object mirroring `GeneratePassphraseOptions`. `length` is optional in the schema (the generator applies the default `6`).
- `EntropyOptionsSchema` — strict object mirroring `EntropyOptions`.

## Implementation Notes

The schemas live in a single feature module to keep the conformance script's `src/schemas/` discovery simple — the script walks that directory and verifies every exported `*Schema` is invoked via `.parse(` or `.safeParse(` somewhere outside the directory. This pattern also matches the layout the `cbor`, `validation`, and `vault` packages already use, so reviewers don't need to context-switch.

Strict-object semantics are non-negotiable for boundary surfaces — Zod's default `passthrough` would let typos silently pass through to the generator and corrupt observability (a `requireDigit` typo with a missing `s` would not enable required-digit quotas but `recordError` would never fire). The trade-off — slightly more verbose error messages when adding new options forces a schema update in the same commit — is the entire point of the gate.