convert_sdk 1.0.0

data/lib/convert_sdk/rule_manager.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # The audience/segmentation rule walk — OR -> AND -> OR_WHEN — ported EXACTLY
+  # from the JS SDK +packages/rules/src/rule-manager.ts+. JS is the only truth
+  # here; the PHP port is quarantined (it diverges on the existence operators and
+  # on +isIn+ case-folding — see {Comparisons}).
+  #
+  # Structure & short-circuit order (mirrors rule-manager.ts:117-255):
+  #   * Top OR (+isRuleMatched+): for each AND-group, +match = process_and+;
+  #     return +true+ on the first matching group; after the loop return +match+
+  #     unless it is +false+ (so a {RuleError} sentinel propagates out). A missing
+  #     or empty +OR+ logs +RULE_NOT_VALID+ at warn and returns +false+.
+  #   * AND (+process_and+): for each OR_WHEN leaf-list, +match = process_or_when+;
+  #     return +match+ on the FIRST non-+true+ result (a +false+ or a sentinel
+  #     short-circuits the AND). All +true+ -> +true+. Missing/empty +AND+ ->
+  #     +RULE_NOT_VALID+ warn + +false+.
+  #   * OR_WHEN (+process_or_when+): for each leaf rule, +match = process_rule_item+;
+  #     return +true+ on the first match; after the loop return +match+ unless it
+  #     is +false+. Missing/empty +OR_WHEN+ -> +RULE_NOT_VALID+ warn + +false+.
+  #
+  # FR22 safety invariant: EVERY empty/missing block shape returns +false+ with a
+  # +RULE_NOT_VALID+ warn — an empty audience excludes everyone, it never matches
+  # everyone.
+  #
+  # The undefined-fallback (rule-manager.ts:323-333): when the data key for a leaf
+  # is ABSENT and the operator is +exists+/+doesNotExist+, the operator is invoked
+  # against {Comparisons::UNDEFINED} (JS +undefined+) so existence semantics hold
+  # for absent keys. Ruby models key-absence with the {Comparisons::UNDEFINED}
+  # marker because a plain +nil+ means "present null value" (JS +null+), which is
+  # a different existence outcome.
+  #
+  # RuleError propagation: a leaf that returns a {RuleError} sentinel propagates
+  # it up the walk via the non-true / non-false short-circuits above (Story 2.11
+  # maps the surfaced sentinel to the public return).
+  #
+  # Pure in-memory (NFR1). Rule options (+keys_case_sensitive+, +negation+) come
+  # from the injected {Config}, never inline. Valid-rule outcomes log at debug;
+  # invalid/empty shapes log +RULE_NOT_VALID+ at warn (rule-manager.ts levels).
+  #
+  # @api private
+  class RuleManager
+    # The +RULE_NOT_VALID+ message — byte-identical to the JS SDK dictionary
+    # (+packages/enums/src/dictionary.ts:12+: "Provided rule is not valid"). Logged
+    # at warn for every empty/missing/invalid block, the FR22 exclusion signal.
+    RULE_NOT_VALID = "Provided rule is not valid"
+
+    # Build a rule walker bound to a {Config}'s rule options and a comparison
+    # processor.
+    #
+    # @param config [Config] supplies +keys_case_sensitive+ and +negation+.
+    # @param comparisons [#dispatch] the operator processor (defaults to
+    #   {Comparisons}); must expose +dispatch+ (wire-name => method symbol) and
+    #   respond to each mapped method as +(value, test_against, negation)+.
+    # @param log_manager [LogManager, nil] optional logger; warn for invalid
+    #   shapes, debug for valid-rule outcomes.
+    def initialize(config:, comparisons: Comparisons, log_manager: nil)
+      @keys_case_sensitive = config.keys_case_sensitive
+      @comparisons = comparisons
+      @log_manager = log_manager
+    end
+
+    # Walk a rule set against a data hash. The top OR level.
+    #
+    # @param data [Hash{String=>Object}] the key-value data to match.
+    # @param rule_set [Hash] the OR/AND/OR_WHEN rule structure.
+    # @param log_entry [String, nil] an optional label for the entity being matched.
+    # @return [Boolean, Sentinel] true/false, or a {RuleError} sentinel propagated
+    #   from a leaf.
+    def is_rule_matched(data, rule_set, log_entry = nil)
+      or_groups = nonempty_block(rule_set, "OR")
+      unless or_groups
+        warn_rule_not_valid("RuleManager#is_rule_matched", log_entry)
+        return false
+      end
+
+      match = false
+      or_groups.each do |and_group|
+        match = process_and(data, and_group)
+        return true if match == true
+
+        log_outcome("RuleManager#is_rule_matched", match, log_entry)
+      end
+      return match if match != false
+
+      false
+    end
+
+    private
+
+    # AND block: every OR_WHEN leaf-list must return true. Returns the first
+    # non-true result (false or a sentinel short-circuits). rule-manager.ts:191-220.
+    def process_and(data, and_group)
+      leaves = nonempty_block(and_group, "AND")
+      unless leaves
+        warn_rule_not_valid("RuleManager#process_and")
+        return false
+      end
+
+      leaves.each do |or_when|
+        match = process_or_when(data, or_when)
+        return match if match != true
+      end
+      @log_manager&.debug("RuleManager#process_and: AND block matched")
+      true
+    end
+
+    # OR_WHEN block: the first matching leaf wins. After the loop, returns the
+    # last result unless false (so a sentinel propagates). rule-manager.ts:229-255.
+    def process_or_when(data, or_when)
+      leaves = nonempty_block(or_when, "OR_WHEN")
+      unless leaves
+        warn_rule_not_valid("RuleManager#process_or_when")
+        return false
+      end
+
+      match = false
+      leaves.each do |rule|
+        match = process_rule_item(data, rule)
+        return true if match == true
+      end
+      return match if match != false
+
+      false
+    end
+
+    # A single leaf rule. Validates shape, resolves the operator from the
+    # comparison processor's dispatch map, and evaluates it against the matching
+    # data value — or against {Comparisons::UNDEFINED} for an absent key under an
+    # existence operator. rule-manager.ts:264-365.
+    def process_rule_item(data, rule)
+      unless valid_rule?(rule)
+        warn_rule_not_valid("RuleManager#process_rule_item")
+        return false
+      end
+
+      negation = rule["matching"]["negated"] || false
+      match_type = rule["matching"]["match_type"]
+      method = @comparisons.dispatch[match_type]
+      unless method
+        @log_manager&.warn(
+          "RuleManager#process_rule_item: rule matching type #{match_type.inspect} is not supported"
+        )
+        return false
+      end
+
+      evaluate_leaf(data, rule, match_type, method, negation)
+    end
+
+    # Resolve the data value for the leaf's key and invoke the operator. Iterates
+    # the data keys honoring +keys_case_sensitive+; on a key match invokes the
+    # operator with the data value. On no key match, an existence operator is
+    # invoked against the UNDEFINED marker (undefined-fallback). Otherwise false.
+    def evaluate_leaf(data, rule, match_type, method, negation)
+      data_value = lookup_data_value(data, rule["key"])
+      unless data_value.equal?(Comparisons::UNDEFINED)
+        result = @comparisons.public_send(method, data_value, rule["value"], negation)
+        debug_outcome("key matched", match_type, result)
+        return result
+      end
+
+      # Key absent: only the existence operators fall back to the UNDEFINED
+      # marker (rule-manager.ts:323-333); everything else is a no-match.
+      if existence_operator?(match_type)
+        result = @comparisons.public_send(method, Comparisons::UNDEFINED, rule["value"], negation)
+        debug_outcome("existence-fallback", match_type, result)
+        return result
+      end
+
+      @log_manager&.debug("RuleManager#evaluate_leaf: key #{rule["key"].inspect} not found in data")
+      false
+    end
+
+    # Resolve the data value for a rule key honoring +keys_case_sensitive+.
+    # Returns {Comparisons::UNDEFINED} when the key is ABSENT — distinct from a
+    # present +nil+ value (JS null), which is returned as +nil+.
+    def lookup_data_value(data, rule_key)
+      return Comparisons::UNDEFINED unless data.is_a?(Hash) && !data.empty?
+
+      target = @keys_case_sensitive ? rule_key : rule_key.to_s.downcase
+      data.each do |key, value|
+        k = @keys_case_sensitive ? key : key.to_s.downcase
+        return value if k == target
+      end
+      Comparisons::UNDEFINED
+    end
+
+    # Debug-log a leaf evaluation outcome.
+    def debug_outcome(path, match_type, result)
+      @log_manager&.debug(
+        "RuleManager#evaluate_leaf: #{path} match_type=#{match_type.inspect} result=#{result.inspect}"
+      )
+    end
+
+    # JS +isValidRule+ (rule-manager.ts:162-182): requires a +matching+ object
+    # with string +match_type+ and boolean +negated+; existence operators are
+    # valid without a +value+, all others require a +value+ field.
+    def valid_rule?(rule)
+      return false unless rule.is_a?(Hash)
+
+      matching = rule["matching"]
+      return false unless matching.is_a?(Hash)
+      return false unless matching["match_type"].is_a?(String)
+      return false unless [true, false].include?(matching["negated"])
+      return true if existence_operator?(matching["match_type"])
+
+      rule.key?("value")
+    end
+
+    # The existence operators get the undefined-fallback and are value-optional.
+    # Mirrors the JS CookieMatchingOptions.EXISTS / DOES_NOT_EXIST special-case.
+    def existence_operator?(match_type)
+      %w[exists doesNotExist].include?(match_type)
+    end
+
+    # Extract +container[key]+ as a non-empty Array, or +nil+ when the container
+    # is not a Hash, the key is missing, the value is not an Array, or the Array
+    # is empty. The single source of the FR22 "empty/missing block" predicate —
+    # every empty/missing OR/AND/OR_WHEN shape collapses to +nil+ here.
+    def nonempty_block(container, key)
+      return nil unless container.is_a?(Hash)
+
+      value = container[key]
+      return nil unless value.is_a?(Array) && !value.empty?
+
+      value
+    end
+
+    # Emit a RULE_NOT_VALID warn (FR22 exclusion signal) — rule-manager.ts warn
+    # sites at :148/:214/:249/:359.
+    def warn_rule_not_valid(site, log_entry = nil)
+      suffix = log_entry ? " (#{log_entry})" : ""
+      @log_manager&.warn("#{site}: #{RULE_NOT_VALID}#{suffix}")
+    end
+
+    # Debug-log a valid-rule outcome (match / no-match / sentinel) at the OR level.
+    def log_outcome(site, match, log_entry)
+      suffix = log_entry ? " (#{log_entry})" : ""
+      @log_manager&.debug("#{site}: outcome=#{match.inspect}#{suffix}")
+    end
+  end
+end

