@kernl-sdk/libsql 0.1.36 → 0.1.39

package/dist/memory/__tests__/update.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { create_client, create_storage, testid } from "../../__tests__/helpers.js";
+describe("LibSQLMemoryStore update", () => {
+    let client;
+    let storage;
+    let memId;
+    beforeEach(async () => {
+        client = create_client();
+        storage = create_storage(client);
+        await storage.memories.list(); // init
+        memId = testid("mem");
+        await storage.memories.create({
+            id: memId,
+            scope: { namespace: "default", entityId: "user-1" },
+            kind: "semantic",
+            collection: "facts",
+            content: { text: "Original content" },
+            wmem: false,
+            metadata: { version: 1 },
+        });
+    });
+    afterEach(() => {
+        client.close();
+    });
+    it("updates content and bumps updated_at", async () => {
+        const before = await storage.memories.get(memId);
+        const originalUpdatedAt = before.updatedAt;
+        // Small delay to ensure timestamp difference
+        await new Promise((r) => setTimeout(r, 10));
+        const updated = await storage.memories.update(memId, {
+            id: memId,
+            content: { text: "Updated content" },
+        });
+        expect(updated.content).toEqual({ text: "Updated content" });
+        expect(updated.updatedAt).toBeGreaterThan(originalUpdatedAt);
+        // Verify persisted
+        const found = await storage.memories.get(memId);
+        expect(found?.content).toEqual({ text: "Updated content" });
+    });
+    it("updates wmem flag", async () => {
+        const updated = await storage.memories.update(memId, {
+            id: memId,
+            wmem: true,
+        });
+        expect(updated.wmem).toBe(true);
+        const found = await storage.memories.get(memId);
+        expect(found?.wmem).toBe(true);
+    });
+    it("updates smem expiration", async () => {
+        const expiresAt = Date.now() + 7200000;
+        const updated = await storage.memories.update(memId, {
+            id: memId,
+            smem: { expiresAt },
+        });
+        expect(updated.smem.expiresAt).toBe(expiresAt);
+        const found = await storage.memories.get(memId);
+        expect(found?.smem.expiresAt).toBe(expiresAt);
+    });
+    it("clears smem expiration", async () => {
+        // First set an expiration
+        await storage.memories.update(memId, {
+            id: memId,
+            smem: { expiresAt: Date.now() + 3600000 },
+        });
+        // Then clear it
+        const updated = await storage.memories.update(memId, {
+            id: memId,
+            smem: { expiresAt: null },
+        });
+        expect(updated.smem.expiresAt).toBeNull();
+    });
+    it("updates metadata", async () => {
+        const newMetadata = { version: 2, source: "api", edited: true };
+        const updated = await storage.memories.update(memId, {
+            id: memId,
+            metadata: newMetadata,
+        });
+        expect(updated.metadata).toEqual(newMetadata);
+        const found = await storage.memories.get(memId);
+        expect(found?.metadata).toEqual(newMetadata);
+    });
+    it("updates multiple fields at once", async () => {
+        const updated = await storage.memories.update(memId, {
+            id: memId,
+            content: { text: "New content" },
+            wmem: true,
+            metadata: { version: 3 },
+        });
+        expect(updated.content).toEqual({ text: "New content" });
+        expect(updated.wmem).toBe(true);
+        expect(updated.metadata).toEqual({ version: 3 });
+    });
+    it("throws when memory does not exist", async () => {
+        await expect(storage.memories.update("nonexistent", {
+            id: "nonexistent",
+            content: { text: "test" },
+        })).rejects.toThrow(/not found/i);
+    });
+    it("preserves unchanged fields", async () => {
+        const before = await storage.memories.get(memId);
+        await storage.memories.update(memId, {
+            id: memId,
+            wmem: true,
+        });
+        const after = await storage.memories.get(memId);
+        // Content should be unchanged
+        expect(after?.content).toEqual(before?.content);
+        expect(after?.kind).toBe(before?.kind);
+        expect(after?.collection).toBe(before?.collection);
+        // wmem should be updated
+        expect(after?.wmem).toBe(true);
+    });
+});

