refactor(persistence): share pure backend guards

packages/session-persistence/src/index.ts

@@ -22,6 +22,7 @@
  */
 
 import { Context, Service } from 'cordis'
+import { isJsonValue } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionId, SessionMeta, SessionSummary } from '@deepseek-ai/dsh-session'
 
 // Re-export the metadata vocabulary so consumers import it from the seam.
@@ -33,6 +34,35 @@ declare module 'cordis' {
   }
 }
 
+/**
+ * Whether a live session's seed reproduces a persisted prefix exactly. Backends
+ * use this collision check to distinguish a legitimate resume/HMR rebind from a
+ * different live session reusing an existing session id.
+ *
+ * The comparison includes the full event payload, not just seq/type/time, so a
+ * mutated seed cannot be grafted onto a durable log with the same envelope.
+ */
+export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly SessionEvent[]): boolean {
+  return prefix.length <= seed.length
+    && prefix.every((event, index) => {
+      const seedEvent = seed[index]
+      return seedEvent !== undefined && JSON.stringify(seedEvent) === JSON.stringify(event)
+    })
+}
+
+/**
+ * Reject non-JSON-serializable event data before a backend serializes a batch.
+ * Live session appends already enforce this; persistence append paths also
+ * accept replay/fork batches that may bypass a live session instance.
+ */
+export function assertSerializable(events: readonly SessionEvent[]): void {
+  for (const event of events) {
+    if (!isJsonValue(event.data)) {
+      throw new Error(`event "${event.type}" carries non-JSON-serializable data (seq ${event.seq})`)
+    }
+  }
+}
+
 /**
  * Abstract durable session-persistence service. Subclass, implement the
  * abstract methods, and load the subclass as a plugin — it registers as

packages/session-persistence/tests/persistence.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { SessionId, isJsonValue, interruptedTurnClosers } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionMeta, SessionSummary } from '@deepseek-ai/dsh-session'
-import { SessionPersistence } from '../src/index.ts'
+import { SessionPersistence, assertSerializable, seedCoversPrefix } from '../src/index.ts'
 import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
 
 /**
@@ -104,3 +104,38 @@ describe('SessionPersistence service registration', () => {
     await fiber.dispose()
   })
 })
+
+describe('shared persistence helpers', () => {
+  it('accepts a seed that reproduces the persisted prefix exactly', () => {
+    const log = oneTurnLog()
+    expect(seedCoversPrefix(log, log.slice(0, 3))).toBe(true)
+    expect(seedCoversPrefix(log, [])).toBe(true)
+  })
+
+  it('rejects a prefix longer than the seed', () => {
+    const log = oneTurnLog()
+    expect(seedCoversPrefix(log.slice(0, 2), log)).toBe(false)
+  })
+
+  it('rejects a same-envelope event with mutated data', () => {
+    const log = oneTurnLog()
+    const tampered = structuredClone(log)
+    const event = tampered[1]!
+    tampered[1] = {
+      ...event,
+      data: { ...event.data, content: [{ type: 'text', text: 'tampered' }] },
+    } as SessionEvent
+    expect(seedCoversPrefix(tampered, log.slice(0, 2))).toBe(false)
+  })
+
+  it('accepts JSON-serializable event data', () => {
+    expect(() => { assertSerializable(oneTurnLog()) }).not.toThrow()
+  })
+
+  it('rejects non-JSON-serializable event data with type and seq context', () => {
+    const bad = [
+      { type: 'user/message', seq: 0, time: 1, data: { content: 1n } },
+    ] as unknown as SessionEvent[]
+    expect(() => { assertSerializable(bad) }).toThrow(/"user\/message".*seq 0/)
+  })
+})