# 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:

   ```bash
   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](/contributing/releasing/).