@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/lib/log.js

@@ -3,6 +3,13 @@
  *
  * Levels: quiet < normal < verbose
  * Set via --quiet or --verbose flags (parsed by caller).
+ *
+ * Context prefix:
+ *   info('generate', 'starting wave 1')  → '[generate] starting wave 1'
+ *   info('starting wave 1')               → 'starting wave 1' (no prefix)
+ * The first argument is treated as a command/context label when it is a
+ * short single-token string with no whitespace; otherwise the call is
+ * prefix-less and backwards-compatible.
  */
 
 let level = 'normal'; // quiet | normal | verbose
@@ -15,22 +22,52 @@ export function getLogLevel() {
   return level;
 }
 
+// Accept a leading short-token context label as the first arg.
+// Heuristic: string, no whitespace, ≤ 32 chars, and there is at least
+// one additional argument after it. This keeps existing call sites
+// (where args is typically a full message) unchanged.
+function applyContextPrefix(args) {
+  if (args.length < 2) return args;
+  const first = args[0];
+  if (typeof first !== 'string') return args;
+  if (first.length > 32) return args;
+  if (/\s/.test(first)) return args;
+  // Avoid treating a message that happens to start with a format token as
+  // a context: require it to look like an identifier (word chars, dots, dashes).
+  if (!/^[A-Za-z][\w.:-]*$/.test(first)) return args;
+  return [`[${first}]`, ...args.slice(1)];
+}
+
 /** Always shown (errors, final results). */
 export function log(...args) {
-  console.log(...args);
+  console.log(...applyContextPrefix(args));
+}
+
+/**
+ * Artifact / final-output path helper.
+ * Always prints regardless of verbosity (survives --quiet) so scripts
+ * that produce files have a machine-parseable path on stdout.
+ */
+export function result(...args) {
+  console.log(...applyContextPrefix(args));
+}
+
+/** Always shown (used for final success lines). */
+export function success(...args) {
+  console.log(...applyContextPrefix(args));
 }
 
 /** Shown at normal and verbose levels (progress, summaries). */
 export function info(...args) {
-  if (level !== 'quiet') console.log(...args);
+  if (level !== 'quiet') console.log(...applyContextPrefix(args));
 }
 
 /** Shown only at verbose level (per-record details, debug context). */
 export function verbose(...args) {
-  if (level === 'verbose') console.log(...args);
+  if (level === 'verbose') console.log(...applyContextPrefix(args));
 }
 
 /** Always shown on stderr. */
 export function warn(...args) {
-  console.error('\x1b[33m⚠\x1b[0m', ...args);
+  console.error('\x1b[33m⚠\x1b[0m', ...applyContextPrefix(args));
 }

package/lib/paths.js

@@ -3,8 +3,9 @@
  */
 
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve, relative, isAbsolute } from 'node:path';
 import { existsSync } from 'node:fs';
