narraeon 0.4.0 → 0.5.1

package/dist/node/runtime/world/WorldDocumentStore.js

@@ -3,11 +3,9 @@ import { isMap, isScalar, isSeq, parseDocument, stringify, } from "yaml";
 const documentIdPattern = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/u;
 const shortRefPattern = /^[a-z][a-z0-9-]*$/u;
 const base64UrlPattern = /^[A-Za-z0-9_-]+$/u;
-const maxWorldDocumentBytes = 4 * 1024 * 1024;
 const maxYamlDepth = 64;
 const maxYamlNodes = 100_000;
 const maxLiteralSearchMatches = 10_000;
-const maxSelectedNodeBytes = 1024 * 1024;
 export class WorldDocumentStore {
     static open(input) {
         return new WorldDocumentStore(input.layout, input.files);
@@ -276,6 +274,7 @@ export class WorldDocumentStore {
                             title: source.metadata.title,
                             summary: source.metadata.summary,
                             aliases: [...source.metadata.aliases],
+                            ...(previous?.retired === true ? { retired: true } : {}),
                         },
                     };
                     let contents;
@@ -314,6 +313,23 @@ export class WorldDocumentStore {
                     }
                     touchedPath = writePath;
                 }
+                else if (command.kind === "retire") {
+                    if (this.layout !== "world_state" ||
+                        !hasOnlyKeys(command, ["kind", "document", "retired"]) ||
+                        typeof command.retired !== "boolean")
+                        return this.#revisionFailure(commandIndex, {
+                            code: "query_invalid",
+                            message: "A retire command requires a world-state target and boolean retired value",
+                        });
+                    const target = this.#resolveRevisionTarget(current, working, command.document);
+                    if ("diagnostics" in target)
+                        return this.#revisionFailure(commandIndex, target.diagnostics);
+                    if (target.entry.descriptor.retired !== command.retired)
+                        target.working.file.contents = setDocumentRetired(target.working.file.contents, target.entry.descriptor.codec, command.retired);
+                    delete target.working.file.encoding;
+                    target.working.lastCommandIndex = commandIndex;
+                    touchedPath = target.working.file.path;
+                }
                 else if (command.kind === "patch") {
                     if (!hasOnlyKeys(command, ["kind", "document", "edits"]) ||
                         !Array.isArray(command.edits) ||
@@ -327,7 +343,7 @@ export class WorldDocumentStore {
                     if ("diagnostics" in target)
                         return this.#revisionFailure(commandIndex, target.diagnostics);
                     if (target.entry.codec === "markdown") {
-                        const patched = patchRevisionMarkdown(target.working.file.contents, command.edits);
+                        const patched = patchRevisionMarkdown(target.working.file.contents, command.edits, target.entry.descriptor);
                         if ("diagnostics" in patched)
                             return this.#revisionFailure(commandIndex, patched.diagnostics.map((problem) => ({
                                 ...problem,
@@ -342,6 +358,11 @@ export class WorldDocumentStore {
                             uniqueKeys: true,
                             strict: true,
                         });
+                        let metadata = {
+                            title: target.entry.descriptor.title,
+                            summary: target.entry.descriptor.summary,
+                            aliases: [...target.entry.descriptor.aliases],
+                        };
                         for (const edit of command.edits) {
                             if (!isRecord(edit) || typeof edit.op !== "string")
                                 return this.#revisionFailure(commandIndex, {
@@ -358,16 +379,18 @@ export class WorldDocumentStore {
                                         documentId: target.entry.descriptor.documentId,
                                         message: "set_metadata accepts only op, title, summary, and aliases",
                                     });
-                                if (!validDocumentMetadata(edit))
+                                const resolved = resolveDocumentMetadataRevision(metadata, edit);
+                                if ("problems" in resolved)
                                     return this.#revisionFailure(commandIndex, {
                                         code: "document_header_invalid",
                                         logicalPath: target.entry.file.path,
                                         documentId: target.entry.descriptor.documentId,
-                                        message: `set_metadata arguments are invalid: ${documentMetadataProblems(edit).join("; ")}`,
+                                        message: `set_metadata arguments are invalid: ${resolved.problems.join("; ")}`,
                                     });
-                                document.setIn(["$document", "title"], edit.title);
-                                document.setIn(["$document", "summary"], edit.summary);
-                                document.setIn(["$document", "aliases"], [...edit.aliases]);
+                                metadata = resolved.metadata;
+                                document.setIn(["$document", "title"], metadata.title);
+                                document.setIn(["$document", "summary"], metadata.summary);
+                                document.setIn(["$document", "aliases"], [...metadata.aliases]);
                                 continue;
                             }
                             if (!["add", "replace", "append", "remove"].includes(edit.op) ||
@@ -820,7 +843,14 @@ export class WorldDocumentStore {
         ]);
     }
     #catalog(request) {
