acts-as-tbackend 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b2e9c9d9dc5ee83794cd1021c42cd1ba5ba6244a2f4542b02e4d902b57e4590
+  data.tar.gz: adbc87746afd734bc452bd42c54c4b954347f5bc3268598e59c0bcb87b34c7b0
+SHA512:
+  metadata.gz: 575d695ec8ffdae22d415774f697d92fc9dcb1fb24f1f1e2fbcb9803b12931444ef1e608b78b7dd8d4af64a4a44a74b0b39ea50281fe14d105ff86ad88a88806
+  data.tar.gz: d70b29f9e4317627e44c8843a2f6b06a99fb09fb79bdc49d7484494a3e26798a78156f2f9684d3f8a4bd87f8e792071e0e9414f4a25ec41e5b90e09c053c33a3

data/README.md

@@ -0,0 +1,111 @@
+# acts-as-tbackend
+
+Production Ruby connector for the **TBackend** temporal-ledger daemon: pooled,
+circuit-broken, idempotent writes over the framed loopback protocol. Built for
+multi-threaded Rails (Puma) — persistent sockets, a connection pool sized to the
+worker threads, and soft, non-fatal results when the daemon is down.
+
+Status: connector is **prod-shaped**; TBackend itself stays a **shadow-ready**
+side ledger (Rails/Postgres authoritative) until convergence + ops gates. See
+`../igniter-tbackend/docs/tbackend-onboarding.md`.
+
+Canonical repository:
+
+```text
+https://github.com/alexander-s-f/acts-as-tbackend
+```
+
+Forgejo may mirror this repository for internal navigation, but GitHub is the
+team-facing source and RubyGems is the package authority.
+
+## Layers (deliberately separate)
+
+| Layer | File | Responsibility |
+| --- | --- | --- |
+| **Connection** | `lib/acts_as_tbackend/connection.rb` | one persistent framed socket + protocol (token, `write_fact_once`, rich status mapping, reconnect). **Not thread-safe.** |
+| **Pool** | `lib/acts_as_tbackend/pool.rb` | N connections, checkout per thread (`connection_pool`). The concurrency layer. |
+| **Client** | `lib/acts_as_tbackend/client.rb` | app-facing facade: pool + circuit breaker. |
+| **Fact** | `lib/acts_as_tbackend/fact.rb` | deterministic derived ids + fact builder. |
+| **Config** | `lib/acts_as_tbackend/config.rb` | host/port/token/timeouts/pool size/durability (ENV-defaulted). |
+| **Mirror** | `lib/acts_as_tbackend/mirror.rb` | plain-Ruby record to fact envelope + soft `write_fact_once_safe`. |
+| **Extension** | `lib/acts_as_tbackend/extension.rb` | optional ActiveRecord macro, loaded explicitly by Rails apps. |
+
+## Usage
+
+```ruby
+ActsAsTbackend.configure do |c|
+  c.host = "127.0.0.1"; c.port = 7401
+  c.token = ENV["TBACKEND_TOKEN"]     # sent on every request when set
+  c.pool_size = 12                    # ≈ Puma threads per process
+  c.durability_default = "accepted"   # or "durable" (group-commit fdatasync)
+end
+
+# Deterministic id → a retry is an idempotent replay, not a duplicate.
+id   = ActsAsTbackend::Fact.derive_id(store: "orders", record_id: order.id,
+                                      event_type: "order.accepted", source_version: order.updated_at)
+fact = ActsAsTbackend::Fact.build(id:, store: "orders", key: "order:#{order.id}",
+                                  value: { status: "accepted" }, valid_time: order.scheduled_at)
+
+result = ActsAsTbackend.client.write_fact_once(fact)
+# => { ok:, status:, committed:, retryable:, response:, error: }
+#    status ∈ committed_acked | idempotent_replay | duplicate_fact_id_conflict
+#             | rejected_before_commit | timeout_unknown | unavailable | circuit_open
+
+ActsAsTbackend.client.facts_by_seq(store: "orders", after_seq: 0)   # clock-free ordered read
+ActsAsTbackend.client.latest_for(store: "orders", key: "order:42")  # point-in-time
+```
+
+Reads/writes never raise for a down daemon (unless `strict`) — they return a soft
+result so a shadow write stays non-fatal, and the circuit breaker fails fast while
+the daemon is unreachable.
+
+## Rails mirror
+
+The core `require "acts_as_tbackend"` stays ActiveRecord-free. Rails apps opt into
+the macro by requiring the extension:
+
+```ruby
+require "acts_as_tbackend/extension"
+
+class Order < ApplicationRecord
+  acts_as_tbackend store: "orders", except: %i[created_at updated_at]
+end
+```
+
+The callback path is intentionally synchronous and soft for v0:
+
+```text
+after_commit -> Mirror.build_fact -> client.write_fact_once_safe
+```
+
+If the daemon is down, the write returns a soft result such as
+`status: "unavailable"` or `status: "circuit_open"` and the Rails request path is
+not raised by default. For heavier paths, call `record.tbackend_fact(...)` or
+`ActsAsTbackend::Mirror.mirror!(...)` from an app-owned background job.
+
+## Fork-safety (Puma / Sidekiq)
+
+Sockets created before a fork are invalid in the child. Reset in the forking hook:
+
+```ruby
+# config/puma.rb
+on_worker_boot { ActsAsTbackend.reset! }
+# Sidekiq
+Sidekiq.configure_server { |cfg| cfg.on(:startup) { ActsAsTbackend.reset! } }
+```
+
+## Throughput
+
+Persistent pooled sockets + `TCP_NODELAY` make 5–8k rpm (≈83–133 rps) modest. The
+daemon sheds load past `max_inflight_requests` with a retryable `overloaded` →
+`rejected_before_commit`, which `write_fact_once_safe` retries with backoff. A live
+load test proving the number (and finding the ceiling) is the next step.
+
+## Legacy files
+
+`shadow_comparison.rb`, `demo.rb`, and `verify_shadow.rb` are retained as
+pre-refresh reference material for the shadow-parity/demo layer. They are not
+loaded by the core entrypoint and still need a separate port if that layer becomes
+active again.
+
+The refreshed core + optional Rails mirror are the supported v0 surface.

