@3sln/trove 0.0.2

package/packages/core/src/sidecar/manager.js

@@ -0,0 +1,239 @@
+// SidecarManager — the "hot" side of the cold/hot split. It keeps recently-used
+// sidecar documents in memory, applies mutations against the live copy for
+// instant reads, and flushes to cold storage on a short debounce. Every flush
+// does a read-merge-write against the cold copy (the doc is a CRDT), so a
+// concurrent writer on another instance never clobbers this one's changes.
+// Idle documents are flushed and evicted to bound memory.
+
+import { mergeDoc } from './document.js';
+
+export class SidecarManager {
+  /**
+   * @param {object} deps
+   * @param {import('./store.js').SidecarStore} deps.store
+   * @param {number} [deps.flushDelayMs] debounce before writing back (default 1500)
+   * @param {number} [deps.idleEvictMs]  evict after this idle time (default 60s)
+   */
+  constructor({ store, flushDelayMs = 1500, idleEvictMs = 60_000, issues = null, maxFlushRetries = 5 }) {
+    this.store = store;
+    this.flushDelayMs = flushDelayMs;
+    this.idleEvictMs = idleEvictMs;
+    this.issues = issues;
+    this.maxFlushRetries = maxFlushRetries;
+    this.hot = new Map(); // nodeId -> { doc, dirty, timer, loading, lastAccess, retries }
+  }
+
+  async #entry(nodeId) {
+    let e = this.hot.get(nodeId);
+    if (e) {
+      if (e.loading) await e.loading;
+      e.lastAccess = now();
+      return e;
+    }
+    e = { doc: null, dirty: false, timer: null, lastAccess: now() };
+    this.hot.set(nodeId, e);
+    e.loading = (async () => {
+      e.doc = (await this.store.load(nodeId)) || this.store.emptyDoc(nodeId);
+    })();
+    try {
+      await e.loading;
+    } catch (err) {
+      // Drop the entry rather than leaving a permanently-rejecting `loading` in the map.
+      // A single transient read failure otherwise made that file's conversation and tags
+      // unreadable AND unwritable until the sweeper happened to evict it — indefinitely
+      // with maintenance off — every later call re-throwing the very same error.
+      this.hot.delete(nodeId);
+      throw err;
+    } finally {
+      e.loading = null;
+    }
+    return e;
+  }
+
+  /** Read the live document (loading it if cold). */
+  async get(nodeId) {
+    return (await this.#entry(nodeId)).doc;
+  }
+
+  /**
+   * Apply `fn(doc)` to the live document, mark dirty, and schedule a flush.
+   * @returns whatever `fn` returns (e.g. the affected comment).
+   */
+  async mutate(nodeId, fn) {
+    const e = await this.#entry(nodeId);
+    const result = await fn(e.doc);
+    e.dirty = true;
+    // Stamp the change. A flush that is already awaiting `store.save()` computed its
+    // merged document BEFORE this ran, so it must not adopt that result wholesale or
+    // mark the entry clean — see #flushOnce.
+    e.gen = (e.gen || 0) + 1;
+    this.#schedule(nodeId, e);
+    return result;
+  }
+
+  /**
+   * Debounce a write-back, and keep trying if it fails.
+   *
+   * Between `mutate` and a successful flush, memory holds the ONLY copy of what the
+   * user just wrote — the API has already replied 200 and their comment is on screen.
+   * A flush that fails and is merely logged means that copy is unreferenced by anything
+   * that will ever write it, so the retry here is not politeness, it is the difference
+   * between a durable comment and one that disappears when the process does.
+   */
+  #schedule(nodeId, e, delay = this.flushDelayMs) {
+    if (e.timer) return;
+    e.timer = setTimeout(() => {
+      e.timer = null;
+      this.flush(nodeId).then(() => {
+        if (e.retries) {
+          e.retries = 0;
+          this.issues?.clear?.('sidecar-flush', nodeId).catch(() => {});
+        }
+      }).catch((err) => {
+        e.retries = (e.retries || 0) + 1;
+        console.error(`sidecar flush failed for ${nodeId} (attempt ${e.retries})`, err);
+        if (e.retries <= this.maxFlushRetries) {
+          // Back off, but stay dirty and stay hot — sweep() will not evict it.
+          this.#schedule(nodeId, e, Math.min(this.flushDelayMs * 2 ** e.retries, 60_000));
+        } else {
+          // Out of retries. The comment is still in memory and still served, but it will
+          // not survive a restart, and the person who wrote it has been told it saved.
+          // That is a standing problem, which is exactly what the issue registry is for.
+          this.issues?.raise?.({
+            kind: 'sidecar-flush',
+            subject: nodeId,
+            severity: 'error',
+            title: 'A comment or tag could not be saved',
+            detail: `Changes to this item's conversation are held in memory only — ${err?.message || err}`,
+            // The op the server registers via issues.handle('sidecar-flush', …), which
+            // is what makes the Retry button appear and do the right thing.
+            retry: 'sidecar-flush',
+          }).catch(() => {});
+        }
+      });
+    }, delay);
+    if (e.timer.unref) e.timer.unref();
+  }
+
+  /** Retry every document that is still holding unsaved changes. */
+  async retryPending() {
+    const pending = [...this.hot.entries()].filter(([, e]) => e.dirty);
+    for (const [id, e] of pending) {
+      e.retries = 0;
+      // This IS the write the pending timer was going to do; leaving it armed would
+      // keep sweep() from ever evicting the entry.
+      if (e.timer) { clearTimeout(e.timer); e.timer = null; }
+      await this.flush(id);
+      this.issues?.clear?.('sidecar-flush', id).catch(() => {});
+    }
+    return { flushed: pending.length };
+  }
+
+  /**
+   * Write the live doc back, merging with the cold copy first.
+   *
+   * Serialized per document. Two flushes of the same sidecar overlapping is how one of
+   * them computes a merge from a document the other is about to replace — and the
+   * replacement wins, silently, after the API has already replied 200.
+   */
+  flush(nodeId) {
+    const e = this.hot.get(nodeId);
+    if (!e || !e.doc) return Promise.resolve();
+    const run = () => this.#flushOnce(nodeId, e);
+    const next = (e.chain || Promise.resolve()).then(run, run);
+    // The chain itself must never stay rejected, or one failure poisons every later
+    // flush of this document. Callers still see their own rejection through `next`.
+    e.chain = next.catch(() => {});
+    return next;
+  }
+
+  async #flushOnce(nodeId, e) {
+    if (e.loading) await e.loading;
+    if (!e.dirty || !e.doc) return;
+    // The generation this write covers. `store.load` and `store.save` are object-store
+    // round trips — hundreds of milliseconds — and `mutate` applies its change in place
+    // on `e.doc` throughout. So a comment accepted during the save lands in `e.doc`,
+    // is NOT in `merged` (computed before it), and used to be erased by `e.doc = merged`
+    // and then guaranteed never to be retried by `e.dirty = false`.
+    const gen = e.gen || 0;
+    const cold = await this.store.load(nodeId);
+    const merged = cold ? mergeDoc(cold, e.doc) : e.doc;
+    await this.store.save(nodeId, merged);
+    if ((e.gen || 0) !== gen) {
+      // Something arrived while we were saving. Fold what we just persisted back INTO
+      // the live document rather than over it, and leave the entry dirty so the next
+      // flush carries the newcomer.
+      e.doc = merged === e.doc ? e.doc : mergeDoc(merged, e.doc);
+      return;
+    }
+    e.doc = merged;
+    e.dirty = false;
+  }
+
+  /** @returns {Promise<{flushed: number, failed: Array<{nodeId, error}>}>} */
+  async flushAll() {
+    const failed = [];
+    let flushed = 0;
+    await Promise.all([...this.hot.keys()].map((id) => this.flush(id)
+      .then(() => { flushed++; })
+      .catch((error) => failed.push({ nodeId: id, error }))));
+    return { flushed, failed };
+  }
+
+  /**
+   * Flush + drop documents idle longer than idleEvictMs.
+   *
+   * A document is evicted only once it is CLEAN. Dropping a dirty one discards the only
+   * copy of a change the user was told had saved — and the failure that made it dirty is
+   * exactly the moment that would happen, so "flush, then delete regardless" turns a
+   * transient storage blip into silent data loss a minute later.
+   */
+  async sweep() {
+    const cutoff = now() - this.idleEvictMs;
+    for (const [id, e] of this.hot) {
+      if (e.lastAccess >= cutoff || e.timer) continue;
+      if (e.dirty) {
+        try {
+          await this.flush(id);
+          // Flushing can succeed and leave the entry DIRTY: the generation guard in
+          // #flushOnce returns cleanly when a mutation landed mid-save, precisely so
+          // the newcomer gets carried by the next write. Evicting on "didn't throw"
+          // discards it — the one thing this method exists not to do.
+          if (e.dirty) { this.#schedule(id, e); continue; }
+        } catch {
+          // Still unsaved: keep it in memory and let the retry schedule own it. Memory
+          // growth is bounded by the store being broken, which is a loud condition.
+          this.#schedule(id, e);
+          continue;
+        }
+      }
+      this.hot.delete(id);
+    }
+  }
+
+  /**
+   * Flush everything and let go.
+   *
+   * Returns what could not be written rather than swallowing it: the caller is a
+   * shutdown path, and exiting 0 after dropping someone's comments is a lie the process
+   * tells on its way out.
+   */
+  async dispose() {
+    for (const e of this.hot.values()) if (e.timer) { clearTimeout(e.timer); e.timer = null; }
+    const result = await this.flushAll();
+    if (result.failed.length) {
+      console.error(`[trove] ${result.failed.length} sidecar document(s) could not be saved on shutdown:`,
+        result.failed.map((f) => `${f.nodeId}: ${f.error?.message || f.error}`).join('; '));
+    }
+    this.hot.clear();
+    return result;
+  }
+}
+
+function now() {
+  try {
+    return Date.now();
+  } catch {
+    return 0;
+  }
+}

