kumi 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91e6e3b6ce1e4911d37588ba8aaf9b89f8129d23fe93b05268756c417249da90
-  data.tar.gz: f019de05a9e05957184fc649d187306fa7cd3736cb9d04c56d6080d4a3cde9de
+  metadata.gz: ec2c56684edac64e9818bbf85de98e9855c3d50df80c490c8f868b3e9b701dab
+  data.tar.gz: d5246f98e10b0365b47f6a67fed5c3a4cbc77d5ad15905d93b046251965135f5
 SHA512:
-  metadata.gz: 6d6439258bcb876374c5f7ca3bafa4e59faabf112e3cfe2dac532f752b2b7ef8533bf888c4e6feb1509995069a103a258b37c6b18b0164487e5215e03dd85b10
-  data.tar.gz: 6e64f9725569836d7a17b83aa82f316f01d4a9169a1323cee3d1d5fcf7d3782902b9c0695bcdb3735a4c206906463a4b7ca3e14f39f253ba23bf23d572ce95aa
+  metadata.gz: f71ba6867b72145247b5c1ea4c3b197f831996bf078798c6a9decdb4e047f83859e062e6a6411e2311d279f8a8cc03ca7e16ac194c9a27b84f8a55b67faa3fcb
+  data.tar.gz: 70c4dab6bf036da2d507f89c2d8e9d65a24da2685412d3e517a2b3c1696d200c294c512786c85bfccf9feca301e90e70a26999f5ed1528221331b55f77175c8d

data/CLAUDE.md

@@ -5,11 +5,9 @@
 !! Do not care about linter or coverage unless asked to do so.
 !! IMPORTANT: Communication style - Write direct, factual statements. Avoid promotional language, unnecessary claims, or marketing speak. State what the system does, not what benefits it provides. Use TODOs for missing information rather than placeholder claims.
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
 ## Project Overview
 
-Kumi is a declarative decision-modeling compiler for Ruby that transforms complex business rules into executable dependency graphs. It features a multi-pass analyzer that validates rule interdependencies, detects cycles, infers types, and generates optimized evaluation functions. The system separates input field declarations from business logic through an explicit input block syntax.
+Kumi is a Declarative logic and rules engine framework with static analysis for Ruby.
 
 ## Development Commands
 
@@ -18,29 +16,11 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 - `bundle exec rspec spec/path/to/specific_spec.rb` - Run specific test file
 - `bundle exec rspec spec/path/to/specific_spec.rb:123` - Run specific test at line
 
-### Linting & Code Quality
-- `bundle exec rubocop` - Run RuboCop linter
-- `bundle exec rubocop -a` - Auto-fix RuboCop issues where possible
-- `rake` - Run default task (includes rspec and rubocop)
-
 ### Gem Management
 - `bundle install` - Install dependencies
 - `gem build kumi.gemspec` - Build the gem
 - `gem install ./kumi-*.gem` - Install locally built gem
 
-### Kumi CLI
-- `./bin/kumi -i` - Start interactive REPL mode for rapid schema testing
-- `./bin/kumi -f schema.rb -d data.json` - Execute schema file with input data
-- `./bin/kumi -f schema.rb -k key1,key2` - Extract specific keys from schema
-- `./bin/kumi -f schema.rb -e key_name` - Explain how a key is computed
-- `./bin/kumi -f schema.rb -d data.json -o json` - Output results in JSON format
-
-**CLI Features**:
-- Interactive REPL with schema loading, data manipulation, and live evaluation
-- File-based schema execution with JSON/YAML input data support
-- Selective key extraction and explain functionality for debugging
-- Multiple output formats (pretty, JSON, YAML) for integration
-
 ## Architecture Overview
 
 ### Core Components
@@ -50,13 +30,7 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 - Provides the `schema(&block)` DSL method that builds the syntax tree, runs analysis, and compiles to executable form
 - Generates a `Runner` instance for executing queries against input data
 
