insika 0.0.1 → 0.1.0

data/lib/insika/commands/send_message.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Canonical turn command: validates everything synchronously, creates the Task, fires
+    # the fiber and responds `{task_id:}` immediately — the result flows through the Event
+    # Stream. Validations that fail do NOT create a Task
+    # (ValidationError/NotFoundError -> direct HTTP response).
+    class SendMessage
+      # RFC-0015 §5.5 — surfaces whose response can carry the "you do not own the reply"
+      # verdict (`merged` for `collect`, `steered` for `steer`), and therefore the only
+      # ones where a message may join another turn. `/v1/responses` is NOT here: its body
+      # is OpenAI-shaped SSE with nowhere to put the field, and it is frozen because a
+      # live consumer speaks it. Joining a caller that cannot hear the verdict makes it
+      # deliver the same answer once per message, which is worse than not joining at all.
+      # Channels declare themselves by `channel:<id>` once RFC-0011 §6 lands.
+      COALESCABLE_TRANSPORTS = %i[http:json].freeze
+
+      # RFC-0011 §6.4 — `inbound_log` is the retry window for channel event ids.
+      # nil = no dedup (every surface that does not send an `event_id`, which is all
+      # of them today), and a caller that cannot supply a stable id gets
+      # at-least-once turns rather than a content hash pretending to be dedup.
+      def initialize(profiles:, session_store:, task_store:, executor:, inbound_log: nil)
+        @profiles = ProfileSource.coerce(profiles)
+        @session_store = session_store
+        @task_store = task_store
+        @executor = executor
+        @inbound_log = inbound_log
+      end
+
+      def call(command)
+        p = normalize(command.payload) # accepts string and symbol keys
+
+        agent = p[:agent].to_s
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+
+        profile = @profiles[agent] ||
+                  (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+
+        message = p[:message]
+        raise Insika::ValidationError, "message is required and non-empty" if message.to_s.strip.empty?
+
+        # session_id XOR history (both -> error; neither -> one-shot).
+        if p[:session_id] && p[:history]
+          raise Insika::ValidationError, "session_id and history are mutually exclusive (D2)"
+        end
+
+        validate_history!(p[:history]) if p[:history]
+        # WHO wrote this message (MessageOrigin). Absent = a customer typed it, which
+        # is what a turn has always meant. Refused here rather than downstream: a
+        # typo'd origin would read as absent, and a marker that silently means
+        # "unmarked" is worse than none — it looks like the filtering is on.
+        Insika::MessageOrigin.parse!(p[:origin])
+        if p[:session_id]
+          @session_store.find(p[:session_id]) ||
+            (raise Insika::NotFoundError, "session '#{p[:session_id]}' not found")
+        end
+
+        # RFC-0011 §6.4 — the platform retried a webhook it already delivered. Answer
+        # with the turn it ALREADY produced and run nothing: without this, one flaky
+        # ack costs a second LLM turn and sends the customer the same answer twice.
+        # Checked before the queue doors on purpose — a duplicate is not a fragment to
+        # merge and not a correction to steer with, it is the same message again.
+        key = dedup_key(command, p)
+        if key && (prior = @inbound_log.find(key))
+          return { task_id: prior, duplicate: true }
+        end
+
+        result = start_turn(command, p, profile)
+        @inbound_log.record(key, result[:task_id]) if key
+        result
+      end
+
+      private
+
+      # The turn (or the verdict that this message joined someone else's).
+      def start_turn(command, p, profile)
+        message = p[:message]
+
+        # RFC-0015 §5.3 — a fragment for a session whose turn is still at the door
+        # joins it instead of becoming a turn of its own. Asked BEFORE `create` so a
+        # merge leaves no orphan :queued task behind (Recovery replays :queued at
+        # boot). Only offered on a surface that can report the verdict back —
+        # §5.5: coalescing a caller that cannot hear `merged` makes it deliver the
+        # same answer twice.
+        if coalescable?(command)
+          if (joined = @executor.collect_into_pending(p[:session_id], message, profile: profile))
+            return { task_id: joined, merged: true }
+          end
+
+          # RFC-0015 §5.1 — the turn is already RUNNING: the message is appended to it at
+          # the next tool-batch boundary. Same verdict as a merge, different word: the
+          # answer comes out of `task_id`, which is not this call's to deliver. Asked
+          # after `collect` because the two cannot both apply — a turn is either still at
+          # the door or running.
+          if (steered = @executor.steer_into_running(p[:session_id], message, profile: profile))
+            return { task_id: steered, steered: true }
+          end
+        end
+
+        # command.to_h persists the entire Command in the Task;
+        # ResumeTask re-reads payload.message from there.
+        task = @task_store.create(command: command.to_h, session_id: p[:session_id])
+        # RFC-0015 §6.4 — `interrupt` mode: the turn in flight is now answering the wrong
+        # question, so it is abandoned at its next boundary. This message keeps its OWN
+        # task and its own reply (that is why it needs no verdict and no surface gate), and
+        # the cancel is posted after `create` so the event can name what replaced what.
+        # No-op in every other mode.
+        @executor.interrupt_running(p[:session_id], profile: profile, replaced_by: task.id)
+        @executor.spawn_in_session(task, profile: profile)
+        { task_id: task.id }
+      end
+
+      def coalescable?(command)
+        transport = command.meta[:transport]
+        COALESCABLE_TRANSPORTS.include?(transport) || transport.to_s.start_with?("channel:")
+      end
+
+      # Scoped by TRANSPORT, never bare: two channels are two consumers with two id
+      # spaces, and a Slack event id that happened to equal a `wamid` would otherwise
+      # silence a real message. nil (no log wired, or no id sent) = no dedup.
+      def dedup_key(command, payload)
+        return nil unless @inbound_log
+
+        event_id = Coercion.presence(payload[:event_id])
+        event_id && "#{command.meta[:transport]}:#{event_id}"
+      end
+
+      def normalize(payload)
+        {
+          agent: payload[:agent] || payload["agent"],
+          message: payload[:message] || payload["message"],
+          session_id: payload[:session_id] || payload["session_id"],
+          history: payload[:history] || payload["history"],
+          origin: payload[:origin] || payload["origin"],
+          event_id: payload[:event_id] || payload["event_id"]
+        }
+      end
+
+      def validate_history!(history)
+        ok = history.is_a?(Array) && history.all? do |m|
+          m.is_a?(Hash) &&
+            !m.values_at(:role, "role").compact.empty? &&
+            !m.values_at(:content, "content").compact.empty?
+        end
+        raise Insika::ValidationError, "history must be [{role:, content:}]" unless ok
+      end
+    end
+  end
+end

data/lib/insika/commands/set_agent_tools.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: adjusts an agent's tools allow/denylist.
+    # `allow` nil = all (AgentProfile rule); `deny` always
+    # wins. `allow_groups` (Phase 7/D4/F5, Step C): per-group allowlist, only
+    # overwritten if the key comes in the payload (otherwise preserved). Takes effect on the next
+    # dispatch (hot). -> AgentProfile.
+    class SetAgentTools
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        id = AgentPayload.presence(p[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+        raise Insika::ValidationError, "allow must be a list or nil" unless p[:allow].nil? || p[:allow].is_a?(Array)
+        raise Insika::ValidationError, "allow_groups must be a list or nil" unless p[:allow_groups].nil? || p[:allow_groups].is_a?(Array)
+
+        existing = @profile_source.fetch(id) ||
+                   (raise Insika::NotFoundError, "agent '#{id}' not found")
+
+        merged = existing.to_h.merge(tools_allow: p[:allow], tools_deny: Array(p[:deny]))
+        merged[:tools_allow_groups] = p[:allow_groups] if p.key?(:allow_groups)
+        @profile_source.put(Insika::AgentProfile.build(**merged))
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_tools_set, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        @profile_source.fetch(id)
+      end
+    end
+  end
+end

data/lib/insika/commands/set_skill_agents.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: enables/disables a skill on N
+    # agents at once, adjusting each one's `profile.skills` allowlist.
+    # Takes effect on the next dispatch (hot via ProfileSource). -> { name, enabled_for }.
+    #
+    # Allowlist semantics (AgentProfile): nil = ALL, [] = none,
+    # [names] = subset. Important and deliberate consequence:
+    #  - enabling on an agent with skills=nil: no-op (already has all).
+    #  - DISABLING on an agent with skills=nil: NOT done here — removing one from
+    #    "all" would require enumerating the catalog and materializing an explicit
+    #    allowlist (destructive/surprising). These agents are left intact and
+    #    go into `skipped_all`. To restrict, use an explicit :set_agent_tools/allowlist
+    #    first.
+    class SetSkillAgents
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        raise Insika::ValidationError, "name is required" if name.nil?
+        raise Insika::ValidationError, "agent_ids must be a list" unless p[:agent_ids].nil? || p[:agent_ids].is_a?(Array)
+
+        wanted = Array(p[:agent_ids]).map(&:to_s)
+        enabled_for = []
+        skipped_all = []
+
+        @profile_source.all.each do |profile|
+          want = wanted.include?(profile.id)
+          new_skills = next_skills(profile.skills, name, want)
+
+          if new_skills == :skip
+            skipped_all << profile.id
+            next
+          end
+          next if new_skills == profile.skills # no change
+
+          @profile_source.put(Insika::AgentProfile.build(**profile.to_h.merge(skills: new_skills)))
+          enabled_for << profile.id if want
+        end
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :skill_agents_set,
+                             data: { name: name, agent_ids: wanted, skipped_all: skipped_all },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name, enabled_for: enabled_for, skipped_all: skipped_all }
+      end
+
+      private
+
+      # -> new allowlist | :skip (agent with nil that requested disable).
+      def next_skills(current, name, want)
+        if want
+          current.nil? ? nil : (Array(current).map(&:to_s) | [name])
+        elsif current.nil?
+          :skip
+        else
+          Array(current).map(&:to_s) - [name]
+        end
+      end
+    end
+  end
+end

data/lib/insika/commands/trigger_workflow.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Turn command: fires a workflow. Reuses the canonical
+    # pipeline — only stage 6 varies (Executor). Validates everything
+    # synchronously and responds `{task_id:}` immediately. The workflow allowlist is NOT
+    # checked here: it is stage-3 enforcement via WorkflowAllowlist
+    # -> PolicyDenied -> task :failed.
+    class TriggerWorkflow
+      ALLOWED_KEYS = %i[workflow agent input session_id].freeze
+
+      def initialize(profiles:, session_store:, task_store:, executor:, workflow_registry:)
+        @profiles = ProfileSource.coerce(profiles)
+        @session_store = session_store
+        @task_store = task_store
+        @executor = executor
+        @workflow_registry = workflow_registry
+      end
+
+      def call(command)
+        p = normalize(command.payload)
+        reject_unknown_keys!(command.payload) # strict validation
+
+        workflow = p[:workflow].to_s
+        raise Insika::ValidationError, "workflow is required" if workflow.empty?
+
+        agent = p[:agent].to_s
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+
+        profile = @profiles[agent] ||
+                  (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+
+        input = p[:input] || {}
+        raise Insika::ValidationError, "input must be a Hash" unless input.is_a?(Hash)
+
+        if p[:session_id]
+          @session_store.find(p[:session_id]) ||
+            (raise Insika::NotFoundError, "session '#{p[:session_id]}' not found")
+        end
+
+        # existence is validatable without executing — names, NEVER resolve (don't instantiate
+        # outside the fiber).
+        unless @workflow_registry.names.include?(workflow)
+          raise Insika::NotFoundError, "workflow '#{workflow}' not registered"
+        end
+
+        # I/O by schema (item 22 / §4.4): the INPUT is validated SYNCHRONOUSLY —
+        # a non-conforming input is a WorkflowSchemaError (< ValidationError -> 422)
+        # with NO run created. `definition` reads the schema metadata without
+        # resolving the factory (stays out of the fiber). No-op without an input_schema.
+        @workflow_registry.definition(workflow).validate_input!(input)
+
+        task = @task_store.create(command: command.to_h, session_id: p[:session_id])
+        @executor.spawn_in_session(task, profile: profile)
+        # runId = the run's durable record, which IS the Task (checkpointed +
+        # recoverable). Exposed under both names so the workflow consumer has a
+        # stable `run_id` while every task surface (GET /v1/tasks/:id, the event
+        # stream) keeps working unchanged.
+        { task_id: task.id, run_id: task.id }
+      end
+
+      private
+
+      def normalize(payload)
+        {
+          workflow: payload[:workflow] || payload["workflow"],
+          agent: payload[:agent] || payload["agent"],
+          input: payload[:input] || payload["input"],
+          session_id: payload[:session_id] || payload["session_id"]
+        }
+      end
+
+      def reject_unknown_keys!(payload)
+        extra = payload.keys.map(&:to_sym) - ALLOWED_KEYS
+        raise Insika::ValidationError, "unknown keys in payload: #{extra.join(', ')}" unless extra.empty?
+      end
+    end
+  end
+end

data/lib/insika/commands/update_agent.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: edits an existing agent. Merges the
+    # patch over the current profile (only the sent fields change) + rebuild + put.
+    # Takes effect on the NEXT dispatch (the ProfileSource reads fresh). -> AgentProfile.
+    class UpdateAgent
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        patch = AgentPayload.attrs(command.payload)
+        id = AgentPayload.presence(patch[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+
+        existing = @profile_source.fetch(id) ||
+                   (raise Insika::NotFoundError, "agent '#{id}' not found")
+
+        # to_h of the current profile brings the correct symbols; patch overwrites only
+        # what was sent. id never changes (rename = create+delete, out of scope).
+        merged = existing.to_h.merge(patch).merge(id: id)
+        profile = Insika::AgentProfile.build(**merged)
+        # RFC-0010 §4.4: definition-time cycle + depth check (an update may ADD
+        # subagents to an existing agent). Raises SubagentError before persisting.
+        validate_subagent_graph!(profile)
+        @profile_source.put(profile)
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_updated, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        @profile_source.fetch(id)
+      end
+
+      private
+
+      def validate_subagent_graph!(profile)
+        return if Array(profile.subagents).empty?
+
+        others = @profile_source.all.reject { |p| p.id.to_s == profile.id.to_s }
+        Insika::SubagentGraph.validate!(others + [profile])
+      end
+    end
+  end
+end

data/lib/insika/commands/update_settings.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: merges a patch into the
+    # general settings (timeouts/streaming/compaction) and persists it in the SettingsStore.
+    # Only what came in the patch changes; the rest (and the defaults) is preserved. Takes effect on the
+    # next turn that reads settings. -> Hash (resulting settings).
+    class UpdateSettings
+      def initialize(settings_store:, event_stream:)
+        @settings_store = settings_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        patch = p[:patch]
+        raise Insika::ValidationError, "patch must be an object" unless patch.nil? || patch.is_a?(Hash)
+        raise Insika::ValidationError, "empty patch" if patch.nil? || patch.empty?
+
+        settings = @settings_store.update(patch)
+        @event_stream.emit(Insika::Event.new(
+                             type: :settings_updated,
+                             data: { keys: patch.keys.map(&:to_s) },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        settings
+      end
+    end
+  end
+end

data/lib/insika/commands/upsert_llm_provider.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates/edits an LLM provider
+    # (api/base_url/auth_header/api_key/models) in the LLMProviderStore and RECONFIGURES
+    # RubyLLM at runtime (LLMConfigurator) — swaps key/base without a restart.
+    # The `api_key` is sentinel-aware (__OCULTO__ preserves; "" clears; a new string
+    # replaces). Returns the MASKED record (the key never comes back in plaintext).
+    class UpsertLLMProvider
+      def initialize(provider_store:, configurator:, event_stream:)
+        @provider_store = provider_store
+        @configurator = configurator
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        masked = @provider_store.upsert(p) # validates `api`; returns masked
+
+        # Reconfigures only THIS provider (with the real key from the store, already reconciled).
+        result = @configurator.apply([@provider_store.get_raw(masked["api"])])
+        @event_stream.emit(Insika::Event.new(
+                             type: :llm_provider_upserted,
+                             data: { api: masked["api"], applied: result[:applied], skipped: result[:skipped] },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        masked
+      end
+    end
+  end
+end

data/lib/insika/commands/upsert_mcp.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates/edits an MCP instance
+    # (transport/command/url/enabled + `env` credentials) in the McpStore. The
+    # credentials are sentinel-aware per key (__OCULTO__ preserves; "" clears;
+    # a new string replaces). Returns the MASKED record (env never comes back in
+    # plaintext). Durable config CRUD — running an MCP client against the
+    # instance is later runtime.
+    class UpsertMcp
+      def initialize(mcp_store:, event_stream:)
+        @mcp_store = mcp_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        masked = @mcp_store.upsert(p) # validates `name`; returns masked
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :mcp_upserted,
+                             data: { name: masked["name"], enabled: masked["enabled"] },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        masked
+      end
+    end
+  end
+end

data/lib/insika/commands/write_agent_file.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes an agent's prompt file to the
+    # workspace (AgentFileStore). This is what gives each BIA its own identity — the
+    # Prompt provider reads these files via `profile.prompt_files`. Takes effect
+    # on the next dispatch (hot). -> { agent_id, file, updated_at }.
+    class WriteAgentFile
+      def initialize(profile_source:, agent_file_store:, event_stream:)
+        @profile_source = profile_source
+        @agent_files = agent_file_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        agent_id = AgentPayload.presence(p[:agent_id])
+        file = AgentPayload.presence(p[:file])
+        raise Insika::ValidationError, "agent_id is required" if agent_id.nil?
+        raise Insika::ValidationError, "file is required" if file.nil?
+        profile = @profile_source.fetch(agent_id) ||
+                  (raise Insika::NotFoundError, "agent '#{agent_id}' not found")
+
+        # `.to_s` used to be unconditional here, which is how a JSON body carrying an
+        # OBJECT for `content` became a prompt file holding Ruby's #inspect of it. The
+        # store refuses that now; keep the coercion for scalars (a form always sends a
+        # String, and nil means "clear the file").
+        content = Insika::AgentFileStore.text!(p[:content], agent_id, file).to_s
+        entry = @agent_files.write(agent_id, file, content, create_only: !!p[:create_only])
+        # Writing a prompt registers it in prompt_files — otherwise the Prompt provider
+        # would never load it. It's the Command's job, not the dispatcher's.
+        register_prompt_file(profile, file)
+        emit(:agent_file_written, agent_id, file)
+        { agent_id: agent_id, file: file, updated_at: entry["updated_at"] }
+      end
+
+      private
+
+      def register_prompt_file(profile, file)
+        files = Array(profile.prompt_files).map(&:to_s)
+        return if files.include?(file)
+
+        @profile_source.put(Insika::AgentProfile.build(**profile.to_h.merge(prompt_files: files + [file])))
+      end
+
+      def emit(type, agent_id, file)
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: { agent_id: agent_id, file: file },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/write_data_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Writes (upserts) a DATA-defined tool into the ToolStore and RELOADS the overlay +
+    # catalog — takes effect without a restart (F5). Rejects a name that collides with a
+    # code tool (R3). Validating the definition (format, method/url, types,
+    # placeholders) is the ToolStore/ToolDefinition's job. Secrets (headers) reconcile
+    # in the store; the event carries only the name (0 leakage). -> { name, definition }.
+    class WriteDataTool
+      def initialize(tool_store:, registry:, tool_catalog:, event_stream:)
+        @tool_store = tool_store
+        @registry = registry
+        @tool_catalog = tool_catalog
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        raise Insika::ValidationError, "name is required" if name.nil?
+        raise Insika::ValidationError, "'#{name}' is already a code tool" if @registry.code_tool?(name)
+
+        masked = @tool_store.write(p, create_only: !!p[:create_only])
+        @registry.reload
+        @tool_catalog.reload
+        emit(name)
+        { name: name, definition: masked }
+      end
+
+      private
+
+      def emit(name)
+        @event_stream.emit(Insika::Event.new(
+                             type: :data_tool_written, data: { name: name },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/write_golden.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes an eval case (RFC-0008 §3.1) into the GoldenStore. This
+    # is what lets a domain owner add a case — above all its RUBRIC, the part of an eval
+    # that is plain language — without a checkout and a text editor.
+    #
+    # The payload carries the case as DATA (`case:`), the same mapping the YAML file
+    # holds; the store validates it with the one loader, so a case authored here and a
+    # case read from `evals/golden/` cannot diverge. -> { id, agent }.
+    class WriteGolden
+      def initialize(golden_store:, event_stream:)
+        @goldens = golden_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        raise Insika::ValidationError, "case is required" unless p[:case].is_a?(Hash)
+
+        golden = @goldens.write(p[:case])
+        emit(:golden_written, id: golden.id, agent: golden.agent)
+        { id: golden.id, agent: golden.agent }
+      end
+
+      private
+
+      def emit(type, **data)
+        @event_stream.emit(Insika::Event.new(type: type, data: data,
+                                            meta: { at: Time.now.utc.iso8601 }))
+      end
+    end
+
+    # Control command: removes an eval case. The corpus on disk is the way back
+    # (`insika evals:import`), which is why this needs no version history.
+    # -> { id, existed }.
+    class DeleteGolden
+      def initialize(golden_store:, event_stream:)
+        @goldens = golden_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        id = AgentPayload.presence(p[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+
+        existed = @goldens.delete(id)
+        @event_stream.emit(Insika::Event.new(type: :golden_deleted, data: { id: id, existed: existed },
+                                            meta: { at: Time.now.utc.iso8601 }))
+        { id: id, existed: existed }
+      end
+    end
+  end
+end