refactor(session): drop the dead mutable SessionSummary

SessionSummary (updatedAt/title/firstPrompt) and SessionPersistence.update()
were dead state: zero production callers of update(), no production reader of
updatedAt/firstPrompt, and ACP's title comes from a tool-call presenter, not
storage. The live Session.header was already typed SessionHeader, so the
summary only ever existed in the persistence layer, written and read by nothing
but its own contract test.

Delete it entirely (no SessionMeta alias — SessionMeta collapses to
SessionHeader everywhere). This removes the JSONL .summary.json sidecar
machinery, the SQLite title/first_prompt/updated_at columns and per-append
updated_at bump, and the update() method from the abstract service and both
backends. SQLite SCHEMA_VERSION goes 1->2 and openDatabase now rejects any
non-current user_version (older or newer) — no migration, unreleased software.

Net -400 lines, and it erases the JSONL-sidecar-vs-SQLite-column durability
divergence that the upcoming write coordinator would otherwise have to model.

Records the decision in docs/rfc/implemented/2026-06-19-drop-mutable-session-summary.md
and migrates the 2026-06-14 session-persistence RFC's facts to current truth.
Adds a standalone AGENTS.md section "Tests document behavior, not golden truth"
(a passing test pins current behavior, not necessarily correct behavior) with
the summary-drop as its worked example, and reinforces the no-migration
pre-release stance.

packages/session-persistence/README.md

@@ -1,8 +1,8 @@
 # @deepseek-ai/dsh-session-persistence
 
-The abstract durable session-persistence seam (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, list, and update sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../docs/rfc/implemented/2026-06-13-capability-seams.md)): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
+The abstract durable session-persistence seam (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, and list sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../docs/rfc/implemented/2026-06-13-capability-seams.md)): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
 
-The persisted unit IS the existing `SessionEvent` (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage) travels separately as `SessionMeta`, owned by `dsh-session` and re-exported here.
+The persisted unit IS the existing `SessionEvent` (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage) travels separately as `SessionHeader`, owned by `dsh-session` and re-exported here.
 
 ## Service API (`ctx.sessionPersistence`)
 
@@ -11,9 +11,8 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 | `create(meta): Promise<void>` | Register a new session's metadata. MAY defer the physical write until the first `append` (lazy materialization). |
 | `append(id, events): Promise<void>` | Durably persist a batch (from the `session/flush` drain). Append-only; first event `seq` == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
 | `load(id): Promise<{ meta; events }>` | Reload meta + log. Preserves an interrupted (unclosed) final turn and closes it with synthetic closers — an error `tool/result` per unanswered `tool-call`, then `step/end?`+`turn/end {interrupted}` (a turn can be huge — never truncated); only a torn tail fragment is dropped. Events contiguous (`events[i].seq === i`); rejects a committed-region gap/parse error or unknown `version`. |
-| `list(): Promise<SessionMeta[]>` | Lightweight listing from metadata, no full-log parse. |
+| `list(): Promise<SessionHeader[]>` | Lightweight listing from metadata, no full-log parse. |
 | `has(id)` / `delete(id)` | Existence / removal. A zero-event lazily-materialized session is absent from `has`/`list`. |
-| `update(id, summary): Promise<void>` | Update mutable `SessionSummary` fields without touching the append-only log. |
 
 ## Invariants every backend must honor
 
@@ -30,4 +29,4 @@ Two backends run this suite: `dsh-session-persistence-jsonl` (append-only file l
 
 ## Metadata types
 
-Re-exported from `dsh-session`: `SessionHeader` (immutable: `version`, `id`, `createdAt`, `cwd?`, `parentSession?`), `SessionSummary` (mutable: `updatedAt`, `title?`, `firstPrompt?`), `SessionMeta` (their intersection).
+Re-exported from `dsh-session`: `SessionHeader` (immutable session metadata: `version`, `id`, `createdAt`, `cwd?`, `parentSession?`).

packages/session-persistence/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * The durable session-persistence seam (`ctx.sessionPersistence`): an abstract
  * service defining WHAT a persistence backend does — durably store, reload,
- * list, and update sessions — without saying HOW. Implementations subclass
+ * and list sessions — without saying HOW. Implementations subclass
  * {@link SessionPersistence} and register themselves as the
  * `sessionPersistence` service; `@deepseek-ai/dsh-session-persistence-jsonl`
  * (an append-only JSONL log per session) is the first and
@@ -15,7 +15,7 @@
  * parallel "persisted message" type the log must be converted to and from
  * (faithful to the event-sourced model: the log is the single source of
  * truth). Metadata that is NOT replayable conversation state (format version,
- * cwd, lineage) travels separately as {@link SessionMeta}, which is owned by
+ * cwd, lineage) travels separately as {@link SessionHeader}, which is owned by
  * `dsh-session` and re-exported here.
  *
  * @module @deepseek-ai/dsh-session-persistence
@@ -23,10 +23,10 @@
 
 import { Context, Service } from 'cordis'
 import { isJsonValue } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionId, SessionMeta, SessionSummary } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 
 // Re-export the metadata vocabulary so consumers import it from the seam.
