# XIC v1.5 Symbolic Pipeline Extension Report

**Date**: 2026-05-21  
**Status**: ✅ Complete and validated  
**Scope**: Symbolic pipeline abstraction + glyph-aware transformations + formal semantics

---

## Executive Summary

Extended XIC v1 to v1.5 with:

1. **Symbolic Pipeline Abstraction** (`glyphos/symbolic_pipeline.py`)
   - Explicit pipeline with step tracking
   - Data structures: SymbolicStep, SymbolicPipelineResult
   - Function: `run_symbolic_pipeline(prompt, context, glyph_id)`

2. **Glyph-Aware Transformations**
   - CALL_GLYPH now routes through pipeline with explicit glyph_id
   - Context includes glyph metadata for LAIN kernel
   - Fused symbols captured in results

3. **Formal Semantics Specification** (`XIC_SEMANTICS_v1_5.md`)
   - Complete instruction semantics for all 9 ops
   - Preconditions, postconditions, side effects
   - Context model and pipeline flow
   - Backward compatibility guarantees

**Zero breaking changes**. All XIC v1 programs work unchanged.

---

## Phase 1: Symbolic Pipeline Abstraction

### File: `glyphos/symbolic_pipeline.py`

#### Data Structures

```python
@dataclass
class SymbolicStep:
    name: str                        # e.g., "initial_prompt", "glyph:xyz", "fusion"
    kind: str                        # "prompt", "glyph_call", "fused_symbol"
    payload: Any                     # Step data
    context: Dict[str, Any]          # Context at this step

@dataclass
class SymbolicPipelineResult:
    steps: List[SymbolicStep]        # Execution steps taken
    output_text: str                 # Final text output
    fused_symbol: Optional[Dict]     # Fused symbolic representation
```

#### Core Function

```python
def run_symbolic_pipeline(
    prompt: str,
    context: Optional[Dict[str, Any]] = None,
    glyph_id: Optional[str] = None,
) -> SymbolicPipelineResult
```

**Behavior**:
1. Creates SymbolicStep for initial_prompt
2. If glyph_id: adds glyph_id to context, creates glyph_call step
3. Compresses prompt → GSZ3
4. Builds minimal manifest/segments
5. Calls `CognitiveKernel.execute_symbolic(manifest, segments, payload, mode="symbolic", context=...)`
6. Extracts output_text and fused_symbol
7. If fused_symbol: creates fusion step
8. Returns SymbolicPipelineResult

**Integration with Cognitive Kernel**:
- Uses existing `CognitiveKernel.execute_symbolic()` API
- Wraps it with step tracking and glyph-aware routing
- No circular imports (lazy import in glyphos/cognitive_kernel.py)

---

## Phase 2: Glyph-Aware Transformations

### Integration Points

#### 1. RUN_PROMPT

```python
def op_RUN_PROMPT(ctx, *args):
    if ctx.symbolic_mode:
        pipeline_result = run_symbolic_pipeline(
            prompt=prompt,
            context=ctx.params.get("context")
        )
        ctx._state["last_symbolic_pipeline"] = pipeline_result
```

**Stores**:
- `last_symbolic_result`: output_text string
- `last_symbolic_pipeline`: full SymbolicPipelineResult

#### 2. STREAM

Same routing as RUN_PROMPT, but streams output line-by-line.

#### 3. CALL_GLYPH

```python
def op_CALL_GLYPH(ctx, *args):
    glyph_id = str(args[0])
    payload = str(args[1]) if len(args) > 1 else ""
    
    glyph_context = dict(ctx.params.get("context", {}))
    glyph_context["glyph_id"] = glyph_id
    
    pipeline_result = run_symbolic_pipeline(
        prompt=payload,
        context=glyph_context,
        glyph_id=glyph_id,
    )
    
    ctx._state[f"glyph_{glyph_id}"] = {
        "output_text": pipeline_result.output_text,
        "fused_symbol": pipeline_result.fused_symbol,
        "steps": [step metadata...]
    }
```

