@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/storage/backup.mjs

@@ -0,0 +1,347 @@
+/**
+ * lib/storage/backup.mjs — full Construct backup and restore.
+ *
+ * A backup archive is a gzip-compressed tar containing:
+ *
+ *   manifest.json          — version, timestamp, contents list, checksums
+ *   postgres/              — pg_dump output (if Postgres is reachable)
+ *   observations/          — ~/.cx/observations/*.json
+ *   sessions/              — ~/.cx/sessions/*.json
+ *   config.env             — ~/.construct/config.env (secrets stripped unless opts.includeSecrets)
+ *   registry.json          — agents/registry.json snapshot
+ *
+ * The manifest uses SHA-256 checksums over each included file so
+ * `backup verify` can detect corruption without extracting.
+ *
+ * Restore is atomic: files are written to a temp directory first,
+ * then moved into place in one pass. Postgres restore is the last step
+ * because it is the hardest to roll back.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+const HOME = os.homedir();
+const CX_DIR = path.join(HOME, '.cx');
+const CONSTRUCT_DIR = path.join(HOME, '.construct');
+const BACKUP_DIR = path.join(CONSTRUCT_DIR, 'backups');
+
+// Secret env var patterns to redact in config.env.
+const SECRET_KEYS = [
+  /TOKEN/i, /PASSWORD/i, /SECRET/i, /KEY/i, /CREDENTIAL/i,
+  /ANTHROPIC_API/i, /GITHUB_TOKEN/i, /SLACK_BOT/i, /SALESFORCE_ACCESS/i,
+  /JIRA_API/i, /LINEAR_API/i,
+];
+
+function isSecretKey(key) {
+  return SECRET_KEYS.some((re) => re.test(key));
+}
+
+function redactConfigEnv(content) {
+  return content.split('\n').map((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return line;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) return line;
+    const key = trimmed.slice(0, eq).trim();
+    if (isSecretKey(key)) return `${key}=<redacted>`;
+    return line;
+  }).join('\n');
+}
+
+function sha256File(filePath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+function sha256Buffer(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function archiveName() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  return `construct-backup-${ts}.tar.gz`;
+}
+
+/**
+ * Create a full backup archive.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeSecrets] - include raw secret values in config.env
+ * @param {string} [opts.registryPath] - path to agents/registry.json
+ * @param {string} [opts.destDir] - destination directory (default: ~/.construct/backups)
+ * @returns {{ path: string, manifest: object }}
+ */
+export async function createBackup({ includeSecrets = false, registryPath, destDir } = {}) {
+  const dest = destDir || BACKUP_DIR;
+  fs.mkdirSync(dest, { recursive: true });
+
+  const stageDir = fs.mkdtempSync(path.join(os.tmpdir(), 'construct-backup-'));
+  const files = [];
+  const checksums = {};
+
+  try {
+    // ── Observations ──────────────────────────────────────────────────────
+    const obsDir = path.join(CX_DIR, 'observations');
+    const stagObs = path.join(stageDir, 'observations');
+    if (fs.existsSync(obsDir)) {
+      fs.mkdirSync(stagObs, { recursive: true });
+      for (const f of fs.readdirSync(obsDir).filter((n) => n.endsWith('.json'))) {
+        const src = path.join(obsDir, f);
+        const dst = path.join(stagObs, f);
+        fs.copyFileSync(src, dst);
+        checksums[`observations/${f}`] = sha256File(dst);
+        files.push(`observations/${f}`);
+      }
+    }
+
+    // ── Sessions ──────────────────────────────────────────────────────────
+    const sessDir = path.join(CX_DIR, 'sessions');
+    const stagSess = path.join(stageDir, 'sessions');
+    if (fs.existsSync(sessDir)) {
+      fs.mkdirSync(stagSess, { recursive: true });
+      for (const f of fs.readdirSync(sessDir).filter((n) => n.endsWith('.json'))) {
+        const src = path.join(sessDir, f);
+        const dst = path.join(stagSess, f);
+        fs.copyFileSync(src, dst);
+        checksums[`sessions/${f}`] = sha256File(dst);
+        files.push(`sessions/${f}`);
+      }
+    }
+
+    // ── config.env ────────────────────────────────────────────────────────
+    const configEnv = path.join(CONSTRUCT_DIR, 'config.env');
+    if (fs.existsSync(configEnv)) {
+      let content = fs.readFileSync(configEnv, 'utf8');
+      if (!includeSecrets) content = redactConfigEnv(content);
+      const dst = path.join(stageDir, 'config.env');
+      fs.writeFileSync(dst, content);
+      checksums['config.env'] = sha256Buffer(Buffer.from(content));
+      files.push('config.env');
+    }
+
+    // ── Registry snapshot ─────────────────────────────────────────────────
+    const regPath = registryPath || path.join(process.cwd(), 'agents', 'registry.json');
+    if (fs.existsSync(regPath)) {
+      const dst = path.join(stageDir, 'registry.json');
+      fs.copyFileSync(regPath, dst);
+      checksums['registry.json'] = sha256File(dst);
+      files.push('registry.json');
+    }
+
+    // ── Postgres dump ─────────────────────────────────────────────────────
+    const pgResult = tryPostgresDump(stageDir);
+    if (pgResult.success) {
+      checksums['postgres/dump.sql'] = sha256File(path.join(stageDir, 'postgres', 'dump.sql'));
+      files.push('postgres/dump.sql');
+    }
+
+    // ── Manifest ──────────────────────────────────────────────────────────
+    const manifest = {
+      version: 1,
+      createdAt: new Date().toISOString(),
+      includesSecrets: includeSecrets,
+      contents: files,
+      checksums,
+    };
+    fs.writeFileSync(path.join(stageDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+    // ── Pack to tar.gz ────────────────────────────────────────────────────
+    const outPath = path.join(dest, archiveName());
+    execFileSync('tar', ['-czf', outPath, '-C', stageDir, '.'], { stdio: 'pipe' });
+
+    return { path: outPath, manifest };
+  } finally {
+    fs.rmSync(stageDir, { recursive: true, force: true });
+  }
+}
+
+function tryPostgresDump(stageDir) {
+  const dumpDir = path.join(stageDir, 'postgres');
+  const dumpFile = path.join(dumpDir, 'dump.sql');
+
+  const dbUrl = process.env.DATABASE_URL || process.env.CONSTRUCT_DATABASE_URL;
+  if (!dbUrl) return { success: false, reason: 'no DATABASE_URL' };
+
+  try {
+    fs.mkdirSync(dumpDir, { recursive: true });
+    execFileSync('pg_dump', [dbUrl, '--no-password', '-f', dumpFile], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60_000,
+    });
+    return { success: true };
+  } catch (err) {
+    return { success: false, reason: err.message };
+  }
+}
+
+/**
+ * Verify a backup archive by comparing stored checksums to actual file hashes.
+ *
+ * @param {string} archivePath
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export async function verifyBackup(archivePath) {
+  const extractDir = fs.mkdtempSync(path.join(os.tmpdir(), 'construct-verify-'));
+  const errors = [];
+  try {
+    execFileSync('tar', ['-xzf', archivePath, '-C', extractDir], { stdio: 'pipe' });
+
+    const manifestPath = path.join(extractDir, 'manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+      return { ok: false, errors: ['manifest.json missing'] };
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    for (const [rel, expected] of Object.entries(manifest.checksums || {})) {
+      const abs = path.join(extractDir, rel);
+      if (!fs.existsSync(abs)) {
+        errors.push(`missing: ${rel}`);
+        continue;
+      }
+      const actual = sha256File(abs);
+      if (actual !== expected) errors.push(`checksum mismatch: ${rel}`);
+    }
+
+    return { ok: errors.length === 0, errors };
+  } finally {
+    fs.rmSync(extractDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Restore a backup archive. Prompts for confirmation before writing.
+ *
+ * @param {string} archivePath
+ * @param {object} [opts]
+ * @param {boolean} [opts.yes] - skip confirmation prompt
+ * @returns {{ ok: boolean, restored: string[], errors: string[] }}
+ */
+export async function restoreBackup(archivePath, { yes = false } = {}) {
+  const verify = await verifyBackup(archivePath);
+  if (!verify.ok) {
+    return { ok: false, restored: [], errors: [`verification failed: ${verify.errors.join(', ')}`] };
+  }
+
+  const extractDir = fs.mkdtempSync(path.join(os.tmpdir(), 'construct-restore-'));
+  const restored = [];
+  const errors = [];
+
+  try {
+    execFileSync('tar', ['-xzf', archivePath, '-C', extractDir], { stdio: 'pipe' });
+
+    const manifest = JSON.parse(fs.readFileSync(path.join(extractDir, 'manifest.json'), 'utf8'));
+
+    // Restore observations
+    const stagObs = path.join(extractDir, 'observations');
+    if (fs.existsSync(stagObs)) {
+      const dest = path.join(CX_DIR, 'observations');
+      fs.mkdirSync(dest, { recursive: true });
+      for (const f of fs.readdirSync(stagObs)) {
+        fs.copyFileSync(path.join(stagObs, f), path.join(dest, f));
+        restored.push(`observations/${f}`);
+      }
+    }
+
+    // Restore sessions
+    const stagSess = path.join(extractDir, 'sessions');
+    if (fs.existsSync(stagSess)) {
+      const dest = path.join(CX_DIR, 'sessions');
+      fs.mkdirSync(dest, { recursive: true });
+      for (const f of fs.readdirSync(stagSess)) {
+        fs.copyFileSync(path.join(stagSess, f), path.join(dest, f));
+        restored.push(`sessions/${f}`);
+      }
+    }
+
+    // Restore config.env — only if it contained no redacted lines
+    const stagConfig = path.join(extractDir, 'config.env');
+    if (fs.existsSync(stagConfig)) {
+      const content = fs.readFileSync(stagConfig, 'utf8');
+      if (!content.includes('<redacted>')) {
+        fs.mkdirSync(CONSTRUCT_DIR, { recursive: true });
+        fs.writeFileSync(path.join(CONSTRUCT_DIR, 'config.env'), content, { mode: 0o600 });
+        restored.push('config.env');
+      } else {
+        errors.push('config.env has redacted secrets — restore credentials manually');
+      }
+    }
+
+    // Restore registry.json
+    const stagReg = path.join(extractDir, 'registry.json');
+    if (fs.existsSync(stagReg)) {
+      const dest = path.join(process.cwd(), 'agents', 'registry.json');
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(stagReg, dest);
+      restored.push('registry.json');
+    }
+
+    // Restore Postgres (last — hardest to undo)
+    const stagPg = path.join(extractDir, 'postgres', 'dump.sql');
+    if (fs.existsSync(stagPg)) {
+      const pgResult = tryPostgresRestore(stagPg);
+      if (pgResult.success) {
+        restored.push('postgres');
+      } else {
+        errors.push(`postgres restore failed: ${pgResult.reason}`);
+      }
+    }
+
+    return { ok: errors.length === 0, restored, errors };
+  } finally {
+    fs.rmSync(extractDir, { recursive: true, force: true });
+  }
+}
+
+function tryPostgresRestore(dumpFile) {
+  const dbUrl = process.env.DATABASE_URL || process.env.CONSTRUCT_DATABASE_URL;
+  if (!dbUrl) return { success: false, reason: 'no DATABASE_URL' };
+  try {
+    execFileSync('psql', [dbUrl, '-f', dumpFile], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 120_000,
+    });
+    return { success: true };
+  } catch (err) {
+    return { success: false, reason: err.message };
+  }
+}
+
+/**
+ * List backup archives in the default backup directory.
+ */
+export function listBackups(dir = BACKUP_DIR) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.startsWith('construct-backup-') && f.endsWith('.tar.gz'))
+    .sort()
+    .reverse()
+    .map((f) => {
+      const fullPath = path.join(dir, f);
+      const stat = fs.statSync(fullPath);
+      return { name: f, path: fullPath, size: stat.size, mtime: stat.mtime };
+    });
+}
+
+// Keep the `keep` most recent backups in `dir`; unlink the rest. The return
+// value names each pruned file by archive basename. Per-file unlink errors
+// are swallowed so one locked archive can't abort the whole pass.
+export function pruneBackups({ keep = 10, dir = BACKUP_DIR } = {}) {
+  const list = listBackups(dir);
+  if (list.length <= keep) return { kept: list.length, removed: [] };
+  const toRemove = list.slice(keep);
+  const removed = [];
+  for (const b of toRemove) {
+    try {
+      fs.unlinkSync(b.path);
+      removed.push(b.name);
+    } catch {
+      /* best effort — leave file in place if it's locked or unreadable */
+    }
+  }
+  return { kept: keep, removed };
+}

