wurk 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3249733631f049cf81a41880d6355512889dd963fa9e3c159610d27b1c52bd2
-  data.tar.gz: a5db03ee0bdbf32d765ba439b4aa0e3fbb5d55cfcd8b58471375a62bf2b3367b
+  metadata.gz: e5540591682172d88b9972b1cfc33cfca88c9c88d823c0b50fe80cb3556e8c08
+  data.tar.gz: a19e9d8e68fd2f9f93131cfad4f845595bc95f45aacb65047da452da52916cdd
 SHA512:
-  metadata.gz: 304f23c4742924dc22a9a3d9cdc0c7c28cbcdf089c6e5d5dd485adc858bc81d239fc501687e378b026e0c42e6be9675ce960c7f8b27007e35925a04f133961f0
-  data.tar.gz: 1fd8a666fa1d02940c4f36d1e49c7c69fad64783f7f52433543cf3bfba77340de2964202ac91224f03cb66b32babc32849fe81694e98ea173023245eda98fc95
+  metadata.gz: 0d264b8039051e56d2f6cec5aaebb4ce1f99d62ad498a247bece1b6464c316685f43562a76c87ec46f31e846ff6cb6d536f51a11b6d9d06348c32c999d4f2be5
+  data.tar.gz: 9f695bfc7da4e5ad9e24e6874431a115b80bf3dab52f175a11b8f383d0586694b2d611f3137b6698eb896c1c2107ef18e97d33b7877a1a4fd3af60f380f0f47a

data/README.md

