@mcptoolshop/style-dataset-lab 3.0.0 → 3.0.1

package/lib/runtime-runs.js

@@ -5,17 +5,23 @@
  * The run folder IS the review surface — humans open it directly.
  */
 
-import { readFile, writeFile, mkdir, readdir, copyFile } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir, copyFile, rename, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 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';
 
 // ─── Run ID generation ───────────────────────────────────────────
 
 /**
  * Generate a run ID: run_YYYY-MM-DD_NNN
  */
+// PB-008: tighten regex so stray directories like 'run_<date>_001_wip'
+// don't inflate the sequence via parseInt's lenient parsing.
+const RUN_SEQ_RE = /^(\d{3})$/;
+
 export function generateRunId(runsDir) {
   const today = new Date().toISOString().slice(0, 10);
   const prefix = `run_${today}_`;
@@ -26,8 +32,10 @@ export function generateRunId(runsDir) {
       .filter(e => e.isDirectory() && e.name.startsWith(prefix));
     for (const e of existing) {
       const seqStr = e.name.slice(prefix.length);
-      const seq = parseInt(seqStr, 10);
-      if (!isNaN(seq) && seq > maxSeq) maxSeq = seq;
+      const match = RUN_SEQ_RE.exec(seqStr);
+      if (!match) continue;
+      const seq = parseInt(match[1], 10);
+      if (seq > maxSeq) maxSeq = seq;
     }
   }
 
@@ -46,7 +54,7 @@ export function generateRunId(runsDir) {
  * @returns {{ base_seed: number, seeds: number[] }}
  */
 export function buildSeedPlan({ seedMode, outputCount, baseSeed }) {
-  const base = baseSeed ?? Math.floor(Math.random() * 2_147_483_647);
+  const base = baseSeed ?? randomInt(2_147_483_647);
   const seeds = [];
 
   switch (seedMode) {
@@ -59,7 +67,7 @@ export function buildSeedPlan({ seedMode, outputCount, baseSeed }) {
     case 'random':
       seeds.push(base);
       for (let i = 1; i < outputCount; i++) {
-        seeds.push(Math.floor(Math.random() * 2_147_483_647));
+        seeds.push(randomInt(2_147_483_647));
       }
       break;
     default:
@@ -103,14 +111,56 @@ export async function prepareRunDir(projectRoot, brief) {
 
 // ─── Manifest ────────────────────────────────────────────────────
 
+/**
+ * Atomic write: write to a temp file in the same directory, then rename.
+ * Rename is atomic on the same filesystem, so a crash mid-write can never
+ * leave a half-written manifest in place of a good one.
+ *
+ * PB-002 / PB-005: callers may invoke this after each slot/candidate to
+ * produce incremental checkpoints.
+ */
+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) {
+    // Best-effort cleanup of the temp file on failure.
+    try { await unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
 /**
  * Build and save a run manifest.
+ *
+ * PB-002: uses atomic write (temp + rename) so a crash mid-write cannot
+ * corrupt an existing manifest. Safe to call repeatedly for incremental
+ * checkpointing after each output completes.
  */
 export async function saveRunManifest(runDir, manifest) {
-  await writeFile(
-    join(runDir, 'manifest.json'),
-    JSON.stringify(manifest, null, 2) + '\n'
-  );
+  const target = join(runDir, 'manifest.json');
+  await atomicWriteJson(target, manifest);
+  verbose(`saveRunManifest: wrote ${target}`);
+}
+
+/**
+ * Incremental checkpoint — same shape as saveRunManifest but stamps
+ * `incremental: true` and `last_checkpoint_at` so a human reading a
+ * partial manifest knows the run is in progress.
+ *
+ * PB-002: call after each completed output in long-running loops so a
+ * crash/interruption leaves a partial record instead of an orphan dir.
+ */
+export async function checkpointRunManifest(runDir, manifest) {
+  const snapshot = {
+    ...manifest,
+    incremental: true,
+    last_checkpoint_at: new Date().toISOString(),
+  };
+  await atomicWriteJson(join(runDir, 'manifest.json'), snapshot);
+  verbose(`checkpointRunManifest: ${manifest.run_id} (${manifest.outputs?.length ?? 0} outputs)`);
 }
 
 // ─── Load / List ─────────────────────────────────────────────────

package/lib/selections.js

@@ -14,12 +14,30 @@ import { getRunsDir } from './paths.js';
 import { getBatchesDir } from './batch-runs.js';
 import { inputError } from './errors.js';
 
+// ─── Filename validation ─────────────────────────────────────────
+
+const SAFE_FILENAME_RE = /^[A-Za-z0-9._-]+\.(png|webp|jpg|jpeg)$/i;
+
+function assertSafeFilename(filename, context) {
+  if (typeof filename !== 'string' || !SAFE_FILENAME_RE.test(filename)) {
+    throw inputError(
+      'UNSAFE_FILENAME',
+      `Invalid filename "${filename}" in ${context}`,
+      `Filenames must match letters/digits/dot/underscore/hyphen and end in .png/.webp/.jpg/.jpeg`,
+    );
+  }
+}
+
 // ─── Selection ID generation ─────────────────────────────────────
 
 export function getSelectionsDir(projectRoot) {
   return join(projectRoot, 'selections');
 }
 
+// PB-008: tighten regex so partial matches (e.g. 'selection_<date>_001_wip')
+// don't inflate the sequence. We require exactly 3 digits.
+const SELECTION_SEQ_RE = /^(\d{3})$/;
+
 export function generateSelectionId(selectionsDir) {
   const today = new Date().toISOString().slice(0, 10);
   const prefix = `selection_${today}_`;
@@ -30,14 +48,46 @@ export function generateSelectionId(selectionsDir) {
       .filter(e => e.isDirectory() && e.name.startsWith(prefix));
     for (const e of existing) {
       const seqStr = e.name.slice(prefix.length);
-      const seq = parseInt(seqStr, 10);
-      if (!isNaN(seq) && seq > maxSeq) maxSeq = seq;
+      const match = SELECTION_SEQ_RE.exec(seqStr);
+      if (!match) continue;
+      const seq = parseInt(match[1], 10);
+      if (seq > maxSeq) maxSeq = seq;
     }
   }
 
   return `${prefix}${String(maxSeq + 1).padStart(3, '0')}`;
 }
 
+/**
+ * PB-008: atomically claim the next selection ID by mkdir retry-on-EEXIST.
+ * Races safely against a concurrent sdlab process — each one will land on
+ * a unique sequence. Returns { selectionId, selectionDir }.
+ *
+ * Callers that already create the directory themselves can keep using
+ * generateSelectionId; the atomic path is opt-in.
+ */
+export async function claimSelectionId(selectionsDir) {
+  if (!existsSync(selectionsDir)) {
+    mkdirSync(selectionsDir, { recursive: true });
+  }
+  for (let attempt = 0; attempt < 25; attempt++) {
+    const candidate = generateSelectionId(selectionsDir);
+    const dir = join(selectionsDir, candidate);
+    try {
+      mkdirSync(dir); // throws EEXIST if a concurrent process already claimed it
+      return { selectionId: candidate, selectionDir: dir };
+    } catch (err) {
+      if (err.code === 'EEXIST') continue;
+      throw err;
+    }
+  }
+  throw inputError(
+    'SELECTION_ID_CLAIM_FAILED',
+    'Could not claim a unique selection ID after 25 attempts',
+    'Another sdlab process may be writing selections in a tight loop. Try again.'
+  );
+}
+
 // ─── Run selection ───────────────────────────────────────────────
 
 /**
@@ -68,6 +118,7 @@ export async function createSelectionFromRun({
 
   // Validate all approved files exist
   for (const file of approvedFiles) {
+    assertSafeFilename(file, `approvedFiles for run ${runId}`);
     if (!existsSync(join(outputsDir, file))) {
       throw inputError(
         'OUTPUT_NOT_FOUND',
@@ -162,6 +213,7 @@ export async function createSelectionFromBatch({
   // Validate each approved slot
   const runManifests = new Map();
   for (const { slotId, filename } of approvedSlots) {
+    assertSafeFilename(filename, `approvedSlots for batch ${batchId}`);
     const slot = slotRunMap.get(slotId);
     if (!slot) {
       throw inputError(

package/lib/snapshot.js

@@ -11,6 +11,45 @@ import { join } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
 import { loadProjectConfig, loadSelectionProfile, detectLane, detectGroup } from './config.js';
 import { evaluateEligibility } from './eligibility.js';
+import { inputError } from './errors.js';
+import { warn } from './log.js';
+
+/**
+ * DB-001 / DB-006: Manifest schema version. Every manifest.json written by
+ * snapshot/split/export/eval-pack/eval-run/training-manifest/training-package/
+ * impl-pack stamps this version; readers log a WARNING on version mismatch
+ * (best-effort compatibility).
+ */
+export const SCHEMA_VERSION = '2.2.0';
+
+/**
+ * Warn if a loaded manifest's schema_version does not match the reader.
+ * Non-fatal — continues with best-effort compatibility. No warning when
+ * manifest is missing the field (legacy unstamped artifacts).
+ */
+export function checkManifestVersion(manifest, kind) {
+  if (manifest?.schema_version && manifest.schema_version !== SCHEMA_VERSION) {
+    warn(
+      `${kind} schema v${manifest.schema_version} loaded by v${SCHEMA_VERSION} reader — continuing with best-effort compatibility`,
+    );
+  }
+}
+
+/**
+ * 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.
+ */
+function rulesCheckedForProfile(profile) {
+  const rules = [];
+  if (profile.require_judgment) rules.push('require_judgment');
+  if (profile.require_status?.length > 0) rules.push('require_status');
+  if (profile.require_canon_bound) rules.push('require_canon_bound');
+  if (profile.minimum_pass_ratio != null) rules.push('minimum_pass_ratio');
+  if (profile.exclude_lanes?.length > 0) rules.push('exclude_lanes');
+  if (profile.rights_filter != null) rules.push('rights_filter');
+  if (profile.exclude_tags?.length > 0) rules.push('exclude_tags');
+  return rules;
+}
 
 /**
  * Generate a snapshot ID: snap-YYYYMMDD-HHMMSS-XXXX
@@ -59,6 +98,20 @@ export async function createSnapshot(projectRoot, profile, options = {}) {
   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';
+  const rulesChecked = rulesCheckedForProfile(profile);
+
   // Load all records (sorted for deterministic output)
   const files = (await readdir(recordsDir))
     .filter(f => f.endsWith('.json'))
@@ -66,13 +119,27 @@ export async function createSnapshot(projectRoot, profile, options = {}) {
 
   const included = [];
   const excluded = [];
+  const unreadable = []; // DB-003: collect per-record parse errors, continue
   const laneDistribution = {};
   const factionDistribution = {};
   const verdictDistribution = { pass: 0, fail: 0, partial: 0 };
 
   for (const file of files) {
-    const raw = await readFile(join(recordsDir, file), 'utf-8');
-    const record = JSON.parse(raw);
+    // DB-003: wrap per-record JSON.parse in try/catch so one bad file does
+    // not abort the entire snapshot. The operator sees an `unreadable` list
+    // in the manifest + a WARNING count on stderr.
+    let record;
+    try {
+      const raw = await readFile(join(recordsDir, file), 'utf-8');
+      record = JSON.parse(raw);
+    } catch (err) {
+      unreadable.push({
+        record_id: file.replace(/\.json$/, ''),
+        file,
+        error: err.message,
+      });
+      continue;
+    }
 
     const { eligible, reasons } = evaluateEligibility(
       record, profile, config.lanes, config.terminology
@@ -89,7 +156,15 @@ export async function createSnapshot(projectRoot, profile, options = {}) {
         : 'n/a';
       const reason = `${record.judgment.status}, canon-bound, pass_ratio=${passRatio}, lane=${lane}`;
 
-      included.push({ record_id: record.id, reason });
+      // D-006: record the rule-trace + profile context so inclusion is
+      // replayable without re-running evaluateEligibility.
+      included.push({
+        record_id: record.id,
+        reason,
+        rules_checked: rulesChecked,
+        profile_id: profileId,
+        config_fingerprint: configFingerprint,
+      });
 
       // Track distributions
       laneDistribution[lane] = (laneDistribution[lane] || 0) + 1;
@@ -104,30 +179,46 @@ export async function createSnapshot(projectRoot, profile, options = {}) {
     }
   }
 
+  // DB-003: surface unreadable records loudly so partial parse failures
+  // are not silent. Manifest also carries the full list for drill-down.
+  if (unreadable.length > 0) {
+    const sample = unreadable.slice(0, 5).map(u => u.file).join(', ');
+    warn(
+      `snapshot: ${unreadable.length} record file(s) were unreadable and skipped` +
+      (unreadable.length > 5 ? ` (first 5: ${sample}, ...)` : ` (${sample})`),
+    );
+  }
+
   // Write snapshot files (skip if dry run)
   if (options.dryRun) {
-    return { snapshotId, included: included.length, excluded: excluded.length };
+    return { snapshotId, included: included.length, excluded: excluded.length, unreadable: unreadable.length };
   }
   await mkdir(snapshotDir, { recursive: true });
 
   const manifest = {
+    // DB-001 / DB-006: stamp manifest schema version (reader checks on load)
+    schema_version: SCHEMA_VERSION,
     snapshot_id: snapshotId,
     created_at: new Date().toISOString(),
     created_by: 'sdlab-snapshot-v1',
     project_name: config.meta.name,
     frozen: true,
     selection_profile: profile,
-    config_fingerprint: computeConfigFingerprint(projectRoot),
+    config_fingerprint: configFingerprint,
     config_versions: {
       constitution: config.constitution.version || '1.0.0',
       project: config.meta.version || '0.0.0',
     },
     counts: {
       total_records: files.length,
-      evaluated: files.length,
+      // DB-003: evaluated reflects records actually parsed (excludes unreadable)
+      evaluated: files.length - unreadable.length,
       included: included.length,
       excluded: excluded.length,
+      unreadable: unreadable.length,
     },
+    // DB-003: preserve the unreadable list so operators can investigate
+    errors: unreadable,
   };
 
   const summary = {
@@ -153,7 +244,9 @@ export async function loadSnapshot(projectRoot, snapshotId) {
   if (!existsSync(path)) {
     throw new Error(`Snapshot "${snapshotId}" not found at ${path}`);
   }
-  return JSON.parse(await readFile(path, 'utf-8'));
+  const manifest = JSON.parse(await readFile(path, 'utf-8'));
+  checkManifestVersion(manifest, 'snapshot');
+  return manifest;
 }
 
 /**

package/lib/split.js

@@ -13,8 +13,9 @@ import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { createHash, randomBytes } from 'node:crypto';
 import { loadProjectConfig, loadSplitProfile, detectLane } from './config.js';
-import { loadSnapshot, loadSnapshotIncluded } from './snapshot.js';
+import { loadSnapshot, loadSnapshotIncluded, SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
 import { loadRecord } from './records.js';
+import { inputError } from './errors.js';
 
 /**
  * Mulberry32 — deterministic 32-bit PRNG.
@@ -119,6 +120,74 @@ function buildAncestorMap(records) {
   return ancestorMap;
 }
 
+/**
+ * Allocate `total` items across train/val/test using largest-remainder rounding,
+ * guaranteeing each partition receives at least 1 when total >= 3.
+ */
+function allocateLargestRemainder(total, profile) {
+  if (total <= 0) return { train: 0, val: 0, test: 0 };
+
+  const ratios = {
+    train: profile.train_ratio,
+    val: profile.val_ratio,
+    test: profile.test_ratio,
+  };
+
+  // Ideal fractional counts
+  const ideal = {
+    train: total * ratios.train,
+    val: total * ratios.val,
+    test: total * ratios.test,
+  };
+
+  // Floor + sort by fractional remainder desc (tie-break by partition name)
+  const base = {
+    train: Math.floor(ideal.train),
+    val: Math.floor(ideal.val),
+    test: Math.floor(ideal.test),
+  };
+  let assigned = base.train + base.val + base.test;
+
+  const remainders = [
+    ['train', ideal.train - base.train],
+    ['val', ideal.val - base.val],
+    ['test', ideal.test - base.test],
+  ].sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    return a[0].localeCompare(b[0]);
+  });
+
+  let ri = 0;
+  while (assigned < total) {
+    base[remainders[ri % remainders.length][0]]++;
+    assigned++;
+    ri++;
+  }
+
+  // Min-1 rebalance: if total >= 3 and any partition is 0, take from the
+  // largest partition. Deterministic — always steal from 'train' first when tied.
+  if (total >= 3) {
+    const partitionOrder = ['train', 'val', 'test'];
+    for (const part of partitionOrder) {
+      if (base[part] === 0) {
+        // find largest (ties broken by name asc to stay deterministic)
+        const donor = partitionOrder
+          .filter(p => p !== part && base[p] > 1)
+          .sort((a, b) => {
+            if (base[b] !== base[a]) return base[b] - base[a];
+            return a.localeCompare(b);
+          })[0];
+        if (donor) {
+          base[donor]--;
+          base[part]++;
+        }
+      }
+    }
+  }
+
+  return base;
+}
+
 /**
  * Create a split from a snapshot.
  *
@@ -156,14 +225,34 @@ export async function createSplit(projectRoot, snapshotId, profile, options = {}
     familyMap.get(family).push(record);
   }
 
-  // Detect primary lane per family (first record's lane)
+  // D-002: Deterministic primary lane per family = majority vote; ties
+  // broken by lexicographic lane name. Record the per-family decision
+  // for the audit so the chosen lane is explainable.
   const familyLane = new Map();
+  const familyLaneDecisions = [];
   for (const [family, recs] of familyMap) {
-    const first = recs[0];
-    const prompt = first.provenance?.prompt || '';
-    const lane = detectLane(first.id, prompt, config.lanes);
-    familyLane.set(family, lane);
+    const laneCounts = new Map();
+    for (const rec of recs) {
+      const prompt = rec.provenance?.prompt || '';
+      const recLane = detectLane(rec.id, prompt, config.lanes);
+      laneCounts.set(recLane, (laneCounts.get(recLane) || 0) + 1);
+    }
+    // Sort: count desc, then lane name asc. Deterministic winner.
+    const ranked = [...laneCounts.entries()].sort((a, b) => {
+      if (b[1] !== a[1]) return b[1] - a[1];
+      return a[0].localeCompare(b[0]);
+    });
+    const [chosenLane, chosenCount] = ranked[0];
+    familyLane.set(family, chosenLane);
+    familyLaneDecisions.push({
+      family,
+      chosen_lane: chosenLane,
+      chosen_count: chosenCount,
+      record_count: recs.length,
+      lane_counts: Object.fromEntries(laneCounts),
+    });
   }
+  familyLaneDecisions.sort((a, b) => a.family.localeCompare(b.family));
 
   // Group families by lane
   const laneGroups = new Map(); // lane → [family]
@@ -173,7 +262,8 @@ export async function createSplit(projectRoot, snapshotId, profile, options = {}
   }
 
   // Split families per lane using seeded PRNG
-  const rng = mulberry32(profile.seed || 42);
+  // D-011: seed:0 is a valid seed; use nullish coalescing so 0 is honored.
+  const rng = mulberry32(profile.seed ?? 42);
   const trainFamilies = new Set();
   const valFamilies = new Set();
   const testFamilies = new Set();
@@ -191,11 +281,17 @@ export async function createSplit(projectRoot, snapshotId, profile, options = {}
       continue;
     }
 
-    // Assign by ratio
+    // D-004: Largest-remainder allocation guarantees min-1 per partition
+    // when total >= 3, and emits a warning if any partition ends up at 0.
     const total = shuffled.length;
-    const trainCount = Math.round(total * profile.train_ratio);
-    const valCount = Math.round(total * profile.val_ratio);
-    // test gets the rest
+    const { train: trainCount, val: valCount, test: testCount } =
+      allocateLargestRemainder(total, profile);
+
+    if (total >= 3 && (trainCount === 0 || valCount === 0 || testCount === 0)) {
+      warnings.push(
+        `lane "${lane}": partition size hit 0 after allocation (train=${trainCount}, val=${valCount}, test=${testCount}) — ratios may be extreme`,
+      );
+    }
 
     let idx = 0;
     for (let i = 0; i < trainCount && idx < total; i++, idx++) {
@@ -226,7 +322,14 @@ export async function createSplit(projectRoot, snapshotId, profile, options = {}
     if (trainFamilies.has(family)) trainRecords.push(record.id);
     else if (valFamilies.has(family)) valRecords.push(record.id);
     else if (testFamilies.has(family)) testRecords.push(record.id);
-    else trainRecords.push(record.id); // fallback: unassigned → train
+    else {
+      // D-003: unassigned family means the familyMap build pass disagreed
+      // with the assignment pass — never silently rescue; surface the bug.
+      throw new Error(
+        `unassigned family for record ${record.id} (family=${family}) — ` +
+        `this indicates a bug in family resolution; the record was not placed in train/val/test`,
+      );
+    }
   }
 
   // Sort for deterministic output
@@ -237,9 +340,9 @@ export async function createSplit(projectRoot, snapshotId, profile, options = {}
   // Leakage audit
   const leakageIssues = auditLeakage(familyMap, trainRecords, valRecords, testRecords);
 
-  // Lane balance audit
+  // Lane balance audit (DB-005: includes deviation from profile ratios)
   const laneBalance = auditLaneBalance(
-    records, trainRecords, valRecords, testRecords, config.lanes
+    records, trainRecords, valRecords, testRecords, config.lanes, profile
   );
 
   // Write output (skip if dry run)
@@ -248,9 +351,19 @@ export async function createSplit(projectRoot, snapshotId, profile, options = {}
     return { splitId, train: trainRecords.length, val: valRecords.length, test: testRecords.length };
   }
   const splitDir = join(projectRoot, 'splits', splitId);
+  // D-005: refuse to silently overwrite on ID collision.
+  if (existsSync(splitDir)) {
+    throw inputError(
+      'SPLIT_ID_COLLISION',
+      `Split directory already exists: ${splitDir}`,
+      'Retry to generate a fresh split ID.',
+    );
+  }
   await mkdir(splitDir, { recursive: true });
 
   const manifest = {
+    // DB-001 / DB-006: stamp manifest schema version
+    schema_version: SCHEMA_VERSION,
     split_id: splitId,
     created_at: new Date().toISOString(),
     created_by: 'sdlab-split-v1',
@@ -280,6 +393,9 @@ export async function createSplit(projectRoot, snapshotId, profile, options = {}
       val: valFamilies.size,
       test: testFamilies.size,
     },
+    // D-002: record the deterministic per-family lane decision for replay.
+    family_lane_decisions: familyLaneDecisions,
+    warnings,
   };
 
   await writeFile(join(splitDir, 'split.json'), JSON.stringify(manifest, null, 2) + '\n');
@@ -322,8 +438,13 @@ function auditLeakage(familyMap, trainIds, valIds, testIds) {
 
 /**
  * Audit lane balance across splits.
+ *
+ * DB-005: includes deviation-from-profile metric per lane + overall score.
+ * A lane that shows train=100/val=0/test=0 and another at 33/33/33 look
+ * equally "balanced" by percentage alone — deviation makes the real gap
+ * between intent and reality visible at a glance.
  */
-function auditLaneBalance(records, trainIds, valIds, testIds, lanesConfig) {
+function auditLaneBalance(records, trainIds, valIds, testIds, lanesConfig, profile) {
   const trainSet = new Set(trainIds);
   const valSet = new Set(valIds);
   const testSet = new Set(testIds);
@@ -339,14 +460,49 @@ function auditLaneBalance(records, trainIds, valIds, testIds, lanesConfig) {
     else if (testSet.has(record.id)) balance[lane].test++;
   }
 
-  // Compute percentages
+  // Compute percentages + deviation from profile ratios (DB-005)
+  const targetTrain = (profile?.train_ratio ?? 0) * 100;
+  const targetVal = (profile?.val_ratio ?? 0) * 100;
+  const targetTest = (profile?.test_ratio ?? 0) * 100;
+
+  let overallDeviation = 0;
+  const deviations = {};
+
   for (const lane of Object.keys(balance)) {
     const b = balance[lane];
     b.train_pct = b.total > 0 ? +(b.train / b.total * 100).toFixed(1) : 0;
     b.val_pct = b.total > 0 ? +(b.val / b.total * 100).toFixed(1) : 0;
     b.test_pct = b.total > 0 ? +(b.test / b.total * 100).toFixed(1) : 0;
+
+    // DB-005: absolute deviation from profile target per partition
+    const devTrain = Math.abs(b.train_pct - targetTrain);
+    const devVal = Math.abs(b.val_pct - targetVal);
+    const devTest = Math.abs(b.test_pct - targetTest);
+    // Lane deviation: sum of per-partition absolute deviations (max ~200)
+    const laneDev = +(devTrain + devVal + devTest).toFixed(1);
+    b.deviation_from_target = {
+      train: +devTrain.toFixed(1),
+      val: +devVal.toFixed(1),
+      test: +devTest.toFixed(1),
+      total: laneDev,
+    };
+    deviations[lane] = laneDev;
+    overallDeviation += laneDev;
   }
 
+  // Attach a summary so the operator sees the signal without scanning per-lane rows.
+  balance._summary = {
+    target_ratios_pct: {
+      train: +targetTrain.toFixed(1),
+      val: +targetVal.toFixed(1),
+      test: +targetTest.toFixed(1),
+    },
+    overall_deviation_score: +overallDeviation.toFixed(1),
+    worst_lane: Object.keys(deviations).length > 0
+      ? Object.entries(deviations).sort((a, b) => b[1] - a[1])[0][0]
+      : null,
+  };
+
   return balance;
 }
 
@@ -358,7 +514,9 @@ export async function loadSplit(projectRoot, splitId) {
   if (!existsSync(path)) {
     throw new Error(`Split "${splitId}" not found at ${path}`);
   }
-  return JSON.parse(await readFile(path, 'utf-8'));
+  const manifest = JSON.parse(await readFile(path, 'utf-8'));
+  checkManifestVersion(manifest, 'split');
+  return manifest;
 }
 
 /**