@poe-platform/safe-js 0.1.22 → 0.1.24

package/README.md

@@ -116,9 +116,9 @@ This prints `2`. Evaluations share declarations, closures and object identity wi
 | --- | --- |
 | `extensions` | Explicit `defineExtension(...)` registrations; `[]`. Setup runs once, on first evaluation, not on construction or unused close. |
 | `grants` | Granted capability names; `[]`. Every requested capability must be granted before any extension setup runs. |
-| `limits` | Positive integer caps: `extensions: 32`, `hostObjects: 1024`, `callbacks: 1024`, `cleanups: 1024`, `nestedEvaluations: 16`. Collection budgets also apply. |
+| `limits` | Positive integer caps: `extensions: 32`, `hostObjects: 1024`, `callbacks: 1024`, `guestReferences: 1024`, `cleanups: 1024`, `nestedEvaluations: 16`. Collection budgets also apply. |
 
-Ordinary host arguments/results are still copied. To preserve live native identity, explicitly create a host object. A guest function crossing to the host becomes an opaque callback: invoke it with `realm.invokeCallback(callback, { thisValue?, args? })`, then `realm.releaseCallback(callback)` when no longer needed. Callbacks and live objects cannot cross realms or survive close. Guest-object argument retention is not yet supported; copying a timer argument does not preserve its guest identity.
+Ordinary host arguments/results are still copied. To preserve live native identity, explicitly create a host object. A guest function crossing to the host becomes an opaque callback: invoke it with `realm.invokeCallback(callback, { thisValue?, args? })`, then `realm.releaseCallback(callback)` when no longer needed. Callbacks and live objects cannot cross realms or survive close. For deferred arguments that must preserve guest identity, opt into retained references as described below.
 
 <details>
 <summary>Trusted extensions and live host objects</summary>
