@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/train-runs.js

@@ -0,0 +1,214 @@
+/**
+ * Trained-LoRA provenance record (`train-run.json`) contract (DESIGN-v3 §7, G13).
+ *
+ * Links every trained LoRA checkpoint back to:
+ *   - dataset_package_id + dataset_manifest_sha256
+ *   - config_sha256 (ai-toolkit-config.yaml)
+ *   - override_file + override_sha256 + upstream_issue (#1087)
+ *   - base_model pin with cleared Apache-2.0 SPDX licence
+ *   - window_id
+ *   - steps, checkpoint_sha256s, sample_grid_sha256s
+ *   - eval_pack_sha (attached once the eval pack runs)
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  AI_TOOLKIT_UPSTREAM_ISSUE,
+  assertNotHeldTrainingData,
+  getAiToolkitOverrideMetadata,
+} from './adapters/ai-toolkit.js';
+import { inputError as rawInputError } from './errors.js';
+
+function inputError(code, msg) {
+  return rawInputError(code, `${code}: ${msg}`);
+}
+
+export const CLEARED_TRAIN_BASE_LICENCES = new Set([
+  'Apache-2.0',
+  'MIT',
+  'BSD-2-Clause',
+  'BSD-3-Clause',
+  'CC0-1.0',
+  'CC-BY-4.0',
+]);
+
+function normalizeSha256(val) {
+  if (typeof val !== 'string') return null;
+  const trimmed = val.trim().toLowerCase();
+  const hex = trimmed.startsWith('sha256:') ? trimmed.slice(7) : trimmed;
+  if (!/^[0-9a-f]{64}$/.test(hex)) return null;
+  return `sha256:${hex}`;
+}
+
+/**
+ * Build and validate a `train-run.json` record (§7, G13).
+ *
+ * @param {Object} opts
+ * @returns {Object}
+ */
+export function buildTrainRunRecord(opts = {}) {
+  const {
+    run_id,
+    window_id,
+    dataset_package_id,
+    dataset_manifest_sha256,
+    config_sha256,
+    override_file,
+    override_sha256,
+    upstream_issue = AI_TOOLKIT_UPSTREAM_ISSUE,
+    base_model,
+    steps = [],
+    checkpoint_sha256s = {},
+    sample_grid_sha256s = {},
+    eval_pack_sha = null,
+    created_at = new Date().toISOString(),
+  } = opts;
+
+  if (!run_id || typeof run_id !== 'string') {
+    throw inputError('TRAIN_RUN_INVALID', 'train-run.json requires a non-empty "run_id".');
+  }
+  if (!window_id || typeof window_id !== 'string') {
+    throw inputError('TRAIN_RUN_INVALID', 'train-run.json requires a non-empty "window_id".');
+  }
+  if (!dataset_package_id || typeof dataset_package_id !== 'string') {
+    throw inputError('TRAIN_RUN_INVALID', 'train-run.json requires a non-empty "dataset_package_id".');
+  }
+
+  assertNotHeldTrainingData({
+    profile: { profile_id: dataset_package_id },
+    manifest: { source_export_id: run_id },
+  });
+
+  const normDatasetSha = normalizeSha256(dataset_manifest_sha256);
+  const normConfigSha = normalizeSha256(config_sha256);
+  const defaultOverride = getAiToolkitOverrideMetadata();
+  const normOverrideSha = normalizeSha256(override_sha256 || defaultOverride.override_sha256);
+
+  if (!normDatasetSha || !normConfigSha || !normOverrideSha) {
+    throw inputError(
+      'TRAIN_RUN_SHA_INVALID',
+      'train-run.json requires valid 64-hex dataset_manifest_sha256, config_sha256, and override_sha256.'
+    );
+  }
+
+  if (!base_model || typeof base_model !== 'object' || !base_model.name) {
+    throw inputError('TRAIN_RUN_BASE_MODEL_INVALID', 'train-run.json requires a base_model object with name.');
+  }
+  const normBaseSha = normalizeSha256(base_model.sha256);
+  if (!normBaseSha) {
+    throw inputError('TRAIN_RUN_SHA_INVALID', 'base_model.sha256 must be a valid 64-hex sha256 digest.');
+  }
+  if (
+    !base_model.licence_id ||
+    !CLEARED_TRAIN_BASE_LICENCES.has(base_model.licence_id) ||
+    !base_model.licence_url ||
+    !base_model.date_read
+  ) {
+    throw inputError(
+      'TRAIN_RUN_LICENCE_INVALID',
+      `base_model "${base_model.name}" must carry a cleared commercial SPDX licence_id (${[...CLEARED_TRAIN_BASE_LICENCES].join(', ')}), licence_url, and date_read (got "${base_model.licence_id}").`
+    );
+  }
+
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw inputError('TRAIN_RUN_STEPS_EMPTY', 'train-run.json requires at least one checkpoint step.');
+  }
+
+  const normalizedCheckpoints = {};
+  const normalizedSamples = {};
+  for (const step of steps) {
+    const key = String(step);
+    const ckptSha = normalizeSha256(checkpoint_sha256s[key] ?? checkpoint_sha256s[step]);
+    if (!ckptSha) {
+      throw inputError(
+        'TRAIN_RUN_SHA_INVALID',
+        `Missing or invalid checkpoint_sha256 for step ${key}.`
+      );
+    }
+    normalizedCheckpoints[key] = ckptSha;
+
+    const gridRaw = sample_grid_sha256s[key] ?? sample_grid_sha256s[step];
+    if (gridRaw !== undefined && gridRaw !== null) {
+      const gridSha = normalizeSha256(gridRaw);
+      if (!gridSha) {
+        throw inputError(
+          'TRAIN_RUN_SHA_INVALID',
+          `Invalid sample_grid_sha256 for step ${key}.`
+        );
+      }
+      normalizedSamples[key] = gridSha;
+    }
+  }
+
+  const normEvalSha = eval_pack_sha ? normalizeSha256(eval_pack_sha) : null;
+  if (eval_pack_sha && !normEvalSha) {
+    throw inputError('TRAIN_RUN_SHA_INVALID', 'eval_pack_sha must be null or a valid 64-hex sha256 digest.');
+  }
+
+  return {
+    run_id,
+    window_id,
+    lane: 'train',
+    dataset_package_id,
+    dataset_manifest_sha256: normDatasetSha,
+    config_sha256: normConfigSha,
+    override_file: override_file || defaultOverride.override_file,
+    override_sha256: normOverrideSha,
+    upstream_issue,
+    base_model: {
+      name: base_model.name,
+      repo: base_model.repo || base_model.name,
+      revision: base_model.revision || 'main',
+      sha256: normBaseSha,
+      licence_id: base_model.licence_id,
+      licence_url: base_model.licence_url,
+      date_read: base_model.date_read,
+    },
+    steps: steps.map(Number),
+    checkpoint_sha256s: normalizedCheckpoints,
+    sample_grid_sha256s: normalizedSamples,
+    eval_pack_sha: normEvalSha,
+    created_at,
+  };
+}
+
+/**
+ * Write `train-run.json` to disk.
+ *
+ * @param {string} trainRunPath
+ * @param {Object} record
+ * @returns {Object}
+ */
+export function writeTrainRunJson(trainRunPath, record) {
+  const validated = buildTrainRunRecord(record);
+  mkdirSync(dirname(trainRunPath), { recursive: true });
+  writeFileSync(trainRunPath, JSON.stringify(validated, null, 2) + '\n', 'utf-8');
+  return validated;
+}
+
+/**
+ * Read and validate `train-run.json` from disk.
+ *
+ * @param {string} trainRunPath
+ * @returns {Object}
+ */
+export function readTrainRunJson(trainRunPath) {
+  const parsed = JSON.parse(readFileSync(trainRunPath, 'utf-8'));
+  return buildTrainRunRecord(parsed);
+}
+
+/**
+ * Attach `eval_pack_sha` to an existing `train-run.json` once the eval pack runs (G13).
+ *
+ * @param {string} trainRunPath
+ * @param {string} evalPackSha
+ * @returns {Object}
+ */
+export function attachEvalPackSha(trainRunPath, evalPackSha) {
+  const current = readTrainRunJson(trainRunPath);
+  return writeTrainRunJson(trainRunPath, {
+    ...current,
+    eval_pack_sha: evalPackSha,
+  });
+}

