@kernl-sdk/pg 0.1.9 → 0.1.11

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kernl-sdk/pg@0.1.8 build /Users/andjones/Documents/projects/kernl/packages/storage/pg
-> tsc && tsc-alias
+> @kernl-sdk/pg@0.1.10 build /Users/andjones/Documents/projects/kernl/packages/storage/pg
+> tsc && tsc-alias --resolve-full-paths
 

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @kernl/pg
 
+## 0.1.11
+
+### Patch Changes
+
+- c5a5fcf: Storage now auto-initializes on first operation - no need to call init() manually
+- Updated dependencies [c5a5fcf]
+  - kernl@0.6.2
+  - @kernl-sdk/storage@0.1.11
+
+## 0.1.10
+
+### Patch Changes
+
+- Fix ESM compatibility by adding --resolve-full-paths to tsc-alias build
+- Updated dependencies
+  - kernl@0.6.1
+  - @kernl-sdk/shared@0.1.6
+  - @kernl-sdk/storage@0.1.10
+
 ## 0.1.9
 
 ### Patch Changes

package/dist/__tests__/integration.test.js

@@ -1,9 +1,89 @@
 import { beforeAll, afterAll, describe, it, expect } from "vitest";
 import { Pool } from "pg";
-import { PGStorage } from "../storage";
+import { PGStorage } from "../storage.js";
 import { Agent, Context, } from "kernl";
 import { Thread } from "kernl/internal";
 const TEST_DB_URL = process.env.KERNL_PG_TEST_URL;
