@poe-platform/safe-js 0.1.734 → 0.1.735

package/README.md

@@ -566,7 +566,7 @@ functions can still be retained by custom Promise constructors.
 - `restore(snapshot, { source })` validates state for compatible source; pass it as `run`'s `snapshot` option. It does not run the program.
 - `new FileSnapshotBackend(path, { writeMaxAttempts?, writeRetryDelayMs? })` defaults to 3 write attempts and a 100 ms retry delay.
 - `createReplayableRandom({ seed?, snapshot? })` supplies `next`, `seed`, `snapshot`, and `restore` for reproducible random sequences. Unseeded generators use Web Crypto entropy; unseeded `makeTimeModule().uuid()` uses `globalThis.crypto.randomUUID()`.
-- `declareHostOperation(fn, policy, { onReplay?, awaitResult? })` declares `re-issue` or `read-side-effect` recovery policy. `registerPendingHostCallPolicy({ moduleId, operation, policy })` registers it by name. Only mark operations re-issuable when repeating them is acceptable; a declaration does not implement deduplication or external recovery. With `awaitResult: true`, an asynchronous host operation completes before the guest call returns its copied value or throws its error, without exposing a guest Promise. This is an explicit host capability; the host event loop still runs, and cancellation, value budgets, and host-call recovery still apply.
+- `declareHostOperation(fn, policy, { onReplay?, awaitResult?, callbackScheduling? })` declares `re-issue` or `read-side-effect` recovery policy. `registerPendingHostCallPolicy({ moduleId, operation, policy })` registers it by name. Only mark operations re-issuable when repeating them is acceptable; a declaration does not implement deduplication or external recovery. With `awaitResult: true`, an asynchronous host operation completes before the guest call returns its copied value or throws its error, without exposing a guest Promise. This is an explicit host capability; the host event loop still runs, and cancellation, value budgets, and host-call recovery still apply. Use `callbackScheduling: "after-prefix"` for event-style APIs whose callbacks must wait for the current guest synchronous work to finish or explicitly await. Callbacks can then await other callbacks without blocking their admission. The default keeps inline callback behavior; `after-prefix` cannot be combined with `awaitResult: true`.
 - `inspectSnapshotMigration(snapshot, { source })` inspects outstanding work. `migrateSnapshot(snapshot, { source, targetSource, state, reconciliation })` creates a continuation checkpoint. Reconciliation supplies `checkpointDigest`, `quiescent`, and `calls`; each call has `callId` and disposition `not-performed`, `fulfilled` with `value`, or `rejected` with `reason`.
 - `migrateSnapshotFile(options)` accepts `snapshotPath`, `sourcePath`, `targetSourcePath`, `planPath`, `outputPath`, `inspect`, `dryRun`, and `cwd`. Inspect mode needs the checkpoint and original source; migration also needs the target, plan, and new output path. See [continuation migration](MIGRATION.md) before changing a checkpointed program.
 

package/dist/safe-js/chunks/{chunk-MDIWQFYU.js → chunk-5X7TFA3E.js}

@@ -21924,6 +21924,10 @@ var hostErrorMetadata = {
   syscall: "string"
 };
 var awaitedHostOperations = /* @__PURE__ */ new WeakSet();
