@3sln/trove 0.0.2

package/packages/server/src/adapters/node.js

@@ -0,0 +1,115 @@
+// Node adapter. Uses the standard http server and converts between Node's
+// req/res and Web Request/Response (Node 20+ has global fetch/Request/Response
+// and Readable.toWeb/fromWeb). Serves the built web app from disk when present,
+// with SPA fallback, so `node adapters/node.js` runs the whole thing.
+//
+//   TROVE_STORAGE=filesystem TROVE_FS_ROOT=./data/objects \
+//   TROVE_METADATA=sqlite TROVE_DB_PATH=./data/trove.db \
+//   node packages/server/src/adapters/node.js
+
+import http from 'node:http';
+import fs, { readFileSync } from 'node:fs';
+import fsp from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { createServer, configFromEnv, warnOnOpenAccess } from '../index.js';
+import { findWebDist } from './webDist.js';
+import { createStaticAssets } from './staticAssets.js';
+
+// A JWKS held in a file rather than inlined in the environment: multi-line JSON is
+// awkward in env vars and shows up in `docker inspect`, while a mounted secret file
+// does not. Read here rather than in configFromEnv, which has to stay loadable on
+// Workers where there is no filesystem.
+if (process.env.TROVE_JWT_JWKS_FILE && !process.env.TROVE_JWT_JWKS) {
+  process.env.TROVE_JWT_JWKS = readFileSync(process.env.TROVE_JWT_JWKS_FILE, 'utf8');
+}
+
+
+// TROVE_-prefixed to match every other setting; bare PORT/HOST still work, since that
+// is what most platforms inject and breaking them would be gratuitous.
+const PORT = Number(process.env.TROVE_PORT || process.env.PORT || 8787);
+const HOST = process.env.TROVE_HOST || process.env.HOST || '0.0.0.0';
+
+// Built web assets, if the app has been built — see webDist.js for why this is a
+// resolution rather than a relative path.
+const { dir: WEB_DIST, source: WEB_DIST_SOURCE } = findWebDist();
+
+// Where to look, what to refuse and what to say about caching is shared with the Bun
+// adapter — see staticAssets.js. All that differs here is how a file is read.
+const staticAssets = WEB_DIST && createStaticAssets({
+  dir: WEB_DIST,
+  read: async (filePath) => {
+    try {
+      const stat = await fsp.stat(filePath);
+      if (!stat.isFile()) return null;
+      return {
+        size: stat.size,
+        mtime: stat.mtimeMs,
+        open: () => Readable.toWeb(fs.createReadStream(filePath)),
+      };
+    } catch {
+      return null;
+    }
+  },
+});
+
+async function toWebRequest(nodeReq) {
+  const url = `http://${nodeReq.headers.host || 'localhost'}${nodeReq.url}`;
+  const method = nodeReq.method;
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(nodeReq.headers)) if (v) headers.set(k, Array.isArray(v) ? v.join(',') : v);
+  const hasBody = method !== 'GET' && method !== 'HEAD';
+  return new Request(url, {
+    method, headers,
+    body: hasBody ? Readable.toWeb(nodeReq) : undefined,
+    duplex: hasBody ? 'half' : undefined,
+  });
+}
+
+async function writeWebResponse(res, webRes) {
+  res.statusCode = webRes.status;
+  webRes.headers.forEach((v, k) => res.setHeader(k, v));
+  if (webRes.body) {
+    await new Promise((resolve, reject) =>
+      Readable.fromWeb(webRes.body).pipe(res).on('finish', resolve).on('error', reject),
+    );
+  } else {
+    res.end();
+  }
+}
+
+const hasWeb = !!WEB_DIST;
+const envConfig = configFromEnv();
+warnOnOpenAccess(envConfig);
+const { handle, close } = await createServer({
+  ...envConfig,
+  assets: hasWeb ? staticAssets : undefined,
+});
+
+const server = http.createServer(async (nodeReq, nodeRes) => {
+  try {
+    const webReq = await toWebRequest(nodeReq);
+    const webRes = await handle(webReq);
+    await writeWebResponse(nodeRes, webRes);
+  } catch (err) {
+    console.error('server error', err);
+    if (!nodeRes.headersSent) nodeRes.statusCode = 500;
+    nodeRes.end('Internal error');
+  }
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`Trove server on http://${HOST}:${PORT}  (web assets: ${hasWeb ? WEB_DIST : `none — ${WEB_DIST_SOURCE}; run npm run build:web`})`);
+});
+
+// Graceful shutdown: stop accepting connections, then flush notifications, dispose
+// the sidecar, and close SQLite cleanly so a redeploy doesn't lose in-flight work.
+let shuttingDown = false;
+async function shutdown(signal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(`Trove shutting down (${signal})…`);
+  server.close();
+  try { await close(); } catch (err) { console.error('shutdown error', err); }
+  process.exit(0);
+}
+for (const sig of ['SIGTERM', 'SIGINT']) process.on(sig, () => shutdown(sig));

