@kya-os/checkpoint-wasm-runtime 1.5.0 → 1.6.0

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { D as Decision } from './types-C3RniIOM.js';
+export { B as BlockReason } from './types-C3RniIOM.js';
+import '@kya-os/checkpoint-shared';
+
 /**
  * AgentShield WASM Runtime Types
  *
@@ -598,6 +602,119 @@ declare class RulesDetector implements IDetector {
  */
 declare function createRulesDetector(): RulesDetector;
 
+/**
+ * Cedar policy-evaluator bridge — Node fallback.
+ *
+ * Surfaces the `PolicyEvaluator` class exported by the cedar-enabled
+ * `kya-os-engine` WASM artifact (built by
+ * `rust/scripts/build-engine-cedar-wasm.sh`, gated on the Rust
+ * `wasm,cedar` features). A JS host (the gateway) compiles a tenant
+ * policy bundle once and authorizes many requests against it in-process,
+ * with no round-trip to a separate policy service.
+ *
+ * The cedar artifact is a SEPARATE, larger binary than the lean
+ * detection artifact — it pulls in `cedar-policy`. Detection-only
+ * consumers load `./engine` (the lean `verify()` glue); only callers that
+ * need in-process authorization reach for this bridge.
+ *
+ * ## Lazy loading
+ *
+ * The cedar `--target nodejs` glue instantiates the ~2 MB cedar WASM the
+ * moment it is `require`d (it `fs.readFileSync`s its `.wasm` sibling at
+ * module load). To keep the separate-artifact promise — detection-only
+ * consumers must NOT pay cedar's memory/startup — the glue is loaded
+ * LAZILY: nothing happens on `import`; the artifact is `require`d (and
+ * memoised) only on the first {@link createPolicyEvaluator} call. This is
+ * also why cedar lives behind the dedicated `./policy` subpath and is NOT
+ * re-exported from the `./node` barrel.
+ *
+ * `createRequire(__filename)` resolves the glue at call time in both
+ * builds — native `require` under CJS, the tsup `shims` / `createRequire`
+ * banner under ESM. The glue stays external (regex
+ * `wasm/kya-os-engine-cedar/` in tsup's `commonOpts.external`), so its
+ * `__dirname` resolves against `node_modules/.../wasm/kya-os-engine-cedar/`
+ * where the `.wasm` lives, and `"type": "commonjs"` on the artifact's
+ * package.json keeps Node from throwing `ERR_REQUIRE_ESM`.
+ *
+ * Direct .wasm path (for callers building their own loaders):
+ *   `@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm`
+ */
+
+/**
+ * Owned, plain-data request the host hands to
+ * {@link PolicyEvaluatorRuntime.authorize}. Mirrors the Rust
+ * `AuthorizeInput` (`rust/crates/kya-os-engine/src/policy/authorize.rs`);
+ * keys are camelCase across the wasm-bindgen boundary, matching every
+ * other engine wire type.
+ *
+ * The evaluator is **synchronous over pre-resolved facts** (H-1 Kickoff
+ * § 4.5): the host pre-fetches the agent's delegation chain, reputation,
+ * etc. and ships the results here — no JS callbacks cross the boundary.
+ *
+ * `agentDid` and `reputation` are optional (omit or pass `undefined` for
+ * an anonymous or reputation-less request); `grantedScopes` defaults to an
+ * empty list when omitted.
+ */
+interface AuthorizeInput {
+    /** Agent DID if identity has been established, otherwise omitted. */
+    agentDid?: string;
+    /** The action being requested (e.g., `"book_flight"`). */
+    action: string;
+    /** The resource being acted on (e.g., `"travel_api"`). */
+    resource: string;
+    /** Scopes granted by the agent's delegation chain. Defaults to `[]`. */
+    grantedScopes?: string[];
+    /** Agent's reputation score in `[0.0, 1.0]`, if computed. */
+    reputation?: number;
+    /** Tenant identifier. */
+    tenantId: string;
+}
+/**
+ * Structural type of the WASM `PolicyEvaluator` class the cedar glue
+ * exports. Pinned here so this bridge type-checks against the artifact's
+ * `.d.ts` (`constructor(policy_text: string)`, `authorize(input): any`,
+ * `free()`).
+ */
+interface WasmPolicyEvaluator {
+    authorize(input: AuthorizeInput): unknown;
+    free(): void;
+}
+/**
+ * Host-facing wrapper around one compiled Cedar policy bundle.
+ *
+ * Construction compiles the bundle once; every {@link authorize} call
+ * evaluates a single owned request against it without re-parsing policy
+ * text (the compile-once / evaluate-many contract the engine upholds,
+ * carried across the boundary).
+ */
+declare class PolicyEvaluatorRuntime {
+    private readonly inner;
+    /**
+     * @param inner - The compiled WASM `PolicyEvaluator` handle. Built in
+     *   {@link createPolicyEvaluator}; reused by every {@link authorize}
+     *   call for the lifetime of this wrapper.
+     */
+    constructor(inner: WasmPolicyEvaluator);
+    /**
+     * Authorize one owned request against the compiled policy bundle.
+     *
+     * The evaluator owns the fail-closed posture — a request it cannot
+     * marshal into Cedar, or one matching no `permit`, comes back as a
+     * {@link Decision} `Block` (not a thrown error). Authorization
+     * *verdicts* never throw; they surface inside the returned value.
+     *
+     * @throws {Error} only for boundary faults the WASM glue rejects: a
+     *   malformed `input` that fails `AuthorizeInput` deserialisation, or a
+     *   failure serialising the resulting `Decision`.
+     */
+    authorize(input: AuthorizeInput): Decision;
+    /**
+     * Release the compiled bundle's WASM memory. Call when the evaluator is
+     * no longer needed; after this the wrapper must not be reused.
+     */
+    free(): void;
+}
+
 /**
  * Create a detector with automatic runtime selection
  *
@@ -650,4 +767,4 @@ declare function createEdgeDetector(wasmModule: WebAssembly.Module, options?: ID
  */
 declare function createFallbackDetector(): IDetector;
 