data/lib/acts_as_tbackend/circuit_breaker.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActsAsTbackend
+  # A small thread-safe circuit breaker per (host, port). After `threshold`
+  # consecutive failures it opens for `cooldown` seconds, then allows a single
+  # half-open probe. Keeps a down daemon from stalling every request thread
+  # (fail-fast) while a shadow write stays non-fatal.
+  class CircuitBreaker
+    def initialize(threshold:, cooldown:)
+      @threshold = threshold
+      @cooldown = cooldown
+      @failures = 0
+      @opened_at = nil
+      @mutex = Mutex.new
+    end
+
+    def allow_request?
+      @mutex.synchronize do
+        return true if @opened_at.nil?
+        return true if (monotonic - @opened_at) >= @cooldown # half-open probe
+
+        false
+      end
+    end
+
+    def record_success
+      @mutex.synchronize do
+        @failures = 0
+        @opened_at = nil
+      end
+    end
+
+    def record_failure
+      @mutex.synchronize do
+        @failures += 1
+        @opened_at = monotonic if @failures >= @threshold
+      end
+    end
+
+    def open?
+      @mutex.synchronize { !@opened_at.nil? && (monotonic - @opened_at) < @cooldown }
+    end
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/acts_as_tbackend/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActsAsTbackend
+  # The app-facing facade: a pooled, circuit-broken TBackend client. Checks the
+  # breaker, checks out a persistent Connection, delegates, and feeds transport
+  # health back to the breaker. Thread-safe (the Pool serialises per connection).
+  #
+  #   ActsAsTbackend.client.write_fact_once(fact)
+  #   ActsAsTbackend.client.facts_by_seq(store: "orders", after_seq: 0)
+  #
+  # Every method returns the Connection's soft result hash
+  # ({ ok:, status:, committed:, retryable:, response:, error: }) — never raises for
+  # a down daemon unless `config.strict` is set. When the breaker is open it
+  # short-circuits with status "circuit_open" (retryable) without touching the socket.
+  class Client
+    WRITE_STATUSES_OK = %w[committed_acked idempotent_replay].freeze
+
+    def initialize(config)
+      @config = config
+      @pool = Pool.new(config)
+      @breaker = CircuitBreaker.new(threshold: config.breaker_threshold, cooldown: config.breaker_cooldown)
+    end
+
+    def write_fact_once(fact, **opts)
+      call { |c| c.write_fact_once(fact, **opts) }
+    end
+
+    def write_fact_once_safe(fact, **opts)
+      call { |c| c.write_fact_once_safe(fact, **opts) }
+    end
+
+    def latest_for(**opts)
+      call { |c| c.latest_for(**opts) }
+    end
+
+    def facts_for(**opts)
+      call { |c| c.facts_for(**opts) }
+    end
+
+    def facts_by_seq(**opts)
+      call { |c| c.facts_by_seq(**opts) }
+    end
+
+    def ping(**opts)
+      call { |c| c.ping(**opts) }
+    end
+
+    def shutdown
+      @pool.shutdown
+    end
+
+    private
+
+    def call
+      return circuit_open_result unless @breaker.allow_request?
+
+      begin
+        result = @pool.with { |conn| yield conn }
+      rescue Connection::TransportUnavailable, Connection::TransportUnknown => e
+        # strict mode — Connection raised instead of soft-resulting.
+        @breaker.record_failure
+        raise e
+      end
+
+      transport_healthy?(result) ? @breaker.record_success : @breaker.record_failure
+      result
+    end
+
+    # A completed round-trip (even a domain error like duplicate_fact_id_conflict) is
+    # transport-healthy. Only connect/ack transport states trip the breaker.
+    def transport_healthy?(result)
+      !%w[unavailable timeout_unknown].include?(result[:status])
+    end
+
+    def circuit_open_result
+      { ok: false, status: "circuit_open", committed: nil, retryable: true, response: nil,
+        error: "TBackend circuit breaker open for #{@config.host}:#{@config.port}" }
+    end
+  end
+end

