poe-code 10.0.3 → 11.0.0

package/packages/safejs/dist/interp/interpreter.js

@@ -422,32 +422,30 @@ async function evaluateAssignmentExpression(node, context) {
             error: createError("UNSUPPORTED_NODE", node, `Unsupported assignment target '${node.left.type}'.`)
         };
     }
-    const binding = context.scope.lookup(node.left.name);
-    if (!binding.found) {
+    const binding = node.operator === "=" ? undefined : context.scope.lookup(node.left.name);
+    if (binding?.found === false) {
         throw new ReferenceError(`Cannot assign to undeclared binding '${node.left.name}'.`);
     }
-    if (binding.kind === "const") {
-        throw new TypeError(`Cannot assign to const '${node.left.name}'`);
-    }
-    if (node.operator === "&&=" && !isTruthy(binding.value)) {
+    const current = binding?.value;
+    if (node.operator === "&&=" && !isTruthy(current)) {
         return {
             kind: "normal",
             hasValue: true,
-            value: binding.value
+            value: current
         };
     }
-    if (node.operator === "||=" && isTruthy(binding.value)) {
+    if (node.operator === "||=" && isTruthy(current)) {
         return {
             kind: "normal",
             hasValue: true,
-            value: binding.value
+            value: current
         };
     }
-    if (node.operator === "??=" && binding.value !== null && binding.value !== undefined) {
+    if (node.operator === "??=" && current !== null && current !== undefined) {
         return {
             kind: "normal",
             hasValue: true,
-            value: binding.value
+            value: current
         };
     }
     const right = await evaluateNode(node.right, context);
@@ -459,7 +457,7 @@ async function evaluateAssignmentExpression(node, context) {
         node.operator === "||=" ||
         node.operator === "??="
         ? right.value
-        : applyCompoundAssignmentOperator(node.operator, binding.value, right.value, context);
+        : await applyCompoundAssignmentOperator(node.operator, current, right.value, context);
     context.scope.assign(node.left.name, value);
     return {
         kind: "normal",
@@ -481,55 +479,38 @@ async function evaluateMemberAssignmentExpression(node, context) {
     if (member.kind === "nullish") {
         throw new TypeError("Cannot assign properties of null or undefined.");
     }
-    if (isSandboxRegex(member.object)) {
-        if (node.operator !== "=") {
-            throw new TypeError("RegExp properties only support direct assignment.");
-        }
-        const right = await evaluateNode(node.right, context);
-        if (right.kind !== "normal")
-            return right;
-        setRegexMember(member.object, member.property, right.value);
-        return { kind: "normal", hasValue: true, value: right.value };
-    }
-    if (!isIndexableSandboxValue(member.object)) {
-        throw new TypeError("Assignment expressions require a sandbox object property.");
-    }
-    if (node.operator === "&&=" &&
-        !isTruthy(getMemberValue(member.object, member.property, context))) {
+    const current = node.operator === "=" ? undefined : getPropertyValue(member.object, member.property, context);
+    if (node.operator === "&&=" && !isTruthy(current)) {
         return {
             kind: "normal",
             hasValue: true,
-            value: getMemberValue(member.object, member.property, context)
+            value: current
         };
     }
-    if (node.operator === "||=" &&
-        isTruthy(getMemberValue(member.object, member.property, context))) {
+    if (node.operator === "||=" && isTruthy(current)) {
         return {
             kind: "normal",
             hasValue: true,
-            value: getMemberValue(member.object, member.property, context)
+            value: current
         };
     }
-    if (node.operator === "??=" &&
-        getMemberValue(member.object, member.property, context) !== null &&
-        getMemberValue(member.object, member.property, context) !== undefined) {
+    if (node.operator === "??=" && current !== null && current !== undefined) {
         return {
             kind: "normal",
             hasValue: true,
-            value: getMemberValue(member.object, member.property, context)
+            value: current
         };
     }
     const right = await evaluateNode(node.right, context);
     if (right.kind !== "normal") {
         return right;
     }
-    const current = getMemberValue(member.object, member.property, context);
     const value = node.operator === "=" ||
         node.operator === "&&=" ||
         node.operator === "||=" ||
         node.operator === "??="
         ? right.value
-        : applyCompoundAssignmentOperator(node.operator, current, right.value, context);
+        : await applyCompoundAssignmentOperator(node.operator, current, right.value, context);
     setSandboxProperty(member.object, member.property, value);
     return {
         kind: "normal",
@@ -1493,10 +1474,7 @@ async function evaluateIdentifierUpdateExpression(node, context) {
             error: createError("UNBOUND_IDENTIFIER", node.argument, `Identifier '${node.argument.name}' is not defined.`)
         };
     }
-    if (binding.kind === "const") {
-        throw new TypeError(`Cannot assign to const '${node.argument.name}'`);
-    }
-    const current = Number(binding.value);
+    const current = toNumber(await toNumericPrimitive(binding.value, context));
     const next = node.operator === "++" ? current + 1 : current - 1;
     context.scope.assign(node.argument.name, next);
     return {
@@ -1519,10 +1497,7 @@ async function evaluateMemberUpdateExpression(node, context) {
     if (member.kind === "nullish") {
         throw new TypeError("Cannot update properties of null or undefined.");
     }
-    if (!isIndexableSandboxValue(member.object)) {
-        throw new TypeError("Update expressions require a sandbox object property.");
-    }
-    const current = Number(getMemberValue(member.object, member.property, context));
+    const current = toNumber(await toNumericPrimitive(getPropertyValue(member.object, member.property, context), context));
     const next = node.operator === "++" ? current + 1 : current - 1;
     setSandboxProperty(member.object, member.property, next);
     return {
@@ -1533,94 +1508,45 @@ async function evaluateMemberUpdateExpression(node, context) {
 }
 async function evaluateMemberExpression(node, context) {
     const member = await evaluateMemberAccess(node, context);
-    if (member.kind === "error") {
+    if (member.kind === "error")
         return member;
-    }
-    if (member.kind === "completion") {
+    if (member.kind === "completion")
         return member.result;
-    }
     if (member.kind === "nullish") {
-        if (node.optional) {
-            return {
-                kind: "normal",
-                hasValue: true,
-                value: undefined
-            };
-        }
+        if (node.optional)
+            return { kind: "normal", hasValue: true, value: undefined };
         throw new TypeError("Cannot read properties of null or undefined.");
     }
-    if (typeof member.object === "string") {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getStringMember(member.object, member.property, context.budget)
-        };
-    }
-    if (typeof member.object === "number") {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getNumberMember(member.object, member.property, context.budget)
-        };
-    }
-    if (Array.isArray(member.object)) {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getArrayMemberValue(member.object, member.property, context)
-        };
-    }
-    if (isSandboxMap(member.object)) {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getMapMember(member.object, member.property, createMapMethodOptions(context))
-        };
-    }
-    if (isSandboxSet(member.object)) {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getSetMember(member.object, member.property, createSetMethodOptions(context))
-        };
-    }
-    if (isSandboxGenerator(member.object)) {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getGeneratorMember(member.object, member.property, context.budget)
-        };
-    }
-    if (isSandboxClosure(member.object)) {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getClosureMemberValue(member.object, member.property, context)
-        };
-    }
-    if (isSandboxPromise(member.object)) {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getPromiseMember(member.property, context.budget)
-        };
-    }
-    if (isSandboxRegex(member.object)) {
-        return {
-            kind: "normal",
-            hasValue: true,
-            value: getRegexMember(member.object, member.property)
-        };
-    }
-    if (!isIndexableSandboxValue(member.object)) {
-        throw new TypeError("Attempted to read a property from a non-object value.");
-    }
     return {
         kind: "normal",
         hasValue: true,
-        value: getMemberValue(member.object, member.property, context)
+        value: getPropertyValue(member.object, member.property, context)
     };
 }
+function getPropertyValue(target, property, context) {
+    if (typeof target === "string")
+        return getStringMember(target, property, context.budget);
+    if (typeof target === "number")
+        return getNumberMember(target, property, context.budget);
+    if (typeof target === "boolean")
+        return undefined;
+    if (isSandboxMap(target))
+        return getMapMember(target, property, createMapMethodOptions(context));
+    if (isSandboxSet(target))
+        return getSetMember(target, property, createSetMethodOptions(context));
+    if (isSandboxGenerator(target))
+        return getGeneratorMember(target, property, context.budget);
+    if (isSandboxClosure(target))
+        return getClosureMemberValue(target, property, context);
+    if (isSandboxPromise(target))
+        return getPromiseMember(property, context.budget);
+    if (isSandboxRegex(target))
+        return getRegexMember(target, property);
+    if (!isIndexableSandboxValue(target)) {
+        throw new TypeError("Attempted to read a property from a non-object value.");
+    }
+    return getMemberValue(target, property, context);
+}
 async function evaluateCallExpression(node, context) {
     if (node.callee.type === "MemberExpression") {
         context.budget.visitNode();
@@ -2033,7 +1959,9 @@ function applyBinaryOperator(node, left, right, context) {
             throw createError("UNSUPPORTED_NODE", node, "Binary operator 'in' is not supported.");
     }
 }
-function applyCompoundAssignmentOperator(operator, left, right, context) {
+async function applyCompoundAssignmentOperator(operator, left, right, context) {
+    left = await toNumericPrimitive(left, context);
+    right = await toNumericPrimitive(right, context);
     switch (operator) {
         case "+=":
             return applyAdditionOperator(left, right, context);
@@ -2160,6 +2088,9 @@ async function toNumericPrimitive(value, context) {
     if (isIndexableSandboxValue(value)) {
         for (const methodName of ["valueOf", "toString"]) {
             const method = getMemberValue(value, methodName, context);
+            if (methodName === "toString" && method === undefined && !Object.hasOwn(value, methodName)) {
+                return toString(value);
+            }
             if (!isSandboxClosure(method)) {
                 continue;
             }
@@ -2168,6 +2099,7 @@ async function toNumericPrimitive(value, context) {
                 return result;
             }
         }
+        throw new TypeError("Cannot convert object to primitive value.");
     }
     return toString(value);
 }
@@ -2231,17 +2163,31 @@ function getArrayMemberValue(target, property, context) {
     return getArrayMember(target, property, createArrayMethodOptions(context));
 }
 function setSandboxProperty(target, property, value) {
+    if (isSandboxRegex(target)) {
+        setRegexMember(target, property, value);
+        return;
+    }
+    if (!isIndexableSandboxValue(target)) {
+        throw new TypeError("Assignment expressions require a sandbox object property.");
+    }
+    const key = String(property);
     if (Array.isArray(target)) {
         assertCollectionMutable(target);
-        const key = String(property);
         if (key === "length" || isArrayIndexKey(key)) {
             target[key] = value;
             return;
         }
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    if (descriptor !== undefined) {
+        if (descriptor.writable !== true) {
+            throw new TypeError(`Cannot assign to read only property '${key}'.`);
+        }
+        Object.defineProperty(target, key, { value });
+    }
+    else {
         defineSandboxProperty(target, key, value);
-        return;
     }
-    defineSandboxProperty(target, String(property), value);
 }
 function deleteSandboxProperty(target, property) {
     if (Array.isArray(target)) {

package/packages/safejs/dist/interp/scope.js

@@ -126,15 +126,15 @@ export class Scope {
             throw new ReferenceError(`Cannot assign to undeclared binding '${name}'.`);
         }
         const binding = scope.#bindings.get(name);
-        if (binding?.kind === "const") {
-            throw new TypeError(`Cannot assign to const binding '${name}'.`);
-        }
         if (binding === undefined) {
             throw new ReferenceError(`Cannot assign to undeclared binding '${name}'.`);
         }
         if (binding.value === uninitialized) {
             throw new ReferenceError(`Cannot access '${name}' before initialization.`);
         }
+        if (binding.kind === "const") {
+            throw new TypeError(`Cannot assign to const binding '${name}'.`);
+        }
         scope.#bindings.set(name, {
             kind: binding.kind,
             value

package/packages/safejs/dist/migrate.d.ts

@@ -0,0 +1,33 @@
+import type { SafeJSSnapshot } from "./restore.js";
+import { type SnapshotMigration, type SnapshotMigrationReconciliation } from "./snapshot/migration.js";
+export type { SnapshotMigration, SnapshotMigrationReconciliation, SnapshotMigrationResolution } from "./snapshot/migration.js";
+export type SnapshotMigrationOptions = {
+    source: string;
+    targetSource: string;
+    state: unknown;
+    reconciliation: SnapshotMigrationReconciliation;
+};
+export declare function inspectSnapshotMigration(snapshot: SafeJSSnapshot, options: {
+    source: string;
+}): {
+    checkpointDigest: string;
+    sourceHash: string;
+    executionSemantics: string;
+    calls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+        asynchronous: boolean;
+        outcome?: {
+            status: "fulfilled" | "rejected";
+            data: import("./snapshot/replay-data.js").ReplayData;
+        };
+    })[];
+    unresolvedCalls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+        asynchronous: boolean;
+        outcome?: {
+            status: "fulfilled" | "rejected";
+            data: import("./snapshot/replay-data.js").ReplayData;
+        };
+    })[];
+};
+export declare function migrateSnapshot(snapshot: SafeJSSnapshot, options: SnapshotMigrationOptions): SafeJSSnapshot & {
+    migration: SnapshotMigration;
+};

package/packages/safejs/dist/migrate.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { assertSnapshotInactive } from "./interp/running-state.js";
+import { deepCopyToSandbox } from "./interp/values.js";
+import { hashSource } from "./parse/hash.js";
+import { parseModule } from "./parse/parser.js";
+import { DUMP_FORMAT_VERSION, EXECUTION_SEMANTICS } from "./snapshot/dump-format.js";
+import { validateMigrationJournal, validateMigrationReconciliation, validateMigrationSemantics, validateSnapshotMigration } from "./snapshot/migration.js";
+import { encodeReplayData } from "./snapshot/replay-data.js";
+import { validateDumpEnvelope, validateSnapshotData } from "./snapshot/validation.js";
+export function inspectSnapshotMigration(snapshot, options) {
+    assertSnapshotInactive(snapshot);
+    validateSnapshotData(snapshot);
+    validateDumpEnvelope(snapshot);
+    validateMigrationSemantics(snapshot.executionSemantics);
+    const sourceHash = hashSource(options.source);
+    if (snapshot.sourceHash !== sourceHash)
+        throw new TypeError(`Migration requires the original executable source (checkpoint hash ${snapshot.sourceHash}, supplied ${sourceHash}). Preserve the checkpoint; do not replace its hash.`);
+    validateSnapshotMigration(snapshot.migration, sourceHash);
+    const replay = validateMigrationJournal(sourceHash, snapshot.replay, snapshot.hostCalls);
+    return {
+        checkpointDigest: createHash("sha256").update(canonicalData(snapshot)).digest("hex"),
+        sourceHash,
+        executionSemantics: snapshot.executionSemantics,
+        calls: replay.calls,
+        unresolvedCalls: replay.calls.filter((call) => !["settled", "consumed"].includes(call.lifecycle))
+    };
+}
+export function migrateSnapshot(snapshot, options) {
+    if (!Object.hasOwn(options, "state"))
+        throw new TypeError("Migration requires explicit application state.");
+    const inspection = inspectSnapshotMigration(snapshot, { source: options.source });
+    parseModule(options.targetSource);
+    const targetSourceHash = hashSource(options.targetSource);
+    validateMigrationReconciliation(options.reconciliation, inspection.checkpointDigest, inspection.calls);
+    const state = encodeReplayData(deepCopyToSandbox(options.state));
+    const previous = snapshot.migration;
+    const migration = {
+        version: 1,
+        state,
+        history: [
+            ...structuredClone(previous?.history ?? []),
+            {
+                sourceHash: inspection.sourceHash,
+                targetSourceHash,
+                executionSemantics: inspection.executionSemantics,
+                replay: { version: 1, calls: inspection.calls },
+                reconciliation: structuredClone(options.reconciliation)
+            }
+        ]
+    };
+    validateSnapshotMigration(migration, targetSourceHash);
+    return {
+        version: DUMP_FORMAT_VERSION,
+        executionSemantics: EXECUTION_SEMANTICS,
+        sourceHash: targetSourceHash,
+        bindings: {},
+        replay: { version: 1, calls: [] },
+        migration
+    };
+}
+function canonicalData(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalData).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalData(value[key])}`)
+            .join(",")}}`;
+    return JSON.stringify(value);
+}

package/packages/safejs/dist/migration-file.d.ts

@@ -0,0 +1,55 @@
+export type SnapshotMigrationFileOptions = {
+    snapshotPath: string;
+    sourcePath: string;
+    targetSourcePath?: string;
+    planPath?: string;
+    outputPath?: string;
+    inspect?: boolean;
+    dryRun?: boolean;
+    cwd?: string;
+};
+export declare function migrateSnapshotFile(options: SnapshotMigrationFileOptions): Promise<{
+    inspection: {
+        checkpointDigest: string;
+        sourceHash: string;
+        executionSemantics: string;
+        calls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+        unresolvedCalls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+    };
+    outputPath?: undefined;
+    dryRun?: undefined;
+} | {
+    inspection: {
+        checkpointDigest: string;
+        sourceHash: string;
+        executionSemantics: string;
+        calls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+        unresolvedCalls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+    };
+    outputPath: string | undefined;
+    dryRun: boolean;
+}>;

package/packages/safejs/dist/migration-file.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { link, open, readFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import { hasOwnErrorCode } from "./error-codes.js";
+import { inspectSnapshotMigration, migrateSnapshot } from "./migrate.js";
+import { serializeSafeJSSnapshot } from "./snapshot/dump-format.js";
+export async function migrateSnapshotFile(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const resolvePath = (value, label) => {
+        if (typeof value !== "string" || value.trim().length === 0)
+            throw new TypeError(`Migration requires ${label}.`);
+        return path.resolve(cwd, value);
+    };
+    const snapshotPath = resolvePath(options.snapshotPath, "a snapshot path");
+    const sourcePath = resolvePath(options.sourcePath, "--from <original.ajs>");
+    if (options.inspect &&
+        [options.targetSourcePath, options.planPath, options.outputPath].some((value) => value !== undefined))
+        throw new TypeError("Migration --inspect cannot be combined with --to, --plan, or --output.");
+    const outputPath = options.inspect
+        ? undefined
+        : resolvePath(options.outputPath, "--output <new-checkpoint.json>");
+    const targetSourcePath = options.inspect
+        ? undefined
+        : resolvePath(options.targetSourcePath, "--to <continuation.ajs>");
+    const planPath = options.inspect
+        ? undefined
+        : resolvePath(options.planPath, "--plan <migration.json>");
+    for (const filepath of [sourcePath, targetSourcePath]) {
+        if (filepath !== undefined && ![".ajs", ".safejs"].includes(path.extname(filepath)))
+            throw new TypeError("Migration source paths must name executable .ajs or .safejs files, not harness Markdown.");
+    }
+    const snapshot = JSON.parse(await readFile(snapshotPath, "utf8"));
+    const source = await readFile(sourcePath, "utf8");
+    const inspection = inspectSnapshotMigration(snapshot, { source });
+    if (options.inspect)
+        return { inspection };
+    const plan = JSON.parse(await readFile(planPath, "utf8"));
+    if (plan === null ||
+        typeof plan !== "object" ||
+        !Object.hasOwn(plan, "state") ||
+        !Object.hasOwn(plan, "reconciliation"))
+        throw new TypeError("Migration plan requires explicit state and reconciliation fields.");
+    const targetSource = await readFile(targetSourcePath, "utf8");
+    const migrated = migrateSnapshot(snapshot, {
+        source,
+        targetSource,
+        state: plan.state,
+        reconciliation: plan.reconciliation
+    });
+    const contents = serializeSafeJSSnapshot(migrated);
+    if (!options.dryRun) {
+        const temporaryPath = path.join(path.dirname(outputPath), `.safejs-migration-${randomUUID()}.tmp`);
+        let created = false;
+        try {
+            const handle = await open(temporaryPath, "wx", 0o600);
+            created = true;
+            try {
+                await handle.writeFile(contents, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            try {
+                await link(temporaryPath, outputPath);
+            }
+            catch (error) {
+                if (hasOwnErrorCode(error, "EEXIST"))
+                    throw Object.assign(new Error(`Migration output already exists: ${JSON.stringify(outputPath)}. Choose a new output path; existing files are never overwritten.`, { cause: error }), { code: "EEXIST" });
+                throw error;
+            }
+        }
+        finally {
+            if (created)
+                await unlink(temporaryPath);
+        }
+    }
+    return { inspection, outputPath, dryRun: options.dryRun === true };
+}

package/packages/safejs/dist/restore.d.ts

@@ -1,6 +1,8 @@
+import { type SnapshotMigration } from "./snapshot/migration.js";
 export type SafeJSSnapshot = {
     version?: number;
     sourceHash: string;
+    migration?: SnapshotMigration;
     clock?: {
         next: number;
     };

package/packages/safejs/dist/restore.js

@@ -3,6 +3,7 @@ import { replaceErrorStack } from "./error/shape.js";
 import { SnapshotValidationError, validateDumpEnvelope } from "./snapshot/validation.js";
 import { EXECUTION_SEMANTICS } from "./snapshot/dump-format.js";
 import { assertSnapshotInactive } from "./interp/running-state.js";
+import { validateSnapshotMigration } from "./snapshot/migration.js";
 export class SnapshotMismatchError extends Error {
     actualHash;
     expectedHash;
@@ -17,6 +18,7 @@ export class SnapshotMismatchError extends Error {
 export function restore(snapshot, options) {
     assertSnapshotInactive(snapshot);
     validateDumpEnvelope(snapshot);
+    validateSnapshotMigration(snapshot.migration, snapshot.sourceHash);
     if (snapshot.executionSemantics !== EXECUTION_SEMANTICS &&
         (snapshot.executionSemantics !== undefined ||
             snapshot.promiseReplay !== undefined ||