@kernl-sdk/pg 0.1.10 → 0.1.12

package/dist/storage.js

@@ -1,19 +1,64 @@
 import assert from "assert";
-import { SCHEMA_NAME, TABLE_MIGRATIONS } from "@kernl-sdk/storage";
+import { KERNL_SCHEMA_NAME, TABLE_MIGRATIONS } from "@kernl-sdk/storage";
 import { UnimplementedError } from "@kernl-sdk/shared/lib";
 /* pg */
 import { PGThreadStore } from "./thread/store.js";
+import { PGMemoryStore } from "./memory/store.js";
+import { MIGRATIONS } from "./migrations.js";
 import { SQL_IDENTIFIER_REGEX } from "./sql.js";
-import { migrations } from "./migrations.js";
+/**
+ * Default vector configuration.
+ */
+export const DEFAULT_VECTOR_CONFIG = {
+    dimensions: 1536,
+    similarity: "cosine",
+};
+/**
+ * Resolve vector config, applying defaults.
+ */
+export function resolveVectorConfig(config) {
+    if (!config)
+        return undefined;
+    if (config === true)
+        return DEFAULT_VECTOR_CONFIG;
+    return {
+        dimensions: config.dimensions ?? DEFAULT_VECTOR_CONFIG.dimensions,
+        similarity: config.similarity ?? DEFAULT_VECTOR_CONFIG.similarity,
+    };
+}
 /**
  * PostgreSQL storage adapter.
+ *
+ * Storage is lazily initialized on first use via `ensureInit()`. This means
+ * callers don't need to explicitly call `init()` - it happens automatically.
+ *
+ * NOTE: If the number of store methods grows significantly, consider replacing
+ * the manual `ensureInit()` calls with a Proxy-based wrapper for foolproof
+ * auto-initialization.
  */
 export class PGStorage {
     pool;
+    initPromise = null;
     threads;
+    memories;
     constructor(config) {
         this.pool = config.pool;
-        this.threads = new PGThreadStore(this.pool);
+        this.threads = new PGThreadStore(this.pool, () => this.ensureInit());
+        this.memories = new PGMemoryStore(this.pool, () => this.ensureInit());
+    }
+    /**
+     * Ensure storage is initialized before any operation.
+     *
+     * Safe to call multiple times - initialization only runs once.
+     */
+    async ensureInit() {
+        if (!this.initPromise) {
+            this.initPromise = this.init().catch((err) => {
+                this.initPromise = null;
+                throw err;
+            });
+        }
+        return this.initPromise;
     }
     /**
      * Bind runtime registries to storage.
@@ -31,7 +76,7 @@ export class PGStorage {
      * Initialize the storage backend.
      */
     async init() {
-        await this.pool.query(`CREATE SCHEMA IF NOT EXISTS "${SCHEMA_NAME}"`);
+        await this.pool.query(`CREATE SCHEMA IF NOT EXISTS "${KERNL_SCHEMA_NAME}"`);
         await this.createTable(TABLE_MIGRATIONS);
         await this.migrate();
     }
@@ -49,10 +94,10 @@ export class PGStorage {
         try {
             await client.query("BEGIN");
             // read applied migration IDs
-            const result = await client.query(`SELECT id FROM "${SCHEMA_NAME}".migrations ORDER BY applied_at ASC`);
+            const result = await client.query(`SELECT id FROM "${KERNL_SCHEMA_NAME}".migrations ORDER BY applied_at ASC`);
             const applied = new Set(result.rows.map((row) => row.id));
             // filter pending migrations
-            const pending = migrations.filter((m) => !applied.has(m.id));
+            const pending = MIGRATIONS.filter((m) => !applied.has(m.id));
             if (pending.length === 0) {
                 await client.query("COMMIT");
                 return;
@@ -65,7 +110,7 @@ export class PGStorage {
                         await this._createTable(client, table);
                     },
                 });
-                await client.query(`INSERT INTO "${SCHEMA_NAME}".migrations (id, applied_at) VALUES ($1, $2)`, [migration.id, Date.now()]);
+                await client.query(`INSERT INTO "${KERNL_SCHEMA_NAME}".migrations (id, applied_at) VALUES ($1, $2)`, [migration.id, Date.now()]);
             }
             await client.query("COMMIT");
         }
