@wrongstack/core 0.289.0 → 0.291.1

package/dist/chronicle/index.js

@@ -235,10 +235,10 @@ async function scanProject(root, excluded, maxHashBytes, onError) {
 }
 async function fingerprint(filePath, maxHashBytes) {
   try {
-    const stat3 = await fsp.stat(filePath);
-    if (!stat3.isFile()) return void 0;
-    const base = { size: stat3.size, mtimeMs: stat3.mtimeMs };
-    if (stat3.size <= maxHashBytes) {
+    const stat5 = await fsp.stat(filePath);
+    if (!stat5.isFile()) return void 0;
+    const base = { size: stat5.size, mtimeMs: stat5.mtimeMs };
+    if (stat5.size <= maxHashBytes) {
       base.hash = createHash2("sha256").update(await fsp.readFile(filePath)).digest("hex");
     }
     return base;
@@ -271,6 +271,7 @@ import * as fs3 from "node:fs/promises";
 import * as path4 from "node:path";
 
 // src/utils/atomic-write.ts
+import { randomBytes } from "node:crypto";
 import * as fs2 from "node:fs/promises";
 import { watch as watchDir } from "node:fs";
 import * as path3 from "node:path";
@@ -378,6 +379,50 @@ var FsError = class extends WrongStackError {
 };
 
 // src/utils/atomic-write.ts
+async function atomicWrite(targetPath, content, opts = {}) {
+  const dir = path3.dirname(targetPath);
+  await fs2.mkdir(dir, { recursive: true });
+  const tmp = path3.join(dir, `.${path3.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    if (typeof content === "string") {
+      await fs2.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
+    } else {
+      await fs2.writeFile(tmp, content, { flag: "wx" });
+    }
+    try {
+      const fh = await fs2.open(tmp, "r+");
+      try {
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
+    } catch {
+    }
+    let mode;
+    try {
+      const stat5 = await fs2.stat(targetPath);
+      mode = stat5.mode & 511;
+    } catch {
+      mode = opts.mode;
+    }
+    if (mode !== void 0) {
+      await fs2.chmod(tmp, mode);
+    }
+    await renameWithRetry(tmp, targetPath);
+    if (mode !== void 0 && process.platform === "win32") {
+      try {
+        await fs2.chmod(targetPath, mode);
+      } catch {
+      }
+    }
+  } catch (err) {
+    try {
+      await fs2.unlink(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
 async function ensureDir(dir) {
   await fs2.mkdir(dir, { recursive: true });
 }
@@ -409,8 +454,8 @@ async function withFileLock(targetPath, fn, opts = {}) {
       }
       if (code !== "EEXIST" && code !== "EPERM") throw err;
       try {
-        const stat3 = await fs2.stat(lockPath);
-        if (Date.now() - stat3.mtimeMs > staleMs) {
+        const stat5 = await fs2.stat(lockPath);
+        if (Date.now() - stat5.mtimeMs > staleMs) {
           await fs2.unlink(lockPath);
           continue;
         }
@@ -486,50 +531,78 @@ async function waitForLockRelease(lockPath, remainingMs) {
     );
   });
 }
+var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
+async function renameWithRetry(from, to) {
+  if (process.platform !== "win32") {
+    await fs2.rename(from, to);
+    return;
+  }
+  const delays = [10, 25, 60, 120, 250];
+  let lastErr;
+  for (let i = 0; i <= delays.length; i++) {
+    try {
+      await fs2.rename(from, to);
+      return;
+    } catch (err) {
+      lastErr = err;
+      const code = err?.code;
+      if (!code || !TRANSIENT_RENAME_CODES.has(code) || i === delays.length) {
+        throw err;
+      }
+      await new Promise((resolve5) => setTimeout(resolve5, delays[i]));
+    }
+  }
+  throw lastErr;
+}
 
 // src/chronicle/types.ts
 var CHRONICLE_SCHEMA_VERSION = 1;
 
 // src/chronicle/journal.ts
 var GENESIS_HASH = "0".repeat(64);
+var DEFAULT_MAX_PARTITION_BYTES = 100 * 1024 * 1024;
+var DEFAULT_ROTATION_WINDOW_MS = 60 * 60 * 1e3;
+var RETENTION_CHECKPOINT_VERSION = 1;
 var ChronicleJournal = class {
-  filePath;
+  basePath;
   now;
   monotonicNow;
   idFactory;
   maxPending;
   batchWindowMs;
+  maxPartitionSizeBytes;
+  rotationWindowMs;
+  retentionDays;
+  autoPurgeIntervalMs;
   pending = [];
   drainPromise;
   drainScheduled = false;
   drainTimer;
-  counters = {
-    acceptedEvents: 0,
-    persistedEvents: 0,
-    rejectedEvents: 0,
-    failedEvents: 0,
-    batches: 0,
-    maxObservedPending: 0,
-    largestBatch: 0
-  };
+  counters = { acceptedEvents: 0, persistedEvents: 0, rejectedEvents: 0, failedEvents: 0, batches: 0, maxObservedPending: 0, largestBatch: 0, partitionRolls: 0 };
   lastBatchDurationMs;
+  partitionIndex = 0;
+  partitionStartedAt;
+  lastSequence = 0;
+  lastHash = GENESIS_HASH;
+  lastAutoPurgeAt = 0;
   constructor(options) {
-    this.filePath = path4.resolve(options.filePath);
+    this.basePath = path4.resolve(options.filePath);
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
     this.monotonicNow = options.monotonicNow ?? (() => process.hrtime.bigint());
     this.idFactory = options.idFactory ?? randomUUID2;
     this.maxPending = Math.max(1, options.maxPending ?? 1e5);
     this.batchWindowMs = Math.max(0, options.batchWindowMs ?? 5);
+    this.maxPartitionSizeBytes = options.maxPartitionSizeBytes ?? DEFAULT_MAX_PARTITION_BYTES;
+    this.rotationWindowMs = options.rotationWindowMs ?? DEFAULT_ROTATION_WINDOW_MS;
+    this.retentionDays = options.retentionDays && Number.isFinite(options.retentionDays) && options.retentionDays > 0 ? options.retentionDays : 0;
+    this.autoPurgeIntervalMs = Math.max(0, options.autoPurgeIntervalMs ?? 36e5);
+    this.partitionStartedAt = Date.now();
   }
   get path() {
-    return this.filePath;
+    return this.partitionIndex === 0 ? this.basePath : rotatedPath(this.basePath, this.partitionIndex);
   }
   stats() {
-    return {
-      ...this.counters,
-      pendingEvents: this.pending.length,
-      ...this.lastBatchDurationMs !== void 0 ? { lastBatchDurationMs: this.lastBatchDurationMs } : {}
-    };
+    return { ...this.counters, pendingEvents: this.pending.length, ...this.lastBatchDurationMs !== void 0 ? { lastBatchDurationMs: this.lastBatchDurationMs } : {} };
   }
   append(input) {
     if (this.pending.length >= this.maxPending) {
@@ -546,9 +619,11 @@ var ChronicleJournal = class {
   }
   async readAll() {
     await this.flush();
-    return readEntries(this.filePath);
+    const files = await collectPartitions(this.basePath);
+    const entries = [];
+    for (const file of files) entries.push(...await readEntriesStrict(file));
+    return entries;
   }
-  /** Wait until every append accepted by this process has settled. */
   async flush() {
     if (this.drainTimer) {
       clearTimeout(this.drainTimer);
@@ -562,33 +637,108 @@ var ChronicleJournal = class {
   }
   async verify() {
     await this.flush();
-    let entries;
-    try {
-      entries = await readEntries(this.filePath, true);
-    } catch (error) {
-      return { ok: false, entries: 0, brokenAt: 0, reason: errorMessage(error) };
+    const files = await collectPartitions(this.basePath);
+    const checkpointResult = await readRetentionCheckpoint(this.basePath);
+    if (checkpointResult.error) return { ok: false, entries: 0, brokenAt: 0, reason: checkpointResult.error };
+    return verifyPartitionFiles(files, checkpointResult.checkpoint);
+  }
+  async purge(options) {
+    await this.flush();
+    if (!Number.isFinite(options.retentionDays) || options.retentionDays <= 0) {
+      throw new TypeError("Chronicle retentionDays must be a positive finite number");
     }
-    let expectedPrevious = GENESIS_HASH;
-    for (let index = 0; index < entries.length; index++) {
-      const entry = entries[index];
-      if (entry.sequence !== index + 1) {
-        return { ok: false, entries: entries.length, brokenAt: index, reason: `sequence ${entry.sequence} is not ${index + 1}` };
+    await this.refreshStateFromDisk();
+    const cutoff = Date.now() - options.retentionDays * 864e5;
+    const activePath = path4.resolve(this.path);
+    const errors = [];
+    let dc = 0, db = 0, sc = 0;
+    const suppliedFiles = options.files === void 0 ? await collectJournalPartitions(this.basePath) : [...options.files];
+    const eligible = /* @__PURE__ */ new Set();
+    for (const suppliedPath of new Set(suppliedFiles)) {
+      const file = path4.resolve(suppliedPath);
+      if (!isJournalPartition(file, path4.dirname(this.basePath), this.basePath)) {
+        errors.push({ file: suppliedPath, reason: "not a Chronicle journal partition in this journal directory" });
+        sc++;
+        continue;
       }
-      if (entry.previousHash !== expectedPrevious) {
-        return { ok: false, entries: entries.length, brokenAt: index, reason: "previous hash mismatch" };
+      if (file === activePath) {
+        sc++;
+        continue;
       }
-      const { hash: recordedHash, ...content } = entry;
-      if (hashValue(content) !== recordedHash) {
-        return { ok: false, entries: entries.length, brokenAt: index, reason: "entry hash mismatch" };
+      let mtimeMs;
+      try {
+        const fileStat = await fs3.lstat(file);
+        if (!fileStat.isFile()) {
+          sc++;
+          continue;
+        }
+        mtimeMs = fileStat.mtimeMs;
+      } catch (error) {
+        if (isNotFound(error)) continue;
+        errors.push({ file, reason: errorMessage(error) });
+        sc++;
+        continue;
+      }
+      if (mtimeMs > cutoff) {
+        sc++;
+        continue;
       }
-      expectedPrevious = recordedHash;
+      eligible.add(file);
+    }
+    const candidates = [];
+    const allPartitions = await collectJournalPartitions(this.basePath);
+    for (const family of groupPartitionsByFamily(allPartitions).values()) {
+      for (const file of family) {
+        if (file === activePath || !eligible.has(file)) break;
+        candidates.push(file);
+        eligible.delete(file);
+      }
+    }
+    sc += eligible.size;
+    if (!options.dryRun) {
+      for (const file of candidates) {
+        try {
+          const familyBase = partitionFamilyBase(file);
+          let deletedBytes;
+          await withFileLock(familyBase, async () => {
+            const fileStat = await fs3.lstat(file);
+            if (!fileStat.isFile() || fileStat.mtimeMs > cutoff) return;
+            const entries = await readEntriesStrict(file);
+            const checkpointResult = await readRetentionCheckpoint(familyBase);
+            if (checkpointResult.error) throw new Error(checkpointResult.error);
+            const checkpoint = checkpointResult.checkpoint;
+            const nextCheckpoint = verifyRetainedPrefix(entries, checkpoint);
+            if (!nextCheckpoint) throw new Error("partition does not extend the trusted Chronicle chain");
+            if (nextCheckpoint.sequence > (checkpoint?.sequence ?? 0)) {
+              await writeRetentionCheckpoint(familyBase, nextCheckpoint);
+            }
+            deletedBytes = fileStat.size;
+            await fs3.unlink(file);
+          });
+          if (deletedBytes === void 0) {
+            sc++;
+            break;
+          }
+          db += deletedBytes;
+          dc++;
+        } catch (error) {
+          errors.push({ file, reason: errorMessage(error) });
+          sc++;
+          break;
+        }
+      }
+    }
+    return { deletedCount: dc, deletedBytes: db, skippedCount: sc, errors, ...options.dryRun ? { candidates } : {} };
+  }
+  async maybeAutoPurge() {
+    if (this.retentionDays <= 0) return;
+    const n = Date.now();
+    if (n - this.lastAutoPurgeAt < this.autoPurgeIntervalMs) return;
+    this.lastAutoPurgeAt = n;
+    try {
+      await this.purge({ retentionDays: this.retentionDays });
+    } catch {
     }
-    return {
-      ok: true,
-      entries: entries.length,
-      lastSequence: entries.at(-1)?.sequence ?? 0,
-      lastHash: entries.at(-1)?.hash ?? GENESIS_HASH
-    };
   }
   scheduleDrain() {
     if (this.drainScheduled || this.drainPromise) return;
@@ -608,45 +758,241 @@ var ChronicleJournal = class {
       if (this.pending.length > 0) this.scheduleDrain();
     });
   }
+  async refreshStateFromDisk() {
+    const files = await collectPartitions(this.basePath);
+    const latest = files[files.length - 1] ?? this.basePath;
+    this.partitionIndex = partitionIndex(latest, this.basePath);
+    const entry = await readLastEntry(latest);
+    const checkpointResult = await readRetentionCheckpoint(this.basePath);
+    if (checkpointResult.error) throw new Error(checkpointResult.error);
+    const checkpoint = checkpointResult.checkpoint;
+    this.lastSequence = entry?.sequence ?? checkpoint?.sequence ?? 0;
+    this.lastHash = entry?.hash ?? checkpoint?.hash ?? GENESIS_HASH;
+    try {
+      this.partitionStartedAt = (await fs3.stat(latest)).birthtimeMs;
+    } catch {
+      this.partitionStartedAt = Date.now();
+    }
+  }
+  async checkRotation() {
+    if (this.partitionIndex === 0 && this.lastSequence === 0) return;
+    if (Number.isFinite(this.rotationWindowMs) && Date.now() - this.partitionStartedAt >= this.rotationWindowMs) {
+      this.rotate();
+      return;
+    }
+    if (Number.isFinite(this.maxPartitionSizeBytes)) {
+      try {
+        if ((await fs3.stat(this.path)).size >= this.maxPartitionSizeBytes) this.rotate();
+      } catch {
+      }
+    }
+  }
+  rotate() {
+    this.partitionIndex++;
+    this.partitionStartedAt = Date.now();
+    this.counters.partitionRolls++;
+  }
   async persistBatch(batch) {
     const started = performance.now();
     this.counters.batches++;
     this.counters.largestBatch = Math.max(this.counters.largestBatch, batch.length);
     try {
-      await ensureDir(path4.dirname(this.filePath));
+      await ensureDir(path4.dirname(this.basePath));
       let recorded = [];
-      await withFileLock(this.filePath, async () => {
-        let previous = await readLastEntry(this.filePath);
+      await withFileLock(this.basePath, async () => {
+        await this.refreshStateFromDisk();
+        await this.checkRotation();
+        const cp = this.path;
+        let prev = this.lastSequence > 0 ? { sequence: this.lastSequence, hash: this.lastHash } : void 0;
         recorded = batch.map(({ input }) => {
           const instant = this.now().toISOString();
-          const normalizedInput = removeUndefined(input);
-          const unhashed = {
-            ...normalizedInput,
-            occurredAt: input.occurredAt ?? instant,
-            monotonicNs: input.monotonicNs ?? this.monotonicNow().toString(),
-            schemaVersion: CHRONICLE_SCHEMA_VERSION,
-            eventId: this.idFactory(),
-            observedAt: instant,
-            persistedAt: instant,
-            sequence: (previous?.sequence ?? 0) + 1,
-            previousHash: previous?.hash ?? GENESIS_HASH
-          };
-          const event = { ...unhashed, hash: hashValue(unhashed) };
-          previous = event;
+          const ni = removeUndefined(input);
+          const uh = { ...ni, occurredAt: input.occurredAt ?? instant, monotonicNs: input.monotonicNs ?? this.monotonicNow().toString(), schemaVersion: CHRONICLE_SCHEMA_VERSION, eventId: this.idFactory(), observedAt: instant, persistedAt: instant, sequence: (prev?.sequence ?? 0) + 1, previousHash: prev?.hash ?? GENESIS_HASH };
+          const event = { ...uh, hash: hashValue(uh) };
+          prev = event;
           return event;
         });
-        await fs3.appendFile(this.filePath, recorded.map((event) => JSON.stringify(event)).join("\n") + "\n", "utf8");
+        await fs3.appendFile(cp, recorded.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf8");
+      });
+      const last = recorded[recorded.length - 1];
+      this.lastSequence = last.sequence;
+      this.lastHash = last.hash;
+      batch.forEach((item, i) => {
+        item.resolve(recorded[i]);
       });
-      batch.forEach((item, index) => item.resolve(recorded[index]));
       this.counters.persistedEvents += batch.length;
+      void this.maybeAutoPurge();
     } catch (error) {
       this.counters.failedEvents += batch.length;
-      batch.forEach((item) => item.reject(error));
+      batch.forEach((item) => {
+        item.reject(error);
+      });
     } finally {
       this.lastBatchDurationMs = performance.now() - started;
     }
   }
 };
+function rotatedPath(basePath, index) {
+  const dir = path4.dirname(basePath);
+  const ext = path4.extname(basePath);
+  const base = path4.basename(basePath, ext);
+  return path4.join(dir, `${base}.${String(index).padStart(5, "0")}${ext}`);
+}
+async function collectPartitions(basePath) {
+  const dir = path4.dirname(basePath);
+  const ext = path4.extname(basePath);
+  const base = path4.basename(basePath, ext);
+  const pattern = new RegExp(`^${escapeRegex(base)}(?:\\.\\d{5})?${escapeRegex(ext)}$`);
+  const result = [];
+  try {
+    const entries = await fs3.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) if (entry.isFile() && pattern.test(entry.name)) result.push(path4.join(dir, entry.name));
+  } catch {
+  }
+  const baseFile = path4.join(dir, base + ext);
+  const rotated = result.filter((file) => file !== baseFile).sort((left, right) => parseIndex(left, base, ext) - parseIndex(right, base, ext));
+  return [baseFile, ...rotated];
+}
+async function collectJournalPartitions(basePath) {
+  const directory = path4.dirname(basePath);
+  const result = [];
+  try {
+    const entries = await fs3.readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const file = path4.join(directory, entry.name);
+      if (entry.isFile() && isJournalPartition(file, directory, basePath)) result.push(file);
+    }
+  } catch {
+  }
+  return result.sort(compareJournalPartitions);
+}
+function isJournalPartition(filePath, directory, basePath) {
+  if (path4.dirname(path4.resolve(filePath)) !== path4.resolve(directory)) return false;
+  const fileName = path4.basename(filePath);
+  if (!basePath) return false;
+  const baseName = path4.basename(basePath);
+  const dailyFamily = /^\d{4}-\d{2}-\d{2}\.events(?:\.\d{5})?\.jsonl$/;
+  if (/^\d{4}-\d{2}-\d{2}\.events\.jsonl$/.test(baseName)) return dailyFamily.test(fileName);
+  return partitionFamilyBase(path4.resolve(filePath)) === partitionFamilyBase(path4.resolve(basePath));
+}
+function compareJournalPartitions(left, right) {
+  const pattern = /^(.*\.events)(?:\.(\d{5}))?\.jsonl$/;
+  const leftMatch = pattern.exec(path4.basename(left));
+  const rightMatch = pattern.exec(path4.basename(right));
+  const familyOrder = (leftMatch?.[1] ?? left).localeCompare(rightMatch?.[1] ?? right);
+  return familyOrder || Number(leftMatch?.[2] ?? 0) - Number(rightMatch?.[2] ?? 0);
+}
+function groupPartitionsByFamily(files) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const family = partitionFamilyBase(file);
+    const group = groups.get(family) ?? [];
+    group.push(file);
+    groups.set(family, group);
+  }
+  return groups;
+}
+function partitionFamilyBase(filePath) {
+  return filePath.replace(/\.\d{5}(?=\.jsonl$)/, "");
+}
+function retentionCheckpointPath(basePath) {
+  return `${partitionFamilyBase(basePath)}.retention.json`;
+}
+function verifyRetainedPrefix(entries, checkpoint) {
+  if (entries.length === 0) return void 0;
+  let sequence = checkpoint?.sequence ?? 0;
+  let hash3 = checkpoint?.hash ?? GENESIS_HASH;
+  let advanced = false;
+  for (const entry of entries) {
+    if (entry.sequence <= sequence) continue;
+    if (entry.sequence !== sequence + 1 || entry.previousHash !== hash3) return void 0;
+    const { hash: recordedHash, ...content } = entry;
+    if (hashValue(content) !== recordedHash) return void 0;
+    sequence = entry.sequence;
+    hash3 = recordedHash;
+    advanced = true;
+  }
+  if (!advanced) return checkpoint;
+  return { version: RETENTION_CHECKPOINT_VERSION, sequence, hash: hash3 };
+}
+async function verifyPartitionFiles(files, checkpoint) {
+  const checkpointSequence = checkpoint?.sequence ?? 0;
+  let previousHash = checkpoint?.hash ?? GENESIS_HASH;
+  let entries = 0;
+  let lastSequence = checkpointSequence;
+  let coveredPrevious;
+  for (const file of files) {
+    let chunk;
+    try {
+      chunk = await readEntriesStrict(file);
+    } catch (error) {
+      return { ok: false, entries, brokenAt: entries, reason: errorMessage(error) };
+    }
+    for (const entry of chunk) {
+      const { hash: recordedHash, ...content } = entry;
+      if (entry.sequence <= checkpointSequence) {
+        if (hashValue(content) !== recordedHash) return { ok: false, entries, brokenAt: entries, reason: "entry hash mismatch" };
+        if (coveredPrevious && entry.sequence !== coveredPrevious.sequence + 1) {
+          return { ok: false, entries, brokenAt: entries, reason: `sequence ${entry.sequence} is not ${coveredPrevious.sequence + 1}` };
+        }
+        if (coveredPrevious && entry.previousHash !== coveredPrevious.hash) {
+          return { ok: false, entries, brokenAt: entries, reason: "previous hash mismatch" };
+        }
+        if (entry.sequence === checkpointSequence && recordedHash !== checkpoint?.hash) {
+          return { ok: false, entries, brokenAt: entries, reason: "retention checkpoint hash mismatch" };
+        }
+        coveredPrevious = entry;
+        continue;
+      }
+      const index = entries++;
+      if (entry.sequence !== lastSequence + 1) return { ok: false, entries, brokenAt: index, reason: `sequence ${entry.sequence} is not ${lastSequence + 1}` };
+      if (entry.previousHash !== previousHash) return { ok: false, entries, brokenAt: index, reason: "previous hash mismatch" };
+      if (hashValue(content) !== recordedHash) return { ok: false, entries, brokenAt: index, reason: "entry hash mismatch" };
+      previousHash = recordedHash;
+      lastSequence = entry.sequence;
+    }
+  }
+  if (coveredPrevious && (coveredPrevious.sequence !== checkpointSequence || coveredPrevious.hash !== checkpoint?.hash)) {
+    return { ok: false, entries, brokenAt: entries, reason: "retention checkpoint hash mismatch" };
+  }
+  return { ok: true, entries, lastSequence, lastHash: previousHash };
+}
+async function readRetentionCheckpoint(basePath) {
+  const checkpointPath = retentionCheckpointPath(basePath);
+  let raw;
+  try {
+    raw = await fs3.readFile(checkpointPath, "utf8");
+  } catch (error) {
+    return isNotFound(error) ? {} : { error: `cannot read retention checkpoint: ${errorMessage(error)}` };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== RETENTION_CHECKPOINT_VERSION || !Number.isSafeInteger(parsed.sequence) || (parsed.sequence ?? -1) < 0 || !isHash(parsed.hash)) {
+      return { error: "invalid Chronicle retention checkpoint" };
+    }
+    return { checkpoint: parsed };
+  } catch {
+    return { error: "invalid Chronicle retention checkpoint JSON" };
+  }
+}
+async function writeRetentionCheckpoint(basePath, checkpoint) {
+  await atomicWrite(retentionCheckpointPath(basePath), `${JSON.stringify(checkpoint)}
+`, { mode: 384 });
+}
+function isHash(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function parseIndex(filePath, base, ext) {
+  const suffix = path4.basename(filePath).slice(base.length + 1, -ext.length);
+  return suffix ? parseInt(suffix, 10) : 0;
+}
+function partitionIndex(filePath, basePath) {
+  const ext = path4.extname(basePath);
+  return parseIndex(filePath, path4.basename(basePath, ext), ext);
+}
+function escapeRegex(text2) {
+  return text2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 async function readLastEntry(filePath) {
   let handle;
   try {
@@ -657,22 +1003,20 @@ async function readLastEntry(filePath) {
   }
   try {
     const size = (await handle.stat()).size;
-    const chunkSize = 64 * 1024;
-    let position = size;
-    let suffix = "";
+    let position = size, suffix = "";
     while (position > 0) {
-      const length = Math.min(chunkSize, position);
+      const length = Math.min(65536, position);
       position -= length;
-      const buffer = Buffer.allocUnsafe(length);
-      await handle.read(buffer, 0, length, position);
-      suffix = buffer.toString("utf8") + suffix;
+      const buf = Buffer.allocUnsafe(length);
+      await handle.read(buf, 0, length, position);
+      suffix = buf.toString("utf8") + suffix;
       const lines = suffix.split("\n");
-      const first = position === 0 ? 0 : 1;
-      for (let index = lines.length - 1; index >= first; index--) {
-        const line = lines[index].trim();
-        if (!line) continue;
+      const start = position === 0 ? 0 : 1;
+      for (let i = lines.length - 1; i >= start; i--) {
+        const trimmed = lines[i].trim();
+        if (!trimmed) continue;
         try {
-          return JSON.parse(line);
+          return JSON.parse(trimmed);
         } catch {
         }
       }
@@ -683,7 +1027,7 @@ async function readLastEntry(filePath) {
     await handle.close();
   }
 }
-async function readEntries(filePath, strict = false) {
+async function readEntriesStrict(filePath) {
   let raw;
   try {
     raw = await fs3.readFile(filePath, "utf8");
@@ -692,12 +1036,14 @@ async function readEntries(filePath, strict = false) {
     throw error;
   }
   const entries = [];
-  for (const [index, line] of raw.split("\n").entries()) {
-    if (!line.trim()) continue;
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed) continue;
     try {
-      entries.push(JSON.parse(line));
-    } catch (error) {
-      if (strict) throw new Error(`invalid JSON at line ${index + 1}: ${errorMessage(error)}`);
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      throw new Error(`invalid JSON at line ${i + 1} in ${path4.basename(filePath)}`);
     }
   }
   return entries;
@@ -708,16 +1054,14 @@ function hashValue(value) {
 function stableStringify(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-  const object = value;
-  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+  const obj = value;
+  return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
 }
 function removeUndefined(value) {
   if (Array.isArray(value)) return value.map((item) => item === void 0 ? null : removeUndefined(item));
   if (value === null || typeof value !== "object") return value;
   const result = {};
-  for (const [key, item] of Object.entries(value)) {
-    if (item !== void 0) result[key] = removeUndefined(item);
-  }
+  for (const [key, item] of Object.entries(value)) if (item !== void 0) result[key] = removeUndefined(item);
   return result;
 }
 function isNotFound(error) {
@@ -748,7 +1092,9 @@ function wireProviderAttemptsToChronicle(options) {
       durationNs: millisecondsToNanoseconds(event.durationMs)
     }))
   ];
-  return () => unsubs.forEach((unsubscribe) => unsubscribe());
+  return () => unsubs.forEach((unsubscribe) => {
+    unsubscribe();
+  });
 }
 function persist(options, event, base) {
   const context = typeof options.context === "function" ? options.context() : options.context;
@@ -803,6 +1149,25 @@ function wireToolsToChronicle(options) {
         }
       });
     }),
+    options.events.on("permission.evaluated", (event) => {
+      persist2(options, event, {
+        eventType: "permission.evaluated",
+        outcome: event.effectiveDecision === "deny" ? "denied" : "success",
+        attributes: {
+          toolName: event.name,
+          inputHash: event.inputHash,
+          policyDecision: event.policyDecision,
+          effectiveDecision: event.effectiveDecision,
+          decisionSource: event.decisionSource,
+          reason: event.reason ? options.scrubber.scrub(event.reason) : void 0,
+          riskTier: event.riskTier,
+          yoloEnabled: event.yoloEnabled,
+          boundaryDecision: event.boundaryDecision,
+          boundaryReason: event.boundaryReason ? options.scrubber.scrub(event.boundaryReason) : void 0,
+          capabilityDowngraded: event.capabilityDowngraded
+        }
+      });
+    }),
     options.events.on("tool.executed", (event) => {
       const output = options.scrubber.scrub(event.output ?? "");
       persist2(options, event, {
@@ -853,7 +1218,9 @@ function wireToolsToChronicle(options) {
       });
     })
   ];
-  return () => unsubs.forEach((unsubscribe) => unsubscribe());
+  return () => unsubs.forEach((unsubscribe) => {
+    unsubscribe();
+  });
 }
 function persist2(options, event, fields) {
   const context = typeof options.context === "function" ? options.context() : options.context;
@@ -958,7 +1325,9 @@ function wireProcessesToChronicle(options) {
       }
     }))
   ];
-  return () => unsubs.forEach((unsubscribe) => unsubscribe());
+  return () => unsubs.forEach((unsubscribe) => {
+    unsubscribe();
+  });
 }
 function persist3(options, event, fields) {
   const context = typeof options.context === "function" ? options.context() : options.context;
@@ -1086,7 +1455,9 @@ function wireDecisionsToChronicle(options) {
     options.events.on("brain.human_answered", (e) => write("decision.human_answered", e.at, e.sessionId, e.id, { resolver: "human", optionId: e.optionId, denied: e.deny ?? false, answerHash: hash(e.text) }, e.deny ? "denied" : "success")),
     options.events.on("brain.outcome", (e) => write("decision.outcome_observed", e.at, e.sessionId, e.requestId, { observedOutcome: e.outcome, detailHash: hash(e.detail) }, e.outcome))
   ];
-  return () => offs.forEach((off) => off());
+  return () => offs.forEach((off) => {
+    off();
+  });
 }
 function hash(value) {
   return value ? createHash6("sha256").update(value).digest("hex") : void 0;
@@ -1116,6 +1487,9 @@ var CODING_SIGNAL = [
 ];
 var SENSITIVE_KEY = /(content|text|prompt|question|rationale|reason|detail|summary|description|context|input|output|error|message|secret|token|password|key)$/i;
 var PRESERVE_STRING_KEY = /(^|_)(id|status|state|kind|type|source|model|provider|phase|risk|fallback|path|name|role|sha|branch|mode)$/i;
+var TRUNCATED_ARRAYS = /* @__PURE__ */ new Set(["recentMail", "recentTools", "recentCommands"]);
+var TRUNCATED_ARRAY_MAX = 5;
+var DEFAULT_ARRAY_MAX = 20;
 function wireDomainEventsToChronicle(options) {
   return options.events.onAny((eventName, payload) => {
     if (SPECIALIZED.some((pattern) => pattern.test(eventName))) return;
@@ -1197,8 +1571,9 @@ function sanitize(value, key = "", depth = 0, seen = /* @__PURE__ */ new WeakSet
   if (depth >= 5) return { hash: digest(safeString(value)), depthLimited: true };
   seen.add(value);
   if (Array.isArray(value)) {
-    const items = value.slice(0, 100).map((item) => sanitize(item, key, depth + 1, seen));
-    return value.length > 100 ? { items, total: value.length, truncated: true } : items;
+    const cap = TRUNCATED_ARRAYS.has(key) ? TRUNCATED_ARRAY_MAX : DEFAULT_ARRAY_MAX;
+    const items = value.slice(0, cap).map((item) => sanitize(item, key, depth + 1, seen));
+    return value.length > cap ? { items, total: value.length, truncated: true } : items;
   }
   const output = {};
   const entries = Object.entries(value);
@@ -1291,7 +1666,9 @@ function wireProviderStreamsToChronicle(options) {
   ];
   return () => {
     for (const state of [...states.values()]) flush(state.sessionId, state.agentId, "failure");
-    offs.forEach((off) => off());
+    offs.forEach((off) => {
+      off();
+    });
   };
 }
 
@@ -1527,7 +1904,9 @@ function wireRollupsToChronicle(options) {
   return () => {
     clearInterval(timer);
     for (const key of [...buckets.keys()]) flush(key);
-    offs.forEach((off) => off());
+    offs.forEach((off) => {
+      off();
+    });
   };
 }
 function text(value) {
@@ -1542,94 +1921,166 @@ function safeDigest(value) {
 }
 
 // src/chronicle/query.ts
+import { createHash as createHash11 } from "node:crypto";
+import { createReadStream } from "node:fs";
 import * as fs4 from "node:fs/promises";
 import * as path5 from "node:path";
+import { createInterface } from "node:readline";
+var MAX_CURSOR_SNAPSHOT_ENTRIES = 1e4;
+function streamLines(filePath, maxBytes) {
+  const stream = createReadStream(filePath, {
+    encoding: "utf8",
+    highWaterMark: 256 * 1024,
+    ...maxBytes !== void 0 ? { end: maxBytes - 1 } : {}
+  });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  return rl[Symbol.asyncIterator]();
+}
 var ChronicleQueryEngine = class _ChronicleQueryEngine {
-  constructor(events, diagnostics) {
-    this.events = events;
+  constructor(files, diagnostics) {
     this.diagnostics = diagnostics;
+    this.partitionFiles = files;
   }
-  events;
   diagnostics;
+  partitionFiles;
   static async fromDirectory(directory) {
-    return _ChronicleQueryEngine.fromFiles(await findPartitions(path5.resolve(directory)));
+    const files = await findPartitions(path5.resolve(directory));
+    return new _ChronicleQueryEngine(files, { sourceFiles: files.length, invalidLines: 0 });
   }
   static async fromFiles(files) {
-    const events = [];
+    return new _ChronicleQueryEngine(files, { sourceFiles: files.length, invalidLines: 0 });
+  }
+  /** Stream all partitions, filter, and return the requested page + summary. */
+  async query(query = {}) {
+    const order = query.order ?? "desc";
+    const limit = Math.max(1, Math.min(query.limit ?? 100, 1e4));
+    const queryHash = hashQuery(query);
+    const cursor = decodeCursor(query.cursor, order, queryHash);
+    const snapshotFiles = cursor ? await resolveSnapshotFiles(this.partitionFiles, cursor.snapshot) : await captureSnapshot(this.partitionFiles);
+    const files = order === "asc" ? snapshotFiles : snapshotFiles.slice().reverse();
+    const summaryAcc = createSummaryAccumulator();
+    const orderedCandidates = [];
+    const pageOrder = (left, right) => compareEvents(left, right) * (order === "asc" ? 1 : -1);
+    let totalCount = 0;
+    let remainingCount = 0;
+    let scannedEvents = 0;
     let invalidLines = 0;
-    for (const file of files) {
-      let raw;
+    for (const snapshotFile of files) {
       try {
-        raw = await fs4.readFile(file, "utf8");
-      } catch {
-        continue;
-      }
-      for (const line of raw.split("\n")) {
-        if (!line.trim()) continue;
-        try {
-          const parsed = JSON.parse(line);
-          if (isChronicleEvent(parsed)) events.push(parsed);
-          else invalidLines++;
-        } catch {
-          invalidLines++;
+        if (snapshotFile.size === 0) continue;
+        const lines = order === "asc" ? streamLines(snapshotFile.file, snapshotFile.size) : reverseLines(snapshotFile.file, snapshotFile.size);
+        for await (const line of lines) {
+          if (!line.trim()) continue;
+          let event;
+          try {
+            event = JSON.parse(line);
+            if (!isChronicleEvent(event)) {
+              invalidLines++;
+              continue;
+            }
+          } catch {
+            invalidLines++;
+            continue;
+          }
+          scannedEvents++;
+          if (!matches(event, query)) continue;
+          totalCount++;
+          updateSummary(summaryAcc, event);
+          if (cursor && compareEventToKey(event, cursor.after) * (order === "asc" ? 1 : -1) <= 0) {
+            continue;
+          }
+          remainingCount++;
+          const insertionIndex = findInsertionIndex(orderedCandidates, event, pageOrder);
+          if (insertionIndex < limit) {
+            orderedCandidates.splice(insertionIndex, 0, event);
+            if (orderedCandidates.length > limit) orderedCandidates.pop();
+          }
         }
+      } catch {
       }
     }
-    return new _ChronicleQueryEngine(events, { sourceFiles: files.length, invalidLines });
-  }
-  query(query = {}) {
-    const order = query.order ?? "desc";
-    const found = this.events.filter((event) => matches(event, query));
-    found.sort((a, b) => compareEvents(a, b) * (order === "asc" ? 1 : -1));
-    const offset = decodeCursor(query.cursor);
-    const limit = Math.max(1, Math.min(query.limit ?? 100, 1e4));
-    const events = found.slice(offset, offset + limit);
-    const nextOffset = offset + events.length;
+    const pageEvents = orderedCandidates;
+    const lastEvent = pageEvents.at(-1);
     return {
-      events,
-      total: found.length,
-      summary: summarize(found),
-      ...nextOffset < found.length ? { nextCursor: encodeCursor(nextOffset) } : {},
-      scannedEvents: this.events.length,
-      sourceFiles: this.diagnostics.sourceFiles,
-      invalidLines: this.diagnostics.invalidLines
+      events: pageEvents,
+      total: totalCount,
+      summary: finalizeSummary(summaryAcc),
+      ...lastEvent && pageEvents.length < remainingCount ? { nextCursor: encodeCursor({
+        version: 1,
+        order,
+        queryHash,
+        after: orderKey(lastEvent),
+        snapshot: snapshotFiles.map(({ id, size }) => ({ id, size }))
+      }) } : {},
+      scannedEvents,
+      sourceFiles: snapshotFiles.length,
+      invalidLines
     };
   }
-  facet(field, query = {}, limit = 100) {
+  /** Stream all partitions and compute facet value counts. */
+  async facet(field, query = {}, limit = 100) {
     const counts = /* @__PURE__ */ new Map();
-    for (const event of this.events) {
-      if (!matches(event, query)) continue;
-      const value = facetValue(event, field);
-      if (value !== void 0) counts.set(value, (counts.get(value) ?? 0) + 1);
+    let invalidLines = 0;
+    for (const file of this.partitionFiles) {
+      try {
+        for await (const line of streamLines(file)) {
+          if (!line.trim()) continue;
+          let event;
+          try {
+            event = JSON.parse(line);
+            if (!isChronicleEvent(event)) {
+              invalidLines++;
+              continue;
+            }
+          } catch {
+            invalidLines++;
+            continue;
+          }
+          if (!matches(event, query)) continue;
+          const value = facetValue(event, field);
+          if (value !== void 0) counts.set(value, (counts.get(value) ?? 0) + 1);
+        }
+      } catch {
+      }
     }
+    this.diagnostics.invalidLines = invalidLines;
     return [...counts].map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count || a.value.localeCompare(b.value)).slice(0, Math.max(0, limit));
   }
   /** Expand explicit and typed correlation edges; temporal proximity alone never creates causality. */
-  graph(seed, hops = 2, maxNodes = 1e3) {
-    const seeds = this.events.filter((event) => matches(event, seed));
-    const byKey = /* @__PURE__ */ new Map();
-    for (const event of this.events) for (const key of relationKeys(event)) {
-      const values = byKey.get(key.key) ?? [];
-      values.push(event);
-      byKey.set(key.key, values);
+  async graph(seed = {}, hops = 2, maxNodes = 1e3) {
+    const nodeLimit = Math.max(0, Math.floor(maxNodes));
+    const selected = /* @__PURE__ */ new Map();
+    let seedCount = 0;
+    for await (const event of streamEvents(this.partitionFiles)) {
+      if (!matches(event, seed)) continue;
+      seedCount++;
+      if (selected.size < nodeLimit) selected.set(event.eventId, event);
     }
-    const selected = new Map(seeds.slice(0, maxNodes).map((event) => [event.eventId, event]));
     let frontier = [...selected.values()];
-    for (let depth = 0; depth < Math.max(0, Math.min(hops, 10)) && frontier.length > 0 && selected.size < maxNodes; depth++) {
+    const depthLimit = Math.max(0, Math.min(hops, 10));
+    for (let depth = 0; depth < depthLimit && frontier.length > 0 && selected.size < nodeLimit; depth++) {
+      const frontierKeys = new Set(frontier.flatMap((event) => relationKeys(event).map((relation) => relation.key)));
       const next = [];
-      for (const event of frontier) for (const relation of relationKeys(event)) for (const candidate of byKey.get(relation.key) ?? []) {
-        if (!selected.has(candidate.eventId) && selected.size < maxNodes) {
-          selected.set(candidate.eventId, candidate);
-          next.push(candidate);
-        }
+      for await (const event of streamEvents(this.partitionFiles)) {
+        if (selected.has(event.eventId)) continue;
+        if (!relationKeys(event).some((relation) => frontierKeys.has(relation.key))) continue;
+        selected.set(event.eventId, event);
+        next.push(event);
+        if (selected.size >= nodeLimit) break;
       }
       frontier = next;
     }
     const nodes = [...selected.values()].sort(compareEvents);
+    const byKey = /* @__PURE__ */ new Map();
+    for (const node of nodes) for (const relation of relationKeys(node)) {
+      const related = byKey.get(relation.key) ?? [];
+      related.push(node);
+      byKey.set(relation.key, related);
+    }
     const edges = [];
     const seen = /* @__PURE__ */ new Set();
     for (const node of nodes) for (const relation of relationKeys(node)) for (const candidate of byKey.get(relation.key) ?? []) {
-      if (!selected.has(candidate.eventId) || candidate.eventId === node.eventId) continue;
+      if (candidate.eventId === node.eventId) continue;
       const [from, to] = compareEvents(node, candidate) <= 0 ? [node, candidate] : [candidate, node];
       const id = `${from.eventId}:${to.eventId}:${relation.kind}`;
       if (!seen.has(id)) {
@@ -1637,87 +2088,241 @@ var ChronicleQueryEngine = class _ChronicleQueryEngine {
         edges.push({ from: from.eventId, to: to.eventId, kind: relation.kind, confidence: relation.confidence });
       }
     }
-    return { nodes, edges, truncated: seeds.length > maxNodes || selected.size >= maxNodes };
+    return { nodes, edges, truncated: seedCount > nodeLimit || selected.size >= nodeLimit };
   }
 };
-function summarize(events) {
-  const ofType = (type) => events.filter((event) => event.eventType === type);
-  const unique = (values) => new Set(values.filter((value) => Boolean(value))).size;
-  const numberAt = (event, path6) => {
-    const value = readPath(event.attributes ?? {}, path6);
-    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+async function* streamEvents(files) {
+  for (const file of files) {
+    try {
+      for await (const line of streamLines(file)) {
+        if (!line.trim()) continue;
+        try {
+          const event = JSON.parse(line);
+          if (isChronicleEvent(event)) yield event;
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
+}
+async function* reverseLines(filePath, maxBytes) {
+  const CHUNK = 64 * 1024;
+  const NEWLINE = 10;
+  let handle;
+  try {
+    handle = await fs4.open(filePath, "r");
+  } catch {
+    return;
+  }
+  try {
+    const fileSize = (await handle.stat()).size;
+    const size = Math.min(fileSize, maxBytes ?? fileSize);
+    let position = size;
+    let suffix = Buffer.alloc(0);
+    while (position > 0) {
+      const length = Math.min(CHUNK, position);
+      position -= length;
+      const buffer = Buffer.allocUnsafe(length);
+      await handle.read(buffer, 0, length, position);
+      const data = suffix.length === 0 ? buffer : Buffer.concat([buffer, suffix]);
+      let lineEnd = data.length;
+      let firstNewline = -1;
+      for (let index = data.length - 1; index >= 0; index--) {
+        if (data[index] !== NEWLINE) continue;
+        const trimmed2 = data.subarray(index + 1, lineEnd).toString("utf8").trim();
+        if (trimmed2) yield trimmed2;
+        lineEnd = index;
+        firstNewline = index;
+      }
+      suffix = firstNewline >= 0 ? Buffer.from(data.subarray(0, firstNewline)) : data;
+    }
+    const trimmed = suffix.toString("utf8").trim();
+    if (trimmed) yield trimmed;
+  } finally {
+    await handle.close();
+  }
+}
+function createSummaryAccumulator() {
+  return {
+    logicalRequestIds: /* @__PURE__ */ new Set(),
+    modelAttempts: 0,
+    completedAttempts: 0,
+    failedAttempts: 0,
+    scheduledRetries: 0,
+    fallbacks: 0,
+    providers: /* @__PURE__ */ new Set(),
+    models: /* @__PURE__ */ new Set(),
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costByScope: /* @__PURE__ */ new Map(),
+    providerDurations: [],
+    toolCalls: 0,
+    completedTools: 0,
+    failedTools: 0,
+    toolDurations: [],
+    processes: 0,
+    failedProcesses: 0,
+    fileEvents: 0,
+    uniqueFiles: /* @__PURE__ */ new Set(),
+    agentEvents: 0,
+    uniqueAgents: /* @__PURE__ */ new Set(),
+    decisions: 0,
+    escalations: 0,
+    failures: 0,
+    cancellations: 0,
+    families: { llm: 0, agent: 0, tool: 0, file: 0, memory: 0, task: 0, decision: 0, runtime: 0 },
+    failuresByFamily: { llm: 0, agent: 0, tool: 0, file: 0, memory: 0, task: 0, decision: 0, runtime: 0 }
   };
-  const completedAttempts = ofType("provider.attempt.completed");
-  const failedAttempts = ofType("provider.attempt.failed");
-  const completedTools = ofType("tool.executed");
-  const failedTools = ofType("tool.failed");
-  const providerDurations = [...completedAttempts, ...failedAttempts].map(durationMs).filter((value) => value > 0).sort((a, b) => a - b);
-  const toolDurations = [...completedTools, ...failedTools].map(durationMs).filter((value) => value > 0);
-  const files = events.filter((event) => event.resource?.kind === "file" || event.eventType.startsWith("file."));
-  const failedProcesses = ofType("process.completed").filter((event) => event.outcome === "failure").length;
-  const latestAccounted = latestByScope(ofType("token.accounted"));
-  const families = familyCounts(events);
-  const terminalFailures = events.filter(isTerminalFailure);
+}
+function updateSummary(acc, event) {
+  const family = signalFamily(event);
+  acc.families[family]++;
+  if (isTerminalFailure(event)) acc.failuresByFamily[family]++;
+  if (event.correlation.logicalRequestId) acc.logicalRequestIds.add(event.correlation.logicalRequestId);
+  if (event.runtime?.providerId) acc.providers.add(event.runtime.providerId);
+  if (event.runtime?.modelId) acc.models.add(event.runtime.modelId);
+  if (event.eventType === "provider.attempt.started") acc.modelAttempts++;
+  else if (event.eventType === "provider.attempt.completed") {
+    acc.completedAttempts++;
+    acc.inputTokens += numberAt(event, "usage.input");
+    acc.outputTokens += numberAt(event, "usage.output");
+    acc.cacheReadTokens += numberAt(event, "usage.cacheRead");
+    acc.cacheWriteTokens += numberAt(event, "usage.cacheWrite");
+    const dur = durationMs(event);
+    if (dur > 0) acc.providerDurations.push(dur);
+  } else if (event.eventType === "provider.attempt.failed") {
+    acc.failedAttempts++;
+    if (event.attributes?.retryScheduled === true) acc.scheduledRetries++;
+    const dur = durationMs(event);
+    if (dur > 0) acc.providerDurations.push(dur);
+  } else if (event.eventType === "provider.fallback") acc.fallbacks++;
+  else if (event.eventType === "tool.started") acc.toolCalls++;
+  else if (event.eventType === "tool.executed") {
+    acc.completedTools++;
+    const dur = durationMs(event);
+    if (dur > 0) acc.toolDurations.push(dur);
+  } else if (event.eventType === "tool.failed") {
+    acc.failedTools++;
+    const dur = durationMs(event);
+    if (dur > 0) acc.toolDurations.push(dur);
+  } else if (event.eventType === "process.started") acc.processes++;
+  else if (event.eventType === "process.completed" && event.outcome === "failure") acc.failedProcesses++;
+  else if (event.eventType === "decision.requested") acc.decisions++;
+  else if (event.eventType === "decision.escalated") acc.escalations++;
+  if (event.eventType === "token.accounted") {
+    const cost = readPath(event.attributes ?? {}, "cost.total");
+    if (typeof cost === "number" && Number.isFinite(cost)) {
+      const key = scopeKey(event);
+      const existing = acc.costByScope.get(key);
+      if (!existing || compareEvents(event, existing.event) > 0) {
+        acc.costByScope.set(key, { cost, event });
+      }
+    }
+  }
+  if (event.resource?.kind === "file" || event.eventType.startsWith("file.")) {
+    acc.fileEvents++;
+    if (event.resource?.path) acc.uniqueFiles.add(event.resource.path);
+  }
+  if (family === "agent") acc.agentEvents++;
+  if (event.scope.agentId) acc.uniqueAgents.add(event.scope.agentId);
+  if (isTerminalFailure(event)) acc.failures++;
+  if (event.outcome === "cancelled" || event.outcome === "abandoned") acc.cancellations++;
+}
+function finalizeSummary(acc) {
+  const sortedProviderDurations = acc.providerDurations.slice().sort((a, b) => a - b);
+  const sortedToolDurations = acc.toolDurations.slice().sort((a, b) => a - b);
+  const totalCost = [...acc.costByScope.values()].reduce((sum, entry) => sum + entry.cost, 0);
   return {
-    logicalRequests: unique(events.map((event) => event.correlation.logicalRequestId)),
-    modelAttempts: ofType("provider.attempt.started").length,
-    completedAttempts: completedAttempts.length,
-    failedAttempts: failedAttempts.length,
-    scheduledRetries: failedAttempts.filter((event) => event.attributes?.retryScheduled === true).length,
-    fallbacks: ofType("provider.fallback").length,
-    providers: unique(events.map((event) => event.runtime?.providerId)),
-    models: unique(events.map((event) => event.runtime?.modelId)),
-    inputTokens: completedAttempts.reduce((sum, event) => sum + numberAt(event, "usage.input"), 0),
-    outputTokens: completedAttempts.reduce((sum, event) => sum + numberAt(event, "usage.output"), 0),
-    cacheReadTokens: completedAttempts.reduce((sum, event) => sum + numberAt(event, "usage.cacheRead"), 0),
-    cacheWriteTokens: completedAttempts.reduce((sum, event) => sum + numberAt(event, "usage.cacheWrite"), 0),
-    estimatedCostUsd: latestAccounted.reduce((sum, event) => sum + numberAt(event, "cost.total"), 0),
-    providerAvgDurationMs: average(providerDurations),
-    providerP95DurationMs: percentile(providerDurations, 0.95),
-    toolCalls: ofType("tool.started").length,
-    completedTools: completedTools.length,
-    failedTools: failedTools.length,
-    toolAvgDurationMs: average(toolDurations),
-    processes: ofType("process.started").length,
-    failedProcesses,
-    fileEvents: files.length,
-    uniqueFiles: unique(files.map((event) => event.resource?.path)),
-    agentEvents: families.agent,
-    uniqueAgents: unique(events.map((event) => event.scope.agentId)),
-    decisions: ofType("decision.requested").length,
-    escalations: ofType("decision.escalated").length,
-    failures: terminalFailures.length,
-    cancellations: events.filter((event) => event.outcome === "cancelled" || event.outcome === "abandoned").length,
-    families,
-    failuresByFamily: familyCounts(terminalFailures)
+    logicalRequests: acc.logicalRequestIds.size,
+    modelAttempts: acc.modelAttempts,
+    completedAttempts: acc.completedAttempts,
+    failedAttempts: acc.failedAttempts,
+    scheduledRetries: acc.scheduledRetries,
+    fallbacks: acc.fallbacks,
+    providers: acc.providers.size,
+    models: acc.models.size,
+    inputTokens: acc.inputTokens,
+    outputTokens: acc.outputTokens,
+    cacheReadTokens: acc.cacheReadTokens,
+    cacheWriteTokens: acc.cacheWriteTokens,
+    estimatedCostUsd: totalCost,
+    providerAvgDurationMs: average(sortedProviderDurations),
+    providerP95DurationMs: percentile(sortedProviderDurations, 0.95),
+    toolCalls: acc.toolCalls,
+    completedTools: acc.completedTools,
+    failedTools: acc.failedTools,
+    toolAvgDurationMs: average(sortedToolDurations),
+    processes: acc.processes,
+    failedProcesses: acc.failedProcesses,
+    fileEvents: acc.fileEvents,
+    uniqueFiles: acc.uniqueFiles.size,
+    agentEvents: acc.agentEvents,
+    uniqueAgents: acc.uniqueAgents.size,
+    decisions: acc.decisions,
+    escalations: acc.escalations,
+    failures: acc.failures,
+    cancellations: acc.cancellations,
+    families: acc.families,
+    failuresByFamily: acc.failuresByFamily
+  };
+}
+Object.defineProperty(ChronicleQueryEngine.prototype, "partitionFiles", {
+  get() {
+    throw new Error("ChronicleQueryEngine no longer loads events on construction. Use async query().");
+  },
+  set(_val) {
+    Object.defineProperty(this, "partitionFiles", { value: _val, writable: false, configurable: false });
+  }
+});
+async function findPartitions(root) {
+  const result = [];
+  const partitionName = /^(.*\.events)(?:\.(\d{5}))?\.jsonl$/;
+  const visit = async (directory) => {
+    let entries;
+    try {
+      entries = await fs4.readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path5.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(full);
+      else if (entry.isFile() && partitionName.test(entry.name)) result.push(full);
+    }
   };
+  await visit(root);
+  return result.sort((left, right) => {
+    const leftMatch = partitionName.exec(path5.basename(left));
+    const rightMatch = partitionName.exec(path5.basename(right));
+    const leftGroup = path5.join(path5.dirname(left), leftMatch?.[1] ?? left);
+    const rightGroup = path5.join(path5.dirname(right), rightMatch?.[1] ?? right);
+    const groupOrder = leftGroup.localeCompare(rightGroup);
+    if (groupOrder !== 0) return groupOrder;
+    return Number(leftMatch?.[2] ?? 0) - Number(rightMatch?.[2] ?? 0);
+  });
+}
+function numberAt(event, dotPath) {
+  const value = readPath(event.attributes ?? {}, dotPath);
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 function durationMs(event) {
   const value = Number(event.durationNs ?? 0) / 1e6;
   return Number.isFinite(value) ? value : 0;
 }
 function average(values) {
-  return values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
+  return values.length ? values.reduce((sum, v) => sum + v, 0) / values.length : 0;
 }
 function percentile(sorted, quantile) {
   return sorted.length ? sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * quantile) - 1))] : 0;
 }
-function latestByScope(events) {
-  const latest = /* @__PURE__ */ new Map();
-  for (const event of events) {
-    const key = `${event.scope.projectId ?? ""}\0${event.scope.sessionId ?? ""}\0${event.scope.agentId ?? ""}`;
-    const current = latest.get(key);
-    if (!current || compareEvents(current, event) < 0) latest.set(key, event);
-  }
-  return [...latest.values()];
-}
-function familyCounts(events) {
-  const counts = { llm: 0, agent: 0, tool: 0, file: 0, memory: 0, task: 0, decision: 0, runtime: 0 };
-  for (const event of events) counts[signalFamily(event)]++;
-  return counts;
+function scopeKey(event) {
+  return `${event.scope.projectId ?? ""}\0${event.scope.sessionId ?? ""}\0${event.scope.agentId ?? ""}`;
 }
 function signalFamily(event) {
-  if (event.eventType.startsWith("decision.") || event.eventType.startsWith("brain.")) return "decision";
+  if (/^(?:decision|brain|permission)\./.test(event.eventType)) return "decision";
   if (event.resource?.kind === "file" || event.resource?.kind === "symbol" || /^(?:file|worktree)\./.test(event.eventType)) return "file";
   if (/^(?:provider|token|context|ctx|compaction)\./.test(event.eventType)) return "llm";
   if (/^(?:agent|subagent|delegate|fleet|concurrency)\./.test(event.eventType)) return "agent";
@@ -1747,24 +2352,6 @@ function relationKeys(event) {
   add("parent_span", event.correlation.spanId, "explicit");
   return result;
 }
-async function findPartitions(root) {
-  const result = [];
-  const visit = async (directory) => {
-    let entries;
-    try {
-      entries = await fs4.readdir(directory, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const full = path5.join(directory, entry.name);
-      if (entry.isDirectory()) await visit(full);
-      else if (entry.isFile() && entry.name.endsWith(".events.jsonl")) result.push(full);
-    }
-  };
-  await visit(root);
-  return result.sort();
-}
 function matches(event, query) {
   if (query.eventId && event.eventId !== query.eventId) return false;
   if (query.eventTypes && !query.eventTypes.includes(event.eventType)) return false;
@@ -1791,7 +2378,8 @@ function normalize2(value) {
   return value?.replaceAll("\\", "/").toLocaleLowerCase();
 }
 function lineContains(event, line) {
-  const start = event.resource?.lineStart, end = event.resource?.lineEnd ?? start;
+  const start = event.resource?.lineStart;
+  const end = event.resource?.lineEnd ?? start;
   return start !== void 0 && end !== void 0 && line >= start && line <= end;
 }
 function objectContains(actual, expected) {
@@ -1803,19 +2391,150 @@ function readPath(value, key) {
 function deepEqual(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
+function findInsertionIndex(events, event, compare) {
+  let low = 0;
+  let high = events.length;
+  while (low < high) {
+    const middle = low + high >>> 1;
+    if (compare(events[middle], event) <= 0) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
 function compareEvents(a, b) {
-  return (a.occurredAt ?? a.observedAt).localeCompare(b.occurredAt ?? b.observedAt) || a.persistedAt.localeCompare(b.persistedAt) || a.sequence - b.sequence;
+  return compareEventToKey(a, orderKey(b));
+}
+function compareEventToKey(event, key) {
+  return (event.occurredAt ?? event.observedAt).localeCompare(key.occurredAt) || event.persistedAt.localeCompare(key.persistedAt) || event.sequence - key.sequence || event.eventId.localeCompare(key.eventId);
+}
+function orderKey(event) {
+  return {
+    occurredAt: event.occurredAt ?? event.observedAt,
+    persistedAt: event.persistedAt,
+    sequence: event.sequence,
+    eventId: event.eventId
+  };
+}
+function hashQuery(query) {
+  const { cursor: _cursor, limit: _limit, order: _order, ...filters } = query;
+  return createHash11("sha256").update(stableStringify2(filters), "utf8").digest("base64url");
+}
+function encodeCursor(cursor) {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeCursor(encoded, order, queryHash) {
+  if (!encoded) return void 0;
+  if (encoded.length > 1e6) throw new Error("Invalid Chronicle cursor");
+  try {
+    const parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    if (!isCursor(parsed) || parsed.order !== order || parsed.queryHash !== queryHash) {
+      throw new Error("cursor does not match the query");
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`Invalid Chronicle cursor: ${error instanceof Error ? error.message : String(error)}`);
+  }
 }
-function encodeCursor(offset) {
-  return Buffer.from(String(offset)).toString("base64url");
+function isCursor(value) {
+  if (!value || typeof value !== "object") return false;
+  const cursor = value;
+  const after = cursor.after;
+  if (cursor.version !== 1 || cursor.order !== "asc" && cursor.order !== "desc" || typeof cursor.queryHash !== "string" || !after || typeof after.occurredAt !== "string" || typeof after.persistedAt !== "string" || !Number.isSafeInteger(after.sequence) || typeof after.eventId !== "string" || !Array.isArray(cursor.snapshot) || cursor.snapshot.length > MAX_CURSOR_SNAPSHOT_ENTRIES) return false;
+  const snapshotIds = /* @__PURE__ */ new Set();
+  for (const entry of cursor.snapshot) {
+    if (!entry || typeof entry.id !== "string" || !entry.id || !Number.isSafeInteger(entry.size) || entry.size < 0 || snapshotIds.has(entry.id)) return false;
+    snapshotIds.add(entry.id);
+  }
+  return true;
+}
+async function captureSnapshot(files) {
+  if (files.length > MAX_CURSOR_SNAPSHOT_ENTRIES) {
+    throw new Error("Chronicle snapshot contains too many partitions");
+  }
+  return Promise.all(files.map(async (file) => {
+    let size = 0;
+    try {
+      size = (await fs4.stat(file)).size;
+    } catch {
+    }
+    return { file, id: fileId(file), size };
+  }));
 }
-function decodeCursor(cursor) {
-  if (!cursor) return 0;
-  const value = Number(Buffer.from(cursor, "base64url").toString("utf8"));
-  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+async function resolveSnapshotFiles(files, snapshot) {
+  const currentFiles = new Map(files.map((file) => [fileId(file), file]));
+  return Promise.all(snapshot.map(async (entry) => {
+    const file = currentFiles.get(entry.id);
+    if (!file) throw new Error("Chronicle cursor snapshot has expired");
+    let currentSize;
+    try {
+      currentSize = (await fs4.stat(file)).size;
+    } catch {
+      throw new Error("Chronicle cursor snapshot has expired");
+    }
+    if (currentSize < entry.size) throw new Error("Chronicle cursor snapshot has expired");
+    return { file, ...entry };
+  }));
+}
+function fileId(file) {
+  return createHash11("sha256").update(path5.resolve(file), "utf8").digest("base64url");
+}
+function stableStringify2(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify2).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
 }
 function isChronicleEvent(value) {
-  return Boolean(value && typeof value.eventId === "string" && typeof value.eventType === "string" && typeof value.occurredAt === "string");
+  if (!isRecord(value) || !isRecord(value.scope) || !isRecord(value.correlation)) return false;
+  return value.schemaVersion === 1 && typeof value.eventId === "string" && typeof value.eventType === "string" && typeof value.occurredAt === "string" && typeof value.observedAt === "string" && typeof value.persistedAt === "string" && Number.isSafeInteger(value.sequence) && value.sequence >= 0 && typeof value.previousHash === "string" && typeof value.hash === "string" && typeof value.scope.installationId === "string" && typeof value.scope.machineId === "string" && optionalStrings(value.scope, [
+    "projectId",
+    "repositoryId",
+    "workspaceId",
+    "worktreeId",
+    "sessionId",
+    "turnId",
+    "iterationId",
+    "agentId",
+    "goalId",
+    "planId",
+    "taskId",
+    "kanbanBoardId"
+  ]) && typeof value.correlation.traceId === "string" && typeof value.correlation.spanId === "string" && optionalStrings(value.correlation, [
+    "parentSpanId",
+    "logicalRequestId",
+    "attemptId",
+    "toolCallId"
+  ]) && isRuntime(value.runtime) && isResource(value.resource) && (value.attributes === void 0 || isRecord(value.attributes)) && (value.tags === void 0 || isStringRecord(value.tags));
+}
+function isRuntime(value) {
+  return value === void 0 || isRecord(value) && optionalStrings(value, ["providerId", "modelId", "modelRevision"]) && optionalFiniteNumbers(value, ["processId", "parentProcessId"]);
+}
+function isResource(value) {
+  if (value === void 0) return true;
+  if (!isRecord(value) || ![
+    "file",
+    "symbol",
+    "memory",
+    "task",
+    "kanban",
+    "process",
+    "network",
+    "artifact",
+    "other"
+  ].includes(String(value.kind)) || typeof value.id !== "string") return false;
+  return optionalStrings(value, ["path", "contentHashBefore", "contentHashAfter"]) && optionalFiniteNumbers(value, ["lineStart", "lineEnd"]);
+}
+function optionalStrings(value, keys) {
+  return keys.every((key) => value[key] === void 0 || typeof value[key] === "string");
+}
+function optionalFiniteNumbers(value, keys) {
+  return keys.every((key) => value[key] === void 0 || typeof value[key] === "number" && Number.isFinite(value[key]));
+}
+function isStringRecord(value) {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function facetValue(event, field) {
   const values = {