@mcptoolshop/style-dataset-lab 3.3.0 → 3.4.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. "../../../../Users/victim/.ssh/id_rsa").
+ * 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,7 @@ 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';
 
 /**
  * Best-effort freeze date for an entry: the `at` of its most recent freeze /
@@ -74,9 +75,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';
 }
 
 /**

package/lib/generated-provenance.js

@@ -9,6 +9,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
+import { warn } from './log.js';
 
 /**
  * Build a generation provenance payload for a selected output.
@@ -68,7 +69,21 @@ export function buildGeneratedProvenance({
         const brief = JSON.parse(readFileSync(briefPath, 'utf-8'));
         if (brief.subject_id) prov.subject_id = brief.subject_id;
         if (brief.parent_brief_id) prov.parent_brief_id = brief.parent_brief_id;
-      } catch { /* skip */ }
+      } catch (err) {
+        // B08: the brief exists but couldn't be read/parsed (e.g. a
+        // concurrent mid-write) — lineage is genuinely UNKNOWN here, not
+        // merely absent. Surface it instead of silently shipping
+        // provenance with no lineage and no signal that anything failed.
+        warn(`generated-provenance: brief ${briefPath} could not be read (${err.message}) — lineage_incomplete`);
+        prov.lineage_incomplete = true;
+      }
+    } else {
+      // B08: no brief on disk at all for this run — the same "genuinely
+      // unknown" lineage state as an unreadable brief, not a normal
+      // "this brief simply has no subject_id" case (that one is NOT
+      // flagged — see the brief-read-fine-but-no-subject_id branch above).
+      warn(`generated-provenance: brief not found at ${briefPath} — lineage_incomplete`);
+      prov.lineage_incomplete = true;
     }
   }
 

package/lib/implementation-packs.js

@@ -8,7 +8,7 @@
  * Every implementation pack is tied to a training manifest.
  */
 
-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 { randomBytes } from 'node:crypto';
@@ -17,8 +17,8 @@ import { loadTrainingProfile } from './training-profiles.js';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
 import { loadSplitPartition } from './split.js';
 import { loadRecord } from './records.js';
