comisai 1.0.4

package/node_modules/@comis/memory/dist/row-mapper.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared helpers for converting between MemoryRow (DB row) and
+ * MemoryEntry (domain type), and for common DB operations.
+ *
+ * Extracted from sqlite-memory-adapter.ts and memory-api.ts to
+ * eliminate duplicate rowToEntry implementations and INSERT SQL.
+ */
+import type { MemoryEntry } from "@comis/core";
+import type Database from "better-sqlite3";
+import type { MemoryRow } from "./types.js";
+/** Parse a JSON-encoded tags string with Zod validation, falling back to empty array on corrupt data. */
+export declare function parseTags(raw: string): string[];
+/** Convert a MemoryRow (DB row) to a MemoryEntry (domain type).
+ *  The returned object includes a non-schema `memoryType` property
+ *  so that RPC handlers can surface the DB-level memory_type column
+ *  without modifying the strict MemoryEntry Zod schema.
+ */
+export declare function rowToEntry(row: MemoryRow, embedding?: number[]): MemoryEntry & {
+    memoryType?: string;
+};
+/**
+ * Insert a memory entry into the `memories` table.
+ *
+ * Encapsulates the INSERT SQL previously duplicated in
+ * SqliteMemoryAdapter.store() and storeWithType().
+ */
+export declare function insertMemoryRow(db: Database.Database, entry: MemoryEntry, memoryType: string): void;
+/**
+ * Store an embedding vector for a memory entry.
+ *
+ * Inserts into vec_memories and sets has_embedding=1 on the memories row.
+ * Only operates when sqlite-vec is available.
+ */
+export declare function storeEmbedding(db: Database.Database, entryId: string, embedding: number[], vecAvailable?: boolean): void;
+/**
+ * Build a WHERE clause and parameter array from optional filter fields.
+ *
+ * Used by memory-api.ts inspect(), clear(), and stats() methods to avoid
+ * repeated conditional WHERE clause assembly.
+ */
+export declare function buildFilterClause(filters: {
+    memoryType?: string;
+    trustLevel?: string;
+    tenantId?: string;
+    agentId?: string;
+    createdAfter?: number;
+    createdBefore?: number;
+    olderThan?: number;
+}): {
+    clause: string;
+    params: unknown[];
+};
+/** Tables allowed in dynamic SQL helpers (countRows, groupCountRows). */
+export declare const ALLOWED_TABLES: Set<string>;
+/** Columns allowed in GROUP BY for groupCountRows. */
+export declare const ALLOWED_GROUP_COLUMNS: Set<string>;
+/**
+ * Execute a COUNT(*) query against a table with an optional WHERE clause.
+ *
+ * Used by stats() to avoid repeating the COUNT pattern for total, sessions,
+ * and embedded entry counts.
+ */
+export declare function countRows(db: Database.Database, table: string, whereClause: string, whereParams: unknown[]): number;
+/**
+ * Execute a grouped COUNT(*) query, returning a Record<string, number>.
+ *
+ * Used by stats() to avoid repeating the GROUP BY + for-loop pattern
+ * for byType, byTrustLevel, and byAgent aggregations.
+ */
+export declare function groupCountRows(db: Database.Database, table: string, groupByColumn: string, whereClause: string, whereParams: unknown[]): Record<string, number>;