data/lib/acts_as_tbackend/config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActsAsTbackend
+  # Process-wide configuration for the TBackend connector. Defaults come from ENV so
+  # the same code runs in dev / CI / prod without edits.
+  #
+  #   ActsAsTbackend.configure do |c|
+  #     c.host = "127.0.0.1"; c.port = 7401
+  #     c.token = ENV["TBACKEND_TOKEN"]
+  #     c.pool_size = 12                 # ~ Puma threads per process
+  #     c.durability_default = "accepted"
+  #   end
+  class Config
+    attr_accessor :host, :port, :token,
+                  :connect_timeout, :request_timeout,
+                  :pool_size, :pool_checkout_timeout,
+                  :durability_default, :strict,
+                  # circuit breaker
+                  :breaker_threshold, :breaker_cooldown,
+                  # producer stamped onto facts built via Fact.build
+                  :producer,
+                  # master kill-switch for the mirror (extension callbacks no-op when false)
+                  :enabled
+
+    def initialize
+      @enabled = ENV.fetch("TBACKEND_ENABLED", "1") != "0"
+      @host = ENV.fetch("TBACKEND_HOST", "127.0.0.1")
+      @port = Integer(ENV.fetch("TBACKEND_PORT", 7401))
+      @token = ENV["TBACKEND_TOKEN"]
+      @connect_timeout = Float(ENV.fetch("TBACKEND_CONNECT_TIMEOUT", 1.0))
+      @request_timeout = Float(ENV.fetch("TBACKEND_REQUEST_TIMEOUT", 2.0))
+      @pool_size = Integer(ENV.fetch("TBACKEND_POOL_SIZE", 5))
+      @pool_checkout_timeout = Float(ENV.fetch("TBACKEND_POOL_CHECKOUT_TIMEOUT", 1.0))
+      @durability_default = ENV.fetch("TBACKEND_DURABILITY", "accepted")
+      @strict = ENV["TBACKEND_STRICT"] == "1"
+      @breaker_threshold = Integer(ENV.fetch("TBACKEND_BREAKER_THRESHOLD", 5))
+      @breaker_cooldown = Float(ENV.fetch("TBACKEND_BREAKER_COOLDOWN", 5.0))
+      @producer = ENV.fetch("TBACKEND_PRODUCER", "acts-as-tbackend")
+    end
+  end
+end

