chore: bump instructions

Signed-off-by: Gordon Smith <GordonJSmith@gmail.com>

Author: GordonSmith

.github/copilot-instructions.md

@@ -1,11 +1,14 @@
 ## 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.
+- **Implementation mirrors the official Python reference**: The C++ code structure, type names, and semantics directly correspond to the Python implementation in `ref/component-model/design/mvp/canonical-abi/definitions.py` and the specification in `ref/component-model/design/mvp/CanonicalABI.md`. When making changes, cross-reference these files to ensure alignment.
+- Supports async runtime primitives (`Store`, `Thread`, `Task`), resource management (`own`, `borrow`), streams/futures, waitables, and error contexts.
 
 ## 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.
+- `include/cmcpp/context.hpp` encapsulates `LiftLowerContext`, `ComponentInstance`, `Task`, resource tables (`HandleTable`, `InstanceTable`), and canonical operations like `canon_waitable_*`, `canon_stream_*`, `canon_future_*`.
+- `include/cmcpp/runtime.hpp` provides async primitives: `Store`, `Thread`, `Call`, and supporting types for cooperative scheduling.
+- `include/cmcpp/error_context.hpp` implements error context lifecycle (`canon_error_context_new/debug_message/drop`).
 - 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
@@ -17,11 +20,14 @@
 - 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.
+- **Maintain Python equivalence**: When implementing new canonical operations or type handling, ensure the C++ behavior matches the corresponding Python code in `definitions.py`. Type names, state transitions, and error conditions should align with the reference implementation.
 
 ## 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).
+- 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 --output-on-failure` 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.
+- Test coverage workflow: run tests, then `lcov --capture --directory . --output-file coverage.info`, filter with `lcov --remove`, and optionally generate HTML with `genhtml`. See README for full workflow.
+- **Python reference tests**: The canonical ABI test suite in `ref/component-model/design/mvp/canonical-abi/run_tests.py` exercises the same ABI rules—use it to cross-check tricky canonical ABI edge cases when changing flattening behavior. Run with `python3 run_tests.py` (requires Python 3.10+).
+- When adding new features to the C++ implementation, verify behavior matches the Python reference by comparing against `definitions.py` logic and running the Python test suite.
 
 ## 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`.
@@ -31,4 +37,5 @@
 ## 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.
+- Release management uses Release Please with conventional commits (`feat:`, `fix:`, etc.) to automate changelog and version bumps.
 - Keep documentation alongside code: update `README.md` when introducing new host types or workflows so downstream integrators stay aligned with the canonical ABI behavior.

.github/instructions/component-model.instructions.md

@@ -7,6 +7,22 @@ applyTo: '**'
 
 This repository implements a C++ ABI (Application Binary Interface) for the WebAssembly Component Model, providing host bindings that allow C++ applications to interact with WebAssembly components.
 
