batchwatch 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfefddebcc183a5e63b03b570caa3d183103d4b661f90a617779241306201d6b
-  data.tar.gz: 02de063b1c8f22d8d2a5f93f2c3dda990b482af905ab811c5a630eb029289279
+  metadata.gz: d76f91aceeae04301676b3b43f48d94ee8cac41b83dede45b38a7d770c8aab1b
+  data.tar.gz: '0493dd22486b9768eb7910e8ed595fecf51efc6419111acd1f0ca8e4d3f8838e'
 SHA512:
-  metadata.gz: e06032ef12b72d4d8213ae27271723afcbbb87a17087304ecda1ea999c8fe65777fc87a39b773cfc58faed151e4d685e94127e4186c4792d59bfd08af553e6fc
-  data.tar.gz: 8134786ba93b55272cbdf87db36e02581b600d229aa5ef08d8275810c93c29344ae583193b6488d8036f14787dac812a39eb3b356bc61132a7c7fc700c728908
+  metadata.gz: 64057bdf78674a4152d026ad69fecec08c549fb0dbd84cd8d04fd48dc858f2700a4fe76b9a2f9bbcf9eaede4ad6b963a8876931405dab47f5153e766d8ccead4
+  data.tar.gz: 2223af0f8679cb1219994f2f246af43616e4fc64f175cbed5e8f590e8739c18f585f8e5a7ad5c04cfccf98360536c4da67ca54065fbc4e8f22a79b37414983be

data/README.md

@@ -12,15 +12,11 @@ No dependencies. The standard library — `net/http`, `json`, `uri`, `socket`,
 
 ## Install
 
-Point your `Gemfile` at the subdirectory:
+    gem install batchwatch
 