data/lib/acts_as_tbackend/connection.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "timeout"
+require "zlib"
+
+module ActsAsTbackend
+  # One persistent framed connection to a TBackend daemon. Protocol parity with the
+  # canonical P16 client (token, write_fact_once, rich status mapping,
+  # Unavailable/Unknown split) — but the socket is **kept open and reused** across
+  # requests (reconnect only on error), which is what makes pooled throughput cheap.
+  #
+  # NOT thread-safe: one in-flight request per connection. Concurrency is the Pool's
+  # job — check a Connection out, use it, check it back in.
+  class Connection
+    DEFAULT_HOST = "127.0.0.1"
+    DEFAULT_PORT = 7401
+    MAX_FRAME_BYTES = 64 * 1024 * 1024
+
+    class TransportUnavailable < StandardError; end # connect failed — nothing was sent
+    class TransportUnknown < StandardError; end     # sent, no ack — may or may not have committed
+    class InvalidFrame < StandardError; end
+
+    def initialize(host: DEFAULT_HOST, port: DEFAULT_PORT, token: nil,
+                   connect_timeout: 1.0, request_timeout: 2.0,
+                   durability_default: "accepted", strict: false)
+      @host = host
+      @port = Integer(port)
+      @token = token
+      @connect_timeout = Float(connect_timeout)
+      @request_timeout = Float(request_timeout)
+      @durability_default = durability_default
+      @strict = strict
+      @socket = nil
+    end
+
+    def ping(timeout: nil)
+      map_generic(request({ op: "ping" }, timeout))
+    end
+
+    # Idempotent durable write — the recommended write path. Derive `fact["id"]`
+    # deterministically (see Fact.derive_id) so a retry is a replay, not a duplicate.
+    def write_fact_once(fact, durability: nil, timeout: nil)
+      req = { op: "write_fact_once", fact: fact, durability: durability || @durability_default }
+      map_write_once(request(req, timeout))
+    end
+
+    # Bounded retry of write_fact_once for the retry-safe transient states
+    # (rejected_before_commit / timeout_unknown). Never loops unbounded.
+    def write_fact_once_safe(fact, durability: nil, timeout: nil, attempts: 2, backoff: 0.05)
+      max = [Integer(attempts), 1].max
+      seen = []
+      max.times do |i|
+        result = write_fact_once(fact, durability: durability, timeout: timeout)
+        seen << summary(result)
+        return result.merge(attempt_count: seen.length, attempts: seen) unless retry_safe?(result[:status]) && i + 1 < max
+
+        sleep(backoff.to_f) if backoff.to_f.positive?
+      end
+    end
+
+    def latest_for(store:, key:, as_of: nil, timeout: nil)
+      req = { op: "latest_for", store: store.to_s, key: key.to_s }
+      req[:as_of] = as_of unless as_of.nil?
+      map_generic(request(req, timeout))
+    end
+
+    def facts_for(store:, key: nil, since: nil, as_of: nil, timeout: nil)
+      req = { op: "facts_for", store: store.to_s }
+      req[:key] = key.to_s unless key.nil?
+      req[:since] = since unless since.nil?
+      req[:as_of] = as_of unless as_of.nil?
+      map_generic(request(req, timeout))
+    end
+
+    # Clock-free ordered read (the ordering authority). Prefer this over timestamp
+    # ordering for replay/audit/pull.
+    def facts_by_seq(store:, after_seq: 0, until_seq: nil, timeout: nil)
+      req = { op: "facts_by_seq", store: store.to_s, after_seq: after_seq }
+      req[:until_seq] = until_seq unless until_seq.nil?
+      map_generic(request(req, timeout))
+    end
+
+    def close
+      @socket&.close
+    rescue StandardError
+      nil
+    ensure
+      @socket = nil
+    end
+
+    private
+
+    # Returns { transport_ok: true, response: <hash> } on a completed round-trip, or a
+    # soft transport result (unavailable / timeout_unknown). Raises in strict mode.
+    def request(req, timeout)
+      raw = raw_request(with_token(req), request_timeout(timeout))
+      { transport_ok: true, response: raw }
+    rescue TransportUnavailable => e
+      raise if @strict
+
+      transport_result("unavailable", e, retryable: true)
+    rescue TransportUnknown => e
+      raise if @strict
+
+      transport_result("timeout_unknown", e, retryable: nil)
+    end
+
+    def raw_request(req, timeout)
+      sock = live_socket
+      Timeout.timeout(timeout) do
+        sock.write(encode_frame(req))
+        decode_frame(sock)
+      end
+    rescue Timeout::Error, EOFError, IOError, SystemCallError, JSON::ParserError, InvalidFrame => e
+      close # desynced/broken socket — force reconnect next time
+      raise TransportUnknown, e.message
+    end
+
+    def live_socket
+      return @socket if @socket && !@socket.closed?
+
+      @socket = open_socket
+    end
+
+    def open_socket
+      socket = nil
+      Timeout.timeout(@connect_timeout) { socket = TCPSocket.new(@host, @port) }
+      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true)
+      socket
+    rescue Timeout::Error, SocketError, SystemCallError => e
+      raise TransportUnavailable, e.message
+    end
+
+    def with_token(req)
+      return req unless @token && !@token.to_s.empty?
+      return req if req.key?(:token) || req.key?("token")
+
+      req.merge(token: @token)
+    end
+
+    def request_timeout(override)
+      override.nil? ? @request_timeout : Float(override)
+    end
+
+    def encode_frame(req)
+      body = JSON.generate(req).b
+      [body.bytesize].pack("N") + body + [Zlib.crc32(body)].pack("N")
+    end
+
+    def decode_frame(socket)
+      len = read_exact(socket, 4).unpack1("N")
+      raise InvalidFrame, "response frame too large" if len > MAX_FRAME_BYTES
+
+      body = read_exact(socket, len)
+      expected = read_exact(socket, 4).unpack1("N")
+      raise InvalidFrame, "CRC mismatch" unless Zlib.crc32(body) == expected
+
+      JSON.parse(body, symbolize_names: true)
+    end
+
+    def read_exact(socket, bytes)
+      data = +"".b
+      while data.bytesize < bytes
+        chunk = socket.read(bytes - data.bytesize)
+        raise EOFError, "socket closed" if chunk.nil? || chunk.empty?
+
+        data << chunk
+      end
+      data
+    end
+
+    # ---- response mapping (parity with canonical client) ----
+
+    def map_write_once(env)
+      return env unless env[:transport_ok]
+
+      r = env[:response]
+      return rejected(r) if overloaded?(r)
+      return dup_conflict(r) if r[:error_code] == "duplicate_fact_id_conflict"
+
+      if r[:ok] == true && r[:committed] == true
+        return result(true, "idempotent_replay", true, false, r, nil) if r[:idempotent_replay] == true
+
+        return result(true, "committed_acked", true, false, r, nil)
+      end
+      generic_error(r)
+    end
+
+    def map_generic(env)
+      return env unless env[:transport_ok]
+
+      r = env[:response]
+      return result(true, "ok", nil, false, r, nil) if r[:ok] == true
+      return rejected(r) if overloaded?(r)
+
+      generic_error(r)
+    end
+
+    def overloaded?(r)  = r[:error_code] == "overloaded" && r[:committed] == false
+    def rejected(r)     = result(false, "rejected_before_commit", false, true, r, r[:error])
+    def dup_conflict(r) = result(false, "duplicate_fact_id_conflict", false, false, r, r[:error])
+    def generic_error(r) = result(false, "error", r[:committed], r[:retryable], r, r[:error])
+    def transport_result(status, error, retryable:) = result(false, status, nil, retryable, nil, sanitize(error))
+
+    def result(ok, status, committed, retryable, response, error)
+      { ok: ok, status: status, committed: committed, retryable: retryable, response: response, error: error }
+    end
+
+    def retry_safe?(status)
+      status == "rejected_before_commit" || status == "timeout_unknown"
+    end
+
+    def summary(result)
+      { ok: result[:ok], status: result[:status], committed: result[:committed], retryable: result[:retryable] }
+    end
+
+    def sanitize(error)
+      text = "#{error.class}: #{error.message}"
+      return text unless @token && !@token.to_s.empty?
+
+      text.gsub(@token.to_s, "[REDACTED]")
+    end
+  end
+end