-        if (!hasOnlyKeys(request, ["kind", "directory", "limit", "cursor"]))
+        if (!hasOnlyKeys(request, [
+            "kind",
+            "directory",
+            "includeRetired",
+            "declaredDirectories",
+            "limit",
+            "cursor",
+        ]))
             return this.#failure("catalog", request, [
                 diagnostic({
                     code: "query_invalid",
@@ -828,20 +858,28 @@ export class WorldDocumentStore {
                 }),
             ]);
         const directory = request.directory ?? "";
+        const includeRetired = request.includeRetired ?? true;
+        const declaredDirectories = request.declaredDirectories ?? [];
         const limit = request.limit ?? 20;
         if ((directory !== "" && !validRelativePath(directory)) ||
+            typeof includeRetired !== "boolean" ||
+            !validDeclaredDirectories(declaredDirectories) ||
             !Number.isInteger(limit) ||
             limit < 1 ||
             limit > 100)
             return this.#failure("catalog", request, [
                 diagnostic({
                     code: "query_invalid",
-                    message: "Catalog directory must be within the layout root, and limit must be 1 to 100",
+                    message: "Catalog directories must be within the layout root, and limit must be 1 to 100",
                 }),
             ]);
+        const normalizedDeclaredDirectories = [
+            ...new Set(declaredDirectories),
+        ].sort((left, right) => left.localeCompare(right));
         const relativePrefix = directory === "" ? "" : `${directory}/`;
         const prefix = `${this.logicalRoot}/${relativePrefix}`;
         const entries = new Map();
+        let excludedDocuments = 0;
         for (const entry of this.#entries) {
             if (!entry.file.path.startsWith(prefix))
                 continue;
@@ -855,6 +893,10 @@ export class WorldDocumentStore {
                 }));
             }
             else {
+                if (entry.descriptor?.retired === true && !includeRetired) {
+                    excludedDocuments += 1;
+                    continue;
+                }
                 entries.set(`document:${relative}`, freeze({
                     kind: "document",
                     logicalPath: entry.file.path,
@@ -868,12 +910,27 @@ export class WorldDocumentStore {
                 }));
             }
         }
+        for (const declaredDirectory of normalizedDeclaredDirectories) {
+            if (!declaredDirectory.startsWith(relativePrefix))
+                continue;
+            const relative = declaredDirectory.slice(relativePrefix.length);
+            if (relative === "")
+                continue;
+            const slash = relative.indexOf("/");
+            const child = slash < 0 ? relative : relative.slice(0, slash);
+            entries.set(`directory:${child}`, freeze({
+                kind: "directory",
+                logicalPath: `${prefix}${child}`,
+            }));
+        }
         const ordered = [...entries.values()].sort((left, right) => left.logicalPath.localeCompare(right.logicalPath));
         const cursorScope = JSON.stringify({
             kind: "catalog",
             layout: this.layout,
             logicalRoot: this.logicalRoot,
             directory,
+            declaredDirectories: normalizedDeclaredDirectories,
+            includeRetired,
             limit,
         });
         const offset = this.#cursorOffset(request.cursor, cursorScope);
@@ -894,7 +951,7 @@ export class WorldDocumentStore {
             }),
             coverage: freeze({
                 status: "complete",
-                excludedDocuments: 0,
+                excludedDocuments,
             }),
             page: freeze({
                 unit: "entries",
@@ -1081,19 +1138,19 @@ export class WorldDocumentStore {
         });
     }
     #readDocument(request) {
-        if (!hasOnlyKeys(request, ["kind", "document", "maxBytes", "cursor"]))
+        if (!hasOnlyKeys(request, ["kind", "document", "referenceProjection"]))
             return this.#failure("read_document", request, [
                 diagnostic({
                     code: "query_invalid",
                     message: "read_document contains undeclared query conditions",
                 }),
             ]);
