monkrb 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b983d19c7b6de8509f55f50c796d00d90c2d5d345cbe2a9e0f30e8f1349fe7be
-  data.tar.gz: 0fc9a16f56f69aafd1f3937268d337054399c7de34dd1a9a4986d3a6ae3e1bd5
+  metadata.gz: e8e07694f006907b83202dbafa0dcbfd61d31e1c1f90b1012597dada8eb24c3e
+  data.tar.gz: cbadf97dbb1fb1063332c7046afcc96fd526e7c483c0bcc8a5873f1b94bb2636
 SHA512:
-  metadata.gz: 582398dd16f93f3d352ed51edfb79904a0e494c98daba3230abce233901b468a5e482d5fa97dfe29832293d79e85e340a491d5899cda327a298b120108008f1a
-  data.tar.gz: 1bde7799803407e6b41c52040e6fa3893a4fd8c2ebb9cca5324cfeb6a1ac291b8a5eaabd7f591204c835179985d14887b009610ebab82f650a6b3d528355f901
+  metadata.gz: f44edaf6f9f80765fa51841d068b920f880fc6855fd702cbff242a51423ca4f7206452b9f4899a6ca5340b2ac228fd8604c287e1dad82d9f122ea6ac26304b2d
+  data.tar.gz: 1dc1579210fbbd2c211a590eb50ccabf9c385b7e2d8362b723c0cbe1edd55ad64bfd886d8948725d4514b84afee274144fd25790dbf554b82a0372072319e33d

data/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to this project are documented here. Format is loosely
 [Keep a Changelog](https://keepachangelog.com/); versions are as released
 in `lib/monk/version.rb`.
 
+## 0.18.0 - 2026-09-29
+
+### Added
+
+- `Monk::Jobs` (`require "monk/jobs"`): background jobs on Postgres, with
+  no other dependency. A job is a `Monk::Job` subclass with
+  `self.perform` and optional `queue`, `priority`, `max_attempts` and
+  `timeout` settings, enqueued with `SendReceipt.enqueue(*args, wait:,
+  at:, conn:)`. Args must be plain JSON values, checked at enqueue.
+  `conn:` enqueues inside the app's own transaction. The queue is a narrow
+  state table plus a payload table, claimed with `FOR UPDATE SKIP
+  LOCKED`: ADR 0013 records the design and the benchmarks that chose it
+  over one wide table and over Solid Queue's split.
+  `Monk::Jobs::Runtime` (`require "monk/jobs/runtime"`) is the job
+  process. It runs a supervisor and a pool of worker Ractors, retries
+  failures with backoff, keeps jobs that run out of attempts as failed
+  (`Monk::Jobs.retry_failed`/`discard_failed`), and releases the jobs of
+  dead workers and dead processes. On `TERM` it finishes the jobs in hand
+  first. Delivery is at-least-once. For tests, `Monk::Jobs.drain!` runs
+  every due job in its own Ractor, and `Monk::Jobs.clear!` empties the
+  queue (test environment only). See `docs/guides/jobs.md`.
+- `monk new --jobs` (implies `--postgres`): `config/jobs.rb`, a demo
+  `HelloJob` with a `POST /jobs/hello` route, `bin/jobs`, the queue's
+  migration, `JOBS_WORKERS`/`JOBS_QUEUES` in `.env`, and `SETUP.md`
+  steps for running and testing jobs.
+- `Monk::Mail.deliver_later` (`require "monk/mail/later"`): `deliver`'s
+  arguments plus `wait:`/`at:`/`conn:`, sent from a job on the `mailers`
+  queue. The message is checked when called, so bad input raises there.
+  Temporary failures are retried, while a refusal the server made final
+  (SMTP 5xx, refused credentials) fails the job at once as the new
+  `Monk::Mail::PermanentDeliveryError`, a `DeliveryError`. `deliver` is
+  unchanged. See ADR 0014.
+- `never_retry *error_classes` on `Monk::Job`: errors that fail a job at
+  once instead of spending its remaining attempts.
+- `monk new` prints the flags it resolved: which ones another flag turned
+  on, and why (`--postgres (needed by --auth, --jobs)`), and which pairs
+  change what gets generated. `monk --help` and the scaffolding guide
+  state the rule behind it: a flag is implied when there's only one right
+  answer, and required when there's a real choice (`--live`'s transport).
+- `monk new --auth --jobs` adds `jobs/send_login_link.rb`, which creates
+  the login token and sends the link inside the job, so the raw token is
+  never stored in the queue. With mail, `--jobs` also loads
+  `deliver_later` and serves the `mailers` queue first.
+
+### Fixed
+
+- `json` and `jsonb` columns read through `Monk::Persistence::Pg` (raw
+  queries and `Model` alike) raised `ArgumentError: unknown keyword:
+  quirks_mode`. pg 1.6.3's JSON decoder passes that keyword to
+  `JSON.parse`, and json 3 removed it. Monk's connections now decode
+  `json`/`jsonb` with their own decoder, keeping pg's other default
+  types.
+- The sample test `SETUP.md` gives a `monk new --postgres` app (without
+  `--auth`) failed as written: it expected `SELECT 1` to return the
+  String `"1"`, but Monk's connections decode it to the Integer `1`.
+
 ## 0.17.0 - 2026-09-26
 
 ### Added

