insika 0.1.0 → 0.3.0

data/lib/insika/followup_engine.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # the tick-driven FIRER of follow-up records: one
+  # pass per claim window; each record is its own claim (pending -> fired + task
+  # creation + the contact bump in ONE transaction — D5). Gating order (D6):
+  #
+  #   policy valid? -> contact state (never-granted / revoked / unavailable ->
+  #   block) -> quiet hours? (pending — DEFER) -> dedup guard (block) ->
+  #   frequency ceiling (block) -> FIRE.
+  #
+  # Blocking is at fire time, never at schedule time; a `blocked` record is
+  # auditable, never silent. The engine never modifies a policy and never
+  # invents a reason — the turn it creates is delivered entirely by the existing
+  # pipeline (it holds no channel code).
+  class FollowupEngine
+    SCOPE = "followup_fire"
+    KEY = "claim"
+    DEFAULT_WINDOW = 300 # seconds; one firing worker per window
+
+    # The engine's kick text. The agent composes the customer-visible message
+    # itself — the engine never writes a word the customer reads. %{reason} and
+    # %{now} (UTC) are empty-escaped.
+    FIRING_PROMPT = "You are following up on a previous conversation, as " \
+                    "scheduled and with the customer's consent. The follow-up " \
+                    "reason: %{reason}. It is now %{now} (UTC). Write ONE short " \
+                    "follow-up message to the customer now, referencing the " \
+                    "earlier conversation."
+
+    def initialize(store:, followup_store:, contact_store:, task_store:,
+                   profiles:, executor:, window: DEFAULT_WINDOW,
+                   now: nil, logger: nil, event_stream: nil)
+      @store = store
+      @followup_store = followup_store
+      @contact_store = contact_store
+      @task_store = task_store
+      @profiles = profiles
+      @executor = executor
+      @window = window
+      @now = now
+      @logger = logger
+      @event_stream = event_stream
+    end
+
+    # -> { claimed: false }
+    #  | { claimed: true, fired: N, blocked: N, errors: N,
+    #      blocked_reasons: { "rule" => N }, deferred: N }
+    # A StoreError on ONE record aborts THAT record's transaction (rescued,
+    # counted, the loop continues) — a broken record must not hold the other
+    # stores' follow-ups hostage.
+    def run
+      now_time = @now || Time.now.utc
+      return { claimed: false } unless claim_window(now_time)
+
+      fired = 0
+      blocked = 0
+      deferred = 0
+      errors = 0
+      reasons = Hash.new(0)
+
+      # D7 at fire time: when more than one PENDING record holds the same
+      # (customer, reason), only the OLDEST fires. The verdict is snapshotted
+      # at pass start — a record that fires earlier in THIS pass must still
+      # dedup the younger ones behind it.
+      dedup_snapshot = {}
+      due = @followup_store.due(now: now_time)
+      due.each do |record|
+        pair = [record.tenant, record.agent, record.customer, record.reason]
+        dedup_snapshot[pair] ||= @followup_store
+                                  .pending_for(tenant: record.tenant, agent: record.agent,
+                                               customer: record.customer, reason: record.reason)
+                                  &.id
+      end
+
+      due.each do |record|
+        begin
+          outcome = fire_record(record, now_time,
+                                older_pending_id: dedup_snapshot[[record.tenant, record.agent,
+                                                                   record.customer, record.reason]])
+          case outcome
+          when :fired then fired += 1
+          when :deferred then deferred += 1
+          when Array
+            # a blocked record is auditable, never silent — the failing rule is
+            # written down on the record itself (D6/D9).
+            @followup_store.block(id: record.id, reason: outcome[1], now: now_time)
+            blocked += 1
+            reasons[outcome[1].to_s] += 1
+          end
+        rescue StandardError
+          # a broken record must not hold the other records' follow-ups
+          # hostage — its own transaction already rolled back.
+          errors += 1
+        end
+      end
+
+      { claimed: true, fired: fired, blocked: blocked, errors: errors,
+        blocked_reasons: reasons, deferred: deferred }
+    end
+
+    private
+
+    # -> :fired | :deferred | [:blocked, rule]
+    def fire_record(record, now_time, older_pending_id: nil)
+      profile = @profiles.fetch(record.agent)
+      policy = profile && Insika::FollowupPolicy.parse(profile.respond_to?(:followup) ? profile.followup : nil)
+      # D9: a malformed policy (or a missing profile) is a BLOCK, never a crash
+      # and never a silent fire.
+      return [:blocked, :policy_invalid] if policy.nil?
+
+      contact = @contact_store.get(tenant: record.tenant, customer: record.customer)
+      return [:blocked, :consent] if contact.nil?       # never messaged (D2)
+      return [:blocked, :revoked] if contact.state == "revoked"
+      return [:blocked, :unavailable] if contact.state == "unavailable"
+
+      # quiet hours keep the record PENDING — that IS the deferral; the next
+      # pass retries it (never a terminal block).
+      return :deferred if policy.quiet?(now_time)
+
+      # D7 at fire time: only the OLDEST pending per (customer, reason) fires;
+      # a younger pending of the same pair blocks (the snapshot taken at pass
+      # start, so a same-pass fire still dedups the younger ones).
+      if older_pending_id && older_pending_id != record.id
+        return [:blocked, :dedup]
+      end
+
+      # frequency: fired sends inside the window already at the ceiling -> block
+      if (window = policy.frequency_window) && window[:count].positive?
+        sent = @followup_store.fired_in_window(tenant: record.tenant, customer: record.customer,
+                                               since: now_time - window[:seconds])
+        return [:blocked, :frequency] if sent >= window[:count]
+      end
+
+      fire(record, policy, now_time)
+      :fired
+    end
+
+    # The atomic claim (D5): the record and the turn commit together or
+    # together fail. Within ONE transaction: create the synthetic task, flip
+    # the record to fired (with the task id), bump the contact counter — and
+    # mark :unavailable when the bump reaches the policy's silence ceiling.
+    def fire(record, policy, now_time)
+      message = format(FIRING_PROMPT, reason: record.reason.to_s, now: now_time.utc.iso8601)
+      command = { "type" => "scheduled_followup",
+                  "session_id" => record.session_id,
+                  "payload" => { "agent" => record.agent, "session_id" => record.session_id,
+                                 "customer" => record.customer, "message" => message,
+                                 "origin" => Insika::MessageOrigin::SCHEDULED },
+                  "meta" => { "tenant" => record.tenant, "transport" => record.transport } }
+
+      @store.transaction do
+        task = @task_store.create(command: command, session_id: record.session_id)
+        @followup_store.transition_fired(id: record.id, task_id: task.id, now: now_time)
+        cell = @contact_store.bump_outbound(tenant: record.tenant, customer: record.customer,
+                                            now: now_time)
+        if cell.sends_without_reply >= policy.silence_after_sends
+          @contact_store.mark_unavailable(tenant: record.tenant, customer: record.customer,
+                                          now: now_time)
+        end
+      end
+
+      # AFTER the commit: spawn. A spawn failure leaves a durable :queued task
+      # — the recovery sweep resumes it (a queued task is claimed once).
+      task_id = @followup_store.find(record.id).task_id
+      task = @task_store.find(task_id)
+      profile = @profiles.fetch(record.agent)
+      @executor.spawn_in_session(task, profile: profile)
+      emit_fired(record, task_id)
+      task_id
+    end
+
+    # :followup_fired carries ids only — a follow-up record's reason is contact
+    # data that rides the record and the Studio, never the event stream.
+    def emit_fired(record, task_id)
+      return unless @event_stream
+
+      @event_stream.emit(Insika::Event.new(
+                           type: :followup_fired,
+                           data: { id: record.id, agent: record.agent, customer: record.customer,
+                                   task_id: task_id, arm: record.arm },
+                           meta: { tenant: record.tenant, at: Time.now.utc.iso8601 }
+                         ))
+    end
+
+    # The claim window (funnel_fold.rb's idiom — read-check-write on one key
+    # inside a transaction): the O(n) scan never rides the 60 s tick, and two
+    # workers racing serialize on the backend's lock.
+    def claim_window(now_time)
+      @store.transaction do
+        current = @store.get(SCOPE, KEY)
+        last = current && begin
+          Time.iso8601(current["claimed_at"].to_s)
+        rescue ArgumentError
+          nil # a corrupted claim is not a claim — take the window
+        end
+        if last.nil? || (now_time - last) >= @window
+          @store.set(SCOPE, KEY, { "claimed_at" => now_time.iso8601 })
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/insika/followup_policy.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Insika
+  # the parsed follow-up policy of ONE agent — the ONLY shape the
+  # engine accepts, shared by the schedule/cancel tools, the FollowupEngine,
+  # the doctor and the Studio. Pure value object: it never touches a store
+  # (D8 — the policy is pack data on the profile, no platform settings layer).
+  #
+  # `parse` returns nil on a malformed hash (D9 — the firer BLOCKS, the doctor
+  # explains, the tools refuse); `parse!` raises Insika::ValidationError naming
+  # the exact defect.
+  class FollowupPolicy
+    QuietHours = Data.define(:timezone, :start, :end)
+
+    FREQUENCY_RE = /\A(\d+)\/(\d+)(m|h|d)s?\z/
+    HH_MM_RE     = /\A\d{2}:\d{2}\z/
+    DEFAULT_ARM = "schedule"
+    DEFAULT_SILENCE_AFTER_SENDS = 3
+    KEYWORD_MAX = 200
+
+    attr_reader :arm, :quiet_hours, :max_frequency, :cancel_keywords, :silence_after_sends
+
+    def self.parse(hash)
+      new(hash)
+    rescue Insika::ValidationError
+      nil
+    end
+
+    def self.parse!(hash)
+      new(hash)
+    end
+
+    def initialize(hash)
+      raise Insika::ValidationError, "followup: declaration must be a Hash" unless hash.is_a?(Hash)
+
+      h = hash.transform_keys(&:to_s)
+      @arm = arm_of(h)
+      policy = h["policy"]
+      raise Insika::ValidationError, "followup.policy must be a Hash" unless policy.is_a?(Hash)
+
+      policy = policy.transform_keys(&:to_s)
+      @quiet_hours = quiet_hours_of(policy)
+      @max_frequency = frequency_of(policy)
+      @cancel_keywords = keywords_of(policy)
+      @silence_after_sends = silence_of(policy)
+      freeze
+    end
+
+    # "2/24h" -> { count: 2, seconds: 86_400 }. nil when the policy has no
+    # ceiling (absent max_frequency — the frequency gate is off). Always valid
+    # once parsed.
+    # `count` is the sends allowed per window; `seconds` is the WINDOW's
+    # duration (the value after the "/"), never count*window.
+    def frequency_window
+      return nil if @max_frequency.nil?
+
+      match = FREQUENCY_RE.match(@max_frequency)
+      multiplier = { "m" => 60, "h" => 3600, "d" => 86_400 }.fetch(match[3])
+      { count: match[1].to_i, seconds: match[2].to_i * multiplier }
+    end
+
+    # Is the given UTC Time inside quiet hours in the policy's timezone? (nil
+    # quiet_hours -> false: no quiet window.)
+    #
+    # IANA names are resolved through the OS tz database by pointing Ruby's
+    # `TZ` at the zone for the computation (Ruby stdlib's `Time#getlocal`
+    # only takes an offset, not a zone name). Save/restore keeps the global
+    # intact; under the engine's cooperative fiber model — no IO between the
+    # save and the restore — the mutation is atomic on the calling fiber.
+    def quiet?(time)
+      return false unless @quiet_hours
+
+      local = in_zone(@quiet_hours.timezone, time) { |t| t.getlocal }
+      minutes = local.hour * 60 + local.min
+      start_min = minutes_of(@quiet_hours.start)
+      end_min = minutes_of(@quiet_hours.end)
+      if start_min <= end_min
+        minutes >= start_min && minutes < end_min
+      else
+        # an overnight window: 21:30-09:00
+        minutes >= start_min || minutes < end_min
+      end
+    end
+
+    # The first cancel keyword matched (case/accent-insensitive substring);
+    # nil when none matches.
+    def match_keyword(text)
+      folded = fold(text)
+      @cancel_keywords.each do |kw|
+        return kw if folded.include?(fold(kw))
+      end
+      nil
+    end
+
+    def to_h
+      { "arm" => @arm,
+        "policy" => {
+          "quiet_hours" => @quiet_hours && {
+            "timezone" => @quiet_hours.timezone, "start" => @quiet_hours.start, "end" => @quiet_hours.end
+          },
+          "max_frequency" => @max_frequency,
+          "cancel_keywords" => @cancel_keywords,
+          "silence_after_sends" => @silence_after_sends
+        }.compact }
+    end
+
+    private
+
+    def arm_of(hash)
+      arm = hash["arm"]
+      return DEFAULT_ARM if arm.nil?
+
+      arm = arm.to_s
+      raise Insika::ValidationError, "followup.arm must be a non-blank String" if arm.strip.empty?
+
+      arm
+    end
+
+    def quiet_hours_of(policy)
+      qh = policy["quiet_hours"]
+      return nil if qh.nil?
+
+      raise Insika::ValidationError, "followup.policy.quiet_hours must be a Hash" unless qh.is_a?(Hash)
+
+      qh = qh.transform_keys(&:to_s)
+      timezone = qh["timezone"]
+      raise Insika::ValidationError, "followup.policy.quiet_hours.timezone is required" if Coercion.blank?(timezone)
+
+      start_at = qh["start"]
+      end_at = qh["end"]
+      unless HH_MM_RE.match?(start_at.to_s) && HH_MM_RE.match?(end_at.to_s)
+        raise Insika::ValidationError,
+              "followup.policy.quiet_hours.start/end must match /\\A\\d{2}:\\d{2}\\z/ (24h)"
+      end
+
+      # a bogus IANA zone is a malformed policy — refused HERE, where the
+      # doctor can name it. An unknown ENV["TZ"] silently behaves as UTC, so
+      # existence is checked against the OS tz database, not by asking Time.
+      unless zone_known?(timezone.to_s)
+        raise Insika::ValidationError,
+              "followup.policy.quiet_hours.timezone is not a valid IANA timezone: #{timezone.inspect}"
+      end
+      QuietHours.new(timezone: timezone.to_s, start: start_at.to_s, end: end_at.to_s)
+    end
+
+    def frequency_of(policy)
+      f = policy["max_frequency"]
+      return nil if f.nil?
+
+      f = f.to_s
+      unless FREQUENCY_RE.match?(f)
+        raise Insika::ValidationError,
+              "followup.policy.max_frequency must match /\\A\\d+\\/(\\d+)(m|h|d)s?\\z/ (e.g. \"2/24h\"; weeks are not allowed)"
+      end
+
+      f
+    end
+
+    def keywords_of(policy)
+      list = policy["cancel_keywords"]
+      return [] if list.nil?
+
+      raise Insika::ValidationError, "followup.policy.cancel_keywords must be an Array" unless list.is_a?(Array)
+
+      list.map!(&:to_s)
+      list.each do |kw|
+        if Coercion.blank?(kw)
+          raise Insika::ValidationError, "followup.policy.cancel_keywords: each keyword must be non-blank"
+        end
+        if kw.length > KEYWORD_MAX
+          raise Insika::ValidationError,
+                "followup.policy.cancel_keywords: each keyword must be <= #{KEYWORD_MAX} chars"
+        end
+      end
+      list
+    end
+
+    def silence_of(policy)
+      s = policy["silence_after_sends"]
+      return DEFAULT_SILENCE_AFTER_SENDS if s.nil?
+
+      raise Insika::ValidationError, "followup.policy.silence_after_sends must be an Integer > 0" unless s.is_a?(Integer) && s.positive?
+
+      s
+    end
+
+    # NFD + strip combining marks + downcase: the same fold the doctor's
+    # identity matcher uses, so "NÃO" matches "não".
+    def fold(text)
+      text.to_s.unicode_normalize(:nfd).gsub(/\p{Mn}/, "").downcase
+    end
+
+    # Yields `time` interpreted in the given IANA zone (via a save/restore of
+    # ENV["TZ"] — the stdlib-only route to the OS tz database; see #quiet?).
+    def in_zone(zone, time)
+      previous = ENV["TZ"]
+      ENV["TZ"] = zone
+      yield time
+    ensure
+      ENV["TZ"] = previous
+    end
+
+    # The candidate tz-data roots (TZDIR first — Ruby's own lookup env). The
+    # zone name maps to a FILE under the root ("America/Sao_Paulo" ->
+    # "America/Sao_Paulo").
+    TZ_ROOTS = ([ENV["TZDIR"]] +
+                %w[/usr/share/zoneinfo /usr/share/lib/zoneinfo /etc/zoneinfo])
+               .compact.freeze
+
+    def zone_known?(zone)
+      return true if zone == "UTC" || zone == "Etc/UTC"
+
+      TZ_ROOTS.any? { |root| File.directory?(root) && File.exist?(File.join(root, zone)) }
+    end
+
+    def minutes_of(hhmm)
+      h, m = hhmm.split(":").map(&:to_i)
+      h * 60 + m
+    end
+  end
+end