# Upgrading Self-Hosted Provon

This document describes how to upgrade a self-hosted Provon deployment and what
compatibility guarantees to expect between releases.

## Compatibility Policy

Provon uses semantic versioning (`MAJOR.MINOR.PATCH`):

- `MAJOR`: Breaking changes that require manual intervention or a documented
  migration path.
- `MINOR`: New features and backward-compatible schema migrations.
- `PATCH`: Bug fixes and security patches.

Node deployments use forward-only database migrations. Cloudflare deployments
use forward-only D1 migrations. Running an older application against a newer
schema is not supported.

## Before Every Upgrade

1. Read the [GitHub Release notes](https://github.com/provon/provon/releases)
   for the target version.
2. Check the [version-specific upgrade notes](#version-specific-upgrade-notes)
   (`docs/upgrades/v<version>.md`) if one exists for
   the target release.
3. Create a coordinated backup of metadata, metering, telemetry, blobs, model
   weights, and `AUTH_SECRET`. Runtime process state is kept in memory only and
   does not need to be backed up.
4. Verify the backup in an isolated environment before touching production.
5. Record the current application version and configuration revision.

## Upgrade Steps (Node / Docker)

1. Stop new traffic at the reverse proxy.
2. Allow in-flight requests and background work to finish.
3. Send `SIGTERM` and wait for graceful shutdown.
4. Back up the persistent data directory.
5. Start one new container or process with the target image/version against the
   same data directory.
6. Wait for startup migrations to complete.
7. Run verification checks:
   - `GET /healthz`
   - Sign-in
   - Project API key creation
   - OTLP ingest
   - Gateway request and trace visibility
   - Diagnostic Rule execution
   - Connector actions, if enabled
8. Resume traffic only after all checks pass.
9. Retain the previous image until the release is accepted.

Do not run old and new Node processes concurrently against one local data
directory.

## Upgrade Steps (Cloudflare)

1. Read release notes and version-specific upgrade notes.
2. Run `pnpm test:cf`.
3. Export D1 metadata and metering databases.
4. Apply any required Data Catalog maintenance changes.
5. Run `pnpm deploy:cf`.
6. Verify each surface and the complete asynchronous evidence path.
7. Watch queue lag, D1 errors, warehouse writes, and R2 SQL reads through the
   rollout window.

## Rollback

Rollback is only safe before the new version applies migrations. Once metadata
or metering migrations run, the schema is forward-only. To recover:

1. Stop the new process.
2. Restore the data directory or D1 export from the pre-upgrade backup.
3. Start the previous application version against the restored data.
4. Verify end-to-end before resuming traffic.

## Version-specific upgrade notes

Individual Provon releases that need steps beyond this general guide have
version-specific notes in `docs/upgrades/v<version>.md`. These files are linked
from the GitHub Release notes when they exist.

## Compatibility Matrix

| Provon Version | Minimum Upgradable From | Schema Changes | Special Notes |
| -------------- | ----------------------- | -------------- | ------------- |
| 0.0.1          | — (initial release)     | Baseline       | —             |

Update this table with each release that changes the upgrade path.