lootforge 0.3.0

package/dist/pipeline/generate.js

@@ -0,0 +1,1088 @@
+// eslint-disable-next-line n/no-unsupported-features/node-builtins
+import { access, cp, mkdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import sharp from "sharp";
+import { scoreCandidateImages, } from "../checks/candidateScore.js";
+import { writeRunProvenance } from "../output/provenance.js";
+import { createProviderRegistry, getProvider, resolveTargetProviderRoute, } from "../providers/registry.js";
+import { resolveProviderRegistryOptions } from "../providers/runtimeConfig.js";
+import { getTargetGenerationPolicy, normalizeGenerationPolicyForProvider, nowIso, parseProviderSelection, ProviderError, sha256Hex, } from "../providers/types.js";
+import { normalizeTargetOutPath, resolvePathWithinRoot, resolveStagePathLayout, } from "../shared/paths.js";
+const COARSE_TO_FINE_DRAFT_SCORING_OPTIONS = {
+    includeSoftAdapters: false,
+    includeVlmGate: false,
+    includePaletteCheck: false,
+};
+const AGENTIC_RETRY_TRIGGER_REASONS = new Set([
+    "vlm_gate_below_threshold",
+    "alpha_halo_risk_exceeded",
+    "alpha_stray_noise_exceeded",
+    "alpha_edge_sharpness_too_low",
+]);
+export async function runGeneratePipeline(options) {
+    const layout = resolveStagePathLayout(options.outDir);
+    const targetsIndexPath = path.resolve(options.targetsIndexPath ?? path.join(layout.jobsDir, "targets-index.json"));
+    const providerSelection = options.provider ?? "auto";
+    const imagesDir = layout.rawDir;
+    const skipLocked = options.skipLocked ?? true;
+    const indexRaw = await readFile(targetsIndexPath, "utf8");
+    const index = parseTargetsIndex(indexRaw, targetsIndexPath);
+    const registry = options.registry ??
+        createProviderRegistry(await resolveProviderRegistryOptions(resolveManifestPathFromIndex(index, targetsIndexPath)));
+    const targets = normalizeTargets(index, targetsIndexPath);
+    const allTargetsById = new Map(targets.map((target) => [target.id, target]));
+    const filteredTargets = filterTargetsByIds(targets.filter((target) => target.generationDisabled !== true), options.ids);
+    const lock = await readSelectionLock(path.resolve(options.selectionLockPath ?? path.join(layout.outDir, "locks", "selection-lock.json")));
+    const lockByTargetId = new Map((lock.targets ?? []).map((item) => [item.targetId, item]));
+    const inputHash = sha256Hex(indexRaw);
+    const startedAt = nowIso(options.now);
+    const runId = options.runId ?? sha256Hex(`${inputHash}:${startedAt}`).slice(0, 16);
+    await mkdir(imagesDir, { recursive: true });
+    const existingTargetOutputIds = await collectExistingTargetOutputIds(targets, imagesDir);
+    const tasks = filteredTargets.map((target, targetIndex) => {
+        const route = resolveTargetProviderRoute(target, providerSelection);
+        return {
+            target,
+            targetIndex,
+            primaryProvider: route.primary,
+            fallbackProviders: route.fallbacks,
+        };
+    });
+    const taskById = new Map(tasks.map((task) => [task.target.id, task]));
+    const executionStages = buildTaskExecutionStages(tasks, {
+        allTargetsById,
+        existingTargetOutputIds,
+    });
+    options.onProgress?.({
+        type: "prepare",
+        totalJobs: tasks.length,
+    });
+    const results = [];
+    const failures = [];
+    for (const stageTasks of executionStages) {
+        const groupedTasks = new Map();
+        for (const task of stageTasks) {
+            const existing = groupedTasks.get(task.primaryProvider);
+            if (existing) {
+                existing.push(task);
+            }
+            else {
+                groupedTasks.set(task.primaryProvider, [task]);
+            }
+        }
+        await Promise.all(Array.from(groupedTasks.entries()).map(async ([providerName, providerTasks]) => {
+            const provider = getProvider(registry, providerName);
+            const providerConcurrency = Math.max(1, ...providerTasks.map((task) => task.target.generationPolicy?.providerConcurrency ?? 0), provider.capabilities.defaultConcurrency);
+            const queue = [...providerTasks].sort((left, right) => left.target.id.localeCompare(right.target.id));
+            let nextTask = 0;
+            let nextScheduledStartAt = 0;
+            const reserveWaitMs = (task) => {
+                const minDelayMs = computeProviderDelayMs(task, provider.capabilities.minDelayMs);
+                const nowMs = Date.now();
+                const scheduledStart = Math.max(nowMs, nextScheduledStartAt);
+                nextScheduledStartAt = scheduledStart + minDelayMs;
+                return Math.max(0, scheduledStart - nowMs);
+            };
+            const workers = [];
+            for (let workerIndex = 0; workerIndex < providerConcurrency; workerIndex += 1) {
+                workers.push((async () => {
+                    while (nextTask < queue.length) {
+                        const currentIndex = nextTask;
+                        nextTask += 1;
+                        const task = queue[currentIndex];
+                        const waitMs = reserveWaitMs(task);
+                        if (waitMs > 0) {
+                            await delay(waitMs);
+                        }
+                        const progressIndex = task.targetIndex;
+                        options.onProgress?.({
+                            type: "job_start",
+                            totalJobs: tasks.length,
+                            jobIndex: progressIndex,
+                            targetId: task.target.id,
+                            provider: task.primaryProvider,
+                            model: task.target.model,
+                        });
+                        try {
+                            const result = await runTaskWithFallback({
+                                task,
+                                outDir: layout.outDir,
+                                imagesDir,
+                                now: options.now,
+                                fetchImpl: options.fetchImpl,
+                                registry,
+                                lockByTargetId,
+                                skipLocked,
+                                taskById,
+                                allTargetsById,
+                            });
+                            results.push(result);
+                            options.onProgress?.({
+                                type: "job_finish",
+                                totalJobs: tasks.length,
+                                jobIndex: progressIndex,
+                                targetId: task.target.id,
+                                provider: result.provider,
+                                model: result.model,
+                                bytesWritten: result.bytesWritten,
+                                outputPath: result.outputPath,
+                            });
+                        }
+                        catch (error) {
+                            const message = error instanceof Error ? error.message : String(error);
+                            failures.push({
+                                targetId: task.target.id,
+                                provider: task.primaryProvider,
+                                attemptedProviders: [task.primaryProvider, ...task.fallbackProviders],
+                                message,
+                            });
+                            options.onProgress?.({
+                                type: "job_error",
+                                totalJobs: tasks.length,
+                                jobIndex: progressIndex,
+                                targetId: task.target.id,
+                                provider: task.primaryProvider,
+                                model: task.target.model,
+                                message,
+                            });
+                        }
+                    }
+                })());
+            }
+            await Promise.all(workers);
+        }));
+    }
+    results.sort((left, right) => left.targetId.localeCompare(right.targetId));
+    failures.sort((left, right) => left.targetId.localeCompare(right.targetId));
+    const finishedAt = nowIso(options.now);
+    const provenancePath = await writeRunProvenance(layout.outDir, {
+        runId,
+        inputHash,
+        startedAt,
+        finishedAt,
+        generatedAt: finishedAt,
+        jobs: results.map((result) => ({
+            jobId: result.jobId,
+            provider: result.provider,
+            model: result.model,
+            targetId: result.targetId,
+            prompt: result.prompt,
+            inputHash: result.inputHash,
+            startedAt: result.startedAt,
+            finishedAt: result.finishedAt,
+            outputPath: result.outputPath,
+            bytesWritten: result.bytesWritten,
+            skipped: result.skipped,
+            candidateOutputs: result.candidateOutputs,
+            candidateScores: result.candidateScores,
+            coarseToFine: result.coarseToFine,
+            agenticRetry: result.agenticRetry,
+            styleReferenceLineage: result.styleReferenceLineage,
+            generationMode: result.generationMode,
+            edit: result.edit,
+            regenerationSource: result.regenerationSource,
+        })),
+        failures,
+    });
+    if (failures.length > 0) {
+        const firstFailure = failures[0];
+        throw new Error(`Generation failed for ${failures.length} target(s): ${failures
+            .slice(0, 5)
+            .map((failure) => failure.targetId)
+            .join(", ")}. First failure (${firstFailure.targetId}): ${firstFailure.message}`);
+    }
+    return {
+        runId,
+        inputHash,
+        targetsIndexPath,
+        imagesDir,
+        provenancePath,
+        jobs: results,
+        failures,
+    };
+}
+export function parseGenerateProviderFlag(value) {
+    return parseProviderSelection(value);
+}
+function parseTargetsIndex(raw, filePath) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse targets index JSON (${filePath}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function normalizeTargets(index, filePath) {
+    if (!Array.isArray(index.targets) || index.targets.length === 0) {
+        throw new Error(`No targets found in planned index: ${filePath}`);
+    }
+    return index.targets.map((target, targetIndex) => {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!target || typeof target !== "object") {
+            throw new Error(`Invalid target at index ${targetIndex} in ${filePath}`);
+        }
+        if (typeof target.id !== "string" || target.id.trim() === "") {
+            throw new Error(`targets[${targetIndex}].id must be a non-empty string`);
+        }
+        if (typeof target.out !== "string" || target.out.trim() === "") {
+            throw new Error(`targets[${targetIndex}].out must be a non-empty string`);
+        }
+        let normalizedOut;
+        try {
+            normalizedOut = normalizeTargetOutPath(target.out);
+        }
+        catch (error) {
+            throw new Error(`targets[${targetIndex}].out is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (typeof target.promptSpec.primary !== "string") {
+            throw new Error(`targets[${targetIndex}].promptSpec.primary must be a string`);
+        }
+        return {
+            ...target,
+            out: normalizedOut,
+        };
+    });
+}
+function filterTargetsByIds(targets, ids) {
+    if (!ids || ids.length === 0) {
+        return targets;
+    }
+    const idSet = new Set(ids.map((id) => id.trim()).filter(Boolean));
+    if (idSet.size === 0) {
+        return targets;
+    }
+    const filtered = targets.filter((target) => idSet.has(target.id));
+    if (filtered.length === 0) {
+        throw new Error(`No targets matched --ids (${Array.from(idSet).join(",")}). Check planned target ids.`);
+    }
+    return filtered;
+}
+function buildTaskExecutionStages(tasks, options) {
+    const tasksById = new Map(tasks.map((task) => [task.target.id, task]));
+    const inDegree = new Map();
+    const adjacency = new Map();
+    for (const task of tasks) {
+        inDegree.set(task.target.id, 0);
+        adjacency.set(task.target.id, []);
+    }
+    for (const task of tasks) {
+        const dependencies = dedupeTargetIdList(task.target.dependsOn ?? []);
+        for (const dependencyId of dependencies) {
+            if (dependencyId === task.target.id) {
+                throw new Error(`Target "${task.target.id}" cannot depend on itself.`);
+            }
+            if (!tasksById.has(dependencyId)) {
+                const dependencyTarget = options.allTargetsById.get(dependencyId);
+                if (!dependencyTarget) {
+                    throw new Error(`Target "${task.target.id}" depends on "${dependencyId}", but no matching planned target exists.`);
+                }
+                if (options.existingTargetOutputIds.has(dependencyId)) {
+                    continue;
+                }
+                throw new Error(`Target "${task.target.id}" depends on "${dependencyId}", but that target is not in the current generation set and ${dependencyTarget.out} has not been generated yet.`);
+            }
+            adjacency.get(dependencyId)?.push(task.target.id);
+            inDegree.set(task.target.id, (inDegree.get(task.target.id) ?? 0) + 1);
+        }
+    }
+    let currentStage = tasks
+        .map((task) => task.target.id)
+        .filter((targetId) => (inDegree.get(targetId) ?? 0) === 0)
+        .sort((left, right) => left.localeCompare(right));
+    const stages = [];
+    let visited = 0;
+    while (currentStage.length > 0) {
+        const stageTasks = currentStage
+            .map((targetId) => tasksById.get(targetId))
+            .filter((task) => Boolean(task));
+        stages.push(stageTasks);
+        visited += stageTasks.length;
+        const nextStageCandidates = new Set();
+        for (const targetId of currentStage) {
+            const dependents = adjacency.get(targetId) ?? [];
+            for (const dependentId of dependents) {
+                const nextDegree = (inDegree.get(dependentId) ?? 0) - 1;
+                inDegree.set(dependentId, nextDegree);
+                if (nextDegree === 0) {
+                    nextStageCandidates.add(dependentId);
+                }
+            }
+        }
+        currentStage = Array.from(nextStageCandidates).sort((left, right) => left.localeCompare(right));
+    }
+    if (visited !== tasks.length) {
+        const blockedTargets = tasks
+            .map((task) => task.target.id)
+            .filter((targetId) => (inDegree.get(targetId) ?? 0) > 0)
+            .sort((left, right) => left.localeCompare(right));
+        throw new Error(`Dependency cycle detected in generation targets: ${blockedTargets.join(", ")}.`);
+    }
+    return stages;
+}
+async function runTaskWithFallback(params) {
+    const providerChain = [params.task.primaryProvider, ...params.task.fallbackProviders];
+    let lastError;
+    for (const providerName of providerChain) {
+        const provider = getProvider(params.registry, providerName);
+        const normalizedPolicy = resolveProviderGenerationPolicy(params.task.target, providerName);
+        const draftTarget = materializeDraftTarget(params.task.target, normalizedPolicy);
+        if (targetRequiresEditSupport(params.task.target) && !provider.supports("image-edits")) {
+            lastError = new Error(`Provider "${providerName}" does not support edit-first generation for target "${params.task.target.id}".`);
+            continue;
+        }
+        // Resolve styleReferenceFrom to actual file paths and inject them into
+        // the target's styleReferenceImages so providers can send them as visual
+        // references (Nano sends inline data, OpenAI uses the edit endpoint).
+        const styleReferenceLineage = await resolveStyleReferenceLineage({
+            task: params.task,
+            taskById: params.taskById,
+            allTargetsById: params.allTargetsById,
+            imagesDir: params.imagesDir,
+        });
+        const resolvedStyleRefPaths = (styleReferenceLineage ?? []).flatMap((entry) => entry.source === "target-output" && entry.resolvedPath ? [entry.resolvedPath] : []);
+        const enrichedTarget = resolvedStyleRefPaths.length > 0
+            ? {
+                ...draftTarget,
+                styleReferenceImages: [
+                    ...(draftTarget.styleReferenceImages ?? []),
+                    ...resolvedStyleRefPaths,
+                ],
+            }
+            : draftTarget;
+        const preparedJobs = await provider.prepareJobs([enrichedTarget], {
+            outDir: params.outDir,
+            imagesDir: params.imagesDir,
+            now: params.now,
+        });
+        if (preparedJobs.length === 0) {
+            lastError = new Error(`Provider ${providerName} produced no jobs for ${params.task.target.id}`);
+            continue;
+        }
+        const job = preparedJobs[0];
+        const lockEntry = params.lockByTargetId.get(params.task.target.id);
+        if (params.skipLocked && lockEntry?.approved && lockEntry.inputHash === job.inputHash) {
+            let lockedPath;
+            try {
+                lockedPath = resolvePathWithinRoot(params.outDir, lockEntry.selectedOutputPath, `selection lock output path for target "${job.targetId}"`);
+            }
+            catch (error) {
+                throw new Error(`Selection lock output path for "${job.targetId}" must stay within --out (${params.outDir}).`, { cause: error });
+            }
+            if (await fileExists(lockedPath)) {
+                if (lockedPath !== job.outPath) {
+                    await cp(lockedPath, job.outPath, { force: true });
+                }
+                const fileStat = await stat(job.outPath);
+                return {
+                    jobId: job.id,
+                    provider: providerName,
+                    model: job.model,
+                    targetId: job.targetId,
+                    prompt: job.prompt,
+                    outputPath: job.outPath,
+                    bytesWritten: fileStat.size,
+                    inputHash: job.inputHash,
+                    startedAt: nowIso(params.now),
+                    finishedAt: nowIso(params.now),
+                    skipped: true,
+                    generationMode: params.task.target.generationMode,
+                    edit: params.task.target.edit,
+                    regenerationSource: params.task.target.regenerationSource,
+                    warnings: [`Skipped generation for ${job.targetId}; approved lock matched input hash.`],
+                    ...(styleReferenceLineage ? { styleReferenceLineage } : {}),
+                };
+            }
+        }
+        const attempts = Math.max(1, job.maxRetries + 1);
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                const runResult = await provider.runJob(job, {
+                    outDir: params.outDir,
+                    imagesDir: params.imagesDir,
+                    now: params.now,
+                    fetchImpl: params.fetchImpl,
+                });
+                const coarseToFinePolicy = normalizedPolicy.coarseToFine;
+                const draftCandidates = await scoreProviderRunCandidates({
+                    target: params.task.target,
+                    runResult,
+                    outDir: params.outDir,
+                    ...(coarseToFinePolicy?.enabled
+                        ? { scoreOptions: COARSE_TO_FINE_DRAFT_SCORING_OPTIONS }
+                        : {}),
+                });
+                let candidateSet;
+                let coarseToFineRecord;
+                if (coarseToFinePolicy?.enabled) {
+                    const coarseToFineResult = await runCoarseToFineRefinement({
+                        provider,
+                        providerName,
+                        task: params.task,
+                        runContext: {
+                            outDir: params.outDir,
+                            imagesDir: params.imagesDir,
+                            now: params.now,
+                            fetchImpl: params.fetchImpl,
+                        },
+                        policy: coarseToFinePolicy,
+                        normalizedPolicy,
+                        draftCandidates,
+                    });
+                    candidateSet = {
+                        candidateOutputs: coarseToFineResult.candidateOutputs,
+                        scores: coarseToFineResult.scores,
+                        bestPath: coarseToFineResult.bestPath,
+                    };
+                    coarseToFineRecord = coarseToFineResult.coarseToFine;
+                }
+                else {
+                    candidateSet = draftCandidates;
+                }
+                const autoCorrection = await runAgenticAutoCorrection({
+                    provider,
+                    providerName,
+                    task: params.task,
+                    runContext: {
+                        outDir: params.outDir,
+                        imagesDir: params.imagesDir,
+                        now: params.now,
+                        fetchImpl: params.fetchImpl,
+                    },
+                    normalizedPolicy,
+                    initialCandidates: candidateSet,
+                });
+                await copyIfDifferent(autoCorrection.bestPath, job.outPath);
+                // If this target is a strip generator (frame 0 of a batch animation),
+                // slice the wide strip image into individual frame files so downstream
+                // processing can treat them as normal per-frame outputs.
+                const strip = params.task.target.spritesheet?.stripGeneration;
+                if (strip && strip.frameCount > 1) {
+                    await sliceStripIntoFrames(job.outPath, strip, params.imagesDir);
+                }
+                const fileStat = await stat(job.outPath);
+                return {
+                    ...runResult,
+                    provider: providerName,
+                    outputPath: job.outPath,
+                    bytesWritten: fileStat.size,
+                    candidateOutputs: autoCorrection.candidateOutputs,
+                    candidateScores: autoCorrection.scores,
+                    ...(coarseToFineRecord ? { coarseToFine: coarseToFineRecord } : {}),
+                    ...(autoCorrection.agenticRetry ? { agenticRetry: autoCorrection.agenticRetry } : {}),
+                    ...(styleReferenceLineage ? { styleReferenceLineage } : {}),
+                    generationMode: params.task.target.generationMode,
+                    edit: params.task.target.edit,
+                    regenerationSource: params.task.target.regenerationSource,
+                };
+            }
+            catch (error) {
+                lastError = provider.normalizeError(error);
+                if (attempt < attempts) {
+                    await delay(backoffMsForAttempt(attempt));
+                }
+            }
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Generation failed for target ${params.task.target.id}`);
+}
+function resolveProviderGenerationPolicy(target, providerName) {
+    return normalizeGenerationPolicyForProvider(providerName, getTargetGenerationPolicy(target))
+        .policy;
+}
+function materializeDraftTarget(target, normalizedPolicy) {
+    if (!normalizedPolicy.coarseToFine?.enabled || !normalizedPolicy.draftQuality) {
+        return target;
+    }
+    return {
+        ...target,
+        generationPolicy: {
+            ...(target.generationPolicy ?? {}),
+            quality: normalizedPolicy.draftQuality,
+        },
+    };
+}
+async function scoreProviderRunCandidates(params) {
+    const candidateOutputs = params.runResult.candidateOutputs && params.runResult.candidateOutputs.length > 0
+        ? params.runResult.candidateOutputs
+        : [
+            {
+                outputPath: params.runResult.outputPath,
+                bytesWritten: params.runResult.bytesWritten,
+            },
+        ];
+    const candidateSelection = await scoreCandidateImages(params.target, candidateOutputs.map((candidate) => candidate.outputPath), {
+        outDir: params.outDir,
+        ...(params.scoreOptions ?? {}),
+    });
+    return {
+        candidateOutputs,
+        scores: candidateSelection.scores,
+        bestPath: candidateSelection.bestPath,
+    };
+}
+async function runCoarseToFineRefinement(params) {
+    const draftQuality = params.normalizedPolicy.draftQuality ?? params.normalizedPolicy.quality;
+    const finalQuality = params.normalizedPolicy.finalQuality ?? params.normalizedPolicy.quality;
+    const promotedRows = [];
+    const discardedRows = [];
+    const warnings = [];
+    const promotedSet = new Set();
+    for (const score of params.draftCandidates.scores) {
+        let discardReason = null;
+        if (params.policy.requireDraftAcceptance && !score.passedAcceptance) {
+            discardReason = "draft_failed_acceptance";
+        }
+        else if (typeof params.policy.minDraftScore === "number" &&
+            score.score < params.policy.minDraftScore) {
+            discardReason = "below_min_draft_score";
+        }
+        else if (promotedRows.length >= params.policy.promoteTopK) {
+            discardReason = "outside_top_k";
+        }
+        if (discardReason) {
+            discardedRows.push({
+                outputPath: score.outputPath,
+                score: score.score,
+                passedAcceptance: score.passedAcceptance,
+                reason: discardReason,
+            });
+            continue;
+        }
+        promotedRows.push({
+            outputPath: score.outputPath,
+            score: score.score,
+            passedAcceptance: score.passedAcceptance,
+        });
+        promotedSet.add(score.outputPath);
+    }
+    const draftScoresDecorated = params.draftCandidates.scores.map((score) => ({
+        ...score,
+        stage: "draft",
+        promoted: promotedSet.has(score.outputPath),
+        selected: false,
+    }));
+    const coarseSummaryBase = {
+        enabled: true,
+        draftQuality,
+        finalQuality,
+        promoteTopK: params.policy.promoteTopK,
+        ...(typeof params.policy.minDraftScore === "number"
+            ? { minDraftScore: params.policy.minDraftScore }
+            : {}),
+        requireDraftAcceptance: params.policy.requireDraftAcceptance,
+        draftCandidateCount: params.draftCandidates.candidateOutputs.length,
+    };
+    if (promotedRows.length === 0) {
+        return {
+            bestPath: params.draftCandidates.bestPath,
+            candidateOutputs: params.draftCandidates.candidateOutputs,
+            scores: draftScoresDecorated.map((score) => ({
+                ...score,
+                selected: score.outputPath === params.draftCandidates.bestPath,
+            })),
+            coarseToFine: {
+                ...coarseSummaryBase,
+                promoted: promotedRows,
+                discarded: discardedRows,
+                skippedReason: "no_candidates_promoted",
+            },
+        };
+    }
+    if (!params.provider.supports("image-edits")) {
+        warnings.push(`Provider "${params.providerName}" lacks image-edits support; coarse-to-fine refinement skipped.`);
+        return {
+            bestPath: params.draftCandidates.bestPath,
+            candidateOutputs: params.draftCandidates.candidateOutputs,
+            scores: draftScoresDecorated.map((score) => ({
+                ...score,
+                selected: score.outputPath === params.draftCandidates.bestPath,
+            })),
+            coarseToFine: {
+                ...coarseSummaryBase,
+                promoted: promotedRows,
+                discarded: discardedRows,
+                skippedReason: "provider_missing_image_edit_support",
+                warnings,
+            },
+        };
+    }
+    if (params.task.target.generationMode === "edit-first") {
+        warnings.push("Coarse-to-fine refinement is skipped for edit-first targets.");
+        return {
+            bestPath: params.draftCandidates.bestPath,
+            candidateOutputs: params.draftCandidates.candidateOutputs,
+            scores: draftScoresDecorated.map((score) => ({
+                ...score,
+                selected: score.outputPath === params.draftCandidates.bestPath,
+            })),
+            coarseToFine: {
+                ...coarseSummaryBase,
+                promoted: promotedRows,
+                discarded: discardedRows,
+                skippedReason: "target_already_edit_first",
+                warnings,
+            },
+        };
+    }
+    const refinedOutputs = [];
+    const sourceByRefinedOutput = new Map();
+    for (const [index, promoted] of promotedRows.entries()) {
+        const refineTarget = createRefineTarget({
+            target: params.task.target,
+            sourceOutputPath: promoted.outputPath,
+            outDir: params.runContext.outDir,
+            finalQuality,
+            refineIndex: index + 1,
+        });
+        const refineJobs = await params.provider.prepareJobs([refineTarget], {
+            outDir: params.runContext.outDir,
+            imagesDir: params.runContext.imagesDir,
+            now: params.runContext.now,
+        });
+        if (refineJobs.length === 0) {
+            throw new ProviderError({
+                provider: params.providerName,
+                code: "coarse_to_fine_no_refine_job",
+                message: `Provider ${params.providerName} did not produce refine job for ${params.task.target.id}.`,
+            });
+        }
+        const refineJob = refineJobs[0];
+        const refineRunResult = await params.provider.runJob(refineJob, {
+            outDir: params.runContext.outDir,
+            imagesDir: params.runContext.imagesDir,
+            now: params.runContext.now,
+            fetchImpl: params.runContext.fetchImpl,
+        });
+        const refineSelection = await scoreProviderRunCandidates({
+            target: params.task.target,
+            runResult: refineRunResult,
+            outDir: params.runContext.outDir,
+            scoreOptions: COARSE_TO_FINE_DRAFT_SCORING_OPTIONS,
+        });
+        await copyIfDifferent(refineSelection.bestPath, refineJob.outPath);
+        const refinedStat = await stat(refineJob.outPath);
+        refinedOutputs.push({
+            outputPath: refineJob.outPath,
+            bytesWritten: refinedStat.size,
+        });
+        sourceByRefinedOutput.set(refineJob.outPath, promoted.outputPath);
+        promoted.refinedOutputPath = refineJob.outPath;
+    }
+    const finalRefineSelection = await scoreCandidateImages(params.task.target, refinedOutputs.map((row) => row.outputPath), { outDir: params.runContext.outDir });
+    const refineScoresDecorated = finalRefineSelection.scores.map((score) => ({
+        ...score,
+        stage: "refine",
+        promoted: true,
+        sourceOutputPath: sourceByRefinedOutput.get(score.outputPath),
+    }));
+    return {
+        bestPath: finalRefineSelection.bestPath,
+        candidateOutputs: [...params.draftCandidates.candidateOutputs, ...refinedOutputs],
+        scores: [...draftScoresDecorated, ...refineScoresDecorated],
+        coarseToFine: {
+            ...coarseSummaryBase,
+            promoted: promotedRows,
+            discarded: discardedRows,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        },
+    };
+}
+async function runAgenticAutoCorrection(params) {
+    const policy = params.normalizedPolicy.agenticRetry;
+    if (!policy?.enabled) {
+        return params.initialCandidates;
+    }
+    const summary = {
+        enabled: true,
+        maxRetries: policy.maxRetries,
+        attempted: 0,
+        succeeded: false,
+        attempts: [],
+    };
+    if (policy.maxRetries <= 0) {
+        summary.skippedReason = "max_retries_zero";
+        return {
+            ...params.initialCandidates,
+            agenticRetry: summary,
+        };
+    }
+    let current = ensureSingleSelectedScore(params.initialCandidates);
+    const initialSelected = getSelectedCandidate(current.scores);
+    const initialTrigger = initialSelected
+        ? resolveAutoCorrectionTrigger(initialSelected)
+        : undefined;
+    if (!initialSelected || !initialTrigger) {
+        summary.skippedReason = "no_trigger_conditions";
+        summary.succeeded = true;
+        return {
+            ...current,
+            agenticRetry: summary,
+        };
+    }
+    if (!params.provider.supports("image-edits")) {
+        summary.skippedReason = "provider_missing_image_edit_support";
+        return {
+            ...current,
+            agenticRetry: summary,
+        };
+    }
+    for (let attempt = 1; attempt <= policy.maxRetries; attempt += 1) {
+        const selectedBefore = getSelectedCandidate(current.scores);
+        if (!selectedBefore) {
+            summary.skippedReason = "selected_candidate_missing";
+            break;
+        }
+        const trigger = resolveAutoCorrectionTrigger(selectedBefore);
+        if (!trigger) {
+            summary.succeeded = true;
+            break;
+        }
+        summary.attempted += 1;
+        const retryTarget = createAutoCorrectionTarget({
+            target: params.task.target,
+            sourceOutputPath: selectedBefore.outputPath,
+            outDir: params.runContext.outDir,
+            quality: params.normalizedPolicy.finalQuality ?? params.normalizedPolicy.quality,
+            attempt,
+            critique: trigger.critique,
+        });
+        const retryJobs = await params.provider.prepareJobs([retryTarget], {
+            outDir: params.runContext.outDir,
+            imagesDir: params.runContext.imagesDir,
+            now: params.runContext.now,
+        });
+        if (retryJobs.length === 0) {
+            summary.skippedReason = "provider_no_retry_job";
+            break;
+        }
+        const retryJob = retryJobs[0];
+        const retryRunResult = await params.provider.runJob(retryJob, {
+            outDir: params.runContext.outDir,
+            imagesDir: params.runContext.imagesDir,
+            now: params.runContext.now,
+            fetchImpl: params.runContext.fetchImpl,
+        });
+        const scoredRetry = await scoreProviderRunCandidates({
+            target: params.task.target,
+            runResult: retryRunResult,
+            outDir: params.runContext.outDir,
+        });
+        const retryScores = scoredRetry.scores.map((score) => ({
+            ...score,
+            stage: "autocorrect",
+            autoCorrectAttempt: attempt,
+            sourceOutputPath: selectedBefore.outputPath,
+            selected: false,
+        }));
+        current = mergeScoredCandidateSets(current, {
+            candidateOutputs: scoredRetry.candidateOutputs,
+            scores: retryScores,
+            bestPath: scoredRetry.bestPath,
+        });
+        const selectedAfter = getSelectedCandidate(current.scores);
+        if (!selectedAfter) {
+            summary.skippedReason = "retry_selected_candidate_missing";
+            break;
+        }
+        const retryOutputPath = retryScores[0]?.outputPath ?? selectedAfter.outputPath;
+        summary.attempts.push({
+            attempt,
+            sourceOutputPath: selectedBefore.outputPath,
+            outputPath: selectedAfter.outputPath,
+            retryOutputPath,
+            critique: trigger.critique,
+            triggeredBy: trigger.triggeredBy,
+            scoreBefore: selectedBefore.score,
+            scoreAfter: selectedAfter.score,
+            passedBefore: selectedBefore.passedAcceptance,
+            passedAfter: selectedAfter.passedAcceptance,
+            reasonsBefore: selectedBefore.reasons,
+            reasonsAfter: selectedAfter.reasons,
+        });
+        if (!resolveAutoCorrectionTrigger(selectedAfter)) {
+            summary.succeeded = true;
+            break;
+        }
+    }
+    return {
+        ...current,
+        agenticRetry: summary,
+    };
+}
+function mergeScoredCandidateSets(base, delta) {
+    const outputsByPath = new Map(base.candidateOutputs.map((row) => [row.outputPath, row]));
+    for (const row of delta.candidateOutputs) {
+        outputsByPath.set(row.outputPath, row);
+    }
+    const scores = [...base.scores, ...delta.scores];
+    scores.sort((left, right) => {
+        if (left.passedAcceptance !== right.passedAcceptance) {
+            return left.passedAcceptance ? -1 : 1;
+        }
+        if (left.score !== right.score) {
+            return right.score - left.score;
+        }
+        return left.outputPath.localeCompare(right.outputPath);
+    });
+    return ensureSingleSelectedScore({
+        candidateOutputs: Array.from(outputsByPath.values()).sort((left, right) => left.outputPath.localeCompare(right.outputPath)),
+        scores,
+        bestPath: scores[0]?.outputPath ?? base.bestPath,
+    });
+}
+function ensureSingleSelectedScore(set) {
+    if (set.scores.length === 0) {
+        return set;
+    }
+    const selectedPath = set.scores[0].outputPath;
+    const scores = set.scores.map((score) => ({
+        ...score,
+        selected: Boolean(selectedPath && score.outputPath === selectedPath),
+    }));
+    return {
+        ...set,
+        scores,
+        bestPath: selectedPath,
+    };
+}
+function getSelectedCandidate(scores) {
+    return scores.find((score) => score.selected) ?? scores[0];
+}
+function resolveAutoCorrectionTrigger(score) {
+    const triggeredBy = dedupeTargetIdList(score.reasons.filter((reason) => AGENTIC_RETRY_TRIGGER_REASONS.has(reason)));
+    if (triggeredBy.length === 0) {
+        return undefined;
+    }
+    const critiqueParts = [
+        "Refine this image to pass hard quality gates while preserving composition, silhouette, and style.",
+    ];
+    if (triggeredBy.includes("vlm_gate_below_threshold")) {
+        critiqueParts.push(`VLM critique: ${score.vlm?.reason ?? "Improve framing and subject clarity against rubric expectations."}`);
+    }
+    if (triggeredBy.includes("alpha_halo_risk_exceeded")) {
+        critiqueParts.push("Remove edge haloing and color fringe around transparent boundaries.");
+    }
+    if (triggeredBy.includes("alpha_stray_noise_exceeded")) {
+        critiqueParts.push("Eliminate isolated stray alpha noise and detached transparency speckles.");
+    }
+    if (triggeredBy.includes("alpha_edge_sharpness_too_low")) {
+        critiqueParts.push("Increase alpha-edge sharpness while keeping clean anti-aliased contours.");
+    }
+    return {
+        critique: critiqueParts.join(" "),
+        triggeredBy,
+    };
+}
+function createAutoCorrectionTarget(params) {
+    const relativeSource = toPortableRelativePath(params.outDir, params.sourceOutputPath);
+    return {
+        ...params.target,
+        out: withAutoCorrectSuffix(params.target.out, params.attempt),
+        generationMode: "edit-first",
+        generationPolicy: {
+            ...(params.target.generationPolicy ?? {}),
+            quality: params.quality,
+            candidates: 1,
+        },
+        edit: {
+            mode: "iterate",
+            instruction: params.critique,
+            preserveComposition: true,
+            inputs: [
+                {
+                    path: relativeSource,
+                    role: "base",
+                    fidelity: "high",
+                },
+            ],
+        },
+    };
+}
+function createRefineTarget(params) {
+    const relativeSource = toPortableRelativePath(params.outDir, params.sourceOutputPath);
+    return {
+        ...params.target,
+        out: withRefineSuffix(params.target.out, params.refineIndex),
+        generationMode: "edit-first",
+        generationPolicy: {
+            ...(params.target.generationPolicy ?? {}),
+            quality: params.finalQuality,
+            candidates: 1,
+        },
+        edit: {
+            mode: "iterate",
+            instruction: params.target.edit?.instruction ??
+                "Refine the supplied draft candidate at higher fidelity while preserving composition and silhouette.",
+            preserveComposition: params.target.edit?.preserveComposition ?? true,
+            inputs: [
+                {
+                    path: relativeSource,
+                    role: "base",
+                    fidelity: "high",
+                },
+            ],
+        },
+    };
+}
+function withRefineSuffix(filePath, refineIndex) {
+    const ext = path.extname(filePath);
+    const base = filePath.slice(0, filePath.length - ext.length);
+    return `${base}.refine-${refineIndex}${ext}`;
+}
+function withAutoCorrectSuffix(filePath, attempt) {
+    const ext = path.extname(filePath);
+    const base = filePath.slice(0, filePath.length - ext.length);
+    return `${base}.autocorrect-${attempt}${ext}`;
+}
+function toPortableRelativePath(rootDir, filePath) {
+    const relative = path.relative(rootDir, filePath);
+    return relative.split(path.sep).join("/");
+}
+async function copyIfDifferent(sourcePath, destinationPath) {
+    if (sourcePath === destinationPath) {
+        return;
+    }
+    await cp(sourcePath, destinationPath, { force: true });
+}
+function backoffMsForAttempt(attempt) {
+    return Math.min(5000, 300 * 2 ** (attempt - 1));
+}
+function targetRequiresEditSupport(target) {
+    if (target.generationMode !== "edit-first") {
+        return false;
+    }
+    return (target.edit?.inputs?.length ?? 0) > 0;
+}
+function computeProviderDelayMs(task, fallbackDelay) {
+    const requestedRateLimit = task.target.generationPolicy?.rateLimitPerMinute;
+    if (typeof requestedRateLimit === "number" &&
+        Number.isFinite(requestedRateLimit) &&
+        requestedRateLimit > 0) {
+        const rateDelay = Math.ceil(60000 / requestedRateLimit);
+        return Math.max(rateDelay, fallbackDelay);
+    }
+    return fallbackDelay;
+}
+async function resolveStyleReferenceLineage(params) {
+    const lineage = [];
+    for (const styleReferenceImage of params.task.target.styleReferenceImages ?? []) {
+        lineage.push({
+            source: "style-kit",
+            reference: styleReferenceImage,
+        });
+    }
+    for (const sourceTargetId of params.task.target.styleReferenceFrom ?? []) {
+        const sourceTask = params.taskById.get(sourceTargetId);
+        const sourceTarget = sourceTask?.target ?? params.allTargetsById.get(sourceTargetId);
+        if (!sourceTarget) {
+            throw new Error(`Target "${params.task.target.id}" chains style references from "${sourceTargetId}", but no matching planned target exists.`);
+        }
+        const sourceOutputPath = path.resolve(params.imagesDir, sourceTarget.out.split("/").join(path.sep));
+        if (!sourceTask && !(await fileExists(sourceOutputPath))) {
+            throw new Error(`Target "${params.task.target.id}" chains style references from "${sourceTargetId}", but ${sourceOutputPath} does not exist. Generate that target first or include it in the current run.`);
+        }
+        lineage.push({
+            source: "target-output",
+            reference: sourceTarget.out,
+            sourceTargetId,
+            resolvedPath: sourceOutputPath,
+        });
+    }
+    return lineage.length > 0 ? lineage : undefined;
+}
+async function sliceStripIntoFrames(stripPath, strip, imagesDir) {
+    // Read the full strip into a buffer first because frameOutputPaths[0]
+    // points to the same file as stripPath (frame 0 IS the strip target).
+    // Sharp cannot read and write the same file simultaneously.
+    const stripBuffer = await readFile(stripPath);
+    const meta = await sharp(stripBuffer).metadata();
+    if (!meta.width || !meta.height)
+        return;
+    const frameWidth = Math.floor(meta.width / strip.frameCount);
+    for (let i = 0; i < strip.frameCount; i += 1) {
+        const framePath = path.resolve(imagesDir, strip.frameOutputPaths[i]);
+        await mkdir(path.dirname(framePath), { recursive: true });
+        await sharp(stripBuffer)
+            .extract({
+            left: i * frameWidth,
+            top: 0,
+            width: i < strip.frameCount - 1 ? frameWidth : meta.width - i * frameWidth,
+            height: meta.height,
+        })
+            .png()
+            .toFile(framePath);
+    }
+}
+function dedupeTargetIdList(targetIds) {
+    const deduped = [];
+    const seen = new Set();
+    for (const targetId of targetIds) {
+        if (seen.has(targetId)) {
+            continue;
+        }
+        seen.add(targetId);
+        deduped.push(targetId);
+    }
+    return deduped;
+}
+function resolveManifestPathFromIndex(index, targetsIndexPath) {
+    if (typeof index.manifestPath !== "string") {
+        return undefined;
+    }
+    const trimmed = index.manifestPath.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (path.isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return path.resolve(path.dirname(targetsIndexPath), trimmed);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function readSelectionLock(filePath) {
+    try {
+        const raw = await readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`selection lock file content is not a JSON object (${filePath}).`);
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (isNoSuchFileError(error)) {
+            return {};
+        }
+        throw new Error(`Failed to parse selection lock JSON (${filePath}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function isNoSuchFileError(error) {
+    return (Boolean(error) && typeof error === "object" && error.code === "ENOENT");
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function collectExistingTargetOutputIds(targets, imagesDir) {
+    const existingIds = new Set();
+    const checks = await Promise.all(targets.map(async (target) => ({
+        targetId: target.id,
+        exists: await fileExists(path.resolve(imagesDir, target.out.split("/").join(path.sep))),
+    })));
+    for (const check of checks) {
+        if (check.exists) {
+            existingIds.add(check.targetId);
+        }
+    }
+    return existingIds;
+}
+//# sourceMappingURL=generate.js.map