@3sln/trove 0.0.2

package/packages/core/src/plugins/runtime.js

@@ -0,0 +1,101 @@
+// IndexerRuntime — executes a server-side indexer sub-package against a node and
+// returns a *clamped* contribution. It's the seam where untrusted plugin code runs,
+// so it's pluggable: a deployment picks a runtime that matches its isolation needs.
+//
+//   InProcessIndexerRuntime  — imports the entry module and calls it directly. NO
+//                              isolation; the indexer runs with the server's full
+//                              authority. Only safe for TRUSTED code (first-party
+//                              indexers, an admin-vetted package). It's the reference
+//                              runtime and what tests use.
+//
+// Real isolation (a Node isolated-vm worker, a Bun worker_thread, a Cloudflare
+// dynamic Worker loader) is a drop-in subclass that implements the same run() — see
+// docs/design/server-plugins-and-indexers.md §5. Whatever the runtime, its output is
+// funnelled through clampContribution() so a misbehaving indexer can't flood the
+// index or the metadata store.
+
+import { TroveError } from '../errors.js';
+import { withTimeout } from '../retry.js';
+// The contribution contract (shape + caps) lives with contributions, not with one of
+// the runtimes that produce them. Clamping here bounds what crosses the isolate
+// boundary into host memory; the indexing coordinator clamps again as the authority
+// for what is actually stored.
+import { clampContribution, DEFAULT_CAPS } from '../indexers/contribution.js';
+
+
+export class IndexerRuntime {
+  /**
+   * Run an indexer sub-package against a node.
+   * @param {{ id: string, entry: string, files: Record<string, Uint8Array>, cacheKey?: string }} spec
+   * @param {object} node
+   * @param {object} ctx  index context (readBytes/readText/presignRead/maxBytes/config/secrets)
+   * @returns {Promise<object>} a clamped contribution
+   */
+  async run(spec, node, ctx) { throw TroveError.unsupported('IndexerRuntime.run'); }
+  async close() {}
+}
+
+/**
+ * Trusted, in-process runtime. Imports the entry module via a data: URL and invokes
+ * its default (or named `index`) export as `index(node, ctx)`. The engine caches a
+ * data: URL module, and we cache the import promise by cacheKey so re-runs are cheap.
+ *
+ * Limitations (accepted for the trusted reference runtime): the entry file must be
+ * self-contained — relative `import` between sub-package files won't resolve through a
+ * data: URL. Bundlers already collapse an indexer to one entry; multi-module loading
+ * belongs to the isolate runtimes.
+ */
+export class InProcessIndexerRuntime extends IndexerRuntime {
+  constructor({ timeoutMs = 10_000, caps = DEFAULT_CAPS } = {}) {
+    super();
+    this.timeoutMs = timeoutMs;
+    this.caps = { ...DEFAULT_CAPS, ...caps };
+    this._mods = new Map(); // cacheKey -> Promise<indexFn>
+  }
+
+  #load(spec) {
+    const key = spec.cacheKey || spec.id;
+    let p = this._mods.get(key);
+    if (!p) {
+      const code = spec.files?.[spec.entry];
+      if (!code) return Promise.reject(TroveError.invalid(`Indexer "${spec.id}" is missing its entry "${spec.entry}"`));
+      // base64 data URL — percent-encoded JS confuses some runtimes' data: loader
+      // (they fall back to a text module), whereas base64 imports reliably.
+      const url = 'data:text/javascript;base64,' + bytesToBase64(code);
+      p = import(/* @vite-ignore */ url).then((mod) => {
+        const fn = mod.default || mod.index;
+        if (typeof fn !== 'function') throw TroveError.invalid(`Indexer "${spec.id}" has no default/index export`);
+        return fn;
+      });
+      this._mods.set(key, p);
+    }
+    return p;
+  }
+
+  async run(spec, node, ctx) {
+    const fn = await this.#load(spec);
+    const result = await withTimeout(
+      Promise.resolve().then(() => fn(node, ctx)),
+      this.timeoutMs,
+      `Indexer "${spec.id}" timed out after ${this.timeoutMs}ms`,
+    );
+    return clampContribution(result, this.caps);
+  }
+}
+
+function bytesToBase64(bytes) {
+  let bin = '';
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}
+
+
+/**
+ * Bound an indexer's output to the caps. Never throws — a runaway or malformed
+ * contribution is trimmed to something safe rather than rejected, so one bad chunk
+ * doesn't sink the whole indexing pass.
+ */
+

