2125_GCE/XIC_V2_QUICK_REFERENCE.md

# XIC v2 Control Flow - Quick Reference

## Operations Summary

### IF - Conditional Branching
```
IF <predicate> <then_label> [<else_label>]
```
**What it does**: Evaluates a predicate and branches to different chains
**When to use**: Decision points based on resonance scores, glyph presence, etc.

```json
{"op": "IF", "args": ["fused.global_resonance_score > 0.8", "analysis_deep", "analysis_simple"]}
```

### MATCH - Pattern Matching
```
MATCH <path> <pattern> <then_label>
```
**What it does**: Checks if a pattern matches a fused symbol field
**When to use**: Looking for specific glyphs in resonance map

```json
{"op": "MATCH", "args": ["fused.glyph_ids", "glyph://entropy", "entropy_found"]}
```

### LOOP - Iterative Execution
```
LOOP <predicate> <body_label> [max_iter]
```
**What it does**: Repeatedly runs a chain while predicate is true
**When to use**: Iterative refinement, convergence detection

```json
{"op": "LOOP", "args": ["fused.global_resonance_score > 0.6", "refine_step", 5]}
```

---

## Predicate Syntax

### Fields
Access fused symbol fields with dot notation:
```
fused.global_resonance_score  # float 0.0-1.0
fused.glyph_ids               # list of strings
fused.glyph_count             # integer
```

### Operators
```
>   Greater than
<   Less than
>=  Greater or equal
<=  Less or equal
==  Equal
!=  Not equal
and Boolean AND
or  Boolean OR
not Boolean NOT
```

### Examples
```
fused.global_resonance_score > 0.8
fused.global_resonance_score > 0.8 and fused.glyph_count > 1
fused.global_resonance_score <= 0.3 or fused.glyph_count < 2
not (fused.global_resonance_score < 0.5)
```

### Helper Functions
```
dominant_contains('glyph://id')  # Check if glyph in dominant list
```

Example:
```
dominant_contains('glyph://entropy')
dominant_contains('glyph://compression') and fused.global_resonance_score > 0.7
```

---

## Complete Program Example

```json
{
  "magic": "GXIC1",
  "version": 1,
  "entrypoint": "main",
  "symbols": {
    "main": 0,
    "loop_body": 7,
    "high_path": 11,
    "low_path": 14,
    "end": 16
  },
  "instructions": [
    {"op": "SET_MODE", "args": ["symbolic"]},
    {"op": "SET_CONTEXT", "args": ["domain", "analysis"]},
    {"op": "PUSH_GLYPH_CONTEXT", "args": ["glyph://a"]},
    {"op": "PUSH_GLYPH_CONTEXT", "args": ["glyph://b"]},
    
    {"op": "LOOP", "args": ["fused.global_resonance_score > 0.5", "loop_body", 3]},
    
    {"op": "CHAIN", "args": ["loop_body"]},
    {"op": "RUN_PROMPT", "args": ["Refine the analysis"]},
    
    {"op": "IF", "args": ["fused.global_resonance_score > 0.8", "high_path", "low_path"]},
    
    {"op": "CHAIN", "args": ["high_path"]},
    {"op": "LOG", "args": ["High resonance detected"]},
    {"op": "RUN_PROMPT", "args": ["Detailed analysis"]},
    {"op": "CHAIN", "args": ["end"]},
    
    {"op": "CHAIN", "args": ["low_path"]},
    {"op": "LOG", "args": ["Lower resonance - trying different approach"]},
    {"op": "RUN_PROMPT", "args": ["Alternative analysis"]},
    {"op": "CHAIN", "args": ["end"]},
    
    {"op": "CHAIN", "args": ["end"]},
    {"op": "LOG", "args": ["Control flow complete"]}
  ]
}
```

---

## Parameters

Set limits with `SET_PARAM`:

```json
{"op": "SET_PARAM", "args": ["max_loop_iterations", 5]}
{"op": "SET_PARAM", "args": ["max_total_steps", 100]}
```

**Default Values:**
- `max_loop_iterations`: 50
- `max_total_steps`: 1000

---

## Testing Your Control Flow

```python
from xic_loader import XICProgram
from xic_vm import run_xic_program

# Load your program
prog = XICProgram.from_json_file("your_program.gx.json")

# Execute
ctx = run_xic_program(prog)

# Check results
print(ctx._state.get("control_steps"))        # Control decisions made
print(ctx._state.get("guardrails"))           # Guardrails triggered
print(ctx._state.get("symbolic_steps"))       # All execution steps
```

---

## Troubleshooting

### "Chain 'xyz' not found"
- Make sure you have a `CHAIN` instruction with the label name
- Check spelling exactly matches

### "Predicate evaluation error"
- Check syntax: `fused.field_name` (not `fused['field_name']`)
- Verify field exists in fused symbol
- Test with simpler predicate first

### "Guardrail triggered"
- Loop exceeded max iterations: increase `max_loop_iterations`
- Total steps exceeded: increase `max_total_steps`
- Check predicate doesn't always evaluate true

### Control flow not executing
- Verify `CHAIN` labels match between ops and chain names
- Check execution with `ctx._state["symbolic_steps"]`
- Enable `LOG` ops to trace execution path

---

## Performance Tips

1. **Keep predicates simple** - Complex boolean logic slows evaluation
2. **Set reasonable loop limits** - High max_loop_iterations can timeout
3. **Use MATCH for frequent checks** - Simpler than IF with complex predicates
4. **Monitor total_steps** - Long programs may hit max_total_steps

---

## Integration with FedMart

Control flow steps automatically:
- Appear in telemetry events
- Display in dashboard timeline
- Contribute to symbolic steps tracking
- Trigger guardrail alerts when limits hit

---

## Next Steps

1. Review example programs:
   - `programs/demo_control_flow_if.gx.json`
   - `programs/demo_control_flow_loop.gx.json`

2. Check test suite:
   - `tests/test_control_flow.py`

3. Read full documentation:
   - `XIC_V2_CONTROL_FLOW_SUMMARY.md`

---

**XIC v2 Control Flow - Ready to Use** ✅