@hominis/fireforge 0.50.0 → 0.52.0

package/dist/src/core/negative-control-compiled.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which negative-control targets only a build can deliver.
+ *
+ * A control is applied after the pre-test build and right before dispatch,
+ * which is right for a file the runtime reads from the source tree or the
+ * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
+ * never compiled: the run tests the unmutated binary and reports
+ * `control=missed`, which reads as a test that cannot fail. Such a target
+ * is now refused without `--build`, and with `--build` the control is
+ * applied before the build so the binary under test carries it. That build
+ * is a full `mach build`: the pre-test build is otherwise `mach build
+ * faster`, which compiles nothing, so the control still missed.
+ */
+/**
+ * The engine-relative targets that reach the runtime only through a
+ * compile: a compiled-source extension and no install-manifest entry that
+ * ships the file itself.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param enginePaths - The control's engine-relative targets
+ */
+export declare function findCompiledControlTargets(engineDir: string, enginePaths: readonly string[]): Promise<string[]>;
+/**
+ * The notice that explains why a compiled control's pre-test build is a
+ * full `mach build` instead of `mach build faster`.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export declare function formatCompiledControlBuildNotice(compiled: readonly string[]): string;
+/**
+ * The refusal for a compiled control without `--build`, naming the manual
+ * procedure for a run that wants to keep its build out of FireForge.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export declare function formatCompiledControlRefusal(compiled: readonly string[]): string;

package/dist/src/core/negative-control-compiled.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Which negative-control targets only a build can deliver.
+ *
+ * A control is applied after the pre-test build and right before dispatch,
+ * which is right for a file the runtime reads from the source tree or the
+ * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
+ * never compiled: the run tests the unmutated binary and reports
+ * `control=missed`, which reads as a test that cannot fail. Such a target
+ * is now refused without `--build`, and with `--build` the control is
+ * applied before the build so the binary under test carries it. That build
+ * is a full `mach build`: the pre-test build is otherwise `mach build
+ * faster`, which compiles nothing, so the control still missed.
+ */
+import { extname } from 'node:path';
+import { classifyRuntimeDelivery } from './objdir-install-manifests.js';
+import { loadEngineInstallIndex } from './test-stale-exempt.js';
+/** Extensions of sources the build compiles or code-generates into the binary. */
+const COMPILED_EXTENSIONS = new Set([
+    '.c',
+    '.cc',
+    '.cpp',
+    '.cxx',
+    '.h',
+    '.hh',
+    '.hpp',
+    '.m',
+    '.mm',
+    '.rs',
+    '.idl',
+    '.webidl',
+    '.ipdl',
+    '.ipdlh',
+    '.yaml',
+    '.yml',
+]);
+/**
+ * The engine-relative targets that reach the runtime only through a
+ * compile: a compiled-source extension and no install-manifest entry that
+ * ships the file itself.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param enginePaths - The control's engine-relative targets
+ */
+export async function findCompiledControlTargets(engineDir, enginePaths) {
+    const candidates = enginePaths.filter((path) => COMPILED_EXTENSIONS.has(extname(path)));
+    if (candidates.length === 0)
+        return [];
+    const index = await loadEngineInstallIndex(engineDir);
+    if (index === undefined)
+        return candidates;
+    const compiled = [];
+    for (const path of candidates) {
+        if ((await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
+            compiled.push(path);
+        }
+    }
+    return compiled;
+}
+/**
+ * The notice that explains why a compiled control's pre-test build is a
+ * full `mach build` instead of `mach build faster`.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export function formatCompiledControlBuildNotice(compiled) {
+    const files = compiled.map((path) => `engine/${path}`).join(', ');
+    return (`The negative control edits compiled source (${files}); escalating this pre-test build to ` +
+        'a full mach build, since mach build faster compiles nothing and the binary under test ' +
+        'would not carry the control.');
+}
+/**
+ * The refusal for a compiled control without `--build`, naming the manual
+ * procedure for a run that wants to keep its build out of FireForge.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export function formatCompiledControlRefusal(compiled) {
+    const files = compiled.map((path) => `engine/${path}`).join(', ');
+    return (`This negative control edits compiled source (${files}). Applied right before dispatch, ` +
+        'it would never be compiled: the run would test the unmutated binary and report ' +
+        'control=missed. Add --build: the control is then applied before the pre-test build, so ' +
+        'the binary under test carries it, and restored afterwards with a fresh mtime so the next ' +
+        'build recompiles the original. To run it by hand instead: copy the mutated file in, ' +
+        '`touch` it, `fireforge build`, `fireforge test`, restore the file byte-exact, `touch` it ' +
+        'again and rebuild.');
+}

package/dist/src/core/negative-control-diff.d.ts

@@ -18,15 +18,27 @@ export interface ControlDiffFile {
     /** The hunks to apply, in file order. */
     hunks: ParsedHunk[];
 }