-export { CONFIDENCE, type DetectionClass, DynamicWasmLoader, type ForgeabilityRisk, type ICustomerPolicy, type IDetectedAgent, type IDetectionInput, type IDetectionResult, type IDetector, type IDetectorOptions, type IPathRule, type IPolicyLoader, type IWasmBindings, type IWasmLoader, PolicyLoadError, PolicyLoader, type PolicyLoaderConfig, RulesDetector, StaticWasmLoader, type VerificationMethod, WasmDetector, createDetector, createDynamicLoader, createEdgeDetector, createFallbackDetector, createPolicyLoader, createRulesDetector, createStaticLoader };
+export { type AuthorizeInput, CONFIDENCE, Decision, type DetectionClass, DynamicWasmLoader, type ForgeabilityRisk, type ICustomerPolicy, type IDetectedAgent, type IDetectionInput, type IDetectionResult, type IDetector, type IDetectorOptions, type IPathRule, type IPolicyLoader, type IWasmBindings, type IWasmLoader, PolicyEvaluatorRuntime, PolicyLoadError, PolicyLoader, type PolicyLoaderConfig, RulesDetector, StaticWasmLoader, type VerificationMethod, WasmDetector, createDetector, createDynamicLoader, createEdgeDetector, createFallbackDetector, createPolicyLoader, createRulesDetector, createStaticLoader };

package/dist/orchestrator-edge.js

