@mcptoolshop/style-dataset-lab 3.3.0 → 3.4.0

package/lib/reingest-selected.js

@@ -6,7 +6,7 @@
  * canon-binding flow as everything else. No bypass.
  */
 
-import { writeFile, mkdir, copyFile } from 'node:fs/promises';
+import { writeFile, mkdir, copyFile, rename, unlink } from 'node:fs/promises';
 import { join, extname } from 'node:path';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { getRunsDir } from './paths.js';
@@ -16,6 +16,35 @@ import { buildGeneratedProvenance } from './generated-provenance.js';
 import { buildBaseRecord } from './records.js';
 import { inputError } from './errors.js';
 
+// SDL-H7: the only shape a selection id can ever legitimately have,
+// mirroring generateSelectionId() in lib/selections.js (selection_<date>_<seq>,
+// same prefix/date/seq scheme as run/batch ids). Validated BEFORE the id is
+// used anywhere — including before loadSelection(), which does its own
+// unguarded join — so a traversal payload never reaches the filesystem, and
+// before the join at `selectionDir` below, which this module writes
+// provenance.jsonl into. A mismatch reuses loadSelection's own
+// SELECTION_NOT_FOUND shape (not a distinct code) because no real selection
+// can ever have an id outside this shape.
+const SELECTION_ID_RE = /^selection_\d{4}-\d{2}-\d{2}_\d{3}$/;
+
+/**
+ * B03: atomic write helper — write temp + rename, mirroring the same
+ * temp-file-then-rename checkpoint pattern lib/batch-runs.js uses for its
+ * per-slot manifest checkpoint. Rename is atomic on a single filesystem, so
+ * a crash mid-write can never leave a half-written provenance.jsonl in
+ * place of a good one.
+ */
+async function atomicWriteText(targetPath, text) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await writeFile(tmpPath, text);
+    await rename(tmpPath, targetPath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
 /**
  * Re-ingest a selection — creates candidate records from chosen outputs.
  *
@@ -27,6 +56,14 @@ import { inputError } from './errors.js';
  * @returns {Promise<{created: string[], skipped: string[]}>}
  */
 export async function reingestSelection({ projectRoot, projectId, selectionId, dryRun }) {
+  if (typeof selectionId !== 'string' || !SELECTION_ID_RE.test(selectionId)) {
+    throw inputError(
+      'SELECTION_NOT_FOUND',
+      `Selection "${selectionId}" not found`,
+      'Check the selection ID or run: sdlab select --run <id> --approve <files>',
+    );
+  }
+
   const manifest = loadSelection(projectRoot, selectionId);
 
   if (!manifest.reingest_ready) {
@@ -69,7 +106,46 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
 
   const created = [];
   const skipped = [];
+
+  // B03: provenance.jsonl is now built incrementally — checkpointed (atomic
+  // full-rewrite, temp+rename) after every item — instead of accumulated in
+  // memory and overwritten once at the end. `provenanceLines` seeds from
+  // whatever is ALREADY on disk (e.g. left by an interrupted prior run of
+  // this same selection) so: (a) a rerun never duplicates a line for a
+  // record it already logged, and (b) a partial rerun can never ERASE lines
+  // a previous call already committed — the old end-of-run `writeFile`
+  // overwrote with only the CURRENT call's accumulator, so a second call
+  // touching fewer items than the first could silently wipe out provenance
+  // the first call had already written to disk.
+  const provenancePath = join(selectionDir, 'provenance.jsonl');
   const provenanceLines = [];
+  const seenProvenanceIds = new Set();
+  if (existsSync(provenancePath)) {
+    for (const line of readFileSync(provenancePath, 'utf-8').split('\n')) {
+      if (!line.trim()) continue;
+      provenanceLines.push(line);
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed?.record_id) seenProvenanceIds.add(parsed.record_id);
+      } catch {
+        // Tolerate a corrupt/partial trailing line from a prior crash —
+        // keep it verbatim rather than dropping it, just don't index it.
+      }
+    }
+  }
+
+  /**
+   * Checkpoint one provenance line: skips dryRun, and skips a record_id
+   * that's already logged (idempotent — safe to call on both the fresh-write
+   * path and the skip/backfill path below).
+   */
+  async function checkpointProvenance(recordId, prov) {
+    if (dryRun) return;
+    if (seenProvenanceIds.has(recordId)) return;
+    provenanceLines.push(JSON.stringify({ record_id: recordId, ...prov }));
+    seenProvenanceIds.add(recordId);
+    await atomicWriteText(provenancePath, provenanceLines.join('\n') + '\n');
+  }
 
   // D-010: use entries() — not indexOf() — to avoid O(n^2) behavior and
   // silent duplicate-ID bugs when manifest.items contains structurally
@@ -88,12 +164,11 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
     seenIds.add(recordId);
     const recordPath = join(recordsDir, `${recordId}.json`);
 
-    if (existsSync(recordPath)) {
-      skipped.push(recordId);
-      continue;
-    }
-
-    // Resolve the run manifest for this item
+    // Resolve the run manifest for this item + build its provenance BEFORE
+    // the existsSync check below — B03: a skipped (already-created) item
+    // still needs its provenance backfilled if an earlier interrupted run
+    // stopped short of appending it, so this can't be gated behind "the
+    // record is new".
     let runManifest;
     if (manifest.source_type === 'run') {
       runManifest = getRunManifest(manifest.source_id);
@@ -126,6 +201,16 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
       projectRoot,
     });
 
