insika 0.1.0 → 0.3.0

data/lib/insika/circuit_state.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # The circuit breaker's durable state (WS3): one cell per
+  # (tenant, provider/model ref) holding the recent failures and when the
+  # circuit opened. The read-modify-write rides `@store.transaction` — the same
+  # discipline as the dispatch claim (A1): two concurrent failures of the same
+  # cell serialize, so the "10 failures in 60s" count is never lost to a race.
+  #
+  # States, standard semantics:
+  #   :closed    fewer than `after` failures in the `within` window — attempts flow.
+  #   :open      the window count is met AND the cooldown hasn't elapsed — the
+  #              edge FAIL-FASTS (no provider call) with retry_after = remaining
+  #              cooldown. Reached at the `after`-th failure, which stamps
+  #              opened_at.
+  #   :half_open the cooldown elapsed — the next attempt is the TRIAL: a success
+  #              closes (record_success clears the cell), a failure reopens
+  #              (a new failure count / opened_at).
+  class CircuitState
+    SCOPE = "circuit_state"
+
+    # Timestamps are pruned to COUNT_LIMIT — a pathological loop cannot grow the
+    # cell unboundedly (the window is 60s-wide; 100 reads and writes bounded).
+    COUNT_LIMIT = 100
+
+    Record = Data.define(:failures, :opened_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Records ONE failure for (tenant, ref). If this failure makes the window
+    # reach `after` and the circuit is not already open, it stamps opened_at
+    # (the instant the breaker trips). -> :closed (still closed) | :open (JUST
+    # tripped — closed->open, the ONLY transition that alerts) | :reopened (an
+    # already-tripped cell re-stamped: a half-open trial failed; the circuit is
+    # open again but the node already told the operator it is sick — no NEW
+    # alert (WS3)).
+    def record_failure(tenant:, ref:, after: 10, within: 60, now: Time.now)
+      key = key_for(tenant, ref)
+      @store.transaction do
+        record = load(key)
+        cutoff = (now.to_i - within)
+        retained = record.failures.select { |t| t > cutoff }.last(COUNT_LIMIT)
+        failures = (retained + [now.to_i]).last(COUNT_LIMIT)
+        opened_at = record.opened_at
+        tripped = :closed
+        if opened_at.nil?
+          if failures.size >= after
+            opened_at = now.to_i
+            tripped = :open
+          end
+        else
+          # the circuit was tripped before; a failure here can only be a HALF-OPEN
+          # trial that failed. Re-stamp opened_at so it RE-OPENS — a breaker that
+          # never restamps is one-shot: after the first cooldown every later turn
+          # is an unlocked half-open trial (WS3).
+          opened_at = now.to_i
+          tripped = :reopened
+        end
+        @store.set(SCOPE, key, { "failures" => failures, "opened_at" => opened_at })
+        tripped
+      end
+    end
+
+    # A successful attempt CLOSES the circuit: the cell is cleared so the
+    # failure window starts fresh (half-open trial success included).
+    def record_success(tenant:, ref:)
+      @store.delete(SCOPE, key_for(tenant, ref))
+    end
+
+    # -> :closed | :open | :half_open
+    def state(tenant:, ref:, after: 10, within: 60, cooldown: 300, now: Time.now)
+      record = load(key_for(tenant, ref))
+      opened = record.opened_at.to_i
+      # :closed needs BOTH doors shut: the window count is under `after` AND the
+      # circuit never tripped. A surviving opened_at tombstone keeps the circuit
+      # governed by the cooldown (open, then half-open) even after its original
+      # failures age out of the rolling window — only a SUCCESS clears it (WS3:
+      # a failed half-open trial must reopen, not silently close).
+      return :closed if record.failures.size < after && opened.zero?
+
+      return :open if opened.zero? || (now.to_i - opened) < cooldown
+
+      :half_open
+    end
+
+    # Seconds until the circuit can be retried (the remaining cooldown). nil
+    # while closed.
+    def retry_after(tenant:, ref:, cooldown: 300, now: Time.now)
+      record = load(key_for(tenant, ref))
+      return nil if record.failures.empty?
+
+      opened = record.opened_at.to_i
+      return nil if opened.zero?
+
+      remaining = cooldown - (now.to_i - opened)
+      remaining.positive? ? remaining : nil
+    end
+
+    private
+
+    def key_for(tenant, ref) = "#{tenant || 'platform'}:#{ref}"
+
+    def load(key)
+      record = @store.get(SCOPE, key)
+      return Record.new([], nil) if record.nil?
+
+      Record.new(Array(record["failures"]), record["opened_at"])
+    end
+  end
+end

data/lib/insika/coercion.rb

@@ -19,6 +19,14 @@ module Insika
     # Inverse of blank? — a usable, non-empty value.
     def present?(value) = !blank?(value)
 
+    # The operator-facing truthy: what a form checkbox ("1"), a JSON round-trip
+    # ("true") or the DSL (true) produce for an opt-in. One list, one reading —
+    # AgentProfile#stream_public?, SkillCatalog#blanket? and the Studio all consult
+    # it, so a value that opts in on one surface cannot opt out on another.
+    TRUTHY = [true, "true", "1", "yes", "on"].freeze
+
+    def truthy?(value) = TRUTHY.include?(value)
+
     # Bytes that come from outside the engine (sockets, pipes, subprocesses)
     # arrive tagged BINARY, or as UTF-8 carrying invalid sequences. Both break
     # `JSON.generate` the moment the text has an accent or an emoji — today a

data/lib/insika/commands/agent_payload.rb

@@ -10,10 +10,12 @@ module Insika
     module AgentPayload
       # Fields accepted by AgentProfile.build (order irrelevant).
       FIELDS = %i[id model provider base_prompt prompt_files tools_allow tools_deny
-                  tools_allow_groups skills context_providers workflows_allow policies
+                  tools_allow_groups skills skills_eager context_providers workflows_allow policies
                   prompt_refs limits approvals_required capabilities subagents tools_deferred
-                  memory params model_policy guardrails refinement capabilities_declared
-                  edge_stream metadata].freeze
+                  memory prompt_caching tool_persistence tool_output_compression budget reliability alerts
+                  routes stuck_signal outputs briefing_fields grounding funnel followup
+                  params model_policy guardrails refinement capabilities_declared
+                  edge_stream metadata distill harvest].freeze
 
       module_function
 
