@mcptoolshop/style-dataset-lab 3.2.0 → 3.4.0

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.`;
+}

package/lib/measure.js

@@ -0,0 +1,422 @@
+/**
+ * Measure — orchestration for `sdlab measure`: resolve which images to
+ * measure, shell out to scripts/measure_image.py for the actual pixel math,
+ * and write the resulting numbers onto records.
+ *
+ * MEASUREMENT, NOT VERDICT (same spirit as lib/critique-engine.js's H2 fix):
+ * this module attaches a `measurements` block to a record. It never touches
+ * `judgment`, `canon`, or any pass/fail/approved/rejected field, and it
+ * never invents one. See scripts/measure_image.py's module docstring for
+ * the full port rationale (ported from the salt-road measure-palette.py /
+ * measure-texture.py instruments; DISTS/StyleLoss perceptual distance is
+ * deliberately out of scope — needs torch+piq).
+ *
+ * Python is an OPTIONAL runtime dependency of this ONE feature, not of the
+ * package (mirrors scripts/qwen_generate.py's relationship to the rest of
+ * sdlab, and tests/cli-scripts/qwen-python-parity.test.js's detection
+ * pattern, adopted here as findPython()/checkPythonDeps() so both
+ * scripts/measure.js and tests/lib-dataset/measure.test.js share one
+ * implementation instead of each hand-rolling their own).
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync, readFileSync, statSync, readdirSync, writeFileSync, mkdtempSync, rmSync,
+} from 'node:fs';
+import { readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { getPackageRoot, resolveSafeProjectPath } from './paths.js';
+import { inputError, runtimeError } from './errors.js';
+
+// ─── Identity / provenance constants (mirrors lib/verifier.js's
+// RULE_BASED_JUDGE / HUMAN_JUDGE naming discipline — "who produced this
+// number" gets a stable id the same way "who judged this" does) ──────────
+
+export const MEASURE_TOOL_ID = 'sdlab-measure-v1';
+export const MEASURE_SCHEMA_VERSION = '1.0.0';
+
+const IMAGE_EXT_RE = /\.(png|jpe?g)$/i;
+
+// Ported verbatim from measure-palette.py's saturated-pixel gate — see
+// scripts/measure_image.py's module docstring for the "ignore greys/darks"
+// rationale. Kept in sync with the Python-side defaults by hand (both files
+// document the same origin; there is no cross-language pinning contract
+// here the way there is for comfy_workflow_sha, since these are STATIC
+// defaults, not per-run computed values).
+const DEFAULT_SAT_MIN = 0.22;
+const DEFAULT_VAL_MIN = 0.18;
+const DEFAULT_HUE_TOLERANCE_DEG = 20;
+
+const REQUIRED_PY_MODULES = ['PIL', 'numpy', 'scipy'];
+
+const MEASURE_SCRIPT = join(getPackageRoot(), 'scripts', 'measure_image.py');
+
+// ─── Python environment detection ──────────────────────────────────────
+
+/**
+ * Locate a working Python interpreter. Precedence mirrors the rest of this
+ * codebase's env-var-override convention (paths.js's SDLAB_ROOT resolution:
+ * cheapest/most-explicit signal first): SDLAB_PYTHON env var if set, else
+ * try "python" then "python3" on PATH. Returns the command string to spawn,
+ * or null if nothing worked.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+export function findPython(env = process.env) {
+  const candidates = env.SDLAB_PYTHON ? [env.SDLAB_PYTHON] : ['python', 'python3'];
+  for (const cmd of candidates) {
+    const res = spawnSync(cmd, ['--version'], { encoding: 'utf-8' });
+    if (res.status === 0) return cmd;
+  }
+  return null;
+}
+
+/**
+ * Probe whether `pythonCmd` has the packages measure_image.py needs.
+ * Reports EVERY missing module in one pass (not just the first import
+ * failure) so the resulting error names all of them at once.
+ * @param {string} pythonCmd
+ * @param {{modules?: string[]}} [opts] — override the probed module list (tests use this)
+ * @returns {{ok: boolean, missing: string[]}}
+ */
+export function checkPythonDeps(pythonCmd, { modules = REQUIRED_PY_MODULES } = {}) {
+  const probe =
+    'import json\n' +
+    'mods = {}\n' +
+    `for m in ${JSON.stringify(modules)}:\n` +
+    '    try:\n' +
+    '        __import__(m)\n' +
+    '        mods[m] = True\n' +
+    '    except ImportError:\n' +
+    '        mods[m] = False\n' +
+    'print(json.dumps(mods))\n';
+  const res = spawnSync(pythonCmd, ['-c', probe], { encoding: 'utf-8' });
+  if (res.status !== 0) {
+    return { ok: false, missing: [...modules], raw: (res.stderr || res.error?.message || 'probe failed').trim() };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse((res.stdout || '').trim());
+  } catch {
+    return { ok: false, missing: [...modules], raw: (res.stdout || '').trim() };
+  }
+  const missing = modules.filter((m) => !parsed[m]);
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Throwing convenience wrapper for the CLI boundary: locate Python and
+ * verify its deps, or fail with a clear, actionable SdlabError naming
+ * exactly what is missing. This is the ONLY function in this module that
+ * throws on a missing/incomplete Python environment — findPython() and
+ * checkPythonDeps() stay pure so tests can drive every branch directly.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string} the python command to use
+ */
+export function assertMeasurementPrereqs(env = process.env) {
+  const python = findPython(env);
+  if (!python) {
+    throw runtimeError(
+      'RUNTIME_PYTHON_MISSING',
+      'Python was not found on PATH (tried "python", "python3").',
+      'sdlab measure needs Python 3.9+ with Pillow, numpy, and scipy for image measurement ' +
+        '(see scripts/measure_image.py). Install Python and ensure it is on PATH, or set ' +
+        'SDLAB_PYTHON to an explicit interpreter path.'
+    );
+  }
+  const deps = checkPythonDeps(python);
+  if (!deps.ok) {
+    throw runtimeError(
+      'RUNTIME_PYTHON_DEPS_MISSING',
+      `Python found (${python}) but missing required package(s): ${deps.missing.join(', ')}.`,
+      `Install them: pip install pillow numpy scipy${deps.raw ? ` (probe said: ${deps.raw})` : ''}`
+    );
+  }
+  return python;
+}
+
+// ─── Target resolution ──────────────────────────────────────────────────
+
+/**
+ * Minimal `*`/`?` glob-to-RegExp. No npm glob dependency exists in this
+ * package (checked before writing this — lib/ and scripts/ have none) and
+ * this file may not add one (package.json is outside this feature's
+ * exclusive file ownership), so record-id matching gets a small hand-rolled
+ * matcher instead of a library.
+ */
+function globToRegExp(pattern) {
+  let out = '';
+  for (const ch of pattern) {
+    if (ch === '*') out += '.*';
+    else if (ch === '?') out += '.';
+    else out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/**
+ * Resolve the `<dir-or-record-glob>` positional into a concrete list of
+ * {id, recordPath, imagePath} targets.
+ *
+ *   - If it resolves to an existing directory (inside the project — see
+ *     resolveSafeProjectPath), every *.png/*.jpg/*.jpeg inside is paired
+ *     with records/<stem>.json by filename stem. Images with no matching
+ *     record are reported in `skipped`, never silently dropped (mirrors
+ *     lib/runtime-runs.js listRuns()'s B01 fix: always report a count,
+ *     detail under --verbose).
+ *   - Otherwise it is treated as a glob PATTERN matched against record ids
+ *     under <project>/records/*.json; each match's image comes from that
+ *     record's own `asset_path` (a trusted, already-on-disk field — joined
+ *     plainly, same as curate.js does with record.asset_path, not run
+ *     through resolveSafeProjectPath a second time).
+ *
+ * @param {string} projectRoot
+ * @param {string} targetArg
+ * @returns {{targets: Array<{id:string, recordPath:string, imagePath:string}>, skipped: Array<{id:string, reason:string}>}}
+ */
+export function resolveMeasureTargets(projectRoot, targetArg) {
+  if (!targetArg) {
+    throw inputError(
+      'INPUT_MISSING_ARGS',
+      'sdlab measure requires a <dir-or-record-glob> positional argument.',
+      'Example: sdlab measure outputs/approved --project salt-road, or ' +
+        'sdlab measure "styleset_p*" --project salt-road (quote glob patterns so your shell does not expand them).'
+    );
+  }
+
+  const recordsDir = join(projectRoot, 'records');
+  // Security boundary FIRST: whether targetArg turns out to be a directory
+  // or a glob pattern, an escape attempt (`..`, an absolute path outside
+  // the project) is rejected before either interpretation is considered.
+  const asPath = resolveSafeProjectPath(projectRoot, targetArg, { flagName: 'target' });
+
+  const targets = [];
+  const skipped = [];
+  const isDir = existsSync(asPath) && statSync(asPath).isDirectory();
+
+  if (isDir) {
+    const files = readdirSync(asPath, { withFileTypes: true })
+      .filter((e) => e.isFile() && IMAGE_EXT_RE.test(e.name))
+      .map((e) => e.name)
+      .sort();
+    for (const file of files) {
+      const id = file.replace(IMAGE_EXT_RE, '');
+      const recordPath = join(recordsDir, `${id}.json`);
+      if (existsSync(recordPath)) {
+        targets.push({ id, recordPath, imagePath: join(asPath, file) });
+      } else {
+        skipped.push({ id, reason: `no matching record at records/${id}.json` });
+      }
+    }
+  } else {
+    const re = globToRegExp(targetArg);
+    const files = existsSync(recordsDir) ? readdirSync(recordsDir).filter((f) => f.endsWith('.json')) : [];
+    for (const file of files) {
+      const id = file.slice(0, -'.json'.length);
+      if (!re.test(id)) continue;
+      const recordPath = join(recordsDir, file);
+      const record = JSON.parse(readFileSync(recordPath, 'utf-8'));
+      if (!record.asset_path) {
+        skipped.push({ id, reason: 'record has no asset_path' });
+        continue;
+      }
+      targets.push({ id, recordPath, imagePath: join(projectRoot, record.asset_path) });
+    }
+  }
+
+  if (targets.length === 0) {
+    throw inputError(
+      'INPUT_NO_MATCHES',
+      `No records matched "${targetArg}" under ${recordsDir}.`,
+      isDir
+        ? 'The directory exists but no image inside it has a matching records/<id>.json.'
+        : 'Check the glob pattern (quote it so your shell does not expand it), or pass an existing directory of images instead.'
+    );
+  }
+
+  return { targets, skipped };
+}
+
+// ─── Anchors ─────────────────────────────────────────────────────────────
+
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+/**
+ * Load a palette anchor config from `--anchors <path>`.
+ *
+ * constitution.json carries no hex/numeric palette data for either salt-road
+ * or star-freight (checked directly before building this — both files are
+ * qualitative rule descriptions with rationale templates, not colour
+ * values; the actual hex anchors salt-road uses live in prose in
+ * canon/salt-road-art-contract.md, not in machine-readable config). So this
+ * is a real `--anchors` flag, not a schema invented to route around a
+ * missing feature.
+ *
+ * Unlike --source/--outputs elsewhere in this codebase (which legitimately
+ * reference shared cross-project directories, hence their REPO_ROOT-scoped
+ * containment), --anchors is scoped to the PROJECT root: anchor definitions
+ * are project-specific canon data, same as constitution.json/lanes.json.
+ *
+ * @param {string|undefined} anchorsFlag — raw --anchors value, or undefined
+ * @param {string} projectRoot
+ * @returns {{anchors: Array<{name:string,hex:string}>, hue_tolerance_deg: number, sat_min: number, val_min: number, source: string|null}}
+ */
+export function loadAnchors(anchorsFlag, projectRoot) {
+  if (!anchorsFlag) {
+    return {
+      anchors: [],
+      hue_tolerance_deg: DEFAULT_HUE_TOLERANCE_DEG,
+      sat_min: DEFAULT_SAT_MIN,
+      val_min: DEFAULT_VAL_MIN,
+      source: null,
+    };
+  }
+
+  const absPath = resolveSafeProjectPath(projectRoot, anchorsFlag, { flagName: 'anchors' });
+  if (!existsSync(absPath)) {
+    throw inputError('INPUT_ANCHORS_NOT_FOUND', `--anchors file not found: ${absPath}`);
+  }
+  let data;
+  try {
+    data = JSON.parse(readFileSync(absPath, 'utf-8'));
+  } catch (err) {
+    throw inputError('INPUT_INVALID_JSON', `--anchors file is not valid JSON: ${absPath} (${err.message})`);
+  }
+  const anchors = Array.isArray(data) ? data : data.anchors;
+  if (!Array.isArray(anchors) || anchors.length === 0) {
+    throw inputError(
+      'INPUT_BAD_ANCHORS',
+      `${absPath} must contain a non-empty "anchors" array of {name, hex}.`,
+      'Example: { "anchors": [{"name":"ochre-warm","hex":"#c9a877"}] }'
+    );
+  }
+  for (const a of anchors) {
+    if (!a || typeof a.name !== 'string' || !a.name || typeof a.hex !== 'string' || !HEX_RE.test(a.hex)) {
+      throw inputError(
+        'INPUT_BAD_ANCHORS',
+        `Invalid anchor entry in ${absPath}: ${JSON.stringify(a)}`,
+        'Each anchor needs a "name" string and a "hex" color like "#c9a877".'
+      );
+    }
+  }
+  return {
+    anchors,
+    hue_tolerance_deg: data.hue_tolerance_deg ?? DEFAULT_HUE_TOLERANCE_DEG,
+    sat_min: data.sat_min ?? DEFAULT_SAT_MIN,
+    val_min: data.val_min ?? DEFAULT_VAL_MIN,
+    source: relative(projectRoot, absPath),
+  };
+}
+
+// ─── Python invocation ───────────────────────────────────────────────────
+
+/**
+ * Spawn scripts/measure_image.py once for a whole batch of images (one
+ * process, not one-per-image — keeps interpreter-startup overhead off the
+ * per-image cost). Writes the request to a temp file, mirroring
+ * scripts/qwen_generate.py's `--wave <path>` handoff shape.
+ *
+ * @param {string} pythonCmd
+ * @param {{images: Array<{id:string,path:string}>, anchors?: Array, hue_tolerance_deg?: number, sat_min?: number, val_min?: number}} request
+ * @returns {{schema_version, tool, results: Array, errors: Array, ok_count: number, error_count: number}}
+ */
+export function runPythonMeasurement(pythonCmd, request) {
+  const dir = mkdtempSync(join(tmpdir(), 'sdlab-measure-'));
+  try {
+    const requestPath = join(dir, 'request.json');
+    const outPath = join(dir, 'result.json');
+    writeFileSync(requestPath, JSON.stringify(request, null, 2));
+
+    const res = spawnSync(pythonCmd, [MEASURE_SCRIPT, '--request', requestPath, '--out', outPath], {
+      encoding: 'utf-8',
+    });
+
+    if (!existsSync(outPath)) {
+      throw runtimeError(
+        'RUNTIME_MEASURE_FAILED',
+        `measure_image.py did not produce a result (exit ${res.status ?? 'unknown'}).`,
+        (res.stderr || res.stdout || '').trim().slice(0, 2000) || 'Run with --debug for detail.'
+      );
+    }
+    return JSON.parse(readFileSync(outPath, 'utf-8'));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ─── Record writing (atomic) ─────────────────────────────────────────────
+
+/**
+ * Temp-file-in-same-dir + rename — the exact pattern documented in
+ * lib/runtime-runs.js's atomicWriteJson (that function is module-private
+ * there, and is duplicated ad hoc in lib/batch-runs.js and
+ * lib/reingest-selected.js too — this file cannot import a shared version
+ * because none is exported anywhere in the codebase; extracting one would
+ * mean editing those files, which sit outside this feature's exclusive file
+ * ownership). Same tmp-name scheme as all three existing copies, for
+ * consistency: `${targetPath}.tmp-${pid}-${timestamp}`.
+ */
+async function atomicWriteJson(targetPath, obj) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  const body = JSON.stringify(obj, null, 2) + '\n';
+  try {
+    await writeFile(tmpPath, body);
+    await rename(tmpPath, targetPath);
+  } catch (err) {
+    try {
+      await unlink(tmpPath);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+}
+
+/**
+ * Build the `measurements` block and (unless dryRun) write it onto each
+ * matched record. Idempotent by design — an unchanged image + unchanged
+ * code reproduces the exact same palette/texture numbers on every run;
+ * only `measured_at` moves forward, the same way re-running `sdlab curate`
+ * or `sdlab bind` overwrites the prior judgment/binding rather than
+ * appending to a history log (see the sdlab compensators table).
+ *
+ * @param {Array<{id:string, recordPath:string}>} targets
+ * @param {{results: Array, errors: Array}} pyResult
+ * @param {{anchorsSource: string|null, dryRun: boolean}} opts
+ * @returns {Promise<{applied: Array<{id:string, measurements:Object}>, failed: Array<{id:string, error:string}>}>}
+ */
+export async function applyMeasurements(targets, pyResult, { anchorsSource = null, dryRun = false } = {}) {
+  const byId = new Map((pyResult.results || []).map((r) => [r.id, r]));
+  const errById = new Map((pyResult.errors || []).map((e) => [e.id, e]));
+  const applied = [];
+  const failed = [];
+
+  for (const t of targets) {
+    const ok = byId.get(t.id);
+    if (!ok) {
+      const err = errById.get(t.id);
+      failed.push({ id: t.id, error: err?.error || 'no result returned for this image' });
+      continue;
+    }
+
+    const measurements = {
+      measured_at: new Date().toISOString(),
+      tool: MEASURE_TOOL_ID,
+      schema_version: MEASURE_SCHEMA_VERSION,
+      anchors_source: anchorsSource,
+      image: ok.image,
+      palette: ok.palette,
+      texture: ok.texture,
+    };
+    applied.push({ id: t.id, measurements });
+
+    if (!dryRun) {
+      const record = JSON.parse(await readFile(t.recordPath, 'utf-8'));
+      record.measurements = measurements;
+      await atomicWriteJson(t.recordPath, record);
+    }
+  }
+
+  return { applied, failed };
+}