-import { inputError } from './errors.js';
-import { SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { SCHEMA_VERSION, checkManifestVersion, claimIdDir } from './snapshot.js';
+import { warn } from './log.js';
 
 function generateImplId() {
   const now = new Date();
@@ -46,13 +46,27 @@ export async function buildImplementationPack(projectRoot, manifestId) {
   // Also load some train records for broader coverage
   const trainEntries = await loadSplitPartition(projectRoot, manifest.source_split_id, 'train');
 
+  // F3: a record the split promised (via source_split_id's train/test
+  // partitions) whose file was later deleted from records/ must not
+  // silently drop out of the implementation pack with no counter, no
+  // warning, no id recorded. loadRecord() returns null on ENOENT
+  // (lib/records.js); previously `if (!record) continue` was the entire
+  // handling at both loops below. WARN + ledger (not hard-fail): an
+  // implementation pack is an illustrative/example artifact, not the
+  // Law-4 reproducibility-guaranteeing one (export.js and
+  // training-packages.js are, and hard-fail on the identical situation).
+  const missingRecords = [];
+
   // Build prompt examples — per-lane best records
   const promptExamples = [];
   const laneExamples = new Map();
 
   for (const entry of [...testEntries, ...trainEntries.slice(0, 50)]) {
     const record = await loadRecord(recordsDir, entry.record_id);
-    if (!record) continue;
+    if (!record) {
+      missingRecords.push({ record_id: entry.record_id, stage: 'implementation-pack', source: 'prompt-examples' });
+      continue;
+    }
     if (record.judgment?.status !== 'approved') continue;
 
     const prompt = record.provenance?.prompt || '';
@@ -85,10 +99,26 @@ export async function buildImplementationPack(projectRoot, manifestId) {
   const knownFailures = [];
   const allFiles = (await readdir(recordsDir)).filter(f => f.endsWith('.json')).sort();
   let failCount = 0;
+  // F4: adopt the DB-003 pattern already proven in snapshot.js's
+  // createSnapshot (and mirrored in eval-pack.js's buildEvalPack) — this
+  // loop was the one place left in the codebase still doing a bare
+  // JSON.parse per record file with no try/catch. One truncated/corrupt
+  // record file threw a filename-free SyntaxError here and discarded the
+  // prompt-examples work (the loop above) and the subject-continuity work
+  // (the loop below) this function had already computed, since every
+  // artifact is written to disk only at the very end of
+  // buildImplementationPack — skip, count, warn, continue instead.
+  const unreadable = [];
 
   for (const file of allFiles) {
     if (failCount >= 10) break;
-    const record = JSON.parse(await readFile(join(recordsDir, file), 'utf-8'));
+    let record;
+    try {
+      record = JSON.parse(await readFile(join(recordsDir, file), 'utf-8'));
+    } catch (err) {
+      unreadable.push({ record_id: file.replace(/\.json$/, ''), file, error: err.message });
+      continue;
+    }
     if (record.judgment?.status !== 'rejected') continue;
 
     const prompt = record.provenance?.prompt || '';
@@ -107,6 +137,15 @@ export async function buildImplementationPack(projectRoot, manifestId) {
     });
     failCount++;
   }
+  // F4: surface unreadable records loudly (DB-003 parity) — same shape,
+  // same warn() visibility as snapshot.js's createSnapshot.
+  if (unreadable.length > 0) {
+    const sample = unreadable.slice(0, 5).map(u => u.file).join(', ');
+    warn(
+      `implementation-pack: ${unreadable.length} record file(s) were unreadable and skipped` +
+      (unreadable.length > 5 ? ` (first 5: ${sample}, ...)` : ` (${sample})`),
+    );
+  }
 
   // Build subject continuity examples
   const subjectExamples = [];
@@ -114,12 +153,33 @@ export async function buildImplementationPack(projectRoot, manifestId) {
 
   for (const entry of [...testEntries, ...trainEntries]) {
     const record = await loadRecord(recordsDir, entry.record_id);
-    if (!record?.identity?.subject_name) continue;
+    // F3: keep "record file is missing" (a data-integrity problem worth a
+    // warning) distinct from "record loaded fine but simply has no
+    // identity.subject_name" (the normal, expected case for most records —
+    // not a missing-record situation). The original combined
+    // `!record?.identity?.subject_name` check could not tell these apart.
+    if (!record) {
+      missingRecords.push({ record_id: entry.record_id, stage: 'implementation-pack', source: 'subject-continuity' });
+      continue;
+    }
+    if (!record.identity?.subject_name) continue;
     const name = record.identity.subject_name;
     if (!bySubject.has(name)) bySubject.set(name, []);
     bySubject.get(name).push(record);
   }
 
+  // F3: warn once for both loops combined — the ledger records which
+  // loop(s) actually hit the miss via `source`, so the summary line stays
+  // useful even though it's a single warning for the whole pack build.
+  if (missingRecords.length > 0) {
+    const sample = missingRecords.slice(0, 10).map(m => `${m.record_id} (${m.source})`);
+    warn(
+      `implementation-pack: ${missingRecords.length} record(s) referenced by split "${manifest.source_split_id}" ` +
+      `could not be loaded from ${recordsDir}` +
+      (missingRecords.length > 10 ? ` — first 10: ${sample.join(', ')}, ...` : ` — ${sample.join(', ')}`),
+    );
+  }
+
   for (const [name, records] of [...bySubject].sort((a, b) => b[1].length - a[1].length).slice(0, 5)) {
     subjectExamples.push({
       subject_name: name,
@@ -138,17 +198,18 @@ export async function buildImplementationPack(projectRoot, manifestId) {
   };
 
   // Write implementation pack
-  const implId = generateImplId();
-  const implDir = join(projectRoot, 'training', 'implementations', implId);
-  // D-005: refuse to silently overwrite on ID collision.
-  if (existsSync(implDir)) {
-    throw inputError(
-      'IMPL_PACK_ID_COLLISION',
-      `Implementation pack directory already exists: ${implDir}`,
-      'Retry to generate a fresh implementation pack ID.',
-    );
-  }
-  await mkdir(implDir, { recursive: true });
+  // SDL-M10: atomically claim the implementation-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: implId, dir: implDir } = await claimIdDir(
+    join(projectRoot, 'training', 'implementations'),
+    generateImplId,
+    {
+      code: 'IMPL_PACK_ID_COLLISION',
+      message: 'Could not claim a unique implementation-pack ID — every candidate collided with an existing implementation-pack directory.',
+      hint: 'Retry; if this persists, another sdlab process may be creating implementation packs in a tight loop.',
+    },
+  );
 
   const implManifest = {
     // DB-001 / DB-006: stamp manifest schema version
@@ -163,7 +224,24 @@ export async function buildImplementationPack(projectRoot, manifestId) {
       known_failures: knownFailures.length,
       subject_examples: subjectExamples.length,
       lanes_covered: laneExamples.size,
+      // F3: how many split-referenced records could not be loaded while
+      // building this pack. 0 in the common case; see missing_records
+      // below for the actual ids.
+      missing_records: missingRecords.length,
+      // F4: how many record files (from the known-failures scan over ALL
+      // of records/) existed but threw on JSON.parse — distinct from
+      // missing_records above, which is "no file at all". 0 in the common
+      // case; see unreadable_records below for the actual files.
+      unreadable_records: unreadable.length,
     },
+    // F3: ledger of every record_id that failed to load while building
+    // this pack (mirrors the images_failed pattern export.js established
+    // at export time) — record_id + stage + which loop hit it, so an
+    // operator can trace it without re-diffing the split against records/.
+    missing_records: missingRecords,
+    // F4: ledger of record files that existed but failed to JSON.parse
+    // (DB-003 parity with snapshot.js's `errors` field).
+    unreadable_records: unreadable,
   };
 
   await writeFile(join(implDir, 'manifest.json'), JSON.stringify(implManifest, null, 2) + '\n');