mirrors-sdk 0.1.0

data/test/executor_test.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "../lib/mirrors_sdk/executor"
+require_relative "../lib/mirrors_sdk/circuit"
+
+class ExecutorTest < Minitest::Test
+  def test_capacity_includes_canceled_but_physically_running_work
+    executor = MirrorsSDK::Executor.new(size: 1, capacity: 1)
+    entered, release = Queue.new, Queue.new
+    future = executor.submit { entered << true; release.pop; :late }
+    entered.pop
+    future.cancel
+    assert future.done?
+    assert_raises(MirrorsSDK::CanceledError) { future.value }
+    assert_nil executor.submit { :overflow }
+    assert_equal 1, executor.diagnostics[:pending]
+    release << true
+    deadline = monotonic + 1
+    sleep 0.001 until executor.diagnostics[:pending].zero? || monotonic > deadline
+    assert_equal 0, executor.diagnostics[:pending]
+    next_job = executor.submit { :next }
+    assert next_job.wait(1)
+    assert_equal :next, next_job.value
+  ensure
+    release << true if release
+    executor.shutdown if executor
+  end
+
+  def test_shutdown_returns_without_waiting_for_stalled_worker
+    executor = MirrorsSDK::Executor.new(size: 1, capacity: 2)
+    entered, release = Queue.new, Queue.new
+    running = executor.submit { entered << true; release.pop }
+    entered.pop
+    queued = executor.submit { flunk "Canceled queued work must not run" }
+    started = monotonic
+    executor.shutdown
+    assert_operator monotonic - started, :<, 0.1
+    assert running.done?
+    assert queued.done?
+    assert_nil executor.submit { :closed }
+    assert_equal 1, executor.diagnostics[:pending]
+  ensure
+    release << true if release
+    executor.shutdown if executor
+  end
+
+  def test_wait_is_bounded_and_callbacks_are_outside_locks
+    future = MirrorsSDK::Future.new
+    assert_equal false, future.wait(0.005)
+    seen = []
+    future.on_complete { |finished| seen << finished.value }
+    assert future.resolve(:first)
+    refute future.resolve(:second)
+    future.on_complete { |finished| seen << finished.value }
+    assert_equal [:first, :first], seen
+    token = MirrorsSDK::Cancellation.new
+    unlink = token.on_cancel { flunk "Unsubscribed callback ran" }
+    unlink.call
+    token.on_cancel { seen << token.reason }
+    assert token.cancel("disabled")
+    refute token.cancel
+    token.on_cancel { seen << token.reason }
+    assert_equal [:first, :first, "disabled", "disabled"], seen
+  end
+
+  def test_circuit_ignores_late_success_and_allows_only_one_recovery_probe
+    clock = 10.0
+    circuit = MirrorsSDK::Circuit.new(1, 1000, clock: -> { clock })
+    old = circuit.acquire
+    circuit.acquire.call(false)
+    old.call(true)
+    assert_nil circuit.acquire
+    clock = 11.0
+    first = circuit.acquire
+    refute_nil first
+    assert_nil circuit.acquire
+    first.call(nil)
+    second = circuit.acquire
+    refute_nil second
+    second.call(false)
+    assert_nil circuit.acquire
+    clock = 12.0
+    circuit.acquire.call(true)
+    refute_nil circuit.acquire
+  end
+
+  private
+
+  def monotonic
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/test/fixtures/canonical-events.json

