hakorune/docs/reference/execution-backend/mir-26-specification.md

MIR 26-Instruction Specification

Nyash Machine Intermediate Representation - ChatGPT5 Compliant Version

Overview

This document specifies the official 26-instruction set for Nyash MIR (Machine Intermediate Representation), following the ChatGPT5 specification and AI consensus from the grand meeting.

Instruction Set (26 Instructions)

Tier-0: Core Instructions (5)

1. Const - Load constant value

   %dst = const <value>
   

   Effect: pure

2. BinOp - Binary operations (includes arithmetic, logical, comparison)

   %dst = binop <op> %lhs, %rhs
   

   Effect: pure

3. Compare - Comparison operations

   %dst = icmp <op> %lhs, %rhs
   

   Effect: pure

4. Phi - SSA phi node

   %dst = phi [%bb1: %val1], [%bb2: %val2], ...
   

   Effect: pure

5. Call - Function and intrinsic calls

   %dst = call <func>(%arg1, %arg2, ...)
   call <func>(%arg1, %arg2, ...)
   

   Effect: context-dependent

Tier-0: Control Flow (3)

6. Branch - Conditional branch

   br %cond, label %then, label %else
   

   Effect: control

7. Jump - Unconditional jump

   br label %target
   

   Effect: control

8. Return - Return from function

   ret %value
   ret void
   

   Effect: control

Tier-1: Box Operations (5)

9. NewBox - Create new Box instance

   %dst = new <BoxType>(%arg1, %arg2, ...)
   

   Effect: mut

10. BoxFieldLoad - Load field from Box

    %dst = %box.field
    

    Effect: pure

11. BoxFieldStore - Store field to Box

    %box.field = %value
    

    Effect: mut

12. BoxCall - Call Box method

    %dst = call %box.method(%arg1, %arg2, ...)
    

    Effect: context-dependent

    重要な識別方法：

    • BoxCall形式: call %値.メソッド名(引数) - 値（%7など）に対してメソッドを直接呼ぶ
    • 通常のCall形式: call %関数値(%me, 引数) - 関数値を呼び、第1引数にmeを渡す

    例：

    ; BoxCall（プラグイン/ビルトインBoxのメソッド）
    %17 = call %7.open(%14, %16)
    %22 = call %7.write(%21)
    
    ; 通常のCall（ユーザー定義Boxのメソッド）
    %func = const "UserBox.method/2"
    %result = call %func(%me, %arg1)
    

13. ExternCall - Call external function

    %dst = extern_call "interface.method"(%arg1, %arg2, ...)
    

    Effect: context-dependent

Tier-1: Reference Operations (6)

14. RefGet - Get reference target

    %dst = ref_get %reference
    

    Effect: pure

15. RefSet - Set reference target

    ref_set %reference -> %new_target
    

    Effect: mut

16. WeakNew - Create weak reference

    %dst = weak_new %box
    

    Effect: pure

17. WeakLoad - Load from weak reference

    %dst = weak_load %weak_ref
    

    Effect: pure

18. WeakCheck - Check if weak reference is alive

    %dst = weak_check %weak_ref
    

    Effect: pure

19. Safepoint - GC safepoint

    safepoint
    

    Effect: io

Tier-2: Advanced Operations (7)

20. Send - Send message via Bus

    send %data -> %target
    

    Effect: io

21. Recv - Receive message from Bus

    %dst = recv %source
    

    Effect: io

22. TailCall - Tail call optimization

    tail_call %func(%arg1, %arg2, ...)
    

    Effect: control

23. Adopt - Adopt ownership

    adopt %parent <- %child
    

    Effect: mut

24. Release - Release ownership

    release %reference
    

    Effect: mut

25. MemCopy - Optimized memory copy

    memcpy %dst <- %src, %size
    

    Effect: mut

26. AtomicFence - Memory barrier

    atomic_fence <ordering>
    

    Effect: io

Deprecated Instructions (17)

The following instructions have been removed from the specification:

1. UnaryOp → Use BinOp (e.g., not %x → %x xor true)
2. Load → Use BoxFieldLoad
3. Store → Use BoxFieldStore
4. ArrayGet → Use BoxFieldLoad or Call @array_get
5. ArraySet → Use BoxFieldStore or Call @array_set
6. Print → Use Call @print
7. Debug → Use Call @debug
8. TypeCheck → Use Call @type_check
9. Cast → Use Call @cast
10. Throw → Use Call @throw
11. Catch → Use Call @catch
12. Copy → Optimization pass only
13. Nop → Not needed
14. RefNew → References handled implicitly
15. BarrierRead → Use AtomicFence
16. BarrierWrite → Use AtomicFence
17. FutureNew/FutureSet/Await → Use NewBox + BoxCall

Intrinsic Functions

Standard intrinsic functions available via Call instruction:

• @print(value) - Print value to console
• @debug(value, message) - Debug output
• @type_check(value, type) - Runtime type check
• @cast(value, type) - Type cast
• @throw(exception) - Throw exception
• @catch(type, handler) - Set exception handler
• @array_get(array, index) - Array element access
• @array_set(array, index, value) - Array element update
• @unary_neg(value) - Unary negation
• @unary_not(value) - Logical not

Effect System

Each instruction has an associated effect mask:

• pure - No side effects, can be reordered/eliminated
• mut - Mutates memory, order-dependent
• io - I/O operations, cannot be eliminated
• control - Control flow, affects program execution path

Migration Guide

UnaryOp Migration

// Before
%dst = neg %x
%dst = not %x

// After
%dst = binop sub 0, %x
%dst = binop xor %x, true

Load/Store Migration

// Before
%value = load %ptr
store %value -> %ptr

// After
%value = %box.field
%box.field = %value

Print Migration

// Before
print %value

// After
call @print(%value)

Future Operations Migration

// Before
%future = future_new %value
future_set %future = %result
%result = await %future

// After
%future = new FutureBox(%value)
call %future.set(%result)
%result = call %future.await()

Implementation Status

• ✅ Phase 1: New instruction definitions
• ✅ Phase 2: Frontend migration (AST→MIR generation)
• ✅ Phase 3: Optimization pass migration
• ✅ Phase 4: Backend implementation (VM/WASM)
• ✅ Phase 5-1: Deprecated instruction marking
• ✅ Phase 5-2: Backend rejection of deprecated instructions
• ✅ Phase 5-3: Frontend stops generating deprecated instructions
• 🔄 Phase 5-4: Test and documentation updates (in progress)
• 📋 Phase 5-5: Final verification and cleanup

---

Last updated: 2025-08-17