@@ -163,9 +163,15 @@ The manifest requires `version: 1` and a nonempty `name`. Optional `capabilities
 | `createHostObject({ properties?, methods? })` | Create a realm-owned capability. Properties declare synchronous `get`/`set` functions; methods are host functions. Undeclared members expose no native prototype. |
 | `invokeCallback(callback, { thisValue?, args? })` | Invoke a captured guest function with the realm's state, cancellation and budgets. Same operation as on the realm. |
 | `releaseCallback(callback)` | Revoke the callback and release its retained guest state. |
+| `retainGuestArguments(operation, from)` | During setup, opt an operation into opaque argument references starting at the zero-based index `from`. Requires declared and granted `guest:retain`. Earlier arguments keep normal conversion; live host methods preserve the declaration. |
+| `releaseGuestReference(reference)` | Revoke one reference and release its retained state. Also available on the realm. |
 | `nestedOperation(fn)` | During setup, mark a host operation authorized to run nested source. Requires declared and granted `source:nested`. |
 | `evaluateNested(source)` | Only inside that extension's authorized operation. Completes before the enclosing call returns to guest code, shares scope/budgets, and propagates errors. Parallel nested evaluations and ordinary source reentry are rejected. |
 
+For a timer-shaped `schedule(callback, delay, ...args)`, register `context.retainGuestArguments(schedule, 2)`. The host receives normal callback/delay values and opaque `GuestReference` handles for the remaining arguments. Pass those handles to `context.invokeCallback(callback, { args })` to recover the original guest objects and observe mutations made after scheduling. References also work as callback receivers and host return values, including cycles, closures, primitives and live host objects.
+
+Release each reference when the host no longer needs it; returning it does not release it. Retained graphs count against data budgets and `limits.guestReferences`. Synchronous native failure releases references captured for that call; asynchronous operations must release theirs in host cleanup. Close revokes all remaining references. Handles cannot be inspected, used in another realm, or serialized into replay/error data. Unmarked operations still copy values.
+
 Live objects do not support native prototypes, property-descriptor manipulation or portable serialization. Realm state is not a checkpoint: snapshot/replay and live-capability error-data conversion are rejected. Extensions are trusted native code; grants are a registration contract, not OS isolation. Native work still needs host timeouts and external process supervision for hard limits. No DOM, timers or browser engine are bundled.
 
 For one-shot use, `run(source, { extensions, grants, ... })` accepts the same realm options plus `filename`, returns data only, and closes resources before settling. Run-only features such as snapshots, `entryPointArgs`, `importMeta`, custom clocks/random generators and telemetry are rejected in this mode rather than silently ignored.

package/dist/safe-js/chunks/{chunk-2M6MNQBY.js → chunk-MXUOEOBE.js}

@@ -6211,6 +6211,25 @@ function copyFloat32Storage(value, state) {
 var hostObjects = /* @__PURE__ */ new WeakMap();
 var guestObjects = /* @__PURE__ */ new WeakMap();
 var guestCallbacks = /* @__PURE__ */ new WeakMap();
+var guestReferences = /* @__PURE__ */ new WeakMap();
+function createGuestReference(root, owner, assertActive) {
+  const reference = Object.freeze(/* @__PURE__ */ Object.create(null));
+  guestReferences.set(reference, { root, owner, assertActive });
+  return reference;
+}
+function readGuestReference(reference, owner) {
+  const state = typeof reference === "object" && reference !== null ? guestReferences.get(reference) : void 0;
+  if (state === void 0 || state.owner !== owner)
+    throw new TypeError("Foreign or invalid guest reference.");
+  state.assertActive();
+  if (state.root === void 0) throw new TypeError("Guest reference is revoked.");
+  return state.root[0];
+}
+function revokeGuestReference(reference, owner) {
+  const state = guestReferences.get(reference);
+  if (state === void 0 || state.owner !== owner) throw new TypeError("Foreign guest reference.");
+  state.root = void 0;
+}
 function createLiveHostObject(definition, controller) {
   const input = readDataRecord(definition, "Host object definition");
   if (Object.keys(input).some((key) => key !== "properties" && key !== "methods"))
@@ -6254,9 +6273,10 @@ function isGuestHostObject(value) {
   return typeof value === "object" && value !== null && guestObjects.has(value);
 }
 function isLiveCapability(value) {
-  return (typeof value === "object" && value !== null || typeof value === "function") && (hostObjects.has(value) || guestObjects.has(value) || guestCallbacks.has(value));
+  return (typeof value === "object" && value !== null || typeof value === "function") && (hostObjects.has(value) || guestObjects.has(value) || guestCallbacks.has(value) || guestReferences.has(value));
 }
 function importHostCapability(value, owner) {
+  if (guestReferences.has(value)) return readGuestReference(value, owner);
   const object = hostObjects.get(value);
   if (object !== void 0) {
     if (object.controller.owner !== owner) throw new TypeError("Foreign realm host capability.");
@@ -28043,7 +28063,7 @@ function wrapCallerInjectedFunction(name, value, options, state) {
           seen: /* @__PURE__ */ new WeakMap(),
           restored: []
         };
-        const hostArgs = deepCopyFromSandbox([...args], {
+        const copyArguments = (values) => deepCopyFromSandbox([...values], {
           compilation,
           unwrapHostObject: options.realm === void 0 ? void 0 : (object) => exportHostCapability(object, options.realm.owner),
           wrapClosure: (closure) => options.realm?.wrapCallback(closure) ?? wrapSandboxClosureForHost(
@@ -28054,13 +28074,21 @@ function wrapCallerInjectedFunction(name, value, options, state) {
             callbacks
           )
         });
+        const captured = options.realm?.captureArguments(callable, args, copyArguments);
+        const hostArgs = captured?.args ?? copyArguments(args);
         const hostCalls = options.hostCalls;
         const operation = options.operation ?? bindingName;
         const moduleId = options.moduleId ?? "<bindings>";
         const policy = readHostOperationPolicy(value) ?? readRegisteredPendingHostCallPolicy(moduleId, operation) ?? "re-issue";
         if (hostCalls === void 0) {
           if (options.realm !== void 0) {
-            const result = options.realm.invoke(callable, () => Reflect.apply(callable, void 0, hostArgs));
+            let result;
+            try {
+              result = options.realm.invoke(callable, () => Reflect.apply(callable, void 0, hostArgs));
+            } catch (error) {
+              captured.rollback();
+              throw error;
+            }
             if (options.realm.awaitResult(callable)) {
               return Promise.resolve(result).then((value2) => copyHostResultToSandbox(value2, stackFrames, options));
             }
@@ -30095,6 +30123,7 @@ var RealmState = class {
       extensions: 32,
       hostObjects: 1024,
       callbacks: 1024,
+      guestReferences: 1024,
       cleanups: 1024,
       nestedEvaluations: 16
     };
@@ -30131,6 +30160,7 @@ var RealmState = class {
       owner: this,
       assertActive: this.assertOpen,
       wrapCallback: this.wrapCallback,
+      captureArguments: this.captureArguments,
       invoke: this.invokeHost,
       awaitResult: (operation) => this.nestedOperations.has(operation)
     };
@@ -30170,7 +30200,7 @@ var RealmState = class {
       }
       options.signal?.addEventListener("abort", this.abort, { once: true });
       if (options.signal?.aborted) this.abort();
-      this.budget.setRetainedValues(this, this.retainedCallbacks);
+      this.budget.setRetainedValues(this, this.retainedRoots);
       this.tracker.onFatalRejection((error) => this.poison(error));
     } catch (error) {
       this.compilation.dispose();
@@ -30194,6 +30224,8 @@ var RealmState = class {
   pendingCallbacks = /* @__PURE__ */ new Set();
   callbackCache = /* @__PURE__ */ new WeakMap();
   hostObjects = /* @__PURE__ */ new Set();
+  guestReferences = /* @__PURE__ */ new Map();
+  retainedOperations = /* @__PURE__ */ new WeakMap();
   nestedOperations = /* @__PURE__ */ new WeakMap();
   convertedModules = /* @__PURE__ */ new Map();
   nativeConversions = { seen: /* @__PURE__ */ new WeakMap() };
@@ -30213,10 +30245,56 @@ var RealmState = class {
     signal: this.controller.signal,
     realm: this.bridge
   });
-  retainedCallbacks = () => [
+  retainedRoots = () => [
     ...this.callbacks.values(),
-    ...Array.from(this.pendingCallbacks, (pending) => pending.closure)
+    ...Array.from(this.pendingCallbacks, (pending) => pending.closure),
+    ...this.guestReferences.values()
   ];
+  captureArguments = (operation, args, copy) => {
+    const from = this.retainedOperations.get(operation)?.from ?? args.length;
+    const values = copy(args.slice(0, from));
+    const captured = [];
+    const rollback = () => {
+      for (const reference of captured) {
+        revokeGuestReference(reference, this);
+        this.guestReferences.delete(reference);
+      }
+    };
+    try {
+      for (const value of args.slice(from)) {
+        this.checkCollection(
+          this.guestReferences.size + 1,
+          this.limits.guestReferences,
+          "guest reference"
+        );
+        const root = [value];
+        const reference = createGuestReference(root, this, this.assertOpen);
+        this.guestReferences.set(reference, root);
+        captured.push(reference);
+        values.push(reference);
+      }
+      if (captured.length > 0)
+        this.budget.reconcileDataUsage(
+          measureSandboxData([...this.scope?.retainedValues() ?? [], ...this.retainedRoots()])
+        );
+      return { args: values, rollback };
+    } catch (error) {
+      rollback();
+      if (error instanceof SandboxError) this.poison(error);
+      throw error;
+    }
+  };
+  releaseGuestReference = (reference) => {
+    readGuestReference(reference, this);
+    revokeGuestReference(reference, this);
+    this.guestReferences.delete(reference);
+    if (this.active === void 0)
+      reconcileCompiledValues(
+        this.budget,
+        [...this.scope?.retainedValues() ?? [], ...this.retainedRoots()],
+        this.compilation
+      );
+  };
   assertOpen = () => {
     if (this.failure !== void 0) throw this.failure.reason;
     if (this.closed) throw new Error("SafeJS realm is closed; capabilities are revoked.");
@@ -30384,7 +30462,7 @@ var RealmState = class {
     });
     try {
       this.budget.reconcileDataUsage(
-        measureSandboxData([...this.scope?.retainedValues() ?? [], ...this.retainedCallbacks()])
+        measureSandboxData([...this.scope?.retainedValues() ?? [], ...this.retainedRoots()])
       );
     } catch (error) {
       this.poison(error);
@@ -30399,7 +30477,7 @@ var RealmState = class {
     if (this.active === void 0)
       reconcileCompiledValues(
         this.budget,
-        [...this.scope?.retainedValues() ?? [], ...this.retainedCallbacks()],
+        [...this.scope?.retainedValues() ?? [], ...this.retainedRoots()],
         this.compilation
       );
   };
@@ -30458,7 +30536,7 @@ var RealmState = class {
       if (!this.closed && this.active === void 0)
         reconcileCompiledValues(
           this.budget,
-          [...this.scope?.retainedValues() ?? [], ...this.retainedCallbacks()],
+          [...this.scope?.retainedValues() ?? [], ...this.retainedRoots()],
           this.compilation
         );
     }
@@ -30475,6 +30553,23 @@ var RealmState = class {
         createHostObject: this.createHostObject,
         invokeCallback: this.invokeCallback,
         releaseCallback: this.releaseCallback,
+        releaseGuestReference: this.releaseGuestReference,
+        retainGuestArguments: (operation, from) => {
+          this.assertOpen();
+          if (!extension.manifest.capabilities?.includes("guest:retain"))
+            throw new TypeError("Retaining arguments requires the guest:retain grant.");
+          if (typeof operation !== "function")
+            throw new TypeError("Retained operation must be a function.");
+          if (!Number.isSafeInteger(from) || from < 0)
+            throw new TypeError("Argument index must be a non-negative safe integer.");
+          if (this.scope !== void 0)
+            throw new TypeError("Retained operations must be registered during setup.");
+          const previous = this.retainedOperations.get(operation);
+          if (previous !== void 0 && (previous.extension !== extension || previous.from !== from))
+            throw new TypeError("Conflicting retained operation declaration.");
+          this.retainedOperations.set(operation, { extension, from });
+          return operation;
+        },
         nestedOperation: (operation) => {
           this.assertOpen();
           if (!extension.manifest.capabilities?.includes("source:nested"))
@@ -30637,7 +30732,7 @@ var RealmState = class {
       if (!this.closed)
         reconcileCompiledValues(
           this.budget,
-          [...this.scope?.retainedValues() ?? [], ...this.retainedCallbacks()],
+          [...this.scope?.retainedValues() ?? [], ...this.retainedRoots()],
           this.compilation
         );
       return result;
@@ -30671,6 +30766,8 @@ var RealmState = class {
     this.callbacks.clear();
     for (const object of this.hostObjects) revokeHostObject(object, this);
     this.hostObjects.clear();
+    for (const reference of this.guestReferences.keys()) revokeGuestReference(reference, this);
+    this.guestReferences.clear();
     this.budget.setRetainedValues(this, void 0);
     this.disposal = (async () => {
       const errors = [];
@@ -30726,6 +30823,7 @@ function createRealm(options = {}) {
     evaluate: state.evaluate,
     invokeCallback: state.invokeCallback,
     releaseCallback: state.releaseCallback,
+    releaseGuestReference: state.releaseGuestReference,
     close: state.close
   });
 }
@@ -31920,4 +32018,4 @@ export {
   FileSnapshotBackend,
   run
 };
-//# sourceMappingURL=chunk-2M6MNQBY.js.map
+//# sourceMappingURL=chunk-MXUOEOBE.js.map