package/lib/training-manifests.js

@@ -6,15 +6,14 @@
  * so the training run is fully reproducible.
  */
 
-import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { readFile, writeFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { createHash, randomBytes } from 'node:crypto';
 import { loadExport } from './export.js';
 import { loadTrainingProfile } from './training-profiles.js';
-import { computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion, claimIdFile } from './snapshot.js';
 import { listEvalPacks } from './eval-pack.js';
-import { inputError } from './errors.js';
 
 /**
  * Generate a training manifest ID: tm-YYYYMMDD-HHMMSS-XXXX
@@ -34,6 +33,24 @@ async function hashFile(filePath) {
   return createHash('sha256').update(data).digest('hex');
 }
 
+/**
+ * SDL-H9: parse a BSD-style checksums.txt (`SHA256 (path) = hash` per
+ * line, as written by export.js and training-packages.js) into
+ * {relPath, hash} entries. Tolerates stray/blank lines rather than
+ * throwing, since this file is meant to be human-readable too.
+ */
+function parseChecksumsFile(text) {
+  const entries = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = /^SHA256 \((.+)\) = ([0-9a-fA-F]{64})$/.exec(trimmed);
+    if (!match) continue;
+    entries.push({ relPath: match[1], hash: match[2].toLowerCase() });
+  }
+  return entries;
+}
+
 /**
  * Create a training manifest from an export package and training profile.
  *
@@ -51,6 +68,17 @@ export async function createTrainingManifest(projectRoot, exportId, profileId, o
   const exportManifestPath = join(projectRoot, 'exports', exportId, 'manifest.json');
   const exportManifestHash = await hashFile(exportManifestPath);
 
+  // SDL-H9: export_manifest_hash above covers ONLY manifest.json — a file
+  // that does not include image bytes. checksums.txt (written by
+  // export.js after the manifest, D-015) covers every file in the export,
+  // including images, so bind to it too when present. `include_checksums`
+  // is a profile-controlled export option — an export built without it
+  // simply has nothing to bind here, which is not itself an error.
+  const exportChecksumsPath = join(projectRoot, 'exports', exportId, 'checksums.txt');
+  const exportChecksumsHash = existsSync(exportChecksumsPath)
+    ? await hashFile(exportChecksumsPath)
+    : null;
+
   // Determine adapter target
   const adapterTarget = options.adapterTarget || profile.adapter_targets[0];
   if (!profile.adapter_targets.includes(adapterTarget)) {
@@ -63,11 +91,14 @@ export async function createTrainingManifest(projectRoot, exportId, profileId, o
   const evalPacks = await listEvalPacks(projectRoot);
   const linkedEvalPackIds = evalPacks.map(p => p.id);
 
-  const manifestId = generateManifestId();
-  const manifest = {
+  // Deferred so the id can be plugged in per-attempt by claimIdFile below
+  // (a training manifest is a flat file, not a directory — see claimIdFile
+  // in snapshot.js for why the atomic primitive differs from the other
+  // artifacts in this domain).
+  const buildContent = (id) => JSON.stringify({
     // DB-001 / DB-006: stamp manifest schema version
     schema_version: SCHEMA_VERSION,
-    training_manifest_id: manifestId,
+    training_manifest_id: id,
     created_at: new Date().toISOString(),
     created_by: 'sdlab-training-manifest-v1',
     project_id: exportManifest.project,
@@ -77,6 +108,9 @@ export async function createTrainingManifest(projectRoot, exportId, profileId, o
     source_split_id: exportManifest.split_id,
     config_fingerprint: computeConfigFingerprint(projectRoot),
     export_manifest_hash: exportManifestHash,
+    // SDL-H9: the binding hash that actually covers image bytes. null
+    // when the source export was built with include_checksums: false.
+    export_checksums_hash: exportChecksumsHash,
     dataset_counts: exportManifest.counts,
     base_model: options.baseModel || profile.base_model_recommendations?.[0] || null,
     adapter_target: adapterTarget,
@@ -87,21 +121,21 @@ export async function createTrainingManifest(projectRoot, exportId, profileId, o
       target_family: profile.target_family,
     },
     linked_eval_pack_ids: linkedEvalPackIds,
-  };
+  }, null, 2) + '\n';
 
-  // Write manifest
-  const dir = join(projectRoot, 'training', 'manifests');
-  await mkdir(dir, { recursive: true });
-  const manifestPath = join(dir, `${manifestId}.json`);
-  // D-005: refuse to silently overwrite on ID collision.
-  if (existsSync(manifestPath)) {
-    throw inputError(
-      'TRAINING_MANIFEST_ID_COLLISION',
-      `Training manifest file already exists: ${manifestPath}`,
-      'Retry to generate a fresh manifest ID.',
-    );
-  }
-  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  // SDL-M10: atomically claim the manifest file — closes the
+  // check-then-act race the old existsSync+writeFile pattern had (D-005's
+  // intent, now actually race-proof).
+  const { id: manifestId } = await claimIdFile(
+    join(projectRoot, 'training', 'manifests'),
+    generateManifestId,
+    buildContent,
+    {
+      code: 'TRAINING_MANIFEST_ID_COLLISION',
+      message: 'Could not claim a unique training-manifest ID — every candidate collided with an existing manifest file.',
+      hint: 'Retry; if this persists, another sdlab process may be creating training manifests in a tight loop.',
+    },
+  );
 
   return { manifestId, exportId, profileId };
 }
@@ -121,13 +155,72 @@ export async function validateTrainingManifest(projectRoot, manifestId) {
   if (!existsSync(exportPath)) {
     issues.push(`source export "${manifest.source_export_id}" not found`);
   } else {
-    // Check export hash
+    // Check export hash — NOTE: manifest.json alone does not include image
+    // bytes (SDL-H9); see the checksums.txt re-verification below for the
+    // check that actually catches a replaced image.
     const currentHash = await hashFile(exportPath);
     if (currentHash !== manifest.export_manifest_hash) {
       issues.push(`export manifest hash mismatch — export may have been modified`);
     }
   }
 
+  // SDL-H9: export_manifest_hash (above) never covered image bytes —
+  // checksums.txt does. Re-verify it two ways:
+  //   1. binding check — checksums.txt's own hash still matches what was
+  //      captured at training-manifest creation time (only meaningful for
+  //      manifests created after SDL-H9, when export_checksums_hash was
+  //      first captured).
+  //   2. full re-verification — every individual file checksums.txt
+  //      records is re-hashed against its CURRENT on-disk content. This is
+  //      the check that actually catches "an image was silently replaced
+  //      after export": checksums.txt's own bytes don't change just
+  //      because a file it lists was overwritten, so step 1 alone cannot
+  //      see it. Runs whenever checksums.txt exists, independent of
+  //      whether this manifest predates export_checksums_hash, so it also
+  //      retroactively protects manifests created before this fix.
+  const exportChecksumsPath = join(projectRoot, 'exports', manifest.source_export_id, 'checksums.txt');
+  if (manifest.export_checksums_hash && !existsSync(exportChecksumsPath)) {
+    issues.push(`export checksums.txt not found at ${exportChecksumsPath} — export may have been modified (checksums.txt removed)`);
+  } else if (existsSync(exportChecksumsPath)) {
+    if (manifest.export_checksums_hash) {
+      const currentChecksumsHash = await hashFile(exportChecksumsPath);
+      if (currentChecksumsHash !== manifest.export_checksums_hash) {
+        issues.push(`export checksums.txt hash mismatch — the checksum manifest itself has changed since this training manifest was created`);
+      }
+    }
+
+    const exportDir = join(projectRoot, 'exports', manifest.source_export_id);
+    const checksumsText = await readFile(exportChecksumsPath, 'utf-8');
+    const entries = parseChecksumsFile(checksumsText);
+    const missing = [];
+    const mismatched = [];
+    for (const entry of entries) {
+      const filePath = join(exportDir, entry.relPath);
+      if (!existsSync(filePath)) {
+        missing.push(entry.relPath);
+        continue;
+      }
+      const currentFileHash = await hashFile(filePath);
+      if (currentFileHash !== entry.hash) {
+        mismatched.push(entry.relPath);
+      }
+    }
+    if (missing.length > 0) {
+      const sample = missing.slice(0, 5).join(', ');
+      issues.push(
+        `export file(s) referenced by checksums.txt are missing: ${sample}` +
+        (missing.length > 5 ? `, ... (${missing.length} total)` : ''),
+      );
+    }
+    if (mismatched.length > 0) {
+      const sample = mismatched.slice(0, 5).join(', ');
+      issues.push(
+        `export file(s) modified since export — content hash no longer matches checksums.txt: ${sample}` +
+        (mismatched.length > 5 ? `, ... (${mismatched.length} total)` : ''),
+      );
+    }
+  }
+
   // Check config fingerprint
   const currentFingerprint = computeConfigFingerprint(projectRoot);
   if (currentFingerprint !== manifest.config_fingerprint) {

package/lib/training-packages.js

@@ -6,19 +6,21 @@
  * but never mutate inclusion or split truth.
  */
 
