@poe-platform/safe-js 0.1.26 → 0.1.27

package/README.md

@@ -212,7 +212,7 @@ The manifest requires `version: 1` and a nonempty `name`. Optional `capabilities
 | `signal` | Realm cancellation signal; aborted on close or failure. |
 | `onCleanup(fn)` | Register a sync/async disposer. Cleanup runs in reverse order, awaits every disposer, and reports failures without skipping the rest. |
 | `chargeWork(units = 1)` | Charge a nonnegative integer against the shared execution budget. Fatal exhaustion cannot be swallowed to continue execution. |
-| `createHostObject({ properties?, methods? })` | Create a realm-owned capability. Properties declare synchronous `get`/`set` functions; methods are host functions. Undeclared members expose no native prototype. |
+| `createHostObject({ properties?, methods?, indexed? })` | Create a realm-owned capability. Properties declare synchronous `get`/`set` functions; methods are host functions. Optional `indexed` exposes a bounded live collection. 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. |
@@ -224,7 +224,21 @@ For a timer-shaped `schedule(callback, delay, ...args)`, register `context.retai
 
 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 a live collection, keep the elements in your adapter and expose virtual indices instead of declaring one getter per element:
+
+```js
+const collection = context.createHostObject({ indexed: {
+  length: () => elements.length,
+  get: index => elements[index],
+  maxLength: 4096
+} });
+```
+
+`length()` and `get(index)` must be synchronous. `maxLength` is required: an integer from 1 to 65,536. Every reported length must be a nonnegative integer within that cap and the execution array-length budget. Return existing `HostObject` handles for elements that need live identity; ordinary results use the normal copy boundary.
+
+Saved collections observe current host contents. Index reads, `Object.keys`/`values`/`entries`, `Object.hasOwn`, `in`, `for...in`, `for...of`, array/object spread and `Array.from` use the live view. Enumerable keys include current indices and fixed members, but not `length`. `Array.from` preserves element identity and interleaves mapping with reads. Noncanonical and out-of-range indices never call `get`; fixed members cannot reuse `length` or canonical index names. Enumeration and traversal consume execution budgets, without eagerly allocating virtual properties.
+
+Indexed members and their `length` are read-only. Live objects reject deletion, freezing, native prototype access, property-descriptor manipulation and 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 random generators and telemetry are rejected in this mode rather than silently ignored.
 

package/dist/safe-js/chunks/{chunk-I2SNTMRS.js → chunk-6V2VGVEH.js}

@@ -27,7 +27,7 @@ import {
   validateMigrationSemantics,
   validateSnapshotData,
   validateSnapshotMigration
-} from "./chunk-2LVAGOJR.js";
+} from "./chunk-MCF7GT3X.js";
 
 // packages/safe-js/src/migrate.ts
 import { createHash } from "node:crypto";
@@ -8245,4 +8245,4 @@ export {
   parseMcpConfig,
   makeMcpModule
 };
-//# sourceMappingURL=chunk-I2SNTMRS.js.map
+//# sourceMappingURL=chunk-6V2VGVEH.js.map

package/dist/safe-js/chunks/{chunk-2LVAGOJR.js → chunk-MCF7GT3X.js}

@@ -6331,6 +6331,7 @@ function serializedDateTime(value) {
 }
 
 // packages/safe-js/src/interp/host-capabilities.ts
+var MAX_INDEXED_LENGTH = 65536;
 var hostObjects = /* @__PURE__ */ new WeakMap();
 var guestObjects = /* @__PURE__ */ new WeakMap();
 var guestCallbacks = /* @__PURE__ */ new WeakMap();
