docs/METAPROGRAMMING.md

# SnapKitty Meta-Programming Systems

**Every code generator, template system, DSL, and schema in the repository.**

---

## Overview

SnapKitty uses meta-programming in four distinct layers:

| Layer | Purpose | Deterministic | Produces |
|-------|---------|:-------------:|---------|
| XSLT 1.0 | XML spec → Rust/C/HTML | Yes | Source code |
| Python compilers | XML/scene → SVG + pipeline | Yes | Visualization + execution order |
| DSL assembler (.rasm) | Assembly source → bytecode | Yes | Binary bytecode |
| Formal spec containers | XML wrapping type signatures | N/A | Archival + codegen routing |

---

## 1. XSLT Pipeline (7 + 1 Transforms)

**Location:** `xslt/` and `generated/`

Every XSLT transform is:
- XSLT 1.0 (maximum compatibility)
- Deterministic (pure functional transforms, no side effects)
- Annotated with `AUTO-GENERATED` comment in output
- Validated by embedding invariants in the generated code itself

### constraint-dsl-to-rust.xsl

**Input:** `<HyperKittyConstraintDSL version="...">` XML  
**Output:** Rust source — `Agent` struct, `UniverseLedger`, `validity_predicate`

**Generated invariants** (cannot be removed without changing the XML spec):
```rust
pub fn validity_predicate(entry: &JournalEntry) -> bool {
    entry.delta_a + entry.delta_e == entry.delta_l + entry.delta_r  // balance
    && entry.entropy_nats <= 0.20                                    // entropy bound
    && entry.proof_valid                                              // proof gate
}
```

The `0.20` is read from `<EntropyBound>` in the input XML at transform time.

### sla-to-rust.xsl

**Input:** `<SymbolicLedgerAlgebra version="...">` XML  
**Output:** Rust `Lambda` type with algebraic invariants baked in

```rust
// AUTO-GENERATED from SymbolicLedgerAlgebra
impl Lambda {
    pub fn new(s: u64, delta: i64, omega: i64) -> Self {
        Self { s, delta, iota: -delta, omega }  // iota = -delta: balance axiom
    }
    pub fn reconciliation(&self) -> i64 { self.delta + self.iota }  // must == 0
    pub fn is_valid(&self) -> bool { self.reconciliation() == 0 }
}
pub const ENTROPY_NATS: f64 = 0.20;  // from XML Meta/Entropy
```

The `ENTROPY_NATS` constant is extracted from the XML's `<Meta><Entropy>` field.

### qlg-to-rust.xsl

**Input:** QLG spec XML  
**Output:** Rust routing certificate generator

```rust
// AUTO-GENERATED by qlg-to-rust.xsl
// Theorem: encode_produces_valid_frame holds by construction
pub fn generate_routing_certs(family: QLGFamily) -> Vec<QLGCertificate> {
    // 6 witness vectors: ±Pi, ±Gamma, ±Delta routes
```

The comment "Theorem: ... holds by construction" is the meta-program's assertion that the generated code satisfies a formal property.

### agent-dsl-a.xsl (DSL-A)

**Input:** `<AGENT_MSG>` XML (per `dsl/agent-msg.dtd`)  
**Output:** `<dispatch>` XML with proof verification inline

```xml
<verified>
  <xsl:choose>
    <xsl:when test="string-length(proof) = 64">true</xsl:when>
    <xsl:otherwise>false</xsl:otherwise>
  </xsl:choose>
</verified>
```

A 64-character proof field = SHA-256 hex. The XSLT validates this structurally.

### agent-dsl-b.xsl (DSL-B)

**Input:** `<RUNTIME_REQ>` XML  
**Output:** Routing directive to `native/hyperkitty-c` or `wasm/pkg/`

This is the **backend selector** — the same XML request routes to different execution targets based on the `target` attribute (`c99 | wasm | auto`).

### generate-readme.xsl + generate-site.xsl

**Input:** HyperKitty `hk:` namespace XML  
**Output:** Markdown README (with badge tables, agent fabric table, status table) + HTML site

Documentation is generated from the same source as the code. When the XML spec changes, both documentation and implementation update together.

### generate-native-config.xsl

**Input:** `QUANTUM-KITTY` XML  
**Output:** C header `generated_config.h` with `hk_agent_*`, `hk_route_*`, `hk_ledger_config`, `hk_sla_bounds` structs

```c
/* GENERATED FILE — do not edit by hand */
```

---

## 2. Python XML Compilers

### xml2svg.py — Scene Compiler

**Input → Output:** `<scene>` XML → SVG string  
**Pipeline:** XML → `xml.etree.ElementTree` → `SVGNode` IR tree → SVG string  
**Validated:** Tag whitelist (`{rect, circle, line, path, text, group}`)  
**Role:** Visualization only — descriptive, not executable

### constraint_graph_svg.py — DAG Compiler

**Input → Output:** `<graph>` XML → (SVG visualization, executable pipeline dict)

**The pipeline dict IS the execution order:**
```python
{ "pipeline": ["input", "memory", "retrieval", "transform", "constraint", "proof", "output"] }
```

This is the point where XML specification becomes an executable artifact. The topological ordering is Kahn's algorithm — cycle detection is structural validation.

---

## 3. .rasm Assembler (Full DSL Compiler Pipeline)

**DSL Name:** Resonance Assembly Language  
**Location:** `snapkitty-resonance-isa/`  
**Crates:** `abjad` (lexer/parser) → `ir` (lowering) → `assembler` (bytecode)

