Upgrading

Effect and Vite+ are beta foundations of the repository. Upgrade them in isolated, reviewable changes, and do not normally upgrade both in one change.

Frozen baseline

The workspace pins the important tools in pnpm-workspace.yaml:

Tool	Version
Node.js	>=24.16.x
pnpm	11.15.1
Vite+ / Vite	0.2.9
Vitest	4.1.11
Effect	4.0.0-rc.111

The lockfile is part of the upgrade. Do not introduce prerelease ranges or a second workspace version.

Procedure

1. Open a dedicated upgrade change and record the reason, upstream release notes, and expected compatibility impact.

2. Change the workspace catalog and lockfile together. Use vp toolchain to inspect the active Vite+ graph; use vp env doctor when setup or runtime resolution is involved.

3. Run the independent gates:

   vp check
   vp test
   vp run check-goldens
   vp run check-pack-manifests
   vp run build

4. Review any changed generated artifacts, diagnostics, public declarations, export maps, packed package contents, and Compose validation output as product changes. Regenerate goldens only deliberately, and review the diff.

5. Run the provider contract and CLI integration suites, then update the PRD, ADRs, and relevant documentation if behavior or public contracts changed.

When an upgrade is not done

An upgrade is not complete because the compiler passes: generated bytes, package contents, exit codes, and clean packed-consumer behavior are part of the compatibility surface. If a change cannot be made compatible, revert the upgrade commit rather than silently accepting a new baseline.

Release-time gates build on this procedure; see Releasing.