@kernl-sdk/storage 0.1.9

package/src/serde/thread.ts

@@ -0,0 +1,178 @@
+/**
+ * Thread serialization - codecs for converting between domain types and database records.
+ */
+
+import { type Codec, neapolitanCodec } from "@kernl-sdk/shared/lib";
+import type { IThread, ThreadEvent } from "kernl/internal";
+import { STOPPED } from "@kernl-sdk/protocol";
+
+import type { ThreadRecord, ThreadEventRecord } from "@/thread/schema";
+import { ThreadRecordSchema, ThreadEventRecordSchema } from "@/thread/schema";
+import type { NewThread } from "@/thread/types";
+
+/**
+ * Decoded thread record - validated but not hydrated.
+ *
+ * Has all IThread fields except:
+ * - agent/model are replaced with agentId/model (string references)
+ * - input/history/task are not included (loaded separately, task becomes parentTaskId)
+ * - context is raw JSONB data (needs reconstruction into Context instance)
+ */
+export type DecodedThread = Omit<
+  IThread,
+  "agent" | "model" | "input" | "history" | "task" | "context"
+> & {
+  namespace: string;
+  agentId: string;
+  model: string; // composite: "provider/modelId"
+  parentTaskId: string | null; // stored task reference
+  context: unknown; // raw JSONB - reconstruct with new Context(data)
+};
+
+/* ---- Codecs ---- */
+
+/**
+ * Thread codec - converts between DecodedThread and ThreadRecord.
+ */
+const rawThreadCodec: Codec<DecodedThread, ThreadRecord> = {
+  encode(decoded: DecodedThread): ThreadRecord {
+    return {
+      id: decoded.tid,
+      namespace: decoded.namespace,
+      agent_id: decoded.agentId,
+      model: decoded.model,
+      parent_task_id: decoded.parentTaskId,
+      context: decoded.context,
+      tick: decoded.tick,
+      state: decoded.state,
+      created_at: decoded.createdAt.getTime(),
+      updated_at: decoded.updatedAt.getTime(),
+      metadata: decoded.metadata,
+    };
+  },
+
+  decode(record: ThreadRecord): DecodedThread {
+    return {
+      tid: record.id,
+      namespace: record.namespace,
+      agentId: record.agent_id,
+      model: record.model,
+      parentTaskId: record.parent_task_id,
+      context: record.context,
+      tick: record.tick,
+      state: record.state,
+      createdAt: new Date(record.created_at),
+      updatedAt: new Date(record.updated_at),
+      metadata: record.metadata,
+    };
+  },
+};
+
+export const ThreadCodec = neapolitanCodec({
+  codec: rawThreadCodec,
+  schema: ThreadRecordSchema,
+});
+
+/**
+ * ThreadEvent codec - converts between flat ThreadEvent and ThreadEventRecord.
+ *
+ * App layer: {kind, ...dataFields, id, tid, seq, timestamp, metadata}
+ * DB layer:  {kind, data: {...dataFields}, id, tid, seq, timestamp, metadata}
+ */
+const rawThreadEventCodec: Codec<ThreadEvent, ThreadEventRecord> = {
+  encode(event: ThreadEvent): ThreadEventRecord {
+    const base = {
+      id: event.id,
+      tid: event.tid,
+      seq: event.seq,
+      timestamp: event.timestamp.getTime(),
+      metadata: event.metadata ?? null,
+    };
+
+    // System events have no data
+    if (event.kind === "system") {
+      return { ...base, kind: "system", data: null };
+    }
+
+    // Extract data (everything except base fields and kind)
+    const { id, tid, seq, timestamp, metadata, kind, ...data } = event as any;
+
+    return {
+      ...base,
+      kind: event.kind,
+      data,
+    };
+  },
+
+  decode(record: ThreadEventRecord): ThreadEvent {
+    const base = {
+      id: record.id,
+      tid: record.tid,
+      seq: record.seq,
+      timestamp: new Date(record.timestamp),
+      metadata: record.metadata ?? {},
+    };
+
+    // System events have no data
+    if (record.kind === "system") {
+      return { ...base, kind: "system" };
+    }
+
+    // For non-system events, data is always a record (enforced by schema)
+    return {
+      ...base,
+      kind: record.kind,
+      ...record.data,
+    } as ThreadEvent;
+  },
+};
+
+export const ThreadEventRecordCodec = neapolitanCodec({
+  codec: rawThreadEventCodec,
+  schema: ThreadEventRecordSchema,
+});
+
+/**
+ * NewThread codec - converts NewThread input to ThreadRecord for insertion.
+ *
+ * Handles default values at encoding time (tick=0, state="stopped", timestamps=now).
+ */
+const rawNewThreadCodec: Codec<NewThread, ThreadRecord> = {
+  encode(thread: NewThread): ThreadRecord {
+    const now = Date.now();
+    return {
+      id: thread.id,
+      namespace: thread.namespace,
+      agent_id: thread.agentId,
+      model: thread.model,
+      context: thread.context ?? {},
+      tick: thread.tick ?? 0,
+      state: thread.state ?? STOPPED,
+      parent_task_id: thread.parentTaskId ?? null,
+      metadata: thread.metadata ?? null,
+      created_at: thread.createdAt?.getTime() ?? now,
+      updated_at: thread.updatedAt?.getTime() ?? now,
+    };
+  },
+
+  decode(record: ThreadRecord): NewThread {
+    return {
+      id: record.id,
+      namespace: record.namespace,
+      agentId: record.agent_id,
+      model: record.model,
+      context: record.context,
+      tick: record.tick,
+      state: record.state,
+      parentTaskId: record.parent_task_id,
+      metadata: record.metadata,
+      createdAt: new Date(record.created_at),
+      updatedAt: new Date(record.updated_at),
+    };
+  },
+};
+
+export const NewThreadCodec = neapolitanCodec({
+  codec: rawNewThreadCodec,
+  schema: ThreadRecordSchema,
+});

