@steerprotocol/app-loader 3.0.5 → 3.1.0

package/README.md

@@ -126,6 +126,79 @@ The returned wasm wrapper exposes the module surface when available, including:
 - `transform()`
 - `reset()`
 
+### Panoptic RuntimeAdapter
+
+The Panoptic RuntimeAdapter is an additive Node-only feature. It is intended as
+a minor release surface, not a major-version runtime contract change:
+
+- existing `as-fetch` imports keep the same module names, function names, and
+  argument shapes
+- existing `env.ccxt_fetchOHLCV` keeps the same import name and argument shape
+- `env.panoptic_call` is added for wasm bundles that opt into Panoptic helpers
+- Panoptic SDK dependencies are optional unless a Panoptic method is called
+
+Browser entrypoints reject `panoptic` options explicitly until browser support
+is designed.
+
+Panoptic support is optional. Consumers that call Panoptic methods must install
+the optional peers used by the adapter:
+
+```bash
+npm install @panoptic-eng/sdk@1.0.15 viem
+```
+
+Some SDK entrypoints also declare React/Wagmi peers; packaged SDK smoke tests
+install the full SDK peer set.
+
+WASM calls the adapter through the additive async import:
+
+```ts
+env.panoptic_call(methodPtr, paramsJsonPtr)
+```
+
+Only JSON-serializable DTOs cross that boundary. SDK objects, viem clients,
+providers, wallet clients, signers, and transaction submission helpers stay in
+the JavaScript host. The adapter returns deterministic reads, protocol calldata
+parts, and DynamicJobs fragments; it does not sign or submit transactions.
+
+The stable helper families are:
+
+- read snapshots: `pool.*`, `account.*`, `greeks.*`, `hypovault.*`, and
+  `uniswap.*` read/quote helpers
+- protocol fragments: `erc20.*Fragment`, `permit2.*Fragment`,
+  `collateral.*Fragment`, `hypovault.*Fragment`, `merkle.*Fragment`, and
+  `panoptic.*Fragment`
+- calldata parts for nested composition: Panoptic dispatch, HypoVault manager
+  `manage`, WETH wrap/unwrap calls, and Universal Router v3 exact-in execute
+- DynamicJobs rendering: `dynamicJobs.renderExecuteJob`
+
+DynamicJobs fragments use the same shape the strategy already emits:
+`target + userProvidedData + strategyProvidedData`. Fragment builders take
+semantic contract inputs and return that fragment shape directly. App-loader
+does not duplicate the orchestrator/job registration manifest:
+
+```ts
+await loadWasm(wasmBytes, {}, {
+  panoptic: {
+    sourceRegistry: {
+      sources: [{ sourceId: 'base-mainnet', chainId: '8453', rpcUrl: 'https://base.example' }],
+    },
+  },
+});
+```
+
+`dynamicJobs.renderExecuteJob` renders fragments into
+`executeJob(address[],bytes[],bytes[])`. It validates only fragment shape,
+zero native value, and serializable bytes, then returns the payload arrays.
+Whether `target + userProvidedData` is registered/executable is handled later
+by the orchestrator and DynamicJobs/contracts. The actual execution boundary
+remains the DynamicJobs registration, the orchestrator caller check, and the
+destination contracts.
+
+The adapter intentionally does not expose host signing, wallet clients, write
+transaction helpers, or SDK object graphs across the wasm boundary.
+`calldata.*` names are not part of the stable RuntimeAdapter API.
+
 ## Development
 
 ### Build
@@ -161,6 +234,19 @@ npm run test:consumers
 This command builds the package, packs it, installs the tarball into fixture apps, validates the packed export artifacts,
 and runs each fixture check.
 
+The Panoptic SDK package smoke test additionally installs `@panoptic-eng/sdk@1.0.15`
+and exercises a real SDK-backed AS fixture:
+
+```bash
+npm run test:panoptic-sdk-smoke
+```
+
+The full verification gate is:
+
+```bash
+npm run verify:phase0
+```
+
 ## Migration Notes
 
 Version 2 changes the package runtime contract.