@@ -6355,8 +6356,23 @@ function revokeGuestReference(reference, owner) {
 }
 function createLiveHostObject(definition, controller) {
   const input = readDataRecord(definition, "Host object definition");
-  if (Object.keys(input).some((key) => key !== "properties" && key !== "methods"))
+  if (Object.keys(input).some((key) => key !== "properties" && key !== "methods" && key !== "indexed"))
     throw new TypeError("Unknown host object definition field.");
+  let indexed;
+  if (input.indexed !== void 0) {
+    const data = readDataRecord(input.indexed, "Indexed host capability");
+    if (Object.keys(data).some((key) => !["length", "get", "maxLength"].includes(key)))
+      throw new TypeError("Unknown indexed host capability field.");
+    if (typeof data.length !== "function" || typeof data.get !== "function")
+      throw new TypeError("Indexed length and get must be synchronous functions.");
+    if (typeof data.maxLength !== "number" || !Number.isInteger(data.maxLength) || data.maxLength < 1 || data.maxLength > MAX_INDEXED_LENGTH)
+      throw new RangeError(`Indexed maxLength must be an integer from 1 to ${MAX_INDEXED_LENGTH}.`);
+    indexed = {
+      length: data.length,
+      get: data.get,
+      maxLength: data.maxLength
+    };
+  }
   const properties = /* @__PURE__ */ new Map();
   for (const [name, inputProperty] of Object.entries(
     readDataRecord(input.properties ?? {}, "Host properties")
@@ -6376,6 +6392,8 @@ function createLiveHostObject(definition, controller) {
   for (const name of [...properties.keys(), ...Object.keys(operations)]) {
     if (["constructor", "prototype", "__proto__"].includes(name))
       throw new TypeError(`Reserved host member '${name}'.`);
+    if (indexed !== void 0 && (name === "length" || canonicalIndex(name) !== void 0))
+      throw new TypeError(`Conflicting indexed host member '${name}'.`);
   }
   controller.assertActive();
   controller.chargeWork(properties.size + Object.keys(operations).length + 1);
@@ -6387,7 +6405,7 @@ function createLiveHostObject(definition, controller) {
       controller.method(operation)
     ])
   );
-  const state = { host, guest, controller, properties, methods };
+  const state = { host, guest, controller, properties, methods, indexed };
   hostObjects.set(host, state);
   guestObjects.set(guest, state);
   return host;
@@ -6444,11 +6462,20 @@ function revokeHostObject(value, owner) {
     throw new TypeError("Foreign host object.");
   state.properties.clear();
   state.methods.clear();
+  state.indexed = void 0;
 }
 function getHostObjectMember(value, key) {
   const state = guestObjects.get(value);
   state.controller.assertActive();
   state.controller.chargeWork();
+  if (state.indexed !== void 0) {
+    if (key === "length") return indexedLength(state);
+    const index = canonicalIndex(key);
+    if (index !== void 0) {
+      if (index >= state.indexed.maxLength || index >= indexedLength(state)) return void 0;
+      return state.controller.read(() => state.indexed.get(index));
+    }
+  }
   const property = state.properties.get(key);
   if (property !== void 0)
     return property.get === void 0 ? void 0 : state.controller.read(property.get);
@@ -6465,7 +6492,65 @@ function setHostObjectMember(value, key, entry) {
 function getHostObjectKeys(value) {
   const state = guestObjects.get(value);
   state.controller.assertActive();
-  return [...state.properties.keys(), ...state.methods.keys()];
+  const length = state.indexed === void 0 ? 0 : indexedLength(state);
+  const size = length + state.properties.size + state.methods.size;
+  state.controller.checkLength(size);
+  state.controller.chargeWork(size + 1);
+  return [
+    ...Array.from({ length }, (_entry, index) => String(index)),
+    ...state.properties.keys(),
+    ...state.methods.keys()
+  ];
+}
+function hasHostObjectMember(value, key, enumerableOnly = false) {
+  const state = guestObjects.get(value);
+  state.controller.assertActive();
+  state.controller.chargeWork();
+  if (state.indexed !== void 0) {
+    if (key === "length") return !enumerableOnly;
+    const index = canonicalIndex(key);
+    if (index !== void 0) return index < state.indexed.maxLength && index < indexedLength(state);
+  }
+  return state.properties.has(key) || state.methods.has(key);
+}
+function measureHostObjectData(value) {
+  const state = guestObjects.get(value);
+  let size = state.indexed === void 0 ? 0 : 16;
+  for (const key of state.properties.keys()) size += key.length + 1;
+  for (const key of state.methods.keys()) size += key.length + 1;
+  return size;
+}
+function getHostObjectIterator(value) {
+  const state = guestObjects.get(value);
+  state.controller.assertActive();
+  if (state.indexed === void 0) return void 0;
+  let index = 0;
+  let exhausted = false;
+  return {
+    next: () => {
+      state.controller.assertActive();
+      state.controller.chargeWork();
+      if (exhausted) return { done: true, value: void 0 };
+      if (index >= indexedLength(state)) {
+        exhausted = true;
+        return { done: true, value: void 0 };
+      }
+      const position = index++;
+      return { done: false, value: state.controller.read(() => state.indexed.get(position)) };
+    }
+  };
+}
+function indexedLength(state) {
+  state.controller.chargeWork();
+  const length = state.controller.read(state.indexed.length);
+  if (typeof length !== "number" || !Number.isInteger(length) || length < 0 || length > state.indexed.maxLength)
+    throw new RangeError("Indexed length must be a non-negative integer within maxLength.");
+  state.controller.checkLength(length);
+  return length;
+}
+function canonicalIndex(key) {
+  const index = Number(key);
+  return Number.isInteger(index) && index >= 0 && index < 4294967295 && String(index) === key ? index : void 0;
 }
 
 // packages/safe-js/src/interp/values.ts
@@ -8406,6 +8491,7 @@ function assertSnapshotInactive(snapshot) {
 
 // packages/safe-js/src/interp/iteration.ts
 function getSandboxIterator(value) {
+  if (isGuestHostObject(value)) return getHostObjectIterator(value);
   if (isFloat32Array(value)) {
     return syncIterator(Float32Array.prototype.values.call(value));
   }
@@ -9563,7 +9649,13 @@ function createSandboxClosure(input) {
   return Object.freeze(closure);
 }
 function ownEnumerableSandboxEntries(value) {
-  if (isGuestHostObject(value)) return getHostObjectKeys(value).map((key) => [key, getHostObjectMember(value, key)]);
+  if (isGuestHostObject(value)) {
+    const entries = [];
+    for (const key of getHostObjectKeys(value)) {
+      if (hasHostObjectMember(value, key, true)) entries.push([key, getHostObjectMember(value, key)]);
+    }
+    return entries;
+  }
   if (value === null || value === void 0) throw new TypeError("Cannot convert undefined or null to object.");
   if (isGuestClosure(value)) return Object.entries(value.properties ?? {});
   if (isSandboxClosure(value) || isSandboxGenerator(value) || isSandboxMap(value) || isSandboxSet(value) || isSandboxPromise(value) || isSandboxRegex(value)) return [];
@@ -9721,7 +9813,7 @@ function measureSandboxData(values, options = {}) {
       return;
     }
     if (isGuestHostObject(value)) {
-      for (const key of getHostObjectKeys(value)) usage += key.length + 1;
+      usage += measureHostObjectData(value);
       return;
     }
     const prototype = getSandboxPrototype(value);
@@ -22962,6 +23054,86 @@ function hoistVarDeclarations(node, scope) {
   }
 }
 
+// packages/safe-js/src/interp/string-coercion.ts
+function sandboxString(value, budget, context, joining = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "function") throw new TypeError("Expected a sandbox value.");
+    return budget.allocateString(String(value));
+  }
+  return stringifyObject(value, budget, context, joining);
+}
+async function stringifyObject(value, budget, context, joining) {
+  const leaveCall = budget.enterCall();
+  try {
+    budget.visitNode();
+    for (const name of ["toString", "valueOf"]) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, name);
+      let result;
+      if (descriptor === void 0) {
+        if (name === "valueOf") continue;
+        result = await defaultToString(value, budget, context, joining);
+      } else {
+        const hook = ownDataValue(value, name);
+        if (!isSandboxClosure(hook)) continue;
+        if (context?.invokeClosure === void 0) {
+          throw new TypeError("String hooks require a sandbox call context.");
+        }
+        result = await context.invokeClosure(hook, [], value);
+      }
+      if (result === null || typeof result !== "object") {
+        return sandboxString(result, budget, context, joining);
+      }
+    }
+    throw new TypeError("Cannot convert object to primitive value");
+  } finally {
+    leaveCall();
+  }
+}
+async function defaultToString(value, budget, context, joining) {
+  if (isSandboxDate(value)) return budget.allocateString(dateString(value));
+  if (Array.isArray(value) || isFloat32Array(value)) {
+    if (Object.hasOwn(value, "join")) {
+      const join = ownDataValue(value, "join");
+      if (!isSandboxClosure(join))
+        return isFloat32Array(value) ? "[object Float32Array]" : "[object Array]";
+      if (context?.invokeClosure === void 0) {
+        throw new TypeError("String hooks require a sandbox call context.");
+      }
+      return context.invokeClosure(join, [], value);
+    }
+    if (joining.has(value)) return "";
+    joining.add(value);
+    try {
+      const length = isFloat32Array(value) ? float32Storage(value).length : value.length;
+      let text = "";
+      for (let index = 0; index < length; index++) {
+        budget.visitNode();
+        const element = ownDataValue(value, String(index));
+        const part = element === null || element === void 0 ? "" : await sandboxString(element, budget, context, joining);
+        text = budget.allocateString(text + (index === 0 ? "" : ",") + part);
+      }
+      return text;
+    } finally {
+      joining.delete(value);
+    }
+  }
+  if (sandboxErrorTypes.has(value)) {
+    const nameValue = ownDataValue(value, "name");
+    const name = nameValue === void 0 ? "Error" : await sandboxString(nameValue, budget, context, joining);
+    const messageValue = ownDataValue(value, "message");
+    const message = messageValue === void 0 ? "" : await sandboxString(messageValue, budget, context, joining);
+    return name === "" ? message : message === "" ? name : `${name}: ${message}`;
+  }
+  return isSandboxPromise(value) ? "[object Promise]" : "[object Object]";
+}
+function ownDataValue(value, name) {
+  const descriptor = Object.getOwnPropertyDescriptor(value, name);
+  if (descriptor !== void 0 && !Object.hasOwn(descriptor, "value")) {
+    throw new TypeError("String conversion requires sandbox data properties.");
+  }
+  return descriptor?.value;
+}
+
 // packages/safe-js/src/interp/methods/array.ts
 var activeArrayCallbacks = /* @__PURE__ */ new WeakMap();
 var arrayMethodNames = /* @__PURE__ */ new Set([
@@ -25779,7 +25951,11 @@ async function evaluateBinaryExpression(node, context) {
   if (right.kind !== "normal") {
     return right;
   }
-  const value = applyBinaryOperator(node, left.value, right.value, context);
+  const value = node.operator === "in" && isGuestHostObject(right.value) ? hasHostObjectMember(right.value, await sandboxString(left.value, context.budget, {
+    stack: context.callStack,
+    thisValue: void 0,
+    invokeClosure: (closure, args, thisValue) => invokeSandboxClosure(closure, args, context, context.callStack, void 0, thisValue)
+  })) : applyBinaryOperator(node, left.value, right.value, context);
   return {
     kind: "normal",
     hasValue: true,
@@ -26476,7 +26652,7 @@ function forInKeys(object, budget) {
   return keys;
 }
 function hasForInProperty(object, key, budget) {
-  if (isGuestHostObject(object)) return getHostObjectKeys(object).includes(key);
+  if (isGuestHostObject(object)) return hasHostObjectMember(object, key, true);
   let depth = 0;
   for (let current = object; current !== null; current = getSandboxPrototype(current, budget)) {
     if (depth > 0) budget.visitNode();
@@ -27937,6 +28113,13 @@ async function evaluateObjectSpread(node, context) {
       value: []
     };
   }
+  if (isGuestHostObject(value.value)) {
+    const entries = [];
+    for (const key of getHostObjectKeys(value.value)) {
+      if (hasHostObjectMember(value.value, key, true)) entries.push([key, getHostObjectMember(value.value, key)]);
+    }
+    return { ok: true, value: entries };
+  }
   if (isSandboxClosure(value.value) && !isGuestClosure(value.value) || isSandboxPromise(value.value)) {
     throw new TypeError(
       `Cannot spread ${describeObjectSpreadValue(value.value)} into object literal.`
@@ -29537,7 +29720,7 @@ async function stringifyValue(value, state, indent) {
     return stringifyArray(value, state, indent);
   }
   if (isStringifyObject(value)) {
-    return stringifyObject(value, state, indent);
+    return stringifyObject2(value, state, indent);
   }
   return void 0;
 }
@@ -29563,7 +29746,7 @@ ${indent}]`;
     leaveStringifyObject(value, state);
   }
 }
-async function stringifyObject(value, state, indent) {
+async function stringifyObject2(value, state, indent) {
   enterStringifyObject(value, state);
   try {
     const nextIndent = indent + state.gap;
@@ -29778,86 +29961,6 @@ function assertStructuredCloneable(value, seen) {
   }
 }
 
-// packages/safe-js/src/interp/string-coercion.ts
-function sandboxString(value, budget, context, joining = /* @__PURE__ */ new Set()) {
-  if (value === null || typeof value !== "object") {
-    if (typeof value === "function") throw new TypeError("Expected a sandbox value.");
-    return budget.allocateString(String(value));
-  }
-  return stringifyObject2(value, budget, context, joining);
-}
-async function stringifyObject2(value, budget, context, joining) {
-  const leaveCall = budget.enterCall();
-  try {
-    budget.visitNode();
-    for (const name of ["toString", "valueOf"]) {
-      const descriptor = Object.getOwnPropertyDescriptor(value, name);
-      let result;
-      if (descriptor === void 0) {
-        if (name === "valueOf") continue;
-        result = await defaultToString(value, budget, context, joining);
-      } else {
-        const hook = ownDataValue(value, name);
-        if (!isSandboxClosure(hook)) continue;
-        if (context?.invokeClosure === void 0) {
-          throw new TypeError("String hooks require a sandbox call context.");
-        }
-        result = await context.invokeClosure(hook, [], value);
-      }
-      if (result === null || typeof result !== "object") {
-        return sandboxString(result, budget, context, joining);
-      }
-    }
-    throw new TypeError("Cannot convert object to primitive value");
-  } finally {
-    leaveCall();
-  }
-}
-async function defaultToString(value, budget, context, joining) {
-  if (isSandboxDate(value)) return budget.allocateString(dateString(value));
-  if (Array.isArray(value) || isFloat32Array(value)) {
-    if (Object.hasOwn(value, "join")) {
-      const join = ownDataValue(value, "join");
-      if (!isSandboxClosure(join))
-        return isFloat32Array(value) ? "[object Float32Array]" : "[object Array]";
-      if (context?.invokeClosure === void 0) {
-        throw new TypeError("String hooks require a sandbox call context.");
-      }
-      return context.invokeClosure(join, [], value);
-    }
-    if (joining.has(value)) return "";
-    joining.add(value);
-    try {
-      const length = isFloat32Array(value) ? float32Storage(value).length : value.length;
-      let text = "";
-      for (let index = 0; index < length; index++) {
-        budget.visitNode();
-        const element = ownDataValue(value, String(index));
-        const part = element === null || element === void 0 ? "" : await sandboxString(element, budget, context, joining);
-        text = budget.allocateString(text + (index === 0 ? "" : ",") + part);
-      }
-      return text;
-    } finally {
-      joining.delete(value);
-    }
-  }
-  if (sandboxErrorTypes.has(value)) {
-    const nameValue = ownDataValue(value, "name");
-    const name = nameValue === void 0 ? "Error" : await sandboxString(nameValue, budget, context, joining);
-    const messageValue = ownDataValue(value, "message");
-    const message = messageValue === void 0 ? "" : await sandboxString(messageValue, budget, context, joining);
-    return name === "" ? message : message === "" ? name : `${name}: ${message}`;
-  }
-  return isSandboxPromise(value) ? "[object Promise]" : "[object Object]";
-}
-function ownDataValue(value, name) {
-  const descriptor = Object.getOwnPropertyDescriptor(value, name);
-  if (descriptor !== void 0 && !Object.hasOwn(descriptor, "value")) {
-    throw new TypeError("String conversion requires sandbox data properties.");
-  }
-  return descriptor?.value;
-}
-
 // packages/safe-js/src/interp/globals/object.ts
 function createObjectGlobal(methods, budget) {
   const construct = ([value]) => {
@@ -29951,7 +30054,7 @@ function requireReceiver(value) {
 }
 function hasOwnSandboxProperty(value, key, enumerable) {
   requireReceiver(value);
-  if (isGuestHostObject(value)) return getHostObjectKeys(value).includes(key);
+  if (isGuestHostObject(value)) return hasHostObjectMember(value, key, enumerable);
   let properties;
   if (isGuestClosure(value)) properties = materializeFunctionProperties(value);
   else if (isSandboxClosure(value)) {
@@ -30110,6 +30213,7 @@ function createObjectArrayGlobals(options) {
       freeze: createSandboxClosure({
         sandbox: true,
         call: ([value]) => {
+          if (isGuestHostObject(value)) throw new TypeError("Live host objects cannot be frozen.");
           if (typeof value === "object" && value !== null) {
             Object.freeze(isGuestClosure(value) ? materializeFunctionProperties(value) : value);
           }
@@ -30324,6 +30428,21 @@ function isAssignableSandboxTarget(value) {
 async function arrayFromSandboxValues(args, budget) {
   const [items, mapFn, thisValue] = args;
   const iterator = getSandboxIterator(items);
+  if (isGuestHostObject(items) && iterator !== void 0) {
+    if (mapFn !== void 0 && !isSandboxClosure(mapFn))
+      throw new TypeError("Array.from mapping callback must be a function.");
+    const values2 = [];
+    while (true) {
+      const next = await iterator.next();
+      if (next.done) break;
+      budget.allocateArrayLength(values2.length + 1);
+      const value = mapFn === void 0 ? next.value : await mapFn.call([next.value, values2.length], { stack: [], thisValue });
+      if (isSandboxPromise(value) && value.synchronousPrefix !== void 0)
+        await value.synchronousPrefix;
+      values2.push(value);
+    }
+    return allocateProducedSandboxValue(values2, budget);
+  }
   const values = iterator === void 0 ? Reflect.apply(Array.from, Array, [items]) : await collectIteratorValues(iterator);
   if (mapFn === void 0 || !isSandboxClosure(mapFn)) {
     if (mapFn !== void 0) {
@@ -30857,6 +30976,7 @@ var RealmState = class {
       owner: this,
       assertActive: this.assertOpen,
       chargeWork: this.chargeWork,
+      checkLength: (length) => this.budget.allocateArrayLength(length),
       read: (operation) => {
         const value = this.invokeHost(operation, operation);
         if (types4.isPromise(value)) {
@@ -32473,4 +32593,4 @@ export {
   FileSnapshotBackend,
   run
 };
-//# sourceMappingURL=chunk-2LVAGOJR.js.map
+//# sourceMappingURL=chunk-MCF7GT3X.js.map