@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/eligibility.js

@@ -6,6 +6,28 @@
  */
 
 import { detectLane, detectGroup } from './config.js';
+import { warn } from './log.js';
+
+/**
+ * F5: stable, machine-readable codes — one per exclusion reason, in the
+ * exact same order/count as the human-readable `reasons` strings pushed
+ * below. Added so categorizeExclusions() can categorize by code instead
+ * of depending on prose matching (rewording a `reasons` string used to
+ * silently break categorization). Purely additive: `reasons` keeps its
+ * exact original shape and text, this is a NEW parallel field
+ * (`reason_codes` on the returned object) — any existing caller that only
+ * reads `.eligible` / `.reasons` sees no change at all.
+ */
+export const REASON_CODES = {
+  NO_JUDGMENT: 'no_judgment',
+  WRONG_STATUS: 'wrong_status',
+  NOT_CANON_BOUND: 'not_canon_bound',
+  UNMEASURED_PASS_COUNT: 'unmeasured_pass_count',
+  LOW_PASS_RATIO: 'low_pass_ratio',
+  EXCLUDED_LANE: 'excluded_lane',
+  RIGHTS_FILTER: 'rights_filter',
+  EXCLUDED_TAGS: 'excluded_tags',
+};
 
 /**
  * Evaluate a single record against a selection profile.
@@ -13,15 +35,18 @@ import { detectLane, detectGroup } from './config.js';
  * @param {Object} profile — selection profile
  * @param {Object} lanesConfig — from lanes.json
  * @param {Object} termConfig — from terminology.json
- * @returns {{ eligible: boolean, reasons: string[] }}
+ * @returns {{ eligible: boolean, reasons: string[], reason_codes: string[] }}
  */
 export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
   const reasons = [];
+  // F5: parallel array — reasonCodes[i] is the stable code for reasons[i].
+  const reasonCodes = [];
 
   // 1. Judgment required
   if (profile.require_judgment) {
     if (!record.judgment) {
       reasons.push('no judgment (record has not been reviewed)');
+      reasonCodes.push(REASON_CODES.NO_JUDGMENT);
     }
   }
 
@@ -29,6 +54,7 @@ export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
   if (profile.require_status?.length > 0 && record.judgment) {
     if (!profile.require_status.includes(record.judgment.status)) {
       reasons.push(`status "${record.judgment.status}" not in [${profile.require_status.join(', ')}]`);
+      reasonCodes.push(REASON_CODES.WRONG_STATUS);
     }
   }
 
@@ -36,14 +62,31 @@ export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
   if (profile.require_canon_bound) {
     if (!record.canon?.assertions || record.canon.assertions.length === 0) {
       reasons.push('not canon-bound (no assertions)');
+      reasonCodes.push(REASON_CODES.NOT_CANON_BOUND);
     }
   }
 
   // 4. Minimum pass ratio
   if (profile.minimum_pass_ratio != null && record.canon?.assertion_count > 0) {
-    const ratio = record.canon.pass_count / record.canon.assertion_count;
-    if (ratio < profile.minimum_pass_ratio) {
-      reasons.push(`pass ratio ${(ratio * 100).toFixed(0)}% below minimum ${(profile.minimum_pass_ratio * 100).toFixed(0)}%`);
+    const passCount = record.canon.pass_count;
+    // pass_count missing/non-numeric while assertion_count > 0 must NOT
+    // silently compute NaN: `NaN < minimum_pass_ratio` is always false, so
+    // the exclusion would never fire and a record whose pass ratio was never
+    // actually measured would be treated as having cleared a bar it never
+    // touched. Law 2 (inclusion is explainable) requires this be its own
+    // named reason, not a silent pass.
+    if (typeof passCount !== 'number' || !Number.isFinite(passCount)) {
+      reasons.push(
+        `pass_count is missing or not a number (assertion_count is ${record.canon.assertion_count}); ` +
+          `cannot verify pass ratio, so it is excluded rather than assumed passing`
+      );
+      reasonCodes.push(REASON_CODES.UNMEASURED_PASS_COUNT);
+    } else {
+      const ratio = passCount / record.canon.assertion_count;
+      if (ratio < profile.minimum_pass_ratio) {
+        reasons.push(`pass ratio ${(ratio * 100).toFixed(0)}% below minimum ${(profile.minimum_pass_ratio * 100).toFixed(0)}%`);
+        reasonCodes.push(REASON_CODES.LOW_PASS_RATIO);
+      }
     }
   }
 
@@ -53,6 +96,7 @@ export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
     const lane = detectLane(record.id, prompt, lanesConfig);
     if (profile.exclude_lanes.includes(lane)) {
       reasons.push(`lane "${lane}" is excluded`);
+      reasonCodes.push(REASON_CODES.EXCLUDED_LANE);
     }
   }
 
