@poe-platform/safe-js 0.1.743 → 0.1.744

package/README.md

@@ -332,6 +332,7 @@ Supply your own bounded `journal`; this does not add browser console behavior. W
 | `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?, 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. |
+| `createHostConstructor(name, construct, { parent?, hasInstance?, constants? })` | Create an opaque guest reference to a native constructor. The synchronous callback must return a live host object from this realm; its identity and prototype are preserved even for subclasses. Optional `parent` is another native constructor reference; `constants` installs finite numeric constants on the function and prototype. A synchronous `hasInstance` predicate receives only live host objects and installs the prototype's name tag. Ordinary objects cannot forge this brand. The handle counts against `guestReferences` and can be released with `releaseGuestReference`; realm close revokes all operations. |
 | `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. |
@@ -536,7 +537,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`. Pass safe-fs instances through `adapter`; supplying one as `fs` throws at construction. Named methods, default imports and `promises` imports expose the same asynchronous filesystem operations. 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 `/`. Adapter text reads pass a byte cap derived conservatively from the guest string and remaining data limits to the backend before decoding. Optional `readFileMaxBytes` and `hostReadMemoryLimit` default to `Infinity` and accept explicit `Infinity`. A finite host allowance reserves ten bytes per input byte for collection, copies, encoding expansion and admission across concurrent reads from that module; reservations release after the underlying read settles and decoding finishes, including when cancellation rejects the caller earlier. Native Node/injected `fs` implementations retain their own read behavior. 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`. Pass safe-fs instances through `adapter`; supplying one as `fs` throws at construction. Named methods, default imports and `promises` imports expose the same asynchronous filesystem operations, including `fs.promises.readFile(...)` on default imports and `promises.default.readFile(...)` on named imports. 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 `/`. Adapter text reads pass a byte cap derived conservatively from the guest string and remaining data limits to the backend before decoding. Optional `readFileMaxBytes` and `hostReadMemoryLimit` default to `Infinity` and accept explicit `Infinity`. A finite host allowance reserves ten bytes per input byte for collection, copies, encoding expansion and admission across concurrent reads from that module; reservations release after the underlying read settles and decoding finishes, including when cancellation rejects the caller earlier. Native Node/injected `fs` implementations retain their own read behavior. 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. |
@@ -562,8 +563,8 @@ drivers, adoption tokens, cleanup state and scope resource-state records out of
 guest data. Their field-specific internal links remain restorable; guest handler
 functions can still be retained by custom Promise constructors.
 
-- `dump(resultOrRunningPromise, { mode?, onFailure? })` returns checkpoint JSON. `mode` is `capture` or `replay`; `onFailure` is `throw` or `checkpoint`.
-- `restore(snapshot, { source })` validates state for compatible source; pass it as `run`'s `snapshot` option. It does not run the program.
+- `dump(resultOrRunningPromise, { mode?, onFailure? })` returns checkpoint JSON. `mode` is `capture` or `replay`; `onFailure` is `throw` or `checkpoint`. Weak collection entries survive when their keys are reachable; weak references and finalization targets retain reachable aliases.
+- `restore(snapshot, { source })` validates state for compatible source; pass it as `run`'s `snapshot` option. It does not run the program. Proxy callable and constructor flags are checked against their targets, including bound functions and dynamic function sources.
 - `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. Unseeded generators use Web Crypto entropy; unseeded `makeTimeModule().uuid()` uses `globalThis.crypto.randomUUID()`.
 - `declareHostOperation(fn, policy, { onReplay?, awaitResult?, callbackScheduling? })` 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. Use `callbackScheduling: "after-prefix"` for event-style APIs whose callbacks must wait for the current guest synchronous work to finish or explicitly await. Callbacks can then await other callbacks without blocking their admission. The default keeps inline callback behavior; `after-prefix` cannot be combined with `awaitResult: true`.

package/dist/safe-js/chunks/{chunk-F6CV74HU.js → chunk-3NFTBEZR.js}

@@ -1,10 +1,10 @@
 import {
   paths_default
-} from "./chunk-YUQFFRUF.js";
+} from "./chunk-MMN3IESA.js";
 import {
   constants,
   hostFs
-} from "./chunk-UQPYTZOZ.js";
+} from "./chunk-JCHJGIQA.js";
 
 // packages/safe-js/src/modules/source-files.ts
 import { resolvePath } from "@poe-platform/safe-fs/core";
@@ -111,4 +111,3 @@ async function openSourceFile(adapter, id, signal) {
 export {
   createRootedSourceResolver
 };
-//# sourceMappingURL=chunk-F6CV74HU.js.map