Validator mode (make ArkType optional, support Standard Schema directly)

[yamcodes]

Decision

ArkEnv will make ArkType optional by introducing an explicit validator mode.

This issue documents the rationale for this decision by comparing it against other viable approaches and explaining why explicit mode is the chosen solution.

Considered Alternatives and Rationale

We'll compare three approaches for supporting optional ArkType in ArkEnv.

The core goals are:

• Keep ArkType a first-class citizen
• Allow ArkEnv to work without ArkType installed
• Maintain clear semantics, strong types, and long-term maintainability

---

Option A (Rejected): Implicit Hybrid (#720)

Description

ArkEnv inspects the provided schema at runtime and automatically decides whether to:

• Use ArkType (string DSL, compiled schemas, lazy proxies), or
• Use Standard Schema validators (Zod, Valibot, etc.) without ArkType

ArkType is treated as an optional peer dependency and loaded lazily when required.

Pros

• Zero configuration for users
• “It just works” for most cases
• ArkType feels seamlessly integrated
• Backward compatible with existing usage

Cons

• High internal complexity (detection, branching, lazy loading)
• Type inference becomes wide and less precise
• Debugging behavior requires understanding internal heuristics
• Harder to reason about guarantees and failure modes
• Increased test surface and maintenance cost
• Refactors tend to cascade across multiple subsystems

Summary

Maximum DX, maximum complexity. Powerful, but fragile as the codebase grows.

---

Option B: Explicit Mode (Recommended)

Description

Users explicitly choose the validation strategy via configuration:

createEnv(schema, { validator: "standard" })
createEnv(schema, { validator: "arktype" })

• standard
  • Uses only key -> validated(value) via Standard Schema
  • ArkType is never loaded
  • String DSL is not allowed
• arktype
  • ArkType is required (checked once at runtime)
  • All validation flows through ArkType
  • Standard Schema works via ArkType’s native support

Pros

• Dramatically simpler internal logic
• Clear mental model and predictable behavior
• ArkType remains explicitly first-class
• Tighter and more accurate TypeScript types
• Easier to test and debug
• Strong long-term maintainability

Cons

• Slightly more configuration required
• Less “magic” behavior

Summary

Cleanest architecture and strongest foundation. Optimizes for correctness, clarity, and longevity.

---

Option C (Rejected): Auto Mode (Hybrid + Explicit)

Description

Introduces a third mode while keeping backward compatibility:

validator: "standard" | "arktype" | "auto" // default: "auto"

• auto behaves like the current hybrid system
• standard and arktype force explicit behavior

Pros

• Backward compatible
• Smooth migration path
• Users can opt out of auto-detection when needed

Cons

• Retains most of the hybrid complexity
• Auto mode still requires detection heuristics
• Documentation and mental model become heavier
• Users may rely on auto indefinitely and hit edge cases

Summary

Good transitional strategy, but not a clean end-state.

---

Comparison Table

Dimension	Hybrid (Current)	Explicit Mode	Auto Mode
Internal complexity	❌ High	✅ Low	⚠️ Medium
User configuration	✅ None	⚠️ Required	✅ Optional
Type safety	❌ Weak	✅ Strong	⚠️ Mixed
Debuggability	❌ Hard	✅ Clear	⚠️ Mixed
ArkType positioning	⚠️ Implicit	✅ First-class	⚠ Conditional
Long-term maintainability	❌ Risky	✅ Excellent	⚠️ Acceptable
Migration friendliness	✅	❌	✅

---

Final Decision

ArkEnv will adopt Explicit Validator Mode as the mechanism for making ArkType optional.

This approach provides the clearest mental model, the lowest internal complexity,
and the strongest long-term foundation for ArkEnv, while preserving ArkType as a
first-class validation engine.