# Support, Version, Upgrade, and Deprecation Policy

This policy describes the PostgreSQL 17 and 18 V1 contract for prototypes,
evaluation, and controlled pilots. Broader production certification remains
post-V1 roadmap work.

## Supported PostgreSQL Versions

PostgreSQL 17 and 18 are supported release targets. Every release container
is compiled for its matching PostgreSQL major, assembled as a multi-platform
manifest, and runtime-verified on both linux/amd64 and linux/arm64 before and
after promotion. PostgreSQL 17 remains the primary development and performance
qualification target and is used by unqualified Docker aliases. Deeper
backup/restore, WAL/restart, security, and long-duration lifecycle evidence may
remain version-specific and is documented separately from the image gate.

## Extension Versions

Stable SQL behavior follows semantic extension-version compatibility after the
first production release. Patch releases may add optional functions, fields,
enum values, diagnostics, or stricter validation for previously invalid input.
They must not remove or repurpose stable SQL objects, change stable result-column
meaning, or change documented SQLSTATEs for the same failure class.

Breaking SQL changes require a new extension version, upgrade notes, and a
named migration or rebuild procedure. A breaking change includes removing a
stable function, changing a stable signature, changing a stable status value,
or making previously valid stable input fail without an explicit migration path.

## Upgrades

pgContext 0.3.0 is a declared clean-install baseline. It has no in-place update
from 0.1 or 0.2; operators preserve authoritative source rows, recreate
extension-owned registrations, and rebuild derived artifacts according to the
release notes. This one-time baseline break is recorded in
`release/clean-install-baselines.data` so release gates do not mistake the
absence of historical SQL for an untested upgrade.

Extension update scripts must not scan user data, start index builds, or mutate
user-owned source tables. Upgrades may update pgContext-owned catalogs and SQL
objects, then operators should run smoke checks for collection metadata, exact
search, filters, telemetry, and deployed index paths.

When an upgrade cannot complete safely, the release notes must name the rollback
or repair path. If acceleration artifacts become incompatible, PostgreSQL source
tables remain authoritative and artifacts must be rebuilt or migrated through a
documented procedure.

## Deprecation

Deprecated stable APIs remain callable for at least one minor release after a
replacement is documented. Deprecation notices belong in this guide, release
notes, and upgrade notes. Clients should branch on stable SQLSTATEs and typed
status fields, not on free-form PostgreSQL messages.

Experimental and internal APIs are excluded from the compatibility promise.
`pgcontext_hnsw` and the variant vector wrappers remain experimental even when
implemented and tested in V1; planned serving surfaces live in the public
roadmap and are not implied by their metadata helpers.
