ugly-app 0.1.821 → 0.1.823

package/src/inspect/agent/perfAgent.ts

@@ -37,6 +37,10 @@ const PROFILE_COOLDOWN_MS = 30_000;
 // racing `visibilitychange`), not event-loop lag. Comfortably above the largest block
 // we still want to report as a spike.
 const SUSPEND_GAP_MS = 10_000;
+// Delay before the one-shot `page-load` snapshot. Long enough for LCP/FCP to settle
+// and the page to become interactive; well inside the "if it's slower than this it
+// doesn't matter" horizon. Startup data lands without needing tab-close or app-quit.
+const STARTUP_SNAPSHOT_DELAY_MS = 8_000;
 
 /**
  * A hidden page's timers are throttled by the browser — Chromium clamps them to 1s
@@ -245,6 +249,7 @@ export class PerfAgent {
   private snapshots: PerfSnapshot[] = [];
   private profiling = false;
   private lastProfileAt = 0;
+  private startupCaptured = false;
   private lcpMs: number | undefined;
   private fcpMs: number | undefined;
   private _startup: {
@@ -294,12 +299,6 @@ export class PerfAgent {
           for (const e of list.getEntries()) {
             this.longTasks.add(Date.now(), e.duration);
           }
-          // Track LCP
-          for (const e of list.getEntries()) {
-            if ((e as PerformanceEntry & { entryType?: string }).entryType === 'largest-contentful-paint') {
-              this.lcpMs = e.startTime;
-            }
-          }
           if (this.longTaskAnomalyDue(vitals)) {
             void this.captureAnomaly('long-task');
           }
@@ -308,6 +307,21 @@ export class PerfAgent {
       }
     } catch { /* unsupported */ }
 
