insika 0.2.0 → 0.3.0

data/lib/insika/commands/record_shadow_reply.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # C4 — the incumbent's half of a shadow pair, recorded on the mirror's
+    # word. One command, two doors: Shape 1 (the reply rides the mirror call
+    # itself) and Shape 2 (the follow-up route, for a consumer that mirrors
+    # before answering) both dispatch HERE, so there is one behaviour and one
+    # store method behind both.
+    #
+    # Idempotency is first-write-wins: the customer received ONE reply, and
+    # letting a retry overwrite it would silently rewrite evidence. The
+    # guarantee lives in ShadowPairStore#record_incumbent (inside its
+    # transaction); the find below is only the cheap fast path for the common
+    # retry. A reply for a pair that does not exist yet creates it :open — the
+    # mirror may legitimately arrive before our turn finishes.
+    class RecordShadowReply
+      def initialize(shadow_pairs:, event_stream: nil)
+        @shadow_pairs = shadow_pairs
+        @event_stream = event_stream
+      end
+
+      # payload: { channel:, external_id:, event_id:, reply:, at: }
+      # -> { pair_id:, status: }
+      def call(command)
+        payload = command.payload
+        channel = Coercion.presence(payload[:channel] || payload["channel"])
+        external_id = Coercion.presence(payload[:external_id] || payload["external_id"])
+        event_id = Coercion.presence(payload[:event_id] || payload["event_id"])
+        reply = payload[:reply] || payload["reply"]
+
+        raise ValidationError, "channel is required" if channel.nil?
+        raise ValidationError, "external_id is required" if external_id.nil?
+        raise ValidationError, "event_id is required" if event_id.nil?
+        raise ValidationError, "reply is required" if reply.to_s.strip.empty?
+
+        id = ShadowPairStore.key_for(channel: channel, external_id: external_id,
+                                     event_id: event_id)
+        existing = @shadow_pairs.find(id)
+        if existing && !existing.incumbent_reply.nil?
+          emit(id, "already_recorded")
+          return { pair_id: id, status: "already_recorded" }
+        end
+
+        pair = @shadow_pairs.record_incumbent(id: id, channel: channel, event_id: event_id,
+                                              external_id: external_id, reply: reply.to_s,
+                                              at: payload[:at] || payload["at"])
+        emit(id, pair.status.to_s)
+        { pair_id: id, status: pair.status.to_s }
+      end
+
+      private
+
+      # Metadata only: the pair id and its status, never the reply's text.
+      def emit(pair_id, status)
+        return unless @event_stream
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :shadow_reply_recorded,
+                             data: { pair_id: pair_id, status: status },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/reject_harvest.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    #   — the operator's dismissal: a candidate that is NOT yet
+    # gated can be rejected by a human directly (a human may always outvote
+    # the miner). The thin wrapper over `mark_rejected`.
+    class RejectHarvest
+      def initialize(harvest_store:, event_stream:)
+        @harvest_store = harvest_store
+        @event_stream = event_stream
+      end
+
+      # payload: { candidate_id:, operator?, note? }
+      # -> Candidate (rejected)
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        candidate_id = AgentPayload.presence(p[:candidate_id])
+        raise Insika::ValidationError, "candidate_id is required" if candidate_id.nil?
+
+        candidate = @harvest_store.find_candidate(candidate_id) ||
+                    (raise Insika::NotFoundError, "harvest candidate not found: #{candidate_id}")
+        operator = (AgentPayload.presence(p[:operator]) || command.meta[:operator] || "operator").to_s
+        rejected = @harvest_store.mark_rejected(candidate.id, operator: operator, note: p[:note])
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :harvest_rejected,
+                             data: { candidate_id: candidate.id, agent: candidate.agent,
+                                     operator: operator },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        rejected
+      end
+    end
+  end
+end