-        const maxBytes = request.maxBytes ?? 8192;
-        if (!Number.isInteger(maxBytes) || maxBytes < 4 || maxBytes > 65_536)
+        if (request.referenceProjection !== undefined &&
+            request.referenceProjection !== "short_ref")
             return this.#failure("read_document", request, [
                 diagnostic({
                     code: "query_invalid",
-                    message: "read_document maxBytes must be 4 to 65536",
+                    message: "read_document referenceProjection, when present, must be short_ref",
                 }),
             ]);
         const resolved = this.#resolveSelector(request.document);
@@ -1109,21 +1166,9 @@ export class WorldDocumentStore {
                     message: "World document has no readable body range",
                 }),
             ], resolved.entry.descriptor);
-        const completeBody = resolved.entry.file.contents.slice(bodyRange.start.offset, bodyRange.end.offset);
-        const bytes = Buffer.from(completeBody, "utf8");
-        const cursorScope = JSON.stringify({
-            kind: "read_document",
-            layout: this.layout,
-            logicalRoot: this.logicalRoot,
-            document: request.document,
-            maxBytes,
-        });
-        const offset = this.#cursorOffset(request.cursor, cursorScope);
-        if (offset === null || offset > bytes.length)
-            return this.#cursorFailure("read_document", request);
-        const end = safeUtf8PageEnd(bytes, offset, maxBytes);
-        const body = bytes.subarray(offset, end).toString("utf8");
-        const complete = end === bytes.length;
+        const completeBody = request.referenceProjection === "short_ref"
+            ? projectExplicitReferenceValues(resolved.entry.file.contents, bodyRange, resolved.entry.references, this.#descriptorIndex(), true)
+            : resolved.entry.file.contents.slice(bodyRange.start.offset, bodyRange.end.offset);
         return freeze({
             kind: "read_document",
             ok: true,
@@ -1140,15 +1185,7 @@ export class WorldDocumentStore {
             }),
             document: resolved.entry.descriptor,
             codec: resolved.entry.codec,
-            body,
-            page: freeze({
-                unit: "utf8_bytes",
-                start: offset,
-                end,
-                total: bytes.length,
-                complete,
-                nextCursor: complete ? null : this.#cursor(cursorScope, end),
-            }),
+            body: completeBody,
             diagnostics: freeze([]),
         });
     }
@@ -1187,20 +1224,6 @@ export class WorldDocumentStore {
             if (value === unresolved || node === undefined)
                 return this.#locatorFailure(entry, publicLocator, "locator_not_found");
             const projected = projectYamlValue(value, this.#descriptorIndex());
-            const isWholeDocumentProjection = locator.yaml.length === 0;
-            if (!isWholeDocumentProjection &&
-                Buffer.byteLength(JSON.stringify(projected), "utf8") >
-                    maxSelectedNodeBytes)
-                return this.#failure("select_node", request, [
-                    diagnostic({
-                        code: "capacity_exceeded",
-                        logicalPath: entry.file.path,
-                        documentId: entry.descriptor.documentId,
-                        locator: publicLocator,
-                        range: node.range,
-                        message: "Exact-node projection exceeds the capacity of one query",
-                    }),
-                ], entry.descriptor);
             return this.#selected(entry, publicLocator, {
                 codec: "yaml",
                 locator: publicLocator,
@@ -1222,17 +1245,6 @@ export class WorldDocumentStore {
                 return this.#locatorFailure(entry, publicLocator, "locator_ambiguous");
             const heading = headings[0];
             const markdown = entry.file.contents.slice(heading.range.start.offset, heading.range.end.offset);
-            if (Buffer.byteLength(markdown, "utf8") > maxSelectedNodeBytes)
-                return this.#failure("select_node", request, [
-                    diagnostic({
-                        code: "capacity_exceeded",
-                        logicalPath: entry.file.path,
-                        documentId: entry.descriptor.documentId,
-                        locator: publicLocator,
-                        range: heading.range,
-                        message: "Exact-node projection exceeds the capacity of one query",
-                    }),
-                ], entry.descriptor);
             return this.#selected(entry, publicLocator, {
                 codec: "markdown",
                 locator: publicLocator,
