wurk 0.0.1

data/lib/wurk/dead_set.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'job_set'
+
+module Wurk
+  # Capped ZSET of jobs that exhausted retries (the "morgue"). Bounded by
+  # `dead_max_jobs` and `dead_timeout_in_seconds` config knobs — every
+  # `kill` trims both axes. Death handlers fire on retry-exhausted kills
+  # (notify_failure: true), not on user-initiated UI kills.
+  #
+  # Spec: docs/target/sidekiq-free.md §19.5, §17.2, §31.8.
+  class DeadSet < JobSet
+    # Optional `name` allows tests to operate on a namespaced ZSET; production
+    # callers always use the default `'dead'` key (wire-compat with Sidekiq).
+    def initialize(name = 'dead')
+      super
+    end
+
+    # Two-axis trim: `ZREMRANGEBYSCORE` evicts entries older than
+    # `dead_timeout_in_seconds`, `ZREMRANGEBYRANK 0 -dead_max_jobs` keeps
+    # the count bounded. Pipelined — partial failure leaves at most one
+    # axis applied (acceptable; trim is non-critical, runs again next kill).
+    #
+    # `max_jobs:` / `timeout:` override the global config for this call.
+    # Lets parallel tests run trim with isolated limits without mutating
+    # `Wurk.configuration` (which is process-global and races across threads).
+    def trim(max_jobs: nil, timeout: nil) # rubocop:disable Naming/PredicateMethod
+      config = Wurk.configuration
+      max_jobs ||= config[:dead_max_jobs] || 10_000
+      timeout ||= config[:dead_timeout_in_seconds] || (180 * 24 * 60 * 60)
+      cutoff = ::Process.clock_gettime(::Process::CLOCK_REALTIME) - timeout
+
+      Wurk.redis do |conn|
+        conn.pipelined do |pipe|
+          pipe.call('ZREMRANGEBYSCORE', @name, '-inf', "(#{cutoff}")
+          pipe.call('ZREMRANGEBYRANK', @name, 0, -(max_jobs + 1))
+        end
+      end
+      true
+    end
+
+    # ZADD the raw JSON payload, trim, fire death handlers. `notify_failure:
+    # true` (default) routes the kill through the death-handler chain;
+    # UI-initiated kills pass false. `ex` is the originating exception (or
+    # synthesized RuntimeError when callers don't have one) — death handlers
+    # receive `(job, ex)`. `max_jobs:` / `timeout:` propagate to the auto-trim;
+    # see `#trim` for the rationale.
+    def kill(message, opts = {}) # rubocop:disable Naming/PredicateMethod
+      notify = opts.fetch(:notify_failure, true)
+      do_trim = opts.fetch(:trim, true)
+      ex = opts[:ex] || RuntimeError.new('Job killed')
+
+      now = ::Process.clock_gettime(::Process::CLOCK_REALTIME)
+      Wurk.redis { |conn| conn.call('ZADD', @name, now.to_s, message) }
+      trim(max_jobs: opts[:max_jobs], timeout: opts[:timeout]) if do_trim
+      fire_death_handlers(message, ex) if notify
+      true
+    end
+
+    private
+
+    def fire_death_handlers(message, ex)
+      job = parse_message(message)
+      handlers = Wurk.configuration.death_handlers
+      handlers.each do |handler|
+        handler.call(job, ex)
+      rescue StandardError => e
+        Wurk.configuration.handle_exception(e, context: 'death handler')
+      end
+    end
+
+    def parse_message(message)
+      message.is_a?(String) ? Wurk.load_json(message) : message
+    rescue ::JSON::ParserError
+      { 'class' => 'Unknown', 'args' => [], '_raw' => message }
+    end
+  end
+end

