create-wxl 0.0.0-stage → 3.1.0

package/dist/source.json

@@ -0,0 +1,6 @@
+{
+  "repository": "BrowserLaboratory/wxl-platform",
+  "version": "3.1.0",
+  "commit": "b4d3fd0e0c46f5c872e7f680e5401f8a8d8c5f60",
+  "engineSha256": "d67a3403bada3d3c8ec9a22d8c43e3e07a99018ab2662cd9e740dd2c7772d61a"
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "create-wxl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.0",
+  "description": "Create a Web eXploitation Laboratory range",
+  "type": "module",
+  "bin": { "create-wxl": "bin/create-wxl.mjs" },
+  "files": ["bin", "src", "dist", "LICENSE"],
+  "engines": { "node": ">=22.6.0" },
+  "license": "LicenseRef-LICENSE",
+  "dependencies": {
+    "tar": "7.5.22",
+    "yaml": "2.9.0"
+  },
+  "devDependencies": {
+    "vitest": "4.1.6"
+  },
+  "scripts": {
+    "prepack": "node scripts/prepare-dist.mjs",
+    "prepublishOnly": "node scripts/prepare-dist.mjs && node scripts/check-publish.mjs",
+    "test": "vitest run"
+  }
+}

package/src/archive-rules.mjs

