mirrors-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8031ec5dde9188cd42bfdad78edf5b7f94d09a7db3258f2b25c94e1acaa7ed49
+  data.tar.gz: c138edebf9c993de0264c19110774d49e283c7a91237054e17f23bc33b222896
+SHA512:
+  metadata.gz: 6c7b2b4237c20df46c699b4b9e6857b31da3d3a03982340719fef7c45ab3d4ef1a5c79342016b465a338c76543665d45d66a6c40611a478862da78dcc85b67ce
+  data.tar.gz: 206264fe2b5ed439310c831743aff066007e31279743f063c866061ae8aacc55162ccc3e88295aa4bfe78f76995e86a4a9e321fd81e4286f850859021342523b

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec
+
+gem "minitest", "~> 5.25"
+gem "rake", "~> 13.2"

data/README.md

@@ -0,0 +1,273 @@
+# Mirrors Ruby SDK
+
+Capture original conversation history in the background and retrieve optional
+context before a model request. Your application owns its system prompt, model
+calls, tools, streaming, errors and cancellation.
+
+Requires Ruby 3.3 or later. Install a released version from RubyGems:
+
+```sh
+gem install mirrors-sdk -v 0.1.0
+```
+
+For an application using Bundler, add this to its Gemfile and run `bundle install`:
+
+```ruby
+gem "mirrors-sdk", "~> 0.1.0", require: "mirrors_sdk"
+```
+
+To test an unreleased version, build and install from a reviewed checkout:
+
+```sh
+cd packages/ruby-sdk
+gem build mirrors-sdk.gemspec
+gem install --local mirrors-sdk-0.1.0.gem --no-document
+ruby -rmirrors_sdk -e 'puts MirrorsSDK::VERSION'
+```
+
+For Bundler development, use the checkout's actual location:
+
+```ruby
+gem "mirrors-sdk", path: "/path/to/sidecar/packages/ruby-sdk", require: "mirrors_sdk"
+```
+
+The gem has no runtime dependencies beyond Ruby's standard libraries. Its version
+is independent of the Python and TypeScript packages. The packaged
+[installation skill](skills/install-mirrors-ruby-sdk/SKILL.md) describes integration
+and verifies official publication before suggesting a registry install.
+
+## Integrate with the existing model loop
+
+Create one reusable client per agent configuration **after worker processes fork**.
+Get the API URL and agent ID from that agent's SDK connection settings, and load
+the corresponding key from server secrets with runtime read/write permissions.
+
+```ruby
+require "mirrors_sdk"
+require "securerandom"
+
+mirrors = MirrorsSDK::Mirrors.new(
+  api_url: ENV.fetch("MIRRORS_API_URL"),
+  api_key: ENV.fetch("MIRRORS_API_KEY"),
+  agent_id: ENV.fetch("MIRRORS_AGENT_ID")
+)
+
+turn = mirrors.start_turn
+trace = {
+  "id" => SecureRandom.uuid,
+  "messages" => [{ "role" => "user", "content" => "Help with my account" }]
+}
+mirrors.capture_trace(trace) # Copy and queue; no network wait.
+selected = mirrors.get_context(trace, timeout_ms: 1000)
+
+# Use your application's existing prompt, model call and stream/tool handling.
+system = original_system_prompt
+system = "#{system}\n\n#{selected.context}" unless selected.context.empty?
+response = existing_model_call(system: system, messages: original_messages)
+
+# Only after all model calls, tools, retries and response streaming have ended:
+ticket = mirrors.capture_trace(
+  trace.merge("messages" => completed_original_messages, "turnLatencyMs" => turn.finish),
+  final: true,
+  terminal: "completed" # Or "failed" / "canceled" at those ending hooks.
+)
+```
+
+`get_context` may wait up to one total **1,000 ms budget from call entry**, including
+copying and scheduling. Set `timeout_ms` from 1–1000 to shorten it. This is a best
+effort deadline under Ruby and operating-system scheduling, not a hard real-time
+guarantee. It never waits for capture delivery. This synchronous method blocks its
+calling thread; use the application's existing background execution facility when
+integrating with an event loop.
+
+Results expose `context`, `mode`, `delivery`, `reason`, `elapsed_ms` and nullable
+`freshness`. Use returned text promptly for the same model request and inspect
+`freshness.expires_at` if dispatch is delayed. Changed history requires a new call.
+The client rechecks freshness before returning, including mode changes, lease
+expiry, supersession, release and finalization. It cannot recall text already used
+by the application.
+
+Mode refresh runs independently in the background. Unknown/expired mode immediately
+returns empty local shadow fallback. Confirmed shadow returns empty while scheduling
+bounded background evaluation; off does not retrieve. Capture continues in every
+server mode. The SDK requires HTTPS except loopback development addresses, refuses
+redirects and never logs keys, requests or conversation bodies.
+
+## Canonical evidence
+
+Ruby methods use snake_case; trace hashes use **string keys with the existing JSON
+names**, such as `conversationId`, `callId` and `turnLatencyMs`. Symbols, custom
+objects, cycles and oversized inputs are rejected rather than coerced or truncated.
+Accepted input is copied so caller mutations cannot alter admitted evidence.
+
+Preserve original roles (`system`, `user`, `assistant`, `tool`), text, reasoning,
+block order and tool call/result IDs. Exclude Mirrors-added context. See the
+[canonical message contract](../../docs/contracts/remote-sdk.md#event-stream) for
+text, reasoning, tool and media blocks. Never invent missing tool associations.
+
+Use a fresh execution ID for each user turn, including after restart, finalization,
+local release or disable/re-enable. If final evidence is unavailable,
+`mirrors.release_trace(trace["id"])` performs local cleanup without claiming server
+completion. Terminal status describes how execution ended, not task success.
+
+For continuing chats, supply both `conversationId` and `conversationRevision` or
+neither. Persist an atomically allocated positive safe-integer revision per
+execution; keep both fields and source completeness metadata fixed across that
+execution's captures/retries. Send the full cumulative original history. Revisions
+are not timestamps, message counts or process-local counters. Branches need distinct
+conversation IDs. Optional `user` is `{ "id" => opaque_internal_id, "segment" => cohort }`.
+
+`start_turn` returns a monotonic timer whose first `finish` freezes elapsed
+milliseconds. Measure the whole user turn, including context waiting, models,
+tools, retries and streaming. Put `turnLatencyMs` on final capture only, excluding
+capture delivery; omit unknown duration.
+
+## Optional original instructions
+
+Attach application-supplied instructions once to the turn's trace:
+
+```ruby
+trace["agentContext"] = {
+  "systemPrompt" => original_system_prompt,
+  "skills" => [{ "name" => "account-policy", "content" => application_skill_text }]
+}
+```
+
+Either field may be omitted; the object must contain at least one. Capture the
+original prompt before appending Mirrors context. Include `agentContext` explicitly
+on the final capture to retain it: values are never inherited from an earlier
+snapshot or another turn. Empty prompt or skills values mean explicitly empty;
+omit unknown values. The SDK does not read files, discover skills or assert that
+supplied skills ran. Preserve existing system messages without synthesizing copies.
+Compatible API and worker readers are required; installing a gem does not deploy
+the service. Ruby supports both prompt and skill fields from the TypeScript
+contract; the current Python SDK accepts only the prompt field.
+
+## Receipts, cancellation and shutdown
+
+`ticket.receipt.status` is `pending`, `accepted`, `dropped` or `unconfirmed`.
+`ticket.wait(2)` waits at most **two seconds** outside the model path.
+Other SDK timeout arguments use milliseconds. `accepted` with ingestion status
+`queued` confirms delivery, not analysis completion. An `unconfirmed` write may
+already have committed; immutable retries preserve its request identity and bytes.
+
+Pass a `MirrorsSDK::Cancellation` token to `get_context(..., cancel: token)` and
+call `token.cancel` from the application's cancellation hook. A canceled request
+returns empty context with a distinct reason. Preserve the host's cancellation
+check before calling its provider; SDK cancellation never invokes a provider.
+
+```ruby
+# At shutdown, stop admitting turns and let active turns finish first.
+summary = mirrors.close(timeout_ms: 2000)
+# Or mirrors.flush(timeout_ms: 2000), then mirrors.dispose.
+```
+
+`flush` waits only for captures pending at entry and reports `accepted`, `dropped`,
+`unconfirmed` and `pending` counts. `close` combines bounded flush and disposal;
+`dispose` cancels optional work without waiting for network completion. Background
+threads do not keep a finished Ruby process alive. There is no durable queue, so
+flush explicitly when confirmation matters.
+
+`set_enabled(false)` cancels optional work; re-enabling requires fresh execution
+IDs. Invalid configuration stays inert with explicit fallback results. A client
+inherited across a fork stays inert; create a new client in the child process.
+
+## Limits and tradeoffs
+
+| Boundary | Limit/default |
+| --- | --- |
+| Encoded snapshot | 1,000,000 bytes; 10,000 messages; 50,000 JSON nodes; depth 32 |
+| Agent context | 262,144 UTF-8 JSON bytes within the snapshot budget |
+| Prompt / each skill content | 100,000 UTF-16 code units |
+| Skills | 64 unique names; names at most 128 UTF-16 code units |
+| Pending captures | 16 prefixes and 16 finals, independently |
+| Active executions / recent final receipts | 64 / 128 |
+| Pending retrievals | 16, independent of capture |
+| Capture timeout | 1 second prefix; 6 seconds final; explicit `timeout_ms` 1–30,000 |
+| Context / response | 32,768 / 65,536 bytes |
+| Circuit | 3 failures, 30-second cooldown, one recovery probe per endpoint |
+| Mode heartbeat / lease | 1 second with jitter / at most 3 seconds |
+
+Fixed pools use two prefix, two final and two retrieval workers, plus one heartbeat
+thread, per client. Separate admission keeps network work bounded. The benefit is
+straightforward synchronous integration with
+no external HTTP library; the cost is per-client threads, fresh HTTP connections
+and best-effort delivery at process exit. Native DNS stalls can occupy bounded
+worker capacity until resolution returns. Endpoint circuits are independent; final
+retries share the original deadline. No automatic infinite retry/restart loop exists.
+
+This gem implements the modern `captureTrace` / `getContext` boundary shared by
+TypeScript and Python. It contains no private evaluator, provider adapter, legacy
+session API or ready-only prompt injection helper.
+
+## Development
+
+From this directory:
+
+```sh
+bundle install
+bundle exec rake test
+gem build mirrors-sdk.gemspec
+```
+
+Dedicated CI runs on Ruby 3.3, 3.4 and 4.0, exercises scripted and loopback HTTP
+behavior, builds the gem, checks a clean installation and runs packaged tests.
+These checks establish package behavior, not registry publication, hosted service
+acceptance, production latency or model quality. Tests call no real provider or
+hosted Mirrors service.
+
+## Publishing through GitHub Actions
+
+The `Ruby SDK` workflow publishes tags named `ruby-sdk-v<VERSION>`, such as
+`ruby-sdk-v0.1.0`. All three Ruby versions must pass verification before the
+`publish` job can upload the exact gem built and tested by the Ruby 3.4 job.
+Pull requests and manual workflow runs only verify; they never publish.
+
+Authentication uses [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/).
+The benefit is no long-lived API key to create, store or rotate. The cost is a
+one-time setup in RubyGems and a matching GitHub environment.
+
+Before the first release, create a RubyGems account and register a
+[pending trusted publisher](https://rubygems.org/profile/oidc/pending_trusted_publishers)
+with these exact values:
+
+| RubyGems field | Value |
+| --- | --- |
+| Gem name | `mirrors-sdk` |
+| Repository owner | `runmirrors` |
+| Repository name | `sidecar` |
+| Workflow filename | `ruby-sdk.yml` |
+| Environment | `rubygems` |
+| Workflow Repository Owner / Name | Leave blank; this workflow is in the same repository |
+
+Create the `rubygems` environment in the repository's GitHub Settings →
+Environments. Select the repository's release protection rules there; the workflow
+uses those configured rules and does not create them. No RubyGems API-key secret
+is required. The pending publisher supports the first release and becomes a
+normal publisher after that push succeeds. These account/environment settings
+must be configured separately; this repository change does not create them.
+
+The first token exchange must identify the pending publisher's account. The
+workflow passes the verified RubyGems account ID `256014` as the string `owner`.
+It uses the documented OIDC exchange directly because the current official
+credentials action does not yet support that field. Tokens are masked and the
+short-lived push key is available only within the publish job.
+
+The gemspec leaves licensing unspecified, matching the current Python and
+TypeScript packages. Merge the reviewed SDK and workflow, then tag the intended
+merged commit after its checks pass:
+
+```sh
+git tag ruby-sdk-v0.1.0 <verified-merged-commit>
+git push origin refs/tags/ruby-sdk-v0.1.0
+```
+
+The tag must exactly match `MirrorsSDK::VERSION`; the publish job also checks the
+downloaded gem's name and version before requesting credentials. Only that job
+has permission to request a short-lived GitHub identity token. It uploads the
+retained artifact without rebuilding it or granting GitHub repository write access.
+
+If authentication or publication fails before a successful push, fix the setup and
+rerun the failed publish job within the artifact's 30-day retention period. If the
+push may already have succeeded, inspect the RubyGems version first; do not assume
+rerunning a public package upload is idempotent.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << "lib"
+  test.test_files = FileList["test/**/*_test.rb"]
+  test.warning = true
+end
+
+task default: :test

data/lib/mirrors_sdk/agent_context.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MirrorsSDK
+  # Original instructions are optional evidence, never modifications to model input.
+  class AgentContextWire
+    TRIM = /\A[\s\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+|[\s\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+\z/.freeze
+
+    def self.length(value)
+      value.encode(Encoding::UTF_16LE).bytesize / 2
+    end
+
+    def self.validate(value)
+      unless value.instance_of?(Hash) && !value.empty? && (value.keys - %w[systemPrompt skills]).empty?
+        raise ArgumentError, "Invalid agent context"
+      end
+      if value.key?("systemPrompt")
+        prompt = value["systemPrompt"]
+        unless prompt.instance_of?(String) && length(prompt) <= 100_000
+          raise ArgumentError, "Invalid system prompt"
+        end
+      end
+      validate_skills(value["skills"]) if value.key?("skills")
+      if JSON.generate(value).bytesize > 262_144
+        raise ArgumentError, "Agent context exceeds the encoded size limit"
+      end
+      value
+    end
+
+    def self.validate_skills(skills)
+      unless skills.instance_of?(Array) && skills.length <= 64
+        raise ArgumentError, "Invalid agent skills"
+      end
+      names = {}
+      skills.each do |skill|
+        unless skill.instance_of?(Hash) && skill.keys.sort == %w[content name]
+          raise ArgumentError, "Invalid agent skill"
+        end
+        name, content = skill.values_at("name", "content")
+        unless name.instance_of?(String) && !name.gsub(TRIM, "").empty? &&
+               length(name) <= 128 && !name.match?(/\p{Cc}/) && !names[name] &&
+               content.instance_of?(String) && !content.empty? && length(content) <= 100_000
+          raise ArgumentError, "Invalid agent skill"
+        end
+        names[name] = true
+      end
+    end
+    private_class_method :validate_skills
+  end
+end

data/lib/mirrors_sdk/capture.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "securerandom"
+require "thread"
+
+module MirrorsSDK
+  # Serializes each execution's ordinal stream, retaining uncertain writes verbatim.
+  class CaptureRuntime
+    Pending = Struct.new(:digest, :body, :request)
+    State = Struct.new(:metadata, :ordinal, :pending, :sealed, :retired, :busy,
+                       :changed, :cancellation, :final_digest, :final_owner, :latest_sequence)
+
+    def initialize(transport, config)
+      @transport, @config = transport, config
+      @lock = Mutex.new
+      @active, @terminal, @recent = {}, {}, {}
+      @closed = false
+    end
+
+    def send(input, deadline:, cancel: nil, sequence: nil)
+      owner = Object.new
+      final = input.instance_of?(Hash) && input["final"] == true
+      trace_id = input.dig("trace", "id") if input.instance_of?(Hash)
+      receipt = perform(input, deadline, cancel, owner, sequence)
+      receipt
+    rescue StandardError
+      receipt = DeliveryReceipt.new("unconfirmed", "transport")
+    ensure
+      finish_final(trace_id, owner, receipt) if final
+    end
+
+    # Local release abandons prefixes without canceling an admitted final.
+    def release(trace_id)
+      state = @lock.synchronize do
+        removed = @active.delete(trace_id)
+        retire(removed) if removed
+        removed
+      end
+      state.cancellation.cancel("canceled") if state
+      nil
+    end
+
+    def clear
+      states = @lock.synchronize do
+        @closed = true
+        values = @active.values + @terminal.values
+        values.each { |state| retire(state) }
+        @active.clear
+        @terminal.clear
+        @recent.clear
+        values
+      end
+      states.each { |state| state.cancellation.cancel("closed") }
+      nil
+    end
+
+    def diagnostics
+      @lock.synchronize do
+        { active: @active.length, terminal: @terminal.length, recent: @recent.length }
+      end
+    end
+
+    private
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def perform(input, deadline, cancel, owner, sequence)
+      final = input["final"] == true
+      deadline = [deadline, now + (@config.timeout_ms || (final ? 6000 : 1000)) / 1000.0].min
+      begin
+        encoded = Wire.encode(input, deadline: deadline)
+        snapshot = JSON.parse(encoded)
+        trace_id = Wire.id(snapshot.fetch("trace").fetch("id"))
+        digest = Digest::SHA256.digest(encoded)
+        metadata = metadata(snapshot["trace"])
+      rescue StandardError
+        return now >= deadline ? DeliveryReceipt.new("unconfirmed", "timeout") : DeliveryReceipt.new("dropped", "invalid_evidence")
+      end
+      state = @lock.synchronize { admit(trace_id, metadata, digest, final, owner, sequence) }
+      return state if state.is_a?(DeliveryReceipt)
+
+      local = Cancellation.new
+      unlink_state = state.cancellation.on_cancel { local.cancel("canceled") }
+      unlink_caller = cancel.on_cancel { local.cancel(cancel.reason) } if cancel
+      acquired = false
+      begin
+        @lock.synchronize do
+          while state.busy
+            check_available(state, deadline, local)
+            state.changed.wait(@lock, [deadline - now, 0.01].min)
+          end
+          check_available(state, deadline, local)
+          return DeliveryReceipt.new("dropped", "superseded") if state.sealed && !final
+          return DeliveryReceipt.new("dropped", "superseded") if stale?(state, sequence)
+          previous = recent(trace_id, digest)
+          return previous if previous
+          state.busy = acquired = true
+        end
+        if state.pending && state.pending.digest != digest
+          return DeliveryReceipt.new("dropped", "terminal_conflict") if state.pending.request["final"]
+          deliver(state, trace_id, deadline, local, retry_final: final)
+        end
+        unless state.pending
+          return DeliveryReceipt.new("dropped", "capacity") if state.ordinal >= 10_000
+          request = snapshot.merge("protocol" => 3, "agentId" => @config.agent_id,
+                                   "requestId" => SecureRandom.uuid, "ordinal" => state.ordinal + 1)
+          state.pending = Pending.new(digest, Wire.encode(request, limit: 1_048_576, deadline: deadline), request)
+        end
+        deliver(state, trace_id, deadline, local, retry_final: final)
+      rescue TransportError => error
+        DeliveryReceipt.new("unconfirmed", error.reason == "timeout" ? "timeout" : "transport")
+      rescue StandardError
+        DeliveryReceipt.new("unconfirmed", now >= deadline ? "timeout" : "transport")
+      ensure
+        if acquired
+          @lock.synchronize do
+            state.busy = false
+            state.changed.broadcast
+          end
+        end
+        unlink_caller.call if unlink_caller
+        unlink_state.call if unlink_state
+      end
+    end
+
+    def admit(trace_id, metadata, digest, final, owner, sequence)
+      return DeliveryReceipt.new("dropped", "closed") if @closed
+      previous = recent(trace_id, digest)
+      return previous if previous
+      state = @terminal[trace_id] || @active[trace_id]
+      return DeliveryReceipt.new("dropped", "superseded") if state && stale?(state, sequence)
+      return DeliveryReceipt.new("dropped", "invalid_evidence") if state && state.metadata != metadata
+      if state && state.sealed && (!final || state.final_digest != digest)
+        return DeliveryReceipt.new("dropped", "terminal_conflict")
+      end
+      unless state
+        pool = final ? @terminal : @active
+        return DeliveryReceipt.new("dropped", "capacity") if pool.length >= (final ? 16 : 64)
+        state = State.new(metadata, 0, nil, false, false, false,
+                          ConditionVariable.new, Cancellation.new, nil, nil, nil)
+        pool[trace_id] = state
+      end
+      if final && !state.sealed
+        return DeliveryReceipt.new("dropped", "capacity") if !@terminal.key?(trace_id) && @terminal.length >= 16
+        state.sealed, state.final_digest, state.final_owner = true, digest, owner
+        @active.delete(trace_id)
+        @terminal[trace_id] = state
+      end
+      state.latest_sequence = sequence if sequence
+      state
+    end
+
+    def stale?(state, sequence)
+      sequence && state.latest_sequence && sequence < state.latest_sequence
+    end
+
+    def deliver(state, trace_id, deadline, cancel, retry_final:)
+      pending = state.pending
+      response = nil
+      (retry_final ? 2 : 1).times do |attempt|
+        @lock.synchronize { check_available(state, deadline, cancel) }
+        begin
+          response = @transport.request("trace", pending.body, deadline: deadline,
+                                        cancel: cancel, final_recovery: retry_final) do |value|
+            Wire.trace_response(value, pending.request)
+          end
+          break
+        rescue TransportError => error
+          raise if error.permanent || !retry_final || attempt == 1 || now >= deadline || cancel.canceled?
+        end
+      end
+      @lock.synchronize do
+        check_available(state, deadline, cancel)
+        raise TransportError.new("transport", permanent: true) unless Wire.trace_response(response, pending.request)
+        state.ordinal = pending.request["ordinal"]
+        state.pending = nil
+        receipt = DeliveryReceipt.new("accepted", ingestion: response["ingestion"])
+        if pending.request["final"]
+          @active.delete(trace_id)
+          @terminal.delete(trace_id)
+          remember(trace_id, pending.digest, receipt)
+        end
+        receipt
+      end
+    end
+
+    def check_available(state, deadline, cancel)
+      raise TransportError.new("timeout") if now >= deadline
+      raise TransportError.new("canceled") if @closed || state.retired || cancel.canceled?
+    end
+
+    def finish_final(trace_id, owner, receipt)
+      release(trace_id)
+      state = @lock.synchronize do
+        value = @terminal[trace_id]
+        if value && value.final_owner.equal?(owner)
+          @terminal.delete(trace_id)
+          remember(trace_id, value.final_digest, receipt)
+          retire(value)
+          value
+        end
+      end
+      state.cancellation.cancel("canceled") if state
+    end
+
+    def retire(state)
+      state.retired = true
+      state.changed.broadcast
+    end
+
+    def recent(trace_id, digest)
+      value = @recent[trace_id]
+      value && (value[0] == digest ? value[1] : DeliveryReceipt.new("dropped", "terminal_conflict"))
+    end
+
+    def remember(trace_id, digest, receipt)
+      @recent.delete(trace_id)
+      @recent[trace_id] = [digest, receipt]
+      @recent.shift if @recent.length > 128
+    end
+
+    def metadata(trace)
+      # These are source facts; final-only user, prompt, and duration may differ.
+      fields = %w[model entryPoint completeness conversationId conversationRevision]
+      value = fields.each_with_object({}) do |key, result|
+        result[key] = trace[key] if trace.key?(key)
+      end
+      value["completeness"] = value["completeness"].sort.to_h if value["completeness"].is_a?(Hash)
+      Wire.encode(value)
+    end
+  end
+end

data/lib/mirrors_sdk/circuit.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MirrorsSDK
+  # Independent admission for each endpoint, including one recovery probe.
+  class Circuit
+    def initialize(threshold = 3, cooldown_ms = 30_000, clock: nil)
+      raise ArgumentError, "Invalid threshold" unless threshold.instance_of?(Integer) && (1..100).cover?(threshold)
+      raise ArgumentError, "Invalid cooldown" unless cooldown_ms.instance_of?(Integer) && (1..300_000).cover?(cooldown_ms)
+
+      @threshold = threshold
+      @cooldown = cooldown_ms / 1000.0
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @lock = Mutex.new
+      @failures = 0
+      @until = 0
+      @probing = false
+      @generation = 0
+    end
+
+    def acquire
+      @lock.synchronize do
+        return nil if @until.positive? && (@clock.call < @until || @probing)
+
+        probe = @until.positive?
+        @probing = true if probe
+        generation = @generation
+        finished = false
+        lambda do |success|
+          @lock.synchronize do
+            next if finished || generation != @generation
+
+            finished = true
+            @probing = false if probe
+            next if success.nil?
+
+            if success
+              @failures = 0
+              @until = 0
+            else
+              @failures += 1
+              if probe || @failures >= @threshold
+                @until = @clock.call + @cooldown
+                @generation += 1
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end