**8 opcodes (A–H):**
| Opcode | Name | Description |
|--------|------|-------------|
| A | LOAD | Load register from address |
| B | STORE | Store register to address |
| C | COMPARE | Compare against threshold |
| D | BRANCH | Conditional branch (fail-safe) |
| E | ENTER | Enter scope (first instruction) |
| F | FREEZE | WORM-seal state (immutable) |
| G | SIGNAL | Emit coherence signal, increment resonance |
| H | HALT | Terminate execution |

**Example program** (`examples/resonance.rasm`):
```
E field_core           ; ENTER: open scope
A trust_vector         ; LOAD: trust field
A entropy_register     ; LOAD: entropy field
C entropy_register 0.21 ; COMPARE: entropy <= 0.21?
D fail_safe_branch     ; BRANCH: if > threshold, jump
G resonance_signal     ; SIGNAL: emit coherence pulse
F seal_state           ; FREEZE: WORM seal
H                      ; HALT
```

The `0.21` threshold is the same invariant (`ENTROPY_THRESHOLD = 0.21`) enforced by the VM at runtime.

**Compilation pipeline:**
```
.rasm source
  ↓
abjad/src/lib.rs  (lexer: tokenize lines, skip comments)
  ↓
ir/src/lib.rs  (lowering: validate Enter at 0, Halt at end)
  ↓
assembler/src/lib.rs  (encode: ByteWord { opcode: u8, operand: hash })
  ↓
binary bytecode  (Vec<ByteWord>)
  ↓
vm/src/lib.rs  (execute with entropy gate at 0.21)
```

**Validated:** Structural invariants (Enter at position 0, Halt at end) enforced in `ir` crate.

---

## 4. Formal Spec Containers (XML wrapping proofs)

### SEB Chain Determinism Invariant

**Path:** `seb/verification/lean4/SEB_CHAIN_DETERMINISM_INVARIANT.xml`

A polyglot XML document that simultaneously contains:
1. A mathematical description of the chain determinism property
2. A complete Idris 2 module in a CDATA block (computable)
3. Proof sketch (tactic steps: `simp`, `induction`, `rw`, `funext`)
4. Codegen routing table: `Ada → seb_kernel.ads`, `Rust → code/T0/primitives`, `Erlang → seb_partition_mgr.erl`
5. Test module in Idris 2

This XML file is not executed directly. It is a **specification artifact** that routes different downstream consumers (Lean/Idris proof checkers, Rust/Ada/Erlang code generators, test frameworks) to the same formal source of truth.

### System Schemas

**`schemas/agent.xsd`** — agent state machine (IDLE/ACTIVE/BLOCKED/COMPLETED/ERROR) with legal transitions  
**`schemas/runtime-event.xsd`** — WORM event format with SHA-256 integrity  
**`schemas/hyper-kitty-system.xsd`** — full system manifest

These are structural validators — consuming code that violates the schema fails at parse time.

---

## 5. Agent Prompt Templates

**Path:** `bob-ide/artifacts/bridges/xml-compiler-skeletons/sovereign_prompt.xml`

```xml
<system_prompt>
  <identity>{{IDENTITY}}</identity>
  <logic_gates>
    <gate><name>{{GATE_1_NAME}}</name>
          <condition>{{GATE_1_CONDITION}}</condition>
          <action>{{GATE_1_ACTION}}</action></gate>
  </logic_gates>
  <execution_flow>
    <step><order>1</order><instruction>{{STEP_1}}</instruction></step>
  </execution_flow>
</system_prompt>
```

Mustache-style template. When instantiated, the `<logic_gates>` become the agent's behavioral constraints. **This is executable metadata** — the template controls agent behavior when filled in.

---

## The Core Meta-Programming Pattern

SnapKitty's meta-programming follows a consistent pattern:

```
XML specification
     │
     ├─── XSLT transform ──→ Source code (Rust/C/HTML/Markdown)
     │                         (entropy bound baked into generated code)
     │
     ├─── Python parser  ──→ Runtime objects + execution order
     │                         (entropy threshold as Python float)
     │
     └─── Formal extractor ─→ Lean 4 / Idris 2 type signatures
                               (proof obligations derived from spec)
```

**The invariant `H ≤ 0.20` travels through all three paths:**
- In XSLT: embedded as literal `0.20` in generated `validity_predicate`
- In Python: parsed as `HKEntropyBound.bound = 0.20` controlling `ConstraintPass`
- In Lean 4: proved as the main theorem in `EntropyBound.lean`
- In .rasm: expressed as `C entropy_register 0.21` assembly instruction
- In Rust VM: hardcoded as `ENTROPY_THRESHOLD: f64 = 0.21`

**This is the strongest evidence that metadata is executable in SnapKitty:** the same mathematical constraint flows from the XML specification through code generation, formal proof, and assembly language, with the same numeric value appearing in all layers.

---

## What Is Generated Automatically?

| Artifact | Generator | From |
|----------|-----------|------|
| `UniverseLedger.rs` | `constraint-dsl-to-rust.xsl` | `HyperKittyConstraintDSL.xml` |
| `Lambda` Rust type | `sla-to-rust.xsl` | `SymbolicLedgerAlgebra.xml` |
| Routing cert Rust code | `qlg-to-rust.xsl` | QLG spec XML |
| `generated_config.h` | `generate-native-config.xsl` | `QUANTUM-KITTY.xml` |
| SVG visualization | `constraint_graph_svg.py` | `constraint_graph.xml` |
| Pipeline execution order | `constraint_graph_svg.py` | `constraint_graph.xml` |
| Binary bytecode | `.rasm` assembler | `.rasm` source file |
| Agent system prompts | Template instantiation | `sovereign_prompt.xml` |
| README + site docs | `generate-readme.xsl`, `generate-site.xsl` | HyperKitty XML |

**What is manually authored:** the XML specifications themselves, the XSLT stylesheets, the formal proofs, the Lean 4 + Agda source.