Summary
Decide the lasting product stance for the Vite/Bun schema/define path (arkenv(schema) + native accessors + .d.ts / ImportMetaEnvAugmented), then document the canonical env object surface accordingly.
ADR 0015 / #1105 originally permanently branded this path as SPA mode. Continuity-alone is not enough justification (see #1423 discussion). The env-module transform (#1328) shipped without resolving escape-hatch-forever vs deprecate/remove — that call happens here, before CLI (#1332) and docs implementation lock it in.
Product call — LOCKED: Option 3 (Remove / don’t offer) for v1
After reviewing the transform DX and weighing long-term maintenance costs, we proceed with Option 3:
- Drop the schema/define path completely on v1.
import { env } from "./env" is the single canonical surface.- v0 (
dev): leave schema/define working as-is (no break for stable production apps).
- DCE loss through the object is an accepted trade-off.
See triage comments for the full decision text, cascaded issue updates (#1105, #1332, #1440), and the agent brief.
Docs scope (implementation — ready for agent)
- Vite/Bun/Next/Nuxt guides lead exclusively with
import { env } from "./env".
- Do not create a dedicated v1 page or buried note for schema/define — migration guide only.
- Document ADR 0015 trade-offs that still apply: DCE loss through the object; flat-layout name/type leak + strict layout escape hatch. Overturn SPA-mode permanence.
- Security guide: client/server boundary for Vite/Bun (runtime guard + ADR 0013 strict-layout blocking) in user-facing terms.
- Update examples to the canonical surface; drop legacy SPA examples.
- Update the
arkenv agent skill to teach the unified surface only for v1.
Landing
v1 branch only (docs deploy per ADR 0006 dual-branch flow). Depends on #1328 / #1329 / #1330 for full docs accuracy; product call is done. Part of #1105 (ADR: #1326).
Gates cleared: #1332 unblocked; #1440 closed out of scope. Package API removal of schema/define is out of scope for this issue (dedicated v1 chore).
Summary
Decide the lasting product stance for the Vite/Bun schema/define path (
arkenv(schema)+ native accessors +.d.ts/ImportMetaEnvAugmented), then document the canonical env object surface accordingly.ADR 0015 / #1105 originally permanently branded this path as SPA mode. Continuity-alone is not enough justification (see #1423 discussion). The env-module transform (#1328) shipped without resolving escape-hatch-forever vs deprecate/remove — that call happens here, before CLI (#1332) and docs implementation lock it in.
Product call — LOCKED: Option 3 (Remove / don’t offer) for v1
After reviewing the transform DX and weighing long-term maintenance costs, we proceed with Option 3:
import { env } from "./env"is the single canonical surface.dev): leave schema/define working as-is (no break for stable production apps).See triage comments for the full decision text, cascaded issue updates (#1105, #1332, #1440), and the agent brief.
Docs scope (implementation — ready for agent)
import { env } from "./env".arkenvagent skill to teach the unified surface only for v1.Landing
v1 branch only (docs deploy per ADR 0006 dual-branch flow). Depends on #1328 / #1329 / #1330 for full docs accuracy; product call is done. Part of #1105 (ADR: #1326).
Gates cleared: #1332 unblocked; #1440 closed out of scope. Package API removal of schema/define is out of scope for this issue (dedicated v1 chore).