narraeon 0.7.4 → 0.7.6

package/dist/node/protocol/v1.js

@@ -353,6 +353,10 @@ function validateRequestFields(request) {
     if (request.type === "play.timeline.detail" &&
         (!Number.isSafeInteger(request.eventId) || Number(request.eventId) < 1))
         throw new V1ProtocolError("invalid_request", "play.timeline.detail.eventId is invalid");
+    if ("turnNote" in request &&
+        request.turnNote !== undefined &&
+        typeof request.turnNote !== "string")
+        throw new V1ProtocolError("invalid_request", "turnNote is invalid");
     if (request.type === "play.chain.revise-player" &&
         request.continuation !== "continue_context" &&
         request.continuation !== "fresh_context")

package/dist/node/runtime/V1Runtime.js

@@ -197,7 +197,7 @@ export class V1Runtime {
         const chain = result;
         if (chain?.status !== "interrupted" ||
             typeof chain.lastFailure !== "string" ||
-            chain.events?.at(-1)?.kind === "cancellation")
+            chain.lastCancelled === true)
             return;
         await this.#errorLog.recordPlayInterruption(request, {
             message: chain.lastFailure,
@@ -458,6 +458,9 @@ export class V1Runtime {
                     }), `content:${request.packageId}.message.genesis.narrator`, "content-preview"),
                     playerInputPlacement: "append",
                     playerInput: request.playerInput,
+                    ...(request.turnNote === undefined
+                        ? {}
+                        : { turnNote: request.turnNote }),
                     modelBinding: modelHost.binding(),
                 }, playPreset);
                 const tools = structuredClone(preview.compilation.toolUniverse ?? preview.compilation.tools);
