tokentracker-cli 1.1.3 → 1.1.4

package/src/lib/rollout.js

@@ -47,6 +47,8 @@ const {
   buildDevinUsageEvents,
 } = require("./devin-usage");
 const { USD_TICKS_PER_USD, normalizeGrokUsage } = require("./grok-usage");
+const { resolveTraeDbPaths, readTraeUsageRows } = require("./trae-db");
+const { normalizeTraeUsage, normalizeTraeModel, traeTimestamp } = require("./trae-usage");
 
 const DEFAULT_SOURCE = "codex";
 const DEFAULT_MODEL = "unknown";
@@ -19662,12 +19664,13 @@ function mergeGrokUsagePrecision(current, next) {
   return "mixed";
 }
 
-function clearGrokHourlyBuckets(hourlyState) {
+function clearSourceHourlyBuckets(hourlyState, source) {
   if (!hourlyState || typeof hourlyState !== "object") return;
+  const prefix = `${source}${BUCKET_SEPARATOR}`;
   const buckets = hourlyState.buckets && typeof hourlyState.buckets === "object" ? hourlyState.buckets : null;
   if (buckets) {
     for (const key of Object.keys(buckets)) {
-      if (key.startsWith("grok|")) delete buckets[key];
+      if (key.startsWith(prefix)) delete buckets[key];
     }
   }
   const groupQueued =
@@ -19676,12 +19679,12 @@ function clearGrokHourlyBuckets(hourlyState) {
       : null;
   if (groupQueued) {
     for (const key of Object.keys(groupQueued)) {
-      if (key.startsWith("grok|")) delete groupQueued[key];
+      if (key.startsWith(prefix)) delete groupQueued[key];
     }
   }
 }
 
-async function retractStaleGrokQueueRows(queuePath, keepKeys) {
+async function retractStaleSourceQueueRows(queuePath, source, keepKeys) {
   if (!queuePath) return 0;
   let raw = "";
   try {
@@ -19691,7 +19694,7 @@ async function retractStaleGrokQueueRows(queuePath, keepKeys) {
     throw error;
   }
 
-  const latestGrok = new Map();
+  const latestRows = new Map();
   for (const line of raw.split("\n")) {
     if (!line.trim()) continue;
     let row;
@@ -19700,21 +19703,21 @@ async function retractStaleGrokQueueRows(queuePath, keepKeys) {
     } catch {
       continue;
     }
-    if ((row?.source || "") !== "grok") continue;
+    if ((row?.source || "") !== source) continue;
     const model = normalizeModelInput(row.model) || DEFAULT_MODEL;
     const hourStart = typeof row.hour_start === "string" ? row.hour_start : null;
     if (!hourStart) continue;
-    latestGrok.set(bucketKey("grok", model, hourStart), { model, hour_start: hourStart, row });
+    latestRows.set(bucketKey(source, model, hourStart), { model, hour_start: hourStart, row });
   }
 
   const zero = initTotals();
   const lines = [];
-  for (const [key, entry] of latestGrok.entries()) {
+  for (const [key, entry] of latestRows.entries()) {
     if (keepKeys.has(key)) continue;
     if (totalsKey(entry.row) === totalsKey(zero)) continue;
     lines.push(
       JSON.stringify({
-        source: "grok",
+        source,
         model: entry.model,
         hour_start: entry.hour_start,
         ...zero,
@@ -19814,7 +19817,7 @@ async function parseGrokBuildIncremental({
         legacySeen: true,
       };
     }
-    clearGrokHourlyBuckets(hourlyState);
+    clearSourceHourlyBuckets(hourlyState, "grok");
   } else {
     sessionSnapshots = normalizeGrokSessionSnapshots(grokState);
   }
@@ -20195,7 +20198,7 @@ async function parseGrokBuildIncremental({
       if (!key.startsWith("grok|") || !bucket?.totals) continue;
       keepKeys.add(key);
     }
-    const retracted = await retractStaleGrokQueueRows(queuePath, keepKeys);
+    const retracted = await retractStaleSourceQueueRows(queuePath, "grok", keepKeys);
     bucketsQueued += retracted;
   }
 
@@ -21687,13 +21690,188 @@ function isCjkCodePoint(code) {
 // ── Trae SOLO (ByteDance AI IDE) ─────────────────────────────────────────────
 // https://www.trae.ai
 //
-// Trae SOLO is scoped to detection (init) + entitlement display (status):
-//   - init: resolveTraeStoragePath() proves an install exists.
-//   - status: readTraeEntitlementFromStorage() serves the plan/limits snapshot.
-// Trae SOLO does NOT expose per-request token usage in a readable local format
-// (session transcripts are SQLCipher-encrypted; memory summaries carry no
-// token counts), so the token-count-only queue is intentionally never written
-// for this provider — the cloud hourly table stays clean.
+// International TRAE usage comes from local encrypted chat_turn metadata.
+//
+// The ledger keeps one compact tuple per turn, keyed by a 128-bit digest, so a
+// correction can retract exactly what the turn contributed even after TRAE
+// deletes its history. total_tokens is the five token columns plus any input
+// without a cache split, which is counted but unpriced (normalizeTraeUsage).
+const TRAE_CURSOR_VERSION = 2;
+const HALF_HOUR_MS = 30 * 60 * 1000;
+const [T_SESSION, T_MODEL, T_BUCKET, T_MODIFIED, T_STORE, T_INPUT, T_CACHED, T_WRITTEN,
+  T_OUTPUT, T_REASONING, T_CONVERSATIONS, T_ESTIMATED, T_UNPRICED] = Array.from({ length: 13 }, (_, i) => i);
+
+function packTraeTurn({ session, model, bucketStart, totals, modifiedAt, store }) {
+  return [session, model, Date.parse(bucketStart) / HALF_HOUR_MS, modifiedAt, store,
+    totals.input_tokens, totals.cached_input_tokens, totals.cache_creation_input_tokens,
+    totals.output_tokens, totals.reasoning_output_tokens, totals.conversation_count,
+    totals.usage_precision === "estimated" ? 1 : 0, totals.unpriced_input_tokens || 0];
+}
+
+function unpackTraeTotals(turn) {
+  const totals = {
+    input_tokens: turn[T_INPUT],
+    cached_input_tokens: turn[T_CACHED],
+    cache_creation_input_tokens: turn[T_WRITTEN],
+    output_tokens: turn[T_OUTPUT],
+    reasoning_output_tokens: turn[T_REASONING],
+    total_tokens: turn[T_INPUT] + turn[T_CACHED] + turn[T_WRITTEN] + turn[T_OUTPUT] + turn[T_REASONING]
+      + turn[T_UNPRICED],
+    conversation_count: turn[T_CONVERSATIONS],
+  };
+  if (turn[T_ESTIMATED]) totals.usage_precision = "estimated";
+  return totals;
+}
+
+function traeTurnBucketStart(turn) {
+  return new Date(turn[T_BUCKET] * HALF_HOUR_MS).toISOString();
+}
+
+async function parseTraeIncremental({
+  dbPaths,
+  cursors,
+  queuePath,
+  env = process.env,
+  onProgress,
+  readUsageRows = readTraeUsageRows,
+} = {}) {
+  const paths = dbPaths || resolveTraeDbPaths(env);
+  const hourlyState = normalizeHourlyState(cursors.hourly);
+  // Queue writes and reads may fail. Publish cursor changes only after the
+  // append succeeds, including copies of the mutable bucket totals.
+  hourlyState.buckets = Object.fromEntries(Object.entries(hourlyState.buckets).map(([key, bucket]) => [
+    key, key.startsWith("trae|") ? { ...bucket, totals: { ...bucket.totals } } : bucket,
+  ]));
+  hourlyState.groupQueued = { ...hourlyState.groupQueued };
+  // A ledger with another TRAE_CURSOR_VERSION cannot retract what it
+  // contributed, so rebuild the TRAE buckets from the stores instead of
+  // adding every turn on top of them.
+  const prior = cursors.trae?.version === TRAE_CURSOR_VERSION ? cursors.trae : null;
+  const rebuilding = !prior && Boolean(cursors.trae);
+  if (rebuilding) clearSourceHourlyBuckets(hourlyState, "trae");
+  const turns = { ...prior?.turns };
+  const databases = { ...prior?.databases };
+  const stores = [...(prior?.stores || [])];
+  const touchedBuckets = new Set();
+  const conversations = new Set(Object.values(turns)
+    .filter((turn) => turn[T_CONVERSATIONS] > 0).map((turn) => turn[T_SESSION]));
+  // 128-bit digests: identifiers are hashed before they are stored.
+  const digest = (value) => crypto.createHash("sha256").update(value).digest().subarray(0, 16).toString("base64url");
+  let recordsProcessed = 0;
+  let eventsAggregated = 0;
+  let recordsSkipped = 0;
+  let estimatedRecords = 0;
+  let unpricedRecords = 0;
+  const errors = [];
+  for (const dbPath of [...new Set(paths)]) {
+    const databaseKey = digest(path.resolve(dbPath));
+    let store = stores.indexOf(databaseKey);
+    if (store < 0) store = stores.push(databaseKey) - 1;
+    let rows;
+    let fingerprint;
+    let finalFingerprint;
+    try {
+      // existsSync also returns false for permission errors. Let stat/read
+      // report inaccessible stores instead of treating them as absent.
+      fssync.statSync(dbPath);
+      fingerprint = devinSqliteFingerprint(dbPath);
+      if (sameSqliteFingerprint(fingerprint, databases[databaseKey])) continue;
+      rows = await readUsageRows(dbPath, { env });
+      finalFingerprint = devinSqliteFingerprint(dbPath);
+    } catch (err) {
+      // One install can be locked, corrupt, or use a different key while
+      // another remains readable. Its prior fingerprint stays retryable;
+      // successful stores still publish together after the queue append.
+      errors.push({ database: dbPath, message: err?.message || String(err) });
+      continue;
+    }
+    for (const row of rows) {
+      recordsProcessed += 1;
+      const totals = normalizeTraeUsage(row.usage, { model: row.model });
+      const timestamp = traeTimestamp(row.created_at);
+      const bucketStart = timestamp && toUtcHalfHourStart(timestamp);
+      const rowId = row.turn_id || row.id;
+      if (!totals || !bucketStart || rowId == null || rowId === "") {
+        recordsSkipped += 1;
+        continue;
+      }
+      const session = digest(String(row.session_id || `${databaseKey}:${rowId}`));
+      // Stable turn ids deduplicate copies across the two international app
+      // stores. Numeric SQLite ids are only unique within their database.
+      const identity = digest(JSON.stringify(row.turn_id
+        ? [session, row.turn_id] : [databaseKey, rowId]));
+      const previous = turns[identity];
+      const modifiedAt = Date.parse(traeTimestamp(row.updated_at) || timestamp);
+      // A copied turn in another install can lag behind the original. Never
+      // let an unrelated rescan of that stale store retract newer usage.
+      // Without a newer timestamp, conflicting copies retain their owner.
+      if (previous && previous[T_STORE] !== store && modifiedAt <= previous[T_MODIFIED]) continue;
+      if (!previous && totals.total_tokens === 0) continue;
+      if (totals.usage_precision === "estimated") estimatedRecords += 1;
+      if (totals.unpriced_input_tokens > 0) unpricedRecords += 1;
+      totals.conversation_count = previous
+        ? previous[T_CONVERSATIONS]
+        : conversations.has(session) ? 0 : 1;
+      conversations.add(session);
+      const model = normalizeTraeModel(row.model);
+      const next = packTraeTurn({ session, model, bucketStart, totals, modifiedAt, store });
+      if (previous && next.every((value, i) => i === T_MODIFIED || i === T_STORE || value === previous[i])) {
+        turns[identity] = next;
+        continue;
+      }
+      if (previous) {
+        const previousBucket = traeTurnBucketStart(previous);
+        const old = getHourlyBucket(hourlyState, "trae", previous[T_MODEL], previousBucket);
+        subtractTotals(old.totals, unpackTraeTotals(previous));
+        touchedBuckets.add(bucketKey("trae", previous[T_MODEL], previousBucket));
+      }
+      const bucket = getHourlyBucket(hourlyState, "trae", model, bucketStart);
+      addTotals(bucket.totals, totals);
+      touchedBuckets.add(bucketKey("trae", model, bucketStart));
+      turns[identity] = next;
+      eventsAggregated += 1;
+    }
+    // A read that races with a writer must be retried on the next sync.
+    databases[databaseKey] = sameSqliteFingerprint(fingerprint, finalFingerprint)
+      ? fingerprint : null;
+    if (typeof onProgress === "function") {
+      onProgress({ recordsProcessed, eventsAggregated, bucketsQueued: touchedBuckets.size });
+    }
+  }
+  // Rebuild precision from the retained contributions, including unchanged
+  // stores. A correction can replace the last estimated turn with reported
+  // usage without changing numeric totals, or move it to another bucket.
+  const bucketPrecisions = new Map();
+  for (const turn of Object.values(turns)) {
+    const key = bucketKey("trae", turn[T_MODEL], traeTurnBucketStart(turn));
+    if (!touchedBuckets.has(key) || unpackTraeTotals(turn).total_tokens === 0) continue;
+    bucketPrecisions.set(key, mergeGrokUsagePrecision(
+      bucketPrecisions.get(key), turn[T_ESTIMATED] ? "estimated" : "reported",
+    ));
+  }
+  for (const key of touchedBuckets) {
+    const precision = bucketPrecisions.get(key);
+    hourlyState.buckets[key].usage_precision = precision === "reported" ? null : precision || null;
+  }
+  // A rebuild is all or nothing. Buckets rebuilt from a subset of the stores
+  // would replace shared buckets with partial totals, and each retry would
+  // append every row again. Keep the old hourly state and ledger instead.
+  if (rebuilding && errors.length) {
+    return { recordsProcessed, eventsAggregated, bucketsQueued: 0, recordsSkipped, estimatedRecords, unpricedRecords, errors };
+  }
+  await ensureDir(path.dirname(queuePath));
+  let bucketsQueued = await enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets });
+  cursors.hourly = hourlyState;
+  if (rebuilding) {
+    // The old ledger may have filed a turn under another bucket key (model or
+    // half-hour); retract those rows so the dashboard does not count it twice.
+    const keepKeys = new Set(Object.keys(hourlyState.buckets).filter((key) => key.startsWith("trae|")));
+    bucketsQueued += await retractStaleSourceQueueRows(queuePath, "trae", keepKeys);
+  }
+  cursors.trae = { version: TRAE_CURSOR_VERSION, stores, databases, turns };
+  return { recordsProcessed, eventsAggregated, bucketsQueued, recordsSkipped, estimatedRecords, unpricedRecords, errors };
+}
+
 // Ordered candidate app-dir names. The CN IDE build installs as "Trae CN" on
 // Windows; the international build installs as "TRAE SOLO". Both expose the same
 // iCubeServerData entitlement key, so either is a valid Trae IDE install.
@@ -24192,6 +24370,7 @@ async function parseCommandCodeIncremental({
 }
 
 module.exports = {
+  parseTraeIncremental,
   listRolloutFiles,
   listRolloutFilesDeep,
   codexSessionIdFromPath,

package/src/lib/trae-db.js

@@ -0,0 +1,127 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { openTraeSnapshot } = require("./trae-snapshot");
+const { withTraeSqlite } = require("./trae-sqlite");
+
+const TOKEN_FIELDS = [
+  "prompt_tokens", "prompt_tokens_total", "input_tokens",
+  "completion_tokens", "completion_tokens_total", "output_tokens",
+  "total_tokens", "cache_read_input_tokens", "cache_creation_input_tokens",
+  "reasoning_tokens", "reasoning_output_tokens",
+];
+
+function resolveTraeDbPaths(env = process.env, { platform = process.platform, home = os.homedir() } = {}) {
+  const explicit = String(env.TOKENTRACKER_TRAE_DB || "").trim();
+  if (explicit) return [path.resolve(explicit)];
+  const customHome = String(env.TOKENTRACKER_TRAE_HOME || "").trim();
+  const parent = platform === "win32"
+    ? env.APPDATA || path.join(home, "AppData", "Roaming")
+    : platform === "darwin"
+      ? path.join(home, "Library", "Application Support")
+      : env.XDG_CONFIG_HOME || path.join(home, ".config");
+  const roots = customHome ? [customHome] : [path.join(parent, "Trae"), path.join(parent, "TRAE SOLO")];
+  const result = [];
+  for (const root of roots) {
+    // A decrypted sibling may be an old export. Only an explicit DB override
+    // opts into one; normal discovery always reads the current application DB.
+    for (const module of ["ai-agent", "ai-chat"]) {
+      const candidate = path.resolve(root, "ModularData", module, "database.db");
+      let present;
+      try { present = fs.statSync(candidate).isFile(); }
+      catch (err) {
+        // Permission failures must reach the reader's diagnostics, not masquerade
+        // as an absent installation and silently drop an entire usage history.
+        present = err.code !== "ENOENT" && err.code !== "ENOTDIR";
+      }
+      if (present) {
+        result.push(candidate);
+        break;
+      }
+    }
+  }
+  return [...new Set(result)];
+}
+
+function error(message) {
+  return new Error(`Cannot read TRAE usage: ${message}`);
+}
+
+async function projectUsage(queryRows) {
+  const tables = await queryRows("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'chat_turn'");
+  // history_v2.token_usage can be a context-size snapshot rather than billed
+  // usage. Do not synthesize input tokens from those scalar values.
+  if (!tables.length) throw error("unsupported database schema: chat_turn table is missing.");
+  const columns = new Set((await queryRows("PRAGMA table_info(chat_turn)")).map((row) => row.name));
+  if (!columns.has("context") || (!columns.has("created_at") && !columns.has("updated_at"))) {
+    throw error("unsupported chat_turn schema.");
+  }
+  const column = (name, fallback = "NULL") => columns.has(name) ? `"${name}"` : fallback;
+  const date = columns.has("created_at") && columns.has("updated_at")
+    ? 'COALESCE("created_at", "updated_at")' : column("created_at", column("updated_at"));
+  const modelPaths = [
+    "persist_user_message_context.model_info.display_model_name",
+    "persist_user_message_context.model_info.model_name",
+    "persist_user_message_context.model_info.config_name", "model_name", "model",
+    "agent_model", "selected_model.name", "selectedModel.name",
+  ];
+  const model = modelPaths.map((field) => `CASE WHEN json_type(context, '$.${field}') = 'text'
+    THEN NULLIF(NULLIF(TRIM(json_extract(context, '$.${field}')), ''), '-') END`);
+  const fields = TOKEN_FIELDS.map((field) => `CASE
+    WHEN json_type(context, '$.token_usage.${field}') IN ('integer', 'real')
+    THEN json_extract(context, '$.token_usage.${field}') END AS "${field}"`);
+  const invalidFields = TOKEN_FIELDS.map((field) =>
+    `COALESCE(json_type(context, '$.token_usage.${field}') NOT IN ('integer', 'real', 'null'), 0)`);
+  // Project inside SQLite: prompts, messages, session titles, fee/account data,
+  // and the rest of the context never cross into JS results or cursor state.
+  const query = `SELECT CAST(${column("id", "rowid")} AS TEXT) AS id,
+    ${column("session_id")} AS session_id, ${column("turn_id")} AS turn_id,
+    ${date} AS created_at, ${column("updated_at")} AS updated_at,
+    COALESCE(${model.join(", ")}, 'trae-unknown') AS model,
+    ${fields.join(", ")}, (${invalidFields.join(" OR ")}) AS invalid_usage
+    FROM chat_turn WHERE CASE WHEN json_valid(context)
+      THEN json_type(context, '$.token_usage') = 'object' ELSE 0 END`;
+  return (await queryRows(query)).map((row) => {
+    const usage = {};
+    let invalid = Boolean(row.invalid_usage);
+    for (const field of TOKEN_FIELDS) {
+      const value = row[field];
+      if (value == null) continue;
+      if (!Number.isSafeInteger(value) || value < 0) invalid = true;
+      else usage[field] = value;
+    }
+    return {
+      id: row.id, session_id: row.session_id, turn_id: row.turn_id,
+      created_at: row.created_at, updated_at: row.updated_at,
+      model: row.model, usage: invalid ? null : usage,
+    };
+  });
+}
+
+async function readTraeUsageRows(dbPath, { env = process.env } = {}) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let snapshot;
+    try { snapshot = openTraeSnapshot(dbPath, env); }
+    catch (err) {
+      // A writer can also change the files while the snapshot opens. Retry
+      // that too, and report the specific failure once attempts run out.
+      if (err?.transient && attempt < 2) continue;
+      throw err;
+    }
+    try {
+      let result;
+      try { result = await withTraeSqlite(snapshot, projectUsage); }
+      catch (err) {
+        // A writer may have changed pages while SQLite was reading. Discard
+        // every projected row and retry; never publish a mixed snapshot.
+        if (snapshot.isStable()) throw err;
+        continue;
+      }
+      if (snapshot.isStable()) return result;
+    } finally { snapshot.close(); }
+  }
+  throw error("database changed during the read; retry after TRAE finishes its current turn.");
+}
+
+module.exports = { resolveTraeDbPaths, readTraeUsageRows };

package/src/lib/trae-snapshot.js

@@ -0,0 +1,230 @@
+"use strict";
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+
+const SQLITE_HEADER = Buffer.from("SQLite format 3\0");
+const PAGE_SIZE = 4096;
+const RESERVED = 80;
+// TRAE's shared application key
+const DEFAULT_SQLCIPHER_KEY = "3605f6691095a993f03d5009c918352ef5be31ae31e8f000212b81ff058da773";
+const CACHE_PAGES = 64;
+const MAX_WAL_INDEX_PAGES = 1024 * 1024;
+
+function error(message) { return new Error(`Cannot read TRAE usage: ${message}`); }
+// A writer race rather than a bad store: the caller may retry immediately.
+function transientError(message) { return Object.assign(error(message), { transient: true }); }
+
+function statOptional(file) {
+  try { return fs.statSync(file, { bigint: true }); }
+  catch (err) { if (err.code === "ENOENT" || err.code === "ENOTDIR") return null; throw err; }
+}
+
+function sameStat(a, b) {
+  if (!a || !b) return a === b;
+  return a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs && a.ino === b.ino;
+}
+
+function readExact(fd, target, offset) {
+  let read = 0;
+  while (read < target.length) {
+    const count = fs.readSync(fd, target, read, target.length - read, offset + read);
+    if (!count) throw transientError("database or WAL was truncated during the read; retry when TRAE is idle.");
+    read += count;
+  }
+  return target;
+}
+
+function pageDecryptor(firstPage, env) {
+  const hex = String(env.TOKENTRACKER_TRAE_SQLCIPHER_KEY || "").trim() || DEFAULT_SQLCIPHER_KEY;
+  if (!/^[0-9a-f]{64}$/i.test(hex)) throw error("TOKENTRACKER_TRAE_SQLCIPHER_KEY must contain 64 hex characters.");
+  const key = Buffer.from(hex, "hex");
+  const salt = Buffer.from(firstPage.subarray(0, 16).map((byte) => byte ^ 0x3a));
+  // SQLCipher 4 raw-key format: AES-256-CBC, 4096-byte pages, SHA-512 HMAC.
+  // https://github.com/sqlcipher/sqlcipher/blob/master/src/sqlcipher.c
+  const hmacKey = crypto.pbkdf2Sync(key, salt, 2, 32, "sha512");
+  salt.fill(0);
+  return {
+    decrypt(page, number) {
+      const start = number === 1 ? 16 : 0;
+      const ivOffset = PAGE_SIZE - RESERVED;
+      const pageId = Buffer.alloc(4);
+      pageId.writeUInt32LE(number);
+      const expected = crypto.createHmac("sha512", hmacKey)
+        .update(page.subarray(start, ivOffset + 16)).update(pageId).digest();
+      if (!crypto.timingSafeEqual(expected, page.subarray(ivOffset + 16))) {
+        throw error("SQLCipher authentication failed (incorrect key, unsupported format, or damaged database); set TOKENTRACKER_TRAE_SQLCIPHER_KEY to override the shared application key.");
+      }
+      const decipher = crypto.createDecipheriv("aes-256-cbc", key, page.subarray(ivOffset, ivOffset + 16));
+      decipher.setAutoPadding(false);
+      const decoded = decipher.update(page.subarray(start, ivOffset));
+      decipher.final();
+      page.fill(0);
+      if (number === 1) SQLITE_HEADER.copy(page);
+      decoded.copy(page, start);
+      decoded.fill(0);
+      if (number === 1 && (page.readUInt16BE(16) !== PAGE_SIZE || page[20] !== RESERVED)) {
+        throw error("unsupported SQLCipher page format.");
+      }
+      return page;
+    },
+    dispose() { key.fill(0); hmacKey.fill(0); },
+  };
+}
+
+function checksum(data, bigEndian, state = [0, 0]) {
+  let [a, b] = state;
+  for (let i = 0; i < data.length; i += 8) {
+    const x = bigEndian ? data.readUInt32BE(i) : data.readUInt32LE(i);
+    const y = bigEndian ? data.readUInt32BE(i + 4) : data.readUInt32LE(i + 4);
+    a = (a + x + b) >>> 0;
+    b = (b + y + a) >>> 0;
+  }
+  return [a, b];
+}
+
+function indexWal(fd, size, pageSize) {
+  const pages = new Map();
+  if (fd == null || size === 0) return { pages, pageCount: null };
+  if (size < 32) throw transientError("incomplete WAL header; retry when TRAE is idle.");
+  const header = readExact(fd, Buffer.alloc(32), 0);
+  const magic = header.readUInt32BE(0);
+  if ((magic !== 0x377f0682 && magic !== 0x377f0683) ||
+      header.readUInt32BE(4) !== 3007000 || header.readUInt32BE(8) !== pageSize) {
+    throw error("unsupported WAL format.");
+  }
+  const bigEndian = magic === 0x377f0683;
+  let sum = checksum(header.subarray(0, 24), bigEndian);
+  if (sum[0] !== header.readUInt32BE(24) || sum[1] !== header.readUInt32BE(28)) throw error("WAL header checksum failed.");
+  let pageCount = null;
+  let pending = new Map();
+  const frame = Buffer.alloc(24 + pageSize);
+  // Index offsets instead of buffering/decrypting an entire WAL. Uncommitted
+  // frames never enter the visible page map. SQLite checksums cover ciphertext.
+  // https://www.sqlite.org/fileformat2.html#walformat
+  for (let offset = 32; offset + frame.length <= size; offset += frame.length) {
+    readExact(fd, frame, offset);
+    if (!frame.subarray(8, 16).equals(header.subarray(16, 24))) break;
+    // Like a salt mismatch, the first checksum mismatch ends the valid log (a
+    // torn append or crash leftover); only committed frames before it count.
+    sum = checksum(frame.subarray(24), bigEndian, checksum(frame.subarray(0, 8), bigEndian, sum));
+    if (sum[0] !== frame.readUInt32BE(16) || sum[1] !== frame.readUInt32BE(20)) break;
+    const number = frame.readUInt32BE(0);
+    const commit = frame.readUInt32BE(4);
+    if (!number || number === 0xffffffff || commit === 0xffffffff) throw error("invalid WAL page number or database size.");
+    pending.set(number, offset + 24);
+    if (pending.size + pages.size > MAX_WAL_INDEX_PAGES) throw error("WAL index exceeds the bounded-memory limit; let TRAE checkpoint its WAL and retry.");
+    if (commit) {
+      for (const [page, position] of pending) pages.set(page, position);
+      pending = new Map();
+      pageCount = commit;
+      for (const page of pages.keys()) if (page > commit) pages.delete(page);
+    }
+  }
+  frame.fill(0);
+  return { pages, pageCount };
+}
+
+// A read-only, optimistic snapshot. SQLite reads authenticated pages on demand;
+// no decrypted database is ever written to disk or materialized in memory.
+// The caller must discard results if isStable() fails after the SQL query.
+function openTraeSnapshot(dbPath, env = process.env) {
+  const paths = [dbPath, `${dbPath}-wal`, `${dbPath}-journal`];
+  const before = paths.map(statOptional);
+  if (!before[0]) throw error("database no longer exists.");
+  if (before.some((stat) => stat && (!stat.isFile() || stat.size > BigInt(Number.MAX_SAFE_INTEGER)))) {
+    throw error("unsupported database file or size.");
+  }
+  const handles = [];
+  const cache = new Map();
+  let decryptor;
+  const close = () => {
+    for (const page of cache.values()) page.fill(0);
+    cache.clear();
+    if (decryptor) { decryptor.dispose(); decryptor = null; }
+    let failure;
+    while (handles.length) {
+      try { fs.closeSync(handles.pop()); }
+      catch (err) { failure ||= err; }
+    }
+    if (failure) throw failure;
+  };
+  try {
+    const dbFd = fs.openSync(dbPath, "r");
+    handles.push(dbFd);
+    if (!sameStat(before[0], fs.fstatSync(dbFd, { bigint: true }))) throw transientError("database changed while opening; retry when TRAE is idle.");
+    let walFd = null;
+    if (before[1]) {
+      walFd = fs.openSync(paths[1], "r");
+      handles.push(walFd);
+      if (!sameStat(before[1], fs.fstatSync(walFd, { bigint: true }))) throw transientError("WAL changed while opening; retry when TRAE is idle.");
+    }
+    if (before[2] && before[2].size >= 8n) {
+      const journalFd = fs.openSync(paths[2], "r");
+      handles.push(journalFd);
+      if (readExact(journalFd, Buffer.alloc(8), 0).some((byte) => byte !== 0)) throw error("a rollback transaction is active; retry when TRAE is idle.");
+    }
+    const size = Number(before[0].size);
+    if (size < 100) throw error("database is truncated.");
+    const header = readExact(dbFd, Buffer.alloc(100), 0);
+    const encrypted = !header.subarray(0, 16).equals(SQLITE_HEADER);
+    const encodedSize = encrypted ? PAGE_SIZE : header.readUInt16BE(16);
+    const pageSize = encodedSize === 1 ? 65536 : encodedSize;
+    if (pageSize < 512 || pageSize > 65536 || (pageSize & (pageSize - 1)) || size % pageSize) throw error("invalid database page size or truncated database.");
+    if (encrypted) decryptor = pageDecryptor(header, env);
+    const { pages, pageCount } = indexWal(walFd, Number(before[1]?.size || 0n), pageSize);
+    const finalPageCount = pageCount == null ? size / pageSize : pageCount;
+    if (!finalPageCount || finalPageCount > 0xfffffffe) throw error("invalid database size.");
+    const byteLength = finalPageCount * pageSize;
+    const getPage = (number) => {
+      if (cache.has(number)) {
+        const page = cache.get(number);
+        cache.delete(number);
+        cache.set(number, page);
+        return page;
+      }
+      const page = Buffer.alloc(pageSize);
+      try {
+        if (pages.has(number)) readExact(walFd, page, pages.get(number));
+        else readExact(dbFd, page, (number - 1) * pageSize);
+        if (decryptor) decryptor.decrypt(page, number);
+        if (number === 1) {
+          // Present the committed view as a standalone rollback-mode database.
+          page[18] = 1;
+          page[19] = 1;
+          page.writeUInt32BE(finalPageCount, 28);
+          page.writeUInt32BE(page.readUInt32BE(24), 92);
+        }
+      } catch (err) { page.fill(0); throw err; }
+      cache.set(number, page);
+      if (cache.size > CACHE_PAGES) {
+        const oldest = cache.keys().next().value;
+        cache.get(oldest).fill(0);
+        cache.delete(oldest);
+      }
+      return page;
+    };
+    return {
+      byteLength,
+      read(target, offset) {
+        if (!Number.isSafeInteger(offset) || offset < 0) throw error("invalid read offset.");
+        target.fill(0);
+        const count = Math.min(target.length, Math.max(0, byteLength - offset));
+        let copied = 0;
+        while (copied < count) {
+          const position = offset + copied;
+          const pageOffset = position % pageSize;
+          const length = Math.min(count - copied, pageSize - pageOffset);
+          const page = getPage(Math.floor(position / pageSize) + 1);
+          target.set(page.subarray(pageOffset, pageOffset + length), copied);
+          copied += length;
+        }
+        return count;
+      },
+      isStable() { return paths.map(statOptional).every((stat, i) => sameStat(before[i], stat)); },
+      close,
+    };
+  } catch (err) { close(); throw err; }
+}
+
+module.exports = { openTraeSnapshot };