**Stores**:
- Key: `glyph_{glyph_id}`
- Value: Dict with output_text, fused_symbol, steps

### Context Propagation

```
SET_CONTEXT "domain" "glyph_cognition"
SET_CONTEXT "style" "analytic"
CALL_GLYPH "glyph://compression" "prompt..."
    ↓
context = {"domain": "glyph_cognition", "style": "analytic", "glyph_id": "glyph://compression"}
    ↓
run_symbolic_pipeline(prompt, context, glyph_id)
    ↓
LAIN kernel processes with glyph-aware context
```

---

## Phase 3: XIC Instruction Semantics v1.5

### File: `XIC_SEMANTICS_v1_5.md`

Comprehensive formal specification covering:

1. **Overview**: Dual execution modes (compressed/symbolic), architecture
2. **XICContext model**: Field definitions, context propagation
3. **Instruction semantics**: All 9 ops with:
   - Signature (JSON form)
   - Preconditions
   - Postconditions
   - Side effects
   - Symbolic vs compressed behavior
4. **Symbolic pipeline semantics**: run_symbolic_pipeline, SymbolicPipelineResult, SymbolicStep
5. **Execution paths**: Compressed and symbolic flowcharts
6. **Context flow**: Example of glyph-aware cognition
7. **Backward compatibility**: v1 → v1.5 changes

### Key Changes from v1

| Aspect | v1 | v1.5 |
|--------|----|----|
| Pipeline implementation | Inline in run_symbolic_prompt | Separate glyphos/symbolic_pipeline.py |
| Glyph support | Manual context manipulation | Explicit glyph_id parameter |
| Step tracking | None | Full SymbolicStep list |
| Result structure | String only | SymbolicPipelineResult (steps + fused_symbol) |
| Formal spec | Docstrings | XIC_SEMANTICS_v1_5.md |

---

## Phase 4: Demo Program and Validation

### Demo Program: `programs/demo_symbolic_pipeline.gx.json`

```json
{
  "instructions": [
    { "op": "SET_MODE", "args": ["symbolic"] },
    { "op": "SET_CONTEXT", "args": ["domain", "glyph_cognition"] },
    { "op": "SET_CONTEXT", "args": ["style", "analytic"] },
    { "op": "CHAIN", "args": ["glyph_analysis"] },
    { "op": "LOG", "args": ["Starting glyph-aware symbolic pipeline"] },
    { "op": "CALL_GLYPH", "args": ["glyph://compression", "..."] },
    { "op": "RUN_PROMPT", "args": ["..."] }
  ]
}
```

### Validation Results (7/7 Tests Passed)

✅ Symbolic pipeline module imports  
✅ run_symbolic_pipeline() execution  
✅ Glyph-aware pipeline (glyph_id parameter)  
✅ Demo symbolic pipeline program  
✅ CALL_GLYPH result storage (output_text, fused_symbol, steps)  
✅ Backward compatibility (demo_chat.gx.json)  
✅ run_symbolic_prompt() wrapper works  

---

## Architecture

### Module Hierarchy

```
glyphos/
  ├── cognitive_kernel.py      (CognitiveKernel, get_kernel, run_symbolic_prompt wrapper)
  ├── symbolic_pipeline.py      (SymbolicStep, SymbolicPipelineResult, run_symbolic_pipeline)
  ├── events.py               (EventBus, emit, on)
  └── __init__.py             (exports all)

xic_ops.py
  └── Uses: run_symbolic_pipeline (lazy import inside ops)
       └── RUN_PROMPT, STREAM, CALL_GLYPH route through pipeline
```

### Data Flow (Symbolic Mode)

```
XIC Program
    ↓
RUN_PROMPT / STREAM / CALL_GLYPH
    ↓
run_symbolic_pipeline(prompt, context, glyph_id)
    ↓
[Step 1] Initial prompt
[Step 2] Glyph call (if glyph_id present)
[Step 3] Compress + build manifest
[Step 4] CognitiveKernel.execute_symbolic()
[Step 5] LAIN 8-lane cognition
[Step 6] Fusion step (if fused_symbol present)
    ↓
SymbolicPipelineResult
    ├── steps: [...SymbolicStep...]
    ├── output_text: str
    └── fused_symbol: Dict | None
    ↓
Store in ctx._state
```

