@poe-platform/safe-js 0.1.28 → 0.1.29

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?, 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. |
+| `createHostObject({ properties?, methods?, indexed?, named? })` | Create a realm-owned capability. Properties declare synchronous `get`/`set` functions; methods are host functions. Optional `indexed` and `named` expose bounded live members. 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. |
@@ -238,7 +238,30 @@ const collection = context.createHostObject({ indexed: {
 
 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 changing named properties, add `named` to the same definition:
+
+```js
+const named = {
+  keys: () => [...attributes.keys()],
+  get: name => attributes.get(name),
+  maxKeys: 256,
+  maxKeyCodeUnits: 8192,
+  enumerable: false
+};
+const attributesObject = context.createHostObject({ named });
+```
+
+| Named option | Contract |
+| --- | --- |
+| `keys()` | Synchronous dense own-data array of distinct strings. Proxies, accessors, sparse arrays and reserved `constructor`/`prototype`/`__proto__` names reject. |
+| `get(name)` | Synchronous value provider, called only for a currently present name. Existing host conversion and identity rules apply. |
+| `maxKeys` | Required positive integer, at most 65,536. |
+| `maxKeyCodeUnits` | Required positive aggregate key-length cap, at most 1,048,576 UTF-16 code units. Execution, array, string and data budgets also apply. |
+| `enumerable` | Defaults to `true`. Set `false` to keep names readable and visible to `in`/`Object.hasOwn`, but omit them from keys/values/entries, object spread and `for...in`. |
+
+Fixed properties/methods take precedence over names. With `indexed`, numeric indices and `length` remain indexed members. Enumeration deduplicates collisions; names removed by an earlier getter are skipped. Named-only objects are not iterable—combine `named` with `indexed` when you need numeric collection access and `for...of`.
+
+Named properties, indexed members and indexed `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-6V2VGVEH.js → chunk-D4J7UXVE.js}

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

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

@@ -6331,7 +6331,10 @@ function serializedDateTime(value) {
 }
 
 // packages/safe-js/src/interp/host-capabilities.ts
+import { types as types3 } from "node:util";
 var MAX_INDEXED_LENGTH = 65536;
+var MAX_NAMED_KEYS = 65536;
+var MAX_NAMED_KEY_CODE_UNITS = 1048576;
 var hostObjects = /* @__PURE__ */ new WeakMap();
 var guestObjects = /* @__PURE__ */ new WeakMap();
 var guestCallbacks = /* @__PURE__ */ new WeakMap();
@@ -6356,7 +6359,7 @@ 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" && key !== "indexed"))
+  if (Object.keys(input).some((key) => !["properties", "methods", "indexed", "named"].includes(key)))
     throw new TypeError("Unknown host object definition field.");
   let indexed;
   if (input.indexed !== void 0) {
@@ -6373,6 +6376,31 @@ function createLiveHostObject(definition, controller) {
       maxLength: data.maxLength
     };
   }
+  let named;
+  if (input.named !== void 0) {
+    const data = readDataRecord(input.named, "Named host capability");
+    if (Object.keys(data).some(
+      (key) => !["keys", "get", "maxKeys", "maxKeyCodeUnits", "enumerable"].includes(key)
+    ))
+      throw new TypeError("Unknown named host capability field.");
+    if (typeof data.keys !== "function" || typeof data.get !== "function")
+      throw new TypeError("Named keys and get must be synchronous functions.");
+    if (typeof data.maxKeys !== "number" || !Number.isInteger(data.maxKeys) || data.maxKeys < 1 || data.maxKeys > MAX_NAMED_KEYS)
+      throw new RangeError(`Named maxKeys must be an integer from 1 to ${MAX_NAMED_KEYS}.`);
+    if (typeof data.maxKeyCodeUnits !== "number" || !Number.isInteger(data.maxKeyCodeUnits) || data.maxKeyCodeUnits < 1 || data.maxKeyCodeUnits > MAX_NAMED_KEY_CODE_UNITS)
+      throw new RangeError(
+        `Named maxKeyCodeUnits must be an integer from 1 to ${MAX_NAMED_KEY_CODE_UNITS}.`
+      );
+    if (data.enumerable !== void 0 && typeof data.enumerable !== "boolean")
+      throw new TypeError("Named enumerable must be a boolean.");
+    named = {
+      keys: data.keys,
+      get: data.get,
+      maxKeys: data.maxKeys,
+      maxKeyCodeUnits: data.maxKeyCodeUnits,
+      enumerable: data.enumerable
+    };
+  }
   const properties = /* @__PURE__ */ new Map();
   for (const [name, inputProperty] of Object.entries(
     readDataRecord(input.properties ?? {}, "Host properties")
@@ -6405,7 +6433,7 @@ function createLiveHostObject(definition, controller) {
       controller.method(operation)
     ])
   );
-  const state = { host, guest, controller, properties, methods, indexed };
+  const state = { host, guest, controller, properties, methods, indexed, named };
   hostObjects.set(host, state);
   guestObjects.set(guest, state);
   return host;
@@ -6463,6 +6491,7 @@ function revokeHostObject(value, owner) {
   state.properties.clear();
   state.methods.clear();
   state.indexed = void 0;
+  state.named = void 0;
 }
 function getHostObjectMember(value, key) {
   const state = guestObjects.get(value);
@@ -6479,7 +6508,11 @@ function getHostObjectMember(value, key) {
   const property = state.properties.get(key);
   if (property !== void 0)
     return property.get === void 0 ? void 0 : state.controller.read(property.get);
-  return state.methods.get(key);
+  const method = state.methods.get(key);
+  if (method !== void 0) return method;
+  if (state.named !== void 0 && namedKeys(state).includes(key))
+    return state.controller.read(() => state.named.get(key));
+  return void 0;
 }
 function setHostObjectMember(value, key, entry) {
   const state = guestObjects.get(value);
@@ -6493,13 +6526,17 @@ function getHostObjectKeys(value) {
   const state = guestObjects.get(value);
   state.controller.assertActive();
   const length = state.indexed === void 0 ? 0 : indexedLength(state);
-  const size = length + state.properties.size + state.methods.size;
+  const names = state.named === void 0 || state.named.enumerable === false ? [] : namedKeys(state).filter(
+    (key) => !state.properties.has(key) && !state.methods.has(key) && !(state.indexed !== void 0 && (key === "length" || canonicalIndex(key) !== void 0))
+  );
+  const size = length + state.properties.size + state.methods.size + names.length;
   state.controller.checkLength(size);
   state.controller.chargeWork(size + 1);
   return [
     ...Array.from({ length }, (_entry, index) => String(index)),
     ...state.properties.keys(),
-    ...state.methods.keys()
+    ...state.methods.keys(),
+    ...names
   ];
 }
 function hasHostObjectMember(value, key, enumerableOnly = false) {
@@ -6511,11 +6548,13 @@ function hasHostObjectMember(value, key, enumerableOnly = false) {
     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);
+  if (state.properties.has(key) || state.methods.has(key)) return true;
+  return state.named !== void 0 && !(enumerableOnly && state.named.enumerable === false) && namedKeys(state).includes(key);
 }
 function measureHostObjectData(value) {
   const state = guestObjects.get(value);
   let size = state.indexed === void 0 ? 0 : 16;
+  if (state.named !== void 0) size += 24;
   for (const key of state.properties.keys()) size += key.length + 1;
   for (const key of state.methods.keys()) size += key.length + 1;
   return size;
@@ -6552,6 +6591,41 @@ function canonicalIndex(key) {
   const index = Number(key);
   return Number.isInteger(index) && index >= 0 && index < 4294967295 && String(index) === key ? index : void 0;
 }
+function namedKeys(state) {
+  const named = state.named;
+  return state.controller.read(named.keys, (value) => {
+    if (!Array.isArray(value) || types3.isProxy(value))
+      throw new TypeError("Named keys must be a dense own-data array of strings, not a proxy.");
+    const length = Object.getOwnPropertyDescriptor(value, "length").value;
+    if (length > named.maxKeys) throw new RangeError("Named keys exceed maxKeys.");
+    state.controller.checkLength(length);
+    state.controller.chargeWork(length + 1);
+    if (Reflect.ownKeys(value).length !== length + 1)
+      throw new TypeError("Named keys must contain only dense own-data indices and length.");
+    const result = [];
+    const seen = /* @__PURE__ */ new Set();
+    let units = 0;
+    for (let index = 0; index < length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (descriptor === void 0 || !("value" in descriptor) || typeof descriptor.value !== "string")
+        throw new TypeError(
+          "Named keys require dense own string data, not accessors or sparse arrays."
+        );
+      const key = descriptor.value;
+      units += key.length;
+      if (units > named.maxKeyCodeUnits)
+        throw new RangeError("Named keys exceed maximum UTF-16 code units.");
+      state.controller.chargeWork(key.length);
+      if (seen.has(key)) throw new TypeError("Named keys must be distinct.");
+      if (["constructor", "prototype", "__proto__"].includes(key))
+        throw new TypeError(`Reserved named host member '${key}'.`);
+      seen.add(key);
+      result.push(key);
+    }
+    state.controller.checkTemporaryDataSize(1 + length + units);
+    return result;
+  });
+}
 
 // packages/safe-js/src/interp/values.ts
 import { types as nodeTypes } from "node:util";
@@ -6673,7 +6747,7 @@ async function flushPromiseJobs() {
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
 // packages/safe-js/src/snapshot/validation.ts
-import { types as types3 } from "node:util";
+import { types as types4 } from "node:util";
 
 // packages/safe-js/src/interp/arguments.ts
 var sandboxArgumentsBrand = /* @__PURE__ */ Symbol("SandboxArguments");
@@ -7557,7 +7631,7 @@ function validateGenericValue(value, path, depth, state) {
   if (typeof value === "object" && value !== null && hasGuestObjectState(value)) {
     fail("invalidState", path, "guest function properties, prototype links and custom descriptors cannot be restored");
   }
-  if (state.dataPropertiesOnly && types3.isProxy(value)) {
+  if (state.dataPropertiesOnly && types4.isProxy(value)) {
     fail("invalidType", path, "proxy objects are not snapshot data");
   }
   if (depth > state.limits.maxDepth)
@@ -29569,7 +29643,7 @@ function createReplayableRandom(options = {}) {
 
 // packages/safe-js/src/realm.ts
 import { AsyncLocalStorage as AsyncLocalStorage6 } from "node:async_hooks";
-import { types as types4 } from "node:util";
+import { types as types5 } from "node:util";
 
 // packages/safe-js/src/interp/globals/console-json.ts
 function createConsoleJsonGlobals(options) {
@@ -30701,7 +30775,7 @@ var RealmState = class {
         throw new TypeError("Realm limits must be positive safe integers with supported names.");
       this.limits[name] = Number(value);
     }
-    if (options.extensions !== void 0 && (!Array.isArray(options.extensions) || types4.isProxy(options.extensions)))
+    if (options.extensions !== void 0 && (!Array.isArray(options.extensions) || types5.isProxy(options.extensions)))
       throw new TypeError("Extensions must be a registration array.");
     const registrations = options.extensions ?? [];
     const extensions = [];
@@ -30921,7 +30995,7 @@ var RealmState = class {
     return this.phase.run(phase, () => {
       try {
         const result = call();
-        if (types4.isPromise(result) || phase.pending.size > 0 || phase.failure !== void 0) {
+        if (types5.isPromise(result) || phase.pending.size > 0 || phase.failure !== void 0) {
           return Promise.resolve(result).then(
             async (value) => {
               await Promise.allSettled(phase.pending);
@@ -30977,17 +31051,25 @@ var RealmState = class {
       assertActive: this.assertOpen,
       chargeWork: this.chargeWork,
       checkLength: (length) => this.budget.allocateArrayLength(length),
-      read: (operation) => {
+      checkTemporaryDataSize: (size) => {
+        const temporary = {};
+        try {
+          this.budget.setRetainedDataUsage(temporary, size);
+        } finally {
+          this.budget.setRetainedDataUsage(temporary, 0);
+        }
+      },
+      read: (operation, validate) => {
         const value = this.invokeHost(operation, operation);
-        if (types4.isPromise(value)) {
+        if (types5.isPromise(value)) {
           void Promise.resolve(value).catch(() => void 0);
           throw new TypeError("Live property getters must be synchronous.");
         }
-        return this.importValue(value);
+        return this.importValue(validate === void 0 ? value : validate(value));
       },
       write: (operation, value) => {
         const result = this.invokeHost(operation, () => operation(this.exportValue(value)));
-        if (types4.isPromise(result)) {
+        if (types5.isPromise(result)) {
           void Promise.resolve(result).catch(() => void 0);
           throw new TypeError("Live property setters must be synchronous.");
         }
@@ -31180,7 +31262,7 @@ var RealmState = class {
         }
       });
       const output = getExtensionSetup(extension)(context);
-      if (types4.isPromise(output)) {
+      if (types5.isPromise(output)) {
         void Promise.resolve(output).catch(() => void 0);
         throw new TypeError("Extension setup must be synchronous.");
       }
@@ -31368,7 +31450,7 @@ var RealmState = class {
 };
 function readModules(input) {
   const entries = (value, label) => {
-    if (types4.isMap(value) && !types4.isProxy(value)) {
+    if (types5.isMap(value) && !types5.isProxy(value)) {
       const result = [...Map.prototype.entries.call(value)];
       if (result.length > 4096 || result.some(([key]) => typeof key !== "string" || key.length === 0))
         throw new TypeError(`${label} requires bounded string keys.`);
@@ -32593,4 +32675,4 @@ export {
   FileSnapshotBackend,
   run
 };
-//# sourceMappingURL=chunk-MCF7GT3X.js.map
+//# sourceMappingURL=chunk-MO3YD4ID.js.map