kumi 0.0.4 → 0.0.6

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/array_expression.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    ArrayExpression = Struct.new(:elements) do
+      include Node
+
+      def children = elements
+
+      def size
+        elements.size
+      end
+    end
+  end
+end

data/lib/kumi/syntax/call_expression.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    CallExpression = Struct.new(:fn_name, :args) do
+      include Node
+
+      def children = args
+    end
+  end
+end

data/lib/kumi/syntax/cascade_expression.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    CascadeExpression = Struct.new(:cases) do
+      include Node
+
+      def children = cases
+    end
+  end
+end

data/lib/kumi/syntax/case_expression.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    CaseExpression = Struct.new(:condition, :result) do
+      include Node
+
+      def children = [condition, result]
+    end
+  end
+end

data/lib/kumi/syntax/declaration_reference.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    DeclarationReference = Struct.new(:name) do
+      include Node
+
+      def children = []
+    end
+  end
+end

data/lib/kumi/syntax/hash_expression.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    HashExpression = Struct.new(:pairs) do
+      include Node
+
+      def children = pairs.flatten
+    end
+  end
+end

data/lib/kumi/syntax/input_declaration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    # For field metadata declarations inside input blocks
+    InputDeclaration = Struct.new(:name, :domain, :type, :children) do
+      include Node
+
+      def children = self[:children] || []
+    end
+  end
+end

data/lib/kumi/syntax/input_element_reference.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    # For field usage/reference in expressions (input.field_name)
+    InputElementReference = Struct.new(:path) do
+      include Node
+
+      def children = []
+    end
+  end
+end

data/lib/kumi/syntax/input_reference.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    # For field usage/reference in expressions (input.field_name)
+    InputReference = Struct.new(:name) do
+      include Node
+
+      def children = []
+    end
+  end
+end

data/lib/kumi/syntax/literal.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    Literal = Struct.new(:value) do
+      include Node
+
+      def children = []
+    end
+  end
+end

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/trait_declaration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    TraitDeclaration = Struct.new(:name, :expression) do
+      include Node
+
+      def children = [expression]
+    end
+  end
+end

data/lib/kumi/syntax/value_declaration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    ValueDeclaration = Struct.new(:name, :expression) do
+      include Node
+
+      def children = [expression]
+    end
+  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/vectorization_metadata.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Kumi
+  # Metadata system for vectorization detection and handling
+  module VectorizationMetadata
+    # Tracks which declarations are arrays with children (vectorizable)
+    class ArrayDeclarationTracker
+      def initialize
+        @array_declarations = {}
+      end
+
+      def register_array(name, children)
+        @array_declarations[name] = children.map(&:name)
+      end
+
+      def array_declaration?(name)
+        @array_declarations.key?(name)
+      end
+
+      def array_children(name)
+        @array_declarations[name] || []
+      end
+
+      def all_arrays
+        @array_declarations.keys
+      end
+    end
+
+    # Detects vectorized operations in expressions
+    class VectorizationDetector
+      def initialize(array_tracker)
+        @array_tracker = array_tracker
+      end
+
+      # Check if an expression should be vectorized
+      def vectorized_expression?(expression)
+        case expression
+        when Kumi::Syntax::CallExpression
+          vectorized_call?(expression)
+        when Kumi::Syntax::InputElementReference
+          vectorized_element_reference?(expression)
+        else
+          false
+        end
+      end
+
+      # Check if a function call should be treated as a reducer
+      def reducer_function?(fn_name, args)
+        REDUCER_FUNCTIONS.include?(fn_name) && 
+          args.any? { |arg| vectorized_expression?(arg) }
+      end
+
+      private
+
+      REDUCER_FUNCTIONS = %i[sum min max size length first last].freeze
+
+      def vectorized_call?(call_expr)
+        # Arithmetic operations between array elements are vectorized
+        ARITHMETIC_OPERATIONS.include?(call_expr.fn_name) &&
+          call_expr.args.any? { |arg| vectorized_expression?(arg) }
+      end
+
+      def vectorized_element_reference?(elem_ref)
+        return false unless elem_ref.path.size >= 2
+        
+        array_name, _field_name = elem_ref.path
+        @array_tracker.array_declaration?(array_name)
+      end
+
+      ARITHMETIC_OPERATIONS = %i[add subtract multiply divide modulo power].freeze
+    end
+
+    # Metadata about how values should be computed
+    class ComputationMetadata
+      attr_reader :vectorized_values, :reducer_values, :scalar_values
+
+      def initialize
+        @vectorized_values = Set.new
+        @reducer_values = Set.new  
+        @scalar_values = Set.new
+      end
+
+      def mark_vectorized(name)
+        @vectorized_values.add(name)
+      end
+
+      def mark_reducer(name)
+        @reducer_values.add(name)
+      end
+
+      def mark_scalar(name)
+        @scalar_values.add(name)
+      end
+
+      def vectorized?(name)
+        @vectorized_values.include?(name)
+      end
+
+      def reducer?(name)
+        @reducer_values.include?(name)
+      end
+
+      def scalar?(name)
+        @scalar_values.include?(name)
+      end
+    end
+  end
+end

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.4"
+  VERSION = "0.0.6"
 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.4
