382 lines
10 KiB
Markdown
382 lines
10 KiB
Markdown
|
# 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** ✅
|