Initial Commit

packages/devtools/tooling/sandbox/src/schemas/schemas.md

@@ -0,0 +1,65 @@
+# 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.