package/lib/browser.d.ts

@@ -2,6 +2,7 @@
  * Browser-only entrypoints for loading Steer wasm bundles.
  */
 import { Candle, RawTradeData } from './internal/instantiate';
+import type { LoadWasmOptions } from './loadOptions';
 import type { WasmModule } from './WasmModule';
 /**
  * Load a wasm bundle synchronously. Only accepts the actual binary data.
@@ -9,13 +10,15 @@ import type { WasmModule } from './WasmModule';
  * @param imports - Imports
  * @returns
  */
-declare function loadWasmSync(input: ArrayBuffer, imports?: {}): WasmModule;
+declare function loadWasmSync(input: ArrayBuffer, imports?: {}, options?: LoadWasmOptions): WasmModule;
 /**
  * Load a wasm bundle asynchronously. Accepts the actual binary data or URL.
  * @param input - Wasm bundle data or URL
  * @param imports - Imports
  * @returns
  */
-declare function loadWasm(input: string | ArrayBuffer, imports?: {}): Promise<WasmModule>;
+declare function loadWasm(input: string | ArrayBuffer, imports?: {}, options?: LoadWasmOptions): Promise<WasmModule>;
 export type { WasmModule } from './WasmModule';
+export type { LoadWasmOptions } from './loadOptions';
+export type { PanopticAuditEvent, PanopticClientCacheOptions, PanopticJsonValue, PanopticOperationOptions, PanopticRpcSource, PanopticRuntimeOptions, PanopticSourceRegistry, PanopticSubgraphSource, SourceMeta, } from './panoptic';
 export { loadWasm, loadWasmSync, Candle, RawTradeData };

package/lib/browser.mjs

@@ -173,6 +173,144 @@ var RawTradeData = class {
   }
 };
 
