@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/re-export-adjacent.d.ts

@@ -1,4 +1,4 @@
-import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+import type { PatchesManifest, PatchMetadata, ReExportOptions } from '../types/commands/index.js';
 import type { ProjectPaths } from '../types/config.js';
 /**
  * Shared per-run context for the adjacency advisory: the classification
@@ -18,6 +18,23 @@ export interface AdjacentUnmanagedContext {
     approvedUnmanaged: ReadonlySet<string>;
     /** Approved paths actually met this run, so unused ones can be surfaced. */
     approvedSeen: Set<string>;
+    /**
+     * Engine-relative paths named by `--expect-new`: files this session
+     * created and will adopt with its next export (or `--scan-file`). They
+     * pass the belt and are reported, while every other adjacent file still
+     * refuses, so a peer's neighbour is not admitted with them.
+     */
+    expectedNew: ReadonlySet<string>;
+    /** `--expect-new` paths actually met this run. */
+    expectedNewSeen: Set<string>;
+    /**
+     * Reviewed `--adjacent-ignore` entries: an engine-relative path, or a
+     * glob whose `*` stays within one path segment. Matches are reported in
+     * one line and never refuse.
+     */
+    adjacentIgnore: readonly string[];
+    /** `--adjacent-ignore` entries that matched a file this run. */
+    adjacentIgnoreSeen: Set<string>;
     /**
      * Offenders collected across the loop. `files` stays the bare paths that
      * downstream consumers already read. `anchored` carries the same entries
@@ -30,6 +47,16 @@ export interface AdjacentUnmanagedContext {
         anchored: string[];
     }[];
 }
+/**
+ * Builds the run's adjacency context. The path flags are normalized once
+ * here, so the per-file comparison matches git's engine-relative output.
+ */
+export declare function buildAdjacentUnmanagedContext(options: ReExportOptions, binaryName: string, furnacePrefixes: ReadonlySet<string>): AdjacentUnmanagedContext;
+/**
+ * The one definition of "adjacent", shared by the per-patch notice and the
+ * run-level refusal so the two cannot drift apart.
+ */
+export declare const ADJACENT_MEANS: string;
 /** Returns the subset of `files` that no longer exist under `engineDir`. */
 export declare function findMissingFiles(engineDir: string, files: readonly string[]): Promise<string[]>;
 /**
@@ -44,8 +71,13 @@ export declare function findMissingFiles(engineDir: string, files: readonly stri
 export interface AdjacentUnmanagedFile {
     /** Engine-relative path of the unmanaged file. */
     file: string;
-    /** Directory holding at least one file this patch owns. */
+    /**
+     * Directory holding at least one file this patch owns, or for a
+     * registration-named file, the directory of the carrier naming it.
+     */
     anchorDir: string;
+    /** The owned carrier whose added registration line names the file. */
+    registeredBy?: string;
 }
 /**
  * Emits the scan-less advisory for one patch: missing manifest files and
@@ -61,4 +93,20 @@ export declare function reportAdjacentUnmanagedFiles(args: {
     manifest: PatchesManifest;
     currentFilesAffected: readonly string[];
     ctx: AdjacentUnmanagedContext;
+    /**
+     * Set beside `--scan`: the scan has already reconciled missing files and
+     * adopted what it was asked to, so only the neighbours it left are judged.
+     */
+    afterScan?: boolean;
 }): Promise<boolean>;
+/**
+ * End-of-run accounting for `--expect-new` and `--adjacent-ignore`.
+ *
+ * An `--expect-new` path is a promise that the next export adopts it, so a
+ * met one is repeated as the export still owed, and an unmet one is a
+ * warning: a typo there leaves the refusal armed for the file it meant to
+ * admit. An unmatched `--adjacent-ignore` entry is only noted, because a
+ * reviewed ignore list is reused across runs and patches, and "not met"
+ * is its normal case.
+ */
+export declare function reportAdjacentCarveOutUsage(ctx: AdjacentUnmanagedContext): void;

package/dist/src/commands/re-export-adjacent.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Scan-less re-export adjacency advisory.
+ * Re-export adjacency advisory.
  *
  * A plain `re-export` keeps the manifest's filesAffected unchanged, so a
  * brand-new file an author just created beside a patch's owned files is
