A reversible computation virtual machine implemented in ReScript + Deno
[](LICENSE) [](LICENSE-PALIMPSEST.txt) [](https://rescript-lang.org/) [](https://deno.land/) [](https://rhodium.dev/)
Idaptik is a reversible computation virtual machine where every operation can be perfectly undone. It’s designed for:
-
🧩 Logic puzzles - Solve puzzles by forward and backward execution
-
↩️ Undo systems - Build robust undo/redo functionality
-
🔬 Reversible algorithms - Explore reversible computing concepts
-
🎓 Education - Learn about time-reversible computation
-
✅ 5 Core Instructions: ADD, SUB, SWAP, NEGATE, NOOP
-
✅ Perfect Reversibility: Every operation is perfectly undoable
-
✅ Type Safety: ReScript’s sound type system prevents errors
-
✅ Zero Dependencies: No npm, no node_modules, just Deno + ReScript
-
✅ Puzzle System: JSON-based puzzle definitions
-
✅ CLI Interface: Full command-line interface with demo and tests
-
✅ Comprehensive Build System: 40+ Just recipes for all tasks
= Install Deno (JavaScript runtime)
curl -fsSL https://deno.land/install.sh | sh
= Install ReScript (compiler)
npm install -g rescript
= Install Just (task runner)
cargo install just # OR: sudo dnf install just= 1. Check dependencies
just doctor
= 2. Build the project
just build
= 3. Run demonstration
just demoExpected output:
[INFO] Starting reversible VM demo...
[INFO] Initial state: x=5, y=3, z=0
[INFO] Executing: ADD x y (x = x + y)
Current State: { x: 8, y: 3, z: 0 }
[INFO] Executing: SWAP x z
Current State: { x: 0, y: 3, z: 8 }
[INFO] Executing: NEGATE y
Current State: { x: 0, y: -3, z: 8 }
[INFO] Now reversing operations...
[INFO] Undoing NEGATE y
Current State: { x: 0, y: 3, z: 8 }
[INFO] Undoing SWAP x z
Current State: { x: 8, y: 3, z: 0 }
[INFO] Undoing ADD x y
Current State: { x: 5, y: 3, z: 0 }
[SUCCESS] Demo complete! Notice how undo perfectly reversed all operations.-
[MIGRATION-GUIDE.md](MIGRATION-GUIDE.md) - Complete guide from TypeScript to ReScript
-
[CONVERSION-SUMMARY.md](CONVERSION-SUMMARY.md) - Detailed conversion report
-
[justfile](justfile) - All available commands (run
just help)
= Show help
deno run --allow-read src/CLI.res.js help
= Run demonstration
deno run --allow-read src/CLI.res.js demo
= Run tests
deno run --allow-read src/CLI.res.js test
= Run puzzle (TODO: implement)
deno run --allow-read src/CLI.res.js run vault_7= Core commands
just build # Compile ReScript → JavaScript
just clean # Remove artifacts
just watch # Auto-rebuild on changes
= Development
just dev # Development mode
just run # Run CLI
just demo # Run demo
just test # Run tests
= Quality
just format # Format code
just lint # Lint code
just verify # Full verification (build + test + lint)
just ci # Complete CI pipeline
= Puzzles
just list-puzzles # List all puzzles
just puzzle <name> # Run specific puzzle
just create-puzzle <n> # Create new puzzle
= Information
just status # Project status
just stats # Code statistics
just help # Detailed helpAliases: b (build), c (clean), r (run), d (demo), t (test), w (watch)
| Instruction | Syntax | Operation | Inverse | Example |
|-------------|--------|-----------|---------|---------|
| ADD | ADD a b | a = a + b | a = a - b | ADD x y → x=15 (if x=10, y=5) |
| SUB | SUB a b | a = a - b | a = a + b | SUB x y → x=5 (if x=10, y=5) |
| SWAP | SWAP a b | swap values | swap again | SWAP x y → x=5, y=10 (if x=10, y=5) |
| NEGATE | NEGATE a | a = -a | negate again | NEGATE x → x=-10 (if x=10) |
| NOOP | NOOP | (nothing) | (nothing) | NOOP → no change |
All instructions are perfectly reversible - running the inverse restores the exact previous state.
idaptik-reversible/
├── src/
│ ├── core/
│ │ ├── Instruction.res # Instruction interface
│ │ ├── State.res # State management
│ │ ├── VM.res # Virtual machine
│ │ └── instructions/
│ │ ├── Add.res
│ │ ├── Sub.res
│ │ ├── Swap.res
│ │ ├── Negate.res
│ │ └── Noop.res
│ └── CLI.res # Command-line interface
├── data/
│ └── puzzles/
│ ├── vault_7.json
│ └── vault_defuse.json
├── rescript.json # ReScript config
├── deno.json # Deno config
├── justfile # Build system (600+ lines!)
├── .gitignore # Updated for ReScript + Deno
├── MIGRATION-GUIDE.md # Migration documentation
├── CONVERSION-SUMMARY.md # Conversion report
└── README-NEW.md # This file// Create initial state
let state = State.createState(~variables=["x", "y"], ~initialValue=0)
Js.Dict.set(state, "x", 10)
Js.Dict.set(state, "y", 5)
// Create VM
let vm = VM.make(state)
// Execute forward
VM.run(vm, Add.make("x", "y")) // x = 15
VM.run(vm, Swap.make("x", "y")) // x = 5, y = 15
// Execute backward (undo)
VM.undo(vm) // Undo SWAP: x = 15, y = 5
VM.undo(vm) // Undo ADD: x = 10, y = 5{
"name": "My Puzzle",
"description": "Get x to 100",
"initialState": {
"x": 0,
"y": 10,
"z": 5
},
"goalState": {
"x": 100,
"y": 10,
"z": 5
},
"maxMoves": 20,
"instructions": [
{"type": "ADD", "args": ["x", "y"]},
{"type": "SUB", "args": ["x", "z"]},
{"type": "SWAP", "args": ["x", "z"]}
]
}Save as data/puzzles/my_puzzle.json, then run:
just puzzle my_puzzle-
[ReScript](https://rescript-lang.org/) - Sound type system, compiles to JavaScript
-
[Deno](https://deno.land/) - Modern, secure JavaScript runtime
-
[Just](https://github.com/casey/just) - Powerful command runner
| Aspect | Benefit |
|--------|---------|
| No Dependencies | Zero npm packages, no node_modules (saves ~100MB) |
| Type Safety | ReScript’s sound types catch errors at compile time |
| Security | Deno’s explicit permissions (--allow-read, etc.) |
| Performance | Fast compilation, optimized JavaScript output |
| Developer Experience | Excellent error messages, fast feedback loop |
= Run all tests
just test
= Expected output:
[INFO] Running instruction tests...
[SUCCESS] ✓ ADD test passed
[SUCCESS] ✓ ADD invert test passed
[SUCCESS] ✓ SWAP test passed
[SUCCESS] ✓ SWAP invert test passed
[SUCCESS] All tests passed!Tests verify: - ✓ Forward execution correctness - ✓ Inverse execution correctness - ✓ Perfect reversibility (forward then inverse = identity)
This is a demonstration project showing ReScript + Deno integration. To extend it:
-
Add new instructions: Create
src/core/instructions/MyInstruction.res -
Add new puzzles: Create JSON files in
data/puzzles/ -
Extend CLI: Modify
src/CLI.res
-
✓ ReScript core modules
-
✓ Basic instructions (ADD, SUB, SWAP, NEGATE, NOOP)
-
✓ CLI interface
-
✓ Test suite
-
✓ Comprehensive build system
-
❏ Implement puzzle loader
-
❏ Add more complex instructions (XOR, ROL, ROR, etc.)
-
❏ Conditional execution
-
❏ Loop constructs (reversible loops!)
-
❏ Visualization mode
Reversible computing is based on the principle that computation can be performed without losing information. Key concepts:
-
Landauer’s Principle: Irreversible operations dissipate energy
-
Bennett’s Reversible Turing Machine: Computation can be reversible
-
Janus Language: First practical reversible programming language
-
Quantum Computing: Quantum gates are inherently reversible
-
Low-Power Computing: Reversible circuits use less energy
-
Debugging: Perfect undo for debugging complex systems
-
Cryptography: Reversible operations in encryption
-
[Reversible Computing - Wikipedia](https://en.wikipedia.org/wiki/Reversible_computing)
-
[Landauer’s Principle](https://en.wikipedia.org/wiki/Landauer%27s_principle)
-
[Janus Language](https://en.wikipedia.org/wiki/Janus_(time-reversible_computing_programming_language))
Dual Licensed: MIT OR Palimpsest License v0.8
This project is dual-licensed - you may use it under either license at your choice:
Permissive, widely compatible open source license. - ✅ Commercial use allowed - ✅ Modification allowed - ✅ Distribution allowed - ✅ Private use allowed
See [LICENSE](LICENSE) for full MIT License text.
Audit-grade, consent-aware, provenance-rich license for responsible software development. - ✅ Same freedoms as MIT - ➕ Provenance tracking encouraged - ➕ Ethical use guidelines - ➕ Audit trail support
See [LICENSE-PALIMPSEST.txt](LICENSE-PALIMPSEST.txt) for full Palimpsest License text.
The original v1.0.0 TypeScript implementation was AGPL-3.0. For compatibility, the AGPL-3.0 text is preserved in [license.txt](license.txt).
Note: v2.0.0 (ReScript/Deno) uses MIT OR Palimpsest - much more permissive!
Choose MIT if: - You want maximum compatibility - You need a widely-recognized OSS license - You prefer simple, battle-tested terms
Choose Palimpsest if: - You value provenance and audit trails - You want ethical use guidelines - You’re building consent-aware systems - You want to support the Rhodium Standard
In practice: Both licenses permit the same uses. Pick whichever fits your needs!
-
ReScript Team - Excellent type system and compiler
-
Deno Team - Modern, secure JavaScript runtime
-
Just Maintainers - Powerful command runner
-
Reversible Computing Community - Pioneering research