@eidentic/postgres 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,126 @@
+import { StorePort, GraphPort, DurablePort, SessionRecord, StoredEvent, Scope, MemoryBlock, BlockHistoryEntry, MemorySnippet, AssertFactInput, Fact, FactQuery, Checkpoint, IdempotencyRecord, SuspendDecision } from '@eidentic/types';
+
+/** Minimal client surface satisfied by both `pg.Pool` and `@electric-sql/pglite`. */
+interface PgClient {
+    /**
+     * Execute a parameterised query.
+     *
+     * Supply a row type parameter `R` to get compile-time column checking:
+     * ```ts
+     * const { rows } = await client.query<{ id: string; name: string }>(
+     *   "SELECT id, name FROM users WHERE id = $1", [userId],
+     * );
+     * // rows is { id: string; name: string }[]
+     * ```
+     *
+     * The default is `any` for back-compat — untyped callers continue to work
+     * without changes, while new call-sites can opt in to typed rows.
+     */
+    query<R = any>(text: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+    /** Present on `pg.Pool` and `pg.Client`; absent on pglite. */
+    connect?(): Promise<PgPoolClient>;
+}
+/** Minimal surface of the dedicated client checked out from a `pg.Pool`. */
+interface PgPoolClient {
+    /** @see {@link PgClient.query} */
+    query<R = any>(text: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+    release(): void;
+}
+declare class PostgresStore implements StorePort, GraphPort, DurablePort {
+    private readonly client;
+    private factIdCounter;
+    private readonly newFactId;
+    private readonly graphNow;
+    /**
+     * Construct a PostgresStore wrapping an injected `PgClient`.
+     *
+     * Pass a `pg.Pool` or a `@electric-sql/pglite` instance as `client`.
+     * Note: when using `pg.Pool`, pass a dedicated client or pool — the store
+     * issues its own BEGIN/COMMIT on the connection for multi-statement atomicity.
+     * For pglite (single-connection WASM), BEGIN/COMMIT on the same client is fine.
+     *
+     * Call `await store.migrate()` before use, or use `PostgresStore.create()`
+     * which runs migrations automatically.
+     */
+    constructor(client: PgClient, opts?: {
+        newId?: () => string;
+        now?: () => string;
+    });
+    /**
+     * Create a PostgresStore and run migrations in one step.
+     * Convenience wrapper for `new PostgresStore(client)` + `migrate()`.
+     */
+    static create(opts: {
+        client: PgClient;
+        newId?: () => string;
+        now?: () => string;
+    }): Promise<PostgresStore>;
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Run `fn` inside a single Postgres transaction.
+     *
+     * When `this.client` is a `pg.Pool` (has a `connect()` method), we check out
+     * a dedicated connection so that BEGIN / body / COMMIT all execute on the same
+     * underlying socket — Pool.query() would otherwise dispatch each call to a
+     * different pooled connection, destroying atomicity.
+     *
+     * When `this.client` is pglite (no `connect()`), the client IS the connection;
+     * we issue BEGIN/COMMIT directly on it, matching the previous behaviour.
+     */
+    private withTransaction;
+    createSession(s: SessionRecord): Promise<void>;
+    getSession(id: string): Promise<SessionRecord | null>;
+    appendEvents(events: StoredEvent[]): Promise<void>;
+    readEvents(sessionId: string): Promise<StoredEvent[]>;
+    getBlocks(scope: Scope): Promise<MemoryBlock[]>;
+    getBlock(scope: Scope, label: string): Promise<MemoryBlock | null>;
+    upsertBlock(scope: Scope, block: {
+        label: string;
+        value: string;
+    }, expectVersion?: number): Promise<MemoryBlock>;
+    appendBlock(scope: Scope, label: string, text: string): Promise<MemoryBlock>;
+    getBlockHistory(scope: Scope, label: string): Promise<BlockHistoryEntry[]>;
+    private writeBlock;
+    indexMemory(entries: Array<{
+        scope: Scope;
+        id: string;
+        text: string;
+        ingestedAt?: number;
+        metadata?: Record<string, unknown>;
+    }>): Promise<void>;
+    searchMemory(scope: Scope, query: string, topK: number): Promise<MemorySnippet[]>;
+    private rowToFact;
+    assertFact(scope: Scope, input: AssertFactInput): Promise<{
+        asserted: Fact;
+        invalidated: Fact[];
+    }>;
+    factHistory(scope: Scope, subject: string, predicate: string): Promise<Fact[]>;
+    corroborate(scope: Scope, factId: string, at?: number): Promise<number>;
+    expireFacts(scope: Scope, ids: string[], at: string): Promise<number>;
+    queryFacts(query: FactQuery): Promise<Fact[]>;
+    sweepExpired(scope: Scope, now: string): Promise<number>;
+    listSessions(opts?: {
+        agentId?: string;
+        limit?: number;
+        userId?: string;
+        orgId?: string;
+    }): Promise<SessionRecord[]>;
+    listBlocks(scope: Scope): Promise<MemoryBlock[]>;
+    eraseScope(scope: Scope): Promise<{
+        deleted: number;
+    }>;
+    writeCheckpoint(sessionId: string, seq: number, hash: string): Promise<void>;
+    lastCheckpoint(sessionId: string): Promise<Checkpoint | null>;
+    recordIntent(key: string, argsHash: string): Promise<void>;
+    recordCompletion(key: string, result: unknown): Promise<void>;
+    getIdempotency(key: string): Promise<IdempotencyRecord | null>;
+    recordDecision(sessionId: string, callId: string, decision: SuspendDecision): Promise<void>;
+    getDecision(sessionId: string, callId: string): Promise<SuspendDecision | null>;
+}
+
+export { type PgClient, type PgPoolClient, PostgresStore };

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { StorePort, GraphPort, DurablePort, SessionRecord, StoredEvent, Scope, MemoryBlock, BlockHistoryEntry, MemorySnippet, AssertFactInput, Fact, FactQuery, Checkpoint, IdempotencyRecord, SuspendDecision } from '@eidentic/types';
+
+/** Minimal client surface satisfied by both `pg.Pool` and `@electric-sql/pglite`. */
+interface PgClient {
+    /**
+     * Execute a parameterised query.
+     *
+     * Supply a row type parameter `R` to get compile-time column checking:
+     * ```ts
+     * const { rows } = await client.query<{ id: string; name: string }>(
+     *   "SELECT id, name FROM users WHERE id = $1", [userId],
+     * );
+     * // rows is { id: string; name: string }[]
+     * ```
+     *
+     * The default is `any` for back-compat — untyped callers continue to work
+     * without changes, while new call-sites can opt in to typed rows.
+     */
+    query<R = any>(text: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+    /** Present on `pg.Pool` and `pg.Client`; absent on pglite. */
+    connect?(): Promise<PgPoolClient>;
+}
+/** Minimal surface of the dedicated client checked out from a `pg.Pool`. */
+interface PgPoolClient {
+    /** @see {@link PgClient.query} */
+    query<R = any>(text: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+    release(): void;
+}
+declare class PostgresStore implements StorePort, GraphPort, DurablePort {
+    private readonly client;
+    private factIdCounter;
+    private readonly newFactId;
+    private readonly graphNow;
+    /**
+     * Construct a PostgresStore wrapping an injected `PgClient`.
+     *
+     * Pass a `pg.Pool` or a `@electric-sql/pglite` instance as `client`.
+     * Note: when using `pg.Pool`, pass a dedicated client or pool — the store
+     * issues its own BEGIN/COMMIT on the connection for multi-statement atomicity.
+     * For pglite (single-connection WASM), BEGIN/COMMIT on the same client is fine.
+     *
+     * Call `await store.migrate()` before use, or use `PostgresStore.create()`
+     * which runs migrations automatically.
+     */
+    constructor(client: PgClient, opts?: {
+        newId?: () => string;
+        now?: () => string;
+    });
+    /**
+     * Create a PostgresStore and run migrations in one step.
+     * Convenience wrapper for `new PostgresStore(client)` + `migrate()`.
+     */
+    static create(opts: {
+        client: PgClient;
+        newId?: () => string;
+        now?: () => string;
+    }): Promise<PostgresStore>;
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Run `fn` inside a single Postgres transaction.
+     *
+     * When `this.client` is a `pg.Pool` (has a `connect()` method), we check out
+     * a dedicated connection so that BEGIN / body / COMMIT all execute on the same
+     * underlying socket — Pool.query() would otherwise dispatch each call to a
+     * different pooled connection, destroying atomicity.
+     *
+     * When `this.client` is pglite (no `connect()`), the client IS the connection;
+     * we issue BEGIN/COMMIT directly on it, matching the previous behaviour.
+     */
+    private withTransaction;
+    createSession(s: SessionRecord): Promise<void>;
+    getSession(id: string): Promise<SessionRecord | null>;
+    appendEvents(events: StoredEvent[]): Promise<void>;
+    readEvents(sessionId: string): Promise<StoredEvent[]>;
+    getBlocks(scope: Scope): Promise<MemoryBlock[]>;
+    getBlock(scope: Scope, label: string): Promise<MemoryBlock | null>;
+    upsertBlock(scope: Scope, block: {
+        label: string;
+        value: string;
+    }, expectVersion?: number): Promise<MemoryBlock>;
+    appendBlock(scope: Scope, label: string, text: string): Promise<MemoryBlock>;
+    getBlockHistory(scope: Scope, label: string): Promise<BlockHistoryEntry[]>;
+    private writeBlock;
+    indexMemory(entries: Array<{
+        scope: Scope;
+        id: string;
+        text: string;
+        ingestedAt?: number;
+        metadata?: Record<string, unknown>;
+    }>): Promise<void>;
+    searchMemory(scope: Scope, query: string, topK: number): Promise<MemorySnippet[]>;
+    private rowToFact;
+    assertFact(scope: Scope, input: AssertFactInput): Promise<{
+        asserted: Fact;
+        invalidated: Fact[];
+    }>;
+    factHistory(scope: Scope, subject: string, predicate: string): Promise<Fact[]>;
+    corroborate(scope: Scope, factId: string, at?: number): Promise<number>;
+    expireFacts(scope: Scope, ids: string[], at: string): Promise<number>;
+    queryFacts(query: FactQuery): Promise<Fact[]>;
+    sweepExpired(scope: Scope, now: string): Promise<number>;
+    listSessions(opts?: {
+        agentId?: string;
+        limit?: number;
+        userId?: string;
+        orgId?: string;
+    }): Promise<SessionRecord[]>;
+    listBlocks(scope: Scope): Promise<MemoryBlock[]>;
+    eraseScope(scope: Scope): Promise<{
+        deleted: number;
+    }>;
+    writeCheckpoint(sessionId: string, seq: number, hash: string): Promise<void>;
+    lastCheckpoint(sessionId: string): Promise<Checkpoint | null>;
+    recordIntent(key: string, argsHash: string): Promise<void>;
+    recordCompletion(key: string, result: unknown): Promise<void>;
+    getIdempotency(key: string): Promise<IdempotencyRecord | null>;
+    recordDecision(sessionId: string, callId: string, decision: SuspendDecision): Promise<void>;
+    getDecision(sessionId: string, callId: string): Promise<SuspendDecision | null>;
+}
+
+export { type PgClient, type PgPoolClient, PostgresStore };