@@ -0,0 +1,164 @@
+// The archive entry rules (traceability.md "Archive entry rules", rules 1-5), checked against the
+// already-parsed entry list `archive.mjs`'s `parseArchive` returns (entries and ignored entries,
+// in archive order, each carrying the raw typeflag `raw-tar.mjs` read off the decompressed
+// bytes, cross-checked against `tar`'s own decode). The whole list is checked before step 8
+// writes anything (step order table, step 7). Entries are walked ONCE, in archive order, checking
+// every rule against each entry before moving to the next (S-03/P-03), so CW-E08 names the first
+// breaking entry in archive order, not the first one a particular rule happens to reach; rule 4
+// compares each entry only against the ones already seen. `checkEntryRules` returns the enriched
+// 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}`}`)
+    this.name = 'ArchiveRuleError'
+    this.rule = rule
+    this.path = path
+    // S-25: rule 2's comment violation has no entry to name; `path` is the FIXED marker text
+    // "pax comment", not a value read from the archive, so it must not be printed as a quoted
+    // JSON literal the way a real entry path is (messages.mjs).
+    this.isCommentMarker = isCommentMarker
+  }
+}
+
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f\u0080-\u009f]/
+const FIRST_COMPONENT_RE = /^[^\u0000-\u001f\u007f\u0080-\u009f\\]+$/
+
+/** Regular file (typeflag `0`, NUL or `7`) or directory (`5`); anything else (symlink, hardlink,
+ * character/block device, FIFO, GNU sparse, unknown) breaks rule 1. Classified from the RAW
+ * typeflag byte, not `tar`'s own reclassified `entry.type` (raw-tar.mjs's header comment). */
+function classify(rawTypeflag) {
+  if (rawTypeflag === '0' || rawTypeflag === '\u0000' || rawTypeflag === '7') return 'file'
+  if (rawTypeflag === '5') return 'dir'
+  return 'other'
+}
+
+function firstComponentAndRest(headerPath) {
+  const idx = headerPath.indexOf('/')
+  if (idx === -1) return { firstComponent: headerPath, rest: '' }
+  return { firstComponent: headerPath.slice(0, idx), rest: headerPath.slice(idx + 1) }
+}
+
+/** The shared first component itself must be a sane, relative, single name (C-01/C-11): step 8
+ * joins `rest` under it, so a `\`, a control character, an empty value or `.`/`..` here would be
+ * the same path-shape problem rule 3 already rejects for everything after it. */
+function checkFirstComponent(component, headerPath) {
+  if (component === '' || component === '.' || component === '..' || !FIRST_COMPONENT_RE.test(component)) {
+    throw new ArchiveRuleError(2, 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 (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)
+  }
+}
+
+/** Rule 3: after dropping the first component, a file's path is non-empty and does not end in
+ * `/`; a directory's path may or may not end in a single trailing `/` (both are accepted, P-04 --
+ * the spec only excepts a directory's trailing `/` from the "no empty component" rule, it does
+ * not require one); the prefix directory itself has an empty `rest` here and is always accepted. */
+function checkRule3(entry) {
+  const { rest, kind, headerPath } = entry
+  if (kind === 'dir') {
+    if (rest === '') return
+    const trimmed = rest.endsWith('/') ? rest.slice(0, -1) : rest
+    checkComponents(trimmed, headerPath)
+    return
+  }
+  if (rest === '' || rest.endsWith('/')) throw new ArchiveRuleError(3, headerPath)
+  checkComponents(rest, headerPath)
+}
+
+function relForCompareOf(entry) {
+  return entry.kind === 'dir' && entry.rest.endsWith('/') ? entry.rest.slice(0, -1) : entry.rest
+}
+
+function isProperPrefix(shortRel, longRel) {
+  return longRel.length > shortRel.length && longRel.startsWith(`${shortRel}/`)
+}
+
+/** Rule 4, checked against only the entries already seen (archive order, S-03/P-03): no two
+ * entries share a path, or a path equal after NFC then `toLowerCase()`; and no file's path is a
+ * proper prefix of another entry's path, whatever their order. A collision names the entry being
+ * checked now (always the later of the two, since `seen` holds only earlier ones); the
+ * proper-prefix check compares the raw (non-folded) relative paths, by decision (no case folding
+ * beyond the spec's literal text). Mutates `entry` with the comparison keys it just computed, and
+ * pushes it onto `seen` for the entries after it. */
+function checkCollisionAgainstSeen(entry, seen) {
+  const relForCompare = relForCompareOf(entry)
+  const normalized = relForCompare.normalize('NFC').toLowerCase()
+  for (const prior of seen) {
+    if (prior.normalized === normalized) throw new ArchiveRuleError(4, entry.headerPath)
+    if (prior.kind === 'file' && isProperPrefix(prior.relForCompare, relForCompare)) {
+      throw new ArchiveRuleError(4, entry.headerPath)
+    }
+    if (entry.kind === 'file' && isProperPrefix(relForCompare, prior.relForCompare)) {
+      throw new ArchiveRuleError(4, entry.headerPath)
+    }
+  }
+  entry.relForCompare = relForCompare
+  entry.normalized = normalized
+  seen.push(entry)
+}
+
+/**
+ * Validates the whole entry list against rules 1-5, throwing `ArchiveRuleError` on the first
+ * 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 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
+  // condition no longer repeats "undefined" as a special case: `commit` is always a non-empty
+  // string, so `comment !== commit` already covers a missing comment.
+  if (comment !== commit) throw new ArchiveRuleError(2, undefined, { isCommentMarker: true })
+  if (entries.length === 0) throw new ArchiveRuleError(5)
+
+  const firstEntryComponent = firstComponentAndRest(entries[0].headerPath).firstComponent
+  checkFirstComponent(firstEntryComponent, entries[0].headerPath)
+
+  let hasFile = false
+  const seen = []
+  const enriched = []
+  for (const entry of entries) {
+    const { firstComponent, rest } = firstComponentAndRest(entry.headerPath)
+    const kind = classify(entry.rawType)
+    const enrichedEntry = { ...entry, firstComponent, rest, kind }
+
+    if (firstComponent !== firstEntryComponent) throw new ArchiveRuleError(2, entry.headerPath)
+    if (kind === 'other') throw new ArchiveRuleError(1, entry.headerPath)
+    checkRule3(enrichedEntry)
+    checkCollisionAgainstSeen(enrichedEntry, seen)
+    if (kind === 'file') hasFile = true
+    enriched.push(enrichedEntry)
+  }
+
+  if (!hasFile) throw new ArchiveRuleError(5)
+
+  return enriched
+}

package/src/archive.mjs

@@ -0,0 +1,109 @@
+// Parses a downloaded archive body (gzip + tar) into an in-memory entry list, using the `tar`
+// package's low-level `Parser` (strict mode turns every parse warning into an 'error' event,
+// rows 6/C55) alongside `raw-tar.mjs`'s own walker, which recovers the raw typeflag byte `tar`'s
+// `entry.type` cannot (archive-rules.mjs needs it for rules 1 and 3). T-0021's `archive-rules.mjs`
+// validates the returned list against rules 1-5; this module only extracts it, in archive order.
+//
+// Review finding P-01/C-02 (desync): two independent parsers walking the same bytes can disagree
+// about where one header ends and the next begins (a pax `size` override, or a directory's
+// decoded size being forced to 0, are the two `tar` applies that `raw-tar.mjs` must mirror). A
+// mirrored rule closes the KNOWN divergences, but as a second line of defence this module also
+// cross-checks every pairing's path and size against `tar`'s own decoded header, and the raw
+// walker's own entry count against `tar`'s: any mismatch is `ArchiveParseError` (CW-E08), not a
+// silent, wrong pairing. Finding P-11/C-07: the body must be gzip (`tar`'s own zstd
+// auto-detection is explicitly turned off, closing another source of divergence); a plain tar
+// body is rejected here even though `raw-tar.mjs`'s own export still accepts one directly.
+
+import { Parser } from 'tar'
+import { walkRawEntries } from './raw-tar.mjs'
+
+const GZIP_MAGIC_0 = 0x1f
+const GZIP_MAGIC_1 = 0x8b
+
+/** Wraps every failure this module itself detects: a `tar`/zlib parse error, or a cross-check
+ * mismatch between the raw walker and `tar`'s own decode. `run.mjs` prints CW-E08 only for this
+ * class and rethrows anything else (a bug is not an archive problem, S-02/P-08/C-08). */
+export class ArchiveParseError extends Error {}
+
+export function parseArchive(bytes) {
+  return new Promise((resolvePromise, reject) => {
+    const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
+    if (buf.length < 2 || buf[0] !== GZIP_MAGIC_0 || buf[1] !== GZIP_MAGIC_1) {
+      reject(new ArchiveParseError('the archive is not gzip-compressed'))
+      return
+    }
+
+    let rawEntries
+    try {
+      rawEntries = walkRawEntries(buf).filter((e) => !e.isMeta)
+    } catch (err) {
+      reject(new ArchiveParseError(err?.message ?? String(err)))
+      return
+    }
+    let rawIndex = 0
+    let desynced = false
+    const nextRaw = () => (rawIndex < rawEntries.length ? rawEntries[rawIndex++] : undefined)
+
+    // `zstd: false` (P-11/C-07): `tar`'s own format auto-detection would otherwise accept a zstd
+    // body the raw walker cannot decode at all, letting an attacker fully control what typeflag
+    // the walker sees at every offset.
+    const parser = new Parser({ strict: true, zstd: false })
+    const entries = []
+    let comment
+
+    function readComment(entry) {
+      if (entry.globalExtended?.comment !== undefined) comment = entry.globalExtended.comment
+    }
+
+    function crossCheck(entry) {
+      const raw = nextRaw()
+      if (raw === undefined || raw.path !== entry.header.path || raw.size !== entry.header.size) {
+        desynced = true
+      }
+      return raw
+    }
+
+    parser.on('entry', (entry) => {
+      const raw = crossCheck(entry)
+      const chunks = []
+      entry.on('data', (chunk) => chunks.push(chunk))
+      entry.on('end', () => {
+        readComment(entry)
+        entries.push({
+          path: entry.path,
+          headerPath: entry.header.path,
+          type: entry.type,
+          rawType: raw?.rawTypeflag,
+          mode: entry.mode,
+          content: Buffer.concat(chunks),
+        })
+      })
+      entry.resume()
+    })
+    // Finding P-10/C-12: a pax global `comment` must be read whatever kind the entry turns out to
+    // be, not only when it happens to be a regular 'entry' -- otherwise an archive whose only
+    // entries are of an ignored type reports a missing comment instead of naming the real
+    // violation (rule 1).
+    parser.on('ignoredEntry', (entry) => {
+      const raw = crossCheck(entry)
+      readComment(entry)
+      entries.push({
+        path: entry.path,
+        headerPath: entry.header.path,
+        type: entry.type,
+        rawType: raw?.rawTypeflag,
+        mode: entry.mode,
+        content: undefined,
+      })
+    })
+    parser.on('error', (err) => reject(new ArchiveParseError(err?.message ?? String(err))))
+    parser.on('end', () => {
+      if (desynced || rawIndex !== rawEntries.length) {
+        reject(new ArchiveParseError('the archive could not be parsed consistently'))
+        return
+      }
+      resolvePromise({ entries, comment })
+    })
+    parser.end(buf)
+  })
+}

package/src/argv.mjs

@@ -0,0 +1,146 @@
+// 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}`)
+    this.name = 'ArgvError'
+    this.token = token
+    this.usage = usage
+    this.reason = reason
+  }
+}
+
+const VALUE_FLAGS = new Set(['--author', '--repo', '--host', '--origin', '--site-name', '--lang'])
+export const SETUP_FLAG_NAMES = ['author', 'repo', 'host', 'origin', 'site-name']
+
+export function parseArgvStrict(argv) {
+  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]
+
+    if (!endOfFlags && arg === '--') {
+      endOfFlags = true
+      continue
+    }
+
+    if (!endOfFlags && (arg === '-h' || arg === '--help' || arg === '--version')) {
+      throw new ArgvError(arg, { usage: true })
+    }
+
+    if (!endOfFlags && arg === '-') {
+      throw new ArgvError(arg)
+    }
+
+    if (!endOfFlags && arg.startsWith('-')) {
+      const eq = arg.indexOf('=')
+      const name = eq === -1 ? arg : arg.slice(0, eq)
+      const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1)
+
+      if (name === '--no-setup') {
+        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)
+
+      let value
+      if (eq !== -1) {
+        if (inlineValue === '') throw new ArgvError(name, { reason: 'missing-value' })
+        value = inlineValue
+      } else {
+        const next = argv[i + 1]
+        // A next argument beginning with `-` (including a lone `-`) is a missing value, not a
+        // value: the Command grammar makes no exception for `-` on its own.
+        if (next === undefined || next.startsWith('-')) {
+          throw new ArgvError(name, { reason: 'missing-value' })
+        }
+        value = next
+        i++
+      }
+
+      if (name === '--lang') {
+        if (value !== 'en' && value !== 'zh-TW') throw new ArgvError(value)
+        result.lang = value
+      } else {
+        result.flags[name.slice(2)] = value
+        createOnlyFlagsSeen.push(name)
+      }
+      continue
+    }
+
+    // positional
+    if (arg === '') 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/fsops.mjs