data/README.md

@@ -2,7 +2,7 @@
 
 A light Ruby web framework designed to be fully `Ractor`-safe: every app it produces is a valid Rack 3 app that is also `Ractor.shareable?`, so it can be served in parallel across Ractor worker pools without silently losing that safety property. Named after Thelonious Sphere Monk, great and unique Jazz piano player and composer.
 
-**Built in** (loaded by `require "monk"`): routing, context and error handling, boot-time Ractor-shareability checks, `Monk::StateRactor` for shared state, settings, ERB views, static assets and logging. **Opt-in** (each needs its own `require`): Postgres persistence and migrations, passwordless auth and sessions, a WebSocket server with Redis or Postgres fan-out, and `Monk::Live` server-pushed HTML updates. Details for each are in the [Features](#features) table below.
+**Built in** (loaded by `require "monk"`): routing, context and error handling, boot-time Ractor-shareability checks, `Monk::StateRactor` for shared state, settings, ERB views, static assets and logging. **Opt-in** (each needs its own `require`): Postgres persistence and migrations, passwordless auth and sessions, email, background jobs on Postgres, a WebSocket server with Redis or Postgres fan-out, and `Monk::Live` server-pushed HTML updates. Details for each are in the [Features](#features) table below.
 
 Monk is Kino-agnostic — it's built on stdlib `Ractor` primitives only, with no runtime dependency on any particular server. [Kino](https://github.com/yaroslav/kino) is the reference/development server (see `bin/server`), but any Ractor-aware Rack server, or a conventional one, can run a Monk app.
 
@@ -22,7 +22,7 @@ bin/server           # -> http://localhost:9292/hello
 
 `monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", require: "monk"`.
 
-`monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `views/`, `public/`, a `SETUP.md`). Flags add Postgres, auth, Redis and live updates: see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md).
+`monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `views/`, `public/`, a `SETUP.md`). Flags add Postgres, auth, email, background jobs, Redis and live updates: see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md).
 
 All `monk` commands and flags are listed by:
 
@@ -60,10 +60,11 @@ Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
 | Persistence | `Monk::Persistence::Pg`: raw `pg`, per-Ractor connections, hash-based `Model` | `require "monk/persistence/pg"` (+ `.../pg/model`); needs the `pg` gem | [`persistence.md`](docs/guides/persistence.md) |
 | Migrations | plain `.sql` up/down pairs, `Migrator` | `require "monk/persistence/pg/migrator"`; needs the `pg` gem | [`migrations.md`](docs/guides/migrations.md) |
 | Auth and sessions | `Monk::Auth`: passwordless tokens, Bearer or cookie + CSRF | `require "monk/auth"`; needs the `pg` gem and a registered Postgres connection | [`auth.md`](docs/guides/auth.md) |
