stablemates-workhorse 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 807d43f9b16d79430d292a3e6c70acdc55bb8cc3f2010b7e03f0356fb0731c90
-  data.tar.gz: f84ab68d2d6d03450983e74dc337880546815472ece79d8cdf1d650679d3912a
+  metadata.gz: 35dc8eaadac2ae86c30ad3cf2a688ffe571b7c7a8cd564ee00844685fbeb4ea6
+  data.tar.gz: 34dfeb5010846d31ea3f7b5751e14bf7ec4ed4783a9223d4e2f483534b419669
 SHA512:
-  metadata.gz: 706d9cfd755c1bc971116245009433dba6d4880dc7b7dec081f486d95f5395395a69b55527527b33252f4cf4bbc5e1a1b94c74ad91b267fe6893884c3bdb09ef
-  data.tar.gz: dd7e13f971e790cc10c4f07843a4b7ec9f086f32365c665f681206bf1376d1d7d03bf11e6dfa78aacc75ea8cb2ce292da3246b9471431d7fa6b1630c58c46a17
+  metadata.gz: 99884c5d12e4501d537c66272a668be206f796ef0f8ac7663d863898caa3f0e4a530af7a79902d81983e671b76f146bc3e54f529a7cf7d6170d44ecaadc96d5f
+  data.tar.gz: dee85878fb8e6862120d5863d8b4cd34cdd18d6e4281e1e5976f9215af12dc0c2b58aef3090e3b42e439868fe367d63f515e66a8968a73d33903c626cb5247c4

data/CHANGELOG.md