@@ -1475,15 +1487,6 @@ export class WorldDocumentStore {
             }));
             return entry;
         }
-        if (Buffer.byteLength(file.contents, "utf8") > maxWorldDocumentBytes) {
-            entry.diagnostics.push(diagnostic({
-                code: "capacity_exceeded",
-                logicalPath: file.path,
-                range: sourceRange(file.contents, 0, file.contents.length),
-                message: "One world document cannot exceed 4 MiB",
-            }));
-            return entry;
-        }
         if (entry.codec === "yaml")
             inspectYamlDocument(entry);
         else
@@ -1854,8 +1857,10 @@ function readHeader(entry, parsed, headerOnly) {
     }
     const header = first.value;
     const pairs = stringPairMap(header);
-    const allowed = new Set(["id", "ref", "title", "summary", "aliases"]);
-    const exactShape = pairs.size === allowed.size &&
+    const required = new Set(["id", "ref", "title", "summary", "aliases"]);
+    const allowed = new Set([...required, "retired"]);
+    const exactShape = (pairs.size === required.size || pairs.size === allowed.size) &&
+        [...required].every((key) => pairs.has(key)) &&
         [...pairs.keys()].every((key) => allowed.has(key)) &&
         (!headerOnly || parsed.root.items.length === 1);
     const idPair = pairs.get("id");
@@ -1863,12 +1868,14 @@ function readHeader(entry, parsed, headerOnly) {
     const titlePair = pairs.get("title");
     const summaryPair = pairs.get("summary");
     const aliasesPair = pairs.get("aliases");
+    const retiredPair = pairs.get("retired");
     const id = scalarString(idPair?.value);
     const shortRef = scalarString(refPair?.value);
     const title = scalarString(titlePair?.value);
     const summary = scalarString(summaryPair?.value);
     const aliases = stringSequence(aliasesPair?.value);
-    let valid = exactShape;
+    const retired = retiredPair === undefined ? false : scalarBoolean(retiredPair.value);
+    let valid = exactShape && retired !== null;
     if (id === null ||
         id.length < 3 ||
         id.length > 128 ||
@@ -1919,7 +1926,7 @@ function readHeader(entry, parsed, headerOnly) {
                 ? { documentId: id }
                 : {}),
             range: nodeRange(entry.file.contents, header, parsed.baseOffset),
-            message: "$document must contain only valid id, ref, title, summary, and aliases",
+            message: "$document must contain valid id, ref, title, summary, aliases, and an optional boolean retired flag",
         }));
         return null;
     }
@@ -1929,6 +1936,7 @@ function readHeader(entry, parsed, headerOnly) {
         title: title,
         summary: summary,
         aliases: freeze(aliases),
+        retired: retired,
         codec: entry.codec,
         logicalPath: entry.file.path,
     });
@@ -2001,7 +2009,7 @@ function inspectYamlReferences(entry, node, locator) {
     if (isSeq(node))
         node.items.forEach((child, index) => inspectYamlReferences(entry, child, [...locator, index]));
 }
