@apifuse/provider-sdk 2.2.0-beta.24 → 2.2.0-beta.26

package/src/schema.ts

@@ -83,8 +83,42 @@ export function safeParseSchemaSync(
 export const APIFUSE_SENSITIVE_META_KEY = "x-apifuse-sensitive";
 export const APIFUSE_SENSITIVE_KIND_META_KEY = "x-apifuse-sensitive-kind";
 export const APIFUSE_DESCRIPTION_KEY_META_KEY = "x-apifuse-description-key";
+export const APIFUSE_TEXT_TRUST_META_KEY = "x-apifuse-text-trust";
 export const APIFUSE_REDACTION_MARKER = "<redacted>";
 
+export type TextTrust = "trusted" | "untrusted";
+
+export interface TextTrustMetadata {
+	readonly v: 1;
+	readonly trust: TextTrust;
+	readonly carrier?: "container";
+}
+
+export type OutputTextTrustMap = Readonly<Record<string, TextTrust>>;
+
+/**
+ * Auto-trusted output leaves are string-valued `z.literal()` / `z.enum()`,
+ * patterns whose every top-level alternative is anchored at both ends and
+ * whose bodies use only finite quantifiers, have a maximum match length of 32,
+ * and contain only digits and safe punctuation in positive whitespace-free
+ * character classes, literals/escapes, and ordinary or non-capturing groups,
+ * plus the structurally constrained formats listed here. A brand is trusted
+ * only when its underlying schema meets one of those rules. Letter-bearing
+ * identifiers, length-only strings, and other formats (including email, URL,
+ * base64, and JWT) are not trusted.
+ */
+export const AUTO_TRUSTED_ZOD_STRING_FORMATS = [
+	"cidrv4",
+	"cidrv6",
+	"date",
+	"datetime",
+	"duration",
+	"e164",
+	"ipv4",
+	"ipv6",
+	"time",
+] as const;
+
 export type SensitivePathSegment = string | "*";
 export type SensitivePath = readonly SensitivePathSegment[];
 export type SensitiveFieldKind =
@@ -127,9 +161,19 @@ export function describeKey<TSchema extends ZodType>(
 	});
 }
 
+/** Attach output text-trust authoring metadata without changing validation. */
+export function textTrust<TSchema extends ZodType>(schema: TSchema, trust: TextTrust): TSchema {
+	const metadata = schema.meta() ?? {};
+	return schema.meta({
+		...metadata,
+		[APIFUSE_TEXT_TRUST_META_KEY]: { v: 1, trust } satisfies TextTrustMetadata,
+	});
+}
+
 declare module "zod" {
 	interface ZodType {
 		describeKey(key: ProviderLocaleKey | string): this;
+		textTrust(trust: TextTrust): this;
 	}
 }
 
@@ -140,16 +184,101 @@ const describeKeyMethod = function <TSchema extends ZodType>(
 	return describeKey(this, key);
 };
 