@@ -669,6 +672,9 @@ export class V1Runtime {
                     eventId: request.eventId,
                     replacementExchangeId: request.replacementExchangeId,
                     replacementText: request.replacementText,
+                    ...(request.turnNote === undefined
+                        ? {}
+                        : { turnNote: request.turnNote }),
                 };
                 const result = await playCall(async () => {
                     await this.#worlds.assertWorldRevisionUnlocked(request.worldId);
@@ -695,6 +701,9 @@ export class V1Runtime {
                     chainId: request.chainId,
                     exchangeId: request.exchangeId,
                     playerText: request.playerText,
+                    ...(request.turnNote === undefined
+                        ? {}
+                        : { turnNote: request.turnNote }),
                     hostBinding,
                     playPreset,
                     modelBinding,
@@ -712,6 +721,9 @@ export class V1Runtime {
                         chainId: request.chainId,
                         exchangeId: request.exchangeId,
                         playerText: request.playerText,
+                        ...(request.turnNote === undefined
+                            ? {}
+                            : { turnNote: request.turnNote }),
                         modelHost: await this.#modelHost(),
                         resolvePrompt: () => this.#continuousBinding(),
                         ...(playCallChainObserver === undefined

package/dist/node/runtime/content/CurrentTreeContentLibrary.js

@@ -1,6 +1,5 @@
 import { PackageScriptPermissions } from "../extension/PackageScriptPermissions.js";
 import { createHash, randomUUID } from "node:crypto";
-import { readFileSync, unlinkSync } from "node:fs";
 import { open, mkdir, readFile, readdir, rename, rm, stat, unlink, } from "node:fs/promises";
 import { linkExclusive } from "../FileNativeExclusiveLink.js";
 import { basename, dirname, isAbsolute, join, posix, win32 } from "node:path";
@@ -54,15 +53,16 @@ export class InvalidContentTreeError extends Error {
  * single replaceable envelope so saving cannot expose half of two file sets.
  */
 export class CurrentTreeContentLibrary {
-    #locksRoot;
+    #legacyLocksRoot;
     #packagesRoot;
     #stagingRoot;
     #limits;
     #beforePackagePublish;
     #beforeCurrentTreeReplace;
     #mutationTail = Promise.resolve();
+    #legacyLocksRemoval;
     constructor(dataRoot, options = {}) {
-        this.#locksRoot = join(dataRoot, "content", ".package-locks");
+        this.#legacyLocksRoot = join(dataRoot, "content", ".package-locks");
         this.#packagesRoot = join(dataRoot, "content", "packages");
         this.#stagingRoot = join(dataRoot, "content", ".package-staging");
         this.#limits = normalizeLimits(options.limits);
@@ -272,48 +272,16 @@ export class CurrentTreeContentLibrary {
         });
     }
     async acquireOperationLease(localId, options = {}) {
-        this.#packageRoot(localId);
-        await mkdir(this.#locksRoot, { recursive: true, mode: 0o700 });
-        const lockPath = this.#packageLockPath(localId);
-        const reclaimPath = this.#packageReclaimPath(localId);
-        await clearDeadPackageLockMarker(reclaimPath);
-        if (await pathExists(reclaimPath)) {
-            throw new CurrentTreeContentPackageBusyError();
-        }
-        const marker = createPackageLockMarker();
-        const temporaryPath = join(this.#locksRoot, `.${localId}.${marker.token}.tmp`);
-        let handle;
-        try {
-            handle = await open(temporaryPath, "wx", 0o600);
-            await handle.writeFile(`${JSON.stringify(marker)}\n`, "utf8");
-            await handle.close();
-            handle = undefined;
-            try {
-                await linkExclusive(temporaryPath, lockPath);
-            }
-            catch (error) {
-                if (!isNodeErrorCode(error, "EEXIST"))
-                    throw error;
-                if (options.wait === true) {
-                    await this.#waitForPackageLock(lockPath, reclaimPath, temporaryPath);
-                }
-                else if (!(await this.#tryReplaceDeadPackageLock(lockPath, reclaimPath, temporaryPath))) {
-                    throw new CurrentTreeContentPackageBusyError();
-                }
-            }
-        }
-        catch (error) {
-            await handle?.close().catch(() => undefined);
-            if (error instanceof CurrentTreeContentPackageBusyError)
-                throw error;
-            throw new CurrentTreeContentLibraryError("Unable to acquire the source-package save owner", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        finally {
-            await unlink(temporaryPath).catch(() => undefined);
-        }
+        const packageRoot = this.#packageRoot(localId);
+        await this.#removeLegacyPackageLocks();
+        await acquireInProcessPackageLease(packageRoot, options.wait === true);
         let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            releaseInProcessPackageLease(packageRoot);
+        };
         try {
             const package_ = (await this.#readPackageSnapshot(localId)).package;
             return {
@@ -326,19 +294,25 @@ export class CurrentTreeContentLibrary {
                     assertGameplayModeUnchanged(package_.files, normalized);
                     return this.#replaceNormalizedCurrentTree(localId, package_.title, normalized, options.signal);
                 },
-                release: () => {
-                    if (released)
-                        return;
-                    released = true;
-                    releasePackageOperationLockSync(lockPath, marker.token);
-                },
+                release,
             };
         }
         catch (error) {
-            releasePackageOperationLockSync(lockPath, marker.token);
+            release();
             throw error;
         }
     }
+    /**
+     * Lock files written by versions that leased packages across processes. No
+     * code reads them any more, so the first lease in a library removes them.
+     */
+    #removeLegacyPackageLocks() {
+        this.#legacyLocksRemoval ??= rm(this.#legacyLocksRoot, {
+            recursive: true,
+            force: true,
+        }).catch(() => undefined);
+        return this.#legacyLocksRemoval;
+    }
     async #replaceNormalizedCurrentTree(localId, title, normalized, signal) {
         const packageRoot = this.#packageRoot(localId);
         const temporaryPath = join(packageRoot, `.current-tree-${randomUUID()}.tmp`);
@@ -427,70 +401,6 @@ export class CurrentTreeContentLibrary {
         }
         return join(this.#packagesRoot, localId);
     }
-    #packageLockPath(localId) {
-        return join(this.#locksRoot, `${localId}.mutation`);
-    }
-    #packageReclaimPath(localId) {
-        return join(this.#locksRoot, `${localId}.reclaim`);
-    }
-    async #tryReplaceDeadPackageLock(lockPath, reclaimPath, replacementPath) {
-        const current = await readPackageLockMarker(lockPath);
-        if (current === null || isProcessAlive(current.pid))
-            return false;
-        const reclaim = createPackageLockMarker();
-        const temporaryPath = join(this.#locksRoot, `.reclaim.${reclaim.token}.tmp`);
-        let handle;
-        try {
-            handle = await open(temporaryPath, "wx", 0o600);
-            await handle.writeFile(`${JSON.stringify(reclaim)}\n`, "utf8");
-            await handle.close();
-            handle = undefined;
-            await linkExclusive(temporaryPath, reclaimPath);
-        }
-        catch (error) {
-            await handle?.close().catch(() => undefined);
-            if (isNodeErrorCode(error, "EEXIST"))
-                return false;
-            throw error;
-        }
-        finally {
-            await unlink(temporaryPath).catch(() => undefined);
-        }
-        try {
-            const verified = await readPackageLockMarker(lockPath);
-            if (verified?.token !== current.token || isProcessAlive(current.pid)) {
-                return false;
-            }
-            await unlink(lockPath).catch((error) => {
-                if (!isNodeErrorCode(error, "ENOENT"))
-                    throw error;
-            });
-            await linkExclusive(replacementPath, lockPath);
-            return true;
-        }
-        finally {
-            const owner = await readPackageLockMarker(reclaimPath);
-            if (owner?.token === reclaim.token) {
-                await unlink(reclaimPath).catch(() => undefined);
-            }
-        }
-    }
-    async #waitForPackageLock(lockPath, reclaimPath, replacementPath) {
-        for (let attempt = 0; attempt < 2_000; attempt += 1) {
-            if ((await this.#tryReplaceDeadPackageLock(lockPath, reclaimPath, replacementPath)) ||
-                (await linkExclusive(replacementPath, lockPath)
-                    .then(() => true)
-                    .catch((error) => {
-                    if (isNodeErrorCode(error, "EEXIST"))
-                        return false;
-                    throw error;
-                }))) {
-                return;
-            }
-            await new Promise((resolve) => setTimeout(resolve, 5));
-        }
-        throw new CurrentTreeContentPackageBusyError();
-    }
     async #mutate(operation) {
         const previous = this.#mutationTail;
         let release = () => undefined;
@@ -763,47 +673,47 @@ function isPlainObject(value) {
 function serialize(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
-function createPackageLockMarker() {
-    return { schemaVersion: 1, pid: process.pid, token: randomUUID() };
-}
-async function readPackageLockMarker(path) {
-    try {
-        const value = JSON.parse(await readFile(path, "utf8"));
-        return parsePackageLockMarker(value);
-    }
-    catch {
-        return null;
-    }
-}
-function parsePackageLockMarker(value) {
-    if (isPlainObject(value) &&
-        value.schemaVersion === 1 &&
-        typeof value.pid === "number" &&
-        Number.isSafeInteger(value.pid) &&
-        value.pid > 0 &&
-        typeof value.token === "string" &&
-        /^[0-9a-f-]{36}$/u.test(value.token)) {
-        return { schemaVersion: 1, pid: value.pid, token: value.token };
-    }
-    return null;
-}
-function releasePackageOperationLockSync(path, token) {
-    try {
-        const current = parsePackageLockMarker(JSON.parse(readFileSync(path, "utf8")));
-        if (current?.token === token)
-            unlinkSync(path);
-    }
-    catch (error) {
-        if (!isNodeErrorCode(error, "ENOENT"))
-            throw error;
+const packageLeaseWaitMs = 10_000;
+/**
+ * Package leases held by this process, keyed by package root. A key is present
+ * while its lease is held; its array queues waiters in arrival order, and a
+ * release hands the lease straight to the first of them.
+ */
+const heldPackageLeases = new Map();
+async function acquireInProcessPackageLease(packageRoot, wait) {
+    const queue = heldPackageLeases.get(packageRoot);
+    if (queue === undefined) {
+        heldPackageLeases.set(packageRoot, []);
+        return;
     }
+    if (!wait)
+        throw new CurrentTreeContentPackageBusyError();
+    await new Promise((resolve, reject) => {
+        const waiter = {
+            grant: () => {
+                clearTimeout(timer);
+                resolve();
+            },
+        };
+        const timer = setTimeout(() => {
+            const index = queue.indexOf(waiter);
+            if (index === -1)
+                return;
+            queue.splice(index, 1);
+            reject(new CurrentTreeContentPackageBusyError());
+        }, packageLeaseWaitMs);
+        queue.push(waiter);
+    });
 }
-async function clearDeadPackageLockMarker(path) {
-    const marker = await readPackageLockMarker(path);
-    if ((marker !== null && !isProcessAlive(marker.pid)) ||
-        (marker === null && (await pathExists(path)))) {
-        await unlink(path).catch(() => undefined);
-    }
+function releaseInProcessPackageLease(packageRoot) {
+    const queue = heldPackageLeases.get(packageRoot);
+    if (queue === undefined)
+        return;
+    const next = queue.shift();
+    if (next === undefined)
+        heldPackageLeases.delete(packageRoot);
+    else
+        next.grant();
 }
 async function pathExists(path) {
     try {
@@ -816,15 +726,6 @@ async function pathExists(path) {
         throw error;
     }
 }
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return !isNodeErrorCode(error, "ESRCH");
-    }
-}
 function isNodeErrorCode(error, code) {
     return (typeof error === "object" &&
         error !== null &&

package/dist/node/runtime/content/FileNativeContentTree.js

@@ -14,8 +14,11 @@ export function inspectContentPackageCurrentTree(files, options = {}) {
             layout: "content_package",
             files,
         });
-    if (worldDocumentSnapshot.layout !== "content_package")
-        throw new Error("Content-package inspection accepts only content_package document snapshots");
+    if (worldDocumentSnapshot.layout === "world_state")
+        throw new Error("Authoring inspection accepts only content_package or world_revision document snapshots");
+    const subject = worldDocumentSnapshot.layout === "world_revision"
+        ? "world revision"
+        : "content package";
     const snapshotFiles = worldDocumentSnapshot.files;
     const issues = [];
     const documents = worldDocumentSnapshotDocuments(worldDocumentSnapshot);
@@ -26,11 +29,11 @@ export function inspectContentPackageCurrentTree(files, options = {}) {
     let opening = "missing";
     if (openingFiles.length === 0) {
         if (options.requireOpening !== false)
-            issue(issues, "missing_opening", "opening.md", "The content package is missing a root-level opening.md introduction");
+            issue(issues, "missing_opening", "opening.md", `The ${subject} is missing a root-level opening.md introduction`);
     }
     else if (openingFiles.length > 1) {
         opening = "invalid";
-        issue(issues, "invalid_opening", "opening.md", "A content package may contain only one root-level opening.md file");
+        issue(issues, "invalid_opening", "opening.md", `A ${subject} may contain only one root-level opening.md file`);
     }
     else {
         const openingFile = openingFiles[0];
@@ -48,19 +51,19 @@ export function inspectContentPackageCurrentTree(files, options = {}) {
     for (const file of snapshotFiles) {
         if (/\.json$/iu.test(file.path) && file.path !== gameplayPath) {
             unsupportedPaths.add(file.path);
-            issue(issues, "unsupported_content_file", file.path, "The current content package does not accept manifest, seven-field JSON, schema, record, or revision files");
+            issue(issues, "unsupported_content_file", file.path, `The current ${subject} does not accept manifest, seven-field JSON, schema, record, or revision files`);
         }
     }
     issues.push(...worldDocumentSnapshot.diagnostics
         .filter(({ logicalPath }) => logicalPath === undefined || !unsupportedPaths.has(logicalPath))
-        .map(worldDocumentIssue));
+        .map((diagnostic) => worldDocumentIssue(diagnostic, worldDocumentSnapshot.logicalRoot)));
     const index = documentIndex(documents);
     const frameSource = textFiles.get("control/frame.yaml");
     let worldFrame = "missing";
     let currentSituation = "missing";
     if (frameSource === undefined) {
-        issue(issues, "missing_world_frame", "control/frame.yaml", "The content package is missing its world prompt frame");
-        issue(issues, "missing_current_situation", "control/frame.yaml", "The content package has not bound a current-situation document");
+        issue(issues, "missing_world_frame", "control/frame.yaml", `The ${subject} is missing its world prompt frame`);
+        issue(issues, "missing_current_situation", "control/frame.yaml", `The ${subject} has not bound a current-situation document`);
     }
     else {
         const frame = parseRestrictedYaml("control/frame.yaml", frameSource, issues);
@@ -97,7 +100,7 @@ export function inspectContentPackageCurrentTree(files, options = {}) {
     const playerSource = textFiles.get("control/player-views.yaml");
     let playerView = "missing";
     if (playerSource === undefined) {
-        issue(issues, "missing_player_view", "control/player-views.yaml", "The content package is missing its player-view control file");
+        issue(issues, "missing_player_view", "control/player-views.yaml", `The ${subject} is missing its player-view control file`);
     }
     else {
         const player = parseRestrictedYaml("control/player-views.yaml", playerSource, issues);
@@ -218,10 +221,10 @@ function contentDocument(document) {
         codec: document.codec,
     };
 }
-function worldDocumentIssue(diagnostic) {
+function worldDocumentIssue(diagnostic, root) {
     return {
         code: contentIssueCode(diagnostic),
-        path: diagnostic.logicalPath ?? "world",
+        path: diagnostic.logicalPath ?? root,
         message: diagnostic.code === "document_reference_invalid"
             ? "An explicit $ref points to a missing document, or the target identity is not unique in the snapshot"
             : diagnostic.message,
@@ -430,9 +433,9 @@ function validateFrameContext(value, index, snapshot, issues) {
         }
         if (entry.slot.kind === "catalog" &&
             entry.slot.required !== false &&
-            catalogDocuments(entry.slot.directory, index.documents(), "world").length === 0) {
+            catalogDocuments(entry.slot.directory, index.documents(), snapshot.logicalRoot).length === 0) {
             const directory = entry.slot.directory;
-            issue(issues, "invalid_world_frame", "control/frame.yaml", `Required catalog ${directory} has no associated documents; it matches only direct children named world/${directory}/<file>.yaml, .yml, or .md, and dots in file names do not create directories`);
+            issue(issues, "invalid_world_frame", "control/frame.yaml", `Required catalog ${directory} has no associated documents; it matches only direct children named ${snapshot.logicalRoot}/${directory}/<file>.yaml, .yml, or .md, and dots in file names do not create directories`);
             continue;
         }
         kinds.push(entry.slot.kind);

package/dist/node/runtime/model/ToolArgumentCoercion.js

@@ -0,0 +1,138 @@
+/** Root arguments are depth 0; parsing and descent stop after two levels. */
+const maxCoercionDepth = 2;
+export function coerceToolArguments(schema, args) {
+    const coerced = [];
+    const value = coerceValue(schema, args, "", 0, coerced);
+    return { arguments: value, coerced };
+}
+/**
+ * Renders the Runtime note appended to a tool result whose arguments were
+ * parsed. It tells the model its arguments were repaired, so the next call
+ * can send native JSON values.
+ */
+export function renderCoercionNote(paths, locale) {
+    const names = paths.map((path) => `"${path}"`).join(", ");
+    return locale === "zh-CN"
+        ? `Runtime 说明：以下参数以 JSON 字符串到达，本次已解析后执行：${names}。请以 JSON 数组或对象的原生值发送，不要用字符串。`
+        : `Runtime note: these arguments arrived as JSON strings and were parsed for this call: ${names}. Send array and object arguments as native JSON values, not strings.`;
+}
+function coerceValue(schema, value, path, depth, coerced) {
+    const type = definiteType(schema);
+    let current = value;
+    if ((type === "array" || type === "object") &&
+        typeof current === "string" &&
+        depth > 0 &&
+        depth <= maxCoercionDepth) {
+        const parsed = parseJson(current);
+        if (matchesType(type, parsed)) {
+            current = parsed;
+            coerced.push(path);
+        }
+    }
+    if (depth >= maxCoercionDepth)
+        return current;
+    if (type === "array" && isArray(current)) {
+        const items = itemsSchema(schema);
+        if (items === undefined)
+            return current;
+        let next = current;
+        current.forEach((element, index) => {
+            const repaired = coerceValue(items, element, `${path}[${index}]`, depth + 1, coerced);
+            if (repaired !== element) {
+                if (next === current)
+                    next = [...current];
+                next[index] = repaired;
+            }
+        });
+        return next;
+    }
+    if (type === "object" && isRecord(current)) {
+        let next = current;
+        for (const key of Object.keys(current)) {
+            const property = propertySchema(schema, key);
+            if (property === undefined)
+                continue;
+            const repaired = coerceValue(property, current[key], path === "" ? key : `${path}.${key}`, depth + 1, coerced);
+            if (repaired !== current[key]) {
+                if (next === current)
+                    next = { ...current };
+                next[key] = repaired;
+            }
+        }
+        return next;
+    }
+    return current;
+}
+/** The single type a schema position admits, or undefined when it is not definite. */
+function definiteType(schema) {
+    if (!isRecord(schema))
+        return undefined;
+    if (schema.type !== undefined) {
+        if (typeof schema.type === "string")
+            return schema.type;
+        if (Array.isArray(schema.type) &&
+            schema.type.length === 1 &&
+            typeof schema.type[0] === "string")
+            return schema.type[0];
+        return undefined;
+    }
+    const branches = Array.isArray(schema.oneOf)
+        ? schema.oneOf
+        : Array.isArray(schema.anyOf)
+            ? schema.anyOf
+            : undefined;
+    if (branches === undefined || branches.length === 0)
+        return undefined;
+    const types = branches.map(definiteType);
+    const first = types[0];
+    return first !== undefined && types.every((type) => type === first)
+        ? first
+        : undefined;
+}
+function itemsSchema(schema) {
+    return isRecord(schema.items) && !Array.isArray(schema.items)
+        ? schema.items
+        : undefined;
+}
+/**
+ * A property schema is taken directly from `properties`, or from oneOf/anyOf
+ * branches only when every branch that declares the key declares it the same.
+ */
+function propertySchema(schema, key) {
+    if (isRecord(schema.properties) && isRecord(schema.properties[key]))
+        return schema.properties[key];
+    const branches = Array.isArray(schema.oneOf)
+        ? schema.oneOf
+        : Array.isArray(schema.anyOf)
+            ? schema.anyOf
+            : [];
+    const declared = branches
+        .map((branch) => isRecord(branch) && isRecord(branch.properties)
+        ? branch.properties[key]
+        : undefined)
+        .filter((property) => property !== undefined);
+    if (declared.length === 0)
+        return undefined;
+    const serialized = declared.map((property) => JSON.stringify(property));
+    return serialized.every((text) => text === serialized[0]) &&
+        isRecord(declared[0])
+        ? declared[0]
+        : undefined;
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function matchesType(type, value) {
+    return type === "array" ? Array.isArray(value) : isRecord(value);
+}
+function isArray(value) {
+    return Array.isArray(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/node/runtime/play/FileNativePlayAdvanceStore.js

@@ -2,7 +2,6 @@ import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { isDeepStrictEqual } from "node:util";
 /** Written last by the released-record cleanup (ADR-0034); its absence means "not yet run". */
 const LAYOUT_MARKER = "play-advance-layout.json";
 /**
@@ -19,15 +18,16 @@ export class FileNativePlayAdvanceStore {
     constructor(dataRoot) {
         this.#worldsRoot = join(resolve(dataRoot), "worlds-file-native");
     }
-    async begin(base) {
-        assertBase(base);
-        const current = await this.readCurrent(base.worldId, base.chainId);
+    async begin(advance) {
+        assertBase(advance);
+        const marker = persistedAdvance(advance);
+        const current = await this.readCurrent(marker.worldId, marker.chainId);
         if (current !== null) {
-            if (!sameAdvanceBase(current, base))
+            if (!sameAdvance(current, marker))
                 throw new Error("Another play advance is still awaiting settlement");
             return;
         }
-        await publishJson(this.#markerPath(base.worldId, base.chainId), base);
+        await publishJson(this.#markerPath(marker.worldId, marker.chainId), marker);
     }
     async readCurrent(worldId, chainId) {
         assertIdentity(worldId, "World ID");
@@ -40,13 +40,15 @@ export class FileNativePlayAdvanceStore {
             throw new Error("Play advance marker belongs to another context");
         return value;
     }
-    async markSettled(base) {
-        const current = await this.readCurrent(base.worldId, base.chainId);
+    async markSettled(advance) {
+        const current = await this.readCurrent(advance.worldId, advance.chainId);
         if (current === null)
             return;
-        if (!sameAdvanceBase(current, base))
+        if (!sameAdvance(current, advance))
             throw new Error("Play advance is no longer current");
-        await rm(this.#markerPath(base.worldId, base.chainId), { force: true });
+        await rm(this.#markerPath(advance.worldId, advance.chainId), {
+            force: true,
+        });
     }
     /** Remove the in-progress marker and all advance records of a discarded chain. */
     async discardChain(worldId, chainId) {
@@ -103,12 +105,25 @@ export class FileNativePlayAdvanceStore {
         return join(this.#worldsRoot, worldId, "runtime", "play-advances", digest(chainId), "in-progress.json");
     }
 }
-function sameAdvanceBase(left, right) {
-    const { createdAt: leftCreatedAt, ...leftIdentity } = left;
-    const { createdAt: rightCreatedAt, ...rightIdentity } = right;
-    void leftCreatedAt;
-    void rightCreatedAt;
-    return isDeepStrictEqual(leftIdentity, rightIdentity);
+/**
+ * Whether two advances are the same one. The marker is confirmed by these
+ * identity fields alone; the frozen request is never compared (ADR-0044).
+ */
+function sameAdvance(left, right) {
+    return (left.advanceKind === right.advanceKind &&
+        left.worldId === right.worldId &&
+        left.chainId === right.chainId &&
+        left.advanceId === right.advanceId &&
+        left.operationId === right.operationId &&
+        left.eventId === right.eventId);
+}
+/** The marker form of an advance: a player advance's frozen request stays in memory. */
+function persistedAdvance(advance) {
+    if (!("nextRequest" in advance))
+        return advance;
+    const { nextRequest: _nextRequest, ...marker } = advance;
+    void _nextRequest;
+    return marker;
 }
 function assertBase(value) {
     if (!isRecord(value) ||
@@ -137,9 +152,10 @@ function assertBase(value) {
             !Number.isSafeInteger(value.transcriptStart) ||
             Number(value.transcriptStart) < 0 ||
             !Number.isSafeInteger(value.exchange) ||
-            Number(value.exchange) < 1 ||
-            !isRecord(value.nextRequest))
+            Number(value.exchange) < 1)
             throw new Error("Player advance has an invalid shape");
+        // A marker released before ADR-0044 may still carry `nextRequest`. Recovery
+        // never reads it, so the field is tolerated and not validated.
     }
     else if (!Number.isSafeInteger(value.exchange) ||
         Number(value.exchange) < 0 ||