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

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

// 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

// 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

<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

/* 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:

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

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