data/lib/wurk/deploy.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Records deploy markers into Redis so the history pane can overlay
+  # "deployed at" lines onto job-throughput charts. Wire-compatible with
+  # Sidekiq's `Sidekiq::Deploy`:
+  #
+  #   <YYYYMMDD>-marks    HASH    fields = iso8601 timestamp (rounded to minute),
+  #                               values = label string, TTL = 90 days
+  #   deploylock-<label>  STRING  SET NX EX 60, dedupe lock for same-label marks
+  #
+  # The lock collapses multiple `mark!` calls for the same label inside a
+  # 60-second window into a single HSET — fleet-wide deploys where every
+  # process calls `Wurk::Deploy.mark!` at boot end up with one row, not N.
+  #
+  # Spec: docs/target/sidekiq-free.md §23.
+  class Deploy
+    MARK_TTL = 90 * 24 * 60 * 60   # 90 days
+    LOCK_TTL = 60                  # 1 minute dedupe window
+    LOCK_PREFIX = 'deploylock-'
+    MARKS_SUFFIX = '-marks'
+
+    # Default label maker: short git SHA + commit subject. Same shape as
+    # Sidekiq Pro's LABEL_MAKER so existing deploy hooks keep working.
+    LABEL_MAKER = -> { `git log -1 --format="%h %s"`.strip }
+
+    # Class-level shorthand `Wurk::Deploy.mark!(label: "abc")` builds a
+    # one-shot Deploy and delegates. Matches Sidekiq's `Sidekiq::Deploy.mark!`.
+    def self.mark!(label: nil, at: ::Time.now)
+      new.mark!(label: label, at: at)
+    end
+
+    def initialize(pool: nil)
+      @pool = pool
+    end
+
+    # Writes a deploy marker. Returns the iso8601 timestamp written, or
+    # `nil` when the per-label lock was already held (a previous process
+    # within the last 60 seconds beat us to it for the same label).
+    def mark!(label: nil, at: ::Time.now)
+      label = resolve_label(label)
+      return nil if label.nil? || label.empty?
+
+      ts = round_to_minute(at)
+      iso = ts.iso8601
+      write_mark?(label, ts, iso) ? iso : nil
+    end
+
+    # Returns the deploy marks for `date` (Date or Time) as `{iso8601 => label}`.
+    def fetch(date = ::Time.now.utc)
+      date = date.utc if date.respond_to?(:utc)
+      key = "#{date.strftime('%Y%m%d')}#{MARKS_SUFFIX}"
+      with_redis { |c| c.call('HGETALL', key) } || {}
+    end
+
+    private
+
+    def round_to_minute(at)
+      utc = at.utc
+      ::Time.utc(utc.year, utc.month, utc.day, utc.hour, utc.min)
+    end
+
+    def write_mark?(label, time, iso)
+      lock_key = "#{LOCK_PREFIX}#{label}"
+      marks_key = "#{time.strftime('%Y%m%d')}#{MARKS_SUFFIX}"
+      with_redis do |conn|
+        return false unless conn.call('SET', lock_key, iso, 'NX', 'EX', LOCK_TTL) == 'OK'
+
+        conn.call('HSET', marks_key, iso, label)
+        conn.call('EXPIRE', marks_key, MARK_TTL)
+      end
+      true
+    end
+
+    def resolve_label(label)
+      return label unless label.nil? || label.empty?
+
+      LABEL_MAKER.call
+    rescue StandardError
+      nil
+    end
+
+    def with_redis(&)
+      if @pool
+        @pool.with(&)
+      else
+        Wurk.redis(&)
+      end
+    end
+  end
+end

