@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/verify-chain.js

@@ -0,0 +1,367 @@
+/**
+ * End-to-end offline provenance chain verifier (G9, §2.2–§2.3).
+ *
+ * Walks every link required for CC-BY-4.0 release eligibility:
+ *   1. owner_and_licence (G5): owner === "mcp-tool-shop", licence === "CC-BY-4.0", ai_assisted_disclosure === true
+ *   2. canon_link (G6): canon_sha, entry_id, entry_sha256 match canon-build/<canon_sha>/manifest.json per_entity_hashes
+ *   3. run_manifest_link (§2.2.1): run_id, seed, prompt/prompt_sha256, comfy_workflow_sha match runs/<run_id>/manifest.json, and image exists
+ *   4. model_licences (G4): all models and LoRAs in pinning have cleared SPDX licence_id, non-empty licence_url, and date_read
+ *   5. quarantine_guard (§2.2.5): no reference to held Portlight data (`plsvessel`, `nano-banana`)
+ *   6. verdict_separation (§2.2.6): approved records cite a reviewer/judge distinct from the generator model
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { STUDIO_OWNER, STUDIO_LICENCE } from './records.js';
+import {
+  isClearedLicenceEntry,
+  isQuarantinedName,
+  hasModelSha256,
+  normalizeModelFamilyKey,
+} from './model-licences.js';
+
+function isSafeRelativeAssetPath(projectRoot, assetPath) {
+  if (!assetPath || typeof assetPath !== 'string') return false;
+  const absRoot = resolve(projectRoot);
+  const absAsset = resolve(projectRoot, assetPath);
+  const rel = relative(absRoot, absAsset);
+  return Boolean(rel && !rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/**
+ * Verify all provenance links for a single record object against on-disk manifests.
+ */
+export function verifyRecordProvenance(projectRoot, record) {
+  const recordId = record?.id || record?.record_id || '<unknown>';
+  const failures = [];
+  const links = {
+    owner_and_licence: 'pass',
+    canon_link: 'pass',
+    run_manifest_link: 'pass',
+    model_licences: 'pass',
+    quarantine_guard: 'pass',
+    verdict_separation: 'pass',
+  };
+
+  function fail(link, code, message) {
+    links[link] = 'fail';
+    failures.push({ record_id: recordId, link, code, message });
+  }
+
+  // 1. G5: Owner and CC-BY-4.0 licence stamp
+  const owner = record?.owner ?? record?.rights?.owner ?? null;
+  const licence = record?.licence ?? record?.rights?.licence ?? null;
+  const disclosure = record?.rights?.ai_assisted_disclosure === true;
+  if (owner !== STUDIO_OWNER || licence !== STUDIO_LICENCE || !disclosure) {
+    fail(
+      'owner_and_licence',
+      'MISSING_OWNER_OR_LICENCE',
+      `Record "${recordId}" must carry owner="${STUDIO_OWNER}", licence="${STUDIO_LICENCE}", and rights.ai_assisted_disclosure=true (got owner=${JSON.stringify(owner)}, licence=${JSON.stringify(licence)}, disclosure=${JSON.stringify(disclosure)})`,
+    );
+  }
+
+  const genProv =
+    record?.generation_provenance ||
+    record?.provenance?.generation_provenance ||
+    record?.provenance ||
+    {};
+
+  // 2. G6: Canon link (canon_sha, entry_id, entry_sha256 -> canon-build/<canon_sha>/manifest.json)
+  const canonSha = record?.canon?.canon_sha ?? genProv?.canon_sha ?? null;
+  const entryId = record?.canon?.entry_id ?? genProv?.entry_id ?? null;
+  const entrySha256 = record?.canon?.entry_sha256 ?? genProv?.entry_sha256 ?? null;
+
+  if (!canonSha || !entryId || !entrySha256) {
+    fail(
+      'canon_link',
+      'BROKEN_CANON_LINK',
+      `Record "${recordId}" is missing canon link fields (canon_sha=${canonSha}, entry_id=${entryId}, entry_sha256=${entrySha256})`,
+    );
+  } else {
+    const dirName = String(canonSha).replace(/:/g, '-');
+    const canonManifestPath = existsSync(join(projectRoot, 'canon-build', String(canonSha), 'manifest.json'))
+      ? join(projectRoot, 'canon-build', String(canonSha), 'manifest.json')
+      : join(projectRoot, 'canon-build', dirName, 'manifest.json');
+    if (!existsSync(canonManifestPath)) {
+      fail(
+        'canon_link',
+        'BROKEN_CANON_LINK',
+        `Canon build manifest not found at canon-build/${canonSha}/manifest.json for record "${recordId}"`,
+      );
+    } else {
+      try {
+        const canonManifest = JSON.parse(readFileSync(canonManifestPath, 'utf-8'));
+        const hashes = canonManifest?.per_entity_hashes || {};
+        const bareId = String(entryId).includes('/') ? String(entryId).split('/').pop() : null;
+        const expectedSha = hashes[entryId] ?? (bareId ? hashes[bareId] : undefined);
+        if (!expectedSha || expectedSha !== entrySha256) {
+          fail(
+            'canon_link',
+            'BROKEN_CANON_LINK',
+            `Record "${recordId}" entry_sha256 (${entrySha256}) does not match canon-build/${canonSha}/manifest.json per_entity_hashes["${entryId}"] (${expectedSha || 'missing'})`,
+          );
+        }
+      } catch (err) {
+        fail(
+          'canon_link',
+          'BROKEN_CANON_LINK',
+          `Canon build manifest canon-build/${canonSha}/manifest.json could not be parsed: ${err.message}`,
+        );
+      }
+    }
+  }
+
+  // 3. §2.2.1: Run manifest link + workflow sha + image existence
+  const runId = genProv?.run_id ?? null;
+  const recWorkflowSha = genProv?.comfy_workflow_sha ?? record?.provenance?.pinning?.comfy_workflow_sha ?? null;
+  const hasSeed = Number.isFinite(genProv?.seed);
+  const hasPrompt =
+    (typeof genProv?.prompt === 'string' && genProv.prompt.length > 0) ||
+    (typeof genProv?.prompt_sha256 === 'string' && genProv.prompt_sha256.length > 0);
+
+  let runManifest = null;
+  if (!runId || !recWorkflowSha || !hasSeed || !hasPrompt) {
+    fail(
+      'run_manifest_link',
+      'BROKEN_RUN_MANIFEST_LINK',
+      `Record "${recordId}" provenance is missing run_id (${runId}), comfy_workflow_sha (${recWorkflowSha}), seed (${genProv?.seed}), or prompt`,
+    );
+  } else {
+    const runManifestPath = join(projectRoot, 'runs', String(runId), 'manifest.json');
+    if (!existsSync(runManifestPath)) {
+      fail(
+        'run_manifest_link',
+        'BROKEN_RUN_MANIFEST_LINK',
+        `Run manifest runs/${runId}/manifest.json not found for record "${recordId}"`,
+      );
+    } else {
+      try {
+        runManifest = JSON.parse(readFileSync(runManifestPath, 'utf-8'));
+        const manifestWfSha = runManifest?.pinning?.comfy_workflow_sha ?? null;
+        if (!manifestWfSha || manifestWfSha !== recWorkflowSha) {
+          fail(
+            'run_manifest_link',
+            'BROKEN_RUN_MANIFEST_LINK',
+            `Record "${recordId}" comfy_workflow_sha (${recWorkflowSha}) does not match runs/${runId}/manifest.json (${manifestWfSha})`,
+          );
+        }
+      } catch (err) {
+        fail(
+          'run_manifest_link',
+          'BROKEN_RUN_MANIFEST_LINK',
+          `Run manifest runs/${runId}/manifest.json could not be parsed: ${err.message}`,
+        );
+      }
+    }
+  }
+
+  const assetPath = record?.asset_path ?? record?.image_path ?? null;
+  if (!isSafeRelativeAssetPath(projectRoot, assetPath) || !existsSync(join(projectRoot, assetPath))) {
+    fail(
+      'run_manifest_link',
+      'BROKEN_RUN_MANIFEST_LINK',
+      `Record "${recordId}" asset_path (${assetPath}) does not exist inside the project`,
+    );
+  }
+
+  // 4. G4: Model and LoRA licences and sha256 digests
+  const pinning = runManifest?.pinning ?? record?.provenance?.pinning ?? null;
+  const modelEntries = Object.entries(pinning?.models || {}).map(([role, entry]) => ({ role, ...entry }));
+  const loraEntries = (pinning?.loras || []).map((entry, idx) => ({ role: `lora[${idx}]`, ...entry }));
+  const allWeightEntries = [...modelEntries, ...loraEntries];
+
+  const recModelLicences =
+    record?.generation_provenance?.model_licences ?? genProv?.model_licences ?? null;
+  const recModelEntries = recModelLicences
+    ? Object.entries(recModelLicences.models || {}).map(([role, entry]) => ({
+        role: `generation_provenance.model_licences.models.${role}`,
+        ...entry,
+      }))
+    : [];
+  const recLoraEntries = recModelLicences
+    ? (recModelLicences.loras || []).map((entry, idx) => ({
+        role: `generation_provenance.model_licences.loras[${idx}]`,
+        ...entry,
+      }))
+    : [];
+  const allCheckedEntries = [...allWeightEntries, ...recModelEntries, ...recLoraEntries];
+
+  if (!pinning || allWeightEntries.length === 0) {
+    fail(
+      'model_licences',
+      'UNLICENSED_OR_EXCLUDED_MODEL',
+      `Record "${recordId}" has no pinned model weights to verify licences against`,
+    );
+  } else {
+    const missingShaWeights = allCheckedEntries.filter((entry) => !hasModelSha256(entry));
+    if (
+      record?.generation_provenance &&
+      (!recModelLicences || recModelEntries.length < modelEntries.length || recLoraEntries.length < loraEntries.length)
+    ) {
+      missingShaWeights.push({
+        role: 'generation_provenance.model_licences',
+        name: '<missing>',
+      });
+    }
+    if (missingShaWeights.length > 0) {
+      const shaDesc = missingShaWeights
+        .map((w) => `${w.role}:${w.name || '<unnamed>'}`)
+        .join(', ');
+      fail(
+        'model_licences',
+        'MISSING_MODEL_SHA256',
+        `Record "${recordId}" is missing a non-empty sha256 for model/LoRA weights: ${shaDesc}`,
+      );
+    }
+
+    const invalidLicenceWeights = allCheckedEntries.filter(
+      (entry) => !isClearedLicenceEntry(entry, { requireSha256: false }),
+    );
+    if (
+      invalidLicenceWeights.length > 0 ||
+      (missingShaWeights.length === 0 &&
+        (pinning.cc_by_4_eligible === false || recModelLicences?.cc_by_4_eligible === false))
+    ) {
+      const desc = invalidLicenceWeights
+        .map((w) => `${w.role}:${w.name || '<unnamed>'}(licence=${w.licence_id || 'missing'})`)
+        .join(', ');
+      fail(
+        'model_licences',
+        'UNLICENSED_OR_EXCLUDED_MODEL',
+        `Record "${recordId}" uses unlicensed or excluded model/LoRA weights: ${desc || 'cc_by_4_eligible=false'}`,
+      );
+    }
+  }
+
+  // 5. §2.2.5: Quarantine guard (no held Portlight data / plsvessel / nano-banana)
+  const serializedChain = JSON.stringify({ record, runManifest });
+  if (isQuarantinedName(serializedChain)) {
+    fail(
+      'quarantine_guard',
+      'QUARANTINED_SOURCE_REFERENCED',
+      `Record "${recordId}" or its run manifest references quarantined/held data (plsvessel / nano-banana)`,
+    );
+  }
+
+  // 6. §2.2.6 / §12.5: Verdict separation (judge family != generator family on approved records)
+  if (record?.judgment && record.judgment.status === 'approved') {
+    const judge = record.judgment.judged_by_model || record.judgment.reviewed_by || null;
+    const generator =
+      record.judgment.generator_model ||
+      (pinning?.models?.unet?.name ? `qwen-image:${pinning.models.unet.name}` : null);
+    const judgeFamily = normalizeModelFamilyKey(judge);
+    const generatorFamily = normalizeModelFamilyKey(generator);
+    const sameFamily =
+      Boolean(judgeFamily && generatorFamily) &&
+      judgeFamily !== 'human' &&
+      judgeFamily !== 'rule-based' &&
+      judgeFamily === generatorFamily;
+    if (!judge || (generator && (judge === generator || sameFamily))) {
+      fail(
+        'verdict_separation',
+        'INVALID_VERDICT_PROVENANCE',
+        `Record "${recordId}" has an invalid approval verdict (judge=${judge} [${judgeFamily || 'none'}], generator=${generator} [${generatorFamily || 'none'}])`,
+      );
+    }
+  }
+
+  return {
+    record_id: recordId,
+    ok: failures.length === 0,
+    links,
+    failures,
+  };
+}
+
+/**
+ * Verify the provenance chain across a project (or a single record / snapshot).
+ */
+export async function verifyProvenanceChain(
+  projectRoot,
+  { recordId = null, snapshotId = null, allowEmpty = false } = {},
+) {
+  const recordsDir = join(projectRoot, 'records');
+  const recordsToCheck = [];
+  const globalFailures = [];
+
+  if (recordId) {
+    const recPath = join(recordsDir, `${recordId}.json`);
+    if (!existsSync(recPath)) {
+      globalFailures.push({
+        record_id: recordId,
+        link: 'scope',
+        code: 'RECORD_NOT_FOUND',
+        message: `Record "${recordId}" not found at records/${recordId}.json`,
+      });
+    } else {
+      recordsToCheck.push(JSON.parse(readFileSync(recPath, 'utf-8')));
+    }
+  } else if (snapshotId) {
+    const incPath = join(projectRoot, 'snapshots', snapshotId, 'included.jsonl');
+    if (!existsSync(incPath)) {
+      globalFailures.push({
+        record_id: null,
+        link: 'scope',
+        code: 'SNAPSHOT_NOT_FOUND',
+        message: `Snapshot "${snapshotId}" included.jsonl not found`,
+      });
+    } else {
+      const lines = readFileSync(incPath, 'utf-8')
+        .split('\n')
+        .filter((l) => l.trim())
+        .map((l) => JSON.parse(l));
+      for (const item of lines) {
+        const rid = item.record_id || item.id;
+        const recPath = join(recordsDir, `${rid}.json`);
+        if (!existsSync(recPath)) {
+          globalFailures.push({
+            record_id: rid,
+            link: 'scope',
+            code: 'RECORD_NOT_FOUND',
+            message: `Snapshot record "${rid}" not found at records/${rid}.json`,
+          });
+        } else {
+          recordsToCheck.push(JSON.parse(readFileSync(recPath, 'utf-8')));
+        }
+      }
+    }
+  } else if (existsSync(recordsDir)) {
+    const files = readdirSync(recordsDir)
+      .filter((f) => f.endsWith('.json'))
+      .sort();
+    for (const file of files) {
+      recordsToCheck.push(JSON.parse(readFileSync(join(recordsDir, file), 'utf-8')));
+    }
+  }
+
+  if (recordsToCheck.length === 0 && globalFailures.length === 0 && !allowEmpty) {
+    globalFailures.push({
+      record_id: null,
+      link: 'scope',
+      code: 'NO_RECORDS_IN_SCOPE',
+      message: 'No records found in scope to verify',
+    });
+  }
+
+  const results = [];
+  const failures = [...globalFailures];
+
+  for (const rec of recordsToCheck) {
+    const res = verifyRecordProvenance(projectRoot, rec);
+    results.push(res);
+    failures.push(...res.failures);
+  }
+
+  const passedCount = results.filter((r) => r.ok).length;
+  const failedCount = results.length - passedCount;
+
+  return {
+    ok: failures.length === 0,
+    project_root: projectRoot,
+    records_checked: results.length,
+    passed_count: passedCount,
+    failed_count: failedCount,
+    results,
+    failures,
+  };
+}