@@ -25,7 +27,7 @@ module Insika
         out[:provider] = presence(out[:provider])&.to_sym if out.key?(:provider)
         out[:policies] = Array(out[:policies]).map(&:to_sym) if out.key?(:policies)
         out[:limits] = out[:limits].transform_keys(&:to_sym) if out[:limits].is_a?(Hash)
-        # generation params (v2, §10) consumed by symbol key (temperature/max_tokens/thinking).
+        # generation params consumed by symbol key (temperature/max_tokens/thinking).
         out[:params] = out[:params].transform_keys(&:to_sym) if out[:params].is_a?(Hash)
         out
       end

data/lib/insika/commands/cancel_followup.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # the operator cancels ONE pending follow-up record (the
+    # Studio's Cancel button dispatches this). Synchronous control command (no
+    # task, like RecordOutcome); idempotent — an already-cancelled record
+    # returns as-is (a repeat of the same call is not an error). Tenant-scoped
+    # (WS1): a tenant principal can only cancel its own tenant's records.
+    class CancelFollowup
+      def initialize(followup_store:, event_stream:)
+        @followup_store = followup_store
+        @event_stream = event_stream
+      end
+
+      # -> Record. Emits :followup_cancelled { id:, cancelled_by: }.
+      def call(command)
+        id = Coercion.presence(command.payload[:followup_id] || command.payload["followup_id"])
+        raise ValidationError, "followup_id is required" if id.nil?
+
+        record = @followup_store.find(id)
+        raise NotFoundError, "follow-up not found: #{id}" if record.nil?
+
+        # WS1: the principal's tenant is the scope — a tenant token cannot
+        # cancel another tenant's record by id.
+        tenant = command.meta[:tenant]
+        unless record.tenant == (tenant.to_s.empty? ? "platform" : tenant.to_s)
+          raise ValidationError, "follow-up #{id} belongs to another tenant"
+        end
+
+        # A non-pending record (the tick fired it between the render and the
+        # click) is a domain error the Studio can flash — never a 500.
+        cancelled = begin
+          @followup_store.cancel(id: id)
+        rescue ArgumentError => e
+          raise ValidationError, e.message
+        end
+        @event_stream.emit(Insika::Event.new(
+                             type: :followup_cancelled,
+                             data: { id: cancelled.id, cancelled_by: "operator" },
+                             meta: { tenant: command.meta[:tenant], at: Time.now.utc.iso8601 }
+                           ))
+        cancelled
+      end
+    end
+  end
+end

