# XIC Instruction Semantics v1.5

**Version**: 1.5  
**Date**: 2026-05-21  
**Status**: Formal Specification

---

## Overview

XIC v1.5 is a symbolic and compressed execution virtual machine. It provides:

1. **Dual execution modes**: Compressed (via execute_gx) and symbolic (via symbolic pipeline)
2. **Explicit instruction set semantics**: Formal definitions of preconditions, postconditions, and side effects
3. **Glyph-aware symbolic processing**: Integration with LAIN 8-lane cognition and glyph metadata
4. **Context propagation**: Symbolic context flows through chains of operations

### Architecture

```
XICContext (model_path, mode, params, context, symbolic_mode, _state)
    ↓
XIC Instructions (9 ops in OP_TABLE)
    ↓
Dual paths:
    - Compressed: execute_gx() → decompresses .gx → execs Python
    - Symbolic: run_symbolic_pipeline() → LAIN 8 lanes → fused_symbol
```

---

## XICContext Model

### Fields

| Field | Type | Meaning |
|-------|------|---------|
| `model_path` | Optional[str] | Path to .gx model file. Set by LOAD_MODEL. |
| `mode` | str | Execution mode: "chat", "eval", "benchmark", "symbolic". Default: "chat". |
| `params` | Dict[str, Any] | Execution parameters (temperature, trace, profile, use_gpu, etc.). |
| `context` | Dict[str, Any] | (In params["context"]) Symbolic/cognitive context metadata (domain, style, glyph_id, etc.). |
| `symbolic_mode` | bool | True if mode == "symbolic". Controls routing in RUN_PROMPT/STREAM/CALL_GLYPH. |
| `_state` | Dict[str, Any] | Internal state: last_result, last_symbolic_result, last_symbolic_pipeline, glyph_* keys. |

### Context Propagation

- `SET_CONTEXT <key> <value>` adds/updates keys in `ctx.params["context"]`.
- Context is passed to `run_symbolic_pipeline(context=...)` in symbolic operations.
- Glyph operations add `glyph_id` to context automatically.

---

## Instruction Semantics (12 Instructions)

### 1. LOAD_MODEL

**Signature**
```json
{ "op": "LOAD_MODEL", "args": ["<path_to_gx_file>"] }
```

**Preconditions**
- Argument must be a valid string (path).

**Postconditions**
- `ctx.model_path = path`

**Side effects**
- Prints `[XIC] Model loaded: <path>`

**Symbolic behavior**
- No effect on `ctx.symbolic_mode`.

**Compressed behavior**
- `ctx.model_path` is used by RUN_PROMPT/STREAM to load the .gx file.

---

### 2. SET_MODE

**Signature**
```json
{ "op": "SET_MODE", "args": ["<mode>"] }
```

**Preconditions**
- `mode` ∈ {"chat", "eval", "benchmark", "symbolic", ...}

**Postconditions**
- `ctx.mode = mode`
- If `mode == "symbolic"`: `ctx.symbolic_mode = True`
- If `mode != "symbolic"`: `ctx.symbolic_mode = False`

**Side effects**
- Prints `[XIC] Mode set to: <mode>`

**Remarks**
- Setting mode to "symbolic" enables routing through symbolic pipeline (run_symbolic_pipeline).
- All other modes use compressed execution (execute_gx).

---

### 3. SET_PARAM

**Signature**
```json
{ "op": "SET_PARAM", "args": ["<key>", <value>] }
```

**Preconditions**
- Arguments: key (str), value (any).

**Postconditions**
- `ctx.params[key] = value`

**Side effects**
- Prints `[XIC] Parameter <key> = <value>`

**Remarks**
- `use_gpu`, `trace`, `profile` are reserved parameter names.
- Parameters are passed to execute_gx (if used).

---

### 4. SET_CONTEXT

**Signature**
```json
{ "op": "SET_CONTEXT", "args": ["<key>", <value>] }
```

**Preconditions**
- Arguments: key (str), value (any).

**Postconditions**
- `ctx.params["context"][key] = value`
- If `ctx.params["context"]` doesn't exist, it is created.

**Side effects**
- Prints `[XIC] Context <key> = <value>`

**Usage**
- Build symbolic context metadata: `SET_CONTEXT "domain" "ai"`, `SET_CONTEXT "style" "analytic"`.
- Context is passed to symbolic operations (RUN_PROMPT, STREAM, CALL_GLYPH).