data/lib/acts_as_tbackend/extension.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "mirror"
+
+module ActsAsTbackend
+  # ActiveRecord integration for the refreshed core. `acts_as_tbackend` mirrors model
+  # lifecycle to TBackend on after_commit — synchronously, with a soft/non-fatal
+  # result (a down daemon never raises into the request path). For heavy write paths,
+  # call `record.tbackend_fact(...)` from your own background job instead.
+  #
+  #   class Order < ApplicationRecord
+  #     acts_as_tbackend store: "orders", except: %i[created_at updated_at]
+  #   end
+  module Extension
+    extend ActiveSupport::Concern
+
+    included do
+      # Optional domain valid-time for the fact; defaults to nil.
+      attr_accessor :valid_time unless method_defined?(:valid_time)
+    end
+
+    class_methods do
+      def acts_as_tbackend(store: nil, only: nil, except: nil)
+        class_attribute :tbackend_options
+        self.tbackend_options = { store: (store || table_name).to_s, only: only, except: except }
+
+        after_commit :mirror_tbackend_create_update, on: %i[create update]
+        after_commit :mirror_tbackend_destroy, on: :destroy
+      end
+
+      # ---- class-level read API (routes through the shared pooled client) ----
+
+      def tbackend_history(id)
+        tbackend_guard([]) { ActsAsTbackend.client.facts_for(store: tbackend_options[:store], key: id.to_s) }
+      end
+
+      def tbackend_latest_for(id, as_of: nil)
+        tbackend_guard(nil) { ActsAsTbackend.client.latest_for(store: tbackend_options[:store], key: id.to_s, as_of: as_of) }
+      end
+
+      def tbackend_facts_by_seq(after_seq: 0, until_seq: nil)
+        tbackend_guard([]) do
+          ActsAsTbackend.client.facts_by_seq(store: tbackend_options[:store], after_seq: after_seq, until_seq: until_seq)
+        end
+      end
+
+      def tbackend_guard(default)
+        return default unless ActsAsTbackend.enabled?
+
+        yield
+      rescue StandardError => e
+        ActsAsTbackend::Extension.log("query error: #{e.message}")
+        default
+      end
+    end
+
+    # Public: build the fact for this record (no write) — for apps mirroring from
+    # their own job.
+    def tbackend_fact(event_type:, tombstone: false)
+      opts = self.class.tbackend_options
+      ActsAsTbackend::Mirror.build_fact(
+        record: self, store: opts[:store], event_type: event_type,
+        only: opts[:only], except: opts[:except], tombstone: tombstone, valid_time: valid_time
+      )
+    end
+
+    def mirror_tbackend(event_type:, tombstone: false)
+      opts = self.class.tbackend_options
+      ActsAsTbackend::Mirror.mirror!(
+        record: self, store: opts[:store], event_type: event_type,
+        only: opts[:only], except: opts[:except], tombstone: tombstone, valid_time: valid_time
+      )
+    rescue StandardError => e
+      ActsAsTbackend::Extension.log("mirror error: #{e.message}")
+      { ok: false, status: "error", committed: nil, retryable: nil, response: nil, error: e.message }
+    end
+
+    def self.log(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error("[ActsAsTbackend] #{message}")
+      else
+        warn "[ActsAsTbackend] #{message}"
+      end
+    end
+
+    private
+
+    def mirror_tbackend_create_update
+      event = respond_to?(:previously_new_record?) && previously_new_record? ? "create" : "update"
+      mirror_tbackend(event_type: event)
+    end
+
+    def mirror_tbackend_destroy
+      mirror_tbackend(event_type: "destroy", tombstone: true)
+    end
+  end
+end
+
+# Self-install the macro when ActiveRecord loads (opt-in: the core entry does not
+# require this file, keeping `require "acts_as_tbackend"` ActiveRecord-free).
+if defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
+  ActiveSupport.on_load(:active_record) { include ActsAsTbackend::Extension }
+end

data/lib/acts_as_tbackend/fact.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActsAsTbackend
+  # Builds facts with a **deterministic, domain-derived id** so a retry re-sends the
+  # same id and collapses to an idempotent replay instead of a duplicate.
+  #
+  # NEVER put wall-clock in the id. Derive it from the source record's own version
+  # stamp (e.g. `updated_at`), which is stable across retries and advances on every
+  # real edit. The observation wall-clock belongs in `transaction_time` only.
+  #
+  #   id = ActsAsTbackend::Fact.derive_id(
+  #     store: "orders", record_id: order.id, event_type: "order.accepted",
+  #     source_version: order.updated_at)
+  #   fact = ActsAsTbackend::Fact.build(
+  #     id:, store: "orders", key: "order:#{order.id}", value: {...},
+  #     valid_time: order.scheduled_at)
+  module Fact
+    module_function
+
+    # Deterministic occurrence id. Components must be colon-free (the ":" is the id
+    # separator); source_version is normalised to a colon-free token.
+    def derive_id(store:, record_id:, event_type:, source_version:)
+      "#{store}:#{record_id}:#{event_type}:#{version_token(source_version)}"
+    end
+
+    # A Time is encoded as an integer microsecond epoch — fully deterministic
+    # (no float formatting) and colon-free. Anything else is used as-is (stringified).
+    def version_token(source_version)
+      if source_version.respond_to?(:usec) && source_version.respond_to?(:to_i)
+        source_version.to_i * 1_000_000 + source_version.usec
+      else
+        source_version.to_s
+      end
+    end
+
+    # Builds a fact envelope. `value_hash` is intentionally omitted: the daemon
+    # stamps its own canonical hash on write_fact_once and is the authority.
+    def build(id:, store:, key:, value:, valid_time: nil, transaction_time: nil,
+              causation: nil, schema_version: 1, producer: nil)
+      fact = {
+        "id" => id,
+        "store" => store.to_s,
+        "key" => key.to_s,
+        "value" => value,
+        "transaction_time" => (transaction_time || now).to_f,
+        "schema_version" => schema_version
+      }
+      fact["valid_time"] = valid_time.to_f unless valid_time.nil?
+      fact["causation"] = causation unless causation.nil?
+      fact["producer"] = producer unless producer.nil?
+      fact
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_REALTIME)
+    end
+  end
+end