-function projectExplicitReferenceValues(source, selectedRange, references, descriptors) {
+function projectExplicitReferenceValues(source, selectedRange, references, descriptors, quoteProjection = false) {
     const selectedStart = selectedRange.start.offset;
     const selectedEnd = selectedRange.end.offset;
     const replacements = references
@@ -2017,8 +2025,12 @@ function projectExplicitReferenceValues(source, selectedRange, references, descr
                     start,
                     end,
                     projection: descriptor === undefined
-                        ? "(invalid document reference)"
-                        : `@${descriptor.shortRef}`,
+                        ? quoteProjection
+                            ? JSON.stringify("(invalid document reference)")
+                            : "(invalid document reference)"
+                        : quoteProjection
+                            ? JSON.stringify(`@${descriptor.shortRef}`)
+                            : `@${descriptor.shortRef}`,
                 },
             ]
             : [];
@@ -2195,12 +2207,6 @@ function lineExcerptRange(source, matchStart, matchEnd) {
     const end = Math.min(lineEnd, matchEnd + 160);
     return sourceRange(source, start, end);
 }
-function safeUtf8PageEnd(bytes, offset, maxBytes) {
-    let end = Math.min(bytes.length, offset + maxBytes);
-    while (end > offset && (bytes[end] ?? 0) >= 0x80 && (bytes[end] ?? 0) < 0xc0)
-        end -= 1;
-    return end;
-}
 function scanMarkdownHeadings(source, bodyStart) {
     const headings = [];
     let fence = null;
@@ -2241,8 +2247,13 @@ function scanMarkdownHeadings(source, bodyStart) {
     }
     return { headings, hasUnclosedFence: fence !== null };
 }
-function patchRevisionMarkdown(source, edits) {
+function patchRevisionMarkdown(source, edits, initialMetadata) {
     let contents = source;
+    let metadata = {
+        title: initialMetadata.title,
+        summary: initialMetadata.summary,
+        aliases: [...initialMetadata.aliases],
+    };
     for (const edit of edits) {
         if (!isRecord(edit) || typeof edit.op !== "string")
             return {
@@ -2254,24 +2265,32 @@ function patchRevisionMarkdown(source, edits) {
                 ],
             };
         if (edit.op === "set_metadata") {
-            if (!hasOnlyKeys(edit, ["op", "title", "summary", "aliases"]) ||
-                !validDocumentMetadata(edit))
+            if (!hasOnlyKeys(edit, ["op", "title", "summary", "aliases"]))
+                return {
+                    diagnostics: [
+                        diagnostic({
+                            code: "document_header_invalid",
+                            message: "set_metadata accepts only op, title, summary, and aliases",
+                        }),
+                    ],
+                };
+            const resolved = resolveDocumentMetadataRevision(metadata, edit);
+            if ("problems" in resolved)
                 return {
                     diagnostics: [
                         diagnostic({
                             code: "document_header_invalid",
-                            message: hasOnlyKeys(edit, ["op", "title", "summary", "aliases"])
-                                ? `set_metadata arguments are invalid: ${documentMetadataProblems(edit).join("; ")}`
-                                : "set_metadata accepts only op, title, summary, and aliases",
+                            message: `set_metadata arguments are invalid: ${resolved.problems.join("; ")}`,
                         }),
                     ],
                 };
+            metadata = resolved.metadata;
             const envelope = markdownEnvelope(contents);
             if ("diagnostics" in envelope)
                 return envelope;
-            envelope.header.setIn(["$document", "title"], edit.title);
-            envelope.header.setIn(["$document", "summary"], edit.summary);
-            envelope.header.setIn(["$document", "aliases"], [...edit.aliases]);
+            envelope.header.setIn(["$document", "title"], metadata.title);
+            envelope.header.setIn(["$document", "summary"], metadata.summary);
+            envelope.header.setIn(["$document", "aliases"], [...metadata.aliases]);
             const body = contents.slice(envelope.bodyStart);
             const firstHeading = scanMarkdownHeadings(body, 0).headings[0];
             if (firstHeading?.level !== 1)
@@ -2283,7 +2302,7 @@ function patchRevisionMarkdown(source, edits) {
                         }),
                     ],
                 };
-            const nextBody = `${body.slice(0, firstHeading.range.start.offset)}# ${edit.title}${body.slice(firstHeading.range.end.offset)}`;
+            const nextBody = `${body.slice(0, firstHeading.range.start.offset)}# ${metadata.title}${body.slice(firstHeading.range.end.offset)}`;
             contents = `---\n${envelope.header.toString({ indent: 2, lineWidth: 0 }).trimEnd()}\n---\n${nextBody}`;
             continue;
         }
@@ -2464,6 +2483,31 @@ function markdownEnvelope(source) {
         };
     return { header, bodyStart: end + 5 };
 }