package/packages/core/src/sidecar/store.js

@@ -0,0 +1,46 @@
+// SidecarStore — cold persistence for sidecar documents. Each file's sidecar is
+// a single JSON object stored in the SAME pluggable storage backend as the file
+// bytes (S3/filesystem/memory), under a reserved `sidecars/` key space. This
+// keeps social/metadata state next to the data, with zero extra infrastructure,
+// and lets an S3 deployment need no database at all for conversations.
+
+import { emptyDoc } from './document.js';
+import { wrapError } from '../errors.js';
+import { readAll } from '../util.js';
+
+function keyFor(nodeId) {
+  return `sidecars/${nodeId}.json`;
+}
+
+export class SidecarStore {
+  /** @param {{storage: import('../storage/interface.js').StorageBackend}} deps */
+  constructor({ storage }) {
+    this.storage = storage;
+  }
+
+  /** @returns {Promise<object|null>} the raw CRDT doc, or null if none yet. */
+  async load(nodeId) {
+    try {
+      const { stream } = await this.storage.get(keyFor(nodeId));
+      const bytes = await readAll(stream);
+      return JSON.parse(new TextDecoder().decode(bytes));
+    } catch (err) {
+      const e = wrapError(err);
+      if (e.code === 'not_found') return null;
+      throw e;
+    }
+  }
+
+  async save(nodeId, doc) {
+    const bytes = new TextEncoder().encode(JSON.stringify(doc));
+    await this.storage.put(keyFor(nodeId), bytes, { contentType: 'application/json' });
+  }
+
+  async remove(nodeId) {
+    await this.storage.delete(keyFor(nodeId)).catch(() => {});
+  }
+
+  emptyDoc(nodeId) {
+    return emptyDoc(nodeId);
+  }
+}