@@ -8,7 +8,8 @@
  * files, filters out tool-managed paths (branding, furnace) so the notice
  * names only genuinely unmanaged candidates, and, under
  * `--refuse-adjacent-unmanaged`, lets the caller turn the notice into a
- * non-zero refusal.
+ * non-zero refusal. Beside `--scan` it judges the files the scan did not
+ * adopt, so a targeted `--scan-file` adoption keeps the belt.
  *
  * Split out of re-export.ts to keep that file inside the max-lines budget.
  * Exports helpers consumed by re-export.ts, no registrar.
@@ -21,6 +22,34 @@ import { isGeneratedBrandingPath } from '../core/status-classify.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
+import { escapeRegex } from '../utils/regex.js';
+import { findRegisteredChangedFiles } from './re-export-adjacent-registrations.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+/**
+ * Builds the run's adjacency context. The path flags are normalized once
+ * here, so the per-file comparison matches git's engine-relative output.
+ */
+export function buildAdjacentUnmanagedContext(options, binaryName, furnacePrefixes) {
+    const normalized = (flag, values) => (values ?? []).map((value) => normalizeEngineRelativeInput(value, flag));
+    return {
+        binaryName,
+        furnacePrefixes,
+        refuseAdjacentUnmanaged: options.refuseAdjacentUnmanaged === true,
+        approvedUnmanaged: new Set(normalized('--expect-unmanaged', options.expectUnmanaged)),
+        approvedSeen: new Set(),
+        expectedNew: new Set(normalized('--expect-new', options.expectNew)),
+        expectedNewSeen: new Set(),
+        adjacentIgnore: normalized('--adjacent-ignore', options.adjacentIgnore),
+        adjacentIgnoreSeen: new Set(),
+        refusals: [],
+    };
+}
+/**
+ * The one definition of "adjacent", shared by the per-patch notice and the
+ * run-level refusal so the two cannot drift apart.
+ */
+export const ADJACENT_MEANS = 'Adjacent means the file sits in the same directory as a file this patch owns, ' +
+    'or a registration line this patch adds (jar.mn, moz.build, test manifest) names it.';
 /** Concurrency bound for existence probes (matches the classify/lint pools). */
 const PATH_PROBE_CONCURRENCY = 8;
 /** Returns the subset of `files` that no longer exist under `engineDir`. */
@@ -42,14 +71,41 @@ function isToolManagedPath(file, isNewFile, ctx) {
     }
     return false;
 }