+/** Options for {@link parseControlDiff}. */
+export interface ParseControlDiffOptions {
+    /**
+     * Called for a section whose old and new paths differ. Returns the path
+     * the control targets (a `git diff --no-index <file> <edited copy>` names
+     * the copy on its new side), or undefined for a real rename, which is
+     * refused.
+     */
+    resolveRename?: (sourcePath: string, targetPath: string) => string | undefined;
+}
 /**
  * Parses a control diff. Accepts `git diff` output (a `diff --git` header
  * per file), which is what `git -C engine diff -- <file>` or a project-root
- * `git diff` writes.
+ * `git diff` writes, a plain unified diff (`diff -u`), and, through
+ * `resolveRename`, a `git diff --no-index` against an edited copy.
  *
  * @param content - The diff file's text
+ * @param options - See {@link ParseControlDiffOptions}
  * @returns One entry per file, in diff order
  */
-export declare function parseControlDiff(content: string): ControlDiffFile[];
+export declare function parseControlDiff(content: string, options?: ParseControlDiffOptions): ControlDiffFile[];
 /**
  * Applies `hunks` to `original`, strictly.
  *

package/dist/src/core/negative-control-diff.js

@@ -17,30 +17,73 @@ import { parseDiffSections } from './patch-parse.js';
 function refuse(message) {
     throw new GeneralError(`Negative control diff refused: ${message}`);
 }
+/** A `---`/`+++` file name, without a trailing timestamp or git's `a/`/`b/`. */
+function plainDiffPath(raw) {
+    const name = raw.split('\t')[0]?.trim() ?? '';
+    return name.startsWith('a/') || name.startsWith('b/') ? name.slice(2) : name;
+}
+/**
+ * Gives a plain unified diff (`diff -u`, no `diff --git` lines) the git
+ * header the section parser keys on, one per `---`/`+++` pair. A diff that
+ * already carries `diff --git` headers is returned unchanged.
+ *
+ * @param content - The diff file's text
+ */
+function withGitHeaders(content) {
+    const lines = content.split('\n');
+    if (lines.some((line) => line.startsWith('diff --git ')))
+        return content;
+    const out = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const next = lines[index + 1] ?? '';
+        if (line.startsWith('--- ') && next.startsWith('+++ ')) {
+            const oldPath = plainDiffPath(line.slice(4));
+            const newPath = plainDiffPath(next.slice(4));
+            index += 1;
+            if (oldPath === '/dev/null' || newPath === '/dev/null') {
+                // Kept as a create/delete, which the parser below refuses by name.
+                const path = oldPath === '/dev/null' ? newPath : oldPath;
+                out.push(`diff --git a/${path} b/${path}`, oldPath === '/dev/null' ? 'new file mode 100644' : 'deleted file mode 100644', oldPath === '/dev/null' ? '--- /dev/null' : `--- a/${path}`, newPath === '/dev/null' ? '+++ /dev/null' : `+++ b/${path}`);
+                continue;
+            }
+            out.push(`diff --git a/${oldPath} b/${newPath}`, `--- a/${oldPath}`, `+++ b/${newPath}`);
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
 /**
  * Parses a control diff. Accepts `git diff` output (a `diff --git` header
  * per file), which is what `git -C engine diff -- <file>` or a project-root
- * `git diff` writes.
+ * `git diff` writes, a plain unified diff (`diff -u`), and, through
+ * `resolveRename`, a `git diff --no-index` against an edited copy.
  *
  * @param content - The diff file's text
+ * @param options - See {@link ParseControlDiffOptions}
  * @returns One entry per file, in diff order
  */
-export function parseControlDiff(content) {
-    const sections = parseDiffSections(content);
+export function parseControlDiff(content, options = {}) {
+    const sections = parseDiffSections(withGitHeaders(content));
     if (sections.length === 0) {
-        refuse('no `diff --git` sections found. Write the control with git, e.g. ' +
+        refuse('no diff sections found. Write the control with git, e.g. ' +
             '`git -C engine diff -- <file> > control.diff` after making the edit, then revert the edit.');
     }
     const seen = new Set();
     return sections.map((section) => {
-        const path = normalizePathSlashes(section.targetPath);
+        let path = normalizePathSlashes(section.targetPath);
         if (section.isBinary)
             refuse(`${path} is a binary section.`);
         if (section.isNewFile || section.isDeletedFile) {
             refuse(`${path} creates or deletes a file; a control may only modify existing text files.`);
         }
         if (section.sourcePath !== section.targetPath) {
-            refuse(`${section.sourcePath} -> ${path} is a rename; a control may only modify files.`);
+            const resolved = options.resolveRename?.(section.sourcePath, section.targetPath);
+            if (resolved === undefined) {
+                refuse(`${section.sourcePath} -> ${path} is a rename; a control may only modify files.`);
+            }
+            path = normalizePathSlashes(resolved);
         }
         if (!isContainedRelativePath(path)) {
             refuse(`${path} is not a contained relative path.`);

package/dist/src/core/negative-control.d.ts

@@ -40,6 +40,12 @@ export interface NegativeControlPlan {
     /** The diff file, as the operator passed it. */
     diffFile: string;
     targets: NegativeControlTarget[];
+    /**
+     * Engine-relative targets only a build delivers (compiled sources). A
+     * control with any must be applied before the pre-test build, and is
+     * restored with a fresh mtime. See `negative-control-compiled.ts`.
+     */
+    compiled?: string[];
 }
 /** Locations a control works against. */
 export interface NegativeControlPaths {
@@ -55,6 +61,12 @@ interface JournalEntry {
     mode: number;
     atimeMs: number;
     mtimeMs: number;
+    /**
+     * Restore with the current time as mtime, not the original: a compiled
+     * source restored with its old mtime is skipped by the incremental build,
+     * which would leave the mutated code in the binary.
+     */
+    freshMtime?: boolean;
 }
 interface Journal {
     version: 1;

package/dist/src/core/negative-control.js

@@ -25,14 +25,15 @@
  *    it releases the held locks.
  */
 import { lstat, mkdir, readFile, rm, utimes } from 'node:fs/promises';
-import { join, posix, resolve } from 'node:path';
+import { isAbsolute, join, posix, relative, resolve } from 'node:path';
 import { GeneralError, PreflightRefusalError } from '../errors/base.js';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { writeFileAtomic } from '../utils/fs.js';
 import { sha256Hex } from '../utils/hash.js';
 import { notice } from '../utils/logger.js';
-import { normalizePathSlashes, stripEnginePrefix } from '../utils/paths.js';
+import { isContainedRelativePath, isPathInsideRoot, normalizePathSlashes, stripEnginePrefix, } from '../utils/paths.js';
 import { loadFurnaceConfig } from './furnace-config.js';
+import { findCompiledControlTargets } from './negative-control-compiled.js';
 import { applyControlHunks, parseControlDiff, } from './negative-control-diff.js';
 import { runInSignalCriticalSection } from './signal-critical.js';
 /** Journal directory, relative to `.fireforge/`. */
@@ -159,7 +160,9 @@ export async function planNegativeControl(projectRoot, engineDir, diffFile, opti
     }
     let files;
     try {
-        files = parseControlDiff(content);
+        files = parseControlDiff(content, {
+            resolveRename: (source, target) => resolveEditedCopyRename(projectRoot, source, target),
+        });
     }
     catch (error) {
         refuse(toError(error).message);
@@ -170,7 +173,40 @@ export async function planNegativeControl(projectRoot, engineDir, diffFile, opti
             continue;
         await prepareTarget(engineDir, target);
     }
-    return { diffFile, targets };
+    const compiled = await findCompiledControlTargets(engineDir, targets.filter((target) => !target.fromComponents).map((target) => target.enginePath));
+    return { diffFile, targets, ...(compiled.length > 0 ? { compiled } : {}) };
+}
+/**
+ * A diff path as a project-relative path: a contained relative path as
+ * is, and an absolute one (git strips the leading `/` into `a/Users/…`)
+ * when it lies inside the project. Undefined otherwise.
+ */
+function projectRelative(projectRoot, path) {
+    const normalized = normalizePathSlashes(path);
+    for (const candidate of [`/${normalized}`, normalized]) {
+        if (!isAbsolute(candidate))
+            continue;
+        if (isPathInsideRoot(projectRoot, candidate)) {
+            return normalizePathSlashes(relative(projectRoot, candidate));
+        }
+    }
+    return isContainedRelativePath(normalized) ? normalized : undefined;
+}
+/**
+ * The control target of a `git diff --no-index <engine file> <edited copy>`
+ * section: its old side, when that names a project file and the new side
+ * names a copy outside `engine/` and `components/`. A section whose sides
+ * both live in those trees is a real rename and stays refused.
+ */
+function resolveEditedCopyRename(projectRoot, source, target) {
+    const old = projectRelative(projectRoot, source);
+    if (old === undefined)
+        return undefined;
+    const edited = projectRelative(projectRoot, target);
+    const tracked = (path) => path.startsWith('engine/') || path.startsWith('components/');
+    if (edited !== undefined && tracked(edited))
+        return undefined;
+    return old;
 }
 async function writeJournal(paths, journal) {
     await writeFileAtomic(join(journalDir(paths), JOURNAL_FILE), `${JSON.stringify(journal, null, 2)}\n`);
@@ -203,6 +239,7 @@ export async function applyNegativeControl(paths, plan) {
                 mode: item.mode,
                 atimeMs: item.atimeMs,
                 mtimeMs: item.mtimeMs,
+                ...(plan.compiled?.includes(item.target.enginePath) === true ? { freshMtime: true } : {}),
             });
         }
         const journal = {
@@ -248,7 +285,13 @@ async function restoreEntry(paths, entry) {
             `left the file as is. Inspect ${journalDir(paths)}.`);
     }
     await writeFileAtomic(absolutePath, original);
-    await utimes(absolutePath, entry.atimeMs / 1000, entry.mtimeMs / 1000);
+    if (entry.freshMtime === true) {
+        const now = Date.now() / 1000;
+        await utimes(absolutePath, now, now);
+    }
+    else {
+        await utimes(absolutePath, entry.atimeMs / 1000, entry.mtimeMs / 1000);
+    }
     const readBack = await readFile(absolutePath);
     const stats = await lstat(absolutePath);
     if (!readBack.equals(original) || (stats.mode & 0o7777) !== (entry.mode & 0o7777)) {

package/dist/src/core/park-store.d.ts

@@ -0,0 +1,63 @@
+/** One parked file: both sides, null meaning absent. */
+export interface ParkedFile {
+    /** Engine-relative path. */
+    path: string;
+    /** The file as the session left it. */
+    before: string | null;
+    /** The file the park wrote in its place. */
+    after: string | null;
+}
+/** The record of one park. */
+export interface ParkRecord {
+    label: string;
+    /** The patch whose files were parked. */
+    patch: string;
+    createdAt: string;
+    /** `baseline` parks every drifted hunk, `hunks` only those a diff named. */
+    mode: 'baseline' | 'hunks';
+    files: ParkedFile[];
+}
+/** What `park.json` holds: the record without file contents. */
+interface ParkIndex extends Omit<ParkRecord, 'files'> {
+    files: {
+        path: string;
+        before: boolean;
+        after: boolean;
+    }[];
+}
+/** The outcome of restoring one file. */
+export type RestoreOutcome = 'restored' | 'unchanged' | 'merged' | 'conflict';
+/** Writes a park; refuses to overwrite an existing label. */
+export declare function writePark(projectRoot: string, record: ParkRecord): Promise<string>;
+/** Reads a park back, contents included. */
+export declare function readPark(projectRoot: string, label: string): Promise<ParkRecord>;
+/** Every park of the project, oldest first. */
+export declare function listParks(projectRoot: string): Promise<ParkIndex[]>;
+/** Deletes a park. */
+export declare function dropPark(projectRoot: string, label: string): Promise<void>;
+/** Reads an engine file, null when absent. */
+export declare function readEngineFile(engineDir: string, path: string): Promise<string | null>;
+/** Writes an engine file, removing it for null. */
+export declare function writeEngineFile(engineDir: string, path: string, content: string | null): Promise<void>;
+/**
+ * Three-way merges `ours` and `theirs` over `base` with `git merge-file`.
+ * Conflicts come back as marker blocks.
+ */
+export declare function mergeThreeWay(ours: string, base: string, theirs: string, path: string): Promise<{
+    content: string;
+    conflicts: number;
+}>;
+/**
+ * What restoring one parked file writes: `before` when the file is still
+ * as the park left it, nothing when it already matches `before`, and a
+ * three-way merge otherwise. Absence only merges with absence.
+ */
+export declare function planRestore(file: ParkedFile, now: string | null): Promise<{
+    outcome: RestoreOutcome;
+    content: string | null;
+}>;
+/** Message ids a Fluent file's lines declare (`id = …`, `-term = …`). */
+export declare function fluentIds(lines: readonly string[]): string[];
+/** Lines `before` has that `after` lacks, as a multiset difference. */
+export declare function removedLines(before: string | null, after: string | null): string[];
+export {};

package/dist/src/core/park-store.js

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Storage and merge logic behind `fireforge park`.
+ *
+ * Several sessions edit the same Hominis files on one engine, and a peer's
+ * `re-export --refuse-foreign-drift` refuses while another session's hunks
+ * sit in its patch's files. Setting those hunks aside meant reversing each
+ * one by hand. A park records, for every file of one patch that drifted:
+ *
+ *  - `before`: the file as the session left it (what the park takes away),
+ *  - `after`: what the park writes in its place (the queue-applied
+ *    baseline, or the working tree minus the named hunks).
+ *
+ * Restoring is a three-way merge of the file as it is now (ours) with
+ * `before` (theirs) over `after` (base), so the owner's commit in between
+ * is kept and the parked hunks come back on top of it.
+ *
+ * A park lives under `.fireforge/park/<label>/`: `park.json` plus one copy
+ * of each side per file. Absent files are recorded as absent, never as
+ * empty.
+ */
+import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { InvalidArgumentError } from '../errors/base.js';
+import { getNodeErrorCode } from '../utils/errors.js';
+import { ensureDir, pathExists, readJson, readText, removeFile, writeJson, writeText, } from '../utils/fs.js';
+import { exec } from '../utils/process.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** The directory holding every park of a project. */
+function parkRoot(projectRoot) {
+    return join(projectRoot, FIREFORGE_DIR, 'park');
+}
+/** Refuses a label that is not a plain file-name segment. */
+function assertParkLabel(label) {
+    if (!LABEL_PATTERN.test(label)) {
+        throw new InvalidArgumentError(`Park label "${label}" must be letters, digits, ".", "_" or "-", starting with a letter or digit.`, '--label');
+    }
+}
+function sideDir(dir, side) {
+    return join(dir, side);
+}
+/** Writes a park; refuses to overwrite an existing label. */
+export async function writePark(projectRoot, record) {
+    assertParkLabel(record.label);
+    const dir = join(parkRoot(projectRoot), record.label);
+    if (await pathExists(dir)) {
+        throw new InvalidArgumentError(`A park named "${record.label}" already exists. Restore or drop it first, or pass another --label.`, '--label');
+    }
+    for (const file of record.files) {
+        for (const side of ['before', 'after']) {
+            const content = file[side];
+            if (content === null)
+                continue;
+            const target = join(sideDir(dir, side), file.path);
+            await ensureDir(dirname(target));
+            await writeText(target, content);
+        }
+    }
+    const index = {
+        label: record.label,
+        patch: record.patch,
+        createdAt: record.createdAt,
+        mode: record.mode,
+        files: record.files.map((file) => ({
+            path: file.path,
+            before: file.before !== null,
+            after: file.after !== null,
+        })),
+    };
+    await writeJson(join(dir, 'park.json'), index);
+    return dir;
+}
+/** Reads a park back, contents included. */
+export async function readPark(projectRoot, label) {
+    assertParkLabel(label);
+    const dir = join(parkRoot(projectRoot), label);
+    if (!(await pathExists(join(dir, 'park.json')))) {
+        throw new InvalidArgumentError(`No park named "${label}". List them with "fireforge park --list".`, label);
+    }
+    const index = await readJson(join(dir, 'park.json'));
+    const files = [];
+    for (const entry of index.files) {
+        files.push({
+            path: entry.path,
+            before: entry.before ? await readText(join(sideDir(dir, 'before'), entry.path)) : null,
+            after: entry.after ? await readText(join(sideDir(dir, 'after'), entry.path)) : null,
+        });
+    }
+    return { ...index, files };
+}
+/** Every park of the project, oldest first. */
+export async function listParks(projectRoot) {
+    let names;
+    try {
+        names = (await readdir(parkRoot(projectRoot), { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const parks = [];
+    for (const name of names) {
+        const path = join(parkRoot(projectRoot), name, 'park.json');
+        if (await pathExists(path))
+            parks.push(await readJson(path));
+    }
+    return parks.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+/** Deletes a park. */
+export async function dropPark(projectRoot, label) {
+    assertParkLabel(label);
+    const dir = join(parkRoot(projectRoot), label);
+    if (!(await pathExists(dir))) {
+        throw new InvalidArgumentError(`No park named "${label}".`, label);
+    }
+    await rm(dir, { recursive: true, force: true });
+}
+/** Reads an engine file, null when absent. */
+export async function readEngineFile(engineDir, path) {
+    const full = join(engineDir, path);
+    return (await pathExists(full)) ? await readText(full) : null;
+}
+/** Writes an engine file, removing it for null. */
+export async function writeEngineFile(engineDir, path, content) {
+    const full = join(engineDir, path);
+    if (content === null) {
+        if (await pathExists(full))
+            await removeFile(full);
+        return;
+    }
+    await ensureDir(dirname(full));
+    await writeText(full, content);
+}
+/**
+ * Three-way merges `ours` and `theirs` over `base` with `git merge-file`.
+ * Conflicts come back as marker blocks.
+ */
+export async function mergeThreeWay(ours, base, theirs, path) {
+    const scratch = await mkdtemp(join(tmpdir(), 'fireforge-park-'));
+    try {
+        const files = {
+            ours: join(scratch, 'ours'),
+            base: join(scratch, 'base'),
+            theirs: join(scratch, 'theirs'),
+        };
+        await writeFile(files.ours, ours);
+        await writeFile(files.base, base);
+        await writeFile(files.theirs, theirs);
+        const result = await exec('git', [
+            'merge-file',
+            '-p',
+            '-L',
+            `${path} (now)`,
+            '-L',
+            `${path} (parked from)`,
+            '-L',
+            `${path} (parked)`,
+            files.ours,
+            files.base,
+            files.theirs,
+        ]);
+        if (result.exitCode < 0 || result.exitCode > 127) {
+            throw new Error(`git merge-file failed for ${path}: ${result.stderr.trim()}`);
+        }
+        return { content: result.stdout, conflicts: result.exitCode };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * What restoring one parked file writes: `before` when the file is still
+ * as the park left it, nothing when it already matches `before`, and a
+ * three-way merge otherwise. Absence only merges with absence.
+ */
+export async function planRestore(file, now) {
+    if (now === file.after)
+        return { outcome: 'restored', content: file.before };
+    if (now === file.before)
+        return { outcome: 'unchanged', content: now };
+    if (now === null || file.before === null || file.after === null) {
+        return { outcome: 'conflict', content: now };
+    }
+    const merged = await mergeThreeWay(now, file.after, file.before, file.path);
+    return { outcome: merged.conflicts > 0 ? 'conflict' : 'merged', content: merged.content };
+}
+/** Message ids a Fluent file's lines declare (`id = …`, `-term = …`). */
+export function fluentIds(lines) {
+    const ids = [];
+    for (const line of lines) {
+        const match = /^(-?[A-Za-z][\w-]*)\s*=/.exec(line);
+        if (match?.[1] !== undefined)
+            ids.push(match[1]);
+    }
+    return ids;
+}
+/** Lines `before` has that `after` lacks, as a multiset difference. */
+export function removedLines(before, after) {
+    const remaining = new Map();
+    for (const line of (after ?? '').split('\n'))
+        remaining.set(line, (remaining.get(line) ?? 0) + 1);
+    const removed = [];
+    for (const line of (before ?? '').split('\n')) {
+        const count = remaining.get(line) ?? 0;
+        if (count > 0)
+            remaining.set(line, count - 1);
+        else
+            removed.push(line);
+    }
+    return removed;
+}

package/dist/src/core/patch-export-update.d.ts

@@ -24,6 +24,8 @@ export interface UpdatePatchAndMetadataOptions {
     newContent: string;
     /** Manifest-row fields to merge into the patch's metadata. */
     updates: Partial<PatchMetadata>;
+    /** Manifest-row fields to delete, e.g. a staged block left empty. */
+    unset?: readonly (keyof PatchMetadata)[] | undefined;
     /** Hook run under the lock after the mutation succeeds. */
     onCommitted?: UpdatePatchCommittedHook | undefined;
     /** Policy gate run against the under-lock projected manifest. */
@@ -49,3 +51,5 @@ export interface UpdatePatchAndMetadataOptions {
  *   already byte-identical to the new content.
  */
 export declare function updatePatchAndMetadata(options: UpdatePatchAndMetadataOptions): Promise<boolean>;
+/** A copy of `row` without `fields`. */
+export declare function withoutFields(row: PatchMetadata, fields: readonly (keyof PatchMetadata)[]): PatchMetadata;