How the codebase validates every untyped boundary with TypeBox — what helper to reach for, what shape a schema takes, and how to migrate from older Zod patterns.

The principle: validate, then trust. Every input from outside (HTTP, JSON.parse, plugin manifests, persisted JSON on disk) goes through a TypeBox schema. Inside the boundary, the code treats the value as the schema says it is — no as Foo casts.

Schemas are the source of truth. Domain types come from Static<typeof Schema>. There is no parallel interface Foo next to FooSchema.

• Helpers live in src/core/utils/typeboxHelpers.ts — Type, Value, Static, withFallback, parseValue, safeParseValue, filterArray, formatValueErrors.
• Compiled validators live in src/core/utils/typeboxCompiler.ts — compiled, compiledCheck, compiledDecode, compiledSafeParseValue, compiledFormatValueErrors. Hot repeated Check / Decode / Errors paths should use these or helpers that already call them.
• JSON boundary helpers live in src/core/utils/jsonValidate.ts — safeParseJson, parseJsonWithFallback, parseJsonResponse.
• Canonical client HTTP layer: @core/http — apiRequest(path, { schema, … }) (the default for JSON browser→server calls), apiBlobRequest(path, …) for binary responses, plus ApiError, isAbortError, readEnvelope, responseErrorMessage, ErrorEnvelopeSchema. All defined in src/core/http/apiClient.ts.
• Schemas are source of truth. type Foo = Static<typeof FooSchema> — never a hand-rolled interface beside the schema.
• Soft fallbacks for corrupted local storage / optional config use withFallback(schema, default) + parseJsonWithFallback.
• Hard fallbacks for required documents throw and bubble to an error boundary.
• zod is banned repo-wide. The AI drivers hit each provider's REST API directly and pass TypeBox schemas through as JSON Schema, so nothing imports Zod anymore; the package has been removed from package.json. Gated by ai-driver-isolation.test.ts.

Use for inputs where invalid data is genuinely an error: HTTP request bodies, HTTP response envelopes the UI needs, required configuration files.

import { Type, parseValue } from '@core/utils/typeboxHelpers'

const RequestBodySchema = Type.Object({
  email:    Type.String({ format: 'email' }),
  password: Type.String({ minLength: 1 }),
})

const body = parseValue(RequestBodySchema, await req.json())
// body is now typed and validated; throws on invalid input

Use for inputs where corruption shouldn't brick the UI: localStorage reads, optional persisted settings, tolerant array parsing where one bad entry shouldn't invalidate the rest.

import { parseJsonWithFallback } from '@core/utils/jsonValidate'

const prefs = parseJsonWithFallback(
  localStorage.getItem('editorPrefs') ?? '',
  EditorPreferencesSchema,
  DEFAULT_PREFERENCES,
)
// prefs is always valid; corrupted storage falls back silently

import { Type, type Static } from '@core/utils/typeboxHelpers'

export const FooSchema = Type.Object({
  id:        Type.String(),
  count:     Type.Number({ minimum: 0 }),
  optional:  Type.Optional(Type.String()),
  tags:      Type.Array(Type.String()),
})

export type Foo = Static<typeof FooSchema>
//   id: string
//   count: number
//   optional?: string
//   tags: string[]

Never write interface Foo next to FooSchema. The schema is the source of truth. If the type drifts from the schema, the schema wins.

TypeBox's Value.Check / Value.Decode / Value.Errors interpret the schema each time. Repeated API response parsing, data-row-heavy screens, import validation, plugin protocol payloads, and other hot paths should use the compiled helpers. Compilation is cached by schema object identity, so define reusable schemas at module scope.

import { compiledCheck, compiledDecode } from '@core/utils/typeboxCompiler'

if (!compiledCheck(DataRowSchema, raw)) {
  throw new Error('Invalid data row')
}
const row = compiledDecode(DataRowSchema, raw)

Do not replace parseValue just because a path is repeated. parseValue intentionally uses TypeBox's full Value.Parse pipeline: clone, clean, defaults, conversion, assertion, and decode. Keep it where callers depend on defaulting/conversion/cleaning, or replace it only after adding tests that prove those semantics are no longer needed.

import { Type } from '@core/utils/typeboxHelpers'
import { badRequest, jsonResponse, readValidatedBody } from '../http'

const CreatePostSchema = Type.Object({
  title: Type.String({ minLength: 1, maxLength: 200 }),
  body:  Type.String(),
})

const body = await readValidatedBody(req, CreatePostSchema)
if (!body) return badRequest('Invalid request body')
// body is typed; proceed.

import { Type } from '@core/utils/typeboxHelpers'
import { apiRequest } from '@core/http'

const PostsResponseSchema = Type.Object({
  rows: Type.Array(PostSchema),
})

// Canonical client call: sets credentials, validates the body, throws ApiError.
const data = await apiRequest('/admin/api/cms/posts', { schema: PostsResponseSchema })
// data.rows is typed

