@kortyx/runtime 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.19.0](https://github.com/kortyx-io/kortyx/compare/runtime-v0.18.0...runtime-v0.19.0) (2026-09-16)
+
+
+### Features
+
+* **runtime:** add PostgreSQL persistence, caching composition, and retention ([#207](https://github.com/kortyx-io/kortyx/issues/207)) ([6c1e7df](https://github.com/kortyx-io/kortyx/commit/6c1e7df22ffe8c792bf52b7dba5ae6ea04c1eb2a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/hooks bumped to 0.25.3
+
 ## [0.18.0](https://github.com/kortyx-io/kortyx/compare/runtime-v0.17.2...runtime-v0.18.0) (2026-09-16)
 
 

package/README.md

@@ -27,6 +27,7 @@ npm install @kortyx/runtime
 - `getRegisteredNode(...)`
 - `createInMemoryFrameworkAdapter(...)`
 - `createRedisFrameworkAdapter(...)`
+- `createPostgresFrameworkAdapter(...)`
 - `createFrameworkAdapterFromEnv(...)`
 
 ## Persistence
@@ -51,3 +52,53 @@ export const framework = createRedisFrameworkAdapter({
 ## License
 
 Apache-2.0. See [LICENSE](https://github.com/kortyx-io/kortyx/blob/main/LICENSE).
+
+## PostgreSQL and retention
+
+Use `createPostgresFrameworkAdapter` for durable runtime history. PostgreSQL is authoritative. Optionally attach a Redis adapter as a checkpoint payload cache with `createCachingFrameworkAdapter({ storage, cache })`.
+
+```ts
+import {
+  createPostgresFrameworkAdapter,
+  createRedisFrameworkAdapter,
+  createCachingFrameworkAdapter,
+} from "kortyx";
+
+const storage = createPostgresFrameworkAdapter({
+  connectionString: process.env.KORTYX_POSTGRES_URL!,
+  namespace: "my-app",
+  ttlMs: 7 * 24 * 60 * 60 * 1000, // Approval lifetime, independent of history.
+  retention: { checkpointHistoryDays: 30, inactiveSessionDays: 30 },
+});
+
+// Optional Redis payload caching; omit the helper to use storage alone.
+const cache = createRedisFrameworkAdapter({
+  url: process.env.REDIS_URL!,
+  ttlMs: 15 * 60 * 1000,
+});
+const persistence = createCachingFrameworkAdapter({ storage, cache, timeoutMs: 25 });
+
+// Run during deployment before serving requests.
+await persistence.maintenance.setup();
+
+// Pass persistence as createAgent({ workflows, frameworkAdapter: persistence }).
+// Your scheduled job/worker performs storage maintenance:
+const result = await persistence.maintenance.prune({ batchSize: 500 });
+
+// After in-flight executions finish, close owned connections on shutdown.
+await persistence.close();
+```
+
+History and inactive sessions default to 30 days, without a 50-checkpoint cap. Interrupts default to 15 minutes; set `ttlMs` explicitly for longer pauses. Current session heads, unexpired pauses, and executing runs are protected. Rollback preserves abandoned branches until retention expires. Reads enforce expiry even before cleanup runs. The app owns scheduling; Kortyx owns safe, bounded pruning.
+
+`KORTYX_POSTGRES_URL` takes precedence over Redis during env-based selection, with Redis used as a cache when configured. `DATABASE_URL` is not used implicitly. Call `maintenance.setup()` before traffic for every built-in adapter; PostgreSQL creates its schema, while Redis and memory need no schema. `maintenance.prune()` and `close()` are also available on every built-in adapter.
+
+PostgreSQL setup applies the SDK's numbered SQL migrations in order, using the existing PostgreSQL client. Each migration commits its changes and version together under a schema lock; reruns skip applied versions. Failed migrations roll back and stop setup, while earlier successful migrations remain committed. Retries resume at the first unapplied version. Newer schemas and gaps in recorded history are rejected. Migrations run only through explicit setup, never in request handlers. Released migrations are immutable; future schema changes add a consecutive migration. Applied SQL is verified against a stored SHA-256 checksum; editing it causes setup to reject. Migration advisory and DDL lock waits are capped at five seconds, preserving stricter database settings; a timeout rolls back that migration and requires retry. This bounds lock acquisition, not migration execution time. The original version-only v1 ledger adopts the current v1 checksum once, without rerunning schema SQL; its prior contents cannot be verified retroactively. Use compatible additive changes during rolling deployments; no automatic down migrations or workflow-state conversions are provided.
+
+Existing factories remain supported. Their shared `ManagedFrameworkAdapter` lifecycle contract requires implementations for every built-in backend; existing custom `FrameworkAdapter` implementations remain compatible. Redis prune reports zero explicit deletions because native TTL owns expiry. Memory prune removes expired approvals in bounded batches; its session history remains count-limited.
+
+Configure the caching helper before traffic. It returns the exact storage adapter and preserves all current/future methods. Currently PostgreSQL storage with Redis caching is supported; unsupported combinations, repeated bindings, and sharing an already-owned cache are rejected. Cache `ttlMs` comes from the Redis adapter; approval `ttlMs` comes from PostgreSQL. The returned adapter owns both connections: close it after executions finish and do not independently use its cache input as another storage backend. Cache keys are separate from standalone Redis runtime keys. Data transfer between storage backends is outside this contract.
+
+Run real-service integration coverage with `KORTYX_TEST_POSTGRES_URL=... KORTYX_TEST_REDIS_URL=... pnpm --filter @kortyx/runtime test:integration:postgres`. Use a disposable test database. Redis is optional for these tests.
+
+Graph checkpoints are saved asynchronously while tokens stream; cache fills do not block authoritative reads. Cache operations default to a 25 ms budget, and cache failures bypass Redis for five seconds. Required PostgreSQL reads and durable acknowledgements still add latency. After building the SDK, compare persistence overhead using an immediate mock model with `KORTYX_TEST_POSTGRES_URL=... KORTYX_TEST_REDIS_URL=... node scripts/benchmark-runtime-persistence.cjs` from the repository root. The benchmark reports generation start, first token, and execution completion at p50/p95; use disposable services and measure production network conditions separately.

package/dist/index.d.ts

@@ -1,12 +1,38 @@
-import { BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import { BaseCheckpointSaver, CheckpointTuple, CheckpointListOptions, Checkpoint, CheckpointMetadata, PendingWrite } from '@langchain/langgraph-checkpoint';
 import * as _kortyx_core from '@kortyx/core';
 import { GraphState, WorkflowDefinition, NodeFn, RuntimeEnvelope } from '@kortyx/core';
+import { RunnableConfig } from '@langchain/core/runnables';
+import postgres from 'postgres';
 import * as _kortyx_hooks from '@kortyx/hooks';
 import { ReasonTraceAdapter, KortyxTelemetryConfig } from '@kortyx/hooks';
 import { GetProviderFn } from '@kortyx/providers';
 
 declare function getCheckpointer(key: string): BaseCheckpointSaver;
 
+type PruneRuntimeOptions = {
+    /** Defaults to wall-clock time; future timestamps are rejected. */
+    now?: Date;
+    /** Maximum parent records removed per table. Default: 500, maximum: 1000. */
+    batchSize?: number;
+};
+type PruneRuntimeResult = {
+    skipped: boolean;
+    hasMore: boolean;
+    deleted: {
+        pendingRequests: number;
+        sessionCheckpoints: number;
+        graphCheckpoints: number;
+        sessions: number;
+        runs: number;
+    };
+};
+type RuntimeMaintenance = {
+    /** Explicit, idempotent backend setup. Complete before serving requests. */
+    setup: () => Promise<void>;
+    /** App-scheduled cleanup. Redis uses native TTL; memory uses lazy expiry/count limits. */
+    prune: (options?: PruneRuntimeOptions) => Promise<PruneRuntimeResult>;
+};
+
 /** A self-contained, JSON snapshot, including pending writes needed for replay. */
 type GraphSnapshotBundle = CheckpointTuple;
 declare function captureGraphSnapshot(saver: BaseCheckpointSaver, threadId: string, checkpointId?: string): Promise<GraphSnapshotBundle | undefined>;
@@ -60,7 +86,108 @@ interface PendingRequestStore {
     delete: (token: string) => Promise<void>;
     update: (token: string, patch: Partial<PendingRequestRecord>) => Promise<void>;
 }
-declare function createInMemoryPendingRequestStore(): PendingRequestStore;
+declare function createInMemoryPendingRequestStore(): PendingRequestStore & {
+    pruneExpired: (now: number, batchSize: number) => number;
+};
+
+/** Internal cache capability. It is separate from authoritative framework stores. */
+type FrameworkPayloadCache = {
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, ttlMs: number) => Promise<void>;
+    close?: () => Promise<void>;
+};
+type CreateCachingFrameworkAdapterOptions<T extends ManagedFrameworkAdapter = ManagedFrameworkAdapter> = {
+    /** Authoritative storage. Currently supports the PostgreSQL adapter. */
+    storage: T;
+    /** Payload cache provider. Currently supports the Redis adapter. */
+    cache: FrameworkAdapter;
+    /** Cache operation budget. Default: 25 ms, maximum: 1000 ms. */
+    timeoutMs?: number;
+};
+/** Attaches caching to storage before traffic, preserving every storage method and its identity.
+ * The returned adapter owns shutdown of both inputs. Do not use the cache input as another storage backend.
+ */
+declare function createCachingFrameworkAdapter<T extends ManagedFrameworkAdapter>(options: CreateCachingFrameworkAdapterOptions<T>): T;
+
+type RedisFrameworkStore = {
+    close?: () => Promise<void>;
+    list?: (prefix: string) => Promise<string[]>;
+    take?: (key: string) => Promise<string | null>;
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, ttlMs: number) => Promise<void>;
+    del: (key: string) => Promise<void>;
+    hset: (key: string, field: string, value: string) => Promise<void>;
+    hsetnx: (key: string, field: string, value: string) => Promise<number>;
+    hgetall: (key: string) => Promise<Record<string, string>>;
+    expire: (key: string, ttlMs: number) => Promise<void>;
+    scanKeys: (prefix: string) => Promise<string[]>;
+    delRaw: (keys: string[]) => Promise<void>;
+};
+
+type RuntimeSql = postgres.Sql | postgres.TransactionSql;
+type RuntimeRetentionPolicy = {
+    /** Rolling history window. The current head and live runs are protected. Default: 30. */
+    checkpointHistoryDays?: number;
+    /** Inactivity window for a session. Unexpired interrupts and live runs protect it. Default: 30. */
+    inactiveSessionDays?: number;
+};
+/** Internal relational storage. Redis never controls visibility or token consumption. */
+declare class PostgresRuntimeStore {
+    private cache?;
+    private cacheTtlMs;
+    private cacheTimeoutMs;
+    readonly sql: postgres.Sql;
+    readonly scope: string;
+    readonly historyMs: number;
+    readonly sessionMs: number;
+    private readonly cachePrefix;
+    private cacheRetryAfter;
+    private cacheClosed;
+    private readonly cachePopulations;
+    constructor(connectionString: string, namespace: string, retention: RuntimeRetentionPolicy, cache?: Pick<RedisFrameworkStore, "get" | "set" | "close">, cacheTtlMs?: number, cacheTimeoutMs?: number);
+    get cacheEnabled(): boolean;
+    attachCache(cache: FrameworkPayloadCache, ttlMs: number, timeoutMs: number): void;
+    setup(): Promise<void>;
+    query<T>(query: PromiseLike<T>): Promise<T>;
+    transaction<T>(operation: (sql: postgres.TransactionSql) => Promise<T>): Promise<T>;
+    liveSession(sql: RuntimeSql, now: number): postgres.PendingQuery<postgres.Row[]>;
+    liveCheckpoint(sql: RuntimeSql, now: number): postgres.PendingQuery<postgres.Row[]>;
+    liveRun(sql: RuntimeSql, now: number): postgres.PendingQuery<postgres.Row[]>;
+    touchRun(sql: postgres.TransactionSql, runId: string): Promise<void>;
+    touchSession(sql: postgres.TransactionSql, sessionId: string): Promise<void>;
+    payload<T>(key: unknown[], load: () => Promise<T>): Promise<T>;
+    private cacheCall;
+    close(): Promise<void>;
+}
+
+/** Kortyx-owned checkpoint format and relational persistence, independent of LangGraph saver packages. */
+declare class PostgresCheckpointSaver extends BaseCheckpointSaver {
+    private readonly store;
+    constructor(store: PostgresRuntimeStore);
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: Record<string, number | string>): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    deleteThread(runId: string): Promise<void>;
+    deleteCheckpointWrites(runId: string, ns: string, id: string): Promise<void>;
+    getLatestCheckpointId(runId: string, ns?: string): Promise<string | undefined>;
+}
+
+type CreatePostgresFrameworkAdapterOptions = {
+    connectionString: string;
+    /** Isolates applications sharing the runtime tables. Default: "default". */
+    namespace?: string;
+    /** Interrupt lifetime, independent of checkpoint retention. Default: 15 minutes. */
+    ttlMs?: number;
+    retention?: RuntimeRetentionPolicy;
+};
+type PostgresFrameworkAdapter = ManagedFrameworkAdapter & {
+    kind: "postgres";
+    checkpointer: PostgresCheckpointSaver;
+    /** Closes owned connections. Call after in-flight executions have completed. */
+    close: () => Promise<void>;
+};
+declare function createPostgresFrameworkAdapter(options: CreatePostgresFrameworkAdapterOptions): PostgresFrameworkAdapter;
 
 type CheckpointId = string;
 type CheckpointSummary = {
@@ -76,6 +203,8 @@ type CheckpointSummary = {
     forkedFrom?: string;
     workflowVersion?: string;
     buildId?: string;
+    /** PostgreSQL retains abandoned branches until their history window expires. */
+    branchStatus?: "active" | "abandoned";
 };
 type SessionCheckpointRecord = CheckpointSummary & {
     runId: string;
@@ -114,13 +243,18 @@ type ForkSessionCheckpointResult = {
     checkpoint: SessionCheckpointRecord;
 };
 type SessionCheckpointStore = {
+    /** The store publishes pending requests in the same transaction as the session transition. */
+    managesPendingRequests?: boolean;
     list: (sessionId: string) => Promise<CheckpointSummary[]>;
     get: (id: CheckpointId) => Promise<SessionCheckpointRecord | null>;
     getHead: (sessionId: string) => Promise<SessionCheckpointRecord | null>;
     append: (args: AppendSessionCheckpointArgs) => Promise<SessionCheckpointRecord>;
-    rollbackTo: (id: CheckpointId) => Promise<RollbackSessionCheckpointResult>;
+    rollbackTo: (id: CheckpointId, options?: {
+        preparePendingRequests?: (requests: PendingRequestRecord[]) => void;
+    }) => Promise<RollbackSessionCheckpointResult>;
     fork: (id: CheckpointId, options?: {
         newSessionId?: string;
+        preparePendingRequests?: (requests: PendingRequestRecord[]) => void;
     }) => Promise<ForkSessionCheckpointResult>;
 };
 type SessionCheckpointStoreOptions = {
@@ -129,30 +263,50 @@ type SessionCheckpointStoreOptions = {
 declare function createInMemorySessionCheckpointStore(options?: SessionCheckpointStoreOptions): SessionCheckpointStore;
 
 type FrameworkAdapter = {
-    kind: "in-memory" | "redis";
+    kind: "in-memory" | "redis" | "postgres";
     pendingRequests: PendingRequestStore;
     sessionCheckpoints: SessionCheckpointStore;
     checkpointer: BaseCheckpointSaver;
     ttlMs: number;
+    /** Optional for legacy custom adapters; required on every built-in adapter. */
+    maintenance?: RuntimeMaintenance;
+    /** Optional for legacy custom adapters; closes owned connections. */
+    close?: () => Promise<void>;
+    /** Protects execution from concurrent retention cleanup. Released after the entire outcome is persisted. */
+    acquireRunLease?: (args: {
+        runId: string;
+        sessionId?: string;
+        onLost: (cause: unknown) => void;
+    }) => Promise<() => Promise<void>>;
     /**
      * Best-effort cleanup for ephemeral framework state for a single run.
      * Called when a workflow completes without pausing for an interrupt.
      */
     cleanupRun?: (runId: string, namespaces: string[]) => Promise<void>;
 };
+/** Shared lifecycle contract implemented by every built-in adapter.
+ * FrameworkAdapter remains available for existing custom implementations.
+ */
+type ManagedFrameworkAdapter = FrameworkAdapter & {
+    maintenance: RuntimeMaintenance;
+    /** Close owned connections after in-flight executions finish. */
+    close: () => Promise<void>;
+};
 type CreateInMemoryFrameworkAdapterOptions = {
     ttlMs?: number;
     maxSessionCheckpoints?: number;
 };
-declare function createInMemoryFrameworkAdapter(options?: CreateInMemoryFrameworkAdapterOptions): FrameworkAdapter;
+declare function createInMemoryFrameworkAdapter(options?: CreateInMemoryFrameworkAdapterOptions): ManagedFrameworkAdapter;
 type CreateRedisFrameworkAdapterOptions = {
     url: string;
     ttlMs?: number;
     prefix?: string;
     maxSessionCheckpoints?: number;
 };
-declare function createRedisFrameworkAdapter(options: CreateRedisFrameworkAdapterOptions): FrameworkAdapter;
-declare function createFrameworkAdapterFromEnv(env?: Record<string, string | undefined>): FrameworkAdapter;
+declare function createRedisFrameworkAdapter(options: CreateRedisFrameworkAdapterOptions): ManagedFrameworkAdapter;
+declare function createFrameworkAdapterFromEnv(env?: Record<string, string | undefined>): (ManagedFrameworkAdapter & {
+    kind: "in-memory" | "redis";
+}) | PostgresFrameworkAdapter;
 
 interface CompiledGraphBase {
     invoke(state: unknown, options?: Record<string, unknown>): Promise<unknown>;
@@ -236,4 +390,4 @@ interface InitialStateArgs<Config = unknown> {
 }
 declare function buildInitialGraphState<Config>({ input, runtime, config, defaultWorkflowId, }: InitialStateArgs<Config>): Promise<GraphState>;
 
-export { type AppendSessionCheckpointArgs, type CheckpointId, type CheckpointSummary, type CreateInMemoryFrameworkAdapterOptions, type CreateRedisFrameworkAdapterOptions, type ExecutionControl, type ExecutionRuntimeConfig, type FileWorkflowRegistryOptions, type ForkSessionCheckpointResult, type FrameworkAdapter, type GraphSnapshotBundle, type HumanInputKind, type HumanInputOption, type InitialStateArgs, type PendingRequestRecord, type PendingRequestStore, type RollbackSessionCheckpointResult, type SessionCheckpointRecord, type SessionCheckpointStore, type SessionCheckpointStoreOptions, type WorkflowRegistry, buildInitialGraphState, captureGraphSnapshot, clearRegisteredNodes, createExecutionGraph, createFileWorkflowRegistry, createFrameworkAdapterFromEnv, createInMemoryFrameworkAdapter, createInMemoryPendingRequestStore, createInMemorySessionCheckpointStore, createInMemoryWorkflowRegistry, createRedisFrameworkAdapter, getCheckpointer, getRegisteredNode, listRegisteredNodes, makeRequestId, makeResumeToken, registerNode, resolveNode, restoreGraphSnapshot };
+export { type AppendSessionCheckpointArgs, type CheckpointId, type CheckpointSummary, type CreateCachingFrameworkAdapterOptions, type CreateInMemoryFrameworkAdapterOptions, type CreatePostgresFrameworkAdapterOptions, type CreateRedisFrameworkAdapterOptions, type ExecutionControl, type ExecutionRuntimeConfig, type FileWorkflowRegistryOptions, type ForkSessionCheckpointResult, type FrameworkAdapter, type GraphSnapshotBundle, type HumanInputKind, type HumanInputOption, type InitialStateArgs, type ManagedFrameworkAdapter, type PendingRequestRecord, type PendingRequestStore, type PostgresFrameworkAdapter, type PruneRuntimeOptions, type PruneRuntimeResult, type RollbackSessionCheckpointResult, type RuntimeMaintenance, type RuntimeRetentionPolicy, type SessionCheckpointRecord, type SessionCheckpointStore, type SessionCheckpointStoreOptions, type WorkflowRegistry, buildInitialGraphState, captureGraphSnapshot, clearRegisteredNodes, createCachingFrameworkAdapter, createExecutionGraph, createFileWorkflowRegistry, createFrameworkAdapterFromEnv, createInMemoryFrameworkAdapter, createInMemoryPendingRequestStore, createInMemorySessionCheckpointStore, createInMemoryWorkflowRegistry, createPostgresFrameworkAdapter, createRedisFrameworkAdapter, getCheckpointer, getRegisteredNode, listRegisteredNodes, makeRequestId, makeResumeToken, registerNode, resolveNode, restoreGraphSnapshot };