@@ -0,0 +1,38 @@
+{
+  "protocol": 1,
+  "agentId": "agent-1",
+  "sessionId": "session-1",
+  "branchId": "main",
+  "events": [
+    {
+      "sequence": 1,
+      "kind": "messages",
+      "data": [
+        { "role": "user", "content": "Find account a" },
+        {
+          "role": "assistant",
+          "content": [
+            {
+              "type": "tool-call",
+              "callId": "call-1",
+              "name": "lookup",
+              "arguments": { "account": "a" }
+            }
+          ]
+        },
+        {
+          "role": "tool",
+          "content": [
+            {
+              "type": "tool-result",
+              "callId": "call-1",
+              "name": "lookup",
+              "value": { "found": true },
+              "error": false
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

data/test/integration_test.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/runtime_server"
+
+class IntegrationTest < Minitest::Test
+  def setup
+    @server = RuntimeServer.new
+    @client = client
+  end
+
+  def teardown
+    @client.dispose
+    @server.close
+  end
+
+  def test_capture_and_context_match_existing_protocols
+    wait_for_active
+    evidence = trace.merge("conversationId" => "chat", "conversationRevision" => 3,
+                           "agentContext" => { "systemPrompt" => "Original prompt", "skills" => [{ "name" => "search", "content" => "Search first" }] })
+    prefix = @client.capture_trace(evidence)
+    result = @client.get_context(evidence)
+    assert_equal @server.context_text, result.context
+    assert_equal "accepted", result.delivery
+    assert_equal "accepted", prefix.wait(1).status
+    final = @client.capture_trace(evidence.merge("turnLatencyMs" => 12.5, "user" => { "id" => "user-1" }), final: true, terminal: "completed")
+    assert_equal "accepted", final.wait(1).status
+    assert_equal "queued", final.receipt.ingestion["status"]
+    captures = @server.requests("trace")
+    assert_equal [1, 2], captures.map { |record| record[:body]["ordinal"] }
+    assert captures.all? { |record| record[:body]["captureOnly"] && record[:body]["protocol"] == 3 }
+    assert_equal "Original prompt", captures.last[:body]["trace"]["agentContext"]["systemPrompt"]
+    assert_equal 12.5, captures.last[:body]["trace"]["turnLatencyMs"]
+    request = @server.requests("retrieve-context").last
+    assert_equal 1, request[:body]["protocol"]
+    assert_equal Digest::SHA256.hexdigest("retrieve-context\n#{request[:raw]}"), request[:headers]["idempotency-key"]
+    assert_equal "execution_closed", @client.get_context(evidence).reason
+  end
+
+  def test_capture_does_not_wait_for_http_or_hold_context
+    wait_for_active
+    @server.capture_delay = 0.2
+    evidence = trace
+    started = monotonic
+    ticket = @client.capture_trace(evidence)
+    assert_operator monotonic - started, :<, 0.1
+    evidence["messages"][0]["content"] = "Mutated after capture"
+    eventually { @server.requests("trace").any? }
+    assert_equal "Hello", @server.requests("trace").first[:body]["trace"]["messages"][0]["content"]
+    assert_equal @server.context_text, @client.get_context(trace).context
+    assert_equal "pending", ticket.receipt.status
+    assert_equal "accepted", ticket.wait(1).status
+  end
+
+  def test_context_timeout_cancel_and_late_reply_never_reused
+    wait_for_active
+    @server.context_delay = 0.2
+    started = monotonic
+    result = @client.get_context(trace, timeout_ms: 40)
+    assert_equal "timeout", result.reason
+    assert_empty result.context
+    assert_operator monotonic - started, :<, 0.15
+    cancel = MirrorsSDK::Cancellation.new
+    waiting = Thread.new { @client.get_context(trace("cancel"), cancel: cancel) }
+    eventually { @server.requests("retrieve-context").length >= 2 }
+    cancel.cancel
+    assert waiting.join(0.2)
+    assert_equal "canceled", waiting.value.reason
+    @server.context_delay = 0
+    @server.context_text = "Fresh decision"
+    assert_equal "Fresh decision", @client.get_context(trace).context
+  ensure
+    waiting&.kill if waiting&.alive?
+  end
+
+  def test_shadow_off_and_expired_mode
+    wait_for_active
+    @server.mode = "shadow"
+    @server.version = "version-2"
+    eventually { @client.get_context(trace).reason == "shadow" }
+    eventually { @server.requests("retrieve-context").any? { |record| record[:body]["shadowOnly"] } }
+    @server.mode = "off"
+    @server.version = "version-3"
+    eventually { @client.get_context(trace).reason == "off" }
+    count = @server.requests("retrieve-context").length
+    assert_empty @client.get_context(trace).context
+    assert_equal count, @server.requests("retrieve-context").length
+    @server.mode_status = 503
+    eventually { @client.get_context(trace).reason == "mode_expired" }
+    assert_equal count, @server.requests("retrieve-context").length
+  end
+
+  def test_changed_capture_and_final_invalidate_pending_context
+    wait_for_active
+    @server.context_delay = 0.2
+    waiting = Thread.new { @client.get_context(trace) }
+    eventually { @server.requests("retrieve-context").any? }
+    ticket = @client.capture_trace(trace.merge("messages" => [{ "role" => "user", "content" => "New evidence" }]))
+    assert waiting.join(0.2)
+    assert_equal "superseded", waiting.value.reason
+    assert_equal "accepted", ticket.wait(1).status
+    waiting = Thread.new { @client.get_context(trace) }
+    eventually { @server.requests("retrieve-context").length == 2 }
+    final = @client.capture_trace(trace, final: true)
+    assert waiting.join(0.2)
+    assert_equal "execution_closed", waiting.value.reason
+    assert_equal "accepted", final.wait(1).status
+  ensure
+    waiting&.kill if waiting&.alive?
+  end
+
+  def test_uncertain_prefix_replays_identical_bytes_before_final
+    @server.capture_failures = 1
+    prefix = @client.capture_trace(trace)
+    assert_equal "unconfirmed", prefix.wait(1).status
+    final = @client.capture_trace(trace, final: true, terminal: "completed")
+    assert_equal "accepted", final.wait(1).status
+    records = @server.requests("trace")
+    assert_equal 3, records.length
+    assert_equal records[0][:raw], records[1][:raw]
+    assert_equal records[0][:headers]["idempotency-key"], records[1][:headers]["idempotency-key"]
+    assert_equal 2, records[2][:body]["ordinal"]
+    assert_same final, @client.capture_trace(trace, final: true, terminal: "completed")
+    assert_equal "terminal_conflict", @client.capture_trace(trace, final: true, terminal: "failed").receipt.reason
+  end
+
+  def test_flush_snapshots_pending_and_close_disposes
+    @server.capture_delay = 0.15
+    ticket = @client.capture_trace(trace, final: true)
+    result = @client.flush(timeout_ms: 10)
+    assert_equal 1, result.pending
+    refute result.complete?
+    result = @client.close(timeout_ms: 1000)
+    assert result.complete?
+    assert_equal "accepted", ticket.receipt.status
+    assert_equal "closed", @client.capture_trace(trace("another")).receipt.reason
+    assert_equal "closed", @client.get_context(trace("another")).reason
+  end
+
+  private
+
+  def client(**options)
+    MirrorsSDK::Mirrors.new(api_url: @server.url, api_key: "test-only", agent_id: "agent",
+                            heartbeat_interval_ms: 20, mode_lease_ms: 250, **options)
+  end
+
+  def wait_for_active
+    eventually { @client.get_context(trace("warmup")).delivery == "accepted" }
+    # Subsequent tests count only the requests belonging to their own execution.
+    @server.instance_variable_get(:@lock).synchronize do
+      @server.instance_variable_get(:@records).clear
+    end
+  end
+end

data/test/lifecycle_test.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/runtime_server"
+
+class LifecycleTest < Minitest::Test
+  def setup
+    @server = RuntimeServer.new
+    @client = MirrorsSDK::Mirrors.new(api_url: @server.url, api_key: "test-only", agent_id: "agent")
+  end
+
+  def teardown
+    @client.dispose
+    @server.close
+  end
+
+  def test_final_terminal_is_detached_before_background_work
+    captured = []
+    worker = @client.instance_variable_get(:@worker)
+    worker.define_singleton_method(:capture) do |value, **_options|
+      captured << value
+      MirrorsSDK::Future.new
+    end
+    terminal = String.new("completed")
+    first = @client.capture_trace(trace, final: true, terminal: terminal)
+    terminal.replace("failed")
+    assert_equal "completed", captured.first["terminal"]
+    assert_same first, @client.capture_trace(trace, final: true, terminal: "completed")
+    assert_equal "terminal_conflict", @client.capture_trace(trace, final: true, terminal: terminal).receipt.reason
+  end
+
+  def test_raw_input_hooks_are_never_called_even_on_failure_paths
+    evidence = trace.merge("unsupported" => Object.new)
+    %i[[] class instance_of? to_json].each do |method|
+      evidence.define_singleton_method(method) { |*_args| raise "application hook executed" }
+    end
+    assert_equal "invalid_evidence", @client.capture_trace(evidence).receipt.reason
+    @client.set_enabled(false)
+    assert_equal "disabled", @client.get_context(evidence).reason
+    assert_equal "disabled", @client.capture_trace(evidence).receipt.reason
+  end
+
+  def test_rejected_final_releases_runtime_prefix_state
+    assert_equal "accepted", @client.capture_trace(trace).wait(1).status
+    worker = @client.instance_variable_get(:@worker)
+    runtime = worker.instance_variable_get(:@capture)
+    assert_equal 1, runtime.diagnostics[:active]
+    worker.define_singleton_method(:capture) { |_value, **_options| nil }
+    assert_equal "capacity", @client.capture_trace(trace, final: true).receipt.reason
+    assert_equal 0, runtime.diagnostics[:active]
+  end
+
+  def test_disable_cancels_work_and_reenable_requires_new_identity
+    @server.capture_delay = 0.2
+    ticket = @client.capture_trace(trace)
+    eventually { @server.requests("trace").any? }
+    @client.set_enabled(false)
+    assert_equal "unconfirmed", ticket.wait(0.1).status
+    assert_equal "disabled", @client.get_context(trace).reason
+    @client.set_enabled(true)
+    assert_equal "terminal_conflict", @client.capture_trace(trace).receipt.reason
+    @server.capture_delay = 0
+    assert_equal "accepted", @client.capture_trace(trace("fresh"), final: true).wait(1).status
+    @client.dispose
+    @client.set_enabled(true)
+    assert_equal "closed", @client.capture_trace(trace("later")).receipt.reason
+  end
+
+  def test_source_metadata_stays_fixed_but_user_and_latency_belong_to_final
+    initial = trace.merge("conversationId" => "chat", "conversationRevision" => 1)
+    assert_equal "accepted", @client.capture_trace(initial).wait(1).status
+    changed = initial.merge("conversationRevision" => 2)
+    assert_equal "invalid_evidence", @client.capture_trace(changed).receipt.reason
+    final = initial.merge("user" => { "id" => "user" }, "turnLatencyMs" => 0)
+    assert_equal "accepted", @client.capture_trace(final, final: true).wait(1).status
+    assert_equal "terminal_conflict", @client.capture_trace(changed).receipt.reason
+  end
+
+  def test_final_capacity_is_independent_of_saturated_prefixes
+    @server.capture_delay = 0.15
+    tickets = 16.times.map { |index| @client.capture_trace(trace("prefix-#{index}")) }
+    assert tickets.all? { |ticket| ticket.receipt.status == "pending" }
+    assert_equal "capacity", @client.capture_trace(trace("overflow")).receipt.reason
+    final = @client.capture_trace(trace("final"), final: true)
+    assert_equal "accepted", final.wait(1).status
+  end
+
+  def test_forked_client_does_not_touch_inherited_locks
+    skip "fork unavailable on this platform" unless Process.respond_to?(:fork)
+    reader, writer = IO.pipe
+    inherited_lock = @client.instance_variable_get(:@lock)
+    ready, release = Queue.new, Queue.new
+    holder = Thread.new { inherited_lock.synchronize { ready << true; release.pop } }
+    ready.pop
+    pid = Process.fork do
+      reader.close
+      result = [@client.capture_trace(trace).receipt.reason, @client.get_context(trace).reason,
+                @client.diagnostics[:reason], @client.close.unconfirmed]
+      @client.release_trace("execution")
+      @client.set_enabled(false)
+      @client.dispose
+      writer.write(JSON.generate(result))
+      writer.close
+      exit! 0
+    end
+    writer.close
+    assert IO.select([reader], nil, nil, 2), "Forked SDK call waited on a vanished thread's lock"
+    assert_equal ["forked_process", "forked_process", "forked_process", 1], JSON.parse(reader.read)
+    Process.wait(pid)
+  ensure
+    release << true if release
+    holder&.join(0.5)
+    reader&.close unless reader&.closed?
+    writer&.close unless writer&.closed?
+  end
+
+  def test_invalid_configuration_fails_open_and_timer_freezes
+    invalid = MirrorsSDK::Mirrors.new(api_url: "http://untrusted.invalid", api_key: "test-only", agent_id: "agent")
+    assert_equal "invalid_options", invalid.get_context(trace).reason
+    assert_equal "invalid_options", invalid.capture_trace(trace).receipt.reason
+    assert invalid.flush.complete?
+    timer = invalid.start_turn
+    elapsed = timer.finish
+    assert_operator elapsed, :>=, 0
+    assert_equal elapsed, timer.finish
+    invalid.dispose
+  end
+end

data/test/snapshot_test.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "mirrors_sdk/snapshot"
+
+class SnapshotTest < Minitest::Test
+  def test_copies_nested_values_and_strings_without_serialization_hooks
+    text = +"original"
+    source = { "nested" => [text, { "number" => 1.5 }] }
+    def source.to_json(*)
+      raise "application hook must not run"
+    end
+    def source.each_pair(*)
+      raise "application hook must not run"
+    end
+    encoded = MirrorsSDK::Snapshot.encode(source)
+    cloned = MirrorsSDK::Snapshot.copy(source)
+    text.replace("changed")
+    source["nested"] << false
+    assert_equal "original", cloned["nested"][0]
+    assert_equal({ "nested" => ["original", { "number" => 1.5 }] }, JSON.parse(encoded))
+  end
+
+  def test_rejects_custom_types_cycles_and_non_json_values
+    hostile = Class.new(Hash) { def each_pair; raise "hook"; end }.new
+    hostile_string = Class.new(String).new("x")
+    cycle = []
+    cycle << cycle
+    values = [hostile, hostile_string, Object.new, { x: 1 }, cycle, Float::NAN, Float::INFINITY]
+    values.each do |value|
+      assert_raises(ArgumentError) { MirrorsSDK::Snapshot.encode(value) }
+    end
+  end
+
+  def test_limits_bound_depth_collections_nodes_and_encoded_bytes
+    deep = nil
+    34.times { deep = [deep] }
+    [deep, Array.new(10_001), Array.new(6) { Array.new(10_000, 0) }, "💡" * 250_000].each do |value|
+      assert_raises(ArgumentError) { MirrorsSDK::Snapshot.encode(value) }
+    end
+    assert_raises(ArgumentError) { MirrorsSDK::Snapshot.encode((+"\xff").force_encoding("UTF-8")) }
+    assert_raises(ArgumentError) { MirrorsSDK::Snapshot.encode("\u0000" * 200_000) }
+    assert_equal '{"text":"é"}', MirrorsSDK::Snapshot.encode({ "text" => "é" })
+  end
+
+  def test_integers_must_not_silently_round_at_the_typescript_boundary
+    [9_007_199_254_740_992, -9_007_199_254_740_992, 10**1000].each do |number|
+      assert_raises(ArgumentError) { MirrorsSDK::Snapshot.encode({ "number" => number }) }
+    end
+    [9_007_199_254_740_991, -9_007_199_254_740_991, 1.0e20].each do |number|
+      assert_equal number, JSON.parse(MirrorsSDK::Snapshot.encode({ "number" => number }))["number"]
+    end
+  end
+
+  def test_expired_deadline_is_checked_before_copying_and_encoding
+    expired = Process.clock_gettime(Process::CLOCK_MONOTONIC) - 1
+    assert_raises(Timeout::Error) { MirrorsSDK::Snapshot.copy({ "x" => 1 }, deadline: expired) }
+    assert_raises(Timeout::Error) { MirrorsSDK::Snapshot.encode({ "x" => 1 }, deadline: expired) }
+  end
+
+  def test_oversized_string_sources_are_rejected_before_copy_or_transcode
+    sources = ["a" * 101, ("a" * 201).encode(Encoding::UTF_16LE)]
+    sources.each do |source|
+      String.stub(:new, ->(*) { raise "Oversized source was copied" }) do
+        assert_raises(ArgumentError) { MirrorsSDK::Snapshot.copy(source, limit: 100) }
+      end
+    end
+  end
+
+  def test_utf16_and_utf32_sources_keep_the_exact_utf8_output_budget
+    [Encoding::UTF_16LE, Encoding::UTF_32BE].each do |encoding|
+      source = ("a" * 90).encode(encoding)
+      assert_operator source.bytesize, :>, 100
+      assert_equal "a" * 90, MirrorsSDK::Snapshot.copy(source, limit: 100)
+      assert_raises(ArgumentError) { MirrorsSDK::Snapshot.copy(source, limit: 50) }
+    end
+  end
+
+  def test_copying_a_string_does_not_start_transcoding_after_its_deadline
+    clock = [0, 0, 1]
+    Process.stub(:clock_gettime, ->(*) { clock.shift || 1 }) do
+      assert_raises(Timeout::Error) do
+        MirrorsSDK::Snapshot.copy("original", deadline: 0.5)
+      end
+    end
+    assert_empty clock
+  end
+end

data/test/support/runtime_server.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require "time"
+
+# Real loopback HTTP, with independently held requests. Never contacts a provider.
+class RuntimeServer
+  attr_accessor :mode, :version, :mode_status, :lease_ms, :context_text,
+                :capture_delay, :context_delay, :mode_delay, :capture_failures
+  attr_reader :url
+
+  def initialize
+    @mode, @version, @mode_status, @lease_ms = "active", "version-1", 200, 250
+    @context_text = "Check the account before changing it."
+    @capture_delay, @context_delay, @mode_delay, @capture_failures = 0, 0, 0, 0
+    @lock, @records, @connections, @handlers = Mutex.new, [], [], []
+    @server = TCPServer.new("127.0.0.1", 0)
+    @url = "http://127.0.0.1:#{@server.addr[1]}"
+    @acceptor = Thread.new do
+      loop do
+        socket = @server.accept
+        @connections << socket
+        @handlers << Thread.new(socket) { |connection| handle(connection) }
+      end
+    rescue IOError, Errno::EBADF
+      nil
+    end
+  end
+
+  def requests(endpoint)
+    @lock.synchronize { @records.select { |record| record[:path].end_with?("/#{endpoint}") } }
+  end
+
+  def close
+    @server.close
+    @acceptor.join(0.2)
+    @connections.each { |socket| socket.close unless socket.closed? }
+    @handlers.each { |thread| thread.join(0.2) || thread.kill }
+  end
+
+  private
+
+  def handle(socket)
+    request = socket.gets
+    return unless request
+
+    path = request.split[1]
+    headers = {}
+    while (line = socket.gets) && line != "\r\n"
+      key, value = line.split(":", 2)
+      headers[key.downcase] = value.strip
+    end
+    raw = socket.read(headers.fetch("content-length", "0").to_i)
+    body = raw.empty? ? nil : JSON.parse(raw)
+    @lock.synchronize { @records << { path: path, raw: raw, body: body, headers: headers } }
+    if path.end_with?("/mode")
+      sleep @mode_delay
+      answer(socket, { "protocol" => 1, "agentId" => "agent", "mode" => @mode,
+                       "version" => @version, "issuedAt" => utc, "expiresAt" => utc(@lease_ms) }, @mode_status)
+    elsif path.end_with?("/trace")
+      sleep @capture_delay
+      fail_request = @lock.synchronize do
+        @capture_failures -= 1 if @capture_failures.positive?
+      end
+      return answer(socket, {}, 503) if fail_request
+
+      response = { "protocol" => 3, "agentId" => "agent", "traceId" => body["trace"]["id"],
+                   "requestId" => body["requestId"], "ordinal" => body["ordinal"], "final" => body["final"],
+                   "decisionId" => "capture-decision", "expiresAt" => utc(1000), "mode" => @mode,
+                   "role" => "system", "context" => nil,
+                   "ingestion" => body["final"] ? { "status" => "queued", "jobId" => "job-1" } : nil }
+      %w[terminal captureOnly].each { |key| response[key] = body[key] if body.key?(key) }
+      answer(socket, response)
+    elsif path.end_with?("/retrieve-context")
+      sleep @context_delay
+      response = { "protocol" => 1, "agentId" => "agent", "traceId" => body["trace"]["id"],
+                   "requestId" => body["requestId"], "decisionId" => "context-decision",
+                   "issuedAt" => utc, "expiresAt" => utc(4000), "mode" => @mode,
+                   "modeVersion" => @version, "role" => "system", "reason" => "matched",
+                   "context" => @mode == "active" && !body["shadowOnly"] ? @context_text : nil }
+      response["shadowOnly"] = body["shadowOnly"] if body.key?("shadowOnly")
+      answer(socket, response)
+    else
+      answer(socket, {}, 404)
+    end
+  rescue IOError, SystemCallError
+    nil
+  ensure
+    socket.close unless socket.closed?
+  end
+
+  def answer(socket, body, status = 200)
+    encoded = JSON.generate(body)
+    socket.write("HTTP/1.1 #{status} Response\r\nContent-Type: application/json\r\nContent-Length: #{encoded.bytesize}\r\nConnection: close\r\n\r\n#{encoded}")
+  end
+
+  def utc(offset_ms = 0)
+    (Time.now + offset_ms / 1000.0).utc.iso8601(3)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "mirrors_sdk"
+require "minitest/autorun"
+
+module SDKTestHelpers
+  def monotonic
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def eventually(timeout: 3)
+    deadline = monotonic + timeout
+    loop do
+      result = yield
+      return result if result
+      raise "Condition did not become true before the test deadline" if monotonic >= deadline
+
+      sleep 0.005
+    end
+  end
+
+  def trace(id = "execution")
+    { "id" => id, "messages" => [{ "role" => "user", "content" => "Hello" }] }
+  end
+end
+
+class Minitest::Test
+  include SDKTestHelpers
+end