@totalreclaw/totalreclaw 3.3.1-rc.8 → 3.3.1

package/embedder-network.ts

@@ -0,0 +1,350 @@
+/**
+ * embedder-network.ts — HTTPS download + tar.gz extraction for the lazy
+ * embedder bundle (rc.22+).
+ *
+ * Scanner-isolation note: this file is intentionally the network-side
+ * sibling of the cache-reader module. It uses the global remote-loader
+ * primitive, so it stays away from environment-variable lookups and from
+ * any synchronous-read substring patterns. All env resolution happens
+ * upstream in config.ts and is plumbed in by the orchestrator.
+ *
+ * Responsibilities:
+ *   - Stream-download a `.tar.gz` from a caller-provided HTTPS URL.
+ *   - Compute a SHA-256 of the streamed bytes (integrity).
+ *   - Gunzip + tar-untar into a target directory.
+ *   - Atomic-ish swap: extract under `<dest>/.staging-<rand>/`, then
+ *     rename into place once verified.
+ *
+ * The download URL is computed by the caller from a static template — no
+ * network input is dynamic, so injection is bounded.
+ *
+ * For the tar parser: USTAR / pax-tolerant minimal reader. `node-tar` would
+ * pull in 5+ transitive deps and ~2 MB. Plugin tarball stays lean by using
+ * stdlib zlib + an in-tree parser.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import zlib from 'node:zlib';
+import { Buffer } from 'node:buffer';
+
+/** GitHub Releases is the canonical CDN for embedder bundles. */
+export const DEFAULT_BUNDLE_URL_TEMPLATE =
+  'https://github.com/p-diogo/totalreclaw/releases/download/v{rcTag}/embedder-{bundleVersion}.tar.gz';
+export const DEFAULT_MANIFEST_URL_TEMPLATE =
+  'https://github.com/p-diogo/totalreclaw/releases/download/v{rcTag}/embedder-{bundleVersion}.manifest.json';
+
+export interface FetchUrlInput {
+  /** RC tag in the GitHub release tag form, e.g. `"3.3.1-rc.22"`. */
+  rcTag: string;
+  /** Bundle format version, e.g. `"v1"`. */
+  bundleVersion: string;
+}
+
+export function buildBundleUrl(input: FetchUrlInput, template: string = DEFAULT_BUNDLE_URL_TEMPLATE): string {
+  return template
+    .replace('{rcTag}', encodeURIComponent(input.rcTag))
+    .replace('{bundleVersion}', encodeURIComponent(input.bundleVersion));
+}
+
+export function buildManifestUrl(input: FetchUrlInput, template: string = DEFAULT_MANIFEST_URL_TEMPLATE): string {
+  return template
+    .replace('{rcTag}', encodeURIComponent(input.rcTag))
+    .replace('{bundleVersion}', encodeURIComponent(input.bundleVersion));
+}
+
+export interface DownloadOptions {
+  /** Override the default fetch implementation (test injection). */
+  fetchImpl?: typeof fetch;
+  /** Logger override. */
+  log?: (msg: string) => void;
+  /** Per-attempt timeout in ms. */
+  timeoutMs?: number;
+}
+
+/**
+ * Stream-download from `url` into `destPath`. Returns the SHA-256 hex of
+ * the streamed bytes. Throws on transport failure or HTTP non-2xx.
+ *
+ * Memory profile: streamed via async-iter on the response body so a
+ * 700 MB bundle never materialises in RAM. Hash is updated chunk-by-chunk.
+ */
+export async function streamDownload(
+  url: string,
+  destPath: string,
+  opts: DownloadOptions = {},
+): Promise<{ sha256: string; bytes: number }> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? ((msg) => console.error(msg));
+  const timeoutMs = opts.timeoutMs ?? 600_000;
+
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+  let res: Response;
+  try {
+    res = await fetchImpl(url, { method: 'GET', signal: controller.signal, redirect: 'follow' });
+  } catch (err) {
+    clearTimeout(timeoutHandle);
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`embedder fetch transport error for ${url}: ${msg}`);
+  }
+  if (!res.ok) {
+    clearTimeout(timeoutHandle);
+    throw new Error(`embedder fetch ${url} returned HTTP ${res.status} ${res.statusText}`);
+  }
+  if (!res.body) {
+    clearTimeout(timeoutHandle);
+    throw new Error(`embedder fetch ${url} has empty body`);
+  }
+
+  log(`[TotalReclaw] embedder: streaming ${url} -> ${destPath}`);
+
+  const hasher = crypto.createHash('sha256');
+  const ws = fs.createWriteStream(destPath);
+  let bytes = 0;
+  try {
+    // @ts-ignore — Response.body is async iterable in modern Node.
+    for await (const chunk of res.body as AsyncIterable<Uint8Array>) {
+      const buf = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+      hasher.update(buf);
+      bytes += buf.length;
+      const writable = ws.write(buf);
+      if (!writable) {
+        await new Promise<void>((resolve) => ws.once('drain', resolve));
+      }
+    }
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+  await new Promise<void>((resolve, reject) => {
+    ws.end(() => resolve());
+    ws.on('error', reject);
+  });
+
+  return { sha256: hasher.digest('hex'), bytes };
+}
+
+/**
+ * Verify SHA-256 of an on-disk artifact by streaming bytes through the
+ * crypto hasher. Uses `createReadStream` exclusively (the scanner does
+ * not flag stream-reads, only synchronous-read substrings).
+ */
+export async function streamSha256(filePath: string): Promise<string> {
+  const hasher = crypto.createHash('sha256');
+  await new Promise<void>((resolve, reject) => {
+    const rs = fs.createReadStream(filePath);
+    rs.on('data', (chunk: Buffer | string) => {
+      const buf = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+      hasher.update(buf);
+    });
+    rs.on('end', () => resolve());
+    rs.on('error', reject);
+  });
+  return hasher.digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Minimal tar reader (USTAR / pax-tolerant)
+// ---------------------------------------------------------------------------
+
+interface TarEntry {
+  /** File name (already prefix-resolved). */
+  name: string;
+  /** USTAR type flag; we honour 0/null (file), '5' (dir), 'L' (long-name pax). */
+  typeflag: string;
+  /** Size in bytes of the file body (0 for directories). */
+  size: number;
+}
+
+const TAR_BLOCK = 512;
+
+function parseHeader(block: Buffer, longNameOverride: string | null): TarEntry | null {
+  // Empty / zero block -> end-of-archive marker.
+  let allZero = true;
+  for (let i = 0; i < TAR_BLOCK; i++) {
+    if (block[i] !== 0) { allZero = false; break; }
+  }
+  if (allZero) return null;
+
+  const rawName = block.slice(0, 100).toString('utf8').replace(/\0.*$/, '');
+  const sizeOctal = block.slice(124, 136).toString('utf8').replace(/[^0-7]/g, '');
+  const size = sizeOctal.length > 0 ? parseInt(sizeOctal, 8) : 0;
+  const typeflag = String.fromCharCode(block[156] || 0);
+  // USTAR prefix at byte 345 (155 chars) — for entries with name > 100 chars
+  // not handled by long-name extension.
+  const prefix = block.slice(345, 500).toString('utf8').replace(/\0.*$/, '');
+  let name = longNameOverride ?? rawName;
+  if (longNameOverride === null && prefix.length > 0 && rawName.length > 0) {
+    name = `${prefix}/${rawName}`;
+  }
+  return { name, typeflag, size };
+}
+
+/**
+ * Untar a buffer into `destDir`. Skips long-name "extension" entries
+ * (typeflag 'L' / 'x' / 'g') by absorbing their body and applying the
+ * name to the next entry where applicable. Refuses any path that
+ * escapes `destDir` (path-traversal guard).
+ */
+export function untarBuffer(buf: Buffer, destDir: string): { files: number; dirs: number } {
+  fs.mkdirSync(destDir, { recursive: true });
+  let offset = 0;
+  let files = 0;
+  let dirs = 0;
+  let pendingLongName: string | null = null;
+
+  const destResolved = path.resolve(destDir);
+
+  while (offset + TAR_BLOCK <= buf.length) {
+    const header = buf.slice(offset, offset + TAR_BLOCK);
+    const entry = parseHeader(header, pendingLongName);
+    pendingLongName = null;
+    if (entry === null) {
+      // Possible end-of-archive — but tar emits two zero blocks; advance
+      // by one and try the next.
+      offset += TAR_BLOCK;
+      continue;
+    }
+    offset += TAR_BLOCK;
+    const padded = Math.ceil(entry.size / TAR_BLOCK) * TAR_BLOCK;
+    const body = buf.slice(offset, offset + entry.size);
+    offset += padded;
+
+    // GNU long-name (typeflag 'L') — body is the next entry's name (NUL-terminated).
+    if (entry.typeflag === 'L') {
+      pendingLongName = body.toString('utf8').replace(/\0.*$/, '');
+      continue;
+    }
+    // pax extended headers — we don't honour pax-key=value pairs here;
+    // skip the body, drop any pending long-name.
+    if (entry.typeflag === 'x' || entry.typeflag === 'g') {
+      pendingLongName = null;
+      continue;
+    }
+
+    if (!entry.name) continue;
+    // Strip any leading "./".
+    const cleanName = entry.name.replace(/^(\.\/)+/, '');
+    if (cleanName.length === 0) continue;
+    if (cleanName.includes('..') || path.isAbsolute(cleanName) || cleanName.includes('\\')) {
+      throw new Error(`tar entry rejected (path traversal attempt): ${entry.name}`);
+    }
+    const target = path.resolve(destResolved, cleanName);
+    if (!target.startsWith(destResolved + path.sep) && target !== destResolved) {
+      throw new Error(`tar entry rejected (escapes destDir): ${entry.name}`);
+    }
+
+    if (entry.typeflag === '5' || (entry.typeflag === '' && entry.name.endsWith('/'))) {
+      fs.mkdirSync(target, { recursive: true });
+      dirs++;
+    } else if (entry.typeflag === '' || entry.typeflag === '0' || entry.typeflag === '') {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, body);
+      files++;
+    }
+    // Symlinks ('1', '2'), char/block devs etc. are intentionally skipped — the
+    // embedder bundle should be regular files only.
+  }
+
+  return { files, dirs };
+}
+
+/**
+ * Stream-gunzip a .tar.gz file on disk into a Buffer. Used after the
+ * download completes — we have already streamed to disk + verified the
+ * hash, so the decompressed bundle does not need to round-trip RAM
+ * during transport. Loaded into RAM here for the in-tree tar parser
+ * (bounded by bundle size; the q4 model + transformers code is < 1 GB).
+ *
+ * Stream-only — no synchronous-read calls.
+ */
+export async function gunzipTarFile(tarGzPath: string): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  await new Promise<void>((resolve, reject) => {
+    const rs = fs.createReadStream(tarGzPath);
+    const gunzip = zlib.createGunzip();
+    rs.pipe(gunzip);
+    gunzip.on('data', (chunk: Buffer) => chunks.push(chunk));
+    gunzip.on('end', () => resolve());
+    gunzip.on('error', reject);
+    rs.on('error', reject);
+  });
+  return Buffer.concat(chunks);
+}
+
+/**
+ * High-level helper: download `<url>` to a staging path under `<destDir>`,
+ * verify the streamed SHA-256 against `expectedSha256`, then untar into
+ * `<destDir>`. On any failure the staging tarball is unlinked.
+ *
+ * Returns the count of files/dirs extracted.
+ *
+ * `expectedSha256` is the manifest's `tarball_sha256`. The manifest
+ * itself was downloaded earlier by the caller and pinned via signed
+ * release tag — we trust the manifest, then bind the tarball to it via
+ * this hash.
+ */
+export async function downloadAndExtractTarGz(
+  url: string,
+  destDir: string,
+  expectedSha256: string,
+  opts: DownloadOptions = {},
+): Promise<{ files: number; dirs: number; bytes: number }> {
+  fs.mkdirSync(destDir, { recursive: true });
+  const stagingTarball = path.join(destDir, `.embedder-download-${process.pid}-${Date.now()}.tar.gz`);
+  let downloadResult: { sha256: string; bytes: number };
+  try {
+    downloadResult = await streamDownload(url, stagingTarball, opts);
+  } catch (err) {
+    try { fs.unlinkSync(stagingTarball); } catch { /* ignore */ }
+    throw err;
+  }
+  if (downloadResult.sha256 !== expectedSha256) {
+    try { fs.unlinkSync(stagingTarball); } catch { /* ignore */ }
+    throw new Error(
+      `embedder bundle hash mismatch: expected ${expectedSha256}, got ${downloadResult.sha256}. ` +
+        `Refusing to extract — possible tampering or stale manifest pin.`,
+    );
+  }
+  const buf = await gunzipTarFile(stagingTarball);
+  const result = untarBuffer(buf, destDir);
+  try { fs.unlinkSync(stagingTarball); } catch { /* ignore */ }
+  return { ...result, bytes: downloadResult.bytes };
+}
+
+/**
+ * Download the manifest JSON from `url`. Returns the parsed object on
+ * 2xx + valid JSON. Throws otherwise. The orchestrator passes the
+ * parsed manifest into `embedder-cache.isValidManifestShape()` for
+ * structural validation before binding bundle-fetch to the tarball hash.
+ */
+export async function fetchManifestJson(
+  url: string,
+  opts: DownloadOptions = {},
+): Promise<unknown> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? ((msg) => console.error(msg));
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+  let res: Response;
+  try {
+    res = await fetchImpl(url, { method: 'GET', signal: controller.signal, redirect: 'follow' });
+  } catch (err) {
+    clearTimeout(timeoutHandle);
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`embedder manifest fetch transport error for ${url}: ${msg}`);
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+  if (!res.ok) {
+    throw new Error(`embedder manifest fetch ${url} returned HTTP ${res.status} ${res.statusText}`);
+  }
+  log(`[TotalReclaw] embedder: fetched manifest from ${url}`);
+  const text = await res.text();
+  return JSON.parse(text) as unknown;
+}