package/lib/workflow-profiles.js

@@ -12,6 +12,7 @@ import { readFile, readdir, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { getWorkflowProfilesDir } from './paths.js';
+import { inputError } from './errors.js';
 
 const REQUIRED_FIELDS = [
   'workflow_id', 'label', 'lane_id', 'output_mode', 'output_count',
@@ -105,12 +106,32 @@ export async function getWorkflowProfile(projectRoot, workflowId) {
   const dir = getWorkflowProfilesDir(projectRoot);
   const path = join(dir, `${workflowId}.json`);
   if (!existsSync(path)) {
-    throw new Error(`Workflow profile "${workflowId}" not found at ${path}`);
+    throw inputError(
+      'WORKFLOW_PROFILE_NOT_FOUND',
+      `Workflow profile "${workflowId}" not found at ${path}`,
+      'Check the workflow id, or run: sdlab workflow list'
+    );
+  }
+  // B06: JSON.parse used to run unguarded here, so a malformed profile file
+  // threw a raw, uncaught SyntaxError naming nothing. Wrapped in the same
+  // structured-error pattern lib/config.js's loadJsonFile already uses.
+  let data;
+  try {
+    data = JSON.parse(await readFile(path, 'utf-8'));
+  } catch (err) {
+    throw inputError(
+      'INPUT_INVALID_JSON',
+      `Failed to parse ${path}: ${err.message}`,
+      'Check the file for JSON syntax errors (trailing commas, unquoted keys, etc).'
+    );
   }
-  const data = JSON.parse(await readFile(path, 'utf-8'));
   const { valid, errors } = validateWorkflowProfile(data);
   if (!valid) {
-    throw new Error(`Workflow profile "${workflowId}" is invalid:\n  ${errors.join('\n  ')}`);
+    throw inputError(
+      'WORKFLOW_PROFILE_INVALID',
+      `Workflow profile "${workflowId}" is invalid:\n  ${errors.join('\n  ')}`,
+      'Fix the listed field(s) and try again.'
+    );
   }
   return data;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Canon-aligned dataset production and generation workbench — define visual rules, build versioned training data, compile production briefs, run local workflows, batch-produce, select winners, and re-ingest into your corpus",
   "type": "module",
   "bin": {
@@ -40,10 +40,11 @@
   "files": [
     "bin/",
     "lib/",
+    "runtime/",
     "scripts/",
     "!scripts/bulk-curate-*.js",
     "!scripts/curate-wave*.js",
-    "!scripts/migrate-records.js",
+    "!scripts/__pycache__/**",
     "templates/",
     "README.md",
     "LICENSE",
@@ -81,7 +82,7 @@
   "author": "mcp-tool-shop",
   "license": "MIT",
   "devDependencies": {
-    "c8": "^10.1.3"
+    "c8": "^12.0.0"
   },
   "dependencies": {
     "yaml": "^2.8.3"

package/runtime/comfyui/txt2img-qwen.json

@@ -0,0 +1,38 @@
+{
+  "template_id": "txt2img-qwen",
+  "label": "Text-to-Image — Qwen-Image (non-anime studio base)",
+  "description": "Qwen-Image txt2img pipeline: UNETLoader → CLIPLoader(qwen_image) + VAELoader → ModelSamplingAuraFlow(shift) → EmptySD3LatentImage → KSampler(euler/simple) → VAEDecode → SaveImage. The studio's verified NON-ANIME base (Apache-2.0). Selected by project/pack defaults.base = \"qwen-image\".",
+  "adapter_target": "comfyui",
+  "base": "qwen-image",
+  "compatible_modes": ["portrait_set", "expression_sheet", "variant_pack", "moodboard", "silhouette_sheet", "turnaround", "concept_art"],
+  "placeholders": {
+    "PROMPT": "Positive prompt text",
+    "NEGATIVE_PROMPT": "Negative prompt text (always include anime/cartoon/cel-shading terms — non-anime is non-negotiable)",
+    "UNET": "Diffusion model filename (default qwen_image_fp8_e4m3fn.safetensors)",
+    "CLIP": "Text encoder filename (default qwen_2.5_vl_7b_fp8_scaled.safetensors, loaded with type=qwen_image)",
+    "VAE": "VAE filename (default qwen_image_vae.safetensors)",
+    "SHIFT": "ModelSamplingAuraFlow shift (default 3.1)",
+    "WIDTH": "Image width (default 1024)",
+    "HEIGHT": "Image height (default 1024)",
+    "STEPS": "Sampling steps (default 22)",
+    "CFG": "Classifier-free guidance scale (default 3.5)",
+    "SAMPLER": "Sampler name (default euler)",
+    "SCHEDULER": "Scheduler name (default simple)",
+    "SEED": "Random seed"
+  },
+  "defaults": {
+    "unet": "qwen_image_fp8_e4m3fn.safetensors",
+    "clip": "qwen_2.5_vl_7b_fp8_scaled.safetensors",
+    "clip_type": "qwen_image",
+    "vae": "qwen_image_vae.safetensors",
+    "weight_dtype": "default",
+    "shift": 3.1,
+    "sampler": "euler",
+    "scheduler": "simple",
+    "steps": 22,
+    "cfg": 3.5,
+    "width": 1024,
+    "height": 1024
+  },
+  "notes": "Built programmatically — the JSON above is a reference. lib/adapters/comfyui-workflows.js buildQwenGraph() constructs the live graph; buildWorkflowGraph() and scripts/generate.js both route to it when base === 'qwen-image'. Node ids/wiring mirror scripts/qwen_generate.py for cross-runner reproducibility. NEVER substitute an anime checkpoint (Illustrious/Pony/Animagine/NoobAI) — see memory/feedback_no_anime.md."
+}

package/runtime/comfyui/txt2img-standard.json

@@ -0,0 +1,21 @@
+{
+  "template_id": "txt2img-standard",
+  "label": "Text-to-Image Standard",
+  "description": "Standard txt2img pipeline: checkpoint → LoRA chain → KSampler → VAEDecode → SaveImage.",
+  "adapter_target": "comfyui",
+  "compatible_modes": ["portrait_set", "expression_sheet", "variant_pack", "moodboard", "silhouette_sheet", "turnaround"],
+  "placeholders": {
+    "PROMPT": "Positive prompt text",
+    "NEGATIVE_PROMPT": "Negative prompt text",
+    "CHECKPOINT": "Checkpoint filename",
+    "WIDTH": "Image width",
+    "HEIGHT": "Image height",
+    "STEPS": "Sampling steps",
+    "CFG": "Classifier-free guidance scale",
+    "SAMPLER": "Sampler name",
+    "SCHEDULER": "Scheduler name",
+    "SEED": "Random seed",
+    "LORAS": "Array of {name, weight, clip_weight?} objects"
+  },
+  "notes": "This template is built programmatically — the JSON below is a reference. comfyui-workflows.js uses buildWorkflowGraph() to construct the graph dynamically with LoRA chain support."
+}

package/scripts/_resume.js

@@ -0,0 +1,62 @@
+/**
+ * _resume.js — internal helper module (NOT a CLI command; underscore prefix
+ * matches the existing scripts/_batch_cut.py / _seam_cutout.py convention
+ * for "helper, not dispatched by bin/sdlab.js").
+ *
+ * H5: generate.js was the only one of the four ComfyUI generator scripts
+ * that implemented `--resume` — skip an asset whose provenance record AND
+ * output image already exist on disk, WITHOUT skipping its seed slot, so a
+ * resumed run stays bit-identical to an uninterrupted one. generate-identity
+ * / generate-controlnet / generate-ipadapter had no --resume at all, which
+ * is expensive specifically for generate-identity (the priciest per-image
+ * generator in the pipeline): interrupting a 12-subject run after subject 9
+ * meant regenerating all 12 from scratch.
+ *
+ * Extracted here (once) so all four generators — and any future one — get
+ * the same discipline by importing it, instead of by copy-pasting the check
+ * next to generate.js's inline version. `lib/` is outside this fix's file
+ * ownership, so this lives under scripts/** instead; see the dispatch
+ * report for the full rationale.
+ *
+ * `requireRecord` exists because not every generator writes a provenance
+ * record: generate.js and generate-identity.js both write
+ * records/<id>.json, but generate-controlnet.js and generate-ipadapter.js
+ * are lighter-weight discovery scripts that only ever write the output PNG
+ * — they have no records/ write path at all. Requiring a record that a
+ * script structurally never writes would make --resume a permanent no-op
+ * for those two, which is worse than not having the flag. Pass
+ * `{ requireRecord: false }` for generators with no records/ write path.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * @param {string} projectRoot — GAME_ROOT
+ * @param {string} assetId — the record id / output filename stem (no extension)
+ * @param {Object} [opts]
+ * @param {boolean} [opts.requireRecord=true] — also require records/<id>.json
+ * @param {string} [opts.recordsSubdir='records']
+ * @param {string} [opts.candidatesSubdir='outputs/candidates']
+ * @returns {boolean} true when the asset is safe to skip on --resume
+ */
+export function isResumable(projectRoot, assetId, opts = {}) {
+  const requireRecord = opts.requireRecord !== false;
+  const candidatesSubdir = opts.candidatesSubdir || 'outputs/candidates';
+  const imagePath = join(projectRoot, candidatesSubdir, `${assetId}.png`);
+  if (!existsSync(imagePath)) return false;
+
+  if (!requireRecord) return true;
+
+  const recordsSubdir = opts.recordsSubdir || 'records';
+  const recordPath = join(projectRoot, recordsSubdir, `${assetId}.json`);
+  return existsSync(recordPath);
+}
+
+/**
+ * Print the standard "(resumed — skipped)" progress line — matches
+ * generate.js's console.log verbatim so all four generators read
+ * identically under --resume.
+ */
+export function logResumedSkip(index, total, assetId) {
+  console.log(`  [${index}/${total}] ${assetId} \x1b[2m(resumed — skipped)\x1b[0m`);
+}

package/scripts/_shared-args.js

@@ -0,0 +1,44 @@
+/**
+ * _shared-args.js — internal helper module (NOT a CLI command; underscore
+ * prefix matches the existing scripts/_batch_cut.py / _seam_cutout.py
+ * convention for "helper, not dispatched by bin/sdlab.js").
+ *
+ * H4 (second half): the five canon-*.js scripts (canon-build.js,
+ * canon-drift.js, canon-freeze.js, canon-freeze-status.js,
+ * canon-unfreeze.js) all use Node's built-in `util.parseArgs({strict:
+ * false})`. strict:false is there deliberately, so a bare positional
+ * argument (the entity id) isn't rejected — but it has a side effect: ANY
+ * unrecognized `--flag` is silently accepted too. A misspelled OPTIONAL
+ * flag (`--staus follow` instead of `--status follow`, `--jsn` instead of
+ * `--json`) produces no error and no warning — the option you meant to set
+ * just quietly keeps its default, and Node's parser stores the typo under
+ * ITS OWN key in `parsed.values`, never touching the one you meant.
+ *
+ * assertKnownOptions() closes that gap without giving up strict:false's
+ * positional leniency: after parsing, walk `parsed.values`'s keys — since
+ * every DECLARED option (default or explicit) and every UNDECLARED flag
+ * alike lands there — and reject any key outside the known option set.
+ * Mirrors lib/args.js's own UNKNOWN_FLAG shape (same code, same
+ * "Did you mean" hint via findClosest) so a typo on a canon-*.js flag reads
+ * identically to a typo anywhere else in the CLI.
+ */
+import { inputError } from '../lib/errors.js';
+import { findClosest } from '../lib/args.js';
+
+/**
+ * @param {Object} parsedValues — the `.values` object returned by
+ *   node:util's parseArgs({strict:false, ...})
+ * @param {Object} optionsSpec — the SAME `options` object passed to parseArgs
+ * @param {{ command?: string }} [opts] — command label for the hint text
+ */
+export function assertKnownOptions(parsedValues, optionsSpec, opts = {}) {
+  const known = new Set(Object.keys(optionsSpec));
+  for (const key of Object.keys(parsedValues || {})) {
+    if (known.has(key)) continue;
+    const suggestion = findClosest(key, [...known]);
+    const hint = suggestion
+      ? `Did you mean --${suggestion}? (Run "sdlab ${opts.command ? opts.command + ' ' : ''}--help" to see all supported flags.)`
+      : `Run "sdlab ${opts.command ? opts.command + ' ' : ''}--help" to see supported flags.`;
+    throw inputError('UNKNOWN_FLAG', `Unknown flag: --${key}`, hint);
+  }
+}