@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/lib/adapters/comfyui-workflows.js

@@ -0,0 +1,163 @@
+/**
+ * ComfyUI workflow adapter — builds executable ComfyUI prompt graphs from briefs.
+ *
+ * The brief carries everything needed: prompt, negative, runtime plan,
+ * plus project defaults for checkpoint/LoRAs. This module translates
+ * that into a ComfyUI node graph.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { getRuntimeDir } from '../paths.js';
+
+// ─── Template registry ───────────────────────────────────────────
+
+/**
+ * List available workflow templates from runtime/comfyui/.
+ */
+export function listWorkflowTemplates() {
+  const dir = join(getRuntimeDir(), 'comfyui');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      const data = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+      return {
+        template_id: data.template_id,
+        label: data.label,
+        compatible_modes: data.compatible_modes || [],
+      };
+    });
+}
+
+/**
+ * Resolve a template for a given output mode.
+ * Returns 'txt2img-standard' for all standard modes.
+ * Throws if no template matches.
+ */
+export function resolveTemplateId(outputMode) {
+  const templates = listWorkflowTemplates();
+  const match = templates.find(t => t.compatible_modes.includes(outputMode));
+  if (match) return match.template_id;
+  // Default fallback for unknown modes
+  return 'txt2img-standard';
+}
+
+// ─── Graph builder ───────────────────────────────────────────────
+
+/**
+ * Build a ComfyUI prompt graph from a compiled brief + project config.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.brief — compiled brief from brief-compiler
+ * @param {Object} opts.projectDefaults — project.json defaults block
+ * @param {number} opts.seed — specific seed for this generation
+ * @returns {{ nodes: Object, saveNodeId: string }}
+ */
+export function buildWorkflowGraph({ brief, projectDefaults, seed }) {
+  const rp = brief.runtime_plan;
+  const defaults = projectDefaults;
+
+  const checkpoint = defaults.checkpoint;
+  const loras = defaults.loras || [];
+  const prompt = brief.prompt;
+  const negativePrompt = brief.negative_prompt;
+  const width = rp.width || defaults.width || 1024;
+  const height = rp.height || defaults.height || 1024;
+  const steps = rp.steps || defaults.steps || 30;
+  const cfg = rp.cfg || defaults.cfg || 6.5;
+  const sampler = rp.sampler || defaults.sampler || 'dpmpp_2m';
+  const scheduler = rp.scheduler || defaults.scheduler || 'karras';
+
+  const nodes = {};
+  let nextId = 1;
+
+  // Checkpoint loader
+  const ckptId = String(nextId++);
+  nodes[ckptId] = {
+    class_type: 'CheckpointLoaderSimple',
+    inputs: { ckpt_name: checkpoint },
+  };
+
+  let modelOut = [ckptId, 0];
+  let clipOut = [ckptId, 1];
+
+  // LoRA loaders (chained)
+  for (const lora of loras) {
+    const loraId = String(nextId++);
+    nodes[loraId] = {
+      class_type: 'LoraLoader',
+      inputs: {
+        model: modelOut,
+        clip: clipOut,
+        lora_name: lora.name,
+        strength_model: lora.weight,
+        strength_clip: lora.clip_weight ?? lora.weight,
+      },
+    };
+    modelOut = [loraId, 0];
+    clipOut = [loraId, 1];
+  }
+
+  // CLIP Text Encode — positive
+  const posId = String(nextId++);
+  nodes[posId] = {
+    class_type: 'CLIPTextEncode',
+    inputs: { text: prompt, clip: clipOut },
+  };
+
+  // CLIP Text Encode — negative
+  const negId = String(nextId++);
+  nodes[negId] = {
+    class_type: 'CLIPTextEncode',
+    inputs: { text: negativePrompt, clip: clipOut },
+  };
+
+  // Empty latent image
+  const latentId = String(nextId++);
+  nodes[latentId] = {
+    class_type: 'EmptyLatentImage',
+    inputs: { width, height, batch_size: 1 },
+  };
+
+  // KSampler
+  const samplerId = String(nextId++);
+  nodes[samplerId] = {
+    class_type: 'KSampler',
+    inputs: {
+      model: modelOut,
+      positive: [posId, 0],
+      negative: [negId, 0],
+      latent_image: [latentId, 0],
+      seed,
+      steps,
+      cfg,
+      sampler_name: sampler,
+      scheduler,
+      denoise: 1.0,
+    },
+  };
+
+  // VAE Decode
+  const vaeId = String(nextId++);
+  nodes[vaeId] = {
+    class_type: 'VAEDecode',
+    inputs: {
+      samples: [samplerId, 0],
+      vae: [ckptId, 2],
+    },
+  };
+
+  // Save Image
+  const saveId = String(nextId++);
+  nodes[saveId] = {
+    class_type: 'SaveImage',
+    inputs: {
+      images: [vaeId, 0],
+      filename_prefix: 'sdl_run',
+    },
+  };
+
+  return { nodes, saveNodeId: saveId };
+}