data/lib/acts_as_tbackend/mirror.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ActsAsTbackend
+  # Plain-Ruby record -> fact mirror, deliberately independent of ActiveSupport so it
+  # is unit-testable without Rails. The AR Extension delegates here; an app can also
+  # call `mirror!` directly from its own background job.
+  #
+  # A "record" is any object that responds to `#id`, `#attributes` (a Hash), and
+  # ideally `#updated_at` (used as the deterministic id version — a retry re-sends the
+  # same id and collapses to an idempotent replay).
+  module Mirror
+    module_function
+
+    def build_fact(record:, store:, event_type:, only: nil, except: nil, tombstone: false, valid_time: nil)
+      store = store.to_s
+      record_id = record.id
+      value = tombstone ? { "_tombstone" => true } : select_value(record, only: only, except: except)
+
+      Fact.build(
+        id: Fact.derive_id(store: store, record_id: record_id, event_type: event_type,
+                           source_version: source_version(record)),
+        store: store,
+        key: "#{store}:#{record_id}",
+        value: value,
+        valid_time: valid_time || record_valid_time(record),
+        causation: "#{store}:#{record_id}:#{event_type}",
+        producer: ActsAsTbackend.config.producer
+      )
+    end
+
+    # Build + idempotent bounded-safe write. Soft/non-fatal: returns the client's soft
+    # result and never raises for a down daemon unless `config.strict`.
+    def mirror!(record:, store:, event_type:, **opts)
+      return disabled_result unless ActsAsTbackend.enabled?
+
+      fact = build_fact(record: record, store: store, event_type: event_type, **opts)
+      ActsAsTbackend.client.write_fact_once_safe(fact)
+    end
+
+    def select_value(record, only:, except:)
+      attrs = stringify(record.attributes)
+      if only
+        attrs.slice(*Array(only).map(&:to_s))
+      elsif except
+        attrs.except(*Array(except).map(&:to_s))
+      else
+        attrs
+      end
+    end
+
+    # A persisted version stamp, stable across retries; falls back to wall-clock only
+    # when the record has none (then the id is best-effort, not retry-stable).
+    def source_version(record)
+      if record.respond_to?(:updated_at) && record.updated_at
+        record.updated_at
+      else
+        Time.now
+      end
+    end
+
+    def record_valid_time(record)
+      record.respond_to?(:valid_time) ? record.valid_time : nil
+    end
+
+    def stringify(hash)
+      hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+    end
+
+    def disabled_result
+      { ok: true, status: "disabled", committed: nil, retryable: false, response: nil, error: nil }
+    end
+  end
+end