data/lib/wurk/embedded.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative 'component'
+require_relative 'launcher'
+
+module Wurk
+  # Embeds Wurk inside an arbitrary Ruby process (Puma, rake task, custom
+  # daemon) without forking a swarm. Same Launcher/Manager/Processor stack
+  # the CLI uses — only the parent-process supervision is skipped.
+  #
+  # Typical use:
+  #   instance = Wurk.configure_embed { |c| c.queues = %w[critical default] }
+  #   instance.run
+  #   # ... host process serves traffic ...
+  #   instance.stop
+  #
+  # Concurrency defaults to 2 (set in `Wurk.configure_embed`) because the GIL
+  # makes contention worse in a host process that already has its own thread
+  # pool. The heartbeat marks `embedded: true` so the dashboard distinguishes
+  # embedded workers from swarm-forked workers.
+  #
+  # Spec: docs/target/sidekiq-free.md §22 (Sidekiq::Embedded).
+  class Embedded
+    include Component
+
+    attr_reader :launcher
+
+    def initialize(config)
+      @config = config
+      @launcher = nil
+    end
+
+    # Validates Redis, fires :startup, boots the launcher, sleeps 0.2 so
+    # the worker threads have time to spin up before the host goes back to
+    # serving traffic. Mirrors Sidekiq::Embedded#run.
+    def run
+      housekeeping
+      fire_event(:startup, reverse: false, reraise: true)
+      @launcher = build_launcher
+      @launcher.run
+      sleep 0.2
+      logger.info { "Wurk running embedded, total process thread count: #{Thread.list.size}" }
+      logger.debug { Thread.list.map(&:name).to_s }
+    end
+
+    # Stop fetching new work; in-flight jobs continue.
+    def quiet
+      @launcher&.quiet
+    end
+
+    # Graceful drain inside config[:timeout]; cancels in-flight jobs that
+    # exceed the deadline.
+    def stop
+      @launcher&.stop
+    end
+
+    private
+
+    # Extracted so tests can swap in a fake launcher without monkey-patching
+    # Wurk::Launcher.new globally (which races other parallel tests).
+    def build_launcher
+      Launcher.new(@config, embedded: true)
+    end
+
+    # Same checks Wurk::CLI performs before launch: tag default, Redis
+    # version floor, maxmemory-policy advisory. We intentionally do NOT
+    # run validate_pool_sizes! — the host owns its connection pools and
+    # may legitimately undersize for embedded workloads.
+    def housekeeping
+      @config[:tag] ||= default_tag
+      logger.info "Running in #{RUBY_DESCRIPTION}"
+      validate_redis!
+    end
+
+    def validate_redis!
+      info = @config.redis_pool.info
+      ver = ::Gem::Version.new(info['redis_version'])
+      if ver < ::Gem::Version.new(CLI::MIN_REDIS_VERSION)
+        raise "You are connected to Redis #{ver}, Wurk requires Redis #{CLI::MIN_REDIS_VERSION} or greater"
+      end
+
+      policy = info['maxmemory_policy']
+      return if policy.nil? || policy.empty? || policy == 'noeviction'
+
+      logger.warn { <<~WARN }
+
+
+        WARNING: Your Redis instance will evict Wurk data under heavy load.
+        The 'noeviction' maxmemory policy is recommended (current policy: '#{policy}').
+
+      WARN
+    end
+  end
+end

