# Behavior traces — colinhacks/zod

> Canonical page: https://codevetter.com/unpack/zod/behavior-traces

# Behavior traces — colinhacks/zod

Scanned commit 10dda3a3a4bc76ed0bf83e994de194587e489ef8 (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

The most important flows begin at package import, schema construction, and a public parse call. The interpreted and compiled paths intentionally converge on the same runtime fallback for errors, while JSON Schema conversion follows a separate graph traversal. Recursive parsing adds a context-scoped memoization layer without changing the public parse contract. The documentation site has its own static content request path layered on top of Fumadocs and MDX.
- Import trace: `src/index.ts` loads `v4/classic/external.ts`; that module exposes classic schemas, checks, errors, parse functions, core helpers, JSON Schema conversion, locales, ISO validators, and coercion factories. — [packages/zod/src/index.ts#L1-7](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/index.ts#L1-L7) [packages/zod/src/v4/classic/external.ts#L1-57](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/classic/external.ts#L1-L57)
- Construction trace: `z.object(shape)` creates `ZodObject`; `ZodObject` ensures the default memoizer, initializes `$ZodObject`, initializes `ZodType`, attaches JSON Schema processing, and ultimately lets `$constructor` run deferred initializers and any global post-processor. — [packages/zod/src/v4/classic/schemas.ts#L1566-1769](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/classic/schemas.ts#L1566-L1769) [packages/zod/src/v4/core/core.ts#L73-145](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/core.ts#L73-L145) [packages/zod/src/v4/core/schemas.ts#L2152-2195](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/schemas.ts#L2152-L2195)
- Successful sync parse trace: `schema.parse(data)` calls classic `parse.parse`, which calls core `_parse`, then `schema._zod.run`; an object run allocates a result, runs each child, merges property results, and returns the transformed value when no issues remain. — [packages/zod/src/v4/classic/schemas.ts#L297-305](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/classic/schemas.ts#L297-L305) [packages/zod/src/v4/classic/parse.ts#L8-27](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/classic/parse.ts#L8-L27) [packages/zod/src/v4/core/parse.ts#L22-35](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/parse.ts#L22-L35) [packages/zod/src/v4/core/schemas.ts#L2196-2239](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/schemas.ts#L2196-L2239)
- Failed sync parse trace: a leaf or container appends raw issues, parents prefix nested paths, `_parse` maps each issue through `finalizeIssue`, constructs the configured error class, restores a useful stack, and throws. — [packages/zod/src/v4/core/schemas.ts#L1973-2014](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/schemas.ts#L1973-L2014) [packages/zod/src/v4/core/parse.ts#L23-34](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/parse.ts#L23-L34) [packages/zod/src/v4/core/errors.ts#L182-217](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/errors.ts#L182-L217)
- Safe parse trace: `_safeParse` runs the same schema graph but returns `{success: true, data}` or a failure object whose `error` getter creates and caches the finalized error only when accessed. — [packages/zod/src/v4/core/parse.ts#L65-103](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/parse.ts#L65-L103)
- Async trace: `parseAsync` sets `ctx.async`, awaits promise-returning schema runs, then performs the same issue finalization; synchronous entrypoints instead throw `$ZodAsyncError` when a promise escapes. — [packages/zod/src/v4/core/parse.ts#L41-63](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/parse.ts#L41-L63) [packages/zod/src/v4/core/parse.ts#L71-80](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/parse.ts#L71-L80) [packages/zod/src/v4/core/core.ts#L166-170](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/core.ts#L166-L170)
- Global compile trace: importing `zod/compile` installs `globalConfig.postProcessor`; each later schema receives a one-shot shim; its first eligible parse calls `compile(..., {strict:true})`, replaces itself with the compiled run on success, or permanently restores the interpreter on refusal. — [packages/zod/src/compile.ts#L13-55](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/compile.ts#L13-L55) [packages/zod/src/v4/core/core.ts#L118-133](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/core.ts#L118-L133)
- Compiled failure trace: the generated parser returns `INVALID`; `withParser` sets the fallback flag and invokes the captured original run, preventing nested compiled wrappers from repeatedly executing user callbacks while preserving runtime-generated errors. — [packages/zod/src/v4/core/compile.ts#L158-197](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/compile.ts#L158-L197) [wiki/compile.md#L18-30](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/wiki/compile.md#L18-L30)
- Cycle trace: a recursive container's memoized wrapper creates context state, caches an output placeholder before children parse, returns that placeholder on a repeated input visit, and records final issues after synchronous or asynchronous completion. — [packages/zod/src/v4/core/memoizer.ts#L240-319](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/memoizer.ts#L240-L319)
- JSON Schema trace: `toJSONSchema` initializes the processor registry, calls `processSchema`, extracts definitions for cycles or reuse, finalizes references and metadata, and returns either one schema document or a registry map with shared definitions. — [packages/zod/src/v4/core/json-schema-processors.ts#L834-874](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/json-schema-processors.ts#L834-L874) [packages/zod/src/v4/core/json-schema-processors.ts#L878-933](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/json-schema-processors.ts#L878-L933) [packages/zod/src/v4/core/to-json-schema.ts#L568-757](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/zod/src/v4/core/to-json-schema.ts#L568-L757)
- Docs request trace: the catch-all route resolves a page through `source.getPage`, derives LLM-friendly markdown with `getLLMText`, renders the compiled MDX body with shared components, and statically enumerates all routes through `source.generateParams`. — [packages/docs/app/(doc)/[[...slug]]/page.tsx#L17-84](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/docs/app/(doc)/%5B%5B...slug%5D%5D/page.tsx#L17-L84) [packages/docs/loaders/get-llm-text.ts#L14-42](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/docs/loaders/get-llm-text.ts#L14-L42) [packages/docs/loaders/source.ts#L9-26](https://github.com/colinhacks/zod/blob/10dda3a3a4bc76ed0bf83e994de194587e489ef8/packages/docs/loaders/source.ts#L9-L26)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)