@3sln/trove 0.0.3 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/trove",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "description": "Trove — a self-hostable, plugin-extensible Google Drive. Semantic search, pluggable storage (S3 / filesystem / NAS), and a VS Code-style contribution system with sandboxed plugins.",
   "repository": {

package/packages/core/src/index.js

@@ -66,9 +66,11 @@ export {
 export { SidecarService, SidecarStore, SidecarManager } from './sidecar/index.js';
 export * as sidecarOps from './sidecar/document.js';
 
-// Notifications: mention batching + web push.
+// Notifications: mention batching and the inbox, plus the channels that deliver.
+// `NotificationChannel` is the extension point — subclass it for email or chat.
 export { NotificationCenter } from './notifications/index.js';
-export { WebPushService, generateVapidKeys } from './notifications/webpush.js';
+export { NotificationChannel } from './notifications/channel.js';
+export { WebPushService, WebPushChannel, generateVapidKeys } from './notifications/webpush.js';
 
 import { Vfs } from './vfs.js';
 import { MemoryStorage } from './storage/memory.js';

package/packages/core/src/notifications/channel.js

@@ -0,0 +1,68 @@
+// A way a notification reaches a person.
+//
+// The inbox is not one of these. NotificationCenter batches mentions, collapses each
+// batch into one notification, and writes it to the user's inbox — that is the durable
+// record, it works with no channel configured at all, and /api/notifications serves it.
+// A channel is the part that goes and TELLS someone: a web push, an email, a message
+// into a chat workspace. Nothing here is allowed to be the only copy of anything.
+//
+// Two constraints worth knowing before writing one:
+//
+//   It must be fetch-based. On Workers the drain runs inside a cron slice, where there
+//   are no sockets — an email channel has to be an HTTP API (Resend, SES, Postmark),
+//   not SMTP. A channel that opens a socket works on a self-hosted drive and fails on
+//   the runtime the drive most often ships to.
+//
+//   Delivery is best-effort and isolated. A channel that throws is logged and the rest
+//   still run; the notification is already in the inbox by then, so a failed send loses
+//   the ping and not the notification.
+//
+// Channels may also own routes — the endpoints a client needs to REGISTER with them, of
+// which a VAPID key and a push subscription are the obvious example. Those endpoints
+// live with the channel rather than in the core route table, so the drive's API does
+// not grow a permanent `/api/push/*` whether or not push exists.
+
+import { TroveError } from '../errors.js';
+
+export class NotificationChannel {
+  /**
+   * Stable identifier, used in logs and to find a channel among its peers.
+   * @returns {string}
+   */
+  get id() {
+    throw TroveError.unsupported('A NotificationChannel must have an id');
+  }
+
+  /**
+   * Deliver one notification to one user. Called once per user per drain, after the
+   * notification is already in their inbox.
+   *
+   * @param {string} userId the principal id
+   * @param {object} note the collapsed notification — id, kind, count, items, title
+   * @returns {Promise<void>}
+   */
+  async deliver(userId, note) { // eslint-disable-line no-unused-vars
+    throw TroveError.unsupported(`Channel "${this.id}" cannot deliver`);
+  }
+
+  /**
+   * Endpoints this channel needs, mounted under the drive's router.
+   *
+   * Each is `{ method, path, deps, handler }` with the same meaning the router gives
+   * them — `deps` names the resources the handler is leased, and the handler receives
+   * them alongside `principal`, `req`, `params` and `query`. Returning nothing is the
+   * common case: a channel that reads an address off the identity has nothing to
+   * register.
+   *
+   * `helpers` is the request plumbing the router owns and a channel should not
+   * reimplement: `body(req)` parses JSON under the server's size cap — the cap is the
+   * point, a channel parsing the body itself is an unbounded read — and
+   * `requirePrincipal(principal)` throws the same 401 every other route throws.
+   *
+   * @param {{body: Function, requirePrincipal: Function}} helpers
+   * @returns {Array<{method: string, path: string, deps?: string[], handler: Function}>}
+   */
+  routes(helpers) { // eslint-disable-line no-unused-vars
+    return [];
+  }
+}

package/packages/core/src/notifications/index.js

@@ -1,17 +1,25 @@
-// NotificationCenter — batches @mentions and flushes them on a configurable
-// interval, exactly as requested: as conversations mutate, mentions accumulate
-// per user; every `flushIntervalMs` we drain the batch, drop it into each user's
-// inbox, and fire a (bodyless) web push so their service worker wakes and pulls
-// the inbox. Push subscriptions, pending batches, and inboxes live in the
-// pluggable KeyValueStore, so this survives restarts and works multi-instance.
+// NotificationCenter — batches @mentions and drains them on a configurable
+// interval: as conversations mutate, mentions accumulate per user; every
+// `flushIntervalMs` we drain the batch, collapse it into one notification, drop that
+// into the user's inbox, and hand it to each delivery channel. Pending batches and
+// inboxes live in the pluggable KeyValueStore, so this survives restarts and works
+// multi-instance.
 //
-// Bodyless push (see webpush.js) means we never put mention text on a third-party
-// push service — the client fetches /api/notifications over its authenticated
-// channel instead.
+// The split worth keeping straight: the INBOX is the record, and it is written whether
+// or not anything can be delivered — /api/notifications serves it and a drive with no
+// channels configured still notifies people perfectly well. A CHANNEL is the part that
+// goes and tells someone, and it is allowed to fail. Web push is one channel (see
+// webpush.js); email or a chat workspace would be others, and nothing here knows the
+// difference between them.
+//
+// Bodyless push means mention text never reaches a third-party push service — the
+// client fetches /api/notifications over its authenticated channel instead. That is a
+// property of the web-push channel rather than of this file, but it is the reason the
+// inbox has to exist independently of delivery.
 
-import { assertPublicUrl } from '../util.js';
+import { TroveError } from '../errors.js';
+import { WebPushChannel } from './webpush.js';
 
-const NS_SUBS = 'push-subs'; // userId -> [subscription]
 const NS_PENDING = 'mentions-pending'; // userId -> [mention]
 const NS_INBOX = 'notifications-inbox'; // userId -> [notification]
 
@@ -19,21 +27,31 @@ export class NotificationCenter {
   /**
    * @param {object} deps
    * @param {import('../kv.js').KeyValueStore} deps.kv
-import { assertPublicUrl } from '../util.js';
-   * @param {import('./webpush.js').WebPushService} [deps.push]
+   * @param {import('./channel.js').NotificationChannel[]} [deps.channels] delivery
+   * @param {import('./webpush.js').WebPushService} [deps.push] the pre-channel
+   *   spelling of "web push": a bare service, wrapped into a channel here so there is
+   *   still exactly one delivery path.
    * @param {number} [deps.flushIntervalMs] default 30s
    * @param {number} [deps.inboxCap] keep at most N per user (default 200)
    */
-  constructor({ kv, push, flushIntervalMs = 30_000, inboxCap = 200 }) {
+  constructor({ kv, push, channels, flushIntervalMs = 30_000, inboxCap = 200 }) {
     this.kv = kv;
-    this.push = push || null;
+    this.channels = [
+      ...(channels || []),
+      ...(push ? [new WebPushChannel({ kv, service: push })] : []),
+    ];
     this.flushIntervalMs = flushIntervalMs;
     this.inboxCap = inboxCap;
     this._timer = null;
   }
 
+  /** A channel by id, for the callers that need a specific one. */
+  channel(id) {
+    return this.channels.find((c) => c.id === id) || null;
+  }
+
   vapidPublicKey() {
-    return this.push?.publicKey || null;
+    return this.channel('web-push')?.publicKey || null;
   }
 
   /** Queue mention events (from SidecarService.onMentions). */
@@ -45,8 +63,25 @@ import { assertPublicUrl } from '../util.js';
     }
   }
 
-  /** Drain all pending batches: inbox + push. Returns how many users notified. */
+  /**
+   * Drain all pending batches: inbox + push. Returns how many users notified.
+   *
+   * Concurrent calls collapse onto one drain. There are two callers — the interval
+   * timer, and maintenance on a runtime whose timers do not survive a request — and
+   * both can be live at once. Two drains reading the same pending batch would deliver
+   * it twice, because the read and the delete are not one operation.
+   *
+   * This makes one PROCESS safe, not a cluster: two servers over a shared KV can still
+   * both read a batch before either deletes it. That race predates this and wants a
+   * claim in the store to fix properly.
+   */
   async flush(now = Date.now()) {
+    if (this._draining) return this._draining;
+    this._draining = this.#drain(now).finally(() => { this._draining = null; });
+    return this._draining;
+  }
+
+  async #drain(now) {
     const pendingUsers = await this.kv.list(NS_PENDING);
     let notified = 0;
     for (const { key: userId, value: mentions } of pendingUsers) {
@@ -70,47 +105,41 @@ import { assertPublicUrl } from '../util.js';
       inbox.unshift(note);
       await this.kv.set(NS_INBOX, userId, inbox.slice(0, this.inboxCap));
       await this.kv.delete(NS_PENDING, userId);
-      await this.#pushTo(userId, note);
+      await this.#deliver(userId, note);
       notified++;
     }
     return notified;
   }
 
-  async #pushTo(userId, note) {
-    if (!this.push) return;
-    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
-    const alive = [];
-    for (const sub of subs) {
+  /**
+   * Hand one notification to every channel.
+   *
+   * Sequential and forgiving: a channel that throws is logged and the others still run.
+   * The inbox was written above, so a failed send costs the ping and not the
+   * notification — which is the whole reason the inbox is not itself a channel.
+   */
+  async #deliver(userId, note) {
+    for (const channel of this.channels) {
       try {
-        const res = await this.push.send(sub, { topic: 'mentions', urgency: 'normal' });
-        if (!res.gone) alive.push(sub);
-      } catch {
-        alive.push(sub); // transient — keep the subscription, retry next flush
+        await channel.deliver(userId, note);
+      } catch (err) {
+        console.error(`[trove] notification channel "${channel.id}" failed for ${userId}`, err);
       }
     }
-    if (alive.length !== subs.length) await this.kv.set(NS_SUBS, userId, alive);
   }
 
   // --- subscriptions & inbox (called by routes) ------------------------------
 
   async subscribePush(userId, subscription) {
-    if (!subscription?.endpoint) throw new Error('Invalid push subscription');
-    // The server POSTs to this endpoint, from inside its own network, on every flush.
-    // Left unchecked it is a request forgery primitive any user can register — cloud
-    // instance metadata being the obvious target. A real push service is on the public
-    // internet, so nothing legitimate is lost by refusing the rest.
-    assertPublicUrl(subscription.endpoint, 'Push endpoint');
-    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
-    if (!subs.some((s) => s.endpoint === subscription.endpoint)) {
-      subs.push(subscription);
-      await this.kv.set(NS_SUBS, userId, subs);
-    }
-    return { ok: true };
+    const channel = this.channel('web-push');
+    if (!channel) throw TroveError.unsupported('Web push is not configured');
+    return channel.subscribe(userId, subscription);
   }
+
   async unsubscribePush(userId, endpoint) {
-    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
-    await this.kv.set(NS_SUBS, userId, subs.filter((s) => s.endpoint !== endpoint));
-    return { ok: true };
+    const channel = this.channel('web-push');
+    if (!channel) throw TroveError.unsupported('Web push is not configured');
+    return channel.unsubscribe(userId, endpoint);
   }
 
   async inbox(userId) {

package/packages/core/src/notifications/webpush.js

@@ -18,6 +18,8 @@
 
 import { TroveError } from '../errors.js';
 import { withRetry } from '../retry.js';
+import { assertPublicUrl } from '../util.js';
+import { NotificationChannel } from './channel.js';
 
 const enc = new TextEncoder();
 
@@ -215,3 +217,111 @@ export class WebPushService {
     );
   }
 }