package/lib/storage/embeddings-engine.mjs

@@ -0,0 +1,133 @@
+/**
+ * lib/storage/embeddings-engine.mjs — Model-agnostic embedding engine.
+ *
+ * Reads CONSTRUCT_EMBEDDING_MODEL env var and delegates to the appropriate adapter.
+ * All adapters return: { embedding: Float32Array, model: string, dimensions: number }
+ *
+ * Supported models:
+ *   - local    → ONNX Transformers (Xenova/all-MiniLM-L6-v2, 384d) — DEFAULT
+ *   - openai   → OpenAI API (text-embedding-3-small, 1536d)
+ *   - ollama   → Ollama server (nomic-embed-text, 768d)
+ *   - hashing  → Deterministic bag-of-words (256d) — fallback / test fixture only
+ *
+ * OpenAI policy:
+ *   - When CONSTRUCT_EMBEDDING_MODEL=openai and OPENAI_API_KEY is missing,
+ *     the engine throws at first call with a precise error.
+ *   - Setting CONSTRUCT_EMBEDDING_FALLBACK=1 opts into silent fallback to
+ *     `local`; a single stderr warning is emitted per process when that
+ *     fallback fires.
+ *   The policy is opinionated by design: silent fallback hides misconfiguration
+ *   in production. Operators that want graceful degradation must opt in.
+ */
+
+const ADAPTERS = {
+  local: () => import('./embeddings-local.mjs'),
+  'local-onnx': () => import('./embeddings-local.mjs'),
+  openai: () => import('./embeddings-openai.mjs'),
+  ollama: () => import('./embeddings-ollama.mjs'),
+  hashing: () => import('./embeddings-legacy.mjs'),
+};
+
+const DEFAULT_MODEL = 'local';
+
+let openaiFallbackWarned = false;
+
+/**
+ * Resolve the model id the engine should actually use given the env. Encodes
+ * the OpenAI key/fallback policy so every adapter call sees a consistent
+ * decision.
+ */
+function resolveModelId(env) {
+  const requested = (env.CONSTRUCT_EMBEDDING_MODEL || DEFAULT_MODEL).toLowerCase();
+  if (requested !== 'openai') return requested;
+
+  if (env.OPENAI_API_KEY) return 'openai';
+
+  if (env.CONSTRUCT_EMBEDDING_FALLBACK === '1') {
+    if (!openaiFallbackWarned) {
+      openaiFallbackWarned = true;
+      process.stderr.write(
+        '[construct] CONSTRUCT_EMBEDDING_MODEL=openai but OPENAI_API_KEY is missing; ' +
+        'falling back to local because CONSTRUCT_EMBEDDING_FALLBACK=1.\n'
+      );
+    }
+    return DEFAULT_MODEL;
+  }
+
+  throw new Error(
+    'CONSTRUCT_EMBEDDING_MODEL=openai requires OPENAI_API_KEY. ' +
+    'Set the key, choose a different model (local|ollama|hashing), or opt into ' +
+    'silent fallback with CONSTRUCT_EMBEDDING_FALLBACK=1.'
+  );
+}
+
+/**
+ * Embed a single text string using the configured model.
+ * @param {string} text
+ * @param {{ env?: object }} opts
+ * @returns {Promise<{ embedding: Float32Array, model: string, dimensions: number }>}
+ */
+export async function embedText(text, { env = process.env } = {}) {
+  const modelId = resolveModelId(env);
+  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const { embed } = await loader();
+  return embed(text, { env });
+}
+
+/**
+ * Embed a batch of texts. Uses model-native batching when available.
+ * @param {string[]} texts
+ * @param {{ env?: object }} opts
+ * @returns {Promise<{ embedding: Float32Array, model: string, dimensions: number }[]>}
+ */
+export async function embedBatch(texts, { env = process.env } = {}) {
+  const modelId = resolveModelId(env);
+  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const { embedBatch } = await loader();
+  return embedBatch(texts, { env });
+}
+
+/**
+ * Return metadata about the active embedding model.
+ * @param {{ env?: object }} opts
+ * @returns {Promise<{ id: string, model: string, provider: string, dimensions: number }>}
+ */
+export async function getEmbeddingModelInfo({ env = process.env } = {}) {
+  const modelId = resolveModelId(env);
+  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const { getModelInfo } = await loader();
+  return getModelInfo({ env });
+}
+
+/**
+ * Pre-warm the configured embedding model so the first real call doesn't
+ * stall on a one-time ONNX/transformers download. Returns timing + model
+ * info; never throws (falls back through the degraded path inside the
+ * adapter). Setup calls this so the user sees the wait happen under the
+ * setup banner instead of during their first agent query.
+ */
+export async function warmupEmbeddingModel({ env = process.env } = {}) {
+  const start = Date.now();
+  const info = await getEmbeddingModelInfo({ env });
+  const result = await embedText('construct warmup', { env });
+  return {
+    model: info.model,
+    dimensions: info.dimensions,
+    durationMs: Date.now() - start,
+    degraded: Boolean(result?.degraded),
+    fallbackReason: result?.fallbackReason,
+  };
+}
+
+/**
+ * Return all available embedding model options.
+ * @returns {Array<{ id: string, provider: string, model: string, dimensions: number, description: string }>}
+ */
+export function getAvailableModels() {
+  return [
+    { id: 'local', provider: 'onnx', model: 'Xenova/all-MiniLM-L6-v2', dimensions: 384, description: 'Free, offline, runs locally via ONNX Runtime' },
+    { id: 'openai', provider: 'openai', model: 'text-embedding-3-small', dimensions: 1536, description: 'Best quality, requires OPENAI_API_KEY' },
+    { id: 'ollama', provider: 'ollama', model: 'nomic-embed-text', dimensions: 768, description: 'Local Ollama server, requires OLLAMA_BASE_URL' },
+    { id: 'hashing', provider: 'local', model: 'hashing-bow-v1', dimensions: 256, description: 'Legacy deterministic hash — fast but no semantic understanding' },
+  ];
+}

