@codelia/storage 0.1.2 → 0.1.3

package/dist/index.cjs

@@ -255,8 +255,12 @@ var StoragePathServiceImpl = class {
 var import_node_fs3 = require("fs");
 var import_node_path3 = __toESM(require("path"), 1);
 var import_core = require("@codelia/core");
-var STATE_DIRNAME = "state";
-var resolveStateDir = (paths) => import_node_path3.default.join(paths.sessionsDir, STATE_DIRNAME);
+var LEGACY_STATE_DIRNAME = "state";
+var MESSAGES_DIRNAME = "messages";
+var STATE_DB_FILENAME = "state.db";
+var resolveLegacyStateDir = (paths) => import_node_path3.default.join(paths.sessionsDir, LEGACY_STATE_DIRNAME);
+var resolveMessagesDir = (paths) => import_node_path3.default.join(paths.sessionsDir, MESSAGES_DIRNAME);
+var resolveStateDbPath = (paths) => import_node_path3.default.join(paths.sessionsDir, STATE_DB_FILENAME);
 var extractLastUserMessage = (messages) => {
   for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
     const message = messages[idx];
@@ -276,69 +280,394 @@ var toSummary = (state) => ({
   message_count: Array.isArray(state.messages) ? state.messages.length : void 0,
   last_user_message: Array.isArray(state.messages) ? extractLastUserMessage(state.messages) : void 0
 });
+var fromSummaryRow = (row) => ({
+  session_id: row.session_id,
+  updated_at: row.updated_at,
+  run_id: row.run_id ?? void 0,
+  message_count: row.message_count ?? void 0,
+  last_user_message: row.last_user_message ?? void 0
+});
+var serializeMessages = (messages) => {
+  if (messages.length === 0) return "";
+  return `${messages.map((message) => JSON.stringify(message)).join("\n")}
+`;
+};
+var deserializeMessages = (payload) => {
+  if (!payload.trim()) return [];
+  const messages = [];
+  const lines = payload.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error("Invalid session message entry");
+    }
+    messages.push(parsed);
+  }
+  return messages;
+};
+var atomicWriteFile = async (filePath, payload) => {
+  const dirname = import_node_path3.default.dirname(filePath);
+  const basename = import_node_path3.default.basename(filePath);
+  const tempFile = import_node_path3.default.join(
+    dirname,
+    `${basename}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
+  );
+  let wroteTemp = false;
+  try {
+    await import_node_fs3.promises.writeFile(tempFile, payload, "utf8");
+    wroteTemp = true;
+    await import_node_fs3.promises.rename(tempFile, filePath);
+  } catch (error) {
+    if (wroteTemp) {
+      await import_node_fs3.promises.rm(tempFile, { force: true }).catch(() => {
+      });
+    }
+    throw error;
+  }
+};
 var SessionStateStoreImpl = class {
-  stateDir;
-  ensureDir;
+  legacyStateDir;
+  messagesDir;
+  stateDbPath;
+  ensureDirs;
+  db;
+  schemaInit;
   onError;
   constructor(options = {}) {
     const paths = options.paths ?? resolveStoragePaths();
-    this.stateDir = resolveStateDir(paths);
-    this.ensureDir = import_node_fs3.promises.mkdir(this.stateDir, { recursive: true }).then(() => {
+    this.legacyStateDir = resolveLegacyStateDir(paths);
+    this.messagesDir = resolveMessagesDir(paths);
+    this.stateDbPath = resolveStateDbPath(paths);
+    this.ensureDirs = Promise.all([
+      import_node_fs3.promises.mkdir(paths.sessionsDir, { recursive: true }),
+      import_node_fs3.promises.mkdir(this.legacyStateDir, { recursive: true }),
+      import_node_fs3.promises.mkdir(this.messagesDir, { recursive: true })
+    ]).then(() => {
     });
     this.onError = options.onError;
+    this.db = this.openDatabase();
+    this.schemaInit = null;
   }
-  resolvePath(sessionId) {
-    return import_node_path3.default.join(this.stateDir, `${sessionId}.json`);
+  resolveLegacyPath(sessionId) {
+    return import_node_path3.default.join(this.legacyStateDir, `${sessionId}.json`);
   }
-  async load(sessionId) {
+  resolveMessagePath(sessionId) {
+    return import_node_path3.default.join(this.messagesDir, `${sessionId}.jsonl`);
+  }
+  async openDatabase() {
+    await this.ensureDirs;
+    if (process.versions.bun) {
+      const bunSqliteSpecifier = "bun:sqlite";
+      const { Database } = await import(bunSqliteSpecifier);
+      const db2 = new Database(this.stateDbPath, { create: true });
+      return {
+        exec: (sql) => {
+          db2.exec(sql);
+        },
+        run: (sql, params = []) => {
+          db2.query(sql).run(...params);
+        },
+        get: (sql, params = []) => {
+          const row = db2.query(sql).get(...params);
+          return row ?? void 0;
+        },
+        all: (sql, params = []) => db2.query(sql).all(...params)
+      };
+    }
+    const betterSqliteSpecifier = "better-sqlite3";
+    const betterSqliteModule = await import(betterSqliteSpecifier);
+    const BetterSqlite3 = betterSqliteModule.default ?? betterSqliteModule;
+    const db = new BetterSqlite3(this.stateDbPath);
+    return {
+      exec: (sql) => {
+        db.exec(sql);
+      },
+      run: (sql, params = []) => {
+        db.prepare(sql).run(...params);
+      },
+      get: (sql, params = []) => {
+        const row = db.prepare(sql).get(...params);
+        return row ?? void 0;
+      },
+      all: (sql, params = []) => db.prepare(sql).all(...params)
+    };
+  }
+  initDatabaseSchema(db) {
+    db.exec("PRAGMA journal_mode = WAL;");
+    db.exec(`
+			CREATE TABLE IF NOT EXISTS session_state (
+				session_id TEXT PRIMARY KEY,
+				updated_at TEXT NOT NULL,
+				run_id TEXT,
+				invoke_seq INTEGER,
+				schema_version INTEGER NOT NULL,
+				meta_json TEXT,
+				message_count INTEGER,
+				last_user_message TEXT
+			);
+		`);
+    db.exec(`
+			CREATE INDEX IF NOT EXISTS idx_session_state_updated_at
+			ON session_state(updated_at DESC);
+		`);
+  }
+  async tryGetDb(action, detail) {
     try {
-      const file = await import_node_fs3.promises.readFile(this.resolvePath(sessionId), "utf8");
+      const db = await this.db;
+      if (!this.schemaInit) {
+        this.schemaInit = Promise.resolve().then(() => {
+          this.initDatabaseSchema(db);
+        });
+      }
+      await this.schemaInit;
+      return db;
+    } catch (error) {
+      this.onError?.(error, { action: `${action}.db_unavailable`, detail });
+      return null;
+    }
+  }
+  async loadLegacy(sessionId) {
+    try {
+      const file = await import_node_fs3.promises.readFile(this.resolveLegacyPath(sessionId), "utf8");
       const parsed = JSON.parse(file);
       if (!parsed || typeof parsed !== "object") return null;
-      return parsed;
+      if (!parsed.session_id || !parsed.updated_at) return null;
+      const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
+      return {
+        schema_version: typeof parsed.schema_version === "number" ? parsed.schema_version : 1,
+        session_id: parsed.session_id,
+        updated_at: parsed.updated_at,
+        run_id: parsed.run_id,
+        invoke_seq: parsed.invoke_seq,
+        messages,
+        meta: parsed.meta && typeof parsed.meta === "object" ? parsed.meta : void 0
+      };
     } catch (error) {
       if (error.code === "ENOENT") {
         return null;
       }
-      this.onError?.(error, { action: "load", detail: sessionId });
+      this.onError?.(error, { action: "legacy.load", detail: sessionId });
       throw error;
     }
   }
-  async save(state) {
-    await this.ensureDir;
+  async loadFromIndex(sessionId, db) {
+    let row;
+    try {
+      row = db.get(
+        `SELECT session_id, updated_at, run_id, invoke_seq, schema_version, meta_json
+				 FROM session_state
+				 WHERE session_id = ?`,
+        [sessionId]
+      );
+    } catch (error) {
+      this.onError?.(error, { action: "index.load", detail: sessionId });
+      throw error;
+    }
+    if (!row) return null;
+    let messages;
+    try {
+      const payload = await import_node_fs3.promises.readFile(this.resolveMessagePath(sessionId), "utf8");
+      messages = deserializeMessages(payload);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        messages = [];
+      } else {
+        this.onError?.(error, { action: "messages.load", detail: sessionId });
+        throw error;
+      }
+    }
+    let meta;
+    if (row.meta_json) {
+      try {
+        const parsed = JSON.parse(row.meta_json);
+        if (parsed && typeof parsed === "object") {
+          meta = parsed;
+        }
+      } catch (error) {
+        this.onError?.(error, { action: "index.meta.parse", detail: sessionId });
+      }
+    }
+    return {
+      schema_version: 1,
+      session_id: row.session_id,
+      updated_at: row.updated_at,
+      run_id: row.run_id ?? void 0,
+      invoke_seq: row.invoke_seq ?? void 0,
+      messages,
+      meta
+    };
+  }
+  async saveToIndex(state, db) {
+    const messagePayload = serializeMessages(
+      Array.isArray(state.messages) ? state.messages : []
+    );
+    await atomicWriteFile(this.resolveMessagePath(state.session_id), messagePayload);
+    const summary = toSummary(state);
+    db.run(
+      `INSERT INTO session_state (
+				session_id,
+				updated_at,
+				run_id,
+				invoke_seq,
+				schema_version,
+				meta_json,
+				message_count,
+				last_user_message
+			)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(session_id) DO UPDATE SET
+				updated_at = excluded.updated_at,
+				run_id = excluded.run_id,
+				invoke_seq = excluded.invoke_seq,
+				schema_version = excluded.schema_version,
+				meta_json = excluded.meta_json,
+				message_count = excluded.message_count,
+				last_user_message = excluded.last_user_message`,
+      [
+        state.session_id,
+        state.updated_at,
+        state.run_id ?? null,
+        state.invoke_seq ?? null,
+        state.schema_version ?? 1,
+        state.meta ? JSON.stringify(state.meta) : null,
+        summary.message_count ?? null,
+        summary.last_user_message ?? null
+      ]
+    );
+  }
+  async saveLegacy(state) {
     const payload = `${JSON.stringify(state)}
 `;
-    await import_node_fs3.promises.writeFile(this.resolvePath(state.session_id), payload, "utf8");
+    await atomicWriteFile(this.resolveLegacyPath(state.session_id), payload);
   }
-  async list() {
-    await this.ensureDir;
+  async hasLegacySnapshot(sessionId) {
+    try {
+      const stat = await import_node_fs3.promises.stat(this.resolveLegacyPath(sessionId));
+      return stat.isFile();
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async saveLegacyIfPresent(state) {
+    if (!await this.hasLegacySnapshot(state.session_id)) {
+      return false;
+    }
+    await this.saveLegacy(state);
+    return true;
+  }
+  async load(sessionId) {
+    const db = await this.tryGetDb("load", sessionId);
+    if (db) {
+      try {
+        const indexed = await this.loadFromIndex(sessionId, db);
+        if (indexed) return indexed;
+      } catch (error) {
+        this.onError?.(error, { action: "load.index", detail: sessionId });
+        throw error;
+      }
+    }
+    const legacy = await this.loadLegacy(sessionId);
+    if (!legacy) return null;
+    if (db) {
+      try {
+        await this.saveToIndex(legacy, db);
+      } catch (error) {
+        this.onError?.(error, { action: "load.migrate_legacy", detail: sessionId });
+      }
+    }
+    return legacy;
+  }
+  async save(state) {
+    await this.ensureDirs;
+    const db = await this.tryGetDb("save", state.session_id);
+    if (!db) {
+      const savedLegacy = await this.saveLegacyIfPresent(state);
+      if (savedLegacy) return;
+      throw new Error(
+        "Session index database unavailable and no legacy snapshot found"
+      );
+    }
+    try {
+      await this.saveToIndex(state, db);
+    } catch (error) {
+      this.onError?.(error, { action: "save.index", detail: state.session_id });
+      try {
+        const savedLegacy = await this.saveLegacyIfPresent(state);
+        if (savedLegacy) return;
+      } catch (legacyError) {
+        this.onError?.(legacyError, {
+          action: "save.legacy_fallback",
+          detail: state.session_id
+        });
+      }
+      throw error;
+    }
+  }
+  async listLegacySummaries() {
     let entries;
     try {
-      entries = await import_node_fs3.promises.readdir(this.stateDir, {
+      entries = await import_node_fs3.promises.readdir(this.legacyStateDir, {
         withFileTypes: true,
         encoding: "utf8"
       });
     } catch (error) {
-      this.onError?.(error, { action: "list" });
+      this.onError?.(error, { action: "legacy.list" });
       throw error;
     }
     const summaries = [];
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       if (!entry.name.endsWith(".json")) continue;
-      const filePath = import_node_path3.default.join(this.stateDir, entry.name);
+      const filePath = import_node_path3.default.join(this.legacyStateDir, entry.name);
       try {
         const contents = await import_node_fs3.promises.readFile(filePath, "utf8");
         const parsed = JSON.parse(contents);
         if (!parsed || typeof parsed !== "object") continue;
         if (!parsed.session_id || !parsed.updated_at) continue;
-        summaries.push(toSummary(parsed));
+        summaries.push(
+          toSummary({
+            ...parsed,
+            schema_version: typeof parsed.schema_version === "number" ? parsed.schema_version : 1,
+            messages: Array.isArray(parsed.messages) ? parsed.messages : []
+          })
+        );
       } catch (error) {
-        this.onError?.(error, { action: "parse", detail: filePath });
+        this.onError?.(error, { action: "legacy.parse", detail: filePath });
       }
     }
     return summaries;
   }
+  async list() {
+    await this.ensureDirs;
+    const summaries = /* @__PURE__ */ new Map();
+    const db = await this.tryGetDb("list");
+    if (db) {
+      try {
+        const rows = db.all(
+          `SELECT session_id, updated_at, run_id, message_count, last_user_message
+					 FROM session_state
+					 ORDER BY updated_at DESC`
+        );
+        for (const row of rows) {
+          summaries.set(row.session_id, fromSummaryRow(row));
+        }
+      } catch (error) {
+        this.onError?.(error, { action: "list.index" });
+      }
+    }
+    const legacy = await this.listLegacySummaries();
+    for (const item of legacy) {
+      if (!summaries.has(item.session_id)) {
+        summaries.set(item.session_id, item);
+      }
+    }
+    return [...summaries.values()];
+  }
 };
 
 // src/tool-output-cache.ts

package/dist/index.d.cts

@@ -40,13 +40,28 @@ type SessionStateStoreOptions = {
     }) => void;
 };
 declare class SessionStateStoreImpl implements SessionStateStore {
-    private readonly stateDir;
-    private readonly ensureDir;
+    private readonly legacyStateDir;
+    private readonly messagesDir;
+    private readonly stateDbPath;
+    private readonly ensureDirs;
+    private readonly db;
+    private schemaInit;
     private readonly onError?;
     constructor(options?: SessionStateStoreOptions);
-    private resolvePath;
+    private resolveLegacyPath;
+    private resolveMessagePath;
+    private openDatabase;
+    private initDatabaseSchema;
+    private tryGetDb;
+    private loadLegacy;
+    private loadFromIndex;
+    private saveToIndex;
+    private saveLegacy;
+    private hasLegacySnapshot;
+    private saveLegacyIfPresent;
     load(sessionId: string): Promise<SessionState | null>;
     save(state: SessionState): Promise<void>;
+    private listLegacySummaries;
     list(): Promise<SessionStateSummary[]>;
 }
 

package/dist/index.d.ts

@@ -40,13 +40,28 @@ type SessionStateStoreOptions = {
     }) => void;
 };
 declare class SessionStateStoreImpl implements SessionStateStore {
-    private readonly stateDir;
-    private readonly ensureDir;
+    private readonly legacyStateDir;
+    private readonly messagesDir;
+    private readonly stateDbPath;
+    private readonly ensureDirs;
+    private readonly db;
+    private schemaInit;
     private readonly onError?;
     constructor(options?: SessionStateStoreOptions);
-    private resolvePath;
+    private resolveLegacyPath;
+    private resolveMessagePath;
+    private openDatabase;
+    private initDatabaseSchema;
+    private tryGetDb;
+    private loadLegacy;
+    private loadFromIndex;
+    private saveToIndex;
+    private saveLegacy;
+    private hasLegacySnapshot;
+    private saveLegacyIfPresent;
     load(sessionId: string): Promise<SessionState | null>;
     save(state: SessionState): Promise<void>;
+    private listLegacySummaries;
     list(): Promise<SessionStateSummary[]>;
 }
 

package/dist/index.js

@@ -212,8 +212,12 @@ var StoragePathServiceImpl = class {
 import { promises as fs3 } from "fs";
 import path3 from "path";
 import { stringifyContent } from "@codelia/core";
-var STATE_DIRNAME = "state";
-var resolveStateDir = (paths) => path3.join(paths.sessionsDir, STATE_DIRNAME);
+var LEGACY_STATE_DIRNAME = "state";
+var MESSAGES_DIRNAME = "messages";
+var STATE_DB_FILENAME = "state.db";
+var resolveLegacyStateDir = (paths) => path3.join(paths.sessionsDir, LEGACY_STATE_DIRNAME);
+var resolveMessagesDir = (paths) => path3.join(paths.sessionsDir, MESSAGES_DIRNAME);
+var resolveStateDbPath = (paths) => path3.join(paths.sessionsDir, STATE_DB_FILENAME);
 var extractLastUserMessage = (messages) => {
   for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
     const message = messages[idx];
@@ -233,69 +237,394 @@ var toSummary = (state) => ({
   message_count: Array.isArray(state.messages) ? state.messages.length : void 0,
   last_user_message: Array.isArray(state.messages) ? extractLastUserMessage(state.messages) : void 0
 });
+var fromSummaryRow = (row) => ({
+  session_id: row.session_id,
+  updated_at: row.updated_at,
+  run_id: row.run_id ?? void 0,
+  message_count: row.message_count ?? void 0,
+  last_user_message: row.last_user_message ?? void 0
+});
+var serializeMessages = (messages) => {
+  if (messages.length === 0) return "";
+  return `${messages.map((message) => JSON.stringify(message)).join("\n")}
+`;
+};
+var deserializeMessages = (payload) => {
+  if (!payload.trim()) return [];
+  const messages = [];
+  const lines = payload.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error("Invalid session message entry");
+    }
+    messages.push(parsed);
+  }
+  return messages;
+};
+var atomicWriteFile = async (filePath, payload) => {
+  const dirname = path3.dirname(filePath);
+  const basename = path3.basename(filePath);
+  const tempFile = path3.join(
+    dirname,
+    `${basename}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
+  );
+  let wroteTemp = false;
+  try {
+    await fs3.writeFile(tempFile, payload, "utf8");
+    wroteTemp = true;
+    await fs3.rename(tempFile, filePath);
+  } catch (error) {
+    if (wroteTemp) {
+      await fs3.rm(tempFile, { force: true }).catch(() => {
+      });
+    }
+    throw error;
+  }
+};
 var SessionStateStoreImpl = class {
-  stateDir;
-  ensureDir;
+  legacyStateDir;
+  messagesDir;
+  stateDbPath;
+  ensureDirs;
+  db;
+  schemaInit;
   onError;
   constructor(options = {}) {
     const paths = options.paths ?? resolveStoragePaths();
-    this.stateDir = resolveStateDir(paths);
-    this.ensureDir = fs3.mkdir(this.stateDir, { recursive: true }).then(() => {
+    this.legacyStateDir = resolveLegacyStateDir(paths);
+    this.messagesDir = resolveMessagesDir(paths);
+    this.stateDbPath = resolveStateDbPath(paths);
+    this.ensureDirs = Promise.all([
+      fs3.mkdir(paths.sessionsDir, { recursive: true }),
+      fs3.mkdir(this.legacyStateDir, { recursive: true }),
+      fs3.mkdir(this.messagesDir, { recursive: true })
+    ]).then(() => {
     });
     this.onError = options.onError;
+    this.db = this.openDatabase();
+    this.schemaInit = null;
   }
-  resolvePath(sessionId) {
-    return path3.join(this.stateDir, `${sessionId}.json`);
+  resolveLegacyPath(sessionId) {
+    return path3.join(this.legacyStateDir, `${sessionId}.json`);
   }
-  async load(sessionId) {
+  resolveMessagePath(sessionId) {
+    return path3.join(this.messagesDir, `${sessionId}.jsonl`);
+  }
+  async openDatabase() {
+    await this.ensureDirs;
+    if (process.versions.bun) {
+      const bunSqliteSpecifier = "bun:sqlite";
+      const { Database } = await import(bunSqliteSpecifier);
+      const db2 = new Database(this.stateDbPath, { create: true });
+      return {
+        exec: (sql) => {
+          db2.exec(sql);
+        },
+        run: (sql, params = []) => {
+          db2.query(sql).run(...params);
+        },
+        get: (sql, params = []) => {
+          const row = db2.query(sql).get(...params);
+          return row ?? void 0;
+        },
+        all: (sql, params = []) => db2.query(sql).all(...params)
+      };
+    }
+    const betterSqliteSpecifier = "better-sqlite3";
+    const betterSqliteModule = await import(betterSqliteSpecifier);
+    const BetterSqlite3 = betterSqliteModule.default ?? betterSqliteModule;
+    const db = new BetterSqlite3(this.stateDbPath);
+    return {
+      exec: (sql) => {
+        db.exec(sql);
+      },
+      run: (sql, params = []) => {
+        db.prepare(sql).run(...params);
+      },
+      get: (sql, params = []) => {
+        const row = db.prepare(sql).get(...params);
+        return row ?? void 0;
+      },
+      all: (sql, params = []) => db.prepare(sql).all(...params)
+    };
+  }
+  initDatabaseSchema(db) {
+    db.exec("PRAGMA journal_mode = WAL;");
+    db.exec(`
+			CREATE TABLE IF NOT EXISTS session_state (
+				session_id TEXT PRIMARY KEY,
+				updated_at TEXT NOT NULL,
+				run_id TEXT,
+				invoke_seq INTEGER,
+				schema_version INTEGER NOT NULL,
+				meta_json TEXT,
+				message_count INTEGER,
+				last_user_message TEXT
+			);
+		`);
+    db.exec(`
+			CREATE INDEX IF NOT EXISTS idx_session_state_updated_at
+			ON session_state(updated_at DESC);
+		`);
+  }
+  async tryGetDb(action, detail) {
     try {
-      const file = await fs3.readFile(this.resolvePath(sessionId), "utf8");
+      const db = await this.db;
+      if (!this.schemaInit) {
+        this.schemaInit = Promise.resolve().then(() => {
+          this.initDatabaseSchema(db);
+        });
+      }
+      await this.schemaInit;
+      return db;
+    } catch (error) {
+      this.onError?.(error, { action: `${action}.db_unavailable`, detail });
+      return null;
+    }
+  }
+  async loadLegacy(sessionId) {
+    try {
+      const file = await fs3.readFile(this.resolveLegacyPath(sessionId), "utf8");
       const parsed = JSON.parse(file);
       if (!parsed || typeof parsed !== "object") return null;
-      return parsed;
+      if (!parsed.session_id || !parsed.updated_at) return null;
+      const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
+      return {
+        schema_version: typeof parsed.schema_version === "number" ? parsed.schema_version : 1,
+        session_id: parsed.session_id,
+        updated_at: parsed.updated_at,
+        run_id: parsed.run_id,
+        invoke_seq: parsed.invoke_seq,
+        messages,
+        meta: parsed.meta && typeof parsed.meta === "object" ? parsed.meta : void 0
+      };
     } catch (error) {
       if (error.code === "ENOENT") {
         return null;
       }
-      this.onError?.(error, { action: "load", detail: sessionId });
+      this.onError?.(error, { action: "legacy.load", detail: sessionId });
       throw error;
     }
   }
-  async save(state) {
-    await this.ensureDir;
+  async loadFromIndex(sessionId, db) {
+    let row;
+    try {
+      row = db.get(
+        `SELECT session_id, updated_at, run_id, invoke_seq, schema_version, meta_json
+				 FROM session_state
+				 WHERE session_id = ?`,
+        [sessionId]
+      );
+    } catch (error) {
+      this.onError?.(error, { action: "index.load", detail: sessionId });
+      throw error;
+    }
+    if (!row) return null;
+    let messages;
+    try {
+      const payload = await fs3.readFile(this.resolveMessagePath(sessionId), "utf8");
+      messages = deserializeMessages(payload);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        messages = [];
+      } else {
+        this.onError?.(error, { action: "messages.load", detail: sessionId });
+        throw error;
+      }
+    }
+    let meta;
+    if (row.meta_json) {
+      try {
+        const parsed = JSON.parse(row.meta_json);
+        if (parsed && typeof parsed === "object") {
+          meta = parsed;
+        }
+      } catch (error) {
+        this.onError?.(error, { action: "index.meta.parse", detail: sessionId });
+      }
+    }
+    return {
+      schema_version: 1,
+      session_id: row.session_id,
+      updated_at: row.updated_at,
+      run_id: row.run_id ?? void 0,
+      invoke_seq: row.invoke_seq ?? void 0,
+      messages,
+      meta
+    };
+  }
+  async saveToIndex(state, db) {
+    const messagePayload = serializeMessages(
+      Array.isArray(state.messages) ? state.messages : []
+    );
+    await atomicWriteFile(this.resolveMessagePath(state.session_id), messagePayload);
+    const summary = toSummary(state);
+    db.run(
+      `INSERT INTO session_state (
+				session_id,
+				updated_at,
+				run_id,
+				invoke_seq,
+				schema_version,
+				meta_json,
+				message_count,
+				last_user_message
+			)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(session_id) DO UPDATE SET
+				updated_at = excluded.updated_at,
+				run_id = excluded.run_id,
+				invoke_seq = excluded.invoke_seq,
+				schema_version = excluded.schema_version,
+				meta_json = excluded.meta_json,
+				message_count = excluded.message_count,
+				last_user_message = excluded.last_user_message`,
+      [
+        state.session_id,
+        state.updated_at,
+        state.run_id ?? null,
+        state.invoke_seq ?? null,
+        state.schema_version ?? 1,
+        state.meta ? JSON.stringify(state.meta) : null,
+        summary.message_count ?? null,
+        summary.last_user_message ?? null
+      ]
+    );
+  }
+  async saveLegacy(state) {
     const payload = `${JSON.stringify(state)}
 `;
-    await fs3.writeFile(this.resolvePath(state.session_id), payload, "utf8");
+    await atomicWriteFile(this.resolveLegacyPath(state.session_id), payload);
   }
-  async list() {
-    await this.ensureDir;
+  async hasLegacySnapshot(sessionId) {
+    try {
+      const stat = await fs3.stat(this.resolveLegacyPath(sessionId));
+      return stat.isFile();
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async saveLegacyIfPresent(state) {
+    if (!await this.hasLegacySnapshot(state.session_id)) {
+      return false;
+    }
+    await this.saveLegacy(state);
+    return true;
+  }
+  async load(sessionId) {
+    const db = await this.tryGetDb("load", sessionId);
+    if (db) {
+      try {
+        const indexed = await this.loadFromIndex(sessionId, db);
+        if (indexed) return indexed;
+      } catch (error) {
+        this.onError?.(error, { action: "load.index", detail: sessionId });
+        throw error;
+      }
+    }
+    const legacy = await this.loadLegacy(sessionId);
+    if (!legacy) return null;
+    if (db) {
+      try {
+        await this.saveToIndex(legacy, db);
+      } catch (error) {
+        this.onError?.(error, { action: "load.migrate_legacy", detail: sessionId });
+      }
+    }
+    return legacy;
+  }
+  async save(state) {
+    await this.ensureDirs;
+    const db = await this.tryGetDb("save", state.session_id);
+    if (!db) {
+      const savedLegacy = await this.saveLegacyIfPresent(state);
+      if (savedLegacy) return;
+      throw new Error(
+        "Session index database unavailable and no legacy snapshot found"
+      );
+    }
+    try {
+      await this.saveToIndex(state, db);
+    } catch (error) {
+      this.onError?.(error, { action: "save.index", detail: state.session_id });
+      try {
+        const savedLegacy = await this.saveLegacyIfPresent(state);
+        if (savedLegacy) return;
+      } catch (legacyError) {
+        this.onError?.(legacyError, {
+          action: "save.legacy_fallback",
+          detail: state.session_id
+        });
+      }
+      throw error;
+    }
+  }
+  async listLegacySummaries() {
     let entries;
     try {
-      entries = await fs3.readdir(this.stateDir, {
+      entries = await fs3.readdir(this.legacyStateDir, {
         withFileTypes: true,
         encoding: "utf8"
       });
     } catch (error) {
-      this.onError?.(error, { action: "list" });
+      this.onError?.(error, { action: "legacy.list" });
       throw error;
     }
     const summaries = [];
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       if (!entry.name.endsWith(".json")) continue;
-      const filePath = path3.join(this.stateDir, entry.name);
+      const filePath = path3.join(this.legacyStateDir, entry.name);
       try {
         const contents = await fs3.readFile(filePath, "utf8");
         const parsed = JSON.parse(contents);
         if (!parsed || typeof parsed !== "object") continue;
         if (!parsed.session_id || !parsed.updated_at) continue;
-        summaries.push(toSummary(parsed));
+        summaries.push(
+          toSummary({
+            ...parsed,
+            schema_version: typeof parsed.schema_version === "number" ? parsed.schema_version : 1,
+            messages: Array.isArray(parsed.messages) ? parsed.messages : []
+          })
+        );
       } catch (error) {
-        this.onError?.(error, { action: "parse", detail: filePath });
+        this.onError?.(error, { action: "legacy.parse", detail: filePath });
       }
     }
     return summaries;
   }
+  async list() {
+    await this.ensureDirs;
+    const summaries = /* @__PURE__ */ new Map();
+    const db = await this.tryGetDb("list");
+    if (db) {
+      try {
+        const rows = db.all(
+          `SELECT session_id, updated_at, run_id, message_count, last_user_message
+					 FROM session_state
+					 ORDER BY updated_at DESC`
+        );
+        for (const row of rows) {
+          summaries.set(row.session_id, fromSummaryRow(row));
+        }
+      } catch (error) {
+        this.onError?.(error, { action: "list.index" });
+      }
+    }
+    const legacy = await this.listLegacySummaries();
+    for (const item of legacy) {
+      if (!summaries.has(item.session_id)) {
+        summaries.set(item.session_id, item);
+      }
+    }
+    return [...summaries.values()];
+  }
 };
 
 // src/tool-output-cache.ts

package/package.json

@@ -1,7 +1,10 @@
 {
 	"name": "@codelia/storage",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"type": "module",
+	"engines": {
+		"node": ">=20 <25"
+	},
 	"files": [
 		"dist"
 	],
@@ -20,7 +23,8 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@codelia/core": "0.1.2"
+		"@codelia/core": "0.1.3",
+		"better-sqlite3": "^12.6.2"
 	},
 	"publishConfig": {
 		"access": "public"