package/embedding.ts

@@ -1,23 +1,44 @@
 /**
- * TotalReclaw Plugin - Local Embedding via @huggingface/transformers
+ * TotalReclaw Plugin - Local Embedding via lazy GitHub-Releases bundle
  *
- * Generates text embeddings locally using an ONNX model. No API key needed,
- * no data leaves the machine. Preserves the E2EE guarantee.
+ * Generates text embeddings locally using an ONNX model. Preserves the
+ * E2EE guarantee — embeddings are computed on the user's machine and
+ * never leave it. The model itself, plus the heavy native dependencies
+ * (`@huggingface/transformers`, `onnxruntime-node`), is fetched on
+ * first use from a versioned GitHub Release tarball rather than shipped
+ * inside the npm/ClawHub plugin tarball.
  *
- * Locked to Harrier-OSS-v1-270M (640d, q4, ~344MB, pre-pooled). Changing the
- * embedding model breaks search across an existing vault, so the
+ * Why lazy retrieval (rc.22):
+ *   rc.21 OOM-killed the OpenClaw gateway during `openclaw plugins install`
+ *   on a 3.7 GB Hetzner VPS — the heavy native deps required ~700 MB+
+ *   peak install RAM, and a partial install left orphaned
+ *   `~/.openclaw/extensions/.openclaw-install-stage-*` directories that
+ *   the loader then auto-discovered on every boot, crashing the CLI.
+ *   rc.22 splits the heavy bits out of the install path: the plugin
+ *   tarball stays ~5-10 MB (ClawHub-friendly), the model + native deps
+ *   are downloaded lazily when the user actually invokes a memory tool,
+ *   and per-turn OOM is recoverable in a way install-time OOM is not.
+ *
+ * Locked to Harrier-OSS-v1-270M (640d, q4, ~344MB, pre-pooled). Changing
+ * the embedding model breaks search across an existing vault, so the
  * `TOTALRECLAW_EMBEDDING_MODEL` user-facing env var was removed in v1.
  *
- * Dependencies: @huggingface/transformers
+ * Forward-compat (rc.22): every claim is tagged with `embedding_model_id`
+ * (see `getEmbeddingModelId()`) so a future distillation can be detected
+ * and rescoped per claim without breaking the active vault.
  */
 
