chore: bump instructions

Signed-off-by: Gordon Smith <[email protected]>

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