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.

{"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

{"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

{"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

{
  "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:

{"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

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 ✅