@poe-platform/safe-js 0.1.426 → 0.1.428

package/dist/safe-js/chunks/{chunk-MYKH5PM4.js → chunk-LXXUZNYA.js}

@@ -27,7 +27,7 @@ import {
   validateMigrationSemantics,
   validateSnapshotData,
   validateSnapshotMigration
-} from "./chunk-V3XJABDF.js";
+} from "./chunk-KHHM7HUO.js";
 
 // packages/safe-js/src/migrate.ts
 import { createHash } from "node:crypto";
@@ -8249,4 +8249,4 @@ export {
   parseMcpConfig,
   makeMcpModule
 };
-//# sourceMappingURL=chunk-MYKH5PM4.js.map
+//# sourceMappingURL=chunk-LXXUZNYA.js.map

package/dist/safe-js/cli.js

@@ -22,7 +22,7 @@ import {
   resolveFsConfig,
   splitFrontmatter,
   withBrokenPipeGuard
-} from "./chunks/chunk-MYKH5PM4.js";
+} from "./chunks/chunk-LXXUZNYA.js";
 import {
   Budget,
   SandboxError,
@@ -34,7 +34,7 @@ import {
   replaceErrorStack,
   restore,
   run
-} from "./chunks/chunk-V3XJABDF.js";
+} from "./chunks/chunk-KHHM7HUO.js";
 import "./chunks/chunk-4YIDX44G.js";
 
 // packages/safe-js/src/cli.ts

package/dist/safe-js/core.js

@@ -5,7 +5,7 @@ import {
   defineExtension,
   lint,
   run
-} from "./chunks/chunk-V3XJABDF.js";
+} from "./chunks/chunk-KHHM7HUO.js";
 import "./chunks/chunk-4YIDX44G.js";
 export {
   Budget,

package/dist/safe-js/index.js

@@ -26,7 +26,7 @@ import {
   runWithSpawnUsageAccumulator,
   splitFrontmatter,
   supportsSpawnMode
-} from "./chunks/chunk-MYKH5PM4.js";
+} from "./chunks/chunk-LXXUZNYA.js";
 import {
   Budget,
   FileSnapshotBackend,
@@ -50,7 +50,7 @@ import {
   registerPendingHostCallPolicy,
   restore,
   run
-} from "./chunks/chunk-V3XJABDF.js";
+} from "./chunks/chunk-KHHM7HUO.js";
 import "./chunks/chunk-4YIDX44G.js";
 
 // packages/safe-js/src/parse.ts

package/dist/safe-js/interp/async-disposable-stack.d.ts

@@ -0,0 +1,36 @@
+import { type Budget } from "./budget.js";
+import { type SandboxCallContext, type SandboxClosure, type SandboxPromise, type SandboxValue } from "./values.js";
+export type AsyncDisposableResource = {
+    method: SandboxClosure | undefined;
+    receiver: SandboxValue;
+    args: SandboxValue[];
+    syncFallback: boolean;
+    synchronous?: boolean;
+};
+export type AsyncDisposableStackState = {
+    disposed: boolean;
+    resources: AsyncDisposableResource[];
+};
+export type AsyncCleanupState = {
+    resources: AsyncDisposableResource[];
+    capability: {
+        promise: SandboxPromise;
+        resolve: SandboxClosure;
+        reject: SandboxClosure;
+    };
+    phase: "running" | "waiting" | "done";
+    failed: boolean;
+    failure: SandboxValue;
+    needsAwait: boolean;
+    hasAwaited: boolean;
+    generation: number;
+};
+export declare const asyncDisposableStackStates: WeakMap<object, AsyncDisposableStackState>;
+export declare const asyncCleanupStates: WeakMap<object, AsyncCleanupState>;
+export declare const asyncCleanupHandlers: WeakMap<SandboxClosure, {
+    cleanup: AsyncCleanupState;
+    action: "fulfilled" | "rejected";
+    generation: number;
+}>;
+export declare function createAsyncCleanupHandler(cleanup: AsyncCleanupState, action: "fulfilled" | "rejected", budget: Budget, context?: SandboxCallContext, generation?: number): SandboxClosure;
+export declare function advanceAsyncCleanup(cleanup: AsyncCleanupState, budget: Budget, context?: SandboxCallContext): Promise<void>;

package/dist/safe-js/interp/async.d.ts

