@askexenow/exe-os 0.9.292 → 0.9.293

package/dist/chunk-Q326CKO3.js

@@ -0,0 +1,377 @@
+import {
+  EXE_AI_DIR
+} from "./chunk-R36FAN53.js";
+
+// src/lib/db-backup.ts
+import { existsSync, readdirSync, unlinkSync, statSync, statfsSync } from "fs";
+import { copyFile, mkdir, unlink, rename } from "fs/promises";
+import path from "path";
+var BACKUP_DIR = path.join(EXE_AI_DIR, "backups");
+var DEFAULT_KEEP_DAYS = 3;
+var DB_NAMES = ["memories.db", "exe-mem.db", "exe-os.db", "exe.db"];
+var REASON_COUNT_CAP = {
+  // Bug 727b7b1e: a daemon OOM crash loop made a ~1.5GB pre-restart backup on
+  // EVERY restart. 22 crashes = 11GB of pre-restart snapshots with no rotation.
+  // Keep only the 2 newest — enough to recover, small enough not to fill disk.
+  "pre-restart": 2,
+  "pre-consolidation": 5,
+  "pre-fix": 5,
+  "pre-restore": 5,
+  // Bug 91b1b167: daily snapshots are full uncompressed SQLCipher copies
+  // (~2-3GB apiece on large enterprise DBs). Time-based rotation alone left
+  // 19GB accumulating when mtimes drifted / the disk guard tripped. A hard
+  // count cap is a belt-and-braces safety net on top of day-based rotation.
+  "daily": 3
+};
+var MIN_FREE_BYTES = 5 * 1024 * 1024 * 1024;
+var STALE_TMP_MAX_AGE_MS = 60 * 60 * 1e3;
+function findActiveDb() {
+  for (const name of DB_NAMES) {
+    const p = path.join(EXE_AI_DIR, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+async function createBackup(reason = "manual") {
+  return createBackupAsync(reason);
+}
+async function createBackupAsync(reason = "manual", opts = {}) {
+  const dbPath = findActiveDb();
+  if (!dbPath) return null;
+  await mkdir(BACKUP_DIR, { recursive: true });
+  try {
+    let dbSize = 0;
+    try {
+      dbSize = statSync(dbPath).size;
+    } catch {
+    }
+    const freeBytes = getFreeBytes(BACKUP_DIR);
+    if (!hasEnoughDiskSpace(freeBytes, dbSize)) {
+      process.stderr.write(
+        `[db-backup] DISK GUARD: skipping "${reason}" backup \u2014 ${Math.round(freeBytes / 1024 / 1024)}MB free, need >${Math.round(Math.max(MIN_FREE_BYTES, dbSize * 2) / 1024 / 1024)}MB. Disk is nearly full; refusing to make it worse.
+`
+      );
+      return null;
+    }
+  } catch {
+  }
+  const dbName = path.basename(dbPath, ".db");
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const backupName = `${dbName}-${reason}-${timestamp}.db`;
+  const backupPath = path.join(BACKUP_DIR, backupName);
+  const tmpBackupPath = `${backupPath}.tmp`;
+  const checkpointMode = opts.checkpointMode ?? "TRUNCATE";
+  try {
+    const { getClient } = await import("./lib/database.js");
+    const client = getClient();
+    await client.execute(`PRAGMA wal_checkpoint(${checkpointMode})`);
+  } catch {
+    try {
+      const { execFile: execFileCb } = await import("child_process");
+      const { promisify } = await import("util");
+      const execFileAsync = promisify(execFileCb);
+      await execFileAsync("sqlite3", [dbPath, `PRAGMA wal_checkpoint(${checkpointMode});`], { timeout: 3e4 });
+    } catch {
+      process.stderr.write(`[db-backup] WAL checkpoint skipped \u2014 proceeding with copy (backup may include stale WAL)
+`);
+    }
+  }
+  try {
+    await unlink(tmpBackupPath);
+  } catch {
+  }
+  await copyFile(dbPath, tmpBackupPath);
+  await rename(tmpBackupPath, backupPath);
+  try {
+    const { getClient } = await import("./lib/database.js");
+    const client = getClient();
+    const chk = await client.execute("PRAGMA quick_check;");
+    const result = String(chk.rows[0]?.quick_check ?? chk.rows[0]?.[0] ?? "").trim();
+    if (result && result !== "ok") {
+      process.stderr.write(`[db-backup] WARNING: backup source failed quick_check (${reason}): ${result}
+`);
+      try {
+        await unlink(backupPath);
+      } catch {
+      }
+      return null;
+    }
+  } catch {
+    process.stderr.write(`[db-backup] Backup validation skipped (encrypted DB or CLI context) \u2014 proceeding with checkpoint-consistent copy.
+`);
+  }
+  const walPath = dbPath + "-wal";
+  if (existsSync(walPath)) {
+    try {
+      await copyFile(walPath, backupPath + "-wal.tmp");
+      await rename(backupPath + "-wal.tmp", backupPath + "-wal");
+    } catch {
+    }
+  }
+  const shmPath = dbPath + "-shm";
+  if (existsSync(shmPath)) {
+    try {
+      await copyFile(shmPath, backupPath + "-shm.tmp");
+      await rename(backupPath + "-shm.tmp", backupPath + "-shm");
+    } catch {
+    }
+  }
+  return backupPath;
+}
+function rotateBackups(keepDays = DEFAULT_KEEP_DAYS) {
+  if (!existsSync(BACKUP_DIR)) return 0;
+  const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1e3;
+  let deleted = 0;
+  try {
+    const files = readdirSync(BACKUP_DIR);
+    for (const file of files) {
+      if (file.endsWith(".tmp")) continue;
+      if (!file.endsWith(".db") && !file.endsWith(".db-wal") && !file.endsWith(".db-shm")) continue;
+      const filePath = path.join(BACKUP_DIR, file);
+      try {
+        const stat = statSync(filePath);
+        if (stat.mtimeMs < cutoff) {
+          unlinkSync(filePath);
+          deleted++;
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return deleted;
+}
+function selectBackupsToDelete(backups, keep) {
+  if (keep < 0) keep = 0;
+  const sorted = [...backups].sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return sorted.slice(keep).map((b) => b.path);
+}
+function selectStaleTmpFiles(tmpFiles, cutoffMs) {
+  return tmpFiles.filter((f) => f.mtimeMs < cutoffMs).map((f) => f.path);
+}
+function cleanupStaleTmp(maxAgeMs = STALE_TMP_MAX_AGE_MS) {
+  if (!existsSync(BACKUP_DIR)) return 0;
+  const cutoffMs = Date.now() - maxAgeMs;
+  let deleted = 0;
+  try {
+    const candidates = [];
+    for (const file of readdirSync(BACKUP_DIR)) {
+      if (!file.endsWith(".tmp")) continue;
+      const filePath = path.join(BACKUP_DIR, file);
+      try {
+        candidates.push({ path: filePath, mtimeMs: statSync(filePath).mtimeMs });
+      } catch {
+      }
+    }
+    for (const target of selectStaleTmpFiles(candidates, cutoffMs)) {
+      try {
+        unlinkSync(target);
+        deleted++;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return deleted;
+}
+function hasEnoughDiskSpace(freeBytes, backupSizeBytes, minFreeBytes = MIN_FREE_BYTES) {
+  const required = Math.max(minFreeBytes, backupSizeBytes * 2);
+  return freeBytes >= required;
+}
+function getFreeBytes(dir) {
+  try {
+    const s = statfsSync(dir);
+    return s.bavail * s.bsize;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+async function quickCheckBackupSource(source) {
+  try {
+    const { execFile: execFileCb } = await import("child_process");
+    const { promisify } = await import("util");
+    const execFileAsync = promisify(execFileCb);
+    const { stdout } = await execFileAsync("sqlite3", [source, "PRAGMA quick_check;"], { timeout: 3e4 });
+    const result = String(stdout ?? "").trim();
+    if (result !== "ok") {
+      throw new Error(result || "quick_check returned no result");
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/file is not a database|not an error/i.test(msg)) {
+      process.stderr.write(`[db-backup] Backup source quick_check unavailable for encrypted backup (${path.basename(source)}); proceeding with atomic restore.
+`);
+      return;
+    }
+    throw new Error(`Backup source failed quick_check: ${msg}`);
+  }
+}
+function rotateBackupsByReason(reason, keep) {
+  if (!existsSync(BACKUP_DIR)) return 0;
+  let deleted = 0;
+  try {
+    const files = readdirSync(BACKUP_DIR);
+    const matches = [];
+    for (const file of files) {
+      if (file.endsWith(".tmp")) continue;
+      if (!file.endsWith(".db")) continue;
+      if (!file.includes(`-${reason}-`)) continue;
+      const filePath = path.join(BACKUP_DIR, file);
+      try {
+        matches.push({ path: filePath, mtimeMs: statSync(filePath).mtimeMs });
+      } catch {
+      }
+    }
+    for (const target of selectBackupsToDelete(matches, keep)) {
+      for (const p of [target, target + "-wal", target + "-shm"]) {
+        try {
+          if (existsSync(p)) {
+            unlinkSync(p);
+            if (p === target) deleted++;
+          }
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  return deleted;
+}
+function enforceRetention(reason, keepDays = DEFAULT_KEEP_DAYS) {
+  let deleted = rotateBackups(keepDays);
+  const cap = REASON_COUNT_CAP[reason];
+  if (typeof cap === "number") {
+    deleted += rotateBackupsByReason(reason, cap);
+  }
+  deleted += cleanupStaleTmp();
+  return deleted;
+}
+var QUARANTINE_KEEP = 2;
+function pruneCorruptQuarantine(keep = QUARANTINE_KEEP) {
+  if (!existsSync(EXE_AI_DIR)) return 0;
+  let deleted = 0;
+  try {
+    const matches = [];
+    for (const file of readdirSync(EXE_AI_DIR)) {
+      if (!/\.corrupt-\d+$/.test(file)) continue;
+      const filePath = path.join(EXE_AI_DIR, file);
+      try {
+        matches.push({ path: filePath, mtimeMs: statSync(filePath).mtimeMs });
+      } catch {
+      }
+    }
+    for (const target of selectBackupsToDelete(matches, keep)) {
+      for (const p of [target, target + "-wal", target + "-shm"]) {
+        try {
+          if (existsSync(p)) {
+            unlinkSync(p);
+            if (p === target) deleted++;
+          }
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  return deleted;
+}
+function cleanupCrashDebris() {
+  let deleted = 0;
+  deleted += rotateBackupsByReason("pre-restart", REASON_COUNT_CAP["pre-restart"] ?? 2);
+  deleted += cleanupStaleTmp();
+  deleted += pruneCorruptQuarantine();
+  return deleted;
+}
+function listBackups() {
+  if (!existsSync(BACKUP_DIR)) return [];
+  try {
+    const files = readdirSync(BACKUP_DIR).filter((f) => f.endsWith(".db") && !f.endsWith(".tmp") && !f.endsWith("-wal") && !f.endsWith("-shm"));
+    return files.map((name) => {
+      const p = path.join(BACKUP_DIR, name);
+      const stat = statSync(p);
+      return { path: p, name, size: stat.size, date: stat.mtime };
+    }).sort((a, b) => b.date.getTime() - a.date.getTime());
+  } catch {
+    return [];
+  }
+}
+function hasBackupToday(reason) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const backups = listBackups();
+  return backups.some((b) => b.name.includes(reason) && b.name.includes(today.replace(/-/g, "-")));
+}
+function getLatestBackup() {
+  const backups = listBackups();
+  return backups.length > 0 ? backups[0].path : null;
+}
+async function restoreBackup(backupPath) {
+  const dbPath = findActiveDb();
+  if (!dbPath) {
+    const target = path.join(EXE_AI_DIR, DB_NAMES[0]);
+    const source2 = backupPath ?? getLatestBackup();
+    if (!source2 || !existsSync(source2)) return null;
+    await copyFile(source2, target);
+    return { restored: path.basename(source2), preRestoreBackup: null };
+  }
+  const source = backupPath ?? getLatestBackup();
+  if (!source || !existsSync(source)) return null;
+  if (path.resolve(source) === path.resolve(dbPath)) return null;
+  await quickCheckBackupSource(source);
+  const preRestoreBackup = await createBackup("pre-restore");
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const tmpDb = `${dbPath}.restore-${stamp}.tmp`;
+  const oldDb = `${dbPath}.pre-restore-active-${stamp}`;
+  await copyFile(source, tmpDb);
+  const walPath = source + "-wal";
+  const shmPath = source + "-shm";
+  const tmpWal = `${tmpDb}-wal`;
+  const tmpShm = `${tmpDb}-shm`;
+  if (existsSync(walPath)) {
+    try {
+      await copyFile(walPath, tmpWal);
+    } catch {
+    }
+  }
+  if (existsSync(shmPath)) {
+    try {
+      await copyFile(shmPath, tmpShm);
+    } catch {
+    }
+  }
+  try {
+    unlinkSync(dbPath + "-wal");
+  } catch {
+  }
+  try {
+    unlinkSync(dbPath + "-shm");
+  } catch {
+  }
+  await rename(dbPath, oldDb);
+  await rename(tmpDb, dbPath);
+  if (existsSync(tmpWal)) await rename(tmpWal, dbPath + "-wal");
+  if (existsSync(tmpShm)) await rename(tmpShm, dbPath + "-shm");
+  return { restored: path.basename(source), preRestoreBackup };
+}
+function getBackupDir() {
+  return BACKUP_DIR;
+}
+
+export {
+  findActiveDb,
+  createBackup,
+  createBackupAsync,
+  rotateBackups,
+  selectBackupsToDelete,
+  selectStaleTmpFiles,
+  cleanupStaleTmp,
+  hasEnoughDiskSpace,
+  rotateBackupsByReason,
+  enforceRetention,
+  pruneCorruptQuarantine,
+  cleanupCrashDebris,
+  listBackups,
+  hasBackupToday,
+  getLatestBackup,
+  restoreBackup,
+  getBackupDir
+};

package/dist/chunk-QAK47LG3.js

@@ -0,0 +1,81 @@
+// src/bin/fast-db-init.ts
+async function fastDbInit() {
+  const { isInitialized, getClient, setExternalClient } = await import("./lib/database.js");
+  if (isInitialized()) {
+    return getClient();
+  }
+  const forceDirect = process.env.EXE_DB_DIRECT === "1" || process.env.EXE_DB_READONLY === "1" || process.env.EXE_SKIP_DAEMON === "1";
+  if (!forceDirect) {
+    try {
+      const { connectEmbedDaemon, sendDaemonRequest, isClientConnected, disconnectClient } = await import("./lib/exe-daemon-client.js");
+      const { deserializeResultSet } = await import("./daemon-protocol-XW2OLNBS.js");
+      await Promise.race([
+        connectEmbedDaemon(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("Daemon socket timeout (2s)")), 2e3))
+      ]);
+      if (isClientConnected()) {
+        const daemonClient = {
+          async execute(stmt) {
+            const sql = typeof stmt === "string" ? stmt : stmt.sql;
+            const args = typeof stmt === "string" ? [] : Array.isArray(stmt.args) ? stmt.args : [];
+            const resp = await sendDaemonRequest({ type: "db-execute", sql, args });
+            if (resp.error) throw new Error(String(resp.error));
+            if (resp.db) return deserializeResultSet(resp.db);
+            throw new Error("Unexpected daemon response");
+          },
+          async batch(stmts, mode) {
+            const statements = stmts.map((s) => {
+              const sql = typeof s === "string" ? s : s.sql;
+              const args = typeof s === "string" ? [] : Array.isArray(s.args) ? s.args : [];
+              return { sql, args };
+            });
+            const resp = await sendDaemonRequest({ type: "db-batch", statements, mode: mode ?? "deferred" });
+            if (resp.error) throw new Error(String(resp.error));
+            const batchResults = resp["db-batch"];
+            if (batchResults) return batchResults.map(deserializeResultSet);
+            throw new Error("Unexpected daemon batch response");
+          },
+          async transaction(_mode) {
+            throw new Error("Transactions not supported via daemon socket");
+          },
+          async executeMultiple(_sql) {
+            throw new Error("executeMultiple not supported via daemon socket");
+          },
+          async migrate(_stmts) {
+            throw new Error("migrate not supported via daemon socket");
+          },
+          sync() {
+            return Promise.resolve(void 0);
+          },
+          close() {
+          },
+          get closed() {
+            return false;
+          },
+          get protocol() {
+            return "file";
+          }
+        };
+        try {
+          await daemonClient.execute("SELECT 1");
+        } catch {
+          try {
+            disconnectClient();
+          } catch {
+          }
+          throw new Error("Daemon socket validation failed");
+        }
+        setExternalClient(daemonClient);
+        return daemonClient;
+      }
+    } catch {
+    }
+  }
+  const { initStore } = await import("./lib/store.js");
+  await initStore({ lightweight: true });
+  return getClient();
+}
+
+export {
+  fastDbInit
+};

package/dist/chunk-QAWSQ5LG.js

@@ -0,0 +1,157 @@
+import {
+  clean,
+  stableId
+} from "./chunk-XDH5XB72.js";
+
+// src/lib/reflection-checkpoints.ts
+function parsePayload(payload) {
+  if (!payload) return {};
+  try {
+    return JSON.parse(payload);
+  } catch {
+    return {};
+  }
+}
+function semanticArray(event, key) {
+  const payload = parsePayload(event.payload);
+  const semantic = payload.semantic;
+  const value = semantic?.[key];
+  return Array.isArray(value) ? value.map(String).filter(Boolean) : [];
+}
+function buildReflectionCheckpoint(events) {
+  if (!events.length) return null;
+  const sorted = [...events].sort((a, b) => a.occurred_at.localeCompare(b.occurred_at));
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  const goals = /* @__PURE__ */ new Set();
+  const successes = [];
+  const failures = [];
+  const risks = [];
+  const nextActions = [];
+  const decisions = [];
+  for (const event of sorted) {
+    for (const goal of semanticArray(event, "goals")) goals.add(goal);
+    for (const item of semanticArray(event, "successSignals")) successes.push(item);
+    for (const item of semanticArray(event, "failureSignals")) failures.push(item);
+    for (const item of semanticArray(event, "nextActions")) nextActions.push(item);
+    for (const item of semanticArray(event, "decisions")) decisions.push(item);
+    if (event.impact === "negative" || event.outcome === "failure_signal" || event.event_type === "problem" || event.event_type === "error") {
+      failures.push(event.outcome || event.intention || event.event_type);
+    }
+    if (event.outcome === "risk_signal") risks.push(event.intention || event.outcome);
+    if (event.impact === "positive" || event.outcome === "success_signal" || event.event_type === "milestone") {
+      successes.push(event.outcome || event.intention || event.event_type);
+    }
+  }
+  const uniqueGoals = [...goals].slice(0, 6);
+  const uniqueSuccesses = [...new Set(successes.map((x) => clean(x, 180)).filter(Boolean))].slice(0, 6);
+  const uniqueFailures = [...new Set(failures.map((x) => clean(x, 180)).filter(Boolean))].slice(0, 6);
+  const uniqueRisks = [...new Set(risks.map((x) => clean(x, 180)).filter(Boolean))].slice(0, 6);
+  const uniqueNext = [...new Set(nextActions.map((x) => clean(x, 180)).filter(Boolean))].slice(0, 6);
+  const uniqueDecisions = [...new Set(decisions.map((x) => clean(x, 180)).filter(Boolean))].slice(0, 6);
+  const learnings = [
+    uniqueSuccesses.length ? `Working: ${uniqueSuccesses.slice(0, 3).join("; ")}` : "Working: no strong success signal yet",
+    uniqueFailures.length ? `Improve: ${uniqueFailures.slice(0, 3).join("; ")}` : "Improve: no strong failure signal in this window",
+    uniqueDecisions.length ? `Decision context: ${uniqueDecisions.slice(0, 2).join("; ")}` : "Decision context: no explicit decision signal"
+  ];
+  const summary = clean([
+    `Window ${first.occurred_at} \u2192 ${last.occurred_at}`,
+    `${sorted.length} events`,
+    uniqueGoals.length ? `goals: ${uniqueGoals.join("; ")}` : "goals: inferred from event trajectory",
+    uniqueSuccesses.length ? `successes: ${uniqueSuccesses.slice(0, 2).join("; ")}` : "successes: none explicit",
+    uniqueFailures.length ? `failures: ${uniqueFailures.slice(0, 2).join("; ")}` : "failures: none explicit"
+  ].join(". "), 1200);
+  return {
+    id: stableId("reflection", first.project_name ?? "", first.session_id ?? "", first.occurred_at, last.occurred_at, sorted.length),
+    projectName: first.project_name ?? null,
+    sessionId: first.session_id ?? null,
+    windowStartAt: first.occurred_at,
+    windowEndAt: last.occurred_at,
+    eventCount: sorted.length,
+    goalCount: uniqueGoals.length,
+    successCount: uniqueSuccesses.length,
+    failureCount: uniqueFailures.length,
+    riskCount: uniqueRisks.length,
+    summary,
+    learnings,
+    nextActions: uniqueNext.length ? uniqueNext : ["Continue from latest successful event and resolve highest-impact failure/risk first."],
+    evidenceEventIds: sorted.slice(-25).map((e) => e.id),
+    confidence: Math.min(0.95, 0.5 + Math.min(sorted.length, 100) / 250 + uniqueGoals.length * 0.03)
+  };
+}
+async function resolveClient(client) {
+  if (client) return client;
+  const { getClient } = await import("./lib/database.js");
+  return getClient();
+}
+async function insertReflectionCheckpoint(checkpoint, client) {
+  const db = await resolveClient(client);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await db.execute({
+    sql: `INSERT INTO agent_reflection_checkpoints
+      (id, project_name, session_id, window_start_at, window_end_at, event_count, goal_count,
+       success_count, failure_count, risk_count, summary, learnings, next_actions, evidence_event_ids,
+       confidence, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET summary = excluded.summary, learnings = excluded.learnings,
+        next_actions = excluded.next_actions, confidence = excluded.confidence`,
+    args: [
+      checkpoint.id,
+      checkpoint.projectName,
+      checkpoint.sessionId,
+      checkpoint.windowStartAt,
+      checkpoint.windowEndAt,
+      checkpoint.eventCount,
+      checkpoint.goalCount,
+      checkpoint.successCount,
+      checkpoint.failureCount,
+      checkpoint.riskCount,
+      checkpoint.summary,
+      JSON.stringify(checkpoint.learnings),
+      JSON.stringify(checkpoint.nextActions),
+      JSON.stringify(checkpoint.evidenceEventIds),
+      checkpoint.confidence,
+      now
+    ]
+  });
+}
+async function generateReflectionCheckpoints(opts = {}) {
+  const db = await resolveClient(opts.client);
+  const windowSize = opts.windowSize ?? 100;
+  const minEvents = opts.minEvents ?? 20;
+  const limit = opts.limit ?? 5e3;
+  const where = opts.projectName ? "WHERE project_name = ?" : "";
+  const args = opts.projectName ? [opts.projectName] : [];
+  const result = await db.execute({
+    sql: `SELECT id, event_type, occurred_at, actor_agent_id, project_name, session_id, intention, outcome, impact, evidence_memory_id, payload
+          FROM agent_events ${where}
+          ORDER BY project_name, session_id, occurred_at, sequence_index
+          LIMIT ?`,
+    args: [...args, limit]
+  });
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of result.rows) {
+    const event = row;
+    const key = `${event.project_name ?? ""}::${event.session_id ?? ""}`;
+    const bucket = groups.get(key) ?? [];
+    bucket.push(event);
+    groups.set(key, bucket);
+  }
+  let inserted = 0;
+  for (const events of groups.values()) {
+    for (let i = 0; i < events.length; i += windowSize) {
+      const window = events.slice(i, i + windowSize);
+      if (window.length < minEvents) continue;
+      const checkpoint = buildReflectionCheckpoint(window);
+      if (!checkpoint) continue;
+      await insertReflectionCheckpoint(checkpoint, db);
+      inserted++;
+    }
+  }
+  return inserted;
+}
+
+export {
+  buildReflectionCheckpoint,
+  generateReflectionCheckpoints
+};