stablemates-workhorse 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b030c71db8e2fa0f3b2e14e4ac34442270e1643ea1105efe904bc965ab6e4823
-  data.tar.gz: 90256bbd761dfa37265e9e0fce4f5f49534e378361a625bbc6bc27cf24b7634b
+  metadata.gz: 35dc8eaadac2ae86c30ad3cf2a688ffe571b7c7a8cd564ee00844685fbeb4ea6
+  data.tar.gz: 34dfeb5010846d31ea3f7b5751e14bf7ec4ed4783a9223d4e2f483534b419669
 SHA512:
-  metadata.gz: 9d580a9360fe1772b51567673be3d787ea287ba7df8693d93d8ea4b153620f0a4c0b4c5ad492593830127ccd2c78a1063b5ac5f9174bbbea6aae3f1ca2880b70
-  data.tar.gz: d353d8e0ce3d2b03b869212dee916bcead4c41034de9403c83ab1f3e3a74eaaadfa36bf0c0c0c03f22728efdee770ef437c3de369f51d1f36765f5861948679f
+  metadata.gz: 99884c5d12e4501d537c66272a668be206f796ef0f8ac7663d863898caa3f0e4a530af7a79902d81983e671b76f146bc3e54f529a7cf7d6170d44ecaadc96d5f
+  data.tar.gz: dee85878fb8e6862120d5863d8b4cd34cdd18d6e4281e1e5976f9215af12dc0c2b58aef3090e3b42e439868fe367d63f515e66a8968a73d33903c626cb5247c4

data/CHANGELOG.md

@@ -3,6 +3,378 @@
 `stablemates-workhorse` gem versions and release notes live here. The gem carries the version the
 other SDKs carry, because every tag names one release of all of them.
 
