Implement IR-based runtime with unified memory model and generated builtins

[Copilot]

IR-based runtime with unified memory model and generated builtins

Problem

Memory layout defined inconsistently across three locations caused struct size mismatches (33KB vs 65KB) and field offset corruption. Handwritten LLVM IR was brittle and diverged from Rust Context struct. Runtime builtin functions needed to be generated as LLVM IR (per ADR-001) instead of being compiled from Rust.

Changes

New jet_ir crate:

• Unified Types<'ctx> struct containing all LLVM types
• Shared constants (WORD_SIZE_BYTES, STACK_SIZE_BYTES, etc.)
• Single source of truth for type definitions

RuntimeBuilder - Full IR Generation:

• Generates LLVM IR programmatically using Inkwell
• Generates 8 runtime builtin functions as IR:
  • Stack operations: push.i256, push.ptr, pop, peek, swap
  • Memory operations: load, store.word, store.byte
• Declares forward references for external functions (contract calls, crypto)

Unified memory model:

• exec_ctx uses pointer-based {ptr, len, cap} representation (ADR-002)
• Rust Context heap-allocates memory buffer
• Both runtime and contract builders use shared Types from jet_ir

Documentation:

• ADR-002: Architectural decision record for pointer-based memory
• Layout tests: Use enums instead of magic numbers for field indices
• Runtime architecture documentation describes current state

Impact

• Correctness: Eliminates memory corruption from layout mismatches
• ADR-001 Compliance: Runtime functions now generated as IR, not compiled Rust
• Performance: Generated IR can be optimized by LLVM
• Maintainability: Type changes propagate automatically through shared Types

Implementation Details

IR-Generated Functions (8):

• jet.stack.push.i256 - Push i256 value onto stack
• jet.stack.push.ptr - Push word by pointer onto stack
• jet.stack.pop - Pop word from stack
• jet.stack.peek - Peek at stack element
• jet.stack.swap - Swap stack elements
• jet.mem.load - Load word from memory
• jet.mem.store.word - Store word to memory
• jet.mem.store.byte - Store byte to memory

External Rust Functions (3):

• Contract calls (complex invocation logic)
• Return data copy (context management)
• Keccak256 (requires sha3 crate)

Notes

• Memory layout definitions reduced: 3 → 2
• Layout verification tests added with enum-based field indices
• ADDRESS_SIZE_BYTES: 20 bytes (EVM standard)

Original prompt

Read these two documents detailing issues related to the same topic:

docs/adrs/adr-001.md
docs/layout-mismatch-analysis.md

The first document explains our decision on handling EVM's 256-bit words. We decided to define all runtime functions using LLVM IR instead of Rust, avoiding handwritten IR difficulties. We'll create the runtime with IR built by Rust using the Inkwell IR builder. This lets us use LLVM's 256-bit semantics while benefiting from Rust's strong typing by developing types and patterns for LLVM IR.

The second document discusses conflicting memory model definitions in our code. It's defined in Rust-based runtime code, handwritten IR for 256-bit integers, and the IR builder context, which contains in-runtime types.

To address the first issue, we're changing the runtime to be fully IR-based but built by Rust. It should fully replace the existing Rust and IR runtime code, aligning with the second document's memory layout guidance. This reduces the memory layout definition from three instances to two. The new runtime code, using the Inkwell builder, will need the type and function registry from the IR builder context, offering a chance to unify our memory model definitions. It will be unified in types holding LLVM type and function data, emitting IR defining the runtime.

Runtime and contract generation codes will remain separate in their crates. Chat_runtime will generate the runtime, and builder code will stay in the builder package of the chat crate. Common components might be shared in a new crate. If needed, the builder code could move to its own crate, separate from the runtime. The main chat crate would depend on the runtime and builder crates, both relying on a common crate, possibly chat_IR, housing the type and function registry and IR context. The builder might become the contract builder, while the runtime becomes the runtime builder. This is a chance to resolve two architectural issues with a single, interconnected change.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
crates/jet/src/bin/jetdbg.rs	45% smaller
crates/jet_runtime/src/exec.rs	12% smaller
crates/jet_runtime/src/lib.rs	7% smaller
Cargo.toml	Unsupported file format
crates/jet/Cargo.toml	Unsupported file format
crates/jet/src/builder/env.rs	0% smaller
crates/jet/src/engine/mod.rs	0% smaller
crates/jet_ir/Cargo.toml	Unsupported file format
crates/jet_ir/src/constants.rs	0% smaller
crates/jet_ir/src/lib.rs	0% smaller
crates/jet_ir/src/types.rs	0% smaller
crates/jet_runtime/Cargo.toml	Unsupported file format
crates/jet_runtime/src/builtins.rs	0% smaller
crates/jet_runtime/src/layout_tests.rs	0% smaller
crates/jet_runtime/src/runtime_builder.rs	0% smaller
docs/adrs/adr-002.md	Unsupported file format
docs/architecture-refactoring-summary.md	Unsupported file format
runtime-ir/jet.ll	Unsupported file format

[tcrypt25519]

I mentioned a few times throughout my comments there being 80+ files that were changed, which is what it said when I started writing the comments. I see it's now down to 18, which is a much more reasonable number. So I don't want to go through and update everywhere I said that, but I do want to say here that whatever exactly changed from when I started leaving these comments until now seems to have been a positive direction.