package/node_modules/@comis/memory/dist/row-mapper.js

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared helpers for converting between MemoryRow (DB row) and
+ * MemoryEntry (domain type), and for common DB operations.
+ *
+ * Extracted from sqlite-memory-adapter.ts and memory-api.ts to
+ * eliminate duplicate rowToEntry implementations and INSERT SQL.
+ */
+import { z } from "zod";
+import { isVecAvailable } from "./schema.js";
+const TagsSchema = z.array(z.string());
+/** Parse a JSON-encoded tags string with Zod validation, falling back to empty array on corrupt data. */
+export function parseTags(raw) {
+    try {
+        const result = TagsSchema.safeParse(JSON.parse(raw));
+        return result.success ? result.data : [];
+    }
+    catch {
+        return [];
+    }
+}
+// ── Row Conversion ───────────────────────────────────────────────────
+/** Convert a MemoryRow (DB row) to a MemoryEntry (domain type).
+ *  The returned object includes a non-schema `memoryType` property
+ *  so that RPC handlers can surface the DB-level memory_type column
+ *  without modifying the strict MemoryEntry Zod schema.
+ */
+export function rowToEntry(row, embedding) {
+    return {
+        id: row.id,
+        tenantId: row.tenant_id,
+        agentId: row.agent_id,
+        userId: row.user_id,
+        content: row.content,
+        trustLevel: row.trust_level,
+        source: {
+            who: row.source_who,
+            ...(row.source_channel ? { channel: row.source_channel } : {}),
+            ...(row.source_session_key ? { sessionKey: row.source_session_key } : {}),
+        },
+        tags: parseTags(row.tags),
+        createdAt: row.created_at,
+        ...(row.updated_at !== null ? { updatedAt: row.updated_at } : {}),
+        ...(row.expires_at !== null ? { expiresAt: row.expires_at } : {}),
+        ...(embedding ? { embedding } : {}),
+        memoryType: row.memory_type,
+    };
+}
+// ── Insert Helper ────────────────────────────────────────────────────
+/**
+ * Insert a memory entry into the `memories` table.
+ *
+ * Encapsulates the INSERT SQL previously duplicated in
+ * SqliteMemoryAdapter.store() and storeWithType().
+ */
+export function insertMemoryRow(db, entry, memoryType) {
+    db.prepare(`INSERT INTO memories (id, tenant_id, agent_id, user_id, content, trust_level, memory_type, source_who, source_channel, source_session_key, tags, created_at, updated_at, expires_at, has_embedding)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)`).run(entry.id, entry.tenantId, entry.agentId ?? "default", entry.userId, entry.content, entry.trustLevel, memoryType, entry.source.who, entry.source.channel ?? null, entry.source.sessionKey ?? null, JSON.stringify(entry.tags), entry.createdAt, entry.updatedAt ?? null, entry.expiresAt ?? null);
+}
+// ── Embedding Storage ────────────────────────────────────────────────
+/**
+ * Store an embedding vector for a memory entry.
+ *
+ * Inserts into vec_memories and sets has_embedding=1 on the memories row.
+ * Only operates when sqlite-vec is available.
+ */
+export function storeEmbedding(db, entryId, embedding, vecAvailable) {
+    // Use per-instance vec state when provided, fall back to global
+    const vecIsAvailable = vecAvailable ?? isVecAvailable();
+    if (!vecIsAvailable)
+        return;
+    const float32 = new Float32Array(embedding);
+    db.prepare("INSERT INTO vec_memories(memory_id, embedding) VALUES (?, ?)").run(entryId, float32);
+    db.prepare("UPDATE memories SET has_embedding = 1 WHERE id = ?").run(entryId);
+}
+// ── Filter Helpers (for MemoryApi) ───────────────────────────────────
+/**
+ * Build a WHERE clause and parameter array from optional filter fields.
+ *
+ * Used by memory-api.ts inspect(), clear(), and stats() methods to avoid
+ * repeated conditional WHERE clause assembly.
+ */
+export function buildFilterClause(filters) {
+    const conditions = [];
+    const params = [];
+    if (filters.memoryType) {
+        conditions.push("memory_type = ?");
+        params.push(filters.memoryType);
+    }
+    if (filters.trustLevel) {
+        conditions.push("trust_level = ?");
+        params.push(filters.trustLevel);
+    }
+    if (filters.tenantId) {
+        conditions.push("tenant_id = ?");
+        params.push(filters.tenantId);
+    }
+    if (filters.agentId) {
+        conditions.push("agent_id = ?");
+        params.push(filters.agentId);
+    }
+    if (filters.createdAfter !== undefined) {
+        conditions.push("created_at > ?");
+        params.push(filters.createdAfter);
+    }
+    if (filters.createdBefore !== undefined) {
+        conditions.push("created_at < ?");
+        params.push(filters.createdBefore);
+    }
+    if (filters.olderThan !== undefined) {
+        conditions.push("created_at < ?");
+        params.push(filters.olderThan);
+    }
+    const clause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    return { clause, params };
+}
+// ── SQL Interpolation Whitelists ─────────────────────────────────────
+/** Tables allowed in dynamic SQL helpers (countRows, groupCountRows). */
+export const ALLOWED_TABLES = new Set(["memories", "sessions"]);
+/** Columns allowed in GROUP BY for groupCountRows. */
+export const ALLOWED_GROUP_COLUMNS = new Set(["memory_type", "trust_level", "agent_id"]);
+// ── Count Helpers (for MemoryApi.stats()) ─────────────────────────────
+/**
+ * Execute a COUNT(*) query against a table with an optional WHERE clause.
+ *
+ * Used by stats() to avoid repeating the COUNT pattern for total, sessions,
+ * and embedded entry counts.
+ */
+export function countRows(db, table, whereClause, whereParams) {
+    if (!ALLOWED_TABLES.has(table)) {
+        throw new Error(`countRows: invalid table "${table}" -- must be one of: ${[...ALLOWED_TABLES].join(", ")}`);
+    }
+    const row = db
+        .prepare(`SELECT COUNT(*) as count FROM ${table} ${whereClause}`)
+        .get(...whereParams);
+    return row.count;
+}
+/**
+ * Execute a grouped COUNT(*) query, returning a Record<string, number>.
+ *
+ * Used by stats() to avoid repeating the GROUP BY + for-loop pattern
+ * for byType, byTrustLevel, and byAgent aggregations.
+ */
+export function groupCountRows(db, table, groupByColumn, whereClause, whereParams) {
+    if (!ALLOWED_TABLES.has(table)) {
+        throw new Error(`groupCountRows: invalid table "${table}" -- must be one of: ${[...ALLOWED_TABLES].join(", ")}`);
+    }
+    if (!ALLOWED_GROUP_COLUMNS.has(groupByColumn)) {
+        throw new Error(`groupCountRows: invalid column "${groupByColumn}" -- must be one of: ${[...ALLOWED_GROUP_COLUMNS].join(", ")}`);
+    }
+    const rows = db
+        .prepare(`SELECT ${groupByColumn}, COUNT(*) as count FROM ${table} ${whereClause} GROUP BY ${groupByColumn}`)
+        .all(...whereParams);
+    const result = {};
+    for (const row of rows) {
+        result[row[groupByColumn]] = row.count;
+    }
+    return result;
+}