-**Parser** (`lib/kumi/parser/`):
-- `dsl.rb` - Main DSL parser that converts Ruby block syntax into AST nodes
-- `dsl_builder_context.rb` - Context for building DSL elements with input/value/trait methods
-- `dsl_cascade_builder.rb` - Specialized builder for cascade expressions
-- `dsl_proxy.rb` - Proxy object for method delegation during parsing
-- `input_dsl_proxy.rb` - Proxy for input block DSL supporting both `key` method and type-specific DSL methods
-- `input_proxy.rb` - Proxy for `input.field_name` references in expressions
+**Parser** (`lib/kumi/ruby_parser{/*,.rb}`):
 
 **Syntax Tree** (`lib/kumi/syntax/`):
 - `node.rb` - Base node class with location tracking
@@ -66,12 +40,13 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 - `input_declaration.rb` - Input field declaration nodes (formerly FieldDecl)
 - `call_expression.rb` - Function call expression nodes
 - `array_expression.rb` - Array expression nodes (formerly ListExpression)
-- `hash_expression.rb` - Hash expression nodes (for future hash literals)
+- `hash_expression.rb` - Hash expression nodes (for future hash literals) (currently not used)
 - `cascade_expression.rb` - Cascade expression nodes (conditional values)
 - `case_expression.rb` - Case expression nodes (formerly WhenCaseExpression)
 - `literal.rb` - Literal value nodes
-- `input_reference.rb` - Input field reference nodes (formerly FieldRef)  
-- `declaration_reference.rb` - Declaration reference nodes (formerly Binding)
+- `input_reference.rb` - Input field reference nodes (formerly FieldRef) 
+- `input_element_reference.rb` - Reference to nested input field (array -> obj.field) 
+- `declaration_reference.rb` - Declaration reference value or trait nodes
 
 **Analyzer** (`lib/kumi/analyzer.rb`):
 - Multi-pass analysis system that validates schemas and builds dependency graphs
@@ -135,10 +110,7 @@ end
 ```
 
 **Function Call Syntax**:
-- **Symbol style**: `fn(:function_name, arg1, arg2)` - Always works, explicit
-- **Method style**: `fn.function_name(arg1, arg2)` - Also works, more readable
-- **Incorrect**: `fn()` - Empty function calls cause parse errors
-- **Incorrect**: `fn.function_name()` - Empty method calls cause parse errors
+- **Symbol style**: `fn(:function_name, arg1, arg2, ...)` - The only supported function call syntax 
 
 **Arithmetic Operations**:
 - **Sugar Syntax**: `input.field1 + input.field2` - Works for input fields and value references
@@ -147,26 +119,13 @@ end
 
 **Cascade Condition Syntax**:
 ```ruby
-# CORRECT - use symbols for trait references in cascades
 value :status do
   on trait_name, "Result"
   base "Default"
 end
-
-# INCORRECT - bare identifiers don't work in cascade conditions
-value :status do
-  on trait_name, "Result"  # This will fail
-  base "Default"
-end
 ```
 
-**UnsatDetector Considerations**:
-- Cascades with mutually exclusive conditions are valid (e.g., `amount < 100` vs `amount >= 100`)
-- Values that depend on such cascades are also valid (fixed in recent update)
-- Use clear, non-contradictory trait names to avoid confusion
-
 ### Key Patterns
-
 **DSL Structure**:
 ```ruby
 schema do
@@ -177,6 +136,14 @@ schema do
     array   :scores, elem: { type: :float }
     hash    :metadata, key: { type: :string }, val: { type: :any }
 
+    array :line_items do
+      float   :price
+      integer :quantity
+      string  :category
+    end
+
+
+
     # Fields with no declared type
     any     :misc_field
   end
@@ -191,20 +158,13 @@ end
 ```
 
 **IMPORTANT CASCADE CONDITION SYNTAX:**
-In cascade expressions (`value :name do ... end`), trait references use **symbols**, not bare identifiers:
+In cascade expressions (`value :name do ... end`), trait references use bare identifiers:
 ```ruby
 value :status do
-  on adult, "Adult Status"      # ✅ Correct - use trait_name symbol
+  on adult, "Adult Status"      
   on verified, "Verified User"
   base "Unverified"
 end
