joobq 0.1.0

data/lib/joobq.rb

@@ -0,0 +1,1528 @@
+# frozen_string_literal: true
+# Code generated by joobqui-selfhosted sdk:generate (v0.1.0) from JoobQ Polyglot SDK Gateway API. DO NOT EDIT.
+# Supported Gateway Operations:
+#   - POST /api/v1/sdk/batches: Create a Pro batch of jobs with completion callbacks, filled and sealed in one call (Pro)
+#   - GET /api/v1/sdk/batches/{id}: Read a Pro batch's progress: pending, succeeded and failed members (Pro)
+#   - POST /api/v1/sdk/blueprints: Register a workflow blueprint, versioned by its content hash
+#   - POST /api/v1/sdk/jobs: Enqueue a background job onto a queue
+#   - POST /api/v1/sdk/jobs/batch: Enqueue up to 500 background jobs in one call
+#   - GET /api/v1/sdk/openapi.json: Describe the Polyglot SDK Gateway API as an OpenAPI 3.1 document
+#   - POST /api/v1/sdk/rate-limit: Reserve one slot of a sliding-window rate limit (Pro)
+#   - POST /api/v1/sdk/schedules: Register a code-declared cron/recurring job or workflow schedule, idempotent by name
+#   - POST /api/v1/sdk/tasks/ack: Settle up to 100 task leases in one call, each completed or failed
+#   - POST /api/v1/sdk/tasks/heartbeat: Extend every lease a worker holds in one call and check each for cancellation
+#   - POST /api/v1/sdk/tasks/poll: Claim due jobs and workflow steps from unpaused queues
+#   - POST /api/v1/sdk/tasks/{token}/complete: Commit task completion and output
+#   - POST /api/v1/sdk/tasks/{token}/fail: Record structured polyglot task failure and stack frames
+#   - POST /api/v1/sdk/tasks/{token}/heartbeat: Extend an active task lease and check for cancellation
+#   - POST /api/v1/sdk/workers/register: Register or heartbeat a polyglot SDK worker
+#   - POST /api/v1/sdk/workers/{id}/deregister: Deregister a polyglot SDK worker on shutdown
+#   - POST /api/v1/sdk/workflows: Start a durable workflow execution
+#   - GET /api/v1/sdk/workflows/{id}: Describe one workflow run: status, output, failure and search attributes
+#   - GET /api/v1/sdk/workflows/{id}/history: The events of a workflow run, after after_seq, at most limit
+#   - POST /api/v1/sdk/workflows/{id}/query: Ask a workflow run a read-only question
+#   - GET /api/v1/sdk/workflows/{id}/result: The outcome of a workflow, following continue-as-new; waits up to wait_ms for it to close
+#   - POST /api/v1/sdk/workflows/{id}/search-attributes: Set and remove search attributes of a workflow's open run
+#   - POST /api/v1/sdk/workflows/{id}/signal: Deliver an asynchronous signal to a running workflow
+#   - POST /api/v1/sdk/workflows/{id}/updates: Send an update to a running workflow and wait for its outcome
+# NOTE: Queue & workflow management (pause, resume, redrive, cancel, terminate) is intentionally
+# excluded from SDKs and must be performed via the JoobQUI Operator Console (/ui/).
+
+require "json"
+require "net/http"
+require "socket"
+require "uri"
+
+module JoobQ
+  SDK_VERSION = "0.1.0"
+
+
+  class NonRetryableError < StandardError; end
+
+  # The gateway answered with an error status.
+  class GatewayError < StandardError
+    attr_reader :status
+
+    def initialize(status, body)
+      super("JoobQ Gateway error (#{status}): #{body.to_s[0, 300]}")
+      @status = status
+    end
+  end
+
+  # `non_retryable` lists error types (the exception's class name, as the worker reports it in `error_class`) that end
+  # the step without another attempt.
+  RetryPolicy = Struct.new(:attempts, :initial_ms, :backoff, :maximum_ms, :non_retryable, keyword_init: true)
+  Compensation = Struct.new(:handler, :input, :activity, keyword_init: true)
+  # Puts a node on one side of a change (versioning): it runs only for runs whose version of `change` is within
+  # `min..max` (open ended when nil), and is skipped otherwise. Made with `gate`.
+  Gate = Struct.new(:change, :min, :max, keyword_init: true)
+  # An update handler declared with `WorkflowBlueprint#update`.
+  UpdateDef = Struct.new(:name, :handler, :validate, :message, :input, :result, :timeout_ms, keyword_init: true)
+  DataRef = Struct.new(:expr) do
+    def to_s
+      expr
+    end
+  end
+
+  module DSL
+    # A step's retry policy, applied by the engine. `non_retryable` names error types (class names) that are not retried.
+    def retry_policy(attempts: 3, initial_ms: 1000, backoff: 2.0, maximum_ms: 30_000, non_retryable: [])
+      RetryPolicy.new(attempts: attempts, initial_ms: initial_ms, backoff: backoff, maximum_ms: maximum_ms,
+                      non_retryable: Array(non_retryable).map(&:to_s))
+    end
+
+    def compensation(handler, input: nil)
+      Compensation.new(handler: JoobQ.normalize_callable(handler), input: input, activity: JoobQ.activity_name(handler))
+    end
+
+    def input(key = nil)
+      key.nil? ? DataRef.new("${input}") : DataRef.new("${input.#{key}}")
+    end
+
+    def output(step_name, key = nil)
+      key.nil? ? DataRef.new("${steps.#{step_name}.output}") : DataRef.new("${steps.#{step_name}.output.#{key}}")
+    end
+
+    # The input of the update being handled (`${update.input}`, or `${update.input.<key>}`): for an update's
+    # `validate`, `input` and `result`.
+    def update_input(key = nil)
+      key.nil? ? DataRef.new("${update.input}") : DataRef.new("${update.input.#{key}}")
+    end
+
+    # A gate on the change `change` (see `WorkflowBlueprint#change`), for the `gate:` option of `step`, `wait_for`,
+    # `timer` and `child`: the node runs only for runs whose version of the change is within `min..max`. At least one
+    # bound is required (ArgumentError otherwise).
+    def gate(change, min: nil, max: nil)
+      raise ArgumentError, "gate on #{change.to_s.inspect} needs a min or a max" if min.nil? && max.nil?
+
+      Gate.new(change: change.to_s, min: min, max: max)
+    end
+
+    def ref(path)
+      clean = path.to_s.strip
+      clean.start_with?("${") && clean.end_with?("}") ? DataRef.new(clean) : DataRef.new("${#{clean}}")
+    end
+
+    def workflow(name, version: 1, timeout_ms: nil, task_queue: "workflows", &block)
+      JoobQ.workflow(name, version: version, timeout_ms: timeout_ms, task_queue: task_queue, &block)
+    end
+  end
+
+  extend DSL
+
+  # The `${...}` references a step input makes (a blueprint sends these, never the literal values around them).
+  def self.collect_references(spec, found = [])
+    case spec
+    when DataRef then found << spec.expr unless found.include?(spec.expr)
+    when Hash then spec.each_value { |v| collect_references(v, found) }
+    when Array then spec.each { |v| collect_references(v, found) }
+    end
+    found
+  end
+
+  # A readable name for a step's activity: its class or job name; nil for a block or lambda.
+  def self.activity_name(target)
+    return target.job_name if target.respond_to?(:job_name)
+    return target.name if target.is_a?(Class) || target.is_a?(Module)
+    return target.name.to_s if target.is_a?(Method)
+    return nil if target.nil? || target.is_a?(Proc)
+
+    target.class.name
+  end
+
+  def self.normalize_callable(target)
+    return target if target.respond_to?(:call)
+    return ->(payload, ctx) { target.perform(payload, ctx) } if target.respond_to?(:perform)
+    if target.is_a?(Class) && target.method_defined?(:perform)
+      return ->(payload, ctx) { target.new.perform(payload, ctx) }
+    end
+
+    raise ArgumentError, "Expected callable or Job/Activity with .perform(payload, ctx), got #{target.inspect}"
+  end
+
+  def self.lookup_path(root, dotted)
+    cur = root
+    dotted.to_s.split(".").each do |part|
+      next if part.empty?
+      return nil unless cur.is_a?(Hash)
+
+      cur = cur[part] || cur[part.to_sym]
+      return nil if cur.nil?
+    end
+    cur
+  end
+
+  def self.resolve_references(spec, workflow_input, checkpoints)
+    return workflow_input if spec.nil?
+
+    case spec
+    when DataRef
+      expr = spec.expr
+      return workflow_input if expr == "${input}"
+      if expr.start_with?("${input.") && expr.end_with?("}")
+        return lookup_path(workflow_input, expr[8..-2])
+      end
+      if expr.start_with?("${steps.") && expr.end_with?("}")
+        parts = expr[8..-2].split(".")
+        step_name = parts[0]
+        step_out = checkpoints[step_name] || checkpoints[step_name.to_sym]
+        return step_out if parts.length <= 2
+        return lookup_path(step_out, parts[2..].join("."))
+      end
+      return checkpoints.dup if expr == "${steps}"
+      if expr.start_with?("${") && expr.end_with?("}")
+        return lookup_path({ "input" => workflow_input, "steps" => checkpoints }, expr[2..-2])
+      end
+      expr
+    when Hash
+      spec.each_with_object({}) do |(k, v), acc|
+        acc[k.to_s] = resolve_references(v, workflow_input, checkpoints)
+      end
+    when Array
+      spec.map { |v| resolve_references(v, workflow_input, checkpoints) }
+    else
+      spec
+    end
+  end
+
+  # A child's or continued run's input as the engine resolves it: references (`input`, `output`, `ref`) in hashes and
+  # arrays, turned into their `${...}` strings. A literal value is refused (ArgumentError): compute a constant in a step
+  # and refer to its output.
+  def self.template(spec, where)
+    case spec
+    when DataRef then spec.expr
+    when Hash then spec.each_with_object({}) { |(k, v), acc| acc[k.to_s] = template(v, "#{where}.#{k}") }
+    when Array then spec.each_with_index.map { |v, i| template(v, "#{where}[#{i}]") }
+    else
+      raise ArgumentError, "#{where}: #{spec.inspect} is not a reference; the engine resolves this input, so only references are sent"
+    end
+  end
+
+  def self.extract_step_dependencies(spec)
+    deps = []
+    visit = lambda do |node|
+      case node
+      when DataRef
+        if node.expr.start_with?("${steps.")
+          step_name = node.expr[8..-2].split(".").first
+          deps << step_name if step_name && !deps.include?(step_name)
+        end
+      when Hash
+        node.each_value { |v| visit.call(v) }
+      when Array
+        node.each { |v| visit.call(v) }
+      end
+    end
+    visit.call(spec)
+    deps
+  end
+
+  module Job
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def job_name(val = nil)
+        @job_name = val.to_s unless val.nil?
+        @job_name || name.split("::").last
+      end
+
+      def queue(val = nil)
+        @queue = val.to_s unless val.nil?
+        @queue || "default"
+      end
+
+      def retries(val = nil)
+        @retries = val.to_i unless val.nil?
+        @retries.nil? ? 3 : @retries
+      end
+
+      def expires_ms(val = nil)
+        @expires_ms = val.to_i unless val.nil?
+        @expires_ms
+      end
+
+      def encrypted_fields(*fields)
+        @encrypted_fields = fields.flatten.map(&:to_s) unless fields.empty?
+        @encrypted_fields || []
+      end
+
+      def unique_ttl_ms(val = nil)
+        @unique_ttl_ms = val.to_i unless val.nil?
+        @unique_ttl_ms
+      end
+
+      def enqueue(client, payload = {}, **opts)
+        client.enqueue(self, payload, **opts)
+      end
+    end
+  end
+
+  class WorkflowBlueprint
+    include DSL
+
+    attr_reader :name, :version, :timeout_ms, :task_queue, :steps, :queries, :continuation, :changes, :updates
+
+    # `timeout_ms` is the whole run's deadline (none by default), enforced by the engine.
+    def initialize(name, version: 1, timeout_ms: nil, task_queue: "workflows")
+      @name = name.to_s
+      @version = version
+      @timeout_ms = timeout_ms
+      @task_queue = task_queue
+      @steps = []
+      @queries = {}
+      @declared_steps = {}
+      @continuation = nil
+      @changes = {}
+      @updates = {}
+      @in_scope = false
+    end
+
+    def query(name, expr)
+      @queries[name.to_s] = expr
+      self
+    end
+
+    # A step. `after` names earlier steps it also waits for (on top of what precedes it, e.g. a sibling in a `parallel`
+    # group); `timeout_ms` limits one attempt, `heartbeat_ms` how long the handler may go without calling
+    # `ctx.heartbeat`, `schedule_to_start_ms` how long the step may wait for a worker; `only_if` (a reference) runs the
+    # step only when it is truthy, else the step is skipped; `gate` (see `gate`) runs it only on one side of a change.
+    # The engine enforces them.
+    def step(name, activity = nil, input: nil, retry_policy: nil, retry: nil, compensate: nil, after: [], timeout_ms: nil,
+             heartbeat_ms: nil, schedule_to_start_ms: nil, only_if: nil, gate: nil, &block)
+      step_name = name.to_s
+      after = Array(after).map(&:to_s)
+      check_condition!(step_name, only_if)
+      check_gate!(step_name, gate)
+      validate_and_register!(step_name, input, after)
+      callable = JoobQ.normalize_callable(activity || block)
+      @steps << {
+        kind: "step",
+        name: step_name,
+        handler: callable,
+        activity: JoobQ.activity_name(activity),
+        input_spec: input,
+        retry: retry_policy || binding.local_variable_get(:retry),
+        compensate: compensate,
+        after: after,
+        timeout_ms: timeout_ms,
+        heartbeat_ms: heartbeat_ms,
+        schedule_to_start_ms: schedule_to_start_ms,
+        only_if: only_if,
+        gate: gate
+      }
+      self
+    end
+
+    # Waits for a signal. `after` names earlier steps it also waits for, `only_if` (a reference) skips the wait unless
+    # it is truthy, `compensate` undoes it when the run fails (its input defaults to the signal's payload), `gate` as on
+    # `step`.
+    def wait_for(name, signal:, timeout_ms: 600_000, after: [], only_if: nil, compensate: nil, gate: nil)
+      step_name = name.to_s
+      after = Array(after).map(&:to_s)
+      check_condition!(step_name, only_if)
+      check_gate!(step_name, gate)
+      validate_and_register!(step_name, nil, after)
+      @steps << { kind: "wait_for", name: step_name, signal: signal.to_s, timeout_ms: timeout_ms, after: after,
+                  only_if: only_if, compensate: compensate, gate: gate }
+      self
+    end
+
+    # Sleeps `for_ms` durably. `after` names earlier steps it also waits for, `only_if` (a reference) skips the timer
+    # unless it is truthy, `compensate` undoes it when the run fails (its input defaults to the timer's output), `gate`
+    # as on `step`.
+    def timer(name, for_ms:, after: [], only_if: nil, compensate: nil, gate: nil)
+      step_name = name.to_s
+      after = Array(after).map(&:to_s)
+      check_condition!(step_name, only_if)
+      check_gate!(step_name, gate)
+      validate_and_register!(step_name, nil, after)
+      @steps << { kind: "timer", name: step_name, duration_ms: for_ms, after: after, only_if: only_if, compensate: compensate,
+                  gate: gate }
+      self
+    end
+
+    # Runs another workflow (a blueprint or its name) as a node; its output is the child run's output, its failure the
+    # node's. The engine starts the child and resolves `input` (references only: `input`, `output`, `ref`, in hashes and
+    # arrays; the parent run's input when omitted). A child is not retried and has no timeout of its own: give the child
+    # workflow's steps retries, and the child workflow a `timeout_ms`. `compensate` undoes it when the run fails (its
+    # input defaults to the child's output), `after`, `only_if` and `gate` as on `step`. The child workflow must be
+    # registered before a run reaches this node.
+    def child(name, workflow, input: nil, compensate: nil, after: [], only_if: nil, gate: nil)
+      step_name = name.to_s
+      after = Array(after).map(&:to_s)
+      JoobQ.template(input, "#{step_name}.input") unless input.nil?
+      check_condition!(step_name, only_if)
+      check_gate!(step_name, gate)
+      validate_and_register!(step_name, input, after)
+      child_name = workflow.is_a?(WorkflowBlueprint) ? workflow.name : workflow.to_s
+      @steps << { kind: "child", name: step_name, workflow: child_name, input_spec: input, compensate: compensate,
+                  after: after, only_if: only_if, gate: gate }
+      self
+    end
+
+    # When the run ends (and `only_if`, a reference, is truthy), it closes `continued_as_new` and a fresh run of this
+    # workflow starts with `input` (references only, resolved by the engine; the same input when omitted), at most
+    # `max_runs` runs; `max_events` bounds a run's history. The engine enforces it.
+    def continue_as_new(input: nil, only_if: nil, max_runs: nil, max_events: nil)
+      policy = {}
+      policy["input"] = JoobQ.template(input, "continue_as_new.input") unless input.nil?
+      unless only_if.nil?
+        raise ArgumentError, "continue_as_new: only_if must be a reference (input, output, ref)" unless only_if.is_a?(DataRef)
+
+        policy["only_if"] = only_if.expr
+      end
+      policy["max_runs"] = max_runs unless max_runs.nil?
+      policy["max_events"] = max_events unless max_events.nil?
+      @continuation = policy
+      self
+    end
+
+    # Declares a change (versioning, like Temporal's getVersion): runs that reach a gated node fresh take `max`, runs
+    # that went past it on the old path keep 0; nodes pick a side with `gate: gate(id, min: ..., max: ...)`. Raise `min`
+    # only once no open run is on an older path. `min` above `max` is an ArgumentError.
+    def change(id, min: 0, max: 1)
+      raise ArgumentError, "change #{id.to_s.inspect} in workflow '#{@name}': min is above max" if min > max
+
+      @changes[id.to_s] = { "min" => min, "max" => max }
+      self
+    end
+
+    # An update handler (`Client#update_workflow`): `validate` (a reference, e.g. `update_input("name")`) must be truthy
+    # or the update is rejected with `message`; then `handler` runs as a step of the run (its payload is `input`, by
+    # default the update's input, and its return value is the result), or, without one, `result` (a template of
+    # references) is the result; `timeout_ms` limits the handler. References may read the run (`input`, `output`) and
+    # `update_input`. A duplicate name, a `validate` that is not a reference, or a literal in `input`/`result` is an
+    # ArgumentError.
+    def update(name, handler = nil, validate: nil, message: nil, input: nil, result: nil, timeout_ms: nil, &block)
+      update_name = name.to_s
+      raise ArgumentError, "Duplicate update '#{update_name}' in workflow '#{@name}'" if @updates.key?(update_name)
+      unless validate.nil? || validate.is_a?(DataRef)
+        raise ArgumentError, "update '#{update_name}': validate must be a reference (update_input, input, output, ref)"
+      end
+
+      JoobQ.template(input, "update #{update_name}.input") unless input.nil?
+      JoobQ.template(result, "update #{update_name}.result") unless result.nil?
+      target = handler || block
+      fn = target.nil? ? nil : JoobQ.normalize_callable(target)
+      @updates[update_name] = UpdateDef.new(name: update_name, handler: fn, validate: validate, message: message,
+                                            input: input, result: result, timeout_ms: timeout_ms)
+      self
+    end
+
+    # A cancellation scope: its steps (declared in the block) run in sequence and can be cancelled as a unit (from the
+    # console or API, or after `timeout_ms` from its first step's start) while the rest of the run goes on; a cancelled
+    # step counts as finished with a null output. A `non_cancellable` scope holds cleanup that still runs when the
+    # workflow is cancelled, times out or fails (it cannot have a timeout). A running step sees a cancel through
+    # `ctx.heartbeat`. Scopes do not nest, and a scope needs at least one step (ArgumentError otherwise).
+    def scope(name, timeout_ms: nil, non_cancellable: false, &block)
+      scope_name = name.to_s
+      if @in_scope
+        raise ArgumentError, "scope '#{scope_name}' in workflow '#{@name}' is inside another scope: scopes do not nest"
+      end
+      if non_cancellable && !timeout_ms.nil?
+        raise ArgumentError, "scope '#{scope_name}' is non_cancellable and cannot time out"
+      end
+
+      sub = WorkflowBlueprint.new("#{@name}:scope", version: @version, timeout_ms: @timeout_ms, task_queue: @task_queue)
+      @declared_steps.each_key { |k| sub.send(:mark_declared!, k) }
+      sub.send(:enter_scope!)
+      sub.instance_eval(&block) if block
+      raise ArgumentError, "scope '#{scope_name}' in workflow '#{@name}' has no steps" if sub.steps.empty?
+
+      sub.send(:declared_keys).each { |k| mark_declared!(k) }
+      @steps << { kind: "scope", name: scope_name, children: sub.steps, timeout_ms: timeout_ms,
+                  non_cancellable: non_cancellable ? true : false }
+      self
+    end
+
+    def parallel(&block)
+      sub = WorkflowBlueprint.new("#{@name}:parallel", version: @version, timeout_ms: @timeout_ms, task_queue: @task_queue)
+      @declared_steps.each_key { |k| sub.send(:mark_declared!, k) }
+      sub.send(:enter_scope!) if @in_scope
+      sub.instance_eval(&block)
+      sub.send(:declared_keys).each { |k| mark_declared!(k) }
+      @steps << { kind: "parallel", name: "parallel_#{@steps.length + 1}", children: sub.steps }
+      self
+    end
+
+    def sequence(&block)
+      sub = WorkflowBlueprint.new("#{@name}:sequence", version: @version, timeout_ms: @timeout_ms, task_queue: @task_queue)
+      @declared_steps.each_key { |k| sub.send(:mark_declared!, k) }
+      sub.send(:enter_scope!) if @in_scope
+      sub.instance_eval(&block)
+      sub.send(:declared_keys).each { |k| mark_declared!(k) }
+      @steps << { kind: "sequence", name: "sequence_#{@steps.length + 1}", children: sub.steps }
+      self
+    end
+
+    # The workflow's structure as data, as the worker registers it with the gateway (`CONTRACT.md`).
+    def to_blueprint
+      blueprint = {
+        "name" => @name,
+        "version" => @version,
+        "task_queue" => @task_queue,
+        "queries" => @queries.transform_values(&:to_s),
+        "nodes" => @steps.map { |s| blueprint_node(s) }
+      }
+      blueprint["timeout_ms"] = @timeout_ms unless @timeout_ms.nil? # the whole run's deadline, enforced by the engine
+      blueprint["continue_as_new"] = @continuation.dup unless @continuation.nil?
+      blueprint["changes"] = @changes.map { |id, bounds| { "id" => id }.merge(bounds) } unless @changes.empty?
+      blueprint["updates"] = @updates.transform_values { |u| update_spec(u) } unless @updates.empty?
+      blueprint
+    end
+
+    private def update_spec(update)
+      spec = {}
+      spec["handler"] = true unless update.handler.nil?
+      spec["validate"] = update.validate.expr unless update.validate.nil?
+      spec["message"] = update.message unless update.message.nil? || update.message.to_s.empty?
+      spec["input"] = JoobQ.template(update.input, "update #{update.name}.input") unless update.input.nil?
+      spec["result"] = JoobQ.template(update.result, "update #{update.name}.result") unless update.result.nil?
+      spec["timeout_ms"] = update.timeout_ms unless update.timeout_ms.nil?
+      spec
+    end
+
+    private def blueprint_node(node)
+      out = { "name" => node[:name], "kind" => node[:kind] }
+      case node[:kind]
+      when "parallel", "sequence", "scope"
+        out["children"] = node[:children].map { |c| blueprint_node(c) }
+        if node[:kind] == "scope"
+          out["timeout_ms"] = node[:timeout_ms] unless node[:timeout_ms].nil?
+          out["non_cancellable"] = true if node[:non_cancellable]
+        end
+      when "wait_for"
+        out.merge!("signal" => node[:signal], "timeout_ms" => node[:timeout_ms])
+      when "timer"
+        out["for_ms"] = node[:duration_ms]
+      when "child"
+        out["workflow"] = node[:workflow]
+        out["input"] = JoobQ.template(node[:input_spec], "#{node[:name]}.input") unless node[:input_spec].nil?
+      else
+        out["activity"] = node[:activity]
+        out["references"] = node[:input_spec].nil? ? ["${input}"] : JoobQ.collect_references(node[:input_spec])
+        %i[timeout_ms heartbeat_ms schedule_to_start_ms].each do |key|
+          out[key.to_s] = node[key] unless node[key].nil?
+        end
+        out["retry"] = blueprint_retry(node[:retry]) if node[:retry]
+      end
+      unless %w[parallel sequence scope].include?(node[:kind]) # a step, wait, timer or child can be undone, skipped, gated
+        if (c = node[:compensate])
+          out["compensate"] = { "activity" => c.activity,
+                                "references" => JoobQ.collect_references(c.input.nil? ? output(node[:name]) : c.input) }
+        end
+        out["only_if"] = node[:only_if].expr unless node[:only_if].nil?
+        if (g = node[:gate])
+          gate_out = { "change" => g.change }
+          gate_out["min"] = g.min unless g.min.nil?
+          gate_out["max"] = g.max unless g.max.nil?
+          out["gate"] = gate_out
+        end
+      end
+      out["after"] = node[:after].dup unless node[:after].nil? || node[:after].empty?
+      out
+    end
+
+    private def blueprint_retry(r)
+      out = { "attempts" => r.attempts, "initial_ms" => r.initial_ms, "backoff" => r.backoff, "maximum_ms" => r.maximum_ms }
+      out["non_retryable"] = r.non_retryable.map(&:to_s) unless r.non_retryable.nil? || r.non_retryable.empty?
+      out
+    end
+
+    # The handlers of this workflow's steps, by the activity name the engine sends them under (`<workflow>/<step>`,
+    # compensations `<workflow>/<node>/compensate`, for waits, timers and children too; a child has no handler of its
+    # own: the engine runs the child workflow; update handlers `<workflow>/@update/<name>`, which receive the task's
+    # payload as is: the engine resolved their input). Each runs its step once: the engine conducts the run (it
+    # retries, compensates and waits). A step's input is resolved against the run's input (the task's payload) and the
+    # outputs of the steps that completed (the task's checkpoints).
+    def activities
+      found = {}
+      visit = lambda do |nodes|
+        nodes.each do |node|
+          case node[:kind]
+          when "sequence", "parallel", "scope"
+            visit.call(node[:children])
+          else
+            found[JoobQ.activity_task_name(@name, node[:name])] = step_activity(node) if node[:kind] == "step"
+            if (comp = node[:compensate]) # a step, wait, timer or child can be undone
+              found[JoobQ.activity_task_name(@name, node[:name], compensate: true)] = compensation_activity(node, comp)
+            end
+          end
+        end
+      end
+      visit.call(@steps)
+      @updates.each_value do |u|
+        found[JoobQ.update_task_name(@name, u.name)] = u.handler unless u.handler.nil?
+      end
+      found
+    end
+
+    private def step_activity(node)
+      lambda do |workflow_input, ctx|
+        node[:handler].call(JoobQ.resolve_references(node[:input_spec], workflow_input, ctx.task["checkpoints"] || {}), ctx)
+      end
+    end
+
+    private def compensation_activity(node, comp)
+      lambda do |workflow_input, ctx|
+        spec = comp.input.nil? ? output(node[:name]) : comp.input
+        comp.handler.call(JoobQ.resolve_references(spec, workflow_input, ctx.task["checkpoints"] || {}), ctx)
+      end
+    end
+
+    private
+
+    def mark_declared!(key)
+      @declared_steps[key.to_s] = true
+    end
+
+    def declared_keys
+      @declared_steps.keys
+    end
+
+    def enter_scope!
+      @in_scope = true
+    end
+
+    def check_gate!(step_name, gate)
+      return if gate.nil? || gate.is_a?(Gate)
+
+      raise ArgumentError, "Step '#{step_name}' in workflow '#{@name}': gate must be made with gate(change, min:, max:)"
+    end
+
+    # `only_if` must be a reference to the input or to an earlier step.
+    def check_condition!(step_name, only_if)
+      return if only_if.nil?
+      unless only_if.is_a?(DataRef)
+        raise ArgumentError, "Step '#{step_name}' in workflow '#{@name}': only_if must be a reference (input, output, ref)"
+      end
+
+      JoobQ.extract_step_dependencies(only_if).each do |dep|
+        unless @declared_steps.key?(dep)
+          raise ArgumentError, "Step '#{step_name}' in workflow '#{@name}': only_if refers to unknown or downstream step '#{dep}'"
+        end
+      end
+    end
+
+    def validate_and_register!(step_name, input_spec, after = [])
+      raise ArgumentError, "Duplicate step '#{step_name}' in workflow '#{@name}'" if @declared_steps.key?(step_name)
+
+      after.each do |dep|
+        unless @declared_steps.key?(dep)
+          raise ArgumentError, "Step '#{step_name}' in workflow '#{@name}' waits (after:) for unknown or downstream step '#{dep}'"
+        end
+      end
+      JoobQ.extract_step_dependencies(input_spec).each do |dep|
+        unless @declared_steps.key?(dep)
+          raise ArgumentError, "Step '#{step_name}' references unknown or downstream step '#{dep}'"
+        end
+      end
+      mark_declared!(step_name)
+    end
+  end
+
+  # The activity the engine sends a step (or its compensation) of an SDK workflow under.
+  def self.activity_task_name(workflow_name, step, compensate: false)
+    compensate ? "#{workflow_name}/#{step}/compensate" : "#{workflow_name}/#{step}"
+  end
+
+  # The activity the engine sends an update handler of an SDK workflow under.
+  def self.update_task_name(workflow_name, update)
+    "#{workflow_name}/@update/#{update}"
+  end
+
+  # A workflow blueprint. `timeout_ms` is the whole run's deadline (none by default), enforced by the engine.
+  def self.workflow(name, version: 1, timeout_ms: nil, task_queue: "workflows", &block)
+    bp = WorkflowBlueprint.new(name, version: version, timeout_ms: timeout_ms, task_queue: task_queue)
+    bp.instance_eval(&block) if block
+    bp
+  end
+
+  class ExecutionContext
+    attr_reader :task, :worker_id, :client, :context, :lease_ttl_ms
+
+    def initialize(task, worker_id, client, lease_ttl_ms = 30_000, transport = nil)
+      @transport = transport
+      @task = task
+      @worker_id = worker_id
+      @client = client
+      @lease_ttl_ms = lease_ttl_ms
+      @context = (task["context"] || {}).dup
+      @last_beat_ms = nil
+      @beat_cancel = false
+    end
+
+    def attempt
+      (@task["attempt"] || 1).to_i
+    end
+
+    def dedupe_key
+      wf = @task["workflow_id"] || @task["id"]
+      st = @task["step_id"] || @task["name"]
+      "#{wf}:#{st}:#{attempt}"
+    end
+
+    # An engine step's heartbeat timeout (`task["heartbeat_ms"]`, nil for most tasks): call `heartbeat` more often.
+    def heartbeat_ms
+      @task["heartbeat_ms"]
+    end
+
+    # True when the run was cancelled. In a running worker it answers what the last lease renewal said without waiting
+    # for the gateway; the worker renews every lease on its own. For a step with `heartbeat_ms` it also
+    # tells the engine the step is alive (at most every third of `heartbeat_ms`): the worker's own renewals do not, so a
+    # handler that stops calling this is timed out.
+    def heartbeat(lease_ttl_ms: @lease_ttl_ms)
+      if (beat_ms = heartbeat_ms) && beat_ms.to_i.positive?
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        if @last_beat_ms.nil? || now - @last_beat_ms >= [100, beat_ms.to_i / 3].max
+          @last_beat_ms = now
+          begin
+            res = @client.heartbeat_task(@task["lease_token"], worker_id: @worker_id, lease_ttl_ms: lease_ttl_ms)
+            @beat_cancel = res.is_a?(Hash) && res["cancel_requested"] == true
+          rescue StandardError
+            nil # the next window's beat tries again; the engine's deadline decides
+          end
+        end
+        return true if @beat_cancel
+      end
+      return @transport.cancel_requested?(@task["lease_token"]) if @transport
+
+      res = @client.heartbeat_task(@task["lease_token"], worker_id: @worker_id, lease_ttl_ms: lease_ttl_ms)
+      res["cancel_requested"] == true
+    end
+
+    def enqueue(job_cls, payload = {}, context: {}, **opts)
+      @client.enqueue(job_cls, payload, context: @context.merge(context), **opts)
+    end
+
+    def enqueue_job(queue:, job_type:, payload: {}, context: {}, **opts)
+      @client.enqueue_job(queue: queue, job_type: job_type, payload: payload, context: @context.merge(context), **opts)
+    end
+
+    def start(workflow_def, input: nil, context: {}, **opts)
+      @client.start(workflow_def, input: input, context: @context.merge(context), **opts)
+    end
+
+    def start_workflow(name:, input: nil, context: {}, **opts)
+      @client.start_workflow(name: name, input: input, context: @context.merge(context), **opts)
+    end
+
+    def register_schedule(name, job_type, queue, **opts)
+      @client.register_schedule(name, job_type, queue, **opts)
+    end
+
+    def rate_limit(key, limit, period_ms)
+      @client.rate_limit(key, limit, period_ms)
+    end
+
+    # `Client#create_batch`; the members and callbacks carry this handler's context.
+    def create_batch(jobs, context: {}, **opts)
+      @client.create_batch(jobs, context: @context.merge(context), **opts)
+    end
+
+    def get_batch(id)
+      @client.get_batch(id)
+    end
+
+    def describe_workflow(id)
+      @client.describe_workflow(id)
+    end
+
+    def workflow_result(id, wait_ms: 0)
+      @client.workflow_result(id, wait_ms: wait_ms)
+    end
+
+    def workflow_history(id, after_seq: 0, limit: 200)
+      @client.workflow_history(id, after_seq: after_seq, limit: limit)
+    end
+
+    def query_workflow(id, name)
+      @client.query_workflow(id, name)
+    end
+
+    def signal_workflow(id:, name:, payload: nil)
+      @client.signal_workflow(id: id, name: name, payload: payload)
+    end
+
+    def update_workflow(id, name, input: nil, update_id: nil, wait_ms: nil)
+      @client.update_workflow(id, name, input: input, update_id: update_id, wait_ms: wait_ms)
+    end
+
+    def upsert_workflow_attributes(id, set: nil, remove: nil)
+      @client.upsert_workflow_attributes(id, set: set, remove: remove)
+    end
+  end
+
+  # The fields that report `error` to the gateway (`fail_task`, and a "fail" item of `ack_tasks`).
+  def self.failure(error, retryable: true)
+    frames = Array(error.backtrace).map do |line|
+      if line =~ /\A(.+):(\d+):in [`'](.+)'\z/
+        { file: Regexp.last_match(1), line: Regexp.last_match(2).to_i, function: Regexp.last_match(3) }
+      else
+        { file: line, line: 0, function: "unknown" }
+      end
+    end
+    message = error.message.to_s
+    message = error.class.name if message.empty?
+    {
+      error_class: error.class.name,
+      error_message: message[0, 4000],
+      retryable: retryable,
+      sdk_language: "ruby",
+      stack_frames: frames,
+      raw_stacktrace: Array(error.backtrace).join("\n")[0, 4000]
+    }
+  end
+
+  class Client
+    attr_reader :gateway_url, :token
+    # Seconds one gateway call may take. A worker lowers it (`Worker#initialize`): a call that hangs for longer than a
+    # lease would let every lease the worker holds expire while its tasks still run.
+    attr_accessor :request_timeout
+
+    def initialize(gateway_url:, token:, context_provider: nil)
+      @gateway_url = gateway_url.sub(%r{/+\z}, "")
+      @token = token
+      @request_timeout = 60
+      @context_provider = context_provider
+      @uri = URI.parse(@gateway_url)
+      @connection_key = :"joobq_http_#{object_id}" # one kept-alive connection per thread
+    end
+
+    # Enqueues many jobs with POST /sdk/jobs/batch (500 per call). Each item is `[JobClass, payload]`,
+    # `[JobClass, payload, { delay_ms:, jid:, unique_key: }]` or a hash of `enqueue_job` arguments. Answers one
+    # `{"jid", "queue", "status"}` per job, in order.
+    def enqueue_many(jobs, context: {})
+      bodies = jobs.map { |item| item_body(item, context) }
+      bodies.each_slice(500).flat_map { |slice| post("/api/v1/sdk/jobs/batch", { jobs: slice })["jobs"] || [] }
+    end
+
+    # Creates a Pro batch with POST /sdk/batches: 1 to 1000 member jobs (the shapes `enqueue_many` takes, without a
+    # `unique_key`) and callback jobs (the same shapes). `on_failure` is enqueued at the first dead member,
+    # `on_complete` once every member completed or was dead-lettered, `on_success` then too when none was dead; each
+    # once, with `{"batch" => {id, kind, total, succeeded, failed}}` merged into its payload. Answers
+    # `{"batch_id", "total", "jobs"}`; 402 pro_required without a Pro licence.
+    def create_batch(jobs, on_complete: nil, on_success: nil, on_failure: nil, description: nil, context: {})
+      body = { description: description, jobs: jobs.map { |item| batch_item_body(item, context) } }
+      { on_complete: on_complete, on_success: on_success, on_failure: on_failure }.each do |kind, callback|
+        body[kind] = batch_item_body(callback, context) unless callback.nil?
+      end
+      post("/api/v1/sdk/batches", body)
+    end
+
+    # A Pro batch's progress with GET /sdk/batches/:id: `{"batch_id", "description", "status", "total", "pending",
+    # "succeeded", "failed", "created_at", "finished_at"}`; `status` is pending, then success (no member dead) or
+    # complete.
+    def get_batch(id)
+      get("/api/v1/sdk/batches/#{segment(id)}")
+    end
+
+    # One member or callback of `create_batch`: the batch's `context` merged key by key under the job's own (the job's
+    # keys win).
+    def batch_item_body(item, context)
+      base = context || {}
+      if item.is_a?(Hash)
+        spec = item.transform_keys(&:to_sym)
+        item_body(spec.merge(context: base.merge(spec[:context] || {})), base)
+      else
+        job_cls, payload, opts = item
+        opts = (opts || {}).transform_keys(&:to_sym)
+        item_body([job_cls, payload, opts.merge(context: base.merge(opts[:context] || {}))], base)
+      end
+    end
+
+    # One job of `enqueue_many` or `create_batch`: a hash of `enqueue_job` arguments or `[JobClass, payload, opts]`.
+    def item_body(item, context)
+      if item.is_a?(Hash)
+        spec = item.transform_keys(&:to_sym)
+        job_body(context: context, **spec)
+      else
+        job_cls, payload, opts = item
+        opts = (opts || {}).transform_keys(&:to_sym)
+        job_body(queue: job_cls.queue, job_type: job_cls.job_name, payload: payload || {},
+                 context: opts.fetch(:context, context), jid: opts[:jid], max_retries: job_cls.retries,
+                 delay_ms: opts.fetch(:delay_ms, 0), run_at_ms: opts[:run_at_ms],
+                 expires_ms: opts[:expires_ms], timeout_ms: opts[:timeout_ms],
+                 encrypt_fields: job_cls.encrypted_fields,
+                 unique_key: opts[:unique_key], unique_mode: opts.fetch(:unique_mode, "while_locked"),
+                 unique_ttl_ms: job_cls.unique_ttl_ms)
+      end
+    end
+
+    # `enqueue` on a thread of its own: `value` on the returned thread waits for `{"jid", "queue", "status"}` (or raises
+    # the error). `enqueue` is the call that answers only once the job is stored.
+    def enqueue_async(job_cls, payload = {}, **opts)
+      Thread.new { enqueue(job_cls, payload, **opts) }.tap { |t| t.report_on_exception = false }
+    end
+
+    def enqueue(job_cls, payload = {}, context: {}, jid: nil, delay_ms: 0, run_at_ms: nil, expires_ms: nil, timeout_ms: nil, unique_key: nil, unique_mode: "while_locked", unique_ttl_ms: nil)
+      enqueue_job(
+        queue: job_cls.queue,
+        job_type: job_cls.job_name,
+        payload: payload,
+        context: context,
+        jid: jid,
+        max_retries: job_cls.retries,
+        delay_ms: delay_ms,
+        run_at_ms: run_at_ms,
+        expires_ms: expires_ms,
+        timeout_ms: timeout_ms,
+        encrypt_fields: job_cls.encrypted_fields,
+        unique_key: unique_key,
+        unique_mode: unique_mode,
+        unique_ttl_ms: unique_ttl_ms.nil? ? job_cls.unique_ttl_ms : unique_ttl_ms
+      )
+    end
+
+    def enqueue_job(**opts)
+      post("/api/v1/sdk/jobs", job_body(**opts))
+    end
+
+    def job_body(queue:, job_type:, payload: {}, context: {}, jid: nil, max_retries: 3, delay_ms: 0, run_at_ms: nil, expires_ms: nil, timeout_ms: nil, encrypt_fields: [], unique_key: nil, unique_mode: "while_locked", unique_ttl_ms: nil)
+      {
+        queue: queue,
+        job_type: job_type,
+        payload: payload,
+        context: resolve_context(context),
+        jid: jid,
+        max_retries: max_retries,
+        delay_ms: delay_ms,
+        run_at_ms: run_at_ms,
+        expires_ms: expires_ms,
+        timeout_ms: timeout_ms,
+        encrypt_fields: encrypt_fields,
+        unique_key: unique_key,
+        unique_mode: unique_mode,
+        unique_ttl_ms: unique_ttl_ms
+      }
+    end
+
+    def start(workflow_def, input: nil, context: {}, id: nil, search_attributes: nil, build: nil)
+      start_workflow(
+        name: workflow_def.name,
+        input: input,
+        context: context,
+        id: id,
+        search_attributes: search_attributes,
+        build: build
+      )
+    end
+
+    def start_workflow(name:, input: nil, context: {}, id: nil, search_attributes: nil, build: nil)
+      post("/api/v1/sdk/workflows", {
+        name: name,
+        input: input,
+        context: resolve_context(context),
+        id: id,
+        search_attributes: search_attributes,
+        build: build
+      })
+    end
+
+    # Registers a recurring schedule with POST /sdk/schedules. Pass exactly one of `cron:` or `every:`
+    # (`every` is "<count> <unit>", e.g. "3 seconds"). Answers `{"id", "name", "kind", "created"}`.
+    def register_schedule(name, job_type, queue, cron: nil, every: nil, timezone: "UTC", payload: nil, max_retries: 3, encrypt_fields: [], unique_key: nil)
+      post("/api/v1/sdk/schedules", {
+        name: name,
+        kind: "job",
+        cron: cron,
+        every: every,
+        timezone: timezone,
+        queue: queue,
+        job_type: job_type,
+        payload: payload || {},
+        max_retries: max_retries,
+        encrypt_fields: encrypt_fields,
+        unique_key: unique_key
+      })
+    end
+
+    # Consumes one unit of a Pro rate-limit window with POST /sdk/rate-limit. Answers
+    # `{"allowed" => Bool, "retry_after_ms" => Int}`.
+    def rate_limit(key, limit, period_ms)
+      post("/api/v1/sdk/rate-limit", { key: key, limit: limit, period_ms: period_ms })
+    end
+
+    def signal_workflow(id:, name:, payload: nil)
+      post("/api/v1/sdk/workflows/#{segment(id)}/signal", {
+        name: name,
+        payload: payload
+      })
+    end
+
+    # Sends an update to a running workflow's update handler `name` (Pro; 402 without a licence) with
+    # POST /sdk/workflows/:id/updates and waits up to `wait_ms` (100 to 30000, default 10000) for its outcome. Answers
+    # `{"update_id", "name", "status", "result", "error", "reason", "message"}`: `status` is completed, rejected
+    # (validate failed: `reason`, `message`), failed, or accepted (a 202) when the handler had not answered in time
+    # (send again with the same `update_id` to wait for the same update).
+    def update_workflow(id, name, input: nil, update_id: nil, wait_ms: nil)
+      body = { name: name, input: input }
+      body[:update_id] = update_id unless update_id.nil?
+      body[:wait_ms] = Integer(wait_ms) unless wait_ms.nil?
+      post("/api/v1/sdk/workflows/#{segment(id)}/updates", body)
+    end
+
+    # One run (Pro; 402 without a licence) with GET /sdk/workflows/:id. Answers `{"id", "name", "status", "closed",
+    # "run", "started_at", "closed_at", "continued_to", "output", "failure", "attributes", "queries"}`; payload fields
+    # with secret-looking names are masked, as in the console.
+    def describe_workflow(id)
+      get("/api/v1/sdk/workflows/#{segment(id)}")
+    end
+
+    # The run at the end of the workflow's continue-as-new chain (Pro; 402 without a licence) with
+    # GET /sdk/workflows/:id/result, waiting up to `wait_ms` (at most 25000) for it to close. Same shape as
+    # `describe_workflow`; `"closed" => false` means it was still open when the wait ended.
+    def workflow_result(id, wait_ms: 0)
+      get("/api/v1/sdk/workflows/#{segment(id)}/result?wait_ms=#{Integer(wait_ms)}")
+    end
+
+    # The run's events after `after_seq`, at most `limit`, oldest first (Pro; 402 without a licence), with
+    # GET /sdk/workflows/:id/history. Answers the array of events.
+    def workflow_history(id, after_seq: 0, limit: 200)
+      res = get("/api/v1/sdk/workflows/#{segment(id)}/history?after_seq=#{Integer(after_seq)}&limit=#{Integer(limit)}")
+      res["items"] || []
+    end
+
+    # Asks the run a read-only question (Pro; 402 without a licence) with POST /sdk/workflows/:id/query. Answers the
+    # query's result (any JSON value).
+    def query_workflow(id, name)
+      post("/api/v1/sdk/workflows/#{segment(id)}/query", { name: name })["result"]
+    end
+
+    # Sets and/or removes search attributes of the workflow's open run (Pro; 402 without a licence) with
+    # POST /sdk/workflows/:id/search-attributes. Answers `{"id", "attributes"}`.
+    def upsert_workflow_attributes(id, set: nil, remove: nil)
+      post("/api/v1/sdk/workflows/#{segment(id)}/search-attributes", { set: set, remove: remove })
+    end
+
+    # Sends a workflow's blueprint; the gateway keeps each new content hash (`created`) and ignores a known one.
+    def register_blueprint(workflow_def, worker_id: nil)
+      post("/api/v1/sdk/blueprints", {
+        name: workflow_def.name,
+        sdk_language: "ruby",
+        worker_id: worker_id,
+        blueprint: workflow_def.to_blueprint
+      })
+    end
+
+    def register_worker(worker_id:, task_queues:, concurrency: 4, service_name: nil, team: nil)
+      post("/api/v1/sdk/workers/register", {
+        worker_id: worker_id,
+        sdk_language: "ruby",
+        sdk_version: SDK_VERSION,
+        service_name: service_name,
+        team: team || ENV["JOOBQ_TEAM"],
+        host: Socket.gethostname,
+        pid: Process.pid,
+        task_queues: task_queues,
+        concurrency: concurrency,
+        delivery_mode: "poll"
+      })
+    end
+
+    def deregister_worker(worker_id:)
+      post("/api/v1/sdk/workers/#{URI.encode_www_form_component(worker_id)}/deregister", {})
+    end
+
+    def poll_tasks(worker_id:, task_queues:, max_tasks: 1, timeout_ms: 0, lease_ttl_ms: 30_000)
+      res = post("/api/v1/sdk/tasks/poll", {
+        worker_id: worker_id,
+        task_queues: task_queues,
+        max_tasks: max_tasks,
+        timeout_ms: timeout_ms,
+        lease_ttl_ms: lease_ttl_ms
+      })
+      res["tasks"] || []
+    end
+
+    def heartbeat_task(lease_token, worker_id:, lease_ttl_ms: 30_000)
+      post("/api/v1/sdk/tasks/#{URI.encode_www_form_component(lease_token)}/heartbeat", {
+        worker_id: worker_id,
+        lease_ttl_ms: lease_ttl_ms
+      })
+    end
+
+    def complete_task(lease_token, worker_id:, output: nil)
+      post("/api/v1/sdk/tasks/#{URI.encode_www_form_component(lease_token)}/complete", {
+        worker_id: worker_id,
+        output: output
+      })
+    end
+
+    def fail_task(lease_token, worker_id:, error:, retryable: true)
+      post("/api/v1/sdk/tasks/#{URI.encode_www_form_component(lease_token)}/fail",
+           { worker_id: worker_id }.merge(JoobQ.failure(error, retryable: retryable)))
+    end
+
+    # Settles up to 100 leases in one call (POST /sdk/tasks/ack): items are `{token:, outcome: "complete", output:}`
+    # or `{token:, outcome: "fail", **JoobQ.failure(error)}`; each gets its own result.
+    def ack_tasks(worker_id:, items:)
+      post("/api/v1/sdk/tasks/ack", { worker_id: worker_id, items: items })
+    end
+
+    # Renews many leases in one call (POST /sdk/tasks/heartbeat): `leases` are `{token:}`.
+    def heartbeat_tasks(worker_id:, leases:, lease_ttl_ms: 30_000)
+      post("/api/v1/sdk/tasks/heartbeat", { worker_id: worker_id, lease_ttl_ms: lease_ttl_ms, leases: leases })
+    end
+
+    private
+
+    def resolve_context(explicit)
+      ambient = @context_provider ? (@context_provider.call || {}) : {}
+      ambient.merge(explicit || {})
+    end
+
+    # This thread's kept-alive connection to the gateway (Net::HTTP honours the proxy environment variables).
+    def connection
+      http = Thread.current[@connection_key]
+      return http if http&.started?
+
+      http = Net::HTTP.new(@uri.hostname, @uri.port)
+      http.use_ssl = @uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = @request_timeout
+      http.write_timeout = @request_timeout
+      http.keep_alive_timeout = 30
+      http.start
+      Thread.current[@connection_key] = http
+    end
+
+    def drop_connection
+      http = Thread.current[@connection_key]
+      Thread.current[@connection_key] = nil
+      http&.finish if http&.started?
+    rescue IOError
+      nil
+    end
+
+    # A workflow id as one percent-encoded URL path segment.
+    def segment(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    def post(path, body)
+      req = Net::HTTP::Post.new("#{@uri.path}#{path}")
+      req["Content-Type"] = "application/json"
+      req.body = JSON.generate(body)
+      send_request(req)
+    end
+
+    def get(path)
+      send_request(Net::HTTP::Get.new("#{@uri.path}#{path}"))
+    end
+
+    def send_request(req)
+      req["Authorization"] = "Bearer #{@token}"
+      attempts = 0
+      begin
+        reused = !Thread.current[@connection_key].nil?
+        res = connection.request(req)
+      rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, IOError => e
+        drop_connection
+        attempts += 1
+        # The gateway closed the kept-alive connection while it was idle: once more, on a new one.
+        retry if reused && attempts == 1
+        raise e
+      rescue StandardError
+        drop_connection
+        raise
+      end
+      drop_connection if res["connection"].to_s.downcase == "close"
+      raise GatewayError.new(res.code.to_i, res.body) unless res.code.to_i.between?(200, 299)
+
+      res.body.to_s.empty? ? {} : JSON.parse(res.body)
+    end
+  end
+
+  # Every gateway call of a running worker, on threads of its own, so a handler thread never waits for HTTP: a poller
+  # keeps a small buffer of leased tasks (free slots plus `prefetch`), an acker sends the outcomes handlers queue
+  # (POST /sdk/tasks/ack, up to 100 per call after at most `ack_linger_ms`, retried while the gateway is unavailable; a
+  # task stays leased until its outcome is acknowledged; when `ack_buffer` outcomes wait, handlers wait), and a
+  # heartbeater renews every lease the worker holds in one call (POST /sdk/tasks/heartbeat).
+  class Transport
+    attr_reader :ready, :lock, :changed
+    attr_accessor :held
+
+    def initialize(ack_buffer)
+      @ready = Queue.new
+      @acks = SizedQueue.new(ack_buffer)
+      @lock = Mutex.new
+      @changed = ConditionVariable.new
+      @held = 0 # buffered + running
+      @leased = {}
+      @cancelled = {}
+      @beat_wake = Queue.new
+      @ack_done = false
+      @give_up = false
+      @beat_stop = false
+    end
+
+    attr_writer :ack_done, :give_up
+
+    # Ends the heartbeater at once instead of at its next renewal.
+    def stop_heartbeat
+      @beat_stop = true
+      @beat_wake << true
+    end
+
+    def give_up?
+      @give_up
+    end
+
+    def leased(tasks)
+      @lock.synchronize do
+        tasks.each { |t| @leased[t["lease_token"]] = true }
+        @held += tasks.size
+      end
+      tasks.each { |t| @ready << t }
+    end
+
+    def settle(item)
+      loop do
+        return if @acks.push(item, timeout: 0.5)
+        return if @give_up # left to its lease
+      end
+    end
+
+    def cancel_requested?(token)
+      @lock.synchronize { @cancelled[token] == true }
+    end
+
+    def release(token)
+      @lock.synchronize do
+        @leased.delete(token)
+        @cancelled.delete(token)
+      end
+    end
+
+    def ack(client, worker_id, linger)
+      loop do
+        first = @acks.pop(timeout: 0.1)
+        if first.nil?
+          return if @ack_done
+
+          next
+        end
+        batch = [first]
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + linger
+        while batch.size < 100
+          left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          more = left.positive? ? @acks.pop(timeout: left) : (@acks.pop(true) rescue nil)
+          break if more.nil?
+
+          batch << more
+        end
+        send_acks(client, worker_id, batch)
+      end
+    end
+
+    def send_acks(client, worker_id, batch)
+      delay = 0.25
+      loop do
+        begin
+          client.ack_tasks(worker_id: worker_id, items: batch)
+          break # a refused item (its lease is gone) is not sent again either
+        rescue GatewayError => e
+          if e.status == 413 && batch.size > 1 # too large for one call: in halves
+            half = batch.size / 2
+            send_acks(client, worker_id, batch[0, half])
+            send_acks(client, worker_id, batch[half..])
+            return
+          end
+          if e.status < 500 && e.status != 429
+            warn "joobq: the gateway refused #{batch.size} outcomes: #{e.message}"
+            break
+          end
+        rescue StandardError
+          nil
+        end
+        break if @give_up # shutting down: the leases bring these tasks back
+
+        sleep delay
+        delay = [delay * 2, 5.0].min
+      end
+      batch.each { |item| release(item[:token]) }
+    end
+
+    def heartbeat(client, worker_id, lease_ttl_ms, &register)
+      every = [lease_ttl_ms / 3000.0, 0.5].max
+      now = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      last_register = now.call
+      until @beat_stop
+        @beat_wake.pop(timeout: every)
+        return if @beat_stop
+
+        tokens = @lock.synchronize { @leased.keys }
+        tokens.each_slice(500) do |chunk|
+          res = client.heartbeat_tasks(worker_id: worker_id, leases: chunk.map { |t| { token: t } }, lease_ttl_ms: lease_ttl_ms)
+          @lock.synchronize do
+            Array(res["leases"]).each do |lease|
+              token = lease["lease_token"]
+              if lease["error"]
+                @leased.delete(token) # gone: its outcome will be refused, nothing to renew
+              elsif @leased.key?(token)
+                @cancelled[token] = lease["cancel_requested"] == true
+              end
+            end
+          end
+        rescue StandardError
+          nil # renewed with the next heartbeat
+        end
+        if now.call - last_register > 10
+          register.call
+          last_register = now.call
+        end
+      end
+    end
+  end
+
+  # In-app worker: runs up to `concurrency` jobs and workflow steps at once on threads inside the booted application,
+  # and on SIGTERM/SIGINT (or `stop`) drains the running tasks, sends their outcomes and deregisters. Its gateway calls
+  # run beside the handlers (`Transport`), never in their way.
+  class Worker
+    attr_reader :task_queues
+
+    def initialize(client:, worker_id:, task_queues: [], concurrency: 4, service_name: nil, team: nil,
+                   lease_ttl_ms: 30_000, poll_timeout_ms: 5_000, drain_timeout: 30.0, prefetch: nil, ack_buffer: nil,
+                   ack_linger_ms: 5)
+      @client = client
+      @worker_id = worker_id
+      @task_queues = Array(task_queues).dup
+      @concurrency = [concurrency.to_i, 1].max
+      @service_name = service_name
+      @team = team
+      @lease_ttl_ms = lease_ttl_ms
+      @poll_timeout_ms = poll_timeout_ms
+      @drain_timeout = drain_timeout
+      # One hung call must not outlast the leases: a poll waits `poll_timeout_ms` at the gateway, and a sixth of a lease
+      # on top keeps a renewal that hangs well inside the lease (10 s with the defaults).
+      bound = (poll_timeout_ms / 1000.0) + (lease_ttl_ms / 6000.0)
+      current = client.respond_to?(:request_timeout) ? client.request_timeout : nil
+      client.request_timeout = bound if current.is_a?(Numeric) && current > bound
+      # Leases held beyond the free slots, so a handler that finishes finds its next task at once.
+      @prefetch = [prefetch.nil? ? [@concurrency / 2, 1].max : prefetch.to_i, 0].max
+      # Outcomes queued for the acker before handlers wait for it.
+      @ack_buffer = [ack_buffer.nil? ? 4 * @concurrency : ack_buffer.to_i, 1].max
+      @ack_linger = [ack_linger_ms.to_f, 0].max / 1000.0
+      @handlers = {}
+      @middlewares = []
+      @stopping = false
+      @workflows = {}
+      @blueprints_sent = {}
+      @transport = nil
+    end
+
+    def use(&block)
+      @middlewares << block
+      self
+    end
+
+    def register_job(job_cls)
+      @task_queues << job_cls.queue if job_cls.respond_to?(:queue) && !@task_queues.include?(job_cls.queue)
+      @handlers[job_cls.job_name] = JoobQ.normalize_callable(job_cls)
+      self
+    end
+
+    def register_workflow(workflow_def)
+      if workflow_def.respond_to?(:task_queue) && !@task_queues.include?(workflow_def.task_queue)
+        @task_queues << workflow_def.task_queue
+      end
+      @workflows[workflow_def.name] = workflow_def
+      # The engine conducts the workflow's runs and sends each step as its own task.
+      @handlers.merge!(workflow_def.activities) if workflow_def.respond_to?(:activities)
+      self
+    end
+
+    def handle_job(job_type, &block)
+      @handlers[job_type] = block
+      self
+    end
+
+    # Says once, on stderr, that the gateway refuses this worker (a wrong or rotated token, no Pro key): it goes on
+    # retrying, and without this line it would sit idle with nothing in its output.
+    def report_refusal(what, error)
+      status = error.respond_to?(:status) ? error.status : nil
+      return unless status.is_a?(Integer) && status >= 400 && status < 500 && ![408, 429].include?(status)
+      return if @refused == status
+
+      @refused = status
+      warn "joobq: the gateway refuses this worker (#{what}): #{error.message}. Retrying; check the SDK token and the server's licence."
+    end
+
+    def process_task(task)
+      token = task["lease_token"]
+      handler = @handlers[task["name"]]
+      unless handler
+        settle(token, { outcome: "fail" }.merge(JoobQ.failure(NonRetryableError.new("No handler registered for #{task['name']}"), retryable: false)))
+        return { "status" => "failed" }
+      end
+
+      # Everything that can raise for this task is inside the begin: a task with no outcome keeps its lease renewed for
+      # ever. Exception, not StandardError, so that a handler raising a ScriptError (NotImplementedError in a stub)
+      # fails its task instead of killing its thread; signals still pass.
+      begin
+        ctx = ExecutionContext.new(task, @worker_id, @client, @lease_ttl_ms, @transport)
+
+        runner = @middlewares.reverse.inject(-> { handler.call(task["payload"], ctx) }) do |next_fn, mw|
+          -> { mw.call(ctx, next_fn) }
+        end
+
+        output = runner.call
+      rescue SignalException
+        raise
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        retryable = !e.is_a?(NonRetryableError)
+        settle(token, { outcome: "fail" }.merge(JoobQ.failure(e, retryable: retryable)))
+        return { "status" => "failed" }
+      end
+      settle(token, { outcome: "complete", output: output })
+      { "status" => "completed", "output" => output }
+    end
+
+    # Stops polling; `start` returns once the running tasks have finished and their outcomes are acknowledged (or
+    # `drain_timeout` passed).
+    def stop
+      @stopping = true
+    end
+
+    # Runs until SIGTERM/SIGINT or `stop`, then drains the running tasks, sends their outcomes and deregisters.
+    def start(install_signal_handlers: true)
+      if install_signal_handlers
+        %w[TERM INT].each { |sig| Signal.trap(sig) { @stopping = true } }
+      end
+      backoff = 0.25
+      until @stopping
+        begin
+          register
+          break
+        rescue StandardError
+          sleep(backoff)
+          backoff = [backoff * 2, 5.0].min
+        end
+      end
+      t = Transport.new(@ack_buffer)
+      @transport = t
+      threads = Array.new(@concurrency) do
+        Thread.new do
+          while (task = t.ready.pop)
+            begin
+              process_task(task)
+            rescue StandardError => e
+              warn "joobq: task #{task['id']} could not be settled: #{e.message}"
+            ensure
+              t.lock.synchronize do
+                t.held -= 1
+                t.changed.broadcast
+              end
+            end
+          end
+        end
+      end
+      acker = Thread.new { t.ack(@client, @worker_id, @ack_linger) }
+      beat = Thread.new do
+        t.heartbeat(@client, @worker_id, @lease_ttl_ms) do
+          register unless @stopping
+        rescue StandardError
+          nil
+        end
+      end
+
+      capacity = @concurrency + @prefetch
+      backoff = 0.25
+      until @stopping
+        room = t.lock.synchronize do
+          t.changed.wait(t.lock, 0.5) while t.held >= capacity && !@stopping
+          capacity - t.held
+        end
+        break if @stopping
+
+        begin
+          tasks = @client.poll_tasks(worker_id: @worker_id, task_queues: @task_queues, max_tasks: [room, 100].min,
+                                     timeout_ms: @poll_timeout_ms, lease_ttl_ms: @lease_ttl_ms)
+          backoff = 0.25
+          @refused = nil
+        rescue StandardError => e
+          report_refusal("poll for tasks", e)
+          sleep(backoff + rand * 0.1)
+          backoff = [backoff * 2, 5.0].min
+          next
+        end
+        t.leased(tasks)
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @drain_timeout
+      left = -> { deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      t.lock.synchronize { t.changed.wait(t.lock, [left.call, 0.05].min) while t.held.positive? && left.call.positive? }
+      threads.size.times { t.ready << nil }
+      t.ack_done = true
+      unless acker.join([left.call, 0.01].max)
+        t.give_up = true
+        acker.join(5)
+      end
+      t.give_up = true
+      t.stop_heartbeat
+      beat.join(5)
+      @transport = nil
+      begin
+        @client.deregister_worker(worker_id: @worker_id)
+      rescue StandardError
+        nil
+      end
+    end
+    alias run start
+
+    private
+
+    # Hands the outcome to the acker (waiting while its queue is full); outside `start` it is sent here.
+    def settle(token, item)
+      item = item.merge(token: token)
+      if @transport
+        @transport.settle(item)
+      else
+        report { @client.ack_tasks(worker_id: @worker_id, items: [item]) }
+      end
+    end
+
+    def register
+      register_blueprints # first: a worker that shows up has its blueprints in
+      @client.register_worker(worker_id: @worker_id, task_queues: @task_queues, concurrency: @concurrency,
+                              service_name: @service_name, team: @team)
+    end
+
+    # Registers every workflow's blueprint once; one the gateway refuses (4xx) is logged and not sent again.
+    def register_blueprints
+      @workflows.each do |name, wf|
+        next if @blueprints_sent[name]
+
+        begin
+          @client.register_blueprint(wf, worker_id: @worker_id)
+        rescue GatewayError => e
+          raise if e.status >= 500
+
+          warn "joobq: blueprint of #{name} refused: #{e.message}"
+        end
+        @blueprints_sent[name] = true
+      end
+    end
+
+    # Sends an outcome, retrying while the gateway is unavailable; a lost outcome is left to the lease.
+    def report
+      delay = 0.25
+      6.times do
+        yield
+        return
+      rescue GatewayError => e
+        return if e.status < 500
+
+        sleep delay
+        delay = [delay * 2, 5.0].min
+      rescue StandardError
+        sleep delay
+        delay = [delay * 2, 5.0].min
+      end
+    end
+  end
+
+end