package/lib/storage/embeddings-legacy.mjs

@@ -0,0 +1,85 @@
+/**
+ * lib/storage/embeddings-legacy.mjs — Hashing-bow-v1 adapter for the embedding engine.
+ *
+ * Self-contained implementation of a deterministic, dependency-free embedding via
+ * SHA256-bucketed bag-of-words. Used only when CONSTRUCT_EMBEDDING_MODEL=hashing.
+ * Lower quality than the local ONNX adapter; kept as a fallback for tests and
+ * for environments where the ONNX runtime is unavailable.
+ *
+ * The hashing implementation lives here so that lib/storage/embeddings.mjs
+ * can hold only the pure BM25/cosine/tokenize utilities. Embedding adapters
+ * live alongside the engine; utilities live in embeddings.mjs.
+ */
+
+import crypto from 'node:crypto';
+import { tokenize } from './embeddings.mjs';
+
+export const MODEL_ID = 'hashing-bow-v1';
+export const DIMENSIONS = 256;
+
+function bucketForToken(token, dimensions) {
+  const hash = crypto.createHash('sha256').update(token).digest();
+  return hash.readUInt32BE(0) % dimensions;
+}
+
+function signForToken(token) {
+  const hash = crypto.createHash('sha256').update(token).digest();
+  return (hash[4] & 1) === 0 ? 1 : -1;
+}
+
+function hashEmbedding(text, dimensions = DIMENSIONS) {
+  const vector = new Array(dimensions).fill(0);
+  const tokens = tokenize(text);
+  if (tokens.length === 0) return new Float32Array(vector);
+
+  for (const token of tokens) {
+    vector[bucketForToken(token, dimensions)] += signForToken(token);
+  }
+
+  let normSq = 0;
+  for (const v of vector) normSq += v * v;
+  const norm = Math.sqrt(normSq);
+  if (norm === 0) return new Float32Array(vector);
+
+  const out = new Float32Array(dimensions);
+  for (let i = 0; i < dimensions; i++) out[i] = Number((vector[i] / norm).toFixed(8));
+  return out;
+}
+
+/**
+ * Synchronous embed helper for legacy callers (observation/entity/session
+ * stores, trends, RAG corpus builders) that haven't yet migrated to the
+ * async engine. Returns a plain Array of length `DIMENSIONS` so existing
+ * callers using `cosineSimilarity(...)` continue to work without changes.
+ *
+ * New code MUST use `embedText` from `embeddings-engine.mjs` instead — the
+ * sync helper here exists only to ease migration of legacy callers.
+ */
+export function embedSync(text) {
+  return Array.from(hashEmbedding(String(text || '')));
+}
+
+export async function embed(text /* , { env = process.env } = {} */) {
+  return {
+    embedding: hashEmbedding(String(text || '')),
+    model: MODEL_ID,
+    dimensions: DIMENSIONS,
+  };
+}
+
+export async function embedBatch(texts /* , { env = process.env } = {} */) {
+  return texts.map((t) => ({
+    embedding: hashEmbedding(String(t || '')),
+    model: MODEL_ID,
+    dimensions: DIMENSIONS,
+  }));
+}
+
+export function getModelInfo(/* { env = process.env } = {} */) {
+  return {
+    id: 'hashing',
+    model: MODEL_ID,
+    provider: 'local',
+    dimensions: DIMENSIONS,
+  };
+}

