@poe-platform/safe-js 0.1.720 → 0.1.722

package/README.md

@@ -42,7 +42,7 @@ console.log(result.returnValue);
 
 - **JavaScript control flow:** functions and closures, classes, async/await, loops, destructuring, spread, templates, exceptions, and synchronous and asynchronous generators.
 - **Guest function objects:** own properties on functions and arrows; ordinary constructors with shared prototypes, inherited methods and `instanceof`. `Object.create`, `getPrototypeOf`, `setPrototypeOf`, own-property inspection, and data descriptors work on ordinary sandbox records.
-- **Data processing:** arrays, objects, strings, numbers, BigInt, Symbol, JSON, Math, Date, Map, Set, WeakMap, WeakSet, typed arrays, ArrayBuffer/DataView, promises, Intl APIs, and budgeted regular expressions.
+- **Data processing:** arrays, objects, strings, numbers, BigInt, Symbol, JSON, Math, Date, Map, Set, WeakMap, WeakSet, typed arrays, ArrayBuffer/DataView, UTF-8 TextEncoder, promises, Intl APIs, and budgeted regular expressions.
 - **Language and object APIs:** guest `eval`, `Function` and async/generator function constructors, `Proxy`, `Reflect`, property descriptors, accessors, and prototype mutation. Dynamically generated code executes inside the interpreter with its existing capabilities and budgets.
 - **Additional built-ins:** all eight Temporal types and `Temporal.Now`, iterator helpers, disposable stacks, `WeakRef`, `FinalizationRegistry`, `SharedArrayBuffer`, and `Atomics`. Availability does not imply complete conformance or portable recovery; see the limitations below.
 - **Explicit capabilities:** static imports and dynamic `import()` resolve against host-supplied modules, not arbitrary npm packages or files. Optional helpers cover agents, MCP tools, files, environment reads, time, logging, and metrics.