+// src/internal/asyncHostCalls.ts
+function createAsyncHostCallSlot() {
+  let stagedHostCall = null;
+  let completedHostCall = null;
+  function stage(call) {
+    if (stagedHostCall || completedHostCall) {
+      throw new Error("Only one async host call can be staged per asyncify unwind.");
+    }
+    stagedHostCall = call;
+  }
+  async function complete() {
+    if (!stagedHostCall) {
+      throw new Error("Asyncify unwound without a staged host call.");
+    }
+    const call = stagedHostCall;
+    stagedHostCall = null;
+    if (call.kind === "fetch-buffer") {
+      completedHostCall = { kind: "fetch-buffer", value: await call.run() };
+      return;
+    }
+    if (call.kind === "ccxt-ohlcv") {
+      completedHostCall = { kind: "ccxt-ohlcv", value: await call.run() };
+      return;
+    }
+    completedHostCall = { kind: "panoptic-json", value: await call.run() };
+  }
+  function take(kind) {
+    if (!completedHostCall) {
+      throw new Error(`Asyncify rewind for ${kind} did not have a completed host result.`);
+    }
+    if (completedHostCall.kind !== kind) {
+      throw new Error(`Asyncify rewind expected ${kind} but found ${completedHostCall.kind}.`);
+    }
+    const call = completedHostCall;
+    completedHostCall = null;
+    return call;
+  }
+  function reset() {
+    stagedHostCall = null;
+    completedHostCall = null;
+  }
+  return { stage, complete, take, reset };
+}
+
+// src/internal/panoptic/protocol.ts
+var DEFAULT_MAX_REQUEST_BYTES = 512 * 1024;
+function parsePanopticRequest(value, maxBytes = DEFAULT_MAX_REQUEST_BYTES) {
+  if (utf8ByteLength(value) > maxBytes) {
+    throw new Error(`Invalid Panoptic request JSON: request exceeds maximum size ${maxBytes} bytes.`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`Invalid Panoptic request JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isJsonObject(parsed) || !isJsonValue(parsed)) {
+    throw new Error("Invalid Panoptic request JSON: expected a JSON-safe object envelope.");
+  }
+  return parsed;
+}
+function assertPanopticSuccessResponse(value) {
+  const keys = isJsonObject(value) ? Object.keys(value) : [];
+  if (!isJsonObject(value) || value.ok !== true || !("result" in value) || !isJsonValue(value.result) || keys.length !== 2 || !keys.includes("ok") || !keys.includes("result")) {
+    throw new Error("Panoptic runtime adapter returned an invalid success response.");
+  }
+}
+function isJsonObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function isJsonValue(value) {
+  if (value === null) return true;
+  const valueType = typeof value;
+  if (valueType === "string" || valueType === "number" || valueType === "boolean") {
+    return Number.isFinite(value) || valueType !== "number";
+  }
+  if (Array.isArray(value)) {
+    return value.every(isJsonValue);
+  }
+  if (isJsonObject(value)) {
+    return Object.values(value).every(isJsonValue);
+  }
+  return false;
+}
+function utf8ByteLength(value) {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const codePoint = value.codePointAt(i) || 0;
+    if (codePoint <= 127) {
+      bytes += 1;
+    } else if (codePoint <= 2047) {
+      bytes += 2;
+    } else if (codePoint <= 65535) {
+      bytes += 3;
+    } else {
+      bytes += 4;
+      i += 1;
+    }
+  }
+  return bytes;
+}
+
+// src/internal/panopticHostImport.ts
+function createPanopticHostImport(options) {
+  return (methodPtr, paramsJsonPtr) => {
+    if (options.getAsyncifyState() === options.rewindingState) {
+      options.stopRewind();
+      const completed = options.hostCalls.take("panoptic-json");
+      return options.lowerString(completed.value, "wasm");
+    }
+    const method = options.liftString(methodPtr);
+    const paramsJson = options.liftString(paramsJsonPtr) || "{}";
+    options.hostCalls.stage({
+      kind: "panoptic-json",
+      run: async () => {
+        if (!method) {
+          throw new Error("Panoptic method not provided.");
+        }
+        const request = parsePanopticRequest(paramsJson);
+        const response = await callPanopticOrThrow(options.runtime, method, request);
+        assertPanopticSuccessResponse(response);
+        return JSON.stringify({ ok: true, result: response.result });
+      }
+    });
+    options.startUnwind();
+  };
+}
+async function callPanopticOrThrow(runtime, method, request) {
+  if (!runtime.callPanoptic) {
+    throw new Error("Panoptic runtime adapter is not available in this runtime.");
+  }
+  return runtime.callPanoptic(method, request);
+}
+
 // src/internal/instantiate.ts
 function instantiate(module, imports = {}, runtime = {}) {
   let WASM_MEMORY;
@@ -181,9 +319,7 @@ function instantiate(module, imports = {}, runtime = {}) {
   let ASYNCIFY_PTR = 0;
   let ASYNCIFY_MEM;
   let ASYNCIFY_INITIALIZED = false;
-  let fetchFn = null;
-  let ccxtFn = null;
-  let detachedValue = null;
+  const hostCalls = createAsyncHostCallSlot();
   let executeInFlight = false;
   const pinScopes = [];
   const adaptedImports = Object.assign(
@@ -281,31 +417,50 @@ function instantiate(module, imports = {}, runtime = {}) {
           const currentState = WASM_EXPORTS.asyncify_get_state();
           if (currentState === 2 /* Rewinding */) {
             WASM_EXPORTS.asyncify_stop_rewind();
+            const completed = hostCalls.take("ccxt-ohlcv");
             const ptr = __lowerStaticArray(
               (pointer, value) => {
-                __setU32(pointer, __lowerStaticArray(__setF64, 7, 3, value, Float64Array));
+                __setU32(pointer, __lowerStaticArray(__setF64, 7, 3, value, Float64Array, "wasm"));
               },
               8,
               2,
-              detachedValue
+              completed.value,
+              null,
+              "host"
             );
             return ptr;
           }
           const _exchange = __liftString(exchangeId);
           const _symbol = __liftString(symbol);
           const _timeframe = __liftString(timeframe);
-          ccxtFn = async () => {
-            if (!_exchange || !_symbol || !_timeframe)
-              throw new Error("Exchange, Symbol, or Timeframe not provided when fetching OHCLV data.");
-            const ccxt = await getCcxtOrThrow(runtime);
-            const data = await new ccxt[_exchange]({
-              apiKey: "",
-              secret: ""
-            }).fetchOHLCV(_symbol, _timeframe, since, limit);
-            return data;
-          };
+          hostCalls.stage({
+            kind: "ccxt-ohlcv",
+            run: async () => {
+              if (!_exchange || !_symbol || !_timeframe)
+                throw new Error("Exchange, Symbol, or Timeframe not provided when fetching OHCLV data.");
+              const ccxt = await getCcxtOrThrow(runtime);
+              const data = await new ccxt[_exchange]({
+                apiKey: "",
+                secret: ""
+              }).fetchOHLCV(_symbol, _timeframe, since, limit);
+              return data;
+            }
+          });
           WASM_EXPORTS.asyncify_start_unwind(ASYNCIFY_PTR);
-        }
+        },
+        panoptic_call: createPanopticHostImport({
+          runtime,
+          hostCalls,
+          // @ts-ignore
+          getAsyncifyState: () => WASM_EXPORTS.asyncify_get_state(),
+          rewindingState: 2 /* Rewinding */,
+          // @ts-ignore
+          stopRewind: () => WASM_EXPORTS.asyncify_stop_rewind(),
+          // @ts-ignore
+          startUnwind: () => WASM_EXPORTS.asyncify_start_unwind(ASYNCIFY_PTR),
+          liftString: __liftString,
+          lowerString: __lowerString
+        })
       },
       "as-fetch": {
         /**
@@ -336,25 +491,28 @@ function instantiate(module, imports = {}, runtime = {}) {
           const currentState = WASM_EXPORTS.asyncify_get_state();
           if (currentState === 2 /* Rewinding */) {
             WASM_EXPORTS.asyncify_stop_rewind();
-            const ptr = __lowerBuffer(detachedValue);
-            detachedValue = null;
+            const completed = hostCalls.take("fetch-buffer");
+            const ptr = __lowerBuffer(completed.value, "wasm");
             return ptr;
           }
-          fetchFn = async () => {
-            const fetchImpl = await getFetchOrThrow(runtime);
-            const res = await fetchImpl(__liftString(url) || "", {
-              method: "POST",
-              mode: modeToString(mode) || "cors",
-              headers: __liftArray(
-                (pointer) => __liftArray((pointer2) => __liftString(__getU32(pointer2)), 2, __getU32(pointer)),
-                2,
-                headers
-              ) || [],
-              body: __liftBuffer(body)
-            });
-            const value = await res.arrayBuffer();
-            return value;
-          };
+          hostCalls.stage({
+            kind: "fetch-buffer",
+            run: async () => {
+              const fetchImpl = await getFetchOrThrow(runtime);
+              const res = await fetchImpl(__liftString(url) || "", {
+                method: "POST",
+                mode: modeToString(mode) || "cors",
+                headers: __liftArray(
+                  (pointer) => __liftArray((pointer2) => __liftString(__getU32(pointer2)), 2, __getU32(pointer)),
+                  2,
+                  headers
+                ) || [],
+                body: __liftBuffer(body)
+              });
+              const value = await res.arrayBuffer();
+              return value;
+            }
+          });
           WASM_EXPORTS.asyncify_start_unwind(ASYNCIFY_PTR);
         },
         /**
@@ -368,24 +526,27 @@ function instantiate(module, imports = {}, runtime = {}) {
           const currentState = WASM_EXPORTS.asyncify_get_state();
           if (currentState === 2 /* Rewinding */) {
             WASM_EXPORTS.asyncify_stop_rewind();
-            const ptr = __lowerBuffer(detachedValue);
-            detachedValue = null;
+            const completed = hostCalls.take("fetch-buffer");
+            const ptr = __lowerBuffer(completed.value, "wasm");
             return ptr;
           }
-          fetchFn = async () => {
-            const fetchImpl = await getFetchOrThrow(runtime);
-            const res = await fetchImpl(__liftString(url) || "", {
-              method: "GET",
-              mode: modeToString(mode) || "cors",
-              headers: __liftArray(
-                (pointer) => __liftArray((pointer2) => __liftString(__getU32(pointer2)), 2, __getU32(pointer)),
-                2,
-                headers
-              ) || []
-            });
-            const value = await res.arrayBuffer();
-            return value;
-          };
+          hostCalls.stage({
+            kind: "fetch-buffer",
+            run: async () => {
+              const fetchImpl = await getFetchOrThrow(runtime);
+              const res = await fetchImpl(__liftString(url) || "", {
+                method: "GET",
+                mode: modeToString(mode) || "cors",
+                headers: __liftArray(
+                  (pointer) => __liftArray((pointer2) => __liftString(__getU32(pointer2)), 2, __getU32(pointer)),
+                  2,
+                  headers
+                ) || []
+              });
+              const value = await res.arrayBuffer();
+              return value;
+            }
+          });
           WASM_EXPORTS.asyncify_start_unwind(ASYNCIFY_PTR);
         },
         /**
@@ -501,6 +662,7 @@ function instantiate(module, imports = {}, runtime = {}) {
         }
         executeInFlight = true;
         const replayArgs = snapshotLogicalArgs(params);
+        pinScopes.push([]);
         try {
           let result;
           try {
@@ -515,25 +677,18 @@ function instantiate(module, imports = {}, runtime = {}) {
           if (ASYNCIFY_INITIALIZED) {
             while (WASM_EXPORTS.asyncify_get_state() === 1 /* Unwinding */) {
               WASM_EXPORTS.asyncify_stop_unwind();
-              if (fetchFn) {
-                const pendingFetch = fetchFn;
-                fetchFn = null;
-                detachedValue = await pendingFetch();
-              }
-              if (ccxtFn) {
-                const pendingCcxt = ccxtFn;
-                ccxtFn = null;
-                detachedValue = await pendingCcxt();
-              }
+              await hostCalls.complete();
               WASM_EXPORTS.asyncify_start_rewind(ASYNCIFY_PTR);
               result = executeWithReplayArgs(replayArgs);
             }
           }
           return __liftString(result);
         } finally {
-          fetchFn = null;
-          ccxtFn = null;
-          detachedValue = null;
+          const scope = pinScopes.pop() || [];
+          for (let i = scope.length - 1; i >= 0; i--) {
+            WASM_EXPORTS.__unpin(scope[i]);
+          }
+          hostCalls.reset();
           executeInFlight = false;
         }
       },
@@ -592,7 +747,7 @@ function instantiate(module, imports = {}, runtime = {}) {
     });
   }
   function executeWithReplayArgs(values) {
-    return withPinScope(() => WASM_EXPORTS.execute(...lowerArgs(values)));
+    return withAutoPinScope(() => WASM_EXPORTS.execute(...lowerArgs(values)));
   }
   function withPinScope(fn) {
     pinScopes.push([]);
@@ -627,10 +782,10 @@ function instantiate(module, imports = {}, runtime = {}) {
     while (end - start > 1024) string += String.fromCharCode(...memoryU16.subarray(start, start += 1024));
     return string + String.fromCharCode(...memoryU16.subarray(start, end));
   }
-  function __lowerString(value) {
+  function __lowerString(value, owner = "host") {
     if (value == null) return 0;
     const length = value.length;
-    const ptr = trackPinnedPointer(WASM_EXPORTS.__pin(WASM_EXPORTS.__new(length << 1, 2) >>> 0));
+    const ptr = allocateLoweredPointer(length << 1, 2, owner);
     const memoryU16 = new Uint16Array(WASM_MEMORY.buffer);
     for (let i = 0; i < length; ++i) memoryU16[(ptr >>> 1) + i] = value.charCodeAt(i);
     return ptr;
@@ -639,9 +794,9 @@ function instantiate(module, imports = {}, runtime = {}) {
     if (!ptr) return null;
     return WASM_MEMORY.buffer.slice(ptr, ptr + new Uint32Array(WASM_MEMORY.buffer)[ptr - 4 >>> 2]);
   }
-  function __lowerBuffer(value) {
+  function __lowerBuffer(value, owner = "host") {
     if (value == null) return 0;
-    const ptr = trackPinnedPointer(WASM_EXPORTS.__pin(WASM_EXPORTS.__new(value.byteLength, 1) >>> 0));
+    const ptr = allocateLoweredPointer(value.byteLength, 1, owner);
     new Uint8Array(WASM_MEMORY.buffer).set(new Uint8Array(value), ptr);
     return ptr;
   }
@@ -653,10 +808,10 @@ function instantiate(module, imports = {}, runtime = {}) {
     for (let i = 0; i < length; ++i) values[i] = liftElement(dataStart + (i << align >>> 0));
     return values;
   }
-  function __lowerStaticArray(lowerElement, id, align, values, typedConstructor = null) {
+  function __lowerStaticArray(lowerElement, id, align, values, typedConstructor = null, owner = "host") {
     if (values == null) return 0;
     const length = values.length;
-    const buffer = trackPinnedPointer(WASM_EXPORTS.__pin(WASM_EXPORTS.__new(length << align, id)) >>> 0) >>> 0;
+    const buffer = allocateLoweredPointer(length << align, id, owner) >>> 0;
     if (typedConstructor) {
       new typedConstructor(WASM_MEMORY.buffer, buffer, length).set(values);
     } else {
@@ -664,6 +819,13 @@ function instantiate(module, imports = {}, runtime = {}) {
     }
     return buffer;
   }
+  function allocateLoweredPointer(size, id, owner) {
+    const ptr = WASM_EXPORTS.__new(size, id) >>> 0;
+    if (owner === "wasm") {
+      return ptr;
+    }
+    return trackPinnedPointer(WASM_EXPORTS.__pin(ptr) >>> 0);
+  }
   function __setU32(ptr, value) {
     try {
       WASM_DV.setUint32(ptr, value, true);
@@ -710,20 +872,38 @@ function modeToString(mode) {
   return null;
 }
 
+// src/internal/panopticBrowserRuntime.ts
+async function callBrowserPanoptic(method, request) {
+  void method;
+  void request;
+  throw new Error(
+    "Panoptic runtime adapter is not enabled for browser runtimes yet. Phase 8 must choose globalThis SDK globals or dynamic browser imports first."
+  );
+}
+
 // src/browser.ts
-function loadWasmSync(input, imports = {}) {
+function loadWasmSync(input, imports = {}, options = {}) {
+  assertBrowserOptionsSupported(options);
   return instantiate(new WebAssembly.Module(input), imports, {
     getFetch: getBrowserFetch,
-    getCcxt: getBrowserCcxt
+    getCcxt: getBrowserCcxt,
+    callPanoptic: callBrowserPanoptic
   });
 }
-async function loadWasm(input, imports = {}) {
+async function loadWasm(input, imports = {}, options = {}) {
+  assertBrowserOptionsSupported(options);
   const module = typeof input === "string" ? await compileFromUrl(input) : await WebAssembly.compile(input);
   return instantiate(module, imports, {
     getFetch: getBrowserFetch,
-    getCcxt: getBrowserCcxt
+    getCcxt: getBrowserCcxt,
+    callPanoptic: callBrowserPanoptic
   });
 }
+function assertBrowserOptionsSupported(options) {
+  if (options.panoptic) {
+    throw new Error("Panoptic runtime adapter is Node-only until browser support lands.");
+  }
+}
 async function compileFromUrl(url) {
   const fetchImpl = await getBrowserFetch();
   const response = await fetchImpl(url);