---

## Backward Compatibility

✅ **XIC v1 programs work unchanged**:
- demo_chat.gx.json executes identically
- execute_gx() behavior preserved
- Compressed mode execution path unchanged

✅ **run_symbolic_prompt() thin wrapper**:
- Existing code importing run_symbolic_prompt() still works
- Now routes through pipeline (transparent upgrade)

✅ **No binary format changes**:
- .gx files unchanged
- JSON manifest format unchanged
- GXIC1 magic and version unchanged

---

## Files Modified or Created

### Created

| File | Purpose |
|------|---------|
| glyphos/symbolic_pipeline.py | Symbolic pipeline abstraction |
| XIC_SEMANTICS_v1_5.md | Formal instruction semantics spec |
| programs/demo_symbolic_pipeline.gx.json | Demo of glyph-aware pipeline |

### Modified

| File | Changes |
|------|---------|
| glyphos/__init__.py | +export SymbolicStep, SymbolicPipelineResult, run_symbolic_pipeline |
| glyphos/cognitive_kernel.py | run_symbolic_prompt() → thin wrapper around pipeline |
| xic_ops.py | op_RUN_PROMPT, op_STREAM, op_CALL_GLYPH → use pipeline |

### Unchanged (Backward Compatibility)

- xic_loader.py
- xic_vm.py
- xic_executor.py
- runtime_executor/runner.py
- All .gx binary files

---

## Key Design Decisions

### 1. Separate Pipeline Module (symbolic_pipeline.py)

**Rationale**: Makes pipeline structure explicit and testable. Enables step tracking without modifying core kernel.

### 2. SymbolicPipelineResult with Steps

**Rationale**: Supports introspection, debugging, and future enhancements (e.g., step replay, conditional routing).

### 3. Explicit glyph_id Parameter

**Rationale**: Makes glyph-aware cognition intentional and traceable. Simplifies context propagation.

### 4. Formal Semantics Specification

**Rationale**: Documents contract clearly for tool builders, enables static analysis, serves as implementation guide.

---

## Usage Examples

### Example 1: Symbolic Mode with Context

```bash
glyph --xic -c "
SET_MODE symbolic
SET_CONTEXT domain compression_theory
SET_CONTEXT style analytical
RUN_PROMPT 'Explain lossy compression as a glyph.'
"
```

### Example 2: Glyph-Aware Cognition

```bash
glyph --xic programs/demo_symbolic_pipeline.gx.json
```

Results in:
- `ctx._state["glyph_glyph://compression"]` with output_text, fused_symbol, steps
- Full execution trace via SymbolicPipelineResult

---

## Testing

All validation tests pass:

```
[TEST 1] Symbolic pipeline module imports ✅
[TEST 2] run_symbolic_pipeline() execution ✅
[TEST 3] Glyph-aware pipeline (glyph_id parameter) ✅
[TEST 4] Demo symbolic pipeline program ✅
[TEST 5] CALL_GLYPH result storage ✅
[TEST 6] Backward compatibility ✅
[TEST 7] run_symbolic_prompt() wrapper ✅
```

---

## References

- **Formal Specification**: See `XIC_SEMANTICS_v1_5.md` for complete instruction semantics
- **Previous Reports**: `XIC_SYMBOLIC_EXTENSION_REPORT.md` documents symbolic mode v1
- **Cognitive Kernel**: `glyphos/cognitive_kernel.py` (CognitiveKernel.execute_symbolic API)

---

## Summary

XIC v1.5 extends the v1 engine with:
- Explicit symbolic pipeline abstraction
- Glyph-aware transformations with context propagation
- Formal instruction semantics specification
- Full backward compatibility

**No breaking changes**. All XIC v1 programs continue to work unchanged.

---

**Implementation Complete** ✅  
**All tests passing** ✅  
**Backward compatible** ✅  
**Formal semantics documented** ✅