package/src/table.ts

@@ -0,0 +1,199 @@
+/**
+ * Schema name for all kernl tables.
+ */
+export const SCHEMA_NAME = "kernl";
+
+/**
+ * Table definition with name, columns, and optional constraints.
+ */
+export interface Table<
+  Name extends string,
+  Cols extends Record<string, Column>,
+> {
+  name: Name;
+  columns: Cols;
+  constraints?: TableConstraint[];
+}
+
+/**
+ * Define a table with name, columns, and optional constraints.
+ */
+export function defineTable<
+  const Name extends string,
+  const Cols extends Record<string, Column>,
+>(
+  name: Name,
+  columns: Cols,
+  constraints?: TableConstraint[],
+): Table<Name, Cols> {
+  // set table/column metadata on each column for FK resolution
+  for (const cname in columns) {
+    columns[cname]._table = name;
+    columns[cname]._column = cname;
+  }
+
+  return { name, columns, constraints };
+}
+
+/* ---- Column Types ---- */
+
+export type ColumnType = "text" | "integer" | "bigint" | "jsonb";
+export type OnDeleteAction = "CASCADE" | "SET NULL" | "RESTRICT";
+
+/**
+ * Column definition with type and constraints.
+ */
+export interface Column<T = unknown> {
+  type: ColumnType;
+
+  _table?: string;
+  _column?: string;
+
+  // Constraints
+  _pk?: boolean;
+  _nullable?: boolean;
+  _unique?: boolean;
+  _default?: T;
+  _fk?: {
+    table: string;
+    column: string;
+  };
+  _onDelete?: OnDeleteAction;
+
+  // -- builders --
+  primaryKey(): Column<T>;
+  nullable(): Column<T>;
+  default(val: T): Column<T>;
+  unique(): Column<T>;
+  references(
+    ref: () => Column,
+    opts?: { onDelete?: OnDeleteAction },
+  ): Column<T>;
+
+  // -- codec --
+  encode(val: T): string;
+  decode(val: string): T;
+}
+
+export const text = (): Column<string> => col("text");
+export const integer = (): Column<number> => col("integer");
+export const bigint = (): Column<number> => col("bigint");
+export const jsonb = <T = unknown>(): Column<T> => col("jsonb");
+
+export const timestamps = {
+  created_at: bigint(),
+  updated_at: bigint(),
+};
+
+function col<T>(type: ColumnType): Column<T> {
+  const c: Column<T> = {
+    type,
+
+    primaryKey() {
+      this._pk = true;
+      return this;
+    },
+
+    nullable() {
+      this._nullable = true;
+      return this;
+    },
+
+    default(val) {
+      this._default = val;
+      return this;
+    },
+
+    unique() {
+      this._unique = true;
+      return this;
+    },
+
+    references(ref, opts) {
+      const targetCol = ref();
+      if (targetCol._table && targetCol._column) {
+        this._fk = {
+          table: targetCol._table,
+          column: targetCol._column,
+        };
+      }
+      this._onDelete = opts?.onDelete;
+      return this;
+    },
+
+    encode(val: T): string {
+      if (val === null || val === undefined) return "NULL";
+
+      switch (this.type) {
+        case "text":
+          return `'${String(val).replace(/'/g, "''")}'`;
+        case "integer":
+        case "bigint":
+          return String(val);
+        case "jsonb":
+          return `'${JSON.stringify(val)}'`;
+      }
+    },
+
+    decode(val: string): T {
+      switch (this.type) {
+        case "text":
+          return val as T;
+        case "integer":
+        case "bigint":
+          return Number.parseInt(val, 10) as T;
+        case "jsonb":
+          return JSON.parse(val) as T;
+      }
+    },
+  };
+
+  return c;
+}
+
+/* ---- Constraints ---- */
+
+/**
+ * Table-level constraint types.
+ */
+export type TableConstraint =
+  | UniqueConstraint
+  | PrimaryKeyConstraint
+  | ForeignKeyConstraint
+  | CheckConstraint
+  | IndexConstraint;
+
+export interface UniqueConstraint {
+  readonly kind: "unique";
+  columns: string[];
+  name?: string; // optional constraint name
+}
+
+export interface IndexConstraint {
+  readonly kind: "index";
+  columns: string[];
+  unique?: boolean;
+}
+
+export interface PrimaryKeyConstraint {
+  readonly kind: "pkey";
+  columns: string[];
+  name?: string;
+}
+
+export interface ForeignKeyConstraint {
+  readonly kind: "fkey";
+  columns: string[];
+  references: {
+    table: string;
+    columns: string[];
+  };
+  onDelete?: OnDeleteAction;
+  name?: string;
+}
+
+export interface CheckConstraint {
+  readonly kind: "check";
+  expression: string;
+  name?: string;
+}

