kumi 0.0.3 → 0.0.5

data/lib/kumi/schema_instance.rb

@@ -9,8 +9,10 @@ module Kumi
   #   instance.slice(:tax_due)         # alias for evaluate(*keys)
   #   instance.explain(:tax_due)       # pretty trace string
   #   instance.input                   # original context (read‑only)
-  #
+
   class SchemaInstance
+    attr_reader :compiled_schema, :analysis, :context
+
     def initialize(compiled_schema, analysis, context)
       @compiled_schema = compiled_schema # Kumi::CompiledSchema
       @analysis = analysis # Analyzer result (for deps)
@@ -36,8 +38,72 @@ module Kumi
       evaluate(key_name)[key_name]
     end
 
-    def input
-      @context
+    # Update input values and clear affected cached computations
+    def update(**changes)
+      changes.each do |field, value|
+        # Validate field exists
+        raise ArgumentError, "unknown input field: #{field}" unless input_field_exists?(field)
+
+        # Validate domain constraints
+        validate_domain_constraint(field, value)
+
+        # Update the input data
+        @context[field] = value
+
+        # Clear affected cached values using transitive closure by default
+        if ENV["KUMI_SIMPLE_CACHE"] == "true"
+          # Simple fallback: clear all cached values
+          @context.clear_cache
+        else
+          # Default: selective cache clearing using precomputed transitive closure
+          affected_keys = find_dependent_declarations_optimized(field)
+          affected_keys.each { |key| @context.clear_cache(key) }
+        end
+      end
+
+      self # Return self for chaining
+    end
+
+    private
+
+    def input_field_exists?(field)
+      # Check if field is declared in input block
+      input_meta = @analysis&.state&.dig(:input_meta) || {}
+      input_meta.key?(field) || @context.key?(field)
+    end
+
+    def validate_domain_constraint(field, value)
+      input_meta = @analysis&.state&.dig(:input_meta) || {}
+      field_meta = input_meta[field]
+      return unless field_meta&.dig(:domain)
+
+      domain = field_meta[:domain]
+      return unless violates_domain?(value, domain)
+
+      raise ArgumentError, "value #{value} is not in domain #{domain}"
+    end
+
+    def violates_domain?(value, domain)
+      case domain
+      when Range
+        !domain.include?(value)
+      when Array
+        !domain.include?(value)
+      when Proc
+        # For Proc domains, we can't statically analyze
+        false
+      else
+        false
+      end
+    end
+
+    def find_dependent_declarations_optimized(field)
+      # Use precomputed transitive closure for true O(1) lookup!
+      transitive_dependents = @analysis&.state&.dig(:transitive_dependents)
+      return [] unless transitive_dependents
+
+      # This is truly O(1) - just array lookup, no traversal needed
+      transitive_dependents[field] || []
     end
   end
 end

data/lib/kumi/syntax/declarations.rb

@@ -5,17 +5,20 @@ module Kumi
     module Declarations
       Attribute = Struct.new(:name, :expression) do
         include Node
+
         def children = [expression]
       end
 
       Trait = Struct.new(:name, :expression) do
         include Node
+
         def children = [expression]
       end
 
       # For field metadata declarations inside input blocks
       FieldDecl = Struct.new(:name, :domain, :type) do
         include Node
+
         def children = []
       end
     end

data/lib/kumi/syntax/expressions.rb

@@ -5,20 +5,24 @@ module Kumi
     module Expressions
       CallExpression = Struct.new(:fn_name, :args) do
         include Node
+
         def children = args
       end
       CascadeExpression = Struct.new(:cases) do
         include Node
+
         def children = cases
       end
 
       WhenCaseExpression = Struct.new(:condition, :result) do
         include Node
+
         def children = [condition, result]
       end
 
       ListExpression = Struct.new(:elements) do
         include Node
+
         def children = elements
 
         def size

data/lib/kumi/syntax/root.rb

@@ -6,6 +6,7 @@ module Kumi
     # It holds all the top-level declarations parsed from the source.
     Root = Struct.new(:inputs, :attributes, :traits) do
       include Node
+
       def children = [inputs, attributes, traits]
     end
   end

data/lib/kumi/syntax/terminal_expressions.rb

@@ -9,17 +9,20 @@ module Kumi
 
       Literal = Struct.new(:value) do
         include Node
+
         def children = []
       end
 
       # For field usage/reference in expressions (input.field_name)
       FieldRef = Struct.new(:name) do
         include Node
+
         def children = []
       end
 
       Binding = Struct.new(:name) do
         include Node
+
         def children = []
       end
     end

