insika 0.0.1 → 0.1.0

data/lib/insika/profile_source.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Insika
+  # Source of AgentProfiles. Profiles used to be
+  # a FROZEN Hash injected into the Executor and the turn Commands — static,
+  # defined in Ruby at wiring time. For the Studio to create/edit agents at
+  # runtime, the source needs to be MUTABLE and reloadable, without changing the
+  # consumption contract.
+  #
+  # The consumption contract is minimal and duck-typed: `source[id] -> AgentProfile|nil`
+  # (like a Hash). That's why the refactor in the Executor/Commands is just
+  # normalizing the input (legacy Hash -> StaticProfileSource); the bodies that do
+  # `@profiles[agent]` stay identical. `all`/`ids` are for the Studio to list.
+  #
+  # `nil` from `[]`/`fetch` = agent not configured (the Commands raise
+  # NotFoundError) — NEVER raises (unlike Hash#fetch).
+  module ProfileSource
+    # Hash-compat sugar: `source[id]`.
+    def [](id) = fetch(id)
+
+    # Normalizes the consumers' input: a legacy Hash becomes a StaticProfileSource;
+    # a ProfileSource passes straight through. A single place for the compat seam.
+    def self.coerce(profiles)
+      return profiles if profiles.is_a?(ProfileSource)
+
+      StaticProfileSource.new(profiles || {})
+    end
+
+    # subclasses implement: fetch(id) -> AgentProfile|nil, all -> [AgentProfile], ids -> [String]
+  end
+
+  # Static source (parity): wraps the usual {id => AgentProfile} Hash.
+  # Behavior IDENTICAL to the frozen Hash — zero regression.
+  class StaticProfileSource
+    include ProfileSource
+
+    def initialize(profiles = {})
+      @profiles = profiles
+    end
+
+    def fetch(id) = @profiles[id]
+    def all = @profiles.values
+    def ids = @profiles.keys
+  end
+
+  # Persisted source (Studio): reads/writes profiles in the ConfigStore (scope "agents").
+  # Each `fetch` reads FRESH from the store — an edit via the Studio takes effect on
+  # the next dispatch, without a restart. An in-flight turn keeps the profile it
+  # captured (the Commands resolve at the start of #call), so the turn semantics are
+  # preserved.
+  class StoredProfileSource
+    include ProfileSource
+    include Coercion
+
+    SCOPE = "agents"
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    def fetch(id)
+      record = @cs.get(SCOPE, id.to_s)
+      record && deserialize(record)
+    end
+
+    def all = @cs.all(SCOPE).map { |r| deserialize(r) }
+    def ids = @cs.keys(SCOPE)
+
+    # Write (used by the :create_agent/:update_agent Commands).
+    def put(profile)
+      @cs.put(SCOPE, profile.id, profile.to_h)
+      profile
+    end
+
+    def delete(id) = @cs.delete(SCOPE, id.to_s)
+
+    private
+
+    # Rebuilds the AgentProfile from the record (the JSON round-trip turns symbols
+    # into strings). Re-symbolizes the fields the runtime consumes as symbols:
+    # provider, policies (names in the PolicyRegistry) and the limits keys (
+    # DEFAULT_LIMITS uses symbols and the merge would break with string keys).
+    def deserialize(record)
+      h = symbolize_top(record)
+      AgentProfile.build(
+        id: h[:id], model: h[:model],
+        provider: presence(h[:provider])&.to_sym,
+        base_prompt: h[:base_prompt].to_s,
+        prompt_files: h[:prompt_files] || [],
+        tools_allow: h[:tools_allow], tools_deny: h[:tools_deny] || [],
+        tools_allow_groups: h[:tools_allow_groups],
+        skills: h[:skills],
+        context_providers: h[:context_providers],
+        workflows_allow: h[:workflows_allow],
+        policies: Array(h[:policies]).map(&:to_sym),
+        prompt_refs: h[:prompt_refs] || [],
+        limits: symbolize_limits(h[:limits]),
+        approvals_required: h[:approvals_required],
+        capabilities: h[:capabilities],
+        # subagents (RFC-0010): allowlist of child ids; build re-normalizes to
+        # [String]. nil round-trips as nil (opt-in: NONE).
+        subagents: h[:subagents],
+        tools_deferred: h[:tools_deferred],
+        memory: h[:memory],
+        prompt_caching: h[:prompt_caching],
+        # params/model_policy (v2, §10): the resolver tolerates string keys from
+        # the JSON round-trip (ModelResolver#normalize_params / ModelPolicy), so no
+        # re-symbolization needed here.
+        params: h[:params] || {},
+        model_policy: h[:model_policy],
+        # guardrails (RFC-0009): a plain Hash; Safety::Config tolerates the JSON
+        # round-trip (string keys/values), so no re-symbolization here.
+        guardrails: h[:guardrails],
+        # sandbox (item 35): a plain config Hash; Sandbox.build tolerates the JSON
+        # round-trip (string keys), so no re-symbolization here. nil = absent.
+        sandbox: h[:sandbox],
+        # refinement (RFC-0013): a plain config Hash read with string keys by the
+        # RunRefinement handler; nil round-trips as nil (= report-only).
+        refinement: h[:refinement],
+        # capabilities_declared (RFC-0014 §3.5): flat [String]; build re-normalizes.
+        capabilities_declared: h[:capabilities_declared],
+        # edge_stream: which internal channels may cross to the customer. {} = neither.
+        edge_stream: h[:edge_stream],
+        metadata: h[:metadata] || {}
+      )
+    end
+
+    def symbolize_top(record) = record.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+
+    # limits keys -> symbol; numeric values preserved by JSON.
+    def symbolize_limits(limits)
+      return {} if limits.nil?
+
+      limits.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/insika/prompt_catalog.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insika
+  # Catalog of prompts: NON-executable content
+  # (it is a Catalog, not a Registry). Mirrors the SkillCatalog: each prompt is a directory
+  # with a PROMPT.md (YAML frontmatter name/description + markdown body).
+  # Source for the Prompt provider when the profile uses prompt_refs.
+  class PromptCatalog
+    Prompt = Data.define(:name, :description, :path, :body)
+
+    # roots ordered by PRECEDENCE (highest first) — same name in more than
+    # one root: the first wins (identical to SkillCatalog).
+    def initialize(roots)
+      @roots = Array(roots)
+      @prompts = load_all
+    end
+
+    def all = @prompts.values
+
+    # -> Prompt | nil (the Prompt provider converts nil into a ContextError; it is not
+    # the catalog's job to raise).
+    def find(name) = @prompts[name.to_s]
+
+    # Rescan + atomic index swap: parity with the SkillCatalog
+    # for reload without a restart when the on-disk seed changes.
+    def reload
+      @prompts = load_all
+      self
+    end
+
+    private
+
+    def load_all
+      found = {}
+      @roots.each do |root|
+        Dir.glob(File.join(root, "**", "PROMPT.md")).sort.each do |file|
+          prompt = parse(file)
+          next unless prompt
+
+          found[prompt.name] ||= prompt # precedence: first root wins
+        end
+      end
+      found
+    end
+
+    def parse(file)
+      raw = File.read(file, encoding: "UTF-8")
+      match = raw.match(/\A---\s*\n(.*?)\n---\s*\n(.*)\z/m)
+      return nil unless match
+
+      meta = YAML.safe_load(match[1]) || {}
+      name = meta["name"]
+      return nil unless name
+
+      Prompt.new(name: name.to_s, description: meta["description"].to_s,
+                 path: file, body: match[2].strip)
+    end
+  end
+end