+## 0.10.0 — 2026-10-26
+
+The npm packages, Python distribution, Go module, Rust crate, Ruby gem, JVM artifacts, and .NET
+packages release from one source commit.
+
+Requires **schema v76**, Ruby **3.3** or newer, and PostgreSQL **15** or newer.
+
+### Upgrade steps
+
+**Migrate the schema before starting updated processes.** Run `workhorse schema migrate` before any
+process of this release starts, producers too. Migrations 0075 through 0087 move the schema to
+version **86**. The SDK compatibility floor rises from 73 to **76**, because every SDK statement
+catalogue now names `dashboard_retention_preview_v1` and `deregister_worker_v2`. An updated worker
+refuses to start on a schema below version 76. A 0.9 process keeps working on version 86, because a
+migration inside a major line only adds.
+
+### A failed reporter callback gives a catalogued log record
+
+A raise from `on_registration_error` or `on_notification_error` gave a log line with the error
+message and no event name (SM-1726). Now the line is the `workhorse.worker.reporter_failed` event
+with `workhorse.worker.id`, `workhorse.worker.reporter` (`registration_error` or
+`notification_error`), and `error.type`. It no longer carries the error message. The logger level,
+the standard error fallback, and the bound do not change.
+
+### The worker refuses a `poll_interval` above 2,147,483.647 seconds
+
+Before this change, `poll_interval:` had no upper limit (SM-1778). Now `Worker.new` raises
+`ArgumentError` for a value above 2,147,483.647 seconds, the limit of the registry column. Every
+SDK accepts an explicit poll interval from 1 through 2,147,483,647 ms (ADR 0112). Zero stays
+refused, and `nil` keeps the default.
+
+### The Rack dashboard refuses a cross-origin read
+
+A Rack CORS middleware can add CORS headers to `Stablemates::Workhorse::Dashboard` responses. If
+that policy allowed credentials, a page on another origin could read the dashboard, task payloads
+included, with the operator's cookies (SM-1675). Now the application answers 403 with
+`{"error":"A same-origin request is required"}` for a page, an asset, or a read procedure whose
+`Origin` header names another origin.
+
+The same-origin check compared the `Host` text exactly, so `Host: example.test:443` with
+`Origin: https://example.test` failed. Now letter case and the default port do not matter, as in
+the allowed hosts check. An `Origin` with a path, a query, a fragment, or a user fails.
+
+A request without `Origin`, such as a top-level navigation, and a same-origin request still
+work. A mutation keeps its own refusal. The change needs no migration.
+
+Upgrade step: if a proxy in front of the host ends TLS, the host must see the scheme that the
+browser used. Otherwise the dashboard page's own module scripts carry an `Origin` that does not
+match, and the host refuses them.
+
+### The dashboard Schedules page shows the last skip of a schedule
+
+Migration 0087 (`0087-show-the-last-schedule-skip-on-the-dashboard.sql`) moves the schema to version 86. The `dashboard/v1` cron document gains `lastSkippedAt`, `lastSkippedCount`, and
+`lastSkippedThrough` on each application schedule, an additive change. The bundled Schedules page
+shows a `Skipped` badge with the count and the time of the last skip of a `skip` schedule (SM-1708).
+The migration does not raise the SDK compatibility floor.
+
+### The worker counts each failed heartbeat round
+
+A heartbeat round can fail before PostgreSQL answers, for example when the connection breaks or the
+round reaches its deadline. Before this change, such a round left no metric (SM-1704).
+
+Now the worker counts each failed round once in the new counter
+`workhorse.worker.heartbeat.round_failure`, with the unit `{round}`. The bounded attribute
+`workhorse.heartbeat.failure_reason` gives the reason: `timeout`, `connection`, `database`, or
+`other`. This applies to the reserved heartbeat connection and to `shared_heartbeats: true`. A
+failed round still gives no ownership verdict, so `workhorse.worker.heartbeat.failure` does not
+change. The worker adds no log record. The new instrument is an addition.
+
+### A canceled task leaves its batch while it waits
+
+A batch handler waits up to its linger for a partial batch. Before this change, a waiting task
+stayed in the batch after a cancel request or a lease loss cancelled its cancellation token. The
+batch handler then got a task that the worker no longer owned, and the task settled only after the
+linger (SM-1709).
+
+Now the worker removes such a task from the batch at once. The task raises the `CancelledError` of
+the token reason, and the batch handler never gets it. The other waiting tasks keep their order and
+dispatch. The TypeScript, Go, and Rust workers already remove such a task.
+
+This includes the `:shutdown` cancellation at the end of the shutdown grace. Before, a task that
+still waited then dispatched, and the batch handler ran its payload after the deadline. Now the task
+goes back to its queue without a charged attempt. Before the deadline, the drain still dispatches a
+lingering batch when all its tasks have arrived.
+
+### The worker waits longer after each not_due expiry answer
+
+When the local timer of a deadline or an execution timeout fires, the worker asks PostgreSQL to
+expire the attempt. If the clock of PostgreSQL has not reached its expiry, PostgreSQL answers
+`not_due`. Before this change, the worker asked again every 5 ms. Each request locks the task row,
+so the heartbeat of the same attempt answered `busy`. If the worker clock ran ahead by more than one
+lease, the attempt could lose its lease before the database expiry (SM-1701).
+
+Now the first retry waits 5 ms, and each later retry waits twice as long, to a maximum of 1 s. The
+TypeScript, Go, and Rust workers already use this schedule.
+
+### The Ruby client measures signal and human wait values as PostgreSQL does
+
+PostgreSQL limits a signal payload, a human wait context, and a human wait result to 65,536 bytes of
+`octet_length(value::jsonb::text)`. That text has a space after each `:` and `,`, so it can be
+longer than compact JSON. Before this change, the Ruby client counted the compact JSON. A value near
+the limit passed that check, and then PostgreSQL refused the statement with a database error
+(SM-1639).
+
+Now `Queue#send_signal`, `Queue#complete_human_wait`, and `HandlerContext#wait_for_human` measure
+the canonical JSONB text before any statement. An oversized value raises `ArgumentError`.
+`HandlerContext#wait_for_human` also checks the context before its tier lookup, which can read
+PostgreSQL. The limit does not change.
+
+### The worker warns when a maintenance pass or a claim waits longer than the stop budget
+
+A maintenance pass or a claim can wait for a lock that another session holds. Before this change,
+the worker logged nothing while it waited. A test run blocked for about one hour, and no log named
+the statement (SM-1785).
+
+Now `Worker` logs `workhorse.worker.statement_slow` once, at warn level, if a maintenance pass or a
+claim waits longer than the stop budget. The stop budget is `shutdown_grace`, 25 s by default. A
+grace of 0 turns the warning off. The record carries `workhorse.worker.id`,
+`workhorse.worker.statement` (`maintenance` or `claim`), and `workhorse.worker.elapsed_ms`.
+`workhorse.worker.elapsed_ms` is the wait at the moment of the warning. The statement continues to
+wait, and no other behavior changes.
+
+### execution_timeout refuses a nonzero value that rounds to 0 ms
+
+The queue rounds `execution_timeout:` to the nearest millisecond. Before this change, a positive
+value below 0.0005 seconds rounded to 0, and the task had no timeout. A small negative value, such
+as -0.0004, also set no timeout (SM-1714).
+
+Now the queue raises `ArgumentError` for a nonzero value that rounds to 0 ms or is negative. `nil`
+and an exact 0 still set no timeout. ADR 0114 records the rule for all seven SDKs.
+
+### The worker intervals refuse a value above the SQL integer limit
+
+`register_worker_v1` takes `maintenance_interval`, `maintenance_routine_interval`, and
+`registry_interval` as PostgreSQL `integer` milliseconds. Before this change, `Worker.new` accepted
+a larger value, and then each registration failed (SM-1668).
+
+Now `Worker.new` raises `ArgumentError` if one of these intervals is not from 0.1 through
+2,147,483.647 seconds. `disable_registry: true` still turns off registration. This is a behavior
+change for a caller who passes a larger value. ADR 0112 records the range for all seven SDKs.
+
+### An anonymous error class records the name of its superclass
+
+Ruby gives an anonymous class a nil name. Before this change, a handler that raised an instance of
+`Class.new(StandardError)` recorded JSON null as the failure `name` (SM-1668).
+
+Now the failure envelope records the name of the nearest named superclass, `StandardError` in that
+example. Logs and telemetry use the same name for `error.type`.
+
+### retry_delay refuses a small negative value and rounds exact values exactly
+
+`fail_v1` takes the retry delay as a PostgreSQL `integer`. Before this change, the worker rounded a
+`retry_delay` to milliseconds first. Thus a negative value such as `-0.0004` became 0 and passed.
+The worker also converted the value to a Float first, so `Rational(1001, 2000)`, which is exactly
+500.5 ms, became 500 ms (SM-1668).
+
+Now the worker raises `ArgumentError` for every negative `retry_delay`, at construction for a fixed
+value and before `fail_v1` for a callable result. It converts Integer, Rational, and BigDecimal
+seconds exactly and rounds half up, so that value becomes 501 ms. ADR 0111 records the rule for all
+seven SDKs.
+
+### A raising reporter callback no longer stops the worker
+
+An application can give `on_registration_error` to the worker to send an alert. Before this change,
+a registration refresh could fail, and then the callback could raise. The error left the registry
+path and could stop the run. The worker also discarded a raise from `on_notification_error` without
+a record (SM-1696).
+
+Now the worker rescues a `StandardError` from either callback and continues. It writes the failure
+to `logger` at the error level. Without a logger, it writes the failure to standard error. For each
+callback, it writes the first failure. Then it writes at most one failure in each 60 s, with the
+count of the failures that it did not write. It never calls the failed callback for its own failure.
+
+### Workers use the database clock for maintenance
+
+Maintenance writes shared state: the due time of each routine and the retention cutoffs. Before
+this change, the Ruby worker sent its host clock as the maintenance time. If that clock was two days
+fast, other workers skipped a routine until that future time. Retention also deleted a 13-day-old
+schedule occurrence under a 14-day policy (SM-1645).
+
+Now `Worker#run` and `Worker#run_once` bind the text `now`, and PostgreSQL resolves it to its own
+time at the start of the call.
+
+The schema does not change.
+
+### The dashboard names an action that the host does not provide
+
+A dashboard host answers the `enqueueTest` and `setSchedulePaused` procedures only when the
+application gives a handler for them. Before this change, a writable host without that handler
+answered `FORBIDDEN` with the message "This procedure is not available". Now the message is "This
+dashboard host does not provide the <action> action", as in the TypeScript dashboard server. A
+read-only host keeps the message "This dashboard is read-only". The code `FORBIDDEN` and the HTTP
+status 403 do not change (SM-1705).
+
+### A lost notification subscription restarts the poll backoff
+
+A worker without a live subscription waits 250 ms after an empty claim, and doubles that wait
+toward 5,000 ms. Before this change, the empty claims of a live period counted toward that backoff.
+After a loss, a worker that was idle for some time therefore waited the 5,000 ms ceiling at once,
+and a new task waited up to 5 s (SM-1648).
+
+Now the backoff restarts at 250 ms when the subscription is lost. The `subscription-recovery` case
+in `protocol/v1/runtime.json` checks this rule in every SDK.
+
+### A polling-only worker keeps its listener connection for claims
+
+A worker without a `cohorts` option caps its default cohort count by the connections that its pool
+can lend. Before this change, a worker with `polling_only: true` also subtracted a connection for a
+listener that it never opens. With a pool of 4 and concurrency 64, it used 2 cohorts instead of 3
+(SM-1668).
+
+Now a polling-only worker reserves no listener connection. A worker that listens still reserves one,
+and a worker with dedicated heartbeats still reserves one more.
+
+### A handler error with text that jsonb cannot store settles by its retry policy
+
+PostgreSQL `jsonb` cannot store a NUL character or an unpaired surrogate. Before this change, a
+handler error with such text made `fail_v1` refuse the failure envelope. The worker stopped, and the
+task stayed active until lease recovery (SM-1650).
+
+Now `error_envelope` replaces each NUL character and each byte that is not UTF-8 with U+FFFD. It
+does this in the name, the message, and the stack. The JVM and .NET workers use the same rule. The
+retry policy then settles the task. All other text does not change.
+
+The `protocol/v1/failures.json` fixtures pin the rule for every SDK.
+
+### A refused completion settles a due deadline or attempt timeout
+
+A handler can return just before its deadline or attempt timeout, and the completion write can then
+arrive after that boundary. PostgreSQL refuses the completion. Before this change, the worker only
+tried to acknowledge a cancellation, then recorded `lease_expired` and left the task to lease
+recovery. The task then settled up to one lease later with the wrong outcome. Now
+`reconcile_rejected_completion` calls `expire_owned_telemetry_v1` under the attempt's fence before
+the completion path returns. The attempt then ends with the outcome of the due boundary. A
+cancellation request and a lost lease keep their own outcomes (SM-1649).
+
+### Workers on one pool renew their leases in one transaction
+
+On the dedicated heartbeat connection, a round sent one transaction for each worker and each 100
+leases. Each transaction needs at least 3 round trips to PostgreSQL. With 8 workers on one pool and
+80 ms for each round trip, workers lost leases while PostgreSQL still answered (SM-1631). Now the heartbeat thread of the pool sends one transaction for each round, with one `heartbeat_pool_v1` statement for every worker and every 100 leases. The
+transaction locks the task rows of every worker in it until its `COMMIT`. A round renews all of its
+leases or none. The settings statement now sets `statement_timeout` and
+`idle_in_transaction_session_timeout` each to one quarter of the time that remains, not to one half
+and one eighth. The statement needs no schema change. The `shared_heartbeats` opt-out does not change (SM-1633).
+
+### The dashboard sets the tier and the history of a queue
+
+The Rack dashboard answers two new mutations, `setQueueTier` and `setQueueHistory`. `setQueueTier`
+calls `Admin#set_queue_tier` with the authenticated actor and answers `{status: "set", tier}`. If
+Workhorse refuses the switch, the dashboard answers the guard as the status: `live_tasks`,
+`concurrency_policy`, or `rate_limit_policy`. Then `tier` is `null`, and the queue keeps its tier.
+`setQueueHistory` calls `Admin#set_queue_history`. An absent setting keeps its current value. A
+read-only dashboard refuses both mutations (SM-966).
+
+### `Admin` moves a queue between tiers and sets its history
+
+`Admin#set_queue_tier(queue, tier, audit:)` moves a queue to the `:fast` or `:full` tier and returns
+the tier after the change. If the tier differs and the queue holds a live task, the method raises
+`FastTierUnsupportedError`.
+`Admin#set_queue_history(queue, record_attempts: nil, record_claims: nil)` chooses the history a
+fast-tier queue records. A `nil` setting keeps its current value. The method returns a
+`QueueHistory`. The other SDKs already have these controls (SM-1417).
+
+### A worker on a pool of 1 polls under the opt-out
+
+Before this change, a worker with `shared_heartbeats: true` started the shared listener on any pool.
+On a pool of 1, the listener held the only connection. Registration, claims, and handler statements
+then waited for the pool timeout, and no task ran (SM-1585).
+
+Now, with `shared_heartbeats: true`, the worker starts the listener only when the pool `size` is an
+Integer of at least 2. On a pool of 1, or on a pool without a `size`, the worker polls. Each run
+then logs `workhorse.worker.polling_only` once at warn level. The message names
+`workhorse.worker.queues` and `workhorse.worker.pool_max_size`. A worker with `polling_only: true`
+logs no warning. Without the opt-out, nothing changes.
+
+### A contract compares a stored schema number with all its digits
+
+Before this change, the Ruby SDK read a stored contract schema with `JSON.parse`, which reads a
+fraction as a Float. Another SDK can store `"minimum": 0.30000000000000000001`, which a Float cannot
+hold. The Ruby SDK then accepted `0.3`. Now a fraction that a Float cannot hold stays a Rational,
+and the contract keywords compare it exactly (SM-1541, ADR 0039). `ContractSchema.new` still
+accepts only JSON values.
+
+### A worker reserves its heartbeat connection at startup, and refuses to start without it
+
+Before this change, a worker took the heartbeat connection of its pool only when a task arrived,
+and returned it when no task remained. If the pool had no free connection then, the worker still
+claimed tasks. The heartbeat waited for a connection, and the leases of those tasks could expire
+(SM-1577). These changes apply to a worker without `shared_heartbeats: true`:
+
+- **A startup reservation failure now ends the run.** This changes behavior. `run` and `run_once`
+  first reserve the heartbeat connection, then borrow one other connection for the compatibility
+  query and return it at once. Both steps must end within the larger of `heartbeat` and 5 s. This
+  bound includes a connect and the query itself, for every kind of pool. If a step does not end in
+  time, the run raises the new `Stablemates::Workhorse::WorkerStartupError` before the worker
+  registers. Its message names the pool, the budget, and the `shared_heartbeats: true` opt-out. A
+  compatibility query that fails keeps its own error type. Before this change, the same worker started and claimed tasks. A
+  supervisor that restarts a failed process, such as `run_worker_processes`, starts the worker
+  again.
+- **The reservation lasts while a worker runs.** The heartbeat keeps its connection while any worker
+  on the pool runs, also when no task runs. The last worker that stops returns it. Thus a pool keeps
+  one heartbeat connection for its running workers, apart from the short replacement after a lost
+  connection.
+- **No claim without a heartbeat connection.** While the pool has no usable heartbeat connection,
+  the worker claims no task. A claim checks this after it has its connection, immediately before
+  each attempt, and only for its own run. A fast-tier completion then settles its task with a claim
+  limit of 0. A rejected or busy lease does not stop claims. The heartbeat checks its connection
+  between rounds, also when no task runs. If the connection is lost, or a round fails, the heartbeat
+  asks for a new one at once. It waits for a checkout at most one round bound, and at most one
+  heartbeat interval between failed attempts. When the new connection is ready, the worker claims at
+  once.
+- **One shutdown deadline.** `shutdown_grace` now starts when dispatch ends. Every wait of the stop
+  path ends by that deadline or one unwind window later. This includes the registration statements
+  and the release of the listener and the heartbeat connection. Thus a stop takes at most
+  `shutdown_grace` plus the unwind window. A claim that returns after the deadline starts no task,
+  and its leases expire. The heartbeat connection stays reserved until that claim statement
+  settles. A stop during the startup reservation ends the run without an error.
+- **A new run waits for the stop statements of the previous run.** The next `run` or `run_once` of
+  the same worker waits for them within its startup budget. Then a late deregistration cannot
+  delete the registry row of the new run. If a statement still runs when the budget ends, the run
+  raises `WorkerStartupError`. A stop during this wait ends the run without an error.
+
+### Throttle works on a fast-tier queue
+
+Before this change, a throttled enqueue into a fast-tier queue raised the fast-tier error with the feature
+`throttle`. Throttle only decides if Workhorse accepts an enqueue request, so it needs no state of
+the full tier (SM-928, ADR 0077). Migration 0075
+(`0075-allow-throttle-on-fast-tier-queues.sql`) moves the schema to version 74. After it,
+`enqueue_throttle_v1` and `enqueue_many_v1` accept throttle on a fast-tier queue. The outcomes are
+`accepted` and `coalesced`, as on the full tier.
+
+A coalesced request on a fast-tier task writes no `throttled` event, because a fast-tier task
+records only the history that its queue enables. The SDK still emits the throttle log and the
+enqueue outcome metric. In a batch with a debounce or a throttle member, a fast-tier rejection of
+one member now reports the position of that member in the batch. Debounce on a fast-tier queue is
+still rejected.
+
+The migration does not raise the SDK compatibility floor. No SDK statement changes. The migration changes no stored data.
+
+### The retention preview reads through a dashboard function
+
+Before this change, each dashboard host read the retention policy, sent a shared statement that
+counted rows directly in the tables, and capped the counts in its own code. ADR 0040 asks for one
+SQL implementation for each dashboard procedure (SM-1478). Migration 0076
+(`0076-add-the-dashboard-retention-preview-function.sql`) moves the schema to version 75 and adds
+`dashboard_retention_preview_v1`. The Ruby dashboard host now calls it. The `previewRetentionPolicy` response does
+not change.
+
+Every SDK statement catalogue names the new function, so the SDK compatibility floor rises from
+schema 73 to 75. Run `workhorse schema migrate` before the first process of this release starts.
+A 0.9 process keeps working on schema 75. The migration changes no stored data.
+
+### A late worker deregistration cannot delete the row of a later run
+
+Before this change, a worker that stopped sent `deregister_worker_v1`, which deletes the registry
+row by worker ID only. If the stop path was slow and the same worker ID started again, the late
+deregistration could delete the row of the new run and its operator pause state. Each SDK guarded
+against this in its own code (SM-1589). Migration
+0077 (`0077-fence-the-worker-deregistration-by-instance.sql`) moves the schema to version 76 and
+adds `deregister_worker_v2`. It deletes the row only while the row names the instance of the run
+that stops. `deregister_worker_v1` does not change.
+
+`Stablemates::Workhorse::Worker` now calls `deregister_worker_v2` with the instance of the run that
+stops.
+
+Each SDK keeps its guard for this release: a new run still waits for the stop statements of the
+previous run, or it refuses to start. Every SDK statement catalogue names the new function, so the
+SDK compatibility floor rises from schema 75 to 76. Run `workhorse schema migrate` before the first
+process of this release starts. A 0.9 process keeps working on schema 76. The migration changes no
+stored data.
+
 ## 0.9.0 — 2026-10-20
 
 The npm packages, Python distribution, Go module, Rust crate, Ruby gem, and JVM artifacts release from one source commit.