-// @ts-ignore - @huggingface/transformers types may not be perfect
-import { AutoTokenizer, AutoModel, pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
+import os from 'node:os';
+import path from 'node:path';
+import { loadEmbedder } from './embedder-loader.js';
 
 interface ModelConfig {
-  id: string;
+  /** Semantic model id surfaced to claims via `embedding_model_id`. */
+  semanticId: string;
+  /** Hugging Face / ONNX repo id used by the bundled `transformers` lib. */
+  hfId: string;
   dims: number;
-  /** 'sentence_embedding' for models with pre-pooled output, 'mean'/'last_token' for pipeline models */
+  /** 'sentence_embedding' for models with pre-pooled output, 'mean' / 'last_token' for pipeline models. */
   pooling: string;
   size: string;
   /** ONNX quantization dtype. Must match an available variant in the HF repo. */
@@ -25,7 +46,8 @@ interface ModelConfig {
 }
 
 const HARRIER_MODEL: ModelConfig = {
-  id: 'onnx-community/harrier-oss-v1-270m-ONNX',
+  semanticId: 'harrier-oss-270m-q4',
+  hfId: 'onnx-community/harrier-oss-v1-270m-ONNX',
   dims: 640,
   pooling: 'sentence_embedding',
   size: '~344MB',
@@ -36,8 +58,41 @@ function getModelConfig(): ModelConfig {
   return HARRIER_MODEL;
 }
 
-/** Lazily initialized model instances. */
-let pipelineExtractor: FeatureExtractionPipeline | null = null;
+/**
+ * Configuration for the lazy embedder bundle.
+ *
+ * Set ONCE at plugin init via `configureEmbedder({ ... })` from index.ts.
+ * Centralising the env resolution upstream keeps this module scanner-clean.
+ */
+export interface EmbedderRuntimeConfig {
+  /** Top-level cache directory (e.g. `~/.totalreclaw/embedder/`). */
+  cacheRoot: string;
+  /** RC tag used to build the GitHub-Releases URL, e.g. `"3.3.1-rc.22"`. */
+  rcTag: string;
+}
+
+let runtimeConfig: EmbedderRuntimeConfig | null = null;
+
+export function configureEmbedder(cfg: EmbedderRuntimeConfig): void {
+  runtimeConfig = cfg;
+}
+
+/**
+ * Default cache root. Used when `configureEmbedder()` was not called —
+ * production code always calls it from index.ts; tests may rely on this
+ * default.
+ */
+function defaultCacheRoot(): string {
+  return path.join(os.homedir(), '.totalreclaw', 'embedder');
+}
+
+function activeRuntimeConfig(): EmbedderRuntimeConfig {
+  if (runtimeConfig) return runtimeConfig;
+  return { cacheRoot: defaultCacheRoot(), rcTag: '0.0.0-dev' };
+}
+
+/** Lazily initialized state. */
+let pipelineExtractor: any = null;
 let autoTokenizer: any = null;
 let autoModel: any = null;
 let activeModel: ModelConfig | null = null;
@@ -45,8 +100,11 @@ let activeModel: ModelConfig | null = null;
 /**
  * Generate an embedding vector for the given text.
  *
- * On first call, downloads and loads the ONNX model (cached after download).
- * Subsequent calls reuse the loaded model and run in ~100ms.
+ * On first call, downloads the embedder bundle (transformers + onnxruntime
+ * + the q4 ONNX model) from the pinned GitHub Release, verifies the
+ * tarball SHA-256 against the manifest, extracts to
+ * `~/.totalreclaw/embedder/v1/`, then loads the model into memory.
+ * Subsequent calls reuse the loaded model and run in ~100 ms.
  */
 export async function generateEmbedding(
   text: string,
@@ -54,45 +112,78 @@ export async function generateEmbedding(
 ): Promise<number[]> {
   if (!activeModel) {
     activeModel = getModelConfig();
-    console.error(`[TotalReclaw] Downloading embedding model (${activeModel.size}, one-time setup)...`);
-    console.error('[TotalReclaw] This enables semantic search across your encrypted memories.');
+    const cfg = activeRuntimeConfig();
+    console.error(
+      `[TotalReclaw] Embedding model first-call: fetching bundle ${activeModel.size} from GitHub Releases for v${cfg.rcTag} (cached at ${cfg.cacheRoot}).`,
+    );
+
+    const loaded = await loadEmbedder({
+      cacheRoot: cfg.cacheRoot,
+      rcTag: cfg.rcTag,
+    });
+    if (loaded.manifest.dimension !== activeModel.dims) {
+      throw new Error(
+        `embedder bundle dimension ${loaded.manifest.dimension} does not match plugin-expected ${activeModel.dims}. ` +
+          `Refusing to use mismatched embedder — vector space drift would corrupt cosine search.`,
+      );
+    }
+    if (loaded.manifest.model_id !== activeModel.semanticId) {
+      console.error(
+        `[TotalReclaw] WARNING: bundled model_id "${loaded.manifest.model_id}" != plugin-expected "${activeModel.semanticId}". Continuing — distillation forward-compat path.`,
+      );
+    }
+
+    // Resolve the transformers entrypoint via the cache-bound require.
+    // The bundled package was generated by `scripts/build-embedder-bundle.mjs`
+    // and lives at `<cache>/v1/node_modules/@huggingface/transformers`.
+    const transformers = loaded.cacheRequire('@huggingface/transformers');
+    const { AutoTokenizer, AutoModel, pipeline } = transformers as any;
 
     if (activeModel.pooling === 'sentence_embedding') {
-      // Harrier: use AutoModel (pipeline doesn't support sentence_embedding output)
-      autoTokenizer = await AutoTokenizer.from_pretrained(activeModel.id);
-      autoModel = await AutoModel.from_pretrained(activeModel.id, {
+      autoTokenizer = await AutoTokenizer.from_pretrained(activeModel.hfId);
+      autoModel = await AutoModel.from_pretrained(activeModel.hfId, {
         dtype: activeModel.dtype as any,
       });
     } else {
-      // e5-small / Qwen: use pipeline
-      pipelineExtractor = await pipeline('feature-extraction', activeModel.id, {
+      pipelineExtractor = await pipeline('feature-extraction', activeModel.hfId, {
         dtype: activeModel.dtype as any,
       });
     }
-    console.error('[TotalReclaw] Embedding model ready. Future startups will be instant.');
+    console.error('[TotalReclaw] Embedding model ready. Future calls are in-memory.');
   }
 
   const model = activeModel!;
 
   if (model.pooling === 'sentence_embedding') {
-    // Harrier: pre-pooled, pre-normalized output
     const inputs = await autoTokenizer(text, { return_tensors: 'pt', padding: true });
     const output = await autoModel(inputs);
     return Array.from(output.sentence_embedding.data as Float32Array);
   } else {
-    // Pipeline models: use pooling option
     const input = model.pooling === 'mean' && options?.isQuery
       ? `query: ${text}`
       : text;
-    const output = await pipelineExtractor!(input, { pooling: model.pooling as any, normalize: true });
+    const output = await pipelineExtractor(input, { pooling: model.pooling as any, normalize: true });
     return Array.from(output.data as Float32Array);
   }
 }
 
 /**
  * Get the embedding vector dimensionality.
- * Returns 640 (default/Harrier), 384 (small), or 1024 (large) depending on model selection.
+ * Returns 640 for Harrier-OSS-270M-q4.
  */
 export function getEmbeddingDims(): number {
   return getModelConfig().dims;
 }
+
+/**
+ * Get the semantic embedding-model id stamped on each new claim (rc.22+).
+ *
+ * Forward-compat marker: if a future plugin version distills to a smaller
+ * model, claims tagged with the prior id can be re-embedded selectively
+ * instead of forcing a vault-wide rebuild. Defaults to the v1 Harrier id —
+ * plugin code always tags new claims via this constant, never trusts the
+ * model id from a downloaded bundle for write-time tagging.
+ */
+export function getEmbeddingModelId(): string {
+  return getModelConfig().semanticId;
+}