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–0042 (admission, workflows, schedules, target attestation, bounded operator projections, the per-queue flow-control plane, …) |
| SQL contract | 0.6.6 |
| Protocol document | 1.0.17 |
| Drift oracle | taskq db verify / verify() / verify_sync() |
Capability roles
| Role | Rights |
|---|---|
taskq_owner | Owns schema objects; migration target ownership |
taskq_producer | EXECUTE enqueue / admission producer paths |
taskq_runner | Claim, heartbeat, settle |
taskq_observer | Stats / finite read views |
taskq_operator | Redrive, cancel, control, schedules, workflows |
taskq_housekeeper | Tick, reaper, and schedule firing |
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, follow-ups, workflows, schedules, continuation admission, trusted effect fence |
| Python | Models, worker loop, standalone scheduler, manifest compiler, 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.