spurline-docs 0.3.0

data/lib/spurline/orchestration/ledger.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Spurline
+  module Orchestration
+    # Workflow state machine for planner/worker/judge orchestration.
+    class Ledger
+      STATES = %i[planning executing merging complete error].freeze
+
+      VALID_TRANSITIONS = {
+        planning: [:executing, :error],
+        executing: [:merging, :error],
+        merging: [:complete, :executing, :error],
+        complete: [],
+        error: [],
+      }.freeze
+
+      TASK_STATES = %i[pending assigned running complete failed].freeze
+
+      attr_reader :id, :state, :plan, :tasks, :dependency_graph,
+                  :merged_output, :metadata, :created_at
+
+      def initialize(id: SecureRandom.uuid, store: nil)
+        @id = id.to_s
+        @state = :planning
+        @plan = []
+        @tasks = {}
+        @dependency_graph = {}
+        @merged_output = {}
+        @metadata = {}
+        @created_at = Time.now.utc
+        @store = store
+      end
+
+      # @param envelope [TaskEnvelope]
+      # @return [TaskEnvelope]
+      def add_task(envelope)
+        assert_state!(:planning, "tasks can only be added during planning")
+
+        normalized = normalize_envelope(envelope)
+        task_id = normalized.task_id
+        raise Spurline::LedgerError, "task already exists: #{task_id}" if @tasks.key?(task_id)
+
+        @tasks[task_id] = {
+          envelope: normalized,
+          state: :pending,
+          worker_session_id: nil,
+          output: nil,
+          error: nil,
+        }
+        @dependency_graph[task_id] = []
+        @plan << task_id
+        persist!
+        normalized
+      end
+
+      def add_dependency(task_id, depends_on:)
+        task_id = task_id.to_s
+        depends_on = depends_on.to_s
+
+        fetch_task!(task_id)
+        fetch_task!(depends_on)
+
+        if task_id == depends_on
+          raise Spurline::LedgerError, "task cannot depend on itself: #{task_id}"
+        end
+
+        deps = (@dependency_graph[task_id] ||= [])
+        deps << depends_on unless deps.include?(depends_on)
+        persist!
+        deps
+      end
+
+      def assign_task(task_id, worker_session_id:)
+        task = fetch_task!(task_id)
+        ensure_task_state!(task_id, expected: :pending)
+
+        if worker_session_id.to_s.strip.empty?
+          raise Spurline::LedgerError, "worker_session_id is required"
+        end
+
+        task[:state] = :assigned
+        task[:worker_session_id] = worker_session_id.to_s
+        task[:error] = nil
+        persist!
+        task
+      end
+
+      def start_task(task_id)
+        task = fetch_task!(task_id)
+        ensure_task_state!(task_id, expected: :assigned)
+
+        task[:state] = :running
+        persist!
+        task
+      end
+
+      def complete_task(task_id, output:)
+        task = fetch_task!(task_id)
+        ensure_task_state_in!(task_id, expected: %i[running assigned])
+
+        task[:state] = :complete
+        task[:output] = deep_copy(output)
+        task[:error] = nil
+        persist!
+        task
+      end
+
+      def fail_task(task_id, error:)
+        task = fetch_task!(task_id)
+        ensure_task_state_in!(task_id, expected: %i[running assigned])
+
+        task[:state] = :failed
+        task[:error] = error.to_s
+        persist!
+        task
+      end
+
+      def task_status(task_id)
+        fetch_task!(task_id)[:state]
+      end
+
+      def all_tasks_complete?
+        @tasks.values.all? { |task| task[:state] == :complete }
+      end
+
+      def completed_tasks
+        select_tasks_by_state(:complete)
+      end
+
+      def pending_tasks
+        select_tasks_by_state(:pending)
+      end
+
+      # pending tasks whose dependencies are all complete
+      def unblocked_tasks
+        pending_tasks.select do |task_id, _task|
+          dependencies = @dependency_graph[task_id] || []
+          dependencies.all? { |dep_id| task_status(dep_id) == :complete }
+        end
+      end
+
+      def transition_to!(new_state)
+        target = new_state.to_sym
+
+        unless STATES.include?(target)
+          raise Spurline::LedgerError, "invalid ledger state: #{new_state.inspect}"
+        end
+
+        allowed = VALID_TRANSITIONS.fetch(@state)
+        unless allowed.include?(target)
+          raise Spurline::LedgerError, "invalid transition #{@state} -> #{target}"
+        end
+
+        @state = target
+        persist!
+        @state
+      end
+
+      def to_h
+        {
+          id: id,
+          state: state,
+          plan: deep_copy(plan),
+          tasks: serialized_tasks,
+          dependency_graph: deep_copy(dependency_graph),
+          merged_output: deep_copy(merged_output),
+          metadata: deep_copy(metadata),
+          created_at: created_at.utc.iso8601,
+        }
+      end
+
+      def self.from_h(data, store: nil)
+        hash = data || {}
+        ledger = new(id: fetch_key(hash, :id, required: true), store: store)
+
+        state = (fetch_key(hash, :state) || :planning).to_sym
+        unless STATES.include?(state)
+          raise Spurline::LedgerError, "invalid ledger state: #{state.inspect}"
+        end
+
+        plan = Array(fetch_key(hash, :plan) || []).map(&:to_s)
+        tasks = deserialize_tasks(fetch_key(hash, :tasks) || {})
+        dependency_graph = deserialize_dependency_graph(fetch_key(hash, :dependency_graph) || {})
+
+        ledger.instance_variable_set(:@state, state)
+        ledger.instance_variable_set(:@plan, plan)
+        ledger.instance_variable_set(:@tasks, tasks)
+        ledger.instance_variable_set(:@dependency_graph, dependency_graph)
+        ledger.instance_variable_set(:@merged_output, ledger.send(:deep_copy, fetch_key(hash, :merged_output) || {}))
+        ledger.instance_variable_set(:@metadata, ledger.send(:deep_copy, fetch_key(hash, :metadata) || {}))
+        ledger.instance_variable_set(:@created_at, parse_time(fetch_key(hash, :created_at)))
+
+        ledger
+      end
+
+      private
+
+      def persist!
+        @store&.save_ledger(self)
+      end
+
+      def normalize_envelope(envelope)
+        return envelope if envelope.is_a?(TaskEnvelope)
+
+        if envelope.is_a?(Hash)
+          return TaskEnvelope.from_h(envelope)
+        end
+
+        raise Spurline::LedgerError, "envelope must be a TaskEnvelope or Hash"
+      end
+
+      def fetch_task!(task_id)
+        id = task_id.to_s
+        @tasks.fetch(id) do
+          raise Spurline::LedgerError, "unknown task: #{id}"
+        end
+      end
+
+      def ensure_task_state!(task_id, expected:)
+        actual = task_status(task_id)
+        return if actual == expected
+
+        raise Spurline::LedgerError, "task #{task_id} must be #{expected}, got #{actual}"
+      end
+
+      def ensure_task_state_in!(task_id, expected:)
+        actual = task_status(task_id)
+        return if expected.include?(actual)
+
+        raise Spurline::LedgerError, "task #{task_id} must be one of #{expected.inspect}, got #{actual}"
+      end
+
+      def assert_state!(expected, message)
+        return if state == expected
+
+        raise Spurline::LedgerError, message
+      end
+
+      def select_tasks_by_state(target)
+        @tasks.each_with_object({}) do |(task_id, task), selected|
+          next unless task[:state] == target
+
+          selected[task_id] = snapshot_task(task)
+        end
+      end
+
+      def snapshot_task(task)
+        {
+          envelope: task[:envelope],
+          state: task[:state],
+          worker_session_id: task[:worker_session_id],
+          output: deep_copy(task[:output]),
+          error: task[:error],
+        }
+      end
+
+      def serialized_tasks
+        @tasks.each_with_object({}) do |(task_id, task), serialized|
+          serialized[task_id] = {
+            envelope: task[:envelope].to_h,
+            state: task[:state],
+            worker_session_id: task[:worker_session_id],
+            output: deep_copy(task[:output]),
+            error: task[:error],
+          }
+        end
+      end
+
+      def deep_copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), copy|
+            copy[key] = deep_copy(item)
+          end
+        when Array
+          value.map { |item| deep_copy(item) }
+        else
+          value
+        end
+      end
+
+      class << self
+        private
+
+        def parse_time(value)
+          return Time.now.utc if value.nil?
+          return value.utc if value.respond_to?(:utc)
+
+          Time.parse(value.to_s).utc
+        end
+
+        def deserialize_tasks(raw_tasks)
+          (raw_tasks || {}).each_with_object({}) do |(task_id, task_data), deserialized|
+            task_hash = task_data || {}
+            envelope_data = fetch_key(task_hash, :envelope, required: true) do
+              raise Spurline::LedgerError, "task #{task_id} missing envelope"
+            end
+
+            envelope = envelope_data.is_a?(TaskEnvelope) ? envelope_data : TaskEnvelope.from_h(envelope_data)
+            task_state = (fetch_key(task_hash, :state) || :pending).to_sym
+
+            unless TASK_STATES.include?(task_state)
+              raise Spurline::LedgerError, "invalid task state for #{task_id}: #{task_state.inspect}"
+            end
+
+            deserialized[task_id.to_s] = {
+              envelope: envelope,
+              state: task_state,
+              worker_session_id: fetch_key(task_hash, :worker_session_id),
+              output: fetch_key(task_hash, :output),
+              error: fetch_key(task_hash, :error),
+            }
+          end
+        end
+
+        def deserialize_dependency_graph(raw_graph)
+          (raw_graph || {}).each_with_object({}) do |(task_id, deps), graph|
+            graph[task_id.to_s] = Array(deps).map(&:to_s)
+          end
+        end
+
+        def fetch_key(hash, key, required: false, &block)
+          if hash.is_a?(Hash) && hash.key?(key)
+            hash[key]
+          elsif hash.is_a?(Hash) && hash.key?(key.to_s)
+            hash[key.to_s]
+          elsif required
+            return block.call if block
+
+            raise KeyError, "missing key: #{key}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/orchestration/merge_queue.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Orchestration
+    # Deterministic FIFO merge queue with explicit conflict handling strategies.
+    class MergeQueue
+      STRATEGIES = %i[escalate file_level union].freeze
+
+      ConflictReport = Struct.new(:task_id, :conflicting_task_id, :resource, :details, keyword_init: true)
+      MergeResult = Struct.new(:success, :merged_output, :conflicts, keyword_init: true) do
+        def success?
+          success
+        end
+      end
+
+      def initialize(strategy: :escalate)
+        @strategy = strategy.to_sym
+        validate_strategy!(@strategy)
+        @queue = []
+      end
+
+      def enqueue(task_id:, output:)
+        unless output.is_a?(Hash)
+          raise ArgumentError, "merge output must be a hash"
+        end
+
+        @queue << { task_id: task_id.to_s, output: deep_copy(output) }
+      end
+
+      def process(existing_output: {})
+        merged = deep_copy(existing_output)
+        key_sources = merged.keys.each_with_object({}) { |key, map| map[key] = nil }
+        conflicts = []
+
+        until @queue.empty?
+          entry = @queue.shift
+          overlaps = detect_conflicts(merged, entry)
+
+          case @strategy
+          when :escalate
+            if overlaps.any?
+              conflicts.concat(build_conflict_reports(entry, overlaps, key_sources, strategy: :escalate))
+              next
+            end
+
+            merge_entry!(merged, key_sources, entry)
+          when :file_level
+            conflicts.concat(build_conflict_reports(entry, overlaps, key_sources, strategy: :file_level))
+            overlapping_keys = overlaps.map { |item| item[:resource] }
+
+            entry[:output].each do |key, value|
+              next if overlapping_keys.include?(key)
+
+              merged[key] = deep_copy(value)
+              key_sources[key] = entry[:task_id]
+            end
+          when :union
+            conflicts.concat(build_conflict_reports(entry, overlaps, key_sources, strategy: :union))
+            merge_entry!(merged, key_sources, entry)
+          end
+        end
+
+        success = @strategy == :escalate ? conflicts.empty? : true
+        MergeResult.new(success: success, merged_output: merged, conflicts: conflicts)
+      end
+
+      def size
+        @queue.size
+      end
+
+      def empty?
+        @queue.empty?
+      end
+
+      private
+
+      # Conflict detection: hash-key overlap with different values.
+      def detect_conflicts(existing, entry)
+        entry[:output].each_with_object([]) do |(key, value), conflicts|
+          next unless existing.key?(key)
+          next if existing[key] == value
+
+          conflicts << {
+            resource: key,
+            existing_value: deep_copy(existing[key]),
+            incoming_value: deep_copy(value),
+          }
+        end
+      end
+
+      def validate_strategy!(strategy)
+        return if STRATEGIES.include?(strategy)
+
+        raise Spurline::ConfigurationError, "invalid merge strategy: #{strategy.inspect}"
+      end
+
+      def merge_entry!(merged, key_sources, entry)
+        entry[:output].each do |key, value|
+          merged[key] = deep_copy(value)
+          key_sources[key] = entry[:task_id]
+        end
+      end
+
+      def build_conflict_reports(entry, overlaps, key_sources, strategy:)
+        overlaps.map do |overlap|
+          ConflictReport.new(
+            task_id: entry[:task_id],
+            conflicting_task_id: key_sources[overlap[:resource]],
+            resource: overlap[:resource],
+            details: {
+              strategy: strategy,
+              existing_value: overlap[:existing_value],
+              incoming_value: overlap[:incoming_value],
+            }
+          )
+        end
+      end
+
+      def deep_copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), copy|
+            copy[key] = deep_copy(item)
+          end
+        when Array
+          value.map { |item| deep_copy(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/spurline/orchestration/permission_intersection.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Orchestration
+    module PermissionIntersection
+      module_function
+
+      # Computes effective parent->child permissions under the setuid rule.
+      # Result is always <= parent when both define the same tool.
+      def compute(parent_permissions, child_permissions)
+        parent = normalize_permissions(parent_permissions)
+        child = normalize_permissions(child_permissions)
+
+        tool_names = (parent.keys + child.keys).uniq
+
+        tool_names.each_with_object({}) do |tool_name, result|
+          parent_tool = parent[tool_name]
+          child_tool = child[tool_name]
+
+          result[tool_name] = if parent_tool && child_tool
+                                intersect_tool(parent_tool, child_tool)
+                              elsif parent_tool
+                                deep_copy(parent_tool)
+                              else
+                                deep_copy(child_tool)
+                              end
+        end
+      end
+
+      # Validates that child permissions do not exceed parent permissions.
+      # Raises PrivilegeEscalationError if a child broadens access.
+      def validate_no_escalation!(parent, child)
+        normalized_parent = normalize_permissions(parent)
+        normalized_child = normalize_permissions(child)
+
+        normalized_child.each do |tool_name, child_tool|
+          parent_tool = normalized_parent[tool_name]
+          next unless parent_tool
+
+          validate_denied!(tool_name, parent_tool, child_tool)
+          validate_requires_confirmation!(tool_name, parent_tool, child_tool)
+          validate_allowed_users!(tool_name, parent_tool, child_tool)
+        end
+
+        true
+      end
+
+      def intersect_tool(parent_tool, child_tool)
+        denied = truthy?(parent_tool[:denied]) || truthy?(child_tool[:denied])
+        requires_confirmation = truthy?(parent_tool[:requires_confirmation]) ||
+                                truthy?(child_tool[:requires_confirmation])
+
+        parent_users = normalize_users(parent_tool[:allowed_users])
+        child_users = normalize_users(child_tool[:allowed_users])
+
+        allowed_users = if parent_users && child_users
+                          parent_users & child_users
+                        elsif parent_users
+                          parent_users
+                        else
+                          child_users
+                        end
+
+        result = {
+          denied: denied,
+          requires_confirmation: requires_confirmation,
+        }
+        result[:allowed_users] = allowed_users if allowed_users
+        result
+      end
+      private_class_method :intersect_tool
+
+      def validate_denied!(tool_name, parent_tool, child_tool)
+        return unless truthy?(parent_tool[:denied]) && !truthy?(child_tool[:denied])
+
+        raise Spurline::PrivilegeEscalationError, "child tool #{tool_name} removes denied=true"
+      end
+      private_class_method :validate_denied!
+
+      def validate_requires_confirmation!(tool_name, parent_tool, child_tool)
+        return unless truthy?(parent_tool[:requires_confirmation]) && !truthy?(child_tool[:requires_confirmation])
+
+        raise Spurline::PrivilegeEscalationError, "child tool #{tool_name} removes requires_confirmation=true"
+      end
+      private_class_method :validate_requires_confirmation!
+
+      def validate_allowed_users!(tool_name, parent_tool, child_tool)
+        parent_users = normalize_users(parent_tool[:allowed_users])
+        child_users = normalize_users(child_tool[:allowed_users])
+
+        return if parent_users.nil?
+
+        if child_users.nil?
+          raise Spurline::PrivilegeEscalationError,
+                "child tool #{tool_name} omits allowed_users while parent restricts it"
+        end
+
+        extra_users = child_users - parent_users
+        return if extra_users.empty?
+
+        raise Spurline::PrivilegeEscalationError,
+              "child tool #{tool_name} adds users not allowed by parent: #{extra_users.join(", ")}"
+      end
+      private_class_method :validate_allowed_users!
+
+      def normalize_permissions(permissions)
+        raw = permissions || {}
+
+        raw.each_with_object({}) do |(tool_name, config), normalized|
+          normalized[tool_name.to_sym] = normalize_tool_config(config)
+        end
+      end
+      private_class_method :normalize_permissions
+
+      def normalize_tool_config(config)
+        return {} unless config.is_a?(Hash)
+
+        config.each_with_object({}) do |(key, value), normalized|
+          normalized[key.to_sym] = key.to_sym == :allowed_users ? normalize_users(value) : value
+        end
+      end
+      private_class_method :normalize_tool_config
+
+      def normalize_users(users)
+        return nil if users.nil?
+
+        Array(users).map(&:to_s).uniq
+      end
+      private_class_method :normalize_users
+
+      def truthy?(value)
+        value == true
+      end
+      private_class_method :truthy?
+
+      def deep_copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), copy|
+            copy[key] = deep_copy(item)
+          end
+        when Array
+          value.map { |item| deep_copy(item) }
+        else
+          value
+        end
+      end
+      private_class_method :deep_copy
+    end
+  end
+end