data/lib/wurk/encryption.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'openssl'
+require_relative 'middleware'
+require_relative 'dead_set'
+require_relative 'job_retry'
+require_relative 'metrics/statsd'
+
+module Wurk
+  # Sidekiq Enterprise encryption. AES-256-GCM over the **last** positional
+  # argument of `perform`. Implemented as a client/server middleware pair —
+  # client envelopes the last arg into a `{v, iv, ct, tag}` Hash, server
+  # peels it back before invoking perform.
+  #
+  # Activation:
+  #
+  #   Sidekiq::Enterprise::Crypto.enable(active_version: 1) do |version|
+  #     File.read("config/crypto/secret.#{Rails.env}.#{version}.key", mode: 'rb')
+  #   end
+  #
+  # The block is the **only** key source: file, ENV, KMS — anything that maps
+  # `Integer version → 32-byte binary key`. Wurk caches resolved keys per
+  # version in-process; rotate by writing a new key file, bumping
+  # `active_version`, and calling `enable` again.
+  #
+  # Per-worker opt-in:
+  #
+  #   class PrivateJob
+  #     include Sidekiq::Job
+  #     sidekiq_options encrypt: true
+  #     def perform(public_arg, secret_bag); end
+  #   end
+  #
+  # Wire format (per docs/target/sidekiq-ent.md §4.4): the last arg becomes
+  # a plain JSON Hash `{"v"=>N, "iv"=>b64(iv), "ct"=>b64(ct), "tag"=>b64(tag)}`
+  # — *not* a base64 blob of a binary envelope — so the args array stays
+  # valid JSON for inspectors that don't know about encryption.
+  #
+  # Constraints:
+  #   * `perform` must take ≥ 2 positional args. Pass `nil` first if no
+  #     cleartext payload exists.
+  #   * Only the last positional argument is encrypted. All earlier args
+  #     remain plaintext.
+  #   * Incompatible with Wurk::Unique (each ciphertext differs → digest
+  #     defeats the lock). Documented invariant.
+  #   * Web UI redacts the last arg when `encrypt: true` is set on the job.
+  #
+  # Spec: docs/target/sidekiq-ent.md §4.
+  module Encryption # rubocop:disable Metrics/ModuleLength
+    CIPHER_NAME = 'aes-256-gcm'
+    KEY_BYTES = 32
+    IV_BYTES = 12 # GCM standard: 96-bit IV.
+    TAG_BYTES = 16
+    ENVELOPE_MARKER = '__wurk_enc__'
+
+    # Reason tag stamped on the dead-set record when a job can't be
+    # decrypted. Surfaced as `error_class` (dashboard "Dead" column) and the
+    # `encryption_error:` prefix on `error_message`, plus the `jobs.encryption_error`
+    # statsd counter — so operators can alert on rotation gaps.
+    DEAD_REASON = 'encryption_error'
+    DECRYPTION_ERROR_CLASS = 'Wurk::Encryption::DecryptionError'
+
+    class Error < StandardError; end
+    class KeyMissingError < Error; end
+
+    # Marker for a terminal, non-retryable decryption failure (missing or
+    # rotated-away key, tampered ciphertext). The server middleware raises
+    # JobRetry::Skip after routing the job to the dead set, so this class
+    # is what callers see as the dead record's `error_class`.
+    class DecryptionError < Error; end
+
+    class << self
+      attr_reader :active_version
+
+      def enabled?
+        @enabled == true
+      end
+
+      # Install crypto with a key resolver. `active_version` is the version
+      # used to *encrypt* new pushes; the resolver block must still return
+      # keys for any older in-flight versions so they decrypt.
+      #
+      # Idempotent: re-calling rebinds the resolver and rebuilds the cache.
+      # Middleware is installed at most once per chain.
+      def enable(active_version:, &resolver) # rubocop:disable Naming/PredicateMethod
+        raise ArgumentError, 'active_version is required' unless active_version
+        raise ArgumentError, 'block returning the key bytes is required' unless resolver
+
+        @active_version = Integer(active_version)
+        @resolver = resolver
+        @key_cache = {}
+        @enabled = true
+        register_middleware!
+        true
+      end
+
+      # Test helper — not part of the public Sidekiq surface.
+      def disable!
+        @enabled = false
+        @active_version = nil
+        @resolver = nil
+        @key_cache = nil
+        nil
+      end
+
+      # Resolve and cache the 32-byte key for `version`. Re-raises with a
+      # Wurk-specific exception when the resolver returns nothing usable so
+      # callers don't have to detect "nil from block" themselves.
+      def key_for(version)
+        raise Error, 'Wurk::Encryption not enabled' unless enabled?
+
+        @key_cache ||= {}
+        @key_cache[version] ||= validate_key!(version, @resolver.call(version))
+      end
+
+      # Encrypt `value` (any JSON-serializable Ruby value) under
+      # `active_version`. Returns a Hash literal — JSON-friendly, so the
+      # job payload stays inspectable.
+      def encrypt(value)
+        version = @active_version
+        key = key_for(version)
+        iv = ::OpenSSL::Random.random_bytes(IV_BYTES)
+        cipher = ::OpenSSL::Cipher.new(CIPHER_NAME).encrypt
+        cipher.key = key
+        cipher.iv = iv
+        ct = cipher.update(::JSON.dump(value)) + cipher.final
+        tag = cipher.auth_tag(TAG_BYTES)
+
+        {
+          ENVELOPE_MARKER => true,
+          'v' => version,
+          'iv' => ::Base64.strict_encode64(iv),
+          'ct' => ::Base64.strict_encode64(ct),
+          'tag' => ::Base64.strict_encode64(tag)
+        }
+      end
+
+      # Decrypt the envelope produced by `encrypt`. Raises
+      # `OpenSSL::Cipher::CipherError` on tag mismatch (bad key / tamper)
+      # — server middleware lets it bubble so the failure flows through
+      # the retry/dead pipeline per §4.6.
+      def decrypt(envelope)
+        version = Integer(envelope['v'])
+        cipher = build_decrypt_cipher(envelope, key_for(version))
+        plain = cipher.update(::Base64.strict_decode64(envelope['ct'])) + cipher.final
+        ::JSON.parse(plain, quirks_mode: true)
+      end
+
+      # @return [Boolean] true if `value` looks like a Wurk crypto envelope.
+      # Used by both server middleware and the Web UI redactor — single
+      # source of truth so the two cannot drift.
+      def envelope?(value)
+        value.is_a?(::Hash) && value[ENVELOPE_MARKER] == true &&
+          value.key?('v') && value.key?('iv') && value.key?('ct') && value.key?('tag')
+      end
+
+      # Web UI display helper (§4.7). Given a job hash, returns the args
+      # array with the last element replaced by the literal `"<encrypted>"`
+      # when the job opted in. Cleartext preceding args are untouched so
+      # operators can still triage on user_id / object_id / etc.
+      def redact_args(job)
+        args = job['args'] || job[:args] || []
+        return args unless job['encrypt'] || job[:encrypt]
+        return args if args.empty?
+
+        args[0..-2] + ['<encrypted>']
+      end
+
+      # A decryption failure means the key is gone (rotated away) or the
+      # ciphertext is bad — neither heals with time, so retrying 25× over
+      # ~21 days is a pointless crash loop. Instead the server middleware
+      # routes the job straight to the dead set, tagged `encryption_error`,
+      # and ACKs it (raises JobRetry::Skip). Done in <1s, death handlers fire
+      # so operators get paged. The still-encrypted envelope is kept on the
+      # record; earlier plaintext args stay visible for triage (§4.6).
+      def route_to_dead(job, cause)
+        record = job.merge(
+          'error_class' => DECRYPTION_ERROR_CLASS,
+          'error_message' => "#{DEAD_REASON}: #{cause.class}: #{cause.message}",
+          'failed_at' => ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+        )
+        Wurk::Metrics::Statsd.increment('jobs.encryption_error', tags: ["worker:#{job['class']}"])
+        Wurk::DeadSet.new.kill(Wurk.dump_json(record), ex: cause)
+        nil
+      end
+
+      private
+
+      def build_decrypt_cipher(envelope, key)
+        cipher = ::OpenSSL::Cipher.new(CIPHER_NAME).decrypt
+        cipher.key = key
+        cipher.iv = ::Base64.strict_decode64(envelope['iv'])
+        cipher.auth_tag = ::Base64.strict_decode64(envelope['tag'])
+        cipher
+      end
+
+      def validate_key!(version, bytes)
+        raise KeyMissingError, "key resolver returned nil for version #{version}" if bytes.nil?
+
+        bytes = bytes.dup.force_encoding(::Encoding::ASCII_8BIT)
+        unless bytes.bytesize == KEY_BYTES
+          raise Error, "key for version #{version} must be #{KEY_BYTES} bytes, got #{bytes.bytesize}"
+        end
+
+        bytes
+      end
+
+      def register_middleware!
+        Wurk.configuration.client_middleware.add(ClientMiddleware) \
+          unless Wurk.configuration.client_middleware.exists?(ClientMiddleware)
+        Wurk.configuration.server_middleware.add(ServerMiddleware) \
+          unless Wurk.configuration.server_middleware.exists?(ServerMiddleware)
+      end
+    end
+
+    # Client middleware — envelopes the **last** positional argument when
+    # the job opts in via `sidekiq_options encrypt: true`. Skips silently
+    # when crypto is disabled, the job didn't opt in, or `args` is empty
+    # (per §4.3, an opt-in worker with empty args is a user bug, but we
+    # don't enqueue garbage — let perform raise ArgumentError if it cares).
+    class ClientMiddleware
+      include Wurk::Middleware::ClientMiddleware
+
+      def call(_worker, job, _queue, _redis_pool)
+        return yield unless Wurk::Encryption.enabled? && job['encrypt']
+
+        args = job['args']
+        if args.is_a?(::Array) && !args.empty? && !Wurk::Encryption.envelope?(args.last)
+          job['args'] = args[0..-2] + [Wurk::Encryption.encrypt(args.last)]
+        end
+        yield
+      end
+    end
+
+    # Server middleware — peels the envelope before perform runs. A decrypt
+    # failure (missing/rotated key, bad tag) is terminal and non-retryable,
+    # so rather than let it bubble into the 25× retry pipeline we route the
+    # job straight to the dead set tagged `encryption_error` and ACK it via
+    # JobRetry::Skip — see Wurk::Encryption.route_to_dead. Plaintext args
+    # remain visible for triage per §4.6.
+    class ServerMiddleware
+      include Wurk::Middleware::ServerMiddleware
+
+      def call(_worker, job, _queue)
+        return yield unless Wurk::Encryption.enabled? && job['encrypt']
+
+        decrypt_last_arg!(job)
+        yield
+      end
+
+      private
+
+      def decrypt_last_arg!(job)
+        args = job['args']
+        return unless args.is_a?(::Array) && !args.empty? && Wurk::Encryption.envelope?(args.last)
+
+        job['args'] = args[0..-2] + [Wurk::Encryption.decrypt(args.last)]
+      rescue Wurk::Encryption::Error,
+             ::OpenSSL::Cipher::CipherError,
+             ::ArgumentError,
+             ::TypeError,
+             ::JSON::ParserError => e
+        # Wurk::Encryption::Error covers KeyMissingError / DecryptionError.
+        # OpenSSL::Cipher::CipherError → tampered ciphertext / bad key (tag mismatch).
+        # ArgumentError → Base64.strict_decode64 / Integer() on a malformed envelope.
+        # TypeError    → Integer(nil) on a missing 'v' field.
+        # JSON::ParserError → ciphertext decrypts to non-JSON (different key, but auth tag is gone via GCM → rare,
+        # but cheap to cover so malformed payloads never re-enter the 25× retry loop).
+        Wurk::Encryption.route_to_dead(job, e)
+        raise Wurk::JobRetry::Skip, "#{Wurk::Encryption::DEAD_REASON}: #{e.class}"
+      end
+    end
+  end
+end