data/lib/acts_as_tbackend/pool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "connection_pool"
+
+module ActsAsTbackend
+  # A pool of persistent Connections — the concurrency layer, kept deliberately
+  # separate from the Connection (protocol) so each can be reasoned about and tested
+  # on its own. Sized to the process's worker threads (≈ Puma `threads`).
+  #
+  # Fork-safety: sockets created before a fork are invalid in the child. Call
+  # `ActsAsTbackend.reset!` in the forking hook (Puma `on_worker_boot`, Sidekiq
+  # `on(:startup)`) so children build fresh connections.
+  class Pool
+    def initialize(config)
+      @pool = ConnectionPool.new(size: config.pool_size, timeout: config.pool_checkout_timeout) do
+        Connection.new(
+          host: config.host, port: config.port, token: config.token,
+          connect_timeout: config.connect_timeout, request_timeout: config.request_timeout,
+          durability_default: config.durability_default, strict: config.strict
+        )
+      end
+    end
+
+    def with(&block)
+      @pool.with(&block)
+    end
+
+    def shutdown
+      @pool.shutdown { |conn| conn.close }
+    end
+  end
+end

data/lib/acts_as_tbackend/shadow_comparison.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# LEGACY (pre-refresh) — targets the old ActsAsTbackend API (write_fact / query_scope /
+# async enqueue_job) and is NOT loaded by `require "acts_as_tbackend"`. Pending port to
+# the Connection/Pool/Client/Mirror core. Kept for reference only; do not wire into apps.
+
+require "open3"
+require "json"
+require "tempfile"
+require "digest"
+require "securerandom"
+require "time"
+
+module ActsAsTbackend
+  module ShadowComparison
+    class << self
+      # Submits a CRM result to be asynchronously compared against the Igniter VM execution.
+      #
+      # contract - String name of the contract (e.g., "BidSummary")
+      # inputs   - Hash of input values (matching the contract's inputs signature)
+      # result   - The result computed by the CRM (to compare against)
+      # opts     - Hash of options (e.g., :host, :port)
+      def submit_crm_result(contract:, inputs:, result:, **opts)
+        return unless ActsAsTbackend.enabled?
+
+        host = opts[:host] || "127.0.0.1"
+        port = opts[:port] || 7401
+
+        job_args = {
+          contract: contract,
+          inputs: inputs,
+          result: result,
+          opts: { host: host, port: port }
+        }
+        ActsAsTbackend.enqueue_job("shadow_comparison", job_args)
+      end
+
+      def execute_comparison(contract:, inputs:, result:, **opts)
+        return unless ActsAsTbackend.enabled?
+
+        host = opts[:host] || "127.0.0.1"
+        port = opts[:port] || 7401
+
+        begin
+          # 1. Locate the compiled contract JSON under igniter-compiler/out/
+          contract_filename = "#{contract.gsub(/(.)([A-Z])/, '\1_\2').downcase}.json"
+          search_pattern = File.expand_path("../../../../igniter-compiler/out/*/contracts/#{contract_filename}", __FILE__)
+          contract_path = Dir.glob(search_pattern).first
+
+          unless contract_path && File.exist?(contract_path)
+            # Also search fallback in Out conformance test directory or igniter-vm test fixtures
+            fallback_pattern = File.expand_path("../../../../igniter-compiler/out_conformance_test/*/contracts/#{contract_filename}", __FILE__)
+            contract_path = Dir.glob(fallback_pattern).first
+          end
+
+          raise "Could not locate compiled contract JSON for #{contract}" unless contract_path
+
+          # 2. Write inputs to a temp file
+          temp_inputs = Tempfile.new(["inputs", ".json"])
+          temp_inputs.write(JSON.generate(inputs))
+          temp_inputs.close
+
+          # 3. Locate VM CLI binary and prepare command
+          vm_bin = File.expand_path("../../../../igniter-vm/target/release/igniter-vm", __FILE__)
+          unless File.exist?(vm_bin)
+            # Check debug target fallback
+            vm_bin = File.expand_path("../../../../igniter-vm/target/debug/igniter-vm", __FILE__)
+          end
+
+          cmd = [
+            vm_bin, "run",
+            "--contract", contract_path,
+            "--inputs", temp_inputs.path,
+            "--json",
+            "-b", "#{host}:#{port}"
+          ]
+
+          # 4. Execute VM CLI
+          start_time = Time.now
+          stdout, stderr, status = Open3.capture3(*cmd)
+          latency_ms = ((Time.now - start_time) * 1000).round(2)
+
+          temp_inputs.unlink # Clean up temp inputs file
+
+          # 5. Parse output and perform comparison
+          if status.success?
+            response = JSON.parse(stdout, symbolize_names: true)
+            if response[:status] == "success"
+              vm_result = response[:result]
+              matched = results_match?(result, vm_result)
+              delta = matched ? nil : compute_delta(result, vm_result)
+
+              # Commit result fact to TBackend
+              payload = {
+                contract_name: contract,
+                inputs_hash: Digest::SHA256.hexdigest(JSON.generate(inputs)),
+                crm_result: result,
+                igniter_result: vm_result,
+                matched: matched,
+                delta_json: delta,
+                latency_ms: latency_ms,
+                executed_at: Time.now.iso8601
+              }
+
+              client = ActsAsTbackend.client(host, port)
+              client.write_fact(
+                store: "shadow_results",
+                key: SecureRandom.uuid,
+                value: payload
+              )
+            else
+              log_error("VM reported execution failure: #{response[:error]}", stderr)
+            end
+          else
+            log_error("VM CLI exited with status #{status.exitstatus}", stderr)
+          end
+        rescue => e
+          log_error("Error in ShadowComparison: #{e.message}\n#{e.backtrace.join("\n")}")
+        end
+      end
+
+      private
+
+      def results_match?(crm_val, vm_val)
+        # Normalize and compare decimals vs normal numbers
+        crm_norm = normalize_val(crm_val)
+        vm_norm = normalize_val(vm_val)
+        crm_norm == vm_norm
+      end
+
+      def normalize_val(val)
+        if val.is_a?(Hash) && (val.key?(:value) || val.key?("value")) && (val.key?(:scale) || val.key?("scale"))
+          # It's a decimal hash representation
+          v = (val[:value] || val["value"]).to_i
+          s = (val[:scale] || val["scale"]).to_i
+          # Return float representation for comparison
+          v.to_f / (10**s)
+        elsif val.is_a?(Numeric)
+          val.to_f
+        elsif val.is_a?(String)
+          val.strip
+        elsif val.is_a?(Array)
+          val.map { |item| normalize_val(item) }
+        else
+          val
+        end
+      end
+
+      def compute_delta(crm_val, vm_val)
+        crm_norm = normalize_val(crm_val)
+        vm_norm = normalize_val(vm_val)
+
+        if crm_norm.is_a?(Numeric) && vm_norm.is_a?(Numeric)
+          { diff: (crm_norm - vm_norm).round(6) }
+        else
+          { crm: crm_val, vm: vm_val }
+        end
+      end
+
+      def log_error(msg, stderr = nil)
+        full_msg = "[ActsAsTbackend::ShadowComparison] #{msg}"
+        full_msg += "\nSTDERR: #{stderr}" if stderr && !stderr.empty?
+
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error(full_msg)
+        else
+          warn full_msg
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_tbackend/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActsAsTbackend
+  VERSION = "0.2.0"
+end

