@mcptoolshop/style-dataset-lab 3.2.0 → 3.3.0

package/lib/run-manifest.js

@@ -0,0 +1,308 @@
+/**
+ * Run-manifest pinning contract (PIN_PER_STEP).
+ *
+ * ONE source of truth for the fields that make a generation wave byte-for-byte
+ * replayable. Three writers emit provenance today — `scripts/generate.js`
+ * (record `provenance`), `lib/adapters/comfyui-runner.js` (run `manifest.json`),
+ * and `scripts/qwen_generate.py` (the wave `generation.json` receipt) — and they
+ * MUST all pin the same way. This module is the field-name authority; the
+ * Python receipt mirrors the identical field contract (see qwen_generate.py).
+ *
+ * Design (DECOMPOSE_BY_SECRETS, Parnas 1972): the pinning field names + the
+ * best-effort model hasher live here so the writers can never drift apart
+ * silently. When the model changes, this secret-hiding boundary survives.
+ *
+ * The pinning block closes three PIN_PER_STEP gaps that the pre-3.3.0 manifests
+ * left open (base/sampler/scheduler/shift/seed/steps/cfg were already recorded):
+ *   1. comfy_workflow_sha — the exact ComfyUI graph that ran, as a hash.
+ *   2. model/LoRA content identity — filenames upgraded to {name,size_bytes,sha256}.
+ *   3. seed_policy — HOW seeds were chosen (intent), not just the values.
+ *
+ * Every field is optional and additive. Legacy manifests with no `pinning`
+ * block load fine; readers nullish-coalesce (`m.pinning?.comfy_workflow_sha ?? null`).
+ */
+
+import { createHash } from 'node:crypto';
+import { openSync, readSync, closeSync, statSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Contract version for the `pinning` block itself. Bump when the block's shape
+ * changes (a new field, a renamed field). Independent of the manifest
+ * SCHEMA_VERSION (lib/snapshot.js) — that versions the snapshot/split/export
+ * manifest family; this versions the generation-provenance pin. Mirrored as a
+ * literal in scripts/qwen_generate.py — keep the two in lockstep.
+ */
+export const PINNING_VERSION = '1.0.0';
+
+/**
+ * Seed policies — the INTENT behind seed selection, recorded alongside the
+ * concrete per-item seed values so a reader knows how to regenerate.
+ */
+export const SEED_POLICIES = Object.freeze({
+  EXPLICIT_PER_ITEM: 'explicit-per-item', // each item's seed is recorded verbatim (qwen_generate.py wave receipt)
+  BASE_INCREMENT: 'base+increment',        // seed = base_seed + job_index (generate.js / batch path)
+  FIXED: 'fixed',                          // every item shares one seed
+  RANDOM: 'random',                        // first seed fixed, rest sampled
+});
+
+/**
+ * Map a runtime seed_mode ('increment' | 'fixed' | 'random') to a seed_policy.
+ * `increment` is the base+index scheme; unknown modes fall back to base+increment.
+ */
+export function seedPolicyFromMode(seedMode) {
+  switch (seedMode) {
+    case 'fixed': return SEED_POLICIES.FIXED;
+    case 'random': return SEED_POLICIES.RANDOM;
+    case 'increment':
+    default: return SEED_POLICIES.BASE_INCREMENT;
+  }
+}
+
+// ─── Stable serialization ────────────────────────────────────────
+
+/**
+ * Deterministic JSON: object keys sorted, arrays kept in order (arrays are
+ * meaningful sequences — a LoRA chain, a node's input wiring). Guarantees the
+ * same semantic graph hashes identically regardless of key insertion order.
+ */
+export function stableStringify(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  if (typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const k of keys) {
+      if (value[k] === undefined) continue;
+      parts.push(JSON.stringify(k) + ':' + stableStringify(value[k]));
+    }
+    return '{' + parts.join(',') + '}';
+  }
+  return 'null';
+}
+
+/**
+ * Return a copy of a ComfyUI graph with per-ITEM nondeterminism removed, so the
+ * whole wave shares ONE comfy_workflow_sha. Normalized out (recorded elsewhere,
+ * per item): KSampler seed / noise_seed, CLIPTextEncode prompt text, SaveImage
+ * filename_prefix. What SURVIVES the hash is the pipeline skeleton — node
+ * topology, model loaders, sampler/scheduler/shift, LoRA chain + weights,
+ * dims/steps/cfg — i.e. exactly the part that must match to replay the wave.
+ */
+export function normalizeGraphForHash(graph) {
+  const out = {};
+  for (const [id, node] of Object.entries(graph || {})) {
+    const inputs = { ...(node?.inputs || {}) };
+    const cls = node?.class_type;
+    if (cls === 'KSampler' || cls === 'KSamplerAdvanced') {
+      if ('seed' in inputs) inputs.seed = 0;
+      if ('noise_seed' in inputs) inputs.noise_seed = 0;
+    } else if (cls === 'CLIPTextEncode') {
+      if ('text' in inputs) inputs.text = '';
+    } else if (cls === 'SaveImage') {
+      if ('filename_prefix' in inputs) inputs.filename_prefix = '';
+    }
+    out[id] = { class_type: cls, inputs };
+  }
+  return out;
+}
+
+/**
+ * SHA-256 of the exact ComfyUI graph submitted for the wave (per-item seed +
+ * prompt normalized out — see normalizeGraphForHash). Returns a `sha256:`-prefixed
+ * digest, or null for an empty/absent graph.
+ */
+export function comfyWorkflowSha(graph) {
+  if (!graph || Object.keys(graph).length === 0) return null;
+  const normalized = normalizeGraphForHash(graph);
+  return 'sha256:' + createHash('sha256').update(stableStringify(normalized)).digest('hex');
+}
+
+// ─── Model file resolution + hashing (best-effort) ───────────────
+
+/**
+ * Default ComfyUI models directory on the rig. Override with SDLAB_MODELS_DIR.
+ * Hashing is opt-in and best-effort, so a wrong/absent path degrades cleanly to
+ * `sha256: null` — it never fails a generation.
+ */
+export function defaultModelsDir() {
+  return process.env.SDLAB_MODELS_DIR
+    || 'E:/AI-Models/ComfyUI_windows_portable/ComfyUI/models';
+}
+
+// Kind → candidate subdirectories under the models dir, in search order.
+const KIND_SUBDIRS = {
+  unet: ['diffusion_models', 'unet'],
+  clip: ['text_encoders', 'clip'],
+  vae: ['vae'],
+  checkpoint: ['checkpoints'],
+  lora: ['loras'],
+};
+
+/**
+ * Resolve a model filename to an absolute path under the models dir. Searches
+ * the kind-appropriate subdirs first, then every known subdir, then the root.
+ * Returns null when nothing matches (unresolvable → sha256 null with a note).
+ */
+export function resolveModelPath(name, kind, modelsDir = defaultModelsDir()) {
+  if (!name || !modelsDir) return null;
+  const tried = new Set();
+  const subdirs = [
+    ...(KIND_SUBDIRS[kind] || []),
+    ...Object.values(KIND_SUBDIRS).flat(),
+    '.',
+  ];
+  for (const sub of subdirs) {
+    const candidate = join(modelsDir, sub, name);
+    if (tried.has(candidate)) continue;
+    tried.add(candidate);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Streaming SHA-256 of a file — 1 MiB chunks, synchronous, never loads the whole
+ * (multi-GB) file into memory. Returns a `sha256:`-prefixed digest.
+ */
+export function sha256File(path) {
+  const hash = createHash('sha256');
+  const fd = openSync(path, 'r');
+  try {
+    const buf = Buffer.allocUnsafe(1 << 20);
+    let bytes;
+    while ((bytes = readSync(fd, buf, 0, buf.length, null)) > 0) {
+      hash.update(bytes === buf.length ? buf : buf.subarray(0, bytes));
+    }
+  } finally {
+    closeSync(fd);
+  }
+  return 'sha256:' + hash.digest('hex');
+}
+
+/**
+ * Best-effort content identity for one model/LoRA file: {name, size_bytes, sha256}
+ * (+ a short `hash_note` when sha256 can't be produced). size_bytes is always
+ * filled when the file resolves (a cheap stat); sha256 is gated behind
+ * `doHash` (the --hash-models opt-in) and cached by (name, size, mtime) so
+ * multi-GB checkpoints aren't re-hashed every wave.
+ *
+ * @param {string} name — model filename as it appears in the graph
+ * @param {Object} [opts]
+ * @param {'unet'|'clip'|'vae'|'checkpoint'|'lora'} [opts.kind]
+ * @param {string} [opts.modelsDir]
+ * @param {boolean} [opts.doHash=false] — compute sha256 (else record name+size only)
+ * @param {{map: Map, cacheFile?: string, dirty: boolean}} [opts.cache]
+ */
+export function hashModelFile(name, { kind, modelsDir = defaultModelsDir(), doHash = false, cache } = {}) {
+  if (!name) return { name: name ?? null, size_bytes: null, sha256: null, hash_note: 'no filename' };
+  const resolved = resolveModelPath(name, kind, modelsDir);
+  if (!resolved) return { name, size_bytes: null, sha256: null, hash_note: `unresolved under ${modelsDir}` };
+  let size_bytes = null;
+  let mtimeMs = 0;
+  try {
+    const st = statSync(resolved);
+    size_bytes = st.size;
+    mtimeMs = st.mtimeMs;
+  } catch {
+    return { name, size_bytes: null, sha256: null, hash_note: 'stat failed' };
+  }
+  if (!doHash) return { name, size_bytes, sha256: null, hash_note: 'hash skipped (pass --hash-models)' };
+  const key = `${name}:${size_bytes}:${Math.round(mtimeMs)}`;
+  if (cache?.map?.has(key)) return { name, size_bytes, sha256: cache.map.get(key) };
+  let sha256;
+  try {
+    sha256 = sha256File(resolved);
+  } catch {
+    return { name, size_bytes, sha256: null, hash_note: 'hash failed (read error)' };
+  }
+  if (cache?.map) {
+    cache.map.set(key, sha256);
+    cache.dirty = true;
+  }
+  return { name, size_bytes, sha256 };
+}
+
+/**
+ * Content-identity block for the model loaders of a wave. `modelSpec` maps a
+ * role to a filename — {unet, clip, vae} for the Qwen DiT path, {checkpoint}
+ * for the SDXL path. Only provided roles appear in the result.
+ */
+export function buildModelHashes(modelSpec = {}, opts = {}) {
+  const roleKind = { unet: 'unet', clip: 'clip', vae: 'vae', checkpoint: 'checkpoint' };
+  const out = {};
+  for (const [role, kind] of Object.entries(roleKind)) {
+    const name = modelSpec[role];
+    if (!name) continue;
+    out[role] = hashModelFile(name, { ...opts, kind });
+  }
+  return out;
+}
+
+// ─── Persistent hash cache (best-effort) ─────────────────────────
+
+/**
+ * Create a hash cache. Loads the on-disk JSON map (name:size:mtime → sha256) if
+ * present, so hashes survive across waves. `cacheFile` defaults to a dotfile in
+ * the models dir; override with SDLAB_HASH_CACHE. All I/O is best-effort — a
+ * missing/unwritable cache never fails a run.
+ */
+export function createHashCache(cacheFile) {
+  const file = cacheFile
+    || process.env.SDLAB_HASH_CACHE
+    || join(defaultModelsDir(), '.sdlab-hash-cache.json');
+  const map = new Map();
+  try {
+    if (existsSync(file)) {
+      const obj = JSON.parse(readFileSync(file, 'utf-8'));
+      for (const [k, v] of Object.entries(obj)) map.set(k, v);
+    }
+  } catch { /* best-effort: ignore a corrupt/unreadable cache */ }
+  return { map, cacheFile: file, dirty: false };
+}
+
+/**
+ * Persist a hash cache to disk if it grew. Best-effort — swallows write errors.
+ */
+export function flushHashCache(cache) {
+  if (!cache || !cache.dirty || !cache.cacheFile) return;
+  try {
+    const obj = Object.fromEntries(cache.map);
+    writeFileSync(cache.cacheFile, JSON.stringify(obj, null, 2));
+    cache.dirty = false;
+  } catch { /* best-effort: ignore */ }
+}
+
+// ─── The pinning block ───────────────────────────────────────────
+
+/**
+ * Build the pinning block for a wave/item. Identical shape across all three
+ * writers (see module header). Every writer calls this so the contract is
+ * enforced in ONE place.
+ *
+ * @param {Object} args
+ * @param {Object} [args.graph] — the ComfyUI node graph submitted (for comfy_workflow_sha)
+ * @param {Object} [args.models] — {unet?, clip?, vae?, checkpoint?} filenames
+ * @param {Array<{name:string, weight?:number}>} [args.loras]
+ * @param {string} [args.seedPolicy] — one of SEED_POLICIES
+ * @param {boolean} [args.hashModels=false] — opt-in sha256 of model/LoRA files
+ * @param {string} [args.modelsDir]
+ * @param {{map: Map, cacheFile?: string, dirty: boolean}} [args.cache]
+ * @returns {Object} pinning block
+ */
+export function buildPinning({ graph, models = {}, loras = [], seedPolicy = null, hashModels = false, modelsDir = defaultModelsDir(), cache } = {}) {
+  const opts = { modelsDir, doHash: hashModels, cache };
+  return {
+    pinning_version: PINNING_VERSION,
+    comfy_workflow_sha: comfyWorkflowSha(graph),
+    seed_policy: seedPolicy,
+    models: buildModelHashes(models, opts),
+    loras: (loras || []).map((l) => ({
+      ...hashModelFile(l.name, { ...opts, kind: 'lora' }),
+      weight: l.weight ?? 1.0,
+    })),
+  };
+}

package/lib/snapshot.js

@@ -19,8 +19,14 @@ import { warn } from './log.js';
  * snapshot/split/export/eval-pack/eval-run/training-manifest/training-package/
  * impl-pack stamps this version; readers log a WARNING on version mismatch
  * (best-effort compatibility).
+ *
+ * 2.3.0 (v3.3.0): PIN_PER_STEP — the ComfyUI run manifest now also stamps this
+ * version and carries a `pinning` block (comfy_workflow_sha + model/LoRA content
+ * hashes + seed_policy; see lib/run-manifest.js). The block is additive and
+ * optional, so a legacy manifest with no schema_version / no pinning still loads
+ * (checkManifestVersion only warns; it never throws).
  */
-export const SCHEMA_VERSION = '2.2.0';
+export const SCHEMA_VERSION = '2.3.0';
 
 /**
  * Warn if a loaded manifest's schema_version does not match the reader.

package/lib/verifier.js

@@ -0,0 +1,67 @@
+/**
+ * EXTERNAL_VERIFIER support (Kambhampati arXiv:2402.01817; Huang / DeepMind
+ * arXiv:2310.01798): a judgment records WHO judged it (`judged_by_model`) and
+ * WHAT produced the artifact (`generator_model`), and we WARN when they are the
+ * same — the self-verification failure mode a verifier must never fall into.
+ *
+ * Today the two judges are `human` (curate) and a rule-based engine
+ * (critique-engine) — both a different artifact class from the image generator,
+ * so the warning does not fire in practice and the standard's spirit is already
+ * met. Recording the fields + wiring the warning installs the muscle: the moment
+ * an LLM critique mode enters the loop sharing the generator's base, the WARN
+ * fires, and the standard's remediation flips it from a warning to a hard gate.
+ */
+
+import { warn } from './log.js';
+
+/** The rule-based critique engine's judge id. Bump vN when the rule set changes. */
+export const RULE_BASED_JUDGE = 'rule-based:sdlab-critique-v1';
+
+/** The human curator's judge id (curate.js reviewer is "human:mike"). */
+export const HUMAN_JUDGE = 'human';
+
+const MODEL_EXT_RE = /\.(safetensors|ckpt|pt|pth|bin|gguf)$/i;
+
+/**
+ * Derive a stable generator model id from a record `provenance` (or any object
+ * carrying {base, unet|checkpoint}): `<base>:<model-basename-without-ext>`, e.g.
+ * "qwen-image:qwen_image_fp8_e4m3fn" or "sdxl:dreamshaperXL". Returns null when
+ * neither a base nor a model file is known (legacy/hand-migrated records).
+ */
+export function deriveGeneratorModel(provenance) {
+  if (!provenance || typeof provenance !== 'object') return null;
+  const base = provenance.base || null;
+  const modelFile = provenance.unet || provenance.checkpoint || null;
+  const stripped = modelFile ? String(modelFile).replace(MODEL_EXT_RE, '') : null;
+  if (base && stripped) return `${base}:${stripped}`;
+  return base || stripped || null;
+}
+
+/**
+ * Derive the generator model id from a run manifest (comfyui-runner shape).
+ * Prefers the pinning block's model identity, falling back to the top-level
+ * checkpoint. Qwen manifests carry pinning.models.unet; SDXL carry checkpoint.
+ */
+export function generatorModelFromManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') return null;
+  const unet = manifest.pinning?.models?.unet?.name;
+  const checkpoint = manifest.checkpoint || manifest.pinning?.models?.checkpoint?.name;
+  const base = unet ? 'qwen-image' : (checkpoint ? 'sdxl' : null);
+  return deriveGeneratorModel({ base, unet, checkpoint });
+}
+
+/**
+ * Emit a WARN when the judge and the generator are the same model — the
+ * self-verification failure mode. No-op when either is null or they differ.
+ * Returns true when the warning fired, so callers/tests can assert on it without
+ * capturing stderr.
+ */
+export function warnIfSelfVerification(judgedByModel, generatorModel, context = '') {
+  if (!judgedByModel || !generatorModel) return false;
+  if (judgedByModel !== generatorModel) return false;
+  warn(
+    `EXTERNAL_VERIFIER: judged_by_model === generator_model ("${judgedByModel}")${context ? ` for ${context}` : ''} — ` +
+    'a model must not verify its own output. Use a different-family judge (ai-eyes-mcp or a cross-family LLM).',
+  );
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "3.2.0",
+  "version": "3.3.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": {

package/scripts/critique.js

@@ -8,10 +8,10 @@
  *   sdlab critique --project star-freight --run run_2026-04-15_001 --json
  */
 
-import { parseArgs, getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName, parseNumberFlag } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
-import { critiqueRun, saveCritique } from '../lib/critique-engine.js';
-import { renderCritiqueMarkdown, renderCritiqueText } from '../lib/critique-render.js';
+import { critiqueRun, saveCritique, triageCandidates, DEFAULT_DRIFT_THRESHOLD } from '../lib/critique-engine.js';
+import { renderCritiqueMarkdown, renderCritiqueText, renderCritiqueTriage } from '../lib/critique-render.js';
 import { info } from '../lib/log.js';
 
 export async function run(argv = process.argv.slice(2)) {
@@ -20,16 +20,20 @@ export async function run(argv = process.argv.slice(2)) {
       project: { type: 'string' },
       run: { type: 'string' },
       json: { type: 'boolean' },
+      triage: { type: 'boolean' },
+      'drift-threshold': { type: 'string' },
     },
     deprecated: { game: 'project' },
   });
 
   if (!flags.run) {
-    console.log('Usage: sdlab critique --run <id> [--project <name>]');
+    console.log('Usage: sdlab critique --run <id> [--project <name>] [--triage]');
     console.log('');
     console.log('Options:');
-    console.log('  --run <id>        Run to critique (required)');
-    console.log('  --json            Output raw JSON');
+    console.log('  --run <id>            Run to critique (required)');
+    console.log('  --triage             Show only candidates needing attention (off-model OR ≥ threshold drift issues)');
+    console.log(`  --drift-threshold <n>  Drift-issue count that flags a candidate under --triage (default ${DEFAULT_DRIFT_THRESHOLD})`);
+    console.log('  --json               Output raw JSON');
     return;
   }
 
@@ -48,10 +52,31 @@ export async function run(argv = process.argv.slice(2)) {
     runId: flags.run,
   });
 
-  // Save
+  // Save the FULL report — triage is a view over it, never a mutation.
   const md = renderCritiqueMarkdown(report);
   await saveCritique(projectRoot, flags.run, report, md);
 
+  // UNCERTAINTY_GATED_HUMANS: --triage surfaces only the candidates that need a
+  // human — off-model OR >= threshold drift issues — so attention isn't spent on
+  // every item. The full critique.json still holds all candidates.
+  if (flags.triage) {
+    const driftThreshold = flags['drift-threshold']
+      ? parseNumberFlag('drift-threshold', flags['drift-threshold'], { int: true, min: 0 })
+      : DEFAULT_DRIFT_THRESHOLD;
+    const triage = triageCandidates(report.candidates, { driftThreshold });
+    if (flags.json) {
+      console.log(JSON.stringify({
+        run_id: report.run_id,
+        triage: { drift_threshold: driftThreshold, flagged_count: triage.flagged.length, suppressed_count: triage.suppressed.length },
+        candidates: triage.flagged,
+      }, null, 2));
+    } else {
+      console.log(renderCritiqueTriage(report, triage));
+      console.log(`Full critique saved to: runs/${flags.run}/critique.json`);
+    }
+    return;
+  }
+
   if (flags.json) {
     console.log(JSON.stringify(report, null, 2));
   } else {

package/scripts/curate.js

@@ -18,6 +18,7 @@ import { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { result } from "../lib/log.js";
 import { assertNotFrozenByAssetPath } from "../lib/freeze-gate.js";
+import { deriveGeneratorModel, warnIfSelfVerification, HUMAN_JUDGE } from "../lib/verifier.js";
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
@@ -132,11 +133,19 @@ export async function run(argv = process.argv.slice(2)) {
     );
   }
 
+  // EXTERNAL_VERIFIER: record WHO judged (human) and WHAT generated the artifact,
+  // and warn if they ever coincide (they never do for human curation — the field
+  // + warning install the muscle for when an LLM judge enters the loop).
+  const generator_model = deriveGeneratorModel(record.provenance);
+  warnIfSelfVerification(HUMAN_JUDGE, generator_model, assetId);
+
   // Now safely update the record. If writing fails, try to restore the image.
   record.asset_path = newPath;
   record.judgment = {
     status,
     reviewer: "human:mike",
+    judged_by_model: HUMAN_JUDGE,
+    generator_model,
     reviewed_at: new Date().toISOString(),
     explanation,
     criteria_scores,
@@ -164,6 +173,18 @@ export async function run(argv = process.argv.slice(2)) {
   result(`  record: records/${assetId}.json`);
   console.log(`  ${explanation}`);
   if (failure_modes.length) console.log(`  Failures: ${failure_modes.join(", ")}`);
+
+  // UNCERTAINTY_GATED_HUMANS: contrastive advisory on borderline (Horvitz CHI
+  // 1999). State the default (HOLD — borderline is not training-eligible) and
+  // what a later promotion must justify, so the promoter argues against a stated
+  // default rather than nudging a status upward unexamined.
+  if (status === 'borderline') {
+    const drift = failure_modes.length ? failure_modes.join(', ') : 'the drift you noted';
+    console.log(
+      `  \x1b[2mDefault: HOLD — 'borderline' is not training-eligible. ` +
+      `To later promote to 'approved', justify why ${drift} is acceptable for canon (re-run curate approved with that reason).\x1b[0m`,
+    );
+  }
 }
 
 async function listUncurated(GAME_ROOT) {

package/scripts/generate.js

@@ -20,6 +20,7 @@ import { runtimeError, inputError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
 import { pickOutputImage } from "../lib/comfyui-output.js";
 import { buildQwenGraph, QWEN_DEFAULTS } from "../lib/adapters/comfyui-workflows.js";
+import { buildPinning, SEED_POLICIES, createHashCache, flushHashCache } from "../lib/run-manifest.js";
 import { info, result } from "../lib/log.js";
 
 /**
@@ -272,12 +273,18 @@ export async function run(argv = process.argv.slice(2)) {
       game: { type: 'string' },
       'dry-run': { type: 'boolean' },
       resume: { type: 'boolean' },
+      'hash-models': { type: 'boolean' },
     },
     deprecated: { game: 'project' },
   });
   const packPath = parsed.positionals[0] || "inputs/prompts/rpg-icons-lane1.json";
   const dryRun = parsed.flags['dry-run'] === true;
   const resume = parsed.flags['resume'] === true;
+  // PIN_PER_STEP: --hash-models opts into content hashing of the checkpoint/
+  // unet/clip/vae/LoRA files (best-effort, cached). Without it the pinning block
+  // still records comfy_workflow_sha + model name/size + seed_policy.
+  const hashModels = parsed.flags['hash-models'] === true;
+  const hashCache = hashModels ? createHashCache() : undefined;
 
   const fullPackPath = resolveSafeProjectPath(GAME_ROOT, packPath, { flagName: 'pack-path' });
   const raw = await readJsonFile(fullPackPath);
@@ -432,6 +439,20 @@ export async function run(argv = process.argv.slice(2)) {
         provenance.loras = loras;
       }
 
+      // PIN_PER_STEP: pin the exact graph + model/LoRA content identity + seed
+      // policy via the shared contract (lib/run-manifest.js). Model hashing is
+      // wave-constant; the shared cache means it runs at most once per wave.
+      provenance.pinning = buildPinning({
+        graph: nodes,
+        models: isQwen
+          ? { unet: provenance.unet, clip: provenance.clip, vae: provenance.vae }
+          : { checkpoint: d.checkpoint },
+        loras: isQwen ? (d.loras || []) : loras,
+        seedPolicy: SEED_POLICIES.BASE_INCREMENT,
+        hashModels,
+        cache: hashCache,
+      });
+
       const record = {
         id: assetId,
         schema_version: "1.0.0",
@@ -467,6 +488,9 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
+  // Persist any newly computed model hashes so the next wave reuses them.
+  flushHashCache(hashCache);
+
   console.log("");
   const succeeded = generated - errors - skipped;
   const totalElapsedMs = Date.now() - runStartMs;