3038 Constraint Rules 949137d0

---
name: constraint-rules
description: Reference guide for constraint propagation rules in typed holes refactoring including dependency tracking and solution space narrowing. Use as reference when propagating constraints between resolved holes.
---

# Constraint Propagation Rules

Complete guide to constraint propagation in typed holes refactoring.

## Overview

When a hole is resolved, its resolution creates constraints that propagate to dependent holes. This narrows the solution space and discovers new requirements.

## Propagation Rule Types

### 1. Interface Resolution → Type Constraints

**Pattern**: Concrete types flow to consumers

**Rule**:
```
IF: Interface hole resolved with type T
THEN: All consumers must handle type T
```

**Example 1: Async Interface**
```python
# Resolution of R3_abstraction_layers
class NodeInterface:
    async def run(self, context: Context) -> Result
    
# Propagates to:
R4_parallel_execution:
    MUST handle async/await
    MUST use asyncio for concurrency
    
R5_error_handling:
    MUST catch async exceptions
    MUST use try/except with async context
    
R7_testing:
    MUST use pytest-asyncio
    MUST test async behavior
```

**Example 2: Generic Types**
```python
# Resolution of R2_module_boundaries  
class Repository(Protocol[T]):
    def get(self, id: str) -> T
    def save(self, entity: T) -> None

# Propagates to:
R4_implementations:
    MUST provide type parameter
    MUST implement both methods with consistent T
    
R7_testing:
    MUST test with concrete types
    MUST verify type safety
```

### 2. Implementation → Performance Constraints

**Pattern**: Resource usage flows to dependent operations

**Rule**:
```
IF: Implementation uses N resources
THEN: Dependent operations share/compete for N resources
```

**Example 1: Concurrency Limits**
```python
# Resolution of R4_parallelization
parallel_executor = {
    "max_concurrent": 3,
    "strategy": "asyncio.gather"
}

# Propagates to:
R8_rate_limiting:
    rate_limit = provider_limit / 3
    
R9_memory_budget:
    memory_per_operation * 3 < total_memory
    
R10_connection_pool:
    pool_size >= 3
    
R7_testing:
    MUST test with max_concurrent operations
    MUST verify no race conditions
```

**Example 2: Cache Size**
```python
# Resolution of R5_caching_strategy
cache = {
    "max_size": 1000,
    "eviction": "LRU",
    "ttl": 3600
}

# Propagates to:
R9_memory_budget:
    cache_memory = 1000 * avg_entry_size
    total_memory >= cache_memory + operation_memory
    
R4_key_design:
    MUST design keys for good hit rate
    MUST handle cache invalidation
    
R7_testing:
    MUST test cache hit/miss scenarios
    MUST test eviction behavior
```

### 3. Validation → Test Requirements

**Pattern**: Test needs flow upstream

**Rule**:
```
IF: Validation requires N test cases
THEN: Test data and metrics must support N cases
```

**Example 1: Optimization Validation**
```python
# Resolution of R8_optimization_testing
validation = {
    "required_examples": 50,
    "statistical_significance": 0.05,
    "comparison_metric": "accuracy"
}

# Propagates to:
R6_test_data:
    MUST collect >= 50 labeled examples
    MUST ensure diversity in examples
    
R7_metrics:
    MUST support batch evaluation
    MUST compute statistical significance
    
R9_infrastructure:
    MUST support running 50+ test cases
    MUST store results for comparison
```

**Example 2: Performance Testing**
```python
# Resolution of R9_performance_validation
perf_tests = {
    "required_scenarios": 20,
    "iterations_per_scenario": 100,
    "metrics": ["latency_p50", "latency_p99", "throughput"]
}

# Propagates to:
R7_test_infrastructure:
    MUST support benchmark harness
    MUST collect timing data
    
R6_test_data:
    MUST have 20 representative scenarios
    
R8_monitoring:
    MUST track same metrics in production
```

### 4. Dependency Resolution → Implementation Constraints

**Pattern**: Chosen dependencies constrain implementations

**Rule**:
```
IF: Dependency D chosen with version V
THEN: Implementation must be compatible with D@V
```

**Example 1: Framework Choice**
```python
# Resolution of R2_testing_framework
testing = {
    "framework": "pytest",
    "version": "7.4.0",
    "plugins": ["pytest-asyncio", "pytest-cov"]
}

# Propagates to:
R7_test_writing:
    MUST use pytest fixtures
    MUST use pytest-asyncio for async tests
    
R8_ci_config:
    MUST install pytest 7.4.0
    MUST run pytest command
    
R4_async_implementation:
    CAN use asyncio (pytest-asyncio supports it)
```

**Example 2: Library Version**
```python
# Resolution of R3_http_client
http = {
    "library": "httpx",
    "version": "0.24.0",
    "features": ["async", "http2"]
}

# Propagates to:
R4_api_implementations:
    MUST use httpx.AsyncClient
    CAN use HTTP/2 features
    
R5_error_handling:
    MUST handle httpx exceptions
    MUST handle httpx.TimeoutException
    
R6_testing:
    MUST mock httpx (not requests)
    CAN use httpx.MockTransport
```

### 5. Architecture → Module Constraints

**Pattern**: Architecture rules flow to all modules

**Rule**:
```
IF: Architecture defines layer L with rules R
THEN: All modules in L must follow R
```

