@poe-platform/safe-js 0.1.25 → 0.1.27

package/README.md

@@ -55,6 +55,29 @@ const result = await run(`
 
 Properties stay inside the interpreter, not on native host functions. Arrows and object methods remain nonconstructible. Prototype links between callable or exotic objects (such as arrays) and accessor descriptors are unsupported; native `Function.prototype` is never exposed.
 
+<details>
+<summary>Object inspection and prototypes</summary>
+
+Ordinary objects inherit a sandbox-owned `Object.prototype`. Cached inspection works:
+
+```js
+const result = await run(`
+  const inspect = ({}).toString;
+  return [inspect.call([]), inspect.call(new Date(0)),
+    Object.getPrototypeOf({}) === Object.prototype];
+`);
+// result.returnValue: ["[object Array]", "[object Date]", true]
+```
+
+- `Object()` / `new Object()` create ordinary objects; passing an object preserves its identity.
+- `toString`, `valueOf`, `hasOwnProperty`, `propertyIsEnumerable` and `isPrototypeOf` support ordinary inspection. Type tags use sandbox brands, not guest-supplied fields.
+- Intrinsic methods are non-enumerable. Guest constructor prototypes inherit the ordinary Object prototype; explicit null/custom prototypes work with `Object.create`, `Object.setPrototypeOf` and literal `__proto__`. A computed `['__proto__']` remains an own data property.
+- Prototype mutations stay inside the current run or persistent realm and consume its retained-data budget. They never change native prototypes or another realm.
+
+Primitive boxing, inherited accessors, symbols and full Array/Function/exotic prototype graphs are unsupported. Use borrowed Object methods for inspecting those supported values. Explicit prototype links and mutated Object intrinsics are not portable checkpoint/copy data; project own data before crossing those boundaries. The conservative `AS011` lint rule still flags explicit `prototype`/`constructor` access; `run()` executes it without automatic linting.
+
+</details>
+
 <details>
 <summary>Dates and clocks</summary>
 
@@ -189,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. |
@@ -201,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-3WYMRVDP.js → chunk-6V2VGVEH.js}

@@ -27,7 +27,7 @@ import {
   validateMigrationSemantics,
   validateSnapshotData,
   validateSnapshotMigration
-} from "./chunk-BWVASPJX.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-3WYMRVDP.js.map
+//# sourceMappingURL=chunk-6V2VGVEH.js.map