Extend prepare API/docs across bindings

Agent-Logs-Url: https://github.com/microsoft/regorus/sessions/49ba4462-95d3-42c0-a302-db1b81df4f65

Co-authored-by: anakrish <35780660+anakrish@users.noreply.github.com>

bindings/wasm/README.md

@@ -23,4 +23,7 @@ Run `cargo xtask build-wasm` to invoke wasm-pack with sensible defaults, or `car
 See [test.js](https://github.com/microsoft/regorus/blob/main/bindings/wasm/test.js) for example usage.
 
 For best performance with large policies, call `engine.prepare()` after loading
-policy/data, then use `engine.clone()` to create per-request engines.
+policy/data, then use `engine.clone()` to create per-request engines. If
+`prepare()` is skipped, the first `eval*` call performs the same one-time
+setup. Adding/changing policy or data after `prepare()` invalidates the
+prepared state.

bindings/wasm/src/lib.rs

@@ -141,6 +141,9 @@ impl Engine {
     /// Clone this engine.
     ///
     /// Useful for creating per-request engines after loading policy/data once.
+    ///
+    /// Clone is designed to avoid reparsing policy text and reloading immutable
+    /// policy structures. Mutable evaluation state is copied for isolation.
     #[wasm_bindgen(js_name = "clone")]
     pub fn cloneEngine(&self) -> Engine {
         Clone::clone(self)
@@ -168,8 +171,14 @@ impl Engine {
 
     /// Prepare the engine for evaluation.
     ///
-    /// This initializes internal evaluation structures so a cloned engine can
-    /// evaluate without requiring an initial "dummy" evaluation.
+    /// The first evaluation on an unprepared engine performs one-time setup.
+    /// Calling `prepare()` performs that setup eagerly.
+    ///
+    /// This is optional for correctness. If omitted, the first `eval*` call
+    /// implicitly performs preparation.
+    ///
+    /// If policies/data are modified after `prepare()`, preparation is
+    /// invalidated and must be performed again (explicitly or via first eval).
     pub fn prepare(&mut self) -> Result<(), JsValue> {
         self.engine.prepare().map_err(error_to_jsvalue)
     }