**Example 1: Layered Architecture**
```python
# Resolution of R1_target_architecture
architecture = {
    "layers": ["api", "domain", "data"],
    "rules": {
        "api": {
            "can_import": ["domain"],
            "cannot_import": ["data"]
        },
        "domain": {
            "can_import": [],
            "cannot_import": ["api", "data"]
        },
        "data": {
            "can_import": ["domain"],
            "cannot_import": ["api"]
        }
    }
}

# Propagates to:
R2_all_modules:
    MUST respect layer import rules
    
R4_new_modules:
    MUST be assigned to a layer
    MUST follow that layer's rules
    
R7_testing:
    MUST test layer violation detection
    test_no_layer_violations()
```

**Example 2: Dependency Direction**
```python
# Resolution of R1_dependency_flow
flow = {
    "direction": "top-down",
    "rule": "Higher layers depend on lower, never reverse"
}

# Propagates to:
R4_all_implementations:
    abstractions in lower layers
    implementations in higher layers
    
R5_interfaces:
    defined in lower layers
    consumed by higher layers
```

## Constraint Discovery

Sometimes resolving a hole discovers NEW constraints:

**Example: Discovering Resource Limits**
```python
# Resolution of R4_parallelization
# Attempts max_concurrent=10

# During testing, discovers:
- Provider rate limit = 30 req/min
- Memory per operation = 500MB
- Total memory = 4GB

# This DISCOVERS new constraints:
R4_updated:
    max_concurrent <= min(
        30 / requests_per_operation,  # Rate limit
        4000 / 500,  # Memory limit (=8)
        10  # Desired
    ) = 8

# And PROPAGATES:
R8_rate_limiting:
    MUST implement backoff for rate limits
    
R9_memory_management:
    MUST monitor memory usage
    MUST fail fast if memory exceeded
```

## Contradiction Detection

If constraints contradict, stop and resolve:

**Example: Conflicting Requirements**
```python
# R4_performance resolved
constraint_1 = "latency < 100ms"

# R5_security resolved  
constraint_2 = "encrypt all data (adds 150ms overhead)"

# CONFLICT DETECTED:
# Cannot satisfy both constraints simultaneously

# Resolution options:
1. Relax performance: latency < 200ms
2. Optimize encryption: use hardware acceleration
3. Parallelize: encrypt async, don't block main path
4. Compromise: encrypt at rest, not in transit

# Document decision in REFACTOR_IR.md
```

## Propagation Algorithm

```python
def propagate_constraints(resolved_hole, resolution):
    """Propagate constraints from resolved hole to dependents"""
    
    # 1. Extract constraints from resolution
    new_constraints = extract_constraints(resolution)
    
    # 2. Find dependent holes
    dependents = get_dependent_holes(resolved_hole)
    
    # 3. For each dependent
    for dependent in dependents:
        # Apply each propagation rule
        for constraint in new_constraints:
            rule = match_propagation_rule(constraint, dependent)
            if rule:
                # Add constraint to dependent
                dependent.constraints.add(
                    apply_rule(rule, constraint)
                )
                
                # Narrow solution space
                dependent.solution_space = filter(
                    dependent.solution_space,
                    lambda s: satisfies(s, constraint)
                )
        
        # Check if dependent is now over-constrained
        if is_unsatisfiable(dependent):
            raise ContradictionError(dependent, new_constraints)
        
        # Update dependent documentation
        update_refactor_ir(dependent)
    
    # 4. Check for newly resolvable holes
    newly_ready = find_ready_holes()
    return newly_ready
```

## Practical Examples

### Full Propagation Chain

```python
# Resolve R1: target_architecture
resolution_R1 = {
    "layers": ["api", "domain", "infrastructure"],
    "principle": "dependency inversion"
}

# Propagates to R2: module_boundaries
constraint_R2 = "domain must not depend on infrastructure"

# Resolve R2: module_boundaries
resolution_R2 = {
    "domain": ["core", "services", "interfaces"],
    "infrastructure": ["repositories", "external_apis"]
}

# Propagates to R3: abstraction_layers
constraint_R3 = "domain defines repository interfaces"

# Resolve R3: abstraction_layers
resolution_R3 = {
    "RepositoryProtocol": "defined in domain/interfaces"
}

# Propagates to R4: implementations
constraint_R4 = "infrastructure implements RepositoryProtocol"

# Resolve R4: implementations
resolution_R4 = {
    "PostgresRepository": "implements RepositoryProtocol in infrastructure"
}

# Propagates to R7: testing
constraint_R7 = "test domain with mock repositories"

# Full chain:
R1 → R2 → R3 → R4 → R7
```

## Constraint Validation

After propagation, validate all constraints:

```python
def validate_all_constraints():
    """Check that all constraints are satisfiable"""
    
    for hole in all_holes:
        # Check local constraint satisfaction
        if not are_satisfiable(hole.constraints):
            raise ContradictionError(hole)
        
        # Check global constraint interaction
        for other_hole in all_holes:
            if conflicts(hole.constraints, other_hole.constraints):
                raise GlobalContradictionError(hole, other_hole)
    
    return True
```

---

## Summary

Constraint propagation is the heart of typed holes refactoring:

1. **Extract** constraints from each resolution
2. **Propagate** to dependent holes via rules
3. **Narrow** solution spaces
4. **Discover** new constraints
5. **Detect** contradictions early
6. **Validate** continuously

This ensures that each hole resolution is informed by all previous decisions, maintaining global consistency throughout the refactoring process.