@@ -6,7 +6,7 @@ import type { EvaluationResult } from "./exceptions.js";
 import type { InterpreterError, InterpreterSnapshot, LoopIterationSnapshot } from "./interpreter.js";
 import { CompileScope } from "./regex/compile-guard.js";
 import type { Scope } from "./scope.js";
-import { type SandboxCallContext, type SandboxClosure, type SandboxObject, type SandboxValue } from "./values.js";
+import { type SandboxCallContext, type SandboxClosure, type SandboxGenerator, type SandboxObject, type SandboxPromise, type SandboxValue } from "./values.js";
 export type InterpreterYieldPoint = {
     kind: "await" | "generator-yield" | "loop-iteration";
     nodeId?: number;
@@ -53,6 +53,8 @@ export type AsyncEvaluationContext = {
     };
     generatorYield?: (value?: SandboxValue, yieldNodeId?: number) => Promise<GeneratorCompletion>;
     asyncGenerator?: boolean;
+    asyncGeneratorFrame?: SandboxGenerator;
+    asyncFunction?: boolean;
     captureGeneratorScope?: (scope: Scope, blocks?: ReadonlyMap<number, Scope>, completions?: ReadonlyMap<number, import("./exceptions.js").CompletionResult>, expressions?: ReadonlyMap<number, import("./generator-expression-state.js").GeneratorExpressionState>) => void;
     generatorExpressionStates?: ReadonlyMap<number, import("./generator-expression-state.js").GeneratorExpressionState>;
     restoredGeneratorExpressionStates?: ReadonlyMap<number, import("./generator-expression-state.js").GeneratorExpressionState>;
@@ -67,12 +69,14 @@ export type AsyncEvaluationContext = {
     };
 };
 export type EvaluateAsyncNode = (node: ParseResult, context: AsyncEvaluationContext) => Promise<AsyncEvaluationResult>;
-export declare function emitResumeBreakpoint(context: AsyncEvaluationContext, breakpoint: ResumeBreakpoint): void;
+export declare function emitResumeBreakpoint(context: Pick<AsyncEvaluationContext, "onYield" | "snapshot" | "scope">, breakpoint: ResumeBreakpoint): void;
 export declare function evaluateArrowFunctionExpression(node: ArrowFunctionExpression, context: AsyncEvaluationContext, evaluateNode: EvaluateAsyncNode): Promise<AsyncEvaluationResult>;
 export declare function evaluateFunctionExpression(node: FunctionExpression, context: AsyncEvaluationContext, evaluateNode: EvaluateAsyncNode): Promise<AsyncEvaluationResult>;
 export declare function createInterpretedClosure(node: ArrowFunctionExpression | FunctionDeclaration | FunctionExpression, context: AsyncEvaluationContext, evaluateNode: EvaluateAsyncNode, homeObject?: SandboxObject | SandboxClosure, initializeGeneratorPrototype?: boolean): SandboxClosure;
-export declare function executeAsyncFunction(execute: (onSuspend: () => void) => Promise<SandboxValue>, budget: Budget, signal?: AbortSignal, callContext?: SandboxCallContext): import("./values.js").SandboxPromise;
+export declare function executeAsyncFunction(execute: (onSuspend: () => void) => Promise<SandboxValue>, budget: Budget, signal?: AbortSignal, callContext?: SandboxCallContext): SandboxPromise;
 export declare function evaluateAwaitExpression(node: AwaitExpression, context: AsyncEvaluationContext, evaluateNode: EvaluateAsyncNode): Promise<AsyncEvaluationResult>;
+export type AsyncSuspensionContext = Pick<AsyncEvaluationContext, "scope" | "captureGeneratorScope" | "generatorBlockScopes" | "finallyCompletions" | "generatorExpressionStates" | "generatorYield" | "generatorResume" | "asyncFunction" | "asyncGeneratorFrame" | "budget" | "onYield" | "snapshot" | "onSuspend" | "captureReplayState" | "signal">;
+export declare function suspendAsyncFunctionValue(value: SandboxValue, node: ParseResult, context: AsyncSuspensionContext, replayState?: unknown, callContext?: SandboxCallContext, phase?: "await" | "yield" | "return" | "resume-return"): Promise<SandboxValue>;
 export declare function executeClosure(node: ArrowFunctionExpression | FunctionDeclaration | FunctionExpression, args: readonly SandboxValue[], thisValue: SandboxValue, context: AsyncEvaluationContext, evaluateNode: EvaluateAsyncNode): Promise<SandboxValue>;
 export declare function normalizeClosureResult(result: SandboxValue | Promise<SandboxValue> | PromiseLike<SandboxValue>, budget?: Budget): SandboxValue;
 export {};