---

### 5. RUN_PROMPT

**Signature**
```json
{ "op": "RUN_PROMPT", "args": ["<prompt>"] }
```

**Preconditions**
- Argument: prompt (str).

**Postconditions**
- If `ctx.symbolic_mode == True`:
  - `ctx._state["last_symbolic_result"] = output_text`
  - `ctx._state["last_symbolic_pipeline"] = SymbolicPipelineResult`
- If `ctx.symbolic_mode == False`:
  - Requires `ctx.model_path` to be set (LOAD_MODEL must be called first).
  - `ctx._state["last_result"] = ExecutionContext`

**Symbolic behavior** (ctx.symbolic_mode=True)
- Calls `run_symbolic_pipeline(prompt, context=ctx.params.get("context"))`.
- Routes through LAIN 8-lane cognition kernel.
- Prints `[XIC-SYMBOLIC] <output_text>`
- Stores full SymbolicPipelineResult for inspection (steps, fused_symbol).

**Compressed behavior** (ctx.symbolic_mode=False)
- Calls `execute_gx(ctx.model_path, trace=ctx.params.get("trace"), profile=ctx.params.get("profile"))`.
- Decompresses .gx binary and executes Python code.
- Prints `[XIC] Execution complete` and result.

**Remarks**
- The prompt argument is informational in compressed mode (not used).
- In symbolic mode, the prompt is the primary input to LAIN cognition.

---

### 6. STREAM

**Signature**
```json
{ "op": "STREAM", "args": ["<prompt>"] }
```

**Preconditions**
- Argument: prompt (str).

**Postconditions**
- Same as RUN_PROMPT, but output is streamed line-by-line.

**Symbolic behavior**
- Calls `run_symbolic_pipeline(prompt, context=...)`.
- Streams output_text line-by-line with `[XIC-STREAM]` prefix.
- Stores pipeline result in `ctx._state["last_symbolic_pipeline"]`.

**Compressed behavior**
- Calls `execute_gx(...)`.
- Streams result line-by-line with `[XIC-STREAM]` prefix.

**Side effects**
- Multiple print statements (one per line).

---

### 7. CHAIN

**Signature**
```json
{ "op": "CHAIN", "args": ["<label>"] }
```

**Preconditions**
- Argument: label (str).

**Postconditions**
- `ctx.params["chain_label"] = label`

**Side effects**
- Prints `[XIC-CHAIN] Entering chain: <label>`

**Remarks**
- CHAIN is a control marker for human readability and logging.
- It does not affect execution but allows grouping operations into named chains.
- Chain label is preserved in `ctx.params` for inspection.

---

### 8. CALL_GLYPH

**Signature**
```json
{ "op": "CALL_GLYPH", "args": ["<glyph_id>", "<payload>"] }
```

**Preconditions**
- Arguments: glyph_id (str), payload (str, optional).

**Postconditions**
- Stores result in `ctx._state[f"glyph_{glyph_id}"]` with:
  - `output_text`: Final text from cognition
  - `fused_symbol`: Fused symbolic representation (if produced)
  - `steps`: List of pipeline steps taken

**Symbolic behavior**
- Calls `run_symbolic_pipeline(prompt=payload, context=glyph_context, glyph_id=glyph_id)`.
- `glyph_context = ctx.params.get("context", {}) | {"glyph_id": glyph_id}`
- Routes through symbolic pipeline with explicit glyph_id parameter.
- The glyph_id is injected into LAIN context for glyph-aware transformations.
- Prints `[XIC-GLYPH] <output_text>`

**Compressed behavior**
- Not applicable. CALL_GLYPH is only used in symbolic mode.
- If called in compressed mode, raises error (or gracefully falls back to symbolic).

**Remarks**
- CALL_GLYPH enables glyph-aware cognition: the symbolic pipeline explicitly marks the operation as glyph-driven.
- The LAIN kernel can use glyph_id to apply glyph-specific transformations or select glyph metadata.

---

### 9. LOG

**Signature**
```json
{ "op": "LOG", "args": ["<message>"] }
```

**Preconditions**
- Argument: message (str, optional).

**Postconditions**
- None (pure side effect).

**Side effects**
- Prints `[XIC-LOG] <message>`

**Remarks**
- LOG is a no-op from an execution standpoint; purely for instrumentation and debugging.

---

### 10. PUSH_GLYPH_CONTEXT

