narraeon 0.7.6 → 0.7.9

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

@@ -52,6 +52,7 @@ export class WorldDocumentStore {
                 original: file,
                 lastCommandIndex: null,
             }));
+            const editOutcomes = [];
             for (const [commandIndex, command] of request.commands.entries()) {
                 activeCommandIndex = commandIndex;
                 if (!isRecord(command) || typeof command.kind !== "string")
@@ -342,201 +343,50 @@ export class WorldDocumentStore {
                     const target = this.#resolveRevisionTarget(current, working, command.document);
                     if ("diagnostics" in target)
                         return this.#revisionFailure(commandIndex, target.diagnostics);
-                    if (target.entry.codec === "markdown") {
-                        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,
-                                logicalPath: target.entry.file.path,
-                                documentId: target.entry.descriptor.documentId,
-                            })));
-                        target.working.file.contents = patched.contents;
-                    }
-                    else {
-                        let document = parseDocument(target.working.file.contents, {
-                            schema: "core",
-                            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, {
-                                    code: "query_invalid",
-                                    logicalPath: target.entry.file.path,
-                                    documentId: target.entry.descriptor.documentId,
-                                    message: "A patch edit must be a closed object with op",
-                                });
-                            if (edit.op === "set_metadata") {
-                                if (!hasOnlyKeys(edit, ["op", "title", "summary", "aliases"]))
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "document_header_invalid",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        message: "set_metadata accepts only op, title, summary, and aliases",
-                                    });
-                                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: ${resolved.problems.join("; ")}`,
-                                    });
-                                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) ||
-                                !validYamlLocator(edit.locator) ||
-                                edit.locator.yaml[0] === "$document")
-                                return this.#revisionFailure(commandIndex, {
-                                    code: "locator_invalid",
-                                    logicalPath: target.entry.file.path,
-                                    documentId: target.entry.descriptor?.documentId,
-                                    ...(isRecord(edit) && isRecord(edit.locator)
-                                        ? {
-                                            locator: copyLocator(edit.locator),
-                                        }
-                                        : {}),
-                                    message: "A YAML edit requires an exact locator outside the technical header",
-                                });
-                            const locator = [...edit.locator.yaml];
-                            if (locator.length === 0) {
-                                if ((edit.op !== "add" && edit.op !== "replace") ||
-                                    !hasOnlyKeys(edit, ["op", "locator", "value"]))
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "locator_invalid",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        locator: { yaml: [] },
-                                        message: "A whole YAML body supports only add or replace",
-                                    });
-                                const value = this.#resolveRevisionYamlValue(edit.value, current, working, { referenceInput: "persistent_or_explicit" }, []);
-                                if ("diagnostics" in value)
-                                    return this.#revisionFailure(commandIndex, value.diagnostics.map((problem) => ({
-                                        ...problem,
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                    })));
-                                if (!isRecord(value.value) ||
-                                    Object.hasOwn(value.value, "$document"))
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "yaml_invalid",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        locator: { yaml: [] },
-                                        message: "A whole YAML body must be a map without $document",
-                                    });
-                                const currentValue = document.toJS({
-                                    maxAliasCount: 0,
-                                });
-                                if (!isRecord(currentValue) ||
-                                    !isRecord(currentValue.$document))
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "document_header_invalid",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        message: "YAML technical header could not be preserved",
-                                    });
-                                if (edit.op === "add" &&
-                                    Object.keys(currentValue).some((key) => key !== "$document"))
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "locator_invalid",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        locator: { yaml: [] },
-                                        message: "Adding a whole YAML body requires the current body to be empty",
-                                    });
-                                document = parseDocument(stringify({ $document: currentValue.$document, ...value.value }, { indent: 2, lineWidth: 0 }), { schema: "core", uniqueKeys: true, strict: true });
-                                continue;
-                            }
-                            const exists = document.hasIn(locator);
-                            if (edit.op === "remove") {
-                                if (!hasOnlyKeys(edit, ["op", "locator"]) || !exists)
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "locator_not_found",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        locator: { yaml: locator },
-                                        message: "YAML remove target must exist",
-                                    });
-                                document.deleteIn(locator);
-                                continue;
-                            }
-                            if (!hasOnlyKeys(edit, ["op", "locator", "value"]))
-                                return this.#revisionFailure(commandIndex, {
-                                    code: "query_invalid",
-                                    logicalPath: target.entry.file.path,
-                                    documentId: target.entry.descriptor.documentId,
-                                    locator: { yaml: locator },
-                                    message: "YAML value-edit arguments are invalid",
-                                });
-                            let valueLocator = locator;
-                            if (edit.op === "append") {
-                                const sequence = document.getIn(locator, true);
-                                if (!isSeq(sequence))
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "locator_invalid",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        locator: { yaml: locator },
-                                        message: "YAML append target must be a sequence",
-                                    });
-                                valueLocator = [...locator, sequence.items.length];
-                            }
-                            const value = this.#resolveRevisionYamlValue(edit.value, current, working, { referenceInput: "persistent_or_explicit" }, valueLocator);
-                            if ("diagnostics" in value)
-                                return this.#revisionFailure(commandIndex, value.diagnostics.map((problem) => ({
-                                    ...problem,
-                                    logicalPath: target.entry.file.path,
-                                    documentId: target.entry.descriptor?.documentId,
-                                })));
-                            if (edit.op === "add") {
-                                const parent = locator.length === 1
-                                    ? document.contents
-                                    : document.getIn(locator.slice(0, -1), true);
-                                const last = locator.at(-1);
-                                const parentAcceptsLocator = (isMap(parent) && typeof last === "string") ||
-                                    (isSeq(parent) && typeof last === "number");
-                                if (exists || !parentAcceptsLocator)
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "locator_invalid",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        locator: { yaml: locator },
-                                        message: "YAML add target must not exist, and its parent map or sequence must exist",
-                                    });
-                                document.setIn(locator, value.value);
-                            }
-                            else if (edit.op === "replace") {
-                                if (!exists)
-                                    return this.#revisionFailure(commandIndex, {
-                                        code: "locator_not_found",
-                                        logicalPath: target.entry.file.path,
-                                        documentId: target.entry.descriptor.documentId,
-                                        locator: { yaml: locator },
-                                        message: "YAML replace target must exist",
-                                    });
-                                document.setIn(locator, value.value);
-                            }
-                            else
-                                document.addIn(locator, value.value);
+                    const logicalPath = target.working.file.path;
+                    const probe = (contents) => this.#localRevisionDiagnostics(WorldDocumentStore.open({
+                        layout: this.layout,
+                        files: working.map(({ file }) => file.path === logicalPath
+                            ? { path: logicalPath, contents }
+                            : file),
+                    }), logicalPath);
+                    const resolveValue = (value, locator) => this.#resolveRevisionYamlValue(value, current, working, { referenceInput: "persistent_or_explicit" }, locator);
+                    // Each edit settles on its own: it is applied to the text left by the
+                    // edits before it, validated alone, and skipped if it cannot apply.
+                    let contents = target.working.file.contents;
+                    let metadata = {
+                        title: target.entry.descriptor.title,
+                        summary: target.entry.descriptor.summary,
+                        aliases: [...target.entry.descriptor.aliases],
+                    };
+                    const outcomes = [];
+                    for (const [editIndex, edit] of command.edits.entries()) {
+                        let settled = target.entry.codec === "markdown"
+                            ? applyMarkdownRevisionEdit(contents, metadata, edit)
+                            : applyYamlRevisionEdit(contents, metadata, edit, resolveValue);
+                        if (settled.kind === "applied") {
+                            const problems = probe(settled.contents);
+                            if (problems.length > 0)
+                                settled = { kind: "failed", diagnostic: problems[0] };
                         }
-                        target.working.file.contents = document.toString({
-                            indent: 2,
-                            lineWidth: 0,
-                        });
+                        if (settled.kind === "applied") {
+                            contents = settled.contents;
+                            metadata = settled.metadata;
+                        }
+                        outcomes.push(revisionEditOutcome(commandIndex, editIndex, settled, {
+                            logicalPath,
+                            documentId: target.entry.descriptor.documentId,
+                        }));
+                    }
+                    if (outcomes.some(({ status }) => status === "applied")) {
+                        target.working.file.contents = contents;
+                        delete target.working.file.encoding;
                     }
-                    delete target.working.file.encoding;
                     target.working.lastCommandIndex = commandIndex;
-                    touchedPath = target.working.file.path;
+                    touchedPath = logicalPath;
+                    editOutcomes.push(...outcomes);
+                    if (outcomes.every(({ status }) => status === "failed"))
+                        return this.#revisionFailure(commandIndex, outcomes.flatMap(({ diagnostic }) => diagnostic === undefined ? [] : [diagnostic]), outcomes);
                 }
                 else
                     return this.#revisionFailure(commandIndex, {
@@ -565,6 +415,7 @@ export class WorldDocumentStore {
                         const commandIndex = working.find(({ file }) => file.path === problem.logicalPath)?.lastCommandIndex;
                         return revisionDiagnostic(commandIndex ?? null, problem);
                     })),
+                    editOutcomes: freeze([...editOutcomes]),
                 });
             const changes = working
                 .filter(({ file, original }) => file.path !== original?.path ||
@@ -603,6 +454,7 @@ export class WorldDocumentStore {
                 files: snapshot.files,
                 diagnostics: freeze([]),
                 changes: freeze(changes),
+                editOutcomes: freeze(editOutcomes),
             });
         }
         catch {
@@ -612,7 +464,7 @@ export class WorldDocumentStore {
             });
         }
     }
-    #revisionFailure(commandIndex, problem) {
+    #revisionFailure(commandIndex, problem, editOutcomes = []) {
         const diagnostics = Array.isArray(problem)
             ? problem
             : [problem];
@@ -622,6 +474,7 @@ export class WorldDocumentStore {
             sourceSnapshotId: this.id,
             snapshotStatus: this.status,
             diagnostics: freeze(diagnostics.map((candidate) => revisionDiagnostic(commandIndex, candidate))),
+            editOutcomes: freeze([...editOutcomes]),
         });
     }
     #resolveRevisionTarget(snapshot, working, target) {
@@ -2247,205 +2100,362 @@ function scanMarkdownHeadings(source, bodyStart) {
     }
     return { headings, hasUnclosedFence: fence !== null };
 }
-function patchRevisionMarkdown(source, edits, initialMetadata) {
-    let contents = source;
-    let metadata = {
-        title: initialMetadata.title,
-        summary: initialMetadata.summary,
-        aliases: [...initialMetadata.aliases],
+function revisionEditOutcome(commandIndex, editIndex, result, document) {
+    return freeze(result.kind === "applied"
+        ? { commandIndex, editIndex, status: "applied" }
+        : {
+            commandIndex,
+            editIndex,
+            status: result.kind,
+            diagnostic: freeze({ ...result.diagnostic, ...document }),
+        });
+}
+function editFailed(problem) {
+    return { kind: "failed", diagnostic: problem };
+}
+function editTargetAbsent(locator) {
+    return {
+        kind: "no_op",
+        diagnostic: diagnostic({
+            code: "locator_not_found",
+            locator,
+            message: "target absent",
+        }),
     };
-    for (const edit of edits) {
-        if (!isRecord(edit) || typeof edit.op !== "string")
-            return {
-                diagnostics: [
-                    diagnostic({
-                        code: "query_invalid",
-                        message: "A Markdown patch edit must be a closed object with op",
-                    }),
-                ],
-            };
-        if (edit.op === "set_metadata") {
-            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: `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"], 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)
-                return {
-                    diagnostics: [
-                        diagnostic({
-                            code: "markdown_invalid",
-                            message: "Markdown body is missing an updateable h1",
-                        }),
-                    ],
-                };
-            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;
-        }
-        if (edit.op === "replace_body" || edit.op === "replace_preamble") {
-            if (!hasOnlyKeys(edit, ["op", "markdown"]) ||
-                typeof edit.markdown !== "string")
-                return {
-                    diagnostics: [
-                        diagnostic({
-                            code: "query_invalid",
-                            message: "A Markdown body edit requires markdown source",
-                        }),
-                    ],
-                };
-            const envelope = markdownEnvelope(contents);
-            if ("diagnostics" in envelope)
-                return envelope;
-            if (edit.op === "replace_body") {
-                contents = `${contents.slice(0, envelope.bodyStart)}${edit.markdown.trimEnd()}\n`;
-                continue;
+}
+function applyYamlRevisionEdit(contents, metadata, edit, resolveValue) {
+    if (!isRecord(edit) || typeof edit.op !== "string")
+        return editFailed(diagnostic({
+            code: "query_invalid",
+            message: "A patch edit must be a closed object with op",
+        }));
+    const document = parseDocument(contents, {
+        schema: "core",
+        uniqueKeys: true,
+        strict: true,
+    });
+    const serialized = (nextMetadata) => ({
+        kind: "applied",
+        contents: document.toString({ indent: 2, lineWidth: 0 }),
+        metadata: nextMetadata,
+    });
+    if (edit.op === "set_metadata") {
+        if (!hasOnlyKeys(edit, ["op", "title", "summary", "aliases"]))
+            return editFailed(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 editFailed(diagnostic({
+                code: "document_header_invalid",
+                message: `set_metadata arguments are invalid: ${resolved.problems.join("; ")}`,
+            }));
+        document.setIn(["$document", "title"], resolved.metadata.title);
+        document.setIn(["$document", "summary"], resolved.metadata.summary);
+        document.setIn(["$document", "aliases"], [...resolved.metadata.aliases]);
+        return serialized(resolved.metadata);
+    }
+    if (!["add", "replace", "append", "remove"].includes(edit.op) ||
+        !validYamlLocator(edit.locator) ||
+        edit.locator.yaml[0] === "$document")
+        return editFailed(diagnostic({
+            code: "locator_invalid",
+            ...(isRecord(edit.locator)
+                ? {
+                    locator: copyLocator(edit.locator),
+                }
+                : {}),
+            message: "A YAML edit requires an exact locator outside the technical header",
+        }));
+    const locator = [...edit.locator.yaml];
+    if (locator.length === 0) {
+        if ((edit.op !== "add" && edit.op !== "replace") ||
+            !hasOnlyKeys(edit, ["op", "locator", "value"]))
+            return editFailed(diagnostic({
+                code: "locator_invalid",
+                locator: { yaml: [] },
+                message: "A whole YAML body supports only add or replace",
+            }));
+        const value = resolveValue(edit.value, []);
+        if ("diagnostics" in value)
+            return editFailed(value.diagnostics[0]);
+        if (!isRecord(value.value) || Object.hasOwn(value.value, "$document"))
+            return editFailed(diagnostic({
+                code: "yaml_invalid",
+                locator: { yaml: [] },
+                message: "A whole YAML body must be a map without $document",
+            }));
+        const currentValue = document.toJS({ maxAliasCount: 0 });
+        if (!isRecord(currentValue) || !isRecord(currentValue.$document))
+            return editFailed(diagnostic({
+                code: "document_header_invalid",
+                message: "YAML technical header could not be preserved",
+            }));
+        const body = parseDocument(stringify({ $document: currentValue.$document, ...value.value }, { indent: 2, lineWidth: 0 }), { schema: "core", uniqueKeys: true, strict: true });
+        return {
+            kind: "applied",
+            contents: body.toString({ indent: 2, lineWidth: 0 }),
+            metadata,
+        };
+    }
+    if (edit.op === "remove") {
+        if (!hasOnlyKeys(edit, ["op", "locator"]))
+            return editFailed(diagnostic({
+                code: "query_invalid",
+                locator: { yaml: locator },
+                message: "YAML remove accepts only op and locator",
+            }));
+        if (!document.hasIn(locator))
+            return editTargetAbsent({ yaml: locator });
+        document.deleteIn(locator);
+        return serialized(metadata);
+    }
+    if (!hasOnlyKeys(edit, ["op", "locator", "value"]))
+        return editFailed(diagnostic({
+            code: "query_invalid",
+            locator: { yaml: locator },
+            message: "YAML value-edit arguments are invalid",
+        }));
+    if (edit.op === "append") {
+        const sequence = document.getIn(locator, true);
+        if (!isSeq(sequence))
+            return editFailed(diagnostic({
+                code: "locator_invalid",
+                locator: { yaml: locator },
+                message: "YAML append target must be a sequence",
+            }));
+        const value = resolveValue(edit.value, [...locator, sequence.items.length]);
+        if ("diagnostics" in value)
+            return editFailed(value.diagnostics[0]);
+        sequence.add(document.createNode(value.value));
+        return serialized(metadata);
+    }
+    const value = resolveValue(edit.value, locator);
+    if ("diagnostics" in value)
+        return editFailed(value.diagnostics[0]);
+    if (!upsertYamlValue(document, locator, value.value))
+        return editFailed(diagnostic({
+            code: "locator_invalid",
+            locator: { yaml: locator },
+            message: "YAML add or replace parent must be a map or sequence",
+        }));
+    return serialized(metadata);
+}
+/**
+ * Writes value at locator, creating what is missing: absent map keys and
+ * parent maps are created, and a sequence index at or past the end appends.
+ * Returns false when an existing parent is neither a map nor a sequence.
+ */
+function upsertYamlValue(document, locator, value) {
+    let node = document.contents;
+    for (const [depth, segment] of locator.entries()) {
+        const rest = locator.slice(depth + 1);
+        if (isMap(node) && typeof segment === "string") {
+            if (rest.length === 0) {
+                node.set(segment, document.createNode(value));
+                return true;
             }
-            const headings = scanMarkdownHeadings(contents, envelope.bodyStart).headings;
-            const h1 = headings.find(({ level }) => level === 1);
-            if (h1 === undefined)
-                return {
-                    diagnostics: [
-                        diagnostic({
-                            code: "markdown_invalid",
-                            message: "Markdown body is missing an updateable h1",
-                        }),
-                    ],
-                };
-            const nextH2 = headings.find(({ level, range }) => level === 2 && range.start.offset > h1.range.start.offset);
-            const end = nextH2?.range.start.offset ?? contents.length;
-            contents = `${contents.slice(0, h1.range.end.offset)}\n\n${edit.markdown.trim()}\n\n${contents.slice(end)}`;
-            continue;
-        }
-        if (![
-            "replace_section",
-            "add_section",
-            "rename_section",
-            "remove_section",
-        ].includes(edit.op) ||
-            !validMarkdownLocator(edit.locator))
-            return {
-                diagnostics: [
-                    diagnostic({
-                        code: "locator_invalid",
-                        ...(isRecord(edit.locator)
-                            ? {
-                                locator: copyLocator(edit.locator),
-                            }
-                            : {}),
-                        message: "A Markdown patch requires an exact heading locator",
-                    }),
-                ],
-            };
-        const locator = { markdown: [...edit.locator.markdown] };
-        const section = markdownRevisionSection(contents, locator.markdown);
-        if ("diagnostics" in section)
-            return section;
-        if (edit.op === "remove_section") {
-            if (!hasOnlyKeys(edit, ["op", "locator"]))
-                return {
-                    diagnostics: [
-                        diagnostic({
-                            code: "query_invalid",
-                            locator,
-                            message: "remove_section contains undeclared arguments",
-                        }),
-                    ],
-                };
-            contents = `${contents.slice(0, section.start)}${contents.slice(section.rawEnd)}`;
-            continue;
+            const child = node.get(segment, true);
+            if (child === undefined) {
+                node.set(segment, document.createNode(yamlTailValue(rest, value)));
+                return true;
+            }
+            if (!isMap(child) && !isSeq(child))
+                return false;
+            node = child;
         }
-        if (edit.op === "rename_section") {
-            if (!hasOnlyKeys(edit, ["op", "locator", "title"]) ||
-                !validMarkdownHeadingTitle(edit.title))
-                return {
-                    diagnostics: [
-                        diagnostic({
-                            code: "query_invalid",
-                            locator,
-                            message: "rename_section requires a valid new heading",
-                        }),
-                    ],
-                };
-            contents = `${contents.slice(0, section.start)}${"#".repeat(section.level)} ${edit.title}${contents.slice(section.headingEnd)}`;
-            continue;
+        else if (isSeq(node) && typeof segment === "number") {
+            if (segment >= node.items.length) {
+                node.items.push(document.createNode(yamlTailValue(rest, value)));
+                return true;
+            }
+            if (rest.length === 0) {
+                node.items[segment] = document.createNode(value);
+                return true;
+            }
+            const child = node.items[segment];
+            if (!isMap(child) && !isSeq(child))
+                return false;
+            node = child;
         }
-        if (!hasOnlyKeys(edit, ["op", "locator", "markdown"]) ||
+        else
+            return false;
+    }
+    return false;
+}
+/** The value a missing path creates: maps for keys, a one-item list for indexes. */
+function yamlTailValue(path, value) {
+    return path.reduceRight((child, segment) => typeof segment === "number" ? [child] : { [segment]: child }, value);
+}
+function applyMarkdownRevisionEdit(source, metadata, edit) {
+    if (!isRecord(edit) || typeof edit.op !== "string")
+        return editFailed(diagnostic({
+            code: "query_invalid",
+            message: "A Markdown patch edit must be a closed object with op",
+        }));
+    // Every applied Markdown edit keeps a single trailing newline.
+    const applied = (contents, nextMetadata) => ({
+        kind: "applied",
+        contents: `${contents.trimEnd()}\n`,
+        metadata: nextMetadata,
+    });
+    if (edit.op === "set_metadata") {
+        if (!hasOnlyKeys(edit, ["op", "title", "summary", "aliases"]))
+            return editFailed(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 editFailed(diagnostic({
+                code: "document_header_invalid",
+                message: `set_metadata arguments are invalid: ${resolved.problems.join("; ")}`,
+            }));
+        const envelope = markdownEnvelope(source);
+        if ("diagnostics" in envelope)
+            return editFailed(envelope.diagnostics[0]);
+        envelope.header.setIn(["$document", "title"], resolved.metadata.title);
+        envelope.header.setIn(["$document", "summary"], resolved.metadata.summary);
+        envelope.header.setIn(["$document", "aliases"], [...resolved.metadata.aliases]);
+        const body = source.slice(envelope.bodyStart);
+        const firstHeading = scanMarkdownHeadings(body, 0).headings[0];
+        if (firstHeading?.level !== 1)
+            return editFailed(diagnostic({
+                code: "markdown_invalid",
+                message: "Markdown body is missing an updateable h1",
+            }));
+        const nextBody = `${body.slice(0, firstHeading.range.start.offset)}# ${resolved.metadata.title}${body.slice(firstHeading.range.end.offset)}`;
+        return applied(`---\n${envelope.header.toString({ indent: 2, lineWidth: 0 }).trimEnd()}\n---\n${nextBody}`, resolved.metadata);
+    }
+    if (edit.op === "replace_body" || edit.op === "replace_preamble") {
+        if (!hasOnlyKeys(edit, ["op", "markdown"]) ||
             typeof edit.markdown !== "string")
-            return {
-                diagnostics: [
-                    diagnostic({
-                        code: "query_invalid",
-                        locator,
-                        message: "A Markdown section edit requires a complete Markdown block",
-                    }),
-                ],
-            };
-        const block = edit.markdown.trim();
-        const { headings, hasUnclosedFence } = scanMarkdownHeadings(block, 0);
-        const first = headings[0];
-        const escapesSectionSubtree = headings
-            .slice(1)
-            .some(({ level }) => first !== undefined && level <= first.level);
-        if (edit.op === "replace_section") {
-            if (first?.range.start.offset !== 0 ||
-                first.level !== section.level ||
-                first.title.normalize("NFKC") !==
-                    locator.markdown.at(-1).normalize("NFKC") ||
-                escapesSectionSubtree ||
-                hasUnclosedFence)
-                return {
-                    diagnostics: [
-                        diagnostic({
-                            code: "locator_invalid",
-                            locator,
-                            message: "replace_section first heading must preserve the exact original heading path",
-                        }),
-                    ],
-                };
-            contents = `${contents.slice(0, section.start)}${block}${contents.slice(section.trimmedEnd)}`;
+            return editFailed(diagnostic({
+                code: "query_invalid",
+                message: "A Markdown body edit requires markdown source",
+            }));
+        const envelope = markdownEnvelope(source);
+        if ("diagnostics" in envelope)
+            return editFailed(envelope.diagnostics[0]);
+        if (edit.op === "replace_body")
+            return applied(`${source.slice(0, envelope.bodyStart)}${edit.markdown.trimEnd()}\n`, metadata);
+        const headings = scanMarkdownHeadings(source, envelope.bodyStart).headings;
+        const h1 = headings.find(({ level }) => level === 1);
+        if (h1 === undefined)
+            return editFailed(diagnostic({
+                code: "markdown_invalid",
+                message: "Markdown body is missing an updateable h1",
+            }));
+        const nextH2 = headings.find(({ level, range }) => level === 2 && range.start.offset > h1.range.start.offset);
+        const end = nextH2?.range.start.offset ?? source.length;
+        return applied(`${source.slice(0, h1.range.end.offset)}\n\n${edit.markdown.trim()}\n\n${source.slice(end)}`, metadata);
+    }
+    if (![
+        "replace_section",
+        "add_section",
+        "rename_section",
+        "remove_section",
+    ].includes(edit.op) ||
+        !validMarkdownLocator(edit.locator, edit.op === "add_section"))
+        return editFailed(diagnostic({
+            code: "locator_invalid",
+            ...(isRecord(edit.locator)
+                ? {
+                    locator: copyLocator(edit.locator),
+                }
+                : {}),
+            message: "A Markdown patch requires an exact heading locator",
+        }));
+    const locator = { markdown: [...edit.locator.markdown] };
+    if (edit.op === "remove_section") {
+        if (!hasOnlyKeys(edit, ["op", "locator"]))
+            return editFailed(diagnostic({
+                code: "query_invalid",
+                locator,
+                message: "remove_section contains undeclared arguments",
+            }));
+        const section = markdownRevisionSection(source, locator.markdown);
+        if ("diagnostics" in section) {
+            const [problem] = section.diagnostics;
+            return problem?.code === "locator_not_found"
+                ? editTargetAbsent(locator)
+                : editFailed(problem);
         }
-        else {
-            if (first?.range.start.offset !== 0 ||
-                first.level !== section.level + 1 ||
-                escapesSectionSubtree ||
-                hasUnclosedFence)
-                return {
-                    diagnostics: [
-                        diagnostic({
-                            code: "locator_invalid",
-                            locator,
-                            message: "add_section must add a complete block with a heading one level lower",
-                        }),
-                    ],
-                };
-            contents = `${contents.slice(0, section.trimmedEnd)}\n\n${block}${contents.slice(section.trimmedEnd)}`;
+        return applied(`${source.slice(0, section.start)}${source.slice(section.rawEnd)}`, metadata);
+    }
+    if (edit.op === "rename_section") {
+        if (!hasOnlyKeys(edit, ["op", "locator", "title"]) ||
+            !validMarkdownHeadingTitle(edit.title))
+            return editFailed(diagnostic({
+                code: "query_invalid",
+                locator,
+                message: "rename_section requires a valid new heading",
+            }));
+        const section = markdownRevisionSection(source, locator.markdown);
+        if ("diagnostics" in section)
+            return editFailed(section.diagnostics[0]);
+        return applied(`${source.slice(0, section.start)}${"#".repeat(section.level)} ${edit.title}${source.slice(section.headingEnd)}`, metadata);
+    }
+    if (!hasOnlyKeys(edit, ["op", "locator", "markdown"]) ||
+        typeof edit.markdown !== "string")
+        return editFailed(diagnostic({
+            code: "query_invalid",
+            locator,
+            message: "A Markdown section edit requires a complete Markdown block",
+        }));
+    const block = edit.markdown.trim();
+    const { headings, hasUnclosedFence } = scanMarkdownHeadings(block, 0);
+    const first = headings[0];
+    const escapesSectionSubtree = headings
+        .slice(1)
+        .some(({ level }) => first !== undefined && level <= first.level);
+    const blockIsSubtree = first?.range.start.offset === 0 &&
+        !escapesSectionSubtree &&
+        !hasUnclosedFence;
+    const requestedTitle = locator.markdown.at(-1)?.normalize("NFKC");
+    if (edit.op === "replace_section") {
+        const section = markdownRevisionSection(source, locator.markdown);
+        if ("diagnostics" in section) {
+            if (section.diagnostics[0]?.code !== "locator_not_found")
+                return editFailed(section.diagnostics[0]);
+            // A heading that does not exist yet is added at the end of its parent.
+            const parent = markdownRevisionSection(source, locator.markdown.slice(0, -1));
+            if ("diagnostics" in parent)
+                return editFailed(parent.diagnostics[0]);
+            if (!blockIsSubtree ||
+                first.level !== parent.level + 1 ||
+                first.title.normalize("NFKC") !== requestedTitle)
+                return editFailed(diagnostic({
+                    code: "locator_invalid",
+                    locator,
+                    message: "replace_section new heading must keep the requested title and sit one level below its parent",
+                }));
+            return applied(insertMarkdownBlock(source, parent.trimmedEnd, block), metadata);
         }
+        if (!blockIsSubtree ||
+            first.level !== section.level ||
+            first.title.normalize("NFKC") !== requestedTitle)
+            return editFailed(diagnostic({
+                code: "locator_invalid",
+                locator,
+                message: "replace_section first heading must preserve the exact original heading path",
+            }));
+        return applied(`${source.slice(0, section.start)}${block}${source.slice(section.trimmedEnd)}`, metadata);
     }
-    return { contents: contents.trimEnd().concat("\n") };
+    const parent = markdownRevisionSection(source, locator.markdown);
+    if ("diagnostics" in parent)
+        return editFailed(parent.diagnostics[0]);
+    if (!blockIsSubtree || first.level !== parent.level + 1)
+        return editFailed(diagnostic({
+            code: "locator_invalid",
+            locator,
+            message: "add_section must add a complete block with a heading one level lower",
+        }));
+    return applied(insertMarkdownBlock(source, parent.trimmedEnd, block), metadata);
+}
+function insertMarkdownBlock(source, offset, block) {
+    return `${source.slice(0, offset)}\n\n${block}${source.slice(offset)}`;
 }
 function markdownEnvelope(source) {
     if (!source.startsWith("---\n"))
@@ -2513,6 +2523,26 @@ function markdownRevisionSection(source, locator) {
     if ("diagnostics" in envelope)
         return envelope;
     const headings = scanMarkdownHeadings(source, envelope.bodyStart).headings;
+    if (locator.length === 0) {
+        // The empty locator names the document body, whose sections are the h2s.
+        const h1 = headings.find(({ level }) => level === 1);
+        if (h1 === undefined)
+            return {
+                diagnostics: [
+                    diagnostic({
+                        code: "markdown_invalid",
+                        message: "Markdown body is missing an updateable h1",
+                    }),
+                ],
+            };
+        return {
+            start: h1.range.start.offset,
+            headingEnd: h1.range.end.offset,
+            trimmedEnd: trimTrailingWhitespaceOffset(source, h1.range.start.offset, source.length),
+            rawEnd: source.length,
+            level: 1,
+        };
+    }
     const stack = [];
     const matches = [];
     for (const [index, heading] of headings.entries()) {
@@ -2527,13 +2557,23 @@ function markdownRevisionSection(source, locator) {
             matches.push({ index, level: heading.level });
     }
     const publicLocator = { markdown: [...locator] };
-    if (matches.length !== 1)
+    if (matches.length === 0)
+        return {
+            diagnostics: [
+                diagnostic({
+                    code: "locator_not_found",
+                    locator: publicLocator,
+                    message: "Markdown heading path was not found",
+                }),
+            ],
+        };
+    if (matches.length > 1)
         return {
             diagnostics: [
                 diagnostic({
-                    code: matches.length === 0 ? "locator_not_found" : "locator_ambiguous",
+                    code: "locator_ambiguous",
                     locator: publicLocator,
-                    message: "Markdown heading path cannot be located uniquely",
+                    message: "Markdown heading path matches more than one section",
                 }),
             ],
         };
@@ -2658,6 +2698,18 @@ function sourcePoint(source, offset) {
 function diagnostic(value) {
     return freeze(value);
 }
+/** Human-readable locator for receipts and failure text; the structured locator stays the source of truth. */
+export function formatWorldDocumentLocator(locator) {
+    if ("markdown" in locator)
+        return locator.markdown.length === 0
+            ? "document body"
+            : locator.markdown.join(" > ");
+    return (locator.yaml.reduce((text, segment) => typeof segment === "number"
+        ? `${text}[${segment}]`
+        : text === ""
+            ? segment
+            : `${text}.${segment}`, "") || "whole body");
+}
 function revisionDiagnostic(commandIndex, value) {
     return freeze({ ...value, commandIndex });
 }
@@ -2801,11 +2853,11 @@ function validYamlLocator(value) {
         value.yaml.every((segment) => typeof segment === "string" ||
             (Number.isSafeInteger(segment) && Number(segment) >= 0)));
 }
-function validMarkdownLocator(value) {
+function validMarkdownLocator(value, allowBodyRoot = false) {
     return (isRecord(value) &&
         Object.keys(value).length === 1 &&
         Array.isArray(value.markdown) &&
-        value.markdown.length > 0 &&
+        (allowBodyRoot || value.markdown.length > 0) &&
         value.markdown.every((segment) => typeof segment === "string" && segment.length > 0));
 }
 function validMarkdownHeadingTitle(value) {