rosett-ai 1.3.3

data/lib/rosett_ai/ai_config/cost_controls.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module AiConfig
+    # Advisory cost tier preferences for AI tool usage.
+    #
+    # Cost controls are purely advisory — rosett-ai is a compiler, not a runtime.
+    # These preferences guide model selection and are compiled into
+    # engine-specific configuration hints.
+    class CostControls
+      TIERS = ['economy', 'standard', 'premium'].freeze
+
+      attr_reader :preferred_tier, :monthly_budget_note
+
+      # @param preferred_tier [String] one of {TIERS}
+      # @param monthly_budget_note [String, nil] advisory budget note
+      def initialize(preferred_tier: 'standard', monthly_budget_note: nil)
+        validate_tier!(preferred_tier)
+
+        @preferred_tier = preferred_tier.freeze
+        @monthly_budget_note = monthly_budget_note&.freeze
+      end
+
+      # @return [Hash] serializable representation
+      def to_h
+        hash = { 'preferred_tier' => @preferred_tier }
+        hash['monthly_budget_note'] = @monthly_budget_note if @monthly_budget_note
+        hash
+      end
+
+      private
+
+      def validate_tier!(tier)
+        return if TIERS.include?(tier)
+
+        raise ArgumentError,
+              "Invalid cost tier '#{tier}'. Allowed: #{TIERS.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rosett_ai/ai_config/fallback_chain.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module AiConfig
+    # Ordered engine fallback chain with local-to-remote transition warnings.
+    #
+    # When the primary engine is unavailable, the chain specifies fallback
+    # engines in order. Warns when a fallback would switch from local to
+    # remote (network requirement change).
+    class FallbackChain
+      LOCAL_ENGINES = ['ollama', 'gpt_neox'].freeze
+
+      attr_reader :engines, :warnings
+
+      # @param engines [Array<String>] ordered engine identifiers
+      def initialize(engines: [])
+        @engines = engines.freeze
+        @warnings = detect_transition_warnings.freeze
+      end
+
+      # @return [String, nil] primary engine (first in chain)
+      def primary
+        @engines.first
+      end
+
+      # @return [Array<String>] fallback engines (all after primary)
+      def fallbacks
+        @engines.drop(1)
+      end
+
+      # @return [Boolean] true if chain contains local-to-remote transitions
+      def local_to_remote_transition?
+        !@warnings.empty?
+      end
+
+      # @return [Hash] serializable representation
+      def to_h
+        {
+          'engines' => @engines.dup,
+          'warnings' => @warnings.dup
+        }
+      end
+
+      private
+
+      def detect_transition_warnings
+        warnings = []
+        @engines.each_cons(2) do |current, fallback|
+          next unless local_engine?(current) && !local_engine?(fallback)
+
+          warnings << "Fallback from local (#{current}) to remote (#{fallback}) — network required"
+        end
+        warnings
+      end
+
+      def local_engine?(engine)
+        LOCAL_ENGINES.include?(engine)
+      end
+    end
+  end
+end

data/lib/rosett_ai/ai_config/model_router.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module AiConfig
+    # Maps canonical model tiers to engine-specific model identifiers.
+    #
+    # Supports three standard tiers (economy, standard, premium) plus
+    # custom model names. Engine manifests declare their model mappings.
+    # Use {.with_manifest_mappings} to load mappings from installed engines.
+    #
+    # @author hugo
+    # @author claude
+    class ModelRouter
+      CANONICAL_TIERS = ['economy', 'standard', 'premium'].freeze
+
+      # Default model mappings per engine (used when engine manifest unavailable).
+      DEFAULT_MAPPINGS = {
+        'claude' => {
+          'economy' => 'claude-haiku-4-5-20251001',
+          'standard' => 'claude-sonnet-4-5-20250929',
+          'premium' => 'claude-opus-4-6'
+        },
+        'ollama' => {
+          'economy' => 'llama3.2:3b',
+          'standard' => 'llama3.3:8b',
+          'premium' => 'llama3.3:70b'
+        }
+      }.freeze
+
+      # Builds a ModelRouter that merges manifest-declared model
+      # mappings from installed engines with DEFAULT_MAPPINGS.
+      #
+      # @param extra_mappings [Hash] additional overrides on top of manifest data
+      # @return [ModelRouter]
+      def self.with_manifest_mappings(extra_mappings: {})
+        manifest_mappings = load_manifest_mappings
+        new(custom_mappings: manifest_mappings.merge(extra_mappings))
+      end
+
+      # @param custom_mappings [Hash] additional engine model mappings
+      def initialize(custom_mappings: {})
+        @mappings = DEFAULT_MAPPINGS.merge(custom_mappings)
+      end
+
+      # Resolves a canonical tier to an engine-specific model ID.
+      #
+      # @param tier [String] canonical tier name or "custom:<name>"
+      # @param engine [String] engine identifier
+      # @return [String] resolved model identifier
+      # @raise [RosettAi::AiConfigError] if tier is not recognised
+      def resolve(tier, engine:)
+        return extract_custom_model(tier) if tier.start_with?('custom:')
+
+        validate_tier!(tier)
+        engine_map = @mappings.fetch(engine, {})
+        engine_map.fetch(tier) do
+          raise RosettAi::AiConfigError,
+                "No model mapping for tier '#{tier}' on engine '#{engine}'"
+        end
+      end
+
+      # Lists all available tiers for an engine.
+      #
+      # @param engine [String] engine identifier
+      # @return [Array<String>] available tier names
+      def available_tiers(engine)
+        engine_map = @mappings.fetch(engine, {})
+        engine_map.keys
+      end
+
+      # @param engine [String] engine identifier
+      # @return [Boolean] true if engine has model mappings
+      def engine_supported?(engine)
+        @mappings.key?(engine)
+      end
+
+      # Resolves a canonical tier across all known engines.
+      #
+      # @param tier [String] canonical tier name
+      # @return [Hash<String, String>] engine name => resolved model ID
+      def resolve_all(tier)
+        validate_tier!(tier)
+        @mappings.each_with_object({}) do |(engine, map), result|
+          result[engine] = map[tier] if map.key?(tier)
+        end
+      end
+
+      private
+
+      def validate_tier!(tier)
+        return if CANONICAL_TIERS.include?(tier)
+
+        raise RosettAi::AiConfigError,
+              "Invalid model tier '#{tier}'. Allowed: #{CANONICAL_TIERS.join(', ')}, or custom:<name>"
+      end
+
+      def extract_custom_model(tier)
+        tier.delete_prefix('custom:')
+      end
+
+      class << self
+        private
+
+        def load_manifest_mappings
+          mappings = {}
+          RosettAi::Engines::Registry.available.each do |engine_name|
+            manifest = RosettAi::Engines::Registry.manifest(engine_name)
+            routing = manifest['model_routing']
+            mappings[engine_name] = routing if routing.is_a?(Hash)
+          rescue RosettAi::Error
+            next
+          end
+          mappings
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/ai_config/validator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json'
+require 'json_schemer'
+
+module RosettAi
+  module AiConfig
+    # Validates AI tool configuration files against the JSON Schema.
+    class Validator
+      SCHEMA_PATH = File.join(RosettAi.root, 'conf', 'schemas', 'ai_config_schema.json')
+
+      # Validates AI config data against the schema.
+      #
+      # @param data [Hash] parsed ai_config.yml data
+      # @return [Array<String>] list of validation errors (empty if valid)
+      def validate(data)
+        schema = load_schema
+        schemer = JSONSchemer.schema(schema)
+        errors = schemer.validate(data)
+        errors.map { |error| format_error(error) }
+      end
+
+      # @param data [Hash] AI config data
+      # @return [Boolean] true if data is valid
+      def valid?(data)
+        validate(data).empty?
+      end
+
+      private
+
+      def load_schema
+        JSON.parse(File.read(SCHEMA_PATH))
+      end
+
+      def format_error(error)
+        path = error['data_pointer']
+        message = error['type']
+        "#{path}: #{message}"
+      end
+    end
+  end
+end

data/lib/rosett_ai/authorship/attribution_compiler.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Authorship
+    # Compiles authorship attribution sections for engine output.
+    #
+    # Generates markdown sections for CLAUDE.md, AGENTS.md, and other
+    # engine-specific output based on the active disclosure level.
+    # Ensures compiled metadata never exceeds what the disclosure level
+    # permits — per-file details are stripped at any level below full.
+    #
+    # @author hugo
+    # @author claude
+    class AttributionCompiler
+      FILES_KEYS = ['files', :files].freeze
+
+      # @param disclosure_policy [DisclosurePolicy] active disclosure policy
+      def initialize(disclosure_policy:)
+        @policy = disclosure_policy
+      end
+
+      # Compiles an attribution section for inclusion in engine output.
+      #
+      # @param engine_name [String] active engine display name
+      # @param provider [String] engine provider
+      # @param provenance_entries [Array<Hash>] recent provenance entries
+      # @return [Hash] with +:section+ (String, nil) and +:warnings+ (Array<String>)
+      def compile(engine_name:, provider:, provenance_entries: [])
+        warnings = []
+        return { section: nil, warnings: warnings } unless @policy.disclose?
+
+        safe_entries = sanitize_entries(provenance_entries)
+        section = build_section(engine_name, provider, safe_entries, warnings)
+        { section: section, warnings: warnings }
+      end
+
+      private
+
+      # Strips per-file data from entries when disclosure level does not
+      # permit it, preventing metadata leakage.
+      def sanitize_entries(entries)
+        return entries if @policy.include_per_file?
+
+        entries.map { |e| e.reject { |k| FILES_KEYS.include?(k) } }
+      end
+
+      def build_section(engine_name, provider, entries, warnings)
+        lines = []
+
+        if @policy.include_attribution?
+          lines << '## AI Attribution'
+          lines << ''
+          lines << "This project uses AI-assisted development via #{engine_name} (#{provider})."
+          lines << 'The human operator is always the accountable author.'
+          lines << 'AI tools are not listed as copyright holders.'
+        elsif @policy.include_trailer_guidance?
+          lines << "<!-- AI-assisted development via #{engine_name} (#{provider}) -->"
+        end
+
+        append_trailer_guidance(lines) if @policy.include_trailer_guidance?
+        append_per_file_summary(lines, entries, warnings) if @policy.include_per_file?
+
+        lines.join("\n")
+      end
+
+      def append_trailer_guidance(lines)
+        lines << ''
+        lines << '### Commit Trailers'
+        lines << ''
+        lines << 'Use standardised commit trailers to attribute AI involvement:'
+        lines << ''
+        lines << '- `AI-Generated-By`: code primarily generated by AI'
+        lines << '- `AI-Co-Author`: code co-authored with AI'
+        lines << '- `AI-Assisted-By`: AI used for suggestions or review'
+        lines << '- `AI-Reviewed-By`: AI reviewed human-written code'
+      end
+
+      def append_per_file_summary(lines, entries, _warnings)
+        return if entries.empty?
+
+        lines << ''
+        lines << '### Per-File AI Involvement'
+        lines << ''
+
+        entries.each do |entry|
+          role = entry['ai_role'] || entry[:ai_role]
+          files = entry['files'] || entry[:files] || []
+          files.each do |file|
+            path = file['path'] || file[:path]
+            lines << "- `#{path}`: #{role}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/authorship/disclosure_policy.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Authorship
+    # Manages disclosure levels for AI authorship attribution.
+    #
+    # Four levels control how much AI involvement metadata appears in
+    # compiled output and commit messages:
+    #
+    # - +none+: no authorship metadata emitted
+    # - +minimal+: brief note that AI tools were used
+    # - +standard+: AI Attribution section in compiled output
+    # - +full+: per-file AI involvement summary
+    #
+    # Disclosure level is read from +.rosett-ai/config.yml+ under
+    # +authorship.disclosure+, not from behaviour YAML.
+    #
+    # @author hugo
+    # @author claude
+    class DisclosurePolicy
+      LEVELS = ['none', 'minimal', 'standard', 'full'].freeze
+      DEFAULT_LEVEL = 'standard'
+
+      attr_reader :level
+
+      # @param level [String] one of {LEVELS}
+      # @raise [ArgumentError] if level is not valid
+      def initialize(level: DEFAULT_LEVEL)
+        validate_level!(level)
+        @level = level.freeze
+      end
+
+      # Loads the disclosure level from a config data hash.
+      #
+      # @param data [Hash] configuration hash (e.g. from YAML config file)
+      # @return [DisclosurePolicy] policy with configured level
+      def self.from_config(data)
+        level = data.dig('authorship', 'disclosure') || DEFAULT_LEVEL
+        new(level: level)
+      rescue ArgumentError
+        new(level: DEFAULT_LEVEL)
+      end
+
+      # @return [Boolean] true if any metadata should be emitted
+      def disclose?
+        @level != 'none'
+      end
+
+      # @return [Boolean] true if compiled output should include attribution section
+      def include_attribution?
+        at_least?('standard')
+      end
+
+      # @return [Boolean] true if per-file AI involvement should be included
+      def include_per_file?
+        at_least?('full')
+      end
+
+      # @return [Boolean] true if trailer guidance should be in compiled output
+      def include_trailer_guidance?
+        at_least?('minimal')
+      end
+
+      private
+
+      def at_least?(minimum)
+        LEVELS.index(@level) >= LEVELS.index(minimum)
+      end
+
+      def validate_level!(level)
+        return if LEVELS.include?(level)
+
+        raise ArgumentError,
+              "Invalid disclosure level '#{level}'. Allowed: #{LEVELS.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rosett_ai/authorship/review_validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Authorship
+    # Validates that Human-Reviewed-By differs from the commit author.
+    #
+    # Self-review (where the submitter is also the reviewer) does not
+    # satisfy the review requirement. At advisory level this produces
+    # a warning; at strict level it produces an error.
+    class ReviewValidator
+      # Result of a review validation check.
+      #
+      # @return [Hash] with +:valid+ (Boolean) and +:message+ (String, nil)
+      def validate(author:, reviewer:)
+        return success if author.nil? || reviewer.nil?
+        return success unless normalize(author) == normalize(reviewer)
+
+        failure('Human-Reviewed-By must differ from the commit author (self-review detected)')
+      end
+
+      private
+
+      def normalize(identity)
+        identity.to_s.strip.downcase
+      end
+
+      def success
+        { valid: true, message: nil }
+      end
+
+      def failure(message)
+        { valid: false, message: message }
+      end
+    end
+  end
+end

data/lib/rosett_ai/authorship/trailer_generator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Authorship
+    # Generates commit trailer templates for AI authorship.
+    #
+    # Trailer format follows the convention:
+    #   Role: Tool Version (Provider) <email>
+    #
+    # Engine capability manifests declare whether trailer support is
+    # available; engines without trailer support get a warning.
+    #
+    # @author hugo
+    # @author claude
+    class TrailerGenerator
+      TRAILER_ROLES = RosettAi::Provenance::Entry::ALLOWED_ROLES
+
+      # Generates a trailer string for a given engine.
+      #
+      # @param engine_name [String] engine display name (e.g. "Claude Opus 4.6")
+      # @param provider [String] engine provider (e.g. "Anthropic")
+      # @param role [String] one of {TRAILER_ROLES}
+      # @return [String] formatted trailer
+      def generate(engine_name:, provider:, role:)
+        validate_role!(role)
+        "#{role}: #{engine_name} (#{provider})"
+      end
+
+      # Generates all four trailer templates for an engine.
+      #
+      # @param engine_name [String] engine display name
+      # @param provider [String] engine provider
+      # @return [Array<String>] all trailer templates
+      def generate_all(engine_name:, provider:)
+        TRAILER_ROLES.map do |role|
+          generate(engine_name: engine_name, provider: provider, role: role)
+        end
+      end
+
+      # Formats trailers as a block suitable for documentation.
+      #
+      # @param engine_name [String] engine display name
+      # @param provider [String] engine provider
+      # @return [String] newline-separated trailer block
+      def trailer_block(engine_name:, provider:)
+        generate_all(engine_name: engine_name, provider: provider).join("\n")
+      end
+
+      # Validates a tool name against known engine manifests.
+      #
+      # @param tool_name [String] tool name from a trailer (e.g. "Claude Opus 4.6")
+      # @param strict [Boolean] when true, unknown tools raise AuthorshipError
+      # @return [Array<String>] warnings (empty if tool is known)
+      def validate_tool(tool_name:, strict: false)
+        known = known_engine_names
+        return [] if known.empty? # no engines installed — skip validation
+        return [] if known.any? { |name| tool_name.include?(name) }
+
+        message = "Unknown AI tool '#{tool_name}' — not found in any engine manifest. " \
+                  "Known engines: #{known.join(', ')}"
+        raise RosettAi::AuthorshipError, message if strict
+
+        [message]
+      end
+
+      private
+
+      def validate_role!(role)
+        return if TRAILER_ROLES.include?(role)
+
+        raise ArgumentError,
+              "Invalid trailer role '#{role}'. Allowed: #{TRAILER_ROLES.join(', ')}"
+      end
+
+      def known_engine_names
+        RosettAi::Engines::Registry.available.filter_map do |engine_name|
+          manifest = RosettAi::Engines::Registry.manifest(engine_name)
+          manifest['display_name']
+        rescue RosettAi::Error
+          nil
+        end
+      end
+    end
+  end
+end