@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/ingest.js

@@ -0,0 +1,396 @@
+/**
+ * Ingest engine — bring pre-existing images into the pipeline as bare,
+ * uncurated candidate records.
+ *
+ * The gap this closes: there was no CLI path to get an image that was NOT
+ * produced by `sdlab generate`/`run generate`/`batch generate` into the
+ * project. `sdlab reingest generated` requires a trained LoRA's training
+ * manifest (lib/reingest.js loadTrainingManifest() unconditionally) — it
+ * exists to bring TRAINED-MODEL outputs back in, not pre-training
+ * candidates. `sdlab reingest selected` requires a selection id, which only
+ * the production loop can mint. Neither can take "a folder of images from
+ * somewhere else" (hand-picked references, a batch rendered in external
+ * Python against Comfy Cloud, salvage from a lost pipeline run) and turn it
+ * into records ready for `sdlab curate`. This module is that third path.
+ *
+ * Non-negotiables this module holds itself to:
+ *  - NEVER invents a judgment, a score, or a caption. Every record ships
+ *    with judgment: null, canon: null (via buildBaseRecord, the same
+ *    shared helper lib/reingest.js already uses) — uncurated, exactly like
+ *    everything else that hasn't been through `sdlab curate` yet.
+ *  - provenance.source is always 'external' — honestly distinguishable
+ *    from provenance.source === 'generated' (lib/reingest.js) and from the
+ *    flat generation_provenance shape lib/generated-provenance.js builds
+ *    for selected run/batch outputs. An ingested record's generation
+ *    details (prompt, seed, ...) are attached ONLY when a --wave file or a
+ *    receipts.jsonl actually supplies them for that specific id — never
+ *    guessed, never interpolated from a sibling.
+ *  - id derivation is validated, not silently rewritten: a filename stem
+ *    that fails the SAME allowlist lib/export.js already uses for every
+ *    other record-id-becomes-a-filename boundary (SAFE_ID_RE / assertSafeId
+ *    — SDL-H5) is rejected per-file with a reason, not coerced into
+ *    something "close enough". A directory scan is bulk, externally-named
+ *    input by nature (unlike an already-pipeline-produced record id), so
+ *    one unsafe filename is reported and skipped rather than aborting the
+ *    whole ingest — the vector is closed either way, since no path is ever
+ *    built from a name that fails the check.
+ *  - --dry-run performs zero filesystem writes: no mkdir, no image copy, no
+ *    record write. (SDL-M11 fixed five scripts that violated exactly this.)
+ *  - idempotent: an id whose record already exists is skipped, never
+ *    duplicated or clobbered, and every skip is reported back to the
+ *    caller (not just counted).
+ *  - crash-safe: both the copied image and the written record land via
+ *    temp-file-then-rename, mirroring the atomic pattern lib/runtime-runs.js
+ *    (saveRunManifest/checkpointRunManifest) and lib/batch-runs.js already
+ *    use. A process killed mid-write must never leave a truncated file at
+ *    the FINAL path that a later run's existsSync() mistakes for "done".
+ */
+
+import { readFile, writeFile, readdir, stat, mkdir, copyFile, rename, unlink } from 'node:fs/promises';
+import { join, basename, extname, relative, sep } from 'node:path';
+import { existsSync } from 'node:fs';
+import { buildBaseRecord } from './records.js';
+import { assertSafeId } from './export.js';
+import { inputError } from './errors.js';
+import { warn, verbose } from './log.js';
+
+// Mirrors lib/reingest.js's IMAGE_EXTENSIONS. Not imported from there —
+// that module doesn't export the constant, and this file's ownership
+// boundary for this change doesn't include editing lib/reingest.js.
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
+
+const RECEIPTS_FILENAME = 'receipts.jsonl';
+
+/** Normalize a path to forward slashes for storage (matches asset_path style used throughout this codebase). */
+function toPortablePath(p) {
+  return p.split(sep).join('/');
+}
+
+// ─── Atomic write helpers ──────────────────────────────────────────
+//
+// Same temp-file-then-rename shape as lib/runtime-runs.js's
+// atomicWriteJson / lib/batch-runs.js's atomicWriteJson / lib/reingest-
+// selected.js's atomicWriteText. None of those three are exported (each
+// module keeps its own copy — that is the established convention in this
+// codebase for this exact ~10-line helper, not an oversight to "fix" by
+// centralizing here), so this is a fourth copy of the same pattern rather
+// than a new invention.
+
+async function atomicWriteFile(targetPath, body) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await writeFile(tmpPath, body);
+    await rename(tmpPath, targetPath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+/**
+ * Copy a file atomically: copy to a temp path in the SAME directory as
+ * destPath, then rename. A process killed mid-copy leaves only the
+ * uniquely-named temp file behind — never a partial file sitting at
+ * destPath that a later run's `existsSync(destPath)` would mistake for a
+ * complete, already-ingested image and skip re-copying forever.
+ */
+async function atomicCopyFile(srcPath, destPath) {
+  const tmpPath = `${destPath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await copyFile(srcPath, tmpPath);
+    await rename(tmpPath, destPath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+// ─── Wave / receipts loaders ────────────────────────────────────────
+
+/**
+ * Load a wave pack (the shape of projects/salt-road/inputs/prompts/
+ * wave-v2.json: `{ formula_ref?, wave?, items: [{ id, seed, subject, ... }] }`)
+ * into a Map<id, item>. Falls back to a `subjects` array (the
+ * `sdlab generate` prompt-pack shape) if `items` is absent, so a wave file
+ * authored either way is still usable.
+ *
+ * Returns an empty index when wavePath is falsy — --wave is opt-in
+ * enrichment, not a requirement. A wavePath that IS given but cannot be
+ * read/parsed is a user error worth stopping for (they asked for that
+ * file specifically), not a silent "provenance unknown" fallback.
+ *
+ * @param {string|null|undefined} wavePath — absolute, already-validated path
+ * @returns {Promise<{index: Map<string,Object>, formulaRef: string|null, waveName: string|null}>}
+ */
+export async function loadWaveIndex(wavePath) {
+  const index = new Map();
+  if (!wavePath) return { index, formulaRef: null, waveName: null };
+
+  if (!existsSync(wavePath)) {
+    throw inputError(
+      'INPUT_WAVE_NOT_FOUND',
+      `--wave file not found: ${wavePath}`,
+      'Check the path. Wave files live under inputs/prompts/*.json — see projects/salt-road/inputs/prompts/wave-v2.json for the shape.'
+    );
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(await readFile(wavePath, 'utf-8'));
+  } catch (err) {
+    throw inputError(
+      'INPUT_INVALID_JSON',
+      `Failed to parse --wave file ${wavePath}: ${err.message}`,
+      'Check the file for JSON syntax errors.'
+    );
+  }
+
+  const items = Array.isArray(raw.items) ? raw.items
+    : Array.isArray(raw.subjects) ? raw.subjects
+    : null;
+
+  if (!items) {
+    warn(`ingest: --wave file ${wavePath} has no "items" or "subjects" array — no entries will be attached.`);
+    return { index, formulaRef: raw.formula_ref || null, waveName: raw.wave || raw.name || null };
+  }
+
+  for (const item of items) {
+    if (item && typeof item.id === 'string') index.set(item.id, item);
+  }
+
+  return { index, formulaRef: raw.formula_ref || null, waveName: raw.wave || raw.name || null };
+}
+
+/**
+ * Load a receipts.jsonl (the shape of projects/salt-road/inbox/generated/
+ * set-v2-2026-07-30/receipts.jsonl: one `{id, status, prompt_id, seed, secs}`
+ * object per line) into a Map<id, receipt>.
+ *
+ * Best-effort by design: a missing file yields an empty Map (this is
+ * opportunistic enrichment co-located with the images, not a requirement),
+ * and a malformed INDIVIDUAL line is skipped with a warning rather than
+ * failing the whole load — one corrupt trailing line from an interrupted
+ * write must not blank out every other real receipt in the file.
+ *
+ * @param {string} receiptsPath — absolute path
+ * @returns {Promise<Map<string,Object>>}
+ */
+export async function loadReceiptsIndex(receiptsPath) {
+  const index = new Map();
+  if (!receiptsPath || !existsSync(receiptsPath)) return index;
+
+  const raw = await readFile(receiptsPath, 'utf-8');
+  const lines = raw.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed) continue;
+    try {
+      const entry = JSON.parse(trimmed);
+      if (entry && typeof entry.id === 'string') index.set(entry.id, entry);
+    } catch (err) {
+      warn(`ingest: ${receiptsPath}:${i + 1} is not valid JSON — line skipped (${err.message})`);
+    }
+  }
+  return index;
+}
+
+// ─── Provenance builder ─────────────────────────────────────────────
+
+/**
+ * Build the provenance block for one ingested image. Additive-only: a
+ * field is set exactly when a real source (the --wave entry or the
+ * receipts.jsonl entry for this id) supplied it. Nothing here is ever
+ * synthesized, interpolated, or defaulted from another record.
+ */
+function buildExternalProvenance({ file, sourcePath, waveEntry, waveMeta, receiptEntry, receiptsRelPath }) {
+  const prov = {
+    source: 'external',
+    ingested_at: new Date().toISOString(),
+    original_filename: file,
+    original_path: sourcePath,
+  };
+
+  const notes = [];
+
+  if (waveEntry) {
+    prov.wave_file = waveMeta.waveRelPath;
+    if (waveMeta.waveName) prov.wave_name = waveMeta.waveName;
+    if (waveMeta.formulaRef) {
+      prov.formula_ref = waveMeta.formulaRef;
+      notes.push(
+        'preamble_ref/negative_ref are keys into the wave\'s formula_ref file, not literal prompt/negative text.'
+      );
+    }
+    if (waveEntry.seed !== undefined) prov.seed = waveEntry.seed;
+    const promptText = waveEntry.subject ?? waveEntry.prompt;
+    if (promptText !== undefined) prov.prompt = promptText;
+    if (waveEntry.preamble !== undefined) prov.preamble_ref = waveEntry.preamble;
+    if (waveEntry.neg !== undefined) prov.negative_ref = waveEntry.neg;
+    if (waveEntry.negExtra !== undefined) prov.negative_extra = waveEntry.negExtra;
+    if (waveEntry.cn !== undefined) prov.controlnet = waveEntry.cn;
+    if (waveEntry.enriched_by !== undefined) prov.enriched_by = waveEntry.enriched_by;
+  } else if (waveMeta.wavePath) {
+    notes.push(`No entry for this id was found in --wave file ${waveMeta.waveRelPath}.`);
+  }
+
+  if (receiptEntry) {
+    prov.receipts_file = receiptsRelPath;
+    if (receiptEntry.prompt_id !== undefined) prov.prompt_id = receiptEntry.prompt_id;
+    // Wave seed wins if both are present and disagree; a receipt seed is
+    // still useful when the wave lacked one — never overwritten if already set.
+    if (receiptEntry.seed !== undefined && prov.seed === undefined) prov.seed = receiptEntry.seed;
+    if (receiptEntry.secs !== undefined) prov.generation_seconds = receiptEntry.secs;
+    if (receiptEntry.status !== undefined) prov.receipt_status = receiptEntry.status;
+  }
+
+  prov.generation_provenance_known = Boolean(waveEntry || receiptEntry);
+  if (!waveEntry && !receiptEntry) {
+    notes.push(
+      waveMeta.wavePath
+        ? 'No matching wave or receipts.jsonl entry for this id — generation details are unknown.'
+        : 'No --wave file supplied and no receipts.jsonl found alongside the source images — generation details are unknown.'
+    );
+  }
+  if (notes.length) prov.provenance_note = notes.join(' ');
+
+  return prov;
+}
+
+// ─── Main entry point ────────────────────────────────────────────────
+
+/**
+ * Ingest a directory of pre-existing images into a project as bare,
+ * uncurated candidate records ready for `sdlab curate`.
+ *
+ * @param {string} projectRoot — absolute project root (already resolved by the caller)
+ * @param {string} sourceDir — absolute path to a directory of images (already validated by the caller)
+ * @param {Object} [options]
+ * @param {string} [options.wavePath] — absolute, already-validated path to a wave JSON file
+ * @param {boolean} [options.dryRun]
+ * @returns {Promise<{created: string[], skipped: string[], rejected: {file:string, reason:string}[], receiptsFile: string|null}>}
+ */
+export async function ingestDirectory(projectRoot, sourceDir, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+
+  if (!existsSync(sourceDir)) {
+    throw inputError(
+      'INPUT_SOURCE_NOT_FOUND',
+      `Source directory not found: ${sourceDir}`,
+      'Check the path passed to "sdlab ingest <dir>".'
+    );
+  }
+
+  const recordsDir = join(projectRoot, 'records');
+  const candidatesDir = join(projectRoot, 'outputs', 'candidates');
+
+  // Wave + receipts are loaded up front, once, before touching any output
+  // directory — reading is safe under --dry-run (no mutation).
+  const wavePath = options.wavePath || null;
+  const { index: waveIndex, formulaRef, waveName } = await loadWaveIndex(wavePath);
+  const waveMeta = {
+    wavePath,
+    waveRelPath: wavePath ? toPortablePath(relative(projectRoot, wavePath)) : null,
+    formulaRef,
+    waveName,
+  };
+
+  const receiptsPath = join(sourceDir, RECEIPTS_FILENAME);
+  const receiptsIndex = await loadReceiptsIndex(receiptsPath);
+  const receiptsFound = receiptsIndex.size > 0;
+  const receiptsRelPath = receiptsFound ? toPortablePath(relative(projectRoot, receiptsPath)) : null;
+  if (receiptsFound) {
+    verbose(`ingest: loaded ${receiptsIndex.size} receipt(s) from ${receiptsPath}`);
+  }
+
+  // SDL-M11 discipline: a --dry-run preview must be side-effect-free. Only
+  // create output directories on a real run.
+  if (!dryRun) {
+    await mkdir(recordsDir, { recursive: true });
+    await mkdir(candidatesDir, { recursive: true });
+  }
+
+  const entries = (await readdir(sourceDir)).sort();
+  const imageFiles = entries.filter((f) => IMAGE_EXTENSIONS.has(extname(f).toLowerCase()));
+
+  const created = [];
+  const skipped = [];
+  const rejected = [];
+
+  for (const file of imageFiles) {
+    const ext = extname(file);
+    const stem = basename(file, ext);
+
+    // SDL-H5-style boundary: a filename becoming a record id (and later a
+    // path segment for the copied image / record file) is a path-traversal
+    // vector. Reuses the exact allowlist lib/export.js already applies at
+    // every other record-id-becomes-a-filename boundary in this codebase.
+    // Unlike that adapter-layer call site (which hard-throws because an
+    // unsafe id THERE means a pipeline-internal invariant already broke),
+    // this is a first-touch scan of an arbitrary, externally-named
+    // directory — one badly-named file (spaces, unicode, an accidental
+    // "..") is the normal case, not an attack. It is rejected and reported
+    // so the other 99 files in the same directory still get ingested; the
+    // vector is closed identically either way, since no path is ever built
+    // from a name that fails this check.
+    try {
+      assertSafeId(stem, `filename "${file}" in ${sourceDir}`);
+    } catch (err) {
+      rejected.push({ file, reason: err.message });
+      continue;
+    }
+
+    const id = stem;
+    const recordPath = join(recordsDir, `${id}.json`);
+
+    if (existsSync(recordPath)) {
+      skipped.push(id);
+      continue;
+    }
+
+    if (dryRun) {
+      // Preview only — no stat(), no copy, no write. Report what WOULD be
+      // created without touching the filesystem beyond the read-only
+      // listing/existence checks already done above.
+      created.push(id);
+      continue;
+    }
+
+    const sourcePath = join(sourceDir, file);
+    const destPath = join(candidatesDir, file);
+    const assetPath = toPortablePath(join('outputs', 'candidates', file));
+
+    const fileStat = await stat(sourcePath);
+
+    if (!existsSync(destPath)) {
+      await atomicCopyFile(sourcePath, destPath);
+    }
+
+    const waveEntry = waveIndex.get(id) || null;
+    const receiptEntry = receiptsIndex.get(id) || null;
+    const provenance = buildExternalProvenance({
+      file,
+      sourcePath,
+      waveEntry,
+      waveMeta,
+      receiptEntry,
+      receiptsRelPath,
+    });
+
+    const record = buildBaseRecord(
+      id,
+      assetPath,
+      { width: null, height: null, bytes: fileStat.size },
+      provenance
+    );
+
+    await atomicWriteFile(recordPath, JSON.stringify(record, null, 2) + '\n');
+    created.push(id);
+  }
+
+  return {
+    created,
+    skipped,
+    rejected,
+    receiptsFile: receiptsFound ? receiptsRelPath : null,
+  };
+}

package/lib/judgment-provenance.js

@@ -0,0 +1,220 @@
+/**
+ * judgment-provenance.js — tell a judgment somebody MADE from one a script MINTED.
+ *
+ * Law 2 of this product is "inclusion is explainable": every record carries a
+ * reason it was included or excluded. That law is only worth anything if the
+ * reason describes the actual image.
+ *
+ * It currently doesn't, at scale. Measured on `projects/star-freight`
+ * (1,182 records) on 2026-08-04:
+ *
+ *   reviewer          records   distinct explanations   max reuse
+ *   bulk_curate_v2        566   ) 82 across both              x144
+ *   bulk_curate_v1        322   )
+ *   wave25-script          60     8                            x32
+ *   human:mike            110   110                             x1
+ *   (no judgment)         124     —                              —
+ *
+ * 948 of 1,182 records — 80% — carry a rationale that was selected by matching
+ * the record id against a prefix regex, not by looking at the image. One string
+ * ("On-style gritty space costume. Faction-appropriate material vocabulary and
+ * wear level…") appears verbatim on 144 different images. The three scripts
+ * that wrote them (`bulk-curate-wave2-5.js`, `bulk-curate-waves11-18.js`,
+ * `curate-wave25.js`) were deleted in this repo's Stage A health pass for
+ * exactly this reason — but deleting the tool did not retract its output, and
+ * that output still flows into eligibility, snapshots, splits, exports and
+ * training packages.
+ *
+ * The `human:mike` row is the control that makes this a finding rather than a
+ * guess: 110 records, 110 distinct explanations, nothing reused. Genuine
+ * curation in this corpus looks like one rationale per image.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * THIS MODULE READS. IT NEVER WRITES.
+ *
+ * The Director's ruling (2026-08-04) was "mark, don't touch": make the
+ * distinction visible everywhere it matters, and leave the records alone. So
+ * there is no migration here, no backfilled flag, no rewritten judgment. The
+ * signal is derived at read time from data already on disk, which also means
+ * it cannot drift out of sync with the records and needs no re-run when they
+ * change.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+/**
+ * Reviewer ids known to have been written by a bulk script rather than a
+ * person. Matched against `judgment.reviewer`.
+ *
+ * Deliberately a conservative allowlist of OBSERVED offenders, not a clever
+ * heuristic like /script|bot|auto/. A false positive here defames a real
+ * human judgment, which is worse than missing one: the corpus-level reuse
+ * statistic below catches anything this list doesn't, without needing to
+ * guess from a name.
+ */
+export const SCRIPT_REVIEWER_PATTERNS = Object.freeze([
+  /^bulk_curate(_v\d+)?$/i,
+  /^wave\d+-script$/i,
+]);
+
+/** A judgment is machine-minted, human-made, or absent. */
+export const JUDGMENT_ORIGIN = Object.freeze({
+  HUMAN: 'human',
+  SCRIPT: 'script',
+  UNKNOWN: 'unknown',
+  NONE: 'none',
+});
+
+/**
+ * Classify a single record's judgment origin from its reviewer id.
+ *
+ * @param {object} record
+ * @returns {'human'|'script'|'unknown'|'none'}
+ */
+export function classifyJudgmentOrigin(record) {
+  const judgment = record?.judgment;
+  if (!judgment || typeof judgment !== 'object') return JUDGMENT_ORIGIN.NONE;
+
+  const reviewer = judgment.reviewer;
+  if (typeof reviewer !== 'string' || reviewer.trim() === '') {
+    return JUDGMENT_ORIGIN.UNKNOWN;
+  }
+  if (SCRIPT_REVIEWER_PATTERNS.some((re) => re.test(reviewer))) {
+    return JUDGMENT_ORIGIN.SCRIPT;
+  }
+  // `human:<name>` is this corpus's convention for a person.
+  if (/^human(:|$)/i.test(reviewer)) return JUDGMENT_ORIGIN.HUMAN;
+
+  // A reviewer id we don't recognise. NOT assumed human — that assumption is
+  // how 948 fabricated rationales passed as curation for months.
+  return JUDGMENT_ORIGIN.UNKNOWN;
+}
+
+/**
+ * Corpus-level rationale-reuse audit.
+ *
+ * This is the evidence the reviewer-name check cannot give you, and it is the
+ * part that generalises: a rationale reused verbatim across many images did
+ * not describe any one of them, whoever or whatever wrote it. It catches a
+ * future bulk script under a reviewer id nobody has added to the list above.
+ *
+ * `reuseThreshold` is the count at which sharing stops being coincidence.
+ * Two records can legitimately share a terse reason ("out of focus"); 144
+ * cannot.
+ *
+ * @param {object[]} records
+ * @param {{reuseThreshold?: number}} [opts]
+ */
+export function auditJudgmentProvenance(records, opts = {}) {
+  const reuseThreshold = opts.reuseThreshold ?? 3;
+
+  const byOrigin = { human: 0, script: 0, unknown: 0, none: 0 };
+  const byReviewer = new Map();
+  const byExplanation = new Map();
+
+  for (const record of records) {
+    const origin = classifyJudgmentOrigin(record);
+    byOrigin[origin]++;
+
+    const judgment = record?.judgment;
+    if (!judgment) continue;
+
+    const reviewer = typeof judgment.reviewer === 'string' ? judgment.reviewer : '(unset)';
+    byReviewer.set(reviewer, (byReviewer.get(reviewer) ?? 0) + 1);
+
+    const explanation = judgment.explanation;
+    if (typeof explanation === 'string' && explanation.trim() !== '') {
+      const key = explanation.trim();
+      if (!byExplanation.has(key)) byExplanation.set(key, []);
+      byExplanation.get(key).push(record.id);
+    }
+  }
+
+  const reused = [...byExplanation.entries()]
+    .filter(([, ids]) => ids.length >= reuseThreshold)
+    .map(([explanation, ids]) => ({
+      explanation,
+      count: ids.length,
+      sample_record_ids: ids.slice(0, 5),
+    }))
+    .sort((a, b) => b.count - a.count);
+
+  const judgedCount = byOrigin.human + byOrigin.script + byOrigin.unknown;
+  const reusedRecordCount = reused.reduce((sum, r) => sum + r.count, 0);
+
+  return {
+    total_records: records.length,
+    judged: judgedCount,
+    by_origin: byOrigin,
+    by_reviewer: Object.fromEntries([...byReviewer.entries()].sort((a, b) => b[1] - a[1])),
+    // How many judged records carry a rationale that is not unique to them.
+    // This is the honest headline number — it does not depend on recognising
+    // a reviewer id.
+    reused_rationale_records: reusedRecordCount,
+    reused_rationale_ratio: judgedCount > 0 ? reusedRecordCount / judgedCount : 0,
+    reuse_threshold: reuseThreshold,
+    // Worst offenders first, capped — this is for an operator to read, not a
+    // full dump of a 1,182-record corpus.
+    top_reused: reused.slice(0, 10),
+    // True when any judged record's rationale is shared at or above the
+    // threshold. Consumers gate their wording on this rather than re-deriving.
+    has_reused_rationales: reusedRecordCount > 0,
+  };
+}
+
+/**
+ * One-line human summary for CLI output. Returns null when there is nothing
+ * to report, so a clean corpus prints nothing rather than a reassuring banner
+ * nobody reads.
+ *
+ * @param {ReturnType<typeof auditJudgmentProvenance>} audit
+ * @returns {string|null}
+ */
+export function formatProvenanceWarning(audit) {
+  // ONLY a script-minted judgment is asserted as a Law 2 problem.
+  //
+  // Reuse alone is NOT evidence of fabrication, and an earlier revision of
+  // this function got that wrong. Measured on `projects/tallow-fen`: 54 of
+  // 293 rationales are reused, and they are legitimate — two strings, ×28 and
+  // ×26, each accurately describing ONE systematic defect across exactly the
+  // images that have it ("style on-target but the style descriptor's
+  // lantern-light noun literalized"). Reviewers there are `human:mike` and
+  // `claude:fable-5`; zero scripts. That is good curation of a bad wave.
+  //
+  // The heuristic cannot separate "144 images share a canned category blurb
+  // chosen by id-prefix" from "28 images share a true description of one
+  // shared flaw" — so it must not claim to. A gate that fires when nothing is
+  // wrong teaches its reader to ignore it, which is the same defect class as
+  // a gate that cannot fire, pointed the other way.
+  if (audit.by_origin.script === 0) return null;
+
+  const pct = Math.round((audit.by_origin.script / Math.max(audit.judged, 1)) * 100);
+  let msg =
+    `Judgment provenance: ${audit.by_origin.script} of ${audit.judged} judgments (${pct}%) ` +
+    `were written by a bulk script, not a reviewer. Those rationales were selected by ` +
+    `matching the record id against a pattern — they do not describe the image. ` +
+    `Treat them as uncurated for Law 2 purposes.`;
+
+  if (audit.reused_rationale_records > 0) {
+    msg += ` (${audit.reused_rationale_records} rationales are also reused verbatim across records.)`;
+  }
+  return msg;
+}
+
+/**
+ * Neutral, non-accusatory reuse note — for corpora with no script reviewer but
+ * heavy rationale reuse. Reuse there is usually a real systematic defect
+ * described accurately across a wave, which is worth SEEING but is not a
+ * finding. Returns null when there is nothing to say.
+ *
+ * @param {ReturnType<typeof auditJudgmentProvenance>} audit
+ * @returns {string|null}
+ */
+export function formatReuseNote(audit) {
+  if (audit.by_origin.script > 0) return null; // the warning above covers it
+  if (audit.reused_rationale_records === 0) return null;
+
+  const pct = Math.round(audit.reused_rationale_ratio * 100);
+  return `${audit.reused_rationale_records} of ${audit.judged} rationales (${pct}%) are shared ` +
+    `across records — often one systematic defect described across the wave it affected. ` +
+    `Worth a glance, not necessarily a problem.`;
+}