data/lib/insika/commands/resolve_proposal.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # the human's answer : approve (→ the
+    # store, CAS, provenance `distilled:<session_ref>`), reject (with an
+    # optional reason), dismiss (latches the tuple). Approval never silently
+    # overwrites an operator edit (D5/E3): the CAS baseline captured at distill
+    # time guards the write, and a lost race flips the proposal to `:stale`
+    # carrying the fact's CURRENT value — both values visible on the wiki.
+    # Synchronous control command — the Studio dispatches it; no task, no actor.
+    class ResolveProposal
+      DECISIONS = %w[approved rejected dismissed].freeze
+
+      def initialize(proposal_store:, memory_store:, event_stream:)
+        @proposal_store = proposal_store
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      # payload: { proposal_id:, decision: "approved"|"rejected"|"dismissed",
+      #            operator?, note? }
+      # operator from payload || command.meta[:operator] || "operator"
+      # -> Proposal (the resolved record; a :stale one carries current_value)
+      def call(command)
+        proposal_id = Coercion.presence(command.payload[:proposal_id] || command.payload["proposal_id"])
+        raise ValidationError, "proposal_id is required" if proposal_id.nil?
+
+        decision = Coercion.presence(command.payload[:decision] || command.payload["decision"])
+        raise ValidationError, "decision is required" unless DECISIONS.include?(decision)
+
+        proposal = @proposal_store.find(proposal_id)
+        raise Insika::NotFoundError, "proposal not found: #{proposal_id}" if proposal.nil?
+
+        operator = operator_for(command)
+        note = Coercion.presence(command.payload[:note] || command.payload["note"])
+
+        case decision
+        when "approved" then approve(command, proposal, operator, note)
+        when "rejected"
+          resolved = @proposal_store.reject(id: proposal.id, operator: operator, note: note)
+          emit(:proposal_rejected, resolved)
+          resolved
+        else # "dismissed"
+          resolved = @proposal_store.dismiss(id: proposal.id, operator: operator, note: note)
+          emit(:proposal_dismissed, resolved)
+          resolved
+        end
+      end
+
+      private
+
+      # The whole safety argument (D5/E3). The read-check-write CAS rides the
+      # store's transaction — a lost race is a re-present, never a silent
+      # overwrite.
+      def approve(command, proposal, operator, note)
+        fact = @memory_store.get_fact(tenant: proposal.tenant, customer: proposal.customer,
+                                      key: proposal.key)
+        if proposal.expected_existed
+          if fact && fact.updated_at == proposal.expected_revision
+            written = @memory_store.replace_if_revision(
+              tenant: proposal.tenant, customer: proposal.customer,
+              key: proposal.key, value: proposal.value,
+              expected_revision: proposal.expected_revision,
+              origin: "distilled:#{proposal.session_ref}")
+            return stale(proposal, fact, operator) unless written
+          else
+            return stale(proposal, fact, operator) # the operator's edit stands
+          end
+        elsif fact
+          return stale(proposal, fact, operator) # the operator created it first
+        else
+          @memory_store.put_fact(tenant: proposal.tenant, customer: proposal.customer,
+                                 key: proposal.key, value: proposal.value,
+                                 origin: "distilled:#{proposal.session_ref}")
+        end
+        resolved = @proposal_store.approve(id: proposal.id, operator: operator, note: note)
+        emit(:proposal_approved, resolved)
+        resolved
+      end
+
+      # The re-present (E3): the proposal carries the fact's CURRENT value next
+      # to the proposed one; both are visible on the wiki page.
+      def stale(proposal, fact, operator)
+        resolved = @proposal_store.mark_stale(id: proposal.id, current_value: fact&.value,
+                                              operator: operator)
+        emit(:proposal_stale, resolved)
+        resolved
+      end
+
+      # ids and statuses only (D7) — a fact value never enters the stream.
+      def emit(type, proposal)
+        @event_stream.emit(Insika::Event.new(
+                             type: type,
+                             data: { proposal_id: proposal.id, status: proposal.status,
+                                     operator: proposal.operator },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      def operator_for(command)
+        Coercion.presence(command.payload[:operator] || command.payload["operator"]) ||
+          Coercion.presence(command.meta[:operator]) ||
+          "operator"
+      end
+    end
+  end
+end

data/lib/insika/commands/revoke_contact.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # a channel opt-out event (mapped by the integration)— or
+    # the operator force-revoking a contact whose opt-out never arrived.
+    # Revokes the contact cell AND cancels every pending record of that
+    # customer in ONE transaction on the shared backend (D2: a half-cancelled
+    # opt-out is the spam bug — a crash mid-revoke must leave the old state,
+    # never the cell revoked with pending records alive). Blocked/fired
+    # records are never touched. Tenant-scoped (WS1).
+    class RevokeContact
+      def initialize(contact_store:, followup_store:, store:, event_stream:)
+        @contact_store = contact_store
+        @followup_store = followup_store
+        @store = store
+        @event_stream = event_stream
+      end
+
+      # -> { customer:, tenant:, cancelled: }.
+      def call(command)
+        customer = Coercion.presence(command.payload[:customer] || command.payload["customer"])
+        raise ValidationError, "customer is required" if customer.nil?
+
+        tenant = command.meta[:tenant]
+        # ONE transaction on the shared backend: both stores' writes (each
+        # wrapped in their own nested transaction) join the outer one.
+        cancelled = @store.transaction do
+          @contact_store.set_revoked(tenant: tenant, customer: customer)
+          @followup_store.cancel_pending_for(tenant: tenant, customer: customer)
+        end
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :contact_revoked,
+                             data: { customer: customer, tenant: tenant },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        @event_stream.emit(Insika::Event.new(
+                             type: :followups_cancelled,
+                             data: { customer: customer, count: cancelled },
+                             meta: { tenant: tenant, at: Time.now.utc.iso8601 }
+                           ))
+        { customer: customer, tenant: tenant, cancelled: cancelled }
+      end
+    end
+  end
+end

data/lib/insika/commands/rollback_harvest.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "time"
+require "securerandom"
+
+module Insika
+  module Commands
+    #   — the snapshot restored. `RollbackHarvest(snapshot_ref:)`
+    # restores the pre-promotion state deterministically: WriteSkill with the
+    # snapshot's pre-promotion content (or DeleteSkill when the skill did not
+    # exist before — the snapshot's `existed` flag), SetSkillAgents to the
+    # snapshot's pre-promotion `enabled_for`, and the `rolled_back_at` stamp on
+    # the SAME log (the log stays the single ledger: a skill promoted, rolled
+    # back, re-promoted is three readable rows). The "rehearsed once
+    # end-to-end" acceptance is this command's full promote -> rollback cycle.
+    class RollbackHarvest
+      def initialize(harvest_store:, skill_store:, skill_catalog:, profile_source:,
+                     event_stream:, write_skill: nil, delete_skill: nil, set_skill_agents: nil)
+        @harvest_store = harvest_store
+        @profiles = ProfileSource.coerce(profile_source)
+        @event_stream = event_stream
+        @write_skill = write_skill ||
+                       Insika::Commands::WriteSkill.new(skill_store: skill_store,
+                                                        skill_catalog: skill_catalog,
+                                                        event_stream: event_stream)
+        @delete_skill = delete_skill ||
+                        Insika::Commands::DeleteSkill.new(skill_store: skill_store,
+                                                          skill_catalog: skill_catalog,
+                                                          event_stream: event_stream)
+        @set_skill_agents = set_skill_agents ||
+                            Insika::Commands::SetSkillAgents.new(profile_source: @profiles,
+                                                                 event_stream: event_stream)
+      end
+
+      # payload: { snapshot_ref:, operator?, reason? }
+      # -> Promotion (the row with rolled_back_at stamped)
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        snapshot_ref = AgentPayload.presence(p[:snapshot_ref])
+        raise Insika::ValidationError, "snapshot_ref is required" if snapshot_ref.nil?
+
+        snap = @harvest_store.find_snapshot(snapshot_ref) ||
+               (raise Insika::NotFoundError, "harvest snapshot not found: #{snapshot_ref}")
+        # The log row whose snapshot_ref matches — but a promotion that never
+        # recorded its row (a crash between the writes and the append) rolls
+        # back by snapshot, and the rollback stamp catches up on whatever row
+        # exists (D8's honest price, resolved by reference).
+        promotion = promotion_for_snapshot(snap)
+        operator = (AgentPayload.presence(p[:operator]) || command.meta[:operator] || "operator").to_s
+
+        if snap.existed
+          @write_skill.call(Insika::Command.build(:write_skill,
+                                                  { name: snap.skill, content: snap.content,
+                                                    agent: snap.agent }))
+        else
+          begin
+            @delete_skill.call(Insika::Command.build(:delete_skill,
+                                                     { name: snap.skill, agent: snap.agent }))
+          rescue Insika::NotFoundError
+            # the desired state (gone) already holds — a snapshot taken for a
+            # skill that never landed rolls back cleanly
+          end
+        end
+        @set_skill_agents.call(Insika::Command.build(:set_skill_agents,
+                                                     { name: snap.skill,
+                                                       agent_ids: snap.enabled_for }))
+
+        rolled = promotion ? @harvest_store.append_rollback(promotion_id: promotion.id,
+                                                    operator: operator, reason: p[:reason]) : nil
+        @event_stream.emit(Insika::Event.new(
+                             type: :skill_rolled_back,
+                             data: { snapshot_ref: snapshot_ref, skill: snap.skill,
+                                     agent: snap.agent, operator: operator }.compact,
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        rolled || promotion
+      end
+
+      private
+
+      def promotion_for_snapshot(snap)
+        @harvest_store.promotions.find { |row| row.snapshot_ref == snap.id }
+      end
+    end
+  end
+end

data/lib/insika/commands/run_distillation.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # the ONLY path that writes proposals. Distills ONE session
+    # end to end: read the transcript and the memory baseline, ask the model,
+    # schema-drop, dedup against the ledger, write proposals, mark the session
+    # distilled. Synchronous (it runs on the engine's worker fiber, C5) — it
+    # creates no task and no turn (D2: no TaskStore work unit — a crash
+    # mid-pass leaves the marker unwritten and the next pass re-scans; a
+    # duplicate proposal is filtered by the ledger, never applied).
+    class RunDistillation
+      DEFAULT_IDLE_HOURS = 6
+      DEFAULT_MIN_MESSAGES = 3
+      DEFAULT_MAX_PROPOSALS = 10
+
+      def initialize(profiles:, proposal_store:, session_store:, memory_store:,
+                     settings_store:, event_stream:, distiller_factory: nil)
+        @profiles = profiles
+        @proposal_store = proposal_store
+        @session_store = session_store
+        @memory_store = memory_store
+        @settings_store = settings_store
+        @event_stream = event_stream
+        @distiller_factory = distiller_factory ||
+                             ->(config) { Distill::DistillerFactory.build(config, utility_model: utility_model) }
+      end
+
+      # payload: { session_id: } (agent resolved from the session, D6-bis)
+      # -> { distilled: true, proposals: N, dropped: {...}, deduped: N, cost: {...} | nil }
+      #  | { distilled: false, skipped: "already|untagged|no_agent|disabled|
+      #        too_fresh|too_short|no_model" }
+      def call(command)
+        session_id = Coercion.presence(command.payload[:session_id] || command.payload["session_id"])
+        raise ValidationError, "session_id is required" if session_id.nil?
+
+        session = @session_store.find(session_id)
+        raise Insika::NotFoundError, "session not found: #{session_id}" if session.nil?
+
+        return skip("already") if @proposal_store.distilled?(session_id)
+
+        customer = Coercion.presence(session.vars["customer"])
+        return skip("untagged") if customer.nil?
+
+        agent_id = Coercion.presence(session.vars["agent"])
+        return skip("no_agent") if agent_id.nil?
+
+        profile = @profiles[agent_id]
+        return skip("no_agent") if profile.nil?
+
+        config = Coercion.deep_stringify(profile.distill)
+        return skip("disabled") if config.nil? || !Coercion.truthy?(config["enabled"])
+
+        # D4: the pack's own idle threshold wins over the scan's lower bound —
+        # a pack that wants 12 h is never distilled at 6.
+        idle_hours = config["idle_hours"].to_i
+        idle_hours = DEFAULT_IDLE_HOURS unless idle_hours.positive?
+        return skip("too_fresh") unless idle?(session.updated_at, idle_hours)
+
+        min_messages = config["min_messages"].to_i
+        min_messages = DEFAULT_MIN_MESSAGES unless min_messages.positive?
+        return skip("too_short") if session.messages.size < min_messages
+
+        tenant = tenant_of(session_id)
+        distiller = @distiller_factory.call(config)
+        return skip("no_model") if distiller.nil?
+
+        baseline = memory_baseline(tenant, customer)
+        prompt = build_prompt(config, session, baseline)
+        result = distiller.distill(prompt: prompt, message_count: session.messages.size,
+                                   max_proposals: (config["max_proposals"] || DEFAULT_MAX_PROPOSALS).to_i)
+
+        deduped = 0
+        survivors = result[:proposals].reject do |proposal|
+          dedup = deduped?(tenant, customer, proposal, baseline)
+          deduped += 1 if dedup
+          dedup
+        end
+
+        survivors.each do |proposal|
+          expected = baseline[proposal["name"]]
+          @proposal_store.create(
+            tenant: tenant, customer: customer, session_ref: session_id,
+            key: proposal["name"], value: proposal["value"],
+            confidence: proposal["confidence"], evidence: proposal["turns"],
+            expected_revision: expected && expected.updated_at,
+            expected_existed: !expected.nil?
+          )
+        end
+
+        @proposal_store.mark_distilled(session_id, agent: agent_id,
+                                       proposals: survivors.size,
+                                       dropped: result[:dropped],
+                                       deduped: deduped,
+                                       cost: result[:cost])
+        @event_stream.emit(Insika::Event.new(
+                             type: :distillation_completed,
+                             # counts and ids only (D7) — a fact value never
+                             # enters the stream.
+                             data: { session_ref: session_id, agent: agent_id,
+                                     proposals: survivors.size,
+                                     dropped: result[:dropped],
+                                     deduped: deduped,
+                                     cost: result[:cost] },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { distilled: true, proposals: survivors.size, dropped: result[:dropped],
+          deduped: deduped, cost: result[:cost] }
+      end
+
+      private
+
+      # nil tenant in single-tenant deployments; the "<tenant>:" prefix of the
+      # session id otherwise (D1 — the same reading ForgetCustomer uses).
+      def tenant_of(session_id)
+        tenant, rest = session_id.to_s.split(":", 2)
+        rest.nil? ? nil : tenant
+      end
+
+      def skip(reason)
+        { distilled: false, skipped: reason }
+      end
+
+      def idle?(updated_at, idle_hours)
+        return false if Coercion.blank?(updated_at)
+
+        Time.iso8601(updated_at.to_s) <= Time.now.utc - idle_hours * 3600
+      rescue ArgumentError
+        false
+      end
+
+      # Per fact key: the existence + updated_at at distill time (D5 — the CAS
+      # baseline the approval compares against). Sorted by key for a stable
+      # prompt.
+      def memory_baseline(tenant, customer)
+        @memory_store.facts(tenant: tenant, customer: customer)
+                     .each_with_object({}) { |f, acc| acc[f.key] = f }
+      end
+
+      def deduped?(tenant, customer, proposal, baseline)
+        key = proposal["name"].to_s
+        value = proposal["value"].to_s
+        return true if @proposal_store.decided?(tenant: tenant, customer: customer,
+                                                key: key, value: value)
+        return true if @proposal_store.open_pending?(tenant: tenant, customer: customer, key: key)
+
+        applied = baseline[key]
+        !applied.nil? && applied.value == value && applied.origin.to_s.start_with?("distilled:")
+      end
+
+      # The prompt gets the transcript slice (masked through the
+      # output filter first — the   redaction rule), the
+      # customer's CURRENT facts (so the model can avoid re-proposing applied
+      # facts), and the answer rules (the pack prompt or DEFAULT_PROMPT).
+      def build_prompt(config, session, baseline)
+        base = Coercion.presence(config["prompt"]) || Distill::DEFAULT_PROMPT
+        transcript = render_transcript(session.messages)
+        facts = baseline.values.map { |f| "- #{f.key}: #{f.value}" }
+        <<~PROMPT
+          #{base.rstrip}
+
+          ## The conversation
+
+          #{transcript}
+
+          ## Facts already in this customer's memory (do not re-propose them)
+
+          #{facts.empty? ? "(none)" : facts.join("\n")}
+        PROMPT
+      end
+
+      def render_transcript(messages)
+        redacted, = Insika::Safety::Detectors.redact(
+          messages.each_with_index.map { |m, i| "[#{i}] #{m['role']}: #{m['content']}" }.join("\n")
+        )
+        redacted
+      end
+
+      def utility_model
+        return nil unless @settings_store
+
+        @settings_store.get["utility_model"]
+      end
+    end
+  end
+end