insika 0.0.1 → 0.2.0

data/lib/insika/recovery.rb

@@ -0,0 +1,168 @@
+# 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. 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.
+    #
+    # stale_after (seconds): the periodic tick's semantics instead of
+    # boot's. Only :queued/:running tasks untouched for longer than that are
+    # candidates — :waiting/:paused are idle by nature (a human wait), so
+    # staleness cannot tell a live one from a dead one, and they stay boot
+    # recovery's. The threshold exists because a live :running turn is bounded
+    # by turn_timeout: anything older cannot be alive.
+    def run(stale_after: nil)
+      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. Tick mode
+      #    narrows this to :running — the only mid-flight state staleness can judge.
+      running = stale_after ? @task_store.with_status(:running) : @task_store.running_or_interrupted
+      sweep(running, stale_after).each { |task| process(task, resumed, failed, tick: !stale_after.nil?) }
+      # 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.
+      sweep(@task_store.queued, stale_after).each { |task| process(task, resumed, failed, tick: !stale_after.nil?) }
+      log(:info, "recovery finished: #{resumed.size} resumed, #{failed.size} failed")
+      { resumed: resumed, failed: failed }
+    end
+
+    private
+
+    # Boot mode (stale_after nil) takes the candidate list as-is; tick mode keeps
+    # only tasks untouched past the threshold — the liveness gate of.
+    def sweep(tasks, stale_after)
+      tasks = tasks.sort_by(&:created_at)
+      return tasks unless stale_after
+
+      cutoff = Time.now.utc - stale_after
+      tasks.select { |task| stale?(task, cutoff) }
+    end
+
+    def stale?(task, cutoff)
+      Time.iso8601(task.updated_at.to_s) < cutoff
+    rescue ArgumentError
+      true # an unreadable timestamp is not proof of life — treat as stale
+    end
+
+    # 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).
+    #
+    # tick: true flips ONE rescue: a ValidationError from the dispatch
+    # is ResumeTask's local liveness check ("task is running") — someone alive
+    # owns it, the normal case on a timer, so the task is SKIPPED for the next
+    # tick. At boot a ValidationError means corruption (nothing may be alive),
+    # so it still fails the task there. This is the trap defused in-process:
+    # the tick must never murder a live turn with its own recovery.
+    def process(task, resumed, failed, tick: false)
+      # :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 Insika::ValidationError => e
+      # Boot keeps the old contract (corruption -> :failed); the tick skips.
+      if tick
+        log(:info, "skipped (alive elsewhere): #{task.id} — #{e.message}")
+      else
+        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
+    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. 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 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. 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, 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