data/lib/kumi/types/compatibility.rb

@@ -12,6 +12,10 @@ module Kumi
         # Exact match
         return true if type1 == type2
 
+        # Generic array compatibility: :array is compatible with any structured array
+        return true if (type1 == :array && Validator.array_type?(type2)) ||
+                       (type2 == :array && Validator.array_type?(type1))
+
         # Numeric compatibility
         return true if numeric_compatible?(type1, type2)
 
@@ -32,6 +36,10 @@ module Kumi
         return type2 if type1 == :any
         return type1 if type2 == :any
 
+        # Generic array unification: structured array is more specific than :array
+        return type2 if type1 == :array && Validator.array_type?(type2)
+        return type1 if type2 == :array && Validator.array_type?(type1)
+
         # Numeric unification
         if numeric_compatible?(type1, type2)
           return :integer if type1 == :integer && type2 == :integer

data/lib/kumi/types/validator.rb

@@ -4,7 +4,7 @@ module Kumi
   module Types
     # Validates type definitions and structures
     class Validator
-      VALID_TYPES = %i[string integer float boolean any symbol regexp time date datetime].freeze
+      VALID_TYPES = %i[string integer float boolean any symbol regexp time date datetime array].freeze
 
       def self.valid_type?(type)
         return true if VALID_TYPES.include?(type)

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.3"
+  VERSION = "0.0.5"
 end

data/scripts/generate_function_docs.rb

@@ -30,10 +30,25 @@ end
 # Main documentation generation logic.
 def generate_docs
   output = []
+  add_header(output)
+  add_function_categories(output)
+  output.join("\n")
+end
+
+def add_header(output)
   output << "# Kumi Standard Function Library Reference"
   output << "\nKumi provides a rich library of built-in functions for use within `value` and `trait` expressions via `fn(...)`."
+end
+
+def add_function_categories(output)
+  function_categories.each do |title, functions|
+    output << "\n## #{title}\n"
+    add_functions_for_category(output, functions)
+  end
+end
 