-import { readFile, writeFile, mkdir, readdir, symlink, copyFile } from 'node:fs/promises';
+import { readFile, writeFile, readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { existsSync } from 'node:fs';
+import { platform } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
 import { loadTrainingManifest } from './training-manifests.js';
 import { loadTrainingProfile } from './training-profiles.js';
 import { loadSplitPartition } from './split.js';
 import { loadRecord } from './records.js';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
-import { inputError } from './errors.js';
-import { SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { inputError, SdlabError } from './errors.js';
+import { SCHEMA_VERSION, checkManifestVersion, claimIdDir } from './snapshot.js';
 import { loadAdapter } from './training-adapters.js';
 import { recordToRow, filterRowsForProfile } from './rows.js';
+import { assertSafeAssetPath, assertSafeId } from './export.js';
 
 /**
  * Generate a training package ID: tp-YYYYMMDD-HHMMSS-XXXX
@@ -51,16 +53,6 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
   const adapter = await loadAdapter(adapterTarget);
 
   const recordsDir = join(projectRoot, 'records');
-  const packageId = generatePackageId();
-  const packageDir = join(projectRoot, 'training', 'packages', packageId);
-  // D-005: refuse to silently overwrite on ID collision.
-  if (existsSync(packageDir)) {
-    throw inputError(
-      'TRAINING_PACKAGE_ID_COLLISION',
-      `Training package directory already exists: ${packageDir}`,
-      'Retry to generate a fresh package ID.',
-    );
-  }
 
   // Convert split partitions → canonical rows (D6 adapter input shape).
   // Adapters only understand rows — records-flow callers go through this
@@ -68,23 +60,90 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
   // contract, two producers.
   const rows = [];
   const partitionCounts = { train: 0, val: 0, test: 0 };
+  // F3: same contract as export.js's identical guard — a record the split
+  // promised (via source_split_id's train/val/test.jsonl) whose file was
+  // later deleted from records/ must never silently shrink the training
+  // package below what the split counted. loadRecord() returns null on
+  // ENOENT; previously that was a silent `continue` with no counter, no
+  // warning, no id recorded. Accumulated across all three partitions so
+  // one thrown error names every missing id instead of discovering them
+  // one rebuild at a time.
+  const missingRecords = [];
+  // H3: recordToRow() can throw CAPTION_SUBJECT_MISSING (lib/captions.js's
+  // buildSubjectNaturalLanguageCaption) per-record. That throw is correct —
+  // the granularity of handling it here was not: a bare loop with no
+  // try/catch meant the FIRST offending record aborted the whole build,
+  // before claimIdDir (below) ever reserved a package id, so a 400-record
+  // build died having written nothing, named exactly one offender, and had
+  // to be rerun in full for each subsequent one. Mirrors the aggregation
+  // pattern lib/canon-build/build.js already uses for contextLimitFailures:
+  // collect across the WHOLE loop, throw one summary naming every offender.
+  const captionFailures = [];
 
   for (const partition of ['train', 'val', 'test']) {
     const entries = await loadSplitPartition(projectRoot, manifest.source_split_id, partition);
 
     for (const entry of entries) {
       const record = await loadRecord(recordsDir, entry.record_id);
-      if (!record) continue;
+      if (!record) {
+        missingRecords.push({ record_id: entry.record_id, stage: 'training-package', partition });
+        continue;
+      }
 
       const prompt = record.provenance?.prompt || '';
       const lane = detectLane(record.id, prompt, config.lanes);
       const group = detectGroup(record.id, prompt, config.terminology);
 
-      const row = recordToRow(record, lane, group, profile, partition);
+      let row;
+      try {
+        row = recordToRow(record, lane, group, profile, partition);
+      } catch (err) {
+        // Only batch STRUCTURED/expected failures (SdlabError) — an
+        // unexpected bug should still crash loud with its real stack
+        // instead of being swallowed into a friendly summary.
+        if (!(err instanceof SdlabError)) throw err;
+        captionFailures.push({ record_id: entry.record_id, partition, message: err.message });
+        continue;
+      }
       if (row) rows.push(row);
     }
   }
 
+  // F3: hard-fail — training packages sit on the same Law 4 ("exports are
+  // reproducible") contract export.js does, one layer further downstream;
+  // see export.js's EXPORT_MISSING_RECORDS guard for the full rationale on
+  // why this escalates to a thrown error rather than the warn()-and-ledger
+  // pattern used in split.js / implementation-packs.js. Checked before the
+  // Windows symlink guard, row-safety validation, and claimIdDir below, so
+  // a doomed build never reserves a package id or touches the filesystem.
+  if (missingRecords.length > 0) {
+    const sample = missingRecords.slice(0, 10).map(m => `${m.record_id} (${m.partition})`);
+    throw inputError(
+      'TRAINING_PACKAGE_MISSING_RECORDS',
+      `${missingRecords.length} record(s) referenced by split "${manifest.source_split_id}" could not be loaded from ${recordsDir} — this training package would silently contain fewer rows than the split promised.` +
+      (missingRecords.length > 10
+        ? ` First 10: ${sample.join(', ')}, ...`
+        : ` Missing: ${sample.join(', ')}.`),
+      'Record file(s) were likely deleted after the split was created. Restore the missing file(s), or create a fresh snapshot/split reflecting current on-disk records before building a training package.',
+    );
+  }
+
+  // H3: aggregated caption-failure report — see the captionFailures
+  // declaration above. Checked alongside missingRecords, before claimIdDir,
+  // so this also never reserves a package id or touches the filesystem.
+  if (captionFailures.length > 0) {
+    const sample = captionFailures.slice(0, 10).map(f => `${f.record_id} (${f.partition}): ${f.message}`);
+    throw inputError(
+      'TRAINING_PACKAGE_CAPTION_FAILURES',
+      `${captionFailures.length} record(s) failed to caption while building this training package.\n` +
+      sample.join('\n') +
+      (captionFailures.length > 10 ? `\n...and ${captionFailures.length - 10} more.` : ''),
+      'Fix the offending record(s) — commonly: populate canon.subject on records using caption_strategy ' +
+      '"subject-natural-language" — then retry. Every failure is listed above so this can be fixed in one ' +
+      'pass instead of one rerun per offender.',
+    );
+  }
+
   // Apply profile filters (eligible_lanes + entity_id_scope — D8).
   // filterRowsForProfile returns rows where lane ∈ eligible_lanes AND
   // entity_id === entity_id_scope (when set). Zero filters = identity.
@@ -95,6 +154,54 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
   const totalRecords = filteredRows.length;
   let totalImages = 0;
 
+  // SDL-C5: mirror export.js's D-008 Windows guard. Symlink mode on
+  // Windows without admin/Developer Mode fails on every single row
+  // (EPERM) — unguarded, that meant imageCount stayed 0, every
+  // metadata/<partition>.jsonl came out empty, and the command still
+  // exited 0 printing "Images: 0". Refuse upfront instead of limping
+  // through an all-rows-fail package that LOOKS like success.
+  if (!options.copy && platform() === 'win32' && filteredRows.length > 0) {
+    throw inputError(
+      'SYMLINK_UNSUPPORTED_WINDOWS',
+      'Symlink mode is not supported on Windows training-package builds (target semantics differ and break on archive/transfer).',
+      'Re-run with --copy to produce a portable, self-contained training package.',
+    );
+  }
+
+  // SDL-H5 / SDL-H6: validate every row BEFORE any adapter touches the
+  // filesystem. export.js already guards asset_path against traversal
+  // (D-007) and now guards the id that becomes the destination filename
+  // (SDL-H5); this ports the exact same checks (same error codes) to the
+  // training-package path, which previously only checked existsSync — a
+  // traversal path satisfies existsSync just as well as a legitimate one.
+  // Centralized here once, per the finding's own suggestion, rather than
+  // duplicated per-adapter — though each adapter ALSO carries the same
+  // guard directly (see lib/adapters/*.js) as defense-in-depth for a
+  // caller that invokes adapter.buildPackage without going through this
+  // function (e.g. the adapters' own unit tests, or a future canon-build
+  // caller — see lib/rows.js's documented second row producer).
+  for (const row of filteredRows) {
+    assertSafeId(row.entity_id, `row.entity_id for training package (asset_path "${row.asset_path}")`);
+    assertSafeAssetPath(row.asset_path, projectRoot, row.entity_id);
+  }
+
+  // SDL-M10: atomically claim the training-package 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 in
+  // snapshot.js). Deferred to here (rather than claimed at the top of the
+  // function) since nothing above this point actually needs packageId —
+  // no point reserving one before the Windows guard / row validation have
+  // had a chance to reject the build outright.
+  const { id: packageId, dir: packageDir } = await claimIdDir(
+    join(projectRoot, 'training', 'packages'),
+    generatePackageId,
+    {
+      code: 'TRAINING_PACKAGE_ID_COLLISION',
+      message: 'Could not claim a unique training-package ID — every candidate collided with an existing package directory.',
+      hint: 'Retry; if this persists, another sdlab process may be creating training packages in a tight loop.',
+    },
+  );
+
   // Let the adapter build the package layout from the canonical rows.
   const adapterResult = await adapter.buildPackage({
     packageDir,
@@ -107,6 +214,22 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
   });
 
   totalImages = adapterResult.imageCount || 0;
+  // SDL-C5: DB-002-style accounting, ported from export.js — a caught
+  // per-row copy/symlink failure must be visible, not silently dropped
+  // alongside its metadata row and caption sidecar via a bare
+  // `catch { continue; }`. The adapter itself already emitted a warn()
+  // (it has the precise per-row context); this builds the PERSISTED
+  // record on the package manifest so the failure survives after the
+  // terminal scrolls, without re-printing the same stderr line twice.
+  const imagesFailed = adapterResult.imagesFailed || [];
+  const warnings = [];
+  if (imagesFailed.length > 0) {
+    const sample = imagesFailed.slice(0, 10).map(f => `${f.record_id} (${f.reason})`);
+    const msg =
+      `training-package: ${imagesFailed.length} of ${filteredRows.length} rows failed to place` +
+      (imagesFailed.length > 10 ? ` — first 10: ${sample.join(', ')}, ...` : ` — ${sample.join(', ')}`);
+    warnings.push(msg);
+  }
 
   // D-015: Write manifest + README FIRST so they are covered by checksums.
   const packageManifest = {
@@ -122,14 +245,23 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
     source_snapshot_id: manifest.source_snapshot_id,
     source_split_id: manifest.source_split_id,
     config_fingerprint: manifest.config_fingerprint,
+    warnings,
     counts: {
       total_records: totalRecords,
       train: partitionCounts.train,
       val: partitionCounts.val,
       test: partitionCounts.test,
       images: totalImages,
+      // SDL-C5: expected/actual/failed breakdown (export.js DB-002 shape)
+      // so a partially- or totally-failed placement is visible in the
+      // manifest, not just inferable from a suspiciously-low `images`.
+      images_expected: filteredRows.length,
+      images_actual: totalImages,
+      images_failed: imagesFailed.length,
       checksums: 0, // updated after checksum pass below
     },
+    // SDL-C5: record-level failure detail for operator triage.
+    images_failed: imagesFailed,
   };
   await writeFile(join(packageDir, 'manifest.json'), JSON.stringify(packageManifest, null, 2) + '\n');
 

package/lib/verifier.js

@@ -13,6 +13,9 @@
  */
 
 import { warn } from './log.js';
+import { assertNoSelfVerification } from './canon-review-gate.js';
+
+export { assertNoSelfVerification };
 
 /** The rule-based critique engine's judge id. Bump vN when the rule set changes. */
 export const RULE_BASED_JUDGE = 'rule-based:sdlab-critique-v1';