**Signature**
```json
{ "op": "PUSH_GLYPH_CONTEXT", "args": ["<glyph_id>"] }
```

**Preconditions**
- `glyph_id` must be a valid string identifier.

**Postconditions**
- `glyph_id` is appended to `ctx.glyph_contexts` list (if not already present).
- If `ctx.glyph_contexts` reaches `max_resonance_glyphs` (default 10), further pushes are rejected by guardrails.

**Side effects**
- Prints `[XIC-MULTI-GLYPH] Pushed glyph context: <glyph_id> (total: N)`
- If guardrail triggered: prints `[XIC-GUARDRAIL] Resonance glyph count at limit (N)`

**Remarks**
- Used to accumulate glyphs for multi-glyph resonance computation.
- Duplicates are ignored (idempotent).
- Works only in symbolic mode.

---

### 11. CLEAR_GLYPH_CONTEXT

**Signature**
```json
{ "op": "CLEAR_GLYPH_CONTEXT", "args": [] }
```

**Preconditions**
- None.

**Postconditions**
- `ctx.glyph_contexts` list is emptied.

**Side effects**
- Prints `[XIC-MULTI-GLYPH] Cleared glyph context (N glyphs removed)`

**Remarks**
- Use to reset context before starting a new multi-glyph analysis chain.
- No effect if context is already empty.

---

### 12. GET_GLYPH_RESONANCE

**Signature**
```json
{ "op": "GET_GLYPH_RESONANCE", "args": ["<glyph_id>", "<metric>"] }
```

**Preconditions**
- `glyph_id` must have been previously used in a CALL_GLYPH operation.
- `metric` is optional. Valid values: "report", "global", "dominant", "weight", "lineage", "contributor", "frequency", "grammar".

**Postconditions**
- Prints formatted resonance data based on requested metric.
- Stores result in `ctx._state[f"resonance_query_{glyph_id}_{metric}"]`.

**Behavior by metric**:

| Metric | Output | Description |
|--------|--------|-------------|
| `<none>` or `"report"` | Human-readable resonance report | Formatted report with global score and top 5 glyphs by weight |
| `"global"` | Global resonance score (float) | Single float value representing overall resonance |
| `"dominant"` | List of top 5 glyphs by weight | List of (glyph_id, weight) tuples sorted descending |
| `"weight"` | Weight metric (float) | Weight component of resonance (relative importance) |
| `"lineage"` | Lineage score (float) | Score representing symbolic lineage and ancestry |
| `"contributor"` | Contributor score (float) | Score representing contribution to fusion |
| `"frequency"` | Frequency score (float) | Score representing occurrence frequency in cognition |
| `"grammar"` | Grammar score (float) | Score representing grammatical/structural alignment |

**Side effects**
- Prints `[XIC-RESONANCE] ...` with requested data.
- Stores result in `ctx._state` for programmatic access.

**Remarks**
- GET_GLYPH_RESONANCE requires prior CALL_GLYPH execution to populate glyph resonance data.
- If glyph_id not found, prints error and stores None.
- Queries access the full SymbolicPipelineResult stored by CALL_GLYPH.

---

## Glyph Resonance Structure

### FusedSymbol Data Structure

The `fused_symbol` in SymbolicPipelineResult contains:

```python
@dataclass
class FusedSymbol:
    summary: str                           # Text summary of fused cognition
    glyph_ids: List[str]                   # List of glyph IDs engaged in fusion
    resonance_map: GlyphResonanceMap       # Resonance metrics for each glyph
```

### GlyphResonanceMap

Maps glyph IDs to their resonance metrics:

```python
@dataclass
class GlyphResonanceMap:
    resonances: Dict[str, GlyphResonanceMetrics]  # glyph_id → metrics
    global_resonance_score: float                  # Overall fusion quality score [0.0, 1.0]
```

Methods:
- `get_glyph_resonance(glyph_id: str) → Optional[GlyphResonanceMetrics]`: Retrieve metrics for a specific glyph.
- `get_top_glyphs(n: int = 5) → List[tuple[str, GlyphResonanceMetrics]]`: Get top N glyphs by weight.
- `get_average_resonance() → float`: Get average resonance across all glyphs.

### GlyphResonanceMetrics

Per-glyph resonance metrics capturing multiple dimensions of symbolic activity:

