EMOJISCRIPT.md

Ahmad's EmojiScript — Bytecode Dialect

High-performance emoji-based programming language compiled to bytecode and executed on a stack-based VM. Part of the SNAP OS sovereign runtime and now integrated into the Clojure Lisp MCP.

Overview

EmojiScript is Ahmad's low-level bytecode language where each instruction is a single emoji (potentially multi-codepoint). Programs compile to SigilOp bytecode and execute on the SoulVM with cryptographic sealing to the WORM chain.

EmojiScript source → lex() → bytecode → execute() → result + WORM seal

The 15 Instructions

Stack Operations

Emoji	Name	Description	Example
🔢<digits>	Push	Push number literal (i64)	🔢42

Binary Operators (pop 2, push result)

Emoji	Name	Description
➕	Add	Integer addition
➖	Sub	Integer subtraction
✖️ (or ✖ or ❌)	Mul	Integer multiplication
➗	Div	Integer division (raises on /0)
🤝 (or 🔗)	And	Bitwise AND
👐 (or 🔀)	Or	Bitwise OR
🌀 (or ⊕)	Xor	Bitwise XOR

Control Flow

Emoji	Name	Args	Description
➡️	Jump	target (i64)	Unconditional jump to PC
❓	JumpIf	target (i64)	Jump if top-of-stack ≠ 0, pop predicate
↩️ (or 🔙 or 🔚)	Ret	—	Return & halt execution

Capability & Memory

Emoji	Name	Args	Description
🔑	CapGate	slot (i64), rights (i64)	Capability proof check (pops 2 args)
⚡	Call	func_idx (i64)	Indirect function call (future)
🏗️	Alloc	size (i64), type_tag (i64)	Allocate memory (pops 2 args)
📤	Load	offset (i64)	Load from memory (pops 1 arg)
📦	Store	offset (i64)	Store to memory (pops 1 arg)

Future Semantic Passes (Sprint 2)

Emoji	Name	Routes To	Purpose
🌊	Stream	telemetry-bus	Emit telemetry event (reserved)
🧠	PolicyCheck	policy-immune	Check policy constraint (reserved)
🔒	Seal	bifrost	Explicit WORM seal hint (reserved)
🔓	ReadOnly	bifrost-policy	Downgrade rights hint (reserved)

Syntax

Programs are whitespace-separated emoji tokens. Numbers follow 🔢:

🔢40 🔢2 ➕ ↩️

Parsing rules:

• Each emoji is a single grapheme cluster (handles multi-codepoint emoji)
• Whitespace (space, tab, newline) is ignored
• Numbers: 🔢 followed immediately by ASCII digits (no separator)
• Arguments are written before their opcode
  • Example: 🔢3 🔢5 🔑 means "push 3, push 5, then execute CapGate(3, 5)"
  • Args are popped in reverse order (last arg pushed = first arg consumed)

Examples

Arithmetic

🔢40 🔢2 ➕ ↩️          → 42
🔢100 🔢40 ➖ ↩️        → 60
🔢6 🔢7 ✖️ ↩️           → 42
🔢84 🔢2 ➗ ↩️          → 42

Bitwise

🔢15 🔢7 🤝 ↩️         → 7 (AND: 1111 & 0111 = 0111)
🔢12 🔢5 👐 ↩️         → 13 (OR: 1100 | 0101 = 1101)
🔢12 🔢5 🌀 ↩️         → 9 (XOR: 1100 ^ 0101 = 1001)

Capability Gate

🔢3 🔢5 🔑 ↩️          → CapGate check (slot=3, rights=5)

Control Flow

🔢1 ❓ ↩️               → Jump if predicate ≠ 0
🔢10 ➡️ ↩️             → Unconditional jump to PC 10

MCP Tools

Three new MCP tools expose EmojiScript:

1. compile_emojiscript

Compile source to bytecode.

Input:

{
  "source": "🔢40 🔢2 ➕ ↩️"
}

Output:

