@kernl-sdk/storage 0.1.9

package/dist/thread/schema.js

@@ -0,0 +1,141 @@
+/**
+ * Thread record schemas and table definitions.
+ */
+import { z } from "zod";
+import { THREAD_STATES } from "kernl";
+import { text, jsonb, bigint, integer, timestamps, defineTable } from "../table";
+/* ---- Table Definitions ---- */
+/**
+ * Threads table schema.
+ */
+export const TABLE_THREADS = defineTable("threads", {
+    id: text().primaryKey(),
+    namespace: text().default("kernl"),
+    agent_id: text(),
+    model: text(),
+    context: jsonb(),
+    parent_task_id: text().nullable(),
+    tick: integer().default(0),
+    state: text(),
+    metadata: jsonb().nullable(),
+    ...timestamps,
+}, [
+    { kind: "index", columns: ["state"] },
+    { kind: "index", columns: ["namespace"] },
+    { kind: "index", columns: ["agent_id"] },
+    { kind: "index", columns: ["parent_task_id"] },
+    { kind: "index", columns: ["created_at"] },
+    { kind: "index", columns: ["updated_at"] },
+]);
+/**
+ * Thread events table schema.
+ */
+export const TABLE_THREAD_EVENTS = defineTable("thread_events", {
+    id: text(),
+    tid: text().references(() => TABLE_THREADS.columns.id, {
+        onDelete: "CASCADE",
+    }),
+    seq: integer(),
+    kind: text(),
+    timestamp: bigint(),
+    data: jsonb().nullable(),
+    metadata: jsonb().nullable(),
+}, [
+    {
+        kind: "unique",
+        columns: ["tid", "id"],
+    },
+    { kind: "index", columns: ["tid", "seq"] }, // for ordering events within a thread
+    { kind: "index", columns: ["tid", "kind"] }, // for filtering by thread + kind
+]);
+/**
+ * Migrations table.
+ */
+export const TABLE_MIGRATIONS = defineTable("migrations", {
+    id: text().primaryKey(),
+    applied_at: bigint(),
+});
+/* ---- Record Schemas ---- */
+/**
+ * Thread record schema (zod-first).
+ */
+export const ThreadRecordSchema = z.object({
+    id: z.string(),
+    namespace: z.string(),
+    agent_id: z.string(),
+    model: z.string(), // composite: "provider/modelId"
+    context: z.unknown(), // JSONB - Context<TContext>
+    parent_task_id: z.string().nullable(),
+    tick: z.number().int().nonnegative(),
+    state: z.enum(THREAD_STATES),
+    created_at: z.number().int(),
+    updated_at: z.number().int(),
+    metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+/**
+ * Thread event inner data - stored in JSONB column.
+ *
+ * Always an object (record) for non-system events. Inner data is validated by protocol layer
+ * and is already JSON-serializable. The actual structure depends on the event kind:
+ * - message: {role, content, ...}
+ * - tool-call: {callId, toolId, state, arguments}
+ * - tool-result: {callId, toolId, state, result, error}
+ * - reasoning: {text}
+ * - system: null (handled separately)
+ */
+export const ThreadEventInnerSchema = z.record(z.string(), z.unknown());
+/**
+ * Thread event record base schema - common fields for all events.
+ */
+const ThreadEventRecordBaseSchema = z.object({
+    id: z.string(),
+    tid: z.string(),
+    seq: z.number().int().nonnegative(),
+    timestamp: z.number().int(), // epoch millis
+    metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+/**
+ * Message event record (user, assistant, system messages).
+ */
+const ThreadMessageEventRecordSchema = ThreadEventRecordBaseSchema.extend({
+    kind: z.literal("message"),
+    data: ThreadEventInnerSchema, // Message data: {role, content, ...}
+});
+/**
+ * Reasoning event record.
+ */
+const ThreadReasoningEventRecordSchema = ThreadEventRecordBaseSchema.extend({
+    kind: z.literal("reasoning"),
+    data: ThreadEventInnerSchema, // Reasoning data: {text}
+});
+/**
+ * Tool call event record.
+ */
+const ThreadToolCallEventRecordSchema = ThreadEventRecordBaseSchema.extend({
+    kind: z.literal("tool-call"),
+    data: ThreadEventInnerSchema, // ToolCall data: {callId, toolId, state, arguments}
+});
+/**
+ * Tool result event record.
+ */
+const ThreadToolResultEventRecordSchema = ThreadEventRecordBaseSchema.extend({
+    kind: z.literal("tool-result"),
+    data: ThreadEventInnerSchema, // ToolResult data: {callId, toolId, state, result, error}
+});
+/**
+ * System event record - runtime state changes (not sent to model).
+ */
+const ThreadSystemEventRecordSchema = ThreadEventRecordBaseSchema.extend({
+    kind: z.literal("system"),
+    data: z.null(), // System events have no data
+});
+/**
+ * Thread event record schema (discriminated union by kind).
+ */
+export const ThreadEventRecordSchema = z.discriminatedUnion("kind", [
+    ThreadMessageEventRecordSchema,
+    ThreadReasoningEventRecordSchema,
+    ThreadToolCallEventRecordSchema,
+    ThreadToolResultEventRecordSchema,
+    ThreadSystemEventRecordSchema,
+]);

package/dist/thread/store.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ThreadStore interface is now defined in kernl.
+ * Re-export it here for convenience.
+ */
+export type { ThreadStore } from "kernl";
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/thread/store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC"}

package/dist/thread/store.js

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

package/dist/thread/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Thread storage DTOs are now defined in kernl.
+ * Re-export them here for convenience.
+ */
+export type { NewThread, ThreadUpdate, ThreadFilter, ThreadInclude, SortOrder, ThreadListOptions, ThreadHistoryOptions, } from "kernl";
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/thread/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EACV,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,OAAO,CAAC"}

package/dist/thread/types.js

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

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Core storage abstractions for Kernl.
+ *
+ * Defines the top-level storage interface and transaction primitives.
+ */
+import type { ThreadStore } from "./thread";
+/**
+ * The main storage interface for Kernl.
+ *
+ * Provides access to system stores (threads, tasks, traces) and transaction support.
+ */
+export interface KernlStorage {
+    /**
+     * Thread store - manages thread execution records and event history.
+     */
+    threads: ThreadStore;
+    /**
+     * Initialize the storage backend.
+     *
+     * Connects to the database and ensures all required schemas/tables exist.
+     */
+    init(): Promise<void>;
+    /**
+     * Close the storage backend and cleanup resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Execute a function within a transaction.
+     *
+     * All operations performed using the transaction-scoped stores will be
+     * committed atomically or rolled back on error.
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+}
+/**
+ * Transaction context providing transactional access to stores.
+ */
+export interface Transaction {
+    /**
+     * Thread store within this transaction.
+     */
+    threads: ThreadStore;
+    /**
+     * Commit the transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the transaction.
+     */
+    rollback(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,EAAE,WAAW,CAAC;IAMrB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,OAAO,EAAE,WAAW,CAAC;IAMrB;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core storage abstractions for Kernl.
+ *
+ * Defines the top-level storage interface and transaction primitives.
+ */
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kernl-sdk/storage",
+  "version": "0.1.9",
+  "description": "Core storage abstractions for kernl",
+  "keywords": [
+    "kernl",
+    "storage",
+    "database"
+  ],
+  "author": "dremnik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kernl-sdk/kernl.git",
+    "directory": "packages/storage/core"
+  },
+  "homepage": "https://github.com/kernl-sdk/kernl#readme",
+  "bugs": {
+    "url": "https://github.com/kernl-sdk/kernl/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "tsc-alias": "^1.8.10",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.8"
+  },
+  "dependencies": {
+    "zod": "^4.1.12",
+    "kernl": "0.6.0",
+    "@kernl-sdk/shared": "0.1.5",
+    "@kernl-sdk/protocol": "0.2.4"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "dev": "tsc --watch",
+    "check-types": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:run": "vitest run"
+  }
+}

package/src/__tests__/table.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+import { text, integer, bigint, jsonb } from "../table";
+
+describe("Column codec", () => {
+  describe("text column", () => {
+    it("should encode strings with single quotes", () => {
+      const col = text();
+      expect(col.encode("hello")).toBe("'hello'");
+    });
+
+    it("should escape single quotes", () => {
+      const col = text();
+      expect(col.encode("it's")).toBe("'it''s'");
+      expect(col.encode("'quoted'")).toBe("'''quoted'''");
+    });
+
+    it("should handle NULL values", () => {
+      const col = text();
+      expect(col.encode(null as any)).toBe("NULL");
+      expect(col.encode(undefined as any)).toBe("NULL");
+    });
+
+    it("should decode strings", () => {
+      const col = text();
+      expect(col.decode("hello")).toBe("hello");
+    });
+  });
+
+  describe("integer column", () => {
+    it("should encode numbers as strings", () => {
+      const col = integer();
+      expect(col.encode(42)).toBe("42");
+      expect(col.encode(0)).toBe("0");
+      expect(col.encode(-100)).toBe("-100");
+    });
+
+    it("should handle NULL values", () => {
+      const col = integer();
+      expect(col.encode(null as any)).toBe("NULL");
+      expect(col.encode(undefined as any)).toBe("NULL");
+    });
+
+    it("should decode strings to numbers", () => {
+      const col = integer();
+      expect(col.decode("42")).toBe(42);
+      expect(col.decode("-100")).toBe(-100);
+    });
+  });
+
+  describe("bigint column", () => {
+    it("should encode numbers as strings", () => {
+      const col = bigint();
+      expect(col.encode(9007199254740991)).toBe("9007199254740991");
+      expect(col.encode(0)).toBe("0");
+    });
+
+    it("should handle NULL values", () => {
+      const col = bigint();
+      expect(col.encode(null as any)).toBe("NULL");
+      expect(col.encode(undefined as any)).toBe("NULL");
+    });
+
+    it("should decode strings to numbers", () => {
+      const col = bigint();
+      expect(col.decode("9007199254740991")).toBe(9007199254740991);
+    });
+  });
+
+  describe("jsonb column", () => {
+    it("should encode objects as JSON strings", () => {
+      const col = jsonb();
+      expect(col.encode({ foo: "bar" })).toBe("'{\"foo\":\"bar\"}'");
+    });
+
+    it("should encode arrays", () => {
+      const col = jsonb();
+      expect(col.encode([1, 2, 3])).toBe("'[1,2,3]'");
+    });
+
+    it("should encode nested objects", () => {
+      const col = jsonb();
+      const obj = { user: { name: "Alice", age: 30 } };
+      expect(col.encode(obj)).toBe("'{\"user\":{\"name\":\"Alice\",\"age\":30}}'");
+    });
+
+    it("should handle NULL values", () => {
+      const col = jsonb();
+      expect(col.encode(null as any)).toBe("NULL");
+      expect(col.encode(undefined as any)).toBe("NULL");
+    });
+
+    it("should decode JSON strings to objects", () => {
+      const col = jsonb();
+      expect(col.decode('{"foo":"bar"}')).toEqual({ foo: "bar" });
+    });
+
+    it("should decode JSON arrays", () => {
+      const col = jsonb();
+      expect(col.decode("[1,2,3]")).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe("column builders", () => {
+    it("should support primaryKey()", () => {
+      const col = text().primaryKey();
+      expect(col._pk).toBe(true);
+    });
+
+    it("should support nullable()", () => {
+      const col = text().nullable();
+      expect(col._nullable).toBe(true);
+    });
+
+    it("should support unique()", () => {
+      const col = text().unique();
+      expect(col._unique).toBe(true);
+    });
+
+    it("should support default() with type safety", () => {
+      const textCol = text().default("hello");
+      expect(textCol._default).toBe("hello");
+
+      const intCol = integer().default(42);
+      expect(intCol._default).toBe(42);
+    });
+
+    it("should chain builder methods", () => {
+      const col = text().unique().nullable().default("test");
+      expect(col._unique).toBe(true);
+      expect(col._nullable).toBe(true);
+      expect(col._default).toBe("test");
+    });
+  });
+});

package/src/base.ts

@@ -0,0 +1,5 @@
+/**
+ * Core storage interfaces are now defined in kernl.
+ * Re-export them here for convenience.
+ */
+export type { KernlStorage, Transaction } from "kernl";

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @kernl-sdk/storage - Generic storage abstractions for Kernl
+ */
+
+export * from "./base";
+export * from "./thread";
+export * from "./serde/thread";
+export * from "./table";

package/src/serde/__tests__/thread.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { RUNNING, STOPPED } from "@kernl-sdk/protocol";
+
+import { NewThreadCodec } from "../thread";
+
+describe("NewThreadCodec", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2024-01-01T00:00:00.000Z"));
+  });
+
+  describe("encode", () => {
+    it("should apply default values (tick=0, state='stopped')", () => {
+      const newThread = {
+        id: "thread-1",
+        namespace: "kernl",
+        agentId: "agent-1",
+        model: "openai/gpt-4",
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.tick).toBe(0);
+      expect(record.state).toBe("stopped");
+      expect(record.parent_task_id).toBeNull();
+      expect(record.metadata).toBeNull();
+    });
+
+    it("should preserve provided values", () => {
+      const newThread = {
+        id: "thread-2",
+        namespace: "kernl",
+        agentId: "agent-2",
+        model: "openai/gpt-4",
+        tick: 5,
+        state: RUNNING as any,
+        metadata: { key: "value" },
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.tick).toBe(5);
+      expect(record.state).toBe(RUNNING);
+      expect(record.metadata).toEqual({ key: "value" });
+    });
+
+    it("should apply current timestamp when not provided", () => {
+      const now = Date.now(); // Mocked to 2024-01-01T00:00:00.000Z
+
+      const newThread = {
+        id: "thread-3",
+        namespace: "kernl",
+        agentId: "agent-3",
+        model: "anthropic/claude-3",
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.created_at).toBe(now);
+      expect(record.updated_at).toBe(now);
+    });
+
+    it("should preserve provided timestamps", () => {
+      const createdAt = new Date("2023-12-01T00:00:00.000Z");
+      const updatedAt = new Date("2023-12-15T00:00:00.000Z");
+
+      const newThread = {
+        id: "thread-4",
+        namespace: "kernl",
+        agentId: "agent-4",
+        model: "openai/gpt-4",
+        createdAt,
+        updatedAt,
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.created_at).toBe(createdAt.getTime());
+      expect(record.updated_at).toBe(updatedAt.getTime());
+    });
+
+    it("should handle context", () => {
+      const context = { foo: "bar", nested: { key: "value" } };
+
+      const newThread = {
+        id: "thread-5",
+        namespace: "kernl",
+        agentId: "agent-5",
+        model: "openai/gpt-4",
+        context: context as any,
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.context).toEqual(context);
+    });
+
+    it("should apply empty object as default context", () => {
+      const newThread = {
+        id: "thread-6",
+        namespace: "kernl",
+        agentId: "agent-6",
+        model: "openai/gpt-4",
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.context).toEqual({});
+    });
+
+    it("should map model field correctly", () => {
+      const newThread = {
+        id: "thread-7",
+        namespace: "kernl",
+        agentId: "agent-7",
+        model: "provider/model-name",
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.model).toBe("provider/model-name");
+    });
+
+    it("should handle parentTaskId", () => {
+      const newThread = {
+        id: "thread-8",
+        namespace: "kernl",
+        agentId: "agent-8",
+        model: "openai/gpt-4",
+        parentTaskId: "task-123",
+      };
+
+      const record = NewThreadCodec.encode(newThread);
+
+      expect(record.parent_task_id).toBe("task-123");
+    });
+  });
+
+  describe("decode", () => {
+    it("should decode ThreadRecord to NewThread", () => {
+      const record = {
+        id: "thread-1",
+        namespace: "kernl",
+        agent_id: "agent-1",
+        model: "openai/gpt-4",
+        context: { foo: "bar" },
+        tick: 5,
+        state: RUNNING as any,
+        parent_task_id: "task-1",
+        metadata: { key: "value" },
+        created_at: 1704067200000, // 2024-01-01T00:00:00.000Z
+        updated_at: 1704070800000, // 2024-01-01T01:00:00.000Z
+      };
+
+      const newThread = NewThreadCodec.decode(record);
+
+      expect(newThread.id).toBe("thread-1");
+      expect(newThread.agentId).toBe("agent-1");
+      expect(newThread.model).toBe("openai/gpt-4");
+      expect(newThread.context).toEqual({ foo: "bar" });
+      expect(newThread.tick).toBe(5);
+      expect(newThread.state).toBe(RUNNING);
+      expect(newThread.parentTaskId).toBe("task-1");
+      expect(newThread.metadata).toEqual({ key: "value" });
+      expect(newThread.createdAt).toEqual(new Date(1704067200000));
+      expect(newThread.updatedAt).toEqual(new Date(1704070800000));
+    });
+
+    it("should handle null values", () => {
+      const record = {
+        id: "thread-2",
+        namespace: "kernl",
+        agent_id: "agent-2",
+        model: "openai/gpt-4",
+        context: {},
+        tick: 0,
+        state: STOPPED as any,
+        parent_task_id: null,
+        metadata: null,
+        created_at: 1704067200000,
+        updated_at: 1704067200000,
+      };
+
+      const newThread = NewThreadCodec.decode(record);
+
+      expect(newThread.parentTaskId).toBeNull();
+      expect(newThread.metadata).toBeNull();
+    });
+  });
+
+  describe("round-trip encoding/decoding", () => {
+    it("should preserve data through encode -> decode cycle", () => {
+      const original = {
+        id: "thread-rt",
+        namespace: "kernl",
+        agentId: "agent-rt",
+        model: "openai/gpt-4",
+        tick: 10,
+        state: RUNNING as any,
+        context: { test: true } as any,
+        parentTaskId: "task-rt",
+        metadata: { source: "test" },
+      };
+
+      const encoded = NewThreadCodec.encode(original);
+      const decoded = NewThreadCodec.decode(encoded);
+
+      expect(decoded.id).toBe(original.id);
+      expect(decoded.agentId).toBe(original.agentId);
+      expect(decoded.model).toBe(original.model);
+      expect(decoded.tick).toBe(original.tick);
+      expect(decoded.state).toBe(original.state);
+      expect(decoded.context).toEqual(original.context);
+      expect(decoded.parentTaskId).toBe(original.parentTaskId);
+      expect(decoded.metadata).toEqual(original.metadata);
+    });
+  });
+});