review: address SHIP-WITH-NITS findings on the mock host

Author: decrypto21

.github/workflows/ci.yml

@@ -171,14 +171,18 @@ jobs:
           npm run build --prefix js/packages/truapi
 
       - name: Install wasm-pack
-        run: cargo install wasm-pack --locked
+        run: cargo install wasm-pack --version 0.15.0 --locked
 
       - name: Build WASM
         run: npm run build:wasm --prefix js/packages/truapi-host-wasm
 
       - name: Test
         run: bun test
         working-directory: js/packages/truapi-host-wasm
+        # Fail loudly if the WASM artifact is missing so the bridge test can't
+        # silently skip green after a build:wasm drift.
+        env:
+          REQUIRE_WASM: "1"
 
   playground:
     name: Playground (build + lint)

js/packages/truapi-host-wasm/README.md

@@ -43,6 +43,37 @@ const provider = await createWebWorkerProvider(new HostWorker(), callbacks, {
 `@parity/truapi-host-wasm/web` also exports `createIframeHost` for the protocol-iframe
 MessageChannel handshake.
 
+## Testing — `createMockHost`
+
+`@parity/truapi-host-wasm/web` exports `createMockHost`, an in-memory implementation of the
+full generated `HostCallbacks` surface — the JS sibling of `truapi-platform`'s `MockPlatform`.
+Feed its callbacks to `createWebWorkerProvider` to run the **real WASM core** against a mocked
+OS seam: storage is in-memory, permissions answer from a fixed policy, navigation and
+notifications are recorded, and the chain connection is silent (or replays canned frames).
+
+```ts
+import {
+  createMockHost,
+  mockRuntimeConfig,
+} from "@parity/truapi-host-wasm/web";
+
+const mock = createMockHost(); // optional MockHostConfig
+const provider = await createWebWorkerProvider(
+  new HostWorker(),
+  mock.callbacks,
+  {
+    runtimeConfig: mockRuntimeConfig(),
+  },
+);
+// the real WASM core now talks to a mocked OS; assert via mock.navigations(), etc.
+```
+
+Coverage of the callback surface is `tsc`-enforced: the callbacks object is typed
+`Required<HostCallbacks>`, so a capability added to the generated surface fails the type
+check until the mock covers it. `wasm-bridge.test.ts` drives the real WASM core against the
+mock headlessly (no browser, no worker). Public API: `createMockHost`, `mockRuntimeConfig`,
+`MockHost`, `MockHostConfig`, `PermissionPolicy`.
+
 ## Publishing
 
 The npm publish workflow is not wired yet. A release-process discussion is needed before adding a

js/packages/truapi-host-wasm/src/web/create-mock-host.test.ts

@@ -20,7 +20,7 @@ describe("createMockHost callbacks", () => {
         const { callbacks } = createMockHost();
         const key: CoreStorageKey = {
             tag: "PermissionAuthorization",
-            value: { storageKey: "cam" },
+            value: { productId: "p", request: { tag: "Device", value: "Camera" } },
         };
         await callbacks.writeCoreStorage(key, new Uint8Array([9]));
         expect(await callbacks.readCoreStorage(key)).toEqual(new Uint8Array([9]));

js/packages/truapi-host-wasm/src/web/create-mock-host.ts

@@ -130,7 +130,10 @@ export function createMockHost(config: MockHostConfig = {}): MockHost {
       : `core:${key.tag}`;
   const granted = (policy: PermissionPolicy): boolean => policy === "allow-all";
 
-  const callbacks: HostCallbacks = {
+  // `Required<HostCallbacks>` (not bare `HostCallbacks`): every optional callback
+  // must be present, so a capability added to the generated surface fails `tsc`
+  // here until the mock covers it. This is the load-bearing coverage guarantee.
+  const callbacks: Required<HostCallbacks> = {
     // ProductStorage
     async read(key) {
       return storage.get(productKey(key));
@@ -196,7 +199,10 @@ export function createMockHost(config: MockHostConfig = {}): MockHost {
             await new Promise<never>(() => {});
           }
         },
-        // The mock holds no real transport; releasing the lease is a no-op.
+        // The mock holds no real transport, so releasing the lease is a no-op.
+        // Note: a Silent connection whose `responses()` stream is already parked
+        // stays parked after close() — tests that need the stream to terminate use
+        // `chainClosed` (or scripted frames), not close().
         close() {},
       };
     },

js/packages/truapi-host-wasm/src/web/wasm-bridge.test.ts

@@ -12,6 +12,16 @@ const wasmUrl = new URL("../../dist/wasm/web/truapi_server_bg.wasm", import.meta
 const glueUrl = new URL("../../dist/wasm/web/truapi_server.js", import.meta.url);
 const built = existsSync(wasmUrl);
 
+// The `host-wasm` CI job builds the WASM first and sets REQUIRE_WASM=1, so a
+// missing artifact (a silent `build:wasm` path/output drift) fails loudly here
+// instead of skipping green. A plain local `bun test` leaves REQUIRE_WASM unset
+// and skips this suite cleanly on a fresh checkout.
+if (process.env.REQUIRE_WASM === "1" && !built) {
+    throw new Error(
+        `REQUIRE_WASM=1 but the WASM artifact is missing at ${wasmUrl.pathname} — run \`npm run build:wasm\` first.`,
+    );
+}
+
 const suite = built ? describe : describe.skip;
 
 suite("real WASM core ↔ createMockHost bridge", () => {

rust/crates/truapi-platform/README.md

@@ -33,3 +33,20 @@ exposed through the trait signatures below.
 
 `Platform` is a blanket-implemented supertrait that combines the capability
 traits above.
+
+## Mock platform (`mock` feature)
+
+The `mock` feature — a dev-dependency, excluded from the default and production
+builds — provides `MockPlatform`, a config-driven, in-memory implementation of all
+the capability traits above. It is the canonical seam mock: plug it into the real
+`truapi-server` core (via `TrUApiCore::from_platform_with_config`) to exercise the
+production dispatcher without a device or a paired wallet.
+
+`MockConfig` drives its behavior — `PermissionPolicy` (`AllowAll`/`DenyAll`, device
+and remote separately), `ChainBehavior` (`Silent` | `Scripted` | `Closed` |
+`ConnectError`), `MockFaults` for fault injection, and confirmation control — and it
+records what the core asked the device to do (navigations, notifications,
+confirmations, auth-state transitions, sent RPC) for assertions. Storage is
+namespaced in-memory (`product:` / `core:`); preimages round-trip via submit → lookup.
+See the `from_mock_platform_*` through-core tests in `truapi-server` for end-to-end
+usage.

rust/crates/truapi-platform/src/mock.rs

@@ -462,6 +462,8 @@ impl JsonRpcConnection for MockConnection {
         }
     }
 
+    // No real transport to release. A `None` (silent) `responses()` stream stays
+    // pending after close(); scripted/`Closed` behaviors terminate on their own.
     fn close(&self) {}
 }
 

rust/crates/truapi-server/src/core.rs

@@ -382,7 +382,7 @@ mod tests {
             response.payload.value
         };
 
-        // Default mock supports the feature: [Ok 0x00][V1 0x00][supported=1].
+        // Default mock supports the feature: [V1 0x00][Ok 0x00][supported=1].
         assert_eq!(dispatch(MockPlatform::new()), vec![0x00, 0x00, 0x01]);
         // A configured "unsupported" answer flows through the same dispatcher.
         let unsupported = MockPlatform::with_config(MockConfig {
@@ -441,15 +441,15 @@ mod tests {
             key: "k".into(),
             value: vec![1, 2, 3],
         });
-        // Ok 0x00, V1 0x00.
+        // V1 0x00, Ok 0x00.
         assert_eq!(
             run_request(&core, "local_storage_write", write.encode()),
             vec![0x00, 0x00]
         );
 
         let read =
             HostLocalStorageReadRequest::V1(v01::HostLocalStorageReadRequest { key: "k".into() });
-        // Ok 0x00, V1 0x00, Some 0x01, compact-len(3) 0x0c, bytes.
+        // V1 0x00, Ok 0x00, Some 0x01, compact-len(3) 0x0c, bytes.
         assert_eq!(
             run_request(&core, "local_storage_read", read.encode()),
             vec![0x00, 0x00, 0x01, 0x0c, 1, 2, 3]
@@ -462,7 +462,7 @@ mod tests {
             vec![0x00, 0x00]
         );
 
-        // After clear the read misses: Ok 0x00, V1 0x00, None 0x00.
+        // After clear the read misses: V1 0x00, Ok 0x00, None 0x00.
         let read_again =
             HostLocalStorageReadRequest::V1(v01::HostLocalStorageReadRequest { key: "k".into() });
         assert_eq!(
@@ -483,7 +483,7 @@ mod tests {
         let request =
             || HostDevicePermissionRequest::V1(v01::HostDevicePermissionRequest::Camera).encode();
 
-        // AllowAll (default): Ok 0x00, V1 0x00, granted=1.
+        // AllowAll (default): V1 0x00, Ok 0x00, granted=1.
         let allow = make_mock_core(MockConfig::default());
         assert_eq!(
             run_request(&allow, "permissions_request_device_permission", request()),
@@ -501,9 +501,10 @@ mod tests {
         );
     }
 
-    /// Preimage submit flows through the core's confirm gate to the platform:
-    /// the default mock auto-confirms (Ok envelope), and a `confirm = false`
-    /// mock is rejected by the core before reaching the platform (Err envelope).
+    /// Preimage submit flows through the core's confirm gate: the default mock
+    /// auto-confirms (Ok envelope), and a `confirm = false` mock is rejected by
+    /// the core after the confirmation prompt but before the preimage backend
+    /// (`PreimageHost::submit_preimage`) is reached (Err envelope).
     #[test]
     fn from_mock_platform_preimage_submit_through_core() {
         use truapi::versioned::preimage::RemotePreimageSubmitRequest;
@@ -523,8 +524,8 @@ mod tests {
         assert_eq!(ok_payload.first(), Some(&0x00));
         assert_eq!(ok_payload.get(1), Some(&0x00));
 
-        // confirm_user_actions = false: the core rejects before the platform
-        // (V1 index 0x00, Err 0x01).
+        // confirm_user_actions = false: the core rejects after the confirmation
+        // prompt, before the preimage backend (V1 index 0x00, Err 0x01).
         let rejected = make_mock_core(MockConfig {
             confirm_user_actions: false,
             ..Default::default()