# Migrating to Zudux-State V2

## Package and brand rename

- Install with `npm install zudux-state`.
- Change core imports from the previous package name to `zudux-state`.
- Change React imports to `zudux-state/react`.
- Prefer `ZuduxStateFault`; the previous base-error name remains as a deprecated compatibility alias.

## Behavioral changes

- Published snapshots are frozen by default. Set `freeze: false` only after measuring and documenting the mutation risk.
- Commands now receive revocable copy-on-write drafts. Never retain a draft reference after a command finishes.
- History uses inverse patches, so unchanged branches preserve reference identity after commits.
- Audit entries include `patchCount`, `previousHash`, and `hash`.
- Domain events include `patches`.
- Post-commit `after` module failures are reported through `onModuleFault` and do not reject an already committed command.
- Persistence envelopes include a checksum; V1 payloads should be migrated or cleared before enabling V2 persistence.

## Upgrade checklist

1. Remove any code that retains `context.read()` or draft references after command completion.
2. Confirm state roots are plain objects or arrays.
3. Add persistence migration/cleanup for existing envelopes.
4. Update custom event consumers for the `patches` field.
5. Update audit storage for the integrity-chain fields.
6. Route telemetry delivery errors through `onModuleFault`.
7. Run typecheck, tests, integration recovery tests, and `npm pack --dry-run`.