TL;DR — Two related cleanups around the optional/catch/transform interaction. Restores 4.3 behavior where z.preprocess(fn, T) accepts absent object keys, and propagates the internal fallback flag through pipe boundaries so that optional() wrapping a catch().transform()/.pipe(...) chain still clobbers the recovered value with undefined on missing input. Also ships an internal wiki/optionality.md reference covering the full optin/optout/fallback machinery.

Key changes

• Restore preprocess on absent object keys — $ZodTransform now sets optin = "optional" at runtime, which $ZodPreprocess inherits through pipe, so z.object({ a: z.preprocess(fn, T) }).parse({}) runs fn(undefined) as it did pre-fix(v4): align object and tuple optionality handling #5661.
• Preserve preprocess(...).optional().parse(undefined) === undefined — $ZodTransform stamps payload.fallback = true on every invocation so an outer $ZodOptional still short-circuits to undefined even though the inner transform ran.
• Carry the flag through handlePipeResult — the fresh payload passed to the right-hand schema now includes fallback alongside value and issues.
• Rename caught → fallback on ParsePayload — describes the consumer contract ("outer wrapper, override me if you have a better value") rather than the specific producer; updated at $ZodCatch set-sites and the $ZodOptional read-site.
• Drop $ZodPreprocess constructor body — the defineLazy overrides for optin/optout are gone; pipe inheritance from $ZodTransform handles both axes.
• Internal wiki/optionality.md — reference doc covering optin × optout × fallback, who sets and reads each, pipe propagation, static/runtime divergence, a full case walkthrough, and why z.unknown().transform(fn).pipe(T) stays strict on absent input.
• Regression tests — covers preprocess on absent keys with and without optional, plus optional() over catch().transform()/.pipe() chains, multi-transform chains, and object-property membership.

_{Summary ｜ 5 files ｜ 5 commits ｜ base: main ← fix-fallback-flag-and-preprocess}

preprocess accepts absent object keys again

Before: After #5661 tightened the object parser, z.object({ a: z.preprocess(fn, T) }).parse({}) started failing on absent keys, breaking the common pattern of using preprocess to inject pre-parse defaults for missing fields.
After: $ZodTransform declares optin = "optional" at runtime; $ZodPreprocess inherits that through its in side of the pipe, so $ZodObject treats absent keys as legal and fn runs with undefined exactly as it did in 4.3.

The fix is now expressed at the transform level rather than as a preprocess-specific override, which means z.transform(fn) itself also accepts absent input — a consistent rule ("any schema with a user-written escape hatch accepts undefined at runtime"). The old defineLazy overrides on $ZodPreprocess are gone; pipe inheritance does the work.

To keep the multi-year-stable preprocess(fn, T).optional().parse(undefined) === undefined behavior, $ZodTransform also flags every invocation as fallback, which $ZodOptional already knows to clobber when input was undefined.

core/schemas.ts · preprocess.test.ts

Fallback flag survives pipe boundaries

Before: handlePipeResult allocated { value, issues } for the right side, dropping the flag $ZodCatch set when catchValue substitutes, so z.string().catch("X").transform((s) => s + "!").optional().parse(undefined) returned "X!" instead of undefined.
After: the right-side payload is seeded with fallback: left.fallback, so $ZodOptional still sees the flag after any number of transforms or explicit .pipe() hops and clobbers the fallback on undefined input.

Any chain shaped like catch().transform()…optional() or catch().pipe(...)…optional() was losing the signal that the inner had recovered, so optional surfaced the catch value instead of undefined. Fix is a one-line propagation in handlePipeResult.

core/schemas.ts · catch.test.ts

caught → fallback rename

Before: The flag was named after its one producer ($ZodCatch), coupling the contract to a specific schema type.
After: The name describes what consumers should do — treat the value as a fallback that an outer wrapper may override when input was undefined. Now set by both $ZodCatch and $ZodTransform.

Field is @internal, so there's no public surface change. Follows up on #5937 / #5939.

core/schemas.ts · classic/schemas.ts

Internal optionality reference

Before: The optin / optout / fallback / aborted signals lived only in code and scattered PR threads (#5661, #5917, #5929, #5937, #5939, #5941).
After: wiki/optionality.md documents the three runtime signals, who sets and reads each, the static/runtime divergence pattern (catch, transform, preprocess), pipe propagation, a concrete case walkthrough, and why z.unknown().transform(fn).pipe(T) stays strict on absent input despite containing a transform.

Meant as an internal reference rather than user-facing docs — frames the design principle ("flexible inputs, strict outputs at runtime") and the rule of thumb for which schema kinds accept absent input.

wiki/optionality.md

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}