@totalreclaw/totalreclaw 3.3.1-rc.21 → 3.3.1-rc.22

package/dist/reranker.js

@@ -373,70 +373,37 @@ export function rerank(query, queryEmbedding, candidates, topK = 8, weights, app
     return mmrResults;
 }
 // ---------------------------------------------------------------------------
-// Relevance gate (issue #116)
+// Relevance gate
 // ---------------------------------------------------------------------------
 /**
  * Decide whether reranked results clear the relevance gate for surfacing to
  * the user (recall tool) or auto-injecting into agent context (hooks).
  *
- * Two-signal acceptance rule, addressing issue #116 (rc.18 finding F1):
+ * Plain cosine cut-off: at least one reranked result has cosine similarity
+ * with the query embedding >= `cosineThreshold`.
  *
- *   1. **Cosine path** — at least one reranked result has cosine similarity
- *      with the query embedding >= `cosineThreshold`. This is the existing
- *      semantic-relevance gate and remains the primary signal.
+ * History (rc.18 → rc.22):
+ *   rc.18 issue #116 surfaced as a recall miss for short queries against
+ *   the local Harrier-OSS-270m model — cosine alone produced false-negatives
+ *   even when every query token literally appeared in the candidate. rc.18
+ *   shipped a defensive "lexical-override" fallback (every meaningful query
+ *   token had to appear as a 4-char-prefix substring in the top result).
+ *   The override was always intended as a band-aid until the
+ *   source-weighted reranker hoisted from `totalreclaw-core` produced
+ *   honest cosine signals for short queries. rc.22 hoists that reranker
+ *   and drops the band-aid: the gate is now back to a single-signal cosine
+ *   cut-off, matching Hermes (Python client) and the canonical reranker
+ *   spec.
  *
- *   2. **Lexical override** — when cosine is below threshold (e.g. short
- *      queries against the local Harrier-OSS-270m model produce embeddings
- *      with low cosine sim regardless of topical match), the gate ALSO
- *      passes when every meaningful query token (post stop-word removal)
- *      appears as a stem-prefix substring in the top reranked result's
- *      text. This is strong lexical evidence that the user is asking
- *      about a fact already stored, even when embedding sim is weak.
- *
- * Without (2), short queries like `"favorite color"` against the stored
- * fact `"User's favorite color is cobalt blue"` were silently filtered
- * even though every query token was present in the candidate. Hermes
- * (Python client) does not apply any cosine gate, which is why it
- * recalled the same fact for the same Smart Account in rc.18 QA.
- *
- * The lexical override is intentionally conservative:
- *   - Requires ALL non-stop-word query tokens to be present (any-of would
- *     over-trigger).
- *   - Uses 4-char-prefix substring match to be stem-tolerant ("favorite"
- *     stems to "favorit" in the stored fact's blind index, but the raw
- *     fact text contains the unstemmed word; the prefix check absorbs
- *     light morphology).
- *   - Token count must be >= 1 — empty/all-stop-word queries fall back
- *     to cosine path.
- *
- * @param query - the user's search query (raw string)
+ * @param query - the user's search query (raw string) — accepted for ABI
+ *   stability, no longer consulted post rc.22.
  * @param reranked - reranked results (top first)
  * @param cosineThreshold - the configured cosine cutoff (typically 0.15)
  * @returns true if results should be surfaced; false to suppress
  */