```python
@dataclass
class GlyphResonanceMetrics:
    weight: float                  # Relative importance of glyph in fusion [0.0, 1.0]
    lineage_score: float          # Symbolic lineage and ancestry score [0.0, 1.0]
    contributor_score: float      # Contribution to overall fusion [0.0, 1.0]
    frequency_score: float        # Occurrence frequency in cognition [0.0, 1.0]
    grammar_score: float          # Grammatical/structural alignment [0.0, 1.0]
```

### Example Structure

```json
{
  "fused_symbol": {
    "summary": "Compression and information theory are foundational to cognition...",
    "glyph_ids": ["glyph://compression_theory", "glyph://entropy", "glyph://coding"],
    "resonance_map": {
      "global_resonance_score": 0.847,
      "resonances": {
        "glyph://compression_theory": {
          "weight": 0.95,
          "lineage_score": 0.82,
          "contributor_score": 0.89,
          "frequency_score": 0.76,
          "grammar_score": 0.88
        },
        "glyph://entropy": {
          "weight": 0.73,
          "lineage_score": 0.68,
          "contributor_score": 0.71,
          "frequency_score": 0.65,
          "grammar_score": 0.75
        }
      }
    }
  }
}
```

### Accessing Resonance Data

From XIC programs:
1. CALL_GLYPH stores result in `ctx._state[f"glyph_{glyph_id}"]` including resonance_metrics and global_resonance_score.
2. GET_GLYPH_RESONANCE queries the stored data with various metric filters.
3. Access pipeline result object via `ctx._state[f"glyph_{glyph_id}_pipeline_result"]` for direct FusedSymbol manipulation.

---

## Multi-Glyph Resonance

### Context Accumulation Model

Multi-glyph resonance enables simultaneous analysis of multiple glyphs with cross-glyph resonance metrics:

```
PUSH_GLYPH_CONTEXT "glyph://a"
PUSH_GLYPH_CONTEXT "glyph://b"
PUSH_GLYPH_CONTEXT "glyph://c"
    ↓
ctx.glyph_contexts = ["glyph://a", "glyph://b", "glyph://c"]
    ↓
CALL_GLYPH "glyph://unified" "prompt"
    ↓
run_symbolic_pipeline(prompt, glyph_ids=["glyph://a", "glyph://b", "glyph://c"])
    ↓
LAIN computes multi-glyph resonance metrics
    ↓
fused_symbol contains:
  - glyph_ids: ["glyph://a", "glyph://b", "glyph://c"]
  - resonance_map: {glyph_id → GlyphResonanceMetrics}
  - global_resonance_score: weighted average across all glyphs
```

### Workflow

1. **PUSH_GLYPH_CONTEXT**: Accumulate glyph IDs in `ctx.glyph_contexts`
2. **CALL_GLYPH**: Detects populated context, passes `glyph_ids` to pipeline
3. **run_symbolic_pipeline**: Routes to multi-glyph mode (glyph_ids parameter)
4. **execute_symbolic**: Computes multi-glyph resonance via `compute_multi_glyph_resonance()`
5. **fused_symbol**: Contains metrics for all glyphs in unified resonance space
6. **CLEAR_GLYPH_CONTEXT**: Reset context for new analysis

### Guardrails

- `max_resonance_glyphs`: Default 10, configurable via SET_PARAM
- `enable_resonance_guardrails`: Default True, set via SET_PARAM
- If `len(glyph_ids) > max_resonance_glyphs`:
  - Truncated to first N glyphs
  - SymbolicStep(kind="guardrail") recorded
  - Message printed: `[XIC-GUARDRAIL] ...`

### Telemetry

When multi-glyph CALL_GLYPH executes, telemetry stored in:

```python
ctx._state["last_resonance_stats"] = {
    "glyph_count": len(multi_glyph_ids),
    "global_resonance_score": float,
    "guardrails_triggered": [list of strings],
    "timestamp": float,
}
```

### Example: Three-Glyph Analysis

```json
{
  "op": "SET_MODE",
  "args": ["symbolic"]
}
{
  "op": "PUSH_GLYPH_CONTEXT",
  "args": ["glyph://compression"]
}
{
  "op": "PUSH_GLYPH_CONTEXT",
  "args": ["glyph://entropy"]
}
{
  "op": "PUSH_GLYPH_CONTEXT",
  "args": ["glyph://information"]
}
{
  "op": "CALL_GLYPH",
  "args": ["glyph://unified", "How do these three glyphs relate?"]
}
{
  "op": "GET_GLYPH_RESONANCE",
  "args": ["glyph://unified", "report"]
}
{
  "op": "CLEAR_GLYPH_CONTEXT",
  "args": []
}
```

