# pg_lease — Changelog

All notable changes to pg_lease are documented here. Format based on
[Keep a Changelog](https://keepachangelog.com/), versions follow SemVer
(per `docs/DEVELOPMENT.md`).

## [0.1.0] — 2026-09-22

First release. Released after a PASS release gate (all 17 items verified)
and a green Docker compatibility matrix on PostgreSQL 14.24 and 15.17.

### Added

- `lease.acquire(key, owner, ttl [, wait])` — atomic, single-winner
  ownership of a key with TTL expiry; idempotent same-owner re-acquire;
  non-blocking denial (`acquired = false`) vs blocking-timeout error
  (`timeout`, SQLSTATE 57014); bounded 50 ms poll loop, no locks held
  across waits.
- `lease.renew(key, owner, epoch, ttl)` — heartbeat extending expiry;
  statuses `ok` / `not_owner` / `lapsed` / `epoch_mismatch`; never
  changes the epoch.
- `lease.release(key, owner, epoch)` — voluntary FREE transition;
  increments the epoch; same statuses as renew.
- `lease.inspect(key)` — lazy-expiry observation; unowned rows expose the
  fencing-counter watermark; never-leased keys return zero rows.
- Monotonic per-key fencing epochs, durable across releases, lapses, and
  crashes/restarts.
- SECURITY DEFINER functions with pinned `search_path`; extension is
  `trusted`; `lease.leases` locked to PUBLIC (functions are the only API).
- Test suites: regression (OPS/TXN/INV sections), isolation (5 specs),
  failure model (15 checks), blocking-acquire wait-wake.
- Docker compatibility matrix (`docker/pg_lease/`, ADR 0007) and CI
  workflow running it.

### Notes

- Pure SQL implementation (ADR 0006): one heap table, single-statement
  guarded transitions, `clock_timestamp()` as sole time authority, lazy
  expiry. No C, background workers, advisory locks, or triggers.
- No upgrade path: 0.1.0 is the first release; no earlier version was
  published.

[0.1.0]: https://github.com/azghr/pg-primitive/releases/tag/pg_lease-v0.1.0