+    // LCP capture — MUST be its own observer. This previously looked for
+    // 'largest-contentful-paint' entries inside the longtask observer above, which
+    // only ever receives longtask entries, so lcpMs was always null. LCP fires
+    // repeatedly (each larger paint), so we keep the latest startTime.
+    try {
+      if (typeof PerformanceObserver !== 'undefined') {
+        const lcpObs = new PerformanceObserver((list) => {
+          const entries = list.getEntries();
+          const last = entries[entries.length - 1];
+          if (last) this.lcpMs = last.startTime;
+        });
+        lcpObs.observe({ type: 'largest-contentful-paint', buffered: true });
+      }
+    } catch { /* unsupported (e.g. Safari) */ }
+
     // FCP capture via paint observer
     try {
       if (typeof PerformanceObserver !== 'undefined') {
@@ -333,6 +347,53 @@ export class PerfAgent {
 
     // Track startup milestones
     this._startup.milestones.push({ label: 'agent:install', deltaMs: Math.round(this.now() - this._startup.t0) });
+
+    // One-shot startup snapshot so initial-load data (startup timings + LCP/FCP)
+    // lands reliably a few seconds after load — not only on anomaly or unload.
+    try {
+      const t = setTimeout(() => this.captureStartupSnapshot(), STARTUP_SNAPSHOT_DELAY_MS);
+      if (t && typeof (t as { unref?: () => void }).unref === 'function') (t as { unref: () => void }).unref();
+    } catch { /* no timers (test) */ }
+  }
+
+  /**
+   * Fire once, ~STARTUP_SNAPSHOT_DELAY_MS after load: a `page-load` snapshot carrying
+   * the startup milestone breakdown + LCP/FCP. Bypasses the hidden-tab gate — startup
+   * timing is a one-time load metric, not ongoing pressure — but LCP/FCP may be null
+   * if the tab never painted (preloaded in the background).
+   */
+  private captureStartupSnapshot(): void {
+    if (this.startupCaptured) return;
+    this.startupCaptured = true;
+    const heap = heapMb();
+    const vitals = this.vitalsReader();
+    const totalMs = this._startup.milestones.length > 0
+      ? this._startup.milestones[this._startup.milestones.length - 1]!.deltaMs
+      : 0;
+    const snapshot: PerfSnapshot = {
+      trigger: 'page-load',
+      cpuPressure: this.heartbeat.pressure,
+      eventLoopLagMs: Math.round(this.heartbeat.avgLagMs),
+      heapUsedMb: Math.round(heap.used * 10) / 10,
+      heapTotalMb: Math.round(heap.total * 10) / 10,
+      longTaskCount: this.longTasks.count,
+      domNodeCount: domCount(),
+      ...(this.lcpMs != null ? { lcpMs: this.lcpMs } : {}),
+      ...(this.fcpMs != null ? { fcpMs: this.fcpMs } : {}),
+      ...(vitals.cls != null ? { cls: vitals.cls } : {}),
+      callTree: null,
+      startup: {
+        milestones: this._startup.milestones.slice(),
+        totalMs,
+        longTaskCount: this._startup.longTasks,
+      },
+    };
+    if (this.snapshots.length >= MAX_PENDING_ANOMALIES) {
+      this.snapshots.shift();
+      this.pendingAnomalies.shift();
+    }
+    this.pendingAnomalies.push('page-load');
+    this.snapshots.push(snapshot);
   }
 
   /**

package/src/inspect/protocol.ts

@@ -228,7 +228,9 @@ export interface WebVitals {
  *  rAF, and PerformanceObserver. On anomaly or page unload it captures a
  *  snapshot that the host can poll and forward to D1 for root-cause analysis. */
 export interface PerfSnapshot {
-  trigger: 'cpu-pressure' | 'dropped-frames' | 'long-task' | 'page-unload';
+  /** `page-load` fires once, a few seconds after load, carrying startup timings +
+   *  LCP/FCP — so initial-load data lands without waiting for anomaly or unload. */
+  trigger: 'cpu-pressure' | 'dropped-frames' | 'long-task' | 'page-unload' | 'page-load';
   /** 0..1 — fraction of recent heartbeat ticks classified as delayed. */
   cpuPressure: number;
   /** Average event-loop lag in ms over the recent window. */

package/src/server/App.ts

@@ -948,7 +948,7 @@ export function createApp<
     perfSnapshotCaptureNoAuth: (
       _userId: string | null,
       input: {
-        trigger: "cpu-pressure" | "dropped-frames" | "long-task" | "page-unload" | "self-snapshot" | "app-quit";
+        trigger: "cpu-pressure" | "dropped-frames" | "long-task" | "page-unload" | "page-load" | "self-snapshot" | "app-quit";
         source?: string;
         cpuPressure?: number;
         eventLoopLagMs?: number;

package/src/server/Logging.ts

@@ -364,7 +364,7 @@ export interface PerfSnapshotInput {
   sessionId?: string | null;
   /** Origin of the snapshot: "app:<id>", "tab:<id>", or "electron-main". */
   source?: string | null;
-  trigger: "cpu-pressure" | "dropped-frames" | "long-task" | "page-unload" | "self-snapshot" | "app-quit";
+  trigger: "cpu-pressure" | "dropped-frames" | "long-task" | "page-unload" | "page-load" | "self-snapshot" | "app-quit";
   cpuPressure?: number | null;
   eventLoopLagMs?: number | null;
   heapUsedMb?: number | null;

package/src/server/adapter/workers/createWorkersApp.ts

@@ -1918,7 +1918,7 @@ export function createWorkersApp<R extends AppRegistryBase>(
     },
     perfSnapshotCaptureNoAuth: async (userId, rawInput) => {
       const input = (rawInput ?? {}) as {
-        trigger: 'cpu-pressure' | 'dropped-frames' | 'long-task' | 'page-unload' | 'self-snapshot' | 'app-quit';
+        trigger: 'cpu-pressure' | 'dropped-frames' | 'long-task' | 'page-unload' | 'page-load' | 'self-snapshot' | 'app-quit';
         source?: string;
         cpuPressure?: number;
         eventLoopLagMs?: number;

package/src/server/sqlite/SqliteDoc.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { makeBetterSqliteExec, type SqliteExec } from './SqliteExec.js';
+import {
+  ensureSqliteTable,
+  sqliteInsertRaw,
+  sqliteGetDoc,
+  sqliteGetDocs,
+  sqliteFindCount,
+  sqliteSetDoc,
+  sqliteSetDocFields,
+  sqliteSetDocOp,
+  sqliteSetDocFieldsOrIgnore,
+  sqliteDeleteDoc,
+  sqliteDeleteDocs,
+  sqliteGetQuery,
+  sqliteGetQueryCount,
+} from './SqliteDoc.js';
+
+let exec: SqliteExec;
+
+beforeAll(async () => {
+  exec = await makeBetterSqliteExec(); // in-memory
+  await ensureSqliteTable(exec, 'post');
+  await sqliteInsertRaw(exec, 'post', { _id: 'a', title: 'hello', n: 10 });
+  await sqliteInsertRaw(exec, 'post', { _id: 'b', title: 'world', n: 9 });
+  await sqliteInsertRaw(exec, 'post', { _id: 'c', title: '' });
+});
+
+describe('SqliteDoc read path', () => {
+  it('getDoc returns a hydrated doc with Date meta', async () => {
+    const doc = await sqliteGetDoc<{ _id: string; title: string; created: Date }>(
+      exec,
+      'post',
+      'a',
+    );
+    expect(doc?._id).toBe('a');
+    expect(doc?.title).toBe('hello');
+    expect(doc?.created).toBeInstanceOf(Date);
+  });
+
+  it('getDoc returns null for a missing id', async () => {
+    expect(await sqliteGetDoc(exec, 'post', 'zzz')).toBeNull();
+  });
+
+  it('getDocs filters by empty-string field (distinct from missing)', async () => {
+    const rows = await sqliteGetDocs<{ _id: string }>(exec, 'post', { title: '' });
+    expect(rows.map((r) => r._id)).toEqual(['c']);
+  });
+
+  it('getDocs sorts ascending with nulls last', async () => {
+    const rows = await sqliteGetDocs<{ _id: string }>(exec, 'post', {}, {
+      sort: { n: 1 },
+    });
+    // 'c' has no n (NULL) → last; '10' < '9' lexically (matches PG) → a before b.
+    expect(rows.map((r) => r._id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('findCount counts matches', async () => {
+    expect(await sqliteFindCount(exec, 'post', { title: { $exists: true } })).toBe(3);
+  });
+});
+
+describe('SqliteDoc write path', () => {
+  it('setDoc inserts then replaces by _id', async () => {
+    await ensureSqliteTable(exec, 'w');
+    expect(await sqliteSetDoc(exec, 'w', { _id: 'x', v: 1 })).toBe(true);
+    await sqliteSetDoc(exec, 'w', { _id: 'x', v: 2 });
+    const doc = await sqliteGetDoc<{ v: number }>(exec, 'w', 'x');
+    expect(doc?.v).toBe(2);
+  });
+
+  it('setDoc skipIfExists returns false and keeps the original', async () => {
+    await ensureSqliteTable(exec, 'w2');
+    await sqliteSetDoc(exec, 'w2', { _id: 'y', v: 1 });
+    expect(
+      await sqliteSetDoc(exec, 'w2', { _id: 'y', v: 9 }, { skipIfExists: true }),
+    ).toBe(false);
+    expect((await sqliteGetDoc<{ v: number }>(exec, 'w2', 'y'))?.v).toBe(1);
+  });
+
+  it('setDocFields updates and bumps version', async () => {
+    await ensureSqliteTable(exec, 'w3');
+    await sqliteSetDoc(exec, 'w3', { _id: 'z', a: 1, version: 1 });
+    const updated = await sqliteSetDocFields<{ a: number; b: number; version: number }>(
+      exec,
+      'w3',
+      'z',
+      { b: 2 },
+    );
+    expect(updated).toMatchObject({ a: 1, b: 2 });
+    expect(updated.version).toBe(2);
+  });
+
+  it('setDocFields throws when the doc is missing', async () => {
+    await ensureSqliteTable(exec, 'w4');
+    await expect(sqliteSetDocFields(exec, 'w4', 'nope', { a: 1 })).rejects.toThrow();
+  });
+
+  it('setDocFieldsOrIgnore returns null when missing', async () => {
+    await ensureSqliteTable(exec, 'w5');
+    expect(await sqliteSetDocFieldsOrIgnore(exec, 'w5', 'nope', { a: 1 })).toBeNull();
+  });
+
+  it('setDocOp $inc increments', async () => {
+    await ensureSqliteTable(exec, 'w6');
+    await sqliteSetDoc(exec, 'w6', { _id: 'c', n: 5 });
+    const r = await sqliteSetDocOp<{ n: number }>(exec, 'w6', 'c', { $inc: { n: 3 } });
+    expect(r.n).toBe(8);
+  });
+
+  it('deleteDoc removes a row; deleteDocs returns matched ids', async () => {
+    await ensureSqliteTable(exec, 'w7');
+    await sqliteSetDoc(exec, 'w7', { _id: 'd1', kind: 'a' });
+    await sqliteSetDoc(exec, 'w7', { _id: 'd2', kind: 'a' });
+    await sqliteSetDoc(exec, 'w7', { _id: 'd3', kind: 'b' });
+    await sqliteDeleteDoc(exec, 'w7', 'd1');
+    expect(await sqliteGetDoc(exec, 'w7', 'd1')).toBeNull();
+    const removed = await sqliteDeleteDocs(exec, 'w7', { kind: 'a' });
+    expect(removed).toEqual(['d2']);
+  });
+});
+
+describe('SqliteDoc getQuery', () => {
+  it('groups and sums', async () => {
+    await ensureSqliteTable(exec, 'agg');
+    await sqliteInsertRaw(exec, 'agg', { _id: 'a1', kind: 'a', amt: 10 });
+    await sqliteInsertRaw(exec, 'agg', { _id: 'a2', kind: 'a', amt: 20 });
+    await sqliteInsertRaw(exec, 'agg', { _id: 'b1', kind: 'b', amt: 5 });
+    const rows = await sqliteGetQuery<{ _id: string; total: number }>(exec, 'agg', [
+      { $group: { _id: '$kind', total: { $sum: '$amt' } } },
+    ]);
+    const byId = Object.fromEntries(rows.map((r) => [r._id, r.total]));
+    expect(byId).toEqual({ a: 30, b: 5 });
+  });
+
+  it('getQueryCount counts matches', async () => {
+    await ensureSqliteTable(exec, 'agg2');
+    await sqliteInsertRaw(exec, 'agg2', { _id: 'x1', k: 'a' });
+    await sqliteInsertRaw(exec, 'agg2', { _id: 'x2', k: 'a' });
+    await sqliteInsertRaw(exec, 'agg2', { _id: 'x3', k: 'b' });
+    expect(
+      await sqliteGetQueryCount(exec, 'agg2', [{ $match: { k: 'a' } }]),
+    ).toBe(2);
+  });
+});

package/src/server/sqlite/SqliteDoc.ts

@@ -0,0 +1,356 @@
+/**
+ * Document read operations on a SQLite/D1 backend. Sibling of PostgresDoc.ts.
+ * Pure builders + an injected SqliteExec — no driver import here. FTS/vector
+ * are intentionally absent (a db:'d1' collection may not declare search/vector).
+ */
+import { translateFilter, translateSort } from './SqliteFilter.js';
+import { translatePipeline } from './SqlitePipeline.js';
+import { applyOpInMemory, type UpdateOp } from './sqliteUpdateOps.js';
+import { ensureSqliteIndexes } from './SqliteSchema.js';
+import type { IndexDef } from '../../shared/DB.js';
+import type { SqliteExec } from './SqliteExec.js';
+
+interface RawRow {
+  _id: string;
+  data: string;
+  created: number;
+  updated: number;
+  version: number;
+}
+
+function toDoc<T>(row: RawRow): T {
+  const data = JSON.parse(row.data) as Record<string, unknown>;
+  return {
+    ...data,
+    _id: row._id,
+    created: new Date(row.created),
+    updated: new Date(row.updated),
+    version: row.version,
+  } as T;
+}
+
+const VALID_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertSafeName(name: string): void {
+  if (!VALID_NAME.test(name)) throw new Error(`Invalid collection name: ${name}`);
+}
+
+export async function ensureSqliteTable(
+  exec: SqliteExec,
+  collection: string,
+  indexes?: IndexDef[],
+): Promise<void> {
+  assertSafeName(collection);
+  await exec.run(
+    `CREATE TABLE IF NOT EXISTS "${collection}" (
+      _id     TEXT PRIMARY KEY,
+      data    TEXT NOT NULL,
+      created INTEGER NOT NULL,
+      updated INTEGER NOT NULL,
+      version INTEGER NOT NULL
+    )`,
+  );
+  if (indexes && indexes.length > 0) {
+    await ensureSqliteIndexes(exec, collection, indexes);
+  }
+}
+
+/** Seed helper (full writes/upserts land in Plan 2). Stores JSON text + epoch-ms meta. */
+export async function sqliteInsertRaw(
+  exec: SqliteExec,
+  collection: string,
+  doc: Record<string, unknown> & { _id: string },
+): Promise<void> {
+  const now = Date.now();
+  const { _id, created, updated, version, ...rest } = doc as Record<
+    string,
+    unknown
+  > & { _id: string };
+  await exec.run(
+    `INSERT INTO "${collection}" (_id, data, created, updated, version)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(_id) DO UPDATE SET data=excluded.data, updated=excluded.updated, version=excluded.version`,
+    [
+      _id,
+      JSON.stringify(rest),
+      typeof created === 'number' ? created : now,
+      typeof updated === 'number' ? updated : now,
+      typeof version === 'number' ? version : 1,
+    ],
+  );
+}
+
+export async function sqliteGetDoc<T>(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+): Promise<T | null> {
+  const rows = await exec.all<RawRow>(
+    `SELECT _id, data, created, updated, version FROM "${collection}" WHERE _id = ?`,
+    [id],
+  );
+  return rows.length === 0 ? null : toDoc<T>(rows[0]!);
+}
+
+export interface SqliteGetDocsOptions {
+  sort?: Record<string, 1 | -1>;
+  limit?: number;
+  skip?: number;
+}
+
+export async function sqliteGetDocs<T>(
+  exec: SqliteExec,
+  collection: string,
+  filter?: Record<string, unknown>,
+  options?: SqliteGetDocsOptions,
+): Promise<T[]> {
+  const { where, values } = translateFilter(filter ?? {});
+  let sql = `SELECT _id, data, created, updated, version FROM "${collection}"`;
+  if (where) sql += ` WHERE ${where}`;
+  if (options?.sort) sql += ` ORDER BY ${translateSort(options.sort)}`;
+  if (options?.limit !== undefined) {
+    sql += ` LIMIT ?`;
+    values.push(options.limit);
+  }
+  if (options?.skip !== undefined) {
+    // SQLite requires a LIMIT before OFFSET; use -1 (unlimited) when only skip is set.
+    if (options.limit === undefined) sql += ` LIMIT -1`;
+    sql += ` OFFSET ?`;
+    values.push(options.skip);
+  }
+  const rows = await exec.all<RawRow>(sql, values);
+  return rows.map((r) => toDoc<T>(r));
+}
+
+export async function sqliteFind<T>(
+  exec: SqliteExec,
+  collection: string,
+  filter?: Record<string, unknown>,
+  options?: SqliteGetDocsOptions,
+): Promise<T[]> {
+  return sqliteGetDocs<T>(exec, collection, filter, options);
+}
+
+export async function sqliteFindCount(
+  exec: SqliteExec,
+  collection: string,
+  filter?: Record<string, unknown>,
+): Promise<number> {
+  const { where, values } = translateFilter(filter ?? {});
+  let sql = `SELECT COUNT(*) AS count FROM "${collection}"`;
+  if (where) sql += ` WHERE ${where}`;
+  const rows = await exec.all<{ count: number }>(sql, values);
+  return rows[0]?.count ?? 0;
+}
+
+export async function sqliteFindRandom<T>(
+  exec: SqliteExec,
+  collection: string,
+  filter?: Record<string, unknown>,
+  limit?: number,
+): Promise<T[]> {
+  const { where, values } = translateFilter(filter ?? {});
+  let sql = `SELECT _id, data, created, updated, version FROM "${collection}"`;
+  if (where) sql += ` WHERE ${where}`;
+  sql += ` ORDER BY RANDOM() LIMIT ?`;
+  values.push(limit ?? 100);
+  const rows = await exec.all<RawRow>(sql, values);
+  return rows.map((r) => toDoc<T>(r));
+}
+
+// ── Writes ────────────────────────────────────────────────────────────────
+
+export async function sqliteSetDoc(
+  exec: SqliteExec,
+  collection: string,
+  doc: Record<string, unknown> & { _id: string },
+  options?: { skipIfExists?: boolean },
+): Promise<boolean> {
+  const now = Date.now();
+  const { _id, created, updated, version, ...rest } = doc;
+  const c = typeof created === 'number' ? created : now;
+  const u = typeof updated === 'number' ? updated : now;
+  const v = typeof version === 'number' ? version : 1;
+  const json = JSON.stringify(rest);
+  if (options?.skipIfExists) {
+    const before = await exec.all<{ n: number }>(
+      `SELECT COUNT(*) AS n FROM "${collection}" WHERE _id = ?`,
+      [_id],
+    );
+    if ((before[0]?.n ?? 0) > 0) return false;
+    await exec.run(
+      `INSERT INTO "${collection}" (_id, data, created, updated, version) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(_id) DO NOTHING`,
+      [_id, json, c, u, v],
+    );
+    return true;
+  }
+  await exec.run(
+    `INSERT INTO "${collection}" (_id, data, created, updated, version) VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(_id) DO UPDATE SET data=excluded.data, updated=excluded.updated, version=excluded.version`,
+    [_id, json, c, u, v],
+  );
+  return true;
+}
+
+export async function sqliteApplyUpdateOp<T>(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+  op: UpdateOp,
+): Promise<T | null> {
+  const rows = await exec.all<RawRow>(
+    `SELECT _id, data, created, updated, version FROM "${collection}" WHERE _id = ?`,
+    [id],
+  );
+  if (rows.length === 0) return null;
+  const row = rows[0]!;
+  const nextData = applyOpInMemory(
+    JSON.parse(row.data) as Record<string, unknown>,
+    op,
+  );
+  const nextVersion = row.version + 1;
+  const now = Date.now();
+  await exec.run(
+    `UPDATE "${collection}" SET data = ?, updated = ?, version = ? WHERE _id = ?`,
+    [JSON.stringify(nextData), now, nextVersion, id],
+  );
+  return {
+    ...nextData,
+    _id: row._id,
+    created: new Date(row.created),
+    updated: new Date(now),
+    version: nextVersion,
+  } as T;
+}
+
+export async function sqliteSetDocFields<T>(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+  fields: Record<string, unknown>,
+): Promise<T> {
+  const r = await sqliteApplyUpdateOp<T>(exec, collection, id, { $set: fields });
+  if (r === null) throw new Error(`Document not found: ${collection}/${id}`);
+  return r;
+}
+
+export async function sqliteSetDocFieldsOrIgnore<T>(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+  fields: Record<string, unknown>,
+): Promise<T | null> {
+  return sqliteApplyUpdateOp<T>(exec, collection, id, { $set: fields });
+}
+
+export async function sqliteSetDocFieldsOrCreate<T extends { _id: string }>(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+  fields: Record<string, unknown>,
+  obj: T,
+): Promise<T> {
+  const existing = await sqliteApplyUpdateOp<T>(exec, collection, id, {
+    $set: fields,
+  });
+  if (existing !== null) return existing;
+  await sqliteSetDoc(
+    exec,
+    collection,
+    obj as Record<string, unknown> & { _id: string },
+    { skipIfExists: true },
+  );
+  return obj;
+}
+
+export async function sqliteSetDocOp<T>(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+  op: UpdateOp,
+): Promise<T> {
+  const r = await sqliteApplyUpdateOp<T>(exec, collection, id, op);
+  if (r === null) throw new Error(`Document not found: ${collection}/${id}`);
+  return r;
+}
+
+export async function sqliteSetDocOpOrIgnore<T>(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+  op: UpdateOp,
+): Promise<T | null> {
+  return sqliteApplyUpdateOp<T>(exec, collection, id, op);
+}
+
+export async function sqliteDeleteDoc(
+  exec: SqliteExec,
+  collection: string,
+  id: string,
+): Promise<void> {
+  await exec.run(`DELETE FROM "${collection}" WHERE _id = ?`, [id]);
+}
+
+export async function sqliteDeleteDocs(
+  exec: SqliteExec,
+  collection: string,
+  filter: Record<string, unknown>,
+): Promise<string[]> {
+  const { where, values } = translateFilter(filter);
+  let selectSql = `SELECT _id FROM "${collection}"`;
+  if (where) selectSql += ` WHERE ${where}`;
+  const matched = await exec.all<{ _id: string }>(selectSql, values);
+  const ids = matched.map((r) => r._id);
+  let deleteSql = `DELETE FROM "${collection}"`;
+  if (where) deleteSql += ` WHERE ${where}`;
+  await exec.run(deleteSql, values);
+  return ids;
+}
+
+export async function sqliteDeleteWhere(
+  exec: SqliteExec,
+  collection: string,
+  filter: Record<string, unknown>,
+): Promise<string[]> {
+  return sqliteDeleteDocs(exec, collection, filter);
+}
+
+// ── Aggregation pipeline ────────────────────────────────────────────────────
+
+export async function sqliteGetQuery<T>(
+  exec: SqliteExec,
+  collection: string,
+  pipeline: Record<string, unknown>[],
+  options?: { skip?: number; limit?: number },
+): Promise<T[]> {
+  const { sql, values } = translatePipeline(collection, pipeline, options);
+  const rows = await exec.all<Record<string, unknown>>(sql, values);
+  return rows.map((row) =>
+    row.data !== undefined && row._id !== undefined && row.created !== undefined
+      ? toDoc<T>(row as unknown as RawRow)
+      : (row as T),
+  );
+}
+
+export async function sqliteGetQueryCount(
+  exec: SqliteExec,
+  collection: string,
+  pipeline: Record<string, unknown>[],
+): Promise<number> {
+  const { sql, values } = translatePipeline(collection, [
+    ...pipeline,
+    { $count: 'count' },
+  ]);
+  const rows = await exec.all<{ count: number }>(sql, values);
+  return Number(rows[0]?.count ?? 0);
+}
+
+export async function sqliteGetQueryRaw<T>(
+  exec: SqliteExec,
+  collection: string,
+  pipeline: Record<string, unknown>[],
+  options?: { skip?: number; limit?: number },
+): Promise<T[]> {
+  const { sql, values } = translatePipeline(collection, pipeline, options);
+  return (await exec.all(sql, values)) as T[];
+}

package/src/server/sqlite/SqliteExec.ts

@@ -0,0 +1,35 @@
+/**
+ * The single SQL primitive the SQLite doc store runs against. Two impls:
+ *   - better-sqlite3 (Node dev / tests) — built by makeBetterSqliteExec below.
+ *   - Cloudflare D1 (prod) — built from the binding in the Workers adapter
+ *     (added in a later plan); its .prepare().bind().all()/run() maps 1:1.
+ * SqliteDoc.ts depends ONLY on this interface, never on a concrete driver.
+ */
+export interface SqliteExec {
+  all<T = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<T[]>;
+  run(sql: string, params?: readonly unknown[]): Promise<void>;
+}
+
+/**
+ * Node-only executor over better-sqlite3. Uses a DYNAMIC import so the native
+ * addon is never pulled into a Workers bundle (see Global Constraints). `:memory:`
+ * by default. better-sqlite3 is synchronous; we wrap results in resolved promises.
+ */
+export async function makeBetterSqliteExec(
+  filename = ':memory:',
+): Promise<SqliteExec> {
+  const { default: Database } = await import('better-sqlite3');
+  const db = new Database(filename);
+  db.pragma('journal_mode = WAL');
+  return {
+    async all<T>(sql: string, params: readonly unknown[] = []): Promise<T[]> {
+      return db.prepare(sql).all(...(params as unknown[])) as T[];
+    },
+    async run(sql: string, params: readonly unknown[] = []): Promise<void> {
+      db.prepare(sql).run(...(params as unknown[]));
+    },
+  };
+}