@@ -77,20 +77,27 @@ function isBlockedIpv6(hostname) {
 
 // src/engine/edge.ts
 var initialised = null;
-function initEngineEdge(moduleOrPath) {
-  return ensureReady(moduleOrPath).then(() => void 0);
+var providedModule;
+function initEngineEdge(wasmModule) {
+  if (wasmModule !== void 0 && providedModule === void 0) {
+    providedModule = wasmModule;
+  }
+  return ensureReady().then(() => void 0);
 }
-function ensureReady(moduleOrPath) {
+function ensureReady() {
   if (initialised) return initialised;
   const pending = (async () => {
     const mod = await import('@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-web/kya_os_engine.js');
-    await mod.default(moduleOrPath !== void 0 ? { module_or_path: moduleOrPath } : void 0);
+    await mod.default(
+      providedModule !== void 0 ? { module_or_path: providedModule } : void 0
+    );
     return mod.verify;
   })();
   initialised = pending;
   pending.catch(() => {
     if (initialised === pending) {
       initialised = null;
+      providedModule = void 0;
     }
   });
   return initialised;
@@ -191,21 +198,30 @@ function parseBodyAsObject(body) {
 function tryBuildMcpIFromLegacyHeader(req) {
   const header = getHeader(req, "kya-delegation");
   if (!header) return null;
-  let parsed;
+  let parsed = void 0;
   try {
     parsed = JSON.parse(header);
   } catch {
-    return null;
   }
-  if (!parsed || typeof parsed !== "object") return null;
-  const obj = parsed;
-  const protectedSeg = obj.protected;
-  const payloadSeg = obj.payload;
-  const signatureSeg = obj.signature;
-  if (typeof protectedSeg !== "string" || typeof payloadSeg !== "string" || typeof signatureSeg !== "string") {
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed;
+    const protectedSeg = obj.protected;
+    const payloadSeg = obj.payload;
+    const signatureSeg = obj.signature;
+    if (typeof protectedSeg === "string" && typeof payloadSeg === "string" && typeof signatureSeg === "string") {
+      const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+      return buildMcpIRequestFromCompact(compact);
+    }
     return null;
   }
-  const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+  const trimmed = header.trim();
+  if (COMPACT_JWS_PATTERN.test(trimmed)) {
+    return buildMcpIRequestFromCompact(trimmed);
+  }
+  return null;
+}
+var COMPACT_JWS_PATTERN = /^[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*$/;
+function buildMcpIRequestFromCompact(compact) {
   const raw = Array.from(Buffer.from(compact, "utf8"));
   const payload = parseJwsPayloadStruct(raw);
   if (!payload) return null;
@@ -404,6 +420,23 @@ function buildBaseHeaders(result) {
   if (result.engineInfo.rulesetHash) {
     headers["X-Checkpoint-Ruleset-Hash"] = result.engineInfo.rulesetHash;
   }
+  const meta = result.detectionDetail.metadata;
+  if (meta) {
+    const verifiedTier = meta.verified_tier;
+    if (typeof verifiedTier === "number" && Number.isFinite(verifiedTier)) {
+      headers["X-Checkpoint-Verified-Tier"] = String(verifiedTier);
+    } else if (typeof verifiedTier === "string" && verifiedTier.length > 0) {
+      headers["X-Checkpoint-Verified-Tier"] = verifiedTier;
+    }
+    const verifiedVendor = meta.verified_vendor;
+    if (typeof verifiedVendor === "string" && verifiedVendor.length > 0) {
+      headers["X-Checkpoint-Verified-Vendor"] = verifiedVendor;
+    }
+    const verifiedProtocol = meta.verified_protocol;
+    if (typeof verifiedProtocol === "string" && verifiedProtocol.length > 0) {
+      headers["X-Checkpoint-Verified-Protocol"] = verifiedProtocol;
+    }
+  }
   return headers;
 }
 function httpStatusForBlockReason(reason) {

package/dist/orchestrator-edge.mjs

@@ -75,20 +75,27 @@ function isBlockedIpv6(hostname) {
 
 // src/engine/edge.ts
 var initialised = null;
-function initEngineEdge(moduleOrPath) {
-  return ensureReady(moduleOrPath).then(() => void 0);
+var providedModule;
+function initEngineEdge(wasmModule) {
+  if (wasmModule !== void 0 && providedModule === void 0) {
+    providedModule = wasmModule;
+  }
+  return ensureReady().then(() => void 0);
 }
-function ensureReady(moduleOrPath) {
+function ensureReady() {
   if (initialised) return initialised;
   const pending = (async () => {
     const mod = await import('@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-web/kya_os_engine.js');
-    await mod.default(moduleOrPath !== void 0 ? { module_or_path: moduleOrPath } : void 0);
+    await mod.default(
+      providedModule !== void 0 ? { module_or_path: providedModule } : void 0
+    );
     return mod.verify;
   })();
   initialised = pending;
   pending.catch(() => {
     if (initialised === pending) {
       initialised = null;
+      providedModule = void 0;
     }
   });
   return initialised;
@@ -189,21 +196,30 @@ function parseBodyAsObject(body) {
 function tryBuildMcpIFromLegacyHeader(req) {
   const header = getHeader(req, "kya-delegation");
   if (!header) return null;
-  let parsed;
+  let parsed = void 0;
   try {
     parsed = JSON.parse(header);
   } catch {
-    return null;
   }
-  if (!parsed || typeof parsed !== "object") return null;
-  const obj = parsed;
-  const protectedSeg = obj.protected;
-  const payloadSeg = obj.payload;
-  const signatureSeg = obj.signature;
-  if (typeof protectedSeg !== "string" || typeof payloadSeg !== "string" || typeof signatureSeg !== "string") {
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed;
+    const protectedSeg = obj.protected;
+    const payloadSeg = obj.payload;
+    const signatureSeg = obj.signature;
+    if (typeof protectedSeg === "string" && typeof payloadSeg === "string" && typeof signatureSeg === "string") {
+      const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+      return buildMcpIRequestFromCompact(compact);
+    }
     return null;
   }
-  const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+  const trimmed = header.trim();
+  if (COMPACT_JWS_PATTERN.test(trimmed)) {
+    return buildMcpIRequestFromCompact(trimmed);
+  }
+  return null;
+}
+var COMPACT_JWS_PATTERN = /^[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*$/;
+function buildMcpIRequestFromCompact(compact) {
   const raw = Array.from(Buffer.from(compact, "utf8"));
   const payload = parseJwsPayloadStruct(raw);
   if (!payload) return null;
@@ -402,6 +418,23 @@ function buildBaseHeaders(result) {
   if (result.engineInfo.rulesetHash) {
     headers["X-Checkpoint-Ruleset-Hash"] = result.engineInfo.rulesetHash;
   }
+  const meta = result.detectionDetail.metadata;
+  if (meta) {
+    const verifiedTier = meta.verified_tier;
+    if (typeof verifiedTier === "number" && Number.isFinite(verifiedTier)) {
+      headers["X-Checkpoint-Verified-Tier"] = String(verifiedTier);
+    } else if (typeof verifiedTier === "string" && verifiedTier.length > 0) {
+      headers["X-Checkpoint-Verified-Tier"] = verifiedTier;
+    }
+    const verifiedVendor = meta.verified_vendor;
+    if (typeof verifiedVendor === "string" && verifiedVendor.length > 0) {
+      headers["X-Checkpoint-Verified-Vendor"] = verifiedVendor;
+    }
+    const verifiedProtocol = meta.verified_protocol;
+    if (typeof verifiedProtocol === "string" && verifiedProtocol.length > 0) {
+      headers["X-Checkpoint-Verified-Protocol"] = verifiedProtocol;
+    }
+  }
   return headers;
 }
 function httpStatusForBlockReason(reason) {

package/dist/orchestrator-node.js

@@ -194,21 +194,30 @@ function parseBodyAsObject(body) {
 function tryBuildMcpIFromLegacyHeader(req) {
   const header = getHeader(req, "kya-delegation");
   if (!header) return null;
-  let parsed;
+  let parsed = void 0;
   try {
     parsed = JSON.parse(header);
   } catch {
-    return null;
   }
-  if (!parsed || typeof parsed !== "object") return null;
-  const obj = parsed;
-  const protectedSeg = obj.protected;
-  const payloadSeg = obj.payload;
-  const signatureSeg = obj.signature;
-  if (typeof protectedSeg !== "string" || typeof payloadSeg !== "string" || typeof signatureSeg !== "string") {
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed;
+    const protectedSeg = obj.protected;
+    const payloadSeg = obj.payload;
+    const signatureSeg = obj.signature;
+    if (typeof protectedSeg === "string" && typeof payloadSeg === "string" && typeof signatureSeg === "string") {
+      const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+      return buildMcpIRequestFromCompact(compact);
+    }
     return null;
   }
-  const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+  const trimmed = header.trim();
+  if (COMPACT_JWS_PATTERN.test(trimmed)) {
+    return buildMcpIRequestFromCompact(trimmed);
+  }
+  return null;
+}
+var COMPACT_JWS_PATTERN = /^[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*$/;
+function buildMcpIRequestFromCompact(compact) {
   const raw = Array.from(Buffer.from(compact, "utf8"));
   const payload = parseJwsPayloadStruct(raw);
   if (!payload) return null;
@@ -508,6 +517,23 @@ function buildBaseHeaders(result) {
   if (result.engineInfo.rulesetHash) {
     headers["X-Checkpoint-Ruleset-Hash"] = result.engineInfo.rulesetHash;
   }
+  const meta = result.detectionDetail.metadata;
+  if (meta) {
+    const verifiedTier = meta.verified_tier;
+    if (typeof verifiedTier === "number" && Number.isFinite(verifiedTier)) {
+      headers["X-Checkpoint-Verified-Tier"] = String(verifiedTier);
+    } else if (typeof verifiedTier === "string" && verifiedTier.length > 0) {
+      headers["X-Checkpoint-Verified-Tier"] = verifiedTier;
+    }
+    const verifiedVendor = meta.verified_vendor;
+    if (typeof verifiedVendor === "string" && verifiedVendor.length > 0) {
+      headers["X-Checkpoint-Verified-Vendor"] = verifiedVendor;
+    }
+    const verifiedProtocol = meta.verified_protocol;
+    if (typeof verifiedProtocol === "string" && verifiedProtocol.length > 0) {
+      headers["X-Checkpoint-Verified-Protocol"] = verifiedProtocol;
+    }
+  }
   return headers;
 }
 function httpStatusForBlockReason(reason) {

package/dist/orchestrator-node.mjs

@@ -173,21 +173,30 @@ function parseBodyAsObject(body) {
 function tryBuildMcpIFromLegacyHeader(req) {
   const header = getHeader(req, "kya-delegation");
   if (!header) return null;
-  let parsed;
+  let parsed = void 0;
   try {
     parsed = JSON.parse(header);
   } catch {
-    return null;
   }
-  if (!parsed || typeof parsed !== "object") return null;
-  const obj = parsed;
-  const protectedSeg = obj.protected;
-  const payloadSeg = obj.payload;
-  const signatureSeg = obj.signature;
-  if (typeof protectedSeg !== "string" || typeof payloadSeg !== "string" || typeof signatureSeg !== "string") {
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed;
+    const protectedSeg = obj.protected;
+    const payloadSeg = obj.payload;
+    const signatureSeg = obj.signature;
+    if (typeof protectedSeg === "string" && typeof payloadSeg === "string" && typeof signatureSeg === "string") {
+      const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+      return buildMcpIRequestFromCompact(compact);
+    }
     return null;
   }
-  const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+  const trimmed = header.trim();
+  if (COMPACT_JWS_PATTERN.test(trimmed)) {
+    return buildMcpIRequestFromCompact(trimmed);
+  }
+  return null;
+}
+var COMPACT_JWS_PATTERN = /^[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*\.[A-Za-z0-9_-]+=*$/;
+function buildMcpIRequestFromCompact(compact) {
   const raw = Array.from(Buffer.from(compact, "utf8"));
   const payload = parseJwsPayloadStruct(raw);
   if (!payload) return null;
@@ -487,6 +496,23 @@ function buildBaseHeaders(result) {
   if (result.engineInfo.rulesetHash) {
     headers["X-Checkpoint-Ruleset-Hash"] = result.engineInfo.rulesetHash;
   }
+  const meta = result.detectionDetail.metadata;
+  if (meta) {
+    const verifiedTier = meta.verified_tier;
+    if (typeof verifiedTier === "number" && Number.isFinite(verifiedTier)) {
+      headers["X-Checkpoint-Verified-Tier"] = String(verifiedTier);
+    } else if (typeof verifiedTier === "string" && verifiedTier.length > 0) {
+      headers["X-Checkpoint-Verified-Tier"] = verifiedTier;
+    }
+    const verifiedVendor = meta.verified_vendor;
+    if (typeof verifiedVendor === "string" && verifiedVendor.length > 0) {
+      headers["X-Checkpoint-Verified-Vendor"] = verifiedVendor;
+    }
+    const verifiedProtocol = meta.verified_protocol;
+    if (typeof verifiedProtocol === "string" && verifiedProtocol.length > 0) {
+      headers["X-Checkpoint-Verified-Protocol"] = verifiedProtocol;
+    }
+  }
   return headers;
 }
 function httpStatusForBlockReason(reason) {

package/dist/orchestrator.d.mts

@@ -222,11 +222,44 @@ interface RenderedResponse {
  * no sync wasm load).
  *
  * This module loads the `wasm-pack --target web` artifact via the
- * async `__wbg_init` default export, then exposes the same typed
- * `engineVerifyEdge(input, ctx) → Promise<VerifyResult>` shape with
- * a small lazy-init wrapper. First call awaits initialisation;
- * subsequent calls resolve synchronously on the JS side (the
- * underlying wasm `verify` is sync).
+ * async `__wbg_init` default export. The web target's `init()`
+ * accepts a pre-instantiated `WebAssembly.Module` argument — the
+ * canonical Cloudflare-Workers + wasm-bindgen pattern.
+ *
+ * # Why the caller MUST pass `wasmModule` on Cloudflare Workers
+ *
+ * Both `--target web` (URL fetch) and `--target bundler` (auto-
+ * instantiated `__wbg_set_wasm(wasm)`) have failure modes on wrangler:
+ *
+ *   - `--target web` falls back to `new URL('<wasm>', import.meta.url)`
+ *     when `init()` is called with no arg. Cloudflare Workers don't
+ *     materialise `import.meta.url` the way browsers do → throws
+ *     `TypeError: Invalid URL string`. (Broke production 2026-05-23,
+ *     captured via dev tail in run 26352287112.)
+ *
+ *   - `--target bundler` expects the host bundler to AUTO-INSTANTIATE
+ *     `import * as wasm from './foo.wasm'` so `wasm` is the
+ *     `Instance.exports` object. Webpack does this. **Wrangler does
+ *     NOT** — wrangler gives you a raw `WebAssembly.Module`, and the
+ *     bundler-target shim's `__wbg_set_wasm(rawModule)` happily
+ *     accepts it, then every export lookup (`wasm.__wbindgen_add_
+ *     to_stack_pointer`, etc.) returns undefined → throws
+ *     `TypeError: wasm.__wbindgen_add_to_stack_pointer is not a function`.
+ *     (Broke production 2026-05-24 after switching to bundler target
+ *     in PR #2785; captured via prod tail.)
+ *
+ * The fix is the standard Cloudflare-Workers + wasm-bindgen pattern:
+ * the consumer statically imports the `.wasm` file (wrangler then
+ * bundles it + hands the worker a `WebAssembly.Module`), then passes
+ * it to `init(wasmModule)`. The web target's init detects the Module
+ * input + calls `WebAssembly.instantiate(Module, imports)` internally
+ * to produce a real `Instance` whose exports populate the JS shim's
+ * `wasm` binding correctly.
+ *
+ * Vercel Edge / webpack consumers MAY omit the argument — webpack's
+ * async-WASM support handles the URL fetch correctly. But the typed
+ * signature here marks `wasmModule` optional for backward compat;
+ * Cloudflare-Workers consumers MUST pass it.
  *
  * **Why this matters for the consolidation narrative.** Phase A
  * shipped Node-only. Without an edge build, the first Vercel-edge
@@ -240,18 +273,21 @@ interface RenderedResponse {
 
 /**
  * Initialise the edge wasm module. Idempotent — subsequent calls
- * return the same in-flight or resolved promise. Host wrappers can
- * call this at startup to eagerly load the wasm and avoid first-
- * request latency, but it's not required: `engineVerifyEdge`
- * lazily initialises on first call.
- *
- * @param moduleOrPath  Optional pre-fetched `WebAssembly.Module` or
- *                      a URL / Request the wasm-bindgen loader will
- *                      fetch. Defaults to the bundled artifact via
- *                      `import.meta.url`. Cloudflare Workers / Vercel
- *                      Edge typically pass a pre-bundled `Module`.
+ * return the same in-flight or resolved promise. Host wrappers
+ * should call this once at startup with the `wasmModule` they
+ * statically imported from the package's `./wasm/kya-os-engine-web/`
+ * subpath (see CLAUDE.md for the wrangler/webpack import pattern).
+ *
+ * @param wasmModule  REQUIRED on Cloudflare Workers (wrangler hands
+ *                    the consumer a `WebAssembly.Module` from the
+ *                    static `.wasm` import; pass it here so the
+ *                    web-target's `init()` instantiates it). OPTIONAL
+ *                    on Vercel Edge / webpack — webpack's async-WASM
+ *                    support resolves the URL fetch correctly, but
+ *                    passing the module explicitly is recommended
+ *                    for cross-runtime consistency.
  */
-declare function initEngineEdge(moduleOrPath?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
+declare function initEngineEdge(wasmModule?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
 
 /**
  * HTTP-to-`AgentRequest` translator — Phase C.1.

package/dist/orchestrator.d.ts

@@ -222,11 +222,44 @@ interface RenderedResponse {
  * no sync wasm load).
  *
  * This module loads the `wasm-pack --target web` artifact via the
- * async `__wbg_init` default export, then exposes the same typed
- * `engineVerifyEdge(input, ctx) → Promise<VerifyResult>` shape with
- * a small lazy-init wrapper. First call awaits initialisation;
- * subsequent calls resolve synchronously on the JS side (the
- * underlying wasm `verify` is sync).
+ * async `__wbg_init` default export. The web target's `init()`
+ * accepts a pre-instantiated `WebAssembly.Module` argument — the
+ * canonical Cloudflare-Workers + wasm-bindgen pattern.
+ *
+ * # Why the caller MUST pass `wasmModule` on Cloudflare Workers
+ *
+ * Both `--target web` (URL fetch) and `--target bundler` (auto-
+ * instantiated `__wbg_set_wasm(wasm)`) have failure modes on wrangler:
+ *
+ *   - `--target web` falls back to `new URL('<wasm>', import.meta.url)`
+ *     when `init()` is called with no arg. Cloudflare Workers don't
+ *     materialise `import.meta.url` the way browsers do → throws
+ *     `TypeError: Invalid URL string`. (Broke production 2026-05-23,
+ *     captured via dev tail in run 26352287112.)
+ *
+ *   - `--target bundler` expects the host bundler to AUTO-INSTANTIATE
+ *     `import * as wasm from './foo.wasm'` so `wasm` is the
+ *     `Instance.exports` object. Webpack does this. **Wrangler does
+ *     NOT** — wrangler gives you a raw `WebAssembly.Module`, and the
+ *     bundler-target shim's `__wbg_set_wasm(rawModule)` happily
+ *     accepts it, then every export lookup (`wasm.__wbindgen_add_
+ *     to_stack_pointer`, etc.) returns undefined → throws
+ *     `TypeError: wasm.__wbindgen_add_to_stack_pointer is not a function`.
+ *     (Broke production 2026-05-24 after switching to bundler target
+ *     in PR #2785; captured via prod tail.)
+ *
+ * The fix is the standard Cloudflare-Workers + wasm-bindgen pattern:
+ * the consumer statically imports the `.wasm` file (wrangler then
+ * bundles it + hands the worker a `WebAssembly.Module`), then passes
+ * it to `init(wasmModule)`. The web target's init detects the Module
+ * input + calls `WebAssembly.instantiate(Module, imports)` internally
+ * to produce a real `Instance` whose exports populate the JS shim's
+ * `wasm` binding correctly.
+ *
+ * Vercel Edge / webpack consumers MAY omit the argument — webpack's
+ * async-WASM support handles the URL fetch correctly. But the typed
+ * signature here marks `wasmModule` optional for backward compat;
+ * Cloudflare-Workers consumers MUST pass it.
  *
  * **Why this matters for the consolidation narrative.** Phase A
  * shipped Node-only. Without an edge build, the first Vercel-edge
@@ -240,18 +273,21 @@ interface RenderedResponse {
 
 /**
  * Initialise the edge wasm module. Idempotent — subsequent calls
- * return the same in-flight or resolved promise. Host wrappers can
- * call this at startup to eagerly load the wasm and avoid first-
- * request latency, but it's not required: `engineVerifyEdge`
- * lazily initialises on first call.
- *
- * @param moduleOrPath  Optional pre-fetched `WebAssembly.Module` or
- *                      a URL / Request the wasm-bindgen loader will
- *                      fetch. Defaults to the bundled artifact via
- *                      `import.meta.url`. Cloudflare Workers / Vercel
- *                      Edge typically pass a pre-bundled `Module`.
+ * return the same in-flight or resolved promise. Host wrappers
+ * should call this once at startup with the `wasmModule` they
+ * statically imported from the package's `./wasm/kya-os-engine-web/`
+ * subpath (see CLAUDE.md for the wrangler/webpack import pattern).
+ *
+ * @param wasmModule  REQUIRED on Cloudflare Workers (wrangler hands
+ *                    the consumer a `WebAssembly.Module` from the
+ *                    static `.wasm` import; pass it here so the
+ *                    web-target's `init()` instantiates it). OPTIONAL
+ *                    on Vercel Edge / webpack — webpack's async-WASM
+ *                    support resolves the URL fetch correctly, but
+ *                    passing the module explicitly is recommended
+ *                    for cross-runtime consistency.
  */
-declare function initEngineEdge(moduleOrPath?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
+declare function initEngineEdge(wasmModule?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
 
 /**
  * HTTP-to-`AgentRequest` translator — Phase C.1.