@hexis-ai/engram-server 0.15.0 → 0.16.0

package/dist/adapters/postgres.d.ts

@@ -10,6 +10,12 @@ export interface SqlClient {
     <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
     /** Raw query for DDL / multi-statement strings. */
     unsafe: (query: string) => Promise<unknown>;
+    /**
+     * Open a transaction. Statements issued via the callback's `tx`
+     * argument commit together, or roll back together if the callback
+     * throws. Mirrors the `postgres` package's signature.
+     */
+    begin<T>(fn: (tx: SqlClient) => Promise<T>): Promise<T>;
 }
 export interface PostgresAdapterOptions {
     /** Workspace scope baked into every row. Required for multi-tenant isolation. */

package/dist/adapters/postgres.js

@@ -57,63 +57,73 @@ export class PostgresAdapter {
     async appendEvents(sessionId, events) {
         if (events.length === 0)
             return;
-        for (const ev of events) {
-            await this.sql `
-        INSERT INTO engram_events (workspace_id, session_id, seq, type, at, payload)
-        VALUES (
-          ${this.workspaceId},
-          ${sessionId},
-          ${ev.seq},
-          ${ev.type},
-          ${ev.at},
-          ${ev}
-        )
-        ON CONFLICT (workspace_id, session_id, seq) DO NOTHING
-      `;
-            // Participant events also widen the session's participants array so
-            // a one-shot listSessions can answer "who took part" without folding
-            // events at read time. viewable_by widens too (participants ⊆ viewable_by).
-            if (ev.type === "participant") {
-                await this.sql `
-          UPDATE engram_sessions
-          SET participants = (
-                SELECT ARRAY(SELECT DISTINCT unnest(participants || ARRAY[${ev.personId}]::text[]))
-              ),
-              viewable_by  = (
-                SELECT ARRAY(SELECT DISTINCT unnest(viewable_by || ARRAY[${ev.personId}]::text[]))
-              )
-          WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+        // Wrap the whole batch in a transaction so the event log and the
+        // denormalized session row (participants[] / viewable_by[] /
+        // updated_at) can never diverge. Previously each INSERT + UPDATE
+        // landed as a separate statement; a mid-batch failure left the
+        // materialized state out of sync with the ledger with no way to
+        // reconstruct it.
+        await this.sql.begin(async (tx) => {
+            for (const ev of events) {
+                await tx `
+          INSERT INTO engram_events (workspace_id, session_id, seq, type, at, payload)
+          VALUES (
+            ${this.workspaceId},
+            ${sessionId},
+            ${ev.seq},
+            ${ev.type},
+            ${ev.at},
+            ${ev}
+          )
+          ON CONFLICT (workspace_id, session_id, seq) DO NOTHING
         `;
+                // Participant events also widen the session's participants array
+                // so a one-shot listSessions can answer "who took part" without
+                // folding events at read time. viewable_by widens too
+                // (participants ⊆ viewable_by).
+                if (ev.type === "participant") {
+                    await tx `
+            UPDATE engram_sessions
+            SET participants = (
+                  SELECT ARRAY(SELECT DISTINCT unnest(participants || ARRAY[${ev.personId}]::text[]))
+                ),
+                viewable_by  = (
+                  SELECT ARRAY(SELECT DISTINCT unnest(viewable_by || ARRAY[${ev.personId}]::text[]))
+                )
+            WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+          `;
+                }
             }
-        }
-        // Bump updated_at once per batch so list-by-recent-activity stays
-        // accurate. Using the latest event's `at` (not now()) keeps the
-        // semantics deterministic for back-dated batches.
-        const latest = events[events.length - 1];
-        await this.sql `
-      UPDATE engram_sessions
-      SET updated_at = GREATEST(updated_at, ${latest.at}::timestamptz)
-      WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
-    `;
+            // Bump updated_at once per batch so list-by-recent-activity stays
+            // accurate. Using the latest event's `at` (not now()) keeps the
+            // semantics deterministic for back-dated batches.
+            const latest = events[events.length - 1];
+            await tx `
+        UPDATE engram_sessions
+        SET updated_at = GREATEST(updated_at, ${latest.at}::timestamptz)
+        WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+      `;
+        });
     }
     async getSession(sessionId) {
         const rows = await this.sql `
-      SELECT id, title, channel, participants, viewable_by, created_at,
-             updated_at, status, summary, model,
-             trigger_conversation_id, trigger_event_id,
-             trigger_purpose, trigger_resume_hint
-      FROM engram_sessions
-      WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+      SELECT s.id, s.title, s.channel, s.participants, s.viewable_by,
+             s.created_at, s.updated_at, s.status, s.summary, s.model,
+             s.trigger_conversation_id, s.trigger_event_id,
+             s.trigger_purpose, s.trigger_resume_hint,
+             COALESCE(
+               (SELECT json_agg(e.payload ORDER BY e.seq)
+                FROM engram_events e
+                WHERE e.workspace_id = s.workspace_id AND e.session_id = s.id),
+               '[]'::json
+             ) AS events
+      FROM engram_sessions s
+      WHERE s.workspace_id = ${this.workspaceId} AND s.id = ${sessionId}
       LIMIT 1
     `;
         if (rows.length === 0)
             return null;
-        const events = await this.sql `
-      SELECT payload FROM engram_events
-      WHERE workspace_id = ${this.workspaceId} AND session_id = ${sessionId}
-      ORDER BY seq
-    `;
-        return foldEvents(toSessionRow(rows[0]), events.map((e) => e.payload), new Date());
+        return foldRowWithEvents(rows[0]);
     }
     async updateSession(sessionId, patch) {
         // Per-column "provided" flags drive a CASE WHEN per field: undefined
@@ -173,45 +183,78 @@ export class PostgresAdapter {
         const hasTrigger = opts.has_trigger === true;
         const noSummary = opts.no_summary === true;
         const updatedBefore = opts.updated_before ?? null;
+        // Single query: session columns + the per-session event payload
+        // array via a correlated subquery (uses the engram_events PK index
+        // (workspace_id, session_id, seq)). Replaces the prior pattern of
+        // SELECT id + N follow-up getSession() round-trips.
         const rows = await this.sql `
-      SELECT id FROM engram_sessions
-      WHERE workspace_id = ${this.workspaceId}
-        AND (${channelFilter}::text IS NULL OR channel = ${channelFilter}::text)
-        AND (${channelPrefix}::text IS NULL OR channel LIKE ${channelPrefix ? channelPrefix + "%" : null}::text)
-        AND (${statusFilter}::text IS NULL OR status  = ${statusFilter}::text)
-        AND (${hasTrigger}::boolean = FALSE OR trigger_conversation_id IS NOT NULL)
-        AND (${noSummary}::boolean = FALSE OR summary IS NULL)
-        AND (${updatedBefore}::timestamptz IS NULL OR updated_at < ${updatedBefore}::timestamptz)
-      ORDER BY updated_at DESC
+      SELECT s.id, s.title, s.channel, s.participants, s.viewable_by,
+             s.created_at, s.updated_at, s.status, s.summary, s.model,
+             s.trigger_conversation_id, s.trigger_event_id,
+             s.trigger_purpose, s.trigger_resume_hint,
+             COALESCE(
+               (SELECT json_agg(e.payload ORDER BY e.seq)
+                FROM engram_events e
+                WHERE e.workspace_id = s.workspace_id AND e.session_id = s.id),
+               '[]'::json
+             ) AS events
+      FROM engram_sessions s
+      WHERE s.workspace_id = ${this.workspaceId}
+        AND (${channelFilter}::text IS NULL OR s.channel = ${channelFilter}::text)
+        AND (${channelPrefix}::text IS NULL OR s.channel LIKE ${channelPrefix ? channelPrefix + "%" : null}::text)
+        AND (${statusFilter}::text IS NULL OR s.status  = ${statusFilter}::text)
+        AND (${hasTrigger}::boolean = FALSE OR s.trigger_conversation_id IS NOT NULL)
+        AND (${noSummary}::boolean = FALSE OR s.summary IS NULL)
+        AND (${updatedBefore}::timestamptz IS NULL OR s.updated_at < ${updatedBefore}::timestamptz)
+      ORDER BY s.updated_at DESC
       LIMIT ${opts.limit}
     `;
-        const sessions = await Promise.all(rows.map((r) => this.getSession(r.id)));
-        return sessions.filter((s) => s !== null);
+        return rows.map(foldRowWithEvents);
     }
     async sessionsForPerson(personId, opts) {
         const channelFilter = opts.channel ?? null;
         const scope = opts.scope ?? "participant";
         // Identifier (column name) can't be parameterized in tagged templates,
-        // so branch the query. Both arms are otherwise identical.
+        // so branch the query. Both arms are otherwise identical and share
+        // the same single-query fold as listSessions.
         const rows = scope === "viewable"
             ? await this.sql `
-          SELECT id FROM engram_sessions
-          WHERE workspace_id = ${this.workspaceId}
-            AND viewable_by @> ARRAY[${personId}]::text[]
-            AND (${channelFilter}::text IS NULL OR channel = ${channelFilter}::text)
-          ORDER BY created_at DESC
+          SELECT s.id, s.title, s.channel, s.participants, s.viewable_by,
+                 s.created_at, s.updated_at, s.status, s.summary, s.model,
+                 s.trigger_conversation_id, s.trigger_event_id,
+                 s.trigger_purpose, s.trigger_resume_hint,
+                 COALESCE(
+                   (SELECT json_agg(e.payload ORDER BY e.seq)
+                    FROM engram_events e
+                    WHERE e.workspace_id = s.workspace_id AND e.session_id = s.id),
+                   '[]'::json
+                 ) AS events
+          FROM engram_sessions s
+          WHERE s.workspace_id = ${this.workspaceId}
+            AND s.viewable_by @> ARRAY[${personId}]::text[]
+            AND (${channelFilter}::text IS NULL OR s.channel = ${channelFilter}::text)
+          ORDER BY s.created_at DESC
           LIMIT ${opts.limit}
         `
             : await this.sql `
-          SELECT id FROM engram_sessions
-          WHERE workspace_id = ${this.workspaceId}
-            AND participants @> ARRAY[${personId}]::text[]
-            AND (${channelFilter}::text IS NULL OR channel = ${channelFilter}::text)
-          ORDER BY created_at DESC
+          SELECT s.id, s.title, s.channel, s.participants, s.viewable_by,
+                 s.created_at, s.updated_at, s.status, s.summary, s.model,
+                 s.trigger_conversation_id, s.trigger_event_id,
+                 s.trigger_purpose, s.trigger_resume_hint,
+                 COALESCE(
+                   (SELECT json_agg(e.payload ORDER BY e.seq)
+                    FROM engram_events e
+                    WHERE e.workspace_id = s.workspace_id AND e.session_id = s.id),
+                   '[]'::json
+                 ) AS events
+          FROM engram_sessions s
+          WHERE s.workspace_id = ${this.workspaceId}
+            AND s.participants @> ARRAY[${personId}]::text[]
+            AND (${channelFilter}::text IS NULL OR s.channel = ${channelFilter}::text)
+          ORDER BY s.created_at DESC
           LIMIT ${opts.limit}
         `;
-        const sessions = await Promise.all(rows.map((r) => this.getSession(r.id)));
-        return sessions.filter((s) => s !== null);
+        return rows.map(foldRowWithEvents);
     }
     // --- Persons ------------------------------------------------------
     async createPerson(input) {
@@ -464,6 +507,11 @@ function toPersonInfo(r) {
         updated_at: isoString(r.updated_at),
     };
 }
+/** Convenience wrapper used by every read path: lifts the joined row
+ *  into a SessionRow + events and folds in a single step. */
+function foldRowWithEvents(r) {
+    return foldEvents(toSessionRow(r), r.events ?? [], new Date());
+}
 function toSessionRow(r) {
     return {
         id: r.id,

package/dist/migrations/0009-events-type-index.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0009-events-type-index";
+export declare const sql = "\n-- Type-aware event index for callers that filter by event type\n-- (the most common is monet's conversation-repository, which fetches\n-- only `type='message'` events to materialize the chat transcript).\n--\n-- The existing PK `(workspace_id, session_id, seq)` lets PG find\n-- events for a session quickly, but it has to read every row to filter\n-- by type. This composite index trades a small write-side cost for an\n-- index-only scan on the typical \"messages for this session\" query.\n\nCREATE INDEX IF NOT EXISTS idx_engram_events_workspace_session_type\n  ON engram_events (workspace_id, session_id, type);\n";

package/dist/migrations/0009-events-type-index.js

@@ -0,0 +1,14 @@
+export const name = "0009-events-type-index";
+export const sql = `
+-- Type-aware event index for callers that filter by event type
+-- (the most common is monet's conversation-repository, which fetches
+-- only \`type='message'\` events to materialize the chat transcript).
+--
+-- The existing PK \`(workspace_id, session_id, seq)\` lets PG find
+-- events for a session quickly, but it has to read every row to filter
+-- by type. This composite index trades a small write-side cost for an
+-- index-only scan on the typical "messages for this session" query.
+
+CREATE INDEX IF NOT EXISTS idx_engram_events_workspace_session_type
+  ON engram_events (workspace_id, session_id, type);
+`;

package/dist/migrations/index.js

@@ -6,6 +6,7 @@ import * as m0005 from "./0005-session-updated-at";
 import * as m0006 from "./0006-auth";
 import * as m0007 from "./0007-orgs";
 import * as m0008 from "./0008-trigger-metadata";
+import * as m0009 from "./0009-events-type-index";
 /**
  * Schema migrations, applied in array order. Add a new file under
  * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
@@ -22,4 +23,5 @@ export const MIGRATIONS = [
     { name: m0006.name, sql: m0006.sql },
     { name: m0007.name, sql: m0007.sql },
     { name: m0008.name, sql: m0008.sql },
+    { name: m0009.name, sql: m0009.sql },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
   "keywords": [
     "engram",