package/packages/core/src/plugins/sql.js

@@ -0,0 +1,52 @@
+// Which SQL a plugin may run against its own database.
+//
+// Its own module rather than part of sqlite.js because BOTH sides of the mirror need it
+// and only one of them can load a driver: the server checks before touching the on-disk
+// store, and the browser checks before touching the wasm one. Importing sqlite.js from
+// the web bundle would drag `bun:sqlite` in behind it.
+
+import { TroveError } from '../errors.js';
+
+// Plugins run SQL against their OWN isolated database, but on a shared-filesystem
+// provider the sibling scope files are guessable, so `ATTACH DATABASE` would be an
+// isolation escape (and `DETACH` its pair). Strip comments + string/identifier
+// literals first so the keyword can't hide inside a value, then reject.
+
+// ATTACH/DETACH would reach a sibling scope's file. VACUUM INTO is worse and less
+// obvious: it writes a complete SQLite database to any path the server process can
+// create, whose pages contain rows the caller chose — attacker-chosen bytes at an
+// attacker-chosen path (a cron file, a webroot, authorized_keys). PRAGMA is refused
+// because several of them (database_list, temp_store_directory) either disclose host
+// paths or move where files land.
+const DANGEROUS_SQL = /\b(ATTACH|DETACH|VACUUM|PRAGMA)\b/i;
+
+/** Blank out --/**-comments and '..'/".."/`..`/[..] literals, preserving length-ish. */
+export function stripSqlLiterals(sql) {
+  let out = '';
+  let i = 0;
+  while (i < sql.length) {
+    const c = sql[i];
+    if (c === '-' && sql[i + 1] === '-') { const nl = sql.indexOf('\n', i); i = nl < 0 ? sql.length : nl; continue; }
+    if (c === '/' && sql[i + 1] === '*') { const e = sql.indexOf('*/', i + 2); i = e < 0 ? sql.length : e + 2; out += ' '; continue; }
+    if (c === "'" || c === '"' || c === '`') {
+      const q = c; i++;
+      while (i < sql.length) {
+        if (sql[i] === q) { if (sql[i + 1] === q) { i += 2; continue; } i++; break; }
+        i++;
+      }
+      out += ' '; continue;
+    }
+    if (c === '[') { const e = sql.indexOf(']', i); i = e < 0 ? sql.length : e + 1; out += ' '; continue; }
+    out += c; i++;
+  }
+  return out;
+}
+
+/** Throw if plugin-supplied SQL tries to escape its isolated database. */
+export function assertSafePluginSql(sql) {
+  if (typeof sql !== 'string' || !sql) throw TroveError.invalid('SQL statement is required');
+  if (DANGEROUS_SQL.test(stripSqlLiterals(sql))) {
+    throw TroveError.invalid('ATTACH, DETACH, VACUUM and PRAGMA are not permitted in plugin storage');
+  }
+}
+

package/packages/core/src/retry.js

