Clarify network and test execution contracts

README.md

@@ -16,8 +16,9 @@ One provider, `ftp`, for the `ftp` and `ftps` schemes. A connection is
 configured with a server name, an optional port, a TLS toggle for FTPS, and an
 optional username and password. An empty username signs in anonymously.
 
-Public, LAN, VPN, link-local and localhost addresses work directly from the
-server name; there is no separate network permission setting.
+With the compatible schema 2 Memona version required by this package, public,
+LAN, VPN, link-local and localhost addresses work directly from the server
+name; that API has no separate connection network grant.
 
 The TLS toggle currently starts TLS on the control connection only. Protected
 data connections and explicit `AUTH TLS` negotiation are not implemented, so

sdk/wit/filesystem.wit

@@ -36,9 +36,10 @@ interface host {
         pull: func(limit: u32) -> result<list<u8>, host-error>;
     }
     /// Begins a request to any HTTP or HTTPS host, including LAN and loopback
-    /// addresses. Each redirect and DNS result is checked, and DNS is pinned.
-    /// Cross-origin redirects remove request headers; HTTPS cannot downgrade.
-    /// The host bounds total bytes per exchange, not buffer size.
+    /// addresses. This API has no per-connection network grant. Each redirect
+    /// and DNS result is checked, and DNS is pinned. Cross-origin redirects
+    /// remove request headers; HTTPS cannot downgrade. The host bounds total
+    /// bytes per exchange, not buffer size.
     http: func(request: request) -> result<exchange, host-error>;
 
     /// One open TCP connection. Dropping the handle closes the socket, and the
@@ -51,9 +52,9 @@ interface host {
         write: func(data: list<u8>) -> result<u32, host-error>;
     }
     /// Opens a socket to any host, including LAN and loopback addresses, on a
-    /// package-declared port. The host resolves and pins DNS and starts TLS
-    /// when asked. Ports negotiated at runtime, such as an FTP data channel,
-    /// must be declared.
+    /// package-declared port. This API has no per-connection network grant.
+    /// The host resolves and pins DNS and starts TLS when asked. Ports
+    /// negotiated at runtime, such as an FTP data channel, must be declared.
     connect: func(host: string, port: u16, tls: bool) -> result<tcp, host-error>;
 
     /// One datagram socket connected to a single peer.
@@ -64,8 +65,8 @@ interface host {
         /// means none arrived inside the host's wait, not that the peer left.
         receive: func(limit: u32) -> result<list<u8>, host-error>;
     }
-    /// Connects a datagram socket under the same port rules as `connect`, for
-    /// the few filesystem protocols that still need one.
+    /// Connects a datagram socket under the same address and port rules as
+    /// `connect`, for the few filesystem protocols that still need one.
     bind: func(host: string, port: u16) -> result<udp, host-error>;
 
     /// A configuration value, typed as the package's manifest declared it.

src/session_tests.rs

@@ -1,5 +1,6 @@
-//! Real FTP commands over a native test socket, with an async local server.
-//! This verifies guest recovery; WASM host integration is exercised separately.
+//! Real FTP commands against an async local server. The generated guest API is
+//! synchronous, so each guest call is isolated with `spawn_blocking`; production
+//! WASM host integration is exercised separately.
 
 use super::Ftp;
 use memona_plugin_sdk::{ErrorCode, Guest, Locator, Setting};

src/test_host.rs

@@ -1,5 +1,6 @@
-//! Native test transport. Guest calls run only inside `spawn_blocking`;
-//! production WASM always uses the host's sockets and network policy.
+//! Native test transport for the generated synchronous `Guest` API. It cannot
+//! await a Tokio socket, so tests confine it to `spawn_blocking` while their FTP
+//! server remains async. Production WASM always uses the host's async sockets.
 
 use std::cell::RefCell;
 use std::io::{Read, Write};