Concepts
SQL-first contract
Why PL/pgSQL functions are the source of truth.
The protocol is a set of functions in schema taskq. The Python library, the HTTP facade, and psql are equal clients.
Schema and migrations
| Item | Value |
|---|---|
| Schema name | taskq (fixed — ADR-002) |
| Packaged migrations | 0001_initial, 0002_contract_0_1_1, 0003_contract_0_1_2 |
| Drift oracle | taskq verify / verify() / verify_sync() |
Capability roles
| Role | Rights |
|---|---|
taskq_owner | Owns schema objects; migration target ownership |
taskq_producer | EXECUTE enqueue paths |
taskq_runner | Claim, heartbeat, settle |
taskq_observer | Stats / read views |
taskq_operator | Redrive, cancel, control |
taskq_housekeeper | Tick / reaper |
Functions are owned by taskq_owner, pin search_path, revoke PUBLIC execute, and grant to a capability role. Because raw table DML is denied to runners, every documented flow has a function.
What lives where
| Layer | Owns |
|---|---|
| Postgres | Claim, fencing, retry budget, uniqueness, concurrency admission |
| Python | Models, worker loop, handler DX, optional HTTP transport |
| Host app | Job handlers, domain side effects, IAM wiring |
Typed results everywhere
Enqueue and settle never return silent null success. Expected races return structured statuses so network retries are safe.