package/dist/memory/row.d.ts

@@ -0,0 +1,11 @@
+/**
+ * LibSQL row codecs for memory data.
+ */
+import type { Row } from "@libsql/client";
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { MemoryDBRecord } from "@kernl-sdk/storage";
+/**
+ * Codec for converting LibSQL rows to MemoryDBRecord.
+ */
+export declare const RowToMemoryRecord: Codec<Row, MemoryDBRecord>;
+//# sourceMappingURL=row.d.ts.map

package/dist/memory/row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row.d.ts","sourceRoot":"","sources":["../../src/memory/row.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIzD;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,GAAG,EAAE,cAAc,CAsBxD,CAAC"}

package/dist/memory/row.js

@@ -0,0 +1,29 @@
+/**
+ * LibSQL row codecs for memory data.
+ */
+import { parsejson } from "../utils.js";
+/**
+ * Codec for converting LibSQL rows to MemoryDBRecord.
+ */
+export const RowToMemoryRecord = {
+    encode(row) {
+        return {
+            id: row.id,
+            namespace: row.namespace,
+            entity_id: row.entity_id,
+            agent_id: row.agent_id,
+            kind: row.kind,
+            collection: row.collection,
+            content: parsejson(row.content) ?? {},
+            wmem: Boolean(row.wmem), // Convert SQLite 0/1 to boolean
+            smem_expires_at: row.smem_expires_at,
+            timestamp: row.timestamp,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+            metadata: parsejson(row.metadata),
+        };
+    },
+    decode() {
+        throw new Error("RowToMemoryRecord.decode not implemented");
+    },
+};

package/dist/memory/sql.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Memory SQL conversion codecs for LibSQL.
+ *
+ * Uses ? placeholders instead of PostgreSQL's $1, $2, etc.
+ */
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { MemoryFilter, MemoryRecordUpdate } from "kernl";
+import { type SQLClause } from "../sql.js";
+export interface WhereInput {
+    filter?: MemoryFilter;
+}
+/**
+ * Encode MemoryFilter to SQL WHERE clause with ? placeholders.
+ */
+export declare const SQL_WHERE: Codec<WhereInput, SQLClause>;
+type OrderDirection = "asc" | "desc";
+export interface OrderInput {
+    order?: OrderDirection;
+    defaultColumn?: string;
+    defaultDirection?: OrderDirection;
+}
+/**
+ * Encode order options to SQL ORDER BY clause.
+ */
+export declare const ORDER: Codec<OrderInput, string>;
+export interface PatchInput {
+    patch: MemoryRecordUpdate;
+}
+/**
+ * Encode MemoryRecordUpdate to SQL SET clause with ? placeholders.
+ */
+export declare const SQL_UPDATE: Codec<PatchInput, SQLClause>;
+export {};
+//# sourceMappingURL=sql.d.ts.map

package/dist/memory/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/memory/sql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE9D,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,QAAQ,CAAC;AAErD,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,CAyDlD,CAAC;AAEF,KAAK,cAAc,GAAG,KAAK,GAAG,MAAM,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,cAAc,CAAC;CACnC;AAED;;GAEG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,CAS3C,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,CAmCnD,CAAC"}

package/dist/memory/sql.js

