# Schemas

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

## Purpose

Zod schemas guard every public boundary of `@suaveplan/sandbox`. The package never trusts its caller; instead, every argument that crosses the API boundary is parsed against a strict schema and rejected with a typed `SandboxError` (`INVALID_CONFIG` / `INVALID_OPTIONS` / `INVALID_MODULE`) when the shape does not match. This means downstream consumers get the same validation guarantees whether they pass typed TypeScript objects or arbitrary JSON deserialised from a network boundary.

The `parseConfig` helper additionally merges parsed partials with `DEFAULT_CONFIG` so the rest of the package consumes a fully resolved `SandboxConfig` rather than a partial. This keeps the merge logic in one place rather than re-implementing it across the facade and the engines.

## Features

- Strict-mode schemas (`.strict()`) so unknown keys are rejected.
- `parseConfig`, `parseOptions`, `parseModule` helpers that translate Zod
  errors into `SandboxError` with the right code.
- `SandboxEngineKindSchema` enum used as the discriminant for engine selection.
- `safeParse` under the hood so the error path stays on the catch-side and
  the success path stays on the happy path.

## Usage: Basic

```ts
import { parseConfig } from "@suaveplan/sandbox/schemas";

const cfg = parseConfig({ timeout: 1000, engine: "worker" });
```

## Usage: Advanced

When validating untrusted input (HTTP, IPC), surface the raw Zod issues to
the caller via `SandboxError.details.issues`:

```ts
import { SandboxError } from "@suaveplan/sandbox/error-codes";
import { parseConfig } from "@suaveplan/sandbox/schemas";

try {
    parseConfig(JSON.parse(httpBody));
} catch (err) {
    if (err instanceof SandboxError) {
        return Response.json({ issues: err.details.issues }, { status: 400 });
    }
    throw err;
}
```

## API Reference

- `SandboxConfigPartialSchema` — `z.ZodObject` for `Partial<SandboxConfig>`.
- `SandboxOptionsSchema` — `z.ZodObject` for `SandboxOptions`.
- `SandboxModuleSchema` — `z.ZodObject` for `SandboxModule`.
- `SandboxEngineKindSchema` — `z.ZodEnum<['vm','worker','spawn','isolate']>`.
- `parseConfig(raw): SandboxConfig` — merges with `DEFAULT_CONFIG`.
- `parseOptions(raw): SandboxOptions`.
- `parseModule(raw): SandboxModule`.

## Implementation Notes

`onAuditLog` is validated via `z.custom` rather than `z.function` because Zod's
function schema would otherwise wrap the callback in a runtime validator and
break referential equality, breaking the "consumer-passes-its-own-callback"
contract. The custom validator only checks `typeof === "function"` (or
undefined), which is the actual invariant the consumer cares about.