-```ruby
-gem "batchwatch", git: "https://github.com/batchwatch/client",
-                  glob: "clients/ruby/*.gemspec"
-```
-
-or vendor the three files under `lib/` — they have no third-party imports. A
-RubyGems release is on the way.
+On [RubyGems](https://rubygems.org/gems/batchwatch), or add `gem "batchwatch"`
+to your `Gemfile`. Or vendor the three files under `lib/` — they have no
+third-party imports.
 
 ## Two lines
 
@@ -52,6 +48,118 @@ Get a key with no email and no card:
 
     curl -X POST https://batchwatch.dev/v1/keys -d '{"label":"my pipeline"}'
 
+## The deadline guard — batch when you can, sync when you must
+
+Batch is half the price, but a queue that misses your deadline can take down a
+product. `bw.batch(...)` gets you both: it runs your batch, watches the clock,
+and if the batch has not finished by your deadline it cancels it and runs your
+synchronous fallback instead — so your job always gets an answer, on time.
+
+```ruby
+job = bw.batch("gpt-5.6-sol", deadline: "15m",
+               on_deadline: -> { client.chat.completions.create(...) })
+job.submit(-> { client.batches.create(...) })
+result = job.result
+```
+
+You hand over two callables — the batch-create and the sync fallback — and the
+client runs them. It never sees or builds your provider payload; there is no
+field for it, exactly as with `track`. If the batch finishes in time you get its
+result; if the deadline fires you get the fallback's result.
+
+Every fallback is a **measured prediction outcome**: "batching would have missed
+— running sync was right." It goes down the same accuracy path `should_batch`
+already feeds, so the server can score how often the guard was needed. Nothing
+new leaves the machine.
+
+`deadline` speaks the same duration language as `should_batch`'s `max_wait` —
+`"15m"`, `"6h"`, `"30s"`, a bare number of seconds, or `nil` for no guard. The
+defaults duck-type the OpenAI / Anthropic batch shape; a different provider
+passes `poll:` / `cancel:` / `result_of:` callables.
+
+### The poll loop is ours, not yours
+
+`result` owns the wait so you do not write the same sleep/backoff loop everyone
+else does. It polls with **exponential backoff and jitter**, never faster than a
+**rate-limit floor** (a naive one-second loop against a 24-hour job is 86,400
+requests and an angry provider) and never slower than a ceiling. The **first**
+interval is informed by the model's own **measured p50** — no reason to poll
+every five seconds against a model whose median queue time is forty minutes —
+and reading that p50 **fails open**: if batchwatch is unreachable, polling simply
+continues on the fixed fallback schedule.
+
+The 24-hour **expiry is a distinct terminal state**, never silently a timeout:
+`job.expired` is `true` when the batch hit the cutoff, so you can tell "the queue
+was slow" from "the batch failed".
+
+Tune the cadence if you need to; the defaults are sane:
+
+```ruby
+job = bw.batch("gpt-5.6-sol", deadline: "6h",
+               on_deadline: -> { client.chat.completions.create(...) },
+               poll_base: 30, poll_floor: 5, poll_ceiling: 900)
+job.submit(-> { client.batches.create(...) })
+result = job.result
+```
+
+Driving an async or worker loop yourself instead of blocking a thread? Step the
+same state machine one poll at a time:
+
+```ruby
+state = job.poll_once            # PollState::RUNNING / DONE / EXPIRED / FAILED
+if state == Batchwatch::PollState::RUNNING
+  sleep(job.next_interval)       # backoff + jitter, already applied
+end
+```
+
+### Partial completion — landed, failed, expired
+
+A batch of 20,000 requests is not binary: some land, some fail per-request, and
+some never return before the 24-hour expiry. `job.split` separates the three,
+mapped back to your own objects **by `custom_id`** (never by index — provider
+ordering is not guaranteed):
+
+```ruby
+result = job.split(downloaded_lines, every_submitted_id)
+result.landed        # count that came back clean
+result.failed        # count that failed per-request
+result.expired       # count still outstanding at the 24h cutoff
+result.complete?     # true only if EVERYTHING landed — never a silent success
+result.result_for("my-request-42")     # your object for one id, mapped correctly
+
+# retry only what failed — idempotent, so a second call submits nothing new
+child = job.retry_failed(->(failed_ids) { client.batches.create(...) })
+```
+
+An expired job is reported to batchwatch as `status="expired"`, which is recorded
+but kept out of the percentiles (only `completed` rows count) — so a slow queue
+neither pollutes p90 nor loses the "the queue was slow" signal. That measurement
+rule lives with the ingest contract on the server, under `/v1/calls/complete` →
+"Partial completion", not only here in the client.
+
+## Subscribe to outcome alerts
+
+Get told when a model's queue degrades, on your own webhook or Slack. All three
+calls are keyed to your own token, so — like `my_calls` and unlike the
+measurement path — they do **not** fail open: without a token they raise
+`Batchwatch::AuthError` rather than silently pretend you subscribed.
+
+```ruby
+bw = Batchwatch::Client.new(token: "bw_...")
+
+# webhook: omit the secret and the server mints one, returned ONCE — read it here
+sub = bw.subscribe("webhook", "https://example.com/hook",
+                   providers: "openai", min_severity: "severe")
+puts sub["secret"]   # shown only on creation, never again
+
+# slack needs no secret
+bw.subscribe("slack", "https://hooks.slack.com/services/...")
+
+# list your active subscriptions (never the secret), then revoke one by id
+bw.subscriptions.each { |s| puts [s["id"], s["channel"], s["target"]].join(" ") }
+bw.unsubscribe(sub["id"])
+```
+
 ## It fails open, always
 
 If batchwatch is down, slow, or broken, your job must not notice. That is the
@@ -100,6 +208,35 @@ back labelled as a ceiling.
 Passing `output_tokens: 0` really does send `0`: zero is a measurement, absence
 is not.
 
+## Read your own contributions and key status
+
+Two read routes, both keyed to your own token. They are the readback for
+`track()`: there is no route to a single call by id, so `my_calls` is how you
+confirm a measurement landed.
+
+```ruby
+bw = Batchwatch::Client.new(token: "bw_...")
+
+# everything this key has contributed
+mine = bw.my_calls
+puts "#{mine['count']} calls"
+mine["calls"].each { |c| puts [c["model"], c["status"], c["duration_s"]].join(" ") }
+
+# page through — pagination is keyed on started_server, never an offset, so a
+# row arriving mid-walk cannot make you skip anything. Follow "next" (or pass
+# after: <unix seconds>) until it is null.
+mine = bw.my_calls(after: 1787666964, limit: 100)
+
+# your tier, whether you are contributing, and your quota
+status = bw.key_status
+puts [status["tier"], status["contributing"], status["quota"]["calls_left"]].join(" ")
+```
+
+Both require a key and, like `subscribe`, do **not** fail open — without a token
+there is nothing to read, so they raise `Batchwatch::AuthError` rather than
+return an empty answer that reads like "no contributions". The server's row comes
+back verbatim; no key is renamed.
+
 ## Spooling
 
 When a measurement cannot be delivered, the completed record is appended to a
@@ -152,6 +289,20 @@ in CI.
   - `t.done(output_tokens: nil, status: "completed", ttfb_ms: nil)`
   - `t.failed(status: "failed")`
   - `t.started(input_tokens: ...)` when the count is only known after submission
+- `batch(model, deadline: nil, on_deadline: nil, provider: "openai", **kw) -> BatchJob` — the deadline-guarded, self-polling job
+  - `job.submit(create)` — run the caller's batch-create callable (a block/proc/lambda), remember the handle
+  - `job.result` — block, polling with backoff + jitter, or fall back to `on_deadline` at the deadline
+  - `job.poll_once -> PollState` — one non-blocking step for an async/worker loop; `job.next_interval` is the seconds to sleep before the next
+  - `job.fell_back` — `true` once the guard has fired; `job.expired` — `true` if the batch hit the 24h expiry; `job.poll_count` — polls made
+  - `job.split(results = nil, custom_ids = nil) -> BatchResult` — split landed / failed / expired, mapped by `custom_id` (`result.complete?` / `result.result_for(id)`)
+  - `job.retry_failed(resubmit, result: nil) -> BatchJob | nil` — resubmit only the failed subset, idempotently
+  - poll cadence: `poll_base:` / `poll_floor:` / `poll_ceiling:` / `poll_backoff:` / `poll_jitter:` / `use_p50_cadence:`
+  - override the provider shape with `poll:` / `cancel:` / `result_of:` / `succeeded:` / `expired:`
+- `subscribe(channel, target, secret: nil, providers: nil, models: nil, min_severity: nil) -> Hash` — outcome alerts for this key (`POST /v1/subscriptions`); requires a key
+- `subscriptions -> Array` — this key's active subscriptions (`GET /v1/subscriptions`); requires a key
+- `unsubscribe(sub_id) -> Hash` — revoke one of your own subscriptions (`DELETE /v1/subscriptions/{id}`); requires a key
+- `my_calls(after: nil, limit: nil) -> Hash` — this key's own contributions (`GET /v1/calls/mine`); requires a key, follows `next`/`after` for pagination
+- `key_status -> Hash` — this key's tier / contribution status / quota (`GET /v1/keys/current`); requires a key
 - `flush(timeout: 5.0) -> true/false` — wait for outstanding submissions before exit
 - `flush_spool(timeout: nil) -> Integer` — send what is on disk, returns accepted
 
@@ -161,11 +312,12 @@ in CI.
     # or a single suite:
     ruby -Ilib -Itest test/test_fail_open.rb
 
-26 tests, no network beyond loopback. They start real HTTP servers on
-ephemeral ports (raw `TCPServer`, port 0) rather than stubbing `Net::HTTP`:
-the thing under test is network behaviour, so the network should be in the
-test. The allowlist and fail-open tests carry positive controls, so a client
-that sent nothing at all would fail them rather than pass.
+No network beyond loopback. They start real HTTP servers on ephemeral ports (raw
+`TCPServer`, port 0) rather than stubbing `Net::HTTP`: the thing under test is
+network behaviour, so the network should be in the test. The allowlist and
+fail-open tests carry positive controls, so a client that sent nothing at all
+would fail them rather than pass. The poll-loop tests inject a clock, sleep and
+rng, so the backoff schedule is pinned exactly with no real sleeps.
 
 ## Requirements
 

data/lib/batchwatch/client.rb

@@ -40,7 +40,7 @@ require "time"
 require_relative "spool"
 
 module Batchwatch
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 
   # How often, at most, we try to drain the spool on our own.
   SPOOL_INTERVAL_S = 60.0
@@ -215,6 +215,16 @@ module Batchwatch
     end
   end
 
+  # Raised when an action REQUIRES a key and none is set.
+  #
+  # The measurement path fails open - with no key it degrades silently, because
+  # a missing telemetry call must never stand in the way of the caller's job.
+  # But reading your own contributions is an EXPLICIT action against a per-key
+  # route: here a silent empty answer would be a lie - the caller reads "no
+  # contributions" when in truth there was nothing to read. So we say it out
+  # loud instead.
+  class AuthError < StandardError; end
+
   # The client. Every submission is non-blocking and fails open.
   #
   # Args:
@@ -278,6 +288,7 @@ module Batchwatch
                   when "GET" then Net::HTTP::Get
                   when "POST" then Net::HTTP::Post
                   when "PATCH" then Net::HTTP::Patch
+                  when "DELETE" then Net::HTTP::Delete
                   else raise ArgumentError, "unknown method #{method}"
                   end
       req = req_class.new(uri)
@@ -417,6 +428,98 @@ module Batchwatch
       @advice_lock.synchronize { @advice[model] }
     end
 
+    # ---------------------------------------------------------- subscription
+
+    # Subscribe to outcome alerts for THIS key. Returns the row.
+    #
+    # +channel+ is "webhook" or "slack", +target+ an https URL. +secret+ applies
+    # only to webhook: if you omit it, the server makes one itself and returns
+    # the plaintext ONCE in +secret+ - read it here and configure your receiver,
+    # it never comes again. +providers+ and +models+ are comma-strings (or omit
+    # = all), +min_severity+ is "degraded" or "severe".
+    #
+    # Unlike the measurement path, this one does NOT fail open: subscribing is an
+    # explicit action against an authorized route, so without a key we raise
+    # AuthError rather than silently pretend.
+    def subscribe(channel, target, secret: nil, providers: nil, models: nil,
+                  min_severity: nil)
+      require_key("subscribe")
+      body = { "channel" => channel, "target" => target }
+      { "secret" => secret, "providers" => providers, "models" => models,
+        "min_severity" => min_severity }.each do |name, value|
+        body[name] = value unless value.nil?
+      end
+      call("/v1/subscriptions", method: "POST", body: body)
+    end
+
+    # THIS key's active subscriptions, as an array. Never the secret.
+    def subscriptions
+      require_key("subscriptions")
+      r = call("/v1/subscriptions")
+      (r || {}).fetch("subscriptions", [])
+    end
+
+    # Revoke one of your OWN subscriptions by numeric id. Returns the response.
+    def unsubscribe(sub_id)
+      require_key("unsubscribe")
+      call("/v1/subscriptions/#{sub_id}", method: "DELETE")
+    end
+
+    # --------------------------------------------------------------- job (#178)
+
+    # A high-level batch job: deadline guard (#178) + poll loop (#179) + partial
+    # completion (#180).
+    #
+    # The epic's promise: *we take the callable, never the payload*. You give us
+    # two callables - the batch-create and the synchronous fallback - and we run
+    # them, watch the deadline, poll the batch, and hand back a result. We never
+    # see or construct the provider payload, exactly as with track().
+    #
+    #     job = bw.batch("gpt-5.6-sol", deadline: "15m",
+    #                    on_deadline: -> { client.chat.completions.create(...) })
+    #     job.submit(-> { client.batches.create(...) })
+    #     result = job.result
+    #
+    # If the batch finishes before +deadline+ you get its result. If the deadline
+    # arrives first we cancel the batch (best-effort), run +on_deadline+ and
+    # return that instead - so the caller's job always gets an answer, on time.
+    # Every fallback is reported down the existing #101 accuracy path
+    # (acted_verdict=false on a completion) so the server can score the
+    # prediction; nothing new is sent.
+    #
+    # See Batchwatch::BatchJob for the full contract (poll cadence, poll_once,
+    # split, retry_failed, and the injectable clock/sleep/rng seams).
+    def batch(model, deadline: nil, on_deadline: nil, provider: "openai", **kw)
+      BatchJob.new(self, model, deadline: deadline, on_deadline: on_deadline,
+                              provider: provider, **kw)
+    end
+
+    # Report a deadline-guard outcome down the existing #101 path.
+    #
+    # The deadline guard is a should_batch-style prediction carried out: when it
+    # falls back, the outcome is the server's "run_sync" case ("batching would
+    # have missed"). #101 already carries exactly that - a completion measurement
+    # bearing acted_verdict and deadline_s, which the server judges against its
+    # own measured duration and rolls into /v1/accuracy. So we seed the same
+    # per-model advice slot should_batch writes and emit a completion through the
+    # SAME track() path - no second reporter, no new route.
+    #
+    # A completion in time carries acted_verdict=true (the batch held the
+    # deadline); a fallback carries false. Both sides are reported, which is what
+    # keeps the accuracy number honest. Percentiles are omitted, not invented as
+    # zero (rule #30): the guard did not quote a p90.
+    def record_job_outcome(model, provider, acted_verdict, deadline_s)
+      @advice_lock.synchronize do
+        @advice[model] = {
+          "acted_verdict" => acted_verdict,
+          "deadline_s" => deadline_s,
+          "quoted_p50_s" => nil,
+          "quoted_p90_s" => nil
+        }
+      end
+      track(model, provider: provider, mode: "batch") { |t| t.done }
+    end
+
     # ------------------------------------------------------------- measurement
 
     # Measure one call. The submission happens in the background.
@@ -447,6 +550,52 @@ module Batchwatch
       end
     end
 
+    # ------------------------------------------------------- read your own key
+
+    # The measurements THIS key has contributed. Requires a key.
+    #
+    # GET /v1/calls/mine returns everything the service holds that came from
+    # your key - the only readback there is: there is no route to a single call
+    # by id, and none to anyone else's rows. Use it to confirm a measurement
+    # landed after track() / flush_spool().
+    #
+    # Returns the server's row verbatim: {"label", "count", "next", "calls":
+    # [...], "note"}. +next+ is a ready-made URL for the following page (null on
+    # the last), keyed on started_server so a walk cannot skip a row that
+    # arrives mid-walk.
+    #
+    #   after: unix seconds; only rows with a later started_server come back.
+    #     Omit for the first page.
+    #   limit: rows per page, clamped server-side to 1-1000 (default 500).
+    #
+    # Unlike the measurement path this does NOT fail open: the route is per-key,
+    # so without one we raise AuthError rather than pretend.
+    def my_calls(after: nil, limit: nil)
+      require_key("my_calls")
+      q = {}
+      q["after"] = after.to_i unless after.nil?
+      q["limit"] = limit.to_i unless limit.nil?
+      path = "/v1/calls/mine"
+      path += "?#{URI.encode_www_form(q)}" unless q.empty?
+      call(path)
+    end
+
+    # THIS key's tier, contribution status and quota. Requires a key.
+    #
+    # GET /v1/keys/current returns the row verbatim: {"label", "tier",
+    # "contributing", "recent_measurements", "required", "window_days",
+    # "delayed_by_s", "live", "quota": {...}}. +tier+ is the effective tier
+    # derived from your measurements (free / contributor; only paid is
+    # operator-assigned), and +quota+ reports the calls window for the gated
+    # routes.
+    #
+    # Unlike the measurement path this does NOT fail open: without a key there
+    # is no key to describe, so we raise AuthError.
+    def key_status
+      require_key("key_status")
+      call("/v1/keys/current")
+    end
+
     # --------------------------------------------------------------- spool
 
     # Send everything waiting on disk. Returns the number accepted.
@@ -516,6 +665,17 @@ module Batchwatch
 
     private
 
+    # Fail loudly if there is no key. The read routes are per-key - without one
+    # there is nothing to read, and a silent empty answer would be misread as
+    # "no contributions".
+    def require_key(action)
+      return if @token
+
+      raise AuthError,
+            "batchwatch: #{action} requires a key - set token: ... or " \
+            "$BATCHWATCH_TOKEN"
+    end
+
     def monotonic
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/batchwatch/job.rb

@@ -0,0 +1,741 @@
+# frozen_string_literal: true
+
+# The high-level batch job - the client does the annoying parts.
+#
+# The epic's core promise is *"we take the callable, never the payload"*. Every
+# other batchwatch surface answers a question and hands the decision back to
+# you; this one carries it out. You hand us two callables - the batch-create and
+# the synchronous fallback - and we run them, watch the deadline, poll the
+# batch, and give you a result. We never see or construct the provider payload:
+# there is no field for it, by construction, exactly as with track().
+#
+#     job = bw.batch("gpt-5.6-sol", deadline: "15m",
+#                    on_deadline: -> { client.chat.completions.create(...) })
+#     job.submit(-> { client.batches.create(...) })
+#     result = job.result
+#
+# What happens:
+#
+# * job.submit(fn) runs your batch-create callable and remembers the handle it
+#   returned and the time it started. We never look inside the handle beyond the
+#   questions we have to ask it - is it done, did it succeed, what did it return
+#   - and those go through callables you can override.
+# * job.result waits for the batch. If it finishes before the deadline you get
+#   its result. If the deadline arrives first, we cancel the batch (best-effort),
+#   run on_deadline and give you *that* result instead - your job still gets an
+#   answer, on time.
+# * **Every fallback is a measured prediction outcome.** A deadline miss is the
+#   server's #101 "run_sync" case, so we report it down the SAME accuracy path
+#   track() already uses: a completion carrying acted_verdict=false and the
+#   deadline_s we were given. No second reporter, no new route, no payload.
+#
+# The wait itself (#179) owns the poll loop so the caller does not: exponential
+# backoff with jitter, a rate-limit floor so a naive one-second loop against a
+# 24-hour job cannot fire 86,400 requests, a ceiling so the interval does not
+# run away, and a first cadence informed by our own measured p50 for the model.
+# All of it fails open: if batchwatch cannot tell us the p50, we poll on the
+# fixed fallback schedule rather than stopping.
+#
+# Partial completion (#180) is the third promise: a real batch of 20,000
+# requests comes back with some landed, some failed per-request, and some never
+# returned before the 24-hour expiry. BatchJob#split hands you a BatchResult
+# that separates those three, mapped back to your own objects by custom_id
+# (never by index - provider ordering is not guaranteed), and
+# BatchJob#retry_failed resubmits only the failed subset with a stable
+# idempotency key so a retry cannot duplicate the job.
+
+module Batchwatch
+  # Raised for a misuse of the job API that we must not paper over.
+  #
+  # The measurement path fails open, because a lost telemetry call must never
+  # stand in the way of the user's job. The job path is different: it IS the
+  # user's job. If we cannot run it as asked - no submit before a result, no
+  # fallback to fall back to - a silent no-op would strand the caller waiting on
+  # a result that never comes. So we say it out loud instead.
+  class BatchJobError < StandardError; end
+
+  # ------------------------------------------------------------- poll cadence
+  #
+  # The floor is the rate-limit guard: never poll faster than this, no matter
+  # how eager the schedule, because a one-second loop against a 24-hour job is
+  # 86,400 requests and an angry provider. The ceiling stops the backoff running
+  # away - once the interval reaches it we keep polling at that cadence rather
+  # than doubling forever. The base is where the schedule starts when we have no
+  # p50 to inform it. All three are seconds; every one is overridable on
+  # bw.batch(...).
+  POLL_FLOOR_S = 5.0           # rate-limit floor: never poll faster than this
+  POLL_BASE_S = 5.0            # first interval when we have no measured p50
+  POLL_CEILING_S = 300.0       # backoff ceiling: never poll slower than this
+  POLL_BACKOFF = 2.0           # multiply the interval by this each miss
+  POLL_JITTER = 0.5            # full-jitter fraction: sleep in [(1-j)*d, d]
+
+  # How much of a model's measured p50 we spend before the first poll. A median
+  # queue time of forty minutes means the batch is very unlikely to be done in
+  # the first few minutes, so polling then only burns rate limit. We wait a
+  # fraction of the p50, clamped to the ceiling, so a slow model gets a patient
+  # first poll and a fast one is not starved. This is the use of our own dataset
+  # that the card calls a genuine selling point - nobody without the
+  # measurements can do it.
+  POLL_P50_FRACTION = 0.5
+
+  # The outcome of a single non-blocking poll - the async/worker driver's view.
+  #
+  # BatchJob#poll_once returns one of these constants so a caller driving the
+  # loop from their own event loop (rather than letting #result block a thread)
+  # can decide what to do next without reading provider internals:
+  #
+  # * RUNNING  - not terminal yet; sleep next_interval and poll again.
+  # * DONE     - terminal and successful; call #result for the value.
+  # * EXPIRED  - terminal via the 24h expiry; a DISTINCT state, never a silent
+  #   timeout, so the caller can tell "the queue was slow" from "the batch
+  #   failed".
+  # * FAILED   - terminal but not successful (failed / cancelled).
+  #
+  # EXPIRED and FAILED both fall back the same way inside #result; they are kept
+  # separate here because the caller - and #180's measurement - must be able to
+  # tell them apart.
+  module PollState
+    RUNNING = "running"
+    DONE = "done"
+    EXPIRED = "expired"
+    FAILED = "failed"
+  end
+
+  # Terminal batch statuses across the providers we have seen. A job in one of
+  # these is not going to change again, so waiting longer is pointless. Mirrors
+  # the status maps in the backfill tool (completed / failed / expired /
+  # cancelled), plus OpenAI's "finalizing"-then-"completed" and Anthropic's
+  # "ended".
+  TERMINAL_STATUSES = %w[
+    completed complete succeeded success
+    failed error errored
+    expired cancelled canceled ended
+  ].freeze
+
+  # The 24h expiry is a TERMINAL state, not "keep waiting" - and it is a
+  # distinct one. Counting an expired job as completed pollutes the accuracy
+  # number; counting it as a plain failure loses the signal that the queue was
+  # slow. So we name it separately (both here for the poll loop and in #180's
+  # split).
+  EXPIRED_STATUSES = %w[expired].freeze
+
+  SUCCESS_STATUSES = %w[completed complete succeeded success ended].freeze
+
+  # Markers for the coarse whole-batch split and an unmappable result line. Kept
+  # as frozen sentinels rather than magic strings so they cannot collide with a
+  # real caller custom_id.
+  WHOLE_MARKER = "__batchwatch_whole_batch__"
+  UNMAPPED_MARKER = "__batchwatch_unmapped__"
+
+  # The lower-cased status string of a handle, or "". Duck-typed.
+  #
+  # Reads handle.status (a method, or a [:status]/["status"] hash key) and
+  # nothing else. Never touches the payload.
+  def self.handle_status(handle)
+    status =
+      if handle.respond_to?(:status)
+        handle.status
+      elsif handle.respond_to?(:[])
+        handle[:status] || handle["status"]
+      end
+    status.nil? ? "" : status.to_s.downcase
+  end
+
+  # Is this batch finished? Duck-typed against the common provider shape. The
+  # OpenAI / Anthropic batch objects both expose a status string; we read it and
+  # nothing else. "Finished" means a terminal status; anything else means keep
+  # waiting.
+  def self.default_poll(handle)
+    TERMINAL_STATUSES.include?(handle_status(handle))
+  end
+
+  # Did the batch finish *successfully* (as opposed to failed/expired)?
+  def self.default_succeeded(handle)
+    SUCCESS_STATUSES.include?(handle_status(handle))
+  end
+
+  # Did the batch reach the 24h expiry? Kept separate from default_succeeded so
+  # an expiry is a distinct terminal state the caller and the measurement can
+  # see - never silently a timeout.
+  def self.default_expired(handle)
+    EXPIRED_STATUSES.include?(handle_status(handle))
+  end
+
+  # What the caller gets back for a completed batch: the handle itself. We do
+  # not download or parse the batch output - that is the caller's data and their
+  # provider SDK's job. Override with result_of: if you want something else.
+  def self.default_result(handle)
+    handle
+  end
+
+  # Best-effort cancel of a running batch. Never raises upward. Duck-typed
+  # against a handle.cancel method if the provider object carries one; otherwise
+  # a no-op. The deadline guard has already decided to fall back, so a cancel
+  # that fails to land only wastes provider spend on a batch nobody will read.
+  def self.default_cancel(handle)
+    handle.cancel if handle.respond_to?(:cancel)
+  end
+
+  # The custom_id of a provider result line, or nil. Duck-typed. Reads
+  # item["custom_id"] (or [:custom_id], or the attribute) - the field OpenAI and
+  # Anthropic both round-trip on a batch line. Nothing else is read.
+  def self.custom_id_of(item)
+    if item.respond_to?(:[])
+      return item["custom_id"] || item[:custom_id]
+    end
+    item.respond_to?(:custom_id) ? item.custom_id : nil
+  end
+
+  # Did this per-request line fail? Duck-typed against the provider shape. A
+  # batch output line carries an error (non-null) on failure, or a response with
+  # a non-2xx status_code. We read only those envelope fields - never the body.
+  def self.result_error?(item)
+    error =
+      if item.respond_to?(:[])
+        item["error"] || item[:error]
+      elsif item.respond_to?(:error)
+        item.error
+      end
+    return true if error
+
+    response =
+      if item.respond_to?(:[])
+        item["response"] || item[:response]
+      elsif item.respond_to?(:response)
+        item.response
+      end
+    if response.respond_to?(:[])
+      code = response["status_code"] || response[:status_code]
+      unless code.nil?
+        begin
+          n = Integer(code)
+          return !(n >= 200 && n < 300)
+        rescue ArgumentError, TypeError
+          return false
+        end
+      end
+    end
+    false
+  end
+
+  # One high-level batch job: deadline guard (#178), poll loop (#179), partial
+  # completion (#180).
+  #
+  # Created by Batchwatch::Client#batch. result blocks, polling with backoff and
+  # jitter until the batch is terminal or the deadline fires. For an async /
+  # worker context that does not want a blocked thread, poll_once drives the same
+  # state machine one step at a time.
+  #
+  # The clock / sleep / rng seams exist for deterministic tests: the backoff
+  # schedule and its jitter are pure functions of these, so a fake clock and a
+  # fake rng pin the exact poll count with no real sleeps. Production leaves them
+  # as the real time / random.
+  class BatchJob
+    def initialize(bw, model, deadline: nil, on_deadline: nil,
+                   provider: "openai", poll: nil, cancel: nil, result_of: nil,
+                   succeeded: nil, expired: nil,
+                   poll_base: nil, poll_floor: nil,
+                   poll_ceiling: POLL_CEILING_S, poll_backoff: POLL_BACKOFF,
+                   poll_jitter: POLL_JITTER, use_p50_cadence: true,
+                   poll_interval: nil, clock: nil, sleep: nil, rng: nil)
+      @bw = bw
+      @model = model
+      @provider = provider
+      @on_deadline = on_deadline
+      @deadline_s = Batchwatch.seconds(deadline)
+      @poll = poll || Batchwatch.method(:default_poll)
+      @cancel = cancel || Batchwatch.method(:default_cancel)
+      @result_of = result_of || Batchwatch.method(:default_result)
+      @succeeded = succeeded || Batchwatch.method(:default_succeeded)
+      @expired = expired || Batchwatch.method(:default_expired)
+
+      # poll_interval is #178's name for the (then-fixed) poll cadence. #179
+      # renamed it to poll_base (the FIRST interval before backoff) and split out
+      # an explicit poll_floor (the rate-limit guard). We honour the old name as
+      # an alias so #178's two-callable usage - and its tests, which set a tiny
+      # interval to make the deadline fire fast - keep working untouched (epic
+      # rule #4). When only poll_interval is given, a small value is also taken
+      # as the floor so the deadline-guard tests still poll as fast as they
+      # asked, not clamped up to the 5s default.
+      if poll_base.nil?
+        poll_base = poll_interval.nil? ? POLL_BASE_S : poll_interval
+      end
+      if poll_floor.nil?
+        poll_floor = poll_interval.nil? ? POLL_FLOOR_S : [poll_interval, POLL_FLOOR_S].min
+      end
+
+      # Poll cadence (#179). The floor and ceiling are the two guard rails; the
+      # base is stored raw because EVERY interval that reaches a sleep goes
+      # through clamp, which is the ONE place the floor and ceiling are applied
+      # (P7: one canonical site, so the rate-limit floor cannot be
+      # half-removed). A base below the floor therefore still polls at the floor.
+      @poll_floor = [0.001, poll_floor.to_f].max
+      @poll_ceiling = [@poll_floor, poll_ceiling.to_f].max
+      @poll_base = [0.0, poll_base.to_f].max
+      @poll_backoff = [1.0, poll_backoff.to_f].max
+      @poll_jitter = [[poll_jitter.to_f, 1.0].min, 0.0].max
+      @use_p50_cadence = use_p50_cadence
+
+      # Injectable seams for deterministic tests; real time/random otherwise.
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @sleep = sleep || ->(s) { Kernel.sleep(s) }
+      @rand = rng || -> { Kernel.rand }
+
+      @handle = nil          # the provider's batch object
+      @submitted_at = nil    # monotonic clock at submit
+      @result = nil
+      @fell_back = false     # did the deadline guard fire?
+      @expired_flag = false  # did the batch hit the 24h expiry?
+      @resolved = false      # has result run to completion?
+      @interval = nil        # current backoff interval, lazily seeded
+      @poll_count = 0        # how many times we asked "are you done?"
+      @retries = nil         # lazy per-job retry registry (#180)
+    end
+
+    attr_reader :handle
+
+    # --------------------------------------------------------------- lifecycle
+
+    # Run the caller's batch-create callable and remember the handle.
+    #
+    # +create+ is a zero-argument callable (a block, proc, or lambda) that
+    # returns the provider's batch object - typically
+    # -> { client.batches.create(...) }. We call it, store what it returns, and
+    # start the deadline clock. We never inspect the payload it built; the handle
+    # is opaque to us except for the questions the poll/result callables ask.
+    #
+    # Raising from create is the caller's own error and is left untouched - the
+    # batch never started, so there is nothing for us to guard.
+    def submit(create = nil, &block)
+      create ||= block
+      raise BatchJobError, "batchwatch: submit() needs a callable" if create.nil?
+
+      unless @handle.nil?
+        raise BatchJobError,
+              "batchwatch: this job was already submitted - create a new " \
+              "bw.batch(...) for a second batch"
+      end
+      @handle = create.call
+      @submitted_at = @clock.call
+      @handle
+    end
+
+    # Block until the batch finishes, or the deadline fires.
+    #
+    # Returns the batch result if it completed in time, otherwise the result of
+    # on_deadline. Idempotent: a second call returns the same result without
+    # re-waiting or re-reporting.
+    #
+    # Raises BatchJobError if called before submit.
+    def result
+      return @result if @resolved
+
+      if @handle.nil?
+        raise BatchJobError,
+              "batchwatch: result() before submit() - call " \
+              "job.submit(-> { client.batches.create(...) }) first"
+      end
+
+      completed_in_time = wait_loop
+      if completed_in_time && @succeeded.call(@handle)
+        @result = @result_of.call(@handle)
+        report_outcome(fell_back: false)
+      else
+        @result = fallback(timed_out: !completed_in_time)
+      end
+      @resolved = true
+      @result
+    end
+
+    # Take one non-blocking step of the poll loop and report the state.
+    #
+    # The non-blocking variant (#179): an async or worker context can drive the
+    # wait itself instead of handing us a thread. Call it, read the returned
+    # PollState, and - if it is RUNNING - sleep next_interval (which we have
+    # already advanced) before the next call. result is still the way to get the
+    # value once a step returns a terminal state; this only reports where the
+    # batch is.
+    #
+    # Unlike result this never sleeps and never falls back - it is a single
+    # question. The deadline is still honoured by result's own loop.
+    def poll_once
+      if @handle.nil?
+        raise BatchJobError,
+              "batchwatch: poll_once() before submit() - call " \
+              "job.submit(-> { client.batches.create(...) }) first"
+      end
+      @interval = seed_interval if @interval.nil?
+      state = poll_state
+      @interval = advance_interval(@interval) if state == PollState::RUNNING
+      state
+    end
+
+    # Seconds to sleep before the next poll_once, jitter applied. Already
+    # includes the rate-limit floor and the jitter, so an async driver can sleep
+    # exactly this and match the blocking loop's cadence.
+    def next_interval
+      @interval = seed_interval if @interval.nil?
+      sleep_for
+    end
+
+    # How many times we have asked the batch whether it is done. This is the
+    # number that gets someone rate-limited, so it is exposed for a caller - and
+    # a test - to assert a bound on.
+    def poll_count
+      @poll_count
+    end
+
+    # true once the batch was seen to reach the 24h expiry. A distinct terminal
+    # state, never folded into a timeout.
+    def expired
+      @expired_flag
+    end
+
+    # true once the deadline guard has fired and the fallback was used.
+    def fell_back
+      @fell_back
+    end
+
+    # ------------------------------------------------- partial completion (#180)
+
+    # Split the batch into landed / failed / expired, mapped by custom_id.
+    #
+    # A real batch is not binary: a job of 20,000 requests can come back with
+    # some landed, some failed per-request, and some never returned before the
+    # 24h expiry. This is where silent data loss lives - a naive "the job
+    # completed" reads all three as success. BatchResult separates them, with
+    # counts and the per-request ids, so the caller can act.
+    #
+    # +results+ is the per-request outcomes the caller downloaded from THEIR
+    # provider (we never fetch content). Each item is a mapping carrying a
+    # custom_id and either a success or an error - the shape the OpenAI /
+    # Anthropic batch output lines already have. +custom_ids+ is the full set the
+    # caller SUBMITTED; any id in it that has no result line is expired
+    # (outstanding at the 24h cutoff). Mapping is by custom_id, never by index:
+    # provider result ordering is not guaranteed.
+    #
+    # Pass neither and we read the whole-batch terminal status off the handle
+    # instead - a whole-batch expiry becomes an all-expired result, a whole-batch
+    # failure an all-failed one.
+    def split(results = nil, custom_ids = nil)
+      BatchResult.from_results(self, results, custom_ids)
+    end
+
+    # Resubmit ONLY the failed subset, once, with an idempotency key.
+    #
+    # +resubmit+ is a callable the caller hands us - resubmit.call(failed_ids) -
+    # that recreates a batch over just those ids. Same epic rule: we take the
+    # callable, never the payload. We call it with the list of failed custom_ids
+    # and remember the handle it returns as a fresh child job.
+    #
+    # Idempotent by construction: calling it twice submits ONE retry. Duplicating
+    # a 20,000-request job is an expensive failure, so the key is the sorted set
+    # of failed ids - a pure function of WHAT is being retried, not of when. A
+    # second call with the same failure set returns the same child without
+    # resubmitting; a genuinely different failure set is a different retry and
+    # does submit.
+    #
+    # Returns the child BatchJob, or nil when there is nothing to retry (an empty
+    # failure set is a no-op, not an empty batch).
+    def retry_failed(resubmit, result: nil)
+      res = result.nil? ? split : result
+      failed_ids = res.failed_ids.sort
+      return nil if failed_ids.empty?
+
+      @retries ||= {}
+      key = failed_ids
+      return @retries[key] if @retries.key?(key)
+
+      child = @bw.batch(@model, deadline: nil, on_deadline: @on_deadline,
+                                provider: @provider)
+      child.submit(-> { resubmit.call(failed_ids.dup) })
+      @retries[key] = child
+      child
+    end
+
+    # ------------------------------------------------------- context-manager use
+
+    # A block form so the partial-completion cleanup has an obvious home; the
+    # base job has nothing to do on the way out. Yields self and returns the
+    # block's value. We do NOT force a result the caller never asked for.
+    def with
+      yield self
+    end
+
+    private
+
+    # ------------------------------------------------------------- the poll loop
+    #
+    # #179 owns the wait. The contract result leans on:
+    #   wait_loop -> true  if the batch reached a terminal status before the
+    #                      deadline (result then asks succeeded/expired what to
+    #                      do with it)
+    #                false if the deadline arrived first
+    #   side:  it must NOT cancel, report, or fall back. Deciding what a false
+    #          means is result's job.
+    def wait_loop
+      @interval = seed_interval
+      loop do
+        state = poll_state
+        return true if state != PollState::RUNNING
+        return false if past_deadline?
+
+        @sleep.call(sleep_for)
+        @interval = advance_interval(@interval)
+      end
+    end
+
+    # Ask the batch its state ONCE and classify it. Counts the poll.
+    def poll_state
+      @poll_count += 1
+      return PollState::RUNNING unless @poll.call(@handle)
+
+      # Terminal. Which kind?
+      if @expired.call(@handle)
+        @expired_flag = true
+        return PollState::EXPIRED
+      end
+      return PollState::DONE if @succeeded.call(@handle)
+
+      PollState::FAILED
+    end
+
+    # ---------------------------------------------------------- cadence + backoff
+
+    # The first poll interval: p50-informed when we can, fixed otherwise. We
+    # spend a fraction of the model's measured p50 before the first poll. The
+    # read fails open (measured_p50 swallows everything and returns nil), so an
+    # unreachable or silent batchwatch drops us to the fixed base with no
+    # interruption. Clamped into [floor, ceiling] so a wild p50 cannot push us
+    # past either guard.
+    def seed_interval
+      base = @poll_base
+      if @use_p50_cadence
+        p50 = measured_p50
+        base = p50 * POLL_P50_FRACTION if p50 && p50 > 0
+      end
+      clamp(base)
+    end
+
+    # Exponential backoff, clamped to the ceiling.
+    def advance_interval(interval)
+      clamp(interval * @poll_backoff)
+    end
+
+    # The ONE place the floor and ceiling are applied (P7).
+    def clamp(interval)
+      [@poll_floor, [@poll_ceiling, interval.to_f].min].max
+    end
+
+    # The model's measured p50 queue time in seconds, or nil. Reuses the
+    # client's existing read of /v1/wait (wait_now) - no new route, no new
+    # payload field. Fails open by construction: wait_now already swallows every
+    # error and returns nil when it cannot answer, and we defend once more here
+    # so a malformed number can never take the poll loop down. A nil means "poll
+    # on the fixed schedule", never "stop polling".
+    def measured_p50
+      info = @bw.wait_now(@model, provider: @provider, mode: "batch")
+      return nil unless info
+
+      %w[p50_s observed_wait_s planning_wait_s].each do |key|
+        value = info[key]
+        return value.to_f unless value.nil?
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def past_deadline?
+      return false if @deadline_s.nil?
+
+      (@clock.call - @submitted_at) >= @deadline_s
+    end
+
+    # Sleep before the next poll: jittered interval, clamped to the deadline.
+    #
+    # Full jitter: the actual sleep is drawn uniformly from
+    # [max(floor, (1-jitter)*interval), interval]. interval is already floored
+    # (it comes from clamp), and we floor the window bottom too, so jitter can
+    # spread a fleet that all submitted at once without any client ever dipping
+    # under the rate-limit floor. Then we clamp to the deadline so a coarse
+    # interval never overshoots the guard.
+    def sleep_for
+      interval = @interval.nil? ? clamp(@poll_base) : @interval
+      low = [@poll_floor, interval * (1.0 - @poll_jitter)].max
+      delay = low + (interval - low) * @rand.call
+      return delay if @deadline_s.nil?
+
+      remaining = @deadline_s - (@clock.call - @submitted_at)
+      [0.0, [delay, remaining].min].max
+    end
+
+    # ------------------------------------------------------------- fallback
+
+    # Cancel the batch, run the sync fallback, report the outcome. Reached when
+    # the batch missed its deadline OR finished in a non-success terminal state
+    # (failed / expired). Either way the caller still needs an answer.
+    def fallback(timed_out:)
+      @fell_back = true
+      # Best-effort cancel first, so we are not paying for a batch nobody will
+      # read. A cancel failure is swallowed - the fallback matters more.
+      begin
+        @cancel.call(@handle)
+      rescue StandardError
+        nil
+      end
+
+      if @on_deadline.nil?
+        raise BatchJobError,
+              "batchwatch: the batch #{why_fallback(timed_out)} but no " \
+              "on_deadline fallback was given - pass " \
+              "on_deadline: -> { client.chat.completions.create(...) } " \
+              "to bw.batch(...)"
+      end
+
+      # Report BEFORE running the fallback: the outcome is already known (the
+      # batch would have missed), and the report goes out on a background thread,
+      # so it costs the caller's own call nothing.
+      report_outcome(fell_back: true)
+      @on_deadline.call
+    end
+
+    # Record the prediction outcome down the existing #101 accuracy path. A
+    # deadline fallback IS the server's "run_sync" case; a batch that completed
+    # in time is the "run_batch" hit. Reporting both sides is what makes the
+    # accuracy number honest. Failing to report must never affect the caller's
+    # job, so this rides the same fail-open contract as track().
+    def report_outcome(fell_back:)
+      @bw.record_job_outcome(@model, @provider, !fell_back, @deadline_s)
+    rescue StandardError
+      nil
+    end
+
+    def why_fallback(timed_out)
+      return "missed its deadline" if timed_out
+      return "expired (24h)" if @expired_flag
+
+      "did not succeed"
+    end
+  end
+
+  # The split of a batch into landed / failed / expired (#180).
+  #
+  # A real batch is three sets, not one: requests that landed, requests that
+  # failed per-request, and requests still outstanding when the 24h expiry hit.
+  # Reporting only "completed" loses the last two, which is exactly where silent
+  # data loss lives. This object carries the three sets, their counts, and the
+  # per-request ids, and - because provider ordering is not guaranteed - is built
+  # by mapping on custom_id, never by index.
+  #
+  # The measurement rule for a partial job (#180): an expiry is reported with
+  # status="expired" (NOT completed, which would pollute p90; NOT failed, which
+  # would lose the "queue was slow" signal), a per-request-failed job as
+  # completed with the landed count, and a clean job as completed. The client
+  # does not invent a fourth reading.
+  class BatchResult
+    attr_reader :job, :landed_ids, :failed_ids, :expired_ids, :results_by_id
+
+    def initialize(job, landed_ids:, failed_ids:, expired_ids:,
+                   results_by_id: nil)
+      @job = job
+      @landed_ids = landed_ids.dup
+      @failed_ids = failed_ids.dup
+      @expired_ids = expired_ids.dup
+      # The caller's own result objects, keyed by custom_id, for the landed ones
+      # - so map-back is a hash lookup, never a positional zip.
+      @results_by_id = (results_by_id || {}).dup
+    end
+
+    # ---- counts, so a caller can branch without .length on three arrays -------
+
+    def landed
+      @landed_ids.length
+    end
+
+    def failed
+      @failed_ids.length
+    end
+
+    def expired
+      @expired_ids.length
+    end
+
+    def total
+      landed + failed + expired
+    end
+
+    # true only when every submitted request landed. No silent success: a job
+    # with anything failed or outstanding at expiry is NOT complete. This is the
+    # method a caller checks before treating the batch as done.
+    def complete?
+      total > 0 && failed.zero? && expired.zero?
+    end
+
+    # The caller's own landed result for one custom_id, or nil. The map-back the
+    # naive zip gets wrong: a lookup by id, so out-of-order provider results
+    # still reach the right caller object.
+    def result_for(custom_id)
+      @results_by_id[custom_id]
+    end
+
+    # Build the split from per-request outcomes, or from the handle status.
+    #
+    # See BatchJob#split for the argument contract. The per-request path
+    # classifies each result line by whether it carries an error, treats any
+    # submitted id with no line as expired, and keys the landed results by
+    # custom_id. The handle-status fallback reads the whole-batch terminal state
+    # for a provider that reports no lines.
+    def self.from_results(job, results = nil, custom_ids = nil)
+      return from_handle(job) if results.nil? && custom_ids.nil?
+
+      results = Array(results)
+      seen = {}
+      landed = []
+      failed = []
+      results.each do |item|
+        cid = Batchwatch.custom_id_of(item)
+        if cid.nil?
+          # A line we cannot map is not silently dropped into "landed" - that
+          # would be the zip-by-index mistake in another guise. It counts as
+          # failed so the caller sees the reconciliation gap.
+          failed << UNMAPPED_MARKER
+          next
+        end
+        seen[cid] = item
+        if Batchwatch.result_error?(item)
+          failed << cid
+        else
+          landed << cid
+        end
+      end
+
+      # Anything submitted but never returned is outstanding at expiry.
+      submitted = custom_ids.nil? ? seen.keys : Array(custom_ids)
+      expired = submitted.reject { |cid| seen.key?(cid) }
+
+      results_by_id = {}
+      landed.each { |cid| results_by_id[cid] = seen[cid] unless cid == UNMAPPED_MARKER }
+      new(job, landed_ids: landed.reject { |c| c == UNMAPPED_MARKER },
+               failed_ids: failed, expired_ids: expired,
+               results_by_id: results_by_id)
+    end
+
+    # Coarse split from the whole-batch terminal status. For a provider that
+    # gives us no per-request lines: an expired handle is all-expired, a
+    # non-success terminal handle all-failed, a success all-landed. There are no
+    # ids to list at this granularity, so the sets carry a single whole-batch
+    # marker each and the counts read 1/0/0-style.
+    def self.from_handle(job)
+      handle = job.handle
+      if Batchwatch.default_expired(handle) || job.expired
+        return new(job, landed_ids: [], failed_ids: [], expired_ids: [WHOLE_MARKER])
+      end
+      if Batchwatch.default_succeeded(handle)
+        return new(job, landed_ids: [WHOLE_MARKER], failed_ids: [], expired_ids: [])
+      end
+
+      new(job, landed_ids: [], failed_ids: [WHOLE_MARKER], expired_ids: [])
+    end
+  end
+end

data/lib/batchwatch.rb

@@ -20,3 +20,4 @@
 #     end
 require_relative "batchwatch/spool"
 require_relative "batchwatch/client"
+require_relative "batchwatch/job"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: batchwatch
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Andreas Graae
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-29 00:00:00.000000000 Z
+date: 2026-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -51,6 +51,7 @@ files:
 - README.md
 - lib/batchwatch.rb
 - lib/batchwatch/client.rb
+- lib/batchwatch/job.rb
 - lib/batchwatch/spool.rb
 homepage: https://batchwatch.dev
 licenses: