kairos-chain 2.0.5 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7256c06e2fd204672e04f33e2b88bed3f302188b6d97cb5fe736e142b84580bd
-  data.tar.gz: c95abbd55c084474595a81e257eee4a5ad08168b47c2d069669dfe8ca49c7ed7
+  metadata.gz: bb6f9b51791860a4898475d255ec105e4de84ac49cdbb8efb22297fff9db3337
+  data.tar.gz: 9c13b5e3743eeb39d84fa037f84027a0be9865d75ba5851123fe57fdd21133f6
 SHA512:
-  metadata.gz: 9552b83a0ebb90e312837ddad5b0086d620be6c92a2e83fdb93d0cec6eb043dcc6b6f37254e52cb2dc9d6e276d7154a9256360487e45c0cf41c25597bd202e4c
-  data.tar.gz: 40636983d68a243b1ba7d7907c59550f6ec15e35ba234f6cd975a6b539f6a416b4da973388310e3bd877cc32ffe25e196ae223aeb736a027330b4a8325eab13a
+  metadata.gz: 955cca06fa60a00c344412a98e73dd47c9164a122fcb185c72c27a9bcc948691477835b69ba51974a5e4702451b7264c61f6627d5791fb3657ecdb817a29af0d
+  data.tar.gz: 105ac2714d16387a47392a20e9fb707034702829abb071cd03f0be4bcf42896bec655ecede56236b4965ddc0ddb140227bcea137a3ca140bddcb2cee7ac0e582

data/CHANGELOG.md

@@ -4,12 +4,38 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
-## [2.0.5] - 2026-02-25
+## [2.1.0] - 2026-02-25
+
+### Added
+
+- **Phase 1: DSL/AST Partial Formalization Layer**
+  - `AstNode` Struct and `DefinitionContext` with 5 node types (Constraint, SemanticReasoning, Plan, ToolCall, Check)
+  - `Skill` Struct extended with `:definition` and `:formalization_notes` fields
+  - `FormalizationDecision` class for on-chain provenance records
+  - `formalization_record` MCP tool: record formalization decisions to blockchain
+  - `formalization_history` MCP tool: query accumulated formalization decisions
+  - `skills_dsl_get` enhanced with Definition (Structural Layer) and Formalization Notes (Provenance Layer) sections
+  - `core_safety` and `evolution_rules` L0 skills annotated with definition blocks
+  - 68 tests (test_dsl_ast_phase1.rb)
+
+- **Phase 2: AST Verification Engine, Decompiler, and Drift Detection**
+  - `AstEngine`: Pattern-matched structural verification (no eval) with condition evaluation (==, <, >=, .method?(), not in)
+  - `Decompiler`: AST to human-readable Markdown reconstruction
+  - `DriftDetector`: Content/definition layer divergence detection with coverage_ratio and keyword matching (no LLM)
+  - `definition_verify` MCP tool: structural constraint verification report
+  - `definition_decompile` MCP tool: reverse AST to human-readable form
+  - `definition_drift` MCP tool: detect content/definition layer misalignment
+  - `skills_dsl_get` enhanced with Verification Status section (with fallback)
+  - Security: method call whitelist for condition evaluation, type-safe numeric comparisons
+  - 91 tests (test_dsl_ast_phase2.rb), full backward compatibility with Phase 1
+
+- **DSL/AST Source of Truth Policy**: Ruby DSL (.rb) is authoritative; JSON representations are derived outputs
+
+- **Upgrade notification at MCP session start**: `Protocol#handle_initialize` checks gem vs. data version via `UpgradeAnalyzer` and returns a `notifications` entry when an upgrade is available, so LLM clients are informed at session start without disrupting normal operation
 
 ### Fixed
 
-- **Deadlock**: `PendingChanges#summary` caused `deadlock; recursive locking` by calling `includes_l0_change?`, `includes_promotion?`, `includes_demotion?` from within a `@mutex.synchronize` block. Separated lock acquisition (public API) from logic (private `_`-prefixed methods).
-- **Atomicity**: `check_trigger_conditions` now executes within a single lock, preventing race conditions between individual predicate checks.
+- **Deadlock in PendingChanges#summary**: Recursive locking when summary calls constraint check methods within already-held @mutex synchronize block. Separated lock acquisition (public API) from logic (private methods). Made check_trigger_conditions atomic.
 
 ---
 

data/lib/kairos_mcp/dsl_ast/ast_engine.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require_relative '../skill_contexts'
+
+module KairosMcp
+  module DslAst
+    # Result of evaluating a single AST node
+    NodeResult = Struct.new(:node_name, :node_type, :satisfied, :detail, :evaluable, keyword_init: true)
+
+    # Result of verifying all definition nodes for a skill
+    VerificationReport = Struct.new(:skill_id, :results, :timestamp, keyword_init: true) do
+      # All deterministic (evaluable) nodes passed?
+      def all_deterministic_passed?
+        results.select(&:evaluable).all? { |r| r.satisfied == true }
+      end
+
+      # Nodes that require human judgment
+      def human_required
+        results.reject(&:evaluable)
+      end
+
+      # Summary counts
+      def summary
+        total = results.size
+        passed = results.count { |r| r.evaluable && r.satisfied == true }
+        failed = results.count { |r| r.evaluable && r.satisfied == false }
+        unknown = results.count { |r| r.evaluable && r.satisfied == :unknown }
+        non_evaluable = results.count { |r| !r.evaluable }
+        { total: total, passed: passed, failed: failed, unknown: unknown, human_required: non_evaluable }
+      end
+    end
+
+    # AST node evaluation engine
+    # Verifies definition nodes against a binding context without using eval.
+    # Design: verification-only — does not replace behavior block execution.
+    # NOTE: The engine itself is infrastructure in Phase 2.
+    # Policy aspects (drift thresholds, etc.) may become a SkillSet in Phase 3.
+    class AstEngine
+      # Allowed methods for condition evaluation via send().
+      # Only query methods (no side effects) are permitted.
+      ALLOWED_METHODS = %i[
+        can_evolve? has_tool? include? key? empty? nil?
+        is_a? respond_to? size length count
+      ].freeze
+
+      # Verify all definition nodes for a skill
+      # @param skill [KairosMcp::SkillsDsl::Skill] the skill to verify
+      # @param binding_context [Hash] runtime values for condition evaluation
+      # @return [VerificationReport]
+      def self.verify(skill, binding_context: {})
+        return nil unless skill.definition
+
+        results = skill.definition.nodes.map do |node|
+          evaluate_node(node, binding_context: binding_context)
+        end
+
+        VerificationReport.new(
+          skill_id: skill.id,
+          results: results,
+          timestamp: Time.now.iso8601
+        )
+      end
+
+      # Evaluate a single AST node
+      # @param node [KairosMcp::AstNode] the node to evaluate
+      # @param binding_context [Hash] runtime values for condition evaluation
+      # @return [NodeResult]
+      def self.evaluate_node(node, binding_context: {})
+        case node.type
+        when :Constraint
+          evaluate_constraint(node, binding_context)
+        when :Check
+          evaluate_check(node, binding_context)
+        when :Plan
+          evaluate_plan(node)
+        when :ToolCall
+          evaluate_tool_call(node)
+        when :SemanticReasoning
+          evaluate_semantic_reasoning(node)
+        else
+          NodeResult.new(
+            node_name: node.name,
+            node_type: node.type,
+            satisfied: :unknown,
+            detail: "Unknown node type: #{node.type}",
+            evaluable: false
+          )
+        end
+      end
+
+      private
+
+      # Evaluate Constraint node via pattern matching (no eval)
+      def self.evaluate_constraint(node, binding_context)
+        opts = node.options || {}
+        condition = opts[:condition]
+
+        if condition.nil?
+          # No condition string — check if required key exists in context
+          if opts[:required] == true
+            # Constraint is a declaration; structurally valid
+            return NodeResult.new(
+              node_name: node.name,
+              node_type: :Constraint,
+              satisfied: true,
+              detail: "Required constraint declared (structural)",
+              evaluable: true
+            )
+          end
+
+          return NodeResult.new(
+            node_name: node.name,
+            node_type: :Constraint,
+            satisfied: true,
+            detail: "Constraint declared (no condition to evaluate)",
+            evaluable: true
+          )
+        end
+
+        # Pattern match the condition string
+        result = match_condition(condition, binding_context)
+        NodeResult.new(
+          node_name: node.name,
+          node_type: :Constraint,
+          satisfied: result[:satisfied],
+          detail: result[:detail],
+          evaluable: result[:evaluable]
+        )
+      end
+
+      # Evaluate Check node
+      def self.evaluate_check(node, binding_context)
+        opts = node.options || {}
+        condition = opts[:condition]
+
+        unless condition
+          return NodeResult.new(
+            node_name: node.name,
+            node_type: :Check,
+            satisfied: :unknown,
+            detail: "No condition specified",
+            evaluable: false
+          )
+        end
+
+        result = match_condition(condition, binding_context)
+        NodeResult.new(
+          node_name: node.name,
+          node_type: :Check,
+          satisfied: result[:satisfied],
+          detail: result[:detail],
+          evaluable: result[:evaluable]
+        )
+      end
+
+      # Evaluate Plan node — structural validity (steps exist and are named)
+      def self.evaluate_plan(node)
+        opts = node.options || {}
+        steps = opts[:steps]
+
+        unless steps.is_a?(Array) && !steps.empty?
+          return NodeResult.new(
+            node_name: node.name,
+            node_type: :Plan,
+            satisfied: false,
+            detail: "Plan has no steps defined",
+            evaluable: true
+          )
+        end
+
+        NodeResult.new(
+          node_name: node.name,
+          node_type: :Plan,
+          satisfied: true,
+          detail: "Plan has #{steps.size} steps: #{steps.map(&:to_s).join(' -> ')}",
+          evaluable: true
+        )
+      end
+
+      # Evaluate ToolCall node — command recognition (does not execute)
+      def self.evaluate_tool_call(node)
+        opts = node.options || {}
+        command = opts[:command]
+
+        unless command && !command.to_s.strip.empty?
+          return NodeResult.new(
+            node_name: node.name,
+            node_type: :ToolCall,
+            satisfied: false,
+            detail: "No command specified",
+            evaluable: true
+          )
+        end
+
+        NodeResult.new(
+          node_name: node.name,
+          node_type: :ToolCall,
+          satisfied: true,
+          detail: "Command recognized: #{command}",
+          evaluable: true
+        )
+      end
+
+      # SemanticReasoning — explicitly non-evaluable (requires human judgment)
+      def self.evaluate_semantic_reasoning(node)
+        opts = node.options || {}
+        prompt = opts[:prompt] || "(no prompt)"
+
+        NodeResult.new(
+          node_name: node.name,
+          node_type: :SemanticReasoning,
+          satisfied: :unknown,
+          detail: "Requires human judgment: #{prompt}",
+          evaluable: false
+        )
+      end
+
+      # Pattern-match a condition string against binding_context
+      # Supported patterns:
+      #   "X == true/false" — boolean comparison
+      #   "X == VALUE" — equality comparison
+      #   "X < Y" / "X > Y" / "X >= Y" / "X <= Y" — numeric comparison
+      #   "X.method?(arg)" — method call on context object
+      #   "X not in Y" — exclusion check
+      # Unsupported patterns return evaluable: false
+      def self.match_condition(condition, binding_context)
+        # Pattern: "X == true" or "X == false"
+        if condition =~ /\A(\w+)\s*==\s*(true|false)\z/
+          var_name = $1.to_sym
+          expected = $2 == 'true'
+          if binding_context.key?(var_name)
+            actual = binding_context[var_name]
+            return {
+              satisfied: actual == expected,
+              detail: "#{var_name}: expected #{expected}, got #{actual}",
+              evaluable: true
+            }
+          else
+            return {
+              satisfied: :unknown,
+              detail: "Variable '#{var_name}' not in binding context",
+              evaluable: false
+            }
+          end
+        end
+
+        # Pattern: "X < Y" or "X > Y" or "X >= Y" or "X <= Y"
+        if condition =~ /\A(\w+)\s*(<|>|<=|>=)\s*(\w+)\z/
+          left_name = $1.to_sym
+          op = $2
+          right_name = $3.to_sym
+
+          left_val = binding_context.key?(left_name) ? binding_context[left_name] : nil
+          right_val = binding_context.key?(right_name) ? binding_context[right_name] : nil
+
+          if left_val.nil? || right_val.nil?
+            missing = []
+            missing << left_name unless binding_context.key?(left_name)
+            missing << right_name unless binding_context.key?(right_name)
+            return {
+              satisfied: :unknown,
+              detail: "Missing variables: #{missing.join(', ')}",
+              evaluable: false
+            }
+          end
+
+          begin
+            result = case op
+                     when '<'  then left_val < right_val
+                     when '>'  then left_val > right_val
+                     when '<=' then left_val <= right_val
+                     when '>=' then left_val >= right_val
+                     end
+
+            return {
+              satisfied: result,
+              detail: "#{left_name}(#{left_val}) #{op} #{right_name}(#{right_val}) = #{result}",
+              evaluable: true
+            }
+          rescue TypeError, ArgumentError => e
+            return {
+              satisfied: :unknown,
+              detail: "Type error in comparison: #{e.message}",
+              evaluable: false
+            }
+          end
+        end
+
+        # Pattern: "X.method?(arg)"
+        if condition =~ /\A(\w+)\.(\w+\??)\(([^)]*)\)\z/
+          obj_name = $1.to_sym
+          method_name = $2.to_sym
+          arg_str = $3.strip
+
+          if binding_context.key?(obj_name)
+            obj = binding_context[obj_name]
+            if obj.respond_to?(method_name)
+              # Security: only allow whitelisted query methods (no side effects)
+              unless ALLOWED_METHODS.include?(method_name)
+                return {
+                  satisfied: :unknown,
+                  detail: "Method '#{method_name}' not in allowed list",
+                  evaluable: false
+                }
+              end
+              # Parse argument: try symbol, then string
+              arg = arg_str.start_with?(':') ? arg_str[1..-1].to_sym : arg_str
+              begin
+                result = obj.send(method_name, arg)
+                return {
+                  satisfied: !!result,
+                  detail: "#{obj_name}.#{method_name}(#{arg_str}) = #{result}",
+                  evaluable: true
+                }
+              rescue StandardError => e
+                return {
+                  satisfied: :unknown,
+                  detail: "Error calling #{method_name}: #{e.message}",
+                  evaluable: false
+                }
+              end
+            end
+          end
+
+          return {
+            satisfied: :unknown,
+            detail: "Cannot evaluate: #{condition}",
+            evaluable: false
+          }
+        end
+
+        # Pattern: "X not in Y"
+        if condition =~ /\A(\w+)\s+not\s+in\s+(\w+)\z/
+          item_name = $1.to_sym
+          collection_name = $2.to_sym
+
+          if binding_context.key?(item_name) && binding_context.key?(collection_name)
+            item = binding_context[item_name]
+            collection = binding_context[collection_name]
+            if collection.respond_to?(:include?)
+              result = !collection.include?(item)
+              return {
+                satisfied: result,
+                detail: "#{item_name} not in #{collection_name}: #{result}",
+                evaluable: true
+              }
+            end
+          end
+
+          return {
+            satisfied: :unknown,
+            detail: "Cannot evaluate exclusion: #{condition}",
+            evaluable: false
+          }
+        end
+
+        # Unrecognized pattern
+        {
+          satisfied: :unknown,
+          detail: "Unrecognized condition pattern: #{condition}",
+          evaluable: false
+        }
+      end
+    end
+  end
+end

data/lib/kairos_mcp/dsl_ast/decompiler.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative '../skill_contexts'
+
+module KairosMcp
+  module DslAst
+    # AST -> Natural language reverse conversion
+    # Template-based decompilation of definition nodes to human-readable Markdown.
+    # Used for: drift detection comparison, formalization_record decompile_text field.
+    class Decompiler
+      # Decompile a full definition to Markdown
+      # @param definition [KairosMcp::DefinitionContext] the definition to decompile
+      # @return [String] Markdown representation
+      def self.decompile(definition)
+        return "" unless definition && definition.nodes && !definition.nodes.empty?
+
+        lines = ["## Definition (Decompiled)\n"]
+
+        definition.nodes.each do |node|
+          lines << decompile_node(node)
+        end
+
+        lines.join("\n")
+      end
+
+      # Decompile a single node to a Markdown line
+      # @param node [KairosMcp::AstNode] the node to decompile
+      # @return [String] Markdown representation
+      def self.decompile_node(node)
+        case node.type
+        when :Constraint
+          decompile_constraint(node)
+        when :Check
+          decompile_check(node)
+        when :Plan
+          decompile_plan(node)
+        when :ToolCall
+          decompile_tool_call(node)
+        when :SemanticReasoning
+          decompile_semantic_reasoning(node)
+        else
+          "- **Unknown** (`#{node.name}`): type=#{node.type}"
+        end
+      end
+
+      private
+
+      def self.decompile_constraint(node)
+        opts = node.options || {}
+        parts = ["- **Requirement** (`#{node.name}`)"]
+
+        if opts[:condition]
+          parts << ": #{opts[:condition]}"
+        end
+
+        qualifiers = []
+        qualifiers << "required" if opts[:required]
+        qualifiers << "timing: #{opts[:timing]}" if opts[:timing]
+        qualifiers << "scope: #{opts[:scope]}" if opts[:scope]
+        qualifiers << "target: #{opts[:target]}" if opts[:target]
+
+        parts << " [#{qualifiers.join(', ')}]" unless qualifiers.empty?
+
+        parts.join
+      end
+
+      def self.decompile_check(node)
+        opts = node.options || {}
+        line = "- **Check** (`#{node.name}`)"
+        line += ": #{opts[:condition]}" if opts[:condition]
+        line
+      end
+
+      def self.decompile_plan(node)
+        opts = node.options || {}
+        steps = opts[:steps] || []
+        step_str = steps.map(&:to_s).join(" -> ")
+        "- **Workflow** (`#{node.name}`): #{steps.size} steps — #{step_str}"
+      end
+
+      def self.decompile_tool_call(node)
+        opts = node.options || {}
+        line = "- **Tool Call** (`#{node.name}`)"
+        line += ": `#{opts[:command]}`" if opts[:command]
+        line
+      end
+
+      def self.decompile_semantic_reasoning(node)
+        opts = node.options || {}
+        prompt = opts[:prompt] || "(no prompt)"
+        "- **Human Judgment Required** (`#{node.name}`): #{prompt}"
+      end
+    end
+  end
+end

data/lib/kairos_mcp/dsl_ast/drift_detector.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative '../skill_contexts'
+
+module KairosMcp
+  module DslAst
+    # Drift item representing a single discrepancy between content and definition
+    DriftItem = Struct.new(:direction, :severity, :description, :node_name, keyword_init: true)
+
+    # Report of all detected drifts for a skill
+    DriftReport = Struct.new(:skill_id, :items, :coverage_ratio, :timestamp, keyword_init: true) do
+      def drifted?
+        !items.empty?
+      end
+
+      def errors
+        items.select { |i| i.severity == :error }
+      end
+
+      def warnings
+        items.select { |i| i.severity == :warning }
+      end
+
+      def infos
+        items.select { |i| i.severity == :info }
+      end
+
+      def summary
+        {
+          total: items.size,
+          errors: errors.size,
+          warnings: warnings.size,
+          info: infos.size,
+          coverage_ratio: coverage_ratio
+        }
+      end
+    end
+
+    # Deterministic content <-> definition drift detection
+    # No LLM usage — keyword matching and structural analysis only.
+    # NOTE: Drift thresholds and policies may become a SkillSet in Phase 3.
+    class DriftDetector
+      # Keywords that indicate structural assertions in natural language content
+      ASSERTION_KEYWORDS = %w[must required always never shall mandatory].freeze
+
+      # Detect drift between content and definition layers
+      # @param skill [KairosMcp::SkillsDsl::Skill] the skill to analyze
+      # @return [DriftReport]
+      def self.detect(skill)
+        items = []
+        content = skill.content || ""
+        definition = skill.definition
+        content_lower = content.downcase
+
+        # No definition => no drift analysis possible
+        unless definition && definition.nodes && !definition.nodes.empty?
+          return DriftReport.new(
+            skill_id: skill.id,
+            items: [],
+            coverage_ratio: nil,
+            timestamp: Time.now.iso8601
+          )
+        end
+
+        # Check 1: definition nodes reflected in content (definition_orphaned)
+        covered_count = 0
+        definition.nodes.each do |node|
+          if node_reflected_in_content?(node, content_lower)
+            covered_count += 1
+          else
+            items << DriftItem.new(
+              direction: :definition_orphaned,
+              severity: :warning,
+              description: "Definition node '#{node.name}' (#{node.type}) has no corresponding mention in content",
+              node_name: node.name
+            )
+          end
+        end
+
+        # Check 2: content assertions not covered by definition (content_uncovered)
+        uncovered = content_assertions_not_covered(content, definition)
+        uncovered.each do |assertion|
+          items << DriftItem.new(
+            direction: :content_uncovered,
+            severity: :info,
+            description: "Content assertion \"#{assertion}\" not covered by any definition node",
+            node_name: nil
+          )
+        end
+
+        # Coverage ratio: proportion of definition nodes reflected in content
+        total_nodes = definition.nodes.size
+        ratio = total_nodes > 0 ? covered_count.to_f / total_nodes : 1.0
+
+        DriftReport.new(
+          skill_id: skill.id,
+          items: items,
+          coverage_ratio: ratio.round(2),
+          timestamp: Time.now.iso8601
+        )
+      end
+
+      private
+
+      # Check if a definition node's name or key options appear in the content
+      def self.node_reflected_in_content?(node, content_lower)
+        # Convert node name from snake_case to words for matching
+        name_words = node.name.to_s.split('_')
+
+        # Check if any name word appears in content
+        name_match = name_words.any? { |word| content_lower.include?(word.downcase) }
+        return true if name_match
+
+        # Also check key option values
+        opts = node.options || {}
+        opts.each_value do |v|
+          next unless v.is_a?(String)
+          return true if content_lower.include?(v.downcase)
+        end
+
+        false
+      end
+
+      # Find content lines with assertion keywords not covered by any definition node
+      def self.content_assertions_not_covered(content, definition)
+        uncovered = []
+        node_keywords = collect_node_keywords(definition)
+
+        content.each_line do |line|
+          stripped = line.strip
+          next if stripped.empty?
+          next if stripped.start_with?('#', '|', '-') # Skip headers, tables, list markers that are structural
+
+          # Check if this line contains an assertion keyword
+          line_lower = stripped.downcase
+          has_assertion = ASSERTION_KEYWORDS.any? { |kw| line_lower.include?(kw) }
+          next unless has_assertion
+
+          # Check if any definition node keyword appears in this line
+          covered = node_keywords.any? { |kw| line_lower.include?(kw) }
+          unless covered
+            # Truncate long lines
+            display = stripped.length > 80 ? "#{stripped[0..77]}..." : stripped
+            uncovered << display
+          end
+        end
+
+        uncovered
+      end
+
+      # Collect searchable keywords from all definition nodes
+      def self.collect_node_keywords(definition)
+        keywords = []
+
+        definition.nodes.each do |node|
+          # Add name parts
+          node.name.to_s.split('_').each { |w| keywords << w.downcase }
+
+          # Add option values that are strings
+          (node.options || {}).each_value do |v|
+            case v
+            when String
+              v.split(/\s+/).each { |w| keywords << w.downcase if w.length > 3 }
+            when Symbol
+              keywords << v.to_s.downcase
+            end
+          end
+        end
+
+        keywords.uniq
+      end
+    end
+  end
+end