package/dist/safe-js/interp/exceptions.d.ts

@@ -4,6 +4,7 @@ import { type Budget } from "./budget.js";
 import type { Scope } from "./scope.js";
 import type { InterpreterError } from "./interpreter.js";
 import { type SandboxObject, type SandboxValue } from "./values.js";
+import type { AsyncSuspensionContext } from "./async.js";
 declare const capturedExceptionBrand: unique symbol;
 export type { SandboxErrorName } from "../error/shape.js";
 export type CompletionKind = "normal" | "return" | "throw" | "break" | "continue";
@@ -26,7 +27,9 @@ type CapturedException = {
     readonly stackFrames: readonly string[];
     readonly [capturedExceptionBrand]: true;
 };
-type ExceptionContext = {
+type ExceptionContext = AsyncSuspensionContext & {
+    onSuspend?: () => void;
+    signal?: AbortSignal;
     budget: Budget;
     callStack: readonly string[];
     scope: Scope;

package/dist/safe-js/interp/generator-expression-state.d.ts

@@ -1,6 +1,7 @@
 import type { SandboxValue } from "./values.js";
 import type { Scope } from "./scope.js";
-import type { SandboxIterator, IteratorSnapshot } from "./iteration.js";
+import type { CompletionResult } from "./exceptions.js";
+import type { SandboxIterator, IteratorSnapshot, IteratorAwaitState } from "./iteration.js";
 export type GeneratorExpressionState<T = SandboxValue, S = Scope, I = SandboxIterator | IteratorSnapshot> = {
     kind: "switch";
     phase: "test" | "body";
@@ -14,6 +15,12 @@ export type GeneratorExpressionState<T = SandboxValue, S = Scope, I = SandboxIte
     value: T;
     current: T;
     iterator: I;
+    phase?: "await" | "close";
+    awaitState?: IteratorAwaitState;
+    completion?: {
+        type: "normal" | "return" | "throw";
+        value: T;
+    };
 } | {
     kind: "declaration";
     index: number;
@@ -49,7 +56,12 @@ export type GeneratorExpressionState<T = SandboxValue, S = Scope, I = SandboxIte
     scope: S;
 } | {
     kind: "for-of-iterator";
-    phase: "left" | "body";
+    phase: "left" | "body" | "next" | "close";
+    awaitState?: IteratorAwaitState;
+    closeCompletion?: Omit<CompletionResult, "value" | "node" | "stackFrames"> & {
+        value: T;
+        stackFrames?: string[];
+    };
     async: boolean;
     value: T;
     current: T;
@@ -65,7 +77,7 @@ export type GeneratorExpressionState<T = SandboxValue, S = Scope, I = SandboxIte
     scope: S;
 } | {
     kind: "for";
-    phase: "init" | "test" | "body" | "update";
+    phase: "init" | "test" | "body" | "update" | "dispose";
     loopScope: S;
     activeScope: S;
 } | {

package/dist/safe-js/interp/generator.d.ts

@@ -3,9 +3,9 @@ export type GeneratorCompletion = {
     value: unknown;
 };
 export type GeneratorChannel = {
-    next(value?: unknown): Promise<IteratorResult<unknown>>;
-    return(value?: unknown): Promise<IteratorResult<unknown>>;
-    throw(error?: unknown): Promise<IteratorResult<unknown>>;
+    next(value?: unknown, record?: boolean): Promise<IteratorResult<unknown>>;
+    return(value?: unknown, record?: boolean): Promise<IteratorResult<unknown>>;
+    throw(error?: unknown, record?: boolean): Promise<IteratorResult<unknown>>;
     snapshot(): GeneratorChannelSnapshot;
 };
 export type GeneratorChannelSnapshot = {

package/dist/safe-js/interp/iteration.d.ts

@@ -1,6 +1,15 @@
 import { type SandboxGenerator, type SandboxCallContext, type SandboxValue } from "./values.js";
 import { Budget } from "./budget.js";
+export type IteratorAwaitState = {
+    kind: "result";
+} | {
+    kind: "value";
+    done: boolean;
+    closeOnReject: boolean;
+};
 export type SandboxIterator = {
+    awaitValue?(value: SandboxValue, state: IteratorAwaitState): Promise<SandboxValue>;
+    resumeAwait?(state: IteratorAwaitState, value: () => Promise<SandboxValue>): Promise<IteratorResult<SandboxValue>>;
     snapshot?(): IteratorSnapshot;
     readonly asyncProtocol?: true;
     readonly generator?: true;
@@ -38,6 +47,6 @@ export declare function readIteratorResult(iterator: SandboxIterator, result: It
     value: SandboxValue;
 }>;
 export declare function getSandboxAsyncIterator(value: SandboxValue, budget: Budget, context?: SandboxCallContext, signal?: AbortSignal): SandboxIterator | undefined;
-export declare function closeIterator(iterator: SandboxIterator, preserveThrow?: boolean): Promise<void>;
+export declare function closeIterator(iterator: SandboxIterator, preserveThrow?: boolean, awaitResult?: <T>(pending: Promise<T>) => Promise<T>): Promise<void>;
 export declare function getSandboxIterator(value: SandboxValue, budget?: Budget, context?: SandboxCallContext): SandboxIterator | undefined;
 export declare function generatorIterator(generator: SandboxGenerator, budget?: Budget, context?: SandboxCallContext): SandboxIterator;

package/dist/safe-js/interp/jobs.d.ts

@@ -17,6 +17,10 @@ export declare class SandboxJobQueue {
     private advance;
 }
 export declare function runPromiseJob<T>(task: () => T | Promise<T>): Promise<T>;
+export declare function createResumableJobContext(): {
+    run<T>(task: () => T): T;
+    release(): void;
+};
 export declare function runAsyncPrefix<T>(task: () => Promise<T>): Promise<T>;
 export declare function suspendJob<T>(pending: Promise<T>): Promise<T>;
 export {};

package/dist/safe-js/interp/resource-management.d.ts

@@ -0,0 +1,26 @@
+import type { ParseResult } from "../parse.js";
+import { type AsyncSuspensionContext } from "./async.js";
+import { type AsyncCleanupState, type AsyncDisposableResource } from "./async-disposable-stack.js";
+import { type Budget } from "./budget.js";
+import { type CompletionResult, type EvaluationResult } from "./exceptions.js";
+import type { Scope } from "./scope.js";
+import { type SandboxCallContext, type SandboxValue } from "./values.js";
+export type ResourceScopeState = {
+    resources: AsyncDisposableResource[];
+    cleanup?: AsyncCleanupState;
+    completion?: Omit<CompletionResult, "stackFrames"> & {
+        stackFrames?: string[];
+    };
+};
+export declare function resourceSuspension(context: AsyncSuspensionContext, node: ParseResult): {
+    awaitResource?: (value: SandboxValue) => Promise<SandboxValue>;
+    resumeResource?: boolean;
+};
+export declare function assertResourceScopeState(value: unknown): asserts value is ResourceScopeState;
+export declare function registerScopeResource(scope: Scope, value: SandboxValue, hint: "sync" | "async", budget: Budget, context?: SandboxCallContext): Promise<void>;
+export declare function evaluateResourceScope<TError>(scope: Scope, budget: Budget, context: (SandboxCallContext & {
+    onSuspend?: () => void;
+    signal?: AbortSignal;
+    awaitResource?: (value: SandboxValue) => Promise<SandboxValue>;
+    resumeResource?: boolean;
+}) | undefined, body: () => Promise<EvaluationResult<TError>>): Promise<EvaluationResult<TError>>;

package/dist/safe-js/interp/scope.d.ts

@@ -1,6 +1,7 @@
 import type { VariableDeclarationKind } from "../parse.js";
 import type { PrivateName } from "./private-state.js";
 import type { InterpreterSnapshot, InterpreterValue } from "./interpreter.js";
+import type { ResourceScopeState } from "./resource-management.js";
 type ScopeLookupResult = {
     found: true;
     kind: VariableDeclarationKind;
@@ -13,6 +14,7 @@ type ScopeOptions = {
     chargeData?: boolean;
 };
 export type ScopeFrame = {
+    resourceState?: ResourceScopeState;
     privateNames?: Array<[string, PrivateName]>;
     parent?: Scope;
     importMeta?: InterpreterValue;
@@ -34,6 +36,7 @@ export declare class Scope {
     private readonly parent?;
     private importMeta?;
     private readonly options;
+    resourceState?: ResourceScopeState;
     privateNames?: Map<string, PrivateName>;
     constructor(bindings?: Record<string, InterpreterValue>, parent?: Scope | undefined, importMeta?: InterpreterValue, options?: ScopeOptions, restoredBindings?: Record<string, InterpreterValue>);
     child(bindings?: Record<string, InterpreterValue>, options?: ScopeOptions): Scope;
@@ -62,6 +65,7 @@ export declare class Scope {
     hydrateFrame(frame: ScopeFrame): void;
     copyInitializedBindingsFrom(source: Scope, names: readonly string[]): void;
     private resolveScope;
+    private trackReplacement;
     private requireInitializedBinding;
 }
 export {};

package/dist/safe-js/parse/parser.d.ts

@@ -217,6 +217,7 @@ export type VariableDeclaration = BaseNode & {
     type: "VariableDeclaration";
     declarations: VariableDeclarator[];
     kind: VariableDeclarationKind;
+    disposal?: "sync" | "async";
 };
 export type ReturnStatement = BaseNode & {
     type: "ReturnStatement";

package/dist/safe-js/snapshot/guest-heap.d.ts

@@ -18,6 +18,7 @@ export type AsyncResourceData<T> = {
     receiver: T;
     args: T[];
     syncFallback: boolean;
+    synchronous?: boolean;
 };
 export type GuestObjectState<T> = {
     properties: PropertyDescriptorData<T>;
@@ -35,6 +36,45 @@ export type PrivateElementData<T> = {
     set: T;
 });
 export type GuestHeapNode<T> = {
+    kind: "async-generator-driver";
+    generator: T;
+    requests: Array<{
+        method: "next" | "return" | "throw";
+        value: T;
+        capability: {
+            promise: T;
+            resolve: T;
+            reject: T;
+        };
+    }>;
+    phase: "idle" | "waiting";
+    suspension: "await" | "yield";
+    awaitKind: "body" | "return";
+    generation: number;
+} | {
+    kind: "async-generator-handler";
+    driver: T;
+    owner: T;
+    action: "fulfilled" | "rejected";
+    generation: number;
+    state: GuestObjectState<T>;
+} | {
+    kind: "async-function-driver";
+    generator: T;
+    capability: {
+        promise: T;
+        resolve: T;
+        reject: T;
+    };
+    phase: "waiting" | "done";
+    generation: number;
+} | {
+    kind: "async-function-handler";
+    driver: T;
+    action: "fulfilled" | "rejected";
+    generation: number;
+    state: GuestObjectState<T>;
+} | {
     kind: "async-disposable-stack";
     disposed: boolean;
     resources: AsyncResourceData<T>[];
@@ -128,6 +168,7 @@ export type GuestHeapNode<T> = {
     value: T;
     reactions?: T[];
     producers?: T[];
+    generatorOwner?: T;
     state: GuestObjectState<T>;
 } | {
     kind: "promise-resolver";
@@ -140,6 +181,7 @@ export type GuestHeapNode<T> = {
     thenable?: T;
     reactions: T[];
     producers?: T[];
+    generatorOwner?: T;
     state: GuestObjectState<T>;
 } | {
     kind: "promise-adoption";
@@ -261,6 +303,9 @@ export type GuestHeapNode<T> = {
     kind: "guest-generator";
     state: "start" | "running" | "suspended" | "done";
     astNodeId: number;
+    asyncFunction?: true;
+    driver?: T;
+    awaitPhase?: "await" | "yield" | "return" | "resume-return";
     async: boolean;
     scope: T;
     closureScope: T;
@@ -310,6 +355,7 @@ export type GuestHeapNode<T> = {
     importMeta: T;
     functionBoundary: boolean;
     chargeData: boolean;
+    resourceState?: T;
     privateNames?: Array<[string, T]>;
     bindings: Array<[string, number]>;
     cells: Array<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-js",
-  "version": "0.1.426",
+  "version": "0.1.428",
   "description": "Budgeted JavaScript interpreter with explicit host capabilities and resumable execution",
   "type": "module",
   "license": "MIT",
@@ -58,7 +58,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@poe-platform/safe-fs": "0.1.426",
+    "@poe-platform/safe-fs": "0.1.428",
     "@petamoriken/float16": "^3.9.3",
     "yaml": "^2.8.2",
     "jose": "^6.1.3",