monkrb 0.17.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b983d19c7b6de8509f55f50c796d00d90c2d5d345cbe2a9e0f30e8f1349fe7be
-  data.tar.gz: 0fc9a16f56f69aafd1f3937268d337054399c7de34dd1a9a4986d3a6ae3e1bd5
+  metadata.gz: 5745b05b44d3f2953a037262d97c7a211ebea46b72f9872e6d626c58886338bf
+  data.tar.gz: f6a970fb8f3e724e992238c7c89f230e215cba4b9d36aadc6122bab452b36ea5
 SHA512:
-  metadata.gz: 582398dd16f93f3d352ed51edfb79904a0e494c98daba3230abce233901b468a5e482d5fa97dfe29832293d79e85e340a491d5899cda327a298b120108008f1a
-  data.tar.gz: 1bde7799803407e6b41c52040e6fa3893a4fd8c2ebb9cca5324cfeb6a1ac291b8a5eaabd7f591204c835179985d14887b009610ebab82f650a6b3d528355f901
+  metadata.gz: 9f16caa7f5d287d95cf1adaf65f72a1da511f9a02671ab06ac51634c4f2a44af2ae76c232b7931ec6118f461116f9fc0ce89d08a56bd1e23eeb8f076f4ff834e
+  data.tar.gz: 8083b153954fee1475e08b778772bdb8592ff597feae9367bf6d589bf22c5859792ea3bf9bc74e5c1baef0567568ee5302b87d1e82addc65a5703081988b7ec7

data/CHANGELOG.md

@@ -4,6 +4,139 @@ 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.19.0 - 2026-10-01
+
+### Fixed
+
+- `Monk::WebSocket::Server#run` stops on `TERM` as it does on Ctrl-C: it
+  stops accepting and returns, so `bin/websocket_server` exits 0 on
+  `docker stop` and deploys instead of being ended by the signal (exit
+  143). Open sockets are still dropped without a close frame; see
+  `docs/guides/websocket.md`, "Stopping and restarting", which also warns
+  what other clients have to handle.
+- `monk_live.js` jitters its reconnect delay (50%–150% of the backoff), so
+  the pages that lose their socket together on a WebSocket restart don't
+  all reconnect and refetch at once. An existing app has a copy of the
+  client in `public/js/monk_live/`: copy `lib/monk/live/client/` over it
+  again to get this.
+
+### Added
+
+- `Monk::WebSocket::Server.new(authenticate: :optional)`: a connection
+  with a valid session gets its subject, and one without (none, revoked or
+  expired) comes in anonymous instead of getting a `401`. The handler
+  decides what an anonymous connection may do; under `Monk::Live`, the
+  topic rules (`anonymous: true`). The `Origin` check covers cookies, as
+  under `true`, and anonymous connections that send an `Origin`.
+  `reverify_interval:` works with it, for connections that have a session.
+  `monk new --auth --live`'s `bin/websocket_server` uses it, so the demo
+  updates for visitors too, and SETUP.md explains who gets which topics.
+  The plain chat `bin/websocket_server` keeps `true`. See
+  `docs/design/websocket.md`, "Anonymous connections".
+
+### Changed
+
+- `monk new` lays the app out under `app/`, by role (ADR 0015):
+  `app/app.rb` holds `class App` and its routes, templates are in
+  `app/views/`, and every role directory is created with a `.keep`:
+  `app/models`, `presenters`, `helpers`, `mailers`, `broadcasts`, `jobs`.
+  `config.ru` is the same three lines for every flag set, and the new
+  `config/load.rb` requires the settings and each enabled module's config,
+  then loads `app/` by role. It never boots the app. `bin/jobs`,
+  `bin/console` and the generated test helper require it too. `--auth`'s
+  magic-link sender moves from `config/auth.rb` to
+  `app/mailers/app_mailer.rb` and is renamed `AppMailer::MAGIC_LINK`;
+  `config/auth.rb` requires that file itself. `config/jobs.rb` no longer
+  loads the job classes. The generated SETUP.md's test helper loads and
+  boots the app, with a sample request test. `docs/guides/scaffolding.md`,
+  "Where code goes", says what goes in each directory.
+  **An 0.18 app keeps working as it is.** To move it to the new layout:
+  1. `git mv views app/views` and `git mv jobs app/jobs`; create the other
+     role directories you want.
+  2. Move `class App` and its routes from `config.ru` into `app/app.rb`,
+     and change `views "views"` to `views "app/views"`.
+  3. Create `config/load.rb`: the `require_relative` lines `config.ru` had
+     for `config/*` (without the `config/` prefix), then the loop over
+     `app/` roles from a freshly generated one. Make `config.ru`
+     `require_relative "config/load"`, `require_relative "app/app"`,
+     `run Monk.boot(App)`.
+  4. Remove the `Dir[...]` loop from `config/jobs.rb`. In `bin/jobs`,
+     replace its config requires with `require_relative "../config/load"`
+     and point `Monk::Views.root` at `../app/views`. Do the same in
+     `bin/console`.
+  5. Optional: move `AppMailer` from `config/auth.rb` into
+     `app/mailers/app_mailer.rb` and `require_relative` it from
+     `config/auth.rb`.
+- **Breaking:** `Monk::WebSocket::RedisFanout` and `PgFanout` no longer
+  subscribe when built. The process that holds sockets calls `#listen!`
+  once at boot: `Monk::Live.listen!`, or `REGISTRY.listen!` for plain
+  `Monk::WebSocket`. Publish-only processes (`bin/server`, `bin/jobs`,
+  `bin/console`) then hold no idle subscriber connection. `#listen!`
+  returns once the subscription is in effect and raises
+  `Monk::WebSocket::ListenError` if Redis or Postgres can't be reached.
+  `#register` before `#listen!` raises
+  `Monk::WebSocket::NotListeningError`. `Registry#listen!` is a no-op, so
+  the same line works with either. The scaffolded `bin/websocket_server`
+  calls it. **To upgrade**, add `Monk::Live.listen!` (or
+  `REGISTRY.listen!`) to your `bin/websocket_server` before
+  `server.run`. See `docs/design/websocket.md`, "Who listens".
+
+## 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, `public/`, a `SETUP.md`), with the app's own code under `app/`: `app/app.rb` for routes, `app/views/`, and one directory per role (`models/`, `presenters/`, `helpers/`, `mailers/`, `broadcasts/`, `jobs/`). Flags add Postgres, auth, email, background jobs, Redis and live updates: see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md), which also says where each kind of code goes.
 
 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
 
@@ -86,6 +87,6 @@ More (server modes, Docker) in [`docs/development.md`](docs/development.md).
 
 ## Status
 
-Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). There's no open roadmap issue at the moment; new work is proposed and tracked as it comes up. Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24).
+Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). There's no open roadmap issue at the moment; new work is proposed and tracked as it comes up. Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24), the built-in mailer `Monk::Mail` (0.17, 2026-09-26, ADR 0012), and background jobs on Postgres, `Monk::Jobs`, with mail sent from jobs (0.18, 2026-09-29, ADRs 0013 and 0014). In 0.19 (2026-10-01): `monk new` lays the app out under `app/`, one directory per role (ADR 0015); a WebSocket fanout listens only in the process that holds the sockets (`#listen!`); `authenticate: :optional` lets visitors' sockets in anonymously, for Live's rules to decide; and the WebSocket server stops cleanly on `TERM` (`docs/design/websocket.md`).
 
 [Made with Love ❤️, Ruby 💎 and AI 🤖](docs/ai_usage_disclaimer.md)

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