-
-# NOT this:
-value :status do
-  on adult, "Adult Status"       # ❌ Wrong - don't use bare identifier in cascade
-  on verified, "Verified User"   # ❌ Wrong
-  base "Unverified"
-end
 ```
 
 **Input Block System**:
@@ -260,72 +220,26 @@ The `examples/` directory contains comprehensive examples showing Kumi usage pat
 - `spec/fixtures/` - Test fixtures and sample schemas
 - `spec/support/` - Test helpers (`ast_factory.rb`, `schema_generator.rb`)
 
-## Key Files for Understanding
-
-1. `lib/kumi/schema.rb` - Start here to understand the main API
-2. `examples/input_block_typing_showcase.rb` - Comprehensive example of current features
-3. `lib/kumi/analyzer.rb` - Core analysis pipeline with multi-pass system
-4. `lib/kumi/types.rb` - Static type system implementation
-5. `lib/kumi/function_registry.rb` - Available functions and extension patterns
-6. `lib/kumi/analyzer/passes/type_inferencer.rb` - Type inference algorithm
-7. `lib/kumi/analyzer/passes/type_checker.rb` - Type validation with enhanced error messages
-8. `spec/kumi/input_block_spec.rb` - Input block syntax and behavior
-9. `spec/integration/compiler_integration_spec.rb` - End-to-end test examples
-10. `docs/DSL.md` - Concise DSL syntax reference
-11. `docs/AST.md` - AST node types and structure reference
-12. `docs/SYNTAX.md` - Comprehensive sugar vs sugar-free syntax comparison with examples
-13. `lib/kumi/cli.rb` - CLI implementation with REPL and file execution
-14. `examples/simple_tax_schema.rb` - CLI-compatible schema example
-15. `docs/features/analysis-cascade-mutual-exclusion.md` - Cascade mutual exclusion detection feature documentation
-16. `docs/features/array-broadcasting.md` - Array broadcasting and vectorization system documentation
-
-## CLI Usage and Best Practices
-
-### Schema File Requirements
-- **Must use module structure**: `module SchemaName; extend Kumi::Schema; schema do ... end; end`
-- **Must have proper require**: `require_relative "../lib/kumi"` at the top
-- **Must have input block**: Even empty `input {}` blocks are required
-- **Avoid inline definitions**: Don't define schemas directly in methods or blocks
-
-### CLI Development Workflow
-1. **Start with REPL**: Use `./bin/kumi -i` for rapid prototyping and testing
-2. **Test with files**: Create `.rb` schema files and `.json/.yaml` data files
-3. **Iterate quickly**: Use `-k key1,key2` to focus on specific outputs
-4. **Debug with explain**: Use `-e key_name` to understand computation flow
-5. **Validate with different data**: Test edge cases with varied input data
-
-### Common CLI Patterns
-```bash
-# Interactive development
-./bin/kumi -i
-kumi> schema examples/my_schema.rb
-kumi> data test_data.json
-kumi> get result
-
-# File-based execution
-./bin/kumi -f examples/tax_schema.rb -d examples/tax_data.json -k total_tax,effective_rate
-
-# Debugging computations
-./bin/kumi -f examples/complex_schema.rb -d examples/data.json -e complex_calculation
-
-# Output formats for integration
-./bin/kumi -f schema.rb -d data.json -k results -o json | jq '.results'
-```
+## Files for Understanding
+
+. `docs/*` - Documents about Kumi, its features, DSL syntax, ... 
+- `examples/*` Random examples of very diverse contexts.
 
 ### Troubleshooting Schema Issues
 - **Parse Errors**: Check function syntax (avoid empty `fn()` calls)
-- **Module Not Found**: Ensure proper module structure and naming
-- **UnsatDetector Errors**: Review trait logic for contradictions
-- **Type Errors**: Check input block type declarations match usage
-- **Runtime Errors**: Use explain to trace computation dependencies
+- **Module Not Found**: Ensure proper module structure and naming, see examples
+- **UnsatDetector Errors**: Review trait logic for contradictions, add debugs!
+- **Type Errors**: Check input block type declarations match usage, add debugs!
+- **Runtime Errors**: Use explain to trace computation dependencies, add debugs!
 
 ## Input Block System Details
 
 ### Required Input Blocks
-- **All schemas must have an input block** - This is now mandatory
+- **All schemas must have an input block** -
 - Input blocks declare expected fields with optional type and domain constraints
-- **Empty input blocks are allowed** - Use `input {}` for schemas that don't require external data
-- Fields are accessed via `input.field_name` syntax (replaces deprecated `key(:field)`)
+- **Empty input blocks are allowed** -`input {}` Even if its not very useful.
+- Fields are accessed via `input.field_name` or `input.field.nested_field.nested_nested_field` which
+works for referencing nested array input declarations.
 
 ### Type System Integration
 - **Declared Types**: Explicit type declarations in input blocks (e.g. `integer :field`, `string :name`, `any :field`)
@@ -335,26 +249,21 @@ kumi> get result
 - **Helper Functions**: Use `array(:type)` and `hash(:key_type, :value_type)` for complex types
 
 ### Parser Components
-- `input_dsl_proxy.rb` - Supports type-specific DSL methods (`integer`, `float`, `string`, `boolean`, `array`, `hash`, `any`)
-- `input_proxy.rb` - Handles `input.field_name` references in expressions
-- `input_collector.rb` - Collects and validates field metadata consistency
+See `lib/kumi/ruby_parser/parser.rb`
 
 ### Domain Constraints
 - Can be declared: `integer :age, domain: 18..65`
-- **Implemented**: Domain validation is active and enforced at runtime
 - Supports Range domains (`18..65`), Array domains (`%w[active inactive]`), and Proc domains for custom validation
-- Field metadata includes domain information and runtime validation occurs during `Schema.from()`
-
+- Analyzer do some limited domain UNSAT detection, and its used to validated against input at Runtime
 ### Type Examples
 ```ruby
 input do
-  # New type-specific DSL methods (recommended)
   string       :name
   integer      :age, domain: 18..65
   hash         :metadata, key: { type: :string }, val: { type: :any }
 
-  # For untyped/any fields
-  any          :misc
+  #generic type
+  any          :misc # this will make Kumi lose most of its analyze/inference power
 end
 ```
 
@@ -437,59 +346,20 @@ trait :qualified, input.age, :>=, 21, input.score  # OLD - shows deprecation war
 3. Add pass to `PASSES` array in `lib/kumi/analyzer.rb` in correct order
 4. Consider dependencies on other passes (e.g., TypeChecker needs TypeInferencer)
 
-### Working with AST Nodes
-- All nodes include `Node` module for location tracking
-- Use `spec/support/ast_factory.rb` helpers in tests
-- Field declarations use `FieldDecl` nodes with name, domain, and type
-- Field references use `FieldRef` nodes (from `input.field_name`) with operator methods
-- FieldRef operator methods (>=, <=, >, <, ==, !=) create CallExpression nodes
-- CallExpression `&` method enables logical AND chaining
-
-### Testing Input Block Features
-- See `spec/kumi/input_block_spec.rb` for comprehensive input block tests
-- Use `schema_generator.rb` helper for creating test schemas
-- All integration tests now require input blocks
-
 ## Architecture Design Principles
 
 - **Multi-pass Analysis**: Each analysis pass has a single responsibility and builds on previous passes
 - **Immutable Syntax Tree**: AST nodes are immutable; analysis results stored separately in analyzer state
 - **Dependency-driven Evaluation**: All computation follows dependency graph to ensure correct order
 - **Type Safety**: Optional but comprehensive type checking without breaking existing schemas
-- **Backward Compatibility**: New features maintain compatibility with existing DSL and APIs
 - **Ruby Integration**: Leverages Ruby's metaprogramming while providing structured analysis
-- **Separation of Concerns**: Input metadata (types, domains) separated from business logic
-- **Class Decomposition**: Large classes split into focused, single-responsibility components following RuboCop guidelines
-- **Delegation Pattern**: Complex operations delegated to specialized analyzer and formatter classes
 - **Unified Error Reporting**: Consistent, localized error messages throughout the system with clear interface patterns
 
 ## Code Organization Patterns
 
-### Modular Validation Architecture
-- **Coordinator Classes**: Main classes like `Input::Validator` and `Domain::Validator` coordinate but delegate complex logic
-- **Specialized Analyzers**: Domain-specific classes like `RangeAnalyzer` and `EnumAnalyzer` handle specific constraint types
-- **Formatter Classes**: Dedicated classes like `ViolationFormatter` handle message formatting with consistent patterns
-- **Creator Classes**: Classes like `ViolationCreator` centralize object creation with standardized structure
-
 ### Testing Best Practices
 - **Spec Organization**: Tests organized by component with clear separation between unit and integration tests
 - **Error Variable Extraction**: RSpec patterns avoid multiline block chains by extracting error variables for assertion
-- **Shared Contexts**: Use `schema_generator` and other shared contexts for consistent test setup
-
-### RuboCop Compliance
-- **Method Length**: Keep methods under 10 lines through extraction and delegation
-- **Class Length**: Break classes over 100 lines into focused components
-- **Complexity Metrics**: Reduce cyclomatic and ABC complexity through single-responsibility design
-- **Style Consistency**: Follow Ruby style guidelines for readability and maintainability
-
-### Error Reporting Architecture
-- **Unified Interface**: Use `ErrorReporter` module and `ErrorReporting` mixin for consistent error handling
-- **Location Information**: All errors must include proper file:line:column location data
-- **Precise Location Tracking**: Error objects preserve location data in `.location` attribute for programmatic access
-- **User Code Location**: Errors point to actual user DSL code, not internal library files
-- **Backward Compatibility**: Support both legacy `[location, message]` and new `ErrorEntry` formats
-- **Type Categorization**: Errors categorized as `:syntax`, `:semantic`, `:type`, `:runtime`
-- **Enhanced Messaging**: Support for error suggestions, context, and similar name detection
 
 ## Development Guides and Standards
 
@@ -522,18 +392,5 @@ end
 - Use `spec/integration/dsl_breakage_spec.rb` patterns for comprehensive error testing
 - Use `spec/integration/potential_breakage_spec.rb` for edge cases break
 - Use `spec/fixtures/location_tracking_test_schema.rb` fixture for testing different syntax error types  
-- Test backward compatibility with existing analyzer pass specs
-
-### Key Development Files
-12. `lib/kumi/error_reporter.rb` - Central error reporting functionality
-13. `lib/kumi/error_reporting.rb` - Mixin for consistent error interfaces  
-14. `spec/integration/location_tracking_spec.rb` - Comprehensive tests for error location accuracy
-15. `spec/fixtures/location_tracking_test_schema.rb` - Fixture with intentional syntax errors for location testing
-16. `ERROR_REPORTING_INTERFACE.md` - Detailed error reporting implementation guide
-17. `ON_ERRORS.md` - Comprehensive analysis of DSL breakage scenarios and error quality
-18. `spec/integration/dsl_breakage_spec.rb` - Integration tests for all DSL breakage scenarios
-19. `spec/integration/potential_breakage_spec.rb` - Edge cases that should break but might not
-20. `docs/development/README.md` - Development guides directory index
-21. `docs/development/error-reporting.md` - Comprehensive error reporting standards and patterns
 
 # 

data/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/amuta/kumi/workflows/CI/badge.svg)](https://github.com/amuta/kumi/actions)
 [![Gem Version](https://badge.fury.io/rb/kumi.svg)](https://badge.fury.io/rb/kumi)
 
-Kumi is a Declarative logic framework with static analysis for Ruby.
+Kumi is a Declarative logic and rules engine framework with static analysis for Ruby.
 
 It is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
 
@@ -330,6 +330,37 @@ Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_st
 
 </details>
 
+<details>
+<summary><strong>📋 Schema Metadata</strong> - Extract structured information for tooling</summary>
+
+### Schema Metadata
+
+Access structured metadata for building tools like form generators and dependency analyzers:
+
+```ruby
+metadata = FederalTax2024.schema_metadata
+
+# Processed metadata (tool-friendly)
+metadata.inputs           # Input field types and domains  
+metadata.values           # Value declarations with dependencies
+metadata.traits           # Trait conditions and metadata
+metadata.functions        # Function registry information
+
+# Raw analyzer state (advanced usage)
+metadata.dependencies     # Dependency graph between declarations
+metadata.evaluation_order # Topologically sorted computation order
+metadata.inferred_types   # Type inference results
+metadata.declarations     # Raw AST declaration nodes
+
+# Export formats
+metadata.to_h             # Serializable hash for JSON/APIs
+metadata.to_json_schema   # JSON Schema for input validation
+```
+
+The SchemaMetadata interface provides both processed metadata for tool development and raw analyzer state for advanced use cases. Complete documentation available in the SchemaMetadata class and [docs/schema_metadata.md](docs/schema_metadata.md).
+
+</details>
+
 ## Usage
 
 **Suitable for:**
@@ -364,4 +395,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/amuta/
 
 ## License
 
-MIT License. See [LICENSE](LICENSE).
+MIT License. See [LICENSE](LICENSE).

data/docs/SYNTAX.md

@@ -131,13 +131,8 @@ trait :needs_review, fn(:and, needs_improvement, fn(:>, input.attempts, 2))
 ### String Operations
 
 ```ruby
-# With Sugar  
-trait :long_name, input.name.length > 20
-trait :starts_with_a, input.name.start_with?("A")
-trait :contains_space, input.name.include?(" ")
-
-# Sugar-Free
-trait :long_name, fn(:>, fn(:string_length, input.name), 20)
+# All string operations use function syntax
+trait :long_name, fn(:string_length, input.name) >  20
 trait :starts_with_a, fn(:start_with?, input.name, "A")
 trait :contains_space, fn(:contains?, input.name, " ")
 ```

data/docs/features/array-broadcasting.md

@@ -24,7 +24,7 @@ schema do
       integer :quantity
       string  :category
     end
-    scalar :tax_rate, type: :float
+    float :tax_rate, type: :float
   end
 
   # Element-wise computation - broadcasts over each item

data/docs/schema_metadata/broadcasts.md

@@ -0,0 +1,53 @@
+# Broadcasts Metadata
+
+Array broadcasting operation analysis for vectorized computations.
+
+## Structure
+
+```ruby
+state[:broadcasts] = {
+  array_fields: Hash,
+  vectorized_operations: Hash,
+  reduction_operations: Hash
+}
+```
+
+## Array Fields
+
+```ruby
+array_fields: {
+  :line_items => {
+    element_fields: [:price, :quantity, :name],
+    element_types: { price: :float, quantity: :integer, name: :string }
+  }
+}
+```
+
+## Vectorized Operations
+
+```ruby
+vectorized_operations: {
+  :item_totals => {
+    operation: :multiply,
+    vectorized_args: { 0 => true, 1 => true }
+  }
+}
+```
+
+## Reduction Operations
+
+```ruby
+reduction_operations: {
+  :total_amount => {
+    function: :sum,
+    source: :array_field
+  }
+}
+```
+
+## Usage
+
+- Compiler optimizations
+- Parallel execution
+- Type inference
+- Performance analysis

data/docs/schema_metadata/cascades.md

@@ -0,0 +1,45 @@
+# Cascades Metadata
+
+Cascade mutual exclusion analysis for safe conditional cycles.
+
+## Structure
+
+```ruby
+state[:cascades] = {
+  cascade_name => {
+    condition_traits: Array,
+    condition_count: Integer,
+    all_mutually_exclusive: Boolean,
+    exclusive_pairs: Integer,
+    total_pairs: Integer
+  }
+}
+```
+
+## Example
+
+```ruby
+{
+  :tax_rate => {
+    condition_traits: [:single, :married],
+    condition_count: 2,
+    all_mutually_exclusive: true,
+    exclusive_pairs: 1,
+    total_pairs: 1
+  }
+}
+```
+
+## Fields
+
+- `condition_traits`: Trait names used in cascade conditions
+- `all_mutually_exclusive`: Whether all condition pairs are exclusive
+- `exclusive_pairs`: Count of mutually exclusive pairs
+- `total_pairs`: Total possible pairs
+
+## Usage
+
+- Cycle safety analysis
+- Topological sorting
+- Optimization detection
+- Dependency validation

data/docs/schema_metadata/declarations.md

@@ -0,0 +1,54 @@
+# Declarations Metadata
+
+Processed declaration metadata for all schema declarations (traits and values) with clean, serializable information.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+declarations = metadata.declarations
+```
+
+## Structure
+
+```ruby
+# Returns Hash<Symbol, Hash>
+{
+  declaration_name => {
+    type: :trait | :value,  # Declaration type
+    expression: String      # Human-readable expression
+  }
+}
+```
+
+## Example
+
+```ruby
+metadata.declarations
+# => {
+#   :adult => { type: :trait, expression: ">=(input.age, 18)" },
+#   :tax_amount => { type: :value, expression: "multiply(input.income, tax_rate)" },
+#   :status => { type: :value, expression: "cascade" }
+# }
+```
+
+## Raw AST Access
+
+For advanced use cases requiring direct AST manipulation:
+
+```ruby
+raw_declarations = metadata.analyzer_state[:declarations]
+# => { :adult => #<TraitDeclaration...>, :tax_amount => #<ValueDeclaration...> }
+```
+
+## AST Node Types
+
+- **TraitDeclaration**: Boolean conditions  
+- **ValueDeclaration**: Computed values or cascades
+
+## Usage
+
+- Dependency analysis
+- Code generation  
+- AST traversal
+- Type inference

data/docs/schema_metadata/dependencies.md

@@ -0,0 +1,57 @@
+# Dependencies Metadata
+
+Processed dependency information showing relationships between declarations with clean, serializable data.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+dependencies = metadata.dependencies
+```
+
+## Structure
+
+```ruby
+# Returns Hash<Symbol, Array<Hash>>
+{
+  declaration_name => [
+    {
+      to: Symbol,           # Target declaration name
+      conditional: Boolean, # True if dependency is conditional (cascade branch)
+      cascade_owner: Symbol # Optional: cascade that owns this conditional edge
+    }
+  ]
+}
+```
+
+## Example
+
+```ruby
+metadata.dependencies
+# => {
+#   :tax_amount => [
+#     { to: :income, conditional: false },
+#     { to: :deductions, conditional: false }
+#   ],
+#   :status => [
+#     { to: :adult, conditional: true, cascade_owner: :status },
+#     { to: :verified, conditional: true, cascade_owner: :status }
+#   ]
+# }
+```
+
+## Raw Edge Objects
+
+For advanced use cases requiring direct Edge object access:
+
+```ruby
+raw_dependencies = metadata.analyzer_state[:dependencies]
+# => { :tax_amount => [#<Edge to: :income>, #<Edge to: :deductions>] }
+```
+
+## Usage
+
+- Topological sorting
+- Cycle detection  
+- Evaluation planning
+- Dependency visualization

data/docs/schema_metadata/evaluation_order.md

@@ -0,0 +1,29 @@
+# Evaluation Order Metadata
+
+Topologically sorted order for safe declaration evaluation.
+
+## Structure
+
+```ruby
+state[:evaluation_order] = [:name1, :name2, :name3, ...]
+```
+
+## Example
+
+```ruby
+[:income, :deductions, :taxable_income, :tax_rate, :tax_amount, :adult, :status]
+```
+
+## Properties
+
+- Dependencies appear before dependents  
+- Handles conditional cycles in cascades
+- Deterministic ordering
+- Leaf nodes typically appear first
+
+## Usage
+
+- Compilation order
+- Evaluation sequencing  
+- Optimization planning
+- Parallel execution grouping