neveroversell 0.1.0__tar.gz

neveroversell-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+coverage/
+*.log
+.DS_Store
+.env
+BRIEF.md
+python/.venv/
+__pycache__/
+*.egg-info/
+python/dist/
+.pytest_cache/
+launch/

neveroversell-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: neveroversell
+Version: 0.1.0
+Summary: Holds that cannot oversell. Postgres reservations with a TTL, a payment phase, idempotent two-path confirmation, a concurrent-safe sweeper and a drift check.
+Project-URL: Homepage, https://github.com/pavangupta352/neveroversell
+Project-URL: Repository, https://github.com/pavangupta352/neveroversell
+Project-URL: Issues, https://github.com/pavangupta352/neveroversell/issues
+Project-URL: Changelog, https://github.com/pavangupta352/neveroversell/blob/main/CHANGELOG.md
+Author-email: Pavan Gupta <pavan.gupta.352@gmail.com>
+License-Expression: MIT
+Keywords: booking,concurrency,hold,idempotent,inventory,oversell,payment,postgres,postgresql,reservation,seat,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: psycopg[binary,pool]>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# neveroversell
+
+Holds that cannot oversell. A Postgres library for selling a finite thing exactly once when payment is asynchronous: seats, tickets, stock, appointment slots, rental units, cohort places.
+
+This is the Python client. It ships the same SQL as the TypeScript package, so both languages share one set of guarantees and one database schema. The full documentation, the design notes and the test results live in the [repository README](https://github.com/pavangupta352/neveroversell#readme).
+
+```sh
+pip install neveroversell
+```
+
+Postgres 13 or newer. No extensions, no Redis, no queue.
+
+```python
+from datetime import timedelta
+from neveroversell import Inventory
+
+inv = Inventory(
+    "postgres://user:pass@host/db",
+    hold_ttl=timedelta(minutes=15),        # a basket lives 15 minutes
+    payment_window=timedelta(minutes=30),  # once payment starts, 30 minutes; must exceed the TTL
+)
+inv.migrate()
+inv.upsert_resource("flight_AI202_2026-10-01", 180)
+
+held = inv.hold("flight_AI202_2026-10-01", 2, account_id=user.id, idempotency_key=basket.id)
+if held.status != "held":
+    ...  # "insufficient" (held.available says how many are left), "account_cap", "unknown_resource"
+
+inv.begin_payment(held.hold.id)
+
+# From the return URL and from the webhook, in any order, any number of times:
+result = inv.confirm(held.hold.id, payment.id)
+match result.status:
+    case "confirmed":          fulfil(result.hold)
+    case "already_confirmed":  pass
+    case "duplicate_payment":  refund(result.payment_ref)          # keep result.existing_payment_ref
+    case "payment_ref_in_use": investigate(result.other_hold_id)
+    case "expired" | "released": refund(result.payment_ref)
+    case "not_found":          pass
+```
+
+Run `inv.sweep()` every minute from a scheduler, or `select nos_sweep()` from `pg_cron`. `inv.check()` compares the counters with the rows whenever you want proof.
+
+Every method returns a `Result` with a `status` string and the fields that status needs. Nothing throws for an expected outcome; exceptions are for programmer errors such as a non-positive quantity.
+
+Pass your own `psycopg_pool.ConnectionPool` with `Inventory(pool=...)` to share connections with the rest of your application.

neveroversell-0.1.0/README.md

@@ -0,0 +1,46 @@
+# neveroversell
+
+Holds that cannot oversell. A Postgres library for selling a finite thing exactly once when payment is asynchronous: seats, tickets, stock, appointment slots, rental units, cohort places.
+
+This is the Python client. It ships the same SQL as the TypeScript package, so both languages share one set of guarantees and one database schema. The full documentation, the design notes and the test results live in the [repository README](https://github.com/pavangupta352/neveroversell#readme).
+
+```sh
+pip install neveroversell
+```
+
+Postgres 13 or newer. No extensions, no Redis, no queue.
+
+```python
+from datetime import timedelta
+from neveroversell import Inventory
+
+inv = Inventory(
+    "postgres://user:pass@host/db",
+    hold_ttl=timedelta(minutes=15),        # a basket lives 15 minutes
+    payment_window=timedelta(minutes=30),  # once payment starts, 30 minutes; must exceed the TTL
+)
+inv.migrate()
+inv.upsert_resource("flight_AI202_2026-10-01", 180)
+
+held = inv.hold("flight_AI202_2026-10-01", 2, account_id=user.id, idempotency_key=basket.id)
+if held.status != "held":
+    ...  # "insufficient" (held.available says how many are left), "account_cap", "unknown_resource"
+
+inv.begin_payment(held.hold.id)
+
+# From the return URL and from the webhook, in any order, any number of times:
+result = inv.confirm(held.hold.id, payment.id)
+match result.status:
+    case "confirmed":          fulfil(result.hold)
+    case "already_confirmed":  pass
+    case "duplicate_payment":  refund(result.payment_ref)          # keep result.existing_payment_ref
+    case "payment_ref_in_use": investigate(result.other_hold_id)
+    case "expired" | "released": refund(result.payment_ref)
+    case "not_found":          pass
+```
+
+Run `inv.sweep()` every minute from a scheduler, or `select nos_sweep()` from `pg_cron`. `inv.check()` compares the counters with the rows whenever you want proof.
+
+Every method returns a `Result` with a `status` string and the fields that status needs. Nothing throws for an expected outcome; exceptions are for programmer errors such as a non-positive quantity.
+
+Pass your own `psycopg_pool.ConnectionPool` with `Inventory(pool=...)` to share connections with the rest of your application.

neveroversell-0.1.0/neveroversell/__init__.py

@@ -0,0 +1,344 @@
+"""neveroversell: holds that cannot oversell, for Postgres.
+
+The guarantees live in the SQL functions shipped inside this package. This module applies them,
+pushes your settings into the database, and turns each function's result row into a typed value.
+Every method is one SQL call; nothing here opens a transaction across calls.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from importlib import resources
+from typing import Any, Literal, Optional
+
+from psycopg import errors
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+__all__ = [
+    "CheckRow",
+    "Hold",
+    "HoldEvent",
+    "HoldState",
+    "Inventory",
+    "RepairRow",
+    "ResourceStatus",
+    "Result",
+    "SweepRow",
+    "sql_files",
+]
+
+__version__ = "0.1.0"
+
+HoldState = Literal["held", "awaiting_payment", "confirmed", "released", "expired"]
+
+
+@dataclass(frozen=True)
+class Hold:
+    id: str
+    resource_id: str
+    account_id: str
+    qty: int
+    state: HoldState
+    expires_at: datetime
+    payment_deadline: Optional[datetime]
+    payment_ref: Optional[str]
+
+
+@dataclass(frozen=True)
+class Result:
+    """The outcome of hold, begin_payment, confirm, release, extend and upsert_resource.
+
+    ``status`` is the value to match on. The other fields are filled when they mean something:
+    ``hold`` for any status that concerns an existing hold; ``available`` for insufficient,
+    account_cap, held and the resource statuses; ``payment_ref`` for the reference you should
+    refund on duplicate_payment, expired and released; ``existing_payment_ref`` on
+    duplicate_payment; ``other_hold_id`` on payment_ref_in_use.
+    """
+
+    status: str
+    hold: Optional[Hold] = None
+    resource_id: Optional[str] = None
+    available: Optional[int] = None
+    payment_ref: Optional[str] = None
+    existing_payment_ref: Optional[str] = None
+    other_hold_id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class SweepRow:
+    resource_id: str
+    expired_holds: int
+    expired_qty: int
+
+
+@dataclass(frozen=True)
+class CheckRow:
+    resource_id: str
+    held: int
+    held_by_rows: int
+    sold: int
+    sold_by_rows: int
+    drift: bool
+
+
+@dataclass(frozen=True)
+class RepairRow:
+    resource_id: str
+    held_before: int
+    held_after: int
+    sold_before: int
+    sold_after: int
+
+
+@dataclass(frozen=True)
+class ResourceStatus:
+    resource_id: str
+    total: int
+    held: int
+    sold: int
+    available: int
+    held_plain: int
+    held_paying: int
+
+
+@dataclass(frozen=True)
+class HoldEvent:
+    id: int
+    hold_id: str
+    event: str
+    detail: dict[str, Any]
+    at: datetime
+
+
+def sql_files() -> list[tuple[str, str]]:
+    """The migration files bundled with the package, as (name, contents), in apply order."""
+    folder = resources.files(__package__).joinpath("sql")
+    out: list[tuple[str, str]] = []
+    for entry in sorted(folder.iterdir(), key=lambda e: e.name):
+        if entry.name.endswith(".sql"):
+            out.append((entry.name, entry.read_text(encoding="utf-8")))
+    return out
+
+
+def _hold(row: dict[str, Any]) -> Optional[Hold]:
+    if row.get("hold_id") is None:
+        return None
+    return Hold(
+        id=str(row["hold_id"]),
+        resource_id=row["resource_id"],
+        account_id=row["account_id"],
+        qty=row["qty"],
+        state=row["state"],
+        expires_at=row["expires_at"],
+        payment_deadline=row.get("payment_deadline"),
+        payment_ref=row.get("payment_ref"),
+    )
+
+
+def _result(row: dict[str, Any]) -> Result:
+    # The SQL already puts the right reference in payment_ref: the hold's own on confirmed and
+    # already_confirmed, the one to refund on duplicate_payment, expired and released.
+    return Result(
+        status=row["status"],
+        hold=_hold(row),
+        resource_id=row.get("resource_id"),
+        available=row.get("available"),
+        payment_ref=row.get("payment_ref"),
+        existing_payment_ref=row.get("existing_payment_ref"),
+        other_hold_id=str(row["other_hold_id"]) if row.get("other_hold_id") else None,
+    )
+
+
+class Inventory:
+    """Holds, payment phase, confirmation, release, extension, sweeping and checking.
+
+    Pass either a connection string, from which a small pool is created, or your own
+    ``psycopg_pool.ConnectionPool``.
+    """
+
+    def __init__(
+        self,
+        conninfo: Optional[str] = None,
+        *,
+        pool: Optional[ConnectionPool] = None,
+        hold_ttl: timedelta = timedelta(minutes=15),
+        payment_window: timedelta = timedelta(minutes=30),
+        account_cap: Optional[int] = None,
+        cap_scope: Literal["resource", "account"] = "resource",
+        max_extensions: int = 1,
+        extension: timedelta = timedelta(minutes=5),
+        max_size: int = 8,
+    ) -> None:
+        if hold_ttl <= timedelta(0):
+            raise ValueError("hold_ttl must be positive")
+        if payment_window <= hold_ttl:
+            raise ValueError(
+                f"payment_window ({payment_window}) must exceed hold_ttl ({hold_ttl}); otherwise the sweeper can kill a live checkout"
+            )
+        if account_cap is not None and account_cap <= 0:
+            raise ValueError("account_cap must be positive or None")
+        if max_extensions < 0:
+            raise ValueError("max_extensions must be zero or positive")
+        if extension <= timedelta(0):
+            raise ValueError("extension must be positive")
+        if cap_scope not in ("resource", "account"):
+            raise ValueError("cap_scope must be 'resource' or 'account'")
+        if pool is None:
+            if conninfo is None:
+                raise ValueError("pass a connection string or a pool")
+            pool = ConnectionPool(conninfo, min_size=1, max_size=max_size, kwargs={"row_factory": dict_row}, open=True)
+        self._pool = pool
+        self.hold_ttl = hold_ttl
+        self.payment_window = payment_window
+        self.account_cap = account_cap
+        self.cap_scope = cap_scope
+        self.max_extensions = max_extensions
+        self.extension = extension
+
+    # ---- infrastructure -------------------------------------------------------------------
+
+    def close(self) -> None:
+        self._pool.close()
+
+    def _one(self, query: str, params: tuple[Any, ...]) -> dict[str, Any]:
+        with self._pool.connection() as conn:
+            row = conn.execute(query, params).fetchone()  # type: ignore[union-attr]
+        if row is None:
+            raise RuntimeError(f"neveroversell: {query} returned no row")
+        return dict(row)
+
+    def _all(self, query: str, params: tuple[Any, ...] = ()) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(query, params).fetchall()  # type: ignore[union-attr]
+        return [dict(r) for r in rows]
+
+    def migrate(self) -> list[str]:
+        """Apply the bundled migrations that have not been applied yet, then push the settings."""
+        applied: list[str] = []
+        with self._pool.connection() as conn:
+            conn.execute("select pg_advisory_lock(hashtext('nos_migrations'))")
+            try:
+                conn.execute(
+                    "create table if not exists nos_migrations (name text primary key, applied_at timestamptz not null default clock_timestamp())"
+                )
+                done = {r["name"] for r in conn.execute("select name from nos_migrations").fetchall()}  # type: ignore[index]
+                conn.commit()
+                for name, body in sql_files():
+                    if name in done:
+                        continue
+                    try:
+                        conn.execute(body)
+                        conn.execute("insert into nos_migrations (name) values (%s)", (name,))
+                        conn.commit()
+                        applied.append(name)
+                    except Exception as err:
+                        conn.rollback()
+                        raise RuntimeError(f"neveroversell migration {name} failed: {err}") from err
+            finally:
+                conn.execute("select pg_advisory_unlock(hashtext('nos_migrations'))")
+                conn.commit()
+        self.apply_settings()
+        return applied
+
+    def apply_settings(self) -> None:
+        """Write the configured settings to nos_settings. The database enforces payment_window > hold_ttl."""
+        try:
+            with self._pool.connection() as conn:
+                conn.execute(
+                    """
+                    update nos_settings
+                       set hold_ttl = %s, payment_window = %s, account_cap = %s,
+                           cap_scope = %s, max_extensions = %s, extension = %s
+                     where id
+                    """,
+                    (self.hold_ttl, self.payment_window, self.account_cap, self.cap_scope, self.max_extensions, self.extension),
+                )
+        except errors.CheckViolation as err:
+            raise ValueError(f"neveroversell: the database rejected these settings ({err})") from err
+
+    # ---- the primitive ------------------------------------------------------------------------
+
+    def upsert_resource(self, resource_id: str, total: int) -> Result:
+        return _result(self._one("select * from nos_upsert_resource(%s, %s)", (resource_id, total)))
+
+    def hold(
+        self,
+        resource_id: str,
+        qty: int,
+        account_id: str,
+        *,
+        idempotency_key: Optional[str] = None,
+        ttl: Optional[timedelta] = None,
+    ) -> Result:
+        """Statuses: held, replayed, insufficient, account_cap, unknown_resource."""
+        return _result(self._one("select * from nos_hold(%s, %s, %s, %s, %s)", (resource_id, qty, account_id, idempotency_key, ttl)))
+
+    def begin_payment(self, hold_id: str, *, window: Optional[timedelta] = None) -> Result:
+        """Statuses: awaiting_payment, replayed, expired, confirmed, released, not_found."""
+        return _result(self._one("select * from nos_begin_payment(%s, %s)", (hold_id, window)))
+
+    def confirm(self, hold_id: str, payment_ref: str) -> Result:
+        """Statuses: confirmed, already_confirmed, duplicate_payment, payment_ref_in_use, expired, released, not_found."""
+        return _result(self._one("select * from nos_confirm(%s, %s)", (hold_id, payment_ref)))
+
+    def release(self, hold_id: str, *, reason: Optional[str] = None) -> Result:
+        """Statuses: released, already_released, confirmed, expired, not_found."""
+        return _result(self._one("select * from nos_release(%s, %s)", (hold_id, reason)))
+
+    def extend(self, hold_id: str, *, by: Optional[timedelta] = None) -> Result:
+        """Statuses: extended, not_extendable, not_found."""
+        return _result(self._one("select * from nos_extend(%s, %s)", (hold_id, by)))
+
+    def sweep(self, limit: int = 1000) -> list[SweepRow]:
+        return [SweepRow(r["resource_id"], r["expired_holds"], r["expired_qty"]) for r in self._all("select * from nos_sweep(%s)", (limit,))]
+
+    def check(self) -> list[CheckRow]:
+        return [
+            CheckRow(r["resource_id"], r["held"], int(r["held_by_rows"]), r["sold"], int(r["sold_by_rows"]), r["drift"])
+            for r in self._all("select * from nos_check()")
+        ]
+
+    def repair(self, resource_id: str) -> Optional[RepairRow]:
+        rows = self._all("select * from nos_repair(%s)", (resource_id,))
+        if not rows:
+            return None
+        r = rows[0]
+        return RepairRow(r["resource_id"], r["held_before"], r["held_after"], r["sold_before"], r["sold_after"])
+
+    def status(self, resource_id: str) -> Optional[ResourceStatus]:
+        rows = self._all("select * from nos_resource_status where resource_id = %s", (resource_id,))
+        if not rows:
+            return None
+        r = rows[0]
+        return ResourceStatus(r["resource_id"], r["total"], r["held"], r["sold"], r["available"], r["held_plain"], r["held_paying"])
+
+    def holds(
+        self,
+        *,
+        resource_id: Optional[str] = None,
+        state: Optional[HoldState] = None,
+        older_than: Optional[timedelta] = None,
+        limit: int = 200,
+    ) -> list[Hold]:
+        rows = self._all(
+            """
+            select id as hold_id, resource_id, account_id, qty, state, expires_at, payment_deadline, payment_ref
+              from nos_holds
+             where (%(resource)s::text is null or resource_id = %(resource)s)
+               and (%(state)s::nos_hold_state is null or state = %(state)s)
+               and (%(older)s::interval is null or created_at <= clock_timestamp() - %(older)s::interval)
+             order by created_at asc
+             limit %(limit)s
+            """,
+            {"resource": resource_id, "state": state, "older": older_than, "limit": limit},  # type: ignore[arg-type]
+        )
+        return [h for h in (_hold(r) for r in rows) if h is not None]
+
+    def events(self, hold_id: str) -> list[HoldEvent]:
+        return [
+            HoldEvent(int(r["id"]), str(r["hold_id"]), r["event"], r["detail"], r["at"])
+            for r in self._all("select id, hold_id, event, detail, at from nos_hold_events where hold_id = %s order by id", (hold_id,))
+        ]
+

neveroversell-0.1.0/neveroversell/sql/001_schema.sql

@@ -0,0 +1,84 @@
+-- neveroversell: schema
+-- Postgres 13 or newer. Every object is prefixed nos_ so it can live inside an existing database.
+
+create table if not exists nos_settings (
+  id              boolean primary key default true check (id),
+  hold_ttl        interval not null default interval '15 minutes' check (hold_ttl > interval '0'),
+  payment_window  interval not null default interval '30 minutes',
+  account_cap     integer check (account_cap is null or account_cap > 0),
+  cap_scope       text not null default 'resource' check (cap_scope in ('resource', 'account')),
+  max_extensions  integer not null default 1 check (max_extensions >= 0),
+  extension       interval not null default interval '5 minutes' check (extension > interval '0'),
+  -- A live checkout must never be killed by the TTL: the payment window has to outlast the hold.
+  constraint nos_settings_window_gt_ttl check (payment_window > hold_ttl)
+);
+insert into nos_settings default values on conflict (id) do nothing;
+
+create table if not exists nos_resources (
+  id          text primary key,
+  total       integer not null check (total >= 0),
+  held        integer not null default 0 check (held >= 0),
+  sold        integer not null default 0 check (sold >= 0),
+  created_at  timestamptz not null default clock_timestamp(),
+  updated_at  timestamptz not null default clock_timestamp(),
+  -- The last line of defence: even a wrong code path cannot commit an oversell.
+  constraint nos_resources_capacity check (held + sold <= total)
+);
+
+do $$ begin
+  create type nos_hold_state as enum ('held', 'awaiting_payment', 'confirmed', 'released', 'expired');
+exception when duplicate_object then null; end $$;
+
+create table if not exists nos_holds (
+  id                  uuid primary key default gen_random_uuid(),
+  resource_id         text not null references nos_resources (id),
+  account_id          text not null,
+  qty                 integer not null check (qty > 0),
+  state               nos_hold_state not null default 'held',
+  idempotency_key     text,
+  payment_ref         text,
+  expires_at          timestamptz not null,
+  payment_started_at  timestamptz,
+  payment_deadline    timestamptz,
+  extensions          integer not null default 0,
+  created_at          timestamptz not null default clock_timestamp(),
+  updated_at          timestamptz not null default clock_timestamp()
+);
+
+-- One hold per (resource, account, idempotency key): a client retry cannot double-hold.
+create unique index if not exists nos_holds_idem_uq
+  on nos_holds (resource_id, account_id, idempotency_key) where idempotency_key is not null;
+-- One payment buys one hold, enforced by the database.
+create unique index if not exists nos_holds_payment_ref_uq
+  on nos_holds (payment_ref) where payment_ref is not null;
+create index if not exists nos_holds_active_ix   on nos_holds (resource_id) where state in ('held', 'awaiting_payment');
+create index if not exists nos_holds_account_ix  on nos_holds (account_id)  where state in ('held', 'awaiting_payment');
+create index if not exists nos_holds_expiry_ix   on nos_holds (expires_at)  where state = 'held';
+create index if not exists nos_holds_deadline_ix on nos_holds (payment_deadline) where state = 'awaiting_payment';
+
+create table if not exists nos_hold_events (
+  id       bigserial primary key,
+  hold_id  uuid not null references nos_holds (id),
+  event    text not null,
+  detail   jsonb not null default '{}'::jsonb,
+  at       timestamptz not null default clock_timestamp()
+);
+create index if not exists nos_hold_events_hold_ix on nos_hold_events (hold_id, id);
+
+-- Every function returns this shape. status carries the outcome; the rest is context for the caller.
+do $$ begin
+  create type nos_result as (
+    status                text,
+    hold_id               uuid,
+    resource_id           text,
+    account_id            text,
+    qty                   integer,
+    state                 nos_hold_state,
+    expires_at            timestamptz,
+    payment_deadline      timestamptz,
+    payment_ref           text,
+    existing_payment_ref  text,
+    other_hold_id         uuid,
+    available             integer
+  );
+exception when duplicate_object then null; end $$;

neveroversell-0.1.0/neveroversell/sql/002_functions.sql

@@ -0,0 +1,418 @@
+-- neveroversell: functions
+--
+-- Rules that every function follows:
+--   1. Default READ COMMITTED isolation. No SERIALIZABLE, no client retries.
+--   2. Lock the resource row first with FOR NO KEY UPDATE. Functions that start from a hold id read the
+--      hold's resource_id without a lock, lock the resource, then re-read the hold under that lock.
+--   3. An account-wide cap takes an advisory lock on the account BEFORE the resource lock.
+--   4. Expected outcomes are statuses in nos_result. Exceptions are for programmer errors only.
+--   5. All time decisions use clock_timestamp() captured once at the top of the call.
+
+-- Build a nos_result from a hold row plus optional context.
+create or replace function nos_pack(
+  p_status        text,
+  p_hold          nos_holds,
+  p_resource      text    default null,
+  p_available     integer default null,
+  p_payment_ref   text    default null,
+  p_existing_ref  text    default null,
+  p_other         uuid    default null
+) returns nos_result language sql immutable as $$
+  select row(
+    p_status,
+    (p_hold).id,
+    coalesce((p_hold).resource_id, p_resource),
+    (p_hold).account_id,
+    (p_hold).qty,
+    (p_hold).state,
+    (p_hold).expires_at,
+    (p_hold).payment_deadline,
+    coalesce(p_payment_ref, (p_hold).payment_ref),
+    p_existing_ref,
+    p_other,
+    p_available
+  )::nos_result;
+$$;
+
+-- Create a resource or change its capacity. Lowering total below held + sold is refused.
+create or replace function nos_upsert_resource(p_id text, p_total integer)
+returns nos_result language plpgsql as $$
+declare
+  r nos_resources%rowtype;
+  v_now timestamptz := clock_timestamp();
+  v_status text;
+begin
+  if p_id is null or p_id = '' then
+    raise exception 'resource id is required' using errcode = '22023';
+  end if;
+  if p_total is null or p_total < 0 then
+    raise exception 'total must be zero or positive' using errcode = '22023';
+  end if;
+  v_status := case when exists (select 1 from nos_resources where id = p_id) then 'updated' else 'created' end;
+  begin
+    insert into nos_resources (id, total) values (p_id, p_total)
+    on conflict (id) do update set total = excluded.total, updated_at = v_now
+    returning * into r;
+  exception when check_violation then
+    select * into r from nos_resources where id = p_id;
+    return nos_pack('capacity_below_committed', null::nos_holds, p_id, r.total - r.held - r.sold);
+  end;
+  return nos_pack(v_status, null::nos_holds, p_id, r.total - r.held - r.sold);
+end $$;
+
+-- Take a hold. Statuses: held | replayed | insufficient | account_cap | unknown_resource
+create or replace function nos_hold(
+  p_resource  text,
+  p_qty       integer,
+  p_account   text,
+  p_idem      text     default null,
+  p_ttl       interval default null
+) returns nos_result language plpgsql as $$
+declare
+  s        nos_settings%rowtype;
+  r        nos_resources%rowtype;
+  h        nos_holds%rowtype;
+  v_now    timestamptz := clock_timestamp();
+  v_ttl    interval;
+  v_exp    integer;
+  v_avail  integer;
+  v_used   integer;
+begin
+  if p_qty is null or p_qty <= 0 then
+    raise exception 'qty must be positive' using errcode = '22023';
+  end if;
+  if p_account is null or p_account = '' then
+    raise exception 'account id is required' using errcode = '22023';
+  end if;
+  select * into s from nos_settings;
+  v_ttl := coalesce(p_ttl, s.hold_ttl);
+  if v_ttl <= interval '0' then
+    raise exception 'ttl must be positive' using errcode = '22023';
+  end if;
+
+  -- 1. Idempotent replay, before any lock.
+  if p_idem is not null then
+    select * into h from nos_holds
+     where resource_id = p_resource and account_id = p_account and idempotency_key = p_idem;
+    if found then
+      return nos_pack('replayed', h);
+    end if;
+  end if;
+
+  -- 2. An account-wide cap needs an account lock, always before the resource lock.
+  if s.account_cap is not null and s.cap_scope = 'account' then
+    perform pg_advisory_xact_lock(hashtext('nos:account:' || p_account));
+  end if;
+
+  -- 3. The resource lock. Everything below happens under it.
+  select * into r from nos_resources where id = p_resource for no key update;
+  if not found then
+    return nos_pack('unknown_resource', null::nos_holds, p_resource, null);
+  end if;
+
+  -- 4. Expire this resource's plain holds that are past their TTL. Payment-phase holds are left alone.
+  with x as (
+    update nos_holds set state = 'expired', updated_at = v_now
+     where resource_id = p_resource and state = 'held' and expires_at <= v_now
+     returning id, qty
+  ), ev as (
+    insert into nos_hold_events (hold_id, event, detail)
+    select id, 'expired', jsonb_build_object('by', 'hold', 'reason', 'ttl') from x
+  )
+  select coalesce(sum(qty), 0)::integer into v_exp from x;
+  if v_exp > 0 then
+    update nos_resources set held = held - v_exp, updated_at = v_now
+     where id = p_resource returning * into r;
+  end if;
+
+  -- 5. Availability from the counters, never from counting rows.
+  v_avail := r.total - r.held - r.sold;
+  if p_qty > v_avail then
+    return nos_pack('insufficient', null::nos_holds, p_resource, v_avail);
+  end if;
+
+  -- 6. Per-account cap.
+  if s.account_cap is not null then
+    select coalesce(sum(qty), 0)::integer into v_used from nos_holds
+     where account_id = p_account and state in ('held', 'awaiting_payment')
+       and (s.cap_scope = 'account' or resource_id = p_resource);
+    if v_used + p_qty > s.account_cap then
+      return nos_pack('account_cap', null::nos_holds, p_resource, v_avail);
+    end if;
+  end if;
+
+  -- 7. Record the hold, then move the counter. Both under the lock.
+  begin
+    insert into nos_holds (resource_id, account_id, qty, state, idempotency_key, expires_at)
+    values (p_resource, p_account, p_qty, 'held', p_idem, v_now + v_ttl)
+    returning * into h;
+  exception when unique_violation then
+    -- A concurrent call with the same idempotency key committed first. Return its hold.
+    select * into h from nos_holds
+     where resource_id = p_resource and account_id = p_account and idempotency_key = p_idem;
+    return nos_pack('replayed', h);
+  end;
+
+  update nos_resources set held = held + p_qty, updated_at = v_now where id = p_resource;
+  insert into nos_hold_events (hold_id, event, detail)
+  values (h.id, 'held', jsonb_build_object('qty', p_qty, 'ttl', v_ttl::text));
+
+  return nos_pack('held', h, null, v_avail - p_qty);
+end $$;
+
+-- Enter the payment phase. Statuses: awaiting_payment | replayed | expired | confirmed | released | not_found
+create or replace function nos_begin_payment(p_hold uuid, p_window interval default null)
+returns nos_result language plpgsql as $$
+declare
+  s      nos_settings%rowtype;
+  h      nos_holds%rowtype;
+  v_res  text;
+  v_now  timestamptz := clock_timestamp();
+begin
+  select * into s from nos_settings;
+  select resource_id into v_res from nos_holds where id = p_hold;
+  if not found then
+    return nos_pack('not_found', null::nos_holds);
+  end if;
+  perform 1 from nos_resources where id = v_res for no key update;
+  select * into h from nos_holds where id = p_hold;
+
+  if h.state = 'held' then
+    if h.expires_at <= v_now then
+      update nos_holds set state = 'expired', updated_at = v_now where id = h.id returning * into h;
+      update nos_resources set held = held - h.qty, updated_at = v_now where id = v_res;
+      insert into nos_hold_events (hold_id, event, detail)
+      values (h.id, 'expired', jsonb_build_object('by', 'begin_payment', 'reason', 'ttl'));
+      return nos_pack('expired', h);
+    end if;
+    update nos_holds
+       set state = 'awaiting_payment',
+           payment_started_at = v_now,
+           payment_deadline = v_now + coalesce(p_window, s.payment_window),
+           updated_at = v_now
+     where id = h.id returning * into h;
+    insert into nos_hold_events (hold_id, event, detail)
+    values (h.id, 'awaiting_payment', jsonb_build_object('deadline', h.payment_deadline));
+    return nos_pack('awaiting_payment', h);
+  elsif h.state = 'awaiting_payment' then
+    return nos_pack('replayed', h);
+  else
+    return nos_pack(h.state::text, h);
+  end if;
+end $$;
+
+-- Confirm a hold with a payment reference. Idempotent across both confirmation paths.
+-- Statuses: confirmed | already_confirmed | duplicate_payment | payment_ref_in_use | expired | released | not_found
+create or replace function nos_confirm(p_hold uuid, p_payment_ref text)
+returns nos_result language plpgsql as $$
+declare
+  h        nos_holds%rowtype;
+  v_res    text;
+  v_other  uuid;
+  v_now    timestamptz := clock_timestamp();
+begin
+  if p_payment_ref is null or p_payment_ref = '' then
+    raise exception 'payment_ref is required' using errcode = '22023';
+  end if;
+  select resource_id into v_res from nos_holds where id = p_hold;
+  if not found then
+    return nos_pack('not_found', null::nos_holds, null, null, p_payment_ref);
+  end if;
+  perform 1 from nos_resources where id = v_res for no key update;
+  select * into h from nos_holds where id = p_hold;
+
+  if h.state in ('held', 'awaiting_payment') then
+    -- A plain hold past its TTL is expired here rather than confirmed; a payment-phase hold is
+    -- honoured until the sweeper expires it, because the customer has paid and the units are still held.
+    if h.state = 'held' and h.expires_at <= v_now then
+      update nos_holds set state = 'expired', updated_at = v_now where id = h.id returning * into h;
+      update nos_resources set held = held - h.qty, updated_at = v_now where id = v_res;
+      insert into nos_hold_events (hold_id, event, detail)
+      values (h.id, 'expired', jsonb_build_object('by', 'confirm', 'reason', 'ttl', 'payment_ref', p_payment_ref));
+      return nos_pack('expired', h, null, null, p_payment_ref);
+    end if;
+
+    -- Has this payment already bought a different hold?
+    select id into v_other from nos_holds where payment_ref = p_payment_ref and id <> h.id;
+    if found then
+      insert into nos_hold_events (hold_id, event, detail)
+      values (h.id, 'payment_ref_in_use', jsonb_build_object('payment_ref', p_payment_ref, 'other_hold_id', v_other));
+      return nos_pack('payment_ref_in_use', h, null, null, p_payment_ref, null, v_other);
+    end if;
+
+    begin
+      update nos_holds set state = 'confirmed', payment_ref = p_payment_ref, updated_at = v_now
+       where id = h.id returning * into h;
+    exception when unique_violation then
+      -- Two different holds raced to confirm with the same payment reference. The unique index decided.
+      select id into v_other from nos_holds where payment_ref = p_payment_ref and id <> h.id;
+      insert into nos_hold_events (hold_id, event, detail)
+      values (h.id, 'payment_ref_in_use', jsonb_build_object('payment_ref', p_payment_ref, 'other_hold_id', v_other));
+      return nos_pack('payment_ref_in_use', h, null, null, p_payment_ref, null, v_other);
+    end;
+    update nos_resources set held = held - h.qty, sold = sold + h.qty, updated_at = v_now where id = v_res;
+    insert into nos_hold_events (hold_id, event, detail)
+    values (h.id, 'confirmed', jsonb_build_object('payment_ref', p_payment_ref));
+    return nos_pack('confirmed', h);
+
+  elsif h.state = 'confirmed' then
+    if h.payment_ref = p_payment_ref then
+      -- The second confirmation path for the same payment: a no-op that returns the same answer.
+      return nos_pack('already_confirmed', h);
+    end if;
+    -- A different payment for an already-confirmed hold: the customer paid twice. Caller refunds p_payment_ref.
+    insert into nos_hold_events (hold_id, event, detail)
+    values (h.id, 'duplicate_payment', jsonb_build_object('payment_ref', p_payment_ref, 'existing_payment_ref', h.payment_ref));
+    return nos_pack('duplicate_payment', h, null, null, p_payment_ref, h.payment_ref);
+
+  else
+    -- released or expired: a late confirmation never revives a hold. Caller refunds p_payment_ref.
+    insert into nos_hold_events (hold_id, event, detail)
+    values (h.id, 'late_confirm', jsonb_build_object('state', h.state, 'payment_ref', p_payment_ref));
+    return nos_pack(h.state::text, h, null, null, p_payment_ref);
+  end if;
+end $$;
+
+-- Release a hold explicitly. Statuses: released | already_released | confirmed | expired | not_found
+create or replace function nos_release(p_hold uuid, p_reason text default null)
+returns nos_result language plpgsql as $$
+declare
+  h      nos_holds%rowtype;
+  v_res  text;
+  v_now  timestamptz := clock_timestamp();
+begin
+  select resource_id into v_res from nos_holds where id = p_hold;
+  if not found then
+    return nos_pack('not_found', null::nos_holds);
+  end if;
+  perform 1 from nos_resources where id = v_res for no key update;
+  select * into h from nos_holds where id = p_hold;
+
+  if h.state in ('held', 'awaiting_payment') then
+    update nos_holds set state = 'released', updated_at = v_now where id = h.id returning * into h;
+    update nos_resources set held = held - h.qty, updated_at = v_now where id = v_res;
+    insert into nos_hold_events (hold_id, event, detail)
+    values (h.id, 'released', jsonb_build_object('reason', p_reason));
+    return nos_pack('released', h);
+  elsif h.state = 'released' then
+    return nos_pack('already_released', h);
+  else
+    return nos_pack(h.state::text, h);
+  end if;
+end $$;
+
+-- Extend a plain hold's TTL, a bounded number of times. Statuses: extended | not_extendable | not_found
+create or replace function nos_extend(p_hold uuid, p_by interval default null)
+returns nos_result language plpgsql as $$
+declare
+  s      nos_settings%rowtype;
+  h      nos_holds%rowtype;
+  v_res  text;
+  v_now  timestamptz := clock_timestamp();
+begin
+  select * into s from nos_settings;
+  select resource_id into v_res from nos_holds where id = p_hold;
+  if not found then
+    return nos_pack('not_found', null::nos_holds);
+  end if;
+  perform 1 from nos_resources where id = v_res for no key update;
+  select * into h from nos_holds where id = p_hold;
+
+  if h.state = 'held' and h.expires_at > v_now and h.extensions < s.max_extensions then
+    update nos_holds
+       set expires_at = greatest(expires_at, v_now) + coalesce(p_by, s.extension),
+           extensions = extensions + 1,
+           updated_at = v_now
+     where id = h.id returning * into h;
+    insert into nos_hold_events (hold_id, event, detail)
+    values (h.id, 'extended', jsonb_build_object('expires_at', h.expires_at, 'extensions', h.extensions));
+    return nos_pack('extended', h);
+  end if;
+  insert into nos_hold_events (hold_id, event, detail)
+  values (h.id, 'extend_refused', jsonb_build_object(
+    'state', h.state,
+    'reason', case
+      when h.state <> 'held' then h.state::text
+      when h.expires_at <= v_now then 'expired'
+      else 'max_extensions' end));
+  return nos_pack('not_extendable', h);
+end $$;
+
+-- Expire plain holds past their TTL and payment-phase holds past their deadline.
+-- Safe to run from several workers at once: per-resource row lock plus conditional updates.
+create or replace function nos_sweep(p_limit integer default 1000)
+returns table (resource_id text, expired_holds integer, expired_qty integer) language plpgsql as $$
+declare
+  v_res  text;
+  v_now  timestamptz := clock_timestamp();
+  v_n    integer;
+  v_q    integer;
+begin
+  for v_res in
+    select distinct h.resource_id from nos_holds h
+     where (h.state = 'held' and h.expires_at <= v_now)
+        or (h.state = 'awaiting_payment' and h.payment_deadline <= v_now)
+     order by h.resource_id
+     limit p_limit
+  loop
+    perform 1 from nos_resources where id = v_res for no key update;
+    with x as (
+      update nos_holds set state = 'expired', updated_at = v_now
+       where nos_holds.resource_id = v_res
+         and ((state = 'held' and expires_at <= v_now)
+           or (state = 'awaiting_payment' and payment_deadline <= v_now))
+       returning id, qty, (payment_deadline is not null) as was_paying
+    ), ev as (
+      insert into nos_hold_events (hold_id, event, detail)
+      select id, 'expired', jsonb_build_object('by', 'sweep', 'reason', case when was_paying then 'payment_window' else 'ttl' end)
+        from x
+    )
+    select count(*)::integer, coalesce(sum(qty), 0)::integer into v_n, v_q from x;
+    if v_q > 0 then
+      update nos_resources set held = held - v_q, updated_at = v_now where id = v_res;
+    end if;
+    if v_n > 0 then
+      resource_id := v_res; expired_holds := v_n; expired_qty := v_q;
+      return next;
+    end if;
+  end loop;
+end $$;
+
+-- Compare the counters with the rows. drift = true means something is wrong and nos_repair may be used.
+create or replace function nos_check()
+returns table (resource_id text, held integer, held_by_rows bigint, sold integer, sold_by_rows bigint, drift boolean)
+language sql stable as $$
+  select r.id,
+         r.held,
+         coalesce(sum(h.qty) filter (where h.state in ('held', 'awaiting_payment')), 0),
+         r.sold,
+         coalesce(sum(h.qty) filter (where h.state = 'confirmed'), 0),
+         r.held <> coalesce(sum(h.qty) filter (where h.state in ('held', 'awaiting_payment')), 0)
+         or r.sold <> coalesce(sum(h.qty) filter (where h.state = 'confirmed'), 0)
+    from nos_resources r
+    left join nos_holds h on h.resource_id = r.id
+   group by r.id, r.held, r.sold
+   order by r.id;
+$$;
+
+-- Recompute one resource's counters from its rows, under the resource lock. Explicit opt-in only.
+create or replace function nos_repair(p_resource text)
+returns table (resource_id text, held_before integer, held_after integer, sold_before integer, sold_after integer)
+language plpgsql as $$
+declare
+  r       nos_resources%rowtype;
+  v_held  integer;
+  v_sold  integer;
+begin
+  select * into r from nos_resources where id = p_resource for no key update;
+  if not found then
+    return;
+  end if;
+  select coalesce(sum(qty) filter (where state in ('held', 'awaiting_payment')), 0)::integer,
+         coalesce(sum(qty) filter (where state = 'confirmed'), 0)::integer
+    into v_held, v_sold
+    from nos_holds where nos_holds.resource_id = p_resource;
+  update nos_resources set held = v_held, sold = v_sold, updated_at = clock_timestamp() where id = p_resource;
+  resource_id := p_resource; held_before := r.held; held_after := v_held; sold_before := r.sold; sold_after := v_sold;
+  return next;
+end $$;

neveroversell-0.1.0/neveroversell/sql/003_views.sql

@@ -0,0 +1,24 @@
+-- neveroversell: observability views
+
+create or replace view nos_holds_by_state as
+select resource_id,
+       state,
+       count(*)::integer      as holds,
+       sum(qty)::integer      as qty,
+       min(created_at)        as oldest,
+       max(created_at)        as newest
+  from nos_holds
+ group by resource_id, state;
+
+create or replace view nos_resource_status as
+select r.id            as resource_id,
+       r.total,
+       r.held,
+       r.sold,
+       r.total - r.held - r.sold as available,
+       coalesce(sum(h.qty) filter (where h.state = 'held'), 0)::integer             as held_plain,
+       coalesce(sum(h.qty) filter (where h.state = 'awaiting_payment'), 0)::integer as held_paying,
+       r.updated_at
+  from nos_resources r
+  left join nos_holds h on h.resource_id = r.id and h.state in ('held', 'awaiting_payment')
+ group by r.id;

neveroversell-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "neveroversell"
+version = "0.1.0"
+description = "Holds that cannot oversell. Postgres reservations with a TTL, a payment phase, idempotent two-path confirmation, a concurrent-safe sweeper and a drift check."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Pavan Gupta", email = "pavan.gupta.352@gmail.com" }]
+keywords = ["postgres", "postgresql", "inventory", "reservation", "hold", "booking", "seat", "oversell", "idempotent", "payment", "webhook", "concurrency"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = ["psycopg[binary,pool]>=3.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/pavangupta352/neveroversell"
+Repository = "https://github.com/pavangupta352/neveroversell"
+Issues = "https://github.com/pavangupta352/neveroversell/issues"
+Changelog = "https://github.com/pavangupta352/neveroversell/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["neveroversell"]
+
+[tool.hatch.build.targets.sdist]
+include = ["neveroversell", "tests", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

neveroversell-0.1.0/tests/test_neveroversell.py

@@ -0,0 +1,188 @@
+"""The Python client against a real Postgres. Same guarantees as the TypeScript suite, same SQL."""
+
+from __future__ import annotations
+
+import os
+import time
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+from datetime import timedelta
+from pathlib import Path
+
+import psycopg
+import pytest
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+from neveroversell import Inventory, SweepRow, sql_files
+
+DATABASE_URL = os.environ.get("DATABASE_URL", "postgres://nos:nos@127.0.0.1:54329/nos")
+
+
+@pytest.fixture(scope="module")
+def pool():
+    p = ConnectionPool(DATABASE_URL, min_size=2, max_size=40, kwargs={"row_factory": dict_row}, open=True)
+    yield p
+    p.close()
+
+
+@pytest.fixture(scope="module")
+def inv(pool):
+    i = Inventory(pool=pool)
+    i.migrate()
+    return i
+
+
+@pytest.fixture(autouse=True)
+def clean(pool, inv):
+    with pool.connection() as conn:
+        conn.execute("truncate nos_hold_events, nos_holds, nos_resources restart identity cascade")
+        conn.execute(
+            "update nos_settings set hold_ttl = default, payment_window = default, account_cap = default, cap_scope = default, max_extensions = default, extension = default"
+        )
+    inv.apply_settings()
+
+
+def no_drift(inv: Inventory) -> None:
+    assert [c for c in inv.check() if c.drift] == []
+
+
+def test_bundled_sql_matches_the_repository_sql():
+    root = Path(__file__).resolve().parents[2] / "sql"
+    if not root.exists():
+        pytest.skip("repository sql/ not present (installed package)")
+    bundled = dict(sql_files())
+    repo = {p.name: p.read_text(encoding="utf-8") for p in sorted(root.glob("*.sql"))}
+    assert bundled == repo
+
+
+def test_migrations_are_idempotent(inv):
+    assert inv.migrate() == []
+
+
+def test_500_concurrent_holds_on_10_units(inv):
+    inv.upsert_resource("gig", 10)
+    with ThreadPoolExecutor(max_workers=40) as ex:
+        results = list(ex.map(lambda i: inv.hold("gig", 1, f"buyer-{i}"), range(500)))
+    assert Counter(r.status for r in results) == {"held": 10, "insufficient": 490}
+    s = inv.status("gig")
+    assert (s.held, s.sold, s.available) == (10, 0, 0)
+    no_drift(inv)
+
+
+def test_confirm_is_idempotent_across_both_paths(inv):
+    inv.upsert_resource("r", 5)
+    h = inv.hold("r", 2, "a")
+    assert h.status == "held"
+    with ThreadPoolExecutor(max_workers=12) as ex:
+        results = list(ex.map(lambda _: inv.confirm(h.hold.id, "pay_1"), range(12)))
+    assert Counter(r.status for r in results) == {"confirmed": 1, "already_confirmed": 11}
+    s = inv.status("r")
+    assert (s.held, s.sold, s.available) == (0, 2, 3)
+    no_drift(inv)
+
+
+def test_duplicate_payment_is_reported_with_both_references(inv):
+    inv.upsert_resource("r", 5)
+    h = inv.hold("r", 1, "a")
+    assert inv.confirm(h.hold.id, "pay_A").status == "confirmed"
+    dup = inv.confirm(h.hold.id, "pay_B")
+    assert (dup.status, dup.payment_ref, dup.existing_payment_ref) == ("duplicate_payment", "pay_B", "pay_A")
+    assert [e.event for e in inv.events(h.hold.id)] == ["held", "confirmed", "duplicate_payment"]
+    no_drift(inv)
+
+
+def test_one_payment_cannot_buy_two_holds(inv, pool):
+    inv.upsert_resource("r1", 5)
+    inv.upsert_resource("r2", 5)
+    h1 = inv.hold("r1", 1, "a")
+    h2 = inv.hold("r2", 1, "a")
+    with ThreadPoolExecutor(max_workers=2) as ex:
+        results = list(ex.map(lambda hid: inv.confirm(hid, "pay_shared"), [h1.hold.id, h2.hold.id]))
+    assert Counter(r.status for r in results) == {"confirmed": 1, "payment_ref_in_use": 1}
+    used = next(r for r in results if r.status == "payment_ref_in_use")
+    winner = next(r for r in results if r.status == "confirmed")
+    assert used.other_hold_id == winner.hold.id
+    with pool.connection() as conn:
+        n = conn.execute("select count(*) as n from nos_holds where payment_ref = 'pay_shared'").fetchone()["n"]
+    assert n == 1
+    no_drift(inv)
+
+
+def test_late_confirmation_never_revives_a_hold(inv):
+    inv.upsert_resource("r", 1)
+    h = inv.hold("r", 1, "a", ttl=timedelta(milliseconds=100))
+    time.sleep(0.2)
+    assert inv.sweep() == [SweepRow("r", 1, 1)]
+    late = inv.confirm(h.hold.id, "pay_late")
+    assert (late.status, late.payment_ref, late.hold.state) == ("expired", "pay_late", "expired")
+    assert inv.hold("r", 1, "someone-else").status == "held"
+    no_drift(inv)
+
+
+def test_payment_phase_outlives_the_ttl(inv):
+    inv.upsert_resource("r", 1)
+    h = inv.hold("r", 1, "a", ttl=timedelta(milliseconds=100))
+    assert inv.begin_payment(h.hold.id, window=timedelta(milliseconds=600)).status == "awaiting_payment"
+    time.sleep(0.25)
+    assert inv.sweep() == []
+    assert inv.hold("r", 1, "b").status == "insufficient"
+    assert inv.confirm(h.hold.id, "pay_slow_bank").status == "confirmed"
+    assert inv.status("r").sold == 1
+    no_drift(inv)
+
+
+def test_idempotency_key_replays(inv):
+    inv.upsert_resource("r", 50)
+    with ThreadPoolExecutor(max_workers=20) as ex:
+        results = list(ex.map(lambda _: inv.hold("r", 1, "a", idempotency_key="same"), range(20)))
+    assert len({r.hold.id for r in results}) == 1
+    assert Counter(r.status for r in results)["held"] == 1
+    assert inv.status("r").held == 1
+    no_drift(inv)
+
+
+def test_release_and_extend(inv):
+    inv.upsert_resource("r", 2)
+    h = inv.hold("r", 1, "a", ttl=timedelta(seconds=5))
+    assert inv.extend(h.hold.id, by=timedelta(minutes=1)).status == "extended"
+    assert inv.extend(h.hold.id, by=timedelta(minutes=1)).status == "not_extendable"
+    assert inv.release(h.hold.id, reason="changed mind").status == "released"
+    assert inv.release(h.hold.id).status == "already_released"
+    assert inv.confirm(h.hold.id, "pay_late").status == "released"
+    assert inv.status("r").available == 2
+    no_drift(inv)
+
+
+def test_configuration_is_validated_twice(inv, pool):
+    with pytest.raises(ValueError, match="must exceed hold_ttl"):
+        Inventory(pool=pool, hold_ttl=timedelta(minutes=20), payment_window=timedelta(minutes=10))
+    with pool.connection() as conn, pytest.raises(psycopg.errors.CheckViolation):
+        conn.execute("update nos_settings set hold_ttl = interval '2 minutes', payment_window = interval '1 minute'")
+
+
+def test_the_database_is_the_last_line_of_defence(inv, pool):
+    inv.upsert_resource("r", 3)
+    inv.hold("r", 2, "a")
+    with pool.connection() as conn, pytest.raises(psycopg.errors.CheckViolation):
+        conn.execute("update nos_resources set sold = total where id = 'r'")
+    assert inv.upsert_resource("r", 1).status == "capacity_below_committed"
+
+
+def test_account_cap_across_resources(pool):
+    capped = Inventory(pool=pool, account_cap=3, cap_scope="account")
+    capped.apply_settings()
+    capped.upsert_resource("r1", 100)
+    capped.upsert_resource("r2", 100)
+    with ThreadPoolExecutor(max_workers=20) as ex:
+        results = list(ex.map(lambda i: capped.hold("r1" if i % 2 else "r2", 1, "greedy"), range(20)))
+    assert Counter(r.status for r in results) == {"held": 3, "account_cap": 17}
+    assert capped.status("r1").held + capped.status("r2").held == 3
+    no_drift(capped)
+
+
+def test_programmer_errors_raise(inv):
+    inv.upsert_resource("r", 1)
+    with pytest.raises(psycopg.errors.InvalidParameterValue):
+        inv.hold("r", 0, "a")
+    assert inv.hold("nope", 1, "a").status == "unknown_resource"