-function installDescribeKeyOnPrototype(prototype: unknown): void {
-	const target = prototype as (Record<string, unknown> & { describeKey?: unknown }) | null;
-	if (!target || typeof target.describeKey === "function") {
+const textTrustMethod = function <TSchema extends ZodType>(
+	this: TSchema,
+	trust: TextTrust,
+): TSchema {
+	return textTrust(this, trust);
+};
+
+interface StaticOutputFallback {
+	readonly value: unknown;
+}
+
+const staticOutputFallbacks = new WeakMap<object, StaticOutputFallback>();
+let suppressDynamicOutputFallbacks = 0;
+
+function trackOutputFallback(schema: unknown, fallback: unknown): void {
+	if (!(schema instanceof z.ZodType)) return;
+	const def = schema._zod.def;
+	if (typeof fallback !== "function") {
+		staticOutputFallbacks.set(def, { value: fallback });
 		return;
 	}
-	Object.defineProperty(target, "describeKey", {
-		configurable: true,
-		value: describeKeyMethod,
-		writable: true,
-	});
+	if (def.type === "default") {
+		const descriptor = Object.getOwnPropertyDescriptor(def, "defaultValue");
+		if (!descriptor?.get) return;
+		const originalGetter = descriptor.get;
+		Object.defineProperty(def, "defaultValue", {
+			...descriptor,
+			get(this: object) {
+				if (suppressDynamicOutputFallbacks > 0) return null;
+				return Reflect.apply(originalGetter, this, []);
+			},
+		});
+		return;
+	}
+	if (def.type === "catch") {
+		const catchValue = Reflect.get(def, "catchValue");
+		if (typeof catchValue !== "function") return;
+		Reflect.set(def, "catchValue", function (this: unknown, ...args: unknown[]) {
+			if (suppressDynamicOutputFallbacks > 0) return null as never;
+			return Reflect.apply(catchValue, this, args) as never;
+		});
+	}
+}
+
+const trackedFallbackPrototypes = new WeakSet<object>();
+
+function installOutputFallbackTrackingOnPrototype(prototype: unknown): void {
+	if (!prototype || typeof prototype !== "object" || trackedFallbackPrototypes.has(prototype)) {
+		return;
+	}
+	trackedFallbackPrototypes.add(prototype);
+	Reflect.apply(z.ZodType.init, z.ZodType, [Object.create(prototype), { type: "custom" }]);
+	for (const methodName of ["default", "catch"] as const) {
+		const descriptor = Object.getOwnPropertyDescriptor(prototype, methodName);
+		if (!descriptor?.configurable || !descriptor.get) continue;
+		const originalGetter = descriptor.get;
+		Object.defineProperty(prototype, methodName, {
+			...descriptor,
+			get(this: object) {
+				const originalMethod = Reflect.apply(originalGetter, this, []);
+				if (typeof originalMethod !== "function") return originalMethod;
+				const trackedMethod = function (this: unknown, fallback: unknown) {
+					const result = Reflect.apply(originalMethod, this, [fallback]);
+					trackOutputFallback(result, fallback);
+					return result;
+				};
+				Object.defineProperty(this, methodName, {
+					configurable: true,
+					enumerable: true,
+					value: trackedMethod,
+					writable: true,
+				});
+				return trackedMethod;
+			},
+		});
+	}
+}
+
+function installSchemaMetadataMethodsOnPrototype(prototype: unknown): void {
+	const target = prototype as Record<string, unknown> | null;
+	if (!target) return;
+	if (typeof target.describeKey !== "function") {
+		Object.defineProperty(target, "describeKey", {
+			configurable: true,
+			value: describeKeyMethod,
+			writable: true,
+		});
+	}
+	if (typeof target.textTrust !== "function") {
+		Object.defineProperty(target, "textTrust", {
+			configurable: true,
+			value: textTrustMethod,
+			writable: true,
+		});
+	}
 }
 
 for (const [name, value] of Object.entries(z)) {
@@ -159,7 +288,8 @@ for (const [name, value] of Object.entries(z)) {
 	if (typeof value !== "function") {
 		continue;
 	}
-	installDescribeKeyOnPrototype(value.prototype);
+	installSchemaMetadataMethodsOnPrototype(value.prototype);
+	installOutputFallbackTrackingOnPrototype(value.prototype);
 }
 
 const RESERVED_SENSITIVE_KEYS = new Set([
@@ -238,6 +368,927 @@ export const fields = {
 		sensitiveString("token", "Provider access or refresh token.", options),
 } as const;
 
+type TextTrustDeclaration = TextTrust | "absent" | "invalid";
+
+type InternalZodSchema = z.core.$ZodTypes;
+type InternalZodDef = InternalZodSchema["_zod"]["def"];
+
+interface OutputTextLeaf {
+	readonly classification: TextTrust;
+	readonly classified: boolean;
+}
+
+interface OutputTextTrustCollection {
+	readonly leaves: Array<OutputTextLeaf & { readonly path: string }>;
+	readonly debtPaths: Set<string>;
+}
+
+export class OutputTextTrustSchemaError extends TypeError {
+	readonly code = "invalid_output_text_trust_schema";
+
+	constructor(value: unknown) {
+		const receivedType = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+		super(`Output text-trust collection requires a Zod schema; received ${receivedType}.`);
+		this.name = "OutputTextTrustSchemaError";
+	}
+}
+
+export class OutputTextTrustCollectionError extends Error {
+	readonly classification = "untrusted" as const;
+	readonly code = "output_text_trust_collection_failed";
+
+	constructor(
+		public readonly schemaPath: string,
+		cause: unknown,
+	) {
+		super(`Output text-trust collection failed at schema path ${schemaPath}.`);
+		this.name = "OutputTextTrustCollectionError";
+		this.cause = cause;
+	}
+}
+
+/**
+ * Collect every textual leaf in a Zod output schema as a deterministic
+ * schema-path-to-classification object. The path grammar is rooted at `$`:
+ * object keys are `["key"]`, arrays and record values are `[*]`, tuple slots
+ * are `[n]`, union/intersection alternatives are `<union:n>` / `<intersection:n>`,
+ * record keys are `<record-key>`, and one bounded cycle expansion is marked
+ * `<recursive>`.
+ */
+export function collectOutputTextTrust(schema: ZodType): OutputTextTrustMap {
+	const { leaves } = collectOutputTextLeaves(requireOutputTextTrustSchema(schema));
+	return Object.fromEntries(
+		leaves
+			.map(({ path, classification }) => [path, classification] as const)
+			.sort(([left], [right]) => left.localeCompare(right)),
+	);
+}
+
+/** Report textual output paths that lack a valid explicit or auto-derived classification. */
+export function findUnclassifiedOutputTextPaths(schema: ZodType): string[] {
+	const { debtPaths, leaves } = collectOutputTextLeaves(requireOutputTextTrustSchema(schema));
+	for (const { classified, path } of leaves) {
+		if (!classified) debtPaths.add(path);
+	}
+	return [...debtPaths].sort((left, right) => left.localeCompare(right));
+}
+
+/** @internal Used by contract JSON Schema projection. */
+export function resolveOutputTextTrust(
+	schema: z.core.$ZodType,
+	inheritedUntrusted = false,
+): TextTrust | undefined {
+	const resolved = resolveOutputTextTrustProjection(schema);
+	return resolved?.[inheritedUntrusted ? "inherited" : "local"];
+}
+
+/** @internal Resolve both projection states from one stable schema traversal. */
+export function resolveOutputTextTrustProjection(
+	schema: z.core.$ZodType,
+): { readonly inherited: TextTrust; readonly local: TextTrust } | undefined {
+	const resolved = resolveOutputTextLeafPair(asInternalZodSchema(schema), [], true);
+	return resolved
+		? {
+				inherited: resolved.inherited.classification,
+				local: resolved.local.classification,
+			}
+		: undefined;
+}
+
+/** @internal Whether this node can bypass or mutate descendant validation guarantees. */
+export function invalidatesDescendantOutputTextAutoTrust(schema: z.core.$ZodType): boolean {
+	return invalidatesOutputTextAutoTrust(asInternalZodSchema(schema)._zod.def);
+}
+
+/** @internal Run output projection without evaluating dynamic fallback callbacks. */
+export function suppressDynamicOutputFallbacksDuring<T>(project: () => T): T {
+	suppressDynamicOutputFallbacks += 1;
+	try {
+		return project();
+	} finally {
+		suppressDynamicOutputFallbacks -= 1;
+	}
+}
+
+/** @internal Whether this mutator has a static fallback that cannot contain text. */
+export function mutatorReturnIsProvablyNonText(schema: z.core.$ZodType): boolean {
+	const def = asInternalZodSchema(schema)._zod.def;
+	if (def.type !== "default" && def.type !== "catch") return false;
+	const fallback = staticOutputFallbacks.get(def);
+	return fallback !== undefined && outputFallbackValueIsProvablyNonText(fallback.value);
+}
+
+/** @internal Whether this mutator has a static array fallback. */
+export function mutatorUsesStaticArrayFallback(schema: z.core.$ZodType): boolean {
+	const def = asInternalZodSchema(schema)._zod.def;
+	if (def.type !== "default" && def.type !== "catch") return false;
+	const fallback = staticOutputFallbacks.get(def);
+	return fallback !== undefined && Array.isArray(fallback.value);
+}
+
+/** @internal Whether this default or catch was authored with a callback. */
+export function hasDynamicOutputFallback(schema: z.core.$ZodType): boolean {
+	const def = asInternalZodSchema(schema)._zod.def;
+	return (def.type === "default" || def.type === "catch") && !staticOutputFallbacks.has(def);
+}
+
+/** @internal Used by contract JSON Schema projection. */
+export function inheritsUntrustedOutputTextTrust(schema: z.core.$ZodType): boolean {
+	let current = asInternalZodSchema(schema);
+	while (true) {
+		if (readTextTrustDeclaration(current) === "untrusted") return true;
+		const inner = flattenedOutputSchema(current._zod.def);
+		if (!inner) return false;
+		current = inner;
+	}
+}
+
+function outputFallbackValueIsProvablyNonText(value: unknown): boolean {
+	return (
+		value === null ||
+		typeof value === "boolean" ||
+		typeof value === "number" ||
+		(Array.isArray(value) && value.every(outputFallbackValueIsProvablyNonText))
+	);
+}
+
+function collectOutputTextLeaves(schema: InternalZodSchema): OutputTextTrustCollection {
+	const leaves: Array<OutputTextLeaf & { readonly path: string }> = [];
+	const debtPaths = new Set<string>();
+	const emittedPaths = new Set<string>();
+	walkOutputSchema(schema, "$", leaves, debtPaths, emittedPaths, new Set(), false, false, true);
+	return { leaves, debtPaths };
+}
+
+function walkOutputSchema(
+	schema: InternalZodSchema,
+	path: string,
+	out: Array<OutputTextLeaf & { readonly path: string }>,
+	debtPaths: Set<string>,
+	emittedPaths: Set<string>,
+	activeSchemas: Set<InternalZodSchema>,
+	expandingCycle: boolean,
+	inheritedUntrusted: boolean,
+	autoTrustAllowed: boolean,
+): void {
+	try {
+		walkOutputSchemaUnchecked(
+			schema,
+			path,
+			out,
+			debtPaths,
+			emittedPaths,
+			activeSchemas,
+			expandingCycle,
+			inheritedUntrusted,
+			autoTrustAllowed,
+		);
+	} catch (error) {
+		if (error instanceof OutputTextTrustCollectionError) throw error;
+		throw new OutputTextTrustCollectionError(path, error);
+	}
+}
+
+function walkOutputSchemaUnchecked(
+	schema: InternalZodSchema,
+	path: string,
+	out: Array<OutputTextLeaf & { readonly path: string }>,
+	debtPaths: Set<string>,
+	emittedPaths: Set<string>,
+	activeSchemas: Set<InternalZodSchema>,
+	expandingCycle: boolean,
+	inheritedUntrusted: boolean,
+	autoTrustAllowed: boolean,
+): void {
+	const alreadyActive = activeSchemas.has(schema);
+	if (alreadyActive) {
+		if (!expandingCycle) {
+			walkOutputSchema(
+				schema,
+				`${path}<recursive>`,
+				out,
+				debtPaths,
+				emittedPaths,
+				new Set(),
+				true,
+				inheritedUntrusted,
+				autoTrustAllowed,
+			);
+		}
+		return;
+	}
+
+	const leaf = resolveOutputTextLeaf(schema, [], autoTrustAllowed, inheritedUntrusted);
+	if (leaf) {
+		if (!emittedPaths.has(path)) {
+			emittedPaths.add(path);
+			out.push({ path, ...leaf });
+		}
+		return;
+	}
+
+	const def = schema._zod.def;
+	const declaration = readTextTrustDeclaration(schema);
+	if (declaration === "trusted" || declaration === "invalid") debtPaths.add(path);
+	const descendantUntrusted = inheritedUntrusted || declaration === "untrusted";
+	const descendantAutoTrustAllowed = autoTrustAllowed && !invalidatesOutputTextAutoTrust(def);
+	if (
+		invalidatesOutputTextAutoTrust(def) &&
+		!mutatorReturnIsProvablyNonText(schema) &&
+		!mutatorCanUseCollectedTextItems(schema) &&
+		!emittedPaths.has(path)
+	) {
+		emittedPaths.add(path);
+		out.push({
+			classification: "untrusted",
+			classified: descendantUntrusted,
+			path,
+		});
+	}
+	if (!alreadyActive) activeSchemas.add(schema);
+	try {
+		switch (def.type) {
+			case "object": {
+				for (const [key, child] of Object.entries(def.shape).sort(([left], [right]) =>
+					left.localeCompare(right),
+				)) {
+					walkOutputSchema(
+						asInternalZodSchema(child),
+						`${path}[${JSON.stringify(key)}]`,
+						out,
+						debtPaths,
+						emittedPaths,
+						activeSchemas,
+						expandingCycle,
+						descendantUntrusted,
+						descendantAutoTrustAllowed,
+					);
+				}
+				if (def.catchall) {
+					if (asInternalZodSchema(def.catchall)._zod.def.type !== "never") {
+						const catchallKeyPath = `${path}<catchall-key>`;
+						if (!emittedPaths.has(catchallKeyPath)) {
+							emittedPaths.add(catchallKeyPath);
+							out.push({
+								classification: "untrusted",
+								classified: descendantUntrusted,
+								path: catchallKeyPath,
+							});
+						}
+					}
+					walkOutputSchema(
+						asInternalZodSchema(def.catchall),
+						`${path}[*]`,
+						out,
+						debtPaths,
+						emittedPaths,
+						activeSchemas,
+						expandingCycle,
+						descendantUntrusted,
+						descendantAutoTrustAllowed,
+					);
+				}
+				break;
+			}
+			case "array":
+				walkOutputSchema(
+					asInternalZodSchema(def.element),
+					`${path}[*]`,
+					out,
+					debtPaths,
+					emittedPaths,
+					activeSchemas,
+					expandingCycle,
+					descendantUntrusted,
+					descendantAutoTrustAllowed,
+				);
+				break;
+			case "tuple": {
+				def.items.forEach((child, index) => {
+					walkOutputSchema(
+						asInternalZodSchema(child),
+						`${path}[${index}]`,
+						out,
+						debtPaths,
+						emittedPaths,
+						activeSchemas,
+						expandingCycle,
+						descendantUntrusted,
+						descendantAutoTrustAllowed,
+					);
+				});
+				if (def.rest) {
+					walkOutputSchema(
+						asInternalZodSchema(def.rest),
+						`${path}[*]`,
+						out,
+						debtPaths,
+						emittedPaths,
+						activeSchemas,
+						expandingCycle,
+						descendantUntrusted,
+						descendantAutoTrustAllowed,
+					);
+				}
+				break;
+			}
+			case "record":
+				walkOutputSchema(
+					asInternalZodSchema(def.keyType),
+					`${path}<record-key>`,
+					out,
+					debtPaths,
+					emittedPaths,
+					activeSchemas,
+					expandingCycle,
+					descendantUntrusted,
+					descendantAutoTrustAllowed,
+				);
+				walkOutputSchema(
+					asInternalZodSchema(def.valueType),
+					`${path}[*]`,
+					out,
+					debtPaths,
+					emittedPaths,
+					activeSchemas,
+					expandingCycle,
+					descendantUntrusted,
+					descendantAutoTrustAllowed,
+				);
+				break;
+			case "union":
+				def.options.forEach((child, index) => {
+					walkOutputSchema(
+						asInternalZodSchema(child),
+						`${path}<union:${index}>`,
+						out,
+						debtPaths,
+						emittedPaths,
+						activeSchemas,
+						expandingCycle,
+						descendantUntrusted,
+						descendantAutoTrustAllowed,
+					);
+				});
+				break;
+			case "intersection":
+				for (const [index, side] of [def.left, def.right].entries()) {
+					walkOutputSchema(
+						asInternalZodSchema(side),
+						`${path}<intersection:${index}>`,
+						out,
+						debtPaths,
+						emittedPaths,
+						activeSchemas,
+						expandingCycle,
+						descendantUntrusted,
+						descendantAutoTrustAllowed,
+					);
+				}
+				break;
+			case "optional":
+			case "nullable":
+			case "default":
+			case "prefault":
+			case "catch":
+			case "readonly":
+			case "nonoptional":
+			case "promise":
+				walkOutputSchema(
+					asInternalZodSchema(def.innerType),
+					path,
+					out,
+					debtPaths,
+					emittedPaths,
+					activeSchemas,
+					expandingCycle,
+					descendantUntrusted,
+					descendantAutoTrustAllowed,
+				);
+				break;
+			case "pipe":
+				walkOutputSchema(
+					asInternalZodSchema(def.out),
+					path,
+					out,
+					debtPaths,
+					emittedPaths,
+					activeSchemas,
+					expandingCycle,
+					descendantUntrusted,
+					descendantAutoTrustAllowed,
+				);
+				break;
+			case "lazy":
+				walkOutputSchema(
+					asInternalZodSchema(def.getter()),
+					path,
+					out,
+					debtPaths,
+					emittedPaths,
+					activeSchemas,
+					expandingCycle,
+					descendantUntrusted,
+					descendantAutoTrustAllowed,
+				);
+				break;
+			case "string":
+			case "template_literal":
+			case "literal":
+			case "enum":
+			case "number":
+			case "bigint":
+			case "boolean":
+			case "date":
+			case "symbol":
+			case "undefined":
+			case "null":
+			case "any":
+			case "unknown":
+			case "never":
+			case "void":
+			case "map":
+			case "set":
+			case "function":
+			case "custom":
+			case "transform":
+			case "nan":
+			case "success":
+			case "file":
+				break;
+			default:
+				assertNeverZodDef(def);
+		}
+	} finally {
+		if (!alreadyActive) activeSchemas.delete(schema);
+	}
+}
+
+function mutatorCanUseCollectedTextItems(schema: InternalZodSchema): boolean {
+	if (!mutatorUsesStaticArrayFallback(schema)) return false;
+	const inner = flattenedOutputSchema(schema._zod.def);
+	if (inner?._zod.def.type !== "array") return false;
+	return collectOutputTextLeaves(asInternalZodSchema(inner._zod.def.element)).leaves.length > 0;
+}
+
+function resolveOutputTextLeaf(
+	schema: InternalZodSchema,
+	outerDeclarations: readonly TextTrustDeclaration[],
+	autoTrustAllowed: boolean,
+	inheritedUntrusted: boolean,
+): OutputTextLeaf | undefined {
+	const resolved = resolveOutputTextLeafPair(schema, outerDeclarations, autoTrustAllowed);
+	return resolved?.[inheritedUntrusted ? "inherited" : "local"];
+}
+
+function resolveOutputTextLeafPair(
+	schema: InternalZodSchema,
+	outerDeclarations: readonly TextTrustDeclaration[],
+	autoTrustAllowed: boolean,
+): { readonly inherited: OutputTextLeaf; readonly local: OutputTextLeaf } | undefined {
+	const declarations = [...outerDeclarations, readTextTrustDeclaration(schema)];
+	const def = schema._zod.def;
+	if (!isOutputTextLeafDef(def)) {
+		const inner = flattenedOutputSchema(def);
+		return inner
+			? resolveOutputTextLeafPair(
+					inner,
+					declarations,
+					autoTrustAllowed && !invalidatesOutputTextAutoTrust(def),
+				)
+			: undefined;
+	}
+
+	const autoTrusted =
+		autoTrustAllowed && !invalidatesOutputTextAutoTrust(def) && isAutoTrustedOutputTextLeaf(schema);
+	const explicitTrustAllowed = autoTrustAllowed && !invalidatesOutputTextAutoTrust(def);
+	return {
+		inherited: classifyOutputTextLeaf(declarations, autoTrusted, explicitTrustAllowed, true),
+		local: classifyOutputTextLeaf(declarations, autoTrusted, explicitTrustAllowed, false),
+	};
+}
+
+function classifyOutputTextLeaf(
+	declarations: readonly TextTrustDeclaration[],
+	autoTrusted: boolean,
+	explicitTrustAllowed: boolean,
+	inheritedUntrusted: boolean,
+): OutputTextLeaf {
+	if (declarations.includes("invalid")) {
+		return { classification: "untrusted", classified: false };
+	}
+	if (declarations.includes("untrusted")) {
+		return { classification: "untrusted", classified: true };
+	}
+	if (declarations.includes("trusted")) {
+		return {
+			classification: explicitTrustAllowed ? "trusted" : "untrusted",
+			classified: explicitTrustAllowed,
+		};
+	}
+	if (inheritedUntrusted) {
+		return { classification: "untrusted", classified: true };
+	}
+	return autoTrusted
+		? { classification: "trusted", classified: true }
+		: { classification: "untrusted", classified: false };
+}
+
+function flattenedOutputSchema(def: InternalZodDef): InternalZodSchema | undefined {
+	switch (def.type) {
+		case "optional":
+		case "nullable":
+		case "default":
+		case "prefault":
+		case "catch":
+		case "readonly":
+		case "nonoptional":
+		case "promise":
+			return asInternalZodSchema(def.innerType);
+		case "pipe":
+			return asInternalZodSchema(def.out);
+		case "lazy":
+			return asInternalZodSchema(def.getter());
+		case "string":
+		case "template_literal":
+		case "literal":
+		case "enum":
+		case "number":
+		case "bigint":
+		case "boolean":
+		case "date":
+		case "symbol":
+		case "undefined":
+		case "null":
+		case "any":
+		case "unknown":
+		case "never":
+		case "void":
+		case "object":
+		case "array":
+		case "tuple":
+		case "record":
+		case "union":
+		case "intersection":
+		case "map":
+		case "set":
+		case "function":
+		case "custom":
+		case "transform":
+		case "nan":
+		case "success":
+		case "file":
+			return undefined;
+		default:
+			return assertNeverZodDef(def);
+	}
+}
+
+function isOutputTextLeafDef(def: InternalZodDef): boolean {
+	switch (def.type) {
+		case "string":
+		case "template_literal":
+			return true;
+		case "literal":
+			return def.values.some((value) => typeof value === "string");
+		case "enum":
+			return Object.values(def.entries).some((value) => typeof value === "string");
+		case "any":
+		case "unknown":
+		case "custom":
+		case "transform":
+			return true;
+		default:
+			return false;
+	}
+}
+
+function isAutoTrustedOutputTextLeaf(schema: InternalZodSchema): boolean {
+	const def = schema._zod.def;
+	if (hasUnsafeOutputCheck(def)) return false;
+	if (def.type === "literal" || def.type === "enum") return isOutputTextLeafDef(def);
+	if (def.type !== "string" && def.type !== "template_literal") return false;
+
+	const { bag, pattern } = schema._zod;
+	if (hasSdkOwnedStringFormatValidator(schema)) {
+		return true;
+	}
+
+	if (pattern instanceof RegExp && isRestrictiveAnchoredPattern(pattern)) return true;
+	const patterns = bag.patterns;
+	return (
+		patterns instanceof Set &&
+		patterns.size > 0 &&
+		[...patterns].every(
+			(candidate) => candidate instanceof RegExp && isRestrictiveAnchoredPattern(candidate),
+		)
+	);
+}
+
+function hasUnsafeOutputCheck(def: InternalZodDef): boolean {
+	const checks = Reflect.get(def, "checks");
+	return (
+		Array.isArray(checks) &&
+		checks.some((check) => {
+			if (!check || typeof check !== "object") return false;
+			const internals = Reflect.get(check, "_zod");
+			if (!internals || typeof internals !== "object") return false;
+			const checkDef = Reflect.get(internals, "def");
+			if (!checkDef || typeof checkDef !== "object") return false;
+			const kind = Reflect.get(checkDef, "check");
+			return kind === "overwrite" || kind === "custom";
+		})
+	);
+}
+
+function invalidatesOutputTextAutoTrust(def: InternalZodDef): boolean {
+	return (
+		def.type === "default" ||
+		def.type === "catch" ||
+		def.type === "transform" ||
+		hasUnsafeOutputCheck(def)
+	);
+}
+
+interface OwnedStringFormatValidator {
+	readonly constructor: unknown;
+	readonly patternFlags: string;
+	readonly patternSource: string;
+}
+
+const SDK_OWNED_STRING_FORMAT_VALIDATORS: readonly OwnedStringFormatValidator[] = [
+	z.cidrv4(),
+	z.cidrv6(),
+	z.iso.date(),
+	z.iso.datetime(),
+	z.iso.duration(),
+	z.e164(),
+	z.ipv4(),
+	z.ipv6(),
+	z.iso.time(),
+].map((validator) => {
+	const pattern = Reflect.get(validator._zod.def, "pattern");
+	if (!(pattern instanceof RegExp)) {
+		throw new TypeError("SDK-owned Zod string format validator is missing its pattern.");
+	}
+	return {
+		constructor: validator.constructor,
+		patternFlags: pattern.flags,
+		patternSource: pattern.source,
+	};
+});
+
+function hasSdkOwnedStringFormatValidator(schema: InternalZodSchema): boolean {
+	const candidates: unknown[] = [schema];
+	const checks = Reflect.get(schema._zod.def, "checks");
+	if (Array.isArray(checks)) candidates.push(...checks);
+	return candidates.some((candidate) => {
+		if (!candidate || typeof candidate !== "object") return false;
+		const internals = Reflect.get(candidate, "_zod");
+		if (!internals || typeof internals !== "object") return false;
+		const def = Reflect.get(internals, "def");
+		if (!def || typeof def !== "object" || Reflect.has(def, "fn")) return false;
+		const pattern = Reflect.get(def, "pattern");
+		if (!(pattern instanceof RegExp)) return false;
+		return SDK_OWNED_STRING_FORMAT_VALIDATORS.some(
+			(owned) =>
+				Reflect.get(candidate, "constructor") === owned.constructor &&
+				pattern.source === owned.patternSource &&
+				pattern.flags === owned.patternFlags,
+		);
+	});
+}
+
+function isRestrictiveAnchoredPattern(pattern: RegExp): boolean {
+	if (pattern.multiline) return false;
+	const alternatives = splitTopLevelRegexAlternatives(pattern.source);
+	if (alternatives.length === 0) return false;
+	let maximumLength = 0;
+	for (const alternative of alternatives) {
+		if (!alternative.startsWith("^") || !alternative.endsWith("$")) return false;
+		const analysis = analyzeProvablyRestrictedRegexBody(alternative.slice(1, -1));
+		if (!analysis) return false;
+		maximumLength = Math.max(maximumLength, analysis.maximumLength);
+	}
+	return maximumLength <= MAXIMUM_AUTO_TRUSTED_REGEX_LENGTH;
+}
+
+function splitTopLevelRegexAlternatives(source: string): string[] {
+	const alternatives: string[] = [];
+	let start = 0;
+	let escaped = false;
+	let inCharacterClass = false;
+	let groupDepth = 0;
+	for (let index = 0; index < source.length; index += 1) {
+		const character = source[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (character === "[") {
+			inCharacterClass = true;
+			continue;
+		}
+		if (character === "]") {
+			inCharacterClass = false;
+			continue;
+		}
+		if (inCharacterClass) continue;
+		if (character === "(") {
+			groupDepth += 1;
+			continue;
+		}
+		if (character === ")") {
+			groupDepth -= 1;
+			continue;
+		}
+		if (character === "|" && groupDepth === 0) {
+			alternatives.push(source.slice(start, index));
+			start = index + 1;
+		}
+	}
+	alternatives.push(source.slice(start));
+	return alternatives;
+}
+
+interface RestrictedRegexAnalysis {
+	readonly maximumLength: number;
+}
+
+interface SafeRegexCharacterClassAnalysis extends RestrictedRegexAnalysis {
+	readonly consumedLength: number;
+}
+
+const MAXIMUM_AUTO_TRUSTED_REGEX_LENGTH = 32;
+
+function analyzeProvablyRestrictedRegexBody(source: string): RestrictedRegexAnalysis | undefined {
+	let index = 0;
+	const parseAlternatives = (): RestrictedRegexAnalysis | undefined => {
+		let maximumLength = 0;
+		while (true) {
+			const sequence = parseSequence();
+			if (!sequence) return undefined;
+			maximumLength = Math.max(maximumLength, sequence.maximumLength);
+			if (source[index] !== "|") break;
+			index += 1;
+		}
+		return { maximumLength };
+	};
+	const parseSequence = (): RestrictedRegexAnalysis | undefined => {
+		let maximumLength = 0;
+		while (index < source.length && source[index] !== "|" && source[index] !== ")") {
+			const atom = parseAtom();
+			if (!atom) return undefined;
+			let maximumRepetitions = 1;
+			if (source[index] === "?") {
+				index += 1;
+			} else if (source[index] === "{") {
+				const match = /^\{(\d+)(?:,(\d+))?\}/.exec(source.slice(index));
+				if (!match) return undefined;
+				const minimum = Number(match[1]);
+				maximumRepetitions = match[2] === undefined ? minimum : Number(match[2]);
+				if (
+					!Number.isSafeInteger(minimum) ||
+					!Number.isSafeInteger(maximumRepetitions) ||
+					maximumRepetitions < minimum
+				)
+					return undefined;
+				index += match[0].length;
+			}
+			if (source[index] === "?") index += 1;
+			maximumLength = addRestrictedRegexLengths(
+				maximumLength,
+				multiplyRestrictedRegexLength(atom.maximumLength, maximumRepetitions),
+			);
+		}
+		return { maximumLength };
+	};
+	const parseAtom = (): RestrictedRegexAnalysis | undefined => {
+		if (source[index] === "(") {
+			index += 1;
+			if (source[index] === "?") {
+				if (source.slice(index, index + 2) !== "?:") return undefined;
+				index += 2;
+			}
+			const group = parseAlternatives();
+			if (!group || source[index] !== ")") return undefined;
+			index += 1;
+			return group;
+		}
+		if (source[index] === "[") {
+			const characterClass = analyzeSafeRegexCharacterClass(source.slice(index));
+			if (!characterClass) return undefined;
+			index += characterClass.consumedLength;
+			return characterClass;
+		}
+		const atomLength = safeRegexAtomLength(source.slice(index));
+		if (atomLength === 0) return undefined;
+		index += atomLength;
+		return { maximumLength: 1 };
+	};
+
+	const analysis = parseAlternatives();
+	return analysis && index === source.length ? analysis : undefined;
+}
+
+function analyzeSafeRegexCharacterClass(
+	source: string,
+): SafeRegexCharacterClassAnalysis | undefined {
+	if (!source.startsWith("[") || source[1] === "^") return undefined;
+	for (let index = 1; index < source.length; index += 1) {
+		const character = source[index];
+		if (character === "]") {
+			return { consumedLength: index + 1, maximumLength: 1 };
+		}
+
+		const atomLength = safeRegexAtomLength(source.slice(index));
+		if (atomLength === 0) return undefined;
+		const rangeSeparator = index + atomLength;
+		if (source[rangeSeparator] === "-" && source[rangeSeparator + 1] !== "]") {
+			const endIndex = rangeSeparator + 1;
+			const endLength = safeRegexAtomLength(source.slice(endIndex));
+			if (endLength === 0 || !isSafeRegexCharacterRange(source, index, endIndex)) return undefined;
+			index = endIndex + endLength - 1;
+			continue;
+		}
+		index += atomLength - 1;
+	}
+	return undefined;
+}
+
+function addRestrictedRegexLengths(left: number, right: number): number {
+	return left > MAXIMUM_AUTO_TRUSTED_REGEX_LENGTH - right
+		? MAXIMUM_AUTO_TRUSTED_REGEX_LENGTH + 1
+		: left + right;
+}
+
+function multiplyRestrictedRegexLength(length: number, repetitions: number): number {
+	if (length === 0 || repetitions === 0) return 0;
+	return repetitions > Math.floor(MAXIMUM_AUTO_TRUSTED_REGEX_LENGTH / length)
+		? MAXIMUM_AUTO_TRUSTED_REGEX_LENGTH + 1
+		: length * repetitions;
+}
+
+function safeRegexAtomLength(source: string): number {
+	const character = source[0];
+	if (character === undefined) return 0;
+	if (/^[0-9]$/.test(character)) return 1;
+	if (character === "-") return 1;
+	if (character !== "\\") return 0;
+	const escaped = source[1];
+	if (escaped === "d") return 2;
+	return escaped !== undefined && SAFE_REGEX_ESCAPED_PUNCTUATION.includes(escaped) ? 2 : 0;
+}
+
+function isSafeRegexCharacterRange(source: string, startIndex: number, endIndex: number): boolean {
+	const start = regexCharacterClassLiteralCodePoint(source, startIndex);
+	const end = regexCharacterClassLiteralCodePoint(source, endIndex);
+	if (start === undefined || end === undefined || start > end) return false;
+	const minimum = "0".codePointAt(0);
+	const maximum = "9".codePointAt(0);
+	return minimum !== undefined && maximum !== undefined && start >= minimum && end <= maximum;
+}
+
+function regexCharacterClassLiteralCodePoint(source: string, index: number): number | undefined {
+	const character = source[index];
+	if (character !== "\\") return character?.codePointAt(0);
+	const escaped = source[index + 1];
+	if (escaped === undefined || escaped === "d" || escaped === "w") return undefined;
+	return escaped.codePointAt(0);
+}
+
+const SAFE_REGEX_ESCAPED_PUNCTUATION = "\\.-^$*+?()[]{}|";
+
+function requireOutputTextTrustSchema(schema: unknown): InternalZodSchema {
+	if (!(schema instanceof z.ZodType)) throw new OutputTextTrustSchemaError(schema);
+	return asInternalZodSchema(schema);
+}
+
+function asInternalZodSchema(schema: z.core.$ZodType): InternalZodSchema {
+	// Zod's child-definition fields use the base type and erase the concrete
+	// union member. This is the only cast boundary; all callers immediately
+	// narrow the returned discriminated definition by `def.type`.
+	return schema as InternalZodSchema;
+}
+
+function assertNeverZodDef(def: never): never {
+	throw new Error(`Unsupported Zod definition: ${String((def as { type?: unknown }).type)}`);
+}
+
+function readTextTrustDeclaration(schema: unknown): TextTrustDeclaration {
+	const metadata = readZodMetadata(schema);
+	if (!metadata || !Reflect.has(metadata, APIFUSE_TEXT_TRUST_META_KEY)) return "absent";
+	const value = Reflect.get(metadata, APIFUSE_TEXT_TRUST_META_KEY);
+	if (!value || typeof value !== "object") return "invalid";
+	if (Reflect.get(value, "v") !== 1) return "invalid";
+	const trust = Reflect.get(value, "trust");
+	return trust === "trusted" || trust === "untrusted" ? trust : "invalid";
+}
+
 export function isSensitiveSchema(schema: unknown): boolean {
 	const metadata = readZodMetadata(schema);
 	return metadata !== undefined && Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true;