package/packages/core/src/signedUrls.js

@@ -0,0 +1,170 @@
+// A URL that carries its own authorization.
+//
+// Some things cannot send an `Authorization` header and still need one object's bytes:
+// an `<img src>`, a `<video src>`, `cache.add()` behind a service worker, an external
+// API an indexer wants to hand a file to. For those the grant travels IN the URL.
+//
+// Two implementations, one contract — see docs/design/signed-urls.md:
+//
+//   - the backend can presign (S3/R2)  → the storage URL, bytes never touch the server
+//   - it cannot (filesystem, NAS, …)   → ours: ?id=…&op=…&exp=…&sig=<hmac>
+//
+// Both are stateless with the expiry baked in: nothing stored, nothing to revoke,
+// nothing to clean up. They stop verifying at `exp` and that is the whole lifecycle.
+//
+// The signature is a GRANT, not a hint. A request carrying a valid one is served without
+// a principal, because the signature was minted by someone who held `read` on that node
+// at the time. Which is why it covers the id and the op: a valid signature for a file you
+// may see must not be editable into one for a file you may not.
+
+import { TroveError } from './errors.js';
+
+const MINUTES = 60;
+const HOURS = 60 * MINUTES;
+
+/**
+ * What a signed URL may be for, and how long each may live.
+ *
+ * Content URLs are LONG on purpose — longer than it takes to consume almost anything.
+ * The failure they prevent is a film that stops forty minutes in, or a download that
+ * dies at 90% and cannot resume, and those are much worse than the exposure of a URL
+ * that stays fetchable for a day.
+ *
+ * `index` is the exception and stays short: that one is handed to an external service
+ * and leaves our control entirely, so it should be good for one prompt fetch and then
+ * nothing.
+ */
+export const URL_PURPOSES = {
+  index: { maxAge: 15 * MINUTES, defaultAge: 5 * MINUTES },
+  // A browser download that stalls and resumes must not find its URL dead. Validated
+  // when the transfer STARTS, so an in-flight 4 GB transfer finishes regardless.
+  download: { maxAge: 12 * HOURS, defaultAge: 2 * HOURS },
+  // A <video> re-requests on every seek, so this outlives the SITTING, not the request:
+  // a long film, an audiobook session, an evening of episodes.
+  media: { maxAge: 24 * HOURS, defaultAge: 12 * HOURS },
+};
+
+const enc = new TextEncoder();
+
+/** base64url, because this ends up in a query string. */
+function b64url(bytes) {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Signs and verifies one-object grants.
+ *
+ * The secret is the server's, never a user's — this is the deployment vouching for a
+ * decision it already made, not an identity claim.
+ */
+export class SignedUrls {
+  /**
+   * @param {object} opts
+   * @param {string} opts.secret signing secret (see the `urlSecret` provider — configured,
+   *   or generated once and kept in the KV store so it survives restarts and is shared
+   *   between instances)
+   * @param {() => number} [opts.now] injected clock, for tests
+   */
+  constructor({ secret, now = () => Date.now() } = {}) {
+    if (!secret || typeof secret !== 'string') {
+      throw TroveError.invalid('SignedUrls requires a signing secret');
+    }
+    this._secret = secret;
+    this._key = null;
+    this.now = now;
+  }
+
+  async #hmacKey() {
+    if (!this._key) {
+      this._key = await crypto.subtle.importKey(
+        'raw', enc.encode(this._secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
+      );
+    }
+    return this._key;
+  }
+
+  /**
+   * The signature over one grant.
+   *
+   * Length-prefixed rather than joined on a separator: `('a|b', 'c')` and `('a', 'b|c')`
+   * join to the same string, so a separator alone lets one field's value be pushed into
+   * the next. Nobody has ever been bitten by that here, and nobody will be.
+   */
+  async sign({ id, op, exp }) {
+    const parts = [String(id), String(op), String(exp)];
+    const payload = parts.map((p) => `${p.length}:${p}`).join('');
+    const sig = await crypto.subtle.sign('HMAC', await this.#hmacKey(), enc.encode(payload));
+    return b64url(new Uint8Array(sig));
+  }
+
+  /** The query parameters that make a grant, for `op` on `id`, good for `expiresIn` seconds. */
+  async grant(id, { op = 'download', expiresIn } = {}) {
+    const purpose = URL_PURPOSES[op];
+    if (!purpose) throw TroveError.invalid(`Unknown signed-URL purpose "${op}"`);
+    // Capped server-side: `expiresIn` reaches here from a client and a URL good for a
+    // year is the one thing this design cannot take back.
+    const age = Math.min(Math.max(1, expiresIn || purpose.defaultAge), purpose.maxAge);
+    const exp = Math.floor(this.now() / 1000) + age;
+    return { id, op, exp, sig: await this.sign({ id, op, exp }), expiresAt: exp * 1000 };
+  }
+
+  /**
+   * Whether these parameters are a grant we issued and that is still good.
+   *
+   * Returns a reason rather than a bare false: "expired" and "not ours" are different
+   * events — the first is ordinary and the client should re-mint, the second is someone
+   * editing URLs and is worth being able to see in a log.
+   */
+  async check({ id, op, exp, sig }) {
+    if (!id || !op || !exp || !sig) return { ok: false, reason: 'incomplete' };
+    if (!URL_PURPOSES[op]) return { ok: false, reason: 'unknown-purpose' };
+    const at = Number(exp);
+    if (!Number.isFinite(at)) return { ok: false, reason: 'malformed' };
+    // Expiry BEFORE the signature check: an expired grant is not a security event, and
+    // it is the overwhelmingly common failure. Cheap first.
+    if (at * 1000 <= this.now()) return { ok: false, reason: 'expired' };
+    const expected = await this.sign({ id, op, exp: at });
+    return timingSafeEqual(expected, String(sig))
+      ? { ok: true, id: String(id), op: String(op), expiresAt: at * 1000 }
+      : { ok: false, reason: 'bad-signature' };
+  }
+}
+
+/**
+ * Constant-time string compare.
+ *
+ * `a === b` on a signature leaks where the first differing byte is, which over enough
+ * requests is a forgery oracle. The cost of not caring is small and the cost of caring is
+ * nothing.
+ */
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+/**
+ * A secret that survives a restart and is shared between instances.
+ *
+ * Configured is best. Failing that, one is generated and kept in the KV store — which is
+ * what makes the fallback safe rather than convenient: a per-process random secret would
+ * work perfectly on one machine and invalidate half the URLs in flight the moment a
+ * second instance answered a request.
+ */
+const SECRET_NS = 'server';
+const SECRET_KEY = 'urlSecret';
+
+export async function resolveUrlSecret({ configured, kv } = {}) {
+  if (configured) return configured;
+  if (!kv) throw TroveError.invalid('Signed URLs need either a configured secret or a KV store to keep one in');
+  const existing = await kv.get(SECRET_NS, SECRET_KEY);
+  if (existing) return existing;
+  const generated = b64url(crypto.getRandomValues(new Uint8Array(32)));
+  await kv.set(SECRET_NS, SECRET_KEY, generated);
+  // Re-read rather than trust the write: a racing instance may have got there first, and
+  // two instances signing with different secrets reject each other's URLs.
+  return (await kv.get(SECRET_NS, SECRET_KEY)) || generated;
+}

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

@@ -0,0 +1,162 @@
+// SQLite on Cloudflare D1.
+//
+// The Workers deployment was the one with a hole in it: storage had R2, vectors had
+// Vectorize, and metadata said "implement the MetadataStore interface over env.DB" —
+// which is a way of saying it didn't work. The provider interface is six methods, and
+// D1 speaks almost exactly the same dialect, so this closes it.
+//
+// Two things about D1 shape the design, and neither is a detail an operator should have
+// to discover from a stack trace:
+//
+//   1. **A binding is one database.** LocalSqliteProvider hands out sibling FILES for
+//      plugin scopes, which is what keeps one plugin's SQL out of another's. There is no
+//      "create me another database" call on D1, so a scope with no binding of its own is
+//      refused rather than quietly co-located — plugin isolation is a security boundary,
+//      and silently collapsing it is the wrong way to save an operator a config line.
+//   2. **No sqlite-vec.** The vector half of search cannot live here. Use Vectorize (the
+//      worker adapter wires it from the binding); the keyword half is fine, since D1
+//      compiles in FTS5.
+
+import { TroveError } from './errors.js';
+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']);
+
+/** 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
+  // string literals or triggers. Deliberately not a SQL parser: if that assumption ever
+  // stops holding, the failure is a loud syntax error from D1 rather than a silent
+  // half-applied migration.
+  return String(sql)
+    .split(';')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+class D1Database extends SqliteDatabase {
+  /** @param {{prepare: Function, batch: Function, exec?: Function}} d1 a D1 binding */
+  constructor(d1) {
+    super();
+    this.d1 = d1;
+  }
+
+  #stmt(sql, params) {
+    const s = this.d1.prepare(sql);
+    return params && params.length ? s.bind(...params) : s;
+  }
+
+  async exec(sql) {
+    // 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);
+    if (!statements.length) return;
+    if (statements.length === 1) {
+      await this.d1.prepare(statements[0]).run();
+      return;
+    }
+    await this.d1.batch(statements.map((s) => this.d1.prepare(s)));
+  }
+
+  async run(sql, ...params) {
+    const res = await this.#stmt(sql, params).run();
+    // Shaped like better-sqlite3's return so callers can't tell the difference. `meta`
+    // is D1's; the field names differ by version, hence the fallbacks.
+    return {
+      changes: res?.meta?.changes ?? res?.meta?.rows_written ?? 0,
+      lastInsertRowid: res?.meta?.last_row_id ?? null,
+    };
+  }
+
+  async get(sql, ...params) {
+    return (await this.#stmt(sql, params).first()) ?? null;
+  }
+
+  async all(sql, ...params) {
+    const res = await this.#stmt(sql, params).all();
+    return res?.results || [];
+  }
+
+  async batch(statements) {
+    if (!statements?.length) return;
+    // D1 batches are atomic — one implicit transaction, rolled back as a unit. That is
+    // exactly the guarantee LocalSqliteDatabase gets from BEGIN/COMMIT, so callers keep
+    // the same promise on both.
+    await this.d1.batch(statements.map(({ sql, params = [] }) =>
+      (params.length ? this.d1.prepare(sql).bind(...params) : this.d1.prepare(sql))));
+  }
+
+  async close() { /* D1 bindings are managed by the runtime */ }
+}
+
+export class D1SqliteProvider extends SqliteProvider {
+  /**
+   * @param {object} opts
+   * @param {object} opts.db      the main D1 binding (metadata, kv, plugin installs)
+   * @param {Record<string, object>} [opts.scopes]
+   *   extra bindings by key, for scopes that need their own database.
+   * @param {object} [opts.pluginStore]
+   *   one binding to hold EVERY plugin scope. A scope key embeds the runtime principal,
+   *   so it cannot be pre-bound and D1 cannot create databases on demand — without this,
+   *   plugin storage simply doesn't exist on Workers.
+   */
+  constructor({ db, scopes = {}, pluginStore = null } = {}) {
+    super();
+    if (!db) throw TroveError.invalid('D1SqliteProvider requires a D1 binding (env.DB)');
+    this.main = new D1Database(db);
+    this.scopes = new Map(Object.entries(scopes).map(([k, v]) => [k, new D1Database(v)]));
+    // The catch-all for plugin scopes (see obtain).
+    this.pluginStore = pluginStore ? new D1Database(pluginStore) : null;
+  }
+
+  // D1 is a real database that survives the isolate being torn down — which is the
+  // whole question this flag answers, and the reason the search index may live here.
+  get durable() { return true; }
+
+  async obtain({ key }) {
+    if (CORE_KEYS.has(key)) return this.main;
+    const scoped = this.scopes.get(key);
+    if (scoped) return scoped;
+    // One binding for every plugin store.
+    //
+    // A plugin scope key embeds the runtime principal — `pstore:alice@x.com:plg:acme/notes`
+    // — so it can never be pre-bound, and D1 cannot create a database on demand. The
+    // adapter's `scopes: { plugins: … }` therefore bound a name that (a) is a CORE key
+    // already, so it short-circuited to `main`, and (b) is not what any real store asks
+    // for: every /api/plugins/:id/sql call on Workers was a 501.
+    //
+    // So a deployment may nominate ONE database to hold them all. Weaker isolation than
+    // the local provider's file-per-scope — the tables live side by side — but the keys
+    // are still distinct per (user, plugin) and it is the strongest thing D1's model
+    // allows. Stated here rather than discovered.
+    if (this.pluginStore) return this.pluginStore;
+    // Plugin scopes are an isolation boundary. Handing back the main database would
+    // put a plugin's tables next to the drive's metadata, which is precisely what the
+    // scope exists to prevent.
+    throw TroveError.unsupported(
+      `No D1 binding for the "${key}" store. D1 cannot create databases on demand, so a `
+      + 'plugin scope needs its own binding — add one to the Worker and pass it as '
+      + `scopes: { "${key}": env.YOUR_BINDING }. Plugin data is not co-located with the `
+      + 'drive metadata by design.',
+    );
+  }
+
+  async drop({ key }) {
+    // Dropping a D1 database is an account-level operation, not something a request can
+    // do. Emptying it is the closest honest equivalent, and it is what uninstall means:
+    // the plugin's data is gone.
+    const db = CORE_KEYS.has(key) ? null : this.scopes.get(key);
+    if (!db) return;
+    const tables = await db.all(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_cf_%'",
+    );
+    if (!tables.length) return;
+    await db.batch(tables.map((t) => ({ sql: `DROP TABLE IF EXISTS "${String(t.name).replace(/"/g, '""')}"` })));
+  }
+
+  async close() { /* nothing to release */ }
+}
+
+export { D1Database, splitStatements };

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

@@ -0,0 +1,42 @@
+// Open a SQLite database using whichever driver the runtime provides: Bun's
+// built-in `bun:sqlite` or Node's built-in `node:sqlite` (Node ≥ 22.5). Both
+// 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.
+
+import { TroveError } from './errors.js';
+
+export async function openDatabase(pathOrMemory = ':memory:') {
+  const db = await open(pathOrMemory);
+  // Durability/concurrency defaults for file-backed dbs: WAL survives an ungraceful
+  // stop far better than the rollback journal, and a busy_timeout avoids spurious
+  // "database is locked" under concurrent readers/writers. (No-op for :memory:.)
+  if (pathOrMemory !== ':memory:') {
+    try {
+      db.exec('PRAGMA journal_mode = WAL');
+      db.exec('PRAGMA synchronous = NORMAL');
+      db.exec('PRAGMA busy_timeout = 5000');
+      db.exec('PRAGMA foreign_keys = ON');
+    } catch { /* pragmas are best-effort */ }
+  }
+  return db;
+}
+
+async function open(pathOrMemory) {
+  if (typeof Bun !== 'undefined') {
+    const { Database } = await import('bun:sqlite');
+    return new Database(pathOrMemory);
+  }
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    // `allowExtension` has to be set at CONSTRUCTION — enableLoadExtension() alone
+    // isn't enough on node:sqlite. It only permits loading; nothing is loaded unless
+    // something asks (the sqlite-vec store does, and degrades if it can't).
+    return new DatabaseSync(pathOrMemory, { allowExtension: true });
+  } catch (err) {
+    throw TroveError.unsupported(
+      'No SQLite driver available — run under Bun (bun:sqlite) or Node ≥ 22.5 (node:sqlite), or supply another store',
+      { cause: err },
+    );
+  }
+}