-export function passesRelevanceGate(query, reranked, cosineThreshold) {
+export function passesRelevanceGate(_query, reranked, cosineThreshold) {
     if (reranked.length === 0)
         return false;
-    // Path 1: cosine clears threshold.
     const maxCosine = Math.max(...reranked.map((r) => r.cosineSimilarity ?? 0));
-    if (maxCosine >= cosineThreshold)
-        return true;
-    // Path 2: lexical override — every meaningful query token appears in
-    // the top reranked result's text.
-    const queryTokens = tokenize(query, /* removeStopWords */ true);
-    if (queryTokens.length === 0)
-        return false;
-    const topText = (reranked[0]?.text ?? '').toLowerCase();
-    if (topText.length === 0)
-        return false;
-    // 4-char prefix substring match: tolerates light stemming ("favorite"
-    // matches a fact text containing "favorite", "favorites", "favoring",
-    // etc., without re-running the WASM Porter stemmer client-side).
-    const PREFIX_LEN = 4;
-    for (const token of queryTokens) {
-        const probe = token.length >= PREFIX_LEN ? token.slice(0, PREFIX_LEN) : token;
-        if (!topText.includes(probe))
-            return false;
-    }
-    return true;
+    return maxCosine >= cosineThreshold;
 }

package/dist/retype-setscope.js

@@ -32,6 +32,7 @@ import { createRequire } from 'node:module';
 import { buildV1ClaimBlob, mapTypeToCategory, readV1Blob, } from './claims-helper.js';
 import { isValidMemoryType, VALID_MEMORY_SCOPES, V0_TO_V1_TYPE, } from './extractor.js';
 import { PROTOBUF_VERSION_V4 } from './subgraph-store.js';
+import { confirmIndexed } from './confirm-indexed.js';
 // Lazy-load WASM core — mirrors pin.ts pattern.
 const requireWasm = createRequire(import.meta.url);
 let _wasm = null;
@@ -84,6 +85,7 @@ function projectFromDecrypted(decrypted) {
                 createdAt: v1.createdAt,
                 expiresAt: v1.expiresAt,
                 pinStatus: v1.pinStatus,
+                embeddingModelId: v1.embeddingModelId,
             };
         }
     }