-| Email | `Monk::Mail`: text/HTML email over SMTP or a local relay, one `MAIL_URL`, sent from any worker Ractor | `require "monk/mail"`; SMTP needs the `net-smtp` gem | [`mail.md`](docs/guides/mail.md) |
+| Email | `Monk::Mail`: text/HTML email over SMTP or a local relay, one `MAIL_URL`, sent from any worker Ractor, or from a background job with `deliver_later` | `require "monk/mail"` (+ `require "monk/mail/later"` for `deliver_later`, which needs background jobs); SMTP needs the `net-smtp` gem | [`mail.md`](docs/guides/mail.md) |
+| Background jobs | `Monk::Jobs`: a queue in Postgres, run by `bin/jobs` on worker Ractors; retries with backoff, scheduled jobs, enqueue inside the app's own transaction, `drain!` for tests | `require "monk/jobs"` (+ `require "monk/jobs/runtime"` in the job process); needs the `pg` gem and a registered Postgres connection | [`jobs.md`](docs/guides/jobs.md) |
 | WebSocket | `Monk::WebSocket`: RFC 6455 server as its own process, Redis or Postgres fan-out | `require "monk/websocket"`; fan-out: `require "monk/websocket/redis_fanout"` (+ the `redis` gem) or `require "monk/websocket/pg_fanout"` (+ the `pg` gem) | [`websocket.md`](docs/guides/websocket.md) |
 | Live updates | `Monk::Live`: server-rendered HTML patches pushed to open tabs | `require "monk/live"`; needs the WebSocket server and, across processes, Redis or Postgres | [`live.md`](docs/guides/live.md) |