@@ -88,6 +88,10 @@ const result = await run(`
 Builtin prototypes retain their originating Object prototype when inspected
 from another realm, including when a budget is reused. Checkpoints preserve
 constructor/prototype identity and their supported property mutations.
+Persistent realms can use `budget.forkRealm()` to keep separate globals and
+intrinsic caches while sharing step, call-depth and retained-data limits. A fork
+preserves consumed allowances, including when a sibling closes. Each budget view
+supports one live realm; suspended invocation data remains charged until released.
 Map and Set instances also retain their selected prototype during inspection
 from another realm.
 Mixed-realm intrinsic checkpoints preserve separate constructor/prototype
@@ -210,6 +214,10 @@ try {
 
 This prints `2`. Evaluations share declarations, closures and object identity without rerunning earlier source. Budgets are cumulative. `evaluate(source, { filename? })` returns `ok`, `returnValue` or `error`, and `stats`; it can also reject. Concurrent evaluations are rejected. Deferred callbacks can run while guest code awaits their result; overlapping invocation of the same callback is rejected. Close cancels pending work, revokes capabilities and awaits cleanup; repeated close does not rerun cleanup. Unhandled execution failures also close the realm.
 
+For scripts whose completion value is unused, call `evaluate(source, { discardResult: true })`. A successful result omits `returnValue`, so guest values with custom prototypes can remain inside the realm without crossing the data-copy boundary. Effects, resource limits and error handling still apply. `realm.supportsDiscardResult` is an immutable `true` marker for adapters that support older SDK versions.
+
+Execution gives host timers and cancellation turns between guest nodes after elapsed host time as well as interpreter work. This preserves guest job ownership and resource checks. A synchronous native call or an individual data scan can still delay delivery; cancellation is cooperative.
+
 `createRealm(options?)` accepts `bindings`, `modules`, `budget`, `clock`, `signal`, `sink` and `randomSeed` as described below, plus:
 
 | Option | Purpose / default |
@@ -218,11 +226,35 @@ This prints `2`. Evaluations share declarations, closures and object identity wi
 | `grants` | Granted capability names; `[]`. Every requested capability must be granted before any extension setup runs. |
 | `builtinOverrides` | Optional `{ console: "extension-name" }` authorizes that registered extension to replace only the builtin console. It must declare `console` and export a host object created in the realm. No overrides by default. |
 | `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. For deferred arguments that must preserve guest identity, opt into retained references as described below.
+| `stringCompilation` | Optional `"allow"` (default) or `"deny"`. Denial raises a catchable guest EvalError for string eval and Function/AsyncFunction/GeneratorFunction/AsyncGeneratorFunction compilation, including retained callbacks. Host source evaluation remains available. This is separate from WebAssembly compilation policy. |
+| `classicScripts` | Optional boolean, default `false`. Evaluations use classic Script grammar with persistent globals: top-level `this` is the intrinsic global object, `var` and functions create global properties, and `let`/`const` remain lexical. Injected capabilities stay immutable lexical bindings. Explicit source modules retain module semantics. |
+| `classicScriptErrors` | Optional `"fatal"` (default) or `"report"`; reporting requires `classicScripts: true`. Ordinary escaped Script exceptions return `ok: false` with `recoverable: true` while preserving realm state. Syntax, budget, cancellation, module, callback and unhandled rejection failures remain fatal. |
+| `callbackScheduling` | Optional `"after-prefix"` for a trusted host scheduler. Allows later source after every admitted callback finishes its synchronous prefix, while their asynchronous tails remain pending. Omit for exclusive source evaluation. |
+| `sourceResolver` | Explicitly grants source text and a canonical identity for each imported source. Classic Scripts use their evaluation filename as the referrer, including later calls to saved functions and generators. No filesystem or network access is granted by default. |
+| `sourceImportTimeoutMs` | Optional integer from 1 to 2147483647, disabled by default. Limits elapsed host time for each dynamic source import across resolution, linking and evaluation, including top-level await. Expiry revokes the entire realm with a deadline budget error. Timers are cooperative; synchronous host work can delay delivery. |
+
+Classic Scripts reject top-level return, await and static imports/exports. This
+option preserves declaration history across evaluations and checkpoints; browser
+window aliases and callback scheduling belong to the host. Dynamic source imports
+require an explicit `sourceResolver` and share canonical module instances with
+source-module evaluations. `realm.sourceModuleStatus()` returns an immutable
+snapshot with `pendingImports`, `preparedModules`, `fulfilledImports` and
+`rejectedImports`; it rejects after realm revocation. Import settlement does not
+establish application readiness.
+
+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. Inside a declared and granted `context.nestedOperation`, await `context.invokeCallback` to settle the full guest result, including nested host calls and returned promises. 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.
 
 Need synchronous effects without waiting for an async callback's tail? Use `realm.startCallback(callback, options)` or `context.startCallback(callback, options)`. The frozen `CallbackInvocation` exposes two promises: await `synchronous` when the guest function returns or its async body reaches its first `await`; await `result` for the final value. Interpreter implementation awaits and budget work do not complete the prefix. Ordinary throws reject both promises; nonfatal async-function errors reject only `result`, even before the first `await`. Close, abort and fatal errors reject still-pending handles without changing a completed prefix. The same callback limits, identity and reentry rules apply; no extra grant is required. Calls started outside a host operation are queued in invocation order. Browser event/default-action policy remains the host's responsibility.
 
+With `callbackScheduling: "after-prefix"`, the host must retain and observe callback
+results. Source remains exclusive, including top-level await; guest-owned host
+operations cannot use this option to admit another source. All work shares the
+realm queue and cumulative limits. Suspended frames remain included in full graph
+accounting. Compilation tickets and allocation charges may remain conservatively
+held until pending work completes. External close waits for canceled work and
+cleanup; close from a guest-owned host operation initiates cancellation and rejects
+with `reentry` instead of awaiting its own caller.
+
 <details>
 <summary>Trusted extensions and live host objects</summary>
 
@@ -287,7 +319,8 @@ Supply your own bounded `journal`; this does not add browser console behavior. W
 | `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?, 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. |
+| `createHostObject({ properties?, methods?, indexed?, named?, expandos? })` | Create a realm-owned capability. Properties declare synchronous `get`/`set` functions; methods are host functions. Optional `indexed` and `named` expose bounded live members. Optional `expandos` stores guest fields with guest identity preserved. Undeclared members expose no native prototype. |
+| `createArrayBufferReference(buffer)` | Create an opaque live reference to a fixed, attached, plain ArrayBuffer without own metadata. Requires declared and granted `array-buffer:share`; full buffer bytes count against array/data budgets and `limits.guestReferences`. |
 | `invokeCallback(callback, { thisValue?, args? })` | Invoke a captured guest function with the realm's state, cancellation and budgets. Same operation as on the realm. |
 | `startCallback(callback, { thisValue?, args? })` | Return separate `synchronous` and `result` promises for the same realm-owned invocation. Also available on the realm. |
 | `releaseCallback(callback)` | Revoke the callback and release its retained guest state. |
@@ -296,8 +329,12 @@ Supply your own bounded `journal`; this does not add browser console behavior. W
 | `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. |
 
+Use `expandos: { maxKeys, maxKeyCodeUnits, assertActive? }` to allow guest assignment, deletion and enumeration of string and symbol fields. `maxKeys` must be 1–65,536; `maxKeyCodeUnits` must be 1–1,048,576 and counts string keys plus symbol descriptions in UTF-16 units. Guest graphs and closures remain subject to the realm's data budget. The optional synchronous `assertActive` hook must return `undefined` and can enforce the publisher's lifetime. Declared members, indexed names and prototype-related names remain protected. Expandos cannot be combined with `named`; arbitrary descriptors and prototype links remain unsupported.
+
 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.
 
+For a trusted native buffer such as WebAssembly memory, use `context.createArrayBufferReference(buffer)` and return the handle from a host property or operation. Guest ArrayBuffer views then share its bytes with the host, preserving identity and bidirectional writes. Ordinary host buffers still copy. Shared, resizable, detached, subclassed and proxy buffers reject, as do buffers with own properties or symbols. After native memory growth detaches the old buffer, create a new reference to the new buffer; the old reference continues to denote the detached buffer.
+
 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.
 
 For a live collection, keep the elements in your adapter and expose virtual indices instead of declaring one getter per element:
@@ -376,10 +413,12 @@ For one-shot use, `run(source, { extensions, grants, ... })` accepts the same re
 | --- | --- |
 | `bindings` | Global input values and host functions; none by default. |
 | `modules` | Module names mapped to export records or Maps; none by default. |
+| `importSpecifiers` | Optional exact names admitted beyond bare imports in harness execution; every name still requires explicit registration in `modules`. Supply the same allowlist to `restore` or snapshot replay. This does not load native, local, or network modules. |
 | `extensions`, `grants`, `builtinOverrides`, `limits` | Opt into a one-shot extension realm; see the supported options and lifetime rules above. |
 | `budget` | A `Budget` instance. Without one, only the default call-depth limit of 1,000 is configured. |
 | `signal` | Host `AbortSignal` for cancellation. |
 | `filename` | Diagnostic filename; defaults to `<input>`. |
+| `sourceLocation` | Optional trusted callback mapping one-based guest stack `{ line, column }` positions to `{ filename, line, column }`. Return `undefined` to retain a generated frame. It changes diagnostics only; re-supply it when resuming snapshots. |
 | `entryPointArgs` | Arguments for invoking the default-exported function. Omit for top-level execution only. |
 | `importMeta` | Host-supplied fields exposed through `import.meta`. |
 | `sink` | Console destination with `log(...args)` and `error(...args)`; defaults to the host console. |
@@ -399,8 +438,12 @@ For one-shot use, `run(source, { extensions, grants, ... })` accepts the same re
 | `deadline` | Absolute epoch milliseconds or a `Date`, not a duration. |
 | `maxCallDepth` | Nested interpreter calls. |
 | `stringLength`, `arrayLength` | Individual string and array lengths. |
+| `regexSourceLength` | Optional regex source cap; positive safe integer, unlimited when omitted. The general `stringLength` limit also applies. |
+| `regexCompileAllocations` | Optional per-regex compilation allocation cap; positive safe integer, unlimited when omitted. Compilation still charges work and retained data against the shared budget. |
 | `dataSize` | Retained sandbox data units, not bytes of process memory. |
 
+`JSON.parse` checks both parse paths before building native objects: input work counts toward steps and deadlines, array lengths and object member counts use `arrayLength`, and nesting uses `maxCallDepth` with an additional ceiling of 256 containers. Parsing requires room for a conservative temporary allocation bound of `16 * text.length + 8` data units alongside existing data; whitespace and duplicate keys count toward this bound.
+
 There are no runtime environment variables to set. `makeEnvModule({ allow, values? })` grants reads of names in `allow`; `values` supplies an explicit string map instead of reading the host's `process.env`. Disallowed reads throw `EnvAccessError`; allowed but unset names return `undefined`. Agent and MCP integrations may require their own credentials.
 
 <details>
@@ -426,7 +469,7 @@ Compiling stored module source enforces the owning budget's string-length
 limit and charges one step per UTF-16 source unit before parsing. Regex
 compilation retains its additional work charges.
 
-`deepCopyToSandbox(value)` and `deepCopyFromSandbox(value, { wrapClosure? })` convert supported values. `wrapClosure` lets the host choose how to represent an exported sandbox function. Not every native JavaScript object is convertible.
+`deepCopyToSandbox(value)` and `deepCopyFromSandbox(value, { wrapClosure? })` convert supported values. `wrapClosure` lets the host choose how to represent an exported sandbox function. Not every native JavaScript object is convertible. When passing sandbox typed arrays to native APIs, use `deepCopyFromSandbox`: SDK-created views use internal wrappers and do not satisfy the host's native `ArrayBuffer.isView` check. Guest reflection and `ArrayBuffer.isView` retain their normal behavior.
 
 Native Promise imports accept genuine promises from other JavaScript realms,
 preserving aliases and copying fulfillment or rejection values. Own string-keyed
@@ -478,7 +521,7 @@ Factories return exports to register in `modules`; calling a factory alone does
 | --- | --- |
 | `makeAgentModule(spawnAgent, options?)` | Inject the agent runner. Options: `defaultRetry`, `onEvent`, `otelSink`. Exposes `spawn`, `spawn.retry`, and `spawn.parallel`; call options follow this table. |
 | `makeMcpModule(options)` | Required `servers` map: stdio `{ command, args?, cwd?, env? }` or HTTP `{ url, headers? }`. Options: `requestTimeoutMs` (30,000), `closeTimeoutMs` (1,000), `maxToolPages` (100), `signal`, and injected `fetch`/`spawn`. Named clients expose `tools`, `tool`, `toolBatch`, and `close`; close managed clients when finished. A custom connector function is also accepted. |
-| `makeFsModule(options?)` | Node-backed `{ root?, fs? }`, or shared-filesystem `{ adapter, root?, cwd?, signal? }`; do not combine `fs` and `adapter`. Node access without `root` is unconfined. With an adapter, `root` confines access and `cwd` selects the virtual relative-path base; without `root`, explicit `cwd` also confines access. Omitting both uses virtual `/`. Read text with `readFile(path, "utf8")`; see the [module methods](src/modules/fs.ts) and [filesystem package](../safe-fs/README.md). |
+| `makeFsModule(options?)` | Node-backed `{ root?, fs? }`, or shared-filesystem `{ adapter, root?, cwd?, signal? }`; do not combine `fs` and `adapter`. Node access without `root` is unconfined. Rooted calls sharing the same adapter or Node implementation are serialized through path checks and backend completion to prevent guest namespace races. External host mutations or distinct adapters over the same storage require independent backend confinement. With an adapter, `root` confines access and `cwd` selects the virtual relative-path base; without `root`, explicit `cwd` also confines access. Omitting both uses virtual `/`. Read text with `readFile(path, "utf8")`; see the [module methods](src/modules/fs.ts) and [filesystem package](../safe-fs/README.md). |
 | `makeEnvModule(namesOrOptions)` | Allowed-name array or `{ allow, values? }`; exposes `get(name)`. `parseEnvConfig(json)` accepts the object form. |
 | `makeTimeModule(options?)` | `now`, `random`, `seed`, `signal`; exposes `now`, `random`, `sleep`, `uuid`. Defaults to host time/randomness; `seed` makes the random generator deterministic, and explicit `random` takes precedence. |
 | `makeLogModule(sink)` | Sends timestamped `info`, `error`, and `event` entries to your callback. |
@@ -508,7 +551,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.
-- `declareHostOperation(fn, policy, { onReplay? })` 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.
+- `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.
 - `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/config-mutations/types.d.ts

@@ -13,7 +13,7 @@ export interface FileSystem {
     }): Promise<void>;
     mkdir(path: string, options?: {
         recursive: boolean;
-    }): Promise<void>;
+    }): Promise<unknown>;
     rename(oldPath: string, newPath: string): Promise<void>;
     unlink(path: string): Promise<void>;
     rm?(path: string, options?: {
@@ -52,6 +52,8 @@ export interface PathMapper {
     }): string;
 }
 export interface MutationContext {
+    /** Path operations for the filesystem namespace; defaults to native host paths. */
+    paths?: typeof import("node:path");
     /** Filesystem interface - required */
     fs: FileSystem;
     /** Home directory for ~ expansion - required */

package/dist/safe-js/chunks/{chunk-B2SQLK4O.js → chunk-3QQYJ4RQ.js}

@@ -8,7 +8,7 @@ import {
   numericTypedArrayConstructors,
   parseModule,
   tokenize
-} from "./chunk-IDQ67DY2.js";
+} from "./chunk-RYVHEOHM.js";
 
 // packages/safe-js/src/lint/rules/AS001.ts
 function AS001(source, options = {}) {
@@ -708,6 +708,7 @@ var KNOWN_RUNTIME_GLOBALS = [
   "structuredClone",
   "SyntaxError",
   "Temporal",
+  "TextEncoder",
   "TypeError",
   "URIError",
   "undefined",
@@ -11176,4 +11177,4 @@ function hasOnlyRegexLiteralDiagnostics(diagnostics) {
 export {
   lint
 };
-//# sourceMappingURL=chunk-B2SQLK4O.js.map
+//# sourceMappingURL=chunk-3QQYJ4RQ.js.map