data/lib/insika/commands/create_agent.rb

@@ -17,13 +17,13 @@ module Insika
         attrs = AgentPayload.attrs(command.payload)
         id = AgentPayload.presence(attrs[:id])
         raise Insika::ValidationError, "id is required" if id.nil?
-        # model is OPTIONAL as of v2 (§10): omitted -> resolves the platform
+        # model is OPTIONAL as of v2: omitted -> resolves the platform
         # default_model (Settings) at turn start. An agent with neither its own
         # model nor a platform default fails clearly at the first turn.
         raise Insika::ValidationError, "agent '#{id}' already exists" if @profile_source.fetch(id)
 
         profile = Insika::AgentProfile.build(**attrs)
-        # RFC-0010 §4.4: definition-time cycle + depth check. Only a profile that
+        # definition-time cycle + depth check. Only a profile that
         # introduces edges (non-empty subagents) can create a violation — a
         # childless agent is always a safe leaf. Raises SubagentError (a
         # ValidationError) BEFORE persisting, so a bad graph never lands.

data/lib/insika/commands/create_session.rb

@@ -21,7 +21,7 @@ module Insika
         vars = command.payload[:vars] || command.payload["vars"] || {}
         raise Insika::ValidationError, "vars must be a Hash" unless vars.is_a?(Hash)
 
-        # Per-chat model pin (v2, §10): `model`/`provider` on the payload become a
+        # Per-chat model pin: `model`/`provider` on the payload become a
         # reserved, collision-safe slot in vars (never rendered in the prompt — the
         # Request provider skips "__"-prefixed vars). The ModelResolver reads it as
         # the highest-precedence layer (Chat > Agent > platform default).

data/lib/insika/commands/delete_llm_provider.rb

@@ -6,7 +6,7 @@ module Insika
   module Commands
     # Control command: removes an LLM provider from the
     # LLMProviderStore. Idempotent (`existed: false` if there was none). UNDOES the
-    # config in RubyLLM at runtime (§9.5): when the provider existed, calls
+    # config in RubyLLM at runtime: when the provider existed, calls
     # `configurator.unapply(api)` clearing the global key/base — without a restart. A provider
     # that RubyLLM does not recognize degrades gracefully (unapply: false, nothing to
     # undo). -> { existed: bool }.