data/README.md

@@ -30,7 +30,7 @@ bundle add connection_pool
 Install the schema once, as a deployment step. The application never installs or migrates it.
 
 ```bash
-npx --package @stablemates/workhorse@0.9.0 workhorse schema install
+npx --package @stablemates/workhorse@0.10.0 workhorse schema install
 ```
 
 The machine that runs that deployment step needs Node.js 22 or newer. The application itself needs

data/lib/stablemates/workhorse/admin.rb

@@ -92,6 +92,9 @@ module Stablemates
 
     ExternalWaitPage = Data.define(:items, :next_cursor)
 
+    # The history a queue records: attempt rows and claim events.
+    QueueHistory = Data.define(:record_attempts, :record_claims)
+
     WorkerPauseResult = Data.define(:worker_id, :paused, :paused_by, :reason, :paused_at, :last_heartbeat_at)
 
     WorkerRegistryEntry = Data.define(
@@ -102,16 +105,18 @@ module Stablemates
     # Inspects and controls tasks, dead letters, workers, and queues through the executor it holds.
     #
     # Like Queue, every call runs on the connection the executor yields, so a control joins the
-    # caller's transaction. Every control takes an AdminAudit that PostgreSQL records.
+    # caller's transaction. Every control except +set_queue_history+ takes an AdminAudit that
+    # PostgreSQL records.
     class Admin
       MAX_PAGE_SIZE = 1000
       MAX_REDRIVE_BATCH_SIZE = 1000
       MAX_PAYLOAD_BYTES = 1_048_576
       MAX_REDACT_KEYS = 50
       TASK_STATES = %i[blocked scheduled ready active succeeded failed canceled].freeze
+      QUEUE_TIERS = %i[fast full].freeze
       REDRIVE_STATUSES = %i[redriven replayed eligible not_found not_failed].freeze
       private_constant :MAX_PAGE_SIZE, :MAX_REDRIVE_BATCH_SIZE, :MAX_PAYLOAD_BYTES, :MAX_REDACT_KEYS,
-        :TASK_STATES, :REDRIVE_STATUSES
+        :TASK_STATES, :QUEUE_TIERS, :REDRIVE_STATUSES
 
       def initialize(executor)
         @executor = Executor.for(executor)
@@ -294,12 +299,14 @@ module Stablemates
 
       def resume_queue(queue, audit:) = set_queue_paused(queue, false, audit)
 
-      # Deletes every pending task in the queue and returns how many tasks it deleted or canceled.
-      # A task that a dependent in another queue waits for is canceled, not deleted.
+      # Deletes the blocked, ready, and scheduled tasks of the queue, and returns how many tasks it
+      # deleted or canceled. If a task outside the purge waits for a purged task, the purge cancels
+      # that task instead of a delete. The rule also applies to a wait through other purged tasks.
+      # The count includes the canceled tasks.
       #
-      # Do not call it in a transaction that already holds task row locks, for example after a
-      # cancel or an enqueue. Two purges run one after the other, so such a transaction can
-      # deadlock with another purge.
+      # Do not call it in a transaction that holds task row locks, for example after a cancel or an
+      # enqueue. Two purges run one after the other, so such a transaction can deadlock with another
+      # purge.
       def purge_queue(queue, audit:)
         name(queue, "queue")
         audit(audit)
@@ -310,6 +317,37 @@ module Stablemates
         Values.parse_integer(rows.first.fetch("deleted_count"))
       end
 
+      # Moves a queue between the +:fast+ and +:full+ tiers and returns the tier after the change.
+      # If the tier differs, Workhorse refuses the change with FastTierUnsupportedError while the
+      # queue holds a live task, so a task never changes tier. The audit's +request_id+ is not recorded.
+      def set_queue_tier(queue, tier, audit:)
+        name(queue, "queue")
+        raise ArgumentError, "tier must be :fast or :full" unless QUEUE_TIERS.include?(tier)
+
+        audit(audit)
+        assert_compatible
+        rows = @executor.rows(SqlCatalogue::SET_QUEUE_TIER, [queue, tier.to_s, audit.actor, audit.reason])
+        raise ArgumentError, "workhorse.set_queue_tier_v1 returned #{rows.length} rows; expected one" unless rows.one?
+
+        rows.first.fetch("tier").to_sym
+      end
+
+      # Chooses the history a fast-tier queue records. A nil setting keeps its current value, and
+      # the QueueHistory reports both settings after the change.
+      def set_queue_history(queue, record_attempts: nil, record_claims: nil)
+        name(queue, "queue")
+        optional_boolean(record_attempts, "record_attempts")
+        optional_boolean(record_claims, "record_claims")
+        assert_compatible
+        rows = @executor.rows(SqlCatalogue::SET_QUEUE_HISTORY,
+          [queue, record_attempts&.to_s, record_claims&.to_s])
+        raise ArgumentError, "workhorse.set_queue_history_v1 returned #{rows.length} rows; expected one" unless rows.one?
+
+        row = rows.first
+        QueueHistory.new(record_attempts: Values.parse_boolean(row.fetch("record_attempts")),
+          record_claims: Values.parse_boolean(row.fetch("record_claims")))
+      end
+
       # The TaskGroup, or nil when no such group exists.
       def get_task_group(group_id)
         group_id = TaskGroups.group_id(group_id)
@@ -412,6 +450,10 @@ module Stablemates
         raise ArgumentError, "#{label} must be a String or nil" unless value.nil? || value.is_a?(String)
       end
 
+      def optional_boolean(value, label)
+        raise ArgumentError, "#{label} must be true, false, or nil" unless [true, false, nil].include?(value)
+      end
+
       def optional_time(value, label) = value.nil? ? nil : Values.timestamp(value, label)
 
       def task_filter(queue, type, states, created_after, created_before)

data/lib/stablemates/workhorse/context.rb

@@ -222,12 +222,15 @@ module Stablemates
       # arrives. +context+ is JSON shown to that person; +timeout+ is a count of seconds.
       def wait_for_human(name, context, timeout: nil)
         external_name(name, "human wait")
-        durable!("human waits")
         timeout_ms = external_timeout(timeout, "human wait")
         Values.check_json(context, "human wait context")
         encoded = canonical_json(context)
+        # PostgreSQL bounds the context with octet_length(context::jsonb::text), which can be
+        # longer than the compact JSON, so the worker measures the same text. The check runs before
+        # the tier lookup, which can read PostgreSQL.
         raise ArgumentError, "human wait context must be at most #{MAX_EXTERNAL_VALUE_BYTES} bytes of JSON" if
-          encoded.bytesize > MAX_EXTERNAL_VALUE_BYTES
+          Values.jsonb_text_bytes(encoded) > MAX_EXTERNAL_VALUE_BYTES
+        durable!("human waits")
 
         once(:wait_for_human, name, encoded) do
           live!(:wait_for_human)

data/lib/stablemates/workhorse/contracts.rb

@@ -122,7 +122,7 @@ module Stablemates
       end
       private_class_method :names?
 
-      def self.number?(value) = value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)
+      def self.number?(value) = value.is_a?(Integer) || value.is_a?(Rational) || (value.is_a?(Float) && value.finite?)
       private_class_method :number?
 
       # A non-negative integer, which JSON may write as 3.0.