data/lib/convert_sdk/segments_manager.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Visitor segmentation — the REPORTING-data layer that attaches segment ids to a
+  # visitor's +StoreData+ in the JS SDK's wire shape (FR28–FR30). Ported from the
+  # JS SDK +packages/segments/src/segments-manager.ts+; the PHP reference is
+  # QUARANTINED here because it diverges on two wire keys.
+  #
+  # == PHP-divergence #2 — the wire-key quarantine (FR30)
+  #
+  # JS +SegmentsKeys+ (+segments-keys.ts:7-15+) emit camelCase:
+  # +visitorType+ / +customSegments+. PHP +SegmentsKeys.php:14-15+ emit snake_case:
+  # +visitor_type+ / +custom_segments+ — a real, disk-verified divergence. Segment
+  # data rides the tracking payload's +segments+ object (Epic 4 +ApiManager+ emits
+  # the visitor's stored +segments+ verbatim), so the wrong key would silently
+  # mis-filter every Ruby segment-report. Ruby follows JS: the seven report-segment
+  # keys, and +customSegments+ in particular, are the ONLY ones persisted, as
+  # camelCase STRINGS at rest in +StoreData+. The {SegmentsManager} never produces
+  # the PHP variants; Story 3.2's quarantine spec asserts their absence.
+  #
+  # == The report-segment filter ({#filter_report_segments}, +data-manager.ts:1180-1199+)
+  #
+  # Exactly seven keys are report-segments: +country+, +browser+, +devices+,
+  # +source+, +campaign+, +visitorType+, +customSegments+. {#put_segments} keeps
+  # ONLY these; every other key is silently DROPPED (JS routes them to a separate
+  # +properties+ bucket the segments layer ignores) — IGNORE, not reject. Ruby adds
+  # a +debug+ line naming the dropped keys (an observability addition; JS drops
+  # silently). A filter that leaves NOTHING is a no-op write (JS +if (reportSegments)+).
+  #
+  # == Custom-segment evaluation REUSES the rule engine ({#select_custom_segments})
+  #
+  # +run_custom_segments+ does NOT introduce new rule logic. For each requested
+  # segment key it looks up the {ConfigSegment} entity (DataManager +segments+
+  # reader), evaluates that segment's +rules+ against the supplied
+  # +segment_rule+ data via {RuleManager#is_rule_matched} (so NEED_MORE_DATA and
+  # every operator semantic come for FREE), and — on a match — appends the
+  # segment's id to the visitor's stored +customSegments+ list (deduped). A
+  # surfaced {RuleError} sentinel propagates out verbatim (mirrors JS
+  # +setCustomSegments+'s +Object.values(RuleError).includes(...)+ early-return).
+  #
+  # == Persistence
+  #
+  # All writes flow through the {DataStoreManager} atomic visitor-data merge
+  # (Story 2.1) into +StoreData["segments"]+. Stored data is string-keyed
+  # wire-world by design (so Epic 4's payload builder needs zero translation).
+  #
+  # @api private
+  class SegmentsManager
+    # The +customSegments+ wire key — byte-identical to JS
+    # +SegmentsKeys.CUSTOM_SEGMENTS+ (+segments-keys.ts:14+). The visitor's matched
+    # custom-segment ids live under this key in +StoreData["segments"]+.
+    CUSTOM_SEGMENTS = "customSegments"
+
+    # The full report-segment key set — byte-identical to JS +SegmentsKeys+
+    # (+segments-keys.ts:7-15+). The report-segment filter is restricted to exactly
+    # these seven; +visitorType+/+customSegments+ are the JS wire keys that diverge
+    # from PHP's snake_case variants (FR30). The SINGLE source of the allowed set.
+    SEGMENTS_KEYS = %w[
+      country browser devices source campaign visitorType customSegments
+    ].freeze
+
+    # @param data_manager [DataManager] the config reader surface (supplies the
+    #   {ConfigSegment} entities by key and the account/project store-key halves).
+    # @param data_store_manager [DataStoreManager] the persistence port (atomic
+    #   visitor-data merge into +StoreData["segments"]+).
+    # @param account_resolver [#call] resolves the account id (store-key half).
+    # @param project_resolver [#call] resolves the project id (store-key half).
+    # @param rule_manager [RuleManager] the Epic 2 rule walker reused for
+    #   custom-segment evaluation (never re-implemented here).
+    # @param log_manager [LogManager, nil] optional logger; debug on misses/drops,
+    #   warn on already-present ids.
+    def initialize(data_manager:, data_store_manager:, account_resolver:,
+                   project_resolver:, rule_manager:, log_manager: nil)
+      @data_manager = data_manager
+      @data_store_manager = data_store_manager
+      @account_resolver = account_resolver
+      @project_resolver = project_resolver
+      @rule_manager = rule_manager
+      @log_manager = log_manager
+    end
+
+    # Set default report-segments for a visitor (JS +setDefaultSegments+ ->
+    # +putSegments+, +context.ts:434-436+ / +segments-manager.ts:78-85+).
+    #
+    # The supplied segments are passed through {#filter_report_segments} (only the
+    # seven {SEGMENTS_KEYS} survive); a non-empty result is merged into the
+    # visitor's +StoreData["segments"]+ via the atomic store merge. An all-dropped
+    # input is a no-op (JS +if (reportSegments)+).
+    #
+    # @param visitor_id [String]
+    # @param segments [Hash] the candidate report-segments (string-keyed wire shape).
+    # @return [void]
+    def put_segments(visitor_id, segments)
+      report_segments = filter_report_segments(segments)
+      return if report_segments.empty?
+
+      merge_segments(visitor_id, report_segments)
+      nil
+    end
+
+    # Evaluate the named custom segments for a visitor and attach matching ids
+    # (JS +selectCustomSegments+ -> +setCustomSegments+, +segments-manager.ts:153-185+).
+    #
+    # Each requested key is resolved to a {ConfigSegment} via the DataManager
+    # +segments+ reader; the segment's +rules+ are walked against +segment_rule+
+    # by {RuleManager#is_rule_matched}. A surfaced {RuleError} sentinel propagates
+    # out verbatim (no attachment). Matching segment ids are appended to the
+    # visitor's stored +customSegments+ list (deduped); an unknown key is skipped
+    # with a debug log.
+    #
+    # @param visitor_id [String]
+    # @param segment_keys [Array<String>] the segment keys to evaluate.
+    # @param segment_rule [Hash, nil] the visitor data the segment rules match
+    #   against; +nil+ attaches every resolved segment unconditionally (JS:
+    #   +if (!segmentRule || segmentsMatched)+).
+    # @return [Hash, Sentinel, nil] the updated segments hash, a propagated
+    #   {RuleError}, or +nil+ when nothing matched.
+    def select_custom_segments(visitor_id, segment_keys, segment_rule = nil)
+      segments = lookup_segments(segment_keys)
+      set_custom_segments(visitor_id, segments, segment_rule)
+    end
+
+    private
+
+    # Keep ONLY the seven {SEGMENTS_KEYS} report-segments; silently drop the rest
+    # (JS +filterReportSegments+, +data-manager.ts:1180-1199+ — non-segment keys go
+    # to a +properties+ bucket the segments layer ignores). Dropped keys are named
+    # in a debug line (Ruby observability addition). Returns a string-keyed hash
+    # (possibly empty).
+    def filter_report_segments(segments)
+      return {} unless segments.is_a?(Hash)
+
+      kept = {} #: Hash[String, untyped]
+      dropped = [] #: Array[String]
+      segments.each do |key, value|
+        if SEGMENTS_KEYS.include?(key)
+          kept[key] = value
+        else
+          dropped << key
+        end
+      end
+      unless dropped.empty?
+        @log_manager&.debug("SegmentsManager#filter_report_segments: dropped non-report keys #{dropped.inspect}")
+      end
+      kept
+    end
+
+    # Resolve the requested segment keys to {ConfigSegment} entities via the
+    # DataManager +segments+ reader (JS +getEntities(keys, 'segments')+). Unknown
+    # keys yield no entity and are debug-logged + skipped. Preserves request order.
+    def lookup_segments(segment_keys)
+      return [] unless segment_keys.is_a?(Array)
+
+      all = @data_manager.segments
+      segment_keys.filter_map do |key|
+        entity = all.find { |seg| seg.is_a?(Hash) && seg["key"] == key }
+        @log_manager&.debug("SegmentsManager#lookup_segments: no segment found for key=#{key}") unless entity
+        entity
+      end
+    end
+
+    # The id-attachment core (JS +setCustomSegments+, +segments-manager.ts:87-143+).
+    # For each resolved segment: when a rule is supplied and nothing has matched
+    # yet, walk the segment's rules — a {RuleError} sentinel short-circuits and
+    # propagates out. On a match (or when no rule was supplied) append the segment
+    # id unless already stored. A non-empty append is persisted via {#put_segments}.
+    def set_custom_segments(visitor_id, segments, segment_rule)
+      existing = stored_custom_segments(visitor_id)
+      segment_ids = [] #: Array[String]
+      matched = false #: (bool | Sentinel)
+
+      segments.each do |segment|
+        if segment_rule && matched != true
+          matched = @rule_manager.is_rule_matched(segment_rule, segment["rules"], "ConfigSegment ##{segment["id"]}")
+          return matched if matched.is_a?(Sentinel)
+        end
+
+        next unless !segment_rule || matched == true
+
+        append_segment_id(segment, existing, segment_ids)
+      end
+
+      persist_custom_segments(visitor_id, existing, segment_ids)
+    end
+
+    # Append +segment["id"]+ (stringified) to the pending list unless it is already
+    # stored or already pending; an already-stored id warns (JS
+    # +CUSTOM_SEGMENTS_KEY_FOUND+).
+    def append_segment_id(segment, existing, segment_ids)
+      id = segment["id"]&.to_s
+      return if id.nil?
+
+      if existing.include?(id)
+        @log_manager&.warn("SegmentsManager#set_custom_segments: custom segment id #{id} already stored")
+      elsif !segment_ids.include?(id)
+        segment_ids << id
+      end
+    end
+
+    # Persist the newly-matched ids (appended to the existing list) into
+    # +StoreData["segments"]["customSegments"]+, or no-op + debug when nothing
+    # matched (JS +SEGMENTS_NOT_FOUND+). Returns the persisted segments hash or nil.
+    def persist_custom_segments(visitor_id, existing, segment_ids)
+      if segment_ids.empty?
+        @log_manager&.debug("SegmentsManager#set_custom_segments: no segments matched")
+        return nil
+      end
+
+      segments_data = { CUSTOM_SEGMENTS => existing + segment_ids }
+      put_segments(visitor_id, segments_data)
+      segments_data
+    end
+
+    # The visitor's currently-stored +customSegments+ id list (or +[]+), read from
+    # +StoreData["segments"]+ through the store seam.
+    def stored_custom_segments(visitor_id)
+      key = @data_store_manager.visitor_key(account_id, project_id, visitor_id)
+      stored = @data_store_manager.get(key)
+      segments = stored.is_a?(Hash) ? stored["segments"] : nil
+      list = segments.is_a?(Hash) ? segments[CUSTOM_SEGMENTS] : nil
+      list.is_a?(Array) ? list : []
+    end
+
+    # Atomically merge a report-segments partial into +StoreData["segments"]+.
+    def merge_segments(visitor_id, report_segments)
+      @data_store_manager.merge_visitor_data(account_id, project_id, visitor_id) do |_current|
+        { "segments" => report_segments }
+      end
+    end
+
+    # The account / project halves of the visitor store key (coerced to String —
+    # nil-safe before any config is installed).
+    def account_id
+      @account_resolver.call.to_s
+    end
+
+    def project_id
+      @project_resolver.call.to_s
+    end
+  end
+end

