create-wxl 3.0.0 → 3.1.0

package/bin/create-wxl.mjs

@@ -67,6 +67,7 @@ async function main() {
   const { dirname, join } = await import('node:path')
   const fsp = await import('node:fs/promises')
   const { readFile } = fsp
+  const { tmpdir } = await import('node:os')
 
   const { run } = await import('../src/run.mjs')
   const { createSpawnGitRunner } = await import('../src/git-runner.mjs')
@@ -106,6 +107,7 @@ async function main() {
       return { status: response.status, body }
     },
     downloadTimeoutMs: 120000,
+    tmpRoot: tmpdir(),
     runGit: createSpawnGitRunner(),
     fs: fsp,
     // `process` itself is `deps.signals` (the seam's own dependency list, traceability.md

package/dist/fork-init.mjs

@@ -18,19 +18,19 @@
  *   (the base definition) to its upstream form from deployment; --base only applies without
  *   --host, and writes A9 as a literal.
  *
- *   --origin sets the short-link origin (A8); --host github-pages derives it when --origin is
- *   not given (required with --host cloudflare-pages). --site-name sets the site title (A6) and
- *   both home pages' hero name (A7). --rebrand cannot be combined with --host, --origin or
- *   --site-name (A mode's new flags are rejected in B mode).
+ *   --origin sets the range address, the origin of every copied link (A8); --host github-pages
+ *   derives it when --origin is not given (required with --host cloudflare-pages). --site-name
+ *   sets the site title (A6) and both home pages' hero name (A7). --rebrand cannot be combined
+ *   with --host, --origin or --site-name (A mode's new flags are rejected in B mode).
  *
  * Modes:
  *   A (default)          rewrites only the identity anchors (traceability.md's A1-A9):
  *                        the manifest (structured), the doc-anchor forms in README.md,
  *                        README.en.md and CONTRIBUTE.md — wherever they occur, whatever
  *                        repository slug they held — A9 (the base definition), A6/A7 (the site
- *                        name, from --site-name), A8 (the short-link origin, from --origin or
- *                        derived), and the deploy workflow (chosen by --host). No tree walk;
- *                        every other file is byte-identical.
+ *                        name, from --site-name), A8 (the range address, the origin of every
+ *                        copied link, from --origin or derived), and the deploy workflow (chosen
+ *                        by --host). No tree walk; every other file is byte-identical.
  *   B (--rebrand <name>) today's path: walks the whole tree doing the upstream-slug swap and
  *                        also renames the four runtime-sensitive keys (deterministic,
  *                        structure-aware), plus an HONEST residual inventory of every
@@ -848,12 +848,12 @@ function sensitiveRenames(lower        , upper        )
   ]
 }
 
-// ─── A6-A8 (site name, short-link origin): anchor mode only — never reached in rebrand mode,
+// ─── A6-A8 (site name, range address): anchor mode only — never reached in rebrand mode,
 // since --rebrand rejects --host/--origin/--site-name (T50) ───────────────────────────────────
 
 const PLATFORM_HOME_RELS = ['platform/index.md', 'platform/zh-TW/index.md']         
 const SHORT_LINK_REL = '.vitepress/challenge/shortLink.ts'
-/** The upstream short-link origin (traceability.md, T81): replacing a value that is not this one
+/** The upstream range address, SITE_ORIGIN (traceability.md, T81): replacing a value that is not this one
  *  warns; a run that starts from this one never does. */
 const UPSTREAM_SITE_ORIGIN = 'https://wxl.browserlab.online'
 
@@ -1079,7 +1079,7 @@ function a7LineFor(line        , newLiteral        )         {
 }
 
 /** `https://<owner, lowercased>.github.io[/<name as given>]` (traceability.md, T36-T37): the
- *  derived short-link origin for `--host github-pages` without `--origin`, omitting the path for
+ *  derived range address for `--host github-pages` without `--origin`, omitting the path for
  *  the user site `<owner>.github.io` (compared case-insensitively). `repo` must already have passed
  *  parseForkInitArgs's `owner/name` check (T45); create-wxl calls it only after a successful parse. */
 export function deriveGithubPagesOrigin(repo        )         {
@@ -1361,7 +1361,7 @@ export function runForkInit(
     } else {
       // ── A mode: only the identity anchors (A1–A9, traceability.md) and the workflow — the doc
       //   anchors (A2–A5), the config's A9 line, A6 (site title) and A7 (home-page hero name) when
-      //   --site-name is given, and A8 (short-link origin) when --origin is given or derived. No
+      //   --site-name is given, and A8 (range address) when --origin is given or derived. No
       //   tree walk — every file outside A1–A9 and the workflow is byte-identical (T3).
       //
       //   Every CHECKED read/content computation below happens before anything is written —
@@ -1450,7 +1450,7 @@ export function runForkInit(
         }
       }
 
-      // ── A8 (short-link origin): --origin, or derived from --host github-pages without
+      // ── A8 (range address): --origin, or derived from --host github-pages without
       //   --origin (T32-T38/T81/AC-O1-AC-O2). Read byte-preserving (latin1) (T4); the write
       //   decision compares the WHOLE LINE about to be written against the existing one, not just
       //   the decoded value (T8: a same-VALUE line in a different quote style is still rewritten
@@ -1478,13 +1478,14 @@ export function runForkInit(
         if (line !== newLine) {
           const oldValue = evalJsStringLiteral(valueMatch[1])
           if (oldValue !== finalOrigin && oldValue !== UPSTREAM_SITE_ORIGIN) {
-            // T81/AC-O2: replacing a short-link origin that is not upstream's warns — the engine
+            // T81/AC-O2: replacing a range address that is not upstream's warns — the engine
             // keeps no state, so it cannot otherwise tell a fork's own custom domain from one that
             // should be silently kept. Compares the DECODED value: a line rewritten only to
             // normalise its quoting (the same value, differently quoted) never warns.
             warnings.push(
               `A8: ${SHORT_LINK_REL} changes from ${JSON.stringify(oldValue)} to ${JSON.stringify(finalOrigin)} — ` +
-                `a custom short-link origin is replaced only when --origin (or a derived GitHub Pages origin) says so.`,
+                `a custom range address (SITE_ORIGIN, the origin of every copied link) is replaced only when ` +
+                `--origin (or a derived GitHub Pages origin) says so.`,
             )
           }
           const nextLines = lines.slice()

package/dist/source.json

@@ -1,6 +1,6 @@
 {
   "repository": "BrowserLaboratory/wxl-platform",
-  "version": "3.0.0",
-  "commit": "52192fa85fe7c6c7bf4cecb4c287d6f2876387a4",
-  "engineSha256": "691937dc55f28cc78e581d66b77f3eb16a34e2bc2ea56b1a83df9bba95f3a035"
+  "version": "3.1.0",
+  "commit": "b4d3fd0e0c46f5c872e7f680e5401f8a8d8c5f60",
+  "engineSha256": "d67a3403bada3d3c8ec9a22d8c43e3e07a99018ab2662cd9e740dd2c7772d61a"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-wxl",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Create a Web eXploitation Laboratory range",
   "type": "module",
   "bin": { "create-wxl": "bin/create-wxl.mjs" },

package/src/archive-rules.mjs

@@ -9,6 +9,8 @@
 // list (first component stripped, classified kind) so step 8 writes from the SAME validated data,
 // never re-deriving a path or kind from `tar`'s own, un-stripped fields (C-01).
 
+import { foldAsciiCase } from './text.mjs'
+
 export class ArchiveRuleError extends Error {
   constructor(rule, path, { isCommentMarker = false } = {}) {
     super(`archive entry rule ${rule} broken${path === undefined ? '' : ` at ${path}`}`)
@@ -49,12 +51,23 @@ function checkFirstComponent(component, headerPath) {
   }
 }
 
+/** 0005 revision 2.2 (D13, T-0062): a component git itself treats as `.git`. Compared ignoring
+ * ASCII case only (as git's own `tolower` does -- not JavaScript's Unicode-aware `/i`): either
+ * `.git` or `git~1`, then any run of `.` and spaces, then nothing or `:` and anything (git's
+ * `is_ntfs_dotgit`); or `.git` once every HFS+ ignorable code point is removed, wherever it occurs
+ * (git's `is_hfs_dotgit`). Other short names (`PLATFO~1`, `GITIGN~1`) are not `.git`. */
+const HFS_IGNORABLE_RE = /[\u200c-\u200f\u202a-\u202e\u206a-\u206f\ufeff]/g
+const NTFS_DOTGIT_RE = /^(?:\.git|git~1)[. ]*(?::.*)?$/s
+function isGitAlias(component) {
+  return NTFS_DOTGIT_RE.test(foldAsciiCase(component)) || foldAsciiCase(component.replace(HFS_IGNORABLE_RE, '')) === '.git'
+}
+
 function checkComponents(relPath, headerPath) {
   if (relPath.includes('\\')) throw new ArchiveRuleError(3, headerPath)
   for (const component of relPath.split('/')) {
     if (component === '') throw new ArchiveRuleError(3, headerPath)
     if (component === '.' || component === '..') throw new ArchiveRuleError(3, headerPath)
-    if (component.toLowerCase() === '.git') throw new ArchiveRuleError(3, headerPath)
+    if (isGitAlias(component)) throw new ArchiveRuleError(3, headerPath)
     if (component.endsWith('.') || component.endsWith(' ')) throw new ArchiveRuleError(3, headerPath)
     if (CONTROL_CHAR_RE.test(component)) throw new ArchiveRuleError(3, headerPath)
   }
@@ -113,8 +126,11 @@ function checkCollisionAgainstSeen(entry, seen) {
  * breaking entry in archive order (D4: the path named is the entry's header path exactly as it
  * appears in the archive, including the first component), and returning the enriched list (each
  * entry's own fields plus `firstComponent`, `rest`, `kind`) for step 8 to write from directly.
- * `commit` is the commit requested (create-wxl always downloads by commit, so rule 2's comment
- * check always applies).
+ * `commit` is the commit rule 2's comment check compares against: the commit requested for a
+ * download by commit (create, a `--from <commit>` base, the upgrade's target), or, for a tag
+ * download (a `--from <version>` base, a base read from `range.json`), the tag archive's own
+ * comment once `readArchiveEntries` has checked it (UP-E08, and J6's UP-E12); for publishing's own
+ * check of the local archive (`publish.mjs`, X7), the commit at `HEAD`.
  */
 export function checkEntryRules({ entries, comment }, { commit }) {
   // S-04: rule 5 (no file in the list) is checked after rule 2's comment, and the comment

package/src/argv.mjs

@@ -1,6 +1,8 @@
 // Command grammar (traceability.md "Command grammar"): `parseArgvStrict` is the full grammar.
 // The `--no-setup` + setup-flag rule (C03) is checked separately by `run.mjs`.
 
+import { VERSION_RE, COMMIT_RE } from './patterns.mjs'
+
 export class ArgvError extends Error {
   constructor(token, { usage = false, reason = 'unknown' } = {}) {
     super(`invalid argument: ${token}`)
@@ -15,10 +17,13 @@ const VALUE_FLAGS = new Set(['--author', '--repo', '--host', '--origin', '--site
 export const SETUP_FLAG_NAMES = ['author', 'repo', 'host', 'origin', 'site-name']
 
 export function parseArgvStrict(argv) {
-  const result = { directory: undefined, noSetup: false, lang: undefined, flags: {} }
+  const result = { directory: undefined, noSetup: false, lang: undefined, flags: {}, mode: undefined }
   const seen = new Set()
   let positionalCount = 0
   let endOfFlags = false
+  // U02: every create-only flag seen, in argv order, whether before or after `upgrade` -- checked
+  // once the loop ends (below), once `mode` is known for certain.
+  const createOnlyFlagsSeen = []
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
@@ -45,10 +50,42 @@ export function parseArgvStrict(argv) {
         if (eq !== -1) throw new ArgvError(arg)
         if (seen.has('--no-setup')) throw new ArgvError(arg, { reason: 'repeated' })
         seen.add('--no-setup')
+        createOnlyFlagsSeen.push('--no-setup')
         result.noSetup = true
         continue
       }
 
+      // Command grammar: "`--from` after `upgrade` only" (decision (2)) -- recognised only once
+      // `upgrade` has already been read as the mode, using the same value-flag shape every other
+      // VALUE_FLAGS member uses (repeated/missing-value/inline `=`); its value goes to
+      // `result.from`, never `result.flags`, so it can never reach `buildEngineArgv`. Anywhere
+      // else (before `upgrade`, or on the create path) it falls through to the unknown-flag throw
+      // below, unchanged.
+      if (name === '--from' && result.mode === 'upgrade') {
+        if (seen.has('--from')) throw new ArgvError('--from', { reason: 'repeated' })
+        seen.add('--from')
+
+        let fromValue
+        if (eq !== -1) {
+          if (inlineValue === '') throw new ArgvError('--from', { reason: 'missing-value' })
+          fromValue = inlineValue
+        } else {
+          const next = argv[i + 1]
+          if (next === undefined || next.startsWith('-')) {
+            throw new ArgvError('--from', { reason: 'missing-value' })
+          }
+          fromValue = next
+          i++
+        }
+        // Command grammar: "`<version>` matches ... `<commit>` matches ...; any other `--from`
+        // value ... -> CW-E02" -- named by the value itself, not by "--from" (U02).
+        if (!VERSION_RE.test(fromValue) && !COMMIT_RE.test(fromValue)) {
+          throw new ArgvError(fromValue)
+        }
+        result.from = fromValue
+        continue
+      }
+
       if (!VALUE_FLAGS.has(name)) throw new ArgvError(arg)
       if (seen.has(name)) throw new ArgvError(name, { reason: 'repeated' })
       seen.add(name)
@@ -73,17 +110,37 @@ export function parseArgvStrict(argv) {
         result.lang = value
       } else {
         result.flags[name.slice(2)] = value
+        createOnlyFlagsSeen.push(name)
       }
       continue
     }
 
     // positional
     if (arg === '') throw new ArgvError(arg)
-    if (arg === 'upgrade') throw new ArgvError(arg)
+    // U02: once `upgrade` has been read, any further positional (another directory-shaped
+    // argument, or `upgrade` again) is rejected by its own literal token -- the upgrade path never
+    // takes a directory argument.
+    if (result.mode === 'upgrade') throw new ArgvError(arg)
+    // Command grammar: "chosen when the first positional argument is `upgrade`" -- Q2's reading
+    // (the first positional's literal covers one after `--` too) makes this check come before the
+    // positional count, not folded into it: a later `upgrade` (positionalCount > 0) falls through
+    // to the ordinary positional handling below, so `['range', 'upgrade']` still fails on the
+    // second-positional check with token "upgrade".
+    if (arg === 'upgrade' && positionalCount === 0) {
+      result.mode = 'upgrade'
+      continue
+    }
     positionalCount++
     if (positionalCount > 1) throw new ArgvError(arg)
     result.directory = arg
   }
 
+  // Command grammar: "a create-only flag (...) -> CW-E02" -- checked once `mode` is known for
+  // certain, so a create-only flag given BEFORE `upgrade` is caught too (U02's 2026-11-07
+  // sub-case), named by whichever such flag argv gave first.
+  if (result.mode === 'upgrade' && createOnlyFlagsSeen.length > 0) {
+    throw new ArgvError(createOnlyFlagsSeen[0])
+  }
+
   return result
 }

package/src/base-version.mjs

@@ -0,0 +1,10 @@
+// D2 (10): the oldest base version this tool upgrades (traceability.md "Decisions", "Step order"
+// row 6). `MINIMUM_BASE_VERSION` is the numeric form `upgrade.mjs`'s own comparison uses;
+// `MINIMUM_BASE_VERSION_TEXT` is the one string both message tables print for UP-E10 (S-10: one
+// source with the actual check, not a literal "3.0.0" repeated in both tables) -- mirroring
+// `git-version.mjs`'s `MINIMUM_GIT_VERSION`/`messages.mjs`'s own `MINIMUM_GIT_VERSION_TEXT` pair.
+// Lives in its own module, not in `upgrade.mjs`, so `messages.mjs` can import this constant
+// without a cycle.
+
+export const MINIMUM_BASE_VERSION = [3, 0, 0]
+export const MINIMUM_BASE_VERSION_TEXT = MINIMUM_BASE_VERSION.join('.')

package/src/git-named.mjs

@@ -0,0 +1,43 @@
+// D19 (traceability.md revision 3.1; T-0061, moved here in T-0062 so step 8 shares it): runs one
+// git command and, when `runGit` rejects (not an exit code -- the spawn itself failed), rethrows it
+// as a bug whose message names the command, so CW-E14 says which git command failed. A signal
+// already received, or a `SignalAbort`, passes through unchanged so the run still exits 130.
+
+import { SignalAbort } from './signals.mjs'
+import { buildGitEnv } from './git-env.mjs'
+
+export async function runGitNamed(deps, guard, args, opts, name) {
+  try {
+    return await deps.runGit(args, opts)
+  } catch (err) {
+    if (err instanceof SignalAbort) throw err
+    guard.throwIfRaised()
+    throw new Error(`git ${name} failed: ${err?.message ?? String(err)}`, { cause: err })
+  }
+}
+
+/** P-5 and D15 (traceability.md "Pre-checks", step 5; Vocabulary's own "ignored path" -- "a path
+ * that is not tracked and that `git check-ignore -q --no-index -- ./<path>` reports as ignored by
+ * the range's rules"); shared by both since T-0062 (S1). `check-ignore`'s own exit codes are 0
+ * (ignored) and 1 (not ignored); any other exit code, or a `runGit` rejection, is a bug naming the
+ * command -- fail closed (D6, D19), never silently read as either answer. Called only for a path
+ * the caller has already found untracked (a force-added, tracked file that also matches an ignore
+ * rule is never P-5, and never D15). */
+export async function isIgnoredPath(deps, guard, rangeRoot, path) {
+  // `./` keeps the path literal: `check-ignore` refuses every pathspec magic (`--literal-pathspecs`
+  // included), and a path starting with `:` would otherwise be read as magic and check another path.
+  const name = `check-ignore -- ./${path}`
+  const result = await runGitNamed(
+    deps,
+    guard,
+    ['check-ignore', '-q', '--no-index', '--', `./${path}`],
+    { cwd: rangeRoot, env: buildGitEnv(deps.env) },
+    name,
+  )
+  // A signal this process already received while that `runGit` call was in flight wins over
+  // interpreting its result, the same way `runMergeFile` already does.
+  guard.throwIfRaised()
+  if (result.code === 0) return true
+  if (result.code === 1) return false
+  throw new Error(`git ${name} failed (exit code ${result.code}): ${result.stderr}`)
+}

package/src/git-runner.mjs

@@ -65,12 +65,16 @@ function resolveGitPath(env, cwd, platform) {
   return null
 }
 
-/** Returns a `runGit(args, { cwd, env })` function matching `deps.runGit`'s contract: resolves to
- * `{ code, stdout, stderr }`, or rejects (ENOENT when `git` cannot be resolved from `PATH`, or
- * whatever `child_process.spawn`'s own `error` event reports). `platform` (default
- * `process.platform`) is injectable so tests can exercise the win32 lookup on any host. */
+/** Returns a `runGit(args, { cwd, env, binary })` function matching `deps.runGit`'s contract:
+ * resolves to `{ code, stdout, stderr }`, or rejects (ENOENT when `git` cannot be resolved from
+ * `PATH`, or whatever `child_process.spawn`'s own `error` event reports). `platform` (default
+ * `process.platform`) is injectable so tests can exercise the win32 lookup on any host. T-0027
+ * (D4, increment 25): `binary` (default falsy; every existing call site is unaffected) keeps
+ * `stdout` as a `Buffer` -- `git merge-file -p`'s own output is the one caller (`merge-plan.mjs`)
+ * that cannot afford the string-decoding path below silently replacing an invalid UTF-8 byte
+ * sequence (a non-UTF-8 text file, e.g. Big5) with U+FFFD before it is ever written back. */
 export function createSpawnGitRunner({ platform = process.platform } = {}) {
-  return function runGit(args, { cwd, env }) {
+  return function runGit(args, { cwd, env, binary = false }) {
     return new Promise((resolvePromise, reject) => {
       const gitPath = resolveGitPath(env, cwd, platform)
       if (!gitPath) {
@@ -86,20 +90,29 @@ export function createSpawnGitRunner({ platform = process.platform } = {}) {
         reject(err)
         return
       }
-      // A multibyte UTF-8 character can land split across two `data` events; decoding each
-      // chunk on its own (`stdout += chunk`) would mangle it, so each stream gets its own
-      // stateful decoder instead (`setEncoding` buffers an incomplete trailing sequence until
-      // the rest arrives).
-      child.stdout.setEncoding('utf8')
+      // stderr is always decoded as text (a multibyte UTF-8 character can land split across two
+      // `data` events; `setEncoding` buffers an incomplete trailing sequence until the rest
+      // arrives, decoding each chunk on its own would mangle it). stdout does the same UNLESS
+      // `binary` asks for the raw bytes instead, accumulated as `Buffer` chunks and concatenated
+      // once on `close` -- never `setEncoding('utf8')`, which would already have thrown away the
+      // original bytes by the time `close` fires.
       child.stderr.setEncoding('utf8')
-      let stdout = ''
       let stderr = ''
-      child.stdout.on('data', (chunk) => {
-        stdout += chunk
-      })
       child.stderr.on('data', (chunk) => {
         stderr += chunk
       })
+      if (binary) {
+        const stdoutChunks = []
+        child.stdout.on('data', (chunk) => stdoutChunks.push(chunk))
+        child.on('error', (err) => reject(err))
+        child.on('close', (code) => resolvePromise({ code, stdout: Buffer.concat(stdoutChunks), stderr }))
+        return
+      }
+      child.stdout.setEncoding('utf8')
+      let stdout = ''
+      child.stdout.on('data', (chunk) => {
+        stdout += chunk
+      })
       child.on('error', (err) => reject(err))
       child.on('close', (code) => resolvePromise({ code, stdout, stderr }))
     })

package/src/git-version.mjs

@@ -1,12 +1,14 @@
-// G0 (traceability.md "Git steps"): `git --version` must report 2.20 or later. `git --version`'s
+// G0 (traceability.md "Git steps"): `git --version` must report 2.26 or later (0006's D21, 0005
+// revision 2.3: before 2.26 git runs `core.fsmonitor=true` as a hook and may report no changes, and
+// before 2.25.2 `git check-ignore` ignores `!` re-inclusions). `git --version`'s
 // own output is `git version <major>.<minor>.<patch>[<anything>]` (a Homebrew/Xcode suffix like
 // `(Apple Git-154)`, or a Windows suffix like `.windows.1`); only the leading `\d+\.\d+(\.\d+)?` is
 // read, compared with `numeric-version.mjs`'s shared helper (S-11) so `2.9.5` is not mistaken
-// for newer than `2.20.0`.
+// for newer than `2.26.0`.
 
 import { isAtLeast } from './numeric-version.mjs'
 
-export const MINIMUM_GIT_VERSION = [2, 20]
+export const MINIMUM_GIT_VERSION = [2, 26]
 
 const VERSION_PREFIX_RE = /^git version (\d+)\.(\d+)(?:\.(\d+))?/
 

package/src/merge-apply.mjs

@@ -0,0 +1,156 @@
+// Step 9 (traceability.md "Step order" row 9): deletions first, then writes, in sorted path
+// order; each write goes to a new file in the destination directory, then renamed over the
+// destination, creating any missing parent directory first. traceability.md "Merge table" M5: a
+// brand-new path takes `op.newFileExecutable`'s own bit (under the process's own umask, through
+// the ordinary `writeFile` mode option); an existing path keeps ITS OWN current mode --
+// write-then-rename always creates a new inode, so that mode is never carried forward for free,
+// hence the explicit `lstat`-then-`chmod` here (T-0027 increment 7). T-0027 increment 10 (U27):
+// a real file-system error on any delete or write is reported as `{ ok: false, path, detail }`
+// instead of propagating as a bug (CW-E14); the half-written temp file, if any, is unlinked
+// first. T-0027 increment 11 (U28): `guard` is checked after every successful operation (delete
+// or write) -- traceability.md "Codes" UP-E09: a signal already raised there stops the loop
+// before the next operation starts and before `range.json` is ever rewritten, reported as
+// `{ ok: false, signal }`.
+
+import { randomBytes } from 'node:crypto'
+import { dirname, join } from 'node:path'
+
+/** A dotfile alongside the destination, inside the same directory (so the final `rename` is
+ * same-device): `.create-wxl-upgrade-tmp-<16 random hex chars>`, a FIXED LENGTH never growing
+ * with the destination's own basename -- a brand-new path whose own basename is already close to
+ * `NAME_MAX` must not fail with `ENAMETOOLONG` only because of space this temporary name added on
+ * top of it. The random part alone still keeps every concurrent write
+ * (in the same destination directory, in the same run) its own temporary name; a FIXED name with
+ * no random part at all could already exist -- an ignored file the teacher has, or a symbolic
+ * link -- and the write loop's own `writeFile`, below, uses `flag: 'wx'` (never the default
+ * `'w'`) so it refuses to create over whatever that existing name turns out to be, instead of
+ * silently truncating it or following a symlink through it. */
+function tempPathFor(rangeRoot, path) {
+  const parts = path.split('/')
+  const last = parts.pop()
+  const dest = join(rangeRoot, ...parts, last)
+  const tmp = join(rangeRoot, ...parts, `.create-wxl-upgrade-tmp-${randomBytes(8).toString('hex')}`)
+  return { dest, tmp }
+}
+
+/** `range.json` after the plan (traceability.md "`range.json` after the plan", T-0027 increment
+ * 8): read the current file (or start from `{}`), replace `upstream`'s value with `upstream`
+ * (keeping every other top-level key and the order of keys -- `upstream` keeps its own position,
+ * or is first when added), two-space indent, one trailing LF. */
+function buildRangeJson(current, upstream) {
+  if (Object.prototype.hasOwnProperty.call(current, 'upstream')) {
+    const next = {}
+    // R-6 (T-0063): define each key as the object's own, as `JSON.parse` did -- a plain assignment
+    // of a `__proto__` key would set `next`'s prototype instead, and the key would be lost.
+    for (const key of Object.keys(current)) {
+      Object.defineProperty(next, key, {
+        value: key === 'upstream' ? upstream : current[key],
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      })
+    }
+    return next
+  }
+  return { upstream, ...current }
+}
+
+/** `range.json`'s own write (the last of step 9) goes through the
+ * same write-then-rename, file-system-error-vs-bug and signal handling as every other write in
+ * the loop below -- a failure here has already deleted/written every other op, so the range may
+ * be partially changed exactly the same way, and needs the same `UP-E09` + restore commands,
+ * not `CW-E14`. Returns `{ ok: true }`, or `{ ok: false, path: 'range.json', detail }` / `{ ok:
+ * false, signal }`, mirroring the write loop's own return shape. */
+async function writeRangeJson(deps, guard, rangeRoot, upstream) {
+  const { dest: path, tmp } = tempPathFor(rangeRoot, 'range.json')
+  try {
+    let current = {}
+    try {
+      current = JSON.parse(await deps.fs.readFile(path, 'utf8'))
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err
+    }
+    await deps.fs.writeFile(tmp, JSON.stringify(buildRangeJson(current, upstream), null, 2) + '\n', { flag: 'wx' })
+    if (guard.isRaised()) {
+      try {
+        await deps.fs.unlink(tmp)
+      } catch {
+        // Never created, or already gone -- either way, nothing left to clean up.
+      }
+      return { ok: false, signal: guard.raised() }
+    }
+    await deps.fs.rename(tmp, path)
+  } catch (err) {
+    try {
+      await deps.fs.unlink(tmp)
+    } catch {
+      // Never created, or already gone -- either way, nothing left to clean up.
+    }
+    return { ok: false, path: 'range.json', detail: err.message }
+  }
+  if (guard.isRaised()) return { ok: false, signal: guard.raised() }
+  return { ok: true }
+}
+
+/** `applyMerge({ deps, guard, rangeRoot, ops, upstream })` -> `{ ok: true }` on success, or
+ * `{ ok: false, path, detail }` (a file-system error at that path) / `{ ok: false, signal }` (a
+ * signal raised mid-apply, U28) otherwise -- the caller (`upgrade.mjs`) turns either into
+ * `UP-E09` and exit 1 / 130. `ops` is `planMerge`'s own sorted array; this function re-sorts
+ * defensively so a caller's own ordering is never relied on by accident. `upstream` (T-0027
+ * increment 8) is `range.json`'s own `upstream` value after the run: `{ repository, version,
+ * commit }` of the target, written last (after every deletion/write), the same write-then-rename
+ * path -- never reached when a delete/write already failed or a signal already stopped the loop,
+ * so an incomplete apply is never recorded as done (U24's deferred sub-case). */
+export async function applyMerge({ deps, guard, rangeRoot, ops, upstream }) {
+  const deletes = ops.filter((op) => op.action === 'delete').sort((a, b) => (a.path < b.path ? -1 : 1))
+  const writes = ops.filter((op) => op.action === 'write').sort((a, b) => (a.path < b.path ? -1 : 1))
+
+  for (const op of deletes) {
+    const { dest } = tempPathFor(rangeRoot, op.path)
+    try {
+      await deps.fs.unlink(dest)
+    } catch (err) {
+      return { ok: false, path: op.path, detail: err.message }
+    }
+    if (guard.isRaised()) return { ok: false, signal: guard.raised() }
+  }
+
+  for (const op of writes) {
+    const { dest, tmp } = tempPathFor(rangeRoot, op.path)
+    try {
+      await deps.fs.mkdir(dirname(dest), { recursive: true })
+
+      let existingMode
+      if (op.existedBefore) {
+        try {
+          existingMode = (await deps.fs.lstat(dest)).mode & 0o777
+        } catch (err) {
+          // Only ENOENT (gone by some other means -- nothing to preserve) is read as absent;
+          // any other error (e.g. EACCES) is a planning failure, not evidence of absence --
+          // fail closed, the same convention every other pre-check's own `lstat` already uses.
+          // Rethrown here, this reaches the write loop's own catch, below, which reports it as
+          // `UP-E09` with the restore commands, the same as any other failed write.
+          if (err?.code !== 'ENOENT') throw err
+          existingMode = undefined
+        }
+      }
+
+      const writeOptions = { flag: 'wx' }
+      if (!op.existedBefore && op.newFileExecutable) writeOptions.mode = 0o755
+      await deps.fs.writeFile(tmp, op.content, writeOptions)
+      if (existingMode !== undefined) await deps.fs.chmod(tmp, existingMode)
+      await deps.fs.rename(tmp, dest)
+    } catch (err) {
+      // The half-written temp file never survives a failed write.
+      try {
+        await deps.fs.unlink(tmp)
+      } catch {
+        // Never created, or already gone -- either way, nothing left to clean up.
+      }
+      return { ok: false, path: op.path, detail: err.message }
+    }
+    if (guard.isRaised()) return { ok: false, signal: guard.raised() }
+  }
+
+  return await writeRangeJson(deps, guard, rangeRoot, upstream)
+}