docs(copilot): document seq concurrent-append window; make test mock explicit

Address PR review:
- Expand appendCopilotChatMessages JSDoc to spell out the non-atomic
  MAX(seq)+INSERT window: distinct concurrent appends can tie seq, which is
  bounded/benign because the cutover read order (seq, created_at, id) resolves
  ties and replaceCopilotChatMessages re-densifies from authoritative JSONB
  order. A per-chat lock is unwarranted (copilot turns are serialized).
- Make the "no prior rows" test mock MAX(seq)=NULL explicitly instead of
  relying on the chain mock's implicit empty-array default.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: waleedlatif1

apps/sim/lib/copilot/chat/messages-dual-write.test.ts

@@ -73,6 +73,11 @@ describe('messages-dual-write', () => {
     })
 
     it('assigns seq as 0-based array index when the chat has no prior rows', async () => {
+      // MAX(seq) over a chat with no rows returns NULL in Postgres; mock the
+      // select().from().where() chain explicitly so the base=0 path is not
+      // relying on the chain mock's implicit empty-array default.
+      dbChainMockFns.where.mockResolvedValueOnce([{ maxSeq: null }])
+
       await appendCopilotChatMessages('chat-1', [userMsg, assistantMsg])
       const rows = lastValuesRows()
       expect(rows[0].seq).toBe(0)

apps/sim/lib/copilot/chat/messages-dual-write.ts

@@ -48,6 +48,19 @@ function toRow(
  * Append messages to the new `copilot_messages` table. Best-effort — errors
  * are logged but never thrown, since the legacy `copilot_chats.messages`
  * JSONB column remains the source of truth during the dual-write rollout.
+ *
+ * Ordering: `seq` is computed as `MAX(seq) + array index` from a non-atomic
+ * read-then-insert. Two appends to the same chat that interleave (both reading
+ * the same `MAX(seq)` before either inserts) can assign overlapping `seq` to
+ * distinct new messages — the `COALESCE` conflict guard only protects re-sends
+ * of an existing `(chat_id, message_id)`, not genuinely new rows. This is an
+ * accepted, bounded window, not a correctness hole, because both read sides
+ * cover it: the cutover read order is `seq, created_at, id` (so a `seq` tie
+ * still resolves deterministically by time then id), and `replaceCopilotChatMessages`
+ * re-densifies `seq` from the authoritative JSONB order on the next snapshot
+ * save. A per-chat lock would close the window but is unwarranted for a
+ * best-effort shadow write — copilot turns for a single chat are effectively
+ * serialized (one stream at a time), so true concurrent appends are rare.
  */
 export async function appendCopilotChatMessages(
   chatId: string,