@poe-platform/safe-js 0.1.721 → 0.1.722

package/dist/safe-js/modules/source-graph.d.ts

@@ -19,7 +19,11 @@ export declare class SourceModuleGraph {
     private readonly records;
     private readonly requests;
     private requestDataSize;
+    private lookupDataSize;
     private readonly pendingImports;
+    private fulfilledImports;
+    private rejectedImports;
+    private readonly importGroup;
     private readonly jobs;
     private readonly evaluationStack;
     private evaluationIndex;
@@ -27,10 +31,24 @@ export declare class SourceModuleGraph {
         scope: Scope;
         resolver: SourceResolver;
         modules: ModuleEnvironment;
+        serializePreparation?: boolean;
+        importDeadline?: {
+            timeoutMs: number;
+            abort(reason: unknown): void;
+        };
     });
     close(): void;
+    sourceModuleStatus(): Readonly<{
+        pendingImports: number;
+        preparedModules: number;
+        fulfilledImports: number;
+        rejectedImports: number;
+    }>;
     import(specifier: string, referrer: string): Promise<SandboxObject>;
-    settle(): Promise<void>;
+    private startImportDeadline;
+    withoutImportGroup<Result>(task: () => Result): Result;
+    withImportGroup<Result>(task: () => Promise<Result>): Promise<Result>;
+    settle(pendingImports?: Set<Promise<SandboxObject>>): Promise<void>;
     evaluateSource(source: SourceModule, beforeEvaluation?: (module: Module) => void): Promise<SandboxObject>;
     private register;
     private load;

package/dist/safe-js/parse/compact-spans.d.ts

@@ -0,0 +1,18 @@
+import type { SourceSpan } from "./parser.js";
+import type { Position } from "./tokenizer.js";
+/** Immutable source coordinates shared by compiler-owned offset spans. */
+export declare class CompactSourcePositions {
+    private readonly sourceLength;
+    private readonly lines;
+    private readonly positions;
+    private readonly makeSpan;
+    constructor(source: string);
+    position(offset: number): Position;
+    span(start: number, end: number): SourceSpan;
+    compatiblePosition(position: Position): Position | undefined;
+    private assertOffset;
+}
+/** Rebased template coordinates compact only when their existing data agrees. */
+export declare function compactDerivedPosition(base: Position, position: Position): Position | undefined;
+/** Only privately owned points from the same source can become offset spans. */
+export declare function compactSourceSpan(start: Position, end: Position): SourceSpan | undefined;

package/dist/safe-js/parse/dynamic-source.d.ts

