synapse-db 0.2.3 → 0.3.1

package/dist/index.js

@@ -1,7 +1,7 @@
 // @bun
 // engine.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, unlinkSync as unlinkSync2, watch } from "fs";
-import { basename, join, resolve } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync2, unlinkSync as unlinkSync2, watch } from "fs";
+import { basename, join as join2, resolve as resolve2 } from "path";
 
 // connectome.ts
 class SynapseConnectome {
@@ -12,6 +12,7 @@ class SynapseConnectome {
   edgeMeta = new Map;
   tokenInvertedIndex = new Map;
   documentTokens = new Map;
+  dirtySearchNodes = new Set;
   constructor() {}
   static makeNodeId(collection, id) {
     return `${collection}/${id}`;
@@ -24,10 +25,28 @@ class SynapseConnectome {
     this.edgeMeta.clear();
     this.tokenInvertedIndex.clear();
     this.documentTokens.clear();
+    this.dirtySearchNodes.clear();
   }
   putDocument(doc) {
     const nodeId = SynapseConnectome.makeNodeId(doc.collection, doc.id);
-    this.removeDocumentOwnedIndices(nodeId);
+    const links = doc.wikilinks;
+    const linksLen = links.length;
+    const existingOutSet = this.outgoingEdges.get(nodeId);
+    let skipEdgeRebuild = false;
+    if (existingOutSet && existingOutSet.size === 1 && linksLen === 1) {
+      const link = links[0];
+      const targetNodeId = SynapseConnectome.makeNodeId(link.targetCollection || doc.collection, link.targetId);
+      if (existingOutSet.has(targetNodeId)) {
+        const metaKey = `${nodeId}->${targetNodeId}`;
+        const existingMeta = this.edgeMeta.get(metaKey);
+        if (existingMeta && existingMeta.alias === link.alias) {
+          skipEdgeRebuild = true;
+        }
+      }
+    }
+    if (!skipEdgeRebuild && existingOutSet) {
+      this.removeDocumentOutgoingEdges(nodeId);
+    }
     this.documents.set(nodeId, doc);
     let colSet = this.collectionDocIds.get(doc.collection);
     if (!colSet) {
@@ -35,34 +54,40 @@ class SynapseConnectome {
       this.collectionDocIds.set(doc.collection, colSet);
     }
     colSet.add(doc.id);
-    for (const link of doc.wikilinks) {
-      const targetNodeId = SynapseConnectome.makeNodeId(link.targetCollection || doc.collection, link.targetId);
+    if (!skipEdgeRebuild && linksLen > 0) {
       let outSet = this.outgoingEdges.get(nodeId);
       if (!outSet) {
         outSet = new Set;
         this.outgoingEdges.set(nodeId, outSet);
       }
-      outSet.add(targetNodeId);
-      let inSet = this.incomingEdges.get(targetNodeId);
-      if (!inSet) {
-        inSet = new Set;
-        this.incomingEdges.set(targetNodeId, inSet);
-      }
-      inSet.add(nodeId);
-      const edgeKey = `${nodeId}->${targetNodeId}`;
-      this.edgeMeta.set(edgeKey, {
-        fromNodeId: nodeId,
-        toNodeId: targetNodeId,
-        alias: link.alias
-      });
+      for (let i = 0;i < linksLen; i++) {
+        const link = links[i];
+        const targetNodeId = SynapseConnectome.makeNodeId(link.targetCollection || doc.collection, link.targetId);
+        outSet.add(targetNodeId);
+        let inSet = this.incomingEdges.get(targetNodeId);
+        if (!inSet) {
+          inSet = new Set;
+          this.incomingEdges.set(targetNodeId, inSet);
+        }
+        inSet.add(nodeId);
+        this.edgeMeta.set(`${nodeId}->${targetNodeId}`, {
+          fromNodeId: nodeId,
+          toNodeId: targetNodeId,
+          alias: link.alias
+        });
+      }
     }
-    this.indexDocumentText(nodeId, doc);
+    this.dirtySearchNodes.add(nodeId);
   }
   removeDocument(collection, id) {
     const nodeId = SynapseConnectome.makeNodeId(collection, id);
     if (!this.documents.has(nodeId))
       return false;
-    this.removeDocumentOwnedIndices(nodeId);
+    this.dirtySearchNodes.delete(nodeId);
+    if (this.outgoingEdges.has(nodeId)) {
+      this.removeDocumentOutgoingEdges(nodeId);
+    }
+    this.removeDocumentSearchTokens(nodeId);
     this.documents.delete(nodeId);
     const colSet = this.collectionDocIds.get(collection);
     if (colSet) {
@@ -73,34 +98,48 @@ class SynapseConnectome {
     }
     return true;
   }
-  removeDocumentOwnedIndices(nodeId) {
+  removeDocumentOutgoingEdges(nodeId) {
     const outSet = this.outgoingEdges.get(nodeId);
-    if (outSet) {
-      for (const targetNodeId of outSet) {
-        const inSet = this.incomingEdges.get(targetNodeId);
-        if (inSet) {
-          inSet.delete(nodeId);
-          if (inSet.size === 0) {
-            this.incomingEdges.delete(targetNodeId);
-          }
+    if (!outSet)
+      return;
+    for (const targetNodeId of outSet) {
+      const inSet = this.incomingEdges.get(targetNodeId);
+      if (inSet) {
+        inSet.delete(nodeId);
+        if (inSet.size === 0) {
+          this.incomingEdges.delete(targetNodeId);
         }
-        this.edgeMeta.delete(`${nodeId}->${targetNodeId}`);
       }
-      this.outgoingEdges.delete(nodeId);
+      this.edgeMeta.delete(`${nodeId}->${targetNodeId}`);
     }
+    this.outgoingEdges.delete(nodeId);
+  }
+  removeDocumentSearchTokens(nodeId) {
     const oldTokens = this.documentTokens.get(nodeId);
-    if (oldTokens) {
-      for (const token of oldTokens) {
-        const nodeSet = this.tokenInvertedIndex.get(token);
-        if (nodeSet) {
-          nodeSet.delete(nodeId);
-          if (nodeSet.size === 0) {
-            this.tokenInvertedIndex.delete(token);
-          }
+    if (!oldTokens)
+      return;
+    for (const token of oldTokens) {
+      const nodeSet = this.tokenInvertedIndex.get(token);
+      if (nodeSet) {
+        nodeSet.delete(nodeId);
+        if (nodeSet.size === 0) {
+          this.tokenInvertedIndex.delete(token);
         }
       }
-      this.documentTokens.delete(nodeId);
     }
+    this.documentTokens.delete(nodeId);
+  }
+  flushDirtySearchIndex() {
+    if (this.dirtySearchNodes.size === 0)
+      return;
+    for (const nodeId of this.dirtySearchNodes) {
+      this.removeDocumentSearchTokens(nodeId);
+      const doc = this.documents.get(nodeId);
+      if (doc) {
+        this.indexDocumentText(nodeId, doc);
+      }
+    }
+    this.dirtySearchNodes.clear();
   }
   getDocument(collection, id) {
     const nodeId = SynapseConnectome.makeNodeId(collection, id);
@@ -139,6 +178,7 @@ class SynapseConnectome {
     return results;
   }
   verifyGraphInvariants() {
+    this.flushDirtySearchIndex();
     const brokenOutgoing = [];
     const brokenIncoming = [];
     const ghostTokens = [];
@@ -199,6 +239,7 @@ class SynapseConnectome {
     return docs.slice(offset, offset + limit);
   }
   search(query, collectionFilter) {
+    this.flushDirtySearchIndex();
     const tokens = this.tokenize(query);
     if (tokens.length === 0)
       return [];
@@ -279,32 +320,94 @@ class SynapseConnectome {
 // serializer.ts
 import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "fs";
 import { dirname } from "path";
+var EMPTY_WIKILINKS = [];
 function extractWikilinks(text, defaultCollection = "") {
-  const regex = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+  if (!text)
+    return EMPTY_WIKILINKS;
+  let openIdx = text.indexOf("[[");
+  if (openIdx === -1)
+    return EMPTY_WIKILINKS;
   const links = [];
-  let match;
-  while ((match = regex.exec(text)) !== null) {
-    const rawTarget = match[1].trim();
-    if (!rawTarget)
-      continue;
-    const alias = match[2]?.trim();
-    let targetCollection = defaultCollection;
-    let targetId = rawTarget;
-    if (rawTarget.includes("/")) {
-      const parts = rawTarget.split("/");
-      targetCollection = parts[0].trim();
-      targetId = parts.slice(1).join("/").trim();
-    }
-    if (!targetId)
+  const textLen = text.length;
+  while (openIdx !== -1 && openIdx + 4 <= textLen) {
+    const closeIdx = text.indexOf("]]", openIdx + 2);
+    if (closeIdx === -1)
+      break;
+    const inner = text.slice(openIdx + 2, closeIdx);
+    const nestedOpen = inner.indexOf("[[");
+    if (nestedOpen !== -1) {
+      openIdx = openIdx + 2 + nestedOpen;
       continue;
-    links.push({
-      raw: match[0],
-      targetCollection,
-      targetId,
-      alias
-    });
+    }
+    let rawTarget = inner;
+    let alias;
+    const pipeIdx = inner.indexOf("|");
+    if (pipeIdx !== -1) {
+      rawTarget = inner.slice(0, pipeIdx).trim();
+      const rawAlias = inner.slice(pipeIdx + 1).trim();
+      if (rawAlias.length > 0)
+        alias = rawAlias;
+    } else {
+      rawTarget = inner.trim();
+    }
+    if (rawTarget.length > 0) {
+      let targetCollection = defaultCollection;
+      let targetId = rawTarget;
+      const slashIdx = rawTarget.indexOf("/");
+      if (slashIdx !== -1) {
+        targetCollection = rawTarget.slice(0, slashIdx).trim();
+        targetId = rawTarget.slice(slashIdx + 1).trim();
+      }
+      if (targetId.length > 0) {
+        links.push({
+          raw: text.slice(openIdx, closeIdx + 2),
+          targetCollection,
+          targetId,
+          alias
+        });
+      }
+    }
+    openIdx = text.indexOf("[[", closeIdx + 2);
+  }
+  return links.length > 0 ? links : EMPTY_WIKILINKS;
+}
+function extractWikilinksFromDataAndBody(data, body, defaultCollection = "") {
+  let result = null;
+  if (data && typeof data === "object") {
+    for (const key in data) {
+      const val = data[key];
+      if (typeof val === "string" && val.includes("[[")) {
+        const extracted = extractWikilinks(val, defaultCollection);
+        if (extracted.length > 0) {
+          if (!result)
+            result = [];
+          for (let i = 0;i < extracted.length; i++)
+            result.push(extracted[i]);
+        }
+      } else if (typeof val === "object" && val !== null) {
+        const jsonStr = JSON.stringify(val);
+        if (jsonStr.includes("[[")) {
+          const extracted = extractWikilinks(jsonStr, defaultCollection);
+          if (extracted.length > 0) {
+            if (!result)
+              result = [];
+            for (let i = 0;i < extracted.length; i++)
+              result.push(extracted[i]);
+          }
+        }
+      }
+    }
+  }
+  if (body && body.includes("[[")) {
+    const bodyLinks = extractWikilinks(body, defaultCollection);
+    if (bodyLinks.length > 0) {
+      if (!result)
+        return bodyLinks;
+      for (let i = 0;i < bodyLinks.length; i++)
+        result.push(bodyLinks[i]);
+    }
   }
-  return links;
+  return result ?? EMPTY_WIKILINKS;
 }
 function parseMarkdownFile(rawContent, defaultCollection = "") {
   const normalizedRaw = rawContent.replace(/\r\n/g, `
@@ -505,14 +608,766 @@ function atomicWriteFile(targetPath, content) {
   }
 }
 
+// wal/index.ts
+import { join } from "path";
+
+// wal/config.ts
+var WAL_CONFIG_DEFAULTS = {
+  RING_BUFFER_CAPACITY: Number(process.env.SYNAPSE_WAL_RING_CAPACITY) || 4096,
+  ARENA_INITIAL_CAPACITY: Number(process.env.SYNAPSE_WAL_ARENA_CAPACITY) || 256,
+  ARENA_MAX_CAPACITY: Number(process.env.SYNAPSE_WAL_ARENA_MAX_CAPACITY) || 65536,
+  SQLITE_WAL_FILENAME: process.env.SYNAPSE_WAL_SQLITE_FILENAME || "synapse_causal_wal.sqlite",
+  SQLITE_MMAP_SIZE_BYTES: Number(process.env.SYNAPSE_WAL_MMAP_BYTES) || 268435456,
+  SQLITE_BUSY_TIMEOUT_MS: Number(process.env.SYNAPSE_WAL_BUSY_TIMEOUT_MS) || 5000,
+  SQLITE_SYNC_MODE: process.env.SYNAPSE_WAL_SYNC_MODE || "NORMAL"
+};
+var CausalWalEventType;
+((CausalWalEventType) => {
+  CausalWalEventType["DOC_UPSERT"] = "DOC_UPSERT";
+  CausalWalEventType["DOC_DELETE"] = "DOC_DELETE";
+  CausalWalEventType["EDGE_LINK"] = "EDGE_LINK";
+  CausalWalEventType["EDGE_UNLINK"] = "EDGE_UNLINK";
+  CausalWalEventType["COMPILER_METRIC"] = "COMPILER_METRIC";
+  CausalWalEventType["CHECKPOINT_MARK"] = "CHECKPOINT_MARK";
+})(CausalWalEventType ||= {});
+
+// wal/ringBuffer.ts
+class TemporalRingBuffer {
+  capacity;
+  isPowerOfTwo;
+  bitMask;
+  slots;
+  lsnBuffer;
+  tsBuffer;
+  head = 0;
+  tail = 0;
+  count = 0;
+  nextLsn = 1;
+  overwrittenCount = 0;
+  constructor(capacity = WAL_CONFIG_DEFAULTS.RING_BUFFER_CAPACITY) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error(`[TemporalRingBuffer] \uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uB9C1 \uBC84\uD37C \uC6A9\uB7C9\uC785\uB2C8\uB2E4: ${capacity}`);
+    }
+    this.capacity = capacity;
+    this.isPowerOfTwo = (capacity & capacity - 1) === 0;
+    this.bitMask = capacity - 1;
+    this.slots = new Array(capacity);
+    this.lsnBuffer = new Float64Array(capacity);
+    this.tsBuffer = new Float64Array(capacity);
+  }
+  wrapIndex(idx) {
+    return this.isPowerOfTwo ? idx & this.bitMask : idx % this.capacity;
+  }
+  append(entryInput) {
+    const lsn = this.nextLsn++;
+    const timestampMs = entryInput.timestampMs ?? Date.now();
+    const entry = {
+      lsn,
+      timestampMs,
+      eventType: entryInput.eventType,
+      collection: entryInput.collection,
+      docId: entryInput.docId,
+      prevDoc: entryInput.prevDoc,
+      nextDoc: entryInput.nextDoc,
+      edgesAdded: entryInput.edgesAdded,
+      edgesRemoved: entryInput.edgesRemoved,
+      compilerMetric: entryInput.compilerMetric
+    };
+    this.writeRawEntry(entry);
+    return entry;
+  }
+  appendRecovered(entry) {
+    if (entry.lsn >= this.nextLsn) {
+      this.nextLsn = entry.lsn + 1;
+    }
+    this.writeRawEntry(entry);
+  }
+  writeRawEntry(entry) {
+    const t = this.tail;
+    this.slots[t] = entry;
+    this.lsnBuffer[t] = entry.lsn;
+    this.tsBuffer[t] = entry.timestampMs;
+    const nextTail = this.isPowerOfTwo ? t + 1 & this.bitMask : (t + 1) % this.capacity;
+    this.tail = nextTail;
+    if (this.count === this.capacity) {
+      this.head = nextTail;
+      this.overwrittenCount++;
+    } else {
+      this.count++;
+    }
+  }
+  getByLsn(targetLsn) {
+    if (this.count === 0)
+      return null;
+    const oldestLsn = this.lsnBuffer[this.head];
+    const newestIdx = this.wrapIndex(this.tail - 1 + this.capacity);
+    const newestLsn = this.lsnBuffer[newestIdx];
+    if (targetLsn < oldestLsn || targetLsn > newestLsn) {
+      return null;
+    }
+    const offset = targetLsn - oldestLsn;
+    if (offset < this.count) {
+      const candidateIdx = this.wrapIndex(this.head + offset);
+      if (this.lsnBuffer[candidateIdx] === targetLsn) {
+        return this.slots[candidateIdx] || null;
+      }
+    }
+    for (let i = 0;i < this.count; i++) {
+      const idx = this.wrapIndex(this.head + i);
+      if (this.lsnBuffer[idx] === targetLsn) {
+        return this.slots[idx] || null;
+      }
+    }
+    return null;
+  }
+  forEachReverse(visitor) {
+    for (let i = this.count - 1;i >= 0; i--) {
+      const idx = (this.head + i) % this.capacity;
+      const entry = this.slots[idx];
+      if (entry) {
+        const shouldContinue = visitor(entry);
+        if (shouldContinue === false)
+          break;
+      }
+    }
+  }
+  toArray() {
+    const result = new Array(this.count);
+    for (let i = 0;i < this.count; i++) {
+      const idx = (this.head + i) % this.capacity;
+      result[i] = this.slots[idx];
+    }
+    return result;
+  }
+  getEntriesSinceLsn(afterLsn) {
+    const result = [];
+    for (let i = 0;i < this.count; i++) {
+      const idx = (this.head + i) % this.capacity;
+      const entry = this.slots[idx];
+      if (entry && entry.lsn > afterLsn) {
+        result.push(entry);
+      }
+    }
+    return result;
+  }
+  getCurrentLsn() {
+    return this.nextLsn - 1;
+  }
+  getOldestLsn() {
+    if (this.count === 0)
+      return 0;
+    return this.lsnBuffer[this.head];
+  }
+  getStats() {
+    return {
+      capacity: this.capacity,
+      size: this.count,
+      currentLsn: this.getCurrentLsn(),
+      oldestLsn: this.getOldestLsn(),
+      overwrittenCount: this.overwrittenCount,
+      utilizationRatio: Number((this.count / this.capacity).toFixed(4))
+    };
+  }
+  clear() {
+    this.slots.fill(undefined);
+    this.lsnBuffer.fill(0);
+    this.tsBuffer.fill(0);
+    this.head = 0;
+    this.tail = 0;
+    this.count = 0;
+    this.nextLsn = 1;
+    this.overwrittenCount = 0;
+  }
+}
+
+// wal/arena.ts
+class CausalArenaAllocator {
+  pool;
+  cursor = 0;
+  inTransaction = false;
+  totalCommitted = 0;
+  totalRolledBack = 0;
+  totalSlotReuses = 0;
+  constructor(initialCapacity = WAL_CONFIG_DEFAULTS.ARENA_INITIAL_CAPACITY) {
+    this.pool = new Array(initialCapacity);
+    for (let i = 0;i < initialCapacity; i++) {
+      this.pool[i] = this.createEmptySlot();
+    }
+  }
+  createEmptySlot() {
+    return {
+      eventType: "DOC_UPSERT" /* DOC_UPSERT */,
+      collection: "",
+      docId: "",
+      prevDoc: null,
+      nextDoc: null,
+      edgesAdded: [],
+      edgesRemoved: [],
+      rawMarkdown: null,
+      targetDiskPath: null,
+      compilerMetric: undefined
+    };
+  }
+  beginScope() {
+    if (this.inTransaction) {
+      throw new Error("[CausalArenaAllocator] \uC911\uCCA9 \uD2B8\uB79C\uC7AD\uC158\uC740 \uC774\uBBF8 \uD65C\uC131\uD654\uB41C \uC2A4\uCF54\uD504\uAC00 \uC874\uC7AC\uD569\uB2C8\uB2E4.");
+    }
+    this.inTransaction = true;
+    this.cursor = 0;
+  }
+  isScopeActive() {
+    return this.inTransaction;
+  }
+  allocSlot(eventType, collection, docId, prevDoc, nextDoc, edgesAdded, edgesRemoved, rawMarkdown = null, targetDiskPath = null, compilerMetric) {
+    if (this.cursor >= this.pool.length) {
+      if (this.pool.length >= WAL_CONFIG_DEFAULTS.ARENA_MAX_CAPACITY) {
+        throw new Error(`[CausalArenaAllocator] \uC544\uB808\uB098 \uCD5C\uB300 \uC6A9\uB7C9 \uC0C1\uD55C\uC120(${WAL_CONFIG_DEFAULTS.ARENA_MAX_CAPACITY})\uC744 \uCD08\uACFC\uD588\uC2B5\uB2C8\uB2E4.`);
+      }
+      const expandCount = Math.min(this.pool.length, WAL_CONFIG_DEFAULTS.ARENA_MAX_CAPACITY - this.pool.length);
+      for (let i = 0;i < expandCount; i++) {
+        this.pool.push(this.createEmptySlot());
+      }
+    } else {
+      this.totalSlotReuses++;
+    }
+    const slot = this.pool[this.cursor++];
+    slot.eventType = eventType;
+    slot.collection = collection;
+    slot.docId = docId;
+    slot.prevDoc = prevDoc;
+    slot.nextDoc = nextDoc;
+    slot.edgesAdded = edgesAdded;
+    slot.edgesRemoved = edgesRemoved;
+    slot.rawMarkdown = rawMarkdown;
+    slot.targetDiskPath = targetDiskPath;
+    slot.compilerMetric = compilerMetric;
+    return slot;
+  }
+  getActiveSlots() {
+    return this.pool.slice(0, this.cursor);
+  }
+  commitAndReset() {
+    this.clearReferencesUpToCursor();
+    this.cursor = 0;
+    this.inTransaction = false;
+    this.totalCommitted++;
+  }
+  rollbackAndReset() {
+    this.clearReferencesUpToCursor();
+    this.cursor = 0;
+    this.inTransaction = false;
+    this.totalRolledBack++;
+  }
+  clearReferencesUpToCursor() {
+    for (let i = 0;i < this.cursor; i++) {
+      const slot = this.pool[i];
+      slot.prevDoc = null;
+      slot.nextDoc = null;
+      slot.rawMarkdown = null;
+      slot.targetDiskPath = null;
+      slot.compilerMetric = undefined;
+    }
+  }
+  getStats() {
+    return {
+      poolCapacity: this.pool.length,
+      activeCursor: this.cursor,
+      totalTransactionsCommitted: this.totalCommitted,
+      totalTransactionsRolledBack: this.totalRolledBack,
+      totalSlotReuses: this.totalSlotReuses
+    };
+  }
+}
+
+// wal/sqliteWalStore.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2, resolve } from "path";
+import { Database } from "bun:sqlite";
+class SqliteCausalWalStore {
+  syncMode;
+  dbPath;
+  sqlite = null;
+  insertStmt = null;
+  batchTx = null;
+  lastFlushedLsn = 0;
+  constructor(dbPath, syncMode = WAL_CONFIG_DEFAULTS.SQLITE_SYNC_MODE) {
+    this.syncMode = syncMode;
+    this.dbPath = resolve(dbPath);
+  }
+  init() {
+    if (this.sqlite)
+      return;
+    try {
+      const parentDir = dirname2(this.dbPath);
+      if (!existsSync2(parentDir)) {
+        mkdirSync2(parentDir, { recursive: true });
+      }
+      this.sqlite = new Database(this.dbPath, { create: true });
+      this.sqlite.exec(`PRAGMA journal_mode = WAL;`);
+      this.sqlite.exec(`PRAGMA synchronous = ${this.syncMode};`);
+      this.sqlite.exec(`PRAGMA temp_store = MEMORY;`);
+      this.sqlite.exec(`PRAGMA mmap_size = ${WAL_CONFIG_DEFAULTS.SQLITE_MMAP_SIZE_BYTES};`);
+      this.sqlite.exec(`PRAGMA busy_timeout = ${WAL_CONFIG_DEFAULTS.SQLITE_BUSY_TIMEOUT_MS};`);
+      this.sqlite.exec(`
+        CREATE TABLE IF NOT EXISTS causal_wal_log (
+          lsn INTEGER PRIMARY KEY,
+          timestamp_ms INTEGER NOT NULL,
+          event_type TEXT NOT NULL,
+          collection TEXT NOT NULL,
+          doc_id TEXT NOT NULL,
+          prev_doc_json TEXT,
+          next_doc_json TEXT,
+          edges_added_json TEXT NOT NULL,
+          edges_removed_json TEXT NOT NULL,
+          compiler_metric_json TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_causal_wal_ts ON causal_wal_log(timestamp_ms);
+        CREATE INDEX IF NOT EXISTS idx_causal_wal_doc ON causal_wal_log(collection, doc_id);
+      `);
+      const maxRow = this.sqlite.query(`SELECT MAX(lsn) as max_lsn FROM causal_wal_log`).get();
+      this.lastFlushedLsn = maxRow?.max_lsn ?? 0;
+      const stmt = this.sqlite.prepare(`
+        INSERT OR REPLACE INTO causal_wal_log (
+          lsn, timestamp_ms, event_type, collection, doc_id,
+          prev_doc_json, next_doc_json, edges_added_json, edges_removed_json, compiler_metric_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+      this.insertStmt = stmt;
+      this.batchTx = this.sqlite.transaction((items) => {
+        let written = 0;
+        for (let i = 0;i < items.length; i++) {
+          const item = items[i];
+          if (item.lsn <= this.lastFlushedLsn)
+            continue;
+          stmt.run(item.lsn, item.timestampMs, item.eventType, item.collection, item.docId, item.prevDoc ? JSON.stringify(item.prevDoc) : null, item.nextDoc ? JSON.stringify(item.nextDoc) : null, item.edgesAdded.length === 0 ? "[]" : JSON.stringify(item.edgesAdded), item.edgesRemoved.length === 0 ? "[]" : JSON.stringify(item.edgesRemoved), item.compilerMetric ? JSON.stringify(item.compilerMetric) : null);
+          if (item.lsn > this.lastFlushedLsn) {
+            this.lastFlushedLsn = item.lsn;
+          }
+          written++;
+        }
+        return written;
+      });
+    } catch (err) {
+      throw new Error(`[SqliteCausalWalStore] SQLite WAL \uCD08\uAE30\uD654 \uC2E4\uD328 (${this.dbPath}): ${err?.message || err}`);
+    }
+  }
+  flushEntries(entries) {
+    if (!this.sqlite || !this.batchTx || entries.length === 0)
+      return 0;
+    try {
+      return this.batchTx(entries);
+    } catch (err) {
+      throw new Error(`[SqliteCausalWalStore] WAL \uC5D4\uD2B8\uB9AC \uBC30\uCE58 \uD50C\uB7EC\uC2DC \uC2E4\uD328: ${err?.message || err}`);
+    }
+  }
+  loadAllEntries() {
+    if (!this.sqlite)
+      return [];
+    try {
+      const rows = this.sqlite.query(`SELECT * FROM causal_wal_log ORDER BY lsn ASC`).all();
+      return rows.map((row) => ({
+        lsn: row.lsn,
+        timestampMs: row.timestamp_ms,
+        eventType: row.event_type,
+        collection: row.collection,
+        docId: row.doc_id,
+        prevDoc: row.prev_doc_json ? JSON.parse(row.prev_doc_json) : null,
+        nextDoc: row.next_doc_json ? JSON.parse(row.next_doc_json) : null,
+        edgesAdded: JSON.parse(row.edges_added_json),
+        edgesRemoved: JSON.parse(row.edges_removed_json),
+        compilerMetric: row.compiler_metric_json ? JSON.parse(row.compiler_metric_json) : undefined
+      }));
+    } catch (err) {
+      throw new Error(`[SqliteCausalWalStore] WAL \uBCF5\uAD6C \uB85C\uADF8 \uB85C\uB4DC \uC2E4\uD328: ${err?.message || err}`);
+    }
+  }
+  getJournalMode() {
+    if (!this.sqlite)
+      return "closed";
+    const row = this.sqlite.query(`PRAGMA journal_mode;`).get();
+    return row?.journal_mode ?? "unknown";
+  }
+  getLastFlushedLsn() {
+    return this.lastFlushedLsn;
+  }
+  getPersistedCount() {
+    if (!this.sqlite)
+      return 0;
+    const row = this.sqlite.query(`SELECT COUNT(*) as cnt FROM causal_wal_log`).get();
+    return row?.cnt ?? 0;
+  }
+  close() {
+    if (!this.sqlite)
+      return;
+    try {
+      this.insertStmt?.finalize();
+    } catch {}
+    this.insertStmt = null;
+    this.batchTx = null;
+    try {
+      this.sqlite.exec(`PRAGMA wal_checkpoint(TRUNCATE);`);
+    } catch {}
+    try {
+      this.sqlite.close();
+    } catch {}
+    this.sqlite = null;
+  }
+}
+
+// wal/timeTravel.ts
+class CausalTimeTravelEngine {
+  static asOfLsn(currentConnectome, ringBuffer, targetLsn) {
+    const currentLsn = ringBuffer.getCurrentLsn();
+    if (targetLsn < 0) {
+      throw new Error(`[CausalTimeTravelEngine] \uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uBAA9\uD45C LSN\uC785\uB2C8\uB2E4: ${targetLsn}`);
+    }
+    const docMap = new Map;
+    for (const doc of currentConnectome.getAllDocuments()) {
+      const nodeId = SynapseConnectome.makeNodeId(doc.collection, doc.id);
+      docMap.set(nodeId, doc);
+    }
+    if (targetLsn < currentLsn) {
+      ringBuffer.forEachReverse((entry) => {
+        if (entry.lsn <= targetLsn) {
+          return false;
+        }
+        if (entry.eventType === "DOC_UPSERT" /* DOC_UPSERT */ || entry.eventType === "DOC_DELETE" /* DOC_DELETE */) {
+          const nodeId = SynapseConnectome.makeNodeId(entry.collection, entry.docId);
+          if (entry.prevDoc !== null) {
+            docMap.set(nodeId, entry.prevDoc);
+          } else {
+            docMap.delete(nodeId);
+          }
+        }
+        return true;
+      });
+    }
+    const snapshotConnectome = new SynapseConnectome;
+    for (const doc of docMap.values()) {
+      snapshotConnectome.putDocument(doc);
+    }
+    return snapshotConnectome;
+  }
+  static asOf(currentConnectome, ringBuffer, timestampMsOrIso) {
+    const targetMs = typeof timestampMsOrIso === "number" ? timestampMsOrIso : new Date(timestampMsOrIso).getTime();
+    if (Number.isNaN(targetMs)) {
+      throw new Error(`[CausalTimeTravelEngine] \uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uD0C0\uC784\uC2A4\uD0EC\uD504 \uD615\uC2DD\uC785\uB2C8\uB2E4: ${timestampMsOrIso}`);
+    }
+    let resolvedLsn = 0;
+    ringBuffer.forEachReverse((entry) => {
+      if (entry.timestampMs <= targetMs) {
+        resolvedLsn = entry.lsn;
+        return false;
+      }
+      return true;
+    });
+    return CausalTimeTravelEngine.asOfLsn(currentConnectome, ringBuffer, resolvedLsn);
+  }
+  static diffBetweenLsn(ringBuffer, fromLsn, toLsn) {
+    const addedSet = new Set;
+    const modifiedSet = new Set;
+    const deletedSet = new Set;
+    const linkedSet = new Set;
+    const unlinkedSet = new Set;
+    const compilerMetrics = [];
+    const entries = ringBuffer.getEntriesSinceLsn(fromLsn);
+    for (const entry of entries) {
+      if (entry.lsn > toLsn)
+        break;
+      const nodeId = SynapseConnectome.makeNodeId(entry.collection, entry.docId);
+      if (entry.eventType === "DOC_UPSERT" /* DOC_UPSERT */) {
+        deletedSet.delete(nodeId);
+        if (entry.prevDoc === null) {
+          addedSet.add(nodeId);
+        } else if (!addedSet.has(nodeId)) {
+          modifiedSet.add(nodeId);
+        }
+      } else if (entry.eventType === "DOC_DELETE" /* DOC_DELETE */) {
+        if (addedSet.has(nodeId)) {
+          addedSet.delete(nodeId);
+        } else {
+          modifiedSet.delete(nodeId);
+          deletedSet.add(nodeId);
+        }
+      } else if (entry.eventType === "COMPILER_METRIC" /* COMPILER_METRIC */ && entry.compilerMetric) {
+        compilerMetrics.push(entry.compilerMetric);
+      }
+      for (const edge of entry.edgesAdded) {
+        const edgeKey = `${nodeId}->${edge}`;
+        unlinkedSet.delete(edgeKey);
+        linkedSet.add(edgeKey);
+      }
+      for (const edge of entry.edgesRemoved) {
+        const edgeKey = `${nodeId}->${edge}`;
+        linkedSet.delete(edgeKey);
+        unlinkedSet.add(edgeKey);
+      }
+    }
+    return {
+      fromLsn,
+      toLsn,
+      addedDocuments: Array.from(addedSet),
+      modifiedDocuments: Array.from(modifiedSet),
+      deletedDocuments: Array.from(deletedSet),
+      edgesLinked: Array.from(linkedSet),
+      edgesUnlinked: Array.from(unlinkedSet),
+      compilerMetrics
+    };
+  }
+}
+
+// wal/index.ts
+var EMPTY_EDGES = [];
+var EMPTY_EDGE_DIFF = { edgesAdded: EMPTY_EDGES, edgesRemoved: EMPTY_EDGES };
+
+class CausalWalEngine {
+  ringBuffer;
+  arena;
+  sqliteStore;
+  constructor(vaultDir, config2) {
+    this.ringBuffer = new TemporalRingBuffer(config2?.ringCapacity ?? WAL_CONFIG_DEFAULTS.RING_BUFFER_CAPACITY);
+    this.arena = new CausalArenaAllocator(config2?.arenaCapacity ?? WAL_CONFIG_DEFAULTS.ARENA_INITIAL_CAPACITY);
+    if (config2?.persistSqlite || config2?.sqlitePath) {
+      const targetSqlitePath = config2.sqlitePath || join(vaultDir, WAL_CONFIG_DEFAULTS.SQLITE_WAL_FILENAME);
+      this.sqliteStore = new SqliteCausalWalStore(targetSqlitePath, config2.syncMode ?? WAL_CONFIG_DEFAULTS.SQLITE_SYNC_MODE);
+    } else {
+      this.sqliteStore = null;
+    }
+  }
+  initAndRecover(connectome) {
+    if (!this.sqliteStore)
+      return 0;
+    this.sqliteStore.init();
+    const persistedEntries = this.sqliteStore.loadAllEntries();
+    let recoveredCount = 0;
+    for (const entry of persistedEntries) {
+      this.ringBuffer.appendRecovered(entry);
+      if (entry.eventType === "DOC_UPSERT" /* DOC_UPSERT */ && entry.nextDoc) {
+        connectome.putDocument(entry.nextDoc);
+        recoveredCount++;
+      } else if (entry.eventType === "DOC_DELETE" /* DOC_DELETE */) {
+        connectome.removeDocument(entry.collection, entry.docId);
+        recoveredCount++;
+      }
+    }
+    return recoveredCount;
+  }
+  static computeEdgeDiff(prevDoc, nextDoc) {
+    const prevLinks = prevDoc ? prevDoc.wikilinks : EMPTY_EDGES;
+    const nextLinks = nextDoc ? nextDoc.wikilinks : EMPTY_EDGES;
+    const prevLen = prevLinks.length;
+    const nextLen = nextLinks.length;
+    if (prevLen === 0 && nextLen === 0) {
+      return EMPTY_EDGE_DIFF;
+    }
+    if (prevLen === 0 && nextLen === 1 && nextDoc) {
+      const l = nextDoc.wikilinks[0];
+      return {
+        edgesAdded: [SynapseConnectome.makeNodeId(l.targetCollection || nextDoc.collection, l.targetId)],
+        edgesRemoved: EMPTY_EDGES
+      };
+    }
+    if (prevLen === 1 && nextLen === 1 && prevDoc && nextDoc) {
+      const pl = prevDoc.wikilinks[0];
+      const nl = nextDoc.wikilinks[0];
+      const pTarget = SynapseConnectome.makeNodeId(pl.targetCollection || prevDoc.collection, pl.targetId);
+      const nTarget = SynapseConnectome.makeNodeId(nl.targetCollection || nextDoc.collection, nl.targetId);
+      if (pTarget === nTarget) {
+        return EMPTY_EDGE_DIFF;
+      }
+      return {
+        edgesAdded: [nTarget],
+        edgesRemoved: [pTarget]
+      };
+    }
+    const prevTargets = new Set;
+    const nextTargets = new Set;
+    if (prevDoc) {
+      for (let i = 0;i < prevLen; i++) {
+        const link = prevDoc.wikilinks[i];
+        prevTargets.add(SynapseConnectome.makeNodeId(link.targetCollection || prevDoc.collection, link.targetId));
+      }
+    }
+    if (nextDoc) {
+      for (let i = 0;i < nextLen; i++) {
+        const link = nextDoc.wikilinks[i];
+        nextTargets.add(SynapseConnectome.makeNodeId(link.targetCollection || nextDoc.collection, link.targetId));
+      }
+    }
+    const edgesAdded = [];
+    const edgesRemoved = [];
+    for (const target of nextTargets) {
+      if (!prevTargets.has(target)) {
+        edgesAdded.push(target);
+      }
+    }
+    for (const target of prevTargets) {
+      if (!nextTargets.has(target)) {
+        edgesRemoved.push(target);
+      }
+    }
+    return { edgesAdded, edgesRemoved };
+  }
+  recordDocumentUpsert(prevDoc, nextDoc, rawMarkdown = null, targetDiskPath = null, timestampMs) {
+    const { edgesAdded, edgesRemoved } = CausalWalEngine.computeEdgeDiff(prevDoc, nextDoc);
+    if (this.arena.isScopeActive()) {
+      this.arena.allocSlot("DOC_UPSERT" /* DOC_UPSERT */, nextDoc.collection, nextDoc.id, prevDoc, nextDoc, edgesAdded, edgesRemoved, rawMarkdown, targetDiskPath);
+      return null;
+    }
+    const entry = this.ringBuffer.append({
+      timestampMs,
+      eventType: "DOC_UPSERT" /* DOC_UPSERT */,
+      collection: nextDoc.collection,
+      docId: nextDoc.id,
+      prevDoc,
+      nextDoc,
+      edgesAdded,
+      edgesRemoved
+    });
+    if (this.sqliteStore) {
+      this.sqliteStore.flushEntries([entry]);
+    }
+    return entry;
+  }
+  recordDocumentDelete(prevDoc, targetDiskPath = null, timestampMs) {
+    const { edgesAdded, edgesRemoved } = CausalWalEngine.computeEdgeDiff(prevDoc, null);
+    if (this.arena.isScopeActive()) {
+      this.arena.allocSlot("DOC_DELETE" /* DOC_DELETE */, prevDoc.collection, prevDoc.id, prevDoc, null, edgesAdded, edgesRemoved, null, targetDiskPath);
+      return null;
+    }
+    const entry = this.ringBuffer.append({
+      timestampMs,
+      eventType: "DOC_DELETE" /* DOC_DELETE */,
+      collection: prevDoc.collection,
+      docId: prevDoc.id,
+      prevDoc,
+      nextDoc: null,
+      edgesAdded,
+      edgesRemoved
+    });
+    if (this.sqliteStore) {
+      this.sqliteStore.flushEntries([entry]);
+    }
+    return entry;
+  }
+  recordCompilerMetric(metric, timestampMs) {
+    const entry = this.ringBuffer.append({
+      timestampMs,
+      eventType: "COMPILER_METRIC" /* COMPILER_METRIC */,
+      collection: "_compiler_metrics",
+      docId: metric.targetFile,
+      prevDoc: null,
+      nextDoc: null,
+      edgesAdded: [],
+      edgesRemoved: [],
+      compilerMetric: metric
+    });
+    if (this.sqliteStore) {
+      this.sqliteStore.flushEntries([entry]);
+    }
+    return entry;
+  }
+  executeArenaTransaction(fn, onCommitSlot) {
+    this.arena.beginScope();
+    try {
+      const result = fn();
+      const activeSlots = this.arena.getActiveSlots();
+      const committedEntries = [];
+      for (const slot of activeSlots) {
+        onCommitSlot(slot);
+        const entry = this.ringBuffer.append({
+          eventType: slot.eventType,
+          collection: slot.collection,
+          docId: slot.docId,
+          prevDoc: slot.prevDoc,
+          nextDoc: slot.nextDoc,
+          edgesAdded: [...slot.edgesAdded],
+          edgesRemoved: [...slot.edgesRemoved],
+          compilerMetric: slot.compilerMetric
+        });
+        committedEntries.push(entry);
+      }
+      this.arena.commitAndReset();
+      if (this.sqliteStore && committedEntries.length > 0) {
+        this.sqliteStore.flushEntries(committedEntries);
+      }
+      return result;
+    } catch (err) {
+      this.arena.rollbackAndReset();
+      throw err;
+    }
+  }
+  async executeArenaTransactionAsync(fn, onCommitSlot) {
+    this.arena.beginScope();
+    try {
+      const result = await fn();
+      const activeSlots = this.arena.getActiveSlots();
+      const committedEntries = [];
+      for (const slot of activeSlots) {
+        onCommitSlot(slot);
+        const entry = this.ringBuffer.append({
+          eventType: slot.eventType,
+          collection: slot.collection,
+          docId: slot.docId,
+          prevDoc: slot.prevDoc,
+          nextDoc: slot.nextDoc,
+          edgesAdded: [...slot.edgesAdded],
+          edgesRemoved: [...slot.edgesRemoved],
+          compilerMetric: slot.compilerMetric
+        });
+        committedEntries.push(entry);
+      }
+      this.arena.commitAndReset();
+      if (this.sqliteStore && committedEntries.length > 0) {
+        this.sqliteStore.flushEntries(committedEntries);
+      }
+      return result;
+    } catch (err) {
+      this.arena.rollbackAndReset();
+      throw err;
+    }
+  }
+  asOfLsn(connectome, targetLsn) {
+    return CausalTimeTravelEngine.asOfLsn(connectome, this.ringBuffer, targetLsn);
+  }
+  asOf(connectome, timestampMsOrIso) {
+    return CausalTimeTravelEngine.asOf(connectome, this.ringBuffer, timestampMsOrIso);
+  }
+  diffBetweenLsn(fromLsn, toLsn) {
+    return CausalTimeTravelEngine.diffBetweenLsn(this.ringBuffer, fromLsn, toLsn);
+  }
+  getStats() {
+    return {
+      ringBuffer: this.ringBuffer.getStats(),
+      arena: this.arena.getStats(),
+      sqlite: {
+        enabled: this.sqliteStore !== null,
+        dbPath: this.sqliteStore?.dbPath ?? null,
+        journalMode: this.sqliteStore ? this.sqliteStore.getJournalMode() : "disabled",
+        lastFlushedLsn: this.sqliteStore ? this.sqliteStore.getLastFlushedLsn() : 0,
+        persistedCount: this.sqliteStore ? this.sqliteStore.getPersistedCount() : 0
+      }
+    };
+  }
+  close() {
+    if (this.sqliteStore) {
+      this.sqliteStore.close();
+    }
+  }
+}
+
 // engine.ts
 class SynapseEngine {
   vaultDir;
   connectome;
+  wal;
   config;
   isInitialized = false;
   pendingWriteQueue = new Map;
   writeTimer = null;
+  nextTimerFlushAtMs = 0;
+  cachedIsoMs = -1;
+  cachedIsoStr = "";
   watcherDebounceTimer = null;
   internalWriteResetTimer = null;
   fileWatcher = null;
@@ -522,18 +1377,20 @@ class SynapseEngine {
       autoWatch: true,
       persistDebounceMs: 100,
       ...config,
-      vaultDir: resolve(config.vaultDir)
+      vaultDir: resolve2(config.vaultDir)
     };
     this.vaultDir = this.config.vaultDir;
     this.connectome = new SynapseConnectome;
+    this.wal = new CausalWalEngine(this.vaultDir, this.config.wal);
   }
   async init() {
     if (this.isInitialized)
       return;
-    if (!existsSync2(this.vaultDir)) {
-      mkdirSync2(this.vaultDir, { recursive: true });
+    if (!existsSync3(this.vaultDir)) {
+      mkdirSync3(this.vaultDir, { recursive: true });
     }
     this.reloadVault();
+    this.wal.initAndRecover(this.connectome);
     if (this.config.autoWatch) {
       this.startWatcher();
     }
@@ -541,13 +1398,13 @@ class SynapseEngine {
   }
   reloadVault() {
     this.connectome.clear();
-    if (!existsSync2(this.vaultDir))
+    if (!existsSync3(this.vaultDir))
       return;
     const entries = readdirSync(this.vaultDir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory()) {
+      if (entry.isDirectory() && !entry.name.startsWith(".")) {
         const collectionName = entry.name;
-        const colPath = join(this.vaultDir, collectionName);
+        const colPath = join2(this.vaultDir, collectionName);
         this.loadCollectionDir(collectionName, colPath);
       }
     }
@@ -559,7 +1416,7 @@ class SynapseEngine {
         if (!file.endsWith(".md") || file.includes(".tmp"))
           continue;
         const id = basename(file, ".md");
-        const fullPath = join(dirPath, file);
+        const fullPath = join2(dirPath, file);
         try {
           const raw = readFileSync2(fullPath, "utf-8");
           const parsed = parseMarkdownFile(raw, collectionName);
@@ -585,39 +1442,74 @@ class SynapseEngine {
       }
     } catch {}
   }
+  getEffectiveDocument(collection, id) {
+    if (this.wal.arena.isScopeActive()) {
+      const slots = this.wal.arena.getActiveSlots();
+      for (let i = slots.length - 1;i >= 0; i--) {
+        const slot = slots[i];
+        if (slot.collection === collection && slot.docId === id) {
+          if (slot.eventType === "DOC_DELETE" /* DOC_DELETE */)
+            return null;
+          if (slot.eventType === "DOC_UPSERT" /* DOC_UPSERT */) {
+            return slot.nextDoc || null;
+          }
+        }
+      }
+    }
+    return this.connectome.getDocument(collection, id);
+  }
+  isValidSafeIdentifier(str) {
+    for (let i = 0;i < str.length; i++) {
+      const code = str.charCodeAt(i);
+      if (code === 47 || code === 92 || code === 58 || code === 42 || code === 63 || code === 34 || code === 60 || code === 62 || code === 124) {
+        return false;
+      }
+    }
+    return true;
+  }
+  getNowIso(nowMs) {
+    if (nowMs === this.cachedIsoMs) {
+      return this.cachedIsoStr;
+    }
+    this.cachedIsoMs = nowMs;
+    this.cachedIsoStr = new Date(nowMs).toISOString();
+    return this.cachedIsoStr;
+  }
   async saveDocument(collection, input) {
-    const now = new Date().toISOString();
-    const existing = this.connectome.getDocument(collection, input.id);
+    const nowMs = Date.now();
+    const now = this.getNowIso(nowMs);
+    const existing = this.getEffectiveDocument(collection, input.id);
     const createdAt = input.createdAt || existing?.createdAt || now;
     const updatedAt = input.updatedAt || now;
-    const cleanBody = (input.body || "").replace(/\r\n/g, `
-`).replace(/^\n+/, "").replace(/\n+$/, "");
-    const rawMarkdown = stringifyDocument({
-      ...input.data,
-      _createdAt: createdAt,
-      _updatedAt: updatedAt
-    }, cleanBody);
-    const parsed = parseMarkdownFile(rawMarkdown, collection);
-    const restoredFm = { ...parsed.frontmatter };
-    delete restoredFm._createdAt;
-    delete restoredFm._updatedAt;
+    const rawBody = input.body || "";
+    const cleanBody = rawBody.length > 0 && (rawBody.includes("\r") || rawBody.charCodeAt(0) === 10 || rawBody.charCodeAt(rawBody.length - 1) === 10) ? rawBody.replace(/\r\n/g, `
+`).replace(/^\n+/, "").replace(/\n+$/, "") : rawBody;
+    const wikilinks = extractWikilinksFromDataAndBody(input.data, cleanBody, collection);
     const finalDoc = {
       id: input.id,
       collection,
-      data: restoredFm,
-      body: parsed.body,
+      data: input.data,
+      body: cleanBody,
       createdAt,
       updatedAt,
-      wikilinks: parsed.wikilinks
+      wikilinks
     };
+    const safeCol = this.isValidSafeIdentifier(collection) ? collection : collection.replace(/[\/\\:*?"<>|]/g, "_");
+    const safeId = this.isValidSafeIdentifier(input.id) ? input.id : input.id.replace(/[\/\\:*?"<>|]/g, "_");
+    const targetPath = `${this.vaultDir}/${safeCol}/${safeId}.md`;
+    this.wal.recordDocumentUpsert(existing, finalDoc, null, targetPath, nowMs);
+    if (this.wal.arena.isScopeActive()) {
+      return finalDoc;
+    }
     this.connectome.putDocument(finalDoc);
-    const safeCol = collection.replace(/[\/\\:*?"<>|]/g, "_");
-    const safeId = input.id.replace(/[\/\\:*?"<>|]/g, "_");
-    const targetDir = join(this.vaultDir, safeCol);
-    const targetPath = join(targetDir, `${safeId}.md`);
     const writeKey = `${collection}/${input.id}`;
-    this.scheduleWrite(writeKey, () => {
+    this.scheduleWrite(writeKey, nowMs, () => {
       this.markInternalWrite();
+      const rawMarkdown = stringifyDocument({
+        ...finalDoc.data,
+        _createdAt: finalDoc.createdAt,
+        _updatedAt: finalDoc.updatedAt
+      }, finalDoc.body);
       atomicWriteFile(targetPath, rawMarkdown);
     });
     return finalDoc;
@@ -633,30 +1525,79 @@ class SynapseEngine {
     }, 120);
   }
   async deleteDocument(collection, id) {
-    const deleted = this.connectome.removeDocument(collection, id);
-    if (!deleted)
+    const existing = this.getEffectiveDocument(collection, id);
+    if (!existing)
       return false;
     const safeCol = collection.replace(/[\/\\:*?"<>|]/g, "_");
     const safeId = id.replace(/[\/\\:*?"<>|]/g, "_");
-    const targetPath = join(this.vaultDir, safeCol, `${safeId}.md`);
+    const targetPath = join2(this.vaultDir, safeCol, `${safeId}.md`);
+    this.wal.recordDocumentDelete(existing, targetPath);
+    if (this.wal.arena.isScopeActive()) {
+      return true;
+    }
+    const deleted = this.connectome.removeDocument(collection, id);
+    if (!deleted)
+      return false;
     const writeKey = `${collection}/${id}`;
     this.pendingWriteQueue.delete(writeKey);
     try {
-      if (existsSync2(targetPath)) {
+      if (existsSync3(targetPath)) {
         this.markInternalWrite();
         unlinkSync2(targetPath);
       }
     } catch {}
     return true;
   }
-  scheduleWrite(key, fn) {
+  async executeTransaction(fn) {
+    return this.wal.executeArenaTransactionAsync(fn, (slot) => {
+      if (slot.eventType === "DOC_UPSERT" /* DOC_UPSERT */ && slot.nextDoc) {
+        const committedDoc = slot.nextDoc;
+        this.connectome.putDocument(committedDoc);
+        if (slot.targetDiskPath) {
+          const targetPath = slot.targetDiskPath;
+          const writeKey = `${slot.collection}/${slot.docId}`;
+          this.scheduleWrite(writeKey, Date.now(), () => {
+            this.markInternalWrite();
+            const rawMarkdown = slot.rawMarkdown ?? stringifyDocument({
+              ...committedDoc.data,
+              _createdAt: committedDoc.createdAt,
+              _updatedAt: committedDoc.updatedAt
+            }, committedDoc.body);
+            atomicWriteFile(targetPath, rawMarkdown);
+          });
+        }
+      } else if (slot.eventType === "DOC_DELETE" /* DOC_DELETE */) {
+        this.connectome.removeDocument(slot.collection, slot.docId);
+        const writeKey = `${slot.collection}/${slot.docId}`;
+        this.pendingWriteQueue.delete(writeKey);
+        if (slot.targetDiskPath) {
+          try {
+            if (existsSync3(slot.targetDiskPath)) {
+              this.markInternalWrite();
+              unlinkSync2(slot.targetDiskPath);
+            }
+          } catch {}
+        }
+      }
+    });
+  }
+  scheduleWrite(key, nowMs, fn) {
     this.pendingWriteQueue.set(key, fn);
-    if (this.writeTimer)
-      clearTimeout(this.writeTimer);
     const debounceMs = this.config.persistDebounceMs || 100;
+    this.nextTimerFlushAtMs = nowMs + debounceMs;
+    if (!this.writeTimer) {
+      this.armWriteTimer(debounceMs);
+    }
+  }
+  armWriteTimer(delayMs) {
     this.writeTimer = setTimeout(() => {
+      const remaining = this.nextTimerFlushAtMs - Date.now();
+      if (remaining > 5 && this.pendingWriteQueue.size > 0) {
+        this.armWriteTimer(remaining);
+        return;
+      }
       this.flushPendingWrites();
-    }, debounceMs);
+    }, delayMs);
   }
   flushPendingWrites() {
     if (this.writeTimer) {
@@ -715,6 +1656,7 @@ class SynapseEngine {
       this.fileWatcher.close();
       this.fileWatcher = null;
     }
+    this.wal.close();
   }
 }
 
@@ -765,7 +1707,7 @@ class SynapseCollection {
 }
 
 // migrator.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 
 class SynapseMigrator {
   engine;
@@ -773,7 +1715,7 @@ class SynapseMigrator {
     this.engine = engine;
   }
   async migrateFromSqlite(sqliteDbPath, mappings) {
-    if (!existsSync3(sqliteDbPath)) {
+    if (!existsSync4(sqliteDbPath)) {
       throw new Error(`[SynapseMigrator] SQLite DB \uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${sqliteDbPath}`);
     }
     for (const m of mappings) {
@@ -923,19 +1865,45 @@ class SynapseDB {
   flush() {
     this.engine.flushPendingWrites();
   }
+  async transaction(fn) {
+    return this.engine.executeTransaction(fn);
+  }
+  asOfLsn(targetLsn) {
+    return this.engine.wal.asOfLsn(this.engine.connectome, targetLsn);
+  }
+  asOf(timestampMsOrIso) {
+    return this.engine.wal.asOf(this.engine.connectome, timestampMsOrIso);
+  }
+  diffBetweenLsn(fromLsn, toLsn) {
+    return this.engine.wal.diffBetweenLsn(fromLsn, toLsn);
+  }
+  recordCompilerMetric(metric) {
+    return this.engine.wal.recordCompilerMetric(metric);
+  }
+  walStats() {
+    return this.engine.wal.getStats();
+  }
   close() {
     this.engine.close();
   }
 }
 export {
+  CausalArenaAllocator,
+  CausalTimeTravelEngine,
+  CausalWalEngine,
+  CausalWalEventType,
+  SqliteCausalWalStore,
   SynapseCollection,
   SynapseConnectome,
   SynapseDB,
   SynapseEngine,
   SynapseMigrator,
+  TemporalRingBuffer,
+  WAL_CONFIG_DEFAULTS,
   atomicWriteFile,
   exportToObsidianCanvas,
   extractWikilinks,
+  extractWikilinksFromDataAndBody,
   parseMarkdownFile,
   parseYamlScalar,
   stringifyDocument