@@ -3,6 +3,498 @@
 `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.
+
+Requires **schema v73**, 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 0073 and 0074 move the schema to version
+**73**. The SDK compatibility floor rises from 69 to **73**, because every SDK statement catalogue
+now names `heartbeat_many_v2` and `heartbeat_v2`. An updated process refuses a schema below version
+73 at startup. A 0.8 process keeps working on version 73, because a migration inside a major line
+only adds.
+
+### Heartbeats do not wait for a locked task row
+
+Before this release, a heartbeat waited for a task row that another transaction locked. If a
+settlement held the row, the heartbeat then kept the row locked after the settlement committed, and
+a claim skipped the ready task (SM-1434). The worker now renews leases through `heartbeat_many_v2`
+(SM-1443, ADR 0105). It skips a locked row and reports that lease as `busy`: no renewal and no
+ownership verdict. The worker keeps a busy lease, retries only the busy leases after a short delay
+with jitter, and does not move the regular heartbeat schedule. A busy answer never extends the local
+lease watchdog, so a lease that stays busy until the watchdog ends is lost, as before. Old and new
+workers can run together: an old worker keeps calling `heartbeat_many_v1`, which does not change.
+
+**One-lease heartbeat without a row lock wait.** Migration 0074 adds `heartbeat_v2` (SM-1461). It
+renews one lease by the rule of `heartbeat_many_v2`, so it reports a locked row as `busy`. This SDK
+names it in its statement catalogue but does not call it. `heartbeat_v1` does not change.
+
+### Heartbeat rounds keep a renewal margin and end on the server
+
+Before this release, the dedicated heartbeat connection bounded each heartbeat statement by one full
+interval. After a failed round, the heartbeat thread started a new schedule on its new connection.
+With the defaults, one timed-out round thus left about 0 s before the lease watchdog expired
+(SM-1444). Also, when the worker stopped waiting for a round, PostgreSQL continued to run the
+heartbeat statement, and that statement kept its row locks (SM-1442). These changes apply to each
+round on the dedicated heartbeat connection:
+
+- **Rounds start on a fixed schedule.** A round falls due one interval after the previous round
+  started, not after it ended. The schedule uses a monotonic clock. If a round ends after its next
+  slot, the worker starts one overdue round at once and sends no round for the other missed slots.
+- **The round bound is shorter.** A round ends by
+  `max(1 ms, interval × 3 / 4, min(50 ms, interval))`. For an interval of 200 ms or more, this is
+  three quarters of the interval. With the defaults (lease 30 s, interval 10 s), the bound is 7.5 s,
+  so one timed-out round leaves a margin of 2.5 s. An attempt keeps its lease after one timed-out
+  round if `2 × interval + round bound < lease`. The worker does not reject an interval that breaks
+  this rule. Before this release, each statement of a round had its own bound of one interval. Now
+  all statements of one round share one deadline, and a statement that would start after it waits
+  for the next round. Each round starts with the next statement in turn, so a statement that is
+  always slow cannot keep a later statement from its turn.
+- **Each round sets server timeouts.** The round sends `BEGIN`, then one `set_config` statement for
+  `statement_timeout` and `idle_in_transaction_session_timeout`, then `heartbeat_many_v2`, then
+  `COMMIT`. Both settings are transaction-local. The heartbeat statement gets one half of the time
+  that remains, and each idle gap one eighth. If less than 8 ms remains at the settings statement,
+  the round fails before the heartbeat. The worker counts a renewal only after a `COMMIT` that ends
+  before the deadline. No setting bounds `COMMIT` on PostgreSQL 15 and later.
+- **A failed round discards its connection only when a statement may still run** (SM-1492). A
+  round that expires before it sends the heartbeat statement rolls back and keeps its connection.
+  Under load, PostgreSQL can log
+  `canceling statement due to statement timeout` for a heartbeat statement. It can also end the
+  session with `terminating connection due to idle-in-transaction timeout`. Each message means that
+  one round failed. Every task continues, and the next round tries again. A deadlock (`40P01`) also
+  fails the round.
+- **A busy retry with less than 20 ms left sends nothing** (SM-1492). A bounded busy retry runs
+  only if its deadline is at least 20 ms after its start: the 8 ms that a round needs at its
+  settings statement, plus a 12 ms margin. Otherwise the next regular round renews the busy leases.
+- **Replacement connections.** The heartbeat thread keeps the start of the latest round when it
+  replaces a failed connection.
+- **100 ms is the smallest supported heartbeat interval** (SM-1471). This applies to `heartbeat:` of
+  `Worker`, in seconds: the smallest supported value is 0.1. At 100 ms, the round bound is 75 ms.
+  The worker still accepts a shorter interval, and it does not warn. On a loaded host, a shorter
+  interval can make each round miss its deadline, and attempts can then lose their leases.
+
+Rounds under `shared_heartbeats: true` have no client deadline and set no server timeouts, as
+before. They follow the new schedule. The [heartbeat round
+deadline](../docs/architecture/lifecycle.md#heartbeat-round-deadline) and the [heartbeat
+schedule](../docs/architecture/lifecycle.md#heartbeat-schedule) state each rule.
+
+### A payload contract compares the decimals of numbers
+
+Before this release, `ContractSchema` compared an Integer with the binary value of a Float in the
+bound keywords, `const`, `enum`, and `uniqueItems` (SM-1539). Thus `1152921504606846980` failed
+`{"maximum": 1.152921504606847e18}`, although PostgreSQL stores the constant as
+`1152921504606847000`. A contract now compares each Float through the decimal of `Float#to_s`
+(ADR 0039). Ruby still reads a stored schema constant that a double cannot hold as a Float
+(SM-1541).
+
+### A bad worker interval raises ArgumentError
+
+Before this release, a bad value for `heartbeat`, `poll_interval`, `maintenance_interval`,
+`maintenance_routine_interval`, or `registry_interval` raised `NoMethodError`, because these options
+have no upper limit (SM-1511). For example, `heartbeat: 0` did this. Now `Worker.new` raises
+`ArgumentError`, and the message names the option and its lower limit.
+
+### The `workhorse.tasks.retried` description matches `api/telemetry.txt`
+
+The Ruby worker now describes `workhorse.tasks.retried` as "Failed or expired tasks returned to live
+work", as the contract does (SM-1514). The counter already counted expired tasks. Only the
+description changes.
+
+### A wrapped durable replay conflict is terminal
+
+Before this release, the Ruby worker checked only the outermost error for a durable replay conflict
+(ADR 0098). If a handler wrapped a conflict in its own error, the worker recorded a retryable
+failure, and the conflict repeated until `max_attempts` (SM-1512). The worker now follows the cause
+chain of the error, as the Go and Rust workers do. It reads at most 16 errors, so a cyclic chain
+cannot stop it. It reads `Exception#cause`, so an error raised in a `rescue` block also counts. A
+wrapped conflict fails the task at once. The failure envelope records the name of the conflict. Its
+fields `message` and `stack` stay those of the outer error.
+
+### A heartbeat round sends at most 100 leases in each statement
+
+`heartbeat_many_v2` accepts at most 100 leases. A fused completion claim registers its tasks before
+the completing attempts unregister, so a round can hold more leases than the concurrency limit. That
+round raised an error, and no lease in it renewed (SM-1495). The worker now splits a round into
+statements of at most 100 leases. Each statement counts on its own. A failed statement renews none
+of its leases, and the statements before it still count, as before for the statements of each
+worker.
+
 ## 0.8.0 — 2026-10-13
 
 The npm packages, Python distribution, Go module, Rust crate, and Ruby gem release from one source commit.

data/README.md

@@ -3,6 +3,13 @@
 The Ruby queue client, operator client, and worker runtime for the Workhorse durable task queue for
 PostgreSQL.
 
+<picture>
+  <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="https://workhorse.run/diagrams/readme-overview-narrow-dark.png">
+  <source media="(max-width: 600px)" srcset="https://workhorse.run/diagrams/readme-overview-narrow-light.png">
+  <source media="(prefers-color-scheme: dark)" srcset="https://workhorse.run/diagrams/readme-overview-dark.png">
+  <img src="https://workhorse.run/diagrams/readme-overview-light.png" width="960" alt="One protocol for your workers and your dashboard">
+</picture>
+
 > **Public beta:** Workhorse is usable for evaluation and early production adoption. A 0.x minor
 > release may change behaviour, so read the
 > [changelog](https://github.com/stablemates/workhorse/blob/main/ruby/CHANGELOG.md) before you
@@ -23,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.8.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)