@axiom-lattice/pg-stores 1.0.82 → 1.0.84

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PoolConfig, PoolClient, Pool } from 'pg';
+import { Pool, PoolConfig, PoolClient } from 'pg';
 export { Pool, PoolConfig } from 'pg';
 import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, MetricsServerConfigStore, MetricsServerConfigEntry, CreateMetricsServerConfigRequest, UpdateMetricsServerConfigRequest, McpServerConfigStore, McpServerConfigEntry, CreateMcpServerConfigRequest, UpdateMcpServerConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, Project, CreateProjectRequest, UpdateProjectRequest, UserStore, User, CreateUserRequest, UpdateUserRequest, TenantStore, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLinkStore, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, WorkflowTrackingStore, CreateWorkflowRunRequest, WorkflowRun, UpdateWorkflowRunRequest, CreateRunStepRequest, RunStep, UpdateRunStepRequest, StepType, EvalStore, EvalProject, CreateEvalProjectRequest, EvalSuite, CreateEvalSuiteRequest, EvalCase, CreateEvalCaseRequest, EvalRun, CreateEvalRunRequest, EvalRunResult, EvalProjectReport, BindingRegistry, Binding, CreateBindingInput, ChannelInstallationStore, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationRequest, UpdateChannelInstallationRequest, A2AApiKeyStore, A2AApiKeyRecord, CreateA2AApiKeyInput, A2AApiKeyEntry, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, TaskStore, CreateTaskRequest, TaskItem, TaskListFilter, UpdateTaskRequest, MenuRegistry, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, SharedResourceStore, ShareRecord, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
 export { Assistant, AssistantStore, Binding, BindingRegistry, ChannelInstallation, ChannelInstallationStore, CreateAssistantRequest, CreateBindingInput, CreateChannelInstallationRequest, CreateDatabaseConfigRequest, CreateEvalCaseRequest, CreateEvalProjectRequest, CreateEvalRunRequest, CreateEvalSuiteRequest, CreateMcpServerConfigRequest, CreateMenuItemInput, CreateMetricsServerConfigRequest, CreateProjectRequest, CreateRunStepRequest, CreateShareRequest, CreateSkillRequest, CreateTenantRequest, CreateThreadRequest, CreateUserRequest, CreateUserTenantLinkRequest, CreateWorkflowRunRequest, CreateWorkspaceRequest, DatabaseConfig, DatabaseConfigEntry, DatabaseConfigStore, DatabaseType, EvalCase, EvalProject, EvalProjectReport, EvalRun, EvalRunResult, EvalStore, EvalSuite, LarkChannelInstallationConfig, McpServerConfigEntry, McpServerConfigStore, MenuItem, MenuRegistry, MetricsServerConfig, MetricsServerConfigEntry, MetricsServerConfigStore, Project, ProjectStore, ResourceAddress, RunStep, ScheduleExecutionType, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ShareRecord, ShareResult, ShareVisibility, SharedResourceStore, Skill, SkillStore, StorageType, Tenant, TenantStatus, TenantStore, Thread, ThreadStore, UpdateChannelInstallationRequest, UpdateDatabaseConfigRequest, UpdateMcpServerConfigRequest, UpdateMetricsServerConfigRequest, UpdateProjectRequest, UpdateRunStepRequest, UpdateTenantRequest, UpdateUserRequest, UpdateUserTenantLinkRequest, UpdateWorkflowRunRequest, UpdateWorkspaceRequest, User, UserStore, UserTenantLink, UserTenantLinkStore, UserTenantRole, WorkflowRun, WorkflowTrackingStore, Workspace, WorkspaceStore } from '@axiom-lattice/protocols';