data/lib/acts_as_tbackend.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "acts_as_tbackend/version"
+require_relative "acts_as_tbackend/config"
+require_relative "acts_as_tbackend/circuit_breaker"
+require_relative "acts_as_tbackend/fact"
+require_relative "acts_as_tbackend/connection"
+require_relative "acts_as_tbackend/pool"
+require_relative "acts_as_tbackend/client"
+require_relative "acts_as_tbackend/mirror"
+
+# Production connector for the TBackend temporal-ledger daemon.
+#
+#   ActsAsTbackend.configure do |c|
+#     c.host = "127.0.0.1"; c.port = 7401
+#     c.token = ENV["TBACKEND_TOKEN"]
+#     c.pool_size = 12                 # ≈ Puma threads/process
+#   end
+#
+#   id   = ActsAsTbackend::Fact.derive_id(store: "orders", record_id: o.id,
+#                                          event_type: "order.accepted", source_version: o.updated_at)
+#   fact = ActsAsTbackend::Fact.build(id:, store: "orders", key: "order:#{o.id}", value: {...})
+#   ActsAsTbackend.client.write_fact_once(fact)      # idempotent, pooled, circuit-broken
+#
+# Layers, deliberately separate:
+#   Connection — one persistent framed socket + protocol (not thread-safe)
+#   Pool       — N connections, checkout per thread (connection_pool)
+#   Client     — facade: pool + circuit breaker; the app-facing API
+module ActsAsTbackend
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    # Master kill-switch (Config#enabled). When false the extension callbacks no-op.
+    def enabled?
+      config.enabled
+    end
+
+    def configure
+      yield config
+      reset!
+      config
+    end
+
+    # Shared pooled client. Thread-safe; memoized per process.
+    def client
+      @client ||= Client.new(config)
+    end
+
+    # Rebuild pool + client. Call in the forking hook (Puma `on_worker_boot`,
+    # Sidekiq `configure_server`) so a child never inherits a parent's sockets.
+    def reset!
+      old = @client
+      @client = nil
+      old&.shutdown
+      nil
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: acts-as-tbackend
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Alexander
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: 'Pooled, circuit-broken, idempotent client for TBackend: persistent framed
+  sockets, write_fact_once with deterministic ids, token auth, and a connection pool
+  sized for multi-threaded Rails.'
+email:
+- alexander.s.fokin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/acts_as_tbackend.rb
+- lib/acts_as_tbackend/circuit_breaker.rb
+- lib/acts_as_tbackend/client.rb
+- lib/acts_as_tbackend/config.rb
+- lib/acts_as_tbackend/connection.rb
+- lib/acts_as_tbackend/extension.rb
+- lib/acts_as_tbackend/fact.rb
+- lib/acts_as_tbackend/mirror.rb
+- lib/acts_as_tbackend/pool.rb
+- lib/acts_as_tbackend/shadow_comparison.rb
+- lib/acts_as_tbackend/version.rb
+homepage: https://github.com/alexander-s-f/acts-as-tbackend
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/alexander-s-f/acts-as-tbackend
+  source_code_uri: https://github.com/alexander-s-f/acts-as-tbackend
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Production Ruby connector for the TBackend temporal-ledger daemon.
+test_files: []