feat(session-persistence): abstract seam + JSONL backend + wiring

Add the durable session-persistence capability seam (ADR 0016): an
abstract SessionPersistence service (dsh-session-persistence,
ctx.sessionPersistence) defining create/append/load/list/has/delete/
update over the existing SessionEvent — no parallel persisted type — and
a first implementation (dsh-session-persistence-jsonl): an append-only
JSONL log per session with crash-safe atomic writes, truncation-repair
of a never-committed crash tail, and a read/replay path. SessionMeta
(format version, cwd, lineage) travels out-of-log via session.header.

A shared runPersistenceContract suite holds every backend to the same
append-only / contiguous-seq / lazy-materialization / serializability
semantics.

Config-driven create() now uses a per-run ${id}-session-<uuid> session
id so a fixed name no longer collides with an on-disk log once a durable
backend is loaded; each run is a new session (a demo simplification). The
examples drop their hand-rolled session-jsonl.ts and load the JSONL
backend via cordis.yml; CI smoke-loads it too.

The agent-facing create/resume factory that consumes load() is a
separate seam, deferred to a follow-up; this change stops at the load
primitive and does not reach into the loop.

packages/session-persistence/tests/contract.ts

@@ -0,0 +1,167 @@
+/**
+ * Reusable contract test for any {@link SessionPersistence} backend. A backend
+ * package imports {@link runPersistenceContract} and calls it with a factory
+ * that yields a fresh, empty backend (and a teardown), so every backend is held
+ * to the same append-only / contiguous-seq / lazy-materialization / crash
+ * semantics. The JSONL backend's own spec adds file-specific tests on top.
+ *
+ * @module @deepseek-ai/dsh-session-persistence/tests/contract
+ */
+
+import { describe, expect, it } from 'vitest'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionMeta } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '../src/index.ts'
+
+/** A backend under test plus its teardown. */
+export interface ContractBackend {
+  persistence: SessionPersistence
+  dispose: () => Promise<void>
+}
+
+/** Build a minimal {@link SessionMeta} for a session id. */
+export function meta(id: string, cwd?: string): SessionMeta {
+  return {
+    version: 1,
+    id: SessionId(id),
+    createdAt: 1000,
+    updatedAt: 1000,
+    ...cwd !== undefined ? { cwd } : {},
+  }
+}
+
+/** A well-formed one-turn event log (contiguous seqs from 0). */
+export function oneTurnLog(): SessionEvent[] {
+  return [
+    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    { type: 'user/message', seq: 1, time: 2, data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } } },
+    { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
+    { type: 'assistant/message', seq: 3, time: 4, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'hello' }] } },
+    { type: 'step/end', seq: 4, time: 5, data: { turn: 1, step: 1 } },
+    { type: 'turn/end', seq: 5, time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
+  ]
+}
+
+/**
+ * Run the backend-agnostic contract suite. `make()` MUST return a fresh, empty
+ * backend each call.
+ */
+export function runPersistenceContract(name: string, make: () => Promise<ContractBackend>): void {
+  describe(`SessionPersistence contract: ${name}`, () => {
+    it('round-trips a session: create + append → load returns identical meta and byte-identical events', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('s1', '/work')
+        const log = oneTurnLog()
+        await persistence.create(m)
+        await persistence.append(m.id, log)
+
+        const loaded = await persistence.load(m.id)
+        expect(loaded.meta).toMatchObject({ version: 1, id: m.id, cwd: '/work' })
+        expect(loaded.events).toEqual(log)
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('has()/list() exclude a created-but-never-appended (zero-event) session', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        await persistence.create(meta('empty'))
+        expect(await persistence.has(SessionId('empty'))).toBe(false)
+        expect((await persistence.list()).map(m => m.id)).not.toContain(SessionId('empty'))
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('has()/list() include a session once it has events', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('s2')
+        await persistence.create(m)
+        await persistence.append(m.id, oneTurnLog())
+        expect(await persistence.has(m.id)).toBe(true)
+        expect((await persistence.list()).map(x => x.id)).toContain(m.id)
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('append rejects a batch whose first seq does not match the stored next-seq', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('s3')
+        await persistence.create(m)
+        await persistence.append(m.id, oneTurnLog()) // seqs 0..5, next-seq = 6
+        // A re-append of an already-stored seq must be rejected, not duplicated.
+        const restated = oneTurnLog()
+        await expect(persistence.append(m.id, restated)).rejects.toThrow()
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('append rejects a mid-batch seq gap', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('s4')
+        await persistence.create(m)
+        const gapped: SessionEvent[] = [
+          { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+          { type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }, // gap: missing seq 1
+        ]
+        await expect(persistence.append(m.id, gapped)).rejects.toThrow()
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('append rejects non-JSON-serializable event data, naming the event type', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('s5')
+        await persistence.create(m)
+        // A plugin-added event carrying a BigInt (not JSON-serializable).
+        const bad = [
+          { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra: 1n } },
+        ] as unknown as SessionEvent[]
+        await expect(persistence.append(m.id, bad)).rejects.toThrow(/user\/message/)
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('delete removes a session', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('s6')
+        await persistence.create(m)
+        await persistence.append(m.id, oneTurnLog())
+        expect(await persistence.has(m.id)).toBe(true)
+        await persistence.delete(m.id)
+        expect(await persistence.has(m.id)).toBe(false)
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('update mutates summary fields without touching the event log', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('s7')
+        const log = oneTurnLog()
+        await persistence.create(m)
+        await persistence.append(m.id, log)
+        await persistence.update(m.id, { title: 'My session', firstPrompt: 'hi' })
+
+        const loaded = await persistence.load(m.id)
+        expect(loaded.meta.title).toBe('My session')
+        expect(loaded.meta.firstPrompt).toBe('hi')
+        expect(loaded.events).toEqual(log) // log untouched
+      } finally {
+        await dispose()
+      }
+    })
+  })
+}

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

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionMeta, SessionSummary } from '@deepseek-ai/dsh-session'
+import { SessionPersistence } from '../src/index.ts'
+import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
+
+/**
+ * A minimal in-memory {@link SessionPersistence} used to (a) cover the abstract
+ * base's constructor + service registration and (b) validate the reusable
+ * contract suite itself. The real durable backend is
+ * `@deepseek-ai/dsh-session-persistence-jsonl`.
+ */
+class MemoryPersistence extends SessionPersistence {
+  private store = new Map<string, { meta: SessionMeta; events: SessionEvent[] }>()
+  private pending = new Map<string, SessionMeta>()
+
+  async create(m: SessionMeta): Promise<void> {
+    // Lazy: record the intended meta, but stay absent from has/list until the
+    // first append materializes the session.
+    this.pending.set(m.id, m)
+  }
+
+  async append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
+    const existing = this.store.get(id)
+    const nextSeq = existing ? existing.events.length : 0
+    if (events.length > 0 && events[0]!.seq !== nextSeq) {
+      throw new Error(`append seq mismatch for "${id}": expected ${nextSeq}, got ${events[0]!.seq}`)
+    }
+    for (let i = 0; i < events.length; i++) {
+      const e = events[i]!
+      if (e.seq !== nextSeq + i) throw new Error(`non-contiguous seq in batch for "${id}" at index ${i}`)
+      if (containsNonSerializable(e.data)) {
+        throw new Error(`event "${e.type}" carries non-JSON-serializable data`)
+      }
+    }
+    if (!existing) {
+      const m = this.pending.get(id)
+      if (!m) throw new Error(`append before create for "${id}"`)
+      this.store.set(id, { meta: m, events: structuredClone(events) as SessionEvent[] })
+    } else {
+      existing.events.push(...structuredClone(events) as SessionEvent[])
+    }
+  }
+
+  async load(id: SessionId): Promise<{ meta: SessionMeta; events: SessionEvent[] }> {
+    const entry = this.store.get(id)
+    if (!entry) throw new Error(`session "${id}" not found`)
+    return { meta: structuredClone(entry.meta), events: structuredClone(entry.events) }
+  }
+
+  async list(): Promise<SessionMeta[]> {
+    return [...this.store.values()].map(e => structuredClone(e.meta))
+  }
+
+  async has(id: SessionId): Promise<boolean> {
+    return this.store.has(id)
+  }
+
+  async delete(id: SessionId): Promise<void> {
+    this.store.delete(id)
+    this.pending.delete(id)
+  }
+
+  async update(id: SessionId, summary: Partial<SessionSummary>): Promise<void> {
+    const entry = this.store.get(id)
+    if (entry) Object.assign(entry.meta, summary)
+  }
+}
+
+/** Detect BigInt (and other JSON-hostile values) in event data. */
+function containsNonSerializable(value: unknown): boolean {
+  if (typeof value === 'bigint' || typeof value === 'function' || typeof value === 'symbol') return true
+  if (value && typeof value === 'object') {
+    return Object.values(value).some(containsNonSerializable)
+  }
+  return false
+}
+
+// Run the shared contract against the in-memory backend.
+runPersistenceContract('memory', async () => {
+  const ctx = new Context()
+  const fiber = await ctx.plugin(MemoryPersistence)
+  return {
+    persistence: ctx.sessionPersistence,
+    dispose: async () => { await fiber.dispose() },
+  }
+})
+
+describe('SessionPersistence service registration', () => {
+  it('registers as ctx.sessionPersistence and is removed on fiber dispose (HMR safety)', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(MemoryPersistence)
+    expect(ctx.sessionPersistence).toBeInstanceOf(SessionPersistence)
+
+    await fiber.dispose()
+    expect(ctx.sessionPersistence).toBeUndefined()
+  })
+
+  it('round-trips through the registered service instance', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(MemoryPersistence)
+    const m = meta('reg')
+    await ctx.sessionPersistence.create(m)
+    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+    const loaded = await ctx.sessionPersistence.load(m.id)
+    expect(loaded.events).toHaveLength(6)
+    await fiber.dispose()
+  })
+})