+import { inputError } from './errors.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -18,10 +19,18 @@ export const REPO_ROOT = join(__dirname, '..');
  * @returns {string} absolute path to projects/<name>/
  */
 export function getProjectRoot(name) {
+  if (!name || typeof name !== 'string') {
+    throw inputError(
+      'INPUT_MISSING_PROJECT',
+      'Project name is required.',
+      'Pass --project <name>.'
+    );
+  }
   const root = join(REPO_ROOT, 'projects', name);
   if (!existsSync(root)) {
-    throw new Error(
-      `Project "${name}" not found at ${root}.\n` +
+    throw inputError(
+      'INPUT_UNKNOWN_PROJECT',
+      `Project "${name}" not found at ${root}.`,
       `Run: sdlab init ${name} --domain <domain>`
     );
   }
@@ -36,3 +45,63 @@ export function getProjectRoot(name) {
 export function resolveProjectPath(name, ...segments) {
   return join(getProjectRoot(name), ...segments);
 }
+
+/**
+ * Resolve a user-supplied path relative to a project root and verify
+ * it does not escape the root (no `..` traversal, no absolute-path escapes
+ * out of root). Returns the absolute resolved path.
+ *
+ * @param {string} projectRoot — absolute project root (trusted)
+ * @param {string} userPath — user-supplied, possibly malicious path
+ * @param {{baseRoot?:string, flagName?:string}} [opts]
+ * @returns {string} absolute path guaranteed to be within baseRoot
+ */
+export function resolveSafeProjectPath(projectRoot, userPath, opts = {}) {
+  const flagName = opts.flagName || 'path';
+  if (userPath == null || userPath === '') {
+    throw inputError('INPUT_MISSING_VALUE', `Flag --${flagName} requires a path.`);
+  }
+  const baseRoot = opts.baseRoot || projectRoot;
+  const absBase = resolve(baseRoot);
+  const resolved = isAbsolute(userPath) ? resolve(userPath) : resolve(absBase, userPath);
+  const rel = relative(absBase, resolved);
+  if (rel.startsWith('..') || (isAbsolute(rel) && rel !== '')) {
+    throw inputError(
+      'INPUT_PATH_TRAVERSAL',
+      `Path "${userPath}" resolves outside of ${absBase}.`,
+      `Paths passed via --${flagName} must stay within the project tree.`
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Return the workflow profiles directory for a project root.
+ * @param {string} projectRoot — absolute path to project
+ */
+export function getWorkflowProfilesDir(projectRoot) {
+  return join(projectRoot, 'workflows', 'profiles');
+}
+
+/**
+ * Return the briefs directory for a project root.
+ * @param {string} projectRoot — absolute path to project
+ */
+export function getBriefsDir(projectRoot) {
+  return join(projectRoot, 'briefs');
+}
+
+/**
+ * Return the runs directory for a project root.
+ * @param {string} projectRoot — absolute path to project
+ */
+export function getRunsDir(projectRoot) {
+  return join(projectRoot, 'runs');
+}
+
+/**
+ * Return the runtime templates directory (repo-level).
+ */
+export function getRuntimeDir() {
+  return join(REPO_ROOT, 'runtime');
+}

package/lib/refine-briefs.js

@@ -0,0 +1,336 @@
+/**
+ * Refine briefs — derive a next-pass brief from critique of a previous run.
+ *
+ * A refined brief is NOT a brand-new brief. It is a delta layer:
+ *   - Preserves: original workflow, subject, lane, canon constraints, runtime plan
+ *   - Adds: preserve/push/suppress instructions derived from critique
+ *   - Updates: prompt and negative prompt with targeted refinements
+ *
+ * This keeps the loop stable — each pass improves, never scrambles.
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { getRunsDir } from './paths.js';
+import { inputError } from './errors.js';
+
+// ─── Refined brief ID generation ─────────────────────────────────
+
+/**
+ * Generate refined brief ID: <parent_brief_id>_refine_NN
+ */
+function generateRefinedBriefId(refineDir, parentBriefId) {
+  const prefix = `${parentBriefId}_refine_`;
+
+  let maxSeq = 0;
+  if (existsSync(refineDir)) {
+    const existing = readdirSync(refineDir)
+      .filter(f => f.startsWith(prefix) && f.endsWith('.json'));
+    for (const f of existing) {
+      const seqStr = f.slice(prefix.length, -5);
+      const seq = parseInt(seqStr, 10);
+      if (!isNaN(seq) && seq > maxSeq) maxSeq = seq;
+    }
+  }
+
+  const seq = String(maxSeq + 1).padStart(2, '0');
+  return `${prefix}${seq}`;
+}
+
+// ─── Prompt refinement ───────────────────────────────────────────
+
+/**
+ * Render a refined prompt from parent prompt + delta instructions.
+ *
+ * Strategy:
+ *   - Start with the original prompt
+ *   - Append preserve notes as reinforcement
+ *   - Append push notes as emphasis
+ *   - Do NOT remove anything from the original — only add emphasis
+ */
+export function renderRefinedPrompt(parentPrompt, delta) {
+  const parts = [parentPrompt];
+
+  // Preserve instructions — reinforce what worked
+  if (delta.preserve?.length > 0) {
+    parts.push(`[preserve: ${delta.preserve.join(', ')}]`);
+  }
+
+  // Push instructions — emphasize what needs to be stronger
+  if (delta.push?.length > 0) {
+    parts.push(`[emphasize: ${delta.push.join(', ')}]`);
+  }
+
+  return parts.join(', ');
+}
+
+/**
+ * Render a refined negative prompt from parent negative + suppress instructions.
+ *
+ * Strategy:
+ *   - Keep the entire original negative prompt
+ *   - Append suppress items that aren't already present
+ */
+export function renderRefinedNegative(parentNegative, delta) {
+  // PB-007: coerce missing/null/non-string negatives to '' so we don't
+  // throw on legacy briefs or hand-edited JSON that dropped the field.
+  const parent = typeof parentNegative === 'string' ? parentNegative : '';
+  const existing = parent
+    .split(',')
+    .map(s => s.trim().toLowerCase())
+    .filter(s => s.length > 0);
+  const additions = [];
+
+  for (const item of delta.suppress || []) {
+    const lower = item.toLowerCase().trim();
+    // Don't duplicate if already in negative (token-exact match)
+    if (lower.length > 0 && !existing.includes(lower)) {
+      additions.push(item);
+    }
+  }
+
+  if (additions.length === 0) return parent;
+  if (parent.length === 0) return additions.join(', ');
+  return `${parent}, ${additions.join(', ')}`;
+}
+
+// ─── Delta extraction from critique ──────────────────────────────
+
+/**
+ * Extract a refine delta from a critique report + picked candidate.
+ *
+ * @param {Object} critique — critique report
+ * @param {string} pickedFilename — filename of the picked candidate
+ * @param {Object} cliOverrides — { preserve: string[], push: string[], suppress: string[] }
+ * @returns {{ preserve: string[], push: string[], suppress: string[] }}
+ */
+export function extractDelta(critique, pickedFilename, cliOverrides = {}) {
+  // Find the picked candidate in the critique
+  const picked = critique.candidates.find(c => c.filename === pickedFilename);
+  if (!picked) {
+    throw inputError(
+      'REFINE_CANDIDATE_NOT_FOUND',
+      `Candidate "${pickedFilename}" not found in critique for run "${critique.run_id}"`,
+      `Available candidates: ${critique.candidates.map(c => c.filename).join(', ')}`
+    );
+  }
+
+  // Start with critique-derived instructions
+  const preserve = [...(picked.preserve_next_pass || [])];
+  const push = [];
+  const suppress = [];
+
+  // Derive push from drift issues that need correction
+  for (const issue of picked.correct_next_pass || []) {
+    push.push(issue);
+  }
+
+  // Derive suppress from drift issues
+  for (const drift of picked.drift_issues || []) {
+    // Strip "check:" and "negative check:" prefixes for cleaner suppress
+    const cleaned = drift
+      .replace(/^\[.*?\]\s*check:\s*/i, '')
+      .replace(/^negative check:\s*/i, '')
+      .trim();
+    if (cleaned) suppress.push(cleaned);
+  }
+
+  // CLI overrides — append without duplicating
+  if (cliOverrides.preserve) {
+    for (const p of cliOverrides.preserve) {
+      if (!preserve.includes(p)) preserve.push(p);
+    }
+  }
+  if (cliOverrides.push) {
+    for (const p of cliOverrides.push) {
+      if (!push.includes(p)) push.push(p);
+    }
+  }
+  if (cliOverrides.suppress) {
+    for (const s of cliOverrides.suppress) {
+      if (!suppress.includes(s)) suppress.push(s);
+    }
+  }
+
+  return { preserve, push, suppress };
+}
+
+// ─── Build refined brief ─────────────────────────────────────────
+
+/**
+ * Build a refined brief from parent brief, critique, and delta.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.parentBrief — original compiled brief
+ * @param {Object} opts.critique — critique report
+ * @param {string} opts.pickedCandidate — filename of selected candidate
+ * @param {Object} opts.delta — { preserve, push, suppress }
+ * @param {string} opts.runId — source run ID
+ * @param {string} opts.refineDir — path to write refined brief
+ * @returns {Object} refined brief
+ */
+export function buildRefinedBrief({ parentBrief, critique, pickedCandidate, delta, runId, refineDir }) {
+  const briefId = generateRefinedBriefId(refineDir, parentBrief.brief_id);
+
+  // Render updated prompts — PB-007 guards missing fields upstream.
+  const prompt = renderRefinedPrompt(parentBrief.prompt ?? '', delta);
+  const negativePrompt = renderRefinedNegative(parentBrief.negative_prompt ?? '', delta);
+
+  const refined = {
+    brief_id: briefId,
+    parent_brief_id: parentBrief.brief_id,
+    source_run_id: runId,
+    source_candidate: pickedCandidate,
+
+    project_id: parentBrief.project_id,
+    workflow_id: parentBrief.workflow_id,
+    lane_id: parentBrief.lane_id,
+    compiled_at: new Date().toISOString(),
+    config_fingerprint: parentBrief.config_fingerprint,
+
+    prompt,
+    negative_prompt: negativePrompt,
+
+    refine_delta: delta,
+
+    // Carry forward from parent
+    canon_constraints: parentBrief.canon_constraints || [],
+    drift_warnings: parentBrief.drift_warnings || [],
+    runtime_plan: { ...parentBrief.runtime_plan },
+    expected_outputs: { ...parentBrief.expected_outputs },
+  };
+
+  // Optional fields
+  if (parentBrief.subject_id) refined.subject_id = parentBrief.subject_id;
+  if (parentBrief.subject_constraints) refined.subject_constraints = parentBrief.subject_constraints;
+  if (parentBrief.reference_selection) refined.reference_selection = parentBrief.reference_selection;
+
+  return refined;
+}
+
+// ─── Markdown renderer ──────────────────────────────────────────
+
+/**
+ * Render a refined brief as Markdown.
+ */
+export function renderRefinedBriefMarkdown(brief) {
+  const lines = [];
+
+  lines.push(`# Refined Brief: ${brief.brief_id}`);
+  lines.push('');
+  lines.push(`**Parent Brief:** ${brief.parent_brief_id}`);
+  lines.push(`**Source Run:** ${brief.source_run_id}`);
+  lines.push(`**Picked Candidate:** ${brief.source_candidate}`);
+  lines.push('');
+  lines.push(`**Workflow:** ${brief.workflow_id}`);
+  lines.push(`**Project:** ${brief.project_id}`);
+  lines.push(`**Lane:** ${brief.lane_id}`);
+  if (brief.subject_id) lines.push(`**Subject:** ${brief.subject_id}`);
+  lines.push('');
+
+  // Refine delta — the key section
+  lines.push('## Refine Delta');
+  lines.push('');
+
+  if (brief.refine_delta?.preserve?.length > 0) {
+    lines.push('### Preserve');
+    for (const p of brief.refine_delta.preserve) lines.push(`- ✓ ${p}`);
+    lines.push('');
+  }
+
+  if (brief.refine_delta?.push?.length > 0) {
+    lines.push('### Push');
+    for (const p of brief.refine_delta.push) lines.push(`- → ${p}`);
+    lines.push('');
+  }
+
+  if (brief.refine_delta?.suppress?.length > 0) {
+    lines.push('### Suppress');
+    for (const s of brief.refine_delta.suppress) lines.push(`- ✗ ${s}`);
+    lines.push('');
+  }
+
+  // Prompt
+  lines.push('## Prompt');
+  lines.push('');
+  lines.push('```');
+  lines.push(brief.prompt);
+  lines.push('```');
+  lines.push('');
+
+  // Negative prompt
+  lines.push('## Negative Prompt');
+  lines.push('');
+  lines.push('```');
+  lines.push(brief.negative_prompt);
+  lines.push('```');
+  lines.push('');
+
+  // Canon constraints
+  if (brief.canon_constraints?.length > 0) {
+    lines.push('## Canon Constraints');
+    lines.push('');
+    for (const c of brief.canon_constraints) lines.push(`- ${c}`);
+    lines.push('');
+  }
+
+  // Drift warnings
+  if (brief.drift_warnings?.length > 0) {
+    lines.push('## Drift Warnings');
+    lines.push('');
+    for (const w of brief.drift_warnings) lines.push(`- ⚠ ${w}`);
+    lines.push('');
+  }
+
+  // Runtime plan
+  lines.push('## Runtime Plan');
+  lines.push('');
+  lines.push('| Parameter | Value |');
+  lines.push('|-----------|-------|');
+  const rp = brief.runtime_plan || {};
+  lines.push(`| Adapter | ${rp.adapter_target || '?'} |`);
+  lines.push(`| Width | ${rp.width || '?'} |`);
+  lines.push(`| Height | ${rp.height || '?'} |`);
+  lines.push(`| Steps | ${rp.steps || '?'} |`);
+  lines.push(`| CFG | ${rp.cfg || '?'} |`);
+  lines.push(`| Sampler | ${rp.sampler || '?'} |`);
+  lines.push(`| Seed Mode | ${rp.seed_mode || '?'} |`);
+  lines.push('');
+
+  // Expected outputs
+  lines.push('## Expected Outputs');
+  lines.push('');
+  const eo = brief.expected_outputs || {};
+  lines.push(`- **Mode:** ${eo.output_mode || '?'}`);
+  lines.push(`- **Count:** ${eo.output_count || '?'}`);
+  lines.push('');
+
+  // Metadata
+  lines.push('---');
+  lines.push('');
+  lines.push(`Compiled: ${brief.compiled_at}`);
+  lines.push(`Config fingerprint: \`${brief.config_fingerprint || '—'}\``);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ─── Save ────────────────────────────────────────────────────────
+
+/**
+ * Save a refined brief to the run's refine directory.
+ */
+export async function saveRefinedBrief(projectRoot, runId, refinedBrief) {
+  const refineDir = join(getRunsDir(projectRoot), runId, 'refine');
+  await mkdir(refineDir, { recursive: true });
+
+  const jsonPath = join(refineDir, `${refinedBrief.brief_id}.json`);
+  await writeFile(jsonPath, JSON.stringify(refinedBrief, null, 2) + '\n');
+
+  const md = renderRefinedBriefMarkdown(refinedBrief);
+  const mdPath = join(refineDir, `${refinedBrief.brief_id}.md`);
+  await writeFile(mdPath, md);
+
+  return { jsonPath, mdPath, refineDir };
+}

package/lib/reingest-selected.js

@@ -0,0 +1,184 @@
+/**
+ * Re-ingest selected outputs as new candidate records.
+ *
+ * Selected outputs re-enter the project as generated candidates
+ * with full provenance. They go through the same review and
+ * canon-binding flow as everything else. No bypass.
+ */
+
+import { writeFile, mkdir, copyFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { getRunsDir } from './paths.js';
+import { getBatchesDir } from './batch-runs.js';
+import { getSelectionsDir, loadSelection } from './selections.js';
+import { buildGeneratedProvenance } from './generated-provenance.js';
+import { buildBaseRecord } from './records.js';
+import { inputError } from './errors.js';
+
+/**
+ * Re-ingest a selection — creates candidate records from chosen outputs.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.projectId
+ * @param {string} opts.selectionId
+ * @param {boolean} [opts.dryRun]
+ * @returns {Promise<{created: string[], skipped: string[]}>}
+ */
+export async function reingestSelection({ projectRoot, projectId, selectionId, dryRun }) {
+  const manifest = loadSelection(projectRoot, selectionId);
+
+  if (!manifest.reingest_ready) {
+    throw inputError(
+      'SELECTION_NOT_READY',
+      `Selection "${selectionId}" is not marked reingest_ready`,
+      'Set reingest_ready: true in the selection manifest.',
+    );
+  }
+
+  const selectionDir = join(getSelectionsDir(projectRoot), selectionId);
+  const recordsDir = join(projectRoot, 'records');
+  const inboxDir = join(projectRoot, 'inbox', 'generated');
+
+  if (!dryRun) {
+    await mkdir(recordsDir, { recursive: true });
+    await mkdir(inboxDir, { recursive: true });
+  }
+
+  // Load source manifests for provenance
+  const runsDir = getRunsDir(projectRoot);
+  const runManifestCache = new Map();
+
+  function getRunManifest(runId) {
+    if (runManifestCache.has(runId)) return runManifestCache.get(runId);
+    const mPath = join(runsDir, runId, 'manifest.json');
+    if (!existsSync(mPath)) return null;
+    const m = JSON.parse(readFileSync(mPath, 'utf-8'));
+    runManifestCache.set(runId, m);
+    return m;
+  }
+
+  let batchManifest = null;
+  if (manifest.source_type === 'batch') {
+    const bmPath = join(getBatchesDir(projectRoot), manifest.source_id, 'manifest.json');
+    if (existsSync(bmPath)) {
+      batchManifest = JSON.parse(readFileSync(bmPath, 'utf-8'));
+    }
+  }
+
+  const created = [];
+  const skipped = [];
+  const provenanceLines = [];
+
+  // D-010: use entries() — not indexOf() — to avoid O(n^2) behavior and
+  // silent duplicate-ID bugs when manifest.items contains structurally
+  // equal or repeated references. Assert uniqueness of generated IDs.
+  const seenIds = new Set();
+  for (const [i, item] of manifest.items.entries()) {
+    const idx = String(i + 1).padStart(3, '0');
+    const recordId = `gen_${selectionId}_${idx}`;
+    if (seenIds.has(recordId)) {
+      throw inputError(
+        'REINGEST_DUPLICATE_RECORD_ID',
+        `Duplicate record ID generated during re-ingest: ${recordId}`,
+        'This indicates a bug in record ID derivation; report this along with the selection manifest.',
+      );
+    }
+    seenIds.add(recordId);
+    const recordPath = join(recordsDir, `${recordId}.json`);
+
+    if (existsSync(recordPath)) {
+      skipped.push(recordId);
+      continue;
+    }
+
+    // Resolve the run manifest for this item
+    let runManifest;
+    if (manifest.source_type === 'run') {
+      runManifest = getRunManifest(manifest.source_id);
+    } else if (manifest.source_type === 'batch' && batchManifest) {
+      // Find which run this slot belongs to
+      const slotId = item.slot_or_output.split(':')[0];
+      const slot = batchManifest.slots?.find(s => s.slot_id === slotId);
+      if (slot) {
+        runManifest = getRunManifest(slot.run_id);
+      }
+    }
+
+    if (!runManifest) {
+      // Fallback: minimal provenance
+      runManifest = {
+        run_id: manifest.source_id,
+        brief_id: 'unknown',
+        workflow_template_id: manifest.workflow_id || 'unknown',
+        created_at: manifest.created_at,
+      };
+    }
+
+    // Build provenance
+    const prov = buildGeneratedProvenance({
+      sourceType: manifest.source_type,
+      sourceId: manifest.source_id,
+      runManifest,
+      batchManifest,
+      item,
+      projectRoot,
+    });
+
+    // Image source in selection/chosen/
+    const srcImage = join(selectionDir, 'chosen', item.filename);
+    const ext = extname(item.filename) || '.png';
+    const destImage = `${recordId}${ext}`;
+    const inboxPath = join(inboxDir, destImage);
+    const assetPath = `inbox/generated/${destImage}`;
+
+    // Get file size
+    let fileBytes = 0;
+    if (existsSync(srcImage)) {
+      fileBytes = statSync(srcImage).size;
+    }
+
+    // Build record
+    const record = buildBaseRecord(recordId, assetPath, {
+      width: null,
+      height: null,
+      bytes: fileBytes,
+    }, {
+      source: 'generated',
+      selection_id: selectionId,
+      generation_provenance: prov,
+    });
+
+    record.schema_version = '2.2.0';
+
+    // Tags
+    const recordTags = ['generated', 'selected'];
+    if (manifest.workflow_id) recordTags.push(manifest.workflow_id);
+    if (manifest.subject_id) recordTags.push(manifest.subject_id);
+    if (item.tags?.length) recordTags.push(...item.tags);
+    record.tags = [...new Set(recordTags)];
+
+    if (!dryRun) {
+      // Copy image into inbox
+      if (existsSync(srcImage)) {
+        await copyFile(srcImage, inboxPath);
+      }
+      // Write record
+      await writeFile(recordPath, JSON.stringify(record, null, 2) + '\n');
+    }
+
+    created.push(recordId);
+    provenanceLines.push(JSON.stringify({ record_id: recordId, ...prov }));
+  }
+
+  // Write provenance log
+  if (!dryRun && provenanceLines.length > 0) {
+    await writeFile(
+      join(selectionDir, 'provenance.jsonl'),
+      provenanceLines.join('\n') + '\n',
+    );
+  }
+
+  return { created, skipped };
+}