@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/adapters/ai-toolkit.js

@@ -1,5 +1,5 @@
 /**
- * Ostris ai-toolkit adapter.
+ * Ostris ai-toolkit adapter (Flux + Qwen-Image target families, DESIGN-v3 §3.3, §3.5, G12).
  *
  * Consumes canonical rows (per D6) and emits a training package ai-toolkit
  * can consume directly:
@@ -10,34 +10,113 @@
  *     metadata/<partition>.jsonl                   (audit rows)
  *     ai-toolkit-config.yaml                       (training config)
  *
- * Precondition: profile.target_family must be 'flux'. ai-toolkit does support
- * SDXL, but this adapter only emits Flux-shaped configs — callers using SDXL
- * should use diffusers-lora instead. Rejecting here keeps config output honest.
+ * Precondition: profile.target_family must be 'flux' or 'qwen-image'.
+ * Callers using SDXL should use diffusers-lora instead.
  */
 
+import { createHash } from 'node:crypto';
 import { writeFile, mkdir, symlink, copyFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import { existsSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 import { deriveStyleTrigger } from '../captions.js';
 import { groupRowsByPartition } from '../rows.js';
 import { inputError } from '../errors.js';
+import { assertSafeAssetPath, assertSafeId } from '../export.js';
+import { warn } from '../log.js';
+
+export const AI_TOOLKIT_UPSTREAM_ISSUE = 'https://github.com/ostris/ai-toolkit/issues/1087';
+
+export const SUPPORTED_AI_TOOLKIT_FAMILIES = Object.freeze(['flux', 'qwen-image']);
+
+const OVERRIDE_RELATIVE_PATH = 'scripts/colab/ai-toolkit-override-py315.txt';
+
+const HELD_DATA_TOKENS = Object.freeze([
+  'pls' + 'vessel',
+  'nano' + '_banana',
+  'nano' + '-banana',
+]);
+
+/**
+ * Load metadata and sha256 for `scripts/colab/ai-toolkit-override-py315.txt` (§3.5, G12).
+ *
+ * @returns {{ override_file: string, override_sha256: string, upstream_issue: string, packages: string[] }}
+ */
+export function getAiToolkitOverrideMetadata() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const fullPath = join(here, '..', '..', 'scripts', 'colab', 'ai-toolkit-override-py315.txt');
+  const raw = readFileSync(fullPath, 'utf-8');
+  const normalized = raw.replace(/\r\n/g, '\n');
+  const sha = 'sha256:' + createHash('sha256').update(normalized, 'utf-8').digest('hex');
+  const packages = normalized
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+  return {
+    override_file: OVERRIDE_RELATIVE_PATH,
+    override_sha256: sha,
+    upstream_issue: AI_TOOLKIT_UPSTREAM_ISSUE,
+    packages,
+  };
+}
+
+/**
+ * Enforce that held Portlight training data (the 336 Nano Banana-derived pairs)
+ * is never packaged or trained on (§1.2, §5.2, G12).
+ *
+ * @param {Object} opts
+ * @param {Object} [opts.profile]
+ * @param {Array<Object>} [opts.rows]
+ * @param {Object} [opts.manifest]
+ */
+export function assertNotHeldTrainingData({ profile = {}, rows = [], manifest = {} } = {}) {
+  const haystacks = [
+    profile?.profile_id,
+    profile?.trigger_override,
+    profile?.label,
+    manifest?.source_export_id,
+    ...(Array.isArray(rows)
+      ? rows.flatMap((r) => [r?.entity_id, r?.caption, r?.asset_path])
+      : []),
+  ]
+    .filter(Boolean)
+    .map((s) => String(s).toLowerCase());
+
+  for (const text of haystacks) {
+    for (const token of HELD_DATA_TOKENS) {
+      if (text.includes(token)) {
+        throw inputError(
+          'AI_TOOLKIT_HELD_DATA_FORBIDDEN',
+          `AI_TOOLKIT_HELD_DATA_FORBIDDEN: Refusing to build training package or config referencing held dataset token "${token}".`
+        );
+      }
+    }
+  }
+}
 
 /**
  * Build training package in ai-toolkit format from canonical rows.
  */
 export async function buildPackage({ packageDir, rows, profile, manifest, config, projectRoot, copy }) {
-  if (profile?.target_family !== 'flux') {
+  if (!SUPPORTED_AI_TOOLKIT_FAMILIES.includes(profile?.target_family)) {
     throw inputError(
       'ADAPTER_TARGET_FAMILY_MISMATCH',
-      `ai-toolkit adapter requires profile.target_family === 'flux' (got "${profile?.target_family}")`,
-      'Use diffusers-lora for SDXL targets, or set target_family: "flux" on the profile.',
+      `ai-toolkit adapter requires profile.target_family === 'flux' or 'qwen-image' (got "${profile?.target_family}")`,
+      'Use diffusers-lora for SDXL targets, or set target_family: "flux" or "qwen-image" on the profile.',
     );
   }
 
+  assertNotHeldTrainingData({ profile, rows, manifest });
+
   const partitioned = groupRowsByPartition(rows || []);
 
   let imageCount = 0;
+  // SDL-C5: per-row failure accounting (export.js DB-002 shape) — see
+  // generic-image-caption.js for the full rationale. A caught copy/symlink
+  // error must not silently drop the image, caption sidecar, AND metadata
+  // row together with zero logging.
+  const imagesFailed = [];
 
   for (const [partition, partitionRows] of Object.entries(partitioned)) {
     const datasetDir = join(packageDir, 'dataset', partition);
@@ -48,10 +127,21 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     const metadataRows = [];
 
     for (const row of partitionRows) {
-      if (!row.asset_path) continue;
+      if (!row.asset_path) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'missing_asset_path' });
+        continue;
+      }
+
+      // SDL-H5 / SDL-H6: defense-in-depth — see generic-image-caption.js
+      // for the full rationale. Throws (hard fail) on traversal/unsafe id;
+      // that is a security boundary, not an operational hiccup.
+      assertSafeId(row.entity_id, `row.entity_id in ai-toolkit adapter (partition "${partition}")`);
+      const sourcePath = assertSafeAssetPath(row.asset_path, projectRoot, row.entity_id);
 
-      const sourcePath = join(projectRoot, row.asset_path);
-      if (!existsSync(sourcePath)) continue;
+      if (!existsSync(sourcePath)) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'source_missing' });
+        continue;
+      }
 
       const sourceBasename = row.asset_path.split(/[\\/]/).pop();
       const extMatch = sourceBasename.match(/\.[^.]+$/);
