spurline-core 0.3.0

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

data/lib/spurline/orchestration/task_envelope.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Spurline
+  module Orchestration
+    # Immutable work unit for worker execution.
+    class TaskEnvelope
+      CURRENT_VERSION = "1.0"
+
+      attr_reader :task_id, :version, :instruction, :input_files,
+                  :constraints, :acceptance_criteria, :output_spec,
+                  :scoped_context, :parent_session_id,
+                  :max_turns, :max_tool_calls, :metadata
+
+      # @param instruction [String] Natural language task description (required)
+      # @param acceptance_criteria [Array<String>] What the output must contain (required)
+      # @param task_id [String] UUID (auto-generated)
+      # @param version [String] Schema version
+      # @param input_files [Array<Hash>] Files the worker needs { path:, content: }
+      # @param constraints [Hash] Behavioral limits { no_modify: [...], read_only: true, ... }
+      # @param output_spec [Hash] Expected output format { type: :patch|:file|:answer, ... }
+      # @param scoped_context [Object,nil] Optional execution scope (M2.3)
+      # @param parent_session_id [String,nil] For audit correlation
+      # @param max_turns [Integer] Safety limit (default 10)
+      # @param max_tool_calls [Integer] Safety limit (default 20)
+      # @param metadata [Hash] Arbitrary extra data
+      def initialize(
+        instruction:,
+        acceptance_criteria:,
+        task_id: SecureRandom.uuid,
+        version: CURRENT_VERSION,
+        input_files: [],
+        constraints: {},
+        output_spec: {},
+        scoped_context: nil,
+        parent_session_id: nil,
+        max_turns: 10,
+        max_tool_calls: 20,
+        metadata: {}
+      )
+        validate_instruction!(instruction)
+        validate_acceptance_criteria!(acceptance_criteria)
+        validate_limit!(max_turns, name: "max_turns")
+        validate_limit!(max_tool_calls, name: "max_tool_calls")
+
+        @task_id = task_id.to_s
+        @version = version.to_s
+        @instruction = instruction.to_s
+        @input_files = deep_copy(input_files || [])
+        @constraints = deep_copy(constraints || {})
+        @acceptance_criteria = acceptance_criteria.map(&:to_s)
+        @output_spec = deep_copy(output_spec || {})
+        @scoped_context = normalize_scoped_context(scoped_context)
+        @parent_session_id = parent_session_id&.to_s
+        @max_turns = max_turns
+        @max_tool_calls = max_tool_calls
+        @metadata = deep_copy(metadata || {})
+
+        deep_freeze(@input_files)
+        deep_freeze(@constraints)
+        deep_freeze(@acceptance_criteria)
+        deep_freeze(@output_spec)
+        deep_freeze(@metadata)
+        if @scoped_context.is_a?(Hash) || @scoped_context.is_a?(Array)
+          deep_freeze(@scoped_context)
+        elsif @scoped_context.respond_to?(:freeze)
+          @scoped_context.freeze
+        end
+        freeze
+      end
+
+      def to_h
+        {
+          task_id: task_id,
+          version: version,
+          instruction: instruction,
+          input_files: deep_copy(input_files),
+          constraints: deep_copy(constraints),
+          acceptance_criteria: deep_copy(acceptance_criteria),
+          output_spec: deep_copy(output_spec),
+          scoped_context: serialize_scoped_context(scoped_context),
+          parent_session_id: parent_session_id,
+          max_turns: max_turns,
+          max_tool_calls: max_tool_calls,
+          metadata: deep_copy(metadata),
+        }
+      end
+
+      def self.from_h(data)
+        hash = deep_symbolize(data || {})
+        new(
+          task_id: hash[:task_id] || SecureRandom.uuid,
+          version: hash[:version] || CURRENT_VERSION,
+          instruction: hash.fetch(:instruction),
+          input_files: hash[:input_files] || [],
+          constraints: hash[:constraints] || {},
+          acceptance_criteria: hash.fetch(:acceptance_criteria),
+          output_spec: hash[:output_spec] || {},
+          scoped_context: hash[:scoped_context],
+          parent_session_id: hash[:parent_session_id],
+          max_turns: hash[:max_turns] || 10,
+          max_tool_calls: hash[:max_tool_calls] || 20,
+          metadata: hash[:metadata] || {}
+        )
+      end
+
+      private
+
+      def validate_instruction!(value)
+        return if value.to_s.strip != ""
+
+        raise Spurline::TaskEnvelopeError, "instruction is required"
+      end
+
+      def validate_acceptance_criteria!(value)
+        unless value.is_a?(Array) && !value.empty?
+          raise Spurline::TaskEnvelopeError, "acceptance_criteria must be a non-empty array"
+        end
+
+        if value.any? { |criterion| criterion.to_s.strip.empty? }
+          raise Spurline::TaskEnvelopeError, "acceptance_criteria entries must be non-empty"
+        end
+      end
+
+      def validate_limit!(value, name:)
+        unless value.is_a?(Integer) && value.positive?
+          raise Spurline::TaskEnvelopeError, "#{name} must be a positive integer"
+        end
+      end
+
+      def normalize_scoped_context(value)
+        return nil if value.nil?
+
+        if value.is_a?(Hash) || value.is_a?(Array)
+          deep_copy(value)
+        elsif value.respond_to?(:to_h)
+          deep_copy(value.to_h)
+        else
+          value
+        end
+      end
+
+      def serialize_scoped_context(value)
+        return nil if value.nil?
+
+        if value.is_a?(Hash) || value.is_a?(Array)
+          deep_copy(value)
+        elsif value.respond_to?(:to_h)
+          deep_copy(value.to_h)
+        else
+          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
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each do |key, item|
+            deep_freeze(key)
+            deep_freeze(item)
+          end
+        when Array
+          value.each { |item| deep_freeze(item) }
+        end
+
+        value.freeze
+      end
+
+      class << self
+        private
+
+        def deep_symbolize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, item), result|
+              result[key.to_sym] = deep_symbolize(item)
+            end
+          when Array
+            value.map { |item| deep_symbolize(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/persona/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Persona
+    # A compiled persona. Holds the system prompt as a Content object with
+    # trust: :system. Frozen after compilation — cannot be modified at runtime.
+    class Base
+      attr_reader :name, :content, :injection_config
+
+      def initialize(name:, system_prompt:, injection_config: {})
+        @name = name.to_sym
+        @content = Security::Gates::SystemPrompt.wrap(
+          system_prompt,
+          persona: name.to_s
+        )
+        @injection_config = injection_config.freeze
+        freeze
+      end
+
+      # Returns the system prompt as a Content object.
+      def render
+        content
+      end
+
+      def system_prompt_text
+        content.text
+      end
+
+      def inject_date?
+        injection_config.fetch(:inject_date, false)
+      end
+
+      def inject_user_context?
+        injection_config.fetch(:inject_user_context, false)
+      end
+
+      def inject_agent_context?
+        injection_config.fetch(:inject_agent_context, false)
+      end
+    end
+  end
+end

data/lib/spurline/persona/registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Persona
+    # Per-class storage of compiled personas. Supports multiple personas
+    # per agent class, selectable at instantiation time.
+    class Registry
+      def initialize
+        @personas = {}
+      end
+
+      def register(name, persona)
+        @personas[name.to_sym] = persona
+      end
+
+      def fetch(name)
+        name = name.to_sym
+        @personas.fetch(name) do
+          raise Spurline::ConfigurationError,
+            "Persona '#{name}' is not defined. Available personas: " \
+            "#{@personas.keys.map(&:inspect).join(", ")}."
+        end
+      end
+
+      def default
+        fetch(:default)
+      rescue Spurline::ConfigurationError
+        nil
+      end
+
+      def names
+        @personas.keys
+      end
+
+      def dup_registry
+        new_registry = self.class.new
+        @personas.each { |name, persona| new_registry.register(name, persona) }
+        new_registry
+      end
+    end
+  end
+end

data/lib/spurline/secrets/resolver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Secrets
+    class Resolver
+      def initialize(vault: nil, overrides: {})
+        @vault = vault
+        @overrides = overrides || {}
+      end
+
+      # Returns resolved value or nil.
+      def resolve(secret_name)
+        name = secret_name.to_sym
+
+        if @overrides.key?(name)
+          return resolve_override(@overrides[name])
+        end
+
+        if @vault&.key?(name)
+          return @vault.fetch(name)
+        end
+
+        cred_value = Spurline.credentials[name.to_s]
+        return cred_value if present?(cred_value)
+
+        env_value = ENV[name.to_s.upcase]
+        return env_value if present?(env_value)
+
+        nil
+      end
+
+      # Returns resolved value or raises SecretNotFoundError.
+      def resolve!(secret_name)
+        value = resolve(secret_name)
+        return value unless value.nil?
+
+        raise Spurline::SecretNotFoundError,
+          "Secret '#{secret_name}' is required but could not be resolved. " \
+          "Provide it via: agent.vault.store(:#{secret_name}, '...'), " \
+          "Spurline.credentials['#{secret_name}'] (spur credentials:edit), " \
+          "or ENV['#{secret_name.to_s.upcase}']."
+      end
+
+      private
+
+      def resolve_override(override)
+        case override
+        when Proc, Method
+          override.call
+        when Symbol, String
+          Spurline.credentials[override.to_s]
+        else
+          override
+        end
+      end
+
+      def present?(value)
+        return false if value.nil?
+        return !value.strip.empty? if value.respond_to?(:strip)
+
+        true
+      end
+    end
+  end
+end

data/lib/spurline/secrets/vault.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Secrets
+    class Vault
+      def initialize
+        @store = {}
+        @mutex = Mutex.new
+      end
+
+      def store(key, value)
+        @mutex.synchronize { @store[key.to_sym] = value }
+      end
+      alias []= store
+
+      def fetch(key, default = nil)
+        @mutex.synchronize { @store.fetch(key.to_sym, default) }
+      end
+      alias [] fetch
+
+      def key?(key)
+        @mutex.synchronize { @store.key?(key.to_sym) }
+      end
+
+      def delete(key)
+        @mutex.synchronize { @store.delete(key.to_sym) }
+      end
+
+      def clear!
+        @mutex.synchronize { @store.clear }
+      end
+
+      def keys
+        @mutex.synchronize { @store.keys }
+      end
+
+      def empty?
+        @mutex.synchronize { @store.empty? }
+      end
+    end
+  end
+end