infra: align embed-llamacpp integration model helpers with diffusion-cpp

Make the integration-test model tooling uniform with diffusion-cpp:
- ensureModel now takes an object ({ modelName, modelDir, manifest, download }),
  matching diffusion-cpp/llm-llamacpp; update all callsites
- log the "no sha256/bytes pinned — integrity check SKIPPED" hint pointing at
  scripts/generate-model-manifest.mjs, same as diffusion
- rename the pinning script to scripts/generate-model-manifest.mjs (verbatim
  diffusion copy) and the unit suite to test/unit/ensure-model-integrity.test.js
- manifest integrity stays null until pinned in CI (HF_TOKEN + network); the
  suite tolerates null now and enforces shape once pinned

Ref: QVAC-21937

Author: tobi-legan

…-llamacpp/scripts/pin-model-manifest.mjs …acpp/scripts/generate-model-manifest.mjspackages/embed-llamacpp/scripts/pin-model-manifest.mjs renamed to packages/embed-llamacpp/scripts/generate-model-manifest.mjs packages/embed-llamacpp/scripts/pin-model-manifest.mjs renamed to packages/embed-llamacpp/scripts/generate-model-manifest.mjs

@@ -4,16 +4,13 @@
 // Populates sha256 + bytes in test/integration/models.manifest.json by
 // downloading each pinned URL FRESH into a temp directory and hashing it.
 //
-// This is the integration-test model cache manifest (single source of truth for
-// URLs + integrity, and the .github/actions/cache-models cache key).
-//
 // IMPORTANT (integrity provenance): shas are computed from a clean download of
 // the pinned URL, never from packages/embed-llamacpp/test/model (which may be a
 // stale or poisoned restored cache). Run this on a machine/CI with network and
 // an HF_TOKEN for gated repos.
 //
 // Usage:
-//   HF_TOKEN=hf_xxx node scripts/pin-model-manifest.mjs [--only <modelName>] [--force]
+//   HF_TOKEN=hf_xxx node scripts/generate-model-manifest.mjs [--only <modelName>] [--force]
 //
 // Flags:
 //   --only <name>   Only (re)generate the named model entry.

packages/embed-llamacpp/test/integration/addon.test.js