data/lib/insika/commands/delete_skill.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an authored skill from the SkillStore and RELOADS the
+    # catalog. -> { name, agent, deleted }.
+    #
+    # With `agent`, it deletes only that agent's SPECIALIZATION — the shared skill
+    # stays exactly where it was, and the agent falls back to it on the next turn.
+    # "Stop specializing this" is the inverse of the specialize action, and it must not
+    # be expressible as "delete the skill".
+    #
+    # Deleting a shared skill does NOT touch any allowlist: an agent left naming a
+    # skill that no longer exists sees nothing (the catalog resolves nothing), which is
+    # the same outcome as never having allowed it.
+    class DeleteSkill
+      def initialize(skill_store:, skill_catalog:, event_stream:)
+        @skill_store = skill_store
+        @skill_catalog = skill_catalog
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        agent = AgentPayload.presence(p[:agent])
+        raise Insika::ValidationError, "name is required" if name.nil?
+
+        deleted = @skill_store.delete(name, agent: agent)
+        raise Insika::NotFoundError, "skill '#{name}' not found#{" for agent '#{agent}'" if agent}" unless deleted
+
+        @skill_catalog.reload
+        @event_stream.emit(Insika::Event.new(
+                             type: :skill_deleted, data: { name: name, agent: agent }.compact,
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name, agent: agent, deleted: true }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_tenant_data.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (WS8, phase 2 — LGPD): purges everything the engine holds
+    # about ONE TENANT — its sessions (the "<tenant>:" namespace) and everything
+    # those sessions left behind (traces, tasks, checkpoints, outbox deliveries
+    # — see SessionPurge), every memory cell under the tenant (its own + the
+    # customer cells), its outcome records (WS7) and its API CREDENTIALS (every
+    # active token of the tenant is revoked first — an offboarded tenant must
+    # not authenticate). The tenant string IS the
+    # isolation boundary, so zeroing it cannot touch another tenant's data.
+    # Operator-only BY CONSTRUCTION: the generic command ingress is
+    # operator-grade (a tenant principal never reaches it).
+    class DeleteTenantData
+      include SessionPurge
+
+      def initialize(memory_store:, session_store:, tool_trace_store: nil,
+                     context_trace_store: nil, model_visible_trace_store: nil,
+                     outcome_store: nil, task_store: nil,
+                     checkpoint_store: nil, outbox_store: nil, shadow_pairs: nil,
+                     token_store: nil, funnel_store: nil, event_stream:,
+                     followup_store: nil, contact_store: nil, proposal_store: nil,
+                     harvest_store: nil)
+        @memory_store = memory_store
+        @token_store = token_store
+        @session_store = session_store
+        @tool_trace_store = tool_trace_store
+        @context_trace_store = context_trace_store
+        @model_visible_trace_store = model_visible_trace_store #  ; nil = parity
+        @outcome_store = outcome_store
+        @task_store = task_store
+        @checkpoint_store = checkpoint_store
+        @outbox_store = outbox_store
+        @shadow_pairs = shadow_pairs
+        @funnel_store = funnel_store #  ; nil = nothing to sweep
+        @followup_store = followup_store #  ; nil = nothing to sweep
+        @contact_store = contact_store   #  ; nil = nothing to sweep
+        @proposal_store = proposal_store #  ; nil = nothing to sweep
+        @harvest_store = harvest_store   #  ; nil = nothing to sweep
+        @event_stream = event_stream
+      end
+
+      # -> { tenant:, sessions:, memory_records:, outcomes:, tokens_revoked:,
+      #      tasks:, checkpoints:, deliveries:, followups:, contacts: }.
+      def call(command)
+        tenant = Coercion.presence(command.payload[:tenant] || command.payload["tenant"])
+        raise ValidationError, "tenant is required" if tenant.nil?
+
+        # CREDENTIALS FIRST (WS1+WS8): erasing the data while the tenant's
+        # tokens still resolve leaves an offboarded tenant authenticating and
+        # opening a NEW session — the purge would report success over a live
+        # customer. Revoking before the sweep closes the door, so nothing the
+        # tenant does mid-purge survives it. nil store = single_tenant mode
+        # (no per-tenant credential exists).
+        tokens_revoked = @token_store ? @token_store.revoke_all(tenant_id: tenant) : 0
+
+        sessions = @session_store.each_id.select { |id| id.to_s.start_with?("#{tenant}:") }
+        purged = purge_sessions(sessions)
+
+        memory_records = @memory_store.purge_tenant(tenant)
+        outcomes = @outcome_store ? @outcome_store.purge(tenant: tenant) : 0
+        funnel = @funnel_store ? @funnel_store.purge(tenant: tenant) : 0
+        # the follow-up footprint dies with the tenant — records
+        # and contact cells under the same tenant prefix.
+        followups = @followup_store ? @followup_store.purge(tenant: tenant) : 0
+        contacts = @contact_store ? @contact_store.purge(tenant: tenant) : 0
+        # the distilled proposals die with the tenant.
+        proposals = @proposal_store ? @proposal_store.purge(tenant: tenant) : 0
+        # candidates reference sessions, and sessions carry the
+        # tenant prefix — the harvest rows die with the tenant (D11).
+        harvest = @harvest_store ? @harvest_store.purge(tenant: tenant) : 0
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_data_deleted,
+                             data: { tenant: tenant, sessions: sessions,
+                                     memory_records: memory_records,
+                                     outcomes: outcomes,
+                                     funnel: funnel,
+                                     followups: followups,
+                                     contacts: contacts,
+                                     proposals: proposals,
+                                     harvest: harvest,
+                                     tokens_revoked: tokens_revoked }.merge(purged),
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { tenant: tenant, sessions: sessions, memory_records: memory_records,
+          outcomes: outcomes, funnel: funnel, followups: followups, contacts: contacts,
+          proposals: proposals, harvest: harvest, tokens_revoked: tokens_revoked }.merge(purged)
+      end
+    end
+  end
+end

data/lib/insika/commands/export_customer_memory.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command  the LGPD access right): exports what the
+    # engine holds about ONE customer — their memory cell's facts + notes,
+    # expired facts excluded. The FULL content is the RETURN VALUE (the Studio
+    # turns it into a JSON download); the emitted event carries counts only, so
+    # the event stream, the audit store and every log stay content-free (D7).
+    # The return value never enters a store, an event or a log.
+    class ExportCustomerMemory
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      # payload: { customer: (REQUIRED), tenant: } — customer from the payload
+      # (an operator names the person); tenant from the payload || meta.
+      # -> { "customer" =>, "tenant" =>, "exported_at" =>, "facts" => [Fact#to_h],
+      #      "notes" => [Note#to_h], "counts" => { "facts" =>, "notes" => } }
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        customer = AgentPayload.presence(p[:customer])
+        raise Insika::ValidationError, "customer is required" if customer.nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        facts = @memory_store.facts(tenant: tenant, customer: customer)
+        notes = @memory_store.notes(tenant: tenant, customer: customer)
+        exported_at = Time.now.utc.iso8601
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :customer_memory_exported,
+                             data: { customer: customer, tenant: tenant,
+                                     counts: { facts: facts.size, notes: notes.size } },
+                             meta: { at: exported_at }
+                           ))
+        {
+          "customer" => customer, "tenant" => tenant, "exported_at" => exported_at,
+          "facts" => facts.map { |f| Coercion.deep_stringify(f.to_h) },
+          "notes" => notes.map { |n| Coercion.deep_stringify(n.to_h) },
+          "counts" => { "facts" => facts.size, "notes" => notes.size }
+        }
+      end
+    end
+  end
+end