+  version: 0.0.6
 platform: ruby
 authors:
 - André Muta
@@ -31,29 +31,41 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
-- CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/AST.md
+- docs/DSL.md
+- docs/FUNCTIONS.md
+- docs/SYNTAX.md
 - docs/development/README.md
 - docs/development/error-reporting.md
-- documents/AST.md
-- documents/DSL.md
-- documents/FUNCTIONS.md
-- documents/SYNTAX.md
+- docs/features/README.md
+- docs/features/analysis-cascade-mutual-exclusion.md
+- docs/features/analysis-type-inference.md
+- docs/features/analysis-unsat-detection.md
+- docs/features/array-broadcasting.md
+- docs/features/input-declaration-system.md
+- docs/features/performance.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/broadcast_detector.rb
+- lib/kumi/analyzer/passes/declaration_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,9 +73,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/domain.rb
+- lib/kumi/constraint_relationship_solver.rb
 - lib/kumi/domain/enum_analyzer.rb
 - lib/kumi/domain/range_analyzer.rb
 - lib/kumi/domain/validator.rb
@@ -89,28 +102,38 @@ files:
 - lib/kumi/function_registry/math_functions.rb
 - lib/kumi/function_registry/string_functions.rb
 - lib/kumi/function_registry/type_functions.rb
-- lib/kumi/input.rb
 - lib/kumi/input/type_matcher.rb
 - lib/kumi/input/validator.rb
 - lib/kumi/input/violation_creator.rb
 - lib/kumi/parser/build_context.rb
+- lib/kumi/parser/declaration_reference_proxy.rb
 - lib/kumi/parser/dsl.rb
 - lib/kumi/parser/dsl_cascade_builder.rb
 - lib/kumi/parser/expression_converter.rb
 - lib/kumi/parser/guard_rails.rb
 - lib/kumi/parser/input_builder.rb
+- lib/kumi/parser/input_field_proxy.rb
 - lib/kumi/parser/input_proxy.rb
+- lib/kumi/parser/nested_input.rb
 - lib/kumi/parser/parser.rb
 - lib/kumi/parser/schema_builder.rb
 - lib/kumi/parser/sugar.rb
 - lib/kumi/schema.rb
 - lib/kumi/schema_instance.rb
-- lib/kumi/syntax.rb
-- lib/kumi/syntax/declarations.rb
-- lib/kumi/syntax/expressions.rb
+- lib/kumi/syntax/array_expression.rb
+- lib/kumi/syntax/call_expression.rb
+- lib/kumi/syntax/cascade_expression.rb
+- lib/kumi/syntax/case_expression.rb
+- lib/kumi/syntax/declaration_reference.rb
+- lib/kumi/syntax/hash_expression.rb
+- lib/kumi/syntax/input_declaration.rb
+- lib/kumi/syntax/input_element_reference.rb
+- lib/kumi/syntax/input_reference.rb
+- lib/kumi/syntax/literal.rb
 - lib/kumi/syntax/node.rb
 - lib/kumi/syntax/root.rb
-- lib/kumi/syntax/terminal_expressions.rb
+- lib/kumi/syntax/trait_declaration.rb
+- lib/kumi/syntax/value_declaration.rb
 - lib/kumi/types.rb
 - lib/kumi/types/builder.rb
 - lib/kumi/types/compatibility.rb
@@ -118,9 +141,9 @@ files:
 - lib/kumi/types/inference.rb
 - lib/kumi/types/normalizer.rb
 - lib/kumi/types/validator.rb
+- lib/kumi/vectorization_metadata.rb
 - lib/kumi/version.rb
 - scripts/generate_function_docs.rb
-- test_impossible_cascade.rb
 homepage: https://github.com/amuta/kumi
 licenses:
 - MIT
@@ -146,7 +169,5 @@ 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 logic framework with static analysis for Ruby.
 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/lib/kumi/domain.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Kumi
-  module Domain
-  end
-end
-
-require_relative "domain/validator"

data/lib/kumi/input.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Kumi
-  module Input
-  end
-end
-
-require_relative "input/validator"

data/lib/kumi/syntax/declarations.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Kumi
-  module Syntax
-    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
-  end
-end