@@ -0,0 +1,109 @@
+/**
+ * Memory SQL conversion codecs for LibSQL.
+ *
+ * Uses ? placeholders instead of PostgreSQL's $1, $2, etc.
+ */
+import { expandarray } from "../sql.js";
+/**
+ * Encode MemoryFilter to SQL WHERE clause with ? placeholders.
+ */
+export const SQL_WHERE = {
+    encode({ filter }) {
+        if (!filter) {
+            return { sql: "", params: [] };
+        }
+        const conditions = [];
+        const params = [];
+        if (filter.scope?.namespace !== undefined) {
+            conditions.push(`namespace = ?`);
+            params.push(filter.scope.namespace);
+        }
+        if (filter.scope?.entityId !== undefined) {
+            conditions.push(`entity_id = ?`);
+            params.push(filter.scope.entityId);
+        }
+        if (filter.scope?.agentId !== undefined) {
+            conditions.push(`agent_id = ?`);
+            params.push(filter.scope.agentId);
+        }
+        if (filter.collections && filter.collections.length > 0) {
+            const { placeholders, params: collectionParams } = expandarray(filter.collections);
+            conditions.push(`collection IN (${placeholders})`);
+            params.push(...collectionParams);
+        }
+        if (filter.wmem !== undefined) {
+            conditions.push(`wmem = ?`);
+            params.push(filter.wmem ? 1 : 0); // SQLite uses 0/1 for boolean
+        }
+        if (filter.smem === true) {
+            conditions.push(`(smem_expires_at IS NOT NULL AND smem_expires_at > ?)`);
+            params.push(Date.now());
+        }
+        else if (filter.smem === false) {
+            conditions.push(`(smem_expires_at IS NULL OR smem_expires_at <= ?)`);
+            params.push(Date.now());
+        }
+        if (filter.after !== undefined) {
+            conditions.push(`timestamp > ?`);
+            params.push(filter.after);
+        }
+        if (filter.before !== undefined) {
+            conditions.push(`timestamp < ?`);
+            params.push(filter.before);
+        }
+        return {
+            sql: conditions.length > 0 ? conditions.join(" AND ") : "",
+            params,
+        };
+    },
+    decode() {
+        throw new Error("SQL_WHERE.decode not implemented");
+    },
+};
+/**
+ * Encode order options to SQL ORDER BY clause.
+ */
+export const ORDER = {
+    encode({ order, defaultColumn = "timestamp", defaultDirection = "desc" }) {
+        const dir = (order ?? defaultDirection).toUpperCase();
+        return `${defaultColumn} ${dir}`;
+    },
+    decode() {
+        throw new Error("ORDER.decode not implemented");
+    },
+};
+/**
+ * Encode MemoryRecordUpdate to SQL SET clause with ? placeholders.
+ */
+export const SQL_UPDATE = {
+    encode({ patch }) {
+        const sets = [];
+        const params = [];
+        if (patch.content !== undefined) {
+            sets.push(`content = ?`);
+            params.push(JSON.stringify(patch.content));
+        }
+        if (patch.wmem !== undefined) {
+            sets.push(`wmem = ?`);
+            params.push(patch.wmem ? 1 : 0); // SQLite uses 0/1 for boolean
+        }
+        if (patch.smem !== undefined) {
+            sets.push(`smem_expires_at = ?`);
+            params.push(patch.smem.expiresAt);
+        }
+        if (patch.metadata !== undefined) {
+            sets.push(`metadata = ?`);
+            params.push(patch.metadata ? JSON.stringify(patch.metadata) : null);
+        }
+        // always update updated_at
+        sets.push(`updated_at = ?`);
+        params.push(Date.now());
+        return {
+            sql: sets.join(", "),
+            params,
+        };
+    },
+    decode() {
+        throw new Error("SQL_UPDATE.decode not implemented");
+    },
+};