data/lib/convert_sdk/sentinel.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # A frozen singleton sentinel — the SDK's public contract for a *business miss*.
+  #
+  # Bucketing and feature decisions that find no answer (no data, not enough
+  # data, no variation decided) return a +Sentinel+ singleton rather than raising
+  # or returning a bare +nil+. This is architecture Decision 2: misses are
+  # signaled by value, never by exception.
+  #
+  # The protocol a +Sentinel+ implements:
+  #
+  # * +#to_s+   — the byte-identical JS wire string (appears in payloads/logs).
+  # * +#key+    — always +nil+, so the documented integrator pattern
+  #   +case variation&.key+ falls through to the +else+ branch on a miss.
+  # * +#error?+ — always +true+, the value-object discriminator that distinguishes
+  #   a sentinel from a real {BucketedVariation}/{BucketedFeature} (both +false+).
+  #
+  # Sentinels are exposed as frozen singleton constants (e.g.
+  # {RuleError::NO_DATA_FOUND}), so callers can branch on object identity for
+  # granular handling:
+  #
+  #   result = context.run_experience("homepage-test")
+  #   case result.key
+  #   when nil
+  #     # a miss — inspect which one via identity
+  #     show_default if result.equal?(ConvertSdk::RuleError::NO_DATA_FOUND)
+  #   else
+  #     render_variation(result.key)
+  #   end
+  #
+  # Equality is intentionally left as default object identity (no +==+ override):
+  # two distinct +Sentinel+ instances built from the same wire string are NOT
+  # equal, which is why the canonical instances live as shared frozen constants.
+  class Sentinel
+    # @param wire_string [String] the JS-parity wire string this sentinel emits.
+    def initialize(wire_string)
+      @wire_string = wire_string.dup.freeze
+      freeze
+    end
+
+    # @return [String] the byte-identical JS wire string.
+    def to_s
+      @wire_string
+    end
+
+    # @return [nil] always nil, so +case variation&.key+ falls through to else.
+    def key
+      nil
+    end
+
+    # @return [Boolean] always true — a sentinel always signals a business miss.
+    def error?
+      true
+    end
+  end
+end

