From fa1943b14bbbd93cc71687b85024eafff9bd28f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9B=B6Rei?=
 <212411920+arcjet-rei@users.noreply.github.com>
Date: Sat, 3 Oct 2026 10:09:09 -0700
Subject: [PATCH] docs: describe value representation and WIT crate coupling in
 AGENTS.md

Replace the I32FromU32 note with the rule codegen now follows: integer
lowerings emit uint32/uint64 conversions in both directions, float
lowerings depend on Direction, integer lifts are Go conversions, and
every store writes its own width. Say that changing the Go type an
instruction produces means checking every instruction that consumes it,
and point at the memory example that covers the memory paths.

Drop wit-bindgen-core's stale version number, and note that wit-bindgen,
wit-bindgen-core and wit-component must move as one matched set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 380eb08..b5fcab9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -134,9 +134,10 @@ the `examples/` directory before the Go tests will compile.
 
 - **WIT (WebAssembly Interface Types)**: The interface definition language for
   the Component Model. Gravity reads WIT embedded in Core Wasm files.
-- **wit-bindgen-core**: Bytecode Alliance library (v0.53.1) that Gravity depends
-  on for canonical ABI instruction generation. It provides the `Instruction`
-  enum that `func.rs` handles.
+- **wit-bindgen-core**: Bytecode Alliance library (version pinned in
+  `cmd/gravity/Cargo.toml`) that Gravity depends on for canonical ABI
+  instruction generation. It provides the `Instruction` enum that `func.rs`
+  handles.
 - **Direction (Import vs Export)**: Gravity generates different code depending on
   whether a function is an import (Go host function called by Wasm guest) or an
   export (Wasm guest function called from Go). The `Func` struct tracks this via
@@ -158,10 +159,20 @@ the `examples/` directory before the Go tests will compile.
 
 ### Important Implementation Details
 
-- `I32FromU32` and `U32FromI32` instructions are identity operations at the Wasm
-  level (both are 32-bit integers). They use simple `uint32()` casts, NOT
-  `api.EncodeU32()`/`api.DecodeU32()`. The `uint64` conversion needed for
-  `api.Function.Call()` is handled separately by the `CallWasm` instruction.
+- **Value representation.** Lowering instructions produce Go values of the core
+  Wasm type their consumer expects. Integer lowerings (`I32FromS32`,
+  `I32FromU8`, …, `I64FromS64`) emit plain `uint32(x)`/`uint64(x)` conversions
+  in both directions, and `CallWasm` widens every export argument with
+  `uint64(...)`. Float lowerings depend on `Direction`: imports pass
+  `float32`/`float64` through, because a host function's Go signature is its
+  Wasm signature, while exports encode the IEEE bits with
+  `api.EncodeF32`/`EncodeF64`. Integer lifts are Go conversions (`int8(x)`,
+  `uint16(x)`), which accept both the `uint64` that `CallWasm` returns and the
+  narrower value a load produces. Every store writes exactly its own width with
+  an explicit conversion. When you change the Go type an instruction produces,
+  check every instruction that consumes it (stores, `VariantLower`, `CallWasm`)
+  in both directions. The `memory` example sends every scalar type through all
+  four memory paths.
 - Import functions with simple return types (bool, enum) that map to Wasm i32
   results use `resolve_wasm_type()` on `wasm_sig.results` to determine the Go
   return type.
@@ -180,6 +191,12 @@ the `examples/` directory before the Go tests will compile.
 | clap             | CLI argument parsing                     |
 | trycmd           | CLI snapshot testing (dev)               |
 
+`wit-bindgen`, `wit-bindgen-core` and `wit-component` move as one set: each
+`wit-bindgen` release requires exactly one `wit-parser`/`wit-component` minor
+(read `wit-bindgen-rust`'s dependencies on crates.io), and two `wit-parser`
+versions in one build fail to compile with mismatched `Resolve`/`World` types.
+Bump every example's pins with them.
+
 ## Style & Conventions
 
 - Use conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.