@@ -23,7 +23,9 @@ export declare function createDynamicSource(kind: DynamicFunctionKind, parameter
 };
 export declare function createEvalSource(body: string, context: Omit<EvalParseContext, "privateNames"> & {
     privateNames?: Iterable<string>;
-}, owner?: CompileOwner, filename?: string): {
+}, owner?: CompileOwner, filename?: string, options?: {
+    compactAst?: boolean;
+}): {
     source: {
         body: string;
         nodes: Map<number, ParseResult>;

package/dist/safe-js/parse/function-source.d.ts

@@ -4,7 +4,7 @@ export type FunctionSource = {
     readonly start: number;
     readonly end: number;
 };
-export declare const functionSources: WeakMap<ClassNode | FunctionNode, FunctionSource>;
+export declare const functionSources: WeakMap<FunctionNode | ClassNode, FunctionSource>;
 export declare const templateSources: WeakMap<TemplateLiteral, string>;
 export declare const functionStrictness: WeakMap<FunctionNode, boolean>;
 /** Eval-root declarations are instantiated before statement execution. */

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

@@ -421,8 +421,11 @@ export type Expression = ArrowFunctionExpression | AssignmentExpression | ArrayE
 export type ParseResult = Expression | Statement;
 export declare function parse(source: string, filename?: string, owner?: CompileOwner): ParseResult;
 export declare function parseModule(source: string, filename?: string, owner?: CompileOwner): Module;
-export declare function parseSourceModule(source: string, filename?: string, owner?: CompileOwner): ParsedSourceModule;
-export declare function parseExecutableModule(source: string, filename?: string, owner?: CompileOwner): Module;
+export declare function parseSourceModule(source: string, filename?: string, owner?: CompileOwner, options?: {
+    sharedPositions?: boolean;
+    compactAst?: boolean;
+}): ParsedSourceModule;
+export declare function parseExecutableModule(source: string, filename?: string, owner?: CompileOwner, importSpecifiers?: readonly string[]): Module;
 export type EvalParseContext = {
     strict?: boolean;
     newTarget?: boolean;
@@ -431,7 +434,9 @@ export type EvalParseContext = {
     arguments?: boolean;
     privateNames?: ReadonlySet<string>;
 };
-export declare function parseEvalScript(source: string, context?: EvalParseContext, owner?: CompileOwner, filename?: string): {
+export declare function parseEvalScript(source: string, context?: EvalParseContext, owner?: CompileOwner, filename?: string, options?: {
+    compactAst?: boolean;
+}): {
     node: Module;
     strict: boolean;
 };

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

@@ -1,3 +1,4 @@
+import type { CompactSourcePositions } from "./compact-spans.js";
 import { type CompileScope } from "../interp/regex/compile-guard.js";
 export type Position = {
     line: number;
@@ -30,7 +31,10 @@ export type TokenizeOptions = {
     allowHtmlComments?: boolean;
     comments?: Comment[];
     compilation?: CompileScope;
+    sharedPositions?: boolean;
 };
 export declare const RESERVED_IDENTIFIER_SPELLINGS: Set<string>;
 export declare function tokenize(source: string, options?: TokenizeOptions): Token[];
+/** Internal classic compilation with bounded materialized token/position caches. */
+export declare function tokenizeCompact(source: string, options: TokenizeOptions, positions: CompactSourcePositions): Token[];
 export declare function collectComments(source: string): Comment[];

package/dist/safe-js/realm.d.ts

@@ -3,7 +3,7 @@ import { type InterpreterResult } from "./interp/interpreter.js";
 import { SandboxJobQueue, type ExecutionControl } from "./interp/jobs.js";
 import { type CallerInjectedBinding } from "./interp/host-bridge.js";
 import { type CallbackOptions, type CallbackInvocation, type SafeJSExtension } from "./extensions.js";
-import { type SourceResolver } from "./modules/source-graph.js";
+import { SourceModuleGraph, type SourceResolver } from "./modules/source-graph.js";
 import { type ModuleRegistry } from "./modules/registry.js";
 import type { ConsoleSink } from "./interp/globals/console-json.js";
 import type { RunClock, RunOptions, RunResult } from "./run.js";
@@ -16,8 +16,13 @@ export type RealmLimits = {
     nestedEvaluations?: number;
 };
 export type RealmOptions = {
+    stringCompilation?: "allow" | "deny";
     classicScripts?: boolean;
+    classicScriptErrors?: "fatal" | "report";
+    callbackScheduling?: "after-prefix";
     sourceResolver?: SourceResolver;
+    /** Elapsed host-time limit per dynamic import; expiry revokes the whole realm. */
+    sourceImportTimeoutMs?: number;
     clock?: RunClock;
     bindings?: Record<string, CallerInjectedBinding>;
     modules?: ModuleRegistry;
@@ -36,19 +41,27 @@ export type RealmResult = (Omit<Extract<InterpreterResult, {
     ok: true;
 }>, "snapshot" | "returnValue"> & {
     returnValue?: unknown;
-}) | Omit<Extract<InterpreterResult, {
+}) | (Omit<Extract<InterpreterResult, {
     ok: false;
-}>, "snapshot">;
+}>, "snapshot"> & {
+    recoverable?: true;
+});
 export type SafeJSRealm = ExecutionControl & {
+    readonly stringCompilation: "allow" | "deny";
+    readonly classicScriptErrors: "fatal" | "report";
+    readonly supportsDiscardResult: true;
+    readonly sourceImportTimeoutMs?: number;
     readonly extensions: readonly SafeJSExtension["manifest"][];
     evaluate(source: string, options?: {
         filename?: string;
         sourceType?: "module";
+        discardResult?: boolean;
     }): Promise<RealmResult>;
     startCallback(callback: unknown, options?: CallbackOptions): CallbackInvocation;
     invokeCallback(callback: unknown, options?: CallbackOptions): Promise<unknown>;
     releaseCallback(callback: unknown): void;
     releaseGuestReference(reference: unknown): void;
+    sourceModuleStatus(): ReturnType<SourceModuleGraph["sourceModuleStatus"]>;
     close(): Promise<void>;
 };
 export declare function createRealm(options?: RealmOptions): SafeJSRealm;

package/dist/safe-js/restore.d.ts

@@ -17,6 +17,7 @@ export type SafeJSSnapshot = {
 };
 export type RestoreOptions = {
     source: string;
+    importSpecifiers?: readonly string[];
 };
 export declare class SnapshotMismatchError extends Error {
     readonly actualHash: string;

package/dist/safe-js/run.d.ts

@@ -15,6 +15,7 @@ import { type OtelSink } from "./observability/otel.js";
 import type { SnapshotBackend } from "./snapshot/backend.js";
 import { type ReplayData } from "./snapshot/replay-data.js";
 export type RunOptions = {
+    importSpecifiers?: readonly string[];
     sourceType?: "module";
     sourceResolver?: SourceResolver;
     sourceRoot?: string;
@@ -27,6 +28,15 @@ export type RunOptions = {
     clock?: RunClock;
     entryPointArgs?: readonly unknown[];
     filename?: string;
+    /** Trusted diagnostic mapping; re-supply when resuming a snapshot. Does not change source or execution. */
+    sourceLocation?: (position: {
+        line: number;
+        column: number;
+    }) => {
+        filename: string;
+        line: number;
+        column: number;
+    } | undefined;
     importMeta?: Record<string, unknown>;
     hostCallResumeProvider?: HostCallResumeProvider;
     modules?: ModuleRegistry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-js",
-  "version": "0.1.721",
+  "version": "0.1.722",
   "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.721",
+    "@poe-platform/safe-fs": "0.1.722",
     "@petamoriken/float16": "^3.9.3",
     "@formatjs/intl-localematcher": "0.8.13",
     "@formatjs/bigdecimal": "0.2.7",

package/dist/safe-js/chunks/chunk-A4L72WXV.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/restore.ts"],
-  "sourcesContent": ["import { hashSource } from \"./parse/hash.js\";\nimport type { CompileOwner } from \"./interp/budget.js\";\nimport { replaceErrorStack } from \"./error/shape.js\";\nimport { SnapshotValidationError, validateDumpEnvelope, validateRuntimeSnapshotDescriptors } from \"./snapshot/validation.js\";\nimport { inMemoryRunSnapshots, serializeSafeJSSnapshot } from \"./snapshot/dump-format.js\";\nimport { assertSnapshotInactive } from \"./interp/running-state.js\";\nimport { validateSnapshotMigration, type SnapshotMigration } from \"./snapshot/migration.js\";\nimport { parseModule } from \"./parse/parser.js\";\nimport { ParseError } from \"./parse/format-error.js\";\nimport { createModuleSource, createDynamicSource, createEvalSource, type DynamicSource, type EvalSourceContext } from \"./parse/dynamic-source.js\";\nimport { validateGuestFunctionAst } from \"./snapshot/guest-ast-validation.js\";\nimport { validateTemplateObjects } from \"./snapshot/template-validation.js\";\nimport type { ParseResult } from \"./parse.js\";\n\nexport type SafeJSSnapshot = {\n  version?: number;\n  sourceHash: string;\n  migration?: SnapshotMigration;\n  clock?: {\n    next: number;\n  };\n  random?: {\n    seed: number;\n    state: number;\n    initialState?: number;\n    resumeState?: number;\n  };\n  [key: string]: unknown;\n};\n\nexport type RestoreOptions = {\n  source: string;\n};\n\nexport class SnapshotMismatchError extends Error {\n  readonly actualHash: string;\n  readonly expectedHash: string;\n\n  constructor(expectedHash: string, actualHash: string) {\n    super(\n      `source changed since snapshot was taken (hash ${expectedHash} expected, got ${actualHash}); pass --reset to discard`\n    );\n    this.name = \"SnapshotMismatchError\";\n    this.actualHash = actualHash;\n    this.expectedHash = expectedHash;\n    replaceErrorStack(this);\n  }\n}\n\nexport function restore<TSnapshot extends SafeJSSnapshot>(\n  snapshot: TSnapshot,\n  options: RestoreOptions,\n  owner?: CompileOwner\n): TSnapshot {\n  assertSnapshotInactive(snapshot);\n  try {\n    validateDumpEnvelope(snapshot, { resume: true });\n  } catch (error) {\n    if (!(error instanceof SnapshotValidationError) || error.code !== \"invalidState\" ||\n        !inMemoryRunSnapshots.has(snapshot)) throw error;\n    // Runtime snapshots can retain guest descriptor state. Use the same portable\n    // representation as dump(), then apply all normal validation below.\n    validateRuntimeSnapshotDescriptors(snapshot);\n    snapshot = JSON.parse(serializeSafeJSSnapshot(snapshot)) as TSnapshot;\n    validateDumpEnvelope(snapshot, { resume: true });\n  }\n  validateSnapshotMigration(snapshot.migration, snapshot.sourceHash, owner);\n\n  const currentSourceHash = hashSource(\n    options.source,\n    owner,\n    snapshot.executionSemantics !== \"jobs-v6\" && snapshot.executionSemantics !== \"jobs-v7\"\n  );\n\n  if (snapshot.sourceHash !== currentSourceHash) {\n    throw new SnapshotMismatchError(snapshot.sourceHash, currentSourceHash);\n  }\n\n  if (snapshot.heap !== undefined && typeof snapshot.heap === \"object\" && snapshot.heap !== null) {\n    const entries = Object.entries(snapshot.heap);\n    const closures = entries.filter(([, value]) =>\n      value !== null && typeof value === \"object\" && ([\"guest-function\", \"guest-class\", \"guest-generator\"].includes(String((value as Record<string, unknown>).kind)) ||\n        (value as Record<string, unknown>).templateNodeId !== undefined));\n    const dynamicSources = new Map<number, DynamicSource>();\n    for (const [id, value] of entries) {\n      const record = value as Record<string, unknown>;\n      if (record.kind === \"guest-source\" || record.kind === \"guest-script\") {\n        try {\n          const compiled = record.kind === \"guest-script\"\n            ? createEvalSource(record.body as string, record.context as EvalSourceContext, owner)\n            : record.functionKind === \"module\" ? createModuleSource(record.body as string, owner)\n            : createDynamicSource(record.functionKind as Exclude<DynamicSource[\"kind\"], \"eval\" | \"module\">,\n              record.parameters as string, record.body as string, owner);\n          dynamicSources.set(Number(id), compiled.source);\n        } catch (error) {\n          if (!(error instanceof SyntaxError) && !(error instanceof ParseError)) throw error;\n          throw new SnapshotValidationError(\"invalidValue\", `$.heap[${JSON.stringify(id)}]`, error.message);\n        }\n      }\n    }\n    if (closures.length > 0) {\n      const functions = new Map<number, Record<string, unknown>>();\n      const pending: unknown[] = [parseModule(options.source, \"<input>\", owner)];\n      while (pending.length > 0) {\n        const value = pending.pop();\n        if (value === null || typeof value !== \"object\") continue;\n        const node = value as Record<string, unknown>;\n        if (typeof node.nodeId === \"number\") {\n          functions.set(node.nodeId, node);\n        }\n        for (const entry of Object.values(node)) pending.push(entry);\n      }\n      for (const [id, value] of closures) {\n        const record = value as Record<string, unknown>;\n        if (record.kind === \"guest-array\") continue;\n        const nodes = record.dynamicSource === undefined ? functions\n          : dynamicSources.get((record.dynamicSource as {id: number}).id)!.nodes;\n        const origin = nodes.get(record.astNodeId as number);\n        try { validateGuestFunctionAst(record, origin); }\n        catch (error) {\n          throw new SnapshotValidationError(\"invalidValue\", `$.heap[${JSON.stringify(id)}].astNodeId`, error instanceof Error ? error.message : String(error));\n        }\n      }\n      try { validateTemplateObjects(snapshot.heap as Record<string, unknown>, functions.values() as Iterable<ParseResult>, dynamicSources); }\n      catch (error) { throw new SnapshotValidationError(\"invalidValue\", \"$.heap\", String(error)); }\n    }\n  }\n\n  return snapshot;\n}\n"],
-  "mappings": "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",
-  "names": []
-}