+### Relationship to the Official Specification
+
+**This implementation directly mirrors the canonical Python reference implementation.** The C++ code in this repository is designed to be a faithful translation of:
+
+- **Python definitions**: `ref/component-model/design/mvp/canonical-abi/definitions.py` - The authoritative reference implementation
+- **Specification**: `ref/component-model/design/mvp/CanonicalABI.md` - The formal specification document
+- **Test suite**: `ref/component-model/design/mvp/canonical-abi/run_tests.py` - Validation tests
+
+The C++ implementation maintains structural and semantic alignment with the Python code:
+- Class names map directly (e.g., `Task`, `Store`, `Thread`, `ComponentInstance`)
+- State machines follow the same transitions (e.g., `Task::State` enum values)
+- Method signatures and behavior match the Python counterparts
+- Error conditions and trap points are equivalent
+
+When modifying or extending the C++ implementation, **always cross-reference the Python code** to ensure conformance. Any divergence from the reference implementation should be documented and justified.
+
 ### WebAssembly Component Model Overview
 The [WebAssembly Component Model](https://github.com/WebAssembly/component-model) is a specification that extends WebAssembly with:
 - **Interface Types**: Rich type system beyond basic WebAssembly types
@@ -21,12 +37,16 @@ The [WebAssembly Component Model](https://github.com/WebAssembly/component-model
   - Primitive types: bool, integers (s8-s64, u8-u64), floats (f32, f64), char
   - String types: UTF-8, UTF-16, Latin-1+UTF-16 encoding support  
   - Composite types: lists, records, tuples, variants, enums, options, results, flags
-  - Resource types: own, borrow (planned)
+  - Resource types: own, borrow
+  - Async types: streams (readable/writable), futures (readable/writable), waitables, tasks
+  - Error handling: error contexts with debug messages
 
 - **ABI Functions**: Core Component Model operations
   - `lower_flat_values`: Convert C++ values to WebAssembly flat representation
   - `lift_flat_values`: Convert WebAssembly flat values to C++ types
   - Memory management with proper encoding handling
+  - Canonical operations: `canon_waitable_*`, `canon_stream_*`, `canon_future_*`, `canon_task_*`, `canon_error_context_*`
+  - Async runtime: `Store`, `Thread`, `Call`, cooperative scheduling with tick-based execution
 
 #### Architecture
 - **Header-only Library**: Pure template-based implementation in `include/cmcpp/`
@@ -50,6 +70,19 @@ When working with this library:
 2. **Host Functions**: Implement host functions using the provided type wrappers
 3. **Guest Interaction**: Use lift/lower functions to marshal data between host and guest
 4. **Memory Management**: Use the provided realloc functions for guest memory allocation
+5. **Async Operations**: Use `Store::invoke` and `Store::tick()` for cooperative async execution
+6. **Resource Management**: Use `ComponentInstance::table` for handle tracking and canonical resource operations
+7. **Error Contexts**: Use `canon_error_context_*` functions for debug message handling
+8. **Validation**: Cross-check behavior against the Python reference in `ref/component-model/design/mvp/canonical-abi/definitions.py` when implementing new features
+
+### Testing Against the Python Reference
+
+When adding or modifying canonical ABI operations:
+1. Read the corresponding Python function in `definitions.py` to understand the expected behavior
+2. Ensure your C++ implementation produces equivalent results for the same inputs
+3. Run `python3 ref/component-model/design/mvp/canonical-abi/run_tests.py` to verify the reference tests still pass
+4. Add corresponding C++ tests in `test/main.cpp` that exercise the same edge cases
+5. Document any intentional deviations (e.g., performance optimizations) with clear justification
 
 ### References
 - [WebAssembly Component Model Specification](https://github.com/WebAssembly/component-model)

.github/instructions/general.instructions.md

@@ -25,13 +25,14 @@ This repository is a modern C++20 header-only library implementing WebAssembly C
 - **Template Specializations**: Use template specialization for different WebAssembly types
 
 ### Build System
-- **CMake**: Uses CMake 3.5+ with modern CMake practices
+- **CMake**: Uses CMake 3.5+ with modern CMake practices (3.22+ recommended for presets)
 - **Interface Library**: Configured as an interface library target
-- **Cross-platform**: Supports Ubuntu, macOS, and Windows
+- **Cross-platform**: Supports Ubuntu 24.04 and Windows 2022
 - **Compiler Requirements**: Requires C++20 support
 - **Dependencies**: Uses vcpkg for third-party library management
   - Package definitions in `vcpkg.json` and `vcpkg-configuration.json`
   - Key dependencies: doctest (testing), ICU (Unicode), wasm-micro-runtime, wasi-sdk
+- **Coverage**: GCC/Clang builds enable coverage instrumentation; use lcov for report generation
 
 ### Type Safety and WebAssembly ABI
 - **Strong Typing**: Use distinct types for WebAssembly values (bool_t, char_t, etc.)
@@ -44,4 +45,5 @@ This repository is a modern C++20 header-only library implementing WebAssembly C
 - **Function Templates**: Use function templates for type-generic operations
 - **SFINAE/Concepts**: Use concepts or SFINAE for template constraints
 - **Const Correctness**: Maintain const correctness throughout
-- **Naming**: Use snake_case for variables, PascalCase for types
+- **Naming**: Use snake_case for variables, PascalCase for types
+- **Commit Messages**: Use conventional commits (`feat:`, `fix:`, etc.) for Release Please automation

.gitmodules

@@ -4,9 +4,6 @@
 [submodule "ref/component-model"]
 	path = ref/component-model
 	url = https://github.com/WebAssembly/component-model.git
-[submodule "ref/vscode-wasm"]
-	path = ref/vscode-wasm
-	url = git@github.com:microsoft/vscode-wasm.git
 [submodule "ref/wasm-micro-runtime"]
 	path = ref/wasm-micro-runtime
 	url = git@github.com:bytecodealliance/wasm-micro-runtime.git

include/cmcpp/float.hpp

@@ -26,12 +26,30 @@ namespace cmcpp
             return f;
         }
 
+        inline float64_t core_f64_reinterpret_i64(int64_t i)
+        {
+            float64_t f;
+            std::memcpy(&f, &i, sizeof f);
+            return f;
+        }
+
         template <Float T>
         T canonicalize_nan(T f)
         {
-            if (!std::isfinite(f))
+            if (std::isnan(f))
             {
-                f = std::numeric_limits<T>::quiet_NaN();
+                // Use canonical NaN bit patterns per Component Model spec
+                // Ref: ref/component-model/design/mvp/canonical-abi/definitions.py
+                if constexpr (std::is_same_v<T, float32_t>)
+                {
+                    constexpr uint32_t CANONICAL_FLOAT32_NAN = 0x7fc00000;
+                    return core_f32_reinterpret_i32(CANONICAL_FLOAT32_NAN);
+                }
+                else if constexpr (std::is_same_v<T, float64_t>)
+                {
+                    constexpr uint64_t CANONICAL_FLOAT64_NAN = 0x7ff8000000000000;
+                    return core_f64_reinterpret_i64(CANONICAL_FLOAT64_NAN);
+                }
             }
             return f;
         }
@@ -71,13 +89,13 @@ namespace cmcpp
         template <>
         inline float32_t load<float32_t>(const LiftLowerContext &cx, offset ptr)
         {
-            return decode_i32_as_float(integer::load<int32_t>(cx, ptr));
+            return canonicalize_nan(decode_i32_as_float(integer::load<int32_t>(cx, ptr)));
         }
 
         template <>
         inline float64_t load<float64_t>(const LiftLowerContext &cx, offset ptr)
         {
-            return decode_i64_as_float(integer::load<int64_t>(cx, ptr));
+            return canonicalize_nan(decode_i64_as_float(integer::load<int64_t>(cx, ptr)));
         }
     }
 

include/cmcpp/integer.hpp

@@ -53,7 +53,8 @@ namespace cmcpp
     template <Boolean T>
     inline void store(LiftLowerContext &cx, const T &v, uint32_t ptr)
     {
-        integer::store<T>(cx, v, ptr);
+        uint8_t byte = v ? 1 : 0;
+        integer::store<uint8_t>(cx, byte, ptr);
     }
     template <Boolean T>
     inline WasmValVector lower_flat(LiftLowerContext &cx, const T &v)

include/cmcpp/list.hpp

@@ -16,7 +16,8 @@ namespace cmcpp
             size_t nbytes = ValTrait<T>::size;
             for (size_t i = 0; i < v.size(); ++i)
             {
-                cmcpp::store<T>(cx, v[i], ptr + i * nbytes);
+                T elem = v[i]; // Convert to actual type (important for std::vector<bool>)
+                cmcpp::store<T>(cx, elem, ptr + i * nbytes);
             }
             return {ptr, v.size()};
         }

ref/vscode-wasm

@@ -35,7 +35,6 @@ class Heap
         last_alloc = ret + new_size;
         if (last_alloc > memory.size())
         {
-            std::cout << "oom: have " << memory.size() << " need " << last_alloc << std::endl;
             trap("oom");
         }
         std::memcpy(&memory[ret], &memory[original_ptr], original_size);