@@ -592,7 +592,7 @@ const DEVICE_API = isDarwinX64 || isLinuxArm64 ? 'cpu' : 'gpu'
 const MODEL_NAME_API = getModelConfigs()[0]?.modelName ?? 'embeddinggemma-300M-Q8_0.gguf'
 
 async function setupModelApiBehavior (t) {
-  await ensureModel(MODEL_NAME_API)
+  await ensureModel({ modelName: MODEL_NAME_API })
   const { inference } = await createEmbeddingsTestInstance(
     t,
     MODEL_NAME_API,

packages/embed-llamacpp/test/integration/multi-gpu.test.js

@@ -35,7 +35,7 @@ async function runMultiGpuTest (t, extraConfig, assertDevices) {
     return
   }
 
-  const [modelName, dirPath] = await ensureModel(MODEL.name)
+  const [modelName, dirPath] = await ensureModel({ modelName: MODEL.name })
   const modelPath = path.join(dirPath, modelName)
   const specLogger = attachSpecLogger({ forwardToConsole: true })
 

packages/embed-llamacpp/test/integration/utils.js

@@ -301,10 +301,12 @@ function prestagedModelDir (modelName) {
 
 /**
  * Ensures the model file exists, downloading it if necessary
- * @param {string} modelName - The model name to ensure
+ * @param {Object} opts
+ * @param {string} opts.modelName - The model name to ensure
  * @returns {Promise<[string, string]>} Returns [modelName, modelDir]
  */
-async function ensureModel (modelName, { modelDir = path.resolve(__dirname, '../model'), manifest, download } = {}) {
+async function ensureModel ({ modelName, modelDir, manifest, download } = {}) {
+  const dir = modelDir || path.resolve(__dirname, '../model')
   const modelConfig = getModelConfig(modelName)
 
   // Model URL + sha256/bytes come from models.manifest.json (by modelName); the
@@ -318,7 +320,7 @@ async function ensureModel (modelName, { modelDir = path.resolve(__dirname, '../
     throw new Error(`Unknown model: ${modelName}`)
   }
 
-  const modelPath = path.join(modelDir, modelName)
+  const modelPath = path.join(dir, modelName)
   const doDownload = download || downloadFileWithRetries
   const urls = hasManifestUrls ? entry.urls : [modelConfig.downloadUrl]
   const hasIntegrity = entryHasIntegrity(entry)
@@ -328,17 +330,21 @@ async function ensureModel (modelName, { modelDir = path.resolve(__dirname, '../
       const res = await verifyModelFile(modelPath, entry)
       if (res.ok) {
         console.log(`[download] ${modelName}: cached copy verified, skipping download`)
-        return [modelName, modelDir]
+        return [modelName, dir]
       }
       console.log(`[download] ${modelName}: cached copy failed integrity (${res.reason}); deleting and re-downloading`)
       try { fs.unlinkSync(modelPath) } catch (_) {}
     } else {
       const stat = fs.statSync(modelPath)
-      if (stat.size > 0) {
-        return [modelName, modelDir]
+      if (stat.size === 0) {
+        console.log(`[download] Removing zero-byte cached file: ${modelName}`)
+        fs.unlinkSync(modelPath)
+      } else {
+        if (entry) {
+          console.log(`[download] ${modelName}: no sha256/bytes pinned in manifest — integrity check SKIPPED (run scripts/generate-model-manifest.mjs to pin)`)
+        }
+        return [modelName, dir]
       }
-      console.log(`[download] Removing zero-byte cached file: ${modelName}`)
-      fs.unlinkSync(modelPath)
     }
   }
 
@@ -348,18 +354,18 @@ async function ensureModel (modelName, { modelDir = path.resolve(__dirname, '../
   // load() writes sibling files next to the model (e.g. openclCacheDir).
   const staged = prestagedModelDir(modelName)
   if (staged) {
-    fs.mkdirSync(modelDir, { recursive: true })
+    fs.mkdirSync(dir, { recursive: true })
     console.log(`[prestage] Using pre-staged model ${modelName} (copying into writable modelDir)`)
     fs.copyFileSync(path.join(staged, modelName), modelPath)
     const stat = fs.statSync(modelPath)
     if (stat.size === 0) {
       fs.unlinkSync(modelPath)
       throw new Error(`[prestage] copied model ${modelName} is empty`)
     }
-    return [modelName, modelDir]
+    return [modelName, dir]
   }
 
-  fs.mkdirSync(modelDir, { recursive: true })
+  fs.mkdirSync(dir, { recursive: true })
   console.log(`[download] Downloading test model: ${modelName}...`)
   _downloadCount++
 
@@ -376,7 +382,7 @@ async function ensureModel (modelName, { modelDir = path.resolve(__dirname, '../
   const stat = fs.statSync(modelPath)
   console.log(`[download] Model ready: ${(stat.size / 1024 / 1024).toFixed(1)}MB`)
 
-  return [modelName, modelDir]
+  return [modelName, dir]
 }
 
 /**
@@ -410,7 +416,7 @@ class TestLogger {
  * @returns {Promise<{inference: GGMLBert}>}
  */
 async function createEmbeddingsTestInstance (t, modelName, device = 'gpu', gpuLayers = null, batchSize = '1024') {
-  const [, modelDir] = await ensureModel(modelName)
+  const [, modelDir] = await ensureModel({ modelName })
   const modelPath = path.join(modelDir, modelName)
 
   t.ok(fs.existsSync(modelPath), 'Model file should exist')

…/test/unit/ensure-model-manifest.test.js …test/unit/ensure-model-integrity.test.jspackages/embed-llamacpp/test/unit/ensure-model-manifest.test.js renamed to packages/embed-llamacpp/test/unit/ensure-model-integrity.test.js packages/embed-llamacpp/test/unit/ensure-model-manifest.test.js renamed to packages/embed-llamacpp/test/unit/ensure-model-integrity.test.js

@@ -1,10 +1,11 @@
 'use strict'
 
-// Offline proof for the models.manifest.json wiring (QVAC-21937): ensureModel
-// resolves URLs + integrity from the manifest, re-downloads poisoned/truncated
+// Offline integrity/manifest proof for embed-llamacpp, mirroring
+// diffusion-cpp/test/unit/ensure-model-integrity.test.js: ensureModel resolves
+// URL + sha256/bytes from models.manifest.json, re-downloads poisoned/truncated
 // caches, falls back to MODEL_CONFIGS when the manifest lacks an entry, and the
-// real integration manifest is well-formed. No network and no native addon are
-// touched — downloads are injected.
+// real manifest is well-formed. No network and no native addon are touched —
+// downloads are injected.
 
 const test = require('brittle')
 const fs = require('bare-fs')
@@ -27,7 +28,7 @@ const BAD_SHORT = 'too-short'
 
 function mkTmpDir () {
   const base = (typeof os.tmpdir === 'function' && os.tmpdir()) || '/tmp'
-  const dir = path.join(base, `qvac-embed-manifest-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  const dir = path.join(base, `qvac-embed-integrity-${Date.now()}-${Math.random().toString(36).slice(2)}`)
   fs.mkdirSync(dir, { recursive: true })
   return dir
 }
@@ -80,7 +81,7 @@ test('correct cached file verifies and performs NO download', async function (t)
   try {
     writeModel(dir, name, GOOD)
     resetDownloadCount()
-    const [, resolvedDir] = await ensureModel(name, { modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
+    const [, resolvedDir] = await ensureModel({ modelName: name, modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
     t.is(spy.calls, 0, 'no download for a valid cached file')
     t.is(getDownloadCount(), 0, 'download counter stays 0 on a warm run')
     t.is(resolvedDir, dir)
@@ -95,12 +96,12 @@ test('poisoned cached file (sha mismatch) is deleted and re-downloaded', async f
   const dir = mkTmpDir()
   const spy = { calls: 0 }
   try {
-    writeModel(dir, name, BAD_SAME_LEN)
+    writeModel(dir, name, BAD_SAME_LEN) // same length -> defeats size check, forces sha path
     resetDownloadCount()
-    await ensureModel(name, { modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
+    await ensureModel({ modelName: name, modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
     t.is(spy.calls, 1, 're-downloaded exactly once after integrity failure')
     t.is(getDownloadCount(), 1, 'download counter incremented')
-    t.is(fs.readFileSync(path.join(dir, name), 'utf8'), GOOD)
+    t.is(fs.readFileSync(path.join(dir, name), 'utf8'), GOOD, 'file replaced with correct content')
   } finally {
     fs.rmSync(dir, { recursive: true, force: true })
   }
@@ -113,7 +114,7 @@ test('truncated cached file (size mismatch) is re-downloaded', async function (t
   const spy = { calls: 0 }
   try {
     writeModel(dir, name, BAD_SHORT)
-    await ensureModel(name, { modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
+    await ensureModel({ modelName: name, modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
     t.is(spy.calls, 1, 'size mismatch triggered a re-download')
     t.is(fs.readFileSync(path.join(dir, name), 'utf8'), GOOD)
   } finally {
@@ -129,7 +130,7 @@ test('persistent mismatch hard-fails and removes the bad file', async function (
   try {
     writeModel(dir, name, BAD_SAME_LEN)
     await t.exception(
-      ensureModel(name, { modelDir: dir, manifest, download: fakeDownloader(BAD_SAME_LEN, spy) }),
+      ensureModel({ modelName: name, modelDir: dir, manifest, download: fakeDownloader(BAD_SAME_LEN, spy) }),
       /failed integrity/
     )
     t.is(spy.calls, 1, 'attempted a re-download before failing')
@@ -145,21 +146,35 @@ test('missing file downloads then verifies', async function (t) {
   const dir = mkTmpDir()
   const spy = { calls: 0 }
   try {
-    await ensureModel(name, { modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
+    await ensureModel({ modelName: name, modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
     t.is(spy.calls, 1, 'downloaded the missing file')
     t.is(fs.readFileSync(path.join(dir, name), 'utf8'), GOOD)
   } finally {
     fs.rmSync(dir, { recursive: true, force: true })
   }
 })
 
+test('entry without pinned integrity skips verification (keeps a non-zero cached file)', async function (t) {
+  const name = 'gte-large_fp16.gguf'
+  const manifest = { models: { [name]: { urls: ['https://example.invalid/x'], sha256: null, bytes: null } } }
+  const dir = mkTmpDir()
+  const spy = { calls: 0 }
+  try {
+    writeModel(dir, name, BAD_SAME_LEN) // any non-zero content is accepted when unpinned
+    await ensureModel({ modelName: name, modelDir: dir, manifest, download: fakeDownloader(GOOD, spy) })
+    t.is(spy.calls, 0, 'no download when an unpinned file already exists and is non-zero')
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
 test('MODEL_CONFIGS is used as a fallback when the manifest has no entry', async function (t) {
   const name = 'gte-large_fp16.gguf' // known in MODEL_CONFIGS
   const dir = mkTmpDir()
   const spy = { calls: 0 }
   try {
     t.ok(MODEL_CONFIGS[name], 'model is declared in MODEL_CONFIGS')
-    await ensureModel(name, { modelDir: dir, manifest: { models: {} }, download: fakeDownloader(GOOD, spy) })
+    await ensureModel({ modelName: name, modelDir: dir, manifest: { models: {} }, download: fakeDownloader(GOOD, spy) })
     t.is(spy.calls, 1, 'downloaded via the MODEL_CONFIGS fallback url')
     t.is(fs.readFileSync(path.join(dir, name), 'utf8'), GOOD)
   } finally {
@@ -171,7 +186,7 @@ test('truly unknown model (no config, no manifest entry) throws', async function
   const dir = mkTmpDir()
   try {
     await t.exception(
-      ensureModel('nope.gguf', { modelDir: dir, manifest: { models: {} } }),
+      ensureModel({ modelName: 'nope.gguf', modelDir: dir, manifest: { models: {} } }),
       /Unknown model/
     )
   } finally {
@@ -193,17 +208,28 @@ test('verifyModelFile flags size before hashing (fail-fast)', async function (t)
   }
 })
 
-test('real integration manifest is well-formed and matches MODEL_CONFIGS', function (t) {
+test('integration manifest is well-formed and covers MODEL_CONFIGS', function (t) {
   const manifest = loadManifest()
   t.ok(manifest && manifest.models, 'models.manifest.json loads')
   const names = Object.keys(manifest.models)
   t.is(new Set(names).size, names.length, 'no duplicate model keys')
+
   for (const [name, entry] of Object.entries(manifest.models)) {
     const hasUrl = Array.isArray(entry.urls) && entry.urls.length > 0 &&
       entry.urls.every(u => typeof u === 'string' && u.startsWith('https://'))
     t.ok(hasUrl, `${name} has at least one https url`)
+
+    // Integrity is pinned in CI (scripts/generate-model-manifest.mjs). When
+    // present it must be the right shape; null is allowed until pinned.
+    if (entry.sha256 !== null && entry.sha256 !== undefined) {
+      t.ok(/^[0-9a-f]{64}$/i.test(entry.sha256), `${name} sha256 is 64 hex chars when pinned`)
+    }
+    if (entry.bytes !== null && entry.bytes !== undefined) {
+      t.ok(Number.isInteger(entry.bytes) && entry.bytes > 0, `${name} bytes is a positive integer when pinned`)
+    }
   }
-  // Every MODEL_CONFIGS model must be represented in the manifest so warm covers it.
+
+  // Every MODEL_CONFIGS model must be represented so warm covers it.
   for (const name of Object.keys(MODEL_CONFIGS)) {
     t.ok(resolveModelEntry(name), `${name} present in manifest`)
   }