@@ -133,6 +133,18 @@ module Stablemates
 
       def initialize(schema)
         Values.check_json(schema, "contract schema")
+        compile(schema)
+      end
+
+      # A schema that +Contracts.parse_schema+ read from PostgreSQL. A Rational in it holds a
+      # fraction that a Float cannot hold. Internal to the SDK.
+      def self.stored(schema) = allocate.tap { |contract| contract.send(:compile, schema) } # :nodoc:
+
+      def valid?(instance) = valid_at?(@schema, instance, 0)
+
+      private
+
+      def compile(schema)
         violation = ContractSchema.profile_violation(schema)
         raise ArgumentError, violation if violation
 
@@ -140,10 +152,6 @@ module Stablemates
         check_references(schema, "$")
       end
 
-      def valid?(instance) = valid_at?(@schema, instance, 0)
-
-      private
-
       # A reference names the root schema or one root definition. The validators behind the six SDKs
       # resolve those two forms alike, and both name a schema position the profile check visited. The
       # check runs before +valid?+, so +valid?+ cannot fail on the schema.
@@ -289,7 +297,8 @@ module Stablemates
 
       # The decimal that JSON writes to PostgreSQL for a number. Float#to_s gives the shortest
       # decimal that reads back as the same Float, so 2**60 as a Float compares as
