@m6d/cortex-server 2.3.0 → 2.5.0

package/src/lib/adapters/database/mssql/messages.ts

@@ -2,6 +2,7 @@
 import { and, desc, eq, getColumns, inArray, type InferInsertModel } from "drizzle-orm";
 import { threads, messages } from "@/db/schema.mssql";
 import type { ChatMessage } from "@/types";
+import { messageUpsertEvent, threadUpsertEvent } from "@/cc/sync-events";
 import type { DatabaseAdapter } from "@/adapters/database/index";
 import {
     mergeStoredContent,
@@ -9,10 +10,14 @@ import {
     withOwnedAttachments,
 } from "@/adapters/database/message-content";
 import type { MssqlDb } from "./client";
+import { enqueueSyncEvents } from "./outbox";
 
 const DEFAULT_MESSAGE_LIMIT = 100;
 
-export function createMessagesRepository(db: MssqlDb) {
+export function createMessagesRepository(
+    db: MssqlDb,
+    enqueue: typeof enqueueSyncEvents = enqueueSyncEvents,
+) {
     return {
         /**
          * Fetches the newest N and reverses, so a limit keeps the most recent
@@ -45,7 +50,12 @@ export function createMessagesRepository(db: MssqlDb) {
                 options?.replaceAttachments,
             );
             const existingMessages = await db
-                .select({ id: messages.id, content: messages.content })
+                .select({
+                    id: messages.id,
+                    content: messages.content,
+                    ordinal: messages.ordinal,
+                    createdAt: messages.createdAt,
+                })
                 .from(messages)
                 .where(
                     inArray(
@@ -54,39 +64,80 @@ export function createMessagesRepository(db: MssqlDb) {
                     ),
                 )
                 .execute();
-            const existingById = new Map(
-                existingMessages.map((message) => [message.id, message.content]),
-            );
+            const existingById = new Map(existingMessages.map((message) => [message.id, message]));
 
             const newMessages = incomingMessages.filter((x) => !existingById.has(x.id));
-            if (newMessages.length) {
-                await db
-                    .insert(messages)
-                    .values(
-                        newMessages.map(
-                            (x, ordinal) =>
-                                ({
-                                    id: x.id,
-                                    role: x.role,
-                                    threadId,
-                                    content: x,
-                                    text: textOf(x),
-                                    ordinal,
-                                }) satisfies InferInsertModel<typeof messages>,
-                        ),
-                    )
+            const updates = incomingMessages
+                .filter((x) => existingById.has(x.id))
+                .map((message) => {
+                    const existing = existingById.get(message.id)!;
+                    return {
+                        existing,
+                        content: mergeStoredContent(existing.content, message),
+                    };
+                });
+            const now = new Date();
+            await db.transaction(async function (tx) {
+                const [thread] = await tx
+                    .select()
+                    .top(1)
+                    .from(threads)
+                    .where(eq(threads.id, threadId))
                     .execute();
-            }
+                if (newMessages.length) {
+                    await tx
+                        .insert(messages)
+                        .values(
+                            newMessages.map(
+                                (x, ordinal) =>
+                                    ({
+                                        id: x.id,
+                                        role: x.role,
+                                        threadId,
+                                        content: x,
+                                        text: textOf(x),
+                                        ordinal,
+                                        createdAt: now,
+                                    }) satisfies InferInsertModel<typeof messages>,
+                            ),
+                        )
+                        .execute();
+                }
 
-            for (const message of incomingMessages.filter((x) => existingById.has(x.id))) {
-                const content = mergeStoredContent(existingById.get(message.id)!, message);
+                for (const { content } of updates) {
+                    await tx
+                        .update(messages)
+                        .set({ content, text: textOf(content) })
+                        .where(eq(messages.id, content.id))
+                        .execute();
+                }
 
-                await db
-                    .update(messages)
-                    .set({ content, text: textOf(content) })
-                    .where(eq(messages.id, message.id))
-                    .execute();
-            }
+                await enqueue(tx, [
+                    // A current thread.upsert leads the batch so cc's thread
+                    // row exists (and stays fresh) before its children.
+                    ...(thread ? [threadUpsertEvent(thread)] : []),
+                    ...newMessages.map((x, ordinal) =>
+                        messageUpsertEvent({
+                            threadId,
+                            message: x,
+                            text: textOf(x),
+                            ordinal,
+                            createdAt: now,
+                        }),
+                    ),
+                    // Edits keep their original timestamp and slot so the
+                    // mirrored transcript does not reorder.
+                    ...updates.map(({ existing, content }) =>
+                        messageUpsertEvent({
+                            threadId,
+                            message: content,
+                            text: textOf(content),
+                            ordinal: existing.ordinal,
+                            createdAt: existing.createdAt,
+                        }),
+                    ),
+                ]);
+            });
         },
     } satisfies DatabaseAdapter["messages"];
 }

package/src/lib/adapters/database/mssql/outbox.ts

@@ -0,0 +1,71 @@
+import { asc, inArray } from "drizzle-orm";
+import type { SyncEvent } from "@cortex/contracts/runtime";
+import { syncMeta, syncOutbox } from "@/db/schema.mssql";
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { MssqlDb } from "./client";
+
+/** A db or one of its transactions, so a write and its events commit together. */
+type Executor = Pick<MssqlDb, "insert">;
+
+export async function enqueueSyncEvents(executor: Executor, events: SyncEvent[]) {
+    if (!events.length) return;
+    await executor
+        .insert(syncOutbox)
+        .values(events.map((event) => ({ event })))
+        .execute();
+}
+
+export function createOutboxRepository(db: MssqlDb) {
+    return {
+        enqueue: (events) => enqueueSyncEvents(db, events),
+
+        async peek(limit) {
+            return await db
+                .select({ id: syncOutbox.id, event: syncOutbox.event })
+                .from(syncOutbox)
+                .orderBy(asc(syncOutbox.id))
+                .offset(0)
+                .fetch(limit)
+                .execute();
+        },
+
+        async epoch() {
+            const [row] = await db
+                .select({ epoch: syncMeta.epoch })
+                .from(syncMeta)
+                .orderBy(asc(syncMeta.id))
+                .offset(0)
+                .fetch(1)
+                .execute();
+            if (row) return row.epoch;
+
+            // First flush on a fresh database mints its generation id: a
+            // time-ordered UUIDv7, so cc can tell a later generation from a
+            // delayed batch out of a superseded one by plain comparison. A
+            // concurrent mint loses on the primary key (swallowed below) and
+            // reads the winner; anything else that leaves no persisted row
+            // aborts the flush rather than syncing under an epoch a restart
+            // would not repeat.
+            try {
+                await db.insert(syncMeta).values({ id: 1, epoch: Bun.randomUUIDv7() }).execute();
+            } catch {
+                // The reselect decides: a lost mint race reads the winner, a
+                // genuine write failure leaves nothing and throws below.
+            }
+            const [persisted] = await db
+                .select({ epoch: syncMeta.epoch })
+                .from(syncMeta)
+                .orderBy(asc(syncMeta.id))
+                .offset(0)
+                .fetch(1)
+                .execute();
+            if (!persisted) throw new Error("sync_meta epoch missing after mint");
+            return persisted.epoch;
+        },
+
+        async ack(ids) {
+            if (!ids.length) return;
+            await db.delete(syncOutbox).where(inArray(syncOutbox.id, ids)).execute();
+        },
+    } satisfies DatabaseAdapter["outbox"];
+}

package/src/lib/adapters/database/mssql/threads.ts

@@ -1,12 +1,18 @@
 import { and, desc, eq } from "drizzle-orm";
 import { attachments, threads } from "@/db/schema.mssql";
+import { threadDeleteEvent, threadUpsertEvent } from "@/cc/sync-events";
 import type { Thread } from "@/types";
 import type { ThreadContextMeta } from "@/ai/context/types";
 import type { DatabaseAdapter } from "@/adapters/database/index";
 import type { MssqlDb } from "./client";
+import { enqueueSyncEvents } from "./outbox";
 import type { StorageAdapter } from "@/adapters/storage/index";
 
-export function createThreadsRepository(db: MssqlDb, storage?: StorageAdapter) {
+export function createThreadsRepository(
+    db: MssqlDb,
+    storage?: StorageAdapter,
+    enqueue: typeof enqueueSyncEvents = enqueueSyncEvents,
+) {
     return {
         async list(userId, agentId) {
             return await db
@@ -26,9 +32,17 @@ export function createThreadsRepository(db: MssqlDb, storage?: StorageAdapter) {
             return result.length ? (result[0] as Thread) : null;
         },
 
-        async create(userId, agentId) {
-            const result = await db.insert(threads).output().values({ userId, agentId }).execute();
-            return result[0] as Thread;
+        async create(userId, agentId, options) {
+            return await db.transaction(async function (tx) {
+                const result = await tx
+                    .insert(threads)
+                    .output()
+                    .values({ userId, agentId, isTest: options?.isTest ?? false })
+                    .execute();
+                const thread = result[0] as Thread;
+                await enqueue(tx, [threadUpsertEvent(thread)]);
+                return thread;
+            });
         },
 
         /** Object storage has no foreign keys, so attachment paths must be swept before row cascade. */
@@ -44,13 +58,21 @@ export function createThreadsRepository(db: MssqlDb, storage?: StorageAdapter) {
                 await storage.delete(attachmentPaths);
             }
 
-            // Avoid SQL Server error 547 from the NO ACTION attachments.message_id constraint.
-            await db.delete(attachments).where(eq(attachments.threadId, threadId)).execute();
+            await db.transaction(async function (tx) {
+                // Avoid SQL Server error 547 from the NO ACTION attachments.message_id constraint.
+                await tx.delete(attachments).where(eq(attachments.threadId, threadId)).execute();
 
-            await db
-                .delete(threads)
-                .where(and(eq(threads.id, threadId), eq(threads.userId, userId)))
-                .execute();
+                const deleted = await tx
+                    .delete(threads)
+                    .where(and(eq(threads.id, threadId), eq(threads.userId, userId)))
+                    .output({ id: threads.id })
+                    .execute();
+                // The ownership filter can match nothing; a delete event for
+                // someone else's thread id must not touch cc's mirror.
+                if (deleted.length) {
+                    await enqueue(tx, [threadDeleteEvent(threadId)]);
+                }
+            });
         },
 
         async touch(threadId) {
@@ -65,7 +87,16 @@ export function createThreadsRepository(db: MssqlDb, storage?: StorageAdapter) {
         },
 
         async updateTitle(threadId, title) {
-            await db.update(threads).set({ title }).where(eq(threads.id, threadId)).execute();
+            await db.transaction(async function (tx) {
+                const result = await tx
+                    .update(threads)
+                    .set({ title })
+                    .where(eq(threads.id, threadId))
+                    .output()
+                    .execute();
+                const thread = result[0];
+                if (thread) await enqueue(tx, [threadUpsertEvent(thread)]);
+            });
         },
 
         async updateSession(threadId, session) {

package/src/lib/adapters/database/postgres/index.ts

@@ -5,19 +5,28 @@ import { createThreadsRepository } from "./threads";
 import { createMessagesRepository } from "./messages";
 import { createLlmRequestsRepository } from "./llm-requests";
 import { createAttachmentsRepository } from "./attachments";
+import { createOutboxRepository, enqueueSyncEvents } from "./outbox";
 
 /**
  * The Postgres implementation of the database contract. One repository per
  * table; only threads takes storage, because deleting a thread is the one
  * operation that also has to reach into object storage.
  */
-export function createPostgresAdapter(connectionString: string, storage?: StorageAdapter) {
+export function createPostgresAdapter(
+    connectionString: string,
+    storage?: StorageAdapter,
+    options?: { syncMirror?: boolean },
+) {
     const db = createPostgresDb(connectionString);
+    // Without a Control Center there is no flusher to drain the outbox, so
+    // enqueueing would only grow sync_outbox forever.
+    const enqueue = options?.syncMirror === false ? async () => {} : enqueueSyncEvents;
 
     return {
-        threads: createThreadsRepository(db, storage),
-        messages: createMessagesRepository(db),
-        llmRequests: createLlmRequestsRepository(db),
+        threads: createThreadsRepository(db, storage, enqueue),
+        messages: createMessagesRepository(db, enqueue),
+        llmRequests: createLlmRequestsRepository(db, enqueue),
         attachments: createAttachmentsRepository(db),
+        outbox: createOutboxRepository(db),
     } satisfies DatabaseAdapter;
 }

package/src/lib/adapters/database/postgres/llm-requests.ts

@@ -2,29 +2,49 @@
 // Drizzle types query builders per dialect. See DatabaseAdapter in ../index.ts.
 import { asc, eq, type InferInsertModel } from "drizzle-orm";
 import { llmRequests } from "@/db/schema.pg";
+import { usageRecordEvent } from "@/cc/sync-events";
 import type { DatabaseAdapter } from "@/adapters/database/index";
 import type { PostgresDb } from "./client";
+import { enqueueSyncEvents } from "./outbox";
 
-export function createLlmRequestsRepository(db: PostgresDb) {
+export function createLlmRequestsRepository(
+    db: PostgresDb,
+    enqueue: typeof enqueueSyncEvents = enqueueSyncEvents,
+) {
     return {
-        async insert(requests) {
+        async insert(threadId, requests) {
             if (!requests.length) return;
 
-            await db
-                .insert(llmRequests)
-                .values(
-                    requests.map(
-                        (r) =>
-                            ({
+            await db.transaction(async function (tx) {
+                await tx
+                    .insert(llmRequests)
+                    .values(
+                        requests.map(
+                            (r) =>
+                                ({
+                                    messageId: r.messageId,
+                                    stepNumber: r.stepNumber,
+                                    prompt: r.prompt,
+                                    output: r.output,
+                                    tokenUsage: r.tokenUsage,
+                                }) satisfies InferInsertModel<typeof llmRequests>,
+                        ),
+                    )
+                    .execute();
+                await enqueue(
+                    tx,
+                    requests
+                        .filter((r) => r.tokenUsage !== null)
+                        .map((r) =>
+                            usageRecordEvent({
+                                threadId,
                                 messageId: r.messageId,
                                 stepNumber: r.stepNumber,
-                                prompt: r.prompt,
-                                output: r.output,
-                                tokenUsage: r.tokenUsage,
-                            }) satisfies InferInsertModel<typeof llmRequests>,
-                    ),
-                )
-                .execute();
+                                tokenUsage: r.tokenUsage!,
+                            }),
+                        ),
+                );
+            });
         },
 
         /** Ordered by step so the inspector replays a turn in the order it ran. */

package/src/lib/adapters/database/postgres/messages.ts

@@ -3,6 +3,7 @@
 import { and, desc, eq, getColumns, inArray, type InferInsertModel } from "drizzle-orm";
 import { threads, messages } from "@/db/schema.pg";
 import type { ChatMessage } from "@/types";
+import { messageUpsertEvent, threadUpsertEvent } from "@/cc/sync-events";
 import type { DatabaseAdapter } from "@/adapters/database/index";
 import {
     mergeStoredContent,
@@ -10,10 +11,14 @@ import {
     withOwnedAttachments,
 } from "@/adapters/database/message-content";
 import type { PostgresDb } from "./client";
+import { enqueueSyncEvents } from "./outbox";
 
 const DEFAULT_MESSAGE_LIMIT = 100;
 
-export function createMessagesRepository(db: PostgresDb) {
+export function createMessagesRepository(
+    db: PostgresDb,
+    enqueue: typeof enqueueSyncEvents = enqueueSyncEvents,
+) {
     return {
         /**
          * Fetches the newest N and reverses, so a limit keeps the most recent
@@ -45,7 +50,12 @@ export function createMessagesRepository(db: PostgresDb) {
                 options?.replaceAttachments,
             );
             const existingMessages = await db
-                .select({ id: messages.id, content: messages.content })
+                .select({
+                    id: messages.id,
+                    content: messages.content,
+                    ordinal: messages.ordinal,
+                    createdAt: messages.createdAt,
+                })
                 .from(messages)
                 .where(
                     inArray(
@@ -54,39 +64,80 @@ export function createMessagesRepository(db: PostgresDb) {
                     ),
                 )
                 .execute();
-            const existingById = new Map(
-                existingMessages.map((message) => [message.id, message.content]),
-            );
+            const existingById = new Map(existingMessages.map((message) => [message.id, message]));
 
             const newMessages = incomingMessages.filter((x) => !existingById.has(x.id));
-            if (newMessages.length) {
-                await db
-                    .insert(messages)
-                    .values(
-                        newMessages.map(
-                            (x, ordinal) =>
-                                ({
-                                    id: x.id,
-                                    role: x.role,
-                                    threadId,
-                                    content: x,
-                                    text: textOf(x),
-                                    ordinal,
-                                }) satisfies InferInsertModel<typeof messages>,
-                        ),
-                    )
+            const updates = incomingMessages
+                .filter((x) => existingById.has(x.id))
+                .map((message) => {
+                    const existing = existingById.get(message.id)!;
+                    return {
+                        existing,
+                        content: mergeStoredContent(existing.content, message),
+                    };
+                });
+            const now = new Date();
+            await db.transaction(async function (tx) {
+                const [thread] = await tx
+                    .select()
+                    .from(threads)
+                    .where(eq(threads.id, threadId))
+                    .limit(1)
                     .execute();
-            }
+                if (newMessages.length) {
+                    await tx
+                        .insert(messages)
+                        .values(
+                            newMessages.map(
+                                (x, ordinal) =>
+                                    ({
+                                        id: x.id,
+                                        role: x.role,
+                                        threadId,
+                                        content: x,
+                                        text: textOf(x),
+                                        ordinal,
+                                        createdAt: now,
+                                    }) satisfies InferInsertModel<typeof messages>,
+                            ),
+                        )
+                        .execute();
+                }
 
-            for (const message of incomingMessages.filter((x) => existingById.has(x.id))) {
-                const content = mergeStoredContent(existingById.get(message.id)!, message);
+                for (const { content } of updates) {
+                    await tx
+                        .update(messages)
+                        .set({ content, text: textOf(content) })
+                        .where(eq(messages.id, content.id))
+                        .execute();
+                }
 
-                await db
-                    .update(messages)
-                    .set({ content, text: textOf(content) })
-                    .where(eq(messages.id, message.id))
-                    .execute();
-            }
+                await enqueue(tx, [
+                    // A current thread.upsert leads the batch so cc's thread
+                    // row exists (and stays fresh) before its children.
+                    ...(thread ? [threadUpsertEvent(thread)] : []),
+                    ...newMessages.map((x, ordinal) =>
+                        messageUpsertEvent({
+                            threadId,
+                            message: x,
+                            text: textOf(x),
+                            ordinal,
+                            createdAt: now,
+                        }),
+                    ),
+                    // Edits keep their original timestamp and slot so the
+                    // mirrored transcript does not reorder.
+                    ...updates.map(({ existing, content }) =>
+                        messageUpsertEvent({
+                            threadId,
+                            message: content,
+                            text: textOf(content),
+                            ordinal: existing.ordinal,
+                            createdAt: existing.createdAt,
+                        }),
+                    ),
+                ]);
+            });
         },
     } satisfies DatabaseAdapter["messages"];
 }

package/src/lib/adapters/database/postgres/outbox.ts

@@ -0,0 +1,66 @@
+// fallow-ignore-file code-duplication -- mirrors ../mssql/outbox.ts by design;
+// Drizzle types query builders per dialect. See DatabaseAdapter in ../index.ts.
+import { asc, inArray } from "drizzle-orm";
+import type { SyncEvent } from "@cortex/contracts/runtime";
+import { syncMeta, syncOutbox } from "@/db/schema.pg";
+import type { DatabaseAdapter } from "@/adapters/database/index";
+import type { PostgresDb } from "./client";
+
+/** A db or one of its transactions, so a write and its events commit together. */
+type Executor = Pick<PostgresDb, "insert">;
+
+export async function enqueueSyncEvents(executor: Executor, events: SyncEvent[]) {
+    if (!events.length) return;
+    await executor
+        .insert(syncOutbox)
+        .values(events.map((event) => ({ event })))
+        .execute();
+}
+
+export function createOutboxRepository(db: PostgresDb) {
+    return {
+        enqueue: (events) => enqueueSyncEvents(db, events),
+
+        async peek(limit) {
+            return await db
+                .select({ id: syncOutbox.id, event: syncOutbox.event })
+                .from(syncOutbox)
+                .orderBy(asc(syncOutbox.id))
+                .limit(limit)
+                .execute();
+        },
+
+        async epoch() {
+            const [row] = await db
+                .select({ epoch: syncMeta.epoch })
+                .from(syncMeta)
+                .limit(1)
+                .execute();
+            if (row) return row.epoch;
+
+            // First flush on a fresh database mints its generation id: a
+            // time-ordered UUIDv7, so cc can tell a later generation from a
+            // delayed batch out of a superseded one by plain comparison. A
+            // concurrent mint loses on the primary key and reads the winner;
+            // anything else that leaves no persisted row aborts the flush
+            // rather than syncing under an epoch a restart would not repeat.
+            await db
+                .insert(syncMeta)
+                .values({ id: 1, epoch: Bun.randomUUIDv7() })
+                .onConflictDoNothing()
+                .execute();
+            const [persisted] = await db
+                .select({ epoch: syncMeta.epoch })
+                .from(syncMeta)
+                .limit(1)
+                .execute();
+            if (!persisted) throw new Error("sync_meta epoch missing after mint");
+            return persisted.epoch;
+        },
+
+        async ack(ids) {
+            if (!ids.length) return;
+            await db.delete(syncOutbox).where(inArray(syncOutbox.id, ids)).execute();
+        },
+    } satisfies DatabaseAdapter["outbox"];
+}