+function setDocumentRetired(source, codec, retired) {
+    if (codec === "yaml") {
+        const document = parseDocument(source, {
+            schema: "core",
+            uniqueKeys: true,
+            strict: true,
+        });
+        if (retired)
+            document.setIn(["$document", "retired"], true);
+        else
+            document.deleteIn(["$document", "retired"]);
+        return document.toString({ indent: 2, lineWidth: 0 });
+    }
+    const headerEnd = source.indexOf("\n---\n", 4);
+    const header = parseDocument(source.slice(4, headerEnd), {
+        schema: "core",
+        uniqueKeys: true,
+        strict: true,
+    });
+    if (retired)
+        header.setIn(["$document", "retired"], true);
+    else
+        header.deleteIn(["$document", "retired"]);
+    return `---\n${header.toString({ indent: 2, lineWidth: 0 }).trimEnd()}${source.slice(headerEnd)}`;
+}
 function markdownRevisionSection(source, locator) {
     const envelope = markdownEnvelope(source);
     if ("diagnostics" in envelope)
@@ -2562,6 +2606,11 @@ function scalarString(value) {
         ? value.value
         : null;
 }
+function scalarBoolean(value) {
+    return isScalar(value) && typeof value.value === "boolean"
+        ? value.value
+        : null;
+}
 function stringSequence(value) {
     if (!isSeq(value))
         return null;
@@ -2618,6 +2667,23 @@ function mechanicalHash(contents) {
 function validDocumentMetadata(value) {
     return documentMetadataProblems(value).length === 0;
 }
+function resolveDocumentMetadataRevision(current, edit) {
+    if (!Object.hasOwn(edit, "title") &&
+        !Object.hasOwn(edit, "summary") &&
+        !Object.hasOwn(edit, "aliases"))
+        return {
+            problems: ["at least one of title, summary, or aliases must be provided"],
+        };
+    const metadata = {
+        title: Object.hasOwn(edit, "title") ? edit.title : current.title,
+        summary: Object.hasOwn(edit, "summary") ? edit.summary : current.summary,
+        aliases: Object.hasOwn(edit, "aliases") ? edit.aliases : current.aliases,
+    };
+    const problems = documentMetadataProblems(metadata);
+    return problems.length === 0
+        ? { metadata: metadata }
+        : { problems };
+}
 /**
  * Says which of the three fields is wrong and what arrived instead.
  *
@@ -2711,6 +2777,10 @@ function validRelativePath(path) {
             .split("/")
             .every((segment) => segment !== "" && segment !== "." && segment !== ".."));
 }
+function validDeclaredDirectories(value) {
+    return (Array.isArray(value) &&
+        value.every((candidate) => typeof candidate === "string" && validRelativePath(candidate)));
+}
 function blockingDocumentDiagnostics(entry) {
     return entry.diagnostics.filter(({ code }) => code !== "locator_ambiguous" && code !== "document_reference_invalid");
 }

package/dist/node/runtime/world/WorldOperationCoordinator.js

@@ -24,6 +24,7 @@ const worldLockHeartbeatStaleMilliseconds = 30_000;
  */
 export class FileNativeWorldOperationCoordinator {
     #correctionClaimsRoot;
+    #revisionLocksRoot;
     #locksRoot;
     #authorityLocksRoot;
     #now;
@@ -32,6 +33,7 @@ export class FileNativeWorldOperationCoordinator {
     constructor(dataRoot, options = {}) {
         const root = join(resolve(dataRoot), "operations");
         this.#correctionClaimsRoot = join(root, "correction-claims");
+        this.#revisionLocksRoot = join(root, "world-revision-locks");
         this.#locksRoot = join(root, "world-locks");
         this.#authorityLocksRoot = join(root, "authority-locks");
         this.#now = options.now ?? Date.now;
@@ -45,7 +47,8 @@ export class FileNativeWorldOperationCoordinator {
         assertNonEmptyIdentity(worldId, "world ID");
         assertNonEmptyIdentity(operationId, "correction operation ID");
         return this.#withWorldLock(worldId, async () => {
-            if ((await this.#reconcileCorrectionClaim(worldId)) !== null)
+            if ((await this.#reconcileCorrectionClaim(worldId)) !== null ||
+                (await this.#readRevisionLock(worldId)) !== null)
                 return { kind: "busy" };
             const now = this.#now();
             const record = {
@@ -107,11 +110,70 @@ export class FileNativeWorldOperationCoordinator {
     async withExclusiveWorldStateMutation(worldId, action) {
         assertNonEmptyIdentity(worldId, "world ID");
         return this.#withWorldLock(worldId, async () => {
-            if ((await this.#reconcileCorrectionClaim(worldId)) !== null)
+            if ((await this.#reconcileCorrectionClaim(worldId)) !== null ||
+                (await this.#readRevisionLock(worldId)) !== null)
                 throw new WorldOperationBusyError();
             return action();
         });
     }
+    /**
+     * Acquire or resume a persistent revision lock. The lock deliberately has no
+     * lease timeout: only Apply or Discard may release its epoch.
+     */
+    async acquireWorldRevision(worldId, epochId) {
+        assertNonEmptyIdentity(worldId, "world ID");
+        assertNonEmptyIdentity(epochId, "world-revision epoch ID");
+        return this.#withWorldLock(worldId, async () => {
+            const existing = await this.#readRevisionLock(worldId);
+            if (existing !== null)
+                return existing.epochId === epochId
+                    ? {
+                        kind: "acquired",
+                        handle: revisionLockHandle(existing),
+                    }
+                    : { kind: "busy", epochId: existing.epochId };
+            if ((await this.#reconcileCorrectionClaim(worldId)) !== null)
+                return { kind: "busy" };
+            const record = {
+                schemaVersion: 1,
+                kind: "world_revision_lock",
+                worldId,
+                epochId,
+                acquiredAt: this.#now(),
+            };
+            await publishJson(this.#revisionLockPath(worldId), record);
+            return { kind: "acquired", handle: revisionLockHandle(record) };
+        });
+    }
+    async readWorldRevisionLock(worldId) {
+        assertNonEmptyIdentity(worldId, "world ID");
+        const record = await this.#readRevisionLock(worldId);
+        return record === null ? null : revisionLockHandle(record);
+    }
+    async assertWorldRevisionUnlocked(worldId) {
+        assertNonEmptyIdentity(worldId, "world ID");
+        if ((await this.#readRevisionLock(worldId)) !== null)
+            throw new WorldOperationBusyError();
+    }
+    async withWorldRevisionLock(handle, action) {
+        assertWorldRevisionLockHandle(handle);
+        return this.#withWorldLock(handle.worldId, async () => {
+            const current = await this.#readRevisionLock(handle.worldId);
+            if (current?.epochId !== handle.epochId)
+                throw new WorldOperationClaimLostError();
+            return action();
+        });
+    }
+    async releaseWorldRevision(handle) {
+        assertWorldRevisionLockHandle(handle);
+        await this.#withWorldLock(handle.worldId, async () => {
+            const current = await this.#readRevisionLock(handle.worldId);
+            if (current?.epochId !== handle.epochId)
+                return;
+            await rm(this.#revisionLockPath(handle.worldId), { force: true });
+            await syncDirectory(this.#revisionLocksRoot);
+        });
+    }
     async withWorldLocalMetadataMutation(worldId, action) {
         assertNonEmptyIdentity(worldId, "world ID");
         return this.#withWorldLock(worldId, action);
@@ -134,6 +196,20 @@ export class FileNativeWorldOperationCoordinator {
             throw new Error("invalid continuity correction claim");
         return value;
     }
+    async #readRevisionLock(worldId) {
+        let value;
+        try {
+            value = JSON.parse(await readFile(this.#revisionLockPath(worldId), "utf8"));
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+        if (!isWorldRevisionLockRecord(value) || value.worldId !== worldId)
+            throw new Error("invalid world revision lock");
+        return value;
+    }
     async #reconcileCorrectionClaim(worldId) {
         const claim = await this.#readCorrectionClaim(worldId);
         if (claim === null)
@@ -216,6 +292,31 @@ export class FileNativeWorldOperationCoordinator {
     #correctionClaimPath(worldId) {
         return join(this.#correctionClaimsRoot, `${digest(worldId)}.json`);
     }
+    #revisionLockPath(worldId) {
+        return join(this.#revisionLocksRoot, `${digest(worldId)}.json`);
+    }
+}
+function isWorldRevisionLockRecord(value) {
+    return (record(value) &&
+        hasExactKeys(value, [
+            "schemaVersion",
+            "kind",
+            "worldId",
+            "epochId",
+            "acquiredAt",
+        ]) &&
+        value.schemaVersion === 1 &&
+        value.kind === "world_revision_lock" &&
+        nonEmptyString(value.worldId) &&
+        nonEmptyString(value.epochId) &&
+        finiteNumber(value.acquiredAt));
+}
+function assertWorldRevisionLockHandle(handle) {
+    assertNonEmptyIdentity(handle.worldId, "world ID");
+    assertNonEmptyIdentity(handle.epochId, "world-revision epoch ID");
+}
+function revisionLockHandle(record) {
+    return { worldId: record.worldId, epochId: record.epochId };
 }
 function isCorrectionClaimRecord(value) {
     return (record(value) &&