data/lib/insika/commands/forget_customer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (WS8, phase 2 — LGPD): purges what the engine holds about
+    # ONE customer — the customer's memory cell, their sessions (found through
+    # the `customer` var the Executor stamps on a tagged conversation) and
+    # everything those sessions left behind (traces, tasks, checkpoints, outbox
+    # deliveries — see SessionPurge). The scope string IS the isolation
+    # boundary, so zeroing it cannot touch another customer's or another
+    # tenant's data. Operator-only BY CONSTRUCTION: the generic command ingress
+    # is operator-grade (a tenant principal never reaches it).
+    #
+    # WHICH TENANT is the whole correctness of the purge: the memory cell is
+    # "memory:<tenant>:<customer>" and the sessions are the "<tenant>:" ones. It
+    # is read from the command meta (an internal caller acting AS a tenant) or
+    # from the payload (`{ customer:, tenant: }` — the operator naming it over
+    # HTTP, where the principal has no tenant of its own). Absent from both, the
+    # purge is deployment-wide: the untagged memory cell plus that customer's
+    # sessions in EVERY tenant — right for a single-tenant deployment, and never
+    # what a multi-tenant operator means, so they must name the tenant.
+    class ForgetCustomer
+      include SessionPurge
+
+      def initialize(memory_store:, session_store:, tool_trace_store: nil,
+                     context_trace_store: nil, model_visible_trace_store: nil,
+                     task_store: nil, checkpoint_store: nil,
+                     outbox_store: nil, shadow_pairs: nil, audit_store: nil, event_stream:,
+                     followup_store: nil, contact_store: nil, proposal_store: nil)
+        @memory_store = memory_store
+        @session_store = session_store
+        @tool_trace_store = tool_trace_store
+        @context_trace_store = context_trace_store
+        @model_visible_trace_store = model_visible_trace_store #  ; nil = parity
+        @task_store = task_store
+        @checkpoint_store = checkpoint_store
+        @outbox_store = outbox_store
+        @shadow_pairs = shadow_pairs
+        @audit_store = audit_store
+        @event_stream = event_stream
+        @followup_store = followup_store #  ; nil = nothing to sweep
+        @contact_store = contact_store   #  ; nil = nothing to sweep
+        @proposal_store = proposal_store #  ; nil = nothing to sweep
+      end
+
+      # -> { customer:, tenant:, memory_records:, sessions: [], tasks:,
+      #      checkpoints:, deliveries:, followups:, contacts: }.
+      def call(command)
+        customer = Coercion.presence(command.payload[:customer] || command.payload["customer"])
+        raise ValidationError, "customer is required" if customer.nil?
+
+        tenant = command.meta[:tenant] ||
+                 Coercion.presence(command.payload[:tenant] || command.payload["tenant"])
+        memory_scope = [tenant, customer].compact.join(":")
+        memory_records = @memory_store.purge(tenant: memory_scope)
+
+        # the follow-up footprint dies with the person — the
+        # schedule records and the contact cell (LGPD).
+        followups = @followup_store&.purge_customer(tenant: tenant, customer: customer) || 0
+        contacts = @contact_store&.delete(tenant: tenant, customer: customer) ? 1 : 0
+
+        # the distilled PROPOSALS die with the person — a proposal
+        # is born inside a customer cell (D6), so forget_customer reaches it.
+        proposals = @proposal_store&.purge_customer(tenant: tenant, customer: customer) || 0
+
+        sessions = session_ids_for(customer, tenant)
+        purged = purge_sessions(sessions)
+
+        # the audit records the thing that happened, content-free —
+        # a digest-free line with the counts (the deleted VALUES never enter
+        # the audit store). Written AFTER the purge, so the line describes a
+        # deletion that actually happened. nil audit_store = no-op.
+        @audit_store&.record(
+          cell: @memory_store.cell_for(tenant, customer),
+          action: "purge", actor: operator(command), tenant: tenant, customer: customer,
+          note: "memory_records: #{memory_records}, sessions: #{sessions.size}"
+        )
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :customer_forgotten,
+                             data: { customer: customer, tenant: tenant,
+                                     memory_records: memory_records,
+                                     sessions: sessions,
+                                     followups: followups,
+                                     contacts: contacts,
+                                     proposals: proposals }.merge(purged),
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { customer: customer, tenant: tenant, memory_records: memory_records,
+          sessions: sessions, followups: followups, contacts: contacts,
+          proposals: proposals }.merge(purged)
+      end
+
+      private
+
+      def operator(command)
+        Coercion.presence(command.payload[:operator] || command.payload["operator"]) || "operator"
+      end
+
+      # The customer's sessions: the ones the Executor stamped with this
+      # customer var — plus, in multi_tenant, only ids inside the tenant's
+      # "<tenant>:" namespace (single_tenant sessions carry no prefix).
+      def session_ids_for(customer, tenant)
+        @session_store.each_id.each_with_object([]) do |id, acc|
+          session = @session_store.find(id)
+          next unless session
+          next unless Coercion.presence(session.vars["customer"]).to_s == customer.to_s
+          next if tenant && !id.to_s.start_with?("#{tenant}:")
+
+          acc << id.to_s
+        end
+      end
+    end
+  end
+end