@@ -0,0 +1,205 @@
+import { dirname, join } from 'node:path'
+import { constants as fsConstants } from 'node:fs'
+import { tagReportPath } from './text.mjs'
+
+/** Step 4's rule, returning `null` when the target is acceptable, or `{ id, detail? }` naming the
+ * CW-E04 condition. The parent is checked with `stat` (a symlink parent, e.g. macOS's `/tmp`, is
+ * followed); the target itself is always checked with `lstat` (any symlink is rejected without
+ * being followed). Only `ENOENT` from the target's `lstat` means "does not exist": any other
+ * error is reported with its own message instead of silently treated as absent. */
+export async function checkTarget(deps, target) {
+  const parent = dirname(target)
+  let parentStat
+  try {
+    parentStat = await deps.fs.stat(parent)
+  } catch {
+    return { id: 'parent-missing' }
+  }
+  if (!parentStat.isDirectory()) return { id: 'parent-not-directory' }
+
+  try {
+    await deps.fs.access(parent, fsConstants.W_OK)
+  } catch {
+    return { id: 'parent-not-writable' }
+  }
+
+  let targetStat
+  try {
+    targetStat = await deps.fs.lstat(target)
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null // does not exist: ok
+    return { id: 'lstat-error', detail: err?.message ?? String(err) }
+  }
+
+  if (targetStat.isSymbolicLink()) return { id: 'symlink' }
+  if (!targetStat.isDirectory()) return { id: 'file' }
+
+  const names = await deps.fs.readdir(target)
+  if (names.length > 0) return { id: 'non-empty' }
+
+  const targetDeviceStat = await deps.fs.stat(target)
+  if (targetDeviceStat.dev !== parentStat.dev) return { id: 'cross-device' }
+
+  return null
+}
+
+/** Step 8: writes the entries `archive-rules.mjs`'s `checkEntryRules` already validated into
+ * `tmpDir`. Writes from the SAME validated data it checked rules 1-5 against -- `entry.rest`
+ * (the header path with the first component already stripped off) and `entry.kind`
+ * (`'file'`/`'dir'`, from the raw typeflag) -- rather than re-deriving a path or type from `tar`'s
+ * own `entry.path`/`entry.type` (review finding C-01: the two used to disagree about which
+ * component to drop, and about how a `tar`-reclassified type maps to file-system writes). Files
+ * use flag `wx` (fails on collision); directories without `recursive`. Mode is 0755 when the
+ * entry has any execute bit, else 0644, each masked by the process umask through the normal
+ * `open`/`mkdir` syscalls (no manual umask arithmetic needed). */
+/** Returns `{ stopped: true }` when `shouldStop` ended the loop early (S-19: a typed result the
+ * caller cannot accidentally ignore, rather than a silent early `return` it would have to
+ * remember to notice through a separate check right after the call), `{ stopped: false }` once
+ * every entry is written. */
+export async function extractEntries(deps, entries, tmpDir, { shouldStop } = {}) {
+  for (const entry of entries) {
+    // traceability.md "Signals": "after a signal no new file-system operation starts" -- checked
+    // BEFORE each entry's write (unlike `moveIntoPlace`'s per-rename check, there is no rollback
+    // to do mid-step-8, so stopping here just means not starting the next one).
+    if (shouldStop && shouldStop()) return { stopped: true }
+    if (entry.rest === '') continue // the prefix directory entry itself
+    const rel = entry.rest.endsWith('/') ? entry.rest.slice(0, -1) : entry.rest
+    const full = join(tmpDir, rel)
+    try {
+      if (entry.kind === 'dir') {
+        await deps.fs.mkdir(full, { mode: 0o755 })
+      } else {
+        const executable = (entry.mode & 0o111) !== 0
+        await deps.fs.writeFile(full, entry.content, { flag: 'wx', mode: executable ? 0o755 : 0o644 })
+      }
+    } catch (err) {
+      // CW-E09 (run.mjs) names the path; a real `fs` error already carries its own `.path`, but
+      // tagging it here (rather than relying on that) also covers an injected test error.
+      throw tagReportPath(err, full)
+    }
+  }
+  return { stopped: false }
+}
+
+/** Step 10's own failure (traceability.md "Writes and cleanup"): a rename failed, or a `shouldStop`
+ * callback (checked after each successful rename, shared by a real failure and a signal) asked to
+ * stop. `stranded`: entries rollback itself could not move back (CW-E11 names them and keeps the
+ * temporary directory); `signaled: true` means nothing actually failed -- the caller asked to stop. */
+export class MoveIntoPlaceError extends Error {
+  constructor(message, { failedEntry, stranded, tmpDir, signaled = false, cause } = {}) {
+    super(message, cause !== undefined ? { cause } : undefined)
+    this.name = 'MoveIntoPlaceError'
+    this.failedEntry = failedEntry
+    this.stranded = stranded ?? []
+    this.tmpDir = tmpDir
+    this.signaled = signaled
+  }
+}
+
+/** Step 10: move the temporary directory into place. `shouldStop`, when given, is checked after
+ * each successful rename (not before): a signal arriving mid-rename still lets that one rename
+ * finish before anything stops (traceability.md "Signals": "the cleanup waits for the operation in
+ * flight"). On any failure or stop, every entry already moved into the target is renamed back,
+ * trying every one even when an earlier one could not be moved back (Notes: "rollback tries every
+ * entry"); only once every entry is back is the temporary directory removed. */
+export async function moveIntoPlace(deps, tmpDir, target, { shouldStop } = {}) {
+  let exists = true
+  try {
+    await deps.fs.lstat(target)
+  } catch {
+    exists = false
+  }
+
+  if (!exists) {
+    // C-04/P-14: a failing whole-directory rename is CW-E11 (nothing moved, nothing to roll
+    // back), not an uncaught "bug" (CW-E14).
+    try {
+      await deps.fs.rename(tmpDir, target)
+    } catch (err) {
+      // Nothing moved: the temporary directory is exactly as it was, so it is removed the same
+      // way a successful rollback's empty `stranded` always is.
+      await deps.fs.rm(tmpDir, { recursive: true, force: true })
+      throw new MoveIntoPlaceError(err.message, { stranded: [], tmpDir, cause: err })
+    }
+    // P-02/C-01: checked after the rename, the same "wait for the operation in flight" rule the
+    // per-entry branch below follows. A signal here still gets a clean "target as it was": rename
+    // the whole range straight back, matching MoveIntoPlaceError's `signaled` path the per-entry
+    // branch already uses (the caller's outer cleanup then removes the temporary directory).
+    if (shouldStop && shouldStop()) {
+      await deps.fs.rename(target, tmpDir)
+      throw new MoveIntoPlaceError('aborted by signal', { stranded: [], tmpDir, signaled: true })
+    }
+    try {
+      // `chmod` does not apply the umask (unlike `open`/`mkdir`), so it is masked by hand here.
+      await deps.fs.chmod(target, 0o755 & ~process.umask())
+    } catch (err) {
+      // C-04/P-14: the range is already physically at `target`; move it back into the temporary
+      // directory where possible, so "target as it was" still holds, and report CW-E11.
+      let movedBack = true
+      try {
+        await deps.fs.rename(target, tmpDir)
+      } catch {
+        movedBack = false
+      }
+      if (movedBack) await deps.fs.rm(tmpDir, { recursive: true, force: true })
+      throw new MoveIntoPlaceError(err.message, { stranded: movedBack ? [] : ['the range'], tmpDir, cause: err })
+    }
+    return
+  }
+
+  const names = (await deps.fs.readdir(tmpDir)).slice().sort()
+  const moved = []
+  let failedEntry
+  let failedError
+  let signaled = false
+  for (const name of names) {
+    try {
+      await deps.fs.rename(join(tmpDir, name), join(target, name))
+    } catch (err) {
+      failedEntry = name
+      failedError = err
+      break
+    }
+    moved.push(name)
+    if (shouldStop && shouldStop()) {
+      signaled = true
+      break
+    }
+  }
+
+  if (failedError === undefined && !signaled) {
+    try {
+      await deps.fs.rmdir(tmpDir)
+    } catch (err) {
+      // C-04/P-14: every entry already succeeded into `target`; move them all back where
+      // possible, so "target as it was" still holds, and report CW-E11 instead of an uncaught bug.
+      const strandedByRmdir = []
+      for (const name of names) {
+        try {
+          await deps.fs.rename(join(target, name), join(tmpDir, name))
+        } catch {
+          strandedByRmdir.push(name)
+        }
+      }
+      throw new MoveIntoPlaceError(err.message, { stranded: strandedByRmdir, tmpDir, cause: err })
+    }
+    return
+  }
+
+  const stranded = []
+  for (const name of moved) {
+    try {
+      await deps.fs.rename(join(target, name), join(tmpDir, name))
+    } catch {
+      stranded.push(name)
+    }
+  }
+  if (stranded.length === 0) {
+    await deps.fs.rm(tmpDir, { recursive: true, force: true })
+  }
+
+  if (signaled) {
+    throw new MoveIntoPlaceError('aborted by signal', { stranded, tmpDir, signaled: true })
+  }
+  throw new MoveIntoPlaceError(failedError.message, { failedEntry, stranded, tmpDir, cause: failedError })
+}