data/lib/wurk/engine.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+require_relative '../active_job/queue_adapters/wurk_adapter'
+require_relative 'dashboard_manifest'
+require_relative 'web'
+
+module Wurk
+  # Rails mountable engine. Owns the dashboard mount, the asset path for
+  # the precompiled SPA, and (via the sibling railtie) the after_initialize
+  # hook that boots the swarm.
+  class Engine < ::Rails::Engine
+    isolate_namespace Wurk
+
+    config.generators do |g|
+      g.test_framework :minitest, fixtures: false
+    end
+
+    # Rack::Files doesn't strip the URL prefix before file lookup, so
+    # `/wurk-assets/assets/foo.js` would resolve under `vendor/assets/dashboard/
+    # wurk-assets/assets/foo.js` — a path that doesn't exist. AssetMount
+    # rewrites PATH_INFO to drop the `/wurk-assets` prefix before delegating
+    # to Rack::Files, then falls through to the next middleware on 404 so
+    # host-app routes outside the mount keep working.
+    class AssetMount
+      PREFIX = '/wurk-assets'
+
+      def initialize(app, root:)
+        @app   = app
+        @files = ::Rack::Files.new(root)
+      end
+
+      def call(env)
+        path = env[::Rack::PATH_INFO]
+        return @app.call(env) unless path == PREFIX || path.start_with?("#{PREFIX}/")
+
+        inner = env.dup
+        stripped = path.delete_prefix(PREFIX)
+        inner[::Rack::PATH_INFO] = stripped.empty? ? '/' : stripped
+        response = @files.call(inner)
+        response[0] == 404 ? @app.call(env) : response
+      end
+    end
+
+    # Precompiled SPA lives in vendor/assets/dashboard; the engine serves
+    # those files as static assets under the /wurk-assets mount point via
+    # AssetMount (above).
+    initializer 'wurk.assets' do |app|
+      assets_path = Wurk::Engine.root.join('vendor', 'assets', 'dashboard')
+      if assets_path.exist?
+        app.middleware.insert_before(
+          ::ActionDispatch::Static,
+          ::Wurk::Engine::AssetMount,
+          root: assets_path.to_s
+        )
+      end
+    end
+
+    # Fail boot in production if the precompiled bundle is missing or its
+    # version doesn't match the gem. Dev and test skip — contributors don't
+    # always have a fresh build, and Vite dev mode owns the shell directly.
+    initializer 'wurk.dashboard_manifest_check' do
+      next if ENV['WURK_VITE_DEV'] == '1'
+      next unless ::Rails.env.production?
+
+      ::Wurk::DashboardManifest.check!
+    end
+
+    # Engine-scoped Rack middleware. Inserted into the engine — not the host —
+    # so the host's own controllers stay unaffected; only requests routed
+    # under the mount point pass through.
+    #
+    #   * MiddlewareStack — host-app auth via `Wurk::Web.use` (#41). Outermost,
+    #     so Devise/Warden/Sorcery run first and their `env` is visible to the
+    #     authorization hook below.
+    #   * Authorization — the `Wurk::Web.configure` authorization + read-only
+    #     hook (sidekiq-ent §9.2), 403 on falsey.
+    middleware.use ::Wurk::Web::MiddlewareStack
+    middleware.use ::Wurk::Web::Authorization
+  end
+end