@@ -61,6 +105,7 @@ export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
     const rights = record.rights_status || record.training_rights_status || null;
     if (rights !== profile.rights_filter) {
       reasons.push(`rights "${rights || 'unknown'}" does not match required "${profile.rights_filter}"`);
+      reasonCodes.push(REASON_CODES.RIGHTS_FILTER);
     }
   }
 
@@ -69,41 +114,108 @@ export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
     const excluded = record.dataset_tags.filter(t => profile.exclude_tags.includes(t));
     if (excluded.length > 0) {
       reasons.push(`has excluded tags: ${excluded.join(', ')}`);
+      reasonCodes.push(REASON_CODES.EXCLUDED_TAGS);
     }
   }
 
   return {
     eligible: reasons.length === 0,
     reasons,
+    reason_codes: reasonCodes,
   };
 }
 
 /**
  * Categorize exclusion reasons for a set of records.
- * @param {Array<{record_id: string, reasons: string[]}>} excluded
- * @returns {Object} — category → count mapping
+ *
+ * F5: every reason is guaranteed to land in exactly one bucket — the
+ * mutually-exclusive if/else-if chain below now ends in a trailing `else`
+ * that increments `uncategorized` instead of silently matching nothing.
+ * Previously, rewording a `reasons` string in evaluateEligibility(), or
+ * adding a ninth reason with no matching branch, meant those exclusions
+ * were counted in NO category at all — a gap invisible in the output
+ * (the category sum would just quietly fall short of the true count).
+ *
+ * When an `excluded` entry carries `reason_codes` (evaluateEligibility's
+ * new parallel array — see REASON_CODES above), categorization uses the
+ * stable code directly instead of prose-matching `reasons`. Entries
+ * without `reason_codes` (older excluded.jsonl written before F5, or a
+ * caller that only forwards `reasons`) fall back to the original
+ * free-text matching, unchanged.
+ *
+ * @param {Array<{record_id: string, reasons: string[], reason_codes?: string[]}>} excluded
+ * @returns {Object} — category → count mapping (includes `uncategorized`)
  */
 export function categorizeExclusions(excluded) {
   const categories = {
     no_judgment: 0,
     wrong_status: 0,
     not_canon_bound: 0,
+    unmeasured_pass_count: 0,
     low_pass_ratio: 0,
     excluded_lane: 0,
     rights_filter: 0,
     excluded_tags: 0,
+    uncategorized: 0,
   };
+  const KNOWN_CODES = new Set(Object.values(REASON_CODES));
 
-  for (const { reasons } of excluded) {
-    for (const r of reasons) {
+  // F5: sample of the actual uncategorized reason strings, surfaced via
+  // warn() below so an operator sees WHAT needs a new branch/code instead
+  // of just a suspicious gap in the numbers.
+  const uncategorizedSamples = [];
+  let totalReasons = 0;
+
+  for (const { reasons, reason_codes: reasonCodes } of excluded) {
+    reasons.forEach((r, i) => {
+      totalReasons++;
+      const code = reasonCodes?.[i];
+      if (code && KNOWN_CODES.has(code)) {
+        categories[code]++;
+        return;
+      }
       if (r.includes('no judgment')) categories.no_judgment++;
       else if (r.includes('status')) categories.wrong_status++;
       else if (r.includes('canon-bound')) categories.not_canon_bound++;
+      // Order matters: "pass_count missing" must be checked before the
+      // generic "pass ratio" match below, since an unmeasured pass_count
+      // is a distinct exclusion reason from a measured-and-low ratio (Law 2
+      // — inclusion must be explainable, so "never measured" cannot be
+      // folded into "measured and failed").
+      else if (r.includes('pass_count')) categories.unmeasured_pass_count++;
       else if (r.includes('pass ratio')) categories.low_pass_ratio++;
       else if (r.includes('lane')) categories.excluded_lane++;
       else if (r.includes('rights')) categories.rights_filter++;
       else if (r.includes('tags')) categories.excluded_tags++;
-    }
+      else {
+        categories.uncategorized++;
+        if (uncategorizedSamples.length < 10) uncategorizedSamples.push(r);
+      }
+    });
+  }
+
+  if (categories.uncategorized > 0) {
+    const shown = uncategorizedSamples.slice(0, 5);
+    warn(
+      `eligibility: ${categories.uncategorized} exclusion reason(s) matched no known category ` +
+      `(first ${shown.length}: ${shown.join(' | ')})` +
+      (uncategorizedSamples.length > shown.length ? ', ...' : '') +
+      ' — add a matching reason_code/branch, or these will keep landing in "uncategorized".',
+    );
+  }
+
+  // F5: defensive tripwire, not a normal-path check — the if/else-if chain
+  // above is mutually exclusive and the trailing else always catches
+  // anything unmatched, so this sum is mathematically guaranteed to equal
+  // totalReasons for any input. A mismatch would mean a future edit broke
+  // that mutual-exclusivity guarantee (e.g. turned an `else if` into a
+  // bare `if`, allowing one reason to double-count).
+  const categorizedSum = Object.values(categories).reduce((a, b) => a + b, 0);
+  if (categorizedSum !== totalReasons) {
+    warn(
+      `eligibility: categorization invariant violated — categorized ${categorizedSum} reason(s) but ` +
+      `${totalReasons} were processed. This indicates a bug in categorizeExclusions itself.`,
+    );
   }
 
   return categories;

package/lib/eval-pack.js

@@ -10,14 +10,13 @@
  * 4. Subject continuity — same-subject records for identity testing
  */
 
-import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
 import { loadRecord } from './records.js';
-import { computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
-import { inputError } from './errors.js';
+import { computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion, claimIdDir } from './snapshot.js';
 
 /**
  * Generate an eval-pack ID: eval-YYYYMMDD-HHMMSS-XXXX
@@ -73,17 +72,18 @@ export async function buildEvalPack(projectRoot, options = {}) {
   const subjectContinuity = buildSubjectContinuity(records, maxContinuity);
 
   // Write eval pack
-  const evalId = generateEvalId();
-  const evalDir = join(projectRoot, 'eval-packs', evalId);
-  // D-005: refuse to silently overwrite on ID collision.
-  if (existsSync(evalDir)) {
-    throw inputError(
-      'EVAL_PACK_ID_COLLISION',
-      `Eval pack directory already exists: ${evalDir}`,
-      'Retry to generate a fresh eval pack ID.',
-    );
-  }
-  await mkdir(evalDir, { recursive: true });
+  // SDL-M10: atomically claim the eval-pack 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).
+  const { id: evalId, dir: evalDir } = await claimIdDir(
+    join(projectRoot, 'eval-packs'),
+    generateEvalId,
+    {
+      code: 'EVAL_PACK_ID_COLLISION',
+      message: 'Could not claim a unique eval-pack ID — every candidate collided with an existing eval-pack directory.',
+      hint: 'Retry; if this persists, another sdlab process may be creating eval packs in a tight loop.',
+    },
+  );
 
   // DB-014: compute `records_available` so the manifest reports sampled vs.
   // available. Operators can see when they're leaving records on the table.

package/lib/eval-runs.js

@@ -14,6 +14,7 @@ import { loadTrainingManifest } from './training-manifests.js';
 import { loadEvalPack } from './eval-pack.js';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
 import { SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { inputError } from './errors.js';
 
 // DB-008: cap sample record_ids per failure bucket so scorecards stay small
 // but the operator has enough detail to start investigation.
@@ -91,6 +92,18 @@ export async function scoreEvalRun(projectRoot, evalRunId, outputsPath) {
 
   // Load eval pack tasks
   const evalPackDir = join(projectRoot, 'eval-packs', runManifest.eval_pack_id);
+  // F2: createEvalRun only ever stores the eval_pack_id string — it never
+  // re-verifies at scoring time that the pack directory still exists. If
+  // the pack was deleted (or moved) between run creation and scoring, this
+  // used to fall straight through to the all-four-skip / vacuous-pass path
+  // below. Fail loudly here with the exact missing path instead.
+  if (!existsSync(evalPackDir)) {
+    throw inputError(
+      'EVAL_PACK_DIR_MISSING',
+      `Eval pack directory not found: ${evalPackDir} (eval run "${evalRunId}" references eval_pack_id "${runManifest.eval_pack_id}").`,
+      'The eval pack this run was created against may have been deleted or moved. Rebuild the eval pack, or create a fresh eval run against one that still exists.',
+    );
+  }
   const taskFiles = {
     'lane-coverage': 'lane-coverage.jsonl',
     'forbidden-drift': 'forbidden-drift.jsonl',
@@ -102,10 +115,18 @@ export async function scoreEvalRun(projectRoot, evalRunId, outputsPath) {
 
   // Score each task type
   const scores = {};
+  // F2: count task files that actually resolved. Object.values({}).every(...)
+  // on an EMPTY scores object is vacuously true in JS — with zero task files
+  // found, `scores` stays `{}` and the verdict below silently computed
+  // overall_verdict:'pass', overall_score:0.000 for a model that was never
+  // evaluated against anything. resolvedTaskFiles turns that into a named,
+  // structured failure instead of a green rubber stamp.
+  let resolvedTaskFiles = 0;
 
   for (const [taskName, fileName] of Object.entries(taskFiles)) {
     const taskPath = join(evalPackDir, fileName);
     if (!existsSync(taskPath)) continue;
+    resolvedTaskFiles++;
 
     const taskEntries = (await readFile(taskPath, 'utf-8'))
       .trim().split('\n').filter(Boolean).map(l => JSON.parse(l));
@@ -121,6 +142,18 @@ export async function scoreEvalRun(projectRoot, evalRunId, outputsPath) {
     }
   }
 
+  // F2: belt-and-suspenders — even with the directory-existence guard above,
+  // a pack directory that exists but has had every individual task file
+  // deleted out from under it must hit the same guard, not the vacuous
+  // Object.values({}).every(...) === true path.
+  if (resolvedTaskFiles === 0) {
+    throw inputError(
+      'EVAL_PACK_NO_TASK_FILES',
+      `Eval pack "${runManifest.eval_pack_id}" at ${evalPackDir} has no resolvable task files — nothing was scored for eval run "${evalRunId}".`,
+      `Expected at least one of: ${Object.values(taskFiles).join(', ')}. Verify the eval pack was built correctly and its directory was not partially deleted.`,
+    );
+  }
+
   // Compute overall verdict
   const allPassed = Object.values(scores).every(s => s.passed);
   const overallScore = Object.values(scores).reduce((sum, s) => sum + (s.score || 0), 0) /

package/lib/export.js

@@ -11,7 +11,7 @@ import { existsSync } from 'node:fs';
 import { platform } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
 import { loadProjectConfig, loadExportProfile, detectLane, detectGroup } from './config.js';
-import { loadSnapshot, loadSnapshotIncluded, computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { loadSnapshot, loadSnapshotIncluded, computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion, claimIdDir } from './snapshot.js';
 import { loadSplit, loadSplitPartition } from './split.js';
 import { loadRecord } from './records.js';
 import { generateCard } from './card.js';
@@ -36,6 +36,63 @@ async function sha256File(filePath) {
   return createHash('sha256').update(data).digest('hex');
 }
 
+/**
+ * SDL-H6: validate that a record-relative asset_path does not escape
+ * projectRoot. Rejects absolute paths outright (ASSET_PATH_INVALID) and
+ * rejects any relative path that resolves outside projectRoot
+ * (ASSET_PATH_TRAVERSAL — e.g. "../../../../etc/passwd").
+ * Returns the resolved absolute path on success.
+ *
+ * This was previously inlined here only (D-007) and never ported to the
+ * training-package adapters, which checked only `existsSync` — a
+ * traversal path satisfies existsSync just as well as a legitimate one.
+ * lib/training-packages.js and the adapters import this so the exact same
+ * guard (same error codes) applies on every path that turns asset_path
+ * into a filesystem read.
+ */
+export function assertSafeAssetPath(assetPath, projectRoot, recordId) {
+  if (isAbsolute(assetPath)) {
+    throw inputError(
+      'ASSET_PATH_INVALID',
+      `Record "${recordId}" has absolute asset_path: ${assetPath}`,
+      'asset_path must be relative to the project root.',
+    );
+  }
+  const projectRootResolved = resolve(projectRoot);
+  const resolvedSource = resolve(projectRootResolved, assetPath);
+  if (resolvedSource !== projectRootResolved &&
+      !resolvedSource.startsWith(projectRootResolved + sep)) {
+    throw inputError(
+      'ASSET_PATH_TRAVERSAL',
+      `Record "${recordId}" asset_path escapes projectRoot: ${assetPath}`,
+      'Reject path traversal segments (e.g. "../") in asset_path.',
+    );
+  }
+  return resolvedSource;
+}
+
+/**
+ * SDL-H5: allowlist model for an id destined to become a filename or path
+ * segment (letters, digits, dot, underscore, hyphen only — no `/`, `\`,
+ * or `..`, so no traversal is expressible). Mirrors the character class
+ * lib/selections.js's SAFE_FILENAME_RE uses for approved-output filenames;
+ * that constant isn't exported and additionally requires an image
+ * extension suffix that doesn't apply to a bare record/entity id, so this
+ * is a parallel definition over the same allowlist model rather than a
+ * copy of a differently-shaped regex.
+ */
+export const SAFE_ID_RE = /^[A-Za-z0-9._-]+$/;
+
+export function assertSafeId(id, context) {
+  if (typeof id !== 'string' || !SAFE_ID_RE.test(id)) {
+    throw inputError(
+      'UNSAFE_RECORD_ID',
+      `Invalid id "${id}" in ${context}`,
+      'ids must match [A-Za-z0-9._-]+ — letters, digits, dot, underscore, hyphen only.',
+    );
+  }
+}
+
 /**
  * Build an export package.
  *
@@ -55,22 +112,12 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
   const included = await loadSnapshotIncluded(projectRoot, snapshotId);
   const recordsDir = join(projectRoot, 'records');
 
-  const exportId = generateExportId();
-  const exportDir = join(projectRoot, 'exports', exportId);
-
-  // D-005: existsSync guard prevents silent overwrite on ID collision
-  if (existsSync(exportDir)) {
-    throw inputError(
-      'EXPORT_ID_COLLISION',
-      `Export directory already exists: ${exportDir}`,
-      'Retry to generate a fresh export ID, or delete the existing directory if this was intentional.',
-    );
-  }
-
   // D-001: Verify fingerprint has not drifted since snapshot creation.
   // We inherit the snapshot's fingerprint in the export manifest; if a caller
   // has edited project config mid-flight we surface that loudly rather than
   // silently embedding a new fingerprint that masks reproducibility loss.
+  // (Checked BEFORE claiming an export id/dir below — no point reserving
+  // one if we're about to abort.)
   const currentFingerprint = computeConfigFingerprint(projectRoot);
   if (snapshot.config_fingerprint && currentFingerprint !== snapshot.config_fingerprint) {
     throw inputError(
@@ -80,18 +127,44 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
     );
   }
 
-  await mkdir(exportDir, { recursive: true });
+  // SDL-M10: atomically claim the export 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).
+  const { id: exportId, dir: exportDir } = await claimIdDir(
+    join(projectRoot, 'exports'),
+    generateExportId,
+    {
+      code: 'EXPORT_ID_COLLISION',
+      message: 'Could not claim a unique export ID — every candidate collided with an existing export directory.',
+      hint: 'Retry; if this persists, another sdlab process may be creating exports in a tight loop.',
+    },
+  );
 
   // Build metadata + collect image paths
   const metadata = [];
   const imagePaths = [];
   const checksumEntries = [];
+  // F3: a record the (frozen, Law-1) snapshot included whose file was
+  // later deleted from records/ must never silently drop the export's
+  // record count below snapshot.counts.included. loadRecord() returns
+  // null on ENOENT (lib/records.js) — previously that null was a silent
+  // `continue` with no counter, no warning, no id recorded, so an export
+  // built from a snapshot with stale/deleted records would just quietly
+  // contain fewer rows than snapshot.counts.included promised. Accumulated
+  // across the whole loop (not fail-fast on the first) so the operator
+  // sees every missing id in one error instead of fixing them one at a
+  // time; hard-failed below rather than warned — see the comment at the
+  // throw site for why export specifically earns that escalation.
+  const missingRecords = [];
 
   const projectRootResolved = resolve(projectRoot);
 
   for (const entry of included) {
     const record = await loadRecord(recordsDir, entry.record_id);
-    if (!record) continue;
+    if (!record) {
+      missingRecords.push({ record_id: entry.record_id, stage: 'export' });
+      continue;
+    }
 
     const prompt = record.provenance?.prompt || '';
     const lane = detectLane(record.id, prompt, config.lanes);
@@ -115,28 +188,20 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
 
     // Track image for linking
     if (profile.include_images && record.asset_path) {
-      // D-007: validate asset_path does not escape projectRoot, use
-      // platform-safe basename, and name output files by record.id
-      // (D-009) to avoid collisions on shared basenames.
-      if (isAbsolute(record.asset_path)) {
-        throw inputError(
-          'ASSET_PATH_INVALID',
-          `Record "${record.id}" has absolute asset_path: ${record.asset_path}`,
-          'asset_path must be relative to the project root.',
-        );
-      }
-      const resolvedSource = resolve(projectRootResolved, record.asset_path);
-      if (resolvedSource !== projectRootResolved &&
-          !resolvedSource.startsWith(projectRootResolved + sep)) {
-        throw inputError(
-          'ASSET_PATH_TRAVERSAL',
-          `Record "${record.id}" asset_path escapes projectRoot: ${record.asset_path}`,
-          'Reject path traversal segments (e.g. "../") in asset_path.',
-        );
-      }
+      // D-007 / SDL-H6: validate asset_path does not escape projectRoot.
+      const resolvedSource = assertSafeAssetPath(record.asset_path, projectRootResolved, record.id);
       const sourceBasename = basename(record.asset_path);
       const extMatch = sourceBasename.match(/\.[^.]+$/);
       const ext = extMatch ? extMatch[0] : '';
+      // SDL-H5: the block above only validated the SOURCE asset_path —
+      // record.id becomes part of the DESTINATION filename below and was
+      // completely unvalidated despite the variable being named
+      // "safeFilename". A record id of "../../../evil" would escape the
+      // export dir on write. Reachable without hand-authoring: reingest
+      // derives ids from generated-output filenames.
+      assertSafeId(record.id, `record.id for export image filename (record "${record.id}")`);
+      // D-009: name output files by record.id to avoid collisions on
+      // shared basenames.
       const safeFilename = `${record.id}${ext}`;
       imagePaths.push({
         record_id: record.id,
@@ -146,6 +211,29 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
     }
   }
 
+  // F3: hard-fail on any record the snapshot promised but records/ no
+  // longer has. Nothing has been written to exportDir yet (metadata.jsonl,
+  // images/, manifest.json, etc. are all written below this point) — an
+  // aborted export leaves only the empty claimed directory behind, no
+  // partial/misleading artifacts. Export (and training-packages.js one
+  // layer further downstream) is where Law 4 ("exports are reproducible —
+  // rebuildable from snapshot + split + profile") makes completeness an
+  // actual contract rather than a courtesy, which is why this escalates to
+  // a thrown error instead of the warn()-and-continue ledger pattern used
+  // in split.js and implementation-packs.js, where the artifact produced
+  // is not itself the reproducibility-guaranteeing one.
+  if (missingRecords.length > 0) {
+    const sample = missingRecords.slice(0, 10).map(m => m.record_id);
+    throw inputError(
+      'EXPORT_MISSING_RECORDS',
+      `${missingRecords.length} of ${included.length} record(s) referenced by snapshot "${snapshotId}" could not be loaded from ${recordsDir} — this export would silently contain fewer records than the snapshot's included count.` +
+      (missingRecords.length > 10
+        ? ` First 10: ${sample.join(', ')}, ...`
+        : ` Missing: ${sample.join(', ')}.`),
+      'Record file(s) were likely deleted after the snapshot was created (a snapshot freezes the SELECTION, not the underlying record files). Restore the missing file(s), or create a fresh snapshot that reflects current on-disk records before exporting.',
+    );
+  }
+
   // Write metadata.jsonl
   const metadataPath = join(exportDir, 'metadata.jsonl');
   await writeFile(metadataPath, metadata.map(r => JSON.stringify(r)).join('\n') + '\n');

package/lib/freeze-gate.js

@@ -26,6 +26,10 @@ import { loadCanonEntriesInDir, entryId } from './canon-build/load-entry.js';
 import { readFreezeStatus } from './freeze-stamp.js';
 import { appendEvent, readEventsFor } from './freeze-events.js';
 import { inputError } from './errors.js';
+import { warn } from './log.js';
+import { assertDirectorRatifiedForFreeze } from './canon-review-gate.js';
+
+export { assertDirectorRatifiedForFreeze };
 
 /**
  * Best-effort freeze date for an entry: the `at` of its most recent freeze /
@@ -74,9 +78,18 @@ export async function loadAllCanonEntries(projectRoot) {
   let config;
   try {
     config = await loadBuildConfig(configPath, projectRoot);
-  } catch {
-    // Invalid config → degrade to "no gate" rather than blocking every write.
-    // The operator will hit the config error on `sdlab canon build`.
+  } catch (err) {
+    // Invalid config → degrade to "no gate" rather than blocking every write
+    // (a config typo shouldn't turn into "no one can generate/curate/paint
+    // anything in this project"). But that degrade-open MUST be audible —
+    // silently disabling freeze protection project-wide with zero operator
+    // signal is its own defect. Warn loudly to stderr; the operator will
+    // also hit the same config error surfaced properly on `sdlab canon build`.
+    warn(
+      `freeze gate disabled for this project: canon-build/config.json is invalid ` +
+        `(${err.message}). Every entry is being treated as not canon-bound — freeze/soft-advisory ` +
+        `protection is OFF until the config is fixed. Run "sdlab canon build" to see the full error.`,
+    );
     return [];
   }
   const entries = [];

package/lib/freeze-stamp.js

@@ -10,6 +10,7 @@
 
 import { createHash } from 'node:crypto';
 import { getByPath } from './canon-build/load-config.js';
+import { inputError } from './errors.js';
 
 /**
  * The four legal freeze statuses. Entries without a `freeze` block behave
@@ -19,13 +20,37 @@ export const FREEZE_STATUSES = Object.freeze(['auto', 'frozen', 'soft-advisory',
 
 /**
  * Read the normalized freeze status for an entry frontmatter.
- * Missing block / missing status / invalid value all collapse to `auto`.
+ *
+ * A missing `freeze` block, or a `freeze` block with no `status` key at all,
+ * collapses to `auto` — that permissive default is deliberate (D8): an entry
+ * that has never opted into freeze protection should never block a write.
+ *
+ * But a `freeze` block that IS present with a `status` value that is a
+ * non-empty string outside `FREEZE_STATUSES` is not "absent" — it is
+ * malformed. Coercing that case to `auto` too would silently disable hard
+ * freeze protection on a hand-edited typo (e.g. `status: Frozen` against the
+ * lowercase-only enum) with no error, no warning, and no bypass event, since
+ * the bypass path is never entered. Fail loud instead: throw so the operator
+ * fixes the typo rather than unknowingly shipping an unprotected entry.
+ *
+ * @throws {SdlabError} CANON_FREEZE_STATUS_INVALID when `freeze` is present
+ *   and `status` is a non-empty string that isn't a legal FREEZE_STATUSES value.
  */
 export function readFreezeStatus(frontmatter) {
   const status = frontmatter?.freeze?.status;
   if (typeof status !== 'string') return 'auto';
-  if (!FREEZE_STATUSES.includes(status)) return 'auto';
-  return status;
+  if (FREEZE_STATUSES.includes(status)) return status;
+  if (status.length > 0) {
+    throw inputError(
+      'CANON_FREEZE_STATUS_INVALID',
+      `Invalid freeze.status "${status}"${frontmatter?.id ? ` on entry "${frontmatter.id}"` : ''}: ` +
+        `not one of [${FREEZE_STATUSES.join(', ')}].`,
+      `Fix the freeze.status value (check for a case typo — statuses are lowercase-only). ` +
+        `A malformed status is treated as an error, not as "auto", so a typo can never ` +
+        `silently disable freeze protection.`,
+    );
+  }
+  return 'auto';
 }
 
 /**