data/lib/insika/queue_policy.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "coercion"
+
+module Insika
+  # RFC-0015 §4 — what happens to an inbound message for a session that is ALREADY
+  # busy. Today the engine has exactly one answer, "it waits in line"; this names
+  # that answer `followup` and adds three others:
+  #
+  #   collect   — the message arrived BEFORE the turn started: merge the fragments
+  #               into one turn (the whole mechanism is a timer at the door).
+  #   steer     — the turn is ALREADY running tools: append the message to the run in
+  #               flight, at a tool-batch boundary, so the customer's correction lands
+  #               before the model's next step instead of after the whole run.
+  #   interrupt — the turn is running and is now answering the wrong question: abandon
+  #               it at its next boundary and let the new message be its own turn.
+  #
+  # They never compete for the same message: `collect` only ever touches a turn that
+  # has not started; `steer` and `interrupt` only a turn that has, and they differ in
+  # whether the run in flight is still worth finishing.
+  #
+  # Resolution per message, the order EdgeLimiter already documents
+  # (`edge_limiter.rb:17`) — configuration over convention:
+  #
+  #   session vars["queue_mode"]   — one conversation pinned by an operator
+  #   profile.limits[:<key>]       — per-agent (a PRESENT key wins, incl. nil/0 = off)
+  #   settings["queue"][<key>]     — platform default, editable in the Studio
+  #   DEFAULTS[<key>]              — = today's behavior
+  #
+  # Every default is off: a bare wiring behaves exactly as it did before this
+  # existed. The knobs live in `profile.limits` next to `tool_concurrency` and
+  # `turn_timeout` because they are bounds on the same thing — how much work one
+  # turn is allowed to absorb.
+  class QueuePolicy
+    # All four of RFC-0015 are delivered, so there is no "specified but unshipped"
+    # tier any more — a mode outside this set is a typo, and it is refused rather than
+    # approximated. Treating an unknown mode as `followup` would look exactly like a
+    # mode that never fires.
+    MODES = %i[followup collect steer interrupt].freeze
+
+    DEFAULTS = {
+      queue_mode: :followup,
+      debounce_ms: 0,          # 0 = no window: dequeue immediately, today's path
+      debounce_max_ms: 10_000, # ceiling on the TOTAL deferral (see #debounce_deadline_ms)
+      steer_max_messages: 5,   # how many messages ONE run may absorb; overflow = followup
+      steer_join: nil          # nil = the raw text; a template frames it (see #frame)
+    }.freeze
+
+    # The placeholder `steer_join` must carry, so a template that would silently
+    # drop the customer's message is a config error and not a lost message.
+    JOIN_PLACEHOLDER = "%{message}"
+
+    attr_reader :mode, :debounce_ms, :debounce_max_ms, :steer_max_messages, :steer_join
+
+    # profile: an AgentProfile (or nil); settings_store: nil = no platform layer;
+    # vars: the session's vars Hash (string keys, as the SessionStore returns).
+    def self.resolve(profile, settings_store: nil, vars: nil)
+      platform = ((settings_store&.get || {})["queue"] || {})
+      limits = profile.respond_to?(:limits) ? (profile.limits || {}) : {}
+
+      new(
+        mode: mode!(pick_mode(vars, limits, platform)),
+        debounce_ms: pick(:debounce_ms, limits, platform),
+        debounce_max_ms: pick(:debounce_max_ms, limits, platform),
+        steer_max_messages: pick(:steer_max_messages, limits, platform),
+        steer_join: pick_text(:steer_join, limits, platform)
+      )
+    end
+
+    def initialize(mode:, debounce_ms:, debounce_max_ms:,
+                   steer_max_messages: DEFAULTS[:steer_max_messages], steer_join: nil)
+      @mode = mode
+      @debounce_ms = [debounce_ms.to_i, 0].max
+      # A non-positive ceiling would mean "defer forever", which nobody wants and
+      # which a stray 0 in a config would silently buy. Fall back to the default.
+      max = debounce_max_ms.to_i
+      @debounce_max_ms = max.positive? ? max : DEFAULTS[:debounce_max_ms]
+      # 0 (or a negative) is a legitimate "never steer on this agent" — unlike the
+      # ceiling above, it forbids rather than defers forever, so it is honored.
+      @steer_max_messages = [steer_max_messages.to_i, 0].max
+      @steer_join = join!(steer_join)
+    end
+
+    # Does this policy want messages held at the door at all?
+    def debounce? = @debounce_ms.positive?
+
+    # Does this policy merge into a turn that has not started yet?
+    def collect? = @mode == :collect
+
+    # Does this policy append into a turn that is already running? `steer_max_messages`
+    # of 0 is the agent saying no, so it answers false rather than steering once and
+    # then refusing.
+    def steer? = @mode == :steer && @steer_max_messages.positive?
+
+    # Does this policy abandon the turn in flight? The new message then becomes an
+    # ordinary turn of its own — which is why `interrupt`, unlike the two joining modes,
+    # needs no verdict field and works on every surface.
+    def interrupt? = @mode == :interrupt
+
+    # The content of the injected message. `steer_join` frames it when an agent needs
+    # the model to know this text arrived mid-run ("the customer just added: %{message}");
+    # nil — the default — appends exactly what the person typed. A plain gsub, not
+    # `format`: the text is a customer's, and a stray `%` in it must not raise.
+    def frame(text)
+      return text.to_s if @steer_join.nil?
+
+      @steer_join.gsub(JOIN_PLACEHOLDER, text.to_s)
+    end
+
+    # A mode name -> Symbol, or raise. Blank = the default (an absent key is not
+    # an error; a WRONG key is).
+    def self.mode!(value)
+      return DEFAULTS[:queue_mode] if Coercion.blank?(value)
+
+      name = value.to_s.strip.downcase.to_sym
+      return name if MODES.include?(name)
+
+      raise Insika::ValidationError,
+            "unknown queue_mode: #{value.inspect} (expected #{MODES.join(', ')})"
+    end
+
+    # A present key WINS even carrying nil/0 — "off for this agent", never
+    # "inherit the platform default". Same semantics EdgeLimiter documents at
+    # `edge_limiter.rb:57`, and for the same reason: an imported pack carrying an
+    # explicit null must not silently re-enable a platform behavior.
+    def self.pick(key, limits, platform)
+      return limits[key].to_i if limits.key?(key)
+      return platform[key.to_s].to_i if platform.key?(key.to_s)
+
+      DEFAULTS[key]
+    end
+
+    # Same rule as #pick for a key whose value is TEXT: `to_i` would turn a template
+    # into 0. A present-but-nil key still means "off for this agent".
+    def self.pick_text(key, limits, platform)
+      return limits[key] if limits.key?(key)
+      return platform[key.to_s] if platform.key?(key.to_s)
+
+      DEFAULTS[key]
+    end
+
+    def self.pick_mode(vars, limits, platform)
+      from_vars = (vars || {})["queue_mode"] || (vars || {})[:queue_mode]
+      return from_vars if Coercion.present?(from_vars)
+      return limits[:queue_mode] if limits.key?(:queue_mode)
+
+      platform["queue_mode"]
+    end
+
+    private_class_method :pick, :pick_text, :pick_mode
+
+    private
+
+    # A template that does not carry the placeholder would drop the customer's message
+    # while the turn still looked steered. Refused where the operator is (config time),
+    # not at 14:02 on a live conversation.
+    def join!(value)
+      return nil if Coercion.blank?(value)
+
+      text = value.to_s
+      return text if text.include?(JOIN_PLACEHOLDER)
+
+      raise Insika::ValidationError,
+            "steer_join must contain #{JOIN_PLACEHOLDER} (got #{value.inspect})"
+    end
+  end
+end