package/src/thread/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Thread storage types and utilities.
+ */
+
+export * from "./types";
+export * from "./store";
+export * from "./schema";

package/src/thread/schema.ts

@@ -0,0 +1,170 @@
+/**
+ * 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(),
+});
+
+export type ThreadRecord = z.infer<typeof ThreadRecordSchema>;
+
+/**
+ * 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());
+
+export type ThreadEventInner = z.infer<typeof ThreadEventInnerSchema>;
+
+/**
+ * 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,
+]);
+
+export type ThreadEventRecord = z.infer<typeof ThreadEventRecordSchema>;

package/src/thread/store.ts

@@ -0,0 +1,5 @@
+/**
+ * ThreadStore interface is now defined in kernl.
+ * Re-export it here for convenience.
+ */
+export type { ThreadStore } from "kernl";

package/src/thread/types.ts

@@ -0,0 +1,13 @@
+/**
+ * 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";

package/src/types.ts

@@ -0,0 +1,67 @@
+/**
+ * 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;
+
+  // Future stores (deferred)
+  // tasks: TaskStore;
+  // traces: TraceStore;
+
+  /**
+   * 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;
+
+  // Future stores (deferred)
+  // tasks: TaskStore;
+  // traces: TraceStore;
+
+  /**
+   * Commit the transaction.
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rollback the transaction.
+   */
+  rollback(): Promise<void>;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "kernl": ["../kernl/src/index.ts"],
+      "kernl/internal": ["../kernl/src/internal.ts"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+import path from "node:path";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    exclude: ["**/node_modules/**", "**/dist/**"],
+  },
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+});