-| Scaffolding | `monk new` and its flags; retrofitting Postgres, Auth or Redis | — (the `monk` command; flags `--postgres`, `--auth`, `--redis`, `--live`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
+| Scaffolding | `monk new` and its flags; retrofitting Postgres, Auth, Redis or Jobs | — (the `monk` command; flags `--postgres`, `--auth`, `--mail`, `--jobs`, `--redis`, `--live`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
 
 ## More documentation
 

data/exe/monk

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 require_relative "../lib/monk/scaffold"
 
-USAGE = "Usage: monk new APP_NAME [--postgres] [--auth] [--mail] [--redis] [--live]".freeze
+USAGE = "Usage: monk new APP_NAME [--postgres] [--auth] [--mail] [--redis] [--live] [--jobs]".freeze
 
 HELP = <<~TEXT.freeze
   #{USAGE}
@@ -79,6 +79,37 @@ HELP = <<~TEXT.freeze
                        views/index.erb and bin/websocket_server with live
                        versions, and adds the runtime's <meta>/<script> tags
                        to the layout.
+      --jobs          Also scaffold Monk::Jobs (background jobs on Postgres).
+                       Implies --postgres, where the queue lives. Adds
+                       config/jobs.rb (required by config.ru, after
+                       persistence/auth/mail), jobs/hello_job.rb (a demo
+                       job, enqueued by a POST /jobs/hello route added to
+                       config.ru), bin/jobs (the job process, run beside
+                       bin/server), and the migration creating the queue's
+                       tables. .env/.env.example get JOBS_WORKERS and
+                       JOBS_QUEUES (not .env.test: tests run jobs with
+                       Monk::Jobs.drain!).
+
+  How flags combine -- a flag is implied when there's only one right
+  answer, and required when there's a real choice:
+
+      Flag         Implies               Requires
+      --auth       --postgres, --mail    -
+      --jobs       --postgres            -
+      --live       -                     --redis or --postgres (Live's
+                                         transport: a choice, so it's yours)
+      --postgres, --mail, --redis stand alone.
+
+  Some pairs also change what gets generated:
+
+      --auth + --jobs      jobs/send_login_link.rb: login links sent from a job
+      --mail + --jobs      config/jobs.rb loads Monk::Mail.deliver_later;
+                           JOBS_QUEUES serves mailers first
+      --live + --redis     config/live.rb fans out over Redis
+      --live + --postgres  config/live.rb fans out over Postgres (without --redis)
+
+  `monk new` prints which flags it turned on, and why, after creating the
+  project.
 
   Commands:
       new APP_NAME    Create a new project (see Options above)
@@ -119,20 +150,27 @@ when "new"
   app_name = rest.find { |arg| !arg.start_with?("-") }
   usage_error! if app_name.nil?
 
+  # Flags as typed: Monk::Scaffold resolves what they imply, and reports it.
   auth = rest.include?("--auth")
-  mail = rest.include?("--mail") || auth
+  mail = rest.include?("--mail") || auth # for the next-steps lines below
   redis = rest.include?("--redis")
   live = rest.include?("--live")
-  Monk::Scaffold.new(
-    app_name, postgres: rest.include?("--postgres"), auth: auth, mail: mail, redis: redis, live: live,
-  ).write!
-
-  puts "Created #{app_name}. Next steps:"
+  jobs = rest.include?("--jobs")
+  scaffold = Monk::Scaffold.new(
+    app_name, postgres: rest.include?("--postgres"), auth: auth, mail: rest.include?("--mail"), redis: redis,
+    live: live, jobs: jobs,
+  )
+  scaffold.write!
+
+  puts "Created #{app_name}."
+  puts scaffold.summary
+  puts "Next steps:"
   puts "  cd #{app_name}"
   puts "  bundle install"
   puts "  see SETUP.md for the full dev-then-test walkthrough"
   puts "  change the placeholder AUTH_SECRET in .env/.env.test before relying on it" if auth
   puts "  set MAIL_URL and MAIL_FROM outside development (see config/mail.rb)" if mail
+  puts "  run bin/jobs beside bin/server to process background jobs (see SETUP.md)" if jobs
   if live
     if redis
       puts "  Monk::Live needs Redis running, bin/server and bin/websocket_server (see SETUP.md)"

data/lib/monk/jobs/adapters/pg.rb

@@ -0,0 +1,272 @@
+require "json"
+require "time"
+require_relative "../../persistence/pg"
+require_relative "../claim"
+
+module Monk
+  module Jobs
+    module Adapters
+      # The queue on Postgres: monk_jobs + monk_job_payloads + monk_processes
+      # (docs/adr/0013-jobs-narrow-state-table-plus-payloads.md). Holds only
+      # the registered database's name and freezes itself, so the one
+      # instance is shareable with every Ractor; each Ractor reaches the
+      # database through its own connection, via Monk::Persistence::Pg.
+      class Pg
+        # One statement, so a job and its payload are written together even
+        # outside a transaction. The database clock decides run_at, and so
+        # whether the job starts scheduled or available -- an app server's
+        # clock running a little ahead can't make a job look due early.
+        ENQUEUE_SQL = <<~SQL.freeze
+          WITH due AS (
+            SELECT COALESCE($4::timestamptz, now() + COALESCE($5::float8, 0) * interval '1 second') AS run_at
+          ), job AS (
+            INSERT INTO monk_jobs (queue, priority, max_attempts, run_at, state)
+            SELECT $1::text, $2::smallint, $3::smallint, run_at,
+              CASE WHEN run_at > now() THEN 'scheduled' ELSE 'available' END
+            FROM due
+            RETURNING id
+          )
+          INSERT INTO monk_job_payloads (job_id, job_class, args)
+          SELECT id, $6::text, $7::jsonb FROM job
+          RETURNING job_id
+        SQL
+
+        # Decision 2: the claim rewrites only the narrow monk_jobs row. args
+        # comes back as text and is parsed here rather than by the
+        # connection's result type map, so it decodes the same whichever
+        # connection runs it.
+        CLAIM_SQL = <<~SQL.freeze
+          WITH claimed AS (
+            UPDATE monk_jobs
+            SET state = 'running', locked_by = $2, locked_at = now(), attempts = attempts + 1
+            WHERE id = (
+              SELECT id FROM monk_jobs
+              WHERE queue = $1 AND state = 'available'
+              ORDER BY priority, run_at, id
+              FOR UPDATE SKIP LOCKED
+              LIMIT 1
+            )
+            RETURNING id, attempts
+          )
+          SELECT claimed.id, claimed.attempts, payload.job_class, payload.args::text AS args
+          FROM claimed JOIN monk_job_payloads payload ON payload.job_id = claimed.id
+        SQL
+
+        # Only while this process still holds the job: one pruned from a dead
+        # process and claimed again elsewhere isn't deleted by the first
+        # worker finishing late. The payload goes by ON DELETE CASCADE.
+        FINISH_SQL = <<~SQL.freeze
+          DELETE FROM monk_jobs WHERE id = $1 AND state = 'running' AND locked_by = $2
+        SQL
+
+        # Only while this process still holds the job, like FINISH_SQL. The
+        # database decides where it goes: back to scheduled, due retry_in
+        # seconds from now, or to failed once it has used its last attempt
+        # (attempts was already counted when it was claimed) or when
+        # retry_in is NULL. The payload keeps the error either way; the
+        # payload update runs whether or not the final SELECT reads it.
+        FAIL_SQL = <<~SQL.freeze
+          WITH job AS (
+            UPDATE monk_jobs SET
+              state = CASE WHEN $3::float8 IS NULL OR attempts >= max_attempts THEN 'failed' ELSE 'scheduled' END,
+              run_at = CASE WHEN $3::float8 IS NULL OR attempts >= max_attempts THEN run_at
+                            ELSE now() + $3::float8 * interval '1 second' END,
+              locked_by = NULL, locked_at = NULL
+            WHERE id = $1 AND state = 'running' AND locked_by = $2
+            RETURNING id, state
+          ), payload AS (
+            UPDATE monk_job_payloads SET last_error = $4 FROM job WHERE monk_job_payloads.job_id = job.id
+          )
+          SELECT state FROM job
+        SQL
+
+        # The stager: due scheduled jobs become available, oldest first, at
+        # most $1 per call. SKIP LOCKED lets every job process stage at
+        # once without two of them moving the same job.
+        STAGE_SQL = <<~SQL.freeze
+          UPDATE monk_jobs SET state = 'available'
+          WHERE id IN (
+            SELECT id FROM monk_jobs
+            WHERE state = 'scheduled' AND run_at <= now()
+            ORDER BY run_at
+            LIMIT $1
+            FOR UPDATE SKIP LOCKED
+          )
+        SQL
+
+        RETRY_FAILED_SQL = <<~SQL.freeze
+          UPDATE monk_jobs SET state = 'available', attempts = 0, run_at = now() WHERE id = $1 AND state = 'failed'
+        SQL
+
+        DISCARD_FAILED_SQL = <<~SQL.freeze
+          DELETE FROM monk_jobs WHERE id = $1 AND state = 'failed'
+        SQL
+
+        REGISTER_PROCESS_SQL = <<~SQL.freeze
+          INSERT INTO monk_processes (hostname, pid) VALUES ($1, $2) RETURNING id
+        SQL
+
+        # An upsert, not an UPDATE: a process that stalled long enough for
+        # another to prune it gets its row back under the same id. The jobs
+        # pruning released stay with whoever claimed them since; this
+        # process's late finish/fail calls on them just find nothing held.
+        HEARTBEAT_SQL = <<~SQL.freeze
+          INSERT INTO monk_processes (id, hostname, pid) OVERRIDING SYSTEM VALUE VALUES ($1, $2, $3)
+          ON CONFLICT (id) DO UPDATE SET last_heartbeat_at = now()
+        SQL
+
+        # Deletes processes whose heartbeat is older than $1 seconds, and
+        # releases their running jobs back to available with their attempt
+        # still counted (Decision 4). Also releases running jobs with no
+        # process row at all once they've been running that long -- a
+        # drain! that crashed mid-job, or rows left by a bug. The NOT EXISTS
+        # sees the rows as they were before the DELETE, so a pruned
+        # process's jobs are caught by the first condition.
+        PRUNE_SQL = <<~SQL.freeze
+          WITH dead AS (
+            DELETE FROM monk_processes
+            WHERE last_heartbeat_at < now() - $1::float8 * interval '1 second'
+            RETURNING id
+          )
+          UPDATE monk_jobs SET state = 'available', locked_by = NULL, locked_at = NULL
+          WHERE state = 'running' AND (
+            locked_by IN (SELECT id FROM dead)
+            OR (locked_at < now() - $1::float8 * interval '1 second'
+                AND NOT EXISTS (SELECT 1 FROM monk_processes p WHERE p.id = monk_jobs.locked_by))
+          )
+        SQL
+
+        # A graceful stop: whatever this process still has running goes back
+        # to available, and its row goes.
+        DEREGISTER_SQL = <<~SQL.freeze
+          WITH gone AS (DELETE FROM monk_processes WHERE id = $1)
+          UPDATE monk_jobs SET state = 'available', locked_by = NULL, locked_at = NULL
+          WHERE state = 'running' AND locked_by = $1
+        SQL
+
+        # One job back to available, if process_id still holds it: the job a
+        # worker was running when that worker died.
+        RELEASE_SQL = <<~SQL.freeze
+          UPDATE monk_jobs SET state = 'available', locked_by = NULL, locked_at = NULL
+          WHERE id = $1 AND state = 'running' AND locked_by = $2
+        SQL
+
+        CLEAR_SQL = <<~SQL.freeze
+          DELETE FROM monk_jobs;
+          DELETE FROM monk_processes;
+        SQL
+
+        attr_reader :db_name
+
+        def initialize(db_name:)
+          @db_name = db_name
+          freeze
+        end
+
+        # Returns the new job's id. conn: runs it on a connection the caller
+        # already holds, inside the caller's transaction -- required rather
+        # than optional there, since checking out the same Ractor's
+        # connection again would wait on itself.
+        def enqueue(job_class:, queue:, priority:, max_attempts:, args:, wait: nil, at: nil, conn: nil)
+          params = [queue, priority, max_attempts, at&.utc&.iso8601(6), wait&.to_f, job_class, args]
+          with_connection(conn) { |c| Integer(c.exec_params(ENQUEUE_SQL, params).getvalue(0, 0)) }
+        end
+
+        # The next available job on `queue`, now running for process_id, or
+        # nil when there's none.
+        def claim(queue, process_id)
+          row = with_connection { |c| c.exec_params(CLAIM_SQL, [queue, process_id]).first }
+          return nil unless row
+
+          Claim.new(
+            id: Integer(row["id"]), job_class: row["job_class"],
+            args: JSON.parse(row["args"]), attempts: Integer(row["attempts"]),
+          )
+        end
+
+        # True if the job was deleted, false if process_id no longer held it.
+        def finish(id, process_id)
+          with_connection { |c| c.exec_params(FINISH_SQL, [id, process_id]).cmd_tuples == 1 }
+        end
+
+        # Records a failure of a job process_id holds: :scheduled when it will
+        # be retried in retry_in seconds, :failed when it won't (no attempts
+        # left, or retry_in nil), nil when process_id no longer held it.
+        def fail(id, process_id, error:, retry_in:)
+          row = with_connection { |c| c.exec_params(FAIL_SQL, [id, process_id, retry_in&.to_f, error]).first }
+          row && row["state"].to_sym
+        end
+
+        # Moves up to `limit` due scheduled jobs to available; returns how many.
+        def stage_due(limit = 500)
+          with_connection { |c| c.exec_params(STAGE_SQL, [limit]).cmd_tuples }
+        end
+
+        # A failed job back to available with fresh attempts. False if it
+        # isn't failed (or doesn't exist).
+        def retry_failed(id)
+          with_connection { |c| c.exec_params(RETRY_FAILED_SQL, [id]).cmd_tuples == 1 }
+        end
+
+        # Deletes a failed job and its payload. False if it isn't failed.
+        def discard_failed(id)
+          with_connection { |c| c.exec_params(DISCARD_FAILED_SQL, [id]).cmd_tuples == 1 }
+        end
+
+        # A job process's own row; returns its id, the process_id it claims
+        # jobs as.
+        def register_process(hostname:, pid:)
+          with_connection { |c| Integer(c.exec_params(REGISTER_PROCESS_SQL, [hostname, pid]).getvalue(0, 0)) }
+        end
+
+        def heartbeat(process_id, hostname:, pid:)
+          with_connection { |c| c.exec_params(HEARTBEAT_SQL, [process_id, hostname, pid]) }
+          nil
+        end
+
+        # Releases the jobs of processes silent for more than `timeout`
+        # seconds, and deletes those processes; returns how many jobs were
+        # released.
+        def prune(timeout)
+          with_connection { |c| c.exec_params(PRUNE_SQL, [timeout.to_f]).cmd_tuples }
+        end
+
+        # The job a dead worker was holding, back to available with its
+        # attempt counted; true if process_id still held it.
+        def release(id, process_id)
+          with_connection { |c| c.exec_params(RELEASE_SQL, [id, process_id]).cmd_tuples == 1 }
+        end
+
+        # Releases this process's running jobs and deletes its row.
+        def deregister(process_id)
+          with_connection { |c| c.exec_params(DEREGISTER_SQL, [process_id]) }
+          nil
+        end
+
+        # After a job timed out mid-query: cancels whatever the calling
+        # Ractor's connection is still running on the server, then
+        # reconnects, so the worker's next query doesn't wait for the
+        # abandoned one (Phase 0.3) or land inside its open transaction.
+        def reset_connection
+          conn = Monk::Persistence::Pg[@db_name]
+          conn.cancel
+          conn.reset
+          nil
+        end
+
+        # Every job (payloads by cascade) and every process row. Behind
+        # Monk::Jobs.clear!, which only runs in tests.
+        def clear!
+          with_connection { |c| c.exec(CLEAR_SQL) }
+          nil
+        end
+
+        private
+
+        def with_connection(conn = nil, &)
+          conn ? yield(conn) : Monk::Persistence::Pg.checkout(@db_name, &)
+        end
+      end
+    end
+  end
+end

data/lib/monk/jobs/args.rb

@@ -0,0 +1,43 @@
+module Monk
+  module Jobs
+    # A job's args are stored as JSON (monk_job_payloads.args) and handed
+    # back to #perform in another process, so only values that come back
+    # from that round trip unchanged are accepted: Strings, Integers,
+    # finite Floats, true/false/nil, and Arrays and String-keyed Hashes of
+    # those. Checked when a job is enqueued, so a bad argument fails in
+    # the code that passed it rather than later, in a worker.
+    module Args
+      def self.check!(args)
+        raise InvalidArgumentsError, "a job's args must be an Array, got #{args.class}" unless args.is_a?(Array)
+
+        args.each_with_index { |value, i| check_value!(value, "args[#{i}]") }
+        nil
+      end
+
+      def self.check_value!(value, path)
+        case value
+        when String, Integer, true, false, nil
+          nil
+        when Float
+          raise InvalidArgumentsError, "#{path} is #{value}, which JSON can't represent" unless value.finite?
+        when Array
+          value.each_with_index { |item, i| check_value!(item, "#{path}[#{i}]") }
+        when Hash
+          value.each do |key, item|
+            unless key.is_a?(String)
+              raise InvalidArgumentsError,
+                "#{path} has the key #{key.inspect} (a #{key.class}); JSON only has String keys, so " \
+                "#perform would get back a different Hash -- use #{key.to_s.inspect}"
+            end
+            check_value!(item, "#{path}[#{key.inspect}]")
+          end
+        else
+          raise InvalidArgumentsError,
+            "#{path} is a #{value.class}, which doesn't survive a JSON round trip -- pass plain values " \
+            "(e.g. an id rather than a record, an ISO 8601 String rather than a Time)"
+        end
+      end
+      private_class_method :check_value!
+    end
+  end
+end

data/lib/monk/jobs/claim.rb

@@ -0,0 +1,7 @@
+module Monk
+  module Jobs
+    # A job a worker has claimed: what it needs to run it (job_class, args)
+    # and to decide what happens if it raises (attempts, counting this one).
+    Claim = Data.define(:id, :job_class, :args, :attempts)
+  end
+end

data/lib/monk/jobs/errors.rb

@@ -0,0 +1,29 @@
+module Monk
+  module Jobs
+    # Looking up a job class before Monk.freeze! (Monk.boot calls it) has
+    # sealed the registry -- from a worker Ractor the unfrozen registry
+    # couldn't even be read.
+    class NotFrozenError < StandardError
+    end
+
+    # A job_class name that isn't a Monk::Job subclass this process knows
+    # about: a job enqueued by a newer deploy, a renamed class, or a name
+    # that was never a job at all.
+    class UnknownJobError < StandardError
+    end
+
+    # Enqueueing (or claiming) before Monk::Jobs.configure has picked the
+    # database the queue lives in.
+    class NotConfiguredError < StandardError
+    end
+
+    # Monk::Jobs.clear! outside MONK_ENV=test: it would empty a real queue.
+    class ClearOutsideTestsError < StandardError
+    end
+
+    # An ArgumentError, like Monk::Mail::InvalidMessageError: it's always
+    # the caller's input that's wrong.
+    class InvalidArgumentsError < ArgumentError
+    end
+  end
+end

data/lib/monk/jobs/job.rb

@@ -0,0 +1,117 @@
+module Monk
+  # The class an app's jobs inherit from:
+  #
+  #   class SendReceipt < Monk::Job
+  #     queue "mailers"   # optional; "default" otherwise
+  #     priority 10       # optional; lower runs sooner, 0 otherwise
+  #     max_attempts 3    # optional; 5 otherwise
+  #     timeout 30        # optional; seconds a run may take, no limit otherwise
+  #     never_retry KeyError  # optional; errors that fail the job at once
+  #
+  #     def self.perform(order_id)
+  #       ...
+  #     end
+  #   end
+  #
+  # A class, not a block: a Class is always Ractor-shareable, so #perform
+  # is callable from every worker Ractor without the make_shareable rules
+  # a Proc has to meet (docs/design/ractor.md). Settings are inherited, so
+  # an app can put shared ones on its own base class.
+  class Job
+    DEFAULT_QUEUE = "default".freeze
+    DEFAULT_PRIORITY = 0
+    DEFAULT_MAX_ATTEMPTS = 5
+
+    # monk_jobs.priority and max_attempts are SMALLINT columns.
+    PRIORITY_RANGE = -32_768..32_767
+    MAX_ATTEMPTS_RANGE = 1..32_767
+
+    class << self
+      def inherited(subclass)
+        super
+        Monk::Jobs.record(subclass)
+      end
+
+      def queue(name = nil)
+        return @queue || inherited_setting(:queue, DEFAULT_QUEUE) if name.nil?
+
+        unless name.is_a?(String) && !name.empty?
+          raise ArgumentError, "#{self.name || "a job"}'s queue must be a non-empty String, got #{name.inspect}"
+        end
+
+        # Frozen, so a worker Ractor can read it back off the class.
+        @queue = name.dup.freeze
+      end
+
+      def priority(value = nil)
+        return @priority || inherited_setting(:priority, DEFAULT_PRIORITY) if value.nil?
+
+        @priority = checked_integer(:priority, value, PRIORITY_RANGE)
+      end
+
+      def max_attempts(value = nil)
+        return @max_attempts || inherited_setting(:max_attempts, DEFAULT_MAX_ATTEMPTS) if value.nil?
+
+        @max_attempts = checked_integer(:max_attempts, value, MAX_ATTEMPTS_RANGE)
+      end
+
+      # Seconds one run of the job may take before the worker gives up on
+      # it: the run fails (and is retried like any other failure) and the
+      # worker resets its database connection, since an interrupted query
+      # keeps running on the server otherwise. nil, the default, means no
+      # limit.
+      def timeout(seconds = nil)
+        return @timeout || (equal?(Monk::Job) ? nil : superclass.timeout) if seconds.nil?
+
+        unless seconds.is_a?(Numeric) && seconds.positive?
+          raise ArgumentError,
+            "#{name || "a job"}'s timeout must be a positive number of seconds, got #{seconds.inspect}"
+        end
+
+        @timeout = seconds
+      end
+
+      # Errors that retrying can't fix: a job that raises one of these (or
+      # a subclass of one, matched the way rescue matches) fails at once
+      # instead of spending its remaining attempts. Adds to the parent
+      # class's list rather than replacing it, so an app's own base job
+      # class can declare errors for every job. With no arguments, returns
+      # the whole list -- frozen, so a worker Ractor can read it.
+      def never_retry(*error_classes)
+        inherited = equal?(Monk::Job) ? [] : superclass.never_retry
+        unless error_classes.empty?
+          error_classes.each do |error_class|
+            next if error_class.is_a?(Class) && error_class <= Exception
+
+            raise ArgumentError,
+              "#{name || "a job"}'s never_retry takes exception classes, got #{error_class.inspect}"
+          end
+          @never_retry = ((@never_retry || []) + error_classes).uniq.freeze
+        end
+
+        (inherited + (@never_retry || [])).uniq.freeze
+      end
+
+      # SendReceipt.enqueue(order_id, wait: 60) -- see Monk::Jobs.enqueue.
+      def enqueue(*, **)
+        Monk::Jobs.enqueue(self, *, **)
+      end
+
+      def perform(*)
+        raise NotImplementedError, "#{name || "this job"} must define self.perform"
+      end
+
+      private
+
+      def inherited_setting(setting, default)
+        equal?(Monk::Job) ? default : superclass.public_send(setting)
+      end
+
+      def checked_integer(setting, value, range)
+        return value if value.is_a?(Integer) && range.cover?(value)
+
+        raise ArgumentError, "#{name || "a job"}'s #{setting} must be an Integer in #{range}, got #{value.inspect}"
+      end
+    end
+  end
+end