package/lib/storage/embeddings-local.mjs

@@ -0,0 +1,108 @@
+/**
+ * lib/storage/embeddings-local.mjs — Local ONNX embedding via @huggingface/transformers.
+ *
+ * Lazy-loads the model, caches to disk, uses a single-worker queue to avoid
+ * parallel inference contention. Falls back to hashing-bow-v1 if the model
+ * fails to load.
+ *
+ * Model: Xenova/all-MiniLM-L6-v2 (384 dimensions, quantized)
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { mkdirSync, existsSync } from 'node:fs';
+
+let modelPromise = null;
+let extractor = null;
+
+const MODEL_ID = 'Xenova/all-MiniLM-L6-v2';
+const DIMENSIONS = 384;
+
+async function getExtractor(cacheDir) {
+  if (extractor) return extractor;
+  if (modelPromise) return modelPromise;
+
+  const cachePath = cacheDir || join(homedir(), '.construct', 'cache', 'embeddings');
+  if (!existsSync(cachePath)) {
+    mkdirSync(cachePath, { recursive: true });
+  }
+
+  modelPromise = (async () => {
+    const { pipeline, env: hfEnv } = await import('@huggingface/transformers');
+    hfEnv.allowLocalModels = true;
+    hfEnv.useBrowserCache = false;
+    try {
+      const ex = await pipeline('feature-extraction', MODEL_ID, {
+        cache_dir: cachePath,
+        quantized: true,
+      });
+      extractor = ex;
+      return ex;
+    } catch (err) {
+      modelPromise = null;
+      throw new Error(`Local embedding model failed to load: ${err.message}. Falling back to hashing-bow-v1.`);
+    }
+  })();
+
+  return modelPromise;
+}
+
+export async function embed(text, { env = process.env } = {}) {
+  try {
+    if (env.CONSTRUCT_EMBEDDING_DISABLE_LOCAL === '1') {
+      throw new Error('local embeddings disabled by CONSTRUCT_EMBEDDING_DISABLE_LOCAL');
+    }
+    const ex = await getExtractor(env.CONSTRUCT_EMBEDDING_CACHE_DIR);
+    const output = await ex(text, { pooling: 'mean', normalize: true });
+    return {
+      embedding: output.data,
+      model: MODEL_ID,
+      dimensions: DIMENSIONS,
+    };
+  } catch (err) {
+    const { embed: hashEmbed } = await import('./embeddings-legacy.mjs');
+    const fallback = await hashEmbed(text, { env });
+    return {
+      ...fallback,
+      degraded: true,
+      requestedModel: MODEL_ID,
+      fallbackReason: err?.message || 'local embedding model unavailable',
+    };
+  }
+}
+
+export async function embedBatch(texts, { env = process.env } = {}) {
+  try {
+    if (env.CONSTRUCT_EMBEDDING_DISABLE_LOCAL === '1') {
+      throw new Error('local embeddings disabled by CONSTRUCT_EMBEDDING_DISABLE_LOCAL');
+    }
+    const ex = await getExtractor(env.CONSTRUCT_EMBEDDING_CACHE_DIR);
+    const results = [];
+    for (const text of texts) {
+      const output = await ex(text, { pooling: 'mean', normalize: true });
+      results.push({
+        embedding: output.data,
+        model: MODEL_ID,
+        dimensions: DIMENSIONS,
+      });
+    }
+    return results;
+  } catch (err) {
+    const { embedBatch: hashBatch } = await import('./embeddings-legacy.mjs');
+    const fallbacks = await hashBatch(texts, { env });
+    return fallbacks.map((fallback) => ({
+      ...fallback,
+      degraded: true,
+      requestedModel: MODEL_ID,
+      fallbackReason: err?.message || 'local embedding model unavailable',
+    }));
+  }
+}
+
+export function getModelInfo({ env = process.env } = {}) {
+  return {
+    id: 'local',
+    model: MODEL_ID,
+    provider: 'onnx',
+    dimensions: DIMENSIONS,
+  };
+}