11.7.1 Walker interrupted ¶

The walker is resumable by design. Kill the JVM mid-run, then systemctl restart ownsona.service, and it picks up exactly the rows still showing the old provider/model. No state to clean up.

11.7.2 Walker failed mid-run ¶

Look at the exception in journalctl -u ownsona.service. Common causes:

• Embedding endpoint unreachable / API key wrong. Fix application.ini and restart.
• Rate-limit / 429. The walker treats this as a fatal error and aborts the run; the next restart resumes. For a one-off run on a small store you’ll usually outrun the rate limit; for a large store you may want to lower BATCH_SIZE in ReembedJob.java.
• Different-dimension migration ran but EMBEDDING_DIMENSIONS in config doesn’t match the column type. The walker will try to write wrong-size vectors and fail at the database with a vector dimension mismatch error. Fix the config and restart.

11.7.3 Full rollback ¶

If the new model is producing terrible recall and you want to revert:

1. Stop the service.
2. Restore from the pre-deploy backup:

   sudo -u postgres psql ownsona < /var/backups/ownsona-pre-reembed-<date>.sql
   

3. Revert application.ini to the old EMBEDDING_MODEL / EMBEDDING_DIMENSIONS / EMBEDDING_API_KEY.
4. If you also ran a dim-change migration, redeploy a WAR built from the pre-dim-change commit (i.e. one whose CURRENT_DB_VERSION is lower). DbMigrator refuses to start against a higher-version DB, so you must restore the DB first or ship code matching the DB version.
5. Start the service.

This is the “data is not cheap” branch — the backup is the only thing that gets you back cleanly. Take backups before the deploy, not after.