data/lib/insika/recovery.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # Called ONCE at boot, BEFORE accepting requests. Discovers
+  # interrupted tasks and dispatches the resume through the SAME path as
+  # ResumeTask — this component executes nothing, opens no Execution, changes no
+  # status of resumable tasks. Just discovery + dispatch + marking of
+  # unrecoverable tasks.
+  #
+  # Durability without an external job runner = stores +
+  # recovery at boot. The "execution" half is the ResumeTask handler.
+  #
+  # `command_bus` is consumed only through the `dispatch(command)` contract.
+  class Recovery
+    SWEEP_SCOPE = "recovery"
+
+    # The per-boot-generation sweep claim (RFC-0016 E2). N workers share one
+    # store, and the sweep's "orphaned :running" test is per-process: a worker
+    # booting while a sibling holds a live turn would see it as an orphan and
+    # re-run it. So the TASK sweep runs once per boot generation — the first
+    # worker to claim `boot_id` sweeps, the rest skip; a worker respawned
+    # mid-generation skips too (its own orphans wait for the next generation).
+    # Rides Store#transaction like every claim. nil/empty boot_id (single
+    # process: DSL serve, scripts, tests) -> always true, every boot sweeps.
+    def self.claim_sweep(store:, boot_id:)
+      id = boot_id.to_s
+      return true if id.empty?
+
+      store.transaction do
+        key = "sweep:#{id}"
+        if store.get(SWEEP_SCOPE, key).nil?
+          store.set(SWEEP_SCOPE, key, { "claimed_at" => Time.now.utc.iso8601 })
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # checkpoint_store: needed to query `latest`. logger optional
+    # (default nil -> silent in tests).
+    def initialize(task_store:, checkpoint_store:, command_bus:, logger: nil)
+      @task_store = task_store
+      @checkpoint_store = checkpoint_store
+      @command_bus = command_bus
+      @logger = logger
+    end
+
+    # -> { resumed: [ids], failed: [ids] }
+    # The initial sweep runs OUTSIDE the per-task rescue: a StoreError here
+    # aborts the boot.
+    def run
+      resumed = []
+      failed = []
+      # Ordered by created_at: tasks from the SAME session are reprocessed
+      # in their original order. Global time ordering is harmless for standalone tasks.
+      # 1) interrupted (crash mid-flight) -> resume from the checkpoint.
+      @task_store.running_or_interrupted.sort_by(&:created_at).each { |task| process(task, resumed, failed) }
+      # 2) queued but never started (turn in the SessionActor queue at crash time)
+      #    -> re-run from scratch (the same resume_task handles :queued). Without
+      #    this, a :queued turn in the volatile queue would be lost on kill -9.
+      @task_store.queued.sort_by(&:created_at).each { |task| process(task, resumed, failed) }
+      log(:info, "recovery finished: #{resumed.size} resumed, #{failed.size} failed")
+      { resumed: resumed, failed: failed }
+    end
+
+    private
+
+    # Failing to resume ONE task does not bring down the boot: a non-store
+    # dispatch/latest error -> mark :failed and continue. StoreError -> propagate
+    # (aborts the boot).
+    def process(task, resumed, failed)
+      # :queued never started (no checkpoint) but IS recoverable — ResumeTask
+      # re-runs from the Command. An interrupted task requires a checkpoint;
+      # without one, it is unrecoverable.
+      if task.status == :queued || @checkpoint_store.latest(task.id)
+        @command_bus.dispatch(resume_command(task.id))
+        resumed << task.id
+        log(:info, "resume dispatched: #{task.id}")
+      else
+        fail_task(task.id, class_name: "Insika::Error",
+                           message: "unrecoverable: no checkpoint")
+        failed << task.id
+        log(:warn, "unrecoverable (no checkpoint): #{task.id}")
+      end
+    rescue Insika::StoreError
+      raise
+    rescue StandardError => e
+      fail_task(task.id, class_name: e.class.name, message: e.message, stage: "recovery")
+      failed << task.id unless failed.include?(task.id)
+      log(:warn, "failed to resume #{task.id}: #{e.class}: #{e.message}")
+    end
+
+    # Transitions the task to :failed, writing the error into the open Execution
+    # (if any). StoreError propagates (aborts the boot). ArgumentError is
+    # absorbed: `paused -> failed` is not in the machine — the task stays in its
+    # current state, but we still report it as failed in the summary. Do not
+    # "fix" the machine here.
+    def fail_task(id, class_name:, message:, stage: nil)
+      error = { class: class_name, message: message }
+      error[:stage] = stage if stage
+      @task_store.transition(id, to: :failed, error: error)
+    rescue Insika::StoreError
+      raise
+    rescue ArgumentError
+      nil
+    end
+
+    def resume_command(task_id)
+      # transport: :recovery identifies the origin (boot) in meta — auditing
+      # (the field is a free Symbol).
+      Insika::Command.build(:resume_task, { task_id: task_id }, transport: :recovery)
+    end
+
+    # Logging is pure observability: a logger failure must NEVER alter the
+    # recovery flow (otherwise a buggy logger would corrupt the summary —
+    # e.g. an id in resumed AND failed). We swallow any logger error.
+    def log(level, message)
+      @logger&.public_send(level, "[recovery] #{message}")
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/insika/refinement/candidate.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Insika
+  module Refinement
+    # ONE proposed change to an agent's instruction files (RFC-0013 §3.4). Data, not
+    # a diff of free text, and that is the load-bearing decision of the whole phase:
+    #
+    #   · an ANCHORED edit is reviewable — the operator reads three lines, not a
+    #     rewritten file, and can tell in seconds whether to approve it;
+    #   · it is ATTRIBUTABLE — when the gate's score moves, it moved because of an
+    #     edit you can point at, not because a model rewrote the prompt;
+    #   · it is STALE-CHECKABLE — `before` must still match the file, so a proposal
+    #     built from a snapshot cannot silently clobber an edit made since.
+    #
+    # A candidate arrives from anywhere (a model, the Studio, a JSON payload) and is
+    # always built through `Candidate.build`, which is the only place the bounds and
+    # the write allowlist are enforced. An edit that violates one is DROPPED with a
+    # reason rather than failing the whole candidate: a proposal with two good edits
+    # and one stale one is worth gating, and the operator should see what fell off.
+    Edit = Data.define(:file, :op, :anchor, :before, :after, :addresses) do
+      def replace? = op == "replace"
+
+      # -> the new content, or nil when this edit no longer applies to `content`.
+      # `append` puts the text at the END of the file: `anchor` is a LABEL for the
+      # reviewer ("## shipping_quote"), never a locator — the locator is `before`,
+      # and inventing a second one would give the same edit two ways to land.
+      def apply_to(content)
+        return nil if content.nil?
+        return "#{content.chomp}\n\n#{after}\n" unless replace?
+        return nil unless content.include?(before)
+
+        content.sub(before, after)
+      end
+
+      def to_h = { "file" => file, "op" => op, "anchor" => anchor, "before" => before,
+                   "after" => after, "addresses" => addresses }
+    end
+
+    # A dropped edit and why. Kept ON the candidate rather than logged: "the model
+    # proposed four things and one was stale" is exactly what an operator reviewing
+    # the loop's usefulness needs, and §10 asks them to judge precisely that.
+    Dropped = Data.define(:file, :op, :reason) do
+      def to_h = { "file" => file, "op" => op, "reason" => reason }
+    end
+
+    Candidate = Data.define(:id, :proposer, :rationale, :edits, :dropped) do
+      def empty? = edits.empty?
+      def files = edits.map(&:file).uniq
+
+      # name => new content, for the files this candidate touches. Edits to the same
+      # file compose in order, so two edits to TOOLS.md both land.
+      def apply(contents)
+        edits.each_with_object({}) do |edit, acc|
+          current = acc[edit.file] || contents[edit.file]
+          applied = edit.apply_to(current)
+          acc[edit.file] = applied unless applied.nil?
+        end
+      end
+
+      def to_h = { "id" => id, "proposer" => proposer, "rationale" => rationale,
+                   "edits" => edits.map(&:to_h), "dropped" => dropped.map(&:to_h) }
+    end
+
+    # The bounds, all config (§3.4). Defaults are deliberately small: what makes a
+    # diff reviewable is that it is short, and what keeps the gate's signal readable
+    # is that a run changed few things.
+    DEFAULT_LIMITS = { "max_edits" => 3, "max_bytes" => 1200, "max_total_growth" => 0.15 }.freeze
+
+    OPS = %w[replace append].freeze
+
+    module CandidateBuilder
+      module_function
+
+      # raw:       { "proposer" =>, "rationale" =>, "edits" => [ … ] } (string keys)
+      # allowlist: the agent's `refinement.files`. EMPTY MEANS NOTHING IS WRITABLE —
+      #            report-only (§3.1/§3.8), so every edit drops. Not "no restriction":
+      #            an unset allowlist that meant "anything" would turn a missing
+      #            config into the most permissive setting there is.
+      # contents:  name => current content, for staleness and growth.
+      # -> Candidate (possibly empty; `empty?` never reaches the gate).
+      def build(raw, allowlist:, contents:, limits: {}, id: nil)
+        raw = Coercion.deep_stringify(raw.is_a?(Hash) ? raw : {})
+        bounds = DEFAULT_LIMITS.merge(limits.is_a?(Hash) ? Coercion.deep_stringify(limits) : {})
+        allow = Array(allowlist).map(&:to_s)
+
+        kept = []
+        dropped = []
+        # Growth is measured per FILE across the whole candidate, so three edits that
+        # are each under the cap cannot add up to a rewritten file.
+        grown = Hash.new(0)
+
+        Array(raw["edits"]).each do |edit|
+          built, reason = validate(Coercion.deep_stringify(edit), allow, contents, bounds, grown, kept.size)
+          if built
+            kept << built
+            grown[built.file] += built.after.to_s.bytesize - (built.replace? ? built.before.to_s.bytesize : 0)
+          else
+            dropped << Dropped.new(file: edit_field(edit, "file"), op: edit_field(edit, "op"), reason: reason)
+          end
+        end
+
+        Candidate.new(id: (id || SecureRandom.uuid).to_s,
+                      proposer: Coercion.presence(raw["proposer"]) || "operator",
+                      rationale: raw["rationale"].to_s, edits: kept, dropped: dropped)
+      end
+
+      # -> [Edit, nil] | [nil, reason]. One reason per edit, in the order an operator
+      # would ask: is it allowed, is it well-formed, does it still apply, is it small.
+      def validate(raw, allow, contents, bounds, grown, kept_count)
+        file = raw["file"].to_s
+        op = raw["op"].to_s
+        after = raw["after"].to_s
+
+        return [nil, "candidate is over max_edits (#{bounds['max_edits']})"] if kept_count >= bounds["max_edits"].to_i
+        return [nil, "'#{file}' is not on the refinement allowlist"] unless allow.include?(file)
+        return [nil, "unknown op '#{op}' (#{OPS.join('|')})"] unless OPS.include?(op)
+
+        current = contents[file]
+        return [nil, "'#{file}' does not exist for this agent"] if current.nil?
+        return [nil, "'after' is empty"] if after.strip.empty?
+
+        if after.bytesize > bounds["max_bytes"].to_i
+          return [nil, "edit is #{after.bytesize}B, over max_bytes (#{bounds['max_bytes']})"]
+        end
+
+        edit = Edit.new(file: file, op: op, anchor: Coercion.presence(raw["anchor"]),
+                        before: raw["before"].to_s, after: after,
+                        addresses: Array(raw["addresses"]).map(&:to_s))
+
+        if edit.replace?
+          return [nil, "'before' is empty — a replace with no anchor text is a rewrite"] if edit.before.empty?
+          # STALE: the file changed since the proposal was built (or the model
+          # hallucinated the text it claims to be replacing). Either way the edit
+          # describes a file that does not exist, and applying it by fuzzy match is
+          # how a refinement loop silently clobbers a human's edit.
+          return [nil, "'before' no longer matches '#{file}' (stale or invented)"] unless current.include?(edit.before)
+
+          if current.scan(edit.before).length > 1
+            return [nil, "'before' matches '#{file}' in #{current.scan(edit.before).length} places — ambiguous"]
+          end
+        end
+
+        growth = grown[file] + after.bytesize - (edit.replace? ? edit.before.bytesize : 0)
+        cap = (current.bytesize * bounds["max_total_growth"].to_f).ceil
+        return [nil, "would grow '#{file}' by #{growth}B, over max_total_growth (#{cap}B)"] if growth > cap
+
+        [edit, nil]
+      end
+
+      def edit_field(edit, key)
+        return nil unless edit.is_a?(Hash)
+
+        (edit[key] || edit[key.to_sym]).to_s
+      end
+    end
+  end
+end