-  categories = {
+def function_categories
+  {
     "Logical Functions" => Kumi::FunctionRegistry.logical_operations,
     "Comparison Functions" => Kumi::FunctionRegistry.comparison_operators,
     "Math Functions" => Kumi::FunctionRegistry.math_operations,
@@ -42,17 +57,14 @@ def generate_docs
     "Conditional Functions" => Kumi::FunctionRegistry.conditional_operations,
     "Type & Hash Functions" => Kumi::FunctionRegistry.type_operations
   }
+end
 
-  categories.each do |title, functions|
-    output << "\n## #{title}\n"
-    functions.sort.each do |name|
-      signature = Kumi::FunctionRegistry.signature(name)
-      output << "* **`#{name}`**: #{signature[:description]}"
-      output << "  * **Usage**: #{generate_signature(name, signature)}"
-    end
+def add_functions_for_category(output, functions)
+  functions.sort.each do |name|
+    signature = Kumi::FunctionRegistry.signature(name)
+    output << "* **`#{name}`**: #{signature[:description]}"
+    output << "  * **Usage**: #{generate_signature(name, signature)}"
   end
-
-  output.join("\n")
 end
 
 # Execute the script and print the documentation.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kumi
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - André Muta
@@ -31,7 +31,6 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
-- CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
 - README.md
@@ -44,16 +43,21 @@ files:
 - documents/SYNTAX.md
 - examples/deep_schema_compilation_and_evaluation_benchmark.rb
 - examples/federal_tax_calculator_2024.rb
+- examples/game_of_life.rb
+- examples/simple_rpg_game.rb
+- examples/static_analysis_errors.rb
 - examples/wide_schema_compilation_and_evaluation_benchmark.rb
 - lib/generators/trait_engine/templates/schema_spec.rb.erb
 - lib/kumi.rb
 - lib/kumi/analyzer.rb
+- lib/kumi/analyzer/analysis_state.rb
 - lib/kumi/analyzer/constant_evaluator.rb
 - lib/kumi/analyzer/passes/definition_validator.rb
 - lib/kumi/analyzer/passes/dependency_resolver.rb
 - lib/kumi/analyzer/passes/input_collector.rb
 - lib/kumi/analyzer/passes/name_indexer.rb
 - lib/kumi/analyzer/passes/pass_base.rb
+- lib/kumi/analyzer/passes/semantic_constraint_validator.rb
 - lib/kumi/analyzer/passes/toposorter.rb
 - lib/kumi/analyzer/passes/type_checker.rb
 - lib/kumi/analyzer/passes/type_consistency_checker.rb
@@ -61,8 +65,10 @@ files:
 - lib/kumi/analyzer/passes/unsat_detector.rb
 - lib/kumi/analyzer/passes/visitor_pass.rb
 - lib/kumi/atom_unsat_solver.rb
+- lib/kumi/cli.rb
 - lib/kumi/compiled_schema.rb
 - lib/kumi/compiler.rb
+- lib/kumi/constraint_relationship_solver.rb
 - lib/kumi/domain.rb
 - lib/kumi/domain/enum_analyzer.rb
 - lib/kumi/domain/range_analyzer.rb
@@ -120,7 +126,6 @@ files:
 - lib/kumi/types/validator.rb
 - lib/kumi/version.rb
 - scripts/generate_function_docs.rb
-- test_impossible_cascade.rb
 homepage: https://github.com/amuta/kumi
 licenses:
 - MIT
@@ -146,7 +151,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.1
 specification_version: 4
-summary: A declarative Ruby DSL for defining business rules and calculations with
-  static dependency checks, cycle detection, domain validation, and human‑readable
-  explainability.
+summary: A declarative DSL that transforms business logic into a statically-checked
+  dependency graph
 test_files: []

data/CHANGELOG.md

@@ -1,25 +0,0 @@
-## [Unreleased]
-
-### Changed
-- **BREAKING**: Replaced `StrictCycleChecker` with `AtomUnsatSolver` for stack-safe UNSAT detection
-- Refactored cycle detection to use iterative Kahn's topological sort algorithm instead of recursive DFS
-- Added support for always-false comparison detection (e.g., `100 < 100`)
-
-### Added  
-- **Evaluation memoization**: `EvaluationWrapper` struct with `@__schema_cache__` provides automatic caching of computed bindings
-- **Massive performance improvements**: 369x-1,379x speedup on deep dependency chains through intelligent memoization
-- Depth-safe UNSAT detection handles 30k+ node graphs without stack overflow
-- Comprehensive test suite for large graph scenarios (acyclic ladders, cycles, mixed constraints)
-- Enhanced documentation with YARD comments for `AtomUnsatSolver` module
-- Extracted `StrictInequalitySolver` module for clear separation of cycle detection logic
-
-### Performance
-- **Stack-safe UNSAT detection**: Eliminates `SystemStackError` in constraint analysis for 30k+ node graphs
-- **Fixed gather_atoms recursion**: Made AST traversal iterative to handle deep dependency chains
-- Sub-millisecond performance on 10k-20k node constraint graphs with cycle detection
-- Maintained identical UNSAT detection correctness for all existing scenarios
-- **Note**: Deep schemas (2500+ dependencies) may still hit Ruby stack limits in compilation/evaluation phases
-
-## [0.1.0] - 2025-07-01
-
-- Initial release

data/test_impossible_cascade.rb

@@ -1,51 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require_relative "lib/kumi"
-
-# This test demonstrates that the UnsatDetector still correctly catches
-# genuinely impossible cascade conditions after our fix
-
-puts "🧪 Testing UnsatDetector Catches Impossible Cascade Conditions"
-puts "=" * 60
-
-begin
-  impossible_schema = Class.new do
-    extend Kumi::Schema
-
-    schema do
-      input do
-        integer :age, domain: 0..150
-      end
-
-      # These traits are individually satisfiable
-      trait :very_young, input.age, :<, 25
-      trait :very_old, input.age, :>, 65
-
-      # This cascade condition combines contradictory traits - should be caught!
-      value :impossible_condition do
-        on :very_young, :very_old, "Impossible: young AND old"  # age < 25 AND age > 65
-        base "Normal"
-      end
-    end
-  end
-  
-  puts "❌ ERROR: Should have caught impossible cascade condition!"
-  
-rescue Kumi::Errors::SemanticError => e
-  if e.message.include?("conjunction") && e.message.include?("logically impossible")
-    puts "✅ CORRECTLY CAUGHT impossible cascade condition!"
-    puts "   Error: #{e.message}"
-    puts
-    puts "   This proves the UnsatDetector still works for genuinely impossible conditions"
-    puts "   while allowing valid mutually exclusive cascades."
-  else
-    puts "❌ UNEXPECTED ERROR: #{e.message}"
-  end
-end
-
-puts
-puts "🎉 UnsatDetector Fix Validation Complete!"
-puts "   ✅ Valid mutually exclusive cascades: WORK"
-puts "   ✅ Impossible cascade conditions: CAUGHT"
-puts "   ✅ Existing functionality: PRESERVED"