@sparkelf/dsh-plus 0.2.1-rc.2.4 → 0.2.2-alpha.2.10

package/patches/image-offload-hoist-replay.patch

@@ -0,0 +1,533 @@
+diff --git a/packages/compaction/compaction-image-offload/src/project-message.ts b/packages/compaction/compaction-image-offload/src/project-message.ts
+index 17116ffb..70913316 100644
+--- a/packages/compaction/compaction-image-offload/src/project-message.ts
++++ b/packages/compaction/compaction-image-offload/src/project-message.ts
+@@ -5,23 +5,51 @@ import { deepFreeze } from '@deepseek-ai/dsh-util-values'
+ 
+ /**
+  * Project selected image occurrences to immutable offloaded blocks.
++ *
++ * Occurrence indexes are recorded against the message the deciding request saw,
++ * which is the *projected* message. Two things make a durable message's image
++ * list differ from that one:
++ *
++ * - `image/hoist` moves tool-result images onto an earlier user carrier, so a
++ *   reader that does not mount that projection sees the images at their original
++ *   positions; the recorded indexes then resolve to different images or to none.
++ * - The same projection may run again and move images further.
++ *
++ * `positionsAreAuthoritative` therefore separates the two situations. A log with
++ * no hoist decision is folded identically everywhere, and a selection that does
++ * not resolve there is a writer bug that must fail loudly. A log that does carry
++ * hoist decisions has projection-dependent positions, and refusing to replay it
++ * would make the session permanently unreadable to every host that does not mount
++ * the plugin that wrote those rows — strictly worse than leaving an image
++ * unsuppressed, and the reason those rows are recorded as `ignorable`.
+  * @param message - message projected before this decision.
+  * @param indexes - nonempty, strictly increasing depth-first image indexes.
+- * @returns an immutable message with the same identity and selected images marked.
+- * @throws when a selected occurrence is missing or already offloaded.
++ * @param positionsAreAuthoritative - whether every recorded index must resolve.
++ * @returns an immutable message with the same identity and every resolvable selected image marked.
++ * @throws when positions are authoritative and a selected occurrence is missing or already offloaded.
+  */
+-export function offloadMessageImages(message: Message, indexes: readonly number[]): Message {
++export function offloadMessageImages(
++  message: Message,
++  indexes: readonly number[],
++  positionsAreAuthoritative = true,
++): Message {
++  const selected = new Set(indexes)
+   let imageIndex = 0
+-  let selected = 0
++  let applied = 0
+   const visit = (blocks: readonly ContentBlock[]): ContentBlock[] => {
+     let next: ContentBlock[] | undefined
+     for (const [index, block] of blocks.entries()) {
+       let projected = block
+       if (block.type === 'image') {
+-        if (imageIndex === indexes[selected]) {
+-          if (block.offloaded === true) throw new Error(`image/offload: image index ${imageIndex} is already offloaded`)
+-          projected = { ...block, offloaded: true }
+-          selected += 1
++        if (selected.has(imageIndex)) {
++          if (block.offloaded === true) {
++            if (positionsAreAuthoritative) {
++              throw new Error(`image/offload: image index ${imageIndex} is already offloaded`)
++            }
++          } else {
++            projected = { ...block, offloaded: true }
++          }
++          applied += 1
+         }
+         imageIndex += 1
+       }
+@@ -31,6 +59,9 @@ export function offloadMessageImages(message: Message, indexes: readonly number[
+     return next ?? blocks as ContentBlock[]
+   }
+   const content = visit(message.content)
+-  if (selected !== indexes.length) throw new Error(`image/offload: image index ${indexes[selected]} does not exist`)
++  if (positionsAreAuthoritative && applied !== indexes.length) {
++    throw new Error(`image/offload: image index ${indexes[applied]} does not exist`)
++  }
++  if (applied === 0) return message
+   return deepFreeze({ ...message, content })
+ }
+diff --git a/packages/compaction/compaction-image-offload/src/projection.ts b/packages/compaction/compaction-image-offload/src/projection.ts
+index 1dd0e81b..ce88e9a4 100644
+--- a/packages/compaction/compaction-image-offload/src/projection.ts
++++ b/packages/compaction/compaction-image-offload/src/projection.ts
+@@ -36,6 +36,22 @@ function isIndex(value: unknown): value is SessionSeq {
+   return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0)
+ }
+ 
++/**
++ * Whether this log carries `image/hoist` decisions.
++ *
++ * Those decisions move tool-result images onto an earlier user carrier at request
++ * time without rewriting the durable message, so a recorded `image/offload`
++ * selection counts occurrences in a shape that only exists while that projection
++ * is mounted. Reading such a log without it must skip unresolvable positions
++ * instead of refusing the session; a log with no hoist decision folds identically
++ * everywhere, and there an unresolvable selection stays a hard error.
++ * @param events - contiguous event window supplied to the fold.
++ * @returns whether any event in the window is an image/hoist decision.
++ */
++function carriesHoistDecisions(events: readonly { type: string }[]): boolean {
++  return events.some(event => event.type === 'image/hoist')
++}
++
+ /** Atomic validation and reconstruction shared by live sessions and detached replay. */
+ export const imageOffloadProjection: SessionMessageProjection<'image/offload'> = {
+   type: 'image/offload',
+@@ -46,6 +62,7 @@ export const imageOffloadProjection: SessionMessageProjection<'image/offload'> =
+     }
+     const messages = new Map<SessionSeq, Message>()
+     const nodes = new Set(context.nodes)
++    const positionsAreAuthoritative = !carriesHoistDecisions(context.events)
+     for (const target of data['targets'] as unknown[]) {
+       if (!isRecord(target) || Object.keys(target).length !== 2 || !isIndex(target['seq'])
+         || !Array.isArray(target['imageIndexes']) || target['imageIndexes'].length === 0) {
+@@ -67,7 +84,7 @@ export const imageOffloadProjection: SessionMessageProjection<'image/offload'> =
+       }
+       const message = context.messages.get(seq)
+         ?? (source.type === 'user/message' ? source.data : source.data.message)
+-      messages.set(seq, offloadMessageImages(message, target['imageIndexes'] as number[]))
++      messages.set(seq, offloadMessageImages(message, target['imageIndexes'] as number[], positionsAreAuthoritative))
+     }
+     return messages
+   },
+diff --git a/packages/compaction/compaction-image-offload/tests/projection.spec.ts b/packages/compaction/compaction-image-offload/tests/projection.spec.ts
+index 0c82575d..e3217782 100644
+--- a/packages/compaction/compaction-image-offload/tests/projection.spec.ts
++++ b/packages/compaction/compaction-image-offload/tests/projection.spec.ts
+@@ -137,4 +137,49 @@ describe('durable image selections', () => {
+     }, { surfaceOp: 'append' })
+     expect(() => session.append('image/offload', { targets: [{ seq: assistant.seq, imageIndexes: [0] }] })).toThrow(/must be user\/message/)
+   })
++
++  // A hoist decision moves tool-result images onto an earlier user carrier at request time
++  // without rewriting the durable message, so the positions a later offload counted only
++  // exist while that projection is mounted. A reader without it must still open the log.
++  const hoistRow = (seq: number): SessionEvent => ({
++    type: 'image/hoist',
++    seq: SessionSeq(seq),
++    time: 0,
++    data: { targets: [{ targetSeq: 0, userSeq: 0 }] },
++    ignorable: true,
++  } as unknown as SessionEvent)
++
++  it('skips unresolvable positions when the log carries hoist decisions', () => {
++    const session = createSession(SessionId('hoisted'))
++    const source = input(session)
++    const events = session.snapshotEvents()
++    // The recorded selection indexes the hoisted shape: the durable message has two
++    // images and the selection names only index 0, which still resolves, while index 5
++    // (the shape the hoisted carrier had) does not.
++    const recorded = {
++      type: 'image/offload',
++      seq: SessionSeq(events.length + 1),
++      time: 0,
++      data: { targets: [{ seq: source.seq, imageIndexes: [0, 5] }] },
++    } as unknown as SessionEvent
++    const withHoist = [...events, hoistRow(events.length), recorded]
++    // Catalog-only fold: index 5 is unresolvable, so it is skipped rather than fatal.
++    const fold = foldSurface(withHoist, [imageOffloadProjection])
++    const projected = deriveEventMessage(source, fold.projectedMessages)
++    expect(projected?.content.filter(block => block.type === 'image').map(block => block.type === 'image' && block.offloaded === true))
++      .toEqual([true, false])
++  })
++
++  it('keeps an unresolvable selection fatal without hoist decisions', () => {
++    const session = createSession(SessionId('no-hoist'))
++    input(session)
++    const events = session.snapshotEvents()
++    const recorded = {
++      type: 'image/offload',
++      seq: SessionSeq(events.length),
++      time: 0,
++      data: { targets: [{ seq: SessionSeq(0), imageIndexes: [0, 5] }] },
++    } as unknown as SessionEvent
++    expect(() => foldSurface([...events, recorded], [imageOffloadProjection])).toThrow(/does not exist/)
++  })
+ })
+diff --git a/packages/session-query/session-query-sqlite/src/index.ts b/packages/session-query/session-query-sqlite/src/index.ts
+index 7c95afa2..97d1763e 100644
+--- a/packages/session-query/session-query-sqlite/src/index.ts
++++ b/packages/session-query/session-query-sqlite/src/index.ts
+@@ -9,11 +9,12 @@ import { SESSION_FORMAT_VERSION, SessionSeq } from '@deepseek-ai/dsh-session'
+ import type { DatabaseSync } from 'node:sqlite'
+ import { Context, Service, type Fiber } from '@deepseek-ai/cordis'
+ import z from '@deepseek-ai/schemastery'
+-import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
++import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset, SessionMessageProjection } from '@deepseek-ai/dsh-session'
+ import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+-import type {
+-  SessionPersistenceRevision,
+-  SessionPersistenceSnapshot,
++import {
++  SessionFormatUnsupportedError,
++  type SessionPersistenceRevision,
++  type SessionPersistenceSnapshot,
+ } from '@deepseek-ai/dsh-session-persistence'
+ import SessionQueryEngine, {
+   SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
+@@ -24,6 +25,7 @@ import SessionQueryEngine, {
+   assertSessionHeadersCompatible,
+   buildSessionEventSearchDocuments,
+   readColdSessionLog,
++  type ColdSessionLog,
+ } from '@deepseek-ai/dsh-session-query'
+ import type {
+   Config as SessionQueryConfig,
+@@ -519,10 +521,27 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
+             // live-preferred.
+             if (initiallyLive.has(entry.header.id) || this.ctx.sessions.get(entry.header.id) !== undefined) continue
+             assertNotAborted(signal)
+-            const loaded = await readColdSessionLog(persistence, entry.header.id, signal)
++            let loaded: ColdSessionLog
++            try {
++              loaded = await readColdSessionLog(persistence, entry.header.id, signal)
++            } catch (readError: unknown) {
++              // A session whose stored log cannot be migrated is not indexable,
++              // but it must not stop every other session from being indexed: one
++              // unreadable log would otherwise fail content search on every
++              // attempt, forever. Leave it out of this pass.
++              if (!(readError instanceof SessionFormatUnsupportedError)) throw readError
++              continue
++            }
+             assertNotAborted(signal)
+             assertSessionHeadersCompatible(entry.header, loaded.header)
+-            entry.loaded = observeSession(loaded.header, loaded.inheritedEventCount, loaded.events)
++            entry.loaded = observeSession(loaded.header, loaded.inheritedEventCount, loaded.events, this.replayMessageProjections)
++            // Publish this session before reading the next one. The first pass
++            // over a large history reads every log, so deferring the write until
++            // the whole corpus is observed means an interrupt discards all of it
++            // and the next search repeats the same work forever. Committing per
++            // session keeps earlier progress, and the revision check above skips
++            // whatever is already indexed on the next attempt.
++            this._persistObservedSession(entry.loaded, entry.revision)
+           }
+           assertNotAborted(signal)
+           const afterSnapshots = await persistence.list(listOptions)
+@@ -547,7 +566,7 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
+       }
+       const live = new Map<SessionId, ObservedSession>()
+       for (const session of this.ctx.sessions.list()) {
+-        const observed = observeLive(session)
++        const observed = observeLive(session, this.replayMessageProjections)
+         const durable = persisted.get(session.id)
+         if (durable !== undefined) assertSessionHeadersCompatible(observed.header, durable.header)
+         live.set(session.id, observed)
+@@ -613,6 +632,34 @@ export class SqliteSessionQueryEngine extends SessionQueryEngine {
+     }
+   }
+ 
++  /**
++   * Index one observed session in its own transaction.
++   *
++   * Called while the corpus is being read rather than after it, so a first pass
++   * that is interrupted keeps every session it already indexed. The next pass
++   * skips those by revision and continues where this one stopped.
++   * @param entry - the observed session and its parsed documents.
++   * @param revision - the persistence revision the entry was read at.
++   */
++  private _persistObservedSession(entry: ObservedSession, revision: SessionPersistenceRevision): void {
++    const db = this._requireDb()
++    const generation = this._mainGeneration() + 1
++    db.exec('BEGIN IMMEDIATE')
++    try {
++      this._replacePersistedSession(entry, revision, generation)
++      db.prepare('UPDATE search_state SET global_generation = ? WHERE singleton = 1').run(generation)
++      db.exec('COMMIT')
++    } catch (error: unknown) {
++      try {
++        db.exec('ROLLBACK')
++      } catch {
++        // The write failure is the actionable cause; a rollback failure on the
++        // same broken transaction adds nothing.
++      }
++      throw error
++    }
++  }
++
+   private _replaceLiveSession(entry: ObservedSession, generation: number, persisted: boolean): void {
+     this._deleteSession('live', entry.header.id)
+     const db = this._requireDb()
+@@ -868,22 +915,23 @@ function selectedDocumentsParams(query: string, persistenceVisible: boolean): Ar
+   ]
+ }
+ 
+-function observeLive(session: Session): ObservedSession {
++function observeLive(session: Session, projections: readonly SessionMessageProjection[]): ObservedSession {
+   // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+-  return observeSession(session.header, session.inheritedEventCount, session.snapshotEvents())
++  return observeSession(session.header, session.inheritedEventCount, session.snapshotEvents(), projections)
+ }
+ 
+ function observeSession(
+   header: SessionHeader,
+   inheritedEventCount: SessionLogOffset,
+   events: readonly SessionEvent[],
++  projections: readonly SessionMessageProjection[],
+ ): ObservedSession {
+   const detachedHeader = structuredClone(header)
+   const detachedEvents = events.map(event => structuredClone(event))
+   return {
+     header: detachedHeader,
+     inheritedEventCount,
+-    documents: buildSessionEventSearchDocuments(detachedHeader.id, detachedEvents),
++    documents: buildSessionEventSearchDocuments(detachedHeader.id, detachedEvents, projections),
+     fingerprint: createHash('sha256')
+       .update(JSON.stringify({ header: detachedHeader, inheritedEventCount, events: detachedEvents }))
+       .digest('base64url'),
+diff --git a/packages/session-query/session-query/src/documents.ts b/packages/session-query/session-query/src/documents.ts
+index 8788c8ea..d191b9cc 100644
+--- a/packages/session-query/session-query/src/documents.ts
++++ b/packages/session-query/session-query/src/documents.ts
+@@ -2,7 +2,7 @@
+ 
+ import { currentSessionMessageProjections } from '@deepseek-ai/dsh-session-format-catalog/message-projections'
+ import { foldSurface } from '@deepseek-ai/dsh-session'
+-import type { SessionEvent, SessionId, SessionSeq } from '@deepseek-ai/dsh-session'
++import type { SessionEvent, SessionId, SessionMessageProjection, SessionSeq } from '@deepseek-ai/dsh-session'
+ import type { SessionEventRecord, SessionEventSearchDocument, SessionEventSurface } from './types.ts'
+ import { SessionQueryError } from './config.ts'
+ import { extractSessionEventText } from './extraction.ts'
+@@ -11,13 +11,15 @@ import { extractSessionEventText } from './extraction.ts'
+  * Project a raw log into lightweight surface-aware event records.
+  * @param sessionId - session that owns the log.
+  * @param events - complete contiguous raw event log.
++ * @param projections - replay definitions this log was written under; catalog-only when omitted.
+  * @returns one record per event in ascending seq order.
+  */
+ export function buildSessionEventRecords(
+   sessionId: SessionId,
+   events: readonly SessionEvent[],
++  projections: readonly SessionMessageProjection[] = currentSessionMessageProjections,
+ ): SessionEventRecord[] {
+-  const surfaceBySeq = classifySurface(events)
++  const surfaceBySeq = classifySurface(events, projections)
+   return events.map(event => ({
+     sessionId,
+     seq: event.seq,
+@@ -31,13 +33,15 @@ export function buildSessionEventRecords(
+  * Build first-party semantic documents for one complete raw event log.
+  * @param sessionId - session that owns the log.
+  * @param events - complete contiguous raw event log.
++ * @param projections - replay definitions this log was written under; catalog-only when omitted.
+  * @returns searchable documents in ascending seq order; structural events are omitted.
+  */
+ export function buildSessionEventSearchDocuments(
+   sessionId: SessionId,
+   events: readonly SessionEvent[],
++  projections: readonly SessionMessageProjection[] = currentSessionMessageProjections,
+ ): SessionEventSearchDocument[] {
+-  const surfaceBySeq = classifySurface(events)
++  const surfaceBySeq = classifySurface(events, projections)
+   const documents: SessionEventSearchDocument[] = []
+   for (const event of events) {
+     const text = extractSessionEventText(event)
+@@ -54,10 +58,13 @@ export function buildSessionEventSearchDocuments(
+   return documents
+ }
+ 
+-function classifySurface(events: readonly SessionEvent[]): Map<SessionSeq, SessionEventSurface> {
++function classifySurface(
++  events: readonly SessionEvent[],
++  projections: readonly SessionMessageProjection[],
++): Map<SessionSeq, SessionEventSurface> {
+   let folded: ReturnType<typeof foldSurface>
+   try {
+-    folded = foldSurface(events, currentSessionMessageProjections)
++    folded = foldSurface(events, projections)
+   } catch (error: unknown) {
+     throw new SessionQueryError(
+       /* v8 ignore next -- foldSurface throws Error instances */
+diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
+index 838ce4c7..83b105fe 100644
+--- a/packages/session-query/session-query/src/index.ts
++++ b/packages/session-query/session-query/src/index.ts
+@@ -11,6 +11,7 @@ import {
+   SessionSeq,
+   snapshotSessionEvent,
+   type SessionId,
++  type SessionMessageProjection,
+   type SessionSeq as SessionSeqType,
+ } from '@deepseek-ai/dsh-session'
+ import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+@@ -131,6 +132,27 @@ export abstract class SessionQueryEngine extends Service {
+     this._observations = new SessionObservationReader(ctx, preparedSessionCacheSize)
+   }
+ 
++  /**
++   * Resolve the message projections a detached read must replay.
++   *
++   * A log is interpreted by whichever projections were mounted when its durable
++   * decisions were written, so a cold read must use the mounted set rather than
++   * the first-party catalog alone. Replaying with only the catalog is what makes
++   * an `image/offload` decision recorded against an already-hoisted message
++   * throw on a later read: `image/hoist` moved those image occurrences onto an
++   * earlier carrier, so the recorded depth-first indexes no longer resolve.
++   *
++   * Catalog definitions are kept first; a live contribution of the same event
++   * type is dropped because the fold rejects duplicate ownership anyway.
++   * @returns borrowed catalog definitions followed by live plugin contributions.
++   */
++  protected get replayMessageProjections(): readonly SessionMessageProjection[] {
++    const live = this.ctx.sessions.messageProjections
++    if (live.length === 0) return currentSessionMessageProjections
++    const seen = new Set(currentSessionMessageProjections.map(projection => projection.type))
++    return [...currentSessionMessageProjections, ...live.filter(projection => !seen.has(projection.type))]
++  }
++
+   /**
+    * Observe one exact live or prepared Session without a persistence listing preflight.
+    * @param sessionId - logical Session identity.
+@@ -188,7 +210,7 @@ export abstract class SessionQueryEngine extends Service {
+       loaded.events,
+       loaded.header,
+       loaded.inheritedEventCount,
+-      currentSessionMessageProjections,
++      this.replayMessageProjections,
+     )
+     return {
+       session: structuredClone(loaded.header),
+@@ -268,7 +290,7 @@ export abstract class SessionQueryEngine extends Service {
+    */
+   async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]> {
+     const loaded = await this._corpus.load(sessionId)
+-    return tracing.eventRecords(sessionId, loaded.events)
++    return tracing.eventRecords(sessionId, loaded.events, this.replayMessageProjections)
+   }
+ 
+   /**
+@@ -297,7 +319,7 @@ export abstract class SessionQueryEngine extends Service {
+     filters: readonly SessionEventResultFilter[],
+   ): Promise<SessionEventSearchDocument[]> {
+     const loaded = await this._corpus.load(sessionId)
+-    const documents = buildSessionEventSearchDocuments(sessionId, loaded.events)
++    const documents = buildSessionEventSearchDocuments(sessionId, loaded.events, this.replayMessageProjections)
+     return filterSessionEventDocuments(documents, filters)
+   }
+ 
+@@ -313,7 +335,7 @@ export abstract class SessionQueryEngine extends Service {
+       session: structuredClone(loaded.header),
+       inheritedEventCount: loaded.inheritedEventCount,
+       capturedThroughSeq: loaded.events.at(-1)?.seq ?? null,
+-      events: tracing.currentSurfaceEvents(sessionId, loaded.events),
++      events: tracing.currentSurfaceEvents(sessionId, loaded.events, this.replayMessageProjections),
+     }
+   }
+ 
+@@ -342,7 +364,7 @@ export abstract class SessionQueryEngine extends Service {
+     signal?.throwIfAborted()
+     return {
+       session: loaded.header,
+-      ...tracing.traceEvent(request.sessionId, loaded.events, request.seq),
++      ...tracing.traceEvent(request.sessionId, loaded.events, request.seq, this.replayMessageProjections),
+     }
+   }
+ 
+diff --git a/packages/session-query/session-query/src/tracing.ts b/packages/session-query/session-query/src/tracing.ts
+index 0cd3fccf..3388e22a 100644
+--- a/packages/session-query/session-query/src/tracing.ts
++++ b/packages/session-query/session-query/src/tracing.ts
+@@ -5,6 +5,7 @@ import { foldSurface, isSurfaceEvent, snapshotSessionEvent } from '@deepseek-ai/
+ import type {
+   SessionEvent,
+   SessionId,
++  SessionMessageProjection,
+   SessionSeq,
+   SurfaceEvent,
+ } from '@deepseek-ai/dsh-session'
+@@ -28,26 +29,30 @@ interface EventLogAnalysis {
+  * Classify a raw event log with one canonical surface fold.
+  * @param sessionId - owner of the event log.
+  * @param events - detached raw event log.
++ * @param projections - replay definitions this log was written under; catalog-only when omitted.
+  * @returns lightweight records in ascending log order.
+  */
+ export function eventRecords(
+   sessionId: SessionId,
+   events: readonly SessionEvent[],
++  projections: readonly SessionMessageProjection[] = currentSessionMessageProjections,
+ ): SessionEventRecord[] {
+-  return analyzeEventLog(sessionId, events).records
++  return analyzeEventLog(sessionId, events, projections).records
+ }
+ 
+ /**
+  * Fold and return the current model surface after validating the whole log.
+  * @param sessionId - owner used in query diagnostics.
+  * @param events - detached raw event log from one corpus observation.
++ * @param projections - replay definitions this log was written under; catalog-only when omitted.
+  * @returns detached current surface events in folded order.
+  */
+ export function currentSurfaceEvents(
+   sessionId: SessionId,
+   events: readonly SessionEvent[],
++  projections: readonly SessionMessageProjection[] = currentSessionMessageProjections,
+ ): SurfaceEvent[] {
+-  const analysis = analyzeEventLog(sessionId, events)
++  const analysis = analyzeEventLog(sessionId, events, projections)
+   return analysis.currentSeqs.map((seq) => {
+     const event = events[seq]
+     /* v8 ignore next 6 -- analyzeEventLog validated contiguous seqs and foldSurface returned only surface-event seqs. */
+@@ -66,12 +71,14 @@ export function currentSurfaceEvents(
+  * @param sessionId - owner of the event log.
+  * @param events - detached raw event log.
+  * @param seq - target event seq.
++ * @param projections - replay definitions this log was written under; catalog-only when omitted.
+  * @returns direct surface replacements and relationships to cited source events.
+  */
+ export function traceEvent(
+   sessionId: SessionId,
+   events: readonly SessionEvent[],
+   seq: SessionSeq,
++  projections: readonly SessionMessageProjection[] = currentSessionMessageProjections,
+ ): SessionEventTrace {
+   const target = events[seq]
+   if (target === undefined || target.seq !== seq) {
+@@ -81,7 +88,7 @@ export function traceEvent(
+     )
+   }
+ 
+-  const analysis = analyzeEventLog(sessionId, events)
++  const analysis = analyzeEventLog(sessionId, events, projections)
+ 
+   const replacementChain: SessionSeq[] = []
+   let replacement = analysis.replacedBy.get(seq)
+@@ -181,10 +188,11 @@ export function traceSession(
+ function analyzeEventLog(
+   sessionId: SessionId,
+   events: readonly SessionEvent[],
++  projections: readonly SessionMessageProjection[],
+ ): EventLogAnalysis {
+   let folded: ReturnType<typeof foldSurface>
+   try {
+-    folded = foldSurface(events, currentSessionMessageProjections)
++    folded = foldSurface(events, projections)
+   } catch (error: unknown) {
+     throw new SessionQueryError(
+       /* v8 ignore next -- foldSurface throws Error instances */

package/patches/legacy-code-preset.patch

@@ -0,0 +1,148 @@
+diff --git a/packages/api/session-controller/src/agent.ts b/packages/api/session-controller/src/agent.ts
+index d16e041773..41b6b4a0d1 100644
+--- a/packages/api/session-controller/src/agent.ts
++++ b/packages/api/session-controller/src/agent.ts
+@@ -13,6 +13,9 @@ import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-ses
+ import { RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
+ import type {} from '@deepseek-ai/dsh-typert-registry'
+ 
++const LEGACY_PTC_PRESET = 'code'
++const PTC_PRESET = 'ptc'
++
+ /** Cold Session identity absent from persistence. */
+ export class ApiSessionNotFound extends Error {}
+ 
+@@ -273,7 +276,15 @@ export class ApiSessionAgentController {
+     if (presets === undefined) {
+       return { setup: (agentCtx) => { installModelSelection(agentCtx) } }
+     }
+-    const resolvedId = (await presets.resolve(presetId)).id
++    let resolved
++    try {
++      resolved = await presets.resolve(presetId)
++    } catch (error: unknown) {
++      if (presetId !== LEGACY_PTC_PRESET
++        || remoteErrorOf(error)?.code !== 'agent-preset/not-found') throw error
++      resolved = await presets.resolve(PTC_PRESET)
++    }
++    const resolvedId = resolved.id
+     return {
+       agentPreset: resolvedId,
+       setup: async (agentCtx) => {
+diff --git a/packages/api/session-controller/tests/agent.host.spec.ts b/packages/api/session-controller/tests/agent.host.spec.ts
+index aea96d5e04..3a37fcbbc0 100644
+--- a/packages/api/session-controller/tests/agent.host.spec.ts
++++ b/packages/api/session-controller/tests/agent.host.spec.ts
+@@ -10,6 +10,7 @@ import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/ds
+ import type { SessionHeader } from '@deepseek-ai/dsh-session'
+ import { SessionAlreadyOwnedError } from '@deepseek-ai/dsh-session-persistence'
+ import type { SessionObservation } from '@deepseek-ai/dsh-session-query'
++import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+ import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+ import { afterEach, describe, expect, it, vi } from 'vitest'
+ import {
+@@ -262,4 +263,61 @@ describe('ApiSession creation', () => {
+     await expect(agents.createSession({ cwd: join(file, 'child'), reusable: () => true }))
+       .rejects.toThrow('failed to ensure project directory')
+   })
++  it('resumes a persisted legacy code session through the ptc composition', async () => {
++    const { ctx, agents } = await harness()
++    const meta = { ...header('stored-legacy-code'), agentPreset: 'code' }
++    providePersistence(ctx, {
++      list: () => Promise.resolve([meta]),
++      inspect: () => Promise.resolve({ meta, events: [] }),
++    })
++    const resolve = vi.fn((id?: string) => id === 'code'
++      ? Promise.reject(new RemoteError(
++        'agent-preset/not-found',
++        'code is no longer shipped',
++        { agentPreset: 'code', available: ['ptc'] },
++      ))
++      : Promise.resolve({ id: id ?? 'ptc' }))
++    ctx.provide('agentPresets', { resolve, mount: () => Promise.resolve() } as never)
++    const resumed = {
++      id: meta.id,
++      session: { id: meta.id, header: meta, events: [] },
++      status: 'idle',
++      ctx,
++    } as unknown as Agent
++    vi.spyOn(ctx.agents, 'resume').mockResolvedValue({
++      agent: resumed,
++      dispose: () => Promise.resolve(),
++    })
++
++    await expect(agents.resolveAgent(meta.id)).resolves.toEqual({ agent: resumed })
++    expect(resolve).toHaveBeenNthCalledWith(1, 'code')
++    expect(resolve).toHaveBeenNthCalledWith(2, 'ptc')
++    expect(resumed.session.header.agentPreset).toBe('code')
++  })
++
++
++  it('falls back from a missing legacy code preset to ptc', async () => {
++    const { ctx, agents } = await harness()
++    const resolve = vi.fn((id?: string) => id === 'code'
++      ? Promise.reject(new RemoteError(
++        'agent-preset/not-found',
++        'code is no longer shipped',
++        { agentPreset: 'code', available: ['ptc'] },
++      ))
++      : Promise.resolve({ id: id ?? 'ptc' }))
++    ctx.provide('agentPresets', { resolve, mount: () => Promise.resolve() } as never)
++
++    await expect(agents.composeAgent('code')).resolves.toMatchObject({ agentPreset: 'ptc' })
++    expect(resolve).toHaveBeenNthCalledWith(1, 'code')
++    expect(resolve).toHaveBeenNthCalledWith(2, 'ptc')
++  })
++
++  it('prefers an explicitly available code preset over the ptc fallback', async () => {
++    const { ctx, agents } = await harness()
++    const resolve = vi.fn((id?: string) => Promise.resolve({ id: id ?? 'ptc' }))
++    ctx.provide('agentPresets', { resolve, mount: () => Promise.resolve() } as never)
++
++    await expect(agents.composeAgent('code')).resolves.toMatchObject({ agentPreset: 'code' })
++    expect(resolve).toHaveBeenCalledExactlyOnceWith('code')
++  })
+ })
+diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx
+index 26fdcfcbf6..25dd5a95bc 100644
+--- a/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx
++++ b/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx
+@@ -19,6 +19,8 @@ import type { AgentPresetSettingsState } from './settings-store.ts'
+ import { presetDisplayText } from './locales.ts'
+ import css from './AgentPresetLabel.module.css'
+ 
++const LEGACY_PTC_PRESET = 'code'
++
+ /** Registration-side business face for the header label. */
+ export interface AgentPresetLabelInjected {
+   hooks: {
+@@ -59,10 +61,11 @@ export function AgentPresetLabel({
+ 
+   const option = options.find(entry => entry.id === preset)
+   const text = option === undefined ? undefined : presetDisplayText(option, t)
++  const name = text?.name ?? (preset === LEGACY_PTC_PRESET ? t('presetPtcName') : preset)
+   return (
+     <span className={css.label} title={text?.description ?? t('headerHint')}>
+       <IconAgentPresetOutlineRegular size={14} className={css.icon} />
+-      {text?.name ?? preset}
++      {name}
+     </span>
+   )
+ }
+diff --git a/packages/client/ui-agent-preset/tests/components.client.spec.tsx b/packages/client/ui-agent-preset/tests/components.client.spec.tsx
+index 79cc930e01..1e9c5f25d2 100644
+--- a/packages/client/ui-agent-preset/tests/components.client.spec.tsx
++++ b/packages/client/ui-agent-preset/tests/components.client.spec.tsx
+@@ -400,6 +400,12 @@ describe('the session-header label', () => {
+     expect(screen.getByTitle(en.headerHint).textContent).toBe('mine')
+   })
+ 
++  it('labels a persisted legacy code preset as PTC mode', () => {
++    renderLabel({ blank: false, projectionValues: { agentPreset: 'code' } })
++
++    expect(screen.getByTitle(en.headerHint).textContent).toBe(en.presetPtcName)
++  })
++
+   it('shows the id until the roster resolves it', () => {
+     renderLabel({
+       blank: false,