package/packages/server/src/adapters/staticAssets.js

@@ -0,0 +1,123 @@
+// Serving the built web app.
+//
+// This was copied into the Node and Bun adapters, and had already drifted — one of them
+// had a content-type fallback the other did not. What differs between the two runtimes
+// is how you read a file; everything else (where to look, what to refuse, what to say
+// about caching) is one policy, so it lives here and each adapter passes in its reader.
+//
+// Three things this gets right that the copies did not:
+//
+//   A miss under /assets/ is a 404, not the SPA fallback. The fallback answered EVERY
+//   non-/api miss with index.html at status 200 — including a request for a hashed
+//   asset. After a deploy the old hashed names are gone, so a client still running the
+//   previous index.html asked for `/assets/main-OLD.js` and got HTML with
+//   `content-type: text/html`. The module fails to load, and because the service worker
+//   caches anything that came back 200, the HTML was stored under the JS URL and served
+//   from cache forever after. A 404 is a miss the browser and the worker both
+//   understand.
+//
+//   Cache-Control is claimed where it is true and nowhere else. Everything under
+//   /assets/ is content-addressed — the filename changes when the bytes do — so it can
+//   be kept for a year and never revalidated. Everything else keeps a stable name and
+//   must be revalidated on every load. Marking the second group immutable is what turns
+//   a deploy into a blank page; leaving the first group unmarked is what makes the
+//   hashing pointless, which is what was happening: the responses carried no
+//   Cache-Control at all.
+//
+//   There are validators. `no-cache` does not mean "do not cache", it means "revalidate
+//   before use" — but a revalidation with nothing to revalidate AGAINST is just a fresh
+//   download. sql-wasm.wasm is 650 kB and sits at a stable name, so without an ETag it
+//   came down in full every time a plugin touched client storage.
+
+import path from 'node:path';
+// The policy lives in its own module because index.js needs it too and has to stay
+// loadable on Workers, where `node:path` is not there to be imported.
+import { IMMUTABLE_PREFIX, cacheControlFor } from '../cachePolicy.js';
+
+export { IMMUTABLE_PREFIX, cacheControlFor };
+
+export const MIME = {
+  '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css',
+  '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.map': 'application/json',
+  '.webmanifest': 'application/manifest+json', '.wasm': 'application/wasm',
+};
+
+/**
+ * Should a miss here fall back to the SPA entry point?
+ *
+ * The client never puts a path in the URL — `navigation.js` calls pushState with no URL
+ * argument, so the whole app lives at `/`. The fallback is therefore for robustness
+ * (a refresh somewhere unexpected), never for deep links, which is what makes it safe
+ * to refuse anything that looks like a file rather than a route.
+ *
+ * @param {string} pathname
+ */
+export function shouldFallBack(pathname) {
+  if (pathname.startsWith('/api/')) return false;
+  // Content-addressed: a miss is a stale reference to a build that no longer exists.
+  // Answering it with HTML is what poisons a service worker cache.
+  if (pathname.startsWith(IMMUTABLE_PREFIX)) return false;
+  // Anything with an extension is asking for a file, not a view.
+  if (path.extname(pathname)) return false;
+  return true;
+}
+
+/** A weak validator from what a stat already tells us — no hashing, no read. */
+export const etagFor = ({ size, mtime }) => `W/"${size.toString(16)}-${Math.floor(mtime).toString(16)}"`;
+
+/**
+ * Build the `assets` fetcher the server takes.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir the built web app
+ * @param {(filePath: string) => Promise<{size: number, mtime: number, type?: string, open: () => any}|null>} opts.read
+ *   runtime-specific: resolve to null when the path is not a readable file. `open` is
+ *   separate from the stat so a 304 or a HEAD does not open a handle it will not read.
+ */
+export function createStaticAssets({ dir, read }) {
+  return async function staticAssets(req) {
+    const url = new URL(req.url);
+    let pathname;
+    try {
+      pathname = decodeURIComponent(url.pathname);
+    } catch {
+      return null; // a bad escape names nothing
+    }
+
+    const served = await serve(pathname === '/' ? '/index.html' : pathname);
+    if (served) return served;
+
+    if ((req.method === 'GET' || req.method === 'HEAD') && shouldFallBack(pathname)) {
+      return serve('/index.html', { as: pathname });
+    }
+    return null;
+
+    async function serve(rel, { as = rel } = {}) {
+      const filePath = path.join(dir, path.normalize(rel));
+      // path.normalize collapses `..`, but only a prefix check proves the result is
+      // still inside the directory we meant.
+      if (filePath !== dir && !filePath.startsWith(dir + path.sep)) return null;
+
+      const file = await read(filePath);
+      if (!file) return null;
+
+      const type = MIME[path.extname(filePath)] || file.type || 'application/octet-stream';
+      const etag = etagFor(file);
+      const headers = {
+        'content-type': type,
+        // The URL the client asked for decides the policy, not the file that answered:
+        // index.html served as an SPA fallback must still be revalidated.
+        'cache-control': cacheControlFor(as),
+        etag,
+      };
+
+      // A validator is only worth attaching if we also honour it — otherwise every
+      // revalidation is a full download of something the client already has.
+      if (req.headers.get('if-none-match') === etag) {
+        return new Response(null, { status: 304, headers });
+      }
+      return new Response(req.method === 'HEAD' ? null : file.open(), { headers });
+    }
+  };
+}

package/packages/server/src/adapters/webDist.js

@@ -0,0 +1,70 @@
+// Where the built web app is.
+//
+// This was once a guess about the shape of the tree three levels above the file doing
+// the guessing:
+//
+//   path.resolve(__dirname, '../../../web/dist')
+//
+// It was right inside the repo and right again when installed, but only while
+// `@trove/server` and `@trove/web` happened to land as siblings under one `@trove/`
+// directory — a fact about a particular installer's layout rather than anything either
+// package promised. Nest the install, vendor one of them, or hoist differently and the
+// drive silently served no web app, with a 404 on `/` as the only clue.
+//
+// Trove now ships as a single package with the built app inside it, which retires the
+// problem rather than working around it: server and web are no longer two things an
+// installer arranges relative to each other, they are two directories in one tarball,
+// and their arrangement is fixed by the package that contains both. So the relative
+// path below is no longer a guess — it is the layout this package's own `files` field
+// guarantees.
+//
+// Resolution is still tried first, because it is the one that keeps working when this
+// file is *not* where it thinks it is: a bundler that flattened the tree, or a copy
+// vendored somewhere else. The two answers agree whenever both are available, and each
+// covers the other's failure mode.
+
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const WEB_DIST_IN_PACKAGE = 'packages/web/dist';
+
+/**
+ * Locate the built web assets, or null when the app has not been built.
+ *
+ * Order matters: an explicit setting is never second-guessed, and if it points
+ * somewhere empty that is reported rather than quietly worked around — an operator who
+ * set TROVE_WEB_DIST wants to know it was wrong, not to be silently given a different
+ * directory that happened to exist.
+ *
+ * @param {string} [envDist] the value of TROVE_WEB_DIST
+ * @returns {{dir: string|null, source: string}} where it looked and how it decided
+ */
+export function findWebDist(envDist = process.env.TROVE_WEB_DIST) {
+  if (envDist) {
+    const dir = path.resolve(envDist);
+    return existsSync(dir)
+      ? { dir, source: 'TROVE_WEB_DIST' }
+      : { dir: null, source: `TROVE_WEB_DIST=${envDist} (no such directory)` };
+  }
+
+  // The package root, wherever the resolver says it is. A package can reference itself
+  // by name, so this resolves both from a checkout and from inside `node_modules` —
+  // and it reaches the manifest because `./package.json` is one of the subpaths
+  // `exports` names. If that ever stops being true this throws rather than returning
+  // something wrong, which is why it is wrapped.
+  try {
+    const require = createRequire(import.meta.url);
+    const root = path.dirname(require.resolve('@3sln/trove/package.json'));
+    const dir = path.join(root, WEB_DIST_IN_PACKAGE);
+    if (existsSync(dir)) return { dir, source: '@3sln/trove' };
+  } catch { /* not resolvable from here — fall through to the layout we ship */ }
+
+  // Four levels up from packages/server/src/adapters/ is the package root.
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const dir = path.resolve(here, '../../../..', WEB_DIST_IN_PACKAGE);
+  if (existsSync(dir)) return { dir, source: 'relative to this file' };
+
+  return { dir: null, source: 'not built' };
+}

package/packages/server/src/adapters/worker-tasks.js

@@ -0,0 +1,206 @@
+// Background work on Workers, in a Durable Object.
+//
+// The TaskRegistry is in-memory and per-process, and that is the right lifetime: a task
+// describes work in flight, and work in flight does not survive the thing doing it.
+// What breaks on Workers is not the lifetime — it is that the process boundary stopped
+// matching the work boundary. On a long-lived server one process runs the scan AND
+// answers the polls, so "in memory" and "where the work is" are the same place. On
+// Workers they come apart: the scan runs in whichever isolate served the POST, and the
+// GET that asks about it lands wherever the router feels like.
+//
+// The fix is NOT to make the task list durable. A stored record saying "running" after
+// the isolate that owned it was evicted is a phantom that nothing can ever correct —
+// on a server a restart clears it, in durable storage it is forever. The fix is to give
+// the work a real process again. A Durable Object is one: addressable by name, so every
+// request reaches the same instance; single-threaded, so "is one already running?" can
+// be answered truthfully; and long-lived, with `setAlarm` to pick work back up.
+//
+// So the registry stays exactly as it is, and moves in here with the work it describes.
+//
+// Three things this fixes that `waitUntil` alone does not:
+//   • progress polling — /api/tasks reaches the isolate that owns the task
+//   • cancel — the AbortController is in the same place as the work it aborts
+//   • the "already running" guard — one instance, not one per isolate
+//
+// Eviction is still possible mid-slice, and that is what the alarm is for: the scan
+// cursor is persisted, `pending:` says the collection is not finished, and the alarm
+// brings the object back to continue. Losing the isolate costs a slice, not the scan.
+
+import { TaskRegistry } from '@3sln/trove/core';
+
+/** How long one scan slice may run before it yields and stores its cursor. */
+const DEFAULT_SLICE_MS = 20_000;
+/** Gap between slices. Long enough not to hammer the store, short enough to feel live. */
+const SLICE_GAP_MS = 5_000;
+const PENDING = 'pending:';
+
+/**
+ * The Durable Object. Export it from the Worker entry module and declare it in
+ * wrangler.toml; see the README section "Work that outlives a request".
+ *
+ * @param {(env: object) => Promise<object>} getServer builds (and caches) the server
+ */
+export function createTaskHost(getServer) {
+  return class TroveTasks {
+    constructor(state, env) {
+      this.state = state;
+      this.env = env;
+      this.server = null;
+      this.sliceMs = Number(env?.TROVE_SLICE_MS || DEFAULT_SLICE_MS);
+    }
+
+    async #boot() {
+      this.server ||= await getServer(this.env);
+      return this.server;
+    }
+
+    /** Wake up in `ms` — unless we are already due sooner. */
+    async #arm(ms) {
+      const at = Date.now() + ms;
+      const current = await this.state.storage.getAlarm();
+      if (current == null || current > at) await this.state.storage.setAlarm(at);
+    }
+
+    async #beginScan(collectionId, reason) {
+      const server = await this.#boot();
+      const { task, alreadyRunning, done } = await server.beginScan(collectionId, {
+        reason, deadlineMs: this.sliceMs,
+      });
+      if (!alreadyRunning) {
+        // Recorded BEFORE the slice runs. If this object is evicted half way through,
+        // the alarm is what brings it back — and it can only do that if it knows the
+        // collection is unfinished. Writing this after the slice would mean an eviction
+        // silently ends the scan, which is the failure this whole file is about.
+        await this.state.storage.put(`${PENDING}${collectionId}`, { reason: reason || 'Continuing' });
+        this.state.waitUntil?.(done.then(
+          // `stopped`, not `nextCursor`: a slice that runs out of budget before it
+          // processes anything stops with a null cursor — correctly, since it got
+          // nowhere and must resume from the start. Reading that as "finished" would
+          // drop the collection off the list having scanned none of it.
+          (r) => (r && !r.stopped ? this.state.storage.delete(`${PENDING}${collectionId}`) : null),
+          () => null, // a failed slice stays pending; the alarm retries it
+        ));
+      }
+      await this.#arm(SLICE_GAP_MS);
+      return { task, alreadyRunning };
+    }
+
+    async #beginReindex(reason) {
+      const server = await this.#boot();
+      const { task, alreadyRunning, done } = await server.beginReindex({ reason });
+      // A reindex has no cursor to resume from, so there is nothing to continue — it
+      // either finishes in this object's lifetime or it is retried, and a failure
+      // leaves an Issue behind either way.
+      if (!alreadyRunning) this.state.waitUntil?.(done.catch(() => null));
+      return { task, alreadyRunning };
+    }
+
+    async fetch(request) {
+      const url = new URL(request.url);
+      const body = request.method === 'POST' ? await request.json().catch(() => ({})) : {};
+      const json = (v) => new Response(JSON.stringify(v), { headers: { 'content-type': 'application/json' } });
+      const server = await this.#boot();
+      switch (url.pathname) {
+        case '/begin':
+          return json(body.kind === 'index'
+            ? await this.#beginReindex(body.reason)
+            : await this.#beginScan(body.collectionId || 'default', body.reason));
+        case '/tasks':
+          return json({ tasks: server.tasks.list(body) });
+        case '/task':
+          return json({ task: server.tasks.get(body.id) });
+        case '/cancel':
+          return json({ cancelled: server.tasks.cancel(body.id) });
+        case '/dismiss':
+          server.tasks.dismiss(body.id);
+          return json({ ok: true });
+        case '/maintain':
+          return json({ result: await server.runMaintenance({ budgetMs: body.budgetMs ?? this.sliceMs }) });
+        default:
+          return new Response('not found', { status: 404 });
+      }
+    }
+
+    /**
+     * Continue every collection that has not finished its pass. This is the durable
+     * half: a Cron Trigger starts things, but it is the alarm that keeps a bucket too
+     * large for one slice moving, without waiting for the next cron tick.
+     */
+    async alarm() {
+      const server = await this.#boot();
+      const pending = await this.state.storage.list({ prefix: PENDING });
+      for (const [key, meta] of pending) {
+        const collectionId = key.slice(PENDING.length);
+        const result = await server
+          .startScan(collectionId, { reason: meta?.reason || 'Continuing', deadlineMs: this.sliceMs })
+          .catch(() => null);
+        // Done only when a pass ran to the end. `alreadyRunning` means another slice
+        // holds the claim right now — still unfinished, so it stays on the list.
+        if (result && !result.alreadyRunning && !result.stopped) await this.state.storage.delete(key);
+      }
+      if ((await this.state.storage.list({ prefix: PENDING })).size) await this.#arm(SLICE_GAP_MS);
+    }
+  };
+}
+
+/**
+ * The other side: a TaskRegistry that answers from the Durable Object rather than from
+ * this isolate's memory. Injected as `config.tasks`, so every route that reads tasks
+ * gets the truth without knowing where it lives.
+ */
+export class RemoteTasks extends TaskRegistry {
+  constructor(stub) {
+    super();
+    this.stub = stub;
+  }
+  async #rpc(path, payload) {
+    const res = await this.stub.fetch(`https://trove.tasks${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload || {}),
+    });
+    return res.json();
+  }
+  async list(opts = {}) { return (await this.#rpc('/tasks', opts)).tasks; }
+  async get(id) { return (await this.#rpc('/task', { id })).task; }
+  async cancel(id) { return (await this.#rpc('/cancel', { id })).cancelled; }
+  async dismiss(id) { await this.#rpc('/dismiss', { id }); }
+  /**
+   * Nothing to wait on here. The work is in the Durable Object, which keeps itself
+   * alive; this isolate only forwarded a message. Returning the base class's answer
+   * would make `ctx.waitUntil` hold the request open for work it does not own.
+   */
+  pending() { return null; }
+}
+
+/**
+ * Everything the front-line Worker needs to hand background work to the object.
+ * Pass into `createServer` as `{ tasks, background }`.
+ */
+export function remoteBackground(namespace) {
+  // One instance for the whole drive, by name. Tasks are few and long, so there is no
+  // throughput argument for sharding — and one instance is what makes GET /api/tasks a
+  // complete answer rather than a per-shard sample.
+  const stub = namespace.get(namespace.idFromName('trove-tasks'));
+  const begin = (payload) => stub
+    .fetch('https://trove.tasks/begin', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    .then((r) => r.json());
+  return {
+    tasks: new RemoteTasks(stub),
+    background: {
+      beginScan: (collectionId, { reason } = {}) => begin({ kind: 'scan', collectionId, reason }),
+      beginReindex: ({ reason } = {}) => begin({ kind: 'index', reason }),
+    },
+    maintain: (budgetMs) => stub
+      .fetch('https://trove.tasks/maintain', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ budgetMs }),
+      })
+      .then((r) => r.json()),
+  };
+}

package/packages/server/src/adapters/worker.js

@@ -0,0 +1,159 @@
+// Cloudflare Worker adapter. A Worker's fetch handler is already Web-standard,
+// so this is thin. Storage should be S3-compatible (R2 via the S3 API) so the
+// SigV4 signer and presigned URLs work. Bind a D1 database as `DB` and metadata, the
+// KV store, plugin installs, and keyword search persist there; bind `VECTORIZE` for the
+// semantic half. Without `DB` everything falls back to memory, which looks fine until
+// the isolate is recycled. Static assets are served from the ASSETS binding.
+//
+// wrangler.toml sketch:
+//   [vars] TROVE_S3_BUCKET = "..."  TROVE_S3_REGION = "auto"
+//   TROVE_S3_ENDPOINT = "https://<acct>.r2.cloudflarestorage.com"
+//   (secrets: TROVE_S3_ACCESS_KEY_ID, TROVE_S3_SECRET_ACCESS_KEY)
+//   [[d1_databases]] binding = "DB"          -> metadata, kv, keyword search
+//   [[vectorize]]    binding = "VECTORIZE"   -> semantic search
+//   [ai]             binding = "AI"          -> LLM query understanding (optional)
+//   [[durable_objects.bindings]] name = "TASKS" class_name = "TroveTasks"
+//                                            -> owns scans and reindexes (see below)
+
+import { D1SqliteProvider } from '@3sln/trove/core';
+import { createServer, configFromEnv } from '../index.js';
+import { createTaskHost, remoteBackground } from './worker-tasks.js';
+
+// Two DIFFERENT servers can be asked for here: the front-line one, which hands long
+// work to the Durable Object, and the one INSIDE that object, which does it. Keyed,
+// because they cannot share a slot — a delegating server handed back inside the object
+// would have it forward work to itself. Cloudflare gives a Durable Object its own
+// isolate today, so this has not been reachable; an invariant that costs one line to
+// state is cheaper than one that holds by luck.
+const cached = new Map();
+
+/**
+ * @param {object} env Worker env bindings
+ * @param {(env) => object} [buildVfs] optional: return { storage, metadata } (e.g. D1)
+ * @param {{delegate?: boolean}} [opts] delegate=false builds the server that DOES the
+ *   background work (inside the Durable Object) rather than one that hands it off
+ */
+async function getServer(env, buildVfs, { delegate = true } = {}) {
+  const slot = delegate ? 'edge' : 'worker';
+  if (cached.has(slot)) return cached.get(slot);
+  const config = configFromEnv(env);
+  if (buildVfs) config.vfs = buildVfs(env);
+  // D1 → metadata, kv, plugin installs, and the keyword half of search. Without this a
+  // Worker falls back to in-memory everything, which looks like it works right up until
+  // the isolate is recycled and the drive is empty. Bind `DB` and it persists.
+  if (env.DB && !config.sqlite) {
+    config.sqlite = new D1SqliteProvider({
+      db: env.DB,
+      // Plugin storage. `scopes: { plugins: … }` named a key that is already a CORE key
+      // (the install-record store), so the binding was silently ignored and every
+      // /api/plugins/:id/sql call was a 501 — the real keys look like
+      // `pstore:<user>:plg:<pluginId>` and cannot be pre-bound at all.
+      pluginStore: env.PLUGIN_DB || null,
+    });
+    config.metadata = { driver: 'sqlite' };
+  }
+  // Cloudflare Vectorize binding → first-class vector store (no REST creds needed).
+  if (env.VECTORIZE) {
+    config.vectorStore = { driver: 'vectorize', binding: env.VECTORIZE };
+  }
+  // Cloudflare Workers AI binding → LLM-assisted search transformer (human text →
+  // semantic text + tag filters). Enabled just by binding `AI`; picks a cheap model.
+  if (env.AI) {
+    config.searchTransformer = { driver: 'workers-ai', ai: env.AI, model: env.TROVE_SEARCH_MODEL };
+  }
+  // Serve static assets from the ASSETS binding (Workers Sites / assets).
+  if (env.ASSETS) {
+    config.assets = async (req) => {
+      const res = await env.ASSETS.fetch(req);
+      return res.status === 404 ? null : res;
+    };
+  }
+  // The Durable Object that owns long work. Bound as TASKS, it becomes the one place
+  // scans and reindexes run and the one place their tasks are listed — so a client
+  // polling /api/tasks reaches the isolate that actually has the task, and Cancel
+  // reaches the AbortController it is meant to abort. Without the binding the drive
+  // still works: the work runs in the request isolate under waitUntil, which is what
+  // it did before, with the caveats in the README.
+  if (delegate && env.TASKS) {
+    const remote = remoteBackground(env.TASKS);
+    config.tasks = remote.tasks;
+    config.background = remote.background;
+    config.maintain = remote.maintain;
+    // Timers do not survive a request here, and the object has its own alarm loop.
+    config.startFlusher = false;
+  }
+  const server = await createServer(config);
+  server.maintain = config.maintain || null;
+  cached.set(slot, server);
+  return server;
+}
+
+/**
+ * Default export usable directly as a Worker module.
+ *
+ * Two things here are Workers-specific and neither is optional.
+ *
+ * `ctx.waitUntil` — a Worker's isolate may be torn down the moment the response
+ * resolves. Work that was started and not awaited (a scan, a reindex) is not merely
+ * slow after that, it is CANCELLED, at whatever point it had reached. `waitUntil` is
+ * the only way to say "this response is done but I am not", so anything the request
+ * kicked off is handed to it.
+ *
+ * `scheduled` — a Cron Trigger. `setInterval` is how a long-lived process does periodic
+ * work and it does not work here at all: a timer registered inside a request does not
+ * outlive the request, so the maintenance and scan intervals never fire on Workers.
+ * Point a cron at the Worker and this runs one bounded slice per firing.
+ *
+ *   [triggers]
+ *   crons = ["*​/5 * * * *"]
+ *
+ * A third piece, `TroveTasks`, is exported below: `waitUntil` can keep work alive but
+ * cannot let another isolate SEE it, which is what progress polling and Cancel need.
+ */
+export default {
+  async fetch(request, env, ctx) {
+    const server = await getServer(env);
+    const res = await server.handle(request);
+    // Anything the request started but did not await — see `pendingWork` below.
+    const pending = server.tasks.pending?.();
+    if (pending && ctx?.waitUntil) ctx.waitUntil(pending);
+    return res;
+  },
+
+  /**
+   * Cron Trigger. Sweeps expired uploads and idle sidecars, applies trash retention,
+   * and advances each collection's scan by one time-boxed slice — the scanner stores
+   * the cursor it reached, so the next firing continues rather than starting over.
+   */
+  async scheduled(event, env, ctx) {
+    const server = await getServer(env);
+    const budgetMs = Number(env.TROVE_CRON_BUDGET_MS || 20_000);
+    // AWAITED, not fire-and-forget: `scheduled` gets its own budget, and the runtime
+    // keeps the isolate alive exactly as long as this promise is pending. With the
+    // Durable Object bound this hands the slice to it instead — the object then keeps
+    // itself going on its own alarm, so a bucket too large for one firing does not
+    // wait for the next cron tick to continue.
+    const work = Promise.resolve(
+      server.maintain ? server.maintain(budgetMs) : server.runMaintenance({ budgetMs }),
+    ).catch((e) => console.error('[trove] scheduled maintenance failed', e));
+    if (ctx?.waitUntil) ctx.waitUntil(work);
+    await work;
+  },
+};
+
+/**
+ * The Durable Object class. Declare it in wrangler.toml and it becomes the home of
+ * every scan and reindex — see worker-tasks.js for why that is the fix rather than
+ * making the task list durable.
+ *
+ *   [[durable_objects.bindings]]
+ *   name = "TASKS"
+ *   class_name = "TroveTasks"
+ *
+ *   [[migrations]]
+ *   tag = "v1"
+ *   new_sqlite_classes = ["TroveTasks"]
+ */
+export const TroveTasks = createTaskHost((env) => getServer(env, undefined, { delegate: false }));
+
+export { getServer };