@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/stop-policy.mjs

@@ -0,0 +1,14 @@
+// Stop recipe deadline policy.
+export const DEFAULT_STOP_TIMEOUT = 90;
+export const STOP_HOOK_MARGIN = 60;
+export const MAX_STOP_TIMEOUT = Math.floor((2 ** 31 - 1) / 1000) - STOP_HOOK_MARGIN;
+
+export function readStopPolicy(manifest) {
+    const seconds = manifest?.verify?.stopTimeout;
+    if (seconds === undefined) return { seconds: DEFAULT_STOP_TIMEOUT, declared: false };
+    const spec = manifest?.portulan?.spec;
+    const version = typeof spec === "string" ? /^(\d+)\.(\d+)$/.exec(spec) : null;
+    if (!version || Number(version[1]) !== 2 || Number(version[2]) < 14) throw new Error("verify.stopTimeout requires portulan.spec 2.14 or a later minor on major 2");
+    if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > MAX_STOP_TIMEOUT) throw new Error(`verify.stopTimeout must be an integer from 1 to ${MAX_STOP_TIMEOUT} seconds`);
+    return { seconds, declared: true };
+}

package/cli/symbols.mjs

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
+import { HTML_ENTITIES } from "./html-entities.mjs";
 
 const USAGE = "usage: node cli/symbols.mjs <file>... | <file.md>#<heading>... | --find <name>...";
 
@@ -764,7 +765,14 @@ function order(entries) {
 // 5. Markdown: headings, and the section under each
 // ===========================================================================================
 
-// Headings as CommonMark reads them, outside fences, HTML comments and frontmatter; a setext heading in a list item is missed.
+// Top-level headings; list-container headings and full CommonMark block parsing are outside this reader.
+
+function characterReference(reference) {
+    if (!reference.startsWith("#")) return Object.hasOwn(HTML_ENTITIES, reference) ? HTML_ENTITIES[reference] : `&${reference};`;
+    const hex = /^#x/i.test(reference);
+    const point = Number.parseInt(reference.slice(hex ? 2 : 1), hex ? 16 : 10);
+    return String.fromCodePoint(point === 0 || point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff) ? 0xfffd : point);
+}
 
 /** A heading's text as it reads rendered: a code span's content kept, links and images their text, and emphasis, tags and escapes gone. */
 function plainText(title) {
@@ -772,9 +780,8 @@ function plainText(title) {
         text
             .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
             .replace(/!?\[([^\]]*)\]\[[^\]]*\]/g, "$1")
