Merge remote-tracking branch 'origin/master' into worktree/provider-routed-llm-adapters

# Conflicts: # docs/config-catalog.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.md # docs/event-producer-consumer.md # docs/persistence-catalog.md # examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl # examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl # examples/acp-agent/tests/snapshots/skill-load/session.jsonl # examples/acp-agent/tests/snapshots/text-turn/session.jsonl # examples/sandbox-acp-agent/cordis.yml # examples/sandbox-acp-agent/tests/snapshots/escalation-approved/session.jsonl # examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/session.jsonl # examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl # packages/compact/compact-basic/README.md # packages/compact/compact-basic/src/index.ts # packages/compact/compact-basic/tests/compact-basic.spec.ts # packages/core/agent-loop/README.md # packages/core/agent-loop/src/loop.ts # packages/core/agent-loop/tests/properties.spec.ts # packages/core/session/README.md # packages/core/session/src/types.ts # packages/core/session/tests/derived-cache.spec.ts # packages/llm/llm-deepseek/src/index.ts # packages/llm/llm-pi-ai/README.md # packages/llm/llm-pi-ai/src/adapter.ts # packages/llm/llm-pi-ai/src/convert.ts # packages/llm/llm-pi-ai/tests/adapter.spec.ts # packages/llm/llm/README.md # packages/llm/llm/src/call-config.ts # packages/llm/llm/src/index.ts # packages/ui/acp-agent/src/index.ts # packages/ui/acp/tests/harness.ts # packages/ui/jsonrpc/README.md # packages/ui/jsonrpc/src/server.ts # packages/ui/stdio-agent/README.md # packages/ui/stdio-agent/src/index.ts # python/sdk/README.i18n.yaml
2026-07-14 22:17:50 +08:00
parent e547980d77 fb126e164a
commit 815365dbbe
672 changed files with 10295 additions and 14200 deletions
--- a/packages/session-query/README.md
+++ b/packages/session-query/README.md
@@ -0,0 +1,9 @@
+# session-query/ — session retrieval capability family
+
+Trusted exact reads over live and durable session logs. Phase one contains one interface package that owns `ctx.sessionQuery`, logical-corpus precedence, surface classification, and bounded event reads.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`session-query/`](session-query/README.md) | Logical-corpus and exact-event read service | `ctx.sessionQuery` |
+
+The family is independent of compaction: it reads the canonical session log but does not participate in compaction policy or execution. Full-text search remains proposed as a phase-two SQLite package rather than a speculative provider seam in this interface package.
--- a/packages/session-query/session-query/README.md
+++ b/packages/session-query/session-query/README.md
@@ -0,0 +1,28 @@
+# @deepseek-ai/dsh-session-query
+
+Exact session-history retrieval through `ctx.sessionQuery`. The service presents live `ctx.sessions` and an optional, dynamically mounted `ctx.sessionPersistence` as one logical corpus. Matching ids produce one record: live events win, while `live` and `persisted` report both source availabilities. Conflicting immutable headers fail with `SESSION_QUERY_SOURCE_CONFLICT`.
+
+## Reads
+
+- `listSessions()` reads current persistence metadata, merges live records with live precedence, and returns cloned records in deterministic newest-first order.
+- `listEvents(sessionId)` loads the live-preferred raw log and classifies each event as `current`, `shadowed`, or `log-only` with the shared `dsh-session` surface fold.
+- `readEvent(request)` returns a cloned header, the full target event, and a bounded raw-seq window. `before` and `after` default to zero and may not exceed `readWindowMax`.
+
+Persistence is optional and may mount or unmount dynamically. A cross-corpus list fails with `SESSION_QUERY_PERSISTENCE_FAILED` while mounted persistence is unreadable. A read targeting a known live session does not consult persistence, so durable backend health cannot make current in-memory history unreadable. Persisted exact reads list before loading, and reject a metadata mismatch rather than combining inconsistent observations.
+
+`SessionQueryError.code` is a closed union: `SESSION_QUERY_EVENT_NOT_FOUND`, `SESSION_QUERY_INVALID_CONFIG`, `SESSION_QUERY_INVALID_SURFACE`, `SESSION_QUERY_INVALID_WINDOW`, `SESSION_QUERY_PERSISTENCE_FAILED`, `SESSION_QUERY_SESSION_NOT_FOUND`, and `SESSION_QUERY_SOURCE_CONFLICT`.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `readWindowMax` | `50` | Maximum `before` or `after` raw-event count. |
+
+## Model Experience
+
+None, as this trusted query service returns cloned session records only to its callers and registers no model-facing prompt, schema, tool, or message.
+
+## Known Limitations and Deferred Work
+
+- **No caller authorization** — this is trusted context-wide infrastructure; a future model tool or UI must constrain which sessions its caller may inspect.
+- **Exact retrieval only** — filters, lineage/provenance traversal, extraction, search-provider protocol, index synchronization, and a model-facing tool are absent. Full-text search belongs beside its first implementation; the proposed SQLite package and its single transaction/reconciliation owner are described in the [phase-two RFC](../../../docs/rfc/proposed/feature/2026-07-10-sqlite-session-query-provider.md).
--- a/packages/session-query/session-query/package.json
+++ b/packages/session-query/session-query/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-session-query",
+  "description": "Live-preferred exact session-history retrieval service (ctx.sessionQuery)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
--- a/packages/session-query/session-query/src/config.ts
+++ b/packages/session-query/session-query/src/config.ts
@@ -0,0 +1,33 @@
+/** Public configuration and typed failures for session-query. */
+
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+
+/** Default maximum `before`/`after` raw-event window. */
+export const SESSION_QUERY_READ_WINDOW_MAX = 50
+
+/** Configuration for exact session-query reads. */
+export interface Config {
+  /** Maximum accepted raw read context on either side. Defaults to 50. */
+  readWindowMax?: number
+}
+
+/** Stable machine-routable failure taxonomy for exact session reads. */
+export type SessionQueryErrorCode =
+  | 'SESSION_QUERY_EVENT_NOT_FOUND'
+  | 'SESSION_QUERY_INVALID_CONFIG'
+  | 'SESSION_QUERY_INVALID_SURFACE'
+  | 'SESSION_QUERY_INVALID_WINDOW'
+  | 'SESSION_QUERY_PERSISTENCE_FAILED'
+  | 'SESSION_QUERY_SESSION_NOT_FOUND'
+  | 'SESSION_QUERY_SOURCE_CONFLICT'
+
+/** Typed session-query failure whose `code` is one closed taxonomy member. */
+export class SessionQueryError extends HarnessError {
+  declare readonly code: SessionQueryErrorCode
+
+  // The base stores the value; this signature narrows its open string code.
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+  constructor(message: string, code: SessionQueryErrorCode, options?: ErrorOptions) {
+    super(message, code, options)
+  }
+}
--- a/packages/session-query/session-query/src/corpus.ts
+++ b/packages/session-query/session-query/src/corpus.ts
@@ -0,0 +1,136 @@
+/** Live/persisted logical-corpus resolution for session-query. */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+import type { SessionRecord } from './types.ts'
+import { SessionQueryError } from './config.ts'
+
+/** Detached source selected for one exact read. */
+export interface LogicalSession {
+  /** Cloned source header. */
+  header: SessionHeader
+  /** Cloned raw event log. */
+  events: SessionEvent[]
+}
+
+/** Resolves a live-preferred corpus against the persistence service mounted now. */
+export class SessionCorpus {
+  private _persistence: SessionPersistence | undefined
+
+  constructor(private readonly _ctx: Context) {
+    _ctx.effect(() => {
+      const fiber = _ctx.inject(['sessionPersistence'], (childCtx: Context) => {
+        const service = childCtx.sessionPersistence
+        this._persistence = service
+        childCtx.effect(() => () => {
+          /* v8 ignore next -- a stale optional-service disposer cannot clear a replacement */
+          if (this._persistence === service) this._persistence = undefined
+        }, 'sessionQuery.persistenceBinding')
+      })
+      return () => void fiber.dispose()
+    }, 'sessionQuery.optionalPersistence')
+  }
+
+  /**
+   * List the complete logical corpus with live precedence and cloned headers.
+   * @returns records in deterministic newest-first order.
+   */
+  async listSessions(): Promise<SessionRecord[]> {
+    const persistence = this._persistence
+    const persisted = persistence === undefined ? [] : await listPersisted(persistence)
+    const records = new Map<SessionId, SessionRecord>()
+    for (const header of persisted) {
+      records.set(header.id, { header: structuredClone(header), live: false, persisted: true })
+    }
+    for (const session of this._ctx.sessions.list()) {
+      const durable = records.get(session.id)
+      if (durable !== undefined) assertCompatibleHeaders(session.header, durable.header)
+      records.set(session.id, {
+        header: structuredClone(session.header),
+        live: true,
+        persisted: durable !== undefined,
+      })
+    }
+    return [...records.values()].sort(compareSessions)
+  }
+
+  /**
+   * Load one logical source, preferring a detached live snapshot.
+   *
+   * A known live target never consults persistence, so an optional backend's
+   * failure cannot make current in-memory history unreadable.
+   * @param sessionId - session to resolve.
+   * @returns detached live-preferred header and events.
+   */
+  async load(sessionId: SessionId): Promise<LogicalSession> {
+    const live = this._ctx.sessions.get(sessionId)
+    if (live !== undefined) return snapshotLive(live)
+    const persistence = this._persistence
+    if (persistence === undefined) throw notFound(sessionId)
+    const listed = (await listPersisted(persistence)).find(header => header.id === sessionId)
+    if (listed === undefined) throw notFound(sessionId)
+    let loaded: Awaited<ReturnType<SessionPersistence['load']>>
+    try {
+      loaded = await persistence.load(sessionId)
+    } catch (error: unknown) {
+      throw new SessionQueryError(
+        `failed to load session "${sessionId}": ${errorMessage(error)}`,
+        'SESSION_QUERY_PERSISTENCE_FAILED',
+        { cause: error },
+      )
+    }
+    assertCompatibleHeaders(loaded.meta, listed)
+    return {
+      header: structuredClone(loaded.meta),
+      events: loaded.events.map(event => structuredClone(event)),
+    }
+  }
+}
+
+async function listPersisted(persistence: SessionPersistence): Promise<SessionHeader[]> {
+  try {
+    return await persistence.list()
+  } catch (error: unknown) {
+    throw new SessionQueryError(
+      `session persistence listing failed: ${errorMessage(error)}`,
+      'SESSION_QUERY_PERSISTENCE_FAILED',
+      { cause: error },
+    )
+  }
+}
+
+function snapshotLive(session: Session): LogicalSession {
+  return {
+    header: structuredClone(session.header),
+    events: session.events.map(event => structuredClone(event)),
+  }
+}
+
+function assertCompatibleHeaders(a: SessionHeader, b: SessionHeader): void {
+  if (
+    a.version !== b.version
+    || a.id !== b.id
+    || a.createdAt !== b.createdAt
+    || a.cwd !== b.cwd
+    || a.parentSession !== b.parentSession
+    || a.seedLength !== b.seedLength
+  ) {
+    throw new SessionQueryError(
+      `live and persisted headers conflict for session "${a.id}"`,
+      'SESSION_QUERY_SOURCE_CONFLICT',
+    )
+  }
+}
+
+function compareSessions(a: SessionRecord, b: SessionRecord): number {
+  return b.header.createdAt - a.header.createdAt || a.header.id.localeCompare(b.header.id)
+}
+
+function notFound(sessionId: SessionId): SessionQueryError {
+  return new SessionQueryError(`session "${sessionId}" not found`, 'SESSION_QUERY_SESSION_NOT_FOUND')
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error'
+}
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -0,0 +1,136 @@
+/**
+ * Exact session-history reads over live and optionally persisted logs.
+ *
+ * @module @deepseek-ai/dsh-session-query
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { foldSurface } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type {
+  SessionEventReadRequest,
+  SessionEventRecord,
+  SessionEventWindow,
+  SessionRecord,
+} from './types.ts'
+import {
+  SESSION_QUERY_READ_WINDOW_MAX,
+  SessionQueryError,
+  type Config,
+} from './config.ts'
+import { SessionCorpus } from './corpus.ts'
+
+export type * from './types.ts'
+export type { Config, SessionQueryErrorCode } from './config.ts'
+export { SESSION_QUERY_READ_WINDOW_MAX, SessionQueryError } from './config.ts'
+
+declare module 'cordis' {
+  interface Context {
+    sessionQuery: SessionQueryService
+  }
+}
+
+/** Live-preferred logical-corpus and exact-event read service. */
+export class SessionQueryService extends Service {
+  static inject = ['sessions']
+  static Config: z<Config> = z.object({
+    readWindowMax: z.number().step(1).min(0).default(SESSION_QUERY_READ_WINDOW_MAX),
+  })
+
+  private readonly _readWindowMax: number
+  private readonly _corpus: SessionCorpus
+
+  constructor(ctx: Context, config: Config = {}) {
+    super(ctx, 'sessionQuery')
+    this._readWindowMax = config.readWindowMax ?? SESSION_QUERY_READ_WINDOW_MAX
+    if (!Number.isInteger(this._readWindowMax) || this._readWindowMax < 0) {
+      throw new SessionQueryError(
+        'session-query: readWindowMax must be a non-negative integer',
+        'SESSION_QUERY_INVALID_CONFIG',
+      )
+    }
+    this._corpus = new SessionCorpus(ctx)
+  }
+
+  /**
+   * List the complete logical corpus using live-preferred records.
+   * @returns deterministic newest-first cloned session records.
+   */
+  listSessions(): Promise<SessionRecord[]> {
+    return this._corpus.listSessions()
+  }
+
+  /**
+   * List lightweight raw-log event records for one logical session.
+   * @param sessionId - live-preferred session id to read.
+   * @returns event records in ascending seq order.
+   */
+  async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]> {
+    const loaded = await this._corpus.load(sessionId)
+    return eventRecords(sessionId, loaded.events)
+  }
+
+  /**
+   * Read one full event plus a bounded raw-log context window.
+   * @param request - target session/seq and context sizes.
+   * @returns cloned target and neighboring events.
+   */
+  async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow> {
+    const before = this._readWindow('before', request.before)
+    const after = this._readWindow('after', request.after)
+    const loaded = await this._corpus.load(request.sessionId)
+    const target = loaded.events[request.seq]
+    if (target === undefined || target.seq !== request.seq) {
+      throw new SessionQueryError(
+        `session "${request.sessionId}" has no event at seq ${request.seq}`,
+        'SESSION_QUERY_EVENT_NOT_FOUND',
+      )
+    }
+    const startSeq = Math.max(0, request.seq - before)
+    const endSeq = Math.min(loaded.events.length - 1, request.seq + after)
+    return {
+      session: loaded.header,
+      target,
+      events: loaded.events.slice(startSeq, endSeq + 1),
+      startSeq,
+      endSeq,
+    }
+  }
+
+  private _readWindow(name: 'before' | 'after', value: number | undefined): number {
+    if (value === undefined) return 0
+    if (!Number.isInteger(value) || value < 0 || value > this._readWindowMax) {
+      throw new SessionQueryError(
+        `${name} must be an integer between 0 and ${this._readWindowMax}`,
+        'SESSION_QUERY_INVALID_WINDOW',
+      )
+    }
+    return value
+  }
+}
+
+function eventRecords(sessionId: SessionId, events: readonly SessionEvent[]): SessionEventRecord[] {
+  let folded: ReturnType<typeof foldSurface>
+  try {
+    folded = foldSurface(events)
+  } catch (error: unknown) {
+    throw new SessionQueryError(
+      /* v8 ignore next -- foldSurface throws Error instances */
+      `invalid session surface: ${error instanceof Error ? error.message : 'unknown error'}`,
+      'SESSION_QUERY_INVALID_SURFACE',
+      { cause: error },
+    )
+  }
+  const current = new Set(folded.nodes.map(node => node.seq))
+  const shadowed = new Set(folded.replacements.flatMap(replacement => replacement.shadowedSeqs))
+  return events.map(event => ({
+    sessionId,
+    seq: event.seq,
+    type: event.type,
+    time: event.time,
+    surface: current.has(event.seq) ? 'current' : shadowed.has(event.seq) ? 'shadowed' : 'log-only',
+  }))
+}
+
+export default SessionQueryService
--- a/packages/session-query/session-query/src/types.ts
+++ b/packages/session-query/session-query/src/types.ts
@@ -0,0 +1,60 @@
+/**
+ * Public records for exact reads over the live-preferred logical session corpus.
+ *
+ * @module @deepseek-ai/dsh-session-query/types
+ */
+
+import type { SessionEvent, SessionEventType, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+
+/** Whether an event is current model context, replaced context, or raw-log-only. */
+export type SessionEventSurface = 'current' | 'shadowed' | 'log-only'
+
+/** Lightweight identity and source availability for one logical session. */
+export interface SessionRecord {
+  /** Cloned session header selected from the live-preferred corpus. */
+  header: SessionHeader
+  /** Whether the id currently exists in `ctx.sessions`. */
+  live: boolean
+  /** Whether the active persistence backend currently materializes the id. */
+  persisted: boolean
+}
+
+/** Lightweight metadata for one event within a logical session. */
+export interface SessionEventRecord {
+  /** Session that owns the event. */
+  sessionId: SessionId
+  /** Monotonic event seq within the session. */
+  seq: number
+  /** Discriminant of the session event. */
+  type: SessionEventType
+  /** Event timestamp in Unix epoch milliseconds. */
+  time: number
+  /** Event placement in the folded session surface. */
+  surface: SessionEventSurface
+}
+
+/** Request for one event plus raw neighboring log context. */
+export interface SessionEventReadRequest {
+  /** Session that owns the target event. */
+  sessionId: SessionId
+  /** Target event seq. */
+  seq: number
+  /** Number of preceding raw events to include. */
+  before?: number
+  /** Number of following raw events to include. */
+  after?: number
+}
+
+/** Full target event and a bounded raw-log window. */
+export interface SessionEventWindow {
+  /** Cloned header for the live-preferred source read. */
+  session: SessionHeader
+  /** Full cloned target event. */
+  target: SessionEvent
+  /** Full cloned events from `startSeq` through `endSeq`. */
+  events: SessionEvent[]
+  /** First seq included in `events`. */
+  startSeq: number
+  /** Last seq included in `events`. */
+  endSeq: number
+}
--- a/packages/session-query/session-query/tests/session-query.spec.ts
+++ b/packages/session-query/session-query/tests/session-query.spec.ts
@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
+import SessionPersistence from '@deepseek-ai/dsh-session-persistence'
+import SessionQueryService, {
+  type SessionQueryErrorCode,
+} from '@deepseek-ai/dsh-session-query'
+
+function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
+}
+
+function eventLog(text = 'hello'): SessionEvent[] {
+  return [{
+    type: 'user/message',
+    seq: 0,
+    time: 10,
+    data: { content: [{ type: 'text', text }], source: { kind: 'user' } },
+    surfaceOp: 'append',
+  }]
+}
+
+class TestPersistence extends SessionPersistence {
+  static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
+  static listFailure: unknown
+  static loadFailure: unknown
+  static afterList: (() => void) | undefined
+
+  static reset(entries: readonly { meta: SessionHeader; events: SessionEvent[] }[] = []): void {
+    this.entries = new Map(entries.map(entry => [entry.meta.id, structuredClone(entry)]))
+    this.listFailure = undefined
+    this.loadFailure = undefined
+    this.afterList = undefined
+  }
+
+  create(meta: SessionHeader): Promise<void> {
+    TestPersistence.entries.set(meta.id, { meta: structuredClone(meta), events: [] })
+    return Promise.resolve()
+  }
+
+  append(id: SessionIdType, events: readonly SessionEvent[]): Promise<void> {
+    const entry = TestPersistence.entries.get(id)
+    if (entry === undefined) return Promise.reject(new Error('missing test session'))
+    entry.events.push(...structuredClone(events))
+    return Promise.resolve()
+  }
+
+  load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    if (TestPersistence.loadFailure !== undefined) return rejectUnknown(TestPersistence.loadFailure)
+    const entry = TestPersistence.entries.get(id)
+    if (entry === undefined) return Promise.reject(new Error('missing test session'))
+    return Promise.resolve(structuredClone(entry))
+  }
+
+  list(): Promise<SessionHeader[]> {
+    if (TestPersistence.listFailure !== undefined) return rejectUnknown(TestPersistence.listFailure)
+    const headers = [...TestPersistence.entries.values()].map(entry => structuredClone(entry.meta))
+    TestPersistence.afterList?.()
+    return Promise.resolve(headers)
+  }
+}
+
+async function liveContext(config: ConstructorParameters<typeof SessionQueryService>[1] = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionQueryService, config)
+  return ctx
+}
+
+function expectCode(code: SessionQueryErrorCode): Error {
+  return expect.objectContaining({ code }) as Error
+}
+
+function rejectUnknown<T>(reason: unknown): Promise<T> {
+  return new Promise<T>((_resolve, reject) => {
+    // Exercise containment for an implementation that violates the Error rejection convention.
+    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+    reject(reason)
+  })
+}
+
+describe('session-query exact reads', () => {
+  it('lists live sessions deterministically and returns detached headers', async () => {
+    const ctx = await liveContext()
+    const older = ctx.sessions.create(SessionId('older'), { meta: { createdAt: 1 } })
+    ctx.sessions.create(SessionId('z'), { meta: { createdAt: 2 } })
+    ctx.sessions.create(SessionId('a'), { meta: { createdAt: 2 } })
+
+    const records = await ctx.sessionQuery.listSessions()
+    expect(records.map(record => record.header.id)).toEqual([SessionId('a'), SessionId('z'), older.id])
+    expect(records.every(record => record.live && !record.persisted)).toBe(true)
+    Object.assign(records[2]!.header, { createdAt: 99 })
+    expect(older.header.createdAt).toBe(1)
+  })
+
+  it('classifies current, shadowed, and raw-log-only events through foldSurface', async () => {
+    const ctx = await liveContext()
+    const session = ctx.sessions.create(SessionId('surface'))
+    const first = session.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'first' }], source: { kind: 'user' } },
+      { surfaceOp: 'append' },
+    )
+    session.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'text-delta', index: 0, text: 'draft' },
+    })
+    session.append(
+      'assistant/message',
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'replacement' }] },
+      { surfaceOp: { op: 'replace', start: first.seq, end: first.seq } },
+    )
+
+    expect((await ctx.sessionQuery.listEvents(session.id)).map(record => record.surface))
+      .toEqual(['shadowed', 'log-only', 'current'])
+  })
+
+  it('returns a bounded detached raw-event window and validates the request', async () => {
+    const ctx = await liveContext({ readWindowMax: 1 })
+    const session = ctx.sessions.create(SessionId('window'), { meta: { cwd: '/work' } })
+    for (const text of ['one', 'two', 'three']) {
+      session.append(
+        'user/message',
+        { content: [{ type: 'text', text }], source: { kind: 'user' } },
+        { surfaceOp: 'append' },
+      )
+    }
+
+    const result = await ctx.sessionQuery.readEvent({ sessionId: session.id, seq: 1, before: 1, after: 1 })
+    expect([result.startSeq, result.endSeq, result.target.seq]).toEqual([0, 2, 1])
+    expect(result.session).toEqual(session.header)
+    Object.assign(result.session, { createdAt: -1 })
+    if (result.events[0]?.type !== 'user/message') throw new Error('expected user message')
+    result.events[0].data.content = []
+    expect(session.header.createdAt).not.toBe(-1)
+    expect(session.events[0]?.type === 'user/message' && session.events[0].data.content).toHaveLength(1)
+
+    await expect(ctx.sessionQuery.readEvent({ sessionId: session.id, seq: 9 }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_EVENT_NOT_FOUND'))
+    for (const request of [
+      { sessionId: session.id, seq: 0, before: -1 },
+      { sessionId: session.id, seq: 0, before: 2 },
+      { sessionId: session.id, seq: 0, after: 0.5 },
+    ]) {
+      await expect(ctx.sessionQuery.readEvent(request)).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_WINDOW'))
+    }
+  })
+
+  it('merges authoritative persistence with live precedence and detects conflicts', async () => {
+    const shared = header('shared', 3, { cwd: '/same' })
+    const durable = header('durable', 2)
+    TestPersistence.reset([
+      { meta: shared, events: eventLog('persisted') },
+      { meta: durable, events: eventLog('durable') },
+    ])
+    const ctx = await liveContext()
+    const live = ctx.sessions.create(shared.id, { meta: { createdAt: 3, cwd: '/same' } })
+    live.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'live' }], source: { kind: 'user' } },
+      { surfaceOp: 'append' },
+    )
+    const persistence = await ctx.plugin(TestPersistence)
+
+    expect((await ctx.sessionQuery.listSessions()).map(record => [record.header.id, record.live, record.persisted]))
+      .toEqual([[shared.id, true, true], [durable.id, false, true]])
+    const liveRead = await ctx.sessionQuery.readEvent({ sessionId: shared.id, seq: 0 })
+    expect(liveRead.target.type === 'user/message' && liveRead.target.data.content[0])
+      .toMatchObject({ text: 'live' })
+    await expect(ctx.sessionQuery.readEvent({ sessionId: durable.id, seq: 0 }))
+      .resolves.toMatchObject({ session: durable })
+
+    const sharedEntry = TestPersistence.entries.get(shared.id)!
+    sharedEntry.meta = { ...sharedEntry.meta, cwd: '/conflict' }
+    await expect(ctx.sessionQuery.listSessions()).rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
+    await persistence.dispose()
+    await expect(ctx.sessionQuery.listSessions()).resolves.toEqual([
+      { header: shared, live: true, persisted: false },
+    ])
+  })
+
+  it('keeps known live reads independent from persistence health', async () => {
+    TestPersistence.reset()
+    const ctx = await liveContext()
+    const live = ctx.sessions.create(SessionId('live'))
+    live.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'available' }], source: { kind: 'user' } },
+      { surfaceOp: 'append' },
+    )
+    await ctx.plugin(TestPersistence)
+    TestPersistence.listFailure = new Error('list unavailable')
+    TestPersistence.loadFailure = new Error('load unavailable')
+
+    await expect(ctx.sessionQuery.listEvents(live.id)).resolves.toHaveLength(1)
+    await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: 0 })).resolves.toMatchObject({ target: { seq: 0 } })
+    await expect(ctx.sessionQuery.listSessions()).rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    await expect(ctx.sessionQuery.listEvents(SessionId('durable'))).rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+  })
+
+  it('reports absent sessions, persisted load failures, and persisted header conflicts', async () => {
+    const durable = header('durable')
+    TestPersistence.reset([{ meta: durable, events: eventLog() }])
+    const ctx = await liveContext()
+    await expect(ctx.sessionQuery.listEvents(SessionId('absent')))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
+    await ctx.plugin(TestPersistence)
+    await expect(ctx.sessionQuery.listEvents(SessionId('absent')))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
+
+    TestPersistence.loadFailure = 'raw failure'
+    await expect(ctx.sessionQuery.listEvents(durable.id))
+      .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
+    TestPersistence.loadFailure = undefined
+    const durableEntry = TestPersistence.entries.get(durable.id)!
+    durableEntry.meta = { ...durableEntry.meta, cwd: '/changed-after-list' }
+    TestPersistence.afterList = () => {
+      const listedEntry = TestPersistence.entries.get(durable.id)!
+      listedEntry.meta = { ...listedEntry.meta, cwd: '/changed-during-read' }
+    }
+    await expect(ctx.sessionQuery.listEvents(durable.id))
+      .rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
+  })
+
+  it('turns malformed surfaces and direct invalid config into typed errors', async () => {
+    const ctx = await liveContext()
+    const session = ctx.sessions.create(SessionId('bad-surface'))
+    session.append(
+      'assistant/message',
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] },
+      { surfaceOp: { op: 'replace', start: 9, end: 9 } },
+    )
+    await expect(ctx.sessionQuery.listEvents(session.id))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
+
+    const persisted = header('bad-persisted-surface')
+    TestPersistence.reset([{
+      meta: persisted,
+      events: [{
+        type: 'user/message',
+        seq: 0,
+        time: 1,
+        data: { content: [{ type: 'text', text: 'hidden' }], source: { kind: 'user' } },
+      }],
+    }])
+    const persistence = await ctx.plugin(TestPersistence)
+    await expect(ctx.sessionQuery.listEvents(persisted.id))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
+    await persistence.dispose()
+
+    const direct = new Context()
+    await direct.plugin(SessionStore)
+    expect(new SessionQueryService(direct)).toBeInstanceOf(SessionQueryService)
+    const invalid = new Context()
+    await invalid.plugin(SessionStore)
+    expect(() => new SessionQueryService(invalid, { readWindowMax: -1 }))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_CONFIG'))
+  })
+
+  it('leaves the optional persistence dependency optional', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(SessionQueryService)
+    expect(ctx.sessionQuery).toBeInstanceOf(SessionQueryService)
+    await fiber.dispose()
+    expect(ctx.sessionQuery).toBeUndefined()
+  })
+})
--- a/packages/session-query/session-query/tsconfig.json
+++ b/packages/session-query/session-query/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    }
+  ]
+}