@@ -24,13 +24,13 @@ Wurk is wire-compatible with Sidekiq — same Redis keys, same job JSON, same Ru
 
 **In production:** Wurk runs the background work at [developerz.ai](https://developerz.ai) and at partner deployments, across many servers, on the fork-based swarm described below. It is not a preview. Throughput numbers from those deployments are not published yet; what has been measured is in [docs/benchmarks.md](docs/benchmarks.md).
 
-**At scale:** Wurk is built for fleets, not just for one box. Kubernetes `/live` + `/ready` probes are a config line, not a sidecar; a bearer-scoped [HTTP API](docs/api-http.md) lets non-Ruby services enqueue and inspect; [OpenTelemetry](docs/telemetry.md) traces propagate client → server; per-queue [global concurrency caps](docs/rate-limiting.md) hold cluster-wide limits; and monitoring is the dashboard you already mount — live SSE, charts, per-job progress, no separate stack to run. See [Wurk extras](#wurk-extras).
+**At scale:** Wurk is built for fleets, not just for one box. Kubernetes `/live` + `/ready` probes are a config line, not a sidecar; a bearer-scoped [HTTP API](docs/api-http.md) lets non-Ruby services enqueue and inspect; [OpenTelemetry](docs/telemetry.md) traces propagate client → server; per-queue [global concurrency caps](docs/rate-limiting.md) hold cluster-wide limits; and monitoring is the dashboard you already mount — live SSE, charts, no separate stack to run. See [Wurk extras](#wurk-extras).
 
-**AI-managed:** Wurk is a 100% AI-managed project. Outside contributors' issues and pull requests, and dependency updates, are triaged, reviewed, merged or closed by the [developerz.ai](https://developerz.ai) maintainer agent, which asks a human only for security reports, license questions and breaking changes, and cuts a release when a shipped fix has waited for one. New features are still built by us, humans and AI together — see [CONTRIBUTING.md](CONTRIBUTING.md) and [AI-maintained](#ai-maintained).
+**AI-managed:** Wurk is a 100% AI-managed project. Every author's issues and pull requests, org members' included, and dependency updates, are triaged, reviewed, merged or closed by the [developerz.ai](https://developerz.ai) maintainer agent, which asks a human only for security reports and license questions, and cuts a release when a shipped fix has waited for one. New features are still built by us, humans and AI together — see [CONTRIBUTING.md](CONTRIBUTING.md) and [AI-maintained](#ai-maintained). The agent always identifies itself as a bot: it works publicly as `developerz-ai[bot]` and marks every comment it posts as bot-made. Its work and its rules are public too — browse the [repository](https://github.com/developerz-ai/wurk) and read the committed policy in [.dz/maintainer/maintainer.yml](.dz/maintainer/maintainer.yml).
 
 **On Sidekiq:** Wurk implements Sidekiq's API because it is a genuinely good API. Sidekiq is human-maintained and funds that work through its paid tiers; Wurk is AI-maintained, which is what lets the same surface be free software. Wurk is independent and not affiliated with or endorsed by Sidekiq or its maintainers — see [Why Wurk exists](#why-wurk-exists).
 
-**On speed:** Wurk is not currently faster than stock Sidekiq — it runs at roughly 0.87×–1.02× depending on workload shape, with parity on CPU and I/O but still behind on framework overhead (noop) and boot time. Numbers, method, and the reproduction command are in [docs/benchmarks.md](docs/benchmarks.md); run them yourself with `rake bench:vs_sidekiq`.
+**On speed:** The latest published paired measurement (2026-08-07) put Wurk at roughly 0.87×–1.02× of stock Sidekiq depending on workload shape: parity on CPU and I/O, behind on framework overhead (noop) and boot time. This is dated evidence, not a throughput guarantee for today's gem. Numbers, method, and the reproduction command are in [docs/benchmarks.md](docs/benchmarks.md); run them yourself with `rake bench:vs_sidekiq`.
 
 **Also from us:** [Ultimate](https://github.com/developerz-ai/ultimate) — the AI-first full-stack framework, for a weekend pet project or the system a company runs on. What a whole stack looks like when the one writing the code is an agent, not a human: [`bunx create-ultimate myapp`](#also-from-developerzai-ultimate).
 
@@ -98,7 +98,7 @@ Sidekiq has no equivalent for any of these — they aren't parity, they're new s
 
 | Extra | What it does | Give up if you migrate back to Sidekiq |
 |---|---|---|
-| **[Job status, progress & results](docs/job-status.md)** | Opt-in `sidekiq_options track: true` persists a `status:<jid>` row — state, coalesced progress writes, the return value (size-capped, withheld under encryption) | `Wurk::Status` reads/writes and the dashboard's per-job progress bar |
+| **[Job status, progress & results](docs/job-status.md)** | Opt-in `sidekiq_options track: true` persists a `status:<jid>` row — state, coalesced progress writes, the return value (size-capped, withheld under encryption) | `Wurk::Status` reads/writes and the `/v1` API's job-status reader (`GET /jobs/:jid`) |
 | **[HTTP producer + observe API](docs/api-http.md)** | A bearer-token-scoped `/v1` JSON API — enqueue, bulk-enqueue, inspect queues/jobs/swarm — mountable standalone, nested in the engine, or via the `wurk api` CLI | The whole `/v1` surface; non-Ruby producers lose their enqueue/inspect path |
 | **[OpenTelemetry tracing](docs/telemetry.md)** | W3C `traceparent`/`tracestate` propagated client → server, one span per attempt, linked (not force-parented) across long delays | Distributed traces across your job graph |
 | **[Flows — DAG-on-batches](docs/flows.md)** | `Wurk::Flow` chains and fans batches out/in with dependency edges, piped results between nodes, cycle/depth/width limits | The DAG builder, `pipe:` result-passing, `Flow.abandon` |
@@ -113,7 +113,7 @@ AI dashboard panes — anomaly detection, natural-language queries, error triage
 
 ## Benchmarks
 
-**Wurk is not faster than stock Sidekiq today.** Here is where it actually stands, measured rather than claimed — wurk 1.5.0 vs sidekiq 8.1.6, ruby 3.4.7, local Redis 7.4.10, 5000 jobs/run, 12 runs per topology, paired per-run ratios.
+**The latest published comparison does not show Wurk ahead of stock Sidekiq.** Measured 2026-08-07 — wurk 1.4.0 vs sidekiq 8.1.6, ruby 3.4.7, local Redis 7.4.10, 5000 jobs/run, 12 runs per topology, paired per-run ratios. These are historical results, not a fresh measurement of today's gem.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/assets/bench-throughput-dark.svg">
@@ -134,8 +134,8 @@ Method, per-invocation records, workload definitions, and the separate `rake ben
 ## Documentation
 
 - **[Website](https://developerz-ai.github.io/wurk/)** · **[Wiki](https://github.com/developerz-ai/wurk/wiki)** — the pitch, install, and short orientation guides; the complete reference is [`docs/`](https://github.com/developerz-ai/wurk/tree/main/docs), linked from every wiki page.
-- **[API reference (YARD)](https://developerz-ai.github.io/wurk/api/)** — generated docs for the public classes (`Wurk::Worker`, `Wurk::Client`, `Wurk::Configuration`, `Wurk::Batch`, `Wurk::Limiter`, `Wurk::Unique`, and the `Sidekiq::*` aliases). Machine-readable map for AI agents: **[llms.txt](https://developerz-ai.github.io/wurk/llms.txt)**.
-- **[Getting started & architecture](https://github.com/developerz-ai/wurk/blob/main/docs/idea/01-overview.md)** — how the swarm, manager, fetcher, and processor fit together.
+- **[API reference (YARD)](https://developerz-ai.github.io/wurk/api/)** — generated from all of `lib/` (per `.yardopts`), so it documents internal classes (`Wurk::Manager`, `Wurk::Fetcher`, `Wurk::Processor`, `Wurk::Swarm`, the `Wurk::API::*` modules, …) as well as public ones; appearing in it does not make something supported public API. The supported public surface is defined by the parity specs ([`docs/target/sidekiq-free.md`](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-free.md) · [Pro](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-pro.md) · [Enterprise](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-ent.md)). Machine-readable map for AI agents: **[llms.txt](https://developerz-ai.github.io/wurk/llms.txt)**.
+- **[Getting started & architecture](https://github.com/developerz-ai/wurk/blob/main/docs/idea/02-architecture.md)** — how the swarm, manager, fetcher, and processor fit together.
 - **[Starting the worker](https://github.com/developerz-ai/wurk/blob/main/docs/running.md)** — Rails auto-start, the `wurk`/`wurkswarm` runners, and running standalone without Rails.
 - **[Configuration reference](https://github.com/developerz-ai/wurk/blob/main/docs/configuration.md)** — every option, env var, YAML key, and CLI flag, with precedence and pool sizing.
 - **[Deploying](https://github.com/developerz-ai/wurk/blob/main/docs/deployment.md)** — systemd, Capistrano, Heroku, Docker, Kubernetes, rolling restarts, memory limits.
@@ -165,6 +165,8 @@ Method, per-invocation records, workload definitions, and the separate `rake ben
 | Ruby | `>= 3.2.0` |
 | Redis | `>= 7.0.0` |
 
+The full test suite also runs as a non-required `compat` workflow job across Ruby 3.2.x and the newest Ruby on the current Rails series, the oldest supported Rails series on the newest Ruby, and Valkey 8 as a drop-in store alongside Redis 7.x.
+
 JRuby, TruffleRuby, and Windows fall back to threads-only mode (no fork) — behaviorally equivalent to stock Sidekiq.
 
 ## Running the workers
@@ -279,16 +281,16 @@ There is no native Prometheus `/metrics` endpoint — the StatsD export or the `
 
 Infrastructure this basic should be free software. A Rails app shouldn't need a licence key to get reliable fetch, batches, rate limiting, or cron — those are table stakes, not a premium tier, and the free-software tradition is that the best tools belong to everyone who runs them.
 
-What has made that hard is maintenance: someone has to be paid to do it. Sidekiq funds a decade of *human* maintenance through its paid tiers, which is an honest trade. Wurk makes a different one — it is maintained **by AI**: outside contributors' issues and pull requests, and dependency updates, are handled end to end by a maintainer agent (the team's own are left to them, their pull requests still reviewed), and the implementation, parity suite, docs, and benchmarks are written and kept current by AI agents working with the team, which still builds the features and cuts the releases. A fix, a doc update, or a version bump is no longer somebody's week, which is what makes it practical to:
+What has made that hard is maintenance: someone has to be paid to do it. Sidekiq funds a decade of *human* maintenance through its paid tiers, which is an honest trade. Wurk makes a different one — it is maintained **by AI**: every author's issues and pull requests, the team's own included, and dependency updates, are handled end to end by a maintainer agent, and the implementation, parity suite, docs, and benchmarks are written and kept current by AI agents working with the team, which still builds the features and cuts the releases. A fix, a doc update, or a version bump is no longer somebody's week, which is what makes it practical to:
 
 - ship the entire Pro + Enterprise surface with no tier, no flag gate, and no license check;
 - keep parity honest mechanically rather than by hand — an independently written parity oracle suite, pinned to a documented Sidekiq revision, plus sidekiq-cron's upstream suite running against Wurk on every push ([docs/idea/14-ecosystem-compat.md](https://github.com/developerz-ai/wurk/blob/main/docs/idea/14-ecosystem-compat.md) tracks the rest);
 - keep adding surface Sidekiq doesn't have — the [Wurk extras](#wurk-extras) above landed as one release;
-- hold ourselves to published numbers instead of adjectives — the suite runs against stock Sidekiq every release and ships the results [as measured](docs/benchmarks.md), including the unflattering ones.
+- hold ourselves to published numbers instead of adjectives — the measured comparison against stock Sidekiq is published [as measured](docs/benchmarks.md), including the unflattering ones, and `rake bench:vs_sidekiq` reproduces it. It is a published measurement, not a per-release CI run.
 
 DHH makes the broader version of this argument in [Let the agents democratize open source](https://world.hey.com/dhh/let-the-agents-democratize-open-source-9fd630a9): open source fought for everyone's right to change the software they run, and refusing agent-written code re-erects the gate it spent decades tearing down — "all programmers are equal, but some programmers are more equal than others." His subject is contributions; ours is maintenance, which is the same economics from the other end. The reason a licence key guards batches and cron is not that the code is precious, it's that somebody had to be paid to keep it working. Drop that cost and the tier stops being necessary.
 
-What makes it work in practice is that the agents run inside machinery built to check them. The oracles, upstream suites, and published numbers above are gates, not decoration, and the release gate has never once let an unverified gem reach RubyGems. Agents supply the pace, the gates supply the certainty — and when a gate does catch something, the fix is to make that class of mistake structurally impossible rather than to slow the agents down. The release lane derives its own tag from `Wurk::VERSION` so the two can't drift apart; [RELEASE.md](https://github.com/developerz-ai/wurk/blob/main/RELEASE.md) walks through it.
+What makes it work in practice is that the agents run inside machinery built to check them. The parity oracle above is a merge-blocking gate, not decoration; sidekiq-cron's upstream suite runs against Wurk in CI and reports on PRs, but it is not a required check and never gates a merge; the `rake bench` PR regression check flags deltas past a noise-adjusted threshold as an advisory comment; and the published benchmark numbers are one-off historical measurements, reproduced on demand rather than enforced in CI. The release gate has never once let an unverified gem reach RubyGems. Agents supply the pace, the gates supply the certainty — and when a gate does catch something, the fix is to make that class of mistake structurally impossible rather than to slow the agents down. The release lane derives its own tag from `Wurk::VERSION` so the two can't drift apart; [RELEASE.md](https://github.com/developerz-ai/wurk/blob/main/RELEASE.md) walks through it.
 
 Wurk is MIT and stays that way. If what you need is a commercial support contract and a human on the other end of an email, buying that is a perfectly good answer.
 
@@ -321,16 +323,16 @@ TypeScript end to end, MIT, and as measured about its own claims as this file is
 
 ## AI-maintained
 
-**Wurk is maintained by AI**: by [developerz.ai](https://developerz.ai), the way a human maintainer looks after an open-source project. The developerz-ai org comes back with new ideas once or twice a year. In between, the project is still looked after:
+**Wurk is fully maintained by AI**: by [developerz.ai](https://developerz.ai), the way a human maintainer looks after an open-source project, for every author, org members included (owner ruling, 2026-10-23). The developerz-ai org comes back with new ideas once or twice a year. In between, the project is still looked after:
 
 | Who opens it | What happens |
 |---|---|
 | you, an issue | triaged; asked for a reproduction when one is missing; a real bug is fixed and released |
 | you, a pull request | reviewed (CodeRabbit and the developerz.ai reviewer), driven to green, merged |
 | Dependabot | driven to green and merged |
-| an issue or pull request by anyone with write access (org members, collaborators) | left to its author; a pull request is still reviewed, and an @-mention of the bot is answered |
+| an issue or pull request by anyone with write access (org members, collaborators) | handled like anyone's: triaged, reviewed, driven to green, merged |
 | an outside change to CI, release or publish automation | declined: members maintain the pipeline that publishes the gem |
-| a breaking change | never merged unattended: the drop-in contract is the one promise a revert cannot take back |
+| a breaking change | the bot's call, not a human's; a change that breaks the drop-in Sidekiq contract is declined, since a revert cannot take that promise back |
 
 Releases follow the work, not a calendar. A weekday checkup asks whether a shipping fix has merged and nobody has released it. When one has, the bot files a release request, its coding fleet opens the `Wurk::VERSION` bump PR, and merging that PR publishes the gem ([RELEASE.md](RELEASE.md)). The bot's policy is committed in [`.dz/maintainer/maintainer.yml`](.dz/maintainer/maintainer.yml).
 

data/app/controllers/wurk/api_controller.rb

@@ -238,11 +238,23 @@ module Wurk
       render json: { lid: params[:lid].to_s, history: ::Wurk::Web::Enterprise::Periodic.history(params[:lid].to_s) }
     end
 
+    # `?minutes=` (default 60) is served raw — the Query layer routes ≤480 to
+    # per-minute buckets and >480 onto the 10-minute buckets, raising
+    # WindowTooWide (400 below) past the 30-day ceiling; a non-positive window
+    # raises ArgumentError there and 400s the same way. `?hours=` is clamped
+    # to MAX_HOURS (default 24 when present) and always takes the 10-minute
+    # path. The response echoes the REQUESTED window so the SPA's label
+    # matches the served period.
     def metrics
-      minutes = ::Wurk::Api::Pagination.clamp_int(params[:minutes], 1, ::Wurk::Metrics::Query::MAX_MINUTES, 60)
-      rows = ::Wurk::Web::Enterprise::Historical.top(minutes: minutes, class_filter: params[:substr])
-      render json: { minutes: minutes, top_jobs: rows.map { |(klass, totals)| ::Wurk::Api::Serializers.metric_row(klass, totals) } }
-    rescue ::Wurk::Metrics::Query::WindowTooWide => e
+      minutes, hours = metrics_window_raw(params)
+      rows = ::Wurk::Web::Enterprise::Historical.top(minutes: minutes, hours: hours, class_filter: params[:substr])
+      payload = { minutes: hours ? hours * 60 : minutes,
+                  top_jobs: rows.map { |(klass, totals)| ::Wurk::Api::Serializers.metric_row(klass, totals) } }
+      # hours is echoed only when the request used it, so a minutes request
+      # keeps the two-key shape (minutes + top_jobs) it has always had.
+      payload[:hours] = hours if hours
+      render json: payload
+    rescue ::ArgumentError, ::Wurk::Metrics::Query::WindowTooWide => e
       render json: { error: e.message }, status: :bad_request
     end
 
@@ -387,8 +399,10 @@ module Wurk
 
       keys = Array(params[:keys]).map(&:to_s).uniq
       # Each key costs a ZRANGEBYSCORE plus per-entry mutations; an uncapped
-      # list lets one POST issue tens of thousands of round-trips. The UI
-      # selects at most a page (200).
+      # list lets one POST issue tens of thousands of round-trips. The UI's
+      # per-row selections accumulate across pages (toggleAll works against
+      # the visible page's keys only) and the bulk POST sends the whole Set,
+      # so this cap — not the page size — is the bound.
       return render(json: { error: 'too many keys (max 1000)' }, status: :bad_request) if keys.size > 1000
 
       entries = entries_for(set, keys)
@@ -515,12 +529,37 @@ module Wurk
       Integer(match[1]) * HISTORY_WINDOW_UNITS.fetch(match[2].empty? ? 's' : match[2])
     end
 
+    # `?hours=` wins over `?minutes=`; minutes > MAX_MINUTES (480) promote onto
+    # the 10-minute buckets in the Query layer, so the clamp ceiling is the
+    # 30-day equivalent (MAX_HOURS * 60 minutes), not 480. Absent both, the
+    # window defaults to 60 minutes.
     def metrics_window(params)
       pagination = ::Wurk::Api::Pagination
-      minutes = pagination.clamp_int(params[:minutes], 1, ::Wurk::Metrics::Query::MAX_MINUTES, 60) if params[:minutes]
-      hours   = pagination.clamp_int(params[:hours],   1, ::Wurk::Metrics::Query::MAX_HOURS,   24) if params[:hours]
-      minutes ||= 60 if hours.nil?
-      [minutes, hours]
+      max_hours = ::Wurk::Metrics::Query::MAX_HOURS
+      if params[:hours]
+        [nil, pagination.clamp_int(params[:hours], 1, max_hours, 24)]
+      else
+        [pagination.clamp_int(params[:minutes], 1, max_hours * 60, 60), nil]
+      end
+    end
+
+    # #metrics variant: `?minutes=` goes through raw so a window past the
+    # 30-day ceiling (MAX_HOURS * 60) reaches the Query layer and raises
+    # WindowTooWide — the endpoint answers 400 rather than silently serving
+    # a shorter window than the SPA's label claims. Unparseable values fall
+    # back to the 60-minute default; `?hours=` is clamped as above.
+    def metrics_window_raw(params)
+      pagination = ::Wurk::Api::Pagination
+      max_hours = ::Wurk::Metrics::Query::MAX_HOURS
+      if params[:hours]
+        [nil, pagination.clamp_int(params[:hours], 1, max_hours, 24)]
+      elsif params[:minutes]
+        [Integer(params[:minutes], 10), nil]
+      else
+        [60, nil]
+      end
+    rescue ::ArgumentError, ::TypeError
+      [60, nil]
     end
   end
 end

data/config/routes.rb

@@ -16,7 +16,7 @@ Wurk::Engine.routes.draw do
     post 'queues/:name/pause',   to: 'api#pause_queue',   as: :api_pause_queue,   constraints: { name: %r{[^/]+} }
     post 'queues/:name/unpause', to: 'api#unpause_queue', as: :api_unpause_queue, constraints: { name: %r{[^/]+} }
 
-    # Job-set mutations (retry/delete/kill/requeue/clear). The SPA posts to
+    # Job-set mutations (retry/delete/kill/add_to_queue/clear). The SPA posts to
     # these; the Authorization middleware 403s every non-GET in read-only mode,
     # so they need no extra guard. `:key` is "<score>|<jid>" (Wurk::SortedEntry#id);
     # `all/:cmd` operates over the whole set; the bare collection POST is a bulk
@@ -50,10 +50,10 @@ Wurk::Engine.routes.draw do
     post 'dead/:key',        to: 'api#dead_job',       as: :api_dead_job, constraints: { key: %r{[^/]+} }
     get  'processes',        to: 'api#processes'
     get  'workers',          to: 'api#workers'
-    # Busy-page process control (quiet/stop). `identity` rides in the body (it
-    # contains ':' and '.', awkward as a path segment); absent or "all" signals
-    # every live process. Read-only mode 403s these via the Authorization
-    # middleware. Spec: docs/target/sidekiq-free.md §25.4 (POST /busy).
+    # Wurk uses split POST /api/busy/quiet and /api/busy/stop requests, not free
+    # spec §25.4 POST /busy with identity/quiet/stop params. Request-shape parity
+    # is unsupported; see docs/idea/parity-divergences.md#busy-control-http-request-shape-parity-is-unsupported.
+    # Read-only mode 403s these via the Authorization middleware.
     post 'busy/quiet', to: 'api#quiet_process', as: :api_quiet_process
     post 'busy/stop',  to: 'api#stop_process',  as: :api_stop_process
     # Flows (Wurk::Flow) read the way the batches below them do — a paged index
@@ -96,13 +96,21 @@ Wurk::Engine.routes.draw do
   # version reaches the app and comes back as the same `unsupported_api_version`
   # problem document the other two mounts answer with.
   #
-  # Nested here it also inherits the engine's middleware — the host's
-  # `Wurk::Web.use` chain and the read-only gate — so a dashboard behind Devise
-  # keeps gating this path too. A machine client that cannot pass a browser
-  # login wants mode 2 instead: `mount Wurk::API => '/wurk-api'` in the host's
-  # own routes, declared BEFORE the engine when its path extends the engine's —
-  # Rails matches a mounted app by bare string prefix, so `mount Wurk::Engine =>
-  # '/wurk'` declared first swallows every `/wurk-api/...` request.
+  # Nested here it also inherits both engine middlewares — the host's
+  # `Wurk::Web.use` chain, then `Wurk::Web::Authorization`
+  # (lib/wurk/engine.rb) — so a dashboard behind Devise keeps gating this path
+  # too. The `Wurk::Web.configure` authorization hook (403 on falsey,
+  # sidekiq-ent §9.2) and the read-only gate both live in Authorization, and
+  # the hook runs before the machine-API handoff (lib/wurk/web/config.rb):
+  # the host hook gates `/v1` paths too, and a valid machine bearer token does
+  # NOT bypass it — bearer auth lives only inside `Wurk::API::App#handle`
+  # (lib/wurk/api/app.rb), downstream of both middlewares, so a session-bound
+  # hook (`env['warden']&.user`) 403s before the token is ever consulted. A
+  # machine client that cannot pass a browser login wants mode 2 instead:
+  # `mount Wurk::API => '/wurk-api'` in the host's own routes, declared BEFORE
+  # the engine when its path extends the engine's — Rails matches a mounted app
+  # by bare string prefix, so `mount Wurk::Engine => '/wurk'` declared first
+  # swallows every `/wurk-api/...` request.
   mount Wurk::API => Wurk::API::ENGINE_MOUNT, constraints: ->(request) { Wurk::API.serves?(request.path_info) }
 
   # Profiles (v8.0+) — not under /api: `:key/data` streams the gzipped gecko

data/lib/active_job/queue_adapters/wurk_adapter.rb

@@ -32,8 +32,14 @@ begin
 
         callback = -> { @@stopping = true } # rubocop:disable Style/ClassVars
 
-        Wurk.configure_client { |config| config.on(:quiet, &callback) }
-        Wurk.configure_server { |config| config.on(:quiet, &callback) }
+        # Registered on the configuration directly, not through
+        # Wurk.configure_client / Wurk.configure_server: one of the two gates
+        # always passes (configure_client while server? is false,
+        # configure_server once it is true), so the hook registered either way.
+        # Going through a gate would spend the one-time skip warning on Wurk's
+        # own internal call and log a spurious WARN — the warning the host's
+        # own skipped initializer needs.
+        Wurk.configuration.on(:quiet, &callback)
 
         # Defer enqueue until the surrounding DB transaction commits so we
         # never push a job whose row hasn't landed. Matches Sidekiq.

data/lib/sidekiq/rails.rb

@@ -6,5 +6,10 @@
 # alone, no ActionDispatch — so this maps to the railtie, NOT the dashboard
 # engine (a wurk-native extra; `require "wurk/rails"` for that). Sidekiq::Web
 # stays mountable as a plain Rack app either way, exactly like upstream.
+# A first require without ActiveJob preloaded needs ActiveSupport's core
+# extensions before rails/railtie. Requiring rails for that bootstrap would
+# also load ActionDispatch, breaking the railtie-only integration boundary.
 require 'wurk'
+require 'active_support'
+require 'active_support/core_ext'
 require 'wurk/railtie'

data/lib/wurk/api/read_only.rb

@@ -52,7 +52,7 @@ module Wurk
         Problem.render(
           Problem::READ_ONLY,
           status: 403,
-          detail: 'This Wurk deployment is read-only; it answers GET and HEAD only.',
+          detail: "This Wurk deployment is read-only; it answers #{SAFE_METHODS.join(', ')} only.",
           instance: request.path
         )
       end

data/lib/wurk/batch/server_middleware.rb

@@ -41,6 +41,29 @@ module Wurk
 
       CALLBACK_JOB = 'Wurk::Batch::CallbackJob'
 
+      # The middleware this one must stay OUTSIDE of — the ordering anchor
+      # `Chain#add` consults before appending.
+      #
+      # Expiry SKIPS an expired job by returning without yielding: inside the
+      # batch onion the batch's `ack_success` never runs, the batch's pending
+      # never drops and the batch never completes. The Limiter turns an
+      # over-limit job into a `Limiter::Rescheduled` (a JobRetry::Skip): inside
+      # the batch onion the batch's generic `rescue StandardError` books a
+      # spurious failure for a job that never ran.
+      #
+      # A plain `add` appends, so re-registering this middleware (a
+      # `configure_server` block, a test helper) would move it inside both and
+      # break the batch's accounting. The anchor keeps it outside.
+      #
+      # Resolved at call time, not at load time: Expiry is loaded after this
+      # file (lib/wurk.rb), so naming the constant here would raise NameError.
+      def self.outer_of
+        anchors = []
+        anchors << Wurk::Middleware::Expiry if defined?(Wurk::Middleware::Expiry)
+        anchors << Wurk::Limiter::ServerMiddleware if defined?(Wurk::Limiter::ServerMiddleware)
+        anchors
+      end
+
       def call(_worker, job, _queue, &)
         bid = job['bid']
         return yield unless bid
@@ -108,4 +131,8 @@ module Wurk
   end
 end
 
+# Auto-registered on the global server chain. The `outer_of` anchor above
+# keeps this middleware outside Expiry and the Limiter wherever it is
+# registered again later; this registration itself appends as usual, because
+# neither anchor is registered in the chain yet.
 Wurk.configuration.server_middleware.add(Wurk::Batch::ServerMiddleware)

data/lib/wurk/capsule.rb

@@ -40,6 +40,8 @@ module Wurk
       @pools = {}
       @client_chain = nil
       @server_chain = nil
+      @server_middleware_seen = []
+      @prepared = false
       @watchdog = nil
     end
 
@@ -102,10 +104,38 @@ module Wurk
     # hook opened across the fork. Idempotent.
     def prepare_shared!
       client_middleware
-      server_middleware
+      refresh_server_middleware!
+      # A second boot (a launcher run twice) finds the capsule frozen — the
+      # flag is already set, so it is not written again.
+      @prepared ||= true
       self
     end
 
+    # True once this capsule has been prepared to run jobs — `prepare_shared!`
+    # in the swarm parent before the fork, `prepare!` in the child at boot.
+    # Only then is the memoized chain the one the workers run, and only then
+    # is it final: a middleware registered on the Configuration afterwards can
+    # never reach it.
+    def prepared?
+      @prepared
+    end
+
+    # True when this capsule's server middleware chain has already been
+    # snapshotted and that snapshot does not carry `klass`.
+    #
+    # The snapshot is the copy `server_middleware` memoized; a middleware
+    # registered on the Configuration after that copy was taken can never
+    # reach this capsule — which is what Wurk::Encryption.enable has to
+    # detect before it seals arguments the workers could not open.
+    #
+    # Pure read: it never materializes the chain and has no side effects.
+    def server_middleware_missing?(klass)
+      chain = @server_chain
+      return false unless chain
+
+      !chain.exists?(klass)
+    end
+
     def client_middleware
       chain = (@client_chain ||= @config.client_middleware.copy_for(self))
       yield chain if block_given?
@@ -116,7 +146,11 @@ module Wurk
       # copy_for(self) — not dup — binds the chain's `@config` to this capsule,
       # so middleware that reach for `redis_pool`/`redis`/`logger` resolve them
       # instead of hitting `nil` (a plain dup leaves @config nil).
-      chain = (@server_chain ||= @config.server_middleware.copy_for(self))
+      chain = (@server_chain ||= begin
+        config_chain = @config.server_middleware
+        @server_middleware_seen = config_chain.entries.map(&:klass)
+        config_chain.copy_for(self)
+      end)
       yield chain if block_given?
       chain
     end
@@ -187,6 +221,27 @@ module Wurk
 
     private
 
+    # The Configuration's chain may have grown since this capsule copied it —
+    # a middleware registered after the copy was taken would otherwise be
+    # missing from the chain the workers run. Track classes already seen rather
+    # than just those still present, so capsule-local removals stay removed.
+    def refresh_server_middleware!
+      copy = server_middleware
+      return copy if frozen?
+
+      @config.server_middleware.entries.each do |entry|
+        next if @server_middleware_seen.include?(entry.klass)
+
+        @server_middleware_seen << entry.klass
+        next if copy.exists?(entry.klass)
+
+        rebound = entry.dup
+        rebound.config = self
+        copy.entries << rebound
+      end
+      copy
+    end
+
     # Drop-in fetch pluggability (spec §5 / §4.1): instantiate
     # `config[:fetch_class]` when the host set one — a custom or Pro fetcher —
     # else the default reliable BLMOVE fetcher (`Sidekiq::BasicFetch`). A

data/lib/wurk/cli.rb

@@ -138,8 +138,10 @@ module Wurk
       # Mark server mode BEFORE the app loads so `configure_server` blocks in
       # the required initializer actually fire (they gate on `config.server?`).
       # Matches Sidekiq, which sets `Sidekiq.server = true` before requiring
-      # the app in its CLI. Skipping this silently drops server middleware,
-      # error handlers, and lifecycle hooks registered via configure_server.
+      # the app in its CLI. Skipping this drops server middleware, error
+      # handlers, and lifecycle hooks registered via configure_server, and each
+      # skip logs one WARN naming the gate (`configure_server` / `server? is
+      # false`).
       enter_server_mode
       boot_application if boot_app
       self_read, self_write = ::IO.pipe

data/lib/wurk/client.rb

@@ -87,17 +87,17 @@ module Wurk
       payload['jid']
     end
 
-    # @param items [Hash] keys: class, args (Array<Array>), at?, spread_interval?, batch_size?, jid?
+    # @param items [Hash] String keys only: class, args (Array<Array>), at?, spread_interval?, batch_size?, jid?
     # @return [Array<String, nil>] jids in submission order; nil entries mark middleware-halted jobs.
     def push_bulk(items)
-      args = items['args'] || items[:args]
+      args = items['args']
       validate_bulk_shape!(items, args)
       return [] if args.empty?
 
       base      = bulk_base(items)
       reject_bulk_collapse!(base)
       at_values = expand_at(items, args.size)
-      batch_sz  = items['batch_size'] || items[:batch_size] || (at_values ? SCHEDULED_BATCH_SIZE : DEFAULT_BATCH_SIZE)
+      batch_sz  = items['batch_size'] || (at_values ? SCHEDULED_BATCH_SIZE : DEFAULT_BATCH_SIZE)
       flush_bulk(args, at_values, base, batch_sz)
     end
 
@@ -183,14 +183,19 @@ module Wurk
     end
 
     def validate_bulk_shape!(items, args)
+      raise ArgumentError, "Bulk items must be a Hash with 'class' and 'args' keys: `#{items}`" unless items.is_a?(Hash)
+
+      symbol_keys = items.keys.grep(Symbol)
+      # Symbol keys raise here exactly like #push does (spec §31.1) and are
+      # never stringified, so every read below can rely on String keys only.
+      raise ArgumentError, "Bulk push keys must be Strings: `#{symbol_keys.inspect}`" unless symbol_keys.empty?
       raise ArgumentError, "Bulk arguments must be an Array of Arrays: `#{args.inspect}`" unless valid_bulk_args?(args)
       raise ArgumentError, "Job 'jid' is only allowed with a single-job bulk" if explicit_jid?(items) && args.size > 1
       raise ArgumentError, "Cannot pass both 'at' and 'spread_interval'" if conflicting_schedule?(items)
     end
 
     def conflicting_schedule?(items)
-      (items.key?('at') || items.key?(:at)) &&
-        (items.key?('spread_interval') || items.key?(:spread_interval))
+      items.key?('at') && items.key?('spread_interval')
     end
 
     def valid_bulk_args?(args)
@@ -198,11 +203,11 @@ module Wurk
     end
 
     def explicit_jid?(items)
-      items.key?('jid') || items.key?(:jid)
+      items.key?('jid')
     end
 
     def bulk_base(items)
-      base = items.transform_keys(&:to_s)
+      base = items.dup
       %w[args at spread_interval batch_size].each { |k| base.delete(k) }
       base
     end
@@ -246,9 +251,9 @@ module Wurk
     end
 
     def expand_at(items, count)
-      return expand_spread(items, count) unless items.key?('at') || items.key?(:at)
+      return expand_spread(items, count) unless items.key?('at')
 
-      at = items['at'] || items[:at]
+      at = items['at']
       case at
       when Array
         raise ArgumentError, "'at' array size must match args" unless at.size == count
@@ -263,9 +268,9 @@ module Wurk
     end
 
     def expand_spread(items, count)
-      return nil unless items.key?('spread_interval') || items.key?(:spread_interval)
+      return nil unless items.key?('spread_interval')
 
-      spread = items['spread_interval'] || items[:spread_interval]
+      spread = items['spread_interval']
       raise ArgumentError, "'spread_interval' must be positive Numeric" unless spread.is_a?(Numeric) && spread.positive?
 
       window = [spread.to_f, SPREAD_INTERVAL_FLOOR].max

data/lib/wurk/compat.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 # Sidekiq aliases. This is the drop-in contract — every public Wurk::*
-# class is exposed under its Sidekiq::* name. Never break.
+# class is exposed under its Sidekiq::* name except two deliberate
+# exclusions, `Sidekiq::Cron` and `Sidekiq::Status` (#204): those namespaces
+# belong to the third-party sidekiq-cron / sidekiq-status gems, not to
+# Sidekiq itself. Never break the rest.
 #
 # Spec: docs/target/sidekiq-{free,pro,ent}.md.
 
@@ -14,7 +17,14 @@ require_relative 'loader'
 # {Wurk.configure_server}; `Sidekiq::Batch`, `Sidekiq::Limiter`,
 # `Sidekiq::Client`, `Sidekiq::Pro::Web`, `Sidekiq::Enterprise` all resolve to
 # their Wurk implementations. This alias surface is the drop-in contract and is
-# never broken.
+# never broken. Two names are deliberately NOT aliased (#204): `Sidekiq::Cron`
+# and `Sidekiq::Status` — those namespaces belong to the third-party
+# sidekiq-cron / sidekiq-status gems. `sidekiq-cron` owns `Sidekiq::Cron`, and
+# squatting it made the gem's own Poller/Job classes collide at load;
+# `sidekiq-status` opens `module Sidekiq::Status`, which resolves the constant
+# instead of defining it, so the alias would hand the gem {Wurk::Status} to
+# reopen and clobber. The guard comments at `CronParser` and `Status` below
+# carry the full rationale.
 #
 # @example The same code targets Sidekiq or Wurk unchanged
 #   class MyJob