@hominis/fireforge 0.50.0 → 0.51.0

package/dist/src/core/mach.js

@@ -7,6 +7,7 @@ import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from
 import { withBuildRunRecord } from './build-run-record.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
+import { createLinePrefixer } from './line-prefixer.js';
 import { explainMachError } from './mach-error-hints.js';
 import { createKnownTeardownNoiseFilter, createTeardownNoiseContext, hasKnownTeardownNoise, KNOWN_TEARDOWN_NOISE_BUILD_NOTE, } from './mach-known-noise-filter.js';
 import { getPython } from './mach-python.js';
@@ -89,6 +90,15 @@ export async function runMachCapture(args, engineDir, options = {}) {
     const noiseContext = options.annotateKnownTeardownNoise === true ? createTeardownNoiseContext() : undefined;
     const stdoutFilter = noiseContext && createKnownTeardownNoiseFilter(noiseContext);
     const stderrFilter = noiseContext && createKnownTeardownNoiseFilter(noiseContext);
+    const prefix = options.outputPrefix;
+    const prefixers = prefix === undefined
+        ? undefined
+        : {
+            stdoutLog: createLinePrefixer(prefix),
+            stdoutEcho: createLinePrefixer(prefix),
+            stderrLog: createLinePrefixer(prefix),
+            stderrEcho: createLinePrefixer(prefix),
+        };
     const exitCode = await execStream(python, [machPath, ...args], {
         cwd: engineDir,
         ...(options.env ? { env: options.env } : {}),
@@ -110,8 +120,9 @@ export async function runMachCapture(args, engineDir, options = {}) {
             // echo filter only exists to shorten what a human scrolls past.
             // Collapsing a traceback in the artifact would reintroduce the loss
             // this log exists to prevent.
-            writeToActiveRunLog(data);
-            process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
+            writeToActiveRunLog(prefixers ? prefixers.stdoutLog.transform(data) : data);
+            const echo = stdoutFilter ? stdoutFilter.transform(data) : data;
+            process.stdout.write(prefixers ? prefixers.stdoutEcho.transform(echo) : echo);
         },
         onStderr: (data) => {
             options.onOutputChunk?.('stderr', data);
@@ -119,19 +130,22 @@ export async function runMachCapture(args, engineDir, options = {}) {
             if (stderr.length > CAPTURE_TAIL_LIMIT) {
                 stderr = stderr.slice(-CAPTURE_TAIL_LIMIT);
             }
-            writeToActiveRunLog(data);
-            process.stderr.write(stderrFilter ? stderrFilter.transform(data) : data);
+            writeToActiveRunLog(prefixers ? prefixers.stderrLog.transform(data) : data);
+            const echo = stderrFilter ? stderrFilter.transform(data) : data;
+            process.stderr.write(prefixers ? prefixers.stderrEcho.transform(echo) : echo);
         },
     });
     if (stdoutFilter) {
         const residue = stdoutFilter.flush();
-        if (residue.length > 0)
-            process.stdout.write(residue);
+        if (residue.length > 0) {
+            process.stdout.write(prefixers ? prefixers.stdoutEcho.transform(residue) : residue);
+        }
     }
     if (stderrFilter) {
         const residue = stderrFilter.flush();
-        if (residue.length > 0)
-            process.stderr.write(residue);
+        if (residue.length > 0) {
+            process.stderr.write(prefixers ? prefixers.stderrEcho.transform(residue) : residue);
+        }
     }
     return { stdout, stderr, exitCode };
 }
@@ -418,13 +432,14 @@ function testVerbosityEnvUnset(fullOutput) {
  * @param options - Engine checkout, test paths, extra args, env, verbosity
  */
 export async function runMachTestSuite(kind, options) {
-    const { engineDir, testPaths = [], args = [], env, fullOutput, teardown } = options;
+    const { engineDir, testPaths = [], args = [], env, fullOutput, teardown, outputPrefix } = options;
     const guard = await installMachResourceGuard(engineDir);
     const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture([kind, ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
         ...(envUnset ? { envUnset } : {}),
         ...teardown,
+        ...(outputPrefix === undefined ? {} : { outputPrefix }),
         annotateKnownTeardownNoise: true,
     });
 }

package/dist/src/core/module-resolution-preflight.d.ts

@@ -18,6 +18,12 @@
  * no owned file is an upstream Firefox module, which FireForge does not
  * police and cannot cheaply enumerate. Policing only what the fork owns is
  * both the actionable set and the one that produces real incidents.
+ *
+ * An unscoped `verify` widens that set with the engine worktree: changed
+ * files import, and untracked files are targets. A chrome script's lazy
+ * getter for a new, not yet exported `.sys.mjs` with no moz.build line
+ * SIGSEGVed every start of a shared objdir, and neither file was in the
+ * queue yet, so the queue-only scan could not see it.
  */
 /** Why a queue-owned module import does not resolve to a packaged module. */
 export type UnresolvedModuleReason = 'missing-file' | 'unregistered';
@@ -31,16 +37,26 @@ export interface UnresolvedModuleImport {
     importers: string[];
     reason: UnresolvedModuleReason;
 }
+/** Engine worktree files the preflight also judges, beside the queue's. */
+export interface WorktreeModuleFiles {
+    /** Changed or untracked files: scanned for imports. */
+    changed: readonly string[];
+    /** Untracked files: new modules the fork has not exported yet. */
+    untracked: readonly string[];
+}
+/** Lists the engine's changed and untracked files for the worktree scan. */
+export declare function collectWorktreeModuleFiles(engineDir: string): Promise<WorktreeModuleFiles>;
 /**
  * Resolves every `resource://` system-module import made by the
- * queue-owned files and reports the ones a packaged browser could not
- * load.
+ * queue-owned files (and, given `worktree`, by changed engine files) and
+ * reports the ones a packaged browser could not load.
  *
  * @param engineDir - Path to the engine checkout
  * @param ownedFiles - Engine-relative paths the patch queue owns
+ * @param worktree - Changed and untracked engine files to judge as well
  * @returns Findings sorted by module path. Empty when everything resolves
  */
-export declare function findUnresolvedSystemModuleImports(engineDir: string, ownedFiles: readonly string[]): Promise<UnresolvedModuleImport[]>;
+export declare function findUnresolvedSystemModuleImports(engineDir: string, ownedFiles: readonly string[], worktree?: WorktreeModuleFiles): Promise<UnresolvedModuleImport[]>;
 /**
  * Renders findings as operator-facing lines, naming the unregistered or
  * unresolvable module, so the failure is a sentence instead of a bare

package/dist/src/core/module-resolution-preflight.js

@@ -19,12 +19,19 @@
  * no owned file is an upstream Firefox module, which FireForge does not
  * police and cannot cheaply enumerate. Policing only what the fork owns is
  * both the actionable set and the one that produces real incidents.
+ *
+ * An unscoped `verify` widens that set with the engine worktree: changed
+ * files import, and untracked files are targets. A chrome script's lazy
+ * getter for a new, not yet exported `.sys.mjs` with no moz.build line
+ * SIGSEGVed every start of a shared objdir, and neither file was in the
+ * queue yet, so the queue-only scan could not see it.
  */
 import { dirname, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { escapeRegex } from '../utils/regex.js';
+import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from './git-status.js';
 import { extractResourceModuleSpecifiers, moduleSourceSuffix, } from './patch-lint-module-registration.js';
 /** Extensions whose contents are scanned for resource-module imports. */
 const IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
@@ -79,20 +86,31 @@ async function isRegisteredInAncestorMozBuild(engineDir, moduleRelPath, mozBuild
         dir = parent;
     }
 }
+/** Lists the engine's changed and untracked files for the worktree scan. */
+export async function collectWorktreeModuleFiles(engineDir) {
+    const entries = await expandUntrackedDirectoryEntries(engineDir, await getWorkingTreeStatus(engineDir));
+    const present = entries.filter((entry) => entry.worktreeStatus !== 'D');
+    return {
+        changed: present.map((entry) => entry.file),
+        untracked: present.filter((entry) => entry.status === '??').map((entry) => entry.file),
+    };
+}
 /**
  * Resolves every `resource://` system-module import made by the
- * queue-owned files and reports the ones a packaged browser could not
- * load.
+ * queue-owned files (and, given `worktree`, by changed engine files) and
+ * reports the ones a packaged browser could not load.
  *
  * @param engineDir - Path to the engine checkout
  * @param ownedFiles - Engine-relative paths the patch queue owns
+ * @param worktree - Changed and untracked engine files to judge as well
  * @returns Findings sorted by module path. Empty when everything resolves
  */
-export async function findUnresolvedSystemModuleImports(engineDir, ownedFiles) {
-    const owned = [...new Set(ownedFiles)];
-    /** specifier → importing owned files. */
+export async function findUnresolvedSystemModuleImports(engineDir, ownedFiles, worktree) {
+    const owned = [...new Set([...ownedFiles, ...(worktree?.untracked ?? [])])];
+    const importing = [...new Set([...owned, ...(worktree?.changed ?? [])])];
+    /** specifier → importing files. */
     const importersBySpecifier = new Map();
-    for (const file of owned) {
+    for (const file of importing) {
         if (!IMPORTABLE_EXTENSIONS.some((extension) => file.endsWith(extension)))
             continue;
         const content = await readIfPresent(join(engineDir, file));

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

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/**
+ * 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 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,73 @@
+// 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.
+ */
+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 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 {};