Result in `ctx._state["glyph_glyph://unified"]`:
```python
{
    "multi_glyph": True,
    "output_text": "...",
    "fused_symbol": {
        "summary": "...",
        "glyph_ids": ["glyph://compression", "glyph://entropy", "glyph://information"]
    },
    "resonance_metrics": {
        "glyph://compression": {"weight": 0.95, "lineage_score": 0.82, ...},
        "glyph://entropy": {"weight": 0.73, "lineage_score": 0.68, ...},
        "glyph://information": {"weight": 0.81, "lineage_score": 0.75, ...},
    },
    "global_resonance_score": 0.83,
}
```

---

## Symbolic Pipeline Semantics

### run_symbolic_pipeline() Entrypoint

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

**Behavior**:
1. Creates SymbolicStep for initial_prompt.
2. If glyph_id is provided:
   - Adds glyph_id to context.
   - Creates SymbolicStep for glyph_call.
3. Compresses prompt via GXCompressor.compress().
4. Builds minimal manifest/segments.
5. Calls CognitiveKernel.execute_symbolic(manifest, segments, payload, mode="symbolic", context=context).
6. Extracts output_text and fused_symbol from result.
7. If fused_symbol is present:
   - Creates SymbolicStep for fusion.
8. Returns SymbolicPipelineResult(steps, output_text, fused_symbol).

### SymbolicPipelineResult

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

### SymbolicStep

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

---

## Execution Paths

### Compressed Path (ctx.symbolic_mode=False)

```
RUN_PROMPT or STREAM
    ↓
Check ctx.model_path
    ↓
execute_gx(path, trace=..., profile=...)
    ↓
Load .gx binary → decompress via GSZ3 → compile → exec Python
    ↓
Store result in ctx._state["last_result"]
```

### Symbolic Path (ctx.symbolic_mode=True)

```
RUN_PROMPT or STREAM or CALL_GLYPH
    ↓
run_symbolic_pipeline(prompt, context, glyph_id)
    ↓
Compress prompt → build manifest/segments
    ↓
CognitiveKernel.execute_symbolic()
    ↓
LAIN 8-lane cognition (structural, semantic, compression, metadata, hints, predictive, imprint, epoch)
    ↓
Fuse lanes → produce output_text and fused_symbol
    ↓
Store SymbolicPipelineResult in ctx._state["last_symbolic_pipeline"]
```

---

## Context Flow

**Example: Glyph-Aware Cognition**

```
SET_CONTEXT "domain" "ai"
SET_CONTEXT "style" "analytical"
CALL_GLYPH "glyph://knowledge_integration" "How do compression and knowledge integrate?"
```

**Flow**:
1. SET_CONTEXT adds `context = {"domain": "ai", "style": "analytical"}` to `ctx.params["context"]`.
2. CALL_GLYPH reads `context` and adds `glyph_id = "glyph://knowledge_integration"`.
3. `run_symbolic_pipeline(prompt, context={"domain": "ai", "style": "analytical", "glyph_id": "..."}, glyph_id="...")` is called.
4. Symbolic pipeline creates SymbolicStep(glyph_call, ...) with the full context.
5. LAIN kernel executes with context, allowing glyph-aware transformations.
6. Result (output_text, fused_symbol) is stored in `ctx._state["glyph_glyph://knowledge_integration"]`.

---

## Backward Compatibility

- All v1 XIC programs continue to work unchanged.
- RUN_PROMPT behavior in compressed mode (symbolic_mode=False) is identical to v1.
- New symbolic pipeline is additive and does not affect compressed execution.
- run_symbolic_prompt() in glyphos/cognitive_kernel.py is a thin wrapper around the pipeline.

---

## Summary of Changes from v1

| Change | v1 | v1.5 |
|--------|----|----|
| Symbolic pipeline abstraction | Inline in run_symbolic_prompt | Separate glyphos/symbolic_pipeline.py |
| Glyph-aware transformations | Manual context manipulation | Explicit glyph_id parameter in run_symbolic_pipeline |
| Pipeline introspection | Limited (just output_text) | Full SymbolicPipelineResult (steps, fused_symbol) |
| Formal semantics | Implicit (docstrings) | Explicit (XIC_SEMANTICS_v1_5.md) |

---

**End of Specification**