+/**
+ * Matches an `--adjacent-ignore` entry. A `*` stays inside one path
+ * segment, the same narrowness as `buildAudit.unpackaged`: a carve-out that
+ * silently spans subtrees is how a reviewed exception becomes a blanket one.
+ */
+function matchesIgnoreEntry(entry, file) {
+    if (!entry.includes('*'))
+        return entry === file;
+    const pattern = entry
+        .split('*')
+        .map((part) => escapeRegex(part))
+        .join('[^/]*');
+    return new RegExp(`^${pattern}$`).test(file);
+}
+/**
+ * Lists the unmanaged files a re-export of this patch would plausibly have
+ * to capture: changed files directly in a directory the patch owns a file
+ * in, and changed files a registration line the patch adds names. A file in
+ * a sibling or nested directory is not adjacent. The directory listing
+ * recurses (pathspecs do), so it is filtered back to the exact directories,
+ * the same footprint the broad `--scan` adopts from.
+ */
 async function findAdjacentUnmanagedFiles(args) {
     const { currentFilesAffected, engineDir, manifest, patchFilename, ctx } = args;
     const parentDirs = [...new Set(currentFilesAffected.map((file) => dirname(file)))];
+    const parentDirSet = new Set(parentDirs);
     const currentSet = new Set(currentFilesAffected);
     const claimedByOthers = getClaimedFiles(manifest, patchFilename);
-    // First anchor wins: the dirs are scanned in ownership order and a file
-    // lives in exactly one of them, so the map is a dedupe, not a choice.
+    // First anchor wins: a file lives in exactly one directory, and a
+    // directory anchor is the stronger statement than a registration one.
     const candidates = new Map();
+    const isCandidate = (file, isNewFile) => !currentSet.has(file) &&
+        !claimedByOthers.has(file) &&
+        !candidates.has(file) &&
+        !isToolManagedPath(file, isNewFile, ctx);
     for (const dir of parentDirs) {
         const [modifiedFiles, untrackedFiles] = await Promise.all([
             getModifiedFilesInDir(engineDir, dir),
@@ -57,41 +113,80 @@ async function findAdjacentUnmanagedFiles(args) {
         ]);
         const untrackedSet = new Set(untrackedFiles);
         for (const file of [...modifiedFiles, ...untrackedFiles]) {
-            if (currentSet.has(file) || claimedByOthers.has(file))
+            if (!parentDirSet.has(dirname(file)))
                 continue;
-            if (isToolManagedPath(file, untrackedSet.has(file), ctx))
-                continue;
-            if (!candidates.has(file))
-                candidates.set(file, dir);
+            if (isCandidate(file, untrackedSet.has(file))) {
+                candidates.set(file, { file, anchorDir: dirname(file) });
+            }
+        }
+    }
+    const registered = await findRegisteredChangedFiles(engineDir, currentFilesAffected);
+    for (const { file, carrier } of registered) {
+        // A registered path is a patch candidate whatever its tracking state,
+        // so it is classified as new: only a generated path is tool-managed.
+        if (isCandidate(file, true)) {
+            candidates.set(file, { file, anchorDir: dirname(carrier), registeredBy: carrier });
         }
     }
-    return [...candidates.entries()]
-        .map(([file, anchorDir]) => ({ file, anchorDir }))
-        .sort((a, b) => a.file.localeCompare(b.file));
+    return [...candidates.values()].sort((a, b) => a.file.localeCompare(b.file));
+}
+function dispositionOf(file, ctx) {
+    if (ctx.approvedUnmanaged.has(file)) {
+        ctx.approvedSeen.add(file);
+        return 'approved';
+    }
+    if (ctx.expectedNew.has(file)) {
+        ctx.expectedNewSeen.add(file);
+        return 'expected-new';
+    }
+    const ignore = ctx.adjacentIgnore.find((entry) => matchesIgnoreEntry(entry, file));
+    if (ignore !== undefined) {
+        ctx.adjacentIgnoreSeen.add(ignore);
+        return 'ignored';
+    }
+    return 'refusing';
 }
 /**
- * Splits the candidates into the ones that refuse and the ones a
- * `--expect-unmanaged` carve-out admits. Approved paths are recorded as seen
- * so an unused carve-out can be reported, and are returned rather than
- * dropped, so the exception stays visible instead of quietly widening.
+ * Splits the candidates into the ones that refuse and the ones a carve-out
+ * (`--expect-unmanaged`, `--expect-new`, `--adjacent-ignore`) admits. Met
+ * carve-outs are recorded so an unused one can be reported, and admitted
+ * files are returned rather than dropped, so the exception stays visible
+ * instead of quietly widening.
  */
 function partitionApproved(files, ctx) {
-    const refusing = [];
-    const approved = [];
-    for (const entry of files) {
-        if (ctx.approvedUnmanaged.has(entry.file)) {
-            ctx.approvedSeen.add(entry.file);
-            approved.push(entry);
-        }
-        else {
-            refusing.push(entry);
-        }
-    }
-    return { refusing, approved };
+    const groups = {
+        refusing: [],
+        approved: [],
+        'expected-new': [],
+        ignored: [],
+    };
+    for (const entry of files)
+        groups[dispositionOf(entry.file, ctx)].push(entry);
+    return groups;
 }
-/** Renders `<file> (beside engine/<dir>)` for a notice line. */
+/** How a notice names one file's anchor. */
+function describeAnchor(entry) {
+    return entry.registeredBy !== undefined
+        ? `registered by engine/${entry.registeredBy}`
+        : `beside engine/${entry.anchorDir}`;
+}
+/** Renders `<file> (beside engine/<dir>)` or `<file> (registered by engine/<carrier>)`. */
 function describeAnchored(entry) {
-    return `${entry.file} (beside engine/${entry.anchorDir})`;
+    return `${entry.file} (${describeAnchor(entry)})`;
+}
+/** The admitted-file notice lines, one per carve-out that admitted anything. */
+function reportAdmitted(patchFilename, groups) {
+    const notices = [
+        [groups.approved, 'admitted by --expect-unmanaged'],
+        [groups['expected-new'], 'expected by --expect-new'],
+        [groups.ignored, 'ignored by --adjacent-ignore'],
+    ];
+    for (const [entries, how] of notices) {
+        if (entries.length === 0)
+            continue;
+        info(`${patchFilename}: ${entries.length} adjacent unmanaged file(s) ${how} ` +
+            `(${entries.map(describeAnchored).join(', ')}) — reported, not refused.`);
+    }
 }
 /**
  * Emits the scan-less advisory for one patch: missing manifest files and
@@ -103,7 +198,7 @@ function describeAnchored(entry) {
  */
 export async function reportAdjacentUnmanagedFiles(args) {
     const { patch, paths, manifest, currentFilesAffected, ctx } = args;
-    const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
+    const missingFiles = args.afterScan === true ? [] : await findMissingFiles(paths.engine, currentFilesAffected);
     if (missingFiles.length > 0) {
         warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
             `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +
@@ -119,20 +214,19 @@ export async function reportAdjacentUnmanagedFiles(args) {
         patchFilename: patch.filename,
         ctx,
     });
-    const { refusing: unmanagedFiles, approved } = partitionApproved(allUnmanaged, ctx);
-    if (approved.length > 0) {
-        info(`${patch.filename}: ${approved.length} adjacent unmanaged file(s) admitted by ` +
-            `--expect-unmanaged (${approved.map(describeAnchored).join(', ')}) — reported, not refused.`);
-    }
+    const groups = partitionApproved(allUnmanaged, ctx);
+    reportAdmitted(patch.filename, groups);
+    const unmanagedFiles = groups.refusing;
     if (unmanagedFiles.length === 0)
         return false;
     const firstFew = unmanagedFiles.slice(0, 3).map(describeAnchored).join(', ');
     const more = unmanagedFiles.length > 3 ? `, +${unmanagedFiles.length - 3} more` : '';
-    warn(`${patch.filename}: found ${unmanagedFiles.length} unmanaged file(s) adjacent to this patch's ownership (${firstFew}${more}); ` +
-        `adjacent means the file sits in a directory this patch already owns a file in. ` +
-        `Plain re-export keeps filesAffected unchanged — use --scan-file to include reviewed files.`);
+    warn(`${patch.filename}: found ${unmanagedFiles.length} unmanaged file(s) adjacent to this patch's ownership (${firstFew}${more}). ` +
+        `${ADJACENT_MEANS} ` +
+        `Plain re-export keeps filesAffected unchanged — use --scan-file to include reviewed files, ` +
+        `or --expect-new for a file your next export adopts.`);
     for (const entry of unmanagedFiles) {
-        info(`  ${entry.file} — beside engine/${entry.anchorDir} — ` +
+        info(`  ${entry.file} — ${describeAnchor(entry)} — ` +
             `fireforge re-export ${patch.filename} --scan --scan-file ${entry.file}`);
     }
     if (ctx.refuseAdjacentUnmanaged) {
@@ -145,3 +239,29 @@ export async function reportAdjacentUnmanagedFiles(args) {
     }
     return false;
 }
+/**
+ * End-of-run accounting for `--expect-new` and `--adjacent-ignore`.
+ *
+ * An `--expect-new` path is a promise that the next export adopts it, so a
+ * met one is repeated as the export still owed, and an unmet one is a
+ * warning: a typo there leaves the refusal armed for the file it meant to
+ * admit. An unmatched `--adjacent-ignore` entry is only noted, because a
+ * reviewed ignore list is reused across runs and patches, and "not met"
+ * is its normal case.
+ */
+export function reportAdjacentCarveOutUsage(ctx) {
+    const unseenNew = [...ctx.expectedNew].filter((file) => !ctx.expectedNewSeen.has(file));
+    if (unseenNew.length > 0) {
+        warn(`--expect-new path(s) were not met as adjacent unmanaged files this run: ` +
+            `${unseenNew.join(', ')}. Check the path for a typo, and that a selected patch owns a ` +
+            'file in its directory or registers it. The refusal stayed armed for everything else.');
+    }
+    if (ctx.expectedNewSeen.size > 0) {
+        info(`--expect-new admitted ${[...ctx.expectedNewSeen].sort().join(', ')}, which no patch owns ` +
+            'yet. Export them next so the queue does not register files it does not ship.');
+    }
+    const unseenIgnore = ctx.adjacentIgnore.filter((entry) => !ctx.adjacentIgnoreSeen.has(entry));
+    if (unseenIgnore.length > 0) {
+        info(`--adjacent-ignore entries matched no adjacent file this run: ${unseenIgnore.join(', ')}.`);
+    }
+}

package/dist/src/commands/re-export-bulk-scan.d.ts

@@ -1,4 +1,5 @@
 import type { PatchesManifest } from '../types/commands/index.js';
+import { type DryRunPurityScope } from './re-export-purity-scope.js';
 /** Loads and validates a `re-export --scan-files` assignment manifest. */
 export declare function loadScanFilesAssignments(manifestPath: string, manifest: PatchesManifest): Promise<Map<string, string[]>>;
 /**
@@ -13,6 +14,6 @@ export declare function loadScanFilesAssignments(manifestPath: string, manifest:
  * violation surfaces the violation with the original error as `cause`.
  * No-op outside dry-run.
  */
-export declare function withDryRunPurityGuard<T>(engineDir: string, patchesDir: string, isDryRun: boolean, operation: () => Promise<T>): Promise<T>;
+export declare function withDryRunPurityGuard<T>(engineDir: string, patchesDir: string, isDryRun: boolean, operation: () => Promise<T>, scope?: DryRunPurityScope): Promise<T>;
 /** Serializes dry-run re-export git inspection against the same project tree. */
 export declare function withDryRunReExportLock<T>(fireforgeDir: string, isDryRun: boolean, operation: () => Promise<T>): Promise<T>;

package/dist/src/commands/re-export-bulk-scan.js

@@ -11,6 +11,7 @@ import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { sha256Hex } from '../utils/hash.js';
 import { isObject } from '../utils/validation.js';
+import { describeForeignWriters, fingerprintScopedDryRunState, } from './re-export-purity-scope.js';
 import { normalizeEngineRelativeInput } from './re-export-scan.js';
 /** Concurrency bound for patch-body hashing (matches the classify/lint pools). */
 const PATCH_HASH_CONCURRENCY = 8;
@@ -161,10 +162,14 @@ async function fingerprintDryRunState(engineDir, patchesDir) {
  * violation surfaces the violation with the original error as `cause`.
  * No-op outside dry-run.
  */
-export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, operation) {
+export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, operation, scope) {
     if (!isDryRun)
         return operation();
-    const before = await fingerprintDryRunState(engineDir, patchesDir);
+    const fingerprint = () => scope === undefined
+        ? fingerprintDryRunState(engineDir, patchesDir)
+        : fingerprintScopedDryRunState(engineDir, patchesDir, scope);
+    const startedAt = Date.now();
+    const before = await fingerprint();
     let result;
     let operationError;
     let failed = false;
@@ -177,7 +182,7 @@ export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, ope
     }
     let after;
     try {
-        after = await fingerprintDryRunState(engineDir, patchesDir);
+        after = await fingerprint();
     }
     catch (fingerprintError) {
         // The post-run fingerprint failing must not swallow the dry run's own
@@ -195,10 +200,20 @@ export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, ope
         .sort()
         .filter((key) => before.get(key) !== after.get(key));
     if (touched.length > 0) {
-        throw new GeneralError(`[dry-run] invariant violated: this dry run modified ${touched.join(', ')}. ` +
-            'This is a FireForge bug — please report it, and inspect the listed state ' +
-            '(e.g. `git status` in engine/ and your patches/ diff) before trusting it.' +
-            (failed ? ` The dry run also failed: ${toError(operationError).message}` : ''), operationError);
+        const also = failed ? ` The dry run also failed: ${toError(operationError).message}` : '';
+        const writers = await describeForeignWriters(patchesDir, startedAt);
+        if (writers.length > 0) {
+            throw new GeneralError(`[dry-run] ${touched.join(', ')} changed during this dry run, written by another ` +
+                `writer: ${writers.join('; ')}. The preview raced that write; rerun it once the ` +
+                `writer is done.${also}`, operationError);
+        }
+        throw new GeneralError(`[dry-run] invariant violated: ${touched.join(', ')} changed during this dry run. No ` +
+            'other FireForge command recorded a write in that window, so either another writer ' +
+            '(an editor, an agent or a git command in engine/) changed it, or this is a FireForge ' +
+            'bug. Rerun the dry run; if it repeats on a quiet tree, please report it, and inspect ' +
+            'the listed state (e.g. `git status` in engine/ and your patches/ diff) before ' +
+            'trusting it.' +
+            also, operationError);
     }
     if (failed)
         throw operationError;

package/dist/src/commands/re-export-drift.d.ts

@@ -8,7 +8,7 @@
  * (`re-export-adjacent.ts`) warns about unmanaged neighbour files but is
  * structurally blind to drift inside owned files. This module compares
  * the old body against the refreshed body per file and reports the
- * payload lines that are about to enter the body. Under
+ * payload lines that are about to enter or leave the body. Under
  * `--refuse-foreign-drift` the patch is skipped and the run exits
  * non-zero, mirroring `--refuse-adjacent-unmanaged`.
  *
@@ -41,23 +41,39 @@ export interface ForeignDriftContext {
         reason: ForeignDriftRefusalReason;
     }[];
 }
-/** One owned file's foreign drift between the old and refreshed body. */
+/**
+ * One owned file's foreign drift between the old and refreshed body,
+ * counted as edits to the engine file rather than as body payload, so a
+ * deletion-only change is drift like any other.
+ */
 export interface FileForeignDrift {
     file: string;
-    /** `+` payload lines in the new body not present in the old body. */
+    /**
+     * Lines the engine file gained since the old body: `+` payload the new
+     * body carries that the old did not, plus `-` payload the old body carried
+     * that the new one dropped (an upstream line restored).
+     */
     addedLines: number;
-    /** `-` payload lines in the new body not present in the old body. */
+    /**
+     * Lines the engine file lost since the old body: `-` payload the new body
+     * carries that the old did not, plus `+` payload the old body carried that
+     * the new one dropped (a line the patch added, now deleted).
+     */
     removedLines: number;
-    /** `@@` headers of new-body hunks carrying foreign lines (capped). */
+    /** `@@` headers of the hunks carrying those lines (capped). */
     hunkSummaries: string[];
     /** True when a binary section's recorded new-side blob hash changed. */
     binaryChanged: boolean;
 }
 /**
  * Pure comparison: per owned file, which `+`/`-` payload lines the
- * refreshed body carries that the old body did not. Files not in
- * `previousFilesAffected` are skipped, since those are intentional
- * adoptions (`--scan`) rather than drift.
+ * refreshed body carries that the old body did not, and which the old body
+ * carried that the refreshed one dropped. Both directions are drift: a
+ * concurrent session deleting a line the patch added changes the patch as
+ * surely as one adding a line, and a belt that only saw absorbed lines let
+ * such a deletion through silently. Files not in `previousFilesAffected`
+ * are skipped, since those are intentional adoptions (`--scan`) or
+ * retirements (`--expect-removed`) rather than drift.
  */
 export declare function computeForeignDrift(oldBody: string, newBody: string, previousFilesAffected: readonly string[]): FileForeignDrift[];
 /**
@@ -71,6 +87,18 @@ export declare function reportForeignDrift(args: {
     engineDir: string;
     newDiffContent: string;
     ctx: ForeignDriftContext;
+    /**
+     * The patch's files that the comparison covers. Defaults to its
+     * `filesAffected`; the caller narrows it by the `--expect-removed`
+     * retirements, which leave the body on purpose.
+     */
+    ownedFiles?: readonly string[];
+    /**
+     * Files a `--scan`/`--scan-file` adoption brings in this run. They sit
+     * outside the comparison (nothing to compare against) and count as
+     * expected, so naming one in `--expect` is not reported as unseen.
+     */
+    adoptedFiles?: readonly string[];
 }): Promise<boolean>;
 /**
  * Names `--expect` paths that never drifted this run. A typo'd