e-volv-logs 0.1.0

data/lib/evolve_logs/flags/js_values.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  module Flags
+    # JavaScript value rules the Launch kernel depends on
+    # (packages/flags-kernel/PORTING.md). The kernel is TypeScript; where its
+    # answer depends on how JavaScript prints, parses or compares a value,
+    # this module reproduces JavaScript on purpose so a flag evaluates
+    # identically in Ruby and Node.
+    module JsValues
+      # The absent sentinel — JavaScript `undefined`, separate from nil.
+      MISSING = Object.new.freeze
+
+      # The exact set JavaScript's String.prototype.trim removes: WhiteSpace +
+      # LineTerminator (ECMA-262). Keep in sync with PORTING.md.
+      JS_WHITESPACE = " \t\n\v\f\r             

  　"
+      DECIMAL = /\A[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?\z/.freeze
+      RADIX = /\A0(?:[xX][0-9a-fA-F]+|[oO][0-7]+|[bB][01]+)\z/.freeze
+      ISO =
+        /\A(\d{4})-(\d{2})-(\d{2})(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?)?([Zz]|[+-]\d{2}:?\d{2})?\z/
+          .freeze
+      SEMVER_PART = /\A\s*[+-]?\d+/.freeze
+
+      module_function
+
+      def js_trim(s)
+        s.gsub(/\A[#{Regexp.escape(JS_WHITESPACE)}]+|[#{Regexp.escape(JS_WHITESPACE)}]+\z/o, "")
+      end
+
+      def number?(v)
+        v.is_a?(Integer) || v.is_a?(Float)
+      end
+
+      def js_type(v)
+        return "undefined" if v.equal?(MISSING)
+        return "object" if v.nil? || v.is_a?(Array) || v.is_a?(Hash)
+        return "boolean" if v.equal?(true) || v.equal?(false)
+        return "number" if number?(v)
+        return "string" if v.is_a?(String)
+
+        "object"
+      end
+
+      # js_number_string is ECMAScript Number::toString over Ruby's shortest
+      # round-trip Float#to_s ("1.0e+20", "0.1"): digits d (length k) and
+      # exponent n with x = 0.d × 10^n, then the ECMA digit-splitting rules.
+      def js_number_string(x)
+        x = x.to_f
+        return "NaN" if x.nan?
+        return(x.positive? ? "Infinity" : "-Infinity") if x.infinite?
+        return "0" if x.zero?
+        return "-#{js_number_string(-x)}" if x.negative?
+
+        mantissa, exponent = x.to_s.split("e")
+        exponent = exponent.nil? ? 0 : exponent.to_i
+        int_part, frac_part = mantissa.split(".")
+        frac_part ||= ""
+        raw = int_part + frac_part
+        n = int_part.length + exponent
+        stripped = raw.sub(/\A0+/, "")
+        n -= raw.length - stripped.length
+        d = stripped.sub(/0+\z/, "")
+        k = d.length
+        return d + ("0" * (n - k)) if k <= n && n <= 21
+        return "#{d[0, n]}.#{d[n..-1]}" if n.positive? && n <= 21
+        return "0.#{'0' * -n}#{d}" if n > -6 && n <= 0
+
+        e = n - 1
+        head = k == 1 ? d : "#{d[0]}.#{d[1..-1]}"
+        "#{head}e#{e >= 0 ? '+' : '-'}#{e.abs}"
+      end
+
+      # js_string is JavaScript's String(v) over the values a context carries.
+      def js_string(v)
+        return "null" if v.nil?
+        return "true" if v.equal?(true)
+        return "false" if v.equal?(false)
+        return js_number_string(v) if number?(v)
+        return v if v.is_a?(String)
+        if v.is_a?(Array)
+          return v.map { |item| item.nil? || item.equal?(MISSING) ? "" : js_string(item) }.join(",")
+        end
+
+        "[object Object]"
+      end
+
+      def strict_equals(a, b)
+        ta = js_type(a)
+        tb = js_type(b)
+        return false unless ta == tb
+        return a.to_f == b.to_f if ta == "number"
+        return a == b if ta == "string" || ta == "boolean"
+
+        ta == "undefined"
+      end
+
+      # loose_equals is JavaScript `==` over the scalars a context carries
+      # (PORTING.md): strict equality first, then string comparison across
+      # differing types.
+      def loose_equals(a, b)
+        return true if a.nil? && b.nil?
+        return true if strict_equals(a, b)
+        return false if a.nil? || a.equal?(MISSING) || b.nil? || b.equal?(MISSING)
+        return false if js_type(a) == js_type(b)
+
+        js_string(a) == js_string(b)
+      end
+
+      # as_number is JavaScript Number(v) for the value shapes a context
+      # carries: decimal strings, 0x/0o/0b radices; booleans and the rest
+      # refuse. Never raises.
+      def as_number(v)
+        return nil if v.equal?(true) || v.equal?(false)
+        return(v.to_f.finite? ? v.to_f : nil) if number?(v)
+        return nil unless v.is_a?(String)
+
+        s = js_trim(v)
+        return nil if s.empty?
+        if DECIMAL.match?(s)
+          # Ruby's Float() refuses "5." (JavaScript allows it) and accepts
+          # ".5" already; normalise both spellings.
+          normalised = s.end_with?(".") ? "#{s}0" : s
+          if normalised.start_with?("+.", "-.")
+            normalised = "#{normalised[0]}0#{normalised[1..-1]}"
+          elsif normalised.start_with?(".")
+            normalised = "0#{normalised}"
+          end
+          f = Float(normalised)
+          return f.finite? ? f : nil
+        end
+        return Integer(s, 0).to_f if RADIX.match?(s) # Integer("0b11", 0) accepts 0x/0o/0b
+
+        nil
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # parse_iso_date is the one date grammar every SDK parses identically
+      # (src/dates.ts): ISO-8601 calendar date, optional time/fraction/offset,
+      # a missing offset is UTC, year 0000 is refused.
+      def parse_iso_date(s)
+        m = ISO.match(js_trim(s.to_s))
+        return nil unless m
+
+        y = m[1].to_i
+        mo = m[2].to_i
+        d = m[3].to_i
+        h = m[4].nil? ? 0 : m[4].to_i
+        mi = m[5].nil? ? 0 : m[5].to_i
+        sec = m[6].nil? ? 0 : m[6].to_i
+        frac = m[7] || ""
+        zone = m[8]
+        return nil if y.zero?
+        return nil if h > 23 || mi > 59 || sec > 59
+
+        # Time.utc normalises overflow instead of raising (2026-02-30 →
+        # March 2); the round-trip check below refuses it like every port.
+        moment = Time.utc(y, mo, d, h, mi, sec)
+        return nil unless moment.year == y && moment.month == mo && moment.day == d
+
+        millis = (frac + "000")[0, 3].to_i
+        offset = 0
+        if zone && zone != "Z" && zone != "z"
+          digits = zone[1..-1].delete(":")
+          offset = (zone[0] == "-" ? -1 : 1) * (digits[0, 2].to_i * 60 + digits[2, 2].to_i)
+        end
+        (moment.to_i * 1000 + millis - offset * 60_000).to_f
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def as_date(v)
+        return nil if v.equal?(true) || v.equal?(false)
+        if number?(v)
+          f = v.to_f
+          return f.finite? ? f : nil
+        end
+        if v.is_a?(String) && !js_trim(v).empty?
+          parsed = parse_iso_date(v)
+          return parsed unless parsed.nil?
+
+          return as_number(v)
+        end
+        nil
+      end
+
+      # semver_parts: strip one leading lowercase v, take the text before the
+      # first "-", split on ".", each part reads its leading signed digits
+      # (else 0). Missing parts count as 0.
+      def semver_parts(v)
+        v = v.to_s
+        v = v[1..-1] if v.start_with?("v")
+        v.split("-").first.split(".").map do |part|
+          m = SEMVER_PART.match(part)
+          m ? m[0].to_i : 0
+        end
+      end
+
+      def semver_compare(a, b)
+        left = semver_parts(a)
+        right = semver_parts(b)
+        [left.length, right.length].max.times do |i|
+          x = i < left.length ? left[i] : 0
+          y = i < right.length ? right[i] : 0
+          diff = x - y
+          return(diff.negative? ? -1 : 1) unless diff.zero?
+        end
+        0
+      end
+
+      # stringify is a bucketing subject: a stable string, or nothing.
+      def stringify(v)
+        return "true" if v.equal?(true)
+        return "false" if v.equal?(false)
+        return(v.empty? ? nil : v) if v.is_a?(String)
+        return js_number_string(v) if number?(v) && v.to_f.finite?
+
+        nil
+      end
+
+      # utf16_length counts UTF-16 code units — the 1,024 match limit is
+      # counted in these, so a code point above U+FFFF counts 2.
+      def utf16_length(s)
+        s.each_char.sum { |ch| ch.ord > 0xFFFF ? 2 : 1 }
+      end
+    end
+  end
+end

data/lib/evolve_logs/flags/kernel.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+require "evolve_logs/flags/js_values"
+require "evolve_logs/flags/context"
+require "evolve_logs/flags/regex_cache"
+
+module EvolveLogs
+  module Flags
+    # The answer to one evaluation — the served value, the chosen variant,
+    # and why (docs/LAUNCH-SDK.md §3).
+    Evaluation = Struct.new(:value, :variant, :reason)
+
+    # Port of packages/flags-kernel/src/evaluate.ts; PORTING.md has the port
+    # map. Evaluation is synchronous, never raises and never performs I/O —
+    # a malformed ruleset answers the caller's fallback with reason ERROR.
+    module Kernel
+      RULESET_VERSION = 2
+      MAX_PREREQUISITE_DEPTH = 16
+      MAX_MATCH_ATTRIBUTE_LENGTH = 1024
+      BUCKET_SPACE = 10_000
+
+      module_function
+
+      # bucket is the deterministic rollout bucket for (flag, subject):
+      # sha1, first eight hex digits, modulo the bucket space (src/bucket.ts).
+      def bucket(flag_key, subject, salt = "")
+        source = salt && !salt.empty? ? "#{flag_key}:#{salt}:#{subject}" : "#{flag_key}:#{subject}"
+        Digest::SHA1.hexdigest(source.encode(Encoding::UTF_8))[0, 8].to_i(16) % BUCKET_SPACE
+      end
+
+      # evaluate resolves one flag for one subject. Precedence, first match
+      # wins: not found → killed → off → unmet prerequisite → individual
+      # target → the first matching rule (its rollout, else its variant) →
+      # the default rollout, else the default variant, else the fallback when
+      # the variant named does not exist.
+      def evaluate(ruleset, flag_key, fallback, context = {}, is_member: nil, resolved: nil, depth: 0)
+        return Evaluation.new(fallback, nil, "ERROR") if depth > MAX_PREREQUISITE_DEPTH
+
+        flag = own(ruleset.is_a?(Hash) ? ruleset["flags"] : nil, flag_key)
+        return Evaluation.new(fallback, nil, "FLAG_NOT_FOUND") if flag.nil? || flag == false
+
+        contexts = resolved || Context.resolve(context.nil? ? {} : context)
+        segments = ruleset.is_a?(Hash) ? (ruleset["segments"] || {}) : {}
+        targeting = flag["targeting"]
+
+        serve = lambda do |variant_key, reason|
+          found = variant_value(flag, variant_key)
+          found.nil? ? Evaluation.new(fallback, nil, "ERROR") : Evaluation.new(found[0], found[1], reason)
+        end
+        served_off = lambda do |reason|
+          # offVariant falls back to defaultVariant when absent or null (??).
+          off = targeting["offVariant"]
+          off = targeting["defaultVariant"] if off.nil?
+          serve.call(off, reason)
+        end
+
+        return served_off.call("KILLED") if targeting["killed"]
+        return served_off.call("OFF") if targeting["on"] == false
+
+        (targeting["prerequisites"] || []).each do |prerequisite|
+          upstream = evaluate(ruleset, prerequisite["flag"], nil, context,
+                              is_member: is_member, resolved: contexts, depth: depth + 1)
+          if upstream.variant.nil? || !(prerequisite["variants"] || []).include?(upstream.variant)
+            return served_off.call("PREREQUISITE_FAILED")
+          end
+        end
+
+        (targeting["targets"] || []).each do |target|
+          context_kind = target.key?("contextKind") ? target["contextKind"] : JsValues::MISSING
+          key = Context.key_of_kind(contexts, context_kind)
+          if !key.nil? && (target["keys"] || []).include?(key)
+            return serve.call(target["variant"], "TARGET_MATCH")
+          end
+        end
+
+        (targeting["rules"] || []).each_with_index do |rule, i|
+          next unless match_rule(rule, contexts, segments, is_member)
+
+          rollout = rule["rollout"]
+          if rollout.is_a?(Array) && !rollout.empty?
+            bucket_by = rule.key?("bucketBy") ? rule["bucketBy"] : JsValues::MISSING
+            rollout_kind = rule.key?("rolloutContextKind") ? rule["rolloutContextKind"] : JsValues::MISSING
+            subject, misconfigured = rollout_subject(contexts, bucket_by, rollout_kind)
+            return served_off.call("ERROR") if misconfigured
+
+            unless subject.nil?
+              salt = rule["id"].nil? ? "" : rule["id"]
+              found = variant_value(flag, slice_for(rollout, flag_key, salt, subject))
+              return Evaluation.new(found[0], found[1], "ROLLOUT") unless found.nil?
+            end
+          else
+            found = variant_value(flag, rule["variant"])
+            return Evaluation.new(found[0], found[1], "RULE:#{i}") unless found.nil?
+          end
+          # No identity to bucket on, or a rule naming a variant the flag does
+          # not have: fall through to the default rather than to the next
+          # rule — the rule DID match, and skipping on would serve a variant
+          # the author did not intend for this subject.
+          break
+        end
+
+        default_rollout = targeting["defaultRollout"]
+        if default_rollout.is_a?(Array) && !default_rollout.empty?
+          bucket_by = targeting.key?("defaultBucketBy") ? targeting["defaultBucketBy"] : JsValues::MISSING
+          rollout_kind = targeting.key?("defaultRolloutContextKind") ? targeting["defaultRolloutContextKind"] : JsValues::MISSING
+          subject, misconfigured = rollout_subject(contexts, bucket_by, rollout_kind)
+          return served_off.call("ERROR") if misconfigured
+
+          unless subject.nil?
+            found = variant_value(flag, slice_for(default_rollout, flag_key, "default", subject))
+            return Evaluation.new(found[0], found[1], "ROLLOUT") unless found.nil?
+          end
+        end
+
+        serve.call(targeting["defaultVariant"], "DEFAULT")
+      rescue StandardError, SystemStackError
+        Evaluation.new(fallback, nil, "ERROR")
+      end
+
+      # -- matching ----------------------------------------------------------
+
+      # match_operator answers one clause operator against the actual value.
+      # An operator this build does not know never matches: refusing is the
+      # safe direction for a rule nobody understands.
+      def match_operator(op, actual, values)
+        is_str = actual.is_a?(String)
+        case op
+        when "exists"
+          !actual.equal?(JsValues::MISSING) && !actual.nil?
+        when "notExists"
+          actual.equal?(JsValues::MISSING) || actual.nil?
+        when "eq", "in"
+          values.any? { |v| JsValues.loose_equals(actual, v) }
+        when "neq", "notIn"
+          !values.any? { |v| JsValues.loose_equals(actual, v) }
+        when "contains"
+          is_str && values.any? { |v| actual.include?(JsValues.js_string(v)) }
+        when "notContains"
+          !is_str || !values.any? { |v| actual.include?(JsValues.js_string(v)) }
+        when "startsWith"
+          is_str && values.any? { |v| actual.start_with?(JsValues.js_string(v)) }
+        when "endsWith"
+          is_str && values.any? { |v| actual.end_with?(JsValues.js_string(v)) }
+        when "matches"
+          is_str &&
+            JsValues.utf16_length(actual) <= MAX_MATCH_ATTRIBUTE_LENGTH &&
+            values.any? { |v| search(v, actual) }
+        when "notMatches"
+          # A pattern that will not compile matches nothing, so its negation
+          # matches everything — but an over-long attribute is refused
+          # outright rather than folded into that fallback.
+          if is_str && JsValues.utf16_length(actual) > MAX_MATCH_ATTRIBUTE_LENGTH
+            return false
+          end
+
+          !is_str || !values.any? { |v| search(v, actual) }
+        when "gt", "gte", "lt", "lte"
+          values.any? { |v| compare_numeric(actual, v, op) }
+        when "before", "after"
+          a = JsValues.as_date(actual)
+          return false if a.nil?
+
+          values.any? do |v|
+            b = JsValues.as_date(v)
+            !b.nil? && (op == "before" ? a < b : a > b)
+          end
+        when "semverEq", "semverGt", "semverLt", "semverGte", "semverLte"
+          return false unless is_str
+
+          values.any? do |v|
+            comparison = JsValues.semver_compare(actual, JsValues.js_string(v))
+            case op
+            when "semverEq" then comparison.zero?
+            when "semverGt" then comparison.positive?
+            when "semverLt" then comparison.negative?
+            when "semverGte" then comparison >= 0
+            else comparison <= 0
+            end
+          end
+        else
+          false
+        end
+      end
+
+      # match_clauses: every clause must match; absent clauses match
+      # everything.
+      def match_clauses(clauses, contexts)
+        (clauses || []).each do |clause|
+          kind = clause.key?("contextKind") ? clause["contextKind"] : JsValues::MISSING
+          actual = Context.attribute_of_kind(contexts, kind, clause["attribute"])
+          return false unless match_operator(clause["op"], actual, clause["values"] || [])
+        end
+        true
+      end
+
+      # match_segment: excluded beats included beats rules — the order people
+      # expect from an allow list with an override. A rule carrying a numeric
+      # weight matches only a deterministic share of what it otherwise would,
+      # bucketed on the segment key.
+      def match_segment(segment, contexts, is_member)
+        return false unless segment.is_a?(Hash)
+
+        kind = segment.key?("contextKind") ? segment["contextKind"] : JsValues::MISSING
+        kind = Context.kind_or_default(kind)
+        key = Context.key_of_kind(contexts, kind)
+
+        if segment["external"]
+          # The lists are too large to ship; "not a member" is the narrower
+          # answer when no callback can say.
+          return false if is_member.nil? || key.nil?
+          return true if is_member.call(segment["key"], kind, key)
+        elsif !key.nil?
+          return false if (segment["excluded"] || []).include?(key)
+          return true if (segment["included"] || []).include?(key)
+        end
+
+        (segment["rules"] || []).each do |rule|
+          next unless match_clauses(rule["clauses"], contexts)
+
+          weight = rule["weight"]
+          return true unless weight.is_a?(Numeric)
+
+          # bucketBy present (even null) means "bucket on this attribute".
+          subject = if rule.key?("bucketBy")
+                      JsValues.stringify(Context.attribute_of_kind(contexts, kind, rule["bucketBy"]))
+                    else
+                      key
+                    end
+          next if subject.nil?
+
+          return true if bucket(segment["key"], subject, "segment") < clamp_weight(weight)
+        end
+        false
+      end
+
+      # segment_conditions normalises the two shapes Rule.segments carries:
+      # a bare string list (pre-negation rulesets) means "in all of these".
+      def segment_conditions(segments)
+        return [] if segments.nil? || segments.empty?
+        return segments.map { |k| { "keys" => [k] } } if segments[0].is_a?(String)
+
+        segments
+      end
+
+      def match_rule(rule, contexts, segments, is_member)
+        return false unless match_clauses(rule["clauses"], contexts)
+
+        segment_conditions(rule["segments"]).each do |condition|
+          in_any = (condition["keys"] || []).any? do |k|
+            match_segment(own(segments, k), contexts, is_member)
+          end
+          negate = condition["negate"]
+          return false if negate ? in_any : !in_any
+        end
+        true
+      end
+
+      # -- rollouts ------------------------------------------------------------
+
+      # slice_for: which slice of a rollout this subject lands in. Weights
+      # summing under the bucket space serve the last slice rather than
+      # nothing — a mis-summed rollout degrades instead of failing.
+      def slice_for(slices, flag_key, salt, subject)
+        point = bucket(flag_key, subject, salt)
+        cursor = 0
+        slices.each do |s|
+          cursor += s["weight"]
+          return s["variant"] if point < cursor
+        end
+        slices.empty? ? nil : slices[-1]["variant"]
+      end
+
+      # rollout_subject: the subject a rollout buckets on. No context key at
+      # all is an anonymous caller — the rollout declines and lets the
+      # default serve. An explicit bucketBy naming an attribute the context
+      # does not carry is a misconfigured rollout: serving anything at all
+      # would measure against an identity nobody chose.
+      def rollout_subject(contexts, bucket_by, context_kind)
+        kind = Context.kind_or_default(context_kind)
+        if bucket_by.equal?(JsValues::MISSING)
+          return [Context.key_of_kind(contexts, kind), false]
+        end
+
+        subject = JsValues.stringify(Context.attribute_of_kind(contexts, kind, bucket_by))
+        [subject, subject.nil?]
+      end
+
+      def variant_value(flag, variant_key)
+        return nil if variant_key.nil? || variant_key == false || variant_key == ""
+
+        flag["definition"]["variants"].each do |v|
+          return [v["value"], v["key"]] if v["key"] == variant_key
+        end
+        nil
+      end
+
+      def clamp_weight(weight)
+        return 0 unless weight.is_a?(Numeric) && weight.to_f.finite?
+
+        [[weight, 0].max, BUCKET_SPACE].min
+      end
+
+      # search runs one `matches` pattern: compiled once, cached, never
+      # raising — a pattern that fails to compile matches nothing.
+      def search(pattern, actual)
+        compiled = RegexCache.compile(JsValues.js_string(pattern))
+        !compiled.nil? && compiled.match?(actual)
+      end
+
+      def compare_numeric(actual, expected, op)
+        a = JsValues.as_number(actual)
+        b = JsValues.as_number(expected)
+        return false if a.nil? || b.nil?
+
+        case op
+        when "gt" then a > b
+        when "gte" then a >= b
+        when "lt" then a < b
+        else a <= b
+        end
+      end
+
+      # own reads a record through its own keys only: a flag or segment named
+      # like a prototype member must stay "not found". JSON.parse-built hashes
+      # are own-key by construction; the key? guard keeps it true for any
+      # hash, default-proc or not.
+      def own(record, key)
+        record.is_a?(Hash) && record.key?(key) ? record[key] : nil
+      end
+    end
+  end
+end

data/lib/evolve_logs/flags/options.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  module Flags
+    # Launch flags client options (docs/LAUNCH-SDK.md §4, Ruby spellings).
+    #
+    # `cache` is nil for the default cache dir, false to disable caching, or
+    # a directory path. `exposures` carries the §7 knobs: enabled,
+    # sample_rate, dedupe_window_seconds, send_attributes.
+    class Options
+      attr_reader :enabled, :url, :mode, :poll_interval_seconds, :cache, :bootstrap,
+                  :exposures, :private_attributes, :stale_after_seconds
+
+      # Exposure option keys, snake_case (built from a Hash that may use
+      # strings or symbols).
+      EXPOSURE_KEYS = %i[enabled sample_rate dedupe_window_seconds send_attributes].freeze
+
+      def initialize(enabled: true, url: nil, mode: "stream", poll_interval_seconds: 30,
+                     cache: nil, bootstrap: nil, exposures: {}, private_attributes: [],
+                     stale_after_seconds: 300)
+        @enabled = enabled
+        @url = url
+        @mode = mode
+        @poll_interval_seconds = poll_interval_seconds
+        @cache = cache
+        @bootstrap = bootstrap
+        @exposures = self.class.normalize_exposures(exposures)
+        @private_attributes = private_attributes || []
+        @stale_after_seconds = stale_after_seconds
+      end
+
+      # build normalises the `flags:` argument of EvolveLogs.init /
+      # EvolveLogs::Client.new: nil, an Options, or a Hash with string or
+      # symbol keys. Unknown keys are ignored so a shared config hash never
+      # raises.
+      def self.build(value)
+        return new if value.nil?
+        return value if value.is_a?(Options)
+
+        hash = {}
+        if value.is_a?(Hash)
+          value.each do |k, v|
+            key = k.to_s.to_sym
+            hash[key] = v if %i[enabled url mode poll_interval_seconds cache bootstrap
+                                exposures private_attributes stale_after_seconds].include?(key)
+          end
+        end
+        hash[:exposures] = normalize_exposures(hash[:exposures])
+        new(**hash)
+      end
+
+      def self.normalize_exposures(value)
+        return {} unless value.is_a?(Hash)
+
+        out = {}
+        value.each do |k, v|
+          key = k.to_s.to_sym
+          out[key] = v if EXPOSURE_KEYS.include?(key)
+        end
+        out
+      end
+    end
+  end
+end

data/lib/evolve_logs/flags/regex_cache.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  module Flags
+    # Port of flags-kernel/src/regex.ts on Onigmo: compile once, cache ≤ 256
+    # (FIFO eviction), a pattern that fails to compile never matches.
+    #
+    # JavaScript (no m flag) anchors ^ and $ to the whole input; Ruby anchors
+    # them to lines — translate() rewrites them outside character classes so
+    # the same pattern answers the same question in both engines. `\d`, `\w`
+    # and `\b` are already ASCII in Ruby, as in JavaScript.
+    module RegexCache
+      LIMIT = 256
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        # compile returns the Regexp or nil; nil is cached too — a pattern
+        # that does not compile does not compile again.
+        def compile(pattern)
+          @mutex.synchronize do
+            return @cache[pattern] if @cache.key?(pattern)
+
+            compiled = begin
+              Regexp.new(translate(pattern))
+            rescue RegexpError, ArgumentError
+              nil
+            end
+            @cache.delete(@cache.keys.first) if @cache.size >= LIMIT
+            @cache[pattern] = compiled
+          end
+        end
+
+        private
+
+        # translate rewrites JavaScript anchors to Ruby's input anchors. A `^`
+        # directly after `[` is a negation and stays; escaped characters pass
+        # through; `(?` constructs are untouched (lookahead is Onigmo-valid,
+        # and the write-time portability check refuses it before a ruleset
+        # can carry it).
+        def translate(pattern)
+          out = +""
+          in_class = false
+          i = 0
+          while i < pattern.length
+            ch = pattern[i]
+            if ch == "\\" && i + 1 < pattern.length
+              out << pattern[i, 2]
+              i += 2
+              next
+            end
+            if in_class
+              in_class = false if ch == "]"
+              out << ch
+            elsif ch == "["
+              in_class = true
+              out << ch
+            elsif ch == "^"
+              out << "\\A"
+            elsif ch == "$"
+              out << "\\z"
+            else
+              out << ch
+            end
+            i += 1
+          end
+          out
+        end
+      end
+    end
+  end
+end