| # 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 | |
| ```emojiscript | |
| 🔢40 🔢2 ➕ ↩️ → 42 | |
| 🔢100 🔢40 ➖ ↩️ → 60 | |
| 🔢6 🔢7 ✖️ ↩️ → 42 | |
| 🔢84 🔢2 ➗ ↩️ → 42 | |
| ``` | |
| ### Bitwise | |
| ```emojiscript | |
| 🔢15 🔢7 🤝 ↩️ → 7 (AND: 1111 & 0111 = 0111) | |
| 🔢12 🔢5 👐 ↩️ → 13 (OR: 1100 | 0101 = 1101) | |
| 🔢12 🔢5 🌀 ↩️ → 9 (XOR: 1100 ^ 0101 = 1001) | |
| ``` | |
| ### Capability Gate | |
| ```emojiscript | |
| 🔢3 🔢5 🔑 ↩️ → CapGate check (slot=3, rights=5) | |
| ``` | |
| ### Control Flow | |
| ```emojiscript | |
| 🔢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:** | |
| ```json | |
| { | |
| "source": "🔢40 🔢2 ➕ ↩️" | |
| } | |
| ``` | |
| **Output:** | |
| ```json | |
| { | |
| "content": [ | |
| { | |
| "type": "text", | |
| "text": "✅ Compiled: 4 instructions\nHash: abc123def456...\nBytecode: [{:op :Push, :value 40}, ...]" | |
| } | |
| ] | |
| } | |
| ``` | |
| ### 2. `execute_emojiscript` | |
| Execute compiled bytecode. | |
| **Input:** | |
| ```json | |
| { | |
| "source": "🔢40 🔢2 ➕ ↩️", | |
| "max-steps": 10000 | |
| } | |
| ``` | |
| **Output:** | |
| ```json | |
| { | |
| "content": [ | |
| { | |
| "type": "text", | |
| "text": "✅ Result: 42\nStack: [42]\nSteps: 4 / 10000" | |
| } | |
| ] | |
| } | |
| ``` | |
| ## Runtime Implementation | |
| **File:** `src/snapkitty/lisp/emojiscript.cljs` | |
| ### Compilation | |
| ```clojure | |
| (emoji/compile-emojiscript "🔢6 🔢7 ✖️ ↩️") | |
| ; => {:source "...", :bytecode [...], :hash "...", :instructions-count 4, :valid? true} | |
| ``` | |
| ### Execution | |
| ```clojure | |
| (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: | |
| ```clojure | |
| {: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: | |
| ```bash | |
| 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/ | |