@@ -67,7 +157,13 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
           await symlink(relative(datasetDir, sourcePath), destPath);
         }
         imageCount++;
-      } catch {
+      } catch (err) {
+        imagesFailed.push({
+          record_id: row.entity_id,
+          partition,
+          reason: copy ? 'copy_failed' : 'link_failed',
+          detail: err.message,
+        });
         continue;
       }
 
@@ -91,39 +187,138 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     );
   }
 
+  if (imagesFailed.length > 0) {
+    const sample = imagesFailed.slice(0, 10).map(f => `${f.record_id} (${f.reason})`);
+    warn(
+      `ai-toolkit adapter: ${imagesFailed.length} of ${imageCount + imagesFailed.length} rows failed to place` +
+      (imagesFailed.length > 10 ? ` — first 10: ${sample.join(', ')}, ...` : ` — ${sample.join(', ')}`),
+    );
+  }
+
   const aiToolkitConfig = buildAiToolkitConfig({ profile, manifest });
   await writeFile(
     join(packageDir, 'ai-toolkit-config.yaml'),
     YAML.stringify(aiToolkitConfig)
   );
 
-  return { imageCount };
+  return { imageCount, imagesFailed };
+}
+
+/**
+ * Build the Qwen-Image ai-toolkit YAML config object (§3.3, §3.5, G12).
+ */
+export function buildQwenAiToolkitConfig({ profile, manifest }) {
+  assertNotHeldTrainingData({ profile, manifest });
+  const trigger = deriveStyleTrigger(profile) || profile.profile_id;
+  const baseModel = profile.base_model_recommendations?.[0] || 'Qwen/Qwen-Image';
+  const sourceExportId = manifest?.source_export_id || 'unknown';
+  const overrideMeta = getAiToolkitOverrideMetadata();
+
+  const hp = profile.training_hyperparameters || {};
+  const linear = hp.rank ?? 16;
+  const linearAlpha = hp.alpha ?? linear;
+  const trainSteps = hp.steps ?? 1000;
+  const lr = hp.lr ?? 1e-4;
+
+  return {
+    job: 'extension',
+    config: {
+      name: `${profile.profile_id}-${sourceExportId}`,
+      process: [
+        {
+          type: 'sd_trainer',
+          training_folder: 'output',
+          device: 'cuda:0',
+          trigger_word: trigger,
+          network: {
+            type: 'lora',
+            linear: linear,
+            linear_alpha: linearAlpha,
+          },
+          save: {
+            dtype: 'float16',
+            save_every: 250,
+            max_step_saves_to_keep: 4,
+          },
+          datasets: [
+            {
+              folder_path: './dataset/train',
+              caption_ext: 'txt',
+              caption_dropout_rate: 0.05,
+              shuffle_tokens: false,
+              cache_latents_to_disk: true,
+              resolution: [512, 768, 1024],
+            },
+          ],
+          train: {
+            batch_size: 1,
+            steps: trainSteps,
+            gradient_accumulation_steps: 1,
+            train_unet: true,
+            train_text_encoder: false,
+            gradient_checkpointing: true,
+            noise_scheduler: 'flowmatch',
+            optimizer: 'adamw8bit',
+            lr: lr,
+            ema_config: {
+              use_ema: true,
+              ema_decay: 0.99,
+            },
+            dtype: 'bf16',
+          },
+          model: {
+            name_or_path: baseModel,
+            arch: 'qwen_image',
+            quantize: true,
+            qtype: 'qfloat8',
+            quantize_te: true,
+            qtype_te: 'qfloat8',
+            low_vram: true,
+          },
+          is_style: profile.is_style_lora === true,
+          sample: {
+            sampler: 'flowmatch',
+            sample_every: 250,
+            width: 1024,
+            height: 1024,
+            prompts: [`${trigger} style sample prompt`],
+            neg: '',
+            seed: 42,
+            walk_seed: true,
+            guidance_scale: 3.5,
+            sample_steps: 22,
+          },
+        },
+      ],
+    },
+    meta: {
+      name: profile.profile_id,
+      version: '1.0',
+      target_family: 'qwen-image',
+      base_licence_id: 'Apache-2.0',
+      override_file: overrideMeta.override_file,
+      override_sha256: overrideMeta.override_sha256,
+      upstream_issue: overrideMeta.upstream_issue,
+    },
+  };
 }
 
 /**
  * Build the ai-toolkit YAML config object from a profile + manifest.
  *
- * Defaults follow ai-toolkit's published Flux examples and the 16GB-VRAM
- * ceiling documented in the slice-3 handoff. Users can override any field
- * by editing the emitted YAML before running ai-toolkit.
+ * Dispatches to `buildQwenAiToolkitConfig` when `profile.target_family === 'qwen-image'`;
+ * otherwise emits the Flux-shaped config.
  */
 export function buildAiToolkitConfig({ profile, manifest }) {
+  assertNotHeldTrainingData({ profile, manifest });
+  if (profile?.target_family === 'qwen-image') {
+    return buildQwenAiToolkitConfig({ profile, manifest });
+  }
+
   const trigger = deriveStyleTrigger(profile) || profile.profile_id;
   const baseModel = profile.base_model_recommendations?.[0] || 'black-forest-labs/FLUX.1-dev';
   const sourceExportId = manifest?.source_export_id || 'unknown';
 
-  // Per-profile training_hyperparameters override the World-LoRA-tuned defaults.
-  // World LoRAs: rank 32, steps 2500 (style absorption across a domain).
-  // Per-character LoRAs: rank 16, alpha 8, steps 2000 (identity on a single
-  // subject — higher rank just overfits face details). See the two-LoRA stack
-  // contract in the handbook + memory/two-lora-stack-research-2026-04-23.md.
-  //
-  // TODO (normalization): the implicit World-LoRA fallback is a transition-era
-  // convenience for existing profiles that pre-date training_hyperparameters.
-  // Once every shipping profile declares training_hyperparameters explicitly,
-  // the ?? fallbacks can be removed in favor of a required block — preventing
-  // the "is this World-tuned by omission or by intent?" ambiguity that grows
-  // once a second World project exists.
   const hp = profile.training_hyperparameters || {};
   const linear = hp.rank ?? 32;
   const linearAlpha = hp.alpha ?? linear;
@@ -179,12 +374,6 @@ export function buildAiToolkitConfig({ profile, manifest }) {
             is_flux: true,
             quantize: true,
           },
-          // ai-toolkit's is_style flag: true for world/style LoRAs that teach
-          // aesthetics broadly; false (default) for subject LoRAs that teach a
-          // specific character or object. Drives ai-toolkit's training
-          // regularization — wrong value silently mistrains. See the two-LoRA
-          // stack research (memory/two-lora-stack-research-2026-04-23.md) for
-          // the World LoRA vs per-character LoRA convention.
           is_style: profile.is_style_lora === true,
           sample: {
             sampler: 'flowmatch',

package/lib/adapters/comfyui-runner.js

@@ -7,9 +7,9 @@
 
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { comfyHealth, submitAndWait, downloadImage } from '../comfyui.js';
+import { comfyHealthDetailed, submitAndWait, downloadImage } from '../comfyui.js';
 import { buildWorkflowGraph, resolveTemplateId, QWEN_DEFAULTS } from './comfyui-workflows.js';
-import { buildSeedPlan, prepareRunDir, saveRunManifest } from '../runtime-runs.js';
+import { buildSeedPlan, prepareRunDir, saveRunManifest, checkpointRunManifest } from '../runtime-runs.js';
 import { loadProjectConfig } from '../config.js';
 import { pickOutputImage } from '../comfyui-output.js';
 import { buildPinning, seedPolicyFromMode, createHashCache, flushHashCache } from '../run-manifest.js';
@@ -17,6 +17,24 @@ import { SCHEMA_VERSION } from '../snapshot.js';
 import { log, info, warn } from '../log.js';
 import { runtimeError } from '../errors.js';
 
+// B04: comfyHealthDetailed()'s `reason` maps to an ACTIONABLE hint, instead
+// of every failure mode sharing the same "start ComfyUI" advice — which is
+// simply wrong for an `http-<5xx>` (ComfyUI is up and answering) and useless
+// for `dns`/`refused` against a misconfigured URL.
+const HEALTH_REASON_HINTS = {
+  timeout: 'ComfyUI accepted the connection but never responded — it may be loading a custom node or a large model. Wait and retry, or check its console for a stuck step.',
+  refused: 'Start ComfyUI, or check COMFY_URL / project defaults.comfy_url — the connection was actively refused.',
+  dns: 'COMFY_URL / project defaults.comfy_url does not resolve — check for a typo in the hostname.',
+  unknown: 'Start ComfyUI or set COMFY_URL / project defaults.comfy_url.',
+};
+
+function healthReasonHint(reason) {
+  if (reason && reason.startsWith('http-')) {
+    return `ComfyUI responded with ${reason.slice('http-'.length)} — it is reachable but reported an error; check its console/logs.`;
+  }
+  return HEALTH_REASON_HINTS[reason] || HEALTH_REASON_HINTS.unknown;
+}
+
 /**
  * Execute a brief: build graphs, submit to ComfyUI, capture outputs.
  *
@@ -50,12 +68,16 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
 
   // Health check
   if (!dryRun) {
-    const healthy = await comfyHealth(comfyUrl);
-    if (!healthy) {
+    // B04: use the reason-carrying check so a 503-while-loading, a refused
+    // connection, a DNS typo, and a genuine timeout each get their OWN
+    // actionable hint instead of the identical (and sometimes factually
+    // wrong) "ComfyUI not reachable — start ComfyUI" message.
+    const health = await comfyHealthDetailed(comfyUrl);
+    if (!health.ok) {
       throw runtimeError(
         'COMFYUI_OFFLINE',
-        `ComfyUI not reachable at ${comfyUrl}`,
-        'Start ComfyUI or set COMFY_URL / project defaults.comfy_url'
+        `ComfyUI not reachable at ${comfyUrl} (${health.reason})`,
+        healthReasonHint(health.reason)
       );
     }
     info('ComfyUI online');
@@ -63,6 +85,43 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
 
   const outputs = [];
   const errors = [];
+  // B01: fixed at run start and reused by every mid-loop checkpoint AND the
+  // final manifest, so `created_at` never drifts between an incremental
+  // snapshot and the finished manifest for the same run.
+  const createdAt = new Date().toISOString();
+
+  // B01: checkpointRunManifest() existed (with a docstring saying exactly
+  // this) but had zero production callers — comfyui-runner.js only called
+  // saveRunManifest() once, after the whole loop. A run killed partway
+  // through wrote NO manifest at all, so listRuns() silently skipped the
+  // directory entirely: no id, no `run show`, no resume. This snapshot
+  // mirrors the final manifest's shape (minus `pinning`, computed only
+  // after the loop) so a partial manifest.json is readable by the same
+  // code that reads a finished one.
+  function buildManifestSnapshot() {
+    return {
+      run_id: runId,
+      schema_version: SCHEMA_VERSION,
+      brief_id: brief.brief_id,
+      project_id: brief.project_id,
+      workflow_template_id: templateId,
+      adapter_target: 'comfyui',
+      output_mode: outputMode,
+      output_count: outputCount,
+      created_at: createdAt,
+      seed_plan: seedPlan,
+      comfy_url: comfyUrl,
+      checkpoint: defaults.checkpoint,
+      loras: defaults.loras || [],
+      pinning: null,
+      runtime_plan: brief.runtime_plan,
+      outputs,
+      errors,
+      dry_run: dryRun,
+      success_count: outputs.filter(o => o.status === 'ok' || o.status === 'dry_run').length,
+      error_count: errors.length,
+    };
+  }
 
   for (let i = 0; i < outputCount; i++) {
     const seed = seedPlan.seeds[i];
@@ -77,6 +136,7 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
         status: 'dry_run',
         filename: `${imageIndex}.png`,
       });
+      await checkpointRunManifest(runDir, buildManifestSnapshot());
       continue;
     }
 
@@ -106,6 +166,7 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
       if (!picked) {
         warn(`  No output image for seed ${seed}`);
         outputs.push({ index: i, seed, status: 'no_output', elapsed_ms: elapsed });
+        await checkpointRunManifest(runDir, buildManifestSnapshot());
         continue;
       }
 
@@ -138,6 +199,12 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
         elapsed_ms: elapsed,
       });
     }
+
+    // B01: checkpoint after every completed output (success OR error) so a
+    // crash/interruption mid-loop leaves a partial, readable manifest.json
+    // instead of an orphan directory — this is the call the docstring on
+    // checkpointRunManifest() always described but nothing ever made.
+    await checkpointRunManifest(runDir, buildManifestSnapshot());
   }
 
   // PIN_PER_STEP: pin the exact graph + model/LoRA content identity + seed
@@ -170,28 +237,14 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
     warn(`pinning skipped: ${err.message}`);
   }
 
-  // Build manifest
+  // Build manifest — reuses buildManifestSnapshot() (same helper the
+  // mid-loop checkpoints use) so the finished manifest and every
+  // incremental checkpoint before it are byte-for-byte the same shape,
+  // just with `pinning` filled in and no `incremental`/`last_checkpoint_at`
+  // stamp (that stamp is what lets a reader tell "done" from "still going").
   const manifest = {
-    run_id: runId,
-    schema_version: SCHEMA_VERSION,
-    brief_id: brief.brief_id,
-    project_id: brief.project_id,
-    workflow_template_id: templateId,
-    adapter_target: 'comfyui',
-    output_mode: outputMode,
-    output_count: outputCount,
-    created_at: new Date().toISOString(),
-    seed_plan: seedPlan,
-    comfy_url: comfyUrl,
-    checkpoint: defaults.checkpoint,
-    loras: defaults.loras || [],
+    ...buildManifestSnapshot(),
     pinning,
-    runtime_plan: brief.runtime_plan,
-    outputs,
-    errors,
-    dry_run: dryRun,
-    success_count: outputs.filter(o => o.status === 'ok' || o.status === 'dry_run').length,
-    error_count: errors.length,
   };
 
   await saveRunManifest(runDir, manifest);

package/lib/adapters/comfyui-workflows.js

@@ -6,7 +6,6 @@
  * 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';
@@ -33,8 +32,16 @@ export function listWorkflowTemplates() {
 
 /**
  * Resolve a template for a given output mode.
- * Returns 'txt2img-standard' for all standard modes.
- * Throws if no template matches.
+ *
+ * Returns the first template declaring `outputMode` in its `compatible_modes`,
+ * and falls back to `'txt2img-standard'` when none matches — it does NOT
+ * throw. (The docstring claimed a throw until 2026-08-04; a caller written
+ * against that claim would guard a branch that cannot fire and would miss the
+ * silent-default case, where an unrecognised mode renders through the standard
+ * SDXL graph instead of failing loudly.)
+ *
+ * The fallback is also what makes an install with no `runtime/comfyui/`
+ * templates degrade rather than crash — see `getRuntimeDir()` in lib/paths.js.
  */
 export function resolveTemplateId(outputMode) {
   const templates = listWorkflowTemplates();
@@ -64,6 +71,41 @@ export const QWEN_DEFAULTS = Object.freeze({
   height: 1024,
 });
 
+function normalizeLoraSpec(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const name = entry.name || entry.lora_name;
+  if (typeof name !== 'string' || name.trim().length === 0) return null;
+  const weight = entry.weight ?? entry.strength_model ?? entry.strength ?? 1.0;
+  return { name: name.trim(), weight: Number(weight) };
+}
+
+/**
+ * Resolve the ordered Qwen-Image LoRA chain (G3) from project defaults, brief,
+ * runtime_plan, and explicit job overrides. Deduplicates by LoRA filename while
+ * preserving the latest weight override.
+ *
+ * @param {Object} [opts]
+ * @param {Object} [opts.brief]
+ * @param {Object} [opts.projectDefaults]
+ * @param {Array} [opts.loras]
+ * @returns {Array<{name: string, weight: number}>}
+ */
+export function resolveQwenLoras({ brief = {}, projectDefaults = {}, loras = [] } = {}) {
+  const sources = [
+    ...(Array.isArray(projectDefaults?.loras) ? projectDefaults.loras : []),
+    ...(Array.isArray(brief?.loras) ? brief.loras : []),
+    ...(Array.isArray(brief?.runtime_plan?.loras) ? brief.runtime_plan.loras : []),
+    ...(Array.isArray(loras) ? loras : []),
+  ];
+  const byName = new Map();
+  for (const raw of sources) {
+    const spec = normalizeLoraSpec(raw);
+    if (!spec) continue;
+    byName.set(spec.name, spec);
+  }
+  return [...byName.values()];
+}
+
 /**
  * Build the Qwen-Image ComfyUI prompt graph.
  *
@@ -110,13 +152,15 @@ export function buildQwenGraph({
   // DiT LoRA chain: 37 → 40 → 41 → … → ModelSamplingAuraFlow.
   let modelOut = ['37', 0];
   let loraId = 40;
-  for (const lora of loras) {
+  for (const rawLora of loras) {
+    const lora = normalizeLoraSpec(rawLora);
+    if (!lora) continue;
     const id = String(loraId++);
     nodes[id] = {
       class_type: 'LoraLoaderModelOnly',
       inputs: {
         lora_name: lora.name,
-        strength_model: lora.weight ?? 1.0,
+        strength_model: lora.weight,
         model: modelOut,
       },
     };
@@ -147,6 +191,43 @@ export function buildQwenGraph({
   return { nodes, saveNodeId: '9' };
 }
 
+/**
+ * Build the minimal 64x64 no-weights ComfyUI fixture graph for Stage 0 CPU
+ * stubs (EmptyImage -> ImageInvert -> SaveImage). Exercises ComfyUI --cpu
+ * execution, extra_pnginfo chunk writing, and /view download without loading
+ * multi-gigabyte diffusion weights.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.seed=0]
+ * @param {number} [opts.width=64]
+ * @param {number} [opts.height=64]
+ * @param {string} [opts.filenamePrefix='sdl_stub']
+ * @returns {{ nodes: Object, saveNodeId: string }}
+ */
+export function buildStubFixtureGraph({
+  seed = 0,
+  width = 64,
+  height = 64,
+  filenamePrefix = 'sdl_stub',
+} = {}) {
+  const color = Math.abs(Number(seed) || 0) & 0xffffff;
+  const nodes = {
+    '1': {
+      class_type: 'EmptyImage',
+      inputs: { width, height, batch_size: 1, color },
+    },
+    '2': {
+      class_type: 'ImageInvert',
+      inputs: { image: ['1', 0] },
+    },
+    '3': {
+      class_type: 'SaveImage',
+      inputs: { filename_prefix: filenamePrefix, images: ['2', 0] },
+    },
+  };
+  return { nodes, saveNodeId: '3' };
+}
+
 // ─── Graph builder ───────────────────────────────────────────────
 
 /**
@@ -160,17 +241,19 @@ export function buildQwenGraph({
  * @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
+ * @param {Array} [opts.loras] — optional explicit LoRA overrides
  * @returns {{ nodes: Object, saveNodeId: string }}
  */
-export function buildWorkflowGraph({ brief, projectDefaults, seed }) {
-  const rp = brief.runtime_plan;
-  const defaults = projectDefaults;
+export function buildWorkflowGraph({ brief, projectDefaults, seed, loras }) {
+  const rp = brief.runtime_plan || {};
+  const defaults = projectDefaults || {};
 
   const prompt = brief.prompt;
   const negativePrompt = brief.negative_prompt;
 
   // ── Qwen-Image branch (non-anime studio base) ──
   if (String(defaults.base || '').toLowerCase() === 'qwen-image') {
+    const resolvedLoras = resolveQwenLoras({ brief, projectDefaults: defaults, loras });
     return buildQwenGraph({
       prompt,
       negativePrompt,
@@ -187,13 +270,13 @@ export function buildWorkflowGraph({ brief, projectDefaults, seed }) {
       vae: defaults.vae || QWEN_DEFAULTS.vae,
       clipType: defaults.clip_type || QWEN_DEFAULTS.clip_type,
       weightDtype: defaults.weight_dtype || QWEN_DEFAULTS.weight_dtype,
-      loras: defaults.loras || [],
+      loras: resolvedLoras,
     });
   }
 
   // ── SDXL branch (default) ──
   const checkpoint = defaults.checkpoint;
-  const loras = defaults.loras || [];
+  const sdxlLoras = loras || defaults.loras || [];
   const width = rp.width || defaults.width || 1024;
   const height = rp.height || defaults.height || 1024;
   const steps = rp.steps || defaults.steps || 30;
@@ -215,7 +298,7 @@ export function buildWorkflowGraph({ brief, projectDefaults, seed }) {
   let clipOut = [ckptId, 1];
 
   // LoRA loaders (chained)
-  for (const lora of loras) {
+  for (const lora of sdxlLoras) {
     const loraId = String(nextId++);
     nodes[loraId] = {
       class_type: 'LoraLoader',