poe-code 10.0.3 → 10.0.4

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 ||

package/packages/safejs/dist/run.js

@@ -28,7 +28,7 @@ import { DUMP_FORMAT_VERSION, EXECUTION_SEMANTICS } from "./snapshot/dump-format
 import { createSnapshotScheduler } from "./snapshot/scheduler.js";
 import { UnsnapshotableValueError } from "./snapshot/serialize.js";
 import { prepareReplayInputs } from "./snapshot/replay-inputs.js";
-import { MissingReplayCapabilityError } from "./snapshot/replay-data.js";
+import { decodeReplayData, MissingReplayCapabilityError } from "./snapshot/replay-data.js";
 export class UnhandledRejectionError extends Error {
     reason;
     constructor(reason, span) {
@@ -122,6 +122,17 @@ export function run(source, options = {}) {
                     }),
                     ...createRegexGlobals()
                 };
+                const importMeta = deepCopyToSandbox(options.importMeta ?? {});
+                if (restoredSnapshot?.migration !== undefined) {
+                    if (Object.hasOwn(importMeta, "migration"))
+                        throw new TypeError("import.meta.migration is reserved for migrated checkpoint state.");
+                    Object.defineProperty(importMeta, "migration", {
+                        value: decodeReplayData(restoredSnapshot.migration.state),
+                        enumerable: true,
+                        configurable: true,
+                        writable: true
+                    });
+                }
                 const initialInputs = prepareReplayInputs({
                     bindings: callerBindings,
                     imports: resolveModuleImports(module, options.modules, {
@@ -133,7 +144,7 @@ export function run(source, options = {}) {
                     entryPointArgs: options.entryPointArgs === undefined
                         ? undefined
                         : deepCopyToSandbox([...options.entryPointArgs]),
-                    importMeta: deepCopyToSandbox(options.importMeta ?? {})
+                    importMeta
                 }, restoredSnapshot?.initialInputs, (promise, id) => {
                     if (promise !== undefined)
                         observeSandboxPromise(promise);
@@ -173,6 +184,7 @@ export function run(source, options = {}) {
                 });
                 snapshotScheduler = activeSnapshotScheduler;
                 createFailureSnapshot = () => createRunSnapshot({
+                    migration: restoredSnapshot?.migration,
                     bindings: executionScope.snapshot().bindings,
                     clock: options.clock,
                     hostCalls: hostCalls.snapshot(),
@@ -198,6 +210,7 @@ export function run(source, options = {}) {
                             }
                             const interpreterSnapshot = yieldPoint.snapshot();
                             snapshot = createRunSnapshot({
+                                migration: restoredSnapshot?.migration,
                                 bindings: interpreterSnapshot.bindings,
                                 clock: options.clock,
                                 hostCalls: hostCalls.snapshot(),
@@ -241,6 +254,7 @@ export function run(source, options = {}) {
                                 }
                                 const interpreterSnapshot = yieldPoint.snapshot();
                                 snapshot = createRunSnapshot({
+                                    migration: restoredSnapshot?.migration,
                                     bindings: interpreterSnapshot.bindings,
                                     clock: options.clock,
                                     hostCalls: hostCalls.snapshot(),
@@ -278,6 +292,7 @@ export function run(source, options = {}) {
                     replayError = error.message;
                 }
                 const snapshot = createRunSnapshot({
+                    migration: restoredSnapshot?.migration,
                     bindings: executionScope.snapshot().bindings,
                     clock: options.clock,
                     hostCalls: hostCalls.snapshot(),
@@ -441,6 +456,7 @@ function createRunSnapshot(input) {
         version: DUMP_FORMAT_VERSION,
         executionSemantics: EXECUTION_SEMANTICS,
         sourceHash: input.sourceHash,
+        ...(input.migration === undefined ? {} : { migration: structuredClone(input.migration) }),
         bindings: input.bindings,
         clock: input.clock?.snapshot(),
         ...(input.hostCalls === undefined || input.hostCalls.length === 0

package/packages/safejs/dist/snapshot/migration.d.ts

@@ -0,0 +1,34 @@
+import { type HostCallReplay } from "../interp/host-call.js";
+import { type ReplayData } from "./replay-data.js";
+export type SnapshotMigrationResolution = {
+    callId: string;
+    disposition: "not-performed";
+} | {
+    callId: string;
+    disposition: "fulfilled";
+    value: unknown;
+} | {
+    callId: string;
+    disposition: "rejected";
+    reason: unknown;
+};
+export type SnapshotMigrationReconciliation = {
+    checkpointDigest: string;
+    quiescent: boolean;
+    calls: SnapshotMigrationResolution[];
+};
+export type SnapshotMigration = {
+    version: 1;
+    state: ReplayData;
+    history: Array<{
+        sourceHash: string;
+        targetSourceHash: string;
+        executionSemantics: string;
+        replay: HostCallReplay;
+        reconciliation: SnapshotMigrationReconciliation;
+    }>;
+};
+export declare function validateMigrationSemantics(value: unknown): asserts value is string;
+export declare function validateMigrationJournal(sourceHash: string, replay: unknown, hostCalls?: unknown): HostCallReplay;
+export declare function validateMigrationReconciliation(value: unknown, checkpointDigest: string, calls: HostCallReplay["calls"]): asserts value is SnapshotMigrationReconciliation;
+export declare function validateSnapshotMigration(value: unknown, sourceHash: string): SnapshotMigration | undefined;

package/packages/safejs/dist/snapshot/migration.js

@@ -0,0 +1,92 @@
+import { HostCallJournal } from "../interp/host-call.js";
+import { decodeReplayData } from "./replay-data.js";
+import { validateSnapshotData } from "./validation.js";
+export function validateMigrationSemantics(value) {
+    if (!["jobs-v1", "jobs-v2", "jobs-v3", "jobs-v4", "jobs-v5"].includes(value))
+        throw new TypeError("Migration requires a supported execution-semantics marker (jobs-v1 through jobs-v5).");
+}
+export function validateMigrationJournal(sourceHash, replay, hostCalls = []) {
+    if (replay === undefined)
+        throw new TypeError("Migration requires a complete host replay journal.");
+    if (!Array.isArray(hostCalls))
+        throw new TypeError("Invalid migration hostCalls.");
+    const journal = new HostCallJournal(sourceHash, hostCalls, undefined, replay);
+    try {
+        const restored = journal.snapshotReplay();
+        for (const call of restored.calls) {
+            if (["created", "running"].includes(call.lifecycle) && call.outcome !== undefined)
+                throw new TypeError("Unresolved migration calls cannot contain a recorded outcome.");
+            for (const callback of call.callbacks ?? []) {
+                if (!call.functions?.includes(callback.id))
+                    throw new TypeError("Migration callback has no registered source function.");
+            }
+        }
+        return restored;
+    }
+    finally {
+        journal.dispose();
+    }
+}
+export function validateMigrationReconciliation(value, checkpointDigest, calls) {
+    validateSnapshotData(value);
+    const receipt = value;
+    if (receipt === null ||
+        typeof receipt !== "object" ||
+        receipt.checkpointDigest !== checkpointDigest ||
+        !isCheckpointDigest(receipt.checkpointDigest))
+        throw new TypeError("Migration reconciliation must identify this exact checkpoint digest.");
+    if (receipt.quiescent !== true)
+        throw new TypeError("Migration requires explicit host confirmation that execution, operations, and callbacks are quiescent.");
+    if (!Array.isArray(receipt.calls))
+        throw new TypeError("Migration reconciliation calls must be an array.");
+    const pending = new Map(calls
+        .filter((call) => !["settled", "consumed"].includes(call.lifecycle))
+        .map((call) => [call.id, call]));
+    for (const resolution of receipt.calls) {
+        if (resolution === null || typeof resolution !== "object" || !pending.has(resolution.callId))
+            throw new TypeError("Migration contains an unknown or duplicate call resolution.");
+        if (!["not-performed", "fulfilled", "rejected"].includes(resolution.disposition) ||
+            (resolution.disposition === "fulfilled" && !Object.hasOwn(resolution, "value")) ||
+            (resolution.disposition === "rejected" && !Object.hasOwn(resolution, "reason")))
+            throw new TypeError("Migration call resolution requires a reconciled outcome or confirmed non-performance.");
+        pending.delete(resolution.callId);
+    }
+    if (pending.size > 0)
+        throw new TypeError(`Migration requires external reconciliation for: ${[...pending.keys()].join(", ")}`);
+}
+export function validateSnapshotMigration(value, sourceHash) {
+    if (value === undefined)
+        return undefined;
+    validateSnapshotData(value);
+    const migration = value;
+    if (migration === null ||
+        typeof migration !== "object" ||
+        migration.version !== 1 ||
+        !Array.isArray(migration.history) ||
+        migration.history.length === 0)
+        throw new TypeError("Invalid snapshot migration history.");
+    decodeReplayData(migration.state);
+    let previousTarget;
+    for (const entry of migration.history) {
+        if (entry === null ||
+            typeof entry !== "object" ||
+            typeof entry.sourceHash !== "string" ||
+            entry.sourceHash.length === 0 ||
+            typeof entry.targetSourceHash !== "string" ||
+            entry.targetSourceHash.length === 0 ||
+            (previousTarget !== undefined && previousTarget !== entry.sourceHash))
+            throw new TypeError("Invalid snapshot migration ancestry.");
+        validateMigrationSemantics(entry.executionSemantics);
+        const replay = validateMigrationJournal(entry.sourceHash, entry.replay);
+        validateMigrationReconciliation(entry.reconciliation, entry.reconciliation?.checkpointDigest, replay.calls);
+        previousTarget = entry.targetSourceHash;
+    }
+    if (previousTarget !== sourceHash)
+        throw new TypeError("Migration ancestry does not match the target source.");
+    return migration;
+}
+function isCheckpointDigest(value) {
+    return (typeof value === "string" &&
+        value.length === 64 &&
+        [...value].every((character) => "0123456789abcdef".includes(character)));
+}