package/node_modules/@comis/memory/dist/row-mapper.test.d.ts

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

package/node_modules/@comis/memory/dist/row-mapper.test.js

@@ -0,0 +1,409 @@
+import Database from "better-sqlite3";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { rowToEntry, insertMemoryRow, storeEmbedding, buildFilterClause, countRows, groupCountRows, ALLOWED_TABLES, ALLOWED_GROUP_COLUMNS, } from "./row-mapper.js";
+import { initSchema, isVecAvailable } from "./schema.js";
+const DIMS = 4;
+// ── Test Fixtures ────────────────────────────────────────────────────
+/** Create a complete MemoryRow with all fields populated. */
+function makeRow(overrides) {
+    const defaults = {
+        id: "row-1",
+        tenant_id: "default",
+        agent_id: "default",
+        user_id: "user-1",
+        content: "test content",
+        trust_level: "learned",
+        memory_type: "semantic",
+        source_who: "agent",
+        source_channel: "telegram",
+        source_session_key: "sess-123",
+        tags: '["tag1","tag2"]',
+        created_at: 1700000000000,
+        updated_at: 1700001000000,
+        expires_at: 1700090000000,
+        has_embedding: 0,
+    };
+    return { ...defaults, ...overrides };
+}
+/** Create a minimal valid MemoryEntry. */
+function makeEntry(overrides) {
+    return {
+        id: overrides?.id ?? crypto.randomUUID(),
+        tenantId: overrides?.tenantId ?? "default",
+        agentId: overrides?.agentId ?? "default",
+        userId: overrides?.userId ?? "user-1",
+        content: overrides?.content ?? "test memory content",
+        trustLevel: overrides?.trustLevel ?? "learned",
+        source: overrides?.source ?? { who: "agent", channel: "telegram" },
+        tags: overrides?.tags ?? [],
+        createdAt: overrides?.createdAt ?? Date.now(),
+        ...(overrides?.updatedAt !== undefined ? { updatedAt: overrides.updatedAt } : {}),
+        ...(overrides?.expiresAt !== undefined ? { expiresAt: overrides.expiresAt } : {}),
+        ...(overrides?.embedding ? { embedding: overrides.embedding } : {}),
+    };
+}
+// ── rowToEntry ───────────────────────────────────────────────────────
+describe("rowToEntry", () => {
+    it("converts a complete MemoryRow with all fields populated", () => {
+        const row = makeRow();
+        const entry = rowToEntry(row);
+        expect(entry.id).toBe("row-1");
+        expect(entry.tenantId).toBe("default");
+        expect(entry.agentId).toBe("default");
+        expect(entry.userId).toBe("user-1");
+        expect(entry.content).toBe("test content");
+        expect(entry.trustLevel).toBe("learned");
+        expect(entry.source.who).toBe("agent");
+        expect(entry.source.channel).toBe("telegram");
+        expect(entry.source.sessionKey).toBe("sess-123");
+        expect(entry.tags).toEqual(["tag1", "tag2"]);
+        expect(entry.createdAt).toBe(1700000000000);
+        expect(entry.updatedAt).toBe(1700001000000);
+        expect(entry.expiresAt).toBe(1700090000000);
+    });
+    it("converts a MemoryRow with null optional fields", () => {
+        const row = makeRow({
+            source_channel: null,
+            source_session_key: null,
+            updated_at: null,
+            expires_at: null,
+        });
+        const entry = rowToEntry(row);
+        expect(entry.source.channel).toBeUndefined();
+        expect(entry.source.sessionKey).toBeUndefined();
+        expect(entry.updatedAt).toBeUndefined();
+        expect(entry.expiresAt).toBeUndefined();
+    });
+    it("includes embedding when provided", () => {
+        const row = makeRow();
+        const embedding = [0.1, 0.2, 0.3, 0.4];
+        const entry = rowToEntry(row, embedding);
+        expect(entry.embedding).toEqual([0.1, 0.2, 0.3, 0.4]);
+    });
+    it("omits embedding when not provided", () => {
+        const row = makeRow();
+        const entry = rowToEntry(row);
+        expect(entry.embedding).toBeUndefined();
+    });
+    it("correctly parses JSON tags", () => {
+        const row = makeRow({ tags: '["important","project-x","review"]' });
+        const entry = rowToEntry(row);
+        expect(entry.tags).toEqual(["important", "project-x", "review"]);
+    });
+    it("parses empty JSON tags array", () => {
+        const row = makeRow({ tags: "[]" });
+        const entry = rowToEntry(row);
+        expect(entry.tags).toEqual([]);
+    });
+});
+// ── insertMemoryRow ──────────────────────────────────────────────────
+describe("insertMemoryRow", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSchema(db, DIMS);
+    });
+    afterEach(() => {
+        db.close();
+    });
+    it("inserts a row with all fields", () => {
+        const entry = makeEntry({
+            id: "mem-1",
+            tenantId: "tenant-a",
+            agentId: "coder",
+            userId: "user-42",
+            content: "important fact",
+            trustLevel: "system",
+            source: { who: "admin", channel: "cli", sessionKey: "sk-1" },
+            tags: ["critical"],
+            createdAt: 1700000000000,
+            updatedAt: 1700001000000,
+            expiresAt: 1700090000000,
+        });
+        insertMemoryRow(db, entry, "semantic");
+        const row = db.prepare("SELECT * FROM memories WHERE id = ?").get("mem-1");
+        expect(row.id).toBe("mem-1");
+        expect(row.tenant_id).toBe("tenant-a");
+        expect(row.agent_id).toBe("coder");
+        expect(row.user_id).toBe("user-42");
+        expect(row.content).toBe("important fact");
+        expect(row.trust_level).toBe("system");
+        expect(row.memory_type).toBe("semantic");
+        expect(row.source_who).toBe("admin");
+        expect(row.source_channel).toBe("cli");
+        expect(row.source_session_key).toBe("sk-1");
+        expect(JSON.parse(row.tags)).toEqual(["critical"]);
+        expect(row.created_at).toBe(1700000000000);
+        expect(row.updated_at).toBe(1700001000000);
+        expect(row.expires_at).toBe(1700090000000);
+        expect(row.has_embedding).toBe(0);
+    });
+    it("defaults agentId to 'default' when undefined", () => {
+        const entry = makeEntry({ id: "mem-2" });
+        // Force agentId to undefined to test default path
+        entry.agentId = undefined;
+        insertMemoryRow(db, entry, "working");
+        const row = db.prepare("SELECT agent_id FROM memories WHERE id = ?").get("mem-2");
+        expect(row.agent_id).toBe("default");
+    });
+    it("handles null optional fields (source_channel, source_session_key, expires_at)", () => {
+        const entry = makeEntry({
+            id: "mem-3",
+            source: { who: "agent" },
+        });
+        insertMemoryRow(db, entry, "episodic");
+        const row = db.prepare("SELECT * FROM memories WHERE id = ?").get("mem-3");
+        expect(row.source_channel).toBeNull();
+        expect(row.source_session_key).toBeNull();
+        expect(row.expires_at).toBeNull();
+    });
+    it("stores correct memory_type", () => {
+        const entry = makeEntry({ id: "mem-4" });
+        insertMemoryRow(db, entry, "procedural");
+        const row = db.prepare("SELECT memory_type FROM memories WHERE id = ?").get("mem-4");
+        expect(row.memory_type).toBe("procedural");
+    });
+});
+// ── storeEmbedding ───────────────────────────────────────────────────
+describe("storeEmbedding", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSchema(db, DIMS);
+    });
+    afterEach(() => {
+        db.close();
+    });
+    it("inserts embedding and sets has_embedding=1", () => {
+        if (!isVecAvailable())
+            return;
+        // First insert a memory row
+        const entry = makeEntry({ id: "mem-embed-1" });
+        insertMemoryRow(db, entry, "semantic");
+        // Store embedding
+        storeEmbedding(db, "mem-embed-1", [0.1, 0.2, 0.3, 0.4]);
+        // Verify has_embedding flag
+        const row = db.prepare("SELECT has_embedding FROM memories WHERE id = ?").get("mem-embed-1");
+        expect(row.has_embedding).toBe(1);
+        // Verify vec_memories entry exists
+        const vecRow = db
+            .prepare("SELECT memory_id FROM vec_memories WHERE memory_id = ?")
+            .get("mem-embed-1");
+        expect(vecRow).toBeDefined();
+        expect(vecRow.memory_id).toBe("mem-embed-1");
+    });
+    it("stores correct float values in vec_memories", () => {
+        if (!isVecAvailable())
+            return;
+        const entry = makeEntry({ id: "mem-embed-2" });
+        insertMemoryRow(db, entry, "semantic");
+        storeEmbedding(db, "mem-embed-2", [0.5, 0.25, 0.75, 1.0]);
+        const vecRow = db
+            .prepare("SELECT embedding FROM vec_memories WHERE memory_id = ?")
+            .get("mem-embed-2");
+        expect(vecRow).toBeDefined();
+        const float32 = new Float32Array(vecRow.embedding.buffer, vecRow.embedding.byteOffset, vecRow.embedding.byteLength / Float32Array.BYTES_PER_ELEMENT);
+        expect(float32[0]).toBeCloseTo(0.5, 4);
+        expect(float32[1]).toBeCloseTo(0.25, 4);
+        expect(float32[2]).toBeCloseTo(0.75, 4);
+        expect(float32[3]).toBeCloseTo(1.0, 4);
+    });
+    it("no-ops when sqlite-vec is unavailable", () => {
+        // This test verifies the function doesn't throw when vec is unavailable.
+        // We can't easily mock isVecAvailable, but we verify it's called
+        // by passing through without error. If vec IS available, this test
+        // exercises the normal path instead.
+        const entry = makeEntry({ id: "mem-embed-3" });
+        insertMemoryRow(db, entry, "semantic");
+        // Should not throw regardless of vec availability
+        expect(() => storeEmbedding(db, "mem-embed-3", [0.1, 0.2, 0.3, 0.4])).not.toThrow();
+    });
+});
+// ── buildFilterClause ────────────────────────────────────────────────
+describe("buildFilterClause", () => {
+    it("empty filters produce empty clause", () => {
+        const result = buildFilterClause({});
+        expect(result.clause).toBe("");
+        expect(result.params).toEqual([]);
+    });
+    it("single filter produces correct WHERE clause", () => {
+        const result = buildFilterClause({ tenantId: "t1" });
+        expect(result.clause).toBe("WHERE tenant_id = ?");
+        expect(result.params).toEqual(["t1"]);
+    });
+    it("multiple filters combine with AND", () => {
+        const result = buildFilterClause({
+            memoryType: "semantic",
+            trustLevel: "learned",
+            tenantId: "t1",
+        });
+        expect(result.clause).toBe("WHERE memory_type = ? AND trust_level = ? AND tenant_id = ?");
+        expect(result.params).toEqual(["semantic", "learned", "t1"]);
+    });
+    it("params array matches clause placeholders", () => {
+        const result = buildFilterClause({
+            agentId: "coder",
+            createdAfter: 1000,
+            createdBefore: 2000,
+        });
+        const placeholderCount = (result.clause.match(/\?/g) ?? []).length;
+        expect(placeholderCount).toBe(result.params.length);
+        expect(result.params).toEqual(["coder", 1000, 2000]);
+    });
+    it("handles all filter types together", () => {
+        const result = buildFilterClause({
+            memoryType: "episodic",
+            trustLevel: "system",
+            tenantId: "t1",
+            agentId: "bot",
+            createdAfter: 100,
+            createdBefore: 900,
+            olderThan: 800,
+        });
+        expect(result.clause).toContain("WHERE");
+        expect(result.clause).toContain("memory_type = ?");
+        expect(result.clause).toContain("trust_level = ?");
+        expect(result.clause).toContain("tenant_id = ?");
+        expect(result.clause).toContain("agent_id = ?");
+        expect(result.clause).toContain("created_at > ?");
+        // createdBefore and olderThan both produce "created_at < ?"
+        expect((result.clause.match(/created_at < \?/g) ?? []).length).toBe(2);
+        expect(result.params).toHaveLength(7);
+    });
+    it("undefined values are skipped", () => {
+        const result = buildFilterClause({
+            memoryType: undefined,
+            trustLevel: "external",
+            tenantId: undefined,
+        });
+        expect(result.clause).toBe("WHERE trust_level = ?");
+        expect(result.params).toEqual(["external"]);
+    });
+});
+// ── countRows ───────────────────────────────────────────────────────
+describe("countRows", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSchema(db, DIMS);
+    });
+    afterEach(() => {
+        db.close();
+    });
+    it("returns 0 for an empty table", () => {
+        const count = countRows(db, "memories", "", []);
+        expect(count).toBe(0);
+    });
+    it("returns correct count with entries", () => {
+        insertMemoryRow(db, makeEntry({ id: "cr-1" }), "semantic");
+        insertMemoryRow(db, makeEntry({ id: "cr-2" }), "episodic");
+        insertMemoryRow(db, makeEntry({ id: "cr-3" }), "semantic");
+        const count = countRows(db, "memories", "", []);
+        expect(count).toBe(3);
+    });
+    it("filters correctly with WHERE clause", () => {
+        insertMemoryRow(db, makeEntry({ id: "cr-4", tenantId: "t1" }), "semantic");
+        insertMemoryRow(db, makeEntry({ id: "cr-5", tenantId: "t1" }), "episodic");
+        insertMemoryRow(db, makeEntry({ id: "cr-6", tenantId: "t2" }), "semantic");
+        const count = countRows(db, "memories", "WHERE tenant_id = ?", ["t1"]);
+        expect(count).toBe(2);
+    });
+});
+// ── groupCountRows ──────────────────────────────────────────────────
+describe("groupCountRows", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSchema(db, DIMS);
+    });
+    afterEach(() => {
+        db.close();
+    });
+    it("returns empty object for an empty table", () => {
+        const result = groupCountRows(db, "memories", "memory_type", "", []);
+        expect(result).toEqual({});
+    });
+    it("groups by memory_type correctly", () => {
+        insertMemoryRow(db, makeEntry({ id: "gc-1" }), "semantic");
+        insertMemoryRow(db, makeEntry({ id: "gc-2" }), "semantic");
+        insertMemoryRow(db, makeEntry({ id: "gc-3" }), "episodic");
+        insertMemoryRow(db, makeEntry({ id: "gc-4" }), "working");
+        const result = groupCountRows(db, "memories", "memory_type", "", []);
+        expect(result).toEqual({
+            semantic: 2,
+            episodic: 1,
+            working: 1,
+        });
+    });
+    it("filters groups with WHERE clause", () => {
+        insertMemoryRow(db, makeEntry({ id: "gc-5", tenantId: "t1" }), "semantic");
+        insertMemoryRow(db, makeEntry({ id: "gc-6", tenantId: "t1" }), "episodic");
+        insertMemoryRow(db, makeEntry({ id: "gc-7", tenantId: "t2" }), "semantic");
+        const result = groupCountRows(db, "memories", "memory_type", "WHERE tenant_id = ?", ["t1"]);
+        expect(result).toEqual({
+            semantic: 1,
+            episodic: 1,
+        });
+    });
+});
+// ── DATA-03: Whitelist validation for table/column names ───────────
+describe("countRows whitelist validation", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSchema(db, DIMS);
+    });
+    afterEach(() => {
+        db.close();
+    });
+    it("accepts 'memories' table", () => {
+        expect(() => countRows(db, "memories", "", [])).not.toThrow();
+    });
+    it("accepts 'sessions' table", () => {
+        expect(() => countRows(db, "sessions", "", [])).not.toThrow();
+    });
+    it("rejects invalid table name", () => {
+        expect(() => countRows(db, "evil_table", "", [])).toThrow('countRows: invalid table "evil_table"');
+    });
+    it("rejects SQL injection in table name", () => {
+        expect(() => countRows(db, "memories; DROP TABLE memories;--", "", [])).toThrow("countRows: invalid table");
+    });
+});
+describe("groupCountRows whitelist validation", () => {
+    let db;
+    beforeEach(() => {
+        db = new Database(":memory:");
+        initSchema(db, DIMS);
+    });
+    afterEach(() => {
+        db.close();
+    });
+    it("accepts 'memory_type' column", () => {
+        expect(() => groupCountRows(db, "memories", "memory_type", "", [])).not.toThrow();
+    });
+    it("accepts 'trust_level' column", () => {
+        expect(() => groupCountRows(db, "memories", "trust_level", "", [])).not.toThrow();
+    });
+    it("accepts 'agent_id' column", () => {
+        expect(() => groupCountRows(db, "memories", "agent_id", "", [])).not.toThrow();
+    });
+    it("rejects invalid column name", () => {
+        expect(() => groupCountRows(db, "memories", "evil_column", "", [])).toThrow('groupCountRows: invalid column "evil_column"');
+    });
+    it("rejects invalid table name", () => {
+        expect(() => groupCountRows(db, "evil_table", "memory_type", "", [])).toThrow('groupCountRows: invalid table "evil_table"');
+    });
+});
+describe("whitelist exports", () => {
+    it("ALLOWED_TABLES contains expected values", () => {
+        expect(ALLOWED_TABLES.has("memories")).toBe(true);
+        expect(ALLOWED_TABLES.has("sessions")).toBe(true);
+        expect(ALLOWED_TABLES.size).toBe(2);
+    });
+    it("ALLOWED_GROUP_COLUMNS contains expected values", () => {
+        expect(ALLOWED_GROUP_COLUMNS.has("memory_type")).toBe(true);
+        expect(ALLOWED_GROUP_COLUMNS.has("trust_level")).toBe(true);
+        expect(ALLOWED_GROUP_COLUMNS.has("agent_id")).toBe(true);
+        expect(ALLOWED_GROUP_COLUMNS.size).toBe(3);
+    });
+});