-      # 1152921504606847000, not as its binary value. A non-finite Float stays a Float.
+      # 1152921504606847000, not as its binary value. A non-finite Float stays a Float. A Rational
+      # from a stored schema is already exact.
       def exact(number) = (number.is_a?(Float) && number.finite?) ? Rational(number.to_s) : number
 
       def finite?(number) = !number.is_a?(Float) || number.finite?
@@ -302,7 +311,7 @@ module Stablemates
         end
         when Array then right.is_a?(Array) && left.size == right.size && left.zip(right).all? { |l, r| equal?(l, r) }
         when true, false, nil then left.equal?(right)
-        when Integer, Float then number?(right) && exact(left) == exact(right)
+        when Integer, Float, Rational then number?(right) && exact(left) == exact(right)
         else left == right
         end
       end
@@ -333,12 +342,12 @@ module Stablemates
       end
 
       def decode(row)
-        schema = Values.parse_json(row.fetch("schema"))
+        schema = parse_schema(row.fetch("schema"))
         raise invalid_definition unless schema.is_a?(Hash) && schema.key?("payload")
 
         PayloadContract.new(
           version: row.fetch("version"),
-          schema: ContractSchema.new(schema["payload"]),
+          schema: ContractSchema.stored(schema["payload"]),
           payload_max_bytes: Values.parse_integer(row.fetch("payload_max_bytes")),
           result_max_bytes: Values.parse_integer(row.fetch("result_max_bytes")),
           payload_redact_keys: Values.parse_text_array(row.fetch("payload_redact_keys")),
@@ -350,6 +359,22 @@ module Stablemates
 
       def invalid_definition = Error.new("invalid contract definition returned by PostgreSQL")
 
+      # The jsonb text of a stored schema document. jsonb keeps every digit of a number that another
+      # SDK synchronized. A fraction that a Float cannot hold stays a Rational, so the contract
+      # compares it exactly.
+      def parse_schema(text) = text.nil? ? nil : exact_numbers(JSON.parse(text, decimal_class: Rational))
+
+      def exact_numbers(value)
+        case value
+        when Rational
+          float = value.to_f
+          (float.finite? && Rational(float.to_s) == value) ? float : value
+        when Array then value.map { |item| exact_numbers(item) }
+        when Hash then value.transform_values { |item| exact_numbers(item) }
+        else value
+        end
+      end
+
       # Compiles every schema, then renders the +sync_contract_definitions_v1+ document.
       def document(contracts)
         raise ArgumentError, "contracts must be a Hash of task type to TaskTypeContracts" unless contracts.is_a?(Hash)