Upgrades

Semver promise

• Major - breaking wire-protocol changes. Plan a coordinated upgrade.
• Minor - additive features, fully backward-compatible for one major.
• Patch - bug fixes, no behavior changes.

See versioning for the full policy.

Upgrade order

1. Upgrade the brain first. Newer brains accept older agents up to one major version behind.
2. Upgrade agents on a schedule. Rolling restarts are fine; agents auto-reconnect.
3. Monitor for “agent version mismatch” banners in the dashboard.

Database migrations

Migrations run automatically on brain start. For multi-replica deploys (v1.1+), run migrations explicitly from one-shot jobs:

docker run --rm \
  -e Z4J_DATABASE_URL=... \
  z4jdev/z4j:v1.1.0 z4j-brain migrate

Then deploy the new image to the actual brain replicas.

Rolling back

z4j migrations are forward-only by policy. Roll back with:

1. Restore Postgres from backup (point-in-time or snapshot).
2. Redeploy the previous brain image.

Test this procedure on staging before you need it.

Version skew tolerance

Brain	Agent	Behavior
v1.x	v1.x	Full feature parity
v1.x	v1.(x-1)	Works; new v1.x features may be unavailable on old agents
v1.x	v1.(x-2)	Works; upgrade banner shown
v1.x	v0.x	Rejected with handshake error
v2.x	v1.x	Rejected with handshake error (major break)

Reading release notes

Every release ships a changelog entry at /reference/changelog. Breaking changes are called out with a ⚠️ marker.

Upgrading Postgres

Separate concern - the brain supports Postgres 17 and 18. Use pg_upgrade or logical replication; the brain is agnostic.