package/node_modules/@comis/memory/dist/schema.d.ts

@@ -0,0 +1,31 @@
+/**
+ * SQLite schema initialization for the @comis/memory package.
+ *
+ * Creates all tables, virtual tables, indexes, and triggers required
+ * by the memory system. Uses better-sqlite3 for synchronous DDL and
+ * sqlite-vec for vector search support (with graceful degradation).
+ */
+import type Database from "better-sqlite3";
+/**
+ * Check whether the sqlite-vec extension was loaded successfully
+ * during the last `initSchema()` call. When false, vector search
+ * is unavailable and only FTS5 text search will work.
+ */
+export declare function isVecAvailable(): boolean;
+/**
+ * Initialize the full memory schema on the given SQLite database.
+ *
+ * Creates:
+ * - `memories` table with CHECK constraints and indexes
+ * - `vec_memories` virtual table (if sqlite-vec is available)
+ * - `memory_fts` FTS5 virtual table with external content triggers
+ * - `sessions` table with indexes
+ *
+ * Safe to call multiple times (all DDL uses IF NOT EXISTS).
+ *
+ * @param db - An open better-sqlite3 Database instance
+ * @param embeddingDimensions - Vector dimension size for vec_memories (e.g. 1536)
+ */
+export declare function initSchema(db: Database.Database, embeddingDimensions: number): {
+    vecAvailable: boolean;
+};