Upgrading the engine

The normal upgrade

git pull                      # or docker compose pull for image-based installs
pip install -e .              # bare installs
alembic upgrade head
# restart the process / containers

Schema migrations are applied by alembic and are safe to run before the restart; compose installs run them automatically on start. Your corpus, checks, and reports carry across versions.

The one thing that can invalidate your corpus

Fingerprints only match when the corpus side and the query side were built with identical parameters. Two kinds of change break that agreement:

1. You change tuning env vars — NOPLAG_FP_K, NOPLAG_FP_W, or the chunking parameters. Entirely in your hands; don't change them casually.
2. A release changes the fingerprinting or winnowing algorithm. These releases are explicitly called out — the contributing rules require any compatibility-breaking detection change to be flagged, and release notes will say "re-ingest required."

After either, matching silently degrades toward zero rather than erroring — new-format query fingerprints just stop matching old-format corpus rows. If recall drops sharply after an upgrade, this is the first thing to check.

Re-ingest procedure: re-run your ingestion path (folder ingester, API uploads, or your own pipeline) so documents are re-chunked and re-fingerprinted under the new parameters, then run ANALYZE and rebuild the document-frequency table if you use one.

Retrieval-tuning variables (NOPLAG_L1_*, NOPLAG_STOP_LIST_N) are the opposite: read at query time, safe to change with just a restart, no re-index — see Configuration.

Downgrading

Downgrades are not routinely tested. The realistic rollback is restoring the pre-upgrade Postgres backup alongside the old code version — take one before upgrading (see Backups).

Staying current

Watch the GitHub repo for releases. Public releases are periodic syncs from the internal development tree, so expect batched changes with release notes rather than a commit-by-commit stream — the contributing guide explains the model.