fix: Simplify coercion: unify ArkType and Standard Schema paths with pre-coercion model

[yamcodes]

Fixes #1178

Unifies the coercion execution model between the default arkenv and arkenv/standard entry points. Uses a pre-coercion flow that shallow-copies the env object and applies coercion prior to validation against the unmodified schema.

Changes

• Replace ArkType's .pipe() coercion wrapper with pre-coercion flow using findCoercionPaths + applyCoercion directly in packages/arkenv/src/arktype/index.ts
• Delete the redundant wrapper file packages/arkenv/src/arktype/coercion/coerce.ts and its re-export
• Update coerce.test.ts unit tests to use a local helper mapping the pre-coercion flow
• Update coercion documentation, FAQ, Standard Schema docs, and ADR-0002

[changeset-bot]

🦋 Changeset detected

Latest commit: 1fbfeaf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
arkenv	Patch
@arkenv/bun-plugin	Patch
@arkenv/nextjs	Patch
@arkenv/vite-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

arkenv

npm i https://pkg.pr.new/arkenv@1193

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@1193

@arkenv/cli

npm i https://pkg.pr.new/@arkenv/cli@1193

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@1193

@arkenv/nextjs

npm i https://pkg.pr.new/@arkenv/nextjs@1193

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@1193

commit: 1fbfeaf

[arkenv-bot]

📦 Bundle Size Report

Package	Size	Limit	Diff	Status
arkenv	1.72 kB	1.95 kB	-0.6%	✅
arkenv/standard	2.13 kB	2.25 kB	+0.5%	✅
arkenv/core	441 B	500 B	0.0%	✅

✅ All size limits passed!

[arkenv-bot]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (Asia/Almaty)
arkenv	Ready	Preview, Comment	Jun 12 2026, 12:10 PM (Asia/Almaty)

[pullfrog]

✅ No new issues found.

Reviewed changes — removes the .pipe()-based coercion wrapper with its unsafe type cast and unifies the ArkType path with the Standard Schema pre-coercion model.

• Delete coerce() wrapper — removes packages/arkenv/src/arktype/coercion/coerce.ts and its barrel re-export, eliminating the at("unknown").pipe(...).pipe(schema) as BaseType<t, $> pattern.
• Inline coercion in parse() — packages/arkenv/src/arktype/index.ts now calls findCoercionPaths + applyCoercion directly, matching the existing flow in parse-standard.ts.
• Update coercion tests — coerce.test.ts replaces the deleted import with a local helper that mirrors the production pre-coercion flow.
• Update documentation — coercion.mdx, faq.mdx, and ADR-0002 all reflect the unified model.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[yamcodes]

Just a few /typescript questions but it's good

I'd also ensure a /jsdoc pass and double check the /changeset although that looked good to me

[pullfrog]

✅ No new issues found.

Reviewed changes — addresses all four TypeScript review comments from the prior review with type narrowing, import simplification, JSDoc, and a generic return type on applyCoercion.

• Narrowed fallback context type — changed from (ctx: any) to (ctx: { base: unknown }) in both parse() and the test helper.
• Removed as any / as Record<string, unknown> casts — changed findCoercionPaths parameter from Record<string, any> to unknown, and added a generic <T> to applyCoercion so coercion preserves the input type.
• Added JsonSchemaNode interface in coercion/shared.ts — replaces ad-hoc Record<string, any> property access with a single internal cast, plus an Array.isArray(node) guard on the early return.
• Simplified imports — new coercion/index.ts barrel re-exports ./morphs and ./shared; callers now import from @/coercion instead of @/coercion/shared.
• Added JSDoc — @param, @returns, and @throws for arkErrorsToIssues and parse.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}