package/dist/memory/store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * LibSQL Memory store implementation.
+ */
+import type { Client } from "@libsql/client";
+import type { MemoryStore, MemoryRecord, NewMemory, MemoryRecordUpdate, MemoryListOptions } from "kernl";
+/**
+ * LibSQL memory store implementation.
+ *
+ * All async methods call `ensureInit()` before database operations
+ * to ensure schema/tables exist.
+ */
+export declare class LibSQLMemoryStore implements MemoryStore {
+    private db;
+    private ensureInit;
+    constructor(db: Client, ensureInit: () => Promise<void>);
+    /**
+     * Get a memory by ID.
+     */
+    get(id: string): Promise<MemoryRecord | null>;
+    /**
+     * List memories matching optional filter criteria.
+     */
+    list(options?: MemoryListOptions): Promise<MemoryRecord[]>;
+    /**
+     * Create a new memory record.
+     */
+    create(memory: NewMemory): Promise<MemoryRecord>;
+    /**
+     * Update a memory record.
+     */
+    update(id: string, patch: MemoryRecordUpdate): Promise<MemoryRecord>;
+    /**
+     * Delete a memory by ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete multiple memories by ID.
+     */
+    mdelete(ids: string[]): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/memory/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAW,MAAM,gBAAgB,CAAC;AAEtD,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,OAAO,CAAC;AAcf;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,UAAU,CAAsB;gBAE5B,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAKvD;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAenD;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAgChE;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IA8BtD;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAkB1E;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvC;;OAEG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAU5C"}

package/dist/memory/store.js

@@ -0,0 +1,132 @@
+/**
+ * LibSQL Memory store implementation.
+ */
+import { KERNL_SCHEMA_NAME, MemoryRecordCodec, NewMemoryCodec, } from "@kernl-sdk/storage";
+import { SQL_WHERE, ORDER, SQL_UPDATE } from "./sql.js";
+import { RowToMemoryRecord } from "./row.js";
+import { expandarray } from "../sql.js";
+// SQLite doesn't support schemas, so we use table name prefix
+const MEMORIES_TABLE = `${KERNL_SCHEMA_NAME}_memories`;
+/**
+ * LibSQL memory store implementation.
+ *
+ * All async methods call `ensureInit()` before database operations
+ * to ensure schema/tables exist.
+ */
+export class LibSQLMemoryStore {
+    db;
+    ensureInit;
+    constructor(db, ensureInit) {
+        this.db = db;
+        this.ensureInit = ensureInit;
+    }
+    /**
+     * Get a memory by ID.
+     */
+    async get(id) {
+        await this.ensureInit();
+        const result = await this.db.execute({
+            sql: `SELECT * FROM ${MEMORIES_TABLE} WHERE id = ?`,
+            args: [id],
+        });
+        if (result.rows.length === 0) {
+            return null;
+        }
+        return MemoryRecordCodec.decode(RowToMemoryRecord.encode(result.rows[0]));
+    }
+    /**
+     * List memories matching optional filter criteria.
+     */
+    async list(options) {
+        await this.ensureInit();
+        const { sql: where, params } = SQL_WHERE.encode({
+            filter: options?.filter,
+        });
+        let query = `SELECT * FROM ${MEMORIES_TABLE}`;
+        // build where + order by
+        if (where)
+            query += ` WHERE ${where}`;
+        query += ` ORDER BY ${ORDER.encode({ order: options?.order })}`;
+        const args = [...params];
+        // add limit + offset
+        // SQLite requires LIMIT when using OFFSET, so use -1 for unlimited
+        if (options?.limit || options?.offset) {
+            query += ` LIMIT ?`;
+            args.push(options?.limit ?? -1);
+        }
+        if (options?.offset) {
+            query += ` OFFSET ?`;
+            args.push(options.offset);
+        }
+        const result = await this.db.execute({ sql: query, args });
+        return result.rows.map((row) => MemoryRecordCodec.decode(RowToMemoryRecord.encode(row)));
+    }
+    /**
+     * Create a new memory record.
+     */
+    async create(memory) {
+        await this.ensureInit();
+        const row = NewMemoryCodec.encode(memory);
+        const result = await this.db.execute({
+            sql: `INSERT INTO ${MEMORIES_TABLE}
+       (id, namespace, entity_id, agent_id, kind, collection, content, wmem, smem_expires_at, timestamp, created_at, updated_at, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING *`,
+            args: [
+                row.id,
+                row.namespace,
+                row.entity_id,
+                row.agent_id,
+                row.kind,
+                row.collection,
+                JSON.stringify(row.content),
+                row.wmem ? 1 : 0, // SQLite uses 0/1 for boolean
+                row.smem_expires_at,
+                row.timestamp,
+                row.created_at,
+                row.updated_at,
+                row.metadata ? JSON.stringify(row.metadata) : null,
+            ],
+        });
+        return MemoryRecordCodec.decode(RowToMemoryRecord.encode(result.rows[0]));
+    }
+    /**
+     * Update a memory record.
+     */
+    async update(id, patch) {
+        await this.ensureInit();
+        const { sql: updates, params } = SQL_UPDATE.encode({ patch });
+        const args = [...params, id];
+        const result = await this.db.execute({
+            sql: `UPDATE ${MEMORIES_TABLE} SET ${updates} WHERE id = ? RETURNING *`,
+            args,
+        });
+        if (result.rows.length === 0) {
+            throw new Error(`memory not found: ${id}`);
+        }
+        return MemoryRecordCodec.decode(RowToMemoryRecord.encode(result.rows[0]));
+    }
+    /**
+     * Delete a memory by ID.
+     */
+    async delete(id) {
+        await this.ensureInit();
+        await this.db.execute({
+            sql: `DELETE FROM ${MEMORIES_TABLE} WHERE id = ?`,
+            args: [id],
+        });
+    }
+    /**
+     * Delete multiple memories by ID.
+     */
+    async mdelete(ids) {
+        if (ids.length === 0)
+            return;
+        await this.ensureInit();
+        const { placeholders, params } = expandarray(ids);
+        await this.db.execute({
+            sql: `DELETE FROM ${MEMORIES_TABLE} WHERE id IN (${placeholders})`,
+            args: params,
+        });
+    }
+}

package/dist/migrations.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Database migrations for LibSQL.
+ */
+import type { Client, Transaction } from "@libsql/client";
+import type { Table, Column } from "@kernl-sdk/storage";
+/**
+ * Migration context with helpers.
+ */
+export interface MigrationContext {
+    client: Client | Transaction;
+    createTable: (table: Table<string, Record<string, Column>>) => Promise<void>;
+}
+export interface Migration {
+    id: string;
+    up: (ctx: MigrationContext) => Promise<void>;
+}
+/**
+ * List of all migrations in order.
+ */
+export declare const MIGRATIONS: Migration[];
+/**
+ * Minimum schema version required by this version of @kernl/libsql.
+ */
+export declare const REQUIRED_SCHEMA_VERSION = "0001_initial";
+/**
+ * Create a table from its definition.
+ *
+ * This function handles the conversion from the generic table definition
+ * to SQLite-compatible DDL.
+ */
+export declare function createTable(client: Client | Transaction, table: Table<string, Record<string, Column>>): Promise<void>;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAUxD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7B,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,EAcjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAwCtD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,GAAG,WAAW,EAC5B,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC,CA0Gf"}

package/dist/migrations.js

@@ -0,0 +1,157 @@
+/**
+ * Database migrations for LibSQL.
+ */
+import { KERNL_SCHEMA_NAME, TABLE_THREADS, TABLE_THREAD_EVENTS, TABLE_MEMORIES, } from "@kernl-sdk/storage";
+import { SQL_IDENTIFIER_REGEX } from "./sql.js";
+/**
+ * List of all migrations in order.
+ */
+export const MIGRATIONS = [
+    {
+        id: "001_threads",
+        async up(ctx) {
+            await ctx.createTable(TABLE_THREADS);
+            await ctx.createTable(TABLE_THREAD_EVENTS);
+        },
+    },
+    {
+        id: "002_memories",
+        async up(ctx) {
+            await ctx.createTable(TABLE_MEMORIES);
+        },
+    },
+];
+/**
+ * Minimum schema version required by this version of @kernl/libsql.
+ */
+export const REQUIRED_SCHEMA_VERSION = "0001_initial";
+/**
+ * Map PostgreSQL types to SQLite types.
+ */
+function mapColumnType(type) {
+    switch (type.toLowerCase()) {
+        case "jsonb":
+            return "TEXT"; // Store JSON as TEXT
+        case "bigint":
+            return "INTEGER"; // SQLite INTEGER can hold 64-bit
+        case "boolean":
+            return "INTEGER"; // SQLite uses 0/1 for boolean
+        default:
+            return type.toUpperCase();
+    }
+}
+/**
+ * Encode a value for use in a DEFAULT clause.
+ */
+function encodeDefault(col, value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    const type = col.type.toLowerCase();
+    switch (type) {
+        case "text":
+            return `'${String(value).replace(/'/g, "''")}'`;
+        case "integer":
+        case "bigint":
+            return String(value);
+        case "boolean":
+            return value ? "1" : "0";
+        case "jsonb":
+            return `'${JSON.stringify(value)}'`;
+        default:
+            return String(value);
+    }
+}
+/**
+ * Create a table from its definition.
+ *
+ * This function handles the conversion from the generic table definition
+ * to SQLite-compatible DDL.
+ */
+export async function createTable(client, table) {
+    if (!SQL_IDENTIFIER_REGEX.test(table.name)) {
+        throw new Error(`Invalid table name: ${table.name}`);
+    }
+    const columns = [];
+    const tableConstraints = [];
+    const indexes = [];
+    // build column definitions
+    for (const name in table.columns) {
+        const col = table.columns[name];
+        const sqlType = mapColumnType(col.type);
+        const constraints = [];
+        if (col._pk)
+            constraints.push("PRIMARY KEY");
+        if (col._unique)
+            constraints.push("UNIQUE");
+        if (!col._nullable && !col._pk)
+            constraints.push("NOT NULL");
+        if (col._default !== undefined) {
+            constraints.push(`DEFAULT ${encodeDefault(col, col._default)}`);
+        }
+        // foreign key reference
+        if (col._fk) {
+            let ref = `REFERENCES "${KERNL_SCHEMA_NAME}_${col._fk.table}" ("${col._fk.column}")`;
+            if (col._onDelete) {
+                ref += ` ON DELETE ${col._onDelete}`;
+            }
+            constraints.push(ref);
+        }
+        columns.push(`"${name}" ${sqlType} ${constraints.join(" ")}`.trim());
+    }
+    // table-level constraints
+    if (table.constraints) {
+        for (const constraint of table.constraints) {
+            switch (constraint.kind) {
+                case "unique": {
+                    const name = constraint.name ??
+                        `${table.name}_${constraint.columns.join("_")}_unique`;
+                    const cols = constraint.columns.map((c) => `"${c}"`).join(", ");
+                    tableConstraints.push(`CONSTRAINT "${name}" UNIQUE (${cols})`);
+                    break;
+                }
+                case "pkey": {
+                    const name = constraint.name ?? `${table.name}_pkey`;
+                    const cols = constraint.columns.map((c) => `"${c}"`).join(", ");
+                    tableConstraints.push(`CONSTRAINT "${name}" PRIMARY KEY (${cols})`);
+                    break;
+                }
+                case "fkey": {
+                    throw new Error("Composite foreign keys not yet supported. Use column-level .references() for single-column FKs.");
+                }
+                case "check": {
+                    const name = constraint.name ?? `${table.name}_check`;
+                    tableConstraints.push(`CONSTRAINT "${name}" CHECK (${constraint.expression})`);
+                    break;
+                }
+                case "index": {
+                    // collect indexes to create after table
+                    indexes.push({
+                        name: `idx_${table.name}_${constraint.columns.join("_")}`,
+                        columns: constraint.columns,
+                        unique: constraint.unique,
+                    });
+                    break;
+                }
+            }
+        }
+    }
+    const allConstraints = [...columns, ...tableConstraints];
+    // Use schema prefix in table name (SQLite doesn't have schemas)
+    const fullTableName = `${KERNL_SCHEMA_NAME}_${table.name}`;
+    const sql = `
+    CREATE TABLE IF NOT EXISTS "${fullTableName}" (
+      ${allConstraints.join(",\n      ")}
+    )
+  `.trim();
+    await client.execute(sql);
+    // create indexes
+    for (const index of indexes) {
+        const uniqueKeyword = index.unique ? "UNIQUE " : "";
+        const cols = index.columns.map((c) => `"${c}"`).join(", ");
+        const indexSql = `
+      CREATE ${uniqueKeyword}INDEX IF NOT EXISTS "${index.name}"
+      ON "${fullTableName}" (${cols})
+    `.trim();
+        await client.execute(indexSql);
+    }
+}