data/lib/insika/commands/freeze_funnel_baseline.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "time"
+require "date"
+
+module Insika
+  module Commands
+    # the operator's FREEZE — turn the folded counts over a
+    # declared span into the baseline snapshot (A/B follow-up) and
+    # (promotion gate) read. One command, dispatched from the Studio
+    # and available to any operator-grade caller. Synchronous control command —
+    # no task, no actor, same discipline as RecordOutcome (WS7).
+    #
+    # The ≥ 4-week rule ("no 1.0 target before a remeasure") is
+    # enforced HERE, not by convention: a frozen span shorter than 28 days is a
+    # ValidationError. `frozen_at` stamps when; the baseline OVERWRITES (D5) —
+    # the freeze event is the audit surface.
+    class FreezeFunnelBaseline
+      MIN_SPAN_DAYS = 28
+
+      def initialize(funnel_store:, profiles:, event_stream:)
+        @funnel_store = funnel_store
+        @profiles = profiles
+        @event_stream = event_stream
+      end
+
+      # payload: { agent:, tenant:, from: "YYYY-MM-DD", to: "YYYY-MM-DD", operator: }
+      #   agent REQUIRED (ValidationError); tenant from payload || meta[:tenant].
+      #   from/to optional — default to the pair's folded span (first/last day
+      #   cell); explicit from/to are inclusive bounds.
+      # -> the baseline record.
+      def call(command)
+        payload = command.payload
+        agent = Coercion.presence(payload[:agent] || payload["agent"])
+        raise ValidationError, "agent is required" if agent.nil?
+
+        declaration = declaration_for(agent)
+        tenant = payload[:tenant] || payload["tenant"] || command.meta[:tenant]
+
+        from, to = bounds(payload, tenant, agent)
+        validate_span!(from, to)
+
+        stages = @funnel_store.days(tenant: tenant, agent: agent, from: from, to: to)
+                              .each_with_object(Hash.new(0)) do |(_, counts), acc|
+          counts.each { |stage, n| acc[stage] += n }
+        end
+        primary = declaration.primary
+        primary_count = stages[primary].to_i
+        first_count = stages[declaration.first_stage].to_i
+        conversion = first_count.zero? ? nil : primary_count.to_f / first_count
+
+        baseline = {
+          "from" => from, "to" => to, "stages" => stages,
+          "primary" => primary, "primary_count" => primary_count,
+          "conversion" => conversion, "window" => declaration.attribution_window,
+          "frozen_at" => Time.now.utc.iso8601
+        }
+        @funnel_store.set_baseline(tenant: tenant, agent: agent, record: baseline)
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :funnel_baseline_frozen,
+                             data: { agent: agent, from: from, to: to,
+                                     primary: primary, primary_count: primary_count,
+                                     conversion: conversion },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        baseline
+      end
+
+      private
+
+      # -> FunnelDeclaration | raise — the freeze needs the parsed declaration,
+      # so a malformed/absent one is a hard ValidationError (D8: the FOLD skips
+      # malformed declarations, but freezing without one is an operator error).
+      def declaration_for(agent)
+        profile = @profiles.fetch(agent)
+        decl = profile && Insika::FunnelDeclaration.parse(profile.funnel)
+        return decl if decl
+
+        raise ValidationError, "agent '#{agent}' has no valid funnel declaration"
+      end
+
+      # Explicit from/to (inclusive) or the pair's folded span (first/last day
+      # cell). -> [String, String].
+      def bounds(payload, tenant, agent)
+        from = Coercion.presence(payload[:from] || payload["from"])
+        to = Coercion.presence(payload[:to] || payload["to"])
+        # both given -> no scan at all (a pair with no cells still freezes,
+        # over a zero-count span, when the operator names the dates)
+        return [from, to] if from && to
+
+        days = @funnel_store.days(tenant: tenant, agent: agent)
+        days_keys = days.keys
+        raise ValidationError, "no folded days for agent '#{agent}'" if days_keys.empty?
+
+        [from || days_keys.first, to || days_keys.last]
+      end
+
+      def validate_span!(from, to)
+        raise ValidationError, "from must be before to" if from >= to
+
+        span = (Date.iso8601(to) - Date.iso8601(from)).to_i
+        if span < MIN_SPAN_DAYS
+          raise ValidationError,
+                "baseline span must cover at least #{MIN_SPAN_DAYS} days " \
+                "(the number needs a remeasured baseline)"
+        end
+      rescue Date::Error
+        raise ValidationError, "from/to must be ISO dates (YYYY-MM-DD)"
+      end
+    end
+  end
+end