comisai 1.0.4

package/node_modules/@comis/memory/dist/secret-store-schema.js

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Secret store SQLite schema DDL and canary-based master key validation.
+ *
+ * Provides the storage foundation for encrypted secrets: a `secrets` table
+ * with BLOB columns for AES-256-GCM encrypted components, and a canary
+ * mechanism to detect master key mismatches at store open time -- preventing
+ * silent data corruption from a wrong key.
+ *
+ * The canary is a known plaintext string encrypted and stored on first
+ * initialization. On subsequent opens, it is decrypted and compared to
+ * the expected value. A mismatch means the master key is wrong.
+ */
+/** Well-known canary row name -- excluded from list/decryptAll operations. */
+export const CANARY_NAME = "__comis_canary__";
+/** Canary plaintext value used for master key validation. */
+const CANARY_PLAINTEXT = "comis-secrets-canary-v1";
+/**
+ * Create the `secrets` table if it does not already exist.
+ *
+ * The table stores encrypted secret components as BLOB columns alongside
+ * metadata for auditing and lifecycle management. Safe to call multiple
+ * times (idempotent via CREATE TABLE IF NOT EXISTS).
+ *
+ * Must be called before `validateCanary()`.
+ *
+ * @param db - An open better-sqlite3 Database instance
+ */
+export function initSecretSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS secrets (
+      name TEXT PRIMARY KEY,
+      ciphertext BLOB NOT NULL,
+      iv BLOB NOT NULL,
+      auth_tag BLOB NOT NULL,
+      salt BLOB NOT NULL,
+      provider TEXT,
+      description TEXT,
+      expires_at INTEGER,
+      last_used_at INTEGER,
+      usage_count INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+}
+/**
+ * Validate the master key by encrypting/decrypting a canary entry.
+ *
+ * On first call (no canary row): encrypts a known plaintext and stores it.
+ * On subsequent calls: decrypts the stored canary and verifies the value.
+ *
+ * Throws an Error containing "DECRYPTION_FAILED" if the master key does
+ * not match the one used to create the canary -- this prevents silent
+ * data corruption from attempting to decrypt secrets with the wrong key.
+ *
+ * @param db - Database with the `secrets` table already created
+ * @param crypto - SecretsCrypto instance bound to the current master key
+ * @throws Error with "DECRYPTION_FAILED" if master key mismatch detected
+ */
+export function validateCanary(db, crypto) {
+    const row = db
+        .prepare("SELECT ciphertext, iv, auth_tag, salt FROM secrets WHERE name = ?")
+        .get(CANARY_NAME);
+    if (!row) {
+        // First initialization: encrypt and store the canary
+        const result = crypto.encrypt(CANARY_PLAINTEXT);
+        if (!result.ok) {
+            throw new Error(`Failed to encrypt canary: ${result.error.message}`);
+        }
+        const encrypted = result.value;
+        const now = Date.now();
+        db.prepare(`INSERT INTO secrets (name, ciphertext, iv, auth_tag, salt, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(CANARY_NAME, encrypted.ciphertext, encrypted.iv, encrypted.authTag, encrypted.salt, now, now);
+        return;
+    }
+    // Existing canary: reconstruct EncryptedSecret and decrypt
+    const encrypted = {
+        ciphertext: row.ciphertext,
+        iv: row.iv,
+        authTag: row.auth_tag,
+        salt: row.salt,
+    };
+    const decryptResult = crypto.decrypt(encrypted);
+    if (!decryptResult.ok) {
+        throw new Error("DECRYPTION_FAILED: Master key does not match the one used to create this secret store");
+    }
+    if (decryptResult.value !== CANARY_PLAINTEXT) {
+        throw new Error("DECRYPTION_FAILED: Canary value mismatch -- store may be corrupted");
+    }
+    // Success: master key matches, canary validated
+}

package/node_modules/@comis/memory/dist/secret-store-schema.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for secret store schema DDL and canary validation.
+ *
+ * Uses in-memory SQLite databases and real crypto from @comis/core
+ * to validate schema creation and master key mismatch detection.
+ */
+export {};

package/node_modules/@comis/memory/dist/secret-store-schema.test.js

@@ -0,0 +1,90 @@
+/**
+ * Tests for secret store schema DDL and canary validation.
+ *
+ * Uses in-memory SQLite databases and real crypto from @comis/core
+ * to validate schema creation and master key mismatch detection.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import Database from "better-sqlite3";
+import { randomBytes } from "node:crypto";
+import { createSecretsCrypto } from "@comis/core";
+import { initSecretSchema, validateCanary, CANARY_NAME, } from "./secret-store-schema.js";
+function makeCrypto() {
+    const key = randomBytes(32);
+    return createSecretsCrypto(key);
+}
+describe("initSecretSchema", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+    });
+    it("creates secrets table with expected columns", () => {
+        initSecretSchema(db);
+        const columns = db
+            .prepare("PRAGMA table_info(secrets)")
+            .all();
+        const columnNames = columns.map((c) => c.name);
+        expect(columnNames).toContain("name");
+        expect(columnNames).toContain("ciphertext");
+        expect(columnNames).toContain("iv");
+        expect(columnNames).toContain("auth_tag");
+        expect(columnNames).toContain("salt");
+        expect(columnNames).toContain("provider");
+        expect(columnNames).toContain("description");
+        expect(columnNames).toContain("expires_at");
+        expect(columnNames).toContain("last_used_at");
+        expect(columnNames).toContain("usage_count");
+        expect(columnNames).toContain("created_at");
+        expect(columnNames).toContain("updated_at");
+        // Should have exactly 12 columns
+        expect(columns).toHaveLength(12);
+        // Verify BLOB types for encrypted fields
+        const blobColumns = columns.filter((c) => c.type === "BLOB");
+        expect(blobColumns.map((c) => c.name).sort()).toEqual(["auth_tag", "ciphertext", "iv", "salt"]);
+        // Verify name is primary key
+        const pkColumn = columns.find((c) => c.pk === 1);
+        expect(pkColumn?.name).toBe("name");
+    });
+    it("is idempotent (safe to call multiple times)", () => {
+        initSecretSchema(db);
+        initSecretSchema(db);
+        const columns = db
+            .prepare("PRAGMA table_info(secrets)")
+            .all();
+        expect(columns).toHaveLength(12);
+    });
+});
+describe("validateCanary", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSecretSchema(db);
+    });
+    it("creates canary row on fresh database", () => {
+        const crypto = makeCrypto();
+        validateCanary(db, crypto);
+        const row = db
+            .prepare("SELECT name FROM secrets WHERE name = ?")
+            .get(CANARY_NAME);
+        expect(row).toBeDefined();
+        expect(row.name).toBe(CANARY_NAME);
+    });
+    it("succeeds silently on existing database with correct key", () => {
+        const crypto = makeCrypto();
+        // First call: creates canary
+        validateCanary(db, crypto);
+        // Second call: validates canary (should not throw)
+        expect(() => validateCanary(db, crypto)).not.toThrow();
+    });
+    it("throws DECRYPTION_FAILED with wrong master key", () => {
+        const crypto1 = makeCrypto();
+        const crypto2 = makeCrypto();
+        // Create canary with key 1
+        validateCanary(db, crypto1);
+        // Validate with key 2 -- should fail
+        expect(() => validateCanary(db, crypto2)).toThrow(/DECRYPTION_FAILED/);
+    });
+    it("exports CANARY_NAME for downstream exclusion", () => {
+        expect(CANARY_NAME).toBe("__comis_canary__");
+    });
+});

package/node_modules/@comis/memory/dist/session-store.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Session store for conversation persistence.
+ *
+ * Provides CRUD operations on the `sessions` table using better-sqlite3
+ * prepared statements. Sessions survive process restarts since they are
+ * stored in SQLite.
+ *
+ * Factory function pattern (createSessionStore) consistent with Phase 1
+ * createSecretManager for minimal public surface area.
+ */
+import type Database from "better-sqlite3";
+import { type SessionKey } from "@comis/core";
+/** Maximum serialized session size in bytes (10MB). */
+export declare const MAX_SESSION_BYTES: number;
+/**
+ * Data returned when loading a session.
+ */
+export interface SessionData {
+    messages: unknown[];
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Session listing entry.
+ */
+export interface SessionListEntry {
+    sessionKey: string;
+    updatedAt: number;
+}
+/**
+ * Detailed session listing entry with all fields needed for kind derivation.
+ */
+export interface SessionDetailedEntry {
+    sessionKey: string;
+    tenantId: string;
+    userId: string;
+    channelId: string;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+    messageCount: number;
+}
+/**
+ * SessionStore provides CRUD operations for conversation sessions.
+ *
+ * All operations are synchronous (better-sqlite3 is synchronous).
+ * Sessions are keyed by formatted SessionKey strings.
+ */
+export interface SessionStore {
+    /**
+     * Save (upsert) a session. On conflict, updates messages/metadata/updatedAt
+     * while preserving the original createdAt.
+     */
+    save(key: SessionKey, messages: unknown[], metadata?: Record<string, unknown>): void;
+    /**
+     * Load a session by its key. Returns undefined if not found.
+     */
+    load(key: SessionKey): SessionData | undefined;
+    /**
+     * List sessions ordered by updatedAt DESC.
+     * Optionally filter by tenantId.
+     */
+    list(tenantId?: string): SessionListEntry[];
+    /**
+     * Delete a session by its key.
+     * @returns true if a row was deleted, false if not found.
+     */
+    delete(key: SessionKey): boolean;
+    /**
+     * Delete sessions that have not been updated within maxAgeMs milliseconds.
+     * @returns The number of sessions deleted.
+     */
+    deleteStale(maxAgeMs: number): number;
+    /**
+     * Load a session by its formatted key string (as returned by list()).
+     * Avoids the need to parse the key back into a SessionKey object.
+     */
+    loadByFormattedKey(sessionKey: string): SessionData | undefined;
+    /**
+     * List sessions with full detail for filtering by kind.
+     * Returns all columns needed to derive session kind (dm, group, sub-agent).
+     * Optionally filter by tenantId.
+     */
+    listDetailed(tenantId?: string): SessionDetailedEntry[];
+}
+/**
+ * Create a SessionStore bound to the given database.
+ *
+ * Assumes `initSchema()` has already been called on the database
+ * to create the `sessions` table.
+ */
+export declare function createSessionStore(db: Database.Database): SessionStore;

package/node_modules/@comis/memory/dist/session-store.js

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Session store for conversation persistence.
+ *
+ * Provides CRUD operations on the `sessions` table using better-sqlite3
+ * prepared statements. Sessions survive process restarts since they are
+ * stored in SQLite.
+ *
+ * Factory function pattern (createSessionStore) consistent with Phase 1
+ * createSecretManager for minimal public surface area.
+ */
+import { formatSessionKey } from "@comis/core";
+import { z } from "zod";
+const SessionMessagesSchema = z.array(z.unknown());
+const SessionMetadataSchema = z.record(z.string(), z.unknown());
+/** Maximum serialized session size in bytes (10MB). */
+export const MAX_SESSION_BYTES = 10 * 1024 * 1024;
+/** Parse JSON-encoded messages with Zod validation, falling back to empty array on corrupt data. */
+function parseMessages(raw) {
+    try {
+        const result = SessionMessagesSchema.safeParse(JSON.parse(raw));
+        return result.success ? result.data : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Parse JSON-encoded metadata with Zod validation, falling back to empty object on corrupt data. */
+function parseMetadata(raw) {
+    try {
+        const result = SessionMetadataSchema.safeParse(JSON.parse(raw));
+        return result.success ? result.data : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Create a SessionStore bound to the given database.
+ *
+ * Assumes `initSchema()` has already been called on the database
+ * to create the `sessions` table.
+ */
+export function createSessionStore(db) {
+    // Prepare statements once for performance
+    const upsertStmt = db.prepare(`
+    INSERT INTO sessions (session_key, tenant_id, user_id, channel_id, messages, created_at, updated_at, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_key) DO UPDATE SET
+      messages = excluded.messages,
+      updated_at = excluded.updated_at,
+      metadata = excluded.metadata
+  `);
+    const loadStmt = db.prepare("SELECT * FROM sessions WHERE session_key = ?");
+    const listAllStmt = db.prepare("SELECT session_key, updated_at FROM sessions ORDER BY updated_at DESC");
+    const listByTenantStmt = db.prepare("SELECT session_key, updated_at FROM sessions WHERE tenant_id = ? ORDER BY updated_at DESC");
+    const deleteStmt = db.prepare("DELETE FROM sessions WHERE session_key = ?");
+    const deleteStaleStmt = db.prepare("DELETE FROM sessions WHERE updated_at < ?");
+    const loadByKeyStmt = db.prepare("SELECT * FROM sessions WHERE session_key = ?");
+    const listDetailedAllStmt = db.prepare("SELECT session_key, tenant_id, user_id, channel_id, metadata, created_at, updated_at, json_array_length(messages) AS message_count FROM sessions ORDER BY updated_at DESC");
+    const listDetailedByTenantStmt = db.prepare("SELECT session_key, tenant_id, user_id, channel_id, metadata, created_at, updated_at, json_array_length(messages) AS message_count FROM sessions WHERE tenant_id = ? ORDER BY updated_at DESC");
+    return {
+        save(key, messages, metadata) {
+            const now = Date.now();
+            const sessionKey = formatSessionKey(key);
+            const messagesJson = JSON.stringify(messages);
+            const metadataJson = JSON.stringify(metadata ?? {});
+            // Validate serialized session size before storing
+            const totalBytes = Buffer.byteLength(messagesJson, "utf-8") + Buffer.byteLength(metadataJson, "utf-8");
+            if (totalBytes > MAX_SESSION_BYTES) {
+                throw new Error(`Session data exceeds maximum size: ${totalBytes} bytes > ${MAX_SESSION_BYTES} bytes (10MB limit)`);
+            }
+            upsertStmt.run(sessionKey, key.tenantId, key.userId, key.channelId, messagesJson, now, now, metadataJson);
+        },
+        load(key) {
+            const sessionKey = formatSessionKey(key);
+            const row = loadStmt.get(sessionKey);
+            if (!row)
+                return undefined;
+            return {
+                messages: parseMessages(row.messages),
+                metadata: parseMetadata(row.metadata),
+                createdAt: row.created_at,
+                updatedAt: row.updated_at,
+            };
+        },
+        list(tenantId) {
+            const rows = (tenantId !== undefined ? listByTenantStmt.all(tenantId) : listAllStmt.all());
+            return rows.map((r) => ({
+                sessionKey: r.session_key,
+                updatedAt: r.updated_at,
+            }));
+        },
+        delete(key) {
+            const sessionKey = formatSessionKey(key);
+            const result = deleteStmt.run(sessionKey);
+            return result.changes > 0;
+        },
+        deleteStale(maxAgeMs) {
+            const cutoff = Date.now() - maxAgeMs;
+            const result = deleteStaleStmt.run(cutoff);
+            return result.changes;
+        },
+        loadByFormattedKey(sessionKey) {
+            const row = loadByKeyStmt.get(sessionKey);
+            if (!row)
+                return undefined;
+            return {
+                messages: parseMessages(row.messages),
+                metadata: parseMetadata(row.metadata),
+                createdAt: row.created_at,
+                updatedAt: row.updated_at,
+            };
+        },
+        listDetailed(tenantId) {
+            const rows = (tenantId !== undefined
+                ? listDetailedByTenantStmt.all(tenantId)
+                : listDetailedAllStmt.all());
+            return rows.map((r) => ({
+                sessionKey: r.session_key,
+                tenantId: r.tenant_id,
+                userId: r.user_id,
+                channelId: r.channel_id,
+                metadata: parseMetadata(r.metadata),
+                createdAt: r.created_at,
+                updatedAt: r.updated_at,
+                messageCount: r.message_count,
+            }));
+        },
+    };
+}

package/node_modules/@comis/memory/dist/session-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@comis/memory/dist/session-store.test.js

@@ -0,0 +1,262 @@
+import { formatSessionKey } from "@comis/core";
+import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it, expect, beforeEach } from "vitest";
+import { initSchema } from "./schema.js";
+import { createSessionStore, MAX_SESSION_BYTES } from "./session-store.js";
+describe("createSessionStore", () => {
+    let db;
+    let store;
+    const testKey = {
+        tenantId: "default",
+        userId: "user-1",
+        channelId: "telegram",
+    };
+    const otherKey = {
+        tenantId: "default",
+        userId: "user-2",
+        channelId: "discord",
+    };
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSchema(db, 1536);
+        store = createSessionStore(db);
+    });
+    it("save and load roundtrip -- messages array preserved exactly", () => {
+        const messages = [
+            { role: "user", content: "Hello" },
+            { role: "assistant", content: "Hi there!" },
+        ];
+        store.save(testKey, messages);
+        const loaded = store.load(testKey);
+        expect(loaded).toBeDefined();
+        expect(loaded.messages).toEqual(messages);
+    });
+    it("save with metadata -- metadata object preserved", () => {
+        const messages = [{ role: "user", content: "test" }];
+        const metadata = { model: "gpt-4", temperature: 0.7, tags: ["debug"] };
+        store.save(testKey, messages, metadata);
+        const loaded = store.load(testKey);
+        expect(loaded).toBeDefined();
+        expect(loaded.metadata).toEqual(metadata);
+    });
+    it("load returns undefined for non-existent session", () => {
+        const result = store.load({
+            tenantId: "default",
+            userId: "nobody",
+            channelId: "nowhere",
+        });
+        expect(result).toBeUndefined();
+    });
+    it("save overwrites existing session (upsert) -- messages updated", () => {
+        const original = [{ role: "user", content: "first" }];
+        const updated = [
+            { role: "user", content: "first" },
+            { role: "assistant", content: "reply" },
+        ];
+        store.save(testKey, original);
+        store.save(testKey, updated);
+        const loaded = store.load(testKey);
+        expect(loaded).toBeDefined();
+        expect(loaded.messages).toEqual(updated);
+    });
+    it("save preserves createdAt on update (only updatedAt changes)", () => {
+        store.save(testKey, [{ msg: "first" }]);
+        const first = store.load(testKey);
+        // Small delay to ensure different timestamps
+        const createdAt = first.createdAt;
+        // Manually set a known created_at in the past for deterministic testing
+        db.prepare("UPDATE sessions SET created_at = 1000, updated_at = 1000 WHERE session_key = ?").run("default:user-1:telegram");
+        store.save(testKey, [{ msg: "second" }]);
+        const second = store.load(testKey);
+        // createdAt should stay at 1000 (the original ON CONFLICT preserves it)
+        expect(second.createdAt).toBe(1000);
+        // updatedAt should be fresh (not 1000)
+        expect(second.updatedAt).toBeGreaterThan(1000);
+    });
+    it("list returns sessions ordered by updatedAt DESC", () => {
+        // Insert with explicit timestamps for deterministic ordering
+        db.prepare(`INSERT INTO sessions (session_key, tenant_id, user_id, channel_id, messages, created_at, updated_at, metadata)
+       VALUES ('s1', 'default', 'u1', 'ch1', '[]', 1000, 1000, '{}')`).run();
+        db.prepare(`INSERT INTO sessions (session_key, tenant_id, user_id, channel_id, messages, created_at, updated_at, metadata)
+       VALUES ('s2', 'default', 'u2', 'ch2', '[]', 2000, 3000, '{}')`).run();
+        db.prepare(`INSERT INTO sessions (session_key, tenant_id, user_id, channel_id, messages, created_at, updated_at, metadata)
+       VALUES ('s3', 'default', 'u3', 'ch3', '[]', 1500, 2000, '{}')`).run();
+        const list = store.list();
+        expect(list).toHaveLength(3);
+        expect(list[0].sessionKey).toBe("s2"); // updatedAt 3000
+        expect(list[1].sessionKey).toBe("s3"); // updatedAt 2000
+        expect(list[2].sessionKey).toBe("s1"); // updatedAt 1000
+    });
+    it("list with tenantId filter returns only matching sessions", () => {
+        const tenantAKey = { tenantId: "tenant-a", userId: "u1", channelId: "ch1" };
+        const tenantBKey = { tenantId: "tenant-b", userId: "u2", channelId: "ch2" };
+        store.save(tenantAKey, [{ msg: "a" }]);
+        store.save(tenantBKey, [{ msg: "b" }]);
+        const filtered = store.list("tenant-a");
+        expect(filtered).toHaveLength(1);
+        expect(filtered[0].sessionKey).toContain("tenant-a");
+    });
+    it("delete removes session and returns true", () => {
+        store.save(testKey, [{ msg: "test" }]);
+        const deleted = store.delete(testKey);
+        expect(deleted).toBe(true);
+        const loaded = store.load(testKey);
+        expect(loaded).toBeUndefined();
+    });
+    it("delete returns false for non-existent session", () => {
+        const deleted = store.delete({
+            tenantId: "default",
+            userId: "nonexistent",
+            channelId: "none",
+        });
+        expect(deleted).toBe(false);
+    });
+    it("deleteStale removes sessions older than threshold", () => {
+        // Insert sessions with specific updatedAt timestamps
+        db.prepare(`INSERT INTO sessions (session_key, tenant_id, user_id, channel_id, messages, created_at, updated_at, metadata)
+       VALUES ('old-session', 'default', 'u1', 'ch1', '[]', 1000, 1000, '{}')`).run();
+        store.save(testKey, [{ msg: "fresh" }]); // This will have a current timestamp
+        // Delete sessions older than 1 hour (the old session at timestamp 1000ms will be deleted)
+        const deleted = store.deleteStale(60 * 60 * 1000);
+        expect(deleted).toBe(1);
+        // Fresh session should survive
+        const loaded = store.load(testKey);
+        expect(loaded).toBeDefined();
+    });
+    it("deleteStale returns count of deleted sessions", () => {
+        // Insert multiple old sessions
+        db.prepare(`INSERT INTO sessions (session_key, tenant_id, user_id, channel_id, messages, created_at, updated_at, metadata)
+       VALUES ('old1', 'default', 'u1', 'ch1', '[]', 100, 100, '{}')`).run();
+        db.prepare(`INSERT INTO sessions (session_key, tenant_id, user_id, channel_id, messages, created_at, updated_at, metadata)
+       VALUES ('old2', 'default', 'u2', 'ch2', '[]', 200, 200, '{}')`).run();
+        const deleted = store.deleteStale(60 * 60 * 1000);
+        expect(deleted).toBe(2);
+    });
+    it("session survives db close/reopen cycle (file-backed)", () => {
+        const dbPath = join(tmpdir(), `comis-test-${randomUUID()}.db`);
+        // Create and populate
+        const fileDb = new Database(dbPath);
+        initSchema(fileDb, 1536);
+        const fileStore = createSessionStore(fileDb);
+        const messages = [
+            { role: "user", content: "persist me" },
+            { role: "assistant", content: "I will be remembered" },
+        ];
+        fileStore.save(testKey, messages, { persistent: true });
+        fileDb.close();
+        // Reopen and verify
+        const reopened = new Database(dbPath);
+        initSchema(reopened, 1536); // Safe to call again (idempotent)
+        const reopenedStore = createSessionStore(reopened);
+        const loaded = reopenedStore.load(testKey);
+        expect(loaded).toBeDefined();
+        expect(loaded.messages).toEqual(messages);
+        expect(loaded.metadata).toEqual({ persistent: true });
+        reopened.close();
+        // Cleanup
+        try {
+            const { unlinkSync } = require("node:fs");
+            unlinkSync(dbPath);
+            unlinkSync(dbPath + "-wal");
+            unlinkSync(dbPath + "-shm");
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    });
+    it("multiple sessions with different keys are independent", () => {
+        const msgs1 = [{ msg: "session 1" }];
+        const msgs2 = [{ msg: "session 2" }];
+        store.save(testKey, msgs1);
+        store.save(otherKey, msgs2);
+        const loaded1 = store.load(testKey);
+        const loaded2 = store.load(otherKey);
+        expect(loaded1.messages).toEqual(msgs1);
+        expect(loaded2.messages).toEqual(msgs2);
+    });
+    it("empty messages array is valid (new session with no history)", () => {
+        store.save(testKey, []);
+        const loaded = store.load(testKey);
+        expect(loaded).toBeDefined();
+        expect(loaded.messages).toEqual([]);
+    });
+    it("default metadata is empty object when not provided", () => {
+        store.save(testKey, [{ msg: "test" }]);
+        const loaded = store.load(testKey);
+        expect(loaded).toBeDefined();
+        expect(loaded.metadata).toEqual({});
+    });
+    describe("loadByFormattedKey", () => {
+        it("loads session by formatted key string", () => {
+            const key = { tenantId: "default", userId: "u1", channelId: "c1" };
+            store.save(key, [{ role: "user", content: "hello" }], { foo: "bar" });
+            const formatted = formatSessionKey(key);
+            const data = store.loadByFormattedKey(formatted);
+            expect(data).toBeDefined();
+            expect(data.messages).toEqual([{ role: "user", content: "hello" }]);
+            expect(data.metadata).toEqual({ foo: "bar" });
+        });
+        it("returns undefined for non-existent key", () => {
+            expect(store.loadByFormattedKey("nonexistent:key:string")).toBeUndefined();
+        });
+    });
+    // ── DATA-07: session size limits ────────────────────────────────
+    describe("session size limits", () => {
+        it("saves session with small messages successfully", () => {
+            const messages = [{ role: "user", content: "hello" }];
+            expect(() => store.save(testKey, messages)).not.toThrow();
+            const loaded = store.load(testKey);
+            expect(loaded).toBeDefined();
+            expect(loaded.messages).toEqual(messages);
+        });
+        it("throws when messages JSON exceeds 10MB", () => {
+            // Create a message array that exceeds 10MB when serialized
+            const largeContent = "x".repeat(11 * 1024 * 1024); // 11MB string
+            const messages = [{ role: "user", content: largeContent }];
+            expect(() => store.save(testKey, messages)).toThrow(/Session data exceeds maximum size/);
+            expect(() => store.save(testKey, messages)).toThrow(/10MB limit/);
+        });
+        it("saves session right at the limit", () => {
+            // Create messages that are close to but under 10MB
+            // MAX_SESSION_BYTES = 10 * 1024 * 1024 = 10485760
+            // We need messages + metadata JSON to be <= 10485760 bytes
+            // JSON overhead: {"role":"user","content":"..."} -> ~30 bytes + content
+            // Outer array: [...]  -> ~2 bytes
+            // metadata: {} -> 2 bytes
+            const targetContentSize = MAX_SESSION_BYTES - 100; // leave room for JSON overhead + metadata
+            const content = "a".repeat(targetContentSize);
+            const messages = [{ content }];
+            expect(() => store.save(testKey, messages)).not.toThrow();
+        });
+        it("MAX_SESSION_BYTES is 10MB", () => {
+            expect(MAX_SESSION_BYTES).toBe(10 * 1024 * 1024);
+        });
+    });
+    describe("listDetailed", () => {
+        it("returns detailed session entries with metadata", () => {
+            const key1 = { tenantId: "t1", userId: "u1", channelId: "c1" };
+            const key2 = { tenantId: "t1", userId: "u2", channelId: "c2" };
+            store.save(key1, [], { parentSessionKey: "some-parent" });
+            store.save(key2, [], {});
+            const entries = store.listDetailed("t1");
+            expect(entries).toHaveLength(2);
+            // Most recent first
+            const subAgent = entries.find(e => e.metadata.parentSessionKey !== undefined);
+            expect(subAgent).toBeDefined();
+            expect(subAgent.userId).toBe("u1");
+            expect(subAgent.metadata.parentSessionKey).toBe("some-parent");
+        });
+        it("filters by tenantId", () => {
+            const key1 = { tenantId: "t1", userId: "u1", channelId: "c1" };
+            const key2 = { tenantId: "t2", userId: "u2", channelId: "c2" };
+            store.save(key1, []);
+            store.save(key2, []);
+            expect(store.listDetailed("t1")).toHaveLength(1);
+            expect(store.listDetailed("t2")).toHaveLength(1);
+            expect(store.listDetailed()).toHaveLength(2);
+        });
+    });
+});