2125_GCE/XIC_SEMANTICS_v1_5.md

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

1. LOAD_MODEL

Signature

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

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

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

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

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

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

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

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

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

Signature

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

@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:

@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:

@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

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

---

Symbolic Pipeline Semantics

run_symbolic_pipeline() Entrypoint

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

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

SymbolicStep

@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