+describe.sequential("PGStorage auto-initialization", () => {
+    if (!TEST_DB_URL) {
+        it.skip("requires KERNL_PG_TEST_URL to be set", () => { });
+        return;
+    }
+    /**
+     * Verifies that ALL store methods auto-initialize without explicit init() call.
+     *
+     * This is critical for DX - users should not need to remember to call init().
+     * Each method must internally call ensureInit() before any DB operation.
+     *
+     * Methods covered: get, list, insert, update, delete, history, append
+     */
+    it("auto-initializes on first store operation (no explicit init required)", async () => {
+        const pool = new Pool({ connectionString: TEST_DB_URL });
+        const storage = new PGStorage({ pool });
+        // Clean slate - drop schema to prove init runs automatically
+        await pool.query('DROP SCHEMA IF EXISTS "kernl" CASCADE');
+        // Bind minimal registries
+        const model = {
+            spec: "1.0",
+            provider: "test",
+            modelId: "auto-init-model",
+        };
+        const agent = new Agent({
+            id: "auto-init-agent",
+            name: "Auto Init Agent",
+            instructions: () => "test",
+            model,
+        });
+        const agents = new Map([["auto-init-agent", agent]]);
+        const models = new Map([
+            ["test/auto-init-model", model],
+        ]);
+        storage.bind({ agents, models });
+        const store = storage.threads;
+        const tid = "auto-init-thread";
+        // 1) list() - should auto-init
+        const threads = await store.list();
+        expect(threads).toEqual([]);
+        // 2) get() - should work (returns null for non-existent)
+        const got = await store.get(tid);
+        expect(got).toBeNull();
+        // 3) insert() - should work
+        const inserted = await store.insert({
+            id: tid,
+            namespace: "kernl",
+            agentId: "auto-init-agent",
+            model: "test/auto-init-model",
+        });
+        expect(inserted.tid).toBe(tid);
+        // 4) update() - should work
+        await store.update(tid, { tick: 1 });
+        const tickResult = await pool.query(`SELECT tick FROM "kernl"."threads" WHERE id = $1`, [tid]);
+        expect(tickResult.rows[0]?.tick).toBe(1);
+        // 5) history() - should work (empty)
+        const hist = await store.history(tid);
+        expect(hist).toEqual([]);
+        // 6) append() - should work
+        await store.append([
+            {
+                id: "evt-1",
+                tid,
+                seq: 0,
+                kind: "message",
+                timestamp: Date.now(),
+                data: { role: "user", text: "test" },
+                metadata: null,
+            },
+        ]);
+        // 7) delete() - should work
+        await store.delete(tid);
+        const afterDelete = await store.get(tid);
+        expect(afterDelete).toBeNull();
+        // Verify schema was created
+        const schemaResult = await pool.query(`SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'kernl'`);
+        expect(schemaResult.rows).toHaveLength(1);
+        await storage.close();
+    });
+});
 describe.sequential("PGStorage integration", () => {
     if (!TEST_DB_URL) {
         it.skip("requires KERNL_PG_TEST_URL to be set", () => {

package/dist/__tests__/thread.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
 import { Pool } from "pg";
 import { Agent, Kernl, tool, FunctionToolkit, } from "kernl";
 import { STOPPED, message, IN_PROGRESS } from "@kernl-sdk/protocol";
-import { postgres } from "../postgres";
+import { postgres } from "../postgres.js";
 // Use helper from test fixtures (handles streaming properly)
 function createMockModel(generateFn) {
     return {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @kernl/pg - PostgreSQL storage adapter for Kernl
  */
-export { PGStorage, type PGStorageConfig } from "./storage";
-export { postgres, type PostgresConfig } from "./postgres";
-export { migrations, REQUIRED_SCHEMA_VERSION } from "./migrations";
+export { PGStorage, type PGStorageConfig } from "./storage.js";
+export { postgres, type PostgresConfig } from "./postgres.js";
+export { migrations, REQUIRED_SCHEMA_VERSION } from "./migrations.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
  * @kernl/pg - PostgreSQL storage adapter for Kernl
  */
-export { PGStorage } from "./storage";
-export { postgres } from "./postgres";
-export { migrations, REQUIRED_SCHEMA_VERSION } from "./migrations";
+export { PGStorage } from "./storage.js";
+export { postgres } from "./postgres.js";
+export { migrations, REQUIRED_SCHEMA_VERSION } from "./migrations.js";

package/dist/postgres.js

@@ -1,5 +1,5 @@
 import { Pool } from "pg";
-import { PGStorage } from "./storage";
+import { PGStorage } from "./storage.js";
 /**
  * Create a PostgreSQL storage adapter for Kernl.
  *

package/dist/storage.d.ts

@@ -1,6 +1,6 @@
 import type { Pool } from "pg";
 import type { AgentRegistry, ModelRegistry, KernlStorage, Transaction } from "kernl";
-import { PGThreadStore } from "./thread/store";
+import { PGThreadStore } from "./thread/store.js";
 /**
  * PostgreSQL storage configuration.
  */
@@ -12,11 +12,25 @@ export interface PGStorageConfig {
 }
 /**
  * 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 declare class PGStorage implements KernlStorage {
     private pool;
+    private initPromise;
     threads: PGThreadStore;
     constructor(config: PGStorageConfig);
+    /**
+     * Ensure storage is initialized before any operation.
+     *
+     * Safe to call multiple times - initialization only runs once.
+     */
+    private ensureInit;
     /**
      * Bind runtime registries to storage.
      */

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAK3C,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,OAAO,CAAC;AAIf,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;GAEG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,OAAO,CAAC,IAAI,CAAO;IAEnB,OAAO,EAAE,aAAa,CAAC;gBAEX,MAAM,EAAE,eAAe;IAKnC;;OAEG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIxE;;OAEG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;OAEG;YACW,WAAW;IAUzB;;OAEG;YACW,YAAY;IA6F1B;;OAEG;YACW,UAAU;IAMxB;;OAEG;YACW,UAAU;IAIxB;;OAEG;YACW,SAAS;IAIvB;;OAEG;YACW,WAAW;CAkB1B"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAG3C,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,OAAO,CAAC;AAMf,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,WAAW,CAA8B;IAEjD,OAAO,EAAE,aAAa,CAAC;gBAEX,MAAM,EAAE,eAAe;IAKnC;;;;OAIG;YACW,UAAU;IAUxB;;OAEG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIxE;;OAEG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;OAEG;YACW,WAAW;IAUzB;;OAEG;YACW,YAAY;IA6F1B;;OAEG;YACW,UAAU;IAMxB;;OAEG;YACW,UAAU;IAIxB;;OAEG;YACW,SAAS;IAIvB;;OAEG;YACW,WAAW;CAkB1B"}

package/dist/storage.js

@@ -2,18 +2,40 @@ import assert from "assert";
 import { SCHEMA_NAME, TABLE_MIGRATIONS } from "@kernl-sdk/storage";
 import { UnimplementedError } from "@kernl-sdk/shared/lib";
 /* pg */
-import { PGThreadStore } from "./thread/store";
-import { SQL_IDENTIFIER_REGEX } from "./sql";
-import { migrations } from "./migrations";
+import { PGThreadStore } from "./thread/store.js";
+import { migrations } from "./migrations.js";
+import { SQL_IDENTIFIER_REGEX } from "./sql.js";
 /**
  * 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;
     constructor(config) {
         this.pool = config.pool;
-        this.threads = new PGThreadStore(this.pool);
+        this.threads = new PGThreadStore(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.

package/dist/thread/store.d.ts

@@ -4,11 +4,15 @@ 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";
 /**
  * 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,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;;;;;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;IAmG1D;;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;IA+C/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;CAkC1E"}

package/dist/thread/store.js

@@ -4,12 +4,17 @@ import { Thread } from "kernl/internal";
 import { Context, } from "kernl";
 /**
  * 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 +29,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;
@@ -110,6 +116,7 @@ export class PGThreadStore {
      * List threads matching the filter.
      */
     async list(options) {
+        await this.ensureInit();
         let query = `SELECT * FROM ${SCHEMA_NAME}.threads`;
         const values = [];
         let paramIndex = 1;
@@ -193,6 +200,7 @@ 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
        (id, namespace, agent_id, model, context, tick, state, parent_task_id, metadata, created_at, updated_at)
@@ -216,6 +224,7 @@ export class PGThreadStore {
      * Update thread runtime state.
      */
     async update(tid, patch) {
+        await this.ensureInit();
         const updates = [];
         const values = [];
         let paramIndex = 1;
@@ -229,7 +238,7 @@ export class PGThreadStore {
         }
         if (patch.context !== undefined) {
             updates.push(`context = $${paramIndex++}`);
-            // NOTE: Store the raw context value, not the Context wrapper. 
+            // 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));
@@ -252,6 +261,7 @@ export class PGThreadStore {
      * Delete a thread and cascade to thread_events.
      */
     async delete(tid) {
+        await this.ensureInit();
         await this.db.query(`DELETE FROM ${SCHEMA_NAME}.threads WHERE id = $1`, [
             tid,
         ]);
@@ -260,6 +270,7 @@ export class PGThreadStore {
      * Get the event history for a thread.
      */
     async history(tid, opts) {
+        await this.ensureInit();
         let query = `SELECT * FROM ${SCHEMA_NAME}.thread_events WHERE tid = $1`;
         const values = [tid];
         let paramIndex = 2;
@@ -284,8 +295,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 +311,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 = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/pg",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "PostgreSQL storage adapter for kernl",
   "keywords": [
     "kernl",
@@ -35,16 +35,16 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/protocol": "^0.2.4"
+    "@kernl-sdk/protocol": "^0.2.5"
   },
   "dependencies": {
     "pg": "^8.16.3",
-    "kernl": "^0.6.0",
-    "@kernl-sdk/shared": "^0.1.5",
-    "@kernl-sdk/storage": "0.1.9"
+    "kernl": "^0.6.2",
+    "@kernl-sdk/shared": "^0.1.6",
+    "@kernl-sdk/storage": "0.1.11"
   },
   "scripts": {
-    "build": "tsc && tsc-alias",
+    "build": "tsc && tsc-alias --resolve-full-paths",
     "dev": "tsc --watch",
     "check-types": "tsc --noEmit",
     "test": "vitest",

package/src/__tests__/integration.test.ts

@@ -16,6 +16,107 @@ const TEST_DB_URL = process.env.KERNL_PG_TEST_URL;
 type TestLanguageModel =
   ModelRegistry extends { get(key: string): infer T | undefined } ? T : never;
 
+describe.sequential("PGStorage auto-initialization", () => {
+  if (!TEST_DB_URL) {
+    it.skip("requires KERNL_PG_TEST_URL to be set", () => {});
+    return;
+  }
+
+  /**
+   * Verifies that ALL store methods auto-initialize without explicit init() call.
+   *
+   * This is critical for DX - users should not need to remember to call init().
+   * Each method must internally call ensureInit() before any DB operation.
+   *
+   * Methods covered: get, list, insert, update, delete, history, append
+   */
+  it("auto-initializes on first store operation (no explicit init required)", async () => {
+    const pool = new Pool({ connectionString: TEST_DB_URL });
+    const storage = new PGStorage({ pool });
+
+    // Clean slate - drop schema to prove init runs automatically
+    await pool.query('DROP SCHEMA IF EXISTS "kernl" CASCADE');
+
+    // Bind minimal registries
+    const model = {
+      spec: "1.0" as const,
+      provider: "test",
+      modelId: "auto-init-model",
+    } as unknown as TestLanguageModel;
+
+    const agent = new Agent({
+      id: "auto-init-agent",
+      name: "Auto Init Agent",
+      instructions: () => "test",
+      model,
+    });
+
+    const agents: AgentRegistry = new Map([["auto-init-agent", agent]]);
+    const models: ModelRegistry = new Map([
+      ["test/auto-init-model", model],
+    ]) as unknown as ModelRegistry;
+
+    storage.bind({ agents, models });
+    const store = storage.threads;
+    const tid = "auto-init-thread";
+
+    // 1) list() - should auto-init
+    const threads = await store.list();
+    expect(threads).toEqual([]);
+
+    // 2) get() - should work (returns null for non-existent)
+    const got = await store.get(tid);
+    expect(got).toBeNull();
+
+    // 3) insert() - should work
+    const inserted = await store.insert({
+      id: tid,
+      namespace: "kernl",
+      agentId: "auto-init-agent",
+      model: "test/auto-init-model",
+    });
+    expect(inserted.tid).toBe(tid);
+
+    // 4) update() - should work
+    await store.update(tid, { tick: 1 });
+    const tickResult = await pool.query<{ tick: number }>(
+      `SELECT tick FROM "kernl"."threads" WHERE id = $1`,
+      [tid],
+    );
+    expect(tickResult.rows[0]?.tick).toBe(1);
+
+    // 5) history() - should work (empty)
+    const hist = await store.history(tid);
+    expect(hist).toEqual([]);
+
+    // 6) append() - should work
+    await store.append([
+      {
+        id: "evt-1",
+        tid,
+        seq: 0,
+        kind: "message",
+        timestamp: new Date(),
+        data: { role: "user", text: "test" },
+        metadata: null,
+      } as any,
+    ]);
+
+    // 7) delete() - should work
+    await store.delete(tid);
+    const afterDelete = await store.get(tid);
+    expect(afterDelete).toBeNull();
+
+    // Verify schema was created
+    const schemaResult = await pool.query(
+      `SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'kernl'`,
+    );
+    expect(schemaResult.rows).toHaveLength(1);
+
+    await storage.close();
+  });
+});
+
 describe.sequential("PGStorage integration", () => {
   if (!TEST_DB_URL) {
     it.skip("requires KERNL_PG_TEST_URL to be set", () => {

package/src/storage.ts

@@ -2,20 +2,20 @@ import assert from "assert";
 import type { Pool, PoolClient } from "pg";
 
 /* workspace */
-import type { Table, Column, IndexConstraint } from "@kernl-sdk/storage";
-import { SCHEMA_NAME, TABLE_MIGRATIONS } from "@kernl-sdk/storage";
 import type {
   AgentRegistry,
   ModelRegistry,
   KernlStorage,
   Transaction,
 } from "kernl";
+import type { Table, Column, IndexConstraint } from "@kernl-sdk/storage";
+import { SCHEMA_NAME, TABLE_MIGRATIONS } from "@kernl-sdk/storage";
 import { UnimplementedError } from "@kernl-sdk/shared/lib";
 
 /* pg */
 import { PGThreadStore } from "./thread/store";
-import { SQL_IDENTIFIER_REGEX } from "./sql";
 import { migrations } from "./migrations";
+import { SQL_IDENTIFIER_REGEX } from "./sql";
 
 /**
  * PostgreSQL storage configuration.
@@ -29,15 +29,38 @@ export interface PGStorageConfig {
 
 /**
  * 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 implements KernlStorage {
   private pool: Pool;
+  private initPromise: Promise<void> | null = null;
 
   threads: PGThreadStore;
 
   constructor(config: PGStorageConfig) {
     this.pool = config.pool;
-    this.threads = new PGThreadStore(this.pool);
+    this.threads = new PGThreadStore(this.pool, () => this.ensureInit());
+  }
+
+  /**
+   * Ensure storage is initialized before any operation.
+   *
+   * Safe to call multiple times - initialization only runs once.
+   */
+  private async ensureInit(): Promise<void> {
+    if (!this.initPromise) {
+      this.initPromise = this.init().catch((err) => {
+        this.initPromise = null;
+        throw err;
+      });
+    }
+    return this.initPromise;
   }
 
   /**

package/src/thread/store.ts

@@ -23,13 +23,18 @@ import {
 
 /**
  * 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 implements ThreadStore {
   private db: Pool | PoolClient;
   private registries: { agents: AgentRegistry; models: ModelRegistry } | null;
+  private ensureInit: () => Promise<void>;
 
-  constructor(db: Pool | PoolClient) {
+  constructor(db: Pool | PoolClient, ensureInit: () => Promise<void>) {
     this.db = db;
+    this.ensureInit = ensureInit;
     this.registries = null;
   }
 
@@ -46,6 +51,8 @@ export class PGThreadStore implements ThreadStore {
    * Get a thread by id.
    */
   async get(tid: string, include?: ThreadInclude): Promise<Thread | null> {
+    await this.ensureInit();
+
     // JOIN with thread_events if include.history
     if (include?.history) {
       const opts =
@@ -150,6 +157,8 @@ export class PGThreadStore implements ThreadStore {
    * List threads matching the filter.
    */
   async list(options?: ThreadListOptions): Promise<Thread[]> {
+    await this.ensureInit();
+
     let query = `SELECT * FROM ${SCHEMA_NAME}.threads`;
     const values: any[] = [];
     let paramIndex = 1;
@@ -250,6 +259,8 @@ export class PGThreadStore implements ThreadStore {
    * Insert a new thread into the store.
    */
   async insert(thread: NewThread): Promise<Thread> {
+    await this.ensureInit();
+
     const record = NewThreadCodec.encode(thread);
 
     const result = await this.db.query<ThreadRecord>(
@@ -279,6 +290,8 @@ export class PGThreadStore implements ThreadStore {
    * Update thread runtime state.
    */
   async update(tid: string, patch: ThreadUpdate): Promise<Thread> {
+    await this.ensureInit();
+
     const updates: string[] = [];
     const values: any[] = [];
     let paramIndex = 1;
@@ -295,7 +308,7 @@ export class PGThreadStore implements ThreadStore {
 
     if (patch.context !== undefined) {
       updates.push(`context = $${paramIndex++}`);
-      // NOTE: Store the raw context value, not the Context wrapper. 
+      // 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));
@@ -327,6 +340,8 @@ export class PGThreadStore implements ThreadStore {
    * Delete a thread and cascade to thread_events.
    */
   async delete(tid: string): Promise<void> {
+    await this.ensureInit();
+
     await this.db.query(`DELETE FROM ${SCHEMA_NAME}.threads WHERE id = $1`, [
       tid,
     ]);
@@ -339,6 +354,8 @@ export class PGThreadStore implements ThreadStore {
     tid: string,
     opts?: ThreadHistoryOptions,
   ): Promise<ThreadEvent[]> {
+    await this.ensureInit();
+
     let query = `SELECT * FROM ${SCHEMA_NAME}.thread_events WHERE tid = $1`;
     const values: any[] = [tid];
     let paramIndex = 2;
@@ -370,8 +387,7 @@ export class PGThreadStore implements ThreadStore {
     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
       } as ThreadEventRecord),
     );
   }
@@ -388,6 +404,7 @@ export class PGThreadStore implements ThreadStore {
    */
   async append(events: ThreadEvent[]): Promise<void> {
     if (events.length === 0) return;
+    await this.ensureInit();
 
     const records = events.map((e) => ThreadEventRecordCodec.encode(e));
 
@@ -434,6 +451,7 @@ export class PGThreadStore implements ThreadStore {
     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})`,