+var scheduledCallbackOperations = /* @__PURE__ */ new WeakSet();
+function schedulesHostCallbacks(operation) {
+  return scheduledCallbackOperations.has(operation);
+}
 var budgetedHostOperations = /* @__PURE__ */ new WeakMap();
 function declareBudgetedHostOperation(operation, invoke) {
   budgetedHostOperations.set(operation, invoke);
@@ -21931,7 +21935,11 @@ function declareBudgetedHostOperation(operation, invoke) {
 var hostOperationPolicies = /* @__PURE__ */ new WeakMap();
 var hostOperationReplayHandlers = /* @__PURE__ */ new WeakMap();
 function declareHostOperation(operation, policy, options = {}) {
+  if (options.callbackScheduling !== void 0 && options.callbackScheduling !== "after-prefix") throw new TypeError("Host callbackScheduling must be after-prefix.");
+  if (options.callbackScheduling === "after-prefix" && options.awaitResult === true) throw new TypeError("Queued callbacks cannot be combined with awaitResult.");
   hostOperationPolicies.set(operation, policy);
+  if (options.callbackScheduling === "after-prefix") scheduledCallbackOperations.add(operation);
+  else scheduledCallbackOperations.delete(operation);
   if (options.awaitResult === true) awaitedHostOperations.add(operation);
   else awaitedHostOperations.delete(operation);
   if (options.onReplay !== void 0) hostOperationReplayHandlers.set(operation, options.onReplay);
@@ -21970,6 +21978,7 @@ function wrapCallerInjectedFunction(name, value, options, state) {
   const bindingName = typeof nativeName === "string" && nativeName.length > 0 ? nativeName : name;
   const callable = value;
   const awaitResult = awaitedHostOperations.has(value) || options.realm?.awaitResult(callable) === true;
+  if (awaitResult && schedulesHostCallbacks(callable)) throw new TypeError("Queued callbacks cannot be combined with awaitResult or nestedOperation.");
   return createSandboxClosure({
     ...isAsyncFunction(callable) && !awaitResult ? { async: true } : {},
     cancellationSignal: options.signal,
@@ -21981,6 +21990,7 @@ function wrapCallerInjectedFunction(name, value, options, state) {
         if (options.signal?.aborted) throw readAbortReason2(options.signal);
         const stackFrames = context?.stack ?? [];
         const callbacks = {
+          ...schedulesHostCallbacks(callable) ? { schedule: captureJobScheduler() } : {},
           journal: options.hostCalls,
           entries: /* @__PURE__ */ new Map(),
           hostFunctions: /* @__PURE__ */ new Map(),
@@ -22002,7 +22012,8 @@ function wrapCallerInjectedFunction(name, value, options, state) {
             stackFrames,
             options.budget,
             operationLease.owner,
-            callbacks
+            callbacks,
+            options.signal
           ))
         });
         const captured = options.realm?.captureArguments(callable, args, copyArguments);
@@ -22427,18 +22438,19 @@ function copyHostErrorMetadata(error, reason, budget, chargeBudget) {
     resumeChecks?.();
   }
 }
-function wrapSandboxClosureForHost(closure, stackFrames, budget, compileOwner, callbacks) {
+function wrapSandboxClosureForHost(closure, stackFrames, budget, compileOwner, callbacks, signal) {
   const existing = callbacks?.seen.get(closure);
   if (existing !== void 0) return existing;
   const id = (callbacks?.entries.size ?? 0) + 1;
-  const invoke = async (sandboxArgs, token, receiver) => {
+  const invokeNow = async (sandboxArgs, token, receiver) => {
     const operation = budget.acquireCompileOwner(false, compileOwner);
     const compilation = new CompileScope(operation.owner);
     let leaveRunning;
     let leaveCall;
-    const wrapClosure = (nestedClosure) => wrapSandboxClosureForHost(nestedClosure, stackFrames, budget, compileOwner, callbacks);
+    const wrapClosure = (nestedClosure) => wrapSandboxClosureForHost(nestedClosure, stackFrames, budget, compileOwner, callbacks, signal);
     const onSharedBuffer = callbacks?.journal?.markSharedCallbackExport.bind(callbacks.journal);
     try {
+      signal?.throwIfAborted();
       leaveRunning = enterRunningState(closure);
       leaveCall = budget.enterCall();
       let result;
@@ -22454,6 +22466,7 @@ function wrapSandboxClosureForHost(closure, stackFrames, budget, compileOwner, c
           invokeClosure: (target, values, receiver2, construct, newTarget) => invokeBuiltinClosure(target, values, budget, callerContext, receiver2, construct, newTarget)
         };
         result = guestProxyStates.has(closure) ? await callGuestProxy(closure, sandboxArgs, budget, bridge, receiver) : closure.call(sandboxArgs, { compilation, stack: stackFrames, thisValue: receiver });
+        if (callbacks?.schedule !== void 0) result = await result;
       } catch (error) {
         if (isSandboxLikeValue(error)) {
           throw deepCopyFromSandbox(error, {
@@ -22464,11 +22477,17 @@ function wrapSandboxClosureForHost(closure, stackFrames, budget, compileOwner, c
         }
         throw error;
       }
-      return await deepCopyFromSandbox(normalizeClosureResult(result, budget), {
+      const settlement = deepCopyFromSandbox(normalizeClosureResult(result, budget), {
         compilation,
         wrapClosure,
         onSharedBuffer
       });
+      if (callbacks?.schedule !== void 0) {
+        void settlement.catch(() => void 0);
+        if (isSandboxPromise(result) && result.synchronousPrefix !== void 0) await result.synchronousPrefix;
+        return await suspendJob(settlement);
+      }
+      return await settlement;
     } catch (error) {
       if (isFatalBridgeError(error)) promiseReplayContext.getStore()?.fail(error);
       throw error;
@@ -22480,6 +22499,7 @@ function wrapSandboxClosureForHost(closure, stackFrames, budget, compileOwner, c
       if (token !== void 0) promiseReplayContext.getStore()?.completeCallback(token);
     }
   };
+  const invoke = callbacks?.schedule === void 0 ? invokeNow : (args, token, receiver) => callbacks.schedule(() => invokeNow(args, token, receiver));
   const wrapped = async function(...args) {
     const operation = budget.acquireCompileOwner(false, compileOwner);
     try {
@@ -49202,6 +49222,7 @@ export {
   createReplayEncodingContext,
   encodeReplayData,
   decodeReplayData,
+  schedulesHostCallbacks,
   declareBudgetedHostOperation,
   declareHostOperation,
   wrapCallerInjectedBindings,
@@ -49312,4 +49333,4 @@ authorization of the copyright holder.
 SPDX-License-Identifier: Unicode-3.0
 
 */
-//# sourceMappingURL=chunk-MDIWQFYU.js.map
+//# sourceMappingURL=chunk-5X7TFA3E.js.map