WIP

Author: GordonSmith

.github/copilot-instructions.md

@@ -0,0 +1,34 @@
+## Repository focus
+- Header-only C++20 implementation of the WebAssembly Component Model canonical ABI; public surface aggregates through `include/cmcpp.hpp` and the `cmcpp` namespace.
+- Core work revolves around marshaling values between C++ types and wasm flat values using `lift_flat`, `lower_flat`, `lift_flat_values`, and `lower_flat_values` templates.
+- Project is kept in sync with the upstream spec (`ref/component-model`) and the reference Python definitions (`definitions.py`, `run_tests.py`). Compare against those when adjusting ABI semantics.
+
+## Core headers
+- `include/cmcpp/traits.hpp` defines `ValTrait`, type aliases (e.g., `bool_t`, `string_t`), and concept shortcuts that every new type must implement.
+- `include/cmcpp/context.hpp` + `InstanceContext` encapsulate guest memory (`std::span<uint8_t>`), realloc callbacks, and host traps; use `createInstanceContext` before calling lift/lower helpers.
+- Memory helpers live in `include/cmcpp/load.hpp`/`store.hpp`; always respect `ValTrait<T>::size` and `alignment` from those headers instead of hard-coding layout rules.
+
+## Lift/Lower workflow
+- `lower_flat_values` flattens function arguments, auto-switching to heap marshalling when the arity exceeds `MAX_FLAT_PARAMS`; `lift_flat_values` mirrors this when decoding results.
+- Heap-based lowering uses `cx.opts.realloc` to allocate guest memory; make sure any caller populates `LiftLowerOptions` with a working realloc when passing heap-backed types (lists, strings, large tuples).
+- String conversions rely on the `convert` callback; tests wire this through ICU (`test/host-util.cpp`). Preserve the encoding enum contract (`Encoding::Utf8`, `Encoding::Utf16`, `Encoding::Latin1`, `Encoding::Latin1_Utf16`).
+
+## Adding types or functions
+- Extend `ValTrait` specializations and `ValTrait<T>::flat_types` for new composite types before touching lift/lower logic.
+- Use concepts from `traits.hpp` (e.g., `List`, `Variant`, `Flags`) so overload resolution stays consistent; mirror patterns in `include/cmcpp/list.hpp`, `variant.hpp`, etc.
+- Guard traps with `trap_if(cx, condition, message)` and route all host failures through the `HostTrap` provided by the context rather than throwing ad-hoc exceptions.
+
+## Testing
+- Default build enables coverage flags on GCC/Clang; run `cmake --preset linux-ninja-Debug` followed by `cmake --build --preset linux-ninja-Debug` and then `ctest --preset linux-ninja-Debug` (or `ctest -VV` from the build tree).
+- C++ tests live in `test/main.cpp` using doctest and ICU for encoding checks; keep new tests near related sections for quick discovery.
+- `run_tests.py` exercises the same ABI rules via Python—use it to cross-check tricky canonical ABI edge cases when changing flattening behavior.
+
+## Samples & runtimes
+- Enabling `-DBUILD_SAMPLES=ON` builds the WAMR host sample (`samples/wamr`); it wraps host callbacks with `host_function`/`guest_function` helpers defined in `include/wamr.hpp`.
+- Sample guest wasm artifacts are generated from `wasm/test.wit` via `wit-bindgen` and `wasm-tools`. The `samples/CMakeLists.txt` external project expects `WASI_SDK_PREFIX` to point at the vcpkg-installed WASI SDK.
+- `wasm/build.sh` spins up a dev container to compile wasm components reproducibly; run it if you need to refresh the sample binaries.
+
+## Tooling notes
+- Dependencies are managed through `vcpkg.json` with overlays in `vcpkg_overlays/` (notably for WAMR); stick with preset builds so CMake wires in the correct toolchain file automatically.
+- Cargo manifest (`Cargo.toml`) is only for fetching `wasm-tools` and `wit-bindgen-cli`; if you touch wasm generation logic, update both the manifest and any scripts referencing those versions.
+- Keep documentation alongside code: update `README.md` when introducing new host types or workflows so downstream integrators stay aligned with the canonical ABI behavior.

include/cmcpp/traits.hpp

@@ -1,13 +1,23 @@
 #ifndef CMCPP_TRAITS_HPP
 #define CMCPP_TRAITS_HPP
 
+#include <algorithm>
+#include <array>
+#include <bitset>
 #include <cassert>
-#include <cstring>
 #include <cmath>
-#include <bitset>
+#include <cstdint>
+#include <cstring>
+#include <functional>
+#include <limits>
 #include <optional>
+#include <string>
+#include <string_view>
+#include <tuple>
+#include <type_traits>
+#include <utility>
 #include <variant>
-#include <limits>
+#include <vector>
 
 #include "boost/pfr.hpp"
 