-export type { SessionHeader, SessionSummary, SessionMeta } from '@deepseek-ai/dsh-session'
+export type { SessionHeader } from '@deepseek-ai/dsh-session'
 
 declare module 'cordis' {
   interface Context {
@@ -102,7 +102,7 @@ export abstract class SessionPersistence extends Service {
    * created-but-never-appended session is absent from {@link has}/{@link list}
    * — abandoned sessions leave nothing behind.
    */
-  abstract create(meta: SessionMeta): Promise<void>
+  abstract create(meta: SessionHeader): Promise<void>
 
   /**
    * Durably persist a batch of events (called from the write-behind drain at
@@ -114,7 +114,7 @@ export abstract class SessionPersistence extends Service {
   abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
 
   /**
-   * Reload a session: its {@link SessionMeta} plus the event log up to the last
+   * Reload a session: its {@link SessionHeader} plus the event log up to the last
    * durable checkpoint. Returns `meta` AND `events` so the live session is
    * reconstructed with its `cwd`/lineage, not just its log.
    *
@@ -135,24 +135,16 @@ export abstract class SessionPersistence extends Service {
    * unloadable (reject). Rejects an unknown format `version`. See the session-persistence RFC for
    * the crash-recovery contract.
    */
-  abstract load(id: SessionId): Promise<{ meta: SessionMeta; events: SessionEvent[] }>
+  abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 
   /** Lightweight listing from metadata, without a full-log parse. */
-  abstract list(): Promise<SessionMeta[]>
+  abstract list(): Promise<SessionHeader[]>
 
   /** Whether a session is durably present (materialized). */
   abstract has(id: SessionId): Promise<boolean>
 
   /** Remove a session and all its persisted artifacts. */
   abstract delete(id: SessionId): Promise<void>
-
-  /**
-   * Update mutable metadata ({@link SessionSummary}: `updatedAt`, `title`,
-   * `firstPrompt`) WITHOUT touching the append-only event log. A backend
-   * stores the summary beside the log (a sidecar file, a header row) and
-   * rewrites only it.
-   */
-  abstract update(id: SessionId, summary: Partial<SessionSummary>): Promise<void>
 }
 
 export default SessionPersistence

packages/session-persistence/tests/contract.ts

@@ -8,9 +8,9 @@
  * @module @deepseek-ai/dsh-session-persistence/tests/contract
  */
 
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SessionMeta } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { SessionPersistence } from '../src/index.ts'
 
@@ -20,13 +20,12 @@ export interface ContractBackend {
   dispose: () => Promise<void>
 }
 
-/** Build a minimal {@link SessionMeta} for a session id. */
-export function meta(id: string, cwd?: string): SessionMeta {
+/** Build a minimal {@link SessionHeader} for a session id. */
+export function meta(id: string, cwd?: string): SessionHeader {
   return {
     version: 1,
     id: SessionId(id),
     createdAt: 1000,
-    updatedAt: 1000,
     ...cwd !== undefined ? { cwd } : {},
   }
 }
@@ -242,31 +241,5 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         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)
-        const beforeUpdate = (await persistence.load(m.id)).meta.updatedAt
-        vi.useFakeTimers()
-        vi.setSystemTime(beforeUpdate + 1_000)
-        try {
-          await persistence.update(m.id, { title: 'My session', firstPrompt: 'hi' })
-        } finally {
-          vi.useRealTimers()
-        }
-
-        const loaded = await persistence.load(m.id)
-        expect(loaded.meta.title).toBe('My session')
-        expect(loaded.meta.firstPrompt).toBe('hi')
-        expect(loaded.meta.updatedAt).toBe(beforeUpdate + 1_000)
-        expect(loaded.events).toEqual(log) // log untouched
-      } finally {
-        await dispose()
-      }
-    })
   })
 }

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

@@ -1,7 +1,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 type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import { SessionPersistence, assertSerializable, seedCoversPrefix } from '../src/index.ts'
 import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
 
@@ -12,10 +12,10 @@ import { runPersistenceContract, meta, oneTurnLog } from './contract.ts'
  * `@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>()
+  private store = new Map<string, { meta: SessionHeader; events: SessionEvent[] }>()
+  private pending = new Map<string, SessionHeader>()
 
-  async create(m: SessionMeta): Promise<void> {
+  async create(m: SessionHeader): 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)
@@ -43,7 +43,7 @@ class MemoryPersistence extends SessionPersistence {
     }
   }
 
-  async load(id: SessionId): Promise<{ meta: SessionMeta; events: SessionEvent[] }> {
+  async load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     const entry = this.store.get(id)
     if (!entry) throw new Error(`session "${id}" not found`)
     // Honor the crash-recovery contract: if the stored log ends mid-turn, close
@@ -54,7 +54,7 @@ class MemoryPersistence extends SessionPersistence {
     return { meta: structuredClone(entry.meta), events: structuredClone(entry.events) }
   }
 
-  async list(): Promise<SessionMeta[]> {
+  async list(): Promise<SessionHeader[]> {
     return [...this.store.values()].map(e => structuredClone(e.meta))
   }
 
@@ -66,11 +66,6 @@ class MemoryPersistence extends SessionPersistence {
     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, { updatedAt: summary.updatedAt ?? Date.now() })
-  }
 }
 
 // Run the shared contract against the in-memory backend.