{
  "content": [
    {
      "type": "text",
      "text": "✅ Compiled: 4 instructions\nHash: abc123def456...\nBytecode: [{:op :Push, :value 40}, ...]"
    }
  ]
}

2. execute_emojiscript

Execute compiled bytecode.

Input:

{
  "source": "🔢40 🔢2 ➕ ↩️",
  "max-steps": 10000
}

Output:

{
  "content": [
    {
      "type": "text",
      "text": "✅ Result: 42\nStack: [42]\nSteps: 4 / 10000"
    }
  ]
}

Runtime Implementation

File: src/snapkitty/lisp/emojiscript.cljs

Compilation

(emoji/compile-emojiscript "🔢6 🔢7 ✖️ ↩️")
; => {:source "...", :bytecode [...], :hash "...", :instructions-count 4, :valid? true}

Execution

(let [compiled (emoji/compile-emojiscript "🔢40 🔢2 ➕ ↩️")]
  (emoji/execute-emojiscript (:bytecode compiled) :max-steps 10000))
; => {:result 42, :stack [42], :steps 4, :halted? true}

Stack-Based Interpreter

• Stack: Mutable vector, push/pop operations
• PC (Program Counter): Jump targets are bytecode indices
• Registers: None (pure stack machine)
• Memory: Stubs (future implementation)
• Step Limit: Prevents infinite loops (default 10,000)

Error Handling

• Parse errors: Unknown emoji, missing arguments, invalid numbers
• Runtime errors: Division by zero, unknown instructions, step limit exceeded
• Graceful degradation: Future semantic tokens (🌊, 🧠, 🔒, 🔓) skip execution

Bytecode Format

Each instruction is a ClojureScript map:

{:op :Push :value 42}
{:op :Add}
{:op :CapGate :slot 3 :rights 5}
{:op :Jump :target 10}
{:op :Load :offset 0}
{:op :Store :offset 8}
{:op :Ret}

Instruction fields:

• :op — Instruction type (keyword)
• :value — For :Push, the i64 literal
• :slot, :rights — For :CapGate
• :func — For :Call, function table index
• :size, :type-tag — For :Alloc
• :offset — For :Load, :Store
• :target — For :Jump, :JumpIf, bytecode index

Testing

Run integration tests:

npm test

Tests cover:

• Compilation of all 15 opcodes
• Execution of arithmetic, bitwise, control flow
• Error cases: empty program, unknown emoji, division by zero
• Step limit enforcement
• MCP tool integration

Performance Notes

• Compilation: O(n) in source length, single pass
• Execution: O(instructions), typical 1-10µs per instruction
• Memory: Minimal (stack + bytecode vector)
• Future: Link to SoulVM JIT (Cranelift) for native code generation

Design Principles

1. Emoji as first-class syntax: Every instruction is a single grapheme cluster
2. Argument-before-opcode: Enables post-fix compilation and clarity
3. Stack machine: No registers, minimal state, deterministic
4. Stateless lexer: Grapheme-by-grapheme parsing, Unicode-aware
5. Extensible: Semantic-pass tokens allow future subsystems without breaking existing code

Future Work (Sprint 2+)

• Memory ops: Implement :Load, :Store, :Alloc
• Function calls: Implement :Call with function tables
• Semantic passes: Route 🌊, 🧠, 🔒, 🔓 to subsystems
• JIT compilation: Link to SoulVM Cranelift backend
• WORM sealing: Bifrost signing of execution results
• ScratchBlocks visual editor: Drag-drop blocks ↔ sync emoji text

References

• Ahmad's EmojiScript (Rust): https://github.com/SNAPKITTYWEST/snap-os/blob/main/craft-crypto/src/emoji.rs
• SNAP OS: https://github.com/SNAPKITTYWEST/snap-os
• SoulVM: https://github.com/SNAPKITTYWEST/snap-os/blob/main/soulvm
• Unicode Graphemes: https://unicode.org/reports/tr29/