-            .replace(/<[^>]*>/g, "")
-            .replace(/\\([!-/:-@[-`{-~])/g, "$1")
-            .replace(/(^|[^\p{L}\p{N}*_])[*_]+|[*_]+(?=[^\p{L}\p{N}*_]|$)/gu, "$1");
+            .replace(/\\([!-/:-@[-`{-~])|<([A-Za-z][A-Za-z0-9+.-]{1,31}:[^<>\x00-\x20]*|[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?)>|<[^>]*>|&(#\d{1,7}|#[xX][\da-fA-F]{1,6}|[A-Za-z][A-Za-z0-9]*);|(^|[^\p{L}\p{N}*_])[*_]+|[*_]+(?=[^\p{L}\p{N}*_]|$)/gu,
+                (match, escaped, autolink, reference, lead) => escaped ?? autolink ?? (reference ? characterReference(reference) : lead ?? ""));
     let out = "";
     let at = 0;
     for (const span of title.matchAll(/(`+)(.+?)\1(?!`)/g)) {
@@ -794,6 +801,15 @@ const loose = (text) => plainText(text).replace(/\s+/g, " ").trim().toLowerCase(
 // A line that opens a block other than a paragraph, so no `=` or `-` line under it makes it a heading.
 const NOT_PARAGRAPH = /^(?: {4}|\t| {0,3}(?:>|[-*+](?:[ \t]|$)|\d{1,9}[.)](?:[ \t]|$)|<[A-Za-z/!?]|\|))/;
 const RULE = /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$/;
+const HEADING_OR_FENCE = /^(?:#{1,6}(?:[ \t]|$)|`{3,}|~{3,})/;
+
+const startsListParagraph = (text) => text.trim() !== "" && !NOT_PARAGRAPH.test(text) && !RULE.test(text) && !HEADING_OR_FENCE.test(text);
+
+function columns(text, start = 0) {
+    let col = start;
+    for (const char of text) col += char === "\t" ? 4 - col % 4 : 1;
+    return col;
+}
 
 /** The outline of a Markdown file: `{lines, bytes, entries}`, an entry per heading, nested by level. */
 export function outlineMd(src) {
@@ -811,8 +827,10 @@ export function outlineMd(src) {
     }
     let fence = null;
     let comment = false;
-    let para = null; // the line a paragraph opened at, at the margin, while it is open
+    let para = null; // the line the current paragraph opened at
     let above = "start"; // what the line above was: start, blank, heading, rule, para or other
+    const listIndents = [];
+    let listParagraph = false;
     for (; i < lines; i++) {
         const line = at(i);
         if (fence) {
@@ -829,6 +847,36 @@ export function outlineMd(src) {
             }
             continue;
         }
+        const indent = columns(/^[ \t]*/.exec(line)[0]);
+        const marker = !RULE.test(line) && /^([ \t]*)([-*+]|\d{1,9}[.)])([ \t]+|$)/.exec(line);
+        if (marker && (indent <= 3 || (listIndents.length && indent < listIndents.at(-1) + 4))) {
+            const end = indent + marker[2].length;
+            const padding = columns(marker[3], end) - end;
+            while (listIndents.length && listIndents.at(-1) > indent) listIndents.pop();
+            listIndents.push(end + (padding >= 1 && padding <= 4 ? padding : 1));
+            listParagraph = padding <= 4 && startsListParagraph(line.slice(marker[0].length));
+            para = null;
+            above = "other";
+            continue;
+        }
+        if (listIndents.length) {
+            if (line.trim() === "") {
+                listParagraph = false;
+            } else if (indent >= listIndents[0] || (listParagraph && !RULE.test(line) && !/^ {0,3}(?:#{1,6}(?:[ \t]|$)|>|`{3,}|~{3,}|<)/.test(line))) {
+                if (indent >= listIndents[0]) {
+                    while (listIndents.at(-1) > indent) listIndents.pop();
+                    listParagraph = (listParagraph || indent < listIndents.at(-1) + 4) && startsListParagraph(line.trimStart());
+                }
+                para = null;
+                above = "other";
+                continue;
+            } else {
+                listIndents.length = 0;
+                listParagraph = false;
+                para = null;
+                above = "blank";
+            }
+        }
         const open = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
         if (open && !(open[1][0] === "`" && open[2].includes("`"))) {
             fence = new RegExp(`^ {0,3}${open[1][0]}{${open[1].length},}[ \\t]*$`);
@@ -843,7 +891,7 @@ export function outlineMd(src) {
         }
         const atx = /^ {0,3}(#{1,6})(?:[ \t]+|$)(.*)$/.exec(line);
         if (atx) {
-            found.push({ start: i + 1, level: atx[1].length, title: atx[2].replace(/(?:^|[ \t]+)#+[ \t]*$/, "").trim() });
+            found.push({ start: i + 1, level: atx[1].length, title: atx[2].replace(/(?:^|[ \t]+)#+[ \t]*$/, "").replace(/^[ \t]+|[ \t]+$/g, "") });
             para = null;
             above = "heading";
             continue;
@@ -866,8 +914,7 @@ export function outlineMd(src) {
             para = null;
             above = "other";
         } else if (above !== "para" && above !== "other") {
-            // A paragraph a setext line may underline opens at the margin; one indented may sit in a list.
-            para = /^\S/.test(line) ? i + 1 : null;
+            para = i + 1;
             above = para === null ? "other" : "para";
         }
     }

package/cli/telemetry.mjs

@@ -17,16 +17,35 @@ import { recipeSet, resolverFor } from "./recipe-set.mjs";
 import { isInside } from "./inside.mjs";
 
 // ---------------------------------------------------------------------------------------------
-// The offline audit: no verify recipe may reach the network
+// The offline audit: recipes reach neither the network nor local usage records
 // ---------------------------------------------------------------------------------------------
 
-/** Every mode in cli/ that can reach the network; a new one is unrailed until it has a row here. */
+/** Every network mode in cli/ or a pack (named from `<category>/<name>/`); a new one is unrailed until it has a row here. */
 export const NETWORK_MODES = Object.freeze([
+    { module: "cli/fixtures/on-path-host/capture.mjs", flag: "--run-host", what: "runs the manual real-host on-path demonstration" },
+    { module: "cli/fixtures/nested-on-path-host/capture.mjs", flag: "--run-host", what: "runs the manual real-host nested instruction demonstration" },
+    { module: "cli/context.mjs", flag: "--count-tokens", what: "sends measured project source to Anthropic's token counter" },
+    { module: "cli/doctor.mjs", flag: "--count-tokens", aliases: [{ module: "cli/portulan.mjs", subcommand: "doctor" }, { module: "portulan", subcommand: "doctor" }, { module: "@sleepy_panda_srl/portulan", subcommand: "doctor" }], what: "requests a provider token estimate" },
     { module: "cli/review-meter.mjs", flag: "--fetch", what: "fetches review data from GitHub" },
     { module: "cli/telemetry.mjs", flag: "--export", what: "posts an OTLP payload to a collector" },
     { module: "cli/feedback.mjs", flag: "--approve", what: "files a GitHub issue with `gh issue create`" },
+    {
+        module: "tools/local-llm/runner/local-llm.mjs",
+        unless: "--verify-offline",
+        alsoUnless: ["eval", "--verify"],
+        what: "calls the model endpoint except offline rails and captured-record verification",
+    },
+]);
+
+/** Local usage is machine-specific too; static mode must be explicit on each recipe invocation. */
+export const LOCAL_RECORD_MODES = Object.freeze([
+    { module: "cli/doctor.mjs", requiresStatic: "--static", what: "reads local usage records by default" },
+    { module: "cli/portulan.mjs", subcommand: "doctor", requiresStatic: "--static", what: "dispatches to the local usage-record reader" },
+    { module: "portulan", subcommand: "doctor", requiresStatic: "--static", what: "dispatches to the local usage-record reader" },
 ]);
 
+export const modeSpelling = (m) => m.requiresStatic ? `${m.module}${m.subcommand ? ` ${m.subcommand}` : ""} without an immediate ${m.requiresStatic}` : (m.flag ? [m, ...(m.aliases ?? [])].map((s) => `${s.module}${s.subcommand ? ` ${s.subcommand}` : ""} ${m.flag}`).join(", ") : `${m.module} with anything but ${m.unless} alone${m.alsoUnless ? ` or ${m.alsoUnless.join(" ")} alone` : ""}`);
+
 /** Whole-line comments only: a trailing `#` may sit inside a quote. */
 export const stripShellComments = (source) =>
     source
@@ -36,13 +55,38 @@ export const stripShellComments = (source) =>
 
 const shellTokens = (body) => body.split(/\s+/).map((t) => t.replace(/^[("'`]+/, "").replace(/[)"'`;]+$/, "")).filter(Boolean);
 
-const tokenNamesModule = (token, module) => token === module || token.endsWith(`/${module}`);
+const tokenNamesModule = (token, module) => token === module || token.endsWith(`/${module}`) || (module.startsWith("@") && token.startsWith(`${module}@`));
 
 const tokenIsFlag = (token, flag) => token === flag || token.startsWith(`${flag}=`);
+const shellSource = (source) => stripShellComments(source).replace(/\\\r?\n/g, "");
+
+/** An `unless` row passes only where every invocation is the module and its one safe flag, alone on its command. */
+const onlySafeInvocations = (source, m) =>
+    shellSource(source)
+        .split(/\n|;|&&?|\|\|?|\$\(|<\(|>\(|`/)
+        .every((segment) => {
+            const tokens = shellTokens(segment);
+            if (tokens[0] === "for" || ["[", "test"].includes(tokens[0]) || (tokens[0] === "if" && ["[", "test"].includes(tokens[1]))) return true;
+            return tokens.every((t, i) => !tokenNamesModule(t, m.module) || ((tokens.length === i + 2 && tokens[i + 1] === m.unless) || (m.alsoUnless && JSON.stringify(tokens.slice(i + 1)) === JSON.stringify(m.alsoUnless))));
+        });
+
+const onlyStaticInvocations = (source, mode) => shellSource(source)
+    .split(/\n|;|&&?|\|\|?|\$\(|<\(|>\(|`/)
+    .every((segment) => {
+        const words = shellTokens(segment);
+        const first = words[0];
+        // A path in a file test or dependency list is data, not a CLI invocation.
+        if (["for", "printf", "echo", "[", "test"].includes(first) || (first === "if" && words.slice(1, 3).some((w) => ["[", "test"].includes(w)))) return true;
+        return words.every((word, i) => !tokenNamesModule(word, mode.module) || (mode.subcommand && words[i + 1] !== mode.subcommand) || words[i + (mode.subcommand ? 2 : 1)] === mode.requiresStatic);
+    });
 
 export function auditRecipeSource(source) {
-    const tokens = shellTokens(stripShellComments(source));
-    return NETWORK_MODES.filter((m) => tokens.some((t) => tokenNamesModule(t, m.module)) && tokens.some((t) => tokenIsFlag(t, m.flag)));
+    const tokens = shellTokens(shellSource(source));
+    const network = NETWORK_MODES.filter((m) =>
+        m.flag ? [m, ...(m.aliases ?? [])].some((s) => tokens.some((t, i) => tokenNamesModule(t, s.module) && (!s.subcommand || tokens[i + 1] === s.subcommand))) && tokens.some((t) => tokenIsFlag(t, m.flag)) : !onlySafeInvocations(source, m),
+    );
+    const local = LOCAL_RECORD_MODES.filter((m) => !onlyStaticInvocations(source, m));
+    return [...network, ...local];
 }
 
 export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
@@ -72,9 +116,11 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
     const findings = [];
     const read = [];
     for (const r of recipes) {
-        const script = String(r.run ?? "")
-            .split(/\s+/)
-            .find((t) => t.endsWith(".sh"));
+        const words = String(r.run ?? "").split(/\s+/).filter(Boolean);
+        // Direct CLI commands are graded as shell text; referenced shell scripts are read too.
+        const bare = words[0] === "portulan";
+        const direct = bare || (words[0] === "node" && !words.some((t) => t.endsWith(".sh")));
+        const script = bare ? "cli/portulan.mjs" : direct ? words.find((t) => /\.[cm]?js$/.test(t)) : words.find((t) => t.endsWith(".sh"));
         if (!script) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} has no readable script in its run line (${JSON.stringify(r.run ?? null)}); this audit cannot grade what it cannot read` };
         }
@@ -89,7 +135,10 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} names ${script}, which could not be read — ${cause.message}` };
         }
         read.push(r.id);
-        for (const hit of auditRecipeSource(source)) findings.push({ recipe: r.id, script, ...hit });
+        const hits = [...auditRecipeSource(r.run), ...(direct ? [] : auditRecipeSource(source))];
+        for (const [i, hit] of hits.entries()) {
+            if (!hits.slice(0, i).some((previous) => previous.module === hit.module && previous.flag === hit.flag && previous.requiresStatic === hit.requiresStatic)) findings.push({ recipe: r.id, script, ...hit });
+        }
     }
     return { ok: true, examined: read, findings };
 }
@@ -157,7 +206,7 @@ export const PRODUCERS = {
             return [
                 { name: "portulan.review.pull_requests", unit: "{pull_request}", description: "Merged pull requests in the metered window.", value: m.pullRequests },
                 { name: "portulan.review.submissions", unit: "{submission}", description: "Reviews the reviewer submitted across the window. Submission units, never fix-rounds.", value: m.submissions },
-                { name: "portulan.review.submissions_per_pull_request", unit: "1", description: "The figure a-review-loop-needs-a-bound.md bounds the loop on.", value: m.submissionsPerPullRequest },
+                { name: "portulan.review.submissions_per_pull_request", unit: "1", description: "The figure the retired a-review-loop-needs-a-bound.md bounded the loop on.", value: m.submissionsPerPullRequest },
                 { name: "portulan.review.submissions_no_inline", unit: "{submission}", description: "Submissions raising no inline comment.", value: m.noInline },
                 { name: "portulan.review.no_inline_rate", unit: "1", description: "An UPPER BOUND on the found-nothing rate; a submission carrying only suppressed notes counts in it.", value: m.noInlineRate },
                 { name: "portulan.review.pushes", unit: "{push}", description: "Distinct heads the reviewer saw — a floor on pushes, not a count of them.", value: m.pushes },
@@ -336,7 +385,7 @@ const USAGE = [
     "                    first: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (used as given) else",
     "                    OTEL_EXPORTER_OTLP_ENDPOINT (a base, +/v1/metrics); and",
     "                    OTEL_EXPORTER_OTLP_METRICS_HEADERS replacing OTEL_EXPORTER_OTLP_HEADERS",
-    "  --audit-recipes   assert that no recipe the workspace YIELDS can reach a network mode;",
+    "  --audit-recipes   assert that no recipe the workspace YIELDS can reach a network mode or read local usage records;",
     "                    takes --workspace and --pack-root, and needs no --config",
     "",
     "exit 0 the thing asked for happened · 1 a verdict (golden drift, or export while opted out)",
@@ -403,16 +452,16 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
             return 2;
         }
         if (res.findings.length > 0) {
-            io.error(`telemetry: ${res.findings.length} verify recipe(s) can reach the network:`);
-            for (const f of res.findings) io.error(`  - ${f.recipe} (${f.script}) invokes ${f.module} ${f.flag}, which ${f.what}`);
-            io.error("A verify recipe may not make a network call: spec/slots.md and .portulan/verify/README.md");
+            io.error(`telemetry: ${res.findings.length} verify recipe(s) can reach the network or local usage records:`);
+            for (const f of res.findings) io.error(`  - ${f.recipe} (${f.script}) invokes ${modeSpelling(f)}, which ${f.what}`);
+            io.error("A verify recipe may not make a network call or read local usage records: spec/slots.md and .portulan/verify/README.md");
             io.error("both prohibit it, because a rail that moves with the network goes red about the world");
             io.error("rather than about the tree.");
             return 1;
         }
-        io.log(`telemetry: ${res.examined.length} yielded recipe(s) examined; none reaches a network mode`);
-        io.log(`  Modes railed: ${NETWORK_MODES.map((m) => `${m.module} ${m.flag}`).join(", ")}.`);
-        io.log("  A network mode with no row here is UNRAILED, and nothing can audit that a row was added.");
+        io.log(`telemetry: ${res.examined.length} yielded recipe(s) examined; none reaches a network mode or reads local usage records`);
+        io.log(`  Modes railed: ${[...NETWORK_MODES, ...LOCAL_RECORD_MODES].map(modeSpelling).join(", ")}.`);
+        io.log("  A network or local-record mode with no row here is UNRAILED, and nothing can audit that a row was added.");
         return 0;
     }
 

package/cli/upgrade.mjs

@@ -4,6 +4,7 @@
 // Exit 0 succeeded · 1 a step owed under `--check` or left by hand, a red workspace, an unresolved pointer · 2 could not run.
 
 import fs from "node:fs";
+import { assertNoSourceJournal } from "./instructions-journal.mjs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -12,6 +13,7 @@ import { resolveGovernor } from "./discover.mjs";
 import { gitIn } from "./form.mjs";
 import { offerLines } from "./sessions.mjs";
 import { walk } from "./vendor.mjs";
+import { atomicWrite,guardedRemove,readOutput,sameContent } from "./guidance-files.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE = path.resolve(HERE, "..");
@@ -19,10 +21,10 @@ const MIGRATIONS = path.join(BUNDLE, "spec", "migrations");
 
 let stagingSeq = 0;
 
-/** Everything that means `upgrade` could not run. Carries no verdict about a workspace. */
+/** Unavailable, without a verdict about the workspace. */
 export class UpgradeError extends Error {}
 
-/** The Workspace Definition version this bundle implements, read from its schema's `$id`. */
+/** This bundle's Workspace Definition version from the schema `$id`. */
 export function bundleSpec({ schemaPath } = {}) {
     const file = schemaPath ?? path.join(BUNDLE, "spec", "workspace.schema.json");
     let text;
@@ -68,7 +70,7 @@ export async function loadSteps({ dir = MIGRATIONS } = {}) {
     return steps;
 }
 
-/** Read a workspace into the view a step is given, as `spec/migrations/README.md` defines it. */
+/** The step's workspace view; contract: `spec/migrations/README.md`. */
 export function readWorkspace(dir) {
     const root = path.resolve(dir);
     const file = path.join(root, "workspace.json");
@@ -120,7 +122,7 @@ export function readWorkspace(dir) {
     };
 }
 
-/** The repository the manifest's `tree` names, as a step reads it; `null` where it names no directory. */
+/** The step's declared repository view, or null without a tree. */
 export function repositoryView(root, manifest) {
     if (typeof manifest?.tree !== "string") return null;
     const dir = path.resolve(root, manifest.tree);
@@ -223,7 +225,7 @@ export async function planFor(ws, ctx, steps) {
         } catch (error) {
             answer = { owed: null, because: `${step.id} threw while deciding whether it is owed — ${error.message}` };
         }
-        // `hand`: owed, and placed by a person rather than by the step, so `--write` reports it and runs on.
+        // `hand` requires a person; report it and continue.
         entries.push({ step, owed: answer.owed, because: answer.because, hand: answer.owed === true && answer.hand === true });
         if (answer.owed === null) unknown += 1;
         else if (answer.owed === true) owed += 1;
@@ -231,14 +233,14 @@ export async function planFor(ws, ctx, steps) {
     return { entries, owed, unknown };
 }
 
-/** `rel` resolved inside `root`, or `null` if it escapes: `path.join` would pass an absolute `rel` as inside. */
+/** Resolve inside root, rejecting escapes. */
 export function inside(root, rel) {
     const resolved = path.resolve(root, rel);
     if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) return null;
     return resolved;
 }
 
-/** A reason to refuse, or `null`; `root` itself is not checked, since macOS's `os.tmpdir()` runs through `/var`. */
+/** Refusal or null; root may itself follow macOS's `/var` alias. */
 function linkOnPath(root, resolved) {
     const rel = path.relative(root, resolved);
     if (rel === "") return null;
@@ -257,7 +259,7 @@ function linkOnPath(root, resolved) {
     return null;
 }
 
-/** `dirs` as created, shallowest first; one that will not go is not empty, and neither are its parents. */
+/** Remove created directories deepest first, stopping at a nonempty one. */
 function unwindDirs(dirs) {
     for (const made of [...dirs].reverse()) {
         try {
@@ -275,6 +277,7 @@ export function applyEdits(dir, edits, options = {}) {
     const treeRoot = typeof options.treeDir === "string" ? path.resolve(options.treeDir) : null;
     const snapshots = [];
     for (const edit of edits) {
+        try{options.beforeMutation?.(edit);}catch(error){return {ok:false,snapshots,reason:error.message};}
         if (edit.root !== undefined && edit.root !== "workspace" && edit.root !== "tree") {
             return { ok: false, snapshots, reason: `an edit names root \`${edit.root}\`, which is neither the workspace nor the tree` };
         }
@@ -294,29 +297,35 @@ export function applyEdits(dir, edits, options = {}) {
         if (linked !== null) return { ok: false, snapshots, reason: linked };
 
         let previous = null;
-        let mode = null;
+        let mode = null, observedIdentity = null;
         try {
-            previous = fs.readFileSync(file, "utf8");
-            mode = fs.lstatSync(file).mode;
+            const at=fs.lstatSync(file);
+            if(!at.isFile()) return {ok:false,snapshots,reason:`${file} is not a regular file`};
+            if(edit.nested && edit.next!==null && at.nlink!==1) return {ok:false,snapshots,reason:`${file} is a multiply linked guidance output`};
+            previous = readOutput(file,root);
+            const after=fs.lstatSync(file);
+            if(after.dev!==at.dev||after.ino!==at.ino||after.mode!==at.mode)return {ok:false,snapshots,reason:`${file} changed while its original was read`};
+            mode=at.mode;observedIdentity={dev:at.dev,ino:at.ino,mode:at.mode};
         } catch (error) {
             if (error.code !== "ENOENT") {
                 return { ok: false, snapshots, reason: `${file} could not be read before writing — ${error.code ?? error.message}` };
             }
         }
 
+        if (Object.hasOwn(edit,"before") && !sameContent(previous,edit.before)) return {ok:false,snapshots,reason:`${file} changed after guidance planning`};
+        if(edit.beforeIdentity){const at=fs.lstatSync(file,{throwIfNoEntry:false});if(!at||at.dev!==edit.beforeIdentity.dev||at.ino!==edit.beforeIdentity.ino||at.mode!==edit.beforeIdentity.mode)return {ok:false,snapshots,reason:`${file} changed identity after source planning`};}
         if (edit.next === null) {
             if (previous === null) continue;
             if (!fs.lstatSync(file).isFile()) return { ok: false, snapshots, reason: `${file} is not a regular file — refusing to delete it` };
             try {
-                fs.rmSync(file);
+                guardedRemove(file,{before:previous,identity:edit.beforeIdentity??observedIdentity,allowLinks:Boolean(edit.claimBase),claimBase:edit.claimBase,onClaim:data=>options.journal?.(edit,"claim",data),onRemove:claim=>{snapshots.push({file:edit.file,root:edit.root,previous,mode,created:[],deleted:true,after:null,identity:null,cleanup:[claim]});options.journal?.(edit,"retired",claim);}});
             } catch (error) {
                 return { ok: false, snapshots, reason: `${file} could not be deleted — ${error.code ?? error.message}` };
             }
-            snapshots.push({ file: edit.file, root: edit.root, previous, mode, created: [], deleted: true });
             continue;
         }
 
-        // `lstat`, not `existsSync`, which follows links and answers `false` for a path it could not read.
+        // lstat distinguishes links and unreadable paths from absence.
         const wanted = [];
         for (let at = path.dirname(file); at.startsWith(root) && at !== root; at = path.dirname(at)) {
             try {
@@ -330,7 +339,7 @@ export function applyEdits(dir, edits, options = {}) {
             }
         }
 
-        // No snapshot owns these until the rename lands, so every failure before it unwinds them.
+        // Unwind this edit's created directories if publication fails.
         const created = [];
         try {
             for (const dir of wanted) {
@@ -338,7 +347,7 @@ export function applyEdits(dir, edits, options = {}) {
                     fs.mkdirSync(dir);
                     created.push(dir);
                 } catch (error) {
-                    // Made by another since the probe: fine if a directory, and not this run's to remove.
+                    // A concurrently created directory is not ours to remove.
                     if (error.code !== "EEXIST" || !fs.lstatSync(dir).isDirectory()) throw error;
                 }
             }
@@ -347,24 +356,17 @@ export function applyEdits(dir, edits, options = {}) {
             return { ok: false, snapshots, reason: `${path.dirname(file)} could not be created — ${error.code ?? error.message}` };
         }
 
-        // Unique per process and edit, and beside its file so the rename stays atomic.
+        // Stage each edit beside its target for exclusive publication.
         const staging = `${file}.portulan-upgrade.${process.pid}.${stagingSeq++}`;
+        let published;
         try {
-            // `wx`: anything already at the staging path, a planted symlink included, fails rather than being followed.
-            write(staging, edit.next, { flag: "wx" });
+            // Exclusive creation refuses existing files and symlinks.
             const keep = mode ?? edit.mode ?? null;
-            if (keep !== null) fs.chmodSync(staging, keep);
-            fs.renameSync(staging, file);
+            published=atomicWrite(file,edit.next,{exclusive:edit.exclusive??previous===null,before:previous,identity:edit.beforeIdentity??observedIdentity??undefined,mode:keep,write,stagingPath:edit.nested?undefined:staging,onPrepare:data=>options.journal?.(edit,"stage",data),onClaim:data=>options.journal?.(edit,"claim",data),onCleanupClaim:data=>options.journal?.(edit,"undo-claim",data),onPublish:(id,cleanup)=>snapshots.push({file:edit.file,root:edit.root,previous,mode,created,after:edit.next,identity:{dev:id.dev,ino:id.ino,mode:id.mode},cleanup})});
         } catch (error) {
-            try {
-                fs.rmSync(staging, { force: true });
-            } catch {
-                /* the staging file is the lesser problem; the write failure is what gets reported */
-            }
             unwindDirs(created);
             return { ok: false, snapshots, reason: `${file} could not be written — ${error.code ?? error.message}` };
         }
-        snapshots.push({ file: edit.file, root: edit.root, previous, mode, created });
     }
     return { ok: true, snapshots };
 }
@@ -374,9 +376,12 @@ export function restore(dir, snapshots, options = {}) {
     const treeRoot = typeof options.treeDir === "string" ? path.resolve(options.treeDir) : null;
     const restored = [];
     const failed = [];
-    // Last edit first: a directory two edits share is recorded on the first, and empties only after the second.
+    const restoredIdentities=new Map();
+    // Reverse order empties shared directories before their owner removes them.
     for (const snapshot of [...snapshots].reverse()) {
-        // Contained again, as `restore` is exported and a snapshot may come from any caller.
+        if(options.stopOnFailure&&failed.length){failed.push(snapshot.file);continue;}
+        try{options.beforeMutation?.(snapshot);}catch{failed.push(snapshot.file);continue;}
+        // Exported restore must recheck containment of caller-supplied snapshots.
         const root = snapshot.root === "tree" ? treeRoot : workspaceRoot;
         const file = root === null ? null : inside(root, snapshot.file);
         if (file === null || linkOnPath(root, file) !== null) {
@@ -384,15 +389,27 @@ export function restore(dir, snapshots, options = {}) {
             continue;
         }
         try {
+            for(const item of snapshot.cleanup??[])if(typeof item.file!=="string"||inside(root,path.relative(root,item.file))!==item.file||linkOnPath(root,item.file)!==null)throw new UpgradeError("cleanup journal is outside its transaction root or aliases another path");
+            const at=fs.lstatSync(file,{throwIfNoEntry:false});
+            const aliases=(snapshot.cleanup??[]).filter(item=>{try{const linked=fs.lstatSync(item.file);return linked.isFile()&&linked.dev===at?.dev&&linked.ino===at?.ino&&sameContent(readOutput(item.file,root),item.before);}catch{return false;}});
+            const allowLinks=Boolean(at&&at.nlink>1&&at.nlink===aliases.length+1);
+            if(at && (!at.isFile() || at.isSymbolicLink() || (at.nlink!==1&&!allowLinks))) throw new UpgradeError(`${file} is not an ordinary singly linked restore target`);
+            const current=at ? readOutput(file,root) : null;
+            if(Object.hasOwn(snapshot,"after")) {
+                const expected=restoredIdentities.has(file) ? restoredIdentities.get(file) : snapshot.identity;
+                if(!sameContent(current,snapshot.after) || (expected && (!at || at.dev!==expected.dev || at.ino!==expected.ino || (expected.mode!==undefined&&at.mode!==expected.mode)))) throw new UpgradeError(`${file} changed since this transaction wrote it`);
+            }
+            let replacedIdentity=null;
             if (snapshot.previous === null) {
-                fs.rmSync(file, { force: true });
-                unwindDirs(snapshot.created ?? []);
+                if(at)guardedRemove(file,{before:current,identity:{dev:at.dev,ino:at.ino,mode:at.mode},allowLinks,onClaim:data=>options.journal?.(snapshot,"undo-claim",data),onRemove:claim=>options.journal?.(snapshot,"retired",claim)});
             } else {
-                const at = fs.lstatSync(file, { throwIfNoEntry: false });
-                if (at?.isSymbolicLink()) throw new UpgradeError(`${file} is a symlink — refusing to restore through it`);
-                fs.writeFileSync(file, snapshot.previous);
-                if (snapshot.mode !== null && snapshot.mode !== undefined) fs.chmodSync(file, snapshot.mode);
+                replacedIdentity=atomicWrite(file,snapshot.previous,{exclusive:!at,before:current,identity:at ? {dev:at.dev,ino:at.ino,mode:at.mode} : undefined,allowLinks,mode:snapshot.mode,onPrepare:data=>options.journal?.(snapshot,"undo-stage",data),onClaim:data=>options.journal?.(snapshot,"undo-claim",data),onCleanupClaim:data=>options.journal?.(snapshot,"claim",data)});
             }
+            for(const item of snapshot.cleanup??[])if(fs.lstatSync(item.file,{throwIfNoEntry:false}))guardedRemove(item.file,{before:item.before,identity:item.identity,allowLinks:true,claimBase:path.basename(file)});
+            if(snapshot.previous===null)unwindDirs(snapshot.created??[]);
+            const replaced=fs.lstatSync(file,{throwIfNoEntry:false});
+            if(replacedIdentity?(!replaced||replaced.dev!==replacedIdentity.dev||replaced.ino!==replacedIdentity.ino||replaced.mode!==replacedIdentity.mode):Boolean(replaced))throw new UpgradeError(`${file} changed during rollback publication`);
+            restoredIdentities.set(file,replacedIdentity);
             restored.push(snapshot.file);
         } catch {
             failed.push(snapshot.file);
@@ -497,7 +514,7 @@ export async function run(argv = [], options = {}) {
         return 2;
     }
 
-    // ---- which workspace, and in which residence
+    // Resolve target and residence.
     const target = await resolveTarget(positional[0], { env });
     if (target.state === "could-not-look") {
         warn(`upgrade: ${target.sentence}`);
@@ -524,6 +541,7 @@ export async function run(argv = [], options = {}) {
         return read.code;
     }
     const ws = read.ws;
+    try{assertNoSourceJournal(ws.dir);if(ws.repository)assertNoSourceJournal(ws.repository.dir);}catch(error){warn(`upgrade: ${error.message}`);return 2;}
     const relative = path.relative(process.cwd(), ws.dir);
     const shown = relative && relative.length < ws.dir.length ? relative : ws.dir;
 
@@ -533,7 +551,7 @@ export async function run(argv = [], options = {}) {
         for (const line of offerLines()) say(`upgrade: ${line}`);
     };
 
-    // ---- which direction is this workspace off in
+    // Classify version drift.
     const declared = /^([0-9]+)\.([0-9]+)$/.exec(ws.manifest?.portulan?.spec ?? "");
     if (!declared) {
         warn(`upgrade: ${shown} declares no readable \`portulan.spec\` — refusing to guess which contract it was written against`);
@@ -551,7 +569,7 @@ export async function run(argv = [], options = {}) {
         return 2;
     }
 
-    // ---- the pre-state gate, which can only ever apply to a gradeable workspace
+    // Pre-state gate requires a gradeable workspace.
     if (!behindByMajor) {
         let pre;
         try {
@@ -572,7 +590,7 @@ export async function run(argv = [], options = {}) {
         }
     }
 
-    // ---- the plan
+    // Plan.
     const ctx = { bundle: BUNDLE, spec, tree, today: options.today ?? new Date().toISOString().slice(0, 10) };
     const plan = await planFor(ws, ctx, steps);
 
@@ -622,10 +640,10 @@ export async function run(argv = [], options = {}) {
         return 0;
     }
 
-    // ---- apply, one step at a time, re-reading between them
+    // Apply and reread after each step.
     let snapshots = [];
     let current = ws;
-    // A step may declare the tree but none moves it, so every snapshot was made in the latest one.
+    // Steps can declare a tree, but never move it.
     let treeDir = ws.repository?.dir ?? null;
     const undo = () => {
         const result = restore(current.dir, snapshots, { treeDir });
@@ -640,7 +658,7 @@ export async function run(argv = [], options = {}) {
     const byHand = new Map();
     const apply = async (entry) => {
         applied.add(entry.step.id);
-        // A step's `plan` is foreign code: a throw becomes a refusal, so the rollback still runs.
+        // Foreign plan failures must reach rollback.
         let planned;
         try {
             planned = await entry.step.plan(current, ctx);
@@ -677,7 +695,7 @@ export async function run(argv = [], options = {}) {
         treeDir = current.repository?.dir ?? treeDir;
         return null;
     };
-    // A step can make an earlier one owed, so the chain is asked again until a pass applies nothing.
+    // Revisit earlier steps until a pass applies nothing.
     for (let pass = 0; ; pass++) {
         let appliedNow = 0;
         for (const entry of plan.entries) {
@@ -712,7 +730,7 @@ export async function run(argv = [], options = {}) {
         }
     }
 
-    // ---- and grade what it produced, with the real validator
+    // Grade with the real validator.
     let post;
     try {
         post = await inspect(current.dir);