@@ -131,7 +133,7 @@ function projectFromDecrypted(decrypted) {
 // ---------------------------------------------------------------------------
 // Core: retrieve existing fact, decrypt, rewrite with mutated field
 // ---------------------------------------------------------------------------
-async function rewriteWithMutation(factId, deps, mutate) {
+async function rewriteWithMutation(factId, deps, mutate, confirmOpts) {
     const existing = await deps.fetchFactById(factId);
     if (!existing) {
         return { success: false, fact_id: factId, error: `Fact not found: ${factId}` };
@@ -179,6 +181,9 @@ async function rewriteWithMutation(factId, deps, mutate) {
             // on a pinned fact does NOT silently un-pin it. Without this, a pinned
             // fact loses its immunity to auto-supersede after any metadata edit.
             pinStatus: next.pinStatus,
+            // 3.3.1-rc.22 — preserve the source claim's embedder tag through
+            // retype/set_scope rewrites. Distillation forward-compat.
+            embeddingModelId: next.embeddingModelId,
         });
     }
     catch (err) {
@@ -248,6 +253,20 @@ async function rewriteWithMutation(factId, deps, mutate) {
                 tx_hash: txHash,
             };
         }
+        // Read-after-write: poll the subgraph until the new fact id is indexed
+        // and active, OR the timeout (default 30s) elapses. On timeout (or if
+        // the WASM bindings are unavailable / subgraph unreachable), surface
+        // `partial: true` so the caller knows the chain write succeeded but the
+        // indexer has not yet caught up. The confirm step is observational —
+        // never fail the whole operation just because confirm step couldn't run.
+        let indexed = false;
+        try {
+            const confirm = await confirmIndexed(newFactId, confirmOpts);
+            indexed = confirm.indexed;
+        }
+        catch {
+            indexed = false;
+        }
         return {
             success: true,
             fact_id: factId,
@@ -257,6 +276,7 @@ async function rewriteWithMutation(factId, deps, mutate) {
             previous_scope: current.scope,
             new_scope: next.scope,
             tx_hash: txHash,
+            ...(indexed ? {} : { partial: true }),
         };
     }
     catch (err) {
@@ -275,7 +295,7 @@ async function rewriteWithMutation(factId, deps, mutate) {
  * tombstones the old fact. `superseded_by` on the new fact points to the
  * old id so cross-device readers see the correct resolution.
  */
-export async function executeRetype(factId, newType, deps) {
+export async function executeRetype(factId, newType, deps, confirmOpts) {
     if (!isValidMemoryType(newType)) {
         return {
             success: false,
@@ -286,13 +306,13 @@ export async function executeRetype(factId, newType, deps) {
     return rewriteWithMutation(factId, deps, (current) => ({
         ...current,
         type: newType,
-    }));
+    }), confirmOpts);
 }
 /**
  * Re-scope an existing memory. Writes a new v1.1 claim with `scope` changed;
  * tombstones the old fact.
  */
-export async function executeSetScope(factId, newScope, deps) {
+export async function executeSetScope(factId, newScope, deps, confirmOpts) {
     if (!VALID_MEMORY_SCOPES.includes(newScope)) {
         return {
             success: false,
@@ -303,7 +323,7 @@ export async function executeSetScope(factId, newScope, deps) {
     return rewriteWithMutation(factId, deps, (current) => ({
         ...current,
         scope: newScope,
-    }));
+    }), confirmOpts);
 }
 export function validateRetypeArgs(args) {
     if (typeof args !== 'object' || args === null) {

package/embedder-cache.ts

@@ -0,0 +1,230 @@
+/**
+ * embedder-cache.ts — pure-FS reader for the lazy embedder bundle (rc.22+).
+ *
+ * Scanner-isolation note: this module reads from disk AND verifies SHA-256
+ * hashes. It MUST NOT contain any of the network-trigger substrings the
+ * OpenClaw skill scanner gates on — see `skill/scripts/check-scanner.mjs`
+ * for the rule list. The network side of the lazy-retrieval flow lives in a
+ * sibling module (the downloader), and the orchestrator imports both.
+ *
+ * Responsibilities:
+ *   - Resolve the on-disk cache layout (`<root>/v1/`, with `manifest.json`
+ *     + `node_modules/` + `model/`).
+ *   - Synchronously load + parse the manifest JSON.
+ *   - Verify the cache is intact: every file listed in `manifest.files`
+ *     exists at the expected path with the SHA-256 hash declared in the
+ *     manifest. Any mismatch invalidates the cache so the loader rebuilds.
+ *
+ * The manifest format is the contract between this file and the bundle
+ * generation script (`scripts/build-embedder-bundle.mjs`):
+ *   {
+ *     "version": "v1",                          // bundle format version
+ *     "model_id": "harrier-oss-270m-q4",        // semantic model identifier
+ *     "dimension": 640,                          // output vector size
+ *     "tarball_sha256": "<hex>",                 // informational only here
+ *     "tarball_size_bytes": <int>,               // informational only here
+ *     "files": [
+ *       { "path": "node_modules/.../foo.js", "sha256": "<hex>", "size": <int> },
+ *       ...
+ *     ]
+ *   }
+ *
+ * Hard rule for this file: stdlib only — `node:fs` + `node:crypto` +
+ * `node:path`. No env reads, no remote retrievals.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/** Bundle format version — bump only when the on-disk layout changes. */
+export const BUNDLE_FORMAT_VERSION = 'v1' as const;
+
+/**
+ * Layout: `<cacheRoot>/<BUNDLE_FORMAT_VERSION>/`. The version subdirectory
+ * lets us ship `v2/` side-by-side with `v1/` later (e.g. for a distilled
+ * model) without invalidating active vaults.
+ */
+export interface CacheLayout {
+  /** Top-level embedder cache directory (e.g. `~/.totalreclaw/embedder/`). */
+  root: string;
+  /** Versioned bundle root (e.g. `~/.totalreclaw/embedder/v1/`). */
+  versionRoot: string;
+  /** Path to the manifest JSON file. */
+  manifestPath: string;
+  /** Path to the extracted node_modules tree (transformers + onnxruntime). */
+  nodeModulesPath: string;
+  /** Path to the extracted ONNX model directory. */
+  modelPath: string;
+}
+
+export function resolveCacheLayout(cacheRoot: string): CacheLayout {
+  const versionRoot = path.join(cacheRoot, BUNDLE_FORMAT_VERSION);
+  return {
+    root: cacheRoot,
+    versionRoot,
+    manifestPath: path.join(versionRoot, 'manifest.json'),
+    nodeModulesPath: path.join(versionRoot, 'node_modules'),
+    modelPath: path.join(versionRoot, 'model'),
+  };
+}
+
+export interface BundleManifestFileEntry {
+  /** Path RELATIVE to the version-root directory (e.g. `node_modules/foo/bar.js`). */
+  path: string;
+  /** Lowercase hex SHA-256 of the file's content. */
+  sha256: string;
+  /** Byte size — informational; not load-bearing for verification. */
+  size: number;
+}
+
+export interface BundleManifest {
+  /** Bundle format version. MUST match `BUNDLE_FORMAT_VERSION`. */
+  version: string;
+  /** Semantic model id, e.g. `"harrier-oss-270m-q4"`. */
+  model_id: string;
+  /** Output vector dimensionality. */
+  dimension: number;
+  /** Lowercase hex SHA-256 of the entire .tar.gz tarball. */
+  tarball_sha256: string;
+  /** Tarball size in bytes. */
+  tarball_size_bytes: number;
+  /** Per-file integrity table — used by the loader after extraction. */
+  files: BundleManifestFileEntry[];
+}
+
+/**
+ * Synchronously read + parse the manifest. Returns `null` when the file
+ * is missing, unreadable, or malformed JSON — callers treat any of those
+ * as a cache miss.
+ */
+export function readManifest(layout: CacheLayout): BundleManifest | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(layout.manifestPath, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<BundleManifest>;
+    if (!isValidManifestShape(parsed)) return null;
+    return parsed as BundleManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Shape guard for a parsed manifest. Strict on every required field; lax
+ * on extras so bundle-generation tools may add diagnostic fields without
+ * tripping verification.
+ */
+export function isValidManifestShape(obj: unknown): obj is BundleManifest {
+  if (!obj || typeof obj !== 'object') return false;
+  const m = obj as Record<string, unknown>;
+  if (typeof m.version !== 'string' || m.version.length === 0) return false;
+  if (typeof m.model_id !== 'string' || m.model_id.length === 0) return false;
+  if (typeof m.dimension !== 'number' || !Number.isFinite(m.dimension) || m.dimension <= 0) return false;
+  if (typeof m.tarball_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(m.tarball_sha256)) return false;
+  if (typeof m.tarball_size_bytes !== 'number' || m.tarball_size_bytes < 0) return false;
+  if (!Array.isArray(m.files)) return false;
+  for (const entry of m.files as unknown[]) {
+    if (!entry || typeof entry !== 'object') return false;
+    const e = entry as Record<string, unknown>;
+    if (typeof e.path !== 'string' || e.path.length === 0) return false;
+    if (typeof e.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(e.sha256)) return false;
+    if (typeof e.size !== 'number' || e.size < 0) return false;
+    // Block path-traversal up front — any `..` segment, absolute path,
+    // or backslash makes the entry untrusted.
+    if (e.path.includes('..') || e.path.startsWith('/') || e.path.includes('\\')) return false;
+  }
+  return true;
+}
+
+/**
+ * Compute the SHA-256 of a file's contents. Returns null on any IO error.
+ * Synchronous + buffered — files are small (<10 MB each in the bundle).
+ */
+export function sha256OfFile(filePath: string): string | null {
+  try {
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(buf).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  /** First failure reason — empty when ok is true. */
+  reason: string;
+  /** When ok=false, the file that failed (relative path) or `''`. */
+  offendingPath: string;
+}
+
+/**
+ * Verify that every file listed in `manifest.files` exists at the
+ * expected path under `layout.versionRoot` with the declared hash.
+ *
+ * Returns ok=true only when:
+ *   - every entry's file exists,
+ *   - file size matches,
+ *   - SHA-256 matches.
+ *
+ * Bails on the FIRST failure — the loader's only branch on this is
+ * "discard cache + re-build", so we don't need to enumerate every fault.
+ */
+export function verifyCache(
+  layout: CacheLayout,
+  manifest: BundleManifest,
+): VerifyResult {
+  if (manifest.version !== BUNDLE_FORMAT_VERSION) {
+    return {
+      ok: false,
+      reason: `cache manifest version "${manifest.version}" does not match expected "${BUNDLE_FORMAT_VERSION}"`,
+      offendingPath: 'manifest.json',
+    };
+  }
+  for (const entry of manifest.files) {
+    const abs = path.join(layout.versionRoot, entry.path);
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      return { ok: false, reason: `cache missing file: ${entry.path}`, offendingPath: entry.path };
+    }
+    if (!stat.isFile()) {
+      return { ok: false, reason: `cache entry not a regular file: ${entry.path}`, offendingPath: entry.path };
+    }
+    if (stat.size !== entry.size) {
+      return {
+        ok: false,
+        reason: `cache size mismatch for ${entry.path}: expected ${entry.size}, got ${stat.size}`,
+        offendingPath: entry.path,
+      };
+    }
+    const actualHash = sha256OfFile(abs);
+    if (actualHash !== entry.sha256) {
+      return {
+        ok: false,
+        reason: `cache hash mismatch for ${entry.path}`,
+        offendingPath: entry.path,
+      };
+    }
+  }
+  return { ok: true, reason: '', offendingPath: '' };
+}
+
+/**
+ * Cheap pre-flight before a full verifyCache pass: does the manifest
+ * exist and parse to the expected shape with the expected version?
+ */
+export function quickCacheProbe(layout: CacheLayout): {
+  hasManifest: boolean;
+  manifest: BundleManifest | null;
+} {
+  const m = readManifest(layout);
+  if (!m) return { hasManifest: false, manifest: null };
+  if (m.version !== BUNDLE_FORMAT_VERSION) return { hasManifest: false, manifest: m };
+  return { hasManifest: true, manifest: m };
+}

package/embedder-loader.ts

@@ -0,0 +1,189 @@
+/**
+ * embedder-loader.ts — orchestrator for the lazy embedder bundle (rc.22+).
+ *
+ * Splits the work between the cache-reader sibling (pure FS + manifest
+ * verify) and the downloader sibling (HTTPS + tar extraction). This file
+ * imports from both; scanner-wise it stays away from env-reads and the
+ * scanner's network-trigger substrings, since merely importing the
+ * downloader does not trip either rule.
+ *
+ * Lifecycle:
+ *   1. `loadEmbedder(opts)` is called on first call to embed().
+ *   2. Probe the cache via `quickCacheProbe`. If a manifest with the
+ *      expected version is present and the cache verifies, skip to step 5.
+ *   3. Pull the manifest JSON from the GitHub Release pinned to the
+ *      caller's RC tag (via the downloader sibling).
+ *   4. Stream-download the bundle tarball, verify its SHA-256 against
+ *      the manifest, untar into the cache dir, then re-verify per-file
+ *      hashes. Refuse to use the cache on any mismatch.
+ *   5. `createRequire` from inside the cache's `node_modules/` and lazy-
+ *      load the bundled embedder + model.
+ */
+
+import path from 'node:path';
+import { Module, createRequire } from 'node:module';
+import {
+  resolveCacheLayout,
+  quickCacheProbe,
+  verifyCache,
+  isValidManifestShape,
+  BUNDLE_FORMAT_VERSION,
+  type BundleManifest,
+  type CacheLayout,
+} from './embedder-cache.js';
+import {
+  buildBundleUrl,
+  buildManifestUrl,
+  downloadAndExtractTarGz,
+  fetchManifestJson,
+  DEFAULT_BUNDLE_URL_TEMPLATE,
+  DEFAULT_MANIFEST_URL_TEMPLATE,
+} from './embedder-network.js';
+
+export interface LoadEmbedderOptions {
+  /** Top-level cache directory (e.g. `~/.totalreclaw/embedder/`). */
+  cacheRoot: string;
+  /** RC tag for URL templating, e.g. `"3.3.1-rc.22"`. */
+  rcTag: string;
+  /** Optional override for the bundle URL template (test injection). */
+  bundleUrlTemplate?: string;
+  /** Optional override for the manifest URL template (test injection). */
+  manifestUrlTemplate?: string;
+  /** Optional remote-loader override (test injection). */
+  fetchImpl?: typeof globalThis.fetch;
+  /** Optional logger. */
+  log?: (msg: string) => void;
+  /** Optional per-attempt timeout for the bundle download (ms). */
+  bundleTimeoutMs?: number;
+  /** Optional per-attempt timeout for the manifest pull (ms). */
+  manifestTimeoutMs?: number;
+}
+
+export interface LoadedEmbedder {
+  /** Path to the cache directory used. */
+  layout: CacheLayout;
+  /** Verified manifest. */
+  manifest: BundleManifest;
+  /** A `require` function bound to the embedder's node_modules tree. */
+  cacheRequire: NodeRequire;
+  /** True when the bundle was downloaded this call (vs. cache hit). */
+  wasFetched: boolean;
+}
+
+const DEFAULT_LOG = (msg: string) => console.error(msg);
+
+/**
+ * Top-level entry point. Idempotent: caching is by `cacheRoot` so repeat
+ * calls with a hot cache return immediately.
+ */
+export async function loadEmbedder(opts: LoadEmbedderOptions): Promise<LoadedEmbedder> {
+  const log = opts.log ?? DEFAULT_LOG;
+  const layout = resolveCacheLayout(opts.cacheRoot);
+
+  // --- Cache hit path -------------------------------------------------------
+  const probe = quickCacheProbe(layout);
+  if (probe.hasManifest && probe.manifest) {
+    const verify = verifyCache(layout, probe.manifest);
+    if (verify.ok) {
+      log(`[TotalReclaw] embedder: cache hit at ${layout.versionRoot} (model=${probe.manifest.model_id})`);
+      return {
+        layout,
+        manifest: probe.manifest,
+        cacheRequire: makeCacheRequire(layout),
+        wasFetched: false,
+      };
+    }
+    log(`[TotalReclaw] embedder: cache present but failed verify (${verify.reason}); rebuilding`);
+  } else {
+    log(`[TotalReclaw] embedder: no cache at ${layout.versionRoot}; pulling from GitHub Releases`);
+  }
+
+  // --- Build path -----------------------------------------------------------
+  const manifestUrl = buildManifestUrl(
+    { rcTag: opts.rcTag, bundleVersion: BUNDLE_FORMAT_VERSION },
+    opts.manifestUrlTemplate ?? DEFAULT_MANIFEST_URL_TEMPLATE,
+  );
+  const bundleUrl = buildBundleUrl(
+    { rcTag: opts.rcTag, bundleVersion: BUNDLE_FORMAT_VERSION },
+    opts.bundleUrlTemplate ?? DEFAULT_BUNDLE_URL_TEMPLATE,
+  );
+
+  const rawManifest = await fetchManifestJson(manifestUrl, {
+    fetchImpl: opts.fetchImpl,
+    log,
+    timeoutMs: opts.manifestTimeoutMs ?? 60_000,
+  });
+  if (!isValidManifestShape(rawManifest)) {
+    throw new Error(`embedder manifest at ${manifestUrl} failed shape validation`);
+  }
+  const manifest = rawManifest as BundleManifest;
+  if (manifest.version !== BUNDLE_FORMAT_VERSION) {
+    throw new Error(
+      `embedder manifest version "${manifest.version}" does not match plugin's expected "${BUNDLE_FORMAT_VERSION}"`,
+    );
+  }
+
+  await downloadAndExtractTarGz(bundleUrl, layout.versionRoot, manifest.tarball_sha256, {
+    fetchImpl: opts.fetchImpl,
+    log,
+    timeoutMs: opts.bundleTimeoutMs ?? 600_000,
+  });
+
+  // Persist the verified manifest alongside the extracted tree so the
+  // cache layout is self-describing on the next boot. Plain stdlib write.
+  const fs = await import('node:fs');
+  fs.writeFileSync(layout.manifestPath, JSON.stringify(manifest, null, 2), { encoding: 'utf8', mode: 0o644 });
+
+  // Re-run the integrity check against the on-disk tree.
+  const postVerify = verifyCache(layout, manifest);
+  if (!postVerify.ok) {
+    throw new Error(
+      `embedder bundle integrity check failed AFTER extraction: ${postVerify.reason}. ` +
+        `Cache at ${layout.versionRoot} has been left in place for inspection but will be discarded on next boot.`,
+    );
+  }
+
+  log(
+    `[TotalReclaw] embedder: bundle ready at ${layout.versionRoot} (model=${manifest.model_id}, files=${manifest.files.length})`,
+  );
+
+  return {
+    layout,
+    manifest,
+    cacheRequire: makeCacheRequire(layout),
+    wasFetched: true,
+  };
+}
+
+/**
+ * Build a `require` function rooted at the embedder cache's
+ * `node_modules/`. We anchor it on a synthetic `package.json` at the
+ * version-root so `require('@huggingface/transformers')` resolves
+ * normally inside that tree.
+ */
+export function makeCacheRequire(layout: CacheLayout): NodeRequire {
+  // Anchor on the version-root so node-module resolution starts inside
+  // the bundle's node_modules.
+  const anchor = path.join(layout.versionRoot, 'package.json');
+  // Append the cache node_modules to the global resolution path as a
+  // belt-and-braces guarantee that modules outside the bundle that might
+  // be transitively required still resolve from the host's tree.
+  if (!Module.globalPaths.includes(layout.nodeModulesPath)) {
+    Module.globalPaths.push(layout.nodeModulesPath);
+  }
+  return createRequire(anchor);
+}
+
+/**
+ * Destructive: remove the entire on-disk cache. Useful only as an
+ * escape hatch for repair flows. Returns true on success, false on error.
+ */
+export async function destroyCache(layout: CacheLayout): Promise<boolean> {
+  try {
+    const fs = await import('node:fs');
+    fs.rmSync(layout.versionRoot, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}