@@ -14,11 +14,16 @@ import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
  * PostgreSQL ThreadStore options
  */
 interface PostgreSQLThreadStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -90,11 +95,16 @@ declare class PostgreSQLThreadStore implements ThreadStore {
  * PostgreSQL AssistantStore options
  */
 interface PostgreSQLAssistantStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -170,11 +180,16 @@ declare class PostgreSQLAssistantStore implements AssistantStore {
  * PostgreSQL DatabaseConfigStore options
  */
 interface PostgreSQLDatabaseConfigStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -193,6 +208,7 @@ declare class PostgreSQLDatabaseConfigStore implements DatabaseConfigStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: PostgreSQLDatabaseConfigStoreOptions);
     /**
@@ -259,11 +275,16 @@ declare class PostgreSQLDatabaseConfigStore implements DatabaseConfigStore {
  * PostgreSQL MetricsServerConfigStore options
  */
 interface PostgreSQLMetricsServerConfigStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -282,6 +303,7 @@ declare class PostgreSQLMetricsServerConfigStore implements MetricsServerConfigS
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: PostgreSQLMetricsServerConfigStoreOptions);
     /**
@@ -348,11 +370,16 @@ declare class PostgreSQLMetricsServerConfigStore implements MetricsServerConfigS
  * PostgreSQL McpServerConfigStore options
  */
 interface PostgreSQLMcpServerConfigStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -371,6 +398,7 @@ declare class PostgreSQLMcpServerConfigStore implements McpServerConfigStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: PostgreSQLMcpServerConfigStoreOptions);
     /**
@@ -437,11 +465,16 @@ declare class PostgreSQLMcpServerConfigStore implements McpServerConfigStore {
  * PostgreSQL WorkspaceStore options
  */
 interface PostgreSQLWorkspaceStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -504,11 +537,16 @@ declare class PostgreSQLWorkspaceStore implements WorkspaceStore {
  * PostgreSQL ProjectStore options
  */
 interface PostgreSQLProjectStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -568,13 +606,15 @@ declare class PostgreSQLProjectStore implements ProjectStore {
 }
 
 interface PostgreSQLUserStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class PostgreSQLUserStore implements UserStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     constructor(options: PostgreSQLUserStoreOptions);
     dispose(): Promise<void>;
     initialize(): Promise<void>;
@@ -596,11 +636,16 @@ declare class PostgreSQLUserStore implements UserStore {
  * PostgreSQL TenantStore options
  */
 interface PostgreSQLTenantStoreOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -657,13 +702,15 @@ declare class PostgreSQLTenantStore implements TenantStore {
 }
 
 interface PostgreSQLUserTenantLinkStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class PostgreSQLUserTenantLinkStore implements UserTenantLinkStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     constructor(options: PostgreSQLUserTenantLinkStoreOptions);
     dispose(): Promise<void>;
     initialize(): Promise<void>;
@@ -683,13 +730,15 @@ declare class PostgreSQLUserTenantLinkStore implements UserTenantLinkStore {
  */
 
 interface PostgreSQLWorkflowTrackingStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class PostgreSQLWorkflowTrackingStore implements WorkflowTrackingStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: PostgreSQLWorkflowTrackingStoreOptions);
     dispose(): Promise<void>;
@@ -719,8 +768,10 @@ declare function mapRowToRunStep(row: any): RunStep;
 
 /** PostgreSQL EvalStore options */
 interface PostgreSQLEvalStoreOptions {
+    /** External pool instance. When provided, poolConfig is not required. */
+    pool?: Pool;
     /** PostgreSQL connection pool configuration */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /** Whether to run migrations automatically on initialization @default true */
     autoMigrate?: boolean;
 }
@@ -824,7 +875,8 @@ declare class PostgreSQLEvalStore implements EvalStore {
  */
 
 interface PostgreSQLThreadMessageQueueStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class ThreadMessageQueueStore implements IMessageQueueStore {
@@ -882,16 +934,19 @@ declare class ThreadMessageQueueStore implements IMessageQueueStore {
 }
 
 interface ChannelBindingStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class ChannelBindingStore implements BindingRegistry {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: ChannelBindingStoreOptions);
     initialize(): Promise<void>;
+    dispose(): Promise<void>;
     resolve(params: {
         channel: string;
         senderId: string;
@@ -918,16 +973,19 @@ declare class ChannelBindingStore implements BindingRegistry {
 }
 
 interface PostgreSQLChannelInstallationStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class PostgreSQLChannelInstallationStore implements ChannelInstallationStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: PostgreSQLChannelInstallationStoreOptions);
     initialize(): Promise<void>;
+    dispose(): Promise<void>;
     getInstallationById(installationId: string): Promise<ChannelInstallation | null>;
     getInstallationsByTenant(tenantId: string, channel?: ChannelInstallationType): Promise<ChannelInstallation[]>;
     getAllInstallations(channel?: ChannelInstallationType): Promise<ChannelInstallation[]>;
@@ -941,16 +999,19 @@ declare class PostgreSQLChannelInstallationStore implements ChannelInstallationS
 }
 
 interface PostgreSQLA2AApiKeyStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class PostgreSQLA2AApiKeyStore implements A2AApiKeyStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: PostgreSQLA2AApiKeyStoreOptions);
     initialize(): Promise<void>;
+    dispose(): Promise<void>;
     private ensureInitialized;
     findByKey(key: string): Promise<A2AApiKeyRecord | null>;
     list(params: {
@@ -977,11 +1038,16 @@ declare class PostgreSQLA2AApiKeyStore implements A2AApiKeyStore {
  * PostgreSQL ScheduleStorage options
  */
 interface PostgreSQLScheduleStorageOptions {
+    /**
+     * External pool instance. When provided, poolConfig is not required and the
+     * caller is responsible for pool lifecycle and migrations.
+     */
+    pool?: Pool;
     /**
      * PostgreSQL connection pool configuration
      * Can be a connection string or PoolConfig object
      */
-    poolConfig: string | PoolConfig;
+    poolConfig?: string | PoolConfig;
     /**
      * Whether to run migrations automatically on initialization
      * @default true
@@ -995,6 +1061,7 @@ declare class PostgreSQLScheduleStorage implements ScheduleStorage {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     constructor(options: PostgreSQLScheduleStorageOptions);
     /**
      * Dispose resources and close the connection pool
@@ -1087,7 +1154,8 @@ declare class PostgreSQLScheduleStorage implements ScheduleStorage {
  */
 
 interface PostgreSQLTaskStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class PostgreSQLTaskStore implements TaskStore {
@@ -1112,16 +1180,19 @@ declare class PostgreSQLTaskStore implements TaskStore {
 }
 
 interface MenuStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class MenuStore implements MenuRegistry {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: MenuStoreOptions);
     initialize(): Promise<void>;
+    dispose(): Promise<void>;
     list(params: {
         tenantId: string;
         menuTarget?: string;
@@ -1137,16 +1208,19 @@ declare class MenuStore implements MenuRegistry {
 }
 
 interface PostgresSharedResourceStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 declare class PostgresSharedResourceStore implements SharedResourceStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: PostgresSharedResourceStoreOptions);
     initialize(): Promise<void>;
+    dispose(): Promise<void>;
     findByToken(token: string): Promise<ShareRecord | null>;
     create(record: Omit<ShareRecord, "accessCount" | "createdAt" | "version">): Promise<ShareRecord>;
     update(token: string, patch: Record<string, unknown>): Promise<void>;
@@ -1157,7 +1231,7 @@ declare class PostgresSharedResourceStore implements SharedResourceStore {
     private _mapRow;
 }
 
-declare function createPgStoreConfig(connectionString: string): {
+declare function createPgStoreConfig(connectionString: string): Promise<{
     workspace: PostgreSQLWorkspaceStore;
     project: PostgreSQLProjectStore;
     eval: PostgreSQLEvalStore;
@@ -1179,14 +1253,15 @@ declare function createPgStoreConfig(connectionString: string): {
     menu: MenuStore;
     sharedResource: PostgresSharedResourceStore;
     checkpoint: PostgresSaver;
-};
+}>;
 
 /**
  * PostgreSQL implementation of SkillStore with tenant isolation
  */
 
 interface PostgreSQLSkillStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 /**
@@ -1259,30 +1334,29 @@ declare class PostgreSQLSkillStore implements SkillStore {
 /**
  * Migration system for database schema management
  *
- * ## Migration Version Rules
+ * ## Identity vs Ordering
  *
- * Version numbers are globally unique across all migrations applied to the same
- * database. They are NOT auto-assigned — you must pick one manually.
+ * **name = identity** — each migration is uniquely identified by its name.
+ * Two migrations MAY share the same version number; they are tracked
+ * independently by name and will both execute.
  *
- * ### Numbering scheme
+ * **version = ordering** — migrations are sorted and applied in ascending
+ * version order. Sharing a version simply means two migrations are at the
+ * same position in the dependency chain (they operate on different tables).
+ *
+ * ### Version numbering scheme
  *
  * | Range   | Purpose                              |
  * |---------|--------------------------------------|
  * | 1–99    | Core table creation + column changes |
  * | 100+    | Independent feature modules          |
  *
- * ### How to pick a version
- *
- * 1. Run `grep -rn "version:" src/migrations/ | sort -t: -k3 -n` to list all versions
- * 2. For a core column change: find the next unused number in the 1–99 range
- * 3. For a new feature module: find the next unused number in the 100+ range
- * 4. Verify your chosen version is NOT in the grep output
- *
  * @remarks
- * - Migrations are sorted and applied in version order on startup
+ * - Migrations are applied in version order on startup
  * - The version must be strictly greater than any migration it depends on
  * - Use `IF NOT EXISTS` / `IF EXISTS` in SQL to keep migrations idempotent
- * - A version number collision will cause one migration to be silently skipped
+ * - Duplicate **names** are rejected at registration time
+ * - Duplicate **versions** are allowed (different features, different tables)
  */
 
 /**
@@ -1302,28 +1376,31 @@ declare class MigrationManager {
     private migrations;
     constructor(pool: Pool);
     /**
-     * Register a migration
+     * Register a migration.
+     * Duplicate names are rejected immediately (name = identity).
+     * Duplicate versions are allowed (version = ordering only).
      */
     register(migration: Migration): void;
     /**
-     * Initialize migrations table if it doesn't exist
+     * Ensure the tracking table exists with the correct schema.
+     * Handles migration from old schema (PK on version) to new schema (PK on name).
      */
     private ensureMigrationsTable;
     /**
-     * Get applied migrations from database
+     * Get the set of already-applied migration names from the tracking table.
      */
-    private getAppliedMigrations;
+    private getAppliedNames;
     /**
      * Apply pending migrations
      * Uses PostgreSQL advisory locks to prevent concurrent migrations
      */
     migrate(): Promise<void>;
     /**
-     * Rollback last migration
+     * Rollback the last-applied migration (highest version).
      */
     rollback(): Promise<void>;
     /**
-     * Get current migration version
+     * Get the highest applied migration version.
      */
     getCurrentVersion(): Promise<number>;
 }
@@ -1538,7 +1615,8 @@ declare const createWorkflowTrackingTables: Migration;
 declare const addStepThreadId: Migration;
 
 interface ChannelIdentityMappingStoreOptions {
-    poolConfig: string | PoolConfig;
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
     autoMigrate?: boolean;
 }
 interface CreateChannelIdentityMappingInput {
@@ -1575,9 +1653,11 @@ declare class ChannelIdentityMappingStore {
     private pool;
     private migrationManager;
     private initialized;
+    private ownsPool;
     private initPromise;
     constructor(options: ChannelIdentityMappingStoreOptions);
     initialize(): Promise<void>;
+    dispose(): Promise<void>;
     createMapping(input: CreateChannelIdentityMappingInput): Promise<ChannelIdentityMapping>;
     getMappingBySubject(input: {
         channel: string;