@@ -0,0 +1,74 @@
+// Retry with exponential backoff + full jitter. Only retries errors classified
+// retryable (see errors.js), respects an AbortSignal between attempts, and
+// surfaces the last error untouched when it gives up — so the caller still sees
+// a clean TroveError, not a generic "retries exhausted".
+
+import { isRetryable, wrapError, TroveError } from './errors.js';
+
+const DEFAULTS = {
+  retries: 4, // attempts after the first = 5 total tries
+  minDelayMs: 250,
+  maxDelayMs: 8000,
+  factor: 2,
+  jitter: true,
+};
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(TroveError.aborted());
+    // `{ once: true }` removes the listener when it FIRES — not when the timer wins,
+    // which is the normal case. One long-lived signal driving a few retried operations
+    // therefore accumulated a listener per attempt and released none of them.
+    const done = (fn) => (arg) => {
+      clearTimeout(t);
+      signal?.removeEventListener('abort', onAbort);
+      fn(arg);
+    };
+    const t = setTimeout(() => done(resolve)(), ms);
+    const onAbort = () => done(reject)(TroveError.aborted());
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * @template T
+ * @param {(attempt: number) => Promise<T>} fn
+ * @param {object} [opts]
+ * @param {number} [opts.retries]
+ * @param {AbortSignal} [opts.signal]
+ * @param {(info: {attempt: number, delayMs: number, error: TroveError}) => void} [opts.onRetry]
+ * @param {(err: unknown) => boolean} [opts.shouldRetry] override classification
+ * @returns {Promise<T>}
+ */
+export async function withRetry(fn, opts = {}) {
+  const cfg = { ...DEFAULTS, ...opts };
+  const shouldRetry = cfg.shouldRetry ?? isRetryable;
+  let attempt = 0;
+
+  for (;;) {
+    if (cfg.signal?.aborted) throw TroveError.aborted();
+    try {
+      return await fn(attempt);
+    } catch (raw) {
+      const err = wrapError(raw);
+      const canRetry = attempt < cfg.retries && shouldRetry(err) && err.code !== 'aborted';
+      if (!canRetry) throw err;
+
+      const base = Math.min(cfg.maxDelayMs, cfg.minDelayMs * cfg.factor ** attempt);
+      const delayMs = cfg.jitter ? Math.random() * base : base;
+      cfg.onRetry?.({ attempt: attempt + 1, delayMs, error: err });
+      await sleep(delayMs, cfg.signal);
+      attempt++;
+    }
+  }
+}
+
+/** Reject after `ms`, unless `promise` settles first. Cleans up its timer. */
+export function withTimeout(promise, ms, message = 'Operation timed out') {
+  if (!ms || ms <= 0) return promise;
+  let t;
+  const timeout = new Promise((_, reject) => {
+    t = setTimeout(() => reject(TroveError.timeout(message)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(t));
+}

package/packages/core/src/scan.js

@@ -0,0 +1,302 @@
+// CollectionScanner — reconcile a collection against the bytes actually in its store.
+//
+// Trove is not the only thing that can touch a bucket. Another tool writes to it, a
+// teammate drags a folder in with the S3 console, a sync client replaces an object in
+// place, a lifecycle rule expires something. Every one of those leaves the drive
+// describing a world that no longer exists — and because there are no folders here,
+// "it isn't in the list" is indistinguishable from "it was never there".
+//
+// So this walks both sides and names the four things that can be true of an object:
+//
+//   known & unchanged   nothing to do (the overwhelming majority — keep it cheap)
+//   in the store only   ADOPT: create an item for it, named from its key
+//   changed in place    REFRESH: same key, different etag/size → re-read and re-index
+//   in metadata only    ORPHANED: the bytes are gone. Reported, never auto-deleted.
+//
+// The asymmetry in that last pair is deliberate. Adopting a file is additive and
+// reversible; deleting an item because a LIST call didn't mention it is neither, and
+// list calls are exactly the operation that goes wrong in interesting ways — a
+// misconfigured prefix, an eventually-consistent replica, a credential scoped to the
+// wrong path. Trove will happily invent an item from bytes it can see. It will not
+// destroy a record because it briefly couldn't see any.
+
+import { TroveError } from './errors.js';
+import { extname } from './util.js';
+import { PACKAGE_PREFIX } from './plugins/packageStore.js';
+
+/** Objects Trove wrote itself. Anything else in the store arrived some other way. */
+const TROVE_KEY = /^obj_[0-9a-f]+$/i;
+/**
+ * Keys that are Trove's own bookkeeping, not user data.
+ *
+ * These MUST match what the writers actually use, and one of them didn't: the package
+ * store writes under `_plugins/` (StoragePackageStore's default prefix) while this list
+ * said `plugins/`. Since that store wraps the primary backend — which is also the
+ * `default` collection's — every account's uploaded plugin zip sat in the default
+ * collection's key space as an unreserved object, and a scan adopted it: the package
+ * bytes became a file anyone with read on `default` could download, its name leaked the
+ * installing account's id (usually an email), its contents went into the shared search
+ * index, and because the adopted item's storageKey IS the real blob key, deleting it
+ * destroyed the owner's package.
+ *
+ * `plugins/` and `packages/` are kept as well — they cost nothing and a store
+ * constructed with a different prefix should still be skipped.
+ */
+const RESERVED_PREFIXES = ['sidecars/', PACKAGE_PREFIX, 'packages/', 'plugins/'];
+
+export class CollectionScanner {
+  /**
+   * @param {object} deps
+   * @param {import('./vfs.js').Vfs} deps.vfs
+   * @param {import('./issues.js').IssueRegistry} [deps.issues]
+   */
+  constructor({ vfs, issues = null }) {
+    this.vfs = vfs;
+    this.issues = issues;
+  }
+
+  /**
+   * Reconcile one collection.
+   *
+   * @param {string} collectionId
+   * @param {object} [opts]
+   * @param {boolean} [opts.adopt]        create items for unknown objects (default true)
+   * @param {boolean} [opts.refresh]      re-index items whose bytes changed (default true)
+   * @param {number}  [opts.pageSize]
+   * @param {(p: object) => void} [opts.onProgress]
+   * @param {() => boolean} [opts.shouldStop]
+   * @param {string|null} [opts.cursor] resume a scan that stopped early (see below)
+   * @returns {Promise<{scanned, adopted, refreshed, orphaned, skipped, failed, stopped, nextCursor}>}
+   *
+   * A scan that stops early returns the `nextCursor` it had reached, so the next call
+   * can pick the bucket up where this one left off. That is what makes this usable on a
+   * runtime with a hard execution budget — Cloudflare Workers, where a request has a CPU
+   * ceiling measured in seconds and a bucket has no ceiling at all. Without it the only
+   * options were "finishes" and "starts from the beginning again forever".
+   */
+  async scan(collectionId = 'default', opts = {}) {
+    const { adopt = true, refresh = true, pageSize = 500, onProgress, shouldStop } = opts;
+    const storage = await this.vfs.storageFor(collectionId);
+    if (!storage.capabilities?.list) {
+      throw TroveError.unsupported('This collection\'s storage backend cannot list its contents');
+    }
+
+    // One pass over metadata first, so the comparison is a map lookup per object rather
+    // than a query per object — a bucket scan that did a round trip per key would take
+    // hours on a real drive.
+    const byKey = new Map();
+    for (const node of await this.#allItems(collectionId)) {
+      if (node.storageKey) byKey.set(node.storageKey, node);
+    }
+    // The trash holds rows too, and their bytes are deliberately still in the store —
+    // that is what makes a delete undoable. `listItems` is live-only by design, so
+    // without this a trashed file's object looks exactly like one that arrived from
+    // outside: the scan adopts it AGAIN, resurrecting the deleted file under a new id
+    // that shares the original's storage key. Emptying the trash then deletes the live
+    // copy's bytes, leaving an item that lists, opens, and 404s forever.
+    const trashedKeys = await this.vfs.metadata.trashedStorageKeys?.(collectionId) ?? new Set();
+
+    const result = {
+      scanned: 0, adopted: 0, refreshed: 0, orphaned: 0, skipped: 0, failed: 0,
+      stopped: false, unaddressable: 0, nextCursor: null, resumed: !!opts.cursor,
+    };
+    const seen = new Set();
+    let cursor = opts.cursor || null;
+
+    outer: for (;;) {
+      const page = await storage.list({ cursor, limit: pageSize });
+      result.unaddressable += page.unaddressable || 0;
+      for (const object of page.objects) {
+        // Stop at a PAGE boundary when we can, so the cursor we hand back is one the
+        // store will honour. Mid-page there is no cursor to express "and 37 objects in",
+        // so those are re-examined next time — which is cheap and idempotent.
+        if (shouldStop?.()) { result.stopped = true; result.nextCursor = cursor; break outer; }
+        result.scanned++;
+        if (this.#reserved(object.key)) { result.skipped++; continue; }
+        seen.add(object.key);
+        // Bytes belonging to something in the trash are accounted for. Not adopted (it
+        // is already ours), and not orphaned (`seen` covers that below).
+        if (trashedKeys.has(object.key)) { result.skipped++; continue; }
+        const node = byKey.get(object.key);
+        try {
+          if (!node) {
+            // #adopt declines Trove's own orphaned blobs, so count what it actually did
+            // rather than assuming — otherwise a drive full of leftover `obj_` keys
+            // would report a large, entirely fictional adoption.
+            const created = adopt ? await this.#adopt(collectionId, object) : null;
+            if (created) result.adopted++;
+            else result.skipped++;
+          } else if (refresh && this.#changed(node, object)) {
+            await this.#refresh(node, object);
+            result.refreshed++;
+          }
+        } catch (err) {
+          result.failed++;
+          console.error(`scan failed on ${object.key}:`, err.message);
+        }
+      }
+      onProgress?.({ ...result });
+      cursor = page.nextCursor;
+      if (!cursor) break;
+      // Between pages is the cheapest place to give up, and the only place a resume is
+      // exact.
+      if (shouldStop?.()) { result.stopped = true; result.nextCursor = cursor; break; }
+    }
+
+    // Orphans are only meaningful after a COMPLETE pass — and "complete" now means this
+    // call reached the end of the bucket having STARTED at the beginning. A scan that was
+    // cut short, or one resuming from a cursor, has not seen the whole store, and calling
+    // the items it didn't reach orphaned would be a false alarm about data loss.
+    if (!result.stopped && !result.resumed) {
+      for (const [key, node] of byKey) {
+        if (!seen.has(key) && !this.#reserved(key)) result.orphaned++;
+      }
+    }
+
+    await this.#report(collectionId, result);
+    return result;
+  }
+
+  /** Every item in the collection, paged so a large drive doesn't load at once. */
+  async #allItems(collectionId) {
+    const items = [];
+    let cursor = null;
+    for (;;) {
+      const page = await this.vfs.metadata.listItems(collectionId, { limit: 500, cursor });
+      items.push(...page.items);
+      if (!page.nextCursor) return items;
+      cursor = page.nextCursor;
+    }
+  }
+
+  #reserved(key) {
+    return RESERVED_PREFIXES.some((p) => key.startsWith(p));
+  }
+
+  /**
+   * Did the bytes behind an item change without us? ETag first (it is what object
+   * stores actually promise), size as the fallback for backends that don't give one.
+   * An item we have no etag for is left alone rather than re-indexed on every scan.
+   */
+  #changed(node, object) {
+    if (object.etag && node.etag) return normalizeEtag(object.etag) !== normalizeEtag(node.etag);
+    if (typeof object.size === 'number' && typeof node.size === 'number') return object.size !== node.size;
+    return false;
+  }
+
+  /**
+   * Create an item for an object that arrived without us.
+   *
+   * The key becomes the name, because in a bucket the key IS what a human called the
+   * thing — `holiday/2019/beach.jpg` is a name someone chose, and flattening it to
+   * `beach.jpg` would collide with every other year's. Trove's own `obj_<hex>` keys are
+   * excluded: one of those with no metadata row is a leftover from a failed write, not
+   * a file someone put there, and adopting it would surface `obj_9fc0…` as a document.
+   */
+  async #adopt(collectionId, object) {
+    if (TROVE_KEY.test(object.key)) return null; // orphaned blob from an interrupted upload
+    const name = await this.#uniqueName(collectionId, object.key);
+    const node = await this.vfs.metadata.create({
+      collectionId,
+      name,
+      storageKey: object.key,
+      size: object.size ?? 0,
+      etag: object.etag ?? null,
+      contentType: this.vfs.guessContentType(name),
+      meta: { adopted: true, adoptedAt: Date.now() },
+    });
+    // Adopted files are indexed like any other, so they are findable immediately —
+    // an item you can't search for is barely an item in a drive with no folders.
+    await this.vfs.indexing.indexNode(node).catch(() => {});
+    return node;
+  }
+
+  /** Re-read an item whose bytes were replaced in place. */
+  async #refresh(node, object) {
+    const updated = await this.vfs.metadata.update(node.id, {
+      size: object.size ?? node.size,
+      etag: object.etag ?? null,
+    });
+    await this.vfs.indexing.indexNode(updated).catch(() => {});
+    return updated;
+  }
+
+  async #uniqueName(collectionId, base) {
+    if (!(await this.vfs.metadata.getByName(collectionId, base))) return base;
+    const ext = extname(base);
+    const stem = ext ? base.slice(0, -ext.length) : base;
+    for (let i = 1; i < 1000; i++) {
+      const candidate = `${stem} (${i})${ext}`;
+      if (!(await this.vfs.metadata.getByName(collectionId, candidate))) return candidate;
+    }
+    throw TroveError.invalid(`Cannot find a free name for "${base}"`);
+  }
+
+  /**
+   * Turn the outcome into something a human sees.
+   *
+   * Orphans and unreachable files are raised as a standing issue rather than logged,
+   * because they are exactly the kind of fact that matters days later: "17 items point
+   * at bytes that are gone" is a data-loss report, and it should still be on screen
+   * tomorrow if nobody has dealt with it. A clean scan clears it.
+   */
+  async #report(collectionId, result) {
+    if (!this.issues || result.stopped) return;
+    try {
+      if (result.orphaned) {
+        await this.issues.raise({
+          kind: 'orphaned',
+          subject: collectionId,
+          collectionId,
+          severity: 'warning',
+          title: result.orphaned === 1
+            ? `1 item in “${collectionId}” points at a file that is no longer in the store`
+            : `${result.orphaned} items in “${collectionId}” point at files that are no longer in the store`,
+          detail: 'Their bytes were removed outside Trove. Nothing was deleted automatically — '
+            + 'the records are kept so you can decide, because a listing that briefly misses objects '
+            + 'must never be able to destroy data.',
+          retry: { op: 'scan-collection', collectionId },
+        });
+      } else {
+        await this.issues.clear('orphaned', collectionId);
+      }
+
+      if (result.unaddressable) {
+        await this.issues.raise({
+          kind: 'unaddressable',
+          subject: collectionId,
+          collectionId,
+          severity: 'warning',
+          title: result.unaddressable === 1
+            ? '1 file in the data directory is not where Trove can read it'
+            : `${result.unaddressable} files in the data directory are not where Trove can read them`,
+          detail: 'Files copied directly into the storage root have to sit at the path their name maps to. '
+            + 'Upload them through Trove instead, or move them into place and scan again.',
+          retry: { op: 'scan-collection', collectionId },
+        });
+      } else {
+        await this.issues.clear('unaddressable', collectionId);
+      }
+
+      if (result.failed) {
+        await this.issues.raise({
+          kind: 'scan',
+          subject: collectionId,
+          collectionId,
+          title: `${result.failed} object${result.failed === 1 ? '' : 's'} in “${collectionId}” could not be reconciled`,
+          detail: `${result.scanned} scanned, ${result.adopted} adopted, ${result.refreshed} refreshed, ${result.failed} failed.`,
+          retry: { op: 'scan-collection', collectionId },
+        });
+      } else {
+        await this.issues.clear('scan', collectionId);
+      }
+    } catch (err) {
+      console.error('could not record a scan issue:', err.message);
+    }
+  }
+}
+
+/** S3 etags are quoted and some backends aren't; compare the value, not the quoting. */
+function normalizeEtag(etag) {
+  return String(etag).replace(/^W\//, '').replace(/^"|"$/g, '');
+}

package/packages/core/src/search/embeddings.js

@@ -0,0 +1,128 @@
+// EmbeddingProvider — turns text into vectors. Pluggable so deployments choose
+// their model/cost tradeoff. Two are bundled:
+//   - LocalHashEmbedding: zero-dependency, offline, deterministic. A hashed
+//     bag-of-bigrams projected to a fixed dim and L2-normalised. Not as good as
+//     a real model, but makes semantic search work out of the box and in tests.
+//   - HttpEmbedding: POSTs to any OpenAI-compatible /embeddings endpoint (OpenAI,
+//     Ollama, LM Studio, a self-hosted model). This is the production path.
+// Both expose `dimensions` and `embed(texts) -> number[][]`.
+
+import { withRetry } from '../retry.js';
+import { TroveError, wrapError } from '../errors.js';
+
+export class EmbeddingProvider {
+  get dimensions() {
+    return 0;
+  }
+  /** @param {string[]} texts @returns {Promise<number[][]>} */
+  async embed(texts) {
+    throw TroveError.unsupported('embed not implemented');
+  }
+  async embedOne(text) {
+    return (await this.embed([text]))[0];
+  }
+}
+
+const STOP = new Set('a an the of to in on for and or is are be as at by with from this that it'.split(' '));
+
+function tokenize(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length > 1 && !STOP.has(t));
+}
+
+// FNV-1a → 32-bit, used to bucket features into vector dims.
+function fnv(str) {
+  let h = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+export class LocalHashEmbedding extends EmbeddingProvider {
+  constructor({ dimensions = 256 } = {}) {
+    super();
+    this._dim = dimensions;
+  }
+  get dimensions() {
+    return this._dim;
+  }
+  async embed(texts) {
+    return texts.map((t) => this.#vec(t));
+  }
+  #vec(text) {
+    const v = new Float64Array(this._dim);
+    const tokens = tokenize(text);
+    // Unigrams + bigrams give a little word-order sensitivity.
+    const feats = [...tokens];
+    for (let i = 0; i < tokens.length - 1; i++) feats.push(tokens[i] + '_' + tokens[i + 1]);
+    for (const f of feats) {
+      const h = fnv(f);
+      const idx = h % this._dim;
+      const sign = (h >> 31) & 1 ? -1 : 1; // signed hashing reduces collisions
+      v[idx] += sign;
+    }
+    // L2 normalise so dot product == cosine similarity.
+    let norm = 0;
+    for (let i = 0; i < v.length; i++) norm += v[i] * v[i];
+    norm = Math.sqrt(norm) || 1;
+    return Array.from(v, (x) => x / norm);
+  }
+}
+
+export class HttpEmbedding extends EmbeddingProvider {
+  /**
+   * @param {object} cfg
+   * @param {string} cfg.url        e.g. https://api.openai.com/v1/embeddings
+   * @param {string} [cfg.apiKey]
+   * @param {string} [cfg.model]    e.g. text-embedding-3-small
+   * @param {number} cfg.dimensions the model's output dim (must match your index)
+   * @param {number} [cfg.batchSize]
+   */
+  constructor(cfg) {
+    super();
+    if (!cfg?.url || !cfg?.dimensions) throw TroveError.invalid('HttpEmbedding requires url and dimensions');
+    this.cfg = cfg;
+  }
+  get dimensions() {
+    return this.cfg.dimensions;
+  }
+  async embed(texts) {
+    const batchSize = this.cfg.batchSize ?? 64;
+    const out = [];
+    for (let i = 0; i < texts.length; i += batchSize) {
+      const batch = texts.slice(i, i + batchSize);
+      out.push(...(await this.#embedBatch(batch)));
+    }
+    return out;
+  }
+  async #embedBatch(batch) {
+    return withRetry(async () => {
+      let res;
+      try {
+        res = await fetch(this.cfg.url, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            ...(this.cfg.apiKey ? { authorization: `Bearer ${this.cfg.apiKey}` } : {}),
+          },
+          body: JSON.stringify({ model: this.cfg.model, input: batch }),
+        });
+      } catch (err) {
+        throw wrapError(err);
+      }
+      if (res.status === 429 || res.status >= 500) {
+        throw TroveError.transient(`Embedding endpoint ${res.status}`);
+      }
+      if (!res.ok) throw TroveError.internal(`Embedding endpoint failed: ${res.status}`);
+      const json = await res.json();
+      // OpenAI shape: { data: [{ embedding: [...] }, ...] }
+      const data = json.data ?? json.embeddings ?? [];
+      return data.map((d) => d.embedding ?? d);
+    });
+  }
+}