# Rollback and Repair Plan

PostgreSQL source tables are authoritative. pgContext catalogs and acceleration
artifacts can be repaired or rebuilt, but user-owned source rows should be
recovered with ordinary PostgreSQL backup and restore procedures.

## Extension Upgrade Failure

If `ALTER EXTENSION pgcontext UPDATE` fails:

- leave the transaction aborted and inspect the PostgreSQL error and SQLSTATE;
- retry only after fixing the reported catalog, privilege, or dependency issue;
- restore from backup when the failed upgrade was part of a larger migration
  transaction that also changed application schema;
- do not manually edit pgContext catalog tables unless a release note gives an
  exact repair statement for the affected version.

Upgrade scripts must not scan user data, mutate user source tables, or start
index builds. After a successful retry, run smoke checks for collection
metadata, exact search, filters, telemetry, and deployed indexes.

## Failed Index Build

If an HNSW or future pgContext index build fails:

- drop the failed index relation if PostgreSQL left one behind;
- keep serving exact search or the previous valid index path;
- lower memory or candidate-budget settings only when the release notes or
  `pgcontext.vacuum_advice` indicate the failure is resource-related;
- rebuild with `CREATE INDEX` or `REINDEX`, then validate with exact search and
  `pgcontext.recall_check` before controlled rollout. Keep exact search when the
  experimental HNSW path does not meet measured workload requirements.

## Corrupt or Missing Artifacts

If diagnostics report `index_corrupt`, `artifact_missing`, or a related typed
status:

- treat the artifact as disposable acceleration state;
- keep PostgreSQL source tables online;
- use `pgcontext.retire_artifact_segment(artifact_id)` to retire manifests and
  attempt cleanup for generated, root-confined experimental segment files that
  should be discarded before a rebuild;
- rebuild the artifact from source tables and pgContext catalog metadata;
- use PostgreSQL backup/restore for authoritative data recovery, not artifact
  files.

## Compatibility Regression

If a release changes a documented SQLSTATE, return column, status value, or
stable API behavior unexpectedly:

- pin clients to the last known good extension version;
- record the failing SQL, expected output, actual output, SQLSTATE, server
  version, and extension version;
- check release notes for an explicit waiver or migration path;
- treat unwaived stable-surface regressions as release blockers.

Clients should branch on documented SQLSTATEs and typed status fields instead
of parsing free-form PostgreSQL messages.