package/lib/adapters/diffusers-lora.js

@@ -68,8 +68,13 @@ export async function buildPackage({ packageDir, partitions, profile, manifest,
       const sourcePath = join(projectRoot, record.asset_path);
       if (!existsSync(sourcePath)) continue;
 
-      const filename = record.asset_path.split('/').pop();
-      const stem = filename.replace(/\.[^.]+$/, '');
+      // D-009: Name output files by record.id (not source basename) to
+      // avoid silent collisions when two records share a filename stem.
+      const sourceBasename = record.asset_path.split(/[\\/]/).pop();
+      const extMatch = sourceBasename.match(/\.[^.]+$/);
+      const ext = extMatch ? extMatch[0] : '';
+      const filename = `${record.id}${ext}`;
+      const stem = record.id;
       const destPath = join(datasetDir, filename);
 
       try {

package/lib/adapters/generic-image-caption.js

@@ -57,7 +57,12 @@ export async function buildPackage({ packageDir, partitions, profile, manifest,
       const sourcePath = join(projectRoot, record.asset_path);
       if (!existsSync(sourcePath)) continue;
 
-      const filename = record.asset_path.split('/').pop();
+      // D-009: Name output files by record.id (not source basename) to
+      // avoid silent collisions when two records share a filename stem.
+      const sourceBasename = record.asset_path.split(/[\\/]/).pop();
+      const extMatch = sourceBasename.match(/\.[^.]+$/);
+      const ext = extMatch ? extMatch[0] : '';
+      const filename = `${record.id}${ext}`;
       const destPath = join(datasetDir, filename);
 
       try {

package/lib/args.js

@@ -10,12 +10,14 @@
  */
 
 import { warnDeprecated } from './deprecation.js';
+import { inputError } from './errors.js';
 
 /**
  * @typedef {Object} ArgSpec
  * @property {Object<string, {type: 'string'|'boolean', default?: any, alias?: string}>} flags
  * @property {string[]} [positionals] - names for positional args (in order)
  * @property {Object<string, string>} [deprecated] - old flag name → new flag name
+ * @property {boolean} [allowUnknown] - permit unknown flags (default false)
  */
 
 /**
@@ -28,6 +30,22 @@ export function parseArgs(argv, spec = {}) {
   const flagDefs = spec.flags || {};
   const deprecated = spec.deprecated || {};
   const positionalNames = spec.positionals || [];
+  const allowUnknown = spec.allowUnknown === true;
+
+  // Build alias index once; detect duplicate aliases.
+  const aliasIndex = {};
+  for (const [name, def] of Object.entries(flagDefs)) {
+    if (def && def.alias) {
+      if (aliasIndex[def.alias]) {
+        throw inputError(
+          'INPUT_DUPLICATE_ALIAS',
+          `Duplicate CLI alias "-${def.alias}" (on both "${aliasIndex[def.alias]}" and "${name}")`,
+          'Fix the flag spec: each alias must be unique.'
+        );
+      }
+      aliasIndex[def.alias] = name;
+    }
+  }
 
   const flags = {};
   const positionals = [];
@@ -61,22 +79,44 @@ export function parseArgs(argv, spec = {}) {
         key = deprecated[key];
       }
 
-      // Handle short aliases defined in flagDefs
-      const canonical = Object.entries(flagDefs).find(([, def]) => def.alias === key);
-      if (canonical) key = canonical[0];
+      // Handle short aliases defined in flagDefs (O(1) via prebuilt index)
+      if (aliasIndex[key]) key = aliasIndex[key];
 
       // Normalize kebab-case to camelCase for lookup
       const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
       const def = flagDefs[key] || flagDefs[camelKey];
 
+      if (!def && !allowUnknown) {
+        const known = Object.keys(flagDefs);
+        const suggestion = findClosest(key, known);
+        const hint = suggestion
+          ? `Did you mean --${suggestion}? (Run with --help to see all supported flags.)`
+          : 'Run with --help to see supported flags.';
+        throw inputError(
+          'UNKNOWN_FLAG',
+          `Unknown flag: --${key}`,
+          hint
+        );
+      }
+
+      const storeKey = key in flagDefs ? key : camelKey;
+
       if (def?.type === 'boolean') {
-        flags[key in flagDefs ? key : camelKey] = true;
+        flags[storeKey] = true;
       } else if (value !== undefined) {
-        flags[key in flagDefs ? key : camelKey] = value;
+        flags[storeKey] = value;
       } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
-        flags[key in flagDefs ? key : camelKey] = argv[++i];
+        flags[storeKey] = argv[++i];
+      } else if (def && def.type === 'string') {
+        // String flag with no value — that's a user error.
+        throw inputError(
+          'INPUT_MISSING_VALUE',
+          `Flag --${key} requires a value.`,
+          `Pass a value after --${key}.`
+        );
       } else {
-        flags[key in flagDefs ? key : camelKey] = true;
+        // Unknown flag in allowUnknown mode (no def), treat as boolean-style.
+        flags[storeKey] = true;
       }
     } else {
       positionals.push(arg);
@@ -95,12 +135,159 @@ export function parseArgs(argv, spec = {}) {
 
 /**
  * Extract the --project (or deprecated --game) value from argv.
- * Convenience for scripts that just need the project name.
+ *
+ * Returns the explicit value if given. If missing, falls back to
+ * 'star-freight' with a LOUD stderr warning — the fallback exists for
+ * backward compatibility with v2.x scripts but should never be relied on
+ * in new code or documentation.
+ *
+ * Set SDLAB_QUIET_FALLBACK=1 to silence the warning in scripted pipelines.
  */
 export function getProjectName(argv) {
-  const { flags } = parseArgs(argv, {
-    flags: { project: { type: 'string', default: 'star-freight' } },
-    deprecated: { game: 'project' },
-  });
-  return flags.project;
+  // Manual parse (avoids triggering UNKNOWN_FLAG on caller's sibling flags)
+  let explicit = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project' || a === '--game') {
+      if (a === '--game') warnDeprecated('game', 'project');
+      explicit = argv[i + 1];
+      break;
+    }
+    if (a.startsWith('--project=')) { explicit = a.slice('--project='.length); break; }
+    if (a.startsWith('--game=')) { warnDeprecated('game', 'project'); explicit = a.slice('--game='.length); break; }
+  }
+  if (explicit) return explicit;
+
+  // Backward compat: fall back to star-freight but warn LOUDLY.
+  if (process.env.SDLAB_QUIET_FALLBACK !== '1') {
+    process.stderr.write(
+      '\x1b[33m⚠ No --project specified, falling back to "star-freight".\x1b[0m\n' +
+      '\x1b[33m  Use --project <name> to be explicit (set SDLAB_QUIET_FALLBACK=1 to silence).\x1b[0m\n'
+    );
+  }
+  return 'star-freight';
+}
+
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Small hand-rolled implementation — O(m*n) time, O(min(m,n)) space.
+ */
+export function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a) return b.length;
+  if (!b) return a.length;
+  // Keep the shorter string in the inner loop for better memory.
+  if (a.length > b.length) { const t = a; a = b; b = t; }
+  const prev = new Array(a.length + 1);
+  const curr = new Array(a.length + 1);
+  for (let i = 0; i <= a.length; i++) prev[i] = i;
+  for (let j = 1; j <= b.length; j++) {
+    curr[0] = j;
+    for (let i = 1; i <= a.length; i++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[i] = Math.min(
+        curr[i - 1] + 1,      // insertion
+        prev[i] + 1,          // deletion
+        prev[i - 1] + cost    // substitution
+      );
+    }
+    for (let i = 0; i <= a.length; i++) prev[i] = curr[i];
+  }
+  return prev[a.length];
+}
+
+/**
+ * Find the nearest match to `needle` in `candidates` within `maxDistance`.
+ * Returns the closest candidate, or null if nothing qualifies.
+ * Used for "did you mean?" hints on unknown flags / commands.
+ */
+export function findClosest(needle, candidates, maxDistance = 2) {
+  if (!needle || !Array.isArray(candidates) || candidates.length === 0) return null;
+  // Short inputs have little tolerance.
+  const cap = needle.length <= 3 ? 1 : maxDistance;
+  let best = null;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    if (typeof c !== 'string') continue;
+    const d = levenshtein(needle.toLowerCase(), c.toLowerCase());
+    if (d < bestDist && d <= cap) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return best;
+}
+
+/**
+ * Parse a CLI value as a number with NaN validation.
+ * @param {string} name - flag name, for error messages
+ * @param {string|number|undefined} value - the raw flag value
+ * @param {{min?:number,max?:number,int?:boolean,default?:number}} opts
+ */
+export function parseNumberFlag(name, value, opts = {}) {
+  if (value === undefined || value === null || value === '') {
+    if (opts.default !== undefined) return opts.default;
+    throw inputError(
+      'INPUT_MISSING_VALUE',
+      `Flag --${name} requires a numeric value.`,
+      `Example: --${name} 4`
+    );
+  }
+  const n = opts.int ? Number.parseInt(String(value), 10) : Number.parseFloat(String(value));
+  if (!Number.isFinite(n)) {
+    throw inputError(
+      'INPUT_BAD_NUMBER',
+      `Flag --${name} expected a number, got "${value}".`,
+      `Pass a ${opts.int ? 'whole number' : 'number'} instead.`
+    );
+  }
+  if (opts.min !== undefined && n < opts.min) {
+    throw inputError('INPUT_OUT_OF_RANGE', `--${name} must be ≥ ${opts.min}, got ${n}.`);
+  }
+  if (opts.max !== undefined && n > opts.max) {
+    throw inputError('INPUT_OUT_OF_RANGE', `--${name} must be ≤ ${opts.max}, got ${n}.`);
+  }
+  return n;
+}
+
+/**
+ * Read an indexed-next-arg value from argv but refuse to consume a flag-like token.
+ * Useful for legacy scripts still using indexOf/argv[idx+1] patterns — wraps the access
+ * with a safety check so `--source --manifest` doesn't silently treat `--manifest` as a path.
+ */
+export function takeFlagValue(argv, flagName) {
+  const idx = argv.indexOf(`--${flagName}`);
+  if (idx < 0) {
+    // Try --flag=value form
+    const eq = argv.find(a => a.startsWith(`--${flagName}=`));
+    if (eq) return eq.slice(`--${flagName}=`.length);
+    return undefined;
+  }
+  const nxt = argv[idx + 1];
+  if (nxt === undefined) {
+    throw inputError('INPUT_MISSING_VALUE', `Flag --${flagName} requires a value.`);
+  }
+  if (typeof nxt === 'string' && nxt.startsWith('--')) {
+    throw inputError(
+      'INPUT_MISSING_VALUE',
+      `Flag --${flagName} is missing its value (got another flag: ${nxt}).`,
+      `Pass a value after --${flagName}.`
+    );
+  }
+  return nxt;
+}
+
+/**
+ * Strip the subcommand token at position argv[firstPositionalIndex] by slicing,
+ * avoiding the value-based filter bug where a project/id that matches the
+ * subcommand string would be stripped too.
+ *
+ * Returns the args AFTER the first non-flag token. If no non-flag token is
+ * found, returns a copy of argv.
+ */
+export function sliceAfterSubcommand(argv, subcommand) {
+  if (subcommand == null) return argv.slice();
+  const idx = argv.indexOf(subcommand);
+  if (idx < 0) return argv.slice();
+  return argv.slice(idx + 1);
 }

package/lib/batch-compiler.js

@@ -0,0 +1,122 @@
+/**
+ * Batch compiler — expand a batch mode into multiple coordinated briefs.
+ *
+ * Takes a batch mode + subject/theme inputs and produces one brief per
+ * variant slot, each with controlled prompt/negative/runtime deltas
+ * on top of a base compiled brief from 4A.
+ */
+
+import { compileBrief, saveCompiledBrief } from './brief-compiler.js';
+import { getBatchMode } from './batch-modes.js';
+import { getWorkflowProfile } from './workflow-profiles.js';
+import { inputError } from './errors.js';
+
+/**
+ * Apply slot-level deltas to a base brief.
+ *
+ * @param {Object} baseBrief — compiled brief from brief-compiler
+ * @param {Object} slot — variant_plan slot definition
+ * @returns {Object} — modified brief (new object, base untouched)
+ */
+export function applySlotDelta(baseBrief, slot) {
+  const modified = JSON.parse(JSON.stringify(baseBrief));
+
+  // Prompt additions — append to the end
+  if (slot.prompt_additions?.length > 0) {
+    modified.prompt = `${modified.prompt}, ${slot.prompt_additions.join(', ')}`;
+  }
+
+  // Negative additions — append without duplicating (token-exact match)
+  if (slot.negative_additions?.length > 0) {
+    const existingLower = modified.negative_prompt
+      .toLowerCase()
+      .split(',')
+      .map(s => s.trim())
+      .filter(s => s.length > 0);
+    const additions = slot.negative_additions.filter(
+      n => !existingLower.includes(n.toLowerCase().trim())
+    );
+    if (additions.length > 0) {
+      modified.negative_prompt = `${modified.negative_prompt}, ${additions.join(', ')}`;
+    }
+  }
+
+  // Runtime overrides
+  if (slot.runtime_overrides) {
+    for (const [key, val] of Object.entries(slot.runtime_overrides)) {
+      if (modified.runtime_plan && val !== undefined) {
+        modified.runtime_plan[key] = val;
+      }
+    }
+  }
+
+  // Tag the slot
+  modified._batch_slot_id = slot.slot_id;
+  modified._batch_slot_label = slot.label;
+
+  return modified;
+}
+
+/**
+ * Compile a full batch — one brief per variant slot.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot — absolute project path
+ * @param {string} opts.projectId — project name
+ * @param {string} opts.modeId — batch mode ID
+ * @param {string} [opts.subjectId] — subject for subject-driven modes
+ * @param {string} [opts.theme] — theme label for environment modes
+ * @param {string} [opts.assetRef] — optional training asset reference
+ * @param {Object} [opts.overrides] — CLI runtime overrides
+ * @returns {Promise<{ mode: Object, baseBrief: Object, slotBriefs: Object[] }>}
+ */
+export async function compileBatch({
+  projectRoot,
+  projectId,
+  modeId,
+  subjectId,
+  theme,
+  assetRef,
+  overrides = {},
+}) {
+  // Load batch mode
+  const mode = getBatchMode(projectRoot, modeId);
+
+  // Enforce subject mode
+  const subjectMode = mode.subject_mode || 'optional';
+  if (subjectMode === 'required' && !subjectId) {
+    throw inputError(
+      'BATCH_SUBJECT_REQUIRED',
+      `Batch mode "${modeId}" requires a subject`,
+      'Add --subject <id> to the command.'
+    );
+  }
+  if (subjectMode === 'forbidden' && subjectId) {
+    throw inputError(
+      'BATCH_SUBJECT_FORBIDDEN',
+      `Batch mode "${modeId}" does not accept a subject`,
+      'Remove --subject from the command.'
+    );
+  }
+
+  // Compile the base brief using the mode's base workflow
+  // Force output_count to 1 — each slot produces one primary candidate
+  const baseBrief = await compileBrief({
+    projectRoot,
+    projectId,
+    workflowId: mode.base_workflow_id,
+    subjectId,
+    assetRef,
+    overrides: { ...overrides, output_count: 1 },
+  });
+
+  // Add theme to prompt if provided
+  if (theme) {
+    baseBrief.prompt = `${baseBrief.prompt}, ${theme}`;
+  }
+
+  // Expand into slot briefs
+  const slotBriefs = mode.variant_plan.map(slot => applySlotDelta(baseBrief, slot));
+
+  return { mode, baseBrief, slotBriefs };
+}

package/lib/batch-modes.js

@@ -0,0 +1,111 @@
+/**
+ * Batch modes — load, validate, list batch production mode definitions.
+ *
+ * A batch mode is a production recipe above the single-brief level.
+ * It defines what deliverable is being made, how many coordinated briefs
+ * are needed, and how results should be assembled.
+ */
+
+import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { getProjectRoot } from './paths.js';
+import { inputError } from './errors.js';
+
+const VALID_BATCH_TYPES = [
+  'expression_sheet', 'variant_board', 'moodboard',
+  'silhouette_grid', 'continuity_pack',
+];
+const VALID_LAYOUTS = ['grid', 'moodboard', 'sheet', 'strip'];
+const VALID_SUBJECT_MODES = ['required', 'optional', 'forbidden'];
+
+/**
+ * Return the batch modes directory for a project.
+ */
+export function getBatchModesDir(projectRoot) {
+  return join(projectRoot, 'workflows', 'batch-modes');
+}
+
+/**
+ * List all batch modes for a project.
+ */
+export function listBatchModes(projectRoot) {
+  const dir = getBatchModesDir(projectRoot);
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      const data = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+      return {
+        mode_id: data.mode_id,
+        label: data.label,
+        batch_type: data.batch_type,
+        base_workflow_id: data.base_workflow_id,
+        subject_mode: data.subject_mode || 'optional',
+        slot_count: data.variant_plan?.length || 0,
+      };
+    })
+    .sort((a, b) => a.mode_id.localeCompare(b.mode_id));
+}
+
+/**
+ * Load a batch mode by ID.
+ */
+export function getBatchMode(projectRoot, modeId) {
+  const dir = getBatchModesDir(projectRoot);
+  const filePath = join(dir, `${modeId}.json`);
+
+  if (!existsSync(filePath)) {
+    throw inputError(
+      'BATCH_MODE_NOT_FOUND',
+      `Batch mode "${modeId}" not found`,
+      `Check workflows/batch-modes/ or run: sdlab batch list`
+    );
+  }
+
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+/**
+ * Validate a batch mode definition.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateBatchMode(mode) {
+  const errors = [];
+
+  if (!mode.mode_id) errors.push('missing mode_id');
+  if (!mode.label) errors.push('missing label');
+  if (!mode.base_workflow_id) errors.push('missing base_workflow_id');
+
+  if (!mode.batch_type || !VALID_BATCH_TYPES.includes(mode.batch_type)) {
+    errors.push(`invalid batch_type "${mode.batch_type}" — must be one of: ${VALID_BATCH_TYPES.join(', ')}`);
+  }
+
+  if (mode.subject_mode && !VALID_SUBJECT_MODES.includes(mode.subject_mode)) {
+    errors.push(`invalid subject_mode "${mode.subject_mode}"`);
+  }
+
+  if (!Array.isArray(mode.variant_plan) || mode.variant_plan.length === 0) {
+    errors.push('variant_plan must be a non-empty array');
+  } else {
+    const slotIds = new Set();
+    for (const slot of mode.variant_plan) {
+      if (!slot.slot_id) errors.push('variant slot missing slot_id');
+      if (!slot.label) errors.push('variant slot missing label');
+      if (slot.slot_id && slotIds.has(slot.slot_id)) {
+        errors.push(`duplicate slot_id "${slot.slot_id}"`);
+      }
+      slotIds.add(slot.slot_id);
+    }
+  }
+
+  if (!mode.assembly) {
+    errors.push('missing assembly');
+  } else {
+    if (!mode.assembly.layout || !VALID_LAYOUTS.includes(mode.assembly.layout)) {
+      errors.push(`invalid assembly.layout "${mode.assembly?.layout}" — must be one of: ${VALID_LAYOUTS.join(', ')}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}