[Copilot]

Pull request overview

This PR implements ADR-001 and resolves critical memory layout mismatches by creating an IR-based runtime architecture with a unified memory model. The changes introduce a new jet_ir crate containing shared LLVM type definitions, implement a RuntimeBuilder that programmatically generates 8 runtime builtin functions as LLVM IR, and migrate the execution context to a pointer-based memory representation.

Changes:

• Created new jet_ir crate with unified Types struct and shared constants
• Implemented RuntimeBuilder to generate 8 runtime functions as IR (stack operations: push.i256, push.word, pop, peek, swap; memory operations: load, store.word, store.byte)
• Migrated Context struct from inline array to pointer-based memory layout with heap allocation and Drop implementation
• Fixed ADDRESS_SIZE_BYTES from 2 to 20 bytes (EVM standard)
• Removed handwritten runtime functions from builtins.rs (now generated as IR)
• Updated engine to use RuntimeBuilder instead of loading runtime-ir/jet.ll
• Created ADR-002 documenting pointer-based memory decision
• Added layout verification tests

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Cargo.toml	Added jet_ir to workspace members
crates/jet_ir/*	New crate with unified Types and constants
crates/jet_runtime/src/runtime_builder.rs	New RuntimeBuilder generating 8 IR functions
crates/jet_runtime/src/exec.rs	Pointer-based memory with heap allocation and Drop
crates/jet_runtime/src/builtins.rs	Removed stack/memory functions (now IR-generated)
crates/jet_runtime/src/lib.rs	Re-exports from jet_ir for backward compatibility
crates/jet_runtime/src/layout_tests.rs	New layout verification tests
crates/jet_runtime/Cargo.toml	Added jet_ir dependency
crates/jet/src/engine/mod.rs	Uses RuntimeBuilder instead of loading jet.ll
crates/jet/src/builder/env.rs	Uses shared Types from jet_ir
crates/jet/src/bin/jetdbg.rs	Fixed coinbase address to 20 bytes
crates/jet/Cargo.toml	Added jet_ir dependency
docs/adrs/adr-002.md	Documents pointer-based memory decision
docs/architecture-refactoring-summary.md	Comprehensive refactoring documentation
runtime-ir/DEPRECATED.md	Deprecation notice for jet.ll
IMPLEMENTATION_COMPLETE.md	Implementation completion summary

[tcrypt25519]

@copilot Fix these issues:

---

Fix function name mismatch for stack push

File: crates/jet_runtime/src/runtime_builder.rs
Lines: (around function creation shown)

Comment: The IR function is created with the name jet.stack.push.word, but the symbol constant FN_STACK_PUSH_PTR expects jet.stack.push.ptr. This mismatch will cause a runtime lookup failure.

Suggested change from reviewer:

Change the function name passed to add_function to match the symbol
constant defined in symbols.rs (use "jet.stack.push.ptr").

---

Correct runtime function count in IMPLEMENTATION_COMPLETE.md

File: IMPLEMENTATION_COMPLETE.md
Lines: +190 to +192

Comment: The documentation claims only jet.stack.push.i256 is generated as IR, but the implementation actually generates eight IR runtime functions.

Suggested change from reviewer:

Replace the statement about a single IR function with an accurate list:

• jet.stack.push.i256
• jet.stack.push.word
• jet.stack.pop
• jet.stack.peek
• jet.stack.swap
• jet.memory.load
• jet.memory.store.word
• jet.memory.store.byte

Clarify that remaining runtime behavior still uses Rust builtins and that
additional IR helpers can be added incrementally.

---

Update “Future Work” section to reflect current IR coverage

File: docs/architecture-refactoring-summary.md

Comment: The “Future Work” section says only jet.stack.push.i256 exists as IR, but eight IR runtime functions are already implemented.

Suggested change from reviewer:

Update the bullet to list the currently implemented IR runtime functions:

• jet.stack.push.i256
• jet.stack.push.word
• jet.stack.pop
• jet.stack.peek
• jet.stack.swap
• jet.mem.load
• jet.mem.store.word
• jet.mem.store.byte

[Copilot]

@copilot Fix these issues:

...

Fixed all three issues in commit 436ad86:

1. Changed function name from jet.stack.push.word to jet.stack.push.ptr to match the FN_STACK_PUSH_PTR symbol constant
2. Updated IMPLEMENTATION_COMPLETE.md to list all 8 IR-generated runtime functions
3. Updated architecture-refactoring-summary.md to list all 8 IR-generated runtime functions

The documentation now accurately reflects that 8 runtime functions are generated as IR, not just one.

[tcrypt25519]

@copilot Fix the rest of your dogshit code. I left you comments on the ones that I saw, but there's probably more, so please, after you fix the things that I called out, look over everything you did, realize how much of it sucks, and fix anything that you are cognitively able to do.

[Copilot]

@copilot Fix the rest of your dogshit code. I left you comments on the ones that I saw, but there's probably more, so please, after you fix the things that I called out, look over everything you did, ...

Fixed all issues in commits f275036 and 1db91e8:

• Removed all transition/change comments
• Removed backward compatibility mentions
• Rewrote architecture doc to describe current state
• Removed IMPLEMENTATION_COMPLETE.md, DEPRECATED.md, and unused jet.ll
• Cleaned up redundant project name mentions