@@ -105,7 +150,7 @@ export class PGStorage {
             }
             // foreign key reference
             if (col._fk) {
-                let ref = `REFERENCES "${SCHEMA_NAME}"."${col._fk.table}" ("${col._fk.column}")`;
+                let ref = `REFERENCES "${KERNL_SCHEMA_NAME}"."${col._fk.table}" ("${col._fk.column}")`;
                 if (col._onDelete) {
                     ref += ` ON DELETE ${col._onDelete}`;
                 }
@@ -149,7 +194,7 @@ export class PGStorage {
         }
         const constraints = [...columns, ...tableConstraints];
         const sql = `
-      CREATE TABLE IF NOT EXISTS "${SCHEMA_NAME}"."${table.name}" (
+      CREATE TABLE IF NOT EXISTS "${KERNL_SCHEMA_NAME}"."${table.name}" (
         ${constraints.join(",\n  ")}
       )
     `.trim();
@@ -187,7 +232,7 @@ export class PGStorage {
         const indexName = `idx_${tableName}_${index.columns.join("_")}`;
         const sql = `
       CREATE ${uniqueKeyword} INDEX IF NOT EXISTS "${indexName}"
-      ON "${SCHEMA_NAME}"."${tableName}" (${columns})
+      ON "${KERNL_SCHEMA_NAME}"."${tableName}" (${columns})
     `.trim();
         await client.query(sql);
     }

package/dist/thread/sql.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Thread SQL conversion codecs.
+ *
+ * TODO: generalize object -> SQL conversion into a shared utility
+ */
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { ThreadFilter, ThreadUpdate, SortOrder } from "kernl";
+export interface SQLClause {
+    sql: string;
+    params: unknown[];
+}
+export interface WhereInput {
+    filter?: ThreadFilter;
+    startIdx: number;
+}
+/**
+ * Encode ThreadFilter to SQL WHERE clause.
+ */
+export declare const SQL_WHERE: Codec<WhereInput, SQLClause>;
+export interface OrderInput {
+    order?: {
+        createdAt?: SortOrder;
+        updatedAt?: SortOrder;
+    };
+}
+/**
+ * Encode order options to SQL ORDER BY clause.
+ */
+export declare const SQL_ORDER: Codec<OrderInput, string>;
+export interface UpdateInput {
+    patch: ThreadUpdate;
+    startIdx: number;
+}
+/**
+ * Encode ThreadUpdate to SQL SET clause.
+ */
+export declare const SQL_UPDATE: Codec<UpdateInput, SQLClause>;
+//# sourceMappingURL=sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/thread/sql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEnE,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,CAsDlD,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,SAAS,CAAC,EAAE,SAAS,CAAC;KACvB,CAAC;CACH;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,CAqB/C,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,WAAW,EAAE,SAAS,CAuCpD,CAAC"}

package/dist/thread/sql.js

@@ -0,0 +1,112 @@
+/**
+ * Thread SQL conversion codecs.
+ *
+ * TODO: generalize object -> SQL conversion into a shared utility
+ */
+/**
+ * Encode ThreadFilter to SQL WHERE clause.
+ */
+export const SQL_WHERE = {
+    encode({ filter, startIdx }) {
+        if (!filter) {
+            return { sql: "", params: [] };
+        }
+        const conditions = [];
+        const params = [];
+        let idx = startIdx;
+        if (filter.namespace !== undefined) {
+            conditions.push(`namespace = $${idx++}`);
+            params.push(filter.namespace);
+        }
+        if (filter.state !== undefined) {
+            if (Array.isArray(filter.state)) {
+                conditions.push(`state = ANY($${idx++})`);
+                params.push(filter.state);
+            }
+            else {
+                conditions.push(`state = $${idx++}`);
+                params.push(filter.state);
+            }
+        }
+        if (filter.agentId !== undefined) {
+            conditions.push(`agent_id = $${idx++}`);
+            params.push(filter.agentId);
+        }
+        if (filter.parentTaskId !== undefined) {
+            conditions.push(`parent_task_id = $${idx++}`);
+            params.push(filter.parentTaskId);
+        }
+        if (filter.createdAfter !== undefined) {
+            conditions.push(`created_at > $${idx++}`);
+            params.push(filter.createdAfter.getTime());
+        }
+        if (filter.createdBefore !== undefined) {
+            conditions.push(`created_at < $${idx++}`);
+            params.push(filter.createdBefore.getTime());
+        }
+        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 SQL_ORDER = {
+    encode({ order }) {
+        const clauses = [];
+        if (order?.createdAt) {
+            clauses.push(`created_at ${order.createdAt.toUpperCase()}`);
+        }
+        if (order?.updatedAt) {
+            clauses.push(`updated_at ${order.updatedAt.toUpperCase()}`);
+        }
+        if (clauses.length === 0) {
+            return "created_at DESC";
+        }
+        return clauses.join(", ");
+    },
+    decode() {
+        throw new Error("SQL_ORDER.decode not implemented");
+    },
+};
+/**
+ * Encode ThreadUpdate to SQL SET clause.
+ */
+export const SQL_UPDATE = {
+    encode({ patch, startIdx }) {
+        const sets = [];
+        const params = [];
+        let idx = startIdx;
+        if (patch.tick !== undefined) {
+            sets.push(`tick = $${idx++}`);
+            params.push(patch.tick);
+        }
+        if (patch.state !== undefined) {
+            sets.push(`state = $${idx++}`);
+            params.push(patch.state);
+        }
+        if (patch.context !== undefined) {
+            sets.push(`context = $${idx++}`);
+            params.push(JSON.stringify(patch.context.context));
+        }
+        if (patch.metadata !== undefined) {
+            sets.push(`metadata = $${idx++}`);
+            params.push(patch.metadata ? JSON.stringify(patch.metadata) : null);
+        }
+        // always update updated_at
+        sets.push(`updated_at = $${idx++}`);
+        params.push(Date.now());
+        return {
+            sql: sets.join(", "),
+            params,
+        };
+    },
+    decode() {
+        throw new Error("SQL_UPDATE.decode not implemented");
+    },
+};

package/dist/thread/store.d.ts

@@ -1,14 +1,18 @@
 import type { Pool, PoolClient } from "pg";
-import { type ThreadRecord } from "@kernl-sdk/storage";
-import { Thread, type ThreadEvent } from "kernl/internal";
 import { type AgentRegistry, type ModelRegistry, type ThreadStore, type NewThread, type ThreadUpdate, type ThreadInclude, type ThreadListOptions, type ThreadHistoryOptions } from "kernl";
+import { Thread, type ThreadEvent } from "kernl/internal";
+import { type ThreadRecord } from "@kernl-sdk/storage";
 /**
  * PostgreSQL Thread store implementation.
+ *
+ * IMPORTANT: All async methods must call `await this.ensureInit()` before
+ * any database operations. This ensures schema/tables exist.
  */
 export declare class PGThreadStore implements ThreadStore {
     private db;
     private registries;
-    constructor(db: Pool | PoolClient);
+    private ensureInit;
+    constructor(db: Pool | PoolClient, ensureInit: () => Promise<void>);
     /**
      * Bind runtime registries for hydrating Thread instances.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/thread/store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAE3C,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,OAAO,CAAC;AAEf;;GAEG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,UAAU,CAA0D;gBAEhE,EAAE,EAAE,IAAI,GAAG,UAAU;IAKjC;;;;OAIG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIxE;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqGvE;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiG1D;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BhD;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA6C/D;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC;;OAEG;IACG,OAAO,CACX,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,WAAW,EAAE,CAAC;IAsCzB;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkClD;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,MAAM;CAkC1E"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/thread/store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAE3C,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAI5B;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,UAAU,CAA0D;IAC5E,OAAO,CAAC,UAAU,CAAsB;gBAE5B,EAAE,EAAE,IAAI,GAAG,UAAU,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAMlE;;;;OAIG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIxE;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAuGvE;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuC1D;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BhD;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB/D;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;OAEG;IACG,OAAO,CACX,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,WAAW,EAAE,CAAC;IAuCzB;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmClD;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,MAAM;CAmC1E"}

package/dist/thread/store.js

@@ -1,15 +1,21 @@
 import assert from "assert";
-import { SCHEMA_NAME, NewThreadCodec, ThreadEventRecordCodec, } from "@kernl-sdk/storage";
-import { Thread } from "kernl/internal";
 import { Context, } from "kernl";
+import { Thread } from "kernl/internal";
+import { KERNL_SCHEMA_NAME, NewThreadCodec, ThreadEventRecordCodec, } from "@kernl-sdk/storage";
+import { SQL_WHERE, SQL_ORDER, SQL_UPDATE } from "./sql.js";
 /**
  * PostgreSQL Thread store implementation.
+ *
+ * IMPORTANT: All async methods must call `await this.ensureInit()` before
+ * any database operations. This ensures schema/tables exist.
  */
 export class PGThreadStore {
     db;
     registries;
-    constructor(db) {
+    ensureInit;
+    constructor(db, ensureInit) {
         this.db = db;
+        this.ensureInit = ensureInit;
         this.registries = null;
     }
     /**
@@ -24,6 +30,7 @@ export class PGThreadStore {
      * Get a thread by id.
      */
     async get(tid, include) {
+        await this.ensureInit();
         // JOIN with thread_events if include.history
         if (include?.history) {
             const opts = typeof include.history === "object" ? include.history : undefined;
@@ -50,8 +57,8 @@ export class PGThreadStore {
           e.timestamp,
           e.data,
           e.metadata as event_metadata
-        FROM ${SCHEMA_NAME}.threads t
-        LEFT JOIN ${SCHEMA_NAME}.thread_events e ON t.id = e.tid${eventFilter}
+        FROM ${KERNL_SCHEMA_NAME}.threads t
+        LEFT JOIN ${KERNL_SCHEMA_NAME}.thread_events e ON t.id = e.tid${eventFilter}
         WHERE t.id = $1
         ORDER BY e.seq ${order.toUpperCase()}
         ${limit}
@@ -95,7 +102,7 @@ export class PGThreadStore {
             }
         }
         // simple query without events
-        const result = await this.db.query(`SELECT * FROM ${SCHEMA_NAME}.threads WHERE id = $1`, [tid]);
+        const result = await this.db.query(`SELECT * FROM ${KERNL_SCHEMA_NAME}.threads WHERE id = $1`, [tid]);
         if (result.rows.length === 0) {
             return null;
         }
@@ -110,71 +117,25 @@ export class PGThreadStore {
      * List threads matching the filter.
      */
     async list(options) {
-        let query = `SELECT * FROM ${SCHEMA_NAME}.threads`;
-        const values = [];
-        let paramIndex = 1;
-        // build WHERE clause
-        const conditions = [];
-        if (options?.filter) {
-            const { state, agentId, parentTaskId, createdAfter, createdBefore, namespace, } = options.filter;
-            if (namespace) {
-                conditions.push(`namespace = $${paramIndex++}`);
-                values.push(namespace);
-            }
-            if (state) {
-                if (Array.isArray(state)) {
-                    conditions.push(`state = ANY($${paramIndex++})`);
-                    values.push(state);
-                }
-                else {
-                    conditions.push(`state = $${paramIndex++}`);
-                    values.push(state);
-                }
-            }
-            if (agentId) {
-                conditions.push(`agent_id = $${paramIndex++}`);
-                values.push(agentId);
-            }
-            if (parentTaskId) {
-                conditions.push(`parent_task_id = $${paramIndex++}`);
-                values.push(parentTaskId);
-            }
-            if (createdAfter) {
-                conditions.push(`created_at > $${paramIndex++}`);
-                values.push(createdAfter.getTime());
-            }
-            if (createdBefore) {
-                conditions.push(`created_at < $${paramIndex++}`);
-                values.push(createdBefore.getTime());
-            }
-        }
-        if (conditions.length > 0) {
-            query += ` WHERE ${conditions.join(" AND ")}`;
-        }
-        // build ORDER BY clause
-        const orderClauses = [];
-        if (options?.order?.createdAt) {
-            orderClauses.push(`created_at ${options.order.createdAt.toUpperCase()}`);
-        }
-        if (options?.order?.updatedAt) {
-            orderClauses.push(`updated_at ${options.order.updatedAt.toUpperCase()}`);
-        }
-        if (orderClauses.length > 0) {
-            query += ` ORDER BY ${orderClauses.join(", ")}`;
-        }
-        else {
-            // default: most recent first
-            query += ` ORDER BY created_at DESC`;
-        }
+        await this.ensureInit();
+        const { sql: where, params } = SQL_WHERE.encode({
+            filter: options?.filter,
+            startIdx: 1,
+        });
+        let idx = params.length + 1;
+        let query = `SELECT * FROM ${KERNL_SCHEMA_NAME}.threads`;
+        if (where)
+            query += ` WHERE ${where}`;
+        query += ` ORDER BY ${SQL_ORDER.encode({ order: options?.order })}`;
         if (options?.limit) {
-            query += ` LIMIT $${paramIndex++}`;
-            values.push(options.limit);
+            query += ` LIMIT $${idx++}`;
+            params.push(options.limit);
         }
         if (options?.offset) {
-            query += ` OFFSET $${paramIndex++}`;
-            values.push(options.offset);
+            query += ` OFFSET $${idx++}`;
+            params.push(options.offset);
         }
-        const result = await this.db.query(query, values);
+        const result = await this.db.query(query, params);
         return result.rows
             .map((record) => {
             try {
@@ -193,8 +154,9 @@ export class PGThreadStore {
      * Insert a new thread into the store.
      */
     async insert(thread) {
+        await this.ensureInit();
         const record = NewThreadCodec.encode(thread);
-        const result = await this.db.query(`INSERT INTO ${SCHEMA_NAME}.threads
+        const result = await this.db.query(`INSERT INTO ${KERNL_SCHEMA_NAME}.threads
        (id, namespace, agent_id, model, context, tick, state, parent_task_id, metadata, created_at, updated_at)
        VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8, $9::jsonb, $10, $11)
        RETURNING *`, [
@@ -216,51 +178,29 @@ export class PGThreadStore {
      * Update thread runtime state.
      */
     async update(tid, patch) {
-        const updates = [];
-        const values = [];
-        let paramIndex = 1;
-        if (patch.tick !== undefined) {
-            updates.push(`tick = $${paramIndex++}`);
-            values.push(patch.tick);
-        }
-        if (patch.state !== undefined) {
-            updates.push(`state = $${paramIndex++}`);
-            values.push(patch.state);
-        }
-        if (patch.context !== undefined) {
-            updates.push(`context = $${paramIndex++}`);
-            // NOTE: Store the raw context value, not the Context wrapper. 
-            //
-            // THis may change in the future depending on Context implementation.
-            values.push(JSON.stringify(patch.context.context));
-        }
-        if (patch.metadata !== undefined) {
-            updates.push(`metadata = $${paramIndex++}`);
-            values.push(patch.metadata ? JSON.stringify(patch.metadata) : null);
-        }
-        // always update `updated_at`
-        updates.push(`updated_at = $${paramIndex++}`);
-        values.push(Date.now());
-        values.push(tid); // WHERE id = $N
-        const result = await this.db.query(`UPDATE ${SCHEMA_NAME}.threads
-       SET ${updates.join(", ")}
-       WHERE id = $${paramIndex}
-       RETURNING *`, values);
+        await this.ensureInit();
+        const { sql: updates, params } = SQL_UPDATE.encode({ patch, startIdx: 1 });
+        const idx = params.length + 1;
+        params.push(tid);
+        const result = await this.db.query(`UPDATE ${KERNL_SCHEMA_NAME}.threads
+       SET ${updates}
+       WHERE id = $${idx}
+       RETURNING *`, params);
         return this.hydrate({ record: result.rows[0] });
     }
     /**
      * Delete a thread and cascade to thread_events.
      */
     async delete(tid) {
-        await this.db.query(`DELETE FROM ${SCHEMA_NAME}.threads WHERE id = $1`, [
-            tid,
-        ]);
+        await this.ensureInit();
+        await this.db.query(`DELETE FROM ${KERNL_SCHEMA_NAME}.threads WHERE id = $1`, [tid]);
     }
     /**
      * Get the event history for a thread.
      */
     async history(tid, opts) {
-        let query = `SELECT * FROM ${SCHEMA_NAME}.thread_events WHERE tid = $1`;
+        await this.ensureInit();
+        let query = `SELECT * FROM ${KERNL_SCHEMA_NAME}.thread_events WHERE tid = $1`;
         const values = [tid];
         let paramIndex = 2;
         // - filter:seq -
@@ -284,8 +224,7 @@ export class PGThreadStore {
         const result = await this.db.query(query, values);
         return result.rows.map((record) => ThreadEventRecordCodec.decode({
             ...record,
-            // Normalize BIGINT (string) to number for zod schema
-            timestamp: Number(record.timestamp),
+            timestamp: Number(record.timestamp), // normalize BIGINT (string) to number for zod schema
         }));
     }
     /**
@@ -301,6 +240,7 @@ export class PGThreadStore {
     async append(events) {
         if (events.length === 0)
             return;
+        await this.ensureInit();
         const records = events.map((e) => ThreadEventRecordCodec.encode(e));
         const values = [];
         const placeholders = [];
@@ -310,7 +250,7 @@ export class PGThreadStore {
             values.push(record.id, record.tid, record.seq, record.kind, record.timestamp, record.data, record.metadata);
         }
         // insert with ON CONFLICT DO NOTHING for idempotency
-        await this.db.query(`INSERT INTO ${SCHEMA_NAME}.thread_events
+        await this.db.query(`INSERT INTO ${KERNL_SCHEMA_NAME}.thread_events
        (id, tid, seq, kind, timestamp, data, metadata)
        VALUES ${placeholders.join(", ")}
        ON CONFLICT (tid, id) DO NOTHING`, values);
@@ -323,6 +263,7 @@ export class PGThreadStore {
         const { record, events = [] } = thread;
         const agent = this.registries.agents.get(record.agent_id);
         const model = this.registries.models.get(record.model);
+        // (TODO): we might want to allow this in the future, unclear how it would look though..
         if (!agent || !model) {
             throw new Error(`Thread ${record.id} references non-existent agent/model (agent: ${record.agent_id}, model: ${record.model})`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/pg",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "PostgreSQL storage adapter for kernl",
   "keywords": [
     "kernl",
@@ -35,15 +35,18 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/protocol": "^0.2.5"
+    "@kernl-sdk/protocol": "^0.2.5",
+    "@kernl-sdk/ai": "^0.2.7"
   },
   "dependencies": {
     "pg": "^8.16.3",
-    "kernl": "^0.6.1",
-    "@kernl-sdk/storage": "0.1.10",
-    "@kernl-sdk/shared": "^0.1.6"
+    "@kernl-sdk/shared": "^0.1.6",
+    "kernl": "^0.6.3",
+    "@kernl-sdk/retrieval": "^0.1.0",
+    "@kernl-sdk/storage": "0.1.12"
   },
   "scripts": {
+    "clean": "rm -rf dist",
     "build": "tsc && tsc-alias --resolve-full-paths",
     "dev": "tsc --watch",
     "check-types": "tsc --noEmit",