+    if (existsSync(recordPath)) {
+      // B03: the record already landed on disk (this item was completed by
+      // a prior, possibly-interrupted run of this same re-ingest). Backfill
+      // its provenance line if that prior run never got to append one —
+      // never let a record exist with no corresponding provenance entry.
+      await checkpointProvenance(recordId, prov);
+      skipped.push(recordId);
+      continue;
+    }
+
     // Image source in selection/chosen/
     const srcImage = join(selectionDir, 'chosen', item.filename);
     const ext = extname(item.filename) || '.png';
@@ -166,18 +251,15 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
       }
       // Write record
       await writeFile(recordPath, JSON.stringify(record, null, 2) + '\n');
+      // B03: checkpoint immediately after the record write (per-item,
+      // matching lib/batch-runs.js's per-slot checkpoint pattern) — NOT
+      // batched to the end of the run. A crash on item 120 of 200 must
+      // leave provenance for 1-119 durably on disk, not lose it because
+      // item 200 never finished.
+      await checkpointProvenance(recordId, prov);
     }
 
     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 };

package/lib/run-manifest.js

@@ -25,6 +25,7 @@
 import { createHash } from 'node:crypto';
 import { openSync, readSync, closeSync, statSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { warn } from './log.js';
 
 /**
  * Contract version for the `pinning` block itself. Bump when the block's shape
@@ -35,6 +36,16 @@ import { join } from 'node:path';
  */
 export const PINNING_VERSION = '1.0.0';
 
+/**
+ * The ONE hash_note value that means "hashing was never attempted because
+ * --hash-models wasn't passed" — NOT a failure. buildPinning() (B07) needs
+ * to tell this apart from every other hash_note (unresolved/stat
+ * failed/read error/no filename), all of which ARE failures worth warning
+ * about. Shared as a constant so hashModelFile's own note and buildPinning's
+ * filter can never drift apart.
+ */
+const HASH_SKIPPED_NOTE = 'hash skipped (pass --hash-models)';
+
 /**
  * Seed policies — the INTENT behind seed selection, recorded alongside the
  * concrete per-item seed values so a reader knows how to regenerate.
@@ -144,17 +155,24 @@ const KIND_SUBDIRS = {
 
 /**
  * Resolve a model filename to an absolute path under the models dir. Searches
- * the kind-appropriate subdirs first, then every known subdir, then the root.
- * Returns null when nothing matches (unresolvable → sha256 null with a note).
+ * ONLY the kind-appropriate subdirs (plus the modelsDir root itself, which is
+ * kind-agnostic, not another kind's territory) — mirroring ComfyUI's own
+ * loaders, which never search across kinds (a UNETLoader never looks in
+ * checkpoints/, a VAELoader never looks in loras/, etc).
+ *
+ * SDL-M8: this used to also fall back to every OTHER kind's subdirs, so a
+ * missing unet could silently resolve to a same-named file under
+ * checkpoints/ and get pinned as though it were the unet ComfyUI actually
+ * loaded — a clean-looking wrong identity. An honest `null` (unresolved →
+ * sha256 null + a note, see hashModelFile) is the correct outcome when the
+ * kind-specific subdirs don't have the file.
+ *
+ * Returns null when nothing matches.
  */
 export function resolveModelPath(name, kind, modelsDir = defaultModelsDir()) {
   if (!name || !modelsDir) return null;
+  const subdirs = [...(KIND_SUBDIRS[kind] || []), '.'];
   const tried = new Set();
-  const subdirs = [
-    ...(KIND_SUBDIRS[kind] || []),
-    ...Object.values(KIND_SUBDIRS).flat(),
-    '.',
-  ];
   for (const sub of subdirs) {
     const candidate = join(modelsDir, sub, name);
     if (tried.has(candidate)) continue;
@@ -183,12 +201,52 @@ export function sha256File(path) {
   return 'sha256:' + hash.digest('hex');
 }
 
+// SDL-M9: a cheap partial-content fingerprint folded into the cache key
+// alongside name/size/mtime. The key used to be bare name:size:round(mtime)
+// with no content check — on a coarse-mtime mount (network shares, some
+// FAT/exFAT mounts), a same-size in-place replacement (e.g. swapping a
+// LoRA) can round to the SAME mtime as the file it replaced, so the cache
+// would silently serve the sha256 of the OLD content forever. Sampling the
+// first/last few KB — not hashing the whole multi-GB file, which would
+// defeat the point of caching — is enough to catch almost any real
+// replacement while staying cheap on every call (including cache hits).
+const SAMPLE_BYTES = 4096;
+
+/**
+ * Cheap content fingerprint: sha256 of the first + last SAMPLE_BYTES of the
+ * file (or the whole file if smaller). Synchronous, bounded I/O — a few KB
+ * regardless of file size, unlike sha256File's full-content streaming read.
+ */
+function sampleFingerprint(path, size) {
+  const fd = openSync(path, 'r');
+  try {
+    const hash = createHash('sha256');
+    const headLen = Math.min(SAMPLE_BYTES, size);
+    if (headLen > 0) {
+      const head = Buffer.allocUnsafe(headLen);
+      readSync(fd, head, 0, headLen, 0);
+      hash.update(head);
+    }
+    if (size > SAMPLE_BYTES) {
+      const tailLen = Math.min(SAMPLE_BYTES, size - headLen);
+      const tail = Buffer.allocUnsafe(tailLen);
+      readSync(fd, tail, 0, tailLen, size - tailLen);
+      hash.update(tail);
+    }
+    return hash.digest('hex').slice(0, 16);
+  } finally {
+    closeSync(fd);
+  }
+}
+
 /**
  * Best-effort content identity for one model/LoRA file: {name, size_bytes, sha256}
  * (+ a short `hash_note` when sha256 can't be produced). size_bytes is always
  * filled when the file resolves (a cheap stat); sha256 is gated behind
- * `doHash` (the --hash-models opt-in) and cached by (name, size, mtime) so
- * multi-GB checkpoints aren't re-hashed every wave.
+ * `doHash` (the --hash-models opt-in) and cached by (name, size, mtime,
+ * partial-content sample) so multi-GB checkpoints aren't re-hashed every
+ * wave (SDL-M9: the sample is what keeps a same-size in-place replacement
+ * from reusing a stale cache entry).
  *
  * @param {string} name — model filename as it appears in the graph
  * @param {Object} [opts]
@@ -210,8 +268,16 @@ export function hashModelFile(name, { kind, modelsDir = defaultModelsDir(), doHa
   } catch {
     return { name, size_bytes: null, sha256: null, hash_note: 'stat failed' };
   }
-  if (!doHash) return { name, size_bytes, sha256: null, hash_note: 'hash skipped (pass --hash-models)' };
-  const key = `${name}:${size_bytes}:${Math.round(mtimeMs)}`;
+  if (!doHash) return { name, size_bytes, sha256: null, hash_note: HASH_SKIPPED_NOTE };
+  let sample = '';
+  try {
+    sample = sampleFingerprint(resolved, size_bytes);
+  } catch {
+    // Best-effort — if sampling fails, fall back to the coarser
+    // name:size:mtime key; the sha256File() attempt below will surface any
+    // real read error anyway.
+  }
+  const key = `${name}:${size_bytes}:${Math.round(mtimeMs)}:${sample}`;
   if (cache?.map?.has(key)) return { name, size_bytes, sha256: cache.map.get(key) };
   let sha256;
   try {
@@ -295,14 +361,34 @@ export function flushHashCache(cache) {
  */
 export function buildPinning({ graph, models = {}, loras = [], seedPolicy = null, hashModels = false, modelsDir = defaultModelsDir(), cache } = {}) {
   const opts = { modelsDir, doHash: hashModels, cache };
+  const modelHashes = buildModelHashes(models, opts);
+  const loraHashes = (loras || []).map((l) => ({
+    ...hashModelFile(l.name, { ...opts, kind: 'lora' }),
+    weight: l.weight ?? 1.0,
+  }));
+
+  // B07: hash_note silently encoded a hashing FAILURE (unresolved file,
+  // stat failed, read error, no filename) with nothing reading it —
+  // buildPinning() never aggregated or logged, and this file imported no
+  // logger at all. A typo'd SDLAB_MODELS_DIR produced a wave where every
+  // model has sha256: null + a note, with zero console signal — PIN_PER_STEP's
+  // whole purpose (byte-for-byte replayability) lost silently. Warn ONCE per
+  // wave with a count, but never on HASH_SKIPPED_NOTE — that note means
+  // "hashing wasn't requested" (the default, --hash-models omitted), which
+  // is expected behavior, not a failure, and would make every ordinary run
+  // noisy if it warned too.
+  const allEntries = [...Object.values(modelHashes), ...loraHashes];
+  const failed = allEntries.filter((e) => e && e.hash_note != null && e.hash_note !== HASH_SKIPPED_NOTE);
+  if (failed.length > 0) {
+    const detail = failed.map((e) => `${e.name ?? '(unnamed)'} (${e.hash_note})`).join(', ');
+    warn(`buildPinning: ${failed.length}/${allEntries.length} model(s)/lora(s) failed to hash: ${detail}`);
+  }
+
   return {
     pinning_version: PINNING_VERSION,
     comfy_workflow_sha: comfyWorkflowSha(graph),
     seed_policy: seedPolicy,
-    models: buildModelHashes(models, opts),
-    loras: (loras || []).map((l) => ({
-      ...hashModelFile(l.name, { ...opts, kind: 'lora' }),
-      weight: l.weight ?? 1.0,
-    })),
+    models: modelHashes,
+    loras: loraHashes,
   };
 }

package/lib/run-summary.js

@@ -12,8 +12,11 @@ import { join } from 'node:path';
  * Build a summary object from a manifest.
  */
 export function buildRunSummary(manifest) {
-  const ok = manifest.outputs.filter(o => o.status === 'ok');
-  const failed = manifest.outputs.filter(o => o.status === 'error');
+  // B10: defensive default — manifest.errors two lines below already had
+  // one; a legacy/truncated manifest with no `outputs` field crashed here
+  // with a bare TypeError instead of degrading to an empty results view.
+  const ok = (manifest.outputs || []).filter(o => o.status === 'ok');
+  const failed = (manifest.outputs || []).filter(o => o.status === 'error');
   const totalElapsed = ok.reduce((sum, o) => sum + (o.elapsed_ms || 0), 0);
 
   return {
@@ -54,7 +57,7 @@ export function renderRunMarkdown(manifest) {
   lines.push('');
   lines.push(`| # | Seed | Status | File | Time |`);
   lines.push(`|---|------|--------|------|------|`);
-  for (const out of manifest.outputs) {
+  for (const out of (manifest.outputs || [])) {
     const file = out.filename || '—';
     const time = out.elapsed_ms ? `${(out.elapsed_ms / 1000).toFixed(1)}s` : '—';
     const status = out.status === 'ok' ? '✓' : out.status === 'dry_run' ? '○' : '✗';
@@ -98,8 +101,11 @@ export function renderRunMarkdown(manifest) {
  * Render a manifest to terminal text.
  */
 export function renderRunText(manifest) {
-  const ok = manifest.outputs.filter(o => o.status === 'ok' || o.status === 'dry_run');
-  const failed = manifest.outputs.filter(o => o.status === 'error');
+  // B10: same defensive default as buildRunSummary above — not explicitly
+  // named by line number in the finding, but the identical defect in the
+  // same file (this is the function `sdlab run show` calls in text mode).
+  const ok = (manifest.outputs || []).filter(o => o.status === 'ok' || o.status === 'dry_run');
+  const failed = (manifest.outputs || []).filter(o => o.status === 'error');
   const lines = [];
 
   lines.push(`Run: ${manifest.run_id}`);
@@ -111,7 +117,7 @@ export function renderRunText(manifest) {
   if (failed.length > 0) lines.push(`Errors: ${failed.length}`);
   lines.push('');
 
-  for (const out of manifest.outputs) {
+  for (const out of (manifest.outputs || [])) {
     const status = out.status === 'ok' ? '✓' : out.status === 'dry_run' ? '○' : '✗';
     const time = out.elapsed_ms ? ` (${(out.elapsed_ms / 1000).toFixed(1)}s)` : '';
     const file = out.filename ? ` → ${out.filename}` : '';

package/lib/runtime-runs.js

@@ -11,7 +11,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { randomInt } from 'node:crypto';
 import { getRunsDir, getBriefsDir } from './paths.js';
 import { inputError } from './errors.js';
-import { verbose } from './log.js';
+import { verbose, warn } from './log.js';
 
 // ─── Run ID generation ───────────────────────────────────────────
 
@@ -165,10 +165,28 @@ export async function checkpointRunManifest(runDir, manifest) {
 
 // ─── Load / List ─────────────────────────────────────────────────
 
+// SDL-H7: the only shape a run id can ever legitimately have, mirroring the
+// prefix/date/seq scheme generateRunId() builds above. Validated BEFORE the
+// id is joined into a path, so `--resume ../../../../some/dir/leftover`
+// (or any other traversal payload) never reaches existsSync/readFile. A
+// mismatch is reported as the SAME RUN_NOT_FOUND (not a distinct code)
+// because no real run can ever have an id outside this shape — the two
+// cases are indistinguishable to the caller, and this avoids leaking
+// validation internals to whoever is probing.
+const RUN_ID_RE = /^run_\d{4}-\d{2}-\d{2}_\d{3}$/;
+
 /**
  * Load a run manifest by ID.
  */
 export async function loadRun(projectRoot, runId) {
+  if (typeof runId !== 'string' || !RUN_ID_RE.test(runId)) {
+    throw inputError(
+      'RUN_NOT_FOUND',
+      `Run "${runId}" not found`,
+      `Check the run ID or run: sdlab run generate --brief <id>`
+    );
+  }
+
   const runDir = join(getRunsDir(projectRoot), runId);
   const manifestPath = join(runDir, 'manifest.json');
 
@@ -185,6 +203,15 @@ export async function loadRun(projectRoot, runId) {
 
 /**
  * List all runs in a project.
+ *
+ * B01: this used to `continue` past a directory with no readable
+ * manifest.json with zero signal — the exact shape a crashed/killed run
+ * leaves behind (see checkpointRunManifest() above). A run that ate 90
+ * minutes of GPU time before dying became invisible: no id, no `run show`,
+ * no resume, and no indication anything was ever skipped. Skipped/unreadable
+ * directories are now reported: a one-line warn() with a count always
+ * (so a human running `sdlab run list` cannot miss it), and the per-directory
+ * detail under --verbose.
  */
 export function listRuns(projectRoot) {
   const runsDir = getRunsDir(projectRoot);
@@ -195,9 +222,13 @@ export function listRuns(projectRoot) {
     .sort((a, b) => a.name.localeCompare(b.name));
 
   const runs = [];
+  const skipped = [];
   for (const entry of entries) {
     const manifestPath = join(runsDir, entry.name, 'manifest.json');
-    if (!existsSync(manifestPath)) continue;
+    if (!existsSync(manifestPath)) {
+      skipped.push({ name: entry.name, reason: 'no manifest.json' });
+      continue;
+    }
 
     try {
       const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
@@ -209,8 +240,18 @@ export function listRuns(projectRoot) {
         created_at: manifest.created_at,
         adapter_target: manifest.adapter_target,
       });
-    } catch {
-      // Skip malformed
+    } catch (err) {
+      skipped.push({ name: entry.name, reason: `unreadable manifest.json (${err.message})` });
+    }
+  }
+
+  if (skipped.length > 0) {
+    warn(
+      `listRuns: skipped ${skipped.length} run director${skipped.length === 1 ? 'y' : 'ies'} ` +
+      `with no readable manifest.json (run with --verbose for details)`
+    );
+    for (const s of skipped) {
+      verbose(`  skipped run dir "${s.name}": ${s.reason}`);
     }
   }
 

package/lib/snapshot.js

@@ -41,6 +41,96 @@ export function checkManifestVersion(manifest, kind) {
   }
 }
 
+/**
+ * SDL-M10: atomically claim a fresh, unused SUBDIRECTORY of `parentDir`.
+ *
+ * The pattern this replaces — `existsSync(dir)` then throw-if-true,
+ * followed later by `mkdir(dir, {recursive:true})` — is check-then-act: a
+ * second concurrent process can create the same directory in the window
+ * between the check and the mkdir, and recursive mkdir never throws on an
+ * already-existing directory, so the race is silently invisible (two
+ * builders interleave writes into one snapshot/split/export/etc. dir —
+ * Law 1 exposure: "snapshots frozen").
+ *
+ * Mirrors lib/selections.js's claimSelectionId: a non-recursive `mkdir`
+ * is atomic at the filesystem level (POSIX and Windows both guarantee
+ * this) — it either creates the directory and returns, or fails with
+ * EEXIST if something else claimed that exact name first. On EEXIST we
+ * regenerate a fresh id and retry; for the timestamp+random ids used
+ * throughout this module, two consecutive real collisions is already
+ * vanishingly unlikely.
+ *
+ * Creating `parentDir` itself (e.g. "snapshots/") is NOT part of the race
+ * being closed here — two processes racing to create the same shared
+ * parent with {recursive:true} is harmless (both succeed; no caller's
+ * data lives directly in the parent, only under their own distinctly
+ * named leaf directory).
+ *
+ * @param {string} parentDir — parent directory, created recursively if missing
+ * @param {() => string} generateId — produces a candidate leaf id; called
+ *   again on every retry so concurrent claimants converge on different ids
+ * @param {{code: string, message: string, hint: string, maxAttempts?: number}} onExhausted
+ *   — error identity thrown if every attempt collides (kept caller-specific
+ *   so existing codes like SNAPSHOT_ID_COLLISION stay externally stable)
+ * @returns {Promise<{id: string, dir: string}>}
+ */
+export async function claimIdDir(parentDir, generateId, onExhausted) {
+  const maxAttempts = onExhausted.maxAttempts ?? 25;
+  if (!existsSync(parentDir)) {
+    await mkdir(parentDir, { recursive: true });
+  }
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const id = generateId();
+    const dir = join(parentDir, id);
+    try {
+      await mkdir(dir); // non-recursive — throws EEXIST if already claimed
+      return { id, dir };
+    } catch (err) {
+      if (err.code === 'EEXIST') continue;
+      throw err;
+    }
+  }
+  throw inputError(onExhausted.code, onExhausted.message, onExhausted.hint);
+}
+
+/**
+ * SDL-M10: atomically claim a fresh, unused FILE `<parentDir>/<id>.json`.
+ *
+ * Same TOCTOU problem as claimIdDir, but for the one artifact in this
+ * domain stored as a flat file rather than a directory (training
+ * manifests: `training/manifests/<id>.json`). The atomic primitive here
+ * is `writeFile(..., {flag: 'wx'})` — exclusive create, which fails with
+ * EEXIST rather than silently overwriting — so claim-and-write happen in
+ * one step instead of racing a separate existsSync check against it.
+ *
+ * @param {string} parentDir — parent directory, created recursively if missing
+ * @param {() => string} generateId — produces a candidate id; called again
+ *   on every retry
+ * @param {(id: string) => string} buildContent — renders the file content
+ *   for a given candidate id (called fresh per attempt since the content
+ *   embeds the id)
+ * @param {{code: string, message: string, hint: string, maxAttempts?: number}} onExhausted
+ * @returns {Promise<{id: string, filePath: string}>}
+ */
+export async function claimIdFile(parentDir, generateId, buildContent, onExhausted) {
+  const maxAttempts = onExhausted.maxAttempts ?? 25;
+  if (!existsSync(parentDir)) {
+    await mkdir(parentDir, { recursive: true });
+  }
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const id = generateId();
+    const filePath = join(parentDir, `${id}.json`);
+    try {
+      await writeFile(filePath, buildContent(id), { flag: 'wx' }); // exclusive create — atomic
+      return { id, filePath };
+    } catch (err) {
+      if (err.code === 'EEXIST') continue;
+      throw err;
+    }
+  }
+  throw inputError(onExhausted.code, onExhausted.message, onExhausted.hint);
+}
+
 /**
  * Derive which rule names were evaluated against a record for a given profile.
  * Mirrors the order of checks in evaluateEligibility() so the trace is stable.
@@ -101,18 +191,6 @@ export function computeConfigFingerprint(projectRoot) {
 export async function createSnapshot(projectRoot, profile, options = {}) {
   const config = loadProjectConfig(projectRoot);
   const recordsDir = join(projectRoot, 'records');
-  const snapshotId = generateSnapshotId();
-  const snapshotDir = join(projectRoot, 'snapshots', snapshotId);
-
-  // D-005: refuse to proceed if the generated ID has collided with an existing
-  // snapshot dir — silent overwrite would break Law 1 (snapshots are frozen).
-  if (!options.dryRun && existsSync(snapshotDir)) {
-    throw inputError(
-      'SNAPSHOT_ID_COLLISION',
-      `Snapshot directory already exists: ${snapshotDir}`,
-      'Retry to generate a fresh snapshot ID.',
-    );
-  }
 
   const configFingerprint = computeConfigFingerprint(projectRoot);
   const profileId = profile.profile_id || profile.id || 'unknown';
@@ -147,7 +225,7 @@ export async function createSnapshot(projectRoot, profile, options = {}) {
       continue;
     }
 
-    const { eligible, reasons } = evaluateEligibility(
+    const { eligible, reasons, reason_codes: reasonCodes } = evaluateEligibility(
       record, profile, config.lanes, config.terminology
     );
 
@@ -181,7 +259,13 @@ export async function createSnapshot(projectRoot, profile, options = {}) {
         }
       }
     } else {
-      excluded.push({ record_id: record.id, reasons });
+      // F5: forward the stable reason_codes alongside the human-readable
+      // reasons — purely additive on excluded.jsonl's on-disk shape (one
+      // new key), so old readers/old files that only expect
+      // {record_id, reasons} are unaffected. Lets categorizeExclusions
+      // (lib/eligibility.js) categorize this snapshot's exclusions by
+      // code instead of prose-matching `reasons`.
+      excluded.push({ record_id: record.id, reasons, reason_codes: reasonCodes });
     }
   }
 
@@ -197,9 +281,24 @@ export async function createSnapshot(projectRoot, profile, options = {}) {
 
   // Write snapshot files (skip if dry run)
   if (options.dryRun) {
+    // Dry run never touches disk, so there is nothing to atomically claim —
+    // a fresh preview id is enough to characterize the shape of the result.
+    const snapshotId = generateSnapshotId();
     return { snapshotId, included: included.length, excluded: excluded.length, unreadable: unreadable.length };
   }
-  await mkdir(snapshotDir, { recursive: true });
+
+  // SDL-M10: atomically claim the snapshot id/dir — closes the
+  // check-then-act race the old existsSync+recursive-mkdir pattern had
+  // (D-005's intent, now actually race-proof; see claimIdDir above).
+  const { id: snapshotId, dir: snapshotDir } = await claimIdDir(
+    join(projectRoot, 'snapshots'),
+    generateSnapshotId,
+    {
+      code: 'SNAPSHOT_ID_COLLISION',
+      message: 'Could not claim a unique snapshot ID — every candidate collided with an existing snapshot directory.',
+      hint: 'Retry; if this persists, another sdlab process may be creating snapshots in a tight loop.',
+    },
+  );
 
   const manifest = {
     // DB-001 / DB-006: stamp manifest schema version (reader checks on load)