Initial Commit

packages/api-stack/api/api-plugin-example/src/wasm/wasm-state.md

@@ -0,0 +1,52 @@
+# wasm-state
+
+## Purpose
+
+Holds the module-singleton `InMemoryStore` consumed by the wasm-tier
+`handleRequest`. The WASI-stdio contract surfaces a synchronous
+`(SerializedRequest) => SerializedResponse` shape with no
+per-request context the host could thread a store reference through —
+so the wasm tier keeps exactly one store at module scope.
+
+`resetState()` is the test-isolation primitive. The shape-conformance
+test calls it before each parity assertion so every iteration starts
+with `inv-1` as the next allocated id and an empty invoice list.
+Production deploys never call `resetState()` directly — `dispose()`
+clears the singleton's contents in place rather than swapping it out.
+
+## Features
+
+- `getStore()` — read the current module-scoped store.
+- `resetState()` — swap in a fresh empty store (test isolation).
+
+## Usage: Basic
+
+```ts
+import { getStore } from "@suaveplan/api-plugin-example/wasm";
+
+const store = getStore();
+console.log(store.list());
+```
+
+## Usage: Advanced
+
+```ts
+import { resetState } from "@suaveplan/api-plugin-example/wasm";
+
+// Inside a test
+beforeEach(() => {
+    resetState();
+});
+```
+
+## API Reference
+
+- `getStore(): InMemoryStore`.
+- `resetState(): void`.
+
+## Implementation Notes
+
+The module-singleton pattern is unusual in this project (most packages
+prefer dependency injection), but the WASI-stdio ABI has no place to
+thread state. The escape hatch is `resetState()` for tests and
+`plugin.dispose()` / `plugin.start()` for production lifecycle reset.