@hominis/fireforge 0.39.0 → 0.41.0

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

@@ -1,11 +1,17 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { isUnavailableGenerationToken, snapshotEngineGeneration, unavailableGenerationReason, } from '../core/engine-session-lock.js';
 import { createSiblingLockPath, withFileLock } from '../core/file-lock.js';
 import { resolvePatchIdentifier } from '../core/patch-manifest.js';
-import { InvalidArgumentError } from '../errors/base.js';
-import { toError } from '../utils/errors.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { normalizeEngineRelativeInput } from './re-export-scan.js';
+/** Concurrency bound for patch-body hashing (matches the classify/lint pools). */
+const PATCH_HASH_CONCURRENCY = 8;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -66,6 +72,140 @@ export async function loadScanFilesAssignments(manifestPath, manifest) {
     }
     return new Map([...filesByPatch.entries()].map(([patchFilename, files]) => [patchFilename, [...files].sort()]));
 }
+/**
+ * Fingerprints every piece of state a `re-export --dry-run` promises not to
+ * disturb: the engine's commit + working-tree status (via the same generation
+ * token `fireforge test` uses) and the byte content of every regular file
+ * under `patches/` — ALL of them, not just the selected patches, because the
+ * FORGE H1 field incident was a dry-run of patch B reverting a just-written
+ * export of patch A. A missing patches directory (ENOENT/ENOTDIR) fingerprints
+ * as empty — there is nothing there to protect — but any other listing failure
+ * (EACCES, EIO, …) throws: an unreadable directory is not evidence it is
+ * empty, and treating it as such would let the guard silently vouch for state
+ * it never saw (fail closed). The same rule covers an unmeasurable engine
+ * generation and an unreadable individual patch file; a before-pass failure
+ * aborts the dry run before it starts, since a guard that measured nothing
+ * cannot vouch for anything.
+ */
+async function fingerprintDryRunState(engineDir, patchesDir) {
+    const fingerprint = new Map();
+    const generation = await snapshotEngineGeneration(engineDir);
+    if (isUnavailableGenerationToken(generation)) {
+        // A failed probe measured nothing — hashing the failure token would let
+        // two identical failures compare "unchanged" (vouching for unmeasured
+        // state) and two differing messages report a spurious violation.
+        throw new GeneralError(`[dry-run] cannot fingerprint the engine working tree for the purity guard: ` +
+            unavailableGenerationReason(generation));
+    }
+    fingerprint.set('the engine working tree', createHash('sha256').update(generation).digest('hex'));
+    let names = [];
+    try {
+        const entries = await readdir(patchesDir, { withFileTypes: true });
+        names = entries
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        // No patches directory — nothing there to protect; the same condition on
+        // the post-run pass produces the same empty set, and a directory that
+        // appears mid-dry-run correctly reports as a violation. Any OTHER failure
+        // must not read as "empty": the guard would be vouching for state it
+        // never saw.
+        const code = getNodeErrorCode(error);
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            throw new GeneralError(`[dry-run] cannot fingerprint ${patchesDir} for the purity guard: ${toError(error).message}`, error);
+        }
+    }
+    const results = await mapWithConcurrency(names, PATCH_HASH_CONCURRENCY, async (name) => {
+        try {
+            return {
+                hash: createHash('sha256')
+                    .update(await readFile(join(patchesDir, name)))
+                    .digest('hex'),
+            };
+        }
+        catch (error) {
+            // A file that vanished between the listing and the read is omitted, so
+            // a dry run that DELETED a patch artifact reports as the violation it
+            // is (key present before, absent after) instead of hiding behind a
+            // fingerprinting error. Every other failure fails closed: a constant
+            // placeholder would make unreadable-before equal unreadable-after even
+            // when the bytes changed underneath.
+            const code = getNodeErrorCode(error);
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                return { vanished: true };
+            return { error };
+        }
+    });
+    for (const [index, name] of names.entries()) {
+        const result = results[index];
+        if (result === undefined)
+            continue;
+        if ('error' in result) {
+            throw new GeneralError(`[dry-run] cannot fingerprint ${join(patchesDir, name)} for the purity guard: ${toError(result.error).message}`, result.error);
+        }
+        if ('vanished' in result)
+            continue;
+        fingerprint.set(`patches/${name}`, result.hash);
+    }
+    return fingerprint;
+}
+/**
+ * Runtime enforcement of the dry-run purity contract (FORGE H1): fingerprints
+ * the engine tree and every patch artifact before and after `operation`, and
+ * throws when a dry-run changed anything it promised only to inspect. This
+ * turns any recurrence of the 0.40.0 "dry-run reverted a just-written export"
+ * incident into a hard, named failure instead of silent data loss discovered
+ * only when a later gate fails. The post-fingerprint runs whether `operation`
+ * resolves or rejects — a dry-run that mutates state and THEN fails is exactly
+ * the case where a rollback defect must not go unreported; a rejection with a
+ * purity violation surfaces the violation with the original error as `cause`.
+ * No-op outside dry-run.
+ */
+export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, operation) {
+    if (!isDryRun)
+        return operation();
+    const before = await fingerprintDryRunState(engineDir, patchesDir);
+    let result;
+    let operationError;
+    let failed = false;
+    try {
+        result = await operation();
+    }
+    catch (error) {
+        failed = true;
+        operationError = error;
+    }
+    let after;
+    try {
+        after = await fingerprintDryRunState(engineDir, patchesDir);
+    }
+    catch (fingerprintError) {
+        // The post-run fingerprint failing must not swallow the dry run's own
+        // failure — an operation that mutated state, broke it, AND made it
+        // unreadable is exactly the case where both facts matter. The combined
+        // message carries both; the operation error stays the `cause`.
+        if (failed) {
+            throw new GeneralError(`[dry-run] this dry run failed (${toError(operationError).message}), and its purity could ` +
+                `not be verified afterwards: ${toError(fingerprintError).message}. Inspect engine/ and ` +
+                'your patches/ diff before trusting them.', operationError);
+        }
+        throw fingerprintError;
+    }
+    const touched = [...new Set([...before.keys(), ...after.keys()])]
+        .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);
+    }
+    if (failed)
+        throw operationError;
+    return result;
+}
 /** Serializes dry-run re-export git inspection against the same project tree. */
 export async function withDryRunReExportLock(fireforgeDir, isDryRun, operation) {
     if (!isDryRun)

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

@@ -0,0 +1,74 @@
+/**
+ * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`
+ * (FORGE J2).
+ *
+ * A scan-less re-export rebuilds each patch body as a whole-file
+ * `git diff HEAD` over the owned files — so a CONCURRENT session's
+ * uncommitted lines inside a file the patch already owns are silently
+ * absorbed into the refreshed body. The adjacency advisory
+ * (`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
+ * `--refuse-foreign-drift` the patch is skipped and the run exits
+ * non-zero, mirroring `--refuse-adjacent-unmanaged`.
+ *
+ * "Foreign" is decided by content, not authorship: re-export's legitimate
+ * job is capturing intentional engine edits, so the preview always prints
+ * and the hard stop is an explicit opt-in for multi-session checkouts.
+ * The comparison is offset-insensitive — per-file MULTISETS of `+`/`-`
+ * payload lines — because a refresh legitimately shifts hunk offsets and
+ * context without changing what the patch does.
+ */
+import type { PatchMetadata } from '../types/commands/index.js';
+/** Why a patch was refused under `--refuse-foreign-drift`. */
+export type ForeignDriftRefusalReason = 'foreign-drift' | 'baseline-unreadable';
+/** Per-run context threaded through the re-export loop (mirrors FORGE G2). */
+export interface ForeignDriftContext {
+    refuseForeignDrift: boolean;
+    /**
+     * Engine-relative files whose drift is expected (`--expect`, FORGE L6):
+     * drift confined to these files does not refuse. Files here that never
+     * drift are reported after the run as likely typos.
+     */
+    expectedDriftFiles: ReadonlySet<string>;
+    /** Expected files that actually drifted at least once this run. */
+    expectedSeen: Set<string>;
+    /** Number of patches whose old/new bodies reached the drift comparison. */
+    evaluationRuns: number;
+    refusals: {
+        patchFilename: string;
+        files: string[];
+        reason: ForeignDriftRefusalReason;
+    }[];
+}
+/** One owned file's foreign drift between the old and refreshed body. */
+export interface FileForeignDrift {
+    file: string;
+    /** `+` payload lines in the new body not present in the old body. */
+    addedLines: number;
+    /** `-` payload lines in the new body not present in the old body. */
+    removedLines: number;
+    /** `@@` headers of new-body hunks carrying foreign 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 — those are intentional adoptions
+ * (`--scan`), not drift.
+ */
+export declare function computeForeignDrift(oldBody: string, newBody: string, previousFilesAffected: readonly string[]): FileForeignDrift[];
+/**
+ * Reads the old body, prints the always-on drift preview (including under
+ * dry-run and `--scan`), and — when `ctx.refuseForeignDrift` is set —
+ * records a refusal and returns `true` so the caller skips the write.
+ */
+export declare function reportForeignDrift(args: {
+    patch: PatchMetadata;
+    patchesDir: string;
+    newDiffContent: string;
+    ctx: ForeignDriftContext;
+}): Promise<boolean>;

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

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`
+ * (FORGE J2).
+ *
+ * A scan-less re-export rebuilds each patch body as a whole-file
+ * `git diff HEAD` over the owned files — so a CONCURRENT session's
+ * uncommitted lines inside a file the patch already owns are silently
+ * absorbed into the refreshed body. The adjacency advisory
+ * (`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
+ * `--refuse-foreign-drift` the patch is skipped and the run exits
+ * non-zero, mirroring `--refuse-adjacent-unmanaged`.
+ *
+ * "Foreign" is decided by content, not authorship: re-export's legitimate
+ * job is capturing intentional engine edits, so the preview always prints
+ * and the hard stop is an explicit opt-in for multi-session checkouts.
+ * The comparison is offset-insensitive — per-file MULTISETS of `+`/`-`
+ * payload lines — because a refresh legitimately shifts hunk offsets and
+ * context without changing what the patch does.
+ */
+import { join } from 'node:path';
+import { parseDiffSections } from '../core/patch-parse.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, verbose, warn } from '../utils/logger.js';
+const MAX_HUNK_SUMMARIES_PER_FILE = 3;
+const MAX_FILES_REPORTED = 10;
+function collectPayloadByFile(body) {
+    const byFile = new Map();
+    for (const section of parseDiffSections(body)) {
+        const file = section.targetPath;
+        let payload = byFile.get(file);
+        if (!payload) {
+            payload = {
+                added: new Map(),
+                removed: new Map(),
+                binaryNewHash: undefined,
+                isBinary: false,
+                sections: [],
+            };
+            byFile.set(file, payload);
+        }
+        payload.sections.push(section);
+        if (section.isBinary) {
+            payload.isBinary = true;
+            payload.binaryNewHash = section.indexNewHash;
+            continue;
+        }
+        for (const hunk of section.hunks) {
+            for (const line of hunk.lines) {
+                if (line.startsWith('+')) {
+                    const text = line.slice(1);
+                    payload.added.set(text, (payload.added.get(text) ?? 0) + 1);
+                }
+                else if (line.startsWith('-')) {
+                    const text = line.slice(1);
+                    payload.removed.set(text, (payload.removed.get(text) ?? 0) + 1);
+                }
+            }
+        }
+    }
+    return byFile;
+}
+/** Multiset difference: occurrences of `next` not consumed by `previous`. */
+function multisetExcess(next, previous) {
+    const excess = new Map();
+    for (const [text, count] of next) {
+        const remaining = count - (previous.get(text) ?? 0);
+        if (remaining > 0)
+            excess.set(text, remaining);
+    }
+    return excess;
+}
+function summarizeForeignHunks(payload, foreignAdded, foreignRemoved) {
+    const summaries = [];
+    const addedBudget = new Map(foreignAdded);
+    const removedBudget = new Map(foreignRemoved);
+    for (const section of payload.sections) {
+        for (const hunk of section.hunks) {
+            let added = 0;
+            let removed = 0;
+            for (const line of hunk.lines) {
+                if (line.startsWith('+')) {
+                    const text = line.slice(1);
+                    const budget = addedBudget.get(text) ?? 0;
+                    if (budget > 0) {
+                        addedBudget.set(text, budget - 1);
+                        added++;
+                    }
+                }
+                else if (line.startsWith('-')) {
+                    const text = line.slice(1);
+                    const budget = removedBudget.get(text) ?? 0;
+                    if (budget > 0) {
+                        removedBudget.set(text, budget - 1);
+                        removed++;
+                    }
+                }
+            }
+            if (added > 0 || removed > 0) {
+                summaries.push(`@@ -${String(hunk.oldStart)},${String(hunk.oldCount)} +${String(hunk.newStart)},${String(hunk.newCount)} @@ (+${String(added)}/-${String(removed)})`);
+            }
+        }
+    }
+    return summaries;
+}
+function countExcess(excess) {
+    let total = 0;
+    for (const count of excess.values())
+        total += count;
+    return total;
+}
+/**
+ * Pure comparison: per owned file, which `+`/`-` payload lines the
+ * refreshed body carries that the old body did not. Files NOT in
+ * `previousFilesAffected` are skipped — those are intentional adoptions
+ * (`--scan`), not drift.
+ */
+export function computeForeignDrift(oldBody, newBody, previousFilesAffected) {
+    const owned = new Set(previousFilesAffected);
+    const oldByFile = collectPayloadByFile(oldBody);
+    const newByFile = collectPayloadByFile(newBody);
+    const drift = [];
+    for (const [file, next] of newByFile) {
+        if (!owned.has(file))
+            continue;
+        const previous = oldByFile.get(file);
+        if (next.isBinary || previous?.isBinary === true) {
+            const binaryChanged = next.binaryNewHash === undefined ||
+                previous?.binaryNewHash === undefined ||
+                !(next.binaryNewHash.startsWith(previous.binaryNewHash) ||
+                    previous.binaryNewHash.startsWith(next.binaryNewHash));
+            if (binaryChanged) {
+                drift.push({ file, addedLines: 0, removedLines: 0, hunkSummaries: [], binaryChanged });
+            }
+            continue;
+        }
+        const foreignAdded = multisetExcess(next.added, previous?.added ?? new Map());
+        const foreignRemoved = multisetExcess(next.removed, previous?.removed ?? new Map());
+        const addedLines = countExcess(foreignAdded);
+        const removedLines = countExcess(foreignRemoved);
+        if (addedLines === 0 && removedLines === 0)
+            continue;
+        drift.push({
+            file,
+            addedLines,
+            removedLines,
+            hunkSummaries: summarizeForeignHunks(next, foreignAdded, foreignRemoved).slice(0, MAX_HUNK_SUMMARIES_PER_FILE),
+            binaryChanged: false,
+        });
+    }
+    return drift;
+}
+/**
+ * Reads the old body, prints the always-on drift preview (including under
+ * dry-run and `--scan`), and — when `ctx.refuseForeignDrift` is set —
+ * records a refusal and returns `true` so the caller skips the write.
+ */
+export async function reportForeignDrift(args) {
+    const { patch, patchesDir, newDiffContent, ctx } = args;
+    const oldPath = join(patchesDir, patch.filename);
+    let oldBody;
+    try {
+        if (!(await pathExists(oldPath))) {
+            return refuseUnreadableBaseline(ctx, patch.filename, 'old patch body missing');
+        }
+        oldBody = await readText(oldPath);
+    }
+    catch (error) {
+        return refuseUnreadableBaseline(ctx, patch.filename, `old body unreadable (${toError(error).message})`);
+    }
+    const drift = computeForeignDrift(oldBody, newDiffContent, patch.filesAffected);
+    ctx.evaluationRuns += 1;
+    if (drift.length === 0)
+        return false;
+    const unexpected = drift.filter((d) => !ctx.expectedDriftFiles.has(d.file));
+    for (const entry of drift) {
+        if (ctx.expectedDriftFiles.has(entry.file))
+            ctx.expectedSeen.add(entry.file);
+    }
+    const totalLines = drift.reduce((sum, d) => sum + d.addedLines + d.removedLines, 0);
+    const lineNoun = totalLines === 1 ? 'line' : 'lines';
+    warn(`${patch.filename}: refreshed body absorbs ${String(totalLines)} ${lineNoun} not present in the old patch body (${String(drift.length)} file(s)):`);
+    for (const entry of drift.slice(0, MAX_FILES_REPORTED)) {
+        const expectedTag = ctx.expectedDriftFiles.has(entry.file) ? ' (expected via --expect)' : '';
+        if (entry.binaryChanged) {
+            info(`  ${entry.file}: binary content changed${expectedTag}`);
+            continue;
+        }
+        info(`  ${entry.file}: +${String(entry.addedLines)}/-${String(entry.removedLines)} newly captured line(s)${expectedTag}`);
+        for (const summary of entry.hunkSummaries) {
+            info(`    ${summary}`);
+        }
+    }
+    if (drift.length > MAX_FILES_REPORTED) {
+        info(`  +${String(drift.length - MAX_FILES_REPORTED)} more file(s)`);
+    }
+    if (ctx.refuseForeignDrift) {
+        if (unexpected.length === 0) {
+            info(`${patch.filename}: drift confined to --expect file(s); proceeding under --refuse-foreign-drift.`);
+            return false;
+        }
+        ctx.refusals.push({
+            patchFilename: patch.filename,
+            files: unexpected.map((d) => d.file),
+            reason: 'foreign-drift',
+        });
+        warn(`${patch.filename}: skipped (--refuse-foreign-drift).`);
+        return true;
+    }
+    warn('  If these are intentional engine edits, this is the normal re-export flow. ' +
+        'FireForge cannot infer authorship; if another session owns them, re-run with ' +
+        "--refuse-foreign-drift, or commit/stash that session's edits first.");
+    return false;
+}
+/**
+ * Fail-closed baseline handling (FORGE L6): a missing or unreadable old
+ * patch body means the drift comparison CANNOT run, so under
+ * `--refuse-foreign-drift` the patch is refused rather than written on the
+ * strength of a check that never happened. Without the flag this stays the
+ * historical advisory skip (the preview is best-effort there).
+ */
+function refuseUnreadableBaseline(ctx, patchFilename, detail) {
+    if (!ctx.refuseForeignDrift) {
+        verbose(`Skipping foreign-drift preview for ${patchFilename}: ${detail}`);
+        return false;
+    }
+    ctx.refusals.push({ patchFilename, files: [], reason: 'baseline-unreadable' });
+    warn(`${patchFilename}: skipped (--refuse-foreign-drift) — ${detail}; the drift comparison cannot run, refusing fail-closed.`);
+    return true;
+}

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

@@ -7,7 +7,7 @@ import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { computeProjectedLintRegressions } from '../core/lint-projection.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
@@ -73,7 +73,7 @@ async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedD
         return null;
     return {
         reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
-        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+        details: regressions.map(formatPatchLintIssue),
     };
 }
 /**
@@ -117,7 +117,9 @@ async function confirmFilesModeProjection(args) {
         for (const line of summary) {
             info(`  ${line}`);
         }
-        throw new InvalidArgumentError(`Refusing to re-export ${target.filename} with --files because it would remove ${removed.length} existing patch-owned file${removed.length === 1 ? '' : 's'}. Run again with --allow-shrink after reviewing the dry-run output.`, '--allow-shrink');
+        throw new InvalidArgumentError(`Refusing to re-export ${target.filename} with --files because it would remove ${removed.length} existing patch-owned file${removed.length === 1 ? '' : 's'}. Run again with --allow-shrink after reviewing the dry-run output. ` +
+            'If the intent is to move those files into their own patch instead, ' +
+            '"fireforge patch move-files <from> <to> --file <path> --create --order <n>" does the shrink and the new patch in one transaction.', '--allow-shrink');
     }
     return confirmDestructive({
         operation: 're-export-files',

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

@@ -0,0 +1,97 @@
+/**
+ * Hoisted + cached lint context for `re-export` (FORGE J1).
+ *
+ * The per-patch loop used to rebuild the whole patch-queue context AND a
+ * fresh queue-wide checkJs TypeScript program for every patch — ~37 s of
+ * fixed setup per patch (measured on a 290-patch consumer queue), so an
+ * N-patch re-export cost N×37 s. This module:
+ *
+ * - builds the queue context and the {@link PerRunCheckJs} program
+ *   controller ONCE per invocation (`buildReExportLintContext`) and slices
+ *   per-patch findings out of it (the FORGE I3 shape `move-files`/`split`
+ *   already use, plus the program-level hoist `lint --per-patch` has);
+ * - reuses the existing per-patch lint RESULT cache
+ *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations —
+ *   re-export lints the identical input `lint --per-patch` does (the
+ *   fresh `git diff HEAD` of the owned files), and the key already
+ *   hashes engine HEAD, per-file content, patch body, config, shims, and
+ *   ownership, so a repeat single re-export is a warm hit (~4 s instead
+ *   of ~41 s). `--no-cache` opts out; run-level checkJs globals are
+ *   never cached (FORGE F5) and are emitted once per invocation;
+ * - keeps the in-memory queue context honest after each write
+ *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
+ *   against the just-refreshed body instead of the stale one.
+ */
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { type PerPatchLintCacheFile } from '../core/lint-cache.js';
+import { type PatchQueueContext } from '../core/patch-lint.js';
+import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type PerRunCheckJs } from './lint-per-run-checkjs.js';
+/** Per-invocation lint context, built once and threaded through the loop. */
+export interface ReExportLintContext {
+    projectRoot: string;
+    paths: ReturnType<typeof getProjectPaths>;
+    config: FireForgeConfig;
+    /** Whole-queue context, built WITH config so the forward-import hints
+     *  match `lint --per-patch` (FORGE F14); undefined when no patches dir. */
+    patchQueueCtx: PatchQueueContext | undefined;
+    /** Queue-wide checkJs controller; undefined when checkJs is off. */
+    checkJs: PerRunCheckJs | undefined;
+    /** Per-patch result cache; undefined under `--no-cache`. */
+    cache: PerPatchLintCacheFile | undefined;
+    engineHeadSha: string | undefined;
+    cacheDirty: boolean;
+    reusedCacheEntries: number;
+    /** Run-level checkJs globals are emitted once per invocation. */
+    globalsEmitted: boolean;
+}
+/** Builds the once-per-invocation lint context (FORGE J1). */
+export declare function buildReExportLintContext(projectRoot: string, paths: ReturnType<typeof getProjectPaths>, config: Awaited<ReturnType<typeof loadConfig>>, noCache: boolean): Promise<ReExportLintContext>;
+/** Fresh lint payload carried to the post-write cache store. */
+export interface ReExportLintResult {
+    issues: PatchLintIssue[];
+    suppressed: PatchLintIssue[];
+    lineCount: number;
+}
+/**
+ * Lints one re-exported patch body using the hoisted context: cache hit →
+ * replay the stored issues through the shared reporter (returns `null`);
+ * miss → lint with the queue-wide program's pre-attributed slices (or a
+ * per-patch build when the fresh diff creates files the hoisted program
+ * never saw — the `--scan` adoption case) and return the payload for
+ * {@link storeReExportLintResult}. Throws exactly like `runPatchLint` on
+ * errors (unless `skipLint`).
+ *
+ * The cache key is built over the PROJECTED metadata (current
+ * filesAffected, merged lintIgnore, effective tier) so `--tier` /
+ * `--lint-ignore` flags change the key. The entry itself is stored AFTER
+ * the body write (the key hashes the on-disk `.patch` file, which this
+ * very run is about to rewrite — a pre-write store could never match a
+ * later run).
+ */
+export declare function lintReExportedPatch(args: {
+    lintCtx: ReExportLintContext;
+    patch: PatchMetadata;
+    projectedMetadata: PatchMetadata;
+    existingFiles: string[];
+    diffContent: string;
+    skipLint?: boolean;
+    ignoreChecks?: ReadonlySet<string>;
+    patchTier?: 'branding';
+}): Promise<ReExportLintResult | null>;
+/**
+ * Stores a fresh lint result AFTER the body write, keying against the
+ * just-written `.patch` file and the refreshed queue context — the state
+ * a later identical invocation will observe (call
+ * {@link refreshQueueCtxEntry} first).
+ */
+export declare function storeReExportLintResult(lintCtx: ReExportLintContext, patchFilename: string, projectedMetadata: PatchMetadata, existingFiles: string[], result: ReExportLintResult): Promise<void>;
+/**
+ * Refreshes the in-memory queue entry for a just-rewritten patch so later
+ * iterations (and later cache keys) lint against the new body instead of
+ * the stale one. The on-disk write is the authority; this mirrors it.
+ */
+export declare function refreshQueueCtxEntry(lintCtx: ReExportLintContext, patchFilename: string, diffContent: string): void;
+/** Persists cache writes and reports reuse, once after the loop. */
+export declare function finishReExportLint(lintCtx: ReExportLintContext): Promise<void>;