@@ -36,11 +46,14 @@ namespace cmcpp
     using WasmVal = std::variant<int32_t, int64_t, float32_t, float64_t>;
     using WasmValVector = std::vector<WasmVal>;
 
+    template <typename>
+    inline constexpr bool dependent_false_v = false;
+
     template <typename T>
     struct WasmValTrait
     {
         static constexpr WasmValType type = WasmValType::UNKNOWN;
-        static_assert(WasmValTrait<T>::type != WasmValType::UNKNOWN, "T must be valid WasmValType.");
+        static_assert(!dependent_false_v<T>, "T must be valid WasmValType.");
     };
 
     template <>
@@ -170,7 +183,7 @@ namespace cmcpp
     template <typename T>
     struct ValTrait
     {
-        static_assert(false, "T is not a valid type for ValTrait. Type: ");
+        static_assert(!dependent_false_v<T>, "T is not a valid type for ValTrait.");
         static constexpr ValType type = ValType::UNKNOWN;
         using inner_type = std::monostate;
         static constexpr uint32_t size = 0;
@@ -246,8 +259,8 @@ namespace cmcpp
         static constexpr uint32_t alignment = 1;
         static constexpr std::array<WasmValType, 1> flat_types = {WasmValType::i32};
 
-        static constexpr int8_t LOW_VALUE = std::numeric_limits<uint8_t>::lowest();
-        static constexpr int8_t HIGH_VALUE = std::numeric_limits<uint8_t>::max();
+        static constexpr uint8_t LOW_VALUE = std::numeric_limits<uint8_t>::lowest();
+        static constexpr uint8_t HIGH_VALUE = std::numeric_limits<uint8_t>::max();
     };
 
     template <>
@@ -428,13 +441,42 @@ namespace cmcpp
         string_t str;
         u16string_t u16str;
 
+        // Maintain both buffers in sync when we carry dual encodings so callers can
+        // materialize either representation without tracking extra state.
         inline void resize(size_t new_size)
         {
-            encoding == Encoding::Latin1 ? str.resize(new_size) : u16str.resize(new_size);
+            switch (encoding)
+            {
+            case Encoding::Latin1:
+            case Encoding::Utf8:
+                str.resize(new_size);
+                break;
+            case Encoding::Utf16:
+                u16str.resize(new_size);
+                break;
+            case Encoding::Latin1_Utf16:
+                str.resize(new_size);
+                u16str.resize(new_size);
+                break;
+            }
+        }
+
+        inline void *data()
+        {
+            if (encoding == Encoding::Latin1 || encoding == Encoding::Latin1_Utf16)
+            {
+                return static_cast<void *>(str.data());
+            }
+            return static_cast<void *>(u16str.data());
         }
-        inline void *data() const
+
+        inline const void *data() const
         {
-            return encoding == Encoding::Latin1 ? (void *)str.data() : (void *)u16str.data();
+            if (encoding == Encoding::Latin1 || encoding == Encoding::Latin1_Utf16)
+            {
+                return static_cast<const void *>(str.data());
+            }
+            return static_cast<const void *>(u16str.data());
         }
     };
     template <>
@@ -739,8 +781,8 @@ namespace cmcpp
     using enum_t = uint32_t;
 
     //  Func  --------------------------------------------------------------------
-    constexpr uint MAX_FLAT_PARAMS = 16;
-    constexpr uint MAX_FLAT_RESULTS = 1;
+    constexpr std::uint32_t MAX_FLAT_PARAMS = 16;
+    constexpr std::uint32_t MAX_FLAT_RESULTS = 1;
 
     template <typename>
     struct func_t_impl;

ref/component-model

@@ -187,6 +187,16 @@ void test_overflow_behavior(const std::unique_ptr<LiftLowerContext> &cx, T input
     CHECK(result == expected_output);
 }
 
+#if defined(__clang__)
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wconstant-conversion"
+#pragma clang diagnostic ignored "-Wimplicit-int-conversion"
+#elif defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Woverflow"
+#pragma GCC diagnostic ignored "-Wconversion"
+#endif
+
 TEST_CASE("Numeric Boundary Cases - Overflow Behavior")
 {
     Heap heap(1024 * 1024);
@@ -247,6 +257,12 @@ TEST_CASE("Numeric Boundary Cases - Overflow Behavior")
     test_overflow_behavior<int64_t>(cx, UINT64_MAX, -1);
 }
 
+#if defined(__clang__)
+#pragma clang diagnostic pop
+#elif defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
 TEST_CASE("Float Special Values - Enhanced")
 {
     Heap heap(1024 * 1024);

ref/vscode-wasm

@@ -1,7 +1,7 @@
 {
   "default-registry": {
     "kind": "git",
-    "baseline": "120deac3062162151622ca4860575a33844ba10b",
+    "baseline": "4334d8b4c8916018600212ab4dd4bbdc343065d1",
     "repository": "https://github.com/microsoft/vcpkg"
   },
   "registries": [