data/lib/convert_sdk/stores/memory_store.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Stores backing the SDK's persistence port (sticky bucketing, goal dedup,
+  # config caching). Every store duck-types to +#get(key)+ / +#set(key, value)+
+  # — the public extension point validated by {DataStoreManager} at wiring time.
+  module Stores
+    # The default in-process store: a plain +Hash+ guarded by a +Mutex+.
+    #
+    # +MemoryStore+ is what {DataStoreManager} falls back to when no custom
+    # store is supplied (or a supplied store fails validation). It satisfies the
+    # duck-typed store contract — +#get+ / +#set+ — with both operations
+    # serialized through a single mutex so concurrent reads and writes from
+    # multiple threads cannot corrupt the underlying +Hash+ or lose a write.
+    #
+    # == Per-process limitation
+    #
+    # State lives only in this process's memory. It is NOT shared across
+    # processes, workers, or machines: sticky bucketing (Story 2.11) and goal
+    # deduplication (Story 4.3) that round-trip through a +MemoryStore+ are
+    # therefore consistent only within the lifetime of a single process. A
+    # forked web worker, a restarted process, or a second host each start with
+    # an empty store. For cross-process stickiness and dedup, supply a shared
+    # backing store — +RedisStore+ (Story 2.2) is the first-party option.
+    #
+    # == Thread safety
+    #
+    # All access to the backing +Hash+ is serialized by +@mutex+; there is no
+    # public path to the +Hash+ that bypasses the lock.
+    class MemoryStore
+      def initialize
+        # Thread safety: guarded by @mutex.
+        @data = {}
+        @mutex = Thread::Mutex.new
+      end
+
+      # Read the value stored under +key+.
+      #
+      # @param key [String] the lookup key.
+      # @return [Object, nil] the stored value, or +nil+ if the key is absent.
+      def get(key)
+        @mutex.synchronize { @data[key] }
+      end
+
+      # Store +value+ under +key+, overwriting any existing value.
+      #
+      # @param key [String] the storage key.
+      # @param value [Object] the value to store.
+      # @return [Object] the stored value.
+      def set(key, value)
+        @mutex.synchronize { @data[key] = value }
+      end
+    end
+  end
+end