@wrongstack/core 0.300.0 → 0.302.0

package/dist/chronicle/index.d.ts

@@ -7,6 +7,8 @@ export { ChronicleProjectServerClient, ChronicleRemoteJournal, isChronicleProjec
 export { chronicleProjectServerEndpoint, chronicleProjectServerKey, chronicleProjectServerMetadataPath, } from './project-server-endpoint.js';
 export { CHRONICLE_PROJECT_SERVER_MAX_FRAME_CHARS, CHRONICLE_PROJECT_SERVER_PROTOCOL_VERSION, type ChronicleMetricsRequest, type ChronicleMetricsResponse, type ChronicleMetricsView, type ChronicleProjectServerHealth, type ChronicleProjectServerInfo, type ChronicleServerOperationName, type ChronicleServerOperations, } from './project-server-protocol.js';
 export { ChronicleJournal, GENESIS_HASH, type ChronicleJournalOptions, type ChronicleJournalStats, type ChroniclePurgeOptions, type ChroniclePurgeResult } from './journal.js';
+export { ChronicleCompactionBusyError, compactChronicleSqlite, type ChronicleSqliteCompactionOptions, type ChronicleSqliteCompactionResult, } from './sqlite-compaction.js';
+export { ChronicleStorageQuotaError } from './sqlite-journal.js';
 export { wireProviderAttemptsToChronicle, type ChronicleProviderAdapterOptions, } from './provider-adapter.js';
 export { wireToolsToChronicle, type ChronicleToolAdapterOptions } from './tool-adapter.js';
 export { wireProcessesToChronicle, type ChronicleProcessAdapterOptions, } from './process-adapter.js';

package/dist/chronicle/index.js

@@ -557,6 +557,9 @@ function canonicalProjectRoot(absRoot) {
     const commonDirFile = path4.join(gitDir, "commondir");
     if (!fs2.statSync(commonDirFile).isFile()) return checkoutRoot;
     const commonDir = path4.resolve(gitDir, fs2.readFileSync(commonDirFile, "utf8").trim());
+    const worktreesDir = path4.dirname(gitDir);
+    if (path4.basename(worktreesDir).toLowerCase() !== "worktrees") return checkoutRoot;
+    if (path4.resolve(worktreesDir, "..") !== commonDir) return checkoutRoot;
     if (path4.basename(commonDir).toLowerCase() !== ".git") return checkoutRoot;
     return path4.dirname(commonDir);
   } catch {
@@ -579,7 +582,7 @@ function safeProfileName(name) {
   const safe = (name ?? "").replace(/[/\\:]/g, "_").replace(/\.\./g, "_").trim();
   return safe || "default";
 }
-function activeProfileName(globalRoot) {
+function bootstrapProfileName(globalRoot) {
   try {
     const parsed = JSON.parse(fs2.readFileSync(path4.join(globalRoot, "config.json"), "utf8"));
     return safeProfileName(
@@ -597,7 +600,7 @@ function wstackGlobalRoot() {
 function resolveWstackPaths(opts) {
   const globalRoot = opts.globalRoot ?? (opts.userHome ? path4.join(opts.userHome, ".wrongstack") : wstackGlobalRoot());
   const homeDir = opts.userHome ?? os2.homedir();
-  const profileName = safeProfileName(opts.profileName ?? activeProfileName(globalRoot));
+  const profileName = safeProfileName(opts.profileName ?? bootstrapProfileName(globalRoot));
   const profileDir = path4.join(globalRoot, "profiles", profileName);
   const hash3 = projectHash(opts.projectRoot);
   const slug = projectSlug(opts.projectRoot);
@@ -667,7 +670,12 @@ function resolveWstackPaths(opts) {
     projectRequirementIntakes: path4.join(projectDir, "requirement-intakes"),
     syncConfig: path4.join(profileDir, "sync.json"),
     configHistoryDir: path4.join(globalRoot, "config-history"),
-    projectStatus: (projectHash2) => path4.join(globalRoot, "projects", projectHash2, "status.json")
+    projectStatus: (statusProjectSlug) => {
+      if (!/^[a-z0-9](?:[a-z0-9-]{0,39})-[a-f0-9]{6}$/.test(statusProjectSlug)) {
+        throw new Error(`Invalid project slug: ${statusProjectSlug}`);
+      }
+      return path4.join(globalRoot, "projects", statusProjectSlug, "status.json");
+    }
   };
 }
 
@@ -3099,9 +3107,24 @@ async function importLegacyChronicleJournal(journal, directory) {
 
 // src/chronicle/sqlite-journal.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
+import * as fs8 from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import * as path11 from "node:path";
 
+// src/utils/pid.ts
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+
 // src/chronicle/sqlite-query.ts
 var MAX_LIMIT = 1e4;
 function encodeCursor2(cursor) {
@@ -3344,6 +3367,25 @@ var CHRONICLE_SQLITE_FILE = "chronicle.sqlite";
 var LEGACY_JSONL_MIGRATION_KEY = "legacy-jsonl-v1";
 var LEGACY_JSONL_QUARANTINE_KEY = "legacy-jsonl-v1:quarantine";
 var SCHEMA_VERSION2 = 1;
+var SQLITE_FIXED_OVERHEAD_BYTES = 16 * 1024 * 1024;
+var MIN_SQLITE_PAGE_BUDGET_BYTES = 64 * 1024;
+var MAX_ROLLBACK_JOURNAL_RESERVE_BYTES = 64 * 1024 * 1024;
+var ChronicleStorageQuotaError = class extends Error {
+  currentBytes;
+  batchBytes;
+  maxBytes;
+  path;
+  constructor(details) {
+    super(
+      `Chronicle SQLite quota exceeded at ${details.path}: ${details.currentBytes} live bytes + ${details.batchBytes} batch bytes exceeds ${details.maxBytes}; lower chronicle retentionDays/maxEvents to shed data (run chronicle compact to return the freed pages to the filesystem)`
+    );
+    this.name = "ChronicleStorageQuotaError";
+    this.currentBytes = details.currentBytes;
+    this.batchBytes = details.batchBytes;
+    this.maxBytes = details.maxBytes;
+    this.path = details.path;
+  }
+};
 var Ctor2;
 function loadDatabaseSync2() {
   if (Ctor2) return Ctor2;
@@ -3366,6 +3408,14 @@ var ChronicleSqliteJournal = class {
   now;
   monotonicNow;
   idFactory;
+  retentionDays;
+  maxEvents;
+  maxBytes;
+  retentionCheckIntervalMs;
+  nextRetentionCheckAt = 0;
+  retainedEventCount = 0;
+  /** Resolved lazily by `pageSizeBytes()`; constant for an open database. */
+  cachedPageSize;
   /**
    * Cached chain head per day. Cleared wholesale on any write failure so the
    * next append rebuilds from the database rather than trusting a counter that
@@ -3387,10 +3437,36 @@ var ChronicleSqliteJournal = class {
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
     this.monotonicNow = options.monotonicNow ?? (() => process.hrtime.bigint());
     this.idFactory = options.idFactory ?? (() => randomUUID3());
+    if (options.retentionDays !== void 0 && (!Number.isFinite(options.retentionDays) || options.retentionDays <= 0)) {
+      throw new RangeError("retentionDays must be a positive finite number");
+    }
+    if (options.retentionCheckIntervalMs !== void 0 && (!Number.isFinite(options.retentionCheckIntervalMs) || options.retentionCheckIntervalMs <= 0)) {
+      throw new RangeError("retentionCheckIntervalMs must be a positive finite number");
+    }
+    if (options.maxEvents !== void 0 && (!Number.isInteger(options.maxEvents) || options.maxEvents < 1)) {
+      throw new RangeError("maxEvents must be a positive integer");
+    }
+    if (options.maxBytes !== void 0 && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 1)) {
+      throw new RangeError("maxBytes must be a positive safe integer");
+    }
+    const minimumQuotaBytes = SQLITE_FIXED_OVERHEAD_BYTES + 2 * MIN_SQLITE_PAGE_BUDGET_BYTES;
+    if (options.maxBytes !== void 0 && options.maxBytes < minimumQuotaBytes) {
+      throw new RangeError(`maxBytes must be at least ${minimumQuotaBytes}`);
+    }
+    this.retentionDays = options.retentionDays;
+    this.maxEvents = options.maxEvents;
+    this.maxBytes = options.maxBytes;
+    this.retentionCheckIntervalMs = options.retentionCheckIntervalMs ?? 60 * 60 * 1e3;
     const Database = loadDatabaseSync2();
     this.db = new Database(this.dbPath);
-    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(`PRAGMA journal_mode = ${this.maxBytes === void 0 ? "WAL" : "DELETE"}`);
     this.ensureSchema();
+    this.configureByteQuota();
+    if (this.maxEvents !== void 0) {
+      const row = this.db.prepare("SELECT COUNT(*) AS count FROM events").get();
+      this.retainedEventCount = row.count;
+      this.enforceEventLimitAtStartup();
+    }
   }
   close() {
     this.db.close();
@@ -3449,8 +3525,10 @@ var ChronicleSqliteJournal = class {
       events.push(event);
       previous = { sequence: event.sequence, hash: event.hash };
     }
+    let retainedCountAfterCommit = this.retainedEventCount;
     try {
       this.db.exec("BEGIN IMMEDIATE");
+      this.assertWithinByteQuota(events);
       const insert = this.db.prepare(
         `INSERT INTO events (
            day, sequence, event_id, hash, previous_hash, occurred_at, event_type, outcome,
@@ -3482,6 +3560,8 @@ var ChronicleSqliteJournal = class {
           JSON.stringify(event)
         );
       }
+      retainedCountAfterCommit = this.enforceEventLimitWithinTransaction();
+      this.assertActualAllocationWithinQuota();
       this.db.exec("COMMIT");
     } catch (error) {
       try {
@@ -3491,11 +3571,13 @@ var ChronicleSqliteJournal = class {
       this.anchors.clear();
       this.counters.failedEvents += inputs.length;
       this.lastBatchDurationMs = performance.now() - started;
-      throw error;
+      throw this.normalizeQuotaError(error);
     }
     this.anchors.set(day, previous);
     this.counters.persistedEvents += events.length;
+    this.retainedEventCount = retainedCountAfterCommit;
     this.lastBatchDurationMs = performance.now() - started;
+    await this.enforceRetentionIfDue();
     return events;
   }
   async readAll() {
@@ -3556,6 +3638,145 @@ var ChronicleSqliteJournal = class {
     }
     return { ok: true, entries, lastSequence, lastHash };
   }
+  async enforceRetentionIfDue() {
+    if (this.retentionDays === void 0) return;
+    const now = this.now();
+    if (now.getTime() < this.nextRetentionCheckAt) return;
+    this.nextRetentionCheckAt = now.getTime() + this.retentionCheckIntervalMs;
+    try {
+      await this.purge({ retentionDays: this.retentionDays });
+    } catch {
+    }
+  }
+  configureByteQuota() {
+    if (this.maxBytes === void 0) {
+      this.db.exec("PRAGMA max_page_count = 2147483646");
+      return;
+    }
+    const halfSplit = Math.floor((this.maxBytes - SQLITE_FIXED_OVERHEAD_BYTES) / 2);
+    const journalReserve = Math.min(MAX_ROLLBACK_JOURNAL_RESERVE_BYTES, halfSplit);
+    const mainBudget = this.maxBytes - SQLITE_FIXED_OVERHEAD_BYTES - journalReserve;
+    if (mainBudget < MIN_SQLITE_PAGE_BUDGET_BYTES) {
+      throw new Error(
+        `maxBytes must be at least ${SQLITE_FIXED_OVERHEAD_BYTES + 2 * MIN_SQLITE_PAGE_BUDGET_BYTES}`
+      );
+    }
+    const maxPages = Math.max(1, Math.floor(mainBudget / this.pageSizeBytes()));
+    this.db.exec(`PRAGMA max_page_count = ${maxPages}`);
+  }
+  /**
+   * Bytes the journal actually occupies: live pages in the main database plus
+   * whatever the rollback/WAL sidecars currently hold.
+   *
+   * The quota MUST be measured this way rather than by `statSync` on the main
+   * database file. SQLite never returns freed pages to the filesystem — it
+   * parks them on the freelist and reuses them — so a database that once grew
+   * large keeps that size forever, even after retention and `maxEvents` have
+   * evicted almost everything. Measuring the file instead wedged the journal
+   * permanently: a 3.9 GB file whose live data was 243 MB failed a 512 MB
+   * quota on EVERY append, and the only escape (`chronicle compact`) refuses
+   * to run while the daemon is up — and the daemon respawns on demand. Live
+   * pages shrink when retention deletes rows, so the quota can recover on its
+   * own; allocated size cannot.
+   *
+   * The sidecars keep their on-disk size: they are transient and genuinely
+   * bounded by `configureByteQuota`'s half-of-budget split.
+   */
+  aggregateLiveBytes() {
+    let total = 0;
+    for (const file of [`${this.dbPath}-journal`, `${this.dbPath}-wal`, `${this.dbPath}-shm`]) {
+      try {
+        total += fs8.statSync(file).size;
+      } catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+      }
+    }
+    return total + this.mainDatabaseLiveBytes();
+  }
+  /** Live (non-freelist) pages of the main database, in bytes. */
+  mainDatabaseLiveBytes() {
+    const pageCount = Number(
+      this.db.prepare("PRAGMA page_count").get().page_count
+    );
+    const freelist = Number(
+      this.db.prepare("PRAGMA freelist_count").get().freelist_count
+    );
+    return Math.max(0, pageCount - freelist) * this.pageSizeBytes();
+  }
+  /** Page size never changes for an open database; resolve it once. */
+  pageSizeBytes() {
+    if (this.cachedPageSize === void 0) {
+      this.cachedPageSize = Number(
+        this.db.prepare("PRAGMA page_size").get().page_size
+      );
+    }
+    return this.cachedPageSize;
+  }
+  normalizeQuotaError(error) {
+    if (this.maxBytes === void 0 || !(error instanceof Error)) return error;
+    const sqliteError = error;
+    const quotaExhausted = sqliteError.code === "SQLITE_FULL" || sqliteError.code === 13 || sqliteError.errcode === 13 || /database or disk is full/i.test(sqliteError.message);
+    if (!quotaExhausted) return error;
+    return new ChronicleStorageQuotaError({
+      currentBytes: this.aggregateLiveBytes(),
+      batchBytes: 0,
+      maxBytes: this.maxBytes,
+      path: this.dbPath
+    });
+  }
+  assertActualAllocationWithinQuota() {
+    if (this.maxBytes === void 0) return;
+    const currentBytes = this.aggregateLiveBytes();
+    if (currentBytes <= this.maxBytes) return;
+    throw new ChronicleStorageQuotaError({
+      currentBytes,
+      batchBytes: 0,
+      maxBytes: this.maxBytes,
+      path: this.dbPath
+    });
+  }
+  assertWithinByteQuota(events) {
+    if (this.maxBytes === void 0) return;
+    const currentBytes = this.aggregateLiveBytes();
+    const batchBytes = Buffer.byteLength(JSON.stringify(events), "utf8");
+    if (currentBytes + batchBytes <= this.maxBytes) return;
+    throw new ChronicleStorageQuotaError({
+      currentBytes,
+      batchBytes,
+      maxBytes: this.maxBytes,
+      path: this.dbPath
+    });
+  }
+  enforceEventLimitWithinTransaction() {
+    const row = this.db.prepare("SELECT COUNT(*) AS count FROM events").get();
+    if (this.maxEvents === void 0 || row.count <= this.maxEvents) return row.count;
+    const excess = row.count - this.maxEvents;
+    const boundary = this.db.prepare("SELECT day, sequence, hash FROM events ORDER BY day, sequence LIMIT 1 OFFSET ?").get(excess - 1);
+    if (!boundary) return row.count;
+    this.db.prepare(
+      `INSERT INTO chain_checkpoint (day, sequence, hash) VALUES (?, ?, ?)
+         ON CONFLICT(day) DO UPDATE SET sequence = excluded.sequence, hash = excluded.hash`
+    ).run(boundary.day, boundary.sequence, boundary.hash);
+    this.db.prepare("DELETE FROM events WHERE day < ? OR (day = ? AND sequence <= ?)").run(boundary.day, boundary.day, boundary.sequence);
+    this.db.prepare("DELETE FROM chain_checkpoint WHERE day < ?").run(boundary.day);
+    this.anchors.clear();
+    return this.maxEvents;
+  }
+  enforceEventLimitAtStartup() {
+    if (this.maxEvents === void 0 || this.retainedEventCount <= this.maxEvents) return;
+    try {
+      this.db.exec("BEGIN IMMEDIATE");
+      const retainedCount = this.enforceEventLimitWithinTransaction();
+      this.db.exec("COMMIT");
+      this.retainedEventCount = retainedCount;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw error;
+    }
+  }
   /**
    * Drop events older than the retention window.
    *
@@ -3601,6 +3822,7 @@ var ChronicleSqliteJournal = class {
       };
     }
     this.anchors.clear();
+    this.retainedEventCount = Math.max(0, this.retainedEventCount - count);
     return { ...empty, deletedCount: count };
   }
   /**
@@ -3632,7 +3854,9 @@ var ChronicleSqliteJournal = class {
          ON CONFLICT(day) DO UPDATE SET sequence = excluded.sequence, hash = excluded.hash`
     );
     this.db.exec("BEGIN IMMEDIATE");
+    let retainedCountAfterCommit = this.retainedEventCount;
     try {
+      this.assertWithinByteQuota([]);
       await load({
         insert: (day, event) => {
           const row = projectEvent(event);
@@ -3662,16 +3886,19 @@ var ChronicleSqliteJournal = class {
           checkpoint.run(day, sequence, hash3);
         }
       });
+      retainedCountAfterCommit = this.enforceEventLimitWithinTransaction();
+      this.assertActualAllocationWithinQuota();
       this.db.exec("COMMIT");
     } catch (error) {
       try {
         this.db.exec("ROLLBACK");
       } catch {
       }
-      throw error;
+      throw this.normalizeQuotaError(error);
     } finally {
       this.anchors.clear();
     }
+    this.retainedEventCount = retainedCountAfterCommit;
   }
   /**
    * A read engine over this journal's own connection.
@@ -3827,7 +4054,7 @@ function projectEvent(event) {
 
 // src/chronicle/project-server-client.ts
 import { spawn } from "node:child_process";
-import * as fs8 from "node:fs";
+import * as fs9 from "node:fs";
 import * as net from "node:net";
 import * as path13 from "node:path";
 import { fileURLToPath } from "node:url";
@@ -3876,14 +4103,14 @@ var DEFAULT_CALL_TIMEOUT_MS = 3e4;
 var APPEND_CALL_TIMEOUT_MS = 6e4;
 var DEFAULT_BATCH_WINDOW_MS = 5;
 var DEFAULT_MAX_PENDING = 1e5;
-function resolveChronicleDaemonAvailability(moduleUrl = import.meta.url, exists = fs8.existsSync) {
+function resolveChronicleDaemonAvailability(moduleUrl = import.meta.url, exists = fs9.existsSync) {
   if (process.env["WRONGSTACK_CHRONICLE_INLINE"] || process.env["WRONGSTACK_CHRONICLE_SERVER"] === "0") {
     return { kind: "inline-requested" };
   }
   const url = locateChronicleProjectServer(moduleUrl, exists);
   return url ? { kind: "available", url } : { kind: "missing-build" };
 }
-function resolveChronicleProjectServerUrl(moduleUrl = import.meta.url, exists = fs8.existsSync) {
+function resolveChronicleProjectServerUrl(moduleUrl = import.meta.url, exists = fs9.existsSync) {
   const availability = resolveChronicleDaemonAvailability(moduleUrl, exists);
   return availability.kind === "available" ? availability.url : null;
 }
@@ -4052,7 +4279,7 @@ var ChronicleProjectServerClient = class {
   currentAuthToken() {
     if (this.authToken === void 0) {
       try {
-        const raw = fs8.readFileSync(
+        const raw = fs9.readFileSync(
           chronicleProjectServerMetadataPath(this.options.projectDir),
           "utf8"
         );
@@ -4596,6 +4823,63 @@ var InlineChronicleProjectAccess = class {
   }
 };
 
+// src/chronicle/sqlite-compaction.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, statSync as statSync3 } from "node:fs";
+import { createRequire as createRequire3 } from "node:module";
+var require2 = createRequire3(import.meta.url);
+var ChronicleCompactionBusyError = class extends Error {
+  constructor(pid) {
+    super(`Chronicle project server is still running (pid ${pid}); stop it before compacting`);
+    this.name = "ChronicleCompactionBusyError";
+  }
+};
+function chronicleSqliteAllocatedBytes(dbPath) {
+  return [dbPath, `${dbPath}-wal`, `${dbPath}-shm`].reduce((total, file) => {
+    try {
+      return total + statSync3(file).size;
+    } catch (error) {
+      if (error.code === "ENOENT") return total;
+      throw error;
+    }
+  }, 0);
+}
+function compactChronicleSqlite(options) {
+  assertProjectServerStopped(options.endpointMetadataPath);
+  const beforeBytes = chronicleSqliteAllocatedBytes(options.dbPath);
+  if (!existsSync2(options.dbPath)) {
+    return { beforeBytes, afterBytes: beforeBytes, reclaimedBytes: 0 };
+  }
+  const Database = withSqliteExperimentalWarningSuppressed(
+    () => require2("node:sqlite").DatabaseSync
+  );
+  const db = new Database(options.dbPath);
+  try {
+    db.exec("PRAGMA busy_timeout = 1");
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    db.exec("VACUUM");
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  } finally {
+    db.close();
+  }
+  const afterBytes = chronicleSqliteAllocatedBytes(options.dbPath);
+  return {
+    beforeBytes,
+    afterBytes,
+    reclaimedBytes: Math.max(0, beforeBytes - afterBytes)
+  };
+}
+function assertProjectServerStopped(endpointMetadataPath) {
+  if (!endpointMetadataPath || !existsSync2(endpointMetadataPath)) return;
+  try {
+    const metadata = JSON.parse(readFileSync3(endpointMetadataPath, "utf8"));
+    if (typeof metadata.pid === "number" && isPidAlive(metadata.pid)) {
+      throw new ChronicleCompactionBusyError(metadata.pid);
+    }
+  } catch (error) {
+    if (error instanceof ChronicleCompactionBusyError) throw error;
+  }
+}
+
 // src/chronicle/provider-adapter.ts
 function wireProviderAttemptsToChronicle(options) {
   const seenToolManifests = /* @__PURE__ */ new Set();
@@ -5753,17 +6037,20 @@ export {
   CHRONICLE_PROJECT_SERVER_MAX_FRAME_CHARS,
   CHRONICLE_PROJECT_SERVER_PROTOCOL_VERSION,
   CHRONICLE_SCHEMA_VERSION,
+  ChronicleCompactionBusyError,
   ChronicleJournal,
   ChronicleMetricsStore,
   ChroniclePartitionRangeCache,
   ChronicleProjectServerClient,
   ChronicleQueryEngine,
   ChronicleRemoteJournal,
+  ChronicleStorageQuotaError,
   GENESIS_HASH,
   childChronicleContext,
   chronicleProjectServerEndpoint,
   chronicleProjectServerKey,
   chronicleProjectServerMetadataPath,
+  compactChronicleSqlite,
   createChronicleContext,
   createChronicleEventJournal,
   createChronicleProjectAccess,