// Code that already holds a Response (e.g. the persistence layer, which injects
// its own fetch) validates with readEnvelope instead:
//   const data = await readEnvelope(res, PostsResponseSchema, 'Failed to load posts')

import { safeParseJson, parseJsonWithFallback } from '@core/utils/jsonValidate'

// Hard: corruption is an error
const result = safeParseJson(localStorage.getItem('mustBeValid') ?? '', Schema)
if (!result.ok) {
  console.error('[prefs] corrupted store:', result.error)
  throw result.error
}
const data = result.value

// Soft: corruption falls back to defaults
const prefs = parseJsonWithFallback(
  localStorage.getItem('editorPrefs') ?? '',
  EditorPreferencesSchema,
  DEFAULT_PREFERENCES,
)

import { Type, filterArray } from '@core/utils/typeboxHelpers'

const FontEntrySchema = Type.Object({ family: Type.String(), url: Type.String() })

// Site document with 5 fonts; one entry has a missing url.
// filterArray keeps the 4 good ones rather than failing the whole document.
const fonts = filterArray(FontEntrySchema, rawSite.fonts)

import { Type, withFallback } from '@core/utils/typeboxHelpers'

const SiteSettingsSchema = Type.Object({
  theme:       withFallback(Type.String(), 'dark'),
  breakpoints: withFallback(Type.Array(BreakpointSchema), DEFAULT_BREAKPOINTS),
})

The annotation is read by parsers like parseWithFallbackAnnotation to fill in missing values during a tolerant parse.

Every CMS handler error returns { error: string }. apiRequest reads it automatically (via responseErrorMessage) and throws an ApiError carrying the HTTP status — so callers branch on the error type instead of re-checking res.ok:

import { apiRequest, ApiError } from '@core/http'

try {
  const site = await apiRequest('/admin/api/cms/site', {
    schema: SiteEnvelopeSchema,
    fallbackMessage: 'Failed to load site',
  })
} catch (err) {
  if (err instanceof ApiError && err.status === 403) {
    // render "no access" state
  }
  throw err
}

apiRequest is the default for browser→server calls. readEnvelope is the equivalent for code that already holds a Response.

For UI states that need to distinguish causes (e.g. "invalid page slug" vs. "duplicate slug"), use a typed subclass with a path field:

export class SiteValidationError extends Error {
  readonly path: string
  constructor(message: string, path: string) {
    super(`[persistence/validate] ${path}: ${message}`)
    this.name = 'SiteValidationError'
    this.path = path
  }
}

path is a dot-separated string identifying the field ('site.pages[0].slug'). The [persistence/validate] prefix is injected in the constructor — callers pass just the path. Already-existing typed errors in the codebase: SiteValidationError, VisualComponentNameError, VisualComponentParamNameError, VisualComponentRecursionError. Add one when the UI needs to render a specific error state.

The codebase migrated off Zod. If you encounter a remaining Zod pattern, translate it:

There are no Zod exemptions. Provider drivers call REST/SSE APIs directly and pass TypeBox schemas through as JSON Schema for tool inputs. Gated by an import scan.

Common boundaries already wrapped — extend the same pattern when you add a new one:

• docs/architecture.md — system overview (TypeBox at every boundary)
• docs/server.md — server validation patterns
• docs/editor.md — editor store + persistence
• Source-of-truth files:
  • src/core/utils/typeboxHelpers.ts — helper layer (parseValue, withFallback, filterArray, etc.)
  • src/core/utils/typeboxCompiler.ts — cached TypeCompiler layer for hot validation execution
  • src/core/utils/jsonValidate.ts — JSON boundary helpers
  • src/core/http/apiClient.ts — apiRequest, apiBlobRequest, ApiError, isAbortError, readEnvelope, assertOk, responseErrorMessage, ErrorEnvelopeSchema
  • src/core/persistence/responseSchemas.ts — shared CMS HTTP response schemas
  • src/core/persistence/validate.ts — validateSite, validatePages, ValidatePagesOptions, SiteValidationError
  • src/core/plugins/manifest.ts — parsePluginManifest
  • server/http.ts — readValidatedBody, jsonResponse, badRequest
  • server/ai/drivers/ — direct provider HTTP drivers; tools are declared with their TypeBox inputSchema passed through as JSON Schema (no Zod)
• Gate tests:
  • src/__tests__/architecture/boundary-validation.test.ts — enforces five boundary rules: (1) no res.json() as in persistence or admin; (2) no JSON.parse as in persistence; (3) no raw fetch( in admin; (4) no raw req.json( in server handlers; (5) no body.field as DeepType after readEnvelope/parseJsonResponse in persistence — embed the field's TypeBox schema in the envelope instead; allowlist interface-only deep types with §5.x
  • src/__tests__/architecture/ai-driver-isolation.test.ts — enforces provider-SDK and zod isolation: @anthropic-ai/sdk, @anthropic-ai/claude-agent-sdk, @openai/agents, @openrouter/agent, and zod are banned repo-wide; @modelcontextprotocol/sdk is scoped to server/ai/mcp/ only