+
+// --- as a notification channel --------------------------------------------------
+
+const NS_SUBS = 'push-subs'; // userId -> [subscription]
+
+/**
+ * Web push, as one way of reaching someone.
+ *
+ * Owns the subscriptions as well as the sending, because they are the same concern:
+ * a subscription is a push endpoint and means nothing to any other channel. It also
+ * owns the endpoints a browser uses to register one — the VAPID public key and the
+ * subscribe/unsubscribe pair — so a drive with no push configured does not answer on
+ * `/api/push/*` at all, rather than answering with a null.
+ */
+export class WebPushChannel extends NotificationChannel {
+  /**
+   * @param {object} o
+   * @param {import('../kv.js').KeyValueStore} o.kv where subscriptions live
+   * @param {WebPushService} [o.service] a ready service; otherwise built from the keys
+   * @param {string} [o.publicKey]
+   * @param {string} [o.privateKey]
+   * @param {string} [o.subject]
+   */
+  constructor({ kv, service, publicKey, privateKey, subject } = {}) {
+    super();
+    if (!kv) throw TroveError.invalid('WebPushChannel requires a kv store');
+    this.kv = kv;
+    this.service = service ?? new WebPushService({ publicKey, privateKey, subject });
+  }
+
+  get id() { return 'web-push'; }
+
+  /** The application server key a browser needs to subscribe. */
+  get publicKey() { return this.service.publicKey; }
+
+  async deliver(userId, note) {
+    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
+    const alive = [];
+    for (const sub of subs) {
+      try {
+        const res = await this.service.send(sub, { topic: 'mentions', urgency: 'normal' });
+        if (!res.gone) alive.push(sub);
+      } catch {
+        alive.push(sub); // transient — keep the subscription, retry next drain
+      }
+    }
+    if (alive.length !== subs.length) await this.kv.set(NS_SUBS, userId, alive);
+  }
+
+  async subscribe(userId, subscription) {
+    if (!subscription?.endpoint) throw TroveError.invalid('Invalid push subscription');
+    // The server POSTs to this endpoint, from inside its own network, on every drain.
+    // Left unchecked it is a request forgery primitive any user can register — cloud
+    // instance metadata being the obvious target. A real push service is on the public
+    // internet, so nothing legitimate is lost by refusing the rest.
+    assertPublicUrl(subscription.endpoint, 'Push endpoint');
+    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
+    if (!subs.some((s) => s.endpoint === subscription.endpoint)) {
+      subs.push(subscription);
+      await this.kv.set(NS_SUBS, userId, subs);
+    }
+    return { ok: true };
+  }
+
+  async unsubscribe(userId, endpoint) {
+    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
+    await this.kv.set(NS_SUBS, userId, subs.filter((s) => s.endpoint !== endpoint));
+    return { ok: true };
+  }
+
+  /**
+   * The registration endpoints, owned here rather than by the core route table.
+   *
+   * They exist only when this channel does, which is the improvement over declaring
+   * them centrally: a drive with no VAPID keys used to answer `/api/push/vapid` with
+   * `{ publicKey: null }` and accept subscriptions it could never send to. Now there is
+   * no route at all, and a client that asks gets a 404 meaning what it says.
+   *
+   * The paths are unchanged, because the shipped web app calls them by name.
+   */
+  routes({ body, requirePrincipal }) {
+    return [
+      {
+        method: 'GET',
+        path: '/api/push/vapid',
+        handler: () => ({ publicKey: this.publicKey }),
+      },
+      {
+        method: 'POST',
+        path: '/api/push/subscribe',
+        handler: async ({ principal, req }) => {
+          requirePrincipal(principal);
+          const b = await body(req);
+          return this.subscribe(principal.id, b.subscription);
+        },
+      },
+      {
+        method: 'DELETE',
+        path: '/api/push/subscribe',
+        handler: async ({ principal, req }) => {
+          requirePrincipal(principal);
+          const b = await body(req);
+          return this.unsubscribe(principal.id, b.endpoint);
+        },
+      },
+    ];
+  }
+}

package/packages/core/src/sqlite-d1.js

@@ -23,6 +23,19 @@ import { SqliteDatabase, SqliteProvider } from './sqlite.js';
 // The keys the server co-locates in one database — see LocalSqliteProvider.
 const CORE_KEYS = new Set(['metadata', 'kv', 'plugins', 'search']);
 
+// D1 answers `PRAGMA journal_mode = WAL` with SQLITE_AUTH: setting a pragma is not
+// something a D1 client may do. The shared metadata schema opens with two of them, and
+// that runs in SqliteStore.init() — so the first request a Workers drive ever served
+// died, and every one after it, on a statement that is pure local-file housekeeping and
+// means nothing here. Dropped rather than made conditional at the call site: this is the
+// one place that knows it is talking to D1.
+//
+// Only ASSIGNMENTS. `PRAGMA table_info(nodes)` is a query, D1 supports it, and the trash
+// migration reads it to decide whether it has already run — filtering that too would
+// silently re-run migrations.
+const PRAGMA_ASSIGNMENT = /^\s*PRAGMA\s+[\w.]+\s*=/i;
+const notAPragmaAssignment = (statement) => !PRAGMA_ASSIGNMENT.test(statement);
+
 /** Split a multi-statement DDL script into individual statements. */
 function splitStatements(sql) {
   // Good enough for the schema DDL Trove ships, which contains no semicolons inside
@@ -51,7 +64,7 @@ class D1Database extends SqliteDatabase {
     // D1's own exec() is documented as slow and unsuitable for anything hot; it is also
     // inconsistent about multi-statement input across versions. Batching prepared
     // statements is both faster and atomic, which is what schema setup wants.
-    const statements = splitStatements(sql);
+    const statements = splitStatements(sql).filter(notAPragmaAssignment);
     if (!statements.length) return;
     if (statements.length === 1) {
       await this.d1.prepare(statements[0]).run();

package/packages/core/src/sqlite-driver.js

@@ -3,6 +3,18 @@
 // expose the same statement API — prepare().run/get/all(...params), exec() for
 // raw/multi-statement SQL, close() — and differ only in the constructor, so
 // callers get one `db` handle that behaves identically under either runtime.
+//
+// Both also load extensions, which is what sqlite-vec needs for a durable vector index:
+// node:sqlite via `allowExtension` at construction, bun:sqlite natively. The one place
+// that is not true is macOS under Bun, where the system libsqlite3 Bun links is built
+// without extension support — see useExtensionCapableSqlite below.
+//
+// better-sqlite3 is deliberately not used here. It would add a native dependency that
+// every consumer installs, including Workers deployments that can never call it, in
+// exchange for a feature set both built-ins already have — and it does not survive the
+// trade: constructing one under Bun 1.2.23 and 1.3.14 on macOS arm64 aborts the process
+// with `NAPI FATAL ERROR`, which is a panic rather than a throw and so cannot even be
+// caught and fallen back from.
 
 import { TroveError } from './errors.js';
 
@@ -22,9 +34,69 @@ export async function openDatabase(pathOrMemory = ':memory:') {
   return db;
 }
 
+// Held in a variable so a bundler cannot read it.
+//
+// `await import('bun:sqlite')` behind a `typeof Bun` guard still fails to BUILD for
+// Workers: esbuild resolves a literal specifier statically, and a guard is a runtime
+// thing that says nothing about what the bundler does with the module graph. The result
+// was a wrangler build that could not link, from an import that would never have run.
+// A non-literal specifier is not resolvable at build time, so it survives as a runtime
+// import — which the guard then never reaches.
+const BUN_SQLITE = 'bun:sqlite';
+
+// Where a SQLite that can load extensions tends to live on macOS. Ordered: an explicit
+// setting wins, then Homebrew on Apple Silicon, then Homebrew on Intel.
+const MACOS_SQLITE_CANDIDATES = [
+  '/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib',
+  '/usr/local/opt/sqlite/lib/libsqlite3.dylib',
+];
+
+let customSqliteTried = false;
+
+/**
+ * Point Bun at a SQLite that can load extensions, on the one platform where it cannot.
+ *
+ * `bun:sqlite` supports extensions natively — `loadExtension` is right there and works
+ * on Linux with nothing special. macOS is the exception, and not because of Bun: the
+ * SYSTEM libsqlite3 that Bun links by default is built without
+ * SQLITE_ENABLE_LOAD_EXTENSION, so the call comes back "This build of sqlite3 does not
+ * support dynamic extension loading". The effect is that sqlite-vec cannot load, and
+ * semantic search silently degrades to an in-memory index rebuilt on every restart —
+ * on developer laptops specifically, which is where it is least likely to be noticed.
+ *
+ * `setCustomSQLite` is Bun's documented answer. It has to happen before any database is
+ * opened, hence doing it here rather than at the point extensions are wanted.
+ *
+ * Best-effort throughout: if no capable library is installed we leave Bun on the system
+ * one and the sqlite-vec store degrades exactly as it did before, with its own warning.
+ * Set TROVE_SQLITE_LIB to override the search.
+ */
+async function useExtensionCapableSqlite(Database) {
+  if (customSqliteTried || process.platform !== 'darwin') return;
+  customSqliteTried = true;
+  if (typeof Database.setCustomSQLite !== 'function') return;
+
+  const configured = process.env.TROVE_SQLITE_LIB;
+  const { existsSync } = await import('node:fs');
+  const candidates = configured ? [configured] : MACOS_SQLITE_CANDIDATES;
+  for (const lib of candidates) {
+    if (!existsSync(lib)) continue;
+    try {
+      Database.setCustomSQLite(lib);
+      return;
+    } catch { /* keep looking; the default is still a working database */ }
+  }
+  // Only worth saying when it was asked for explicitly — otherwise this is the ordinary
+  // case of a machine without Homebrew sqlite, and the vector store says its own piece.
+  if (configured) {
+    console.warn(`[trove] TROVE_SQLITE_LIB=${configured} could not be used; falling back to the system SQLite`);
+  }
+}
+
 async function open(pathOrMemory) {
   if (typeof Bun !== 'undefined') {
-    const { Database } = await import('bun:sqlite');
+    const { Database } = await import(BUN_SQLITE);
+    await useExtensionCapableSqlite(Database);
     return new Database(pathOrMemory);
   }
   try {

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

@@ -149,12 +149,14 @@ export function createTaskHost(getServer) {
  * gets the truth without knowing where it lives.
  */
 export class RemoteTasks extends TaskRegistry {
+  /** @param {() => object} stub resolves the Durable Object stub — see remoteBackground
+   *  for why this is a function and not the stub itself. */
   constructor(stub) {
     super();
     this.stub = stub;
   }
   async #rpc(path, payload) {
-    const res = await this.stub.fetch(`https://trove.tasks${path}`, {
+    const res = await this.stub().fetch(`https://trove.tasks${path}`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(payload || {}),
@@ -181,8 +183,16 @@ 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
+  //
+  // Resolved per call, never held. A stub belongs to the I/O context of the request that
+  // created it, and the server that owns this one is cached at module scope for the life
+  // of the isolate — so the stub outlived its request and every later use threw. The
+  // first request worked and the second did not, which reads like a fluke and is not:
+  // GET /api/tasks was broken for the entire life of every isolate after its first
+  // request. `idFromName` is a pure hash, so re-deriving it costs nothing and always
+  // names the same object.
+  const stub = () => namespace.get(namespace.idFromName('trove-tasks'));
+  const begin = (payload) => stub()
     .fetch('https://trove.tasks/begin', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
@@ -195,7 +205,7 @@ export function remoteBackground(namespace) {
       beginScan: (collectionId, { reason } = {}) => begin({ kind: 'scan', collectionId, reason }),
       beginReindex: ({ reason } = {}) => begin({ kind: 'index', reason }),
     },
-    maintain: (budgetMs) => stub
+    maintain: (budgetMs) => stub()
       .fetch('https://trove.tasks/maintain', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },

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

@@ -53,7 +53,13 @@ async function getServer(env, buildVfs, { delegate = true } = {}) {
     config.metadata = { driver: 'sqlite' };
   }
   // Cloudflare Vectorize binding → first-class vector store (no REST creds needed).
-  if (env.VECTORIZE) {
+  //
+  // An explicit TROVE_VECTOR wins. The binding used to be taken unconditionally, which
+  // left no way to opt out: `wrangler dev` against a real Vectorize index is the only
+  // shape a local run could have, and setting TROVE_VECTOR=memory in .dev.vars did
+  // nothing. Naming a store and being given a different one is the kind of override that
+  // should never be silent.
+  if (env.VECTORIZE && (!env.TROVE_VECTOR || env.TROVE_VECTOR === 'vectorize')) {
     config.vectorStore = { driver: 'vectorize', binding: env.VECTORIZE };
   }
   // Cloudflare Workers AI binding → LLM-assisted search transformer (human text →

package/packages/server/src/engine/providers/core.js

@@ -32,7 +32,7 @@ import {
   cloudflareAccess,
   KeyValueStore, MemoryKV, SqliteKV,
   SqliteProvider, LocalSqliteProvider,
-  SidecarService, NotificationCenter, WebPushService,
+  SidecarService, NotificationCenter, WebPushService, WebPushChannel, NotificationChannel,
   CollectionService,
   PluginService, PackageStore, StoragePackageStore, SqlitePluginInstallStore,
   IndexerRuntime, InProcessIndexerRuntime, PluginIndexers,
@@ -285,17 +285,44 @@ export function coreProviders(config, lifecycleState) {
         })
         : null))),
 
-    notifications: Provider.fromLazySingleton(
+    // How notifications actually reach people. A list, because there is no reason for
+    // it to be one: a drive can push to browsers and mail a digest and post into a chat
+    // workspace, and none of those knows about the others. Web push is the default and
+    // only when VAPID is configured, so a drive that sets nothing gets an inbox and no
+    // delivery — which is what it got before.
+    //
+    // `config.notificationChannels` replaces the list wholesale rather than adding to
+    // it, so a caller who wants email INSTEAD of push says so by saying so.
+    notificationChannels: Provider.fromLazySingleton(
       async (deps) => {
         const { kv, push } = await need(deps, ['kv', 'push']);
-        const center = new NotificationCenter({ kv, push, flushIntervalMs: config.mentionFlushMs ?? 30_000 });
+        if (config.notificationChannels) {
+          return config.notificationChannels.filter(Boolean).map((c) => {
+            if (!(c instanceof NotificationChannel)) {
+              throw TroveError.invalid('Every notificationChannels entry must be a NotificationChannel');
+            }
+            return c;
+          });
+        }
+        return push ? [new WebPushChannel({ kv, service: push })] : [];
+      },
+      null,
+      { deps: ['kv', 'push'] },
+    ),
+
+    notifications: Provider.fromLazySingleton(
+      async (deps) => {
+        const { kv, notificationChannels } = await need(deps, ['kv', 'notificationChannels']);
+        const center = new NotificationCenter({
+          kv, channels: notificationChannels, flushIntervalMs: config.mentionFlushMs ?? 30_000,
+        });
         if (config.startFlusher !== false) center.start();
         return center;
       },
       // Stopping the flusher used to be a line in close() that had to remember this
       // existed. Now it is attached to the thing it stops.
       (center) => center.stop(),
-      { deps: ['kv', 'push'] },
+      { deps: ['kv', 'notificationChannels'] },
     ),
 
     sidecar: Provider.fromLazySingleton(

package/packages/server/src/index.js

@@ -16,7 +16,7 @@ import {
   accessHost, TroveError,
   protectedResourceMetadata, challengeHeaders, publicOrigin,
 } from '@3sln/trove/core';
-import { createRouter } from './routes.js';
+import { createRouter, routeHelpers } from './routes.js';
 import { createDriveEngine, scanStarter, BACKBONE } from './engine/index.js';
 import { createMcpHandler } from './mcp/index.js';
 import { cacheControlFor } from './cachePolicy.js';
@@ -210,6 +210,17 @@ export async function createServer(config = {}) {
 
   const router = createRouter();
 
+  // Routes contributed by delivery channels — the endpoints a client uses to REGISTER
+  // with one, of which a VAPID key and a push subscription are the obvious example.
+  // Mounted here rather than declared in routes.js so the drive's API reflects what is
+  // actually configured: no web push, no /api/push/*. Added after the core table, so a
+  // channel cannot shadow a built-in route by claiming its path.
+  for (const channel of notifications?.channels || []) {
+    for (const route of channel.routes?.(routeHelpers) || []) {
+      router.add(route.method, route.path, route.deps || [], route.handler);
+    }
+  }
+
   // Said at boot, because that is when someone is looking and can still fix it. The
   // alternative is discovering it from a client that can't sign in and a 401 that
   // doesn't say why.
@@ -341,9 +352,19 @@ export async function createServer(config = {}) {
    * does, so it does as much as it can and stores where it got to.
    */
   async function runMaintenance({ budgetMs = 20_000, scan = true } = {}) {
-    const out = { swept: false, purged: 0, scans: [] };
+    const out = { swept: false, purged: 0, scans: [], notified: 0 };
     await vfs.uploads.sweepExpired(Date.now());
     await sidecar.sweep();
+    // Mentions are batched and drained on an interval — a timer, and a timer registered
+    // during a request does not outlive it on Workers, where the adapter switches the
+    // flusher off for exactly that reason. Nothing else called flush, so on that runtime
+    // mentions piled up in the pending store and were never delivered at all: no inbox
+    // entry, no push, no error. Maintenance runs from a cron there, which is the one
+    // thing that does fire. Harmless where the timer works — concurrent drains collapse.
+    out.notified = await notifications.flush().catch((e) => {
+      console.error('[trove] mention flush failed', e);
+      return 0;
+    });
     const trashMs = (config.trashRetentionDays ?? 30) * 86400_000;
     if (trashMs > 0) out.purged = (await vfs.purgeTrash({ before: Date.now() - trashMs }))?.purged || 0;
     out.swept = true;

package/packages/server/src/routes.js

@@ -442,6 +442,14 @@ export function createRouter() {
 
   // --- search & indexing -----------------------------------------------------
 
+  // Raw search: the query string is passed through as text, with NO transformer.
+  //
+  // Which means the `#tag` grammar does not apply here. `/api/capabilities` advertises a
+  // searchPrompt telling people `#tag` narrows by tag, and against this endpoint that
+  // degrades into a text search for the literal string "#tag" — no error, just quietly
+  // different results. POST /api/query is the one that runs the transformer and is what
+  // the workbench uses; this stays as the lower-level endpoint for callers that have
+  // already resolved their own query.
   r.get('/api/search', ['collections', 'vfs'], async (ctx) => {
     const { vfs, query } = ctx;
     if (!query.q) throw TroveError.invalid('q is required');
@@ -748,20 +756,10 @@ export function createRouter() {
     return notifications.markRead(principal.id, b.ids);
   });
 
-  r.get('/api/push/vapid', ['notifications'], ({ notifications }) => ({ publicKey: notifications?.vapidPublicKey() || null }));
-
-  r.post('/api/push/subscribe', ['notifications'], async ({ notifications, principal, req }) => {
-    requireNotifications(notifications);
-    requirePrincipal(principal);
-    const b = await body(req);
-    return notifications.subscribePush(principal.id, b.subscription);
-  });
-  r.delete('/api/push/subscribe', ['notifications'], async ({ notifications, principal, req }) => {
-    requireNotifications(notifications);
-    requirePrincipal(principal);
-    const b = await body(req);
-    return notifications.unsubscribePush(principal.id, b.endpoint);
-  });
+  // /api/push/* is not here. Registering with a delivery channel is the channel's own
+  // business — see WebPushChannel.routes() — so the drive's route table does not carry
+  // endpoints for a transport it may not have configured, and adding email or chat does
+  // not mean editing this file.
 
   // --- plugins: domain verification proxy + per-plugin server storage --------
 
@@ -1064,3 +1062,12 @@ function requirePrincipal(principal) {
 function requireNotifications(n) {
   if (!n) throw TroveError.unsupported('Notifications are not enabled on this server');
 }
+
+/**
+ * The request plumbing handed to routes contributed from outside this file.
+ *
+ * `body` is the capped JSON read — the cap is the reason to share it rather than let a
+ * channel call `req.json()` and accept an unbounded body — and `requirePrincipal` is
+ * the same 401 every route here throws.
+ */
+export const routeHelpers = { body, requirePrincipal };