Merge remote-tracking branch 'origin/master' into feat/send-unify

# Conflicts:
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/pty/pty-local/tests/index.spec.ts
#	packages/session-query/session-query/tests/tracing.spec.ts

packages/session-query/README.md

@@ -1,9 +1,10 @@
 # session-query/ — session retrieval capability family
 
-Trusted exact reads and relationship traces over live and durable session logs. The family contains one interface package that owns `ctx.sessionQuery`, logical-corpus precedence, title folding, surface classification, bounded event reads, lineage, and direct event relationships.
+Trusted exact reads, relationship traces, provider-independent semantic filtering, and SQLite full-text search over live and durable session logs.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`session-query/`](session-query/README.md) | Logical-corpus title, event, lineage, and relationship reads | `ctx.sessionQuery` |
+| [`session-query/`](session-query/README.md) | Combined service contract with concrete logical-corpus reads, traces, and semantic filters plus abstract full-text methods | `ctx.sessionQuery` |
+| [`session-query-sqlite/`](session-query-sqlite/README.md) | Concrete service backend with SQLite FTS5 persistent bases and live overlays | `ctx.sessionQuery` |
 
-The family is independent of compaction: it reads canonical lineage, surface operations, and logged provenance but does not participate in compaction policy or execution. Full-text search remains a proposed SQLite package rather than a speculative provider seam in this interface package.
+The family is independent of compaction: it reads canonical lineage, surface operations, logged provenance, and semantic event text but does not participate in compaction policy or execution. One abstract service combines every query operation, and one concrete backend owns the full-text lifecycle without a provider registry or coordinator.

packages/session-query/session-query-sqlite/README.md

@@ -0,0 +1,51 @@
+# @deepseek-ai/dsh-session-query-sqlite
+
+Concrete `ctx.sessionQuery` backend. `SessionQuerySqlite` inherits exact reads, traces, and provider-independent filters from the interface package and implements its two full-text methods with SQLite FTS5. Search uses the live-preferred logical session corpus and groups cross-session results by their strongest event.
+
+## Search contract
+
+`searchSessions(request, exec?)` returns `SessionSearchHit` pages across the corpus; `searchEvents(request, exec?)` returns `SessionEventSearchHit` pages within one session. Queries are required, trimmed, whitespace-normalized literal phrases. FTS5 syntax such as quotes, `OR`, `NEAR`, and `*` is treated as data rather than executable MATCH syntax. Metadata filters are parameterized SQL predicates applied before ranking. To keep SQLite FTS5 MATCH in a supported outer-predicate context, cross-session requests may compile at most 14 combined session and event filter predicates; within-session requests may compile at most 13 filter predicates because the fixed target-session predicate consumes one slot. Each range endpoint compiles as one predicate. A request exceeding either predicate budget or SQLite's portable limit of 32,766 total bindings, including fixed query and pagination values, fails with `SESSION_QUERY_INVALID_FILTER` before statement preparation.
+
+Relevance is source-comparable across persistent and TEMP tables: actual FTS5 highlighted-match span count descending, then stored document code-point length ascending. Event time, session id where applicable, and seq break remaining ties. Cross-session results expose the selected event as `bestMatch`; both scopes derive whitespace-normalized plain text from FTS5 highlight positions and bound it in Unicode code points. Cursors are opaque branded values, bind to the normalized request and service instance, and fail when the relevant generation changes. A within-session cursor survives unrelated-session changes; a cross-session cursor does not.
+
+All three surfaces (`current`, `shadowed`, and `log-only`) are searchable by default. Pass a surface filter to narrow them.
+
+## Source and index lifecycle
+
+The service requires `ctx.sessions` and observes optional `ctx.sessionPersistence` dynamically. One serialized state machine compares source-qualified lightweight durable snapshot revisions, non-mutatingly inspects only new or changed logs, extracts shared semantic documents, reconciles changes transactionally, and runs the query. Session queries never invoke the persistence backend's crash-repairing `load()`; an owner attaching during inspection cannot mutate its log, and the stable-observation retry makes the result live-preferred. The TEMP live row still records persisted availability, and the durable base refreshes after that live owner detaches. Repeated queries and an unchanged same-store reopen perform no full durable-log inspection; switching stores, or observing new, changed, deleted, or externally load-repaired sources, reconciles on the next stable observation. Source or transaction failure commits nothing, and the next search retries.
+
+Persisted FTS rows live in a dedicated derived database. Connection-local TEMP tables hold live rows, which shadow the durable base for the same session and reveal it when the live owner disappears. Unmounting persistence hides durable rows without discarding the cache; remounting reconciles it. Closing or reopening the database drops every live overlay while retaining persisted rows.
+
+The database is disposable but reset is guarded: every recognized schema version rejects unknown user tables before mutating journal mode, and only a recognized incompatible schema containing derived tables rebuilds in place. An unrelated or canonical database is refused. Never point `path` at the session-persistence database. On filesystems with POSIX modes, missing directories and databases are created owner-only (`0700` and `0600` before the process umask), and SQLite sidecars inherit the database mode; existing modes are preserved. Exactly one service in one process owns a derived-index path; external writers or a second process are unsupported because generations and TEMP shadow state are connection-owned.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `path` | required | Dedicated derived-index SQLite path; `:memory:` is supported. Missing filesystem paths are created owner-only on POSIX filesystems. |
+| `journalMode` | `wal` | `wal`, `delete`, `truncate`, or `persist`. |
+| `defaultLimit` | `20` | Page size when a request omits `limit`; at most `Number.MAX_SAFE_INTEGER - 1`. |
+| `maxLimit` | `100` | Largest accepted request page size; at most `Number.MAX_SAFE_INTEGER - 1`. |
+| `snippetChars` | `240` | Maximum snippet length in Unicode code points. |
+| `readWindowMax` | `50` | Maximum `before` or `after` raw-event count for inherited `readEvent()`. |
+
+## Tokenizer and limits
+
+The index uses FTS5 `unicode61`. In the implementation experiment it supported the two-character query `AI` and produced an index about 2.1× smaller than the trigram alternative. The trade-off is token/phrase recall rather than arbitrary substring recall: `AI` does not match the token `BRAID`. Use `ctx.sessionQuery.filterEvents()` with a `text` clause when a literal whitespace-flexible substring scan is required. NUL is rejected in queries; reserved highlight markers and NUL in documents are normalized before indexing so presentation markers cannot collide with source text.
+
+Abort signals stop queued work and caller waits around asynchronous source observation. Node's synchronous `DatabaseSync` API cannot interrupt a MATCH statement already executing on the JavaScript thread; the signal is checked immediately before and after the serialized observation/reconciliation boundary.
+
+## Model Experience
+
+None, as this trusted search backend returns hits only to callers and registers no model-facing prompt, schema, tool, or message.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No caller authorization** — this is a trusted context-wide service; a model tool or UI must enforce its own access policy.
+- **Synchronous query execution** — `DatabaseSync` blocks the JavaScript thread during MATCH execution and cannot interrupt a statement already running.
+- **Token recall, not arbitrary substrings** — the `unicode61` tokenizer does not match substrings inside a larger token; use `filterEvents()` for literal scans.
+- **Single-owner derived index** — one service in one process must own each index path; external writers and multi-process sharing are unsupported.

packages/session-query/session-query-sqlite/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-session-query-sqlite",
+  "description": "Concrete ctx.sessionQuery backend with SQLite FTS5 search",
+  "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"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/session-query/session-query-sqlite/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-query-sqlite`.
+ * @module @deepseek-ai/dsh-session-query-sqlite/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-query-sqlite'
+
+/** Cordis companion plugin name. */
+export const name = 'session-query-sqlite-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: reconciliation, cursor generations, and derived-index
+ * ownership are validated at each serialized query boundary.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/session-query/session-query-sqlite/src/query.ts

@@ -0,0 +1,477 @@
+/** Request normalization, parameterized predicates, and result presentation. */
+
+import {
+  SessionQueryError,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+} from '@deepseek-ai/dsh-session-query'
+import type {
+  SessionAvailability,
+  SessionEventMetadataFilter,
+  SessionEventResultFilter,
+  SessionEventSearchRequest,
+  SessionResultFilter,
+  SessionSearchCursor,
+  SessionSearchRequest,
+} from '@deepseek-ai/dsh-session-query'
+
+/** Collision-free marker inserted before an FTS5 match by `highlight()`. */
+export const FTS_HIGHLIGHT_START = '\uFDD0'
+/** Collision-free marker inserted after an FTS5 match by `highlight()`. */
+export const FTS_HIGHLIGHT_END = '\uFDD1'
+
+/** Largest page size whose internal lookahead remains an exact SQLite integer binding. */
+export const SQLITE_MAX_PAGE_LIMIT = Number.MAX_SAFE_INTEGER - 1
+
+/** Portable host-parameter ceiling shared by predicate and statement builders. */
+export const SQLITE_PORTABLE_VARIABLE_LIMIT = 32_766
+
+/** Supported outer-predicate budget that keeps SQLite FTS5 MATCH usable. */
+export const SQLITE_FTS5_OUTER_PREDICATE_LIMIT = 14
+
+/**
+ * Reject prospective SQLite binding growth beyond the portable ceiling.
+ * @param count - binding count at the current construction boundary.
+ */
+export function assertPortableBindingCount(count: number): void {
+  if (count > SQLITE_PORTABLE_VARIABLE_LIMIT) {
+    throw new SessionQueryError(
+      `session-search request exceeds SQLite's portable ${SQLITE_PORTABLE_VARIABLE_LIMIT}-variable limit; reduce filter values`,
+      'SESSION_QUERY_INVALID_FILTER',
+    )
+  }
+}
+
+/**
+ * Reject compiled outer predicates beyond the supported FTS5 planner budget.
+ * @param count - predicate count including fixed statement predicates.
+ */
+export function assertFts5OuterPredicateCount(count: number): void {
+  if (count > SQLITE_FTS5_OUTER_PREDICATE_LIMIT) {
+    throw new SessionQueryError(
+      `session-search request exceeds the supported SQLite FTS5 outer-predicate budget of ${SQLITE_FTS5_OUTER_PREDICATE_LIMIT}; reduce filters`,
+      'SESSION_QUERY_INVALID_FILTER',
+    )
+  }
+}
+
+/** Limit defaults needed to normalize a search request. */
+export interface QueryLimits {
+  /** Page size used when the request omits one. */
+  defaultLimit: number
+  /** Largest accepted page size. */
+  maxLimit: number
+}
+
+/** Normalized cross-session request. */
+export interface NormalizedSessionRequest {
+  query: string
+  sessionFilters: readonly SessionResultFilter[]
+  eventFilters: readonly SessionEventMetadataFilter[]
+  limit: number
+  cursor?: SessionSearchCursor
+}
+
+/** Normalized within-session request. */
+export interface NormalizedEventRequest {
+  sessionId: SessionEventSearchRequest['sessionId']
+  query: string
+  filters: readonly SessionEventMetadataFilter[]
+  limit: number
+  cursor?: SessionSearchCursor
+}
+
+/** Parameterized SQL predicate fragment. */
+export interface SqlWhere {
+  /** SQL without the leading `WHERE`. */
+  sql: string
+  /** Bindings in placeholder order. */
+  params: Array<string | number>
+  /** Number of compiled predicates in `sql`. */
+  predicateCount: number
+}
+
+/**
+ * Validate and canonicalize a cross-session request.
+ * @param request - caller-provided query, filters, limit, and cursor.
+ * @param limits - configured default and maximum page sizes.
+ * @returns normalized request with explicit arrays and limit.
+ */
+export function normalizeSessionRequest(
+  request: SessionSearchRequest,
+  limits: QueryLimits,
+): NormalizedSessionRequest {
+  const sessionFilters = materializeSessionResultFilters(request.sessionFilters ?? [])
+  const eventFilters = materializeMetadataFilters(request.eventFilters ?? [])
+  const cursor = materializeCursor(request.cursor)
+  return {
+    query: normalizeQuery(request.query),
+    sessionFilters,
+    eventFilters,
+    limit: normalizeLimit(request.limit, limits),
+    ...cursor === undefined ? {} : { cursor },
+  }
+}
+
+/**
+ * Validate and canonicalize a within-session request.
+ * @param request - caller-provided target, query, filters, limit, and cursor.
+ * @param limits - configured default and maximum page sizes.
+ * @returns normalized request with an explicit filter array and limit.
+ */
+export function normalizeEventRequest(
+  request: SessionEventSearchRequest,
+  limits: QueryLimits,
+): NormalizedEventRequest {
+  if (typeof request.sessionId !== 'string') {
+    throw new SessionQueryError('session-search session id must be text', 'SESSION_QUERY_INVALID_FILTER')
+  }
+  const filters = materializeMetadataFilters(request.filters ?? [])
+  const cursor = materializeCursor(request.cursor)
+  return {
+    sessionId: request.sessionId,
+    query: normalizeQuery(request.query),
+    filters,
+    limit: normalizeLimit(request.limit, limits),
+    ...cursor === undefined ? {} : { cursor },
+  }
+}
+
+/**
+ * Compile logical-session predicates against selected-document columns.
+ * @param filters - validated ANDed logical-session clauses.
+ * @returns parameterized SQL fragment and ordered bindings.
+ */
+export function buildSessionWhere(filters: readonly SessionResultFilter[]): SqlWhere {
+  const clauses: string[] = []
+  const params: Array<string | number> = []
+  for (const filter of filters) {
+    switch (filter.kind) {
+      case 'id':
+        addList(clauses, params, 'session_id', filter.values)
+        break
+      case 'cwd':
+        addNullableList(clauses, params, 'cwd', filter.values)
+        break
+      case 'created-at':
+        addRange(clauses, params, 'created_at', filter)
+        break
+      case 'parent':
+        addNullableList(clauses, params, 'parent_session', filter.values)
+        break
+      case 'availability': {
+        const availability = [...new Set(filter.values)]
+        if (availability.length === 0) clauses.push('0')
+        else if (availability.length === 1) {
+          const value = availability[0] as SessionAvailability
+          switch (value) {
+            case 'live':
+              clauses.push('live = 1')
+              break
+            case 'persisted':
+              clauses.push('persisted = 1')
+              break
+            default:
+              unknownAvailability(value)
+          }
+        }
+        break
+      }
+      default:
+        unknownFilter(filter)
+    }
+  }
+  assertFts5OuterPredicateCount(clauses.length)
+  return { sql: clauses.join(' AND '), params, predicateCount: clauses.length }
+}
+
+/**
+ * Compile event metadata predicates against selected-document columns.
+ * @param filters - validated ANDed event metadata clauses.
+ * @returns parameterized SQL fragment and ordered bindings.
+ */
+export function buildEventWhere(filters: readonly SessionEventMetadataFilter[]): SqlWhere {
+  const clauses: string[] = []
+  const params: Array<string | number> = []
+  for (const filter of filters) {
+    switch (filter.kind) {
+      case 'seq':
+        addRange(clauses, params, 'seq', filter)
+        break
+      case 'time':
+        addRange(clauses, params, 'time', filter)
+        break
+      case 'type':
+        addList(clauses, params, 'type', filter.values)
+        break
+      case 'surface':
+        addList(clauses, params, 'surface', filter.values)
+        break
+      default:
+        unknownFilter(filter)
+    }
+  }
+  assertFts5OuterPredicateCount(clauses.length)
+  return { sql: clauses.join(' AND '), params, predicateCount: clauses.length }
+}
+
+/**
+ * Quote caller text as one FTS5 phrase so query syntax remains inert data.
+ * @param query - normalized caller query.
+ * @returns FTS5 expression containing one escaped literal phrase.
+ */
+export function quoteFtsData(query: string): string {
+  return `"${query.replaceAll('"', '""')}"`
+}
+
+/**
+ * Remove reserved marker collisions before text enters FTS5 or MATCH.
+ * @param text - extracted document text or normalized caller query.
+ * @returns text with reserved noncharacters mapped to replacement characters.
+ */
+export function sanitizeFtsText(text: string): string {
+  return text
+    .replaceAll('\0', '\uFFFD')
+    .replaceAll(FTS_HIGHLIGHT_START, '\uFFFD')
+    .replaceAll(FTS_HIGHLIGHT_END, '\uFFFD')
+}
+
+/**
+ * Build the stable normalized request identity stored in opaque cursors.
+ * @param request - normalized request whose filter ordering is canonicalized.
+ * @returns deterministic JSON identity for cursor binding.
+ */
+export function requestFingerprint(request: NormalizedSessionRequest | NormalizedEventRequest): string {
+  if ('sessionId' in request) {
+    return JSON.stringify({
+      scope: 'events',
+      sessionId: request.sessionId,
+      query: request.query,
+      filters: canonicalFilters(request.filters),
+      limit: request.limit,
+    })
+  }
+  return JSON.stringify({
+    scope: 'sessions',
+    query: request.query,
+    sessionFilters: canonicalFilters(request.sessionFilters),
+    eventFilters: canonicalFilters(request.eventFilters),
+    limit: request.limit,
+  })
+}
+
+/**
+ * Build a whitespace-normalized excerpt no longer than `maxChars`.
+ * @param markedText - complete document with FTS5 `highlight()` markers.
+ * @param maxChars - maximum result length in Unicode code points.
+ * @returns bounded plain-text snippet.
+ */
+export function makeSnippet(markedText: string, maxChars: number): string {
+  const { text: clean, matchStart } = normalizeMarkedText(markedText)
+  const characters = Array.from(clean)
+  if (characters.length <= maxChars) return clean
+  if (maxChars === 1) return '…'
+  const matchedIndex = Math.min(matchStart, characters.length - 1)
+  let start = Math.max(0, matchedIndex - Math.floor(maxChars / 3))
+  const prefix = start > 0 ? '…' : ''
+  let suffix = '…'
+  let contentLength = maxChars - prefix.length - suffix.length
+  if (contentLength < 1) {
+    start = matchedIndex
+    suffix = ''
+    contentLength = maxChars - prefix.length - suffix.length
+  } else if (matchedIndex >= start + contentLength) {
+    start = matchedIndex - contentLength + 1
+  }
+  let end = Math.min(characters.length, start + contentLength)
+  if (end === characters.length) {
+    suffix = ''
+    contentLength = maxChars - prefix.length
+    start = Math.max(0, end - contentLength)
+  }
+  end = Math.min(characters.length, start + contentLength)
+  return `${prefix}${characters.slice(start, end).join('')}${suffix}`
+}
+
+function normalizeMarkedText(markedText: string): { text: string; matchStart: number } {
+  const characters: string[] = []
+  let matchStart: number | undefined
+  for (const character of markedText) {
+    if (character === FTS_HIGHLIGHT_START) {
+      matchStart ??= characters.length
+      continue
+    }
+    if (character === FTS_HIGHLIGHT_END) continue
+    if (/\s/u.test(character)) {
+      if (characters.length > 0 && characters.at(-1) !== ' ') characters.push(' ')
+    } else {
+      characters.push(character)
+    }
+  }
+  if (characters.at(-1) === ' ') characters.pop()
+  return {
+    text: characters.join(''),
+    matchStart: matchStart ?? 0,
+  }
+}
+
+function normalizeQuery(value: string): string {
+  if (typeof value !== 'string') {
+    throw new SessionQueryError('session-search query must be text', 'SESSION_QUERY_INVALID_QUERY')
+  }
+  const query = value.trim().replace(/\s+/gu, ' ')
+  if (query.length === 0) {
+    throw new SessionQueryError(
+      'session-search query must contain non-whitespace text',
+      'SESSION_QUERY_INVALID_QUERY',
+    )
+  }
+  if (query.includes('\0')) {
+    throw new SessionQueryError(
+      'session-search query must not contain NUL',
+      'SESSION_QUERY_INVALID_QUERY',
+    )
+  }
+  return sanitizeFtsText(query)
+}
+
+function materializeCursor(cursor: SessionSearchCursor | undefined): SessionSearchCursor | undefined {
+  if (cursor === undefined) return undefined
+  if (typeof cursor !== 'string') {
+    throw new SessionQueryError('session-search cursor must be text', 'SESSION_QUERY_INVALID_CURSOR')
+  }
+  return cursor
+}
+
+function materializeMetadataFilters(
+  filters: readonly SessionEventMetadataFilter[],
+): SessionEventMetadataFilter[] {
+  const candidates: readonly SessionEventResultFilter[] = filters
+  for (const filter of candidates) {
+    switch (filter.kind) {
+      case 'seq':
+      case 'time':
+      case 'type':
+      case 'surface':
+        break
+      case 'text':
+        throw new SessionQueryError(
+          'session-search metadata filters do not accept text clauses',
+          'SESSION_QUERY_INVALID_FILTER',
+        )
+      default:
+        unknownFilter(filter)
+    }
+  }
+  return materializeSessionEventResultFilters(filters) as SessionEventMetadataFilter[]
+}
+
+function normalizeLimit(value: number | undefined, limits: QueryLimits): number {
+  const limit = value ?? limits.defaultLimit
+  const maxLimit = Math.min(limits.maxLimit, SQLITE_MAX_PAGE_LIMIT)
+  if (
+    !Number.isSafeInteger(limit)
+    || limit < 1
+    || limit > maxLimit
+  ) {
+    throw new SessionQueryError(
+      `session-search limit must be an integer between 1 and ${maxLimit}`,
+      'SESSION_QUERY_INVALID_LIMIT',
+    )
+  }
+  return limit
+}
+
+function addList(
+  clauses: string[],
+  params: Array<string | number>,
+  column: string,
+  values: readonly (string | number)[],
+): void {
+  if (values.length === 0) {
+    clauses.push('0')
+    return
+  }
+  clauses.push(`${column} IN (${appendListBindings(params, values)})`)
+}
+
+function addNullableList(
+  clauses: string[],
+  params: Array<string | number>,
+  column: string,
+  values: readonly (string | null)[],
+): void {
+  if (values.length === 0) {
+    clauses.push('0')
+    return
+  }
+  const concrete = values.filter((value): value is string => value !== null)
+  const parts: string[] = []
+  if (concrete.length > 0) {
+    parts.push(`${column} IN (${appendListBindings(params, concrete)})`)
+  }
+  if (values.includes(null)) parts.push(`${column} IS NULL`)
+  clauses.push(`(${parts.join(' OR ')})`)
+}
+
+function addRange(
+  clauses: string[],
+  params: Array<string | number>,
+  column: string,
+  range: { from?: number; to?: number },
+): void {
+  if (range.from !== undefined) {
+    assertPortableBindingCount(params.length + 1)
+    clauses.push(`CAST(${column} AS INTEGER) >= ?`)
+    params.push(range.from)
+  }
+  if (range.to !== undefined) {
+    assertPortableBindingCount(params.length + 1)
+    clauses.push(`CAST(${column} AS INTEGER) <= ?`)
+    params.push(range.to)
+  }
+}
+
+function appendListBindings(
+  params: Array<string | number>,
+  values: readonly (string | number)[],
+): string {
+  assertPortableBindingCount(params.length + values.length)
+  for (const value of values) params.push(value)
+  return values.map(() => '?').join(', ')
+}
+
+function canonicalFilters(filters: readonly (SessionResultFilter | SessionEventMetadataFilter)[]): unknown[] {
+  return filters.map((filter) => {
+    if ('values' in filter) {
+      return { ...filter, values: [...filter.values].sort(compareNullable) }
+    }
+    return {
+      kind: filter.kind,
+      from: filter.from ?? null,
+      to: filter.to ?? null,
+    }
+  }).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))
+}
+
+function compareNullable(a: string | null, b: string | null): number {
+  if (a === b) return 0
+  if (a === null) return -1
+  if (b === null) return 1
+  return a.localeCompare(b)
+}
+
+function unknownAvailability(value: never): never {
+  throw new SessionQueryError(
+    `session availability filter contains unknown value "${String(value)}"`,
+    'SESSION_QUERY_INVALID_FILTER',
+  )
+}
+
+function unknownFilter(filter: never): never {
+  const kind = (filter as { kind?: unknown }).kind
+  throw new SessionQueryError(
+    `session filter contains unknown kind ${typeof kind === 'string' ? `"${kind}"` : '(missing)'}`,
+    'SESSION_QUERY_INVALID_FILTER',
+  )
+}

packages/session-query/session-query-sqlite/src/schema.ts

@@ -0,0 +1,170 @@
+/** SQLite schema for the disposable session full-text read model. */
+
+import { DatabaseSync } from 'node:sqlite'
+import { mkdir, open } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+
+/** Current derived-index schema version. Incompatible versions reset in place. */
+export const SESSION_QUERY_SQLITE_SCHEMA_VERSION = 3
+
+/** SQLite application id protecting unrelated databases from derived resets. */
+export const SESSION_QUERY_SQLITE_APPLICATION_ID = 0x44534851
+
+/** Supported SQLite journal modes. */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+
+const DERIVED_USER_TABLES = new Set([
+  'search_state',
+  'persisted_sessions',
+  'persisted_docs',
+  'persisted_docs_data',
+  'persisted_docs_idx',
+  'persisted_docs_content',
+  'persisted_docs_docsize',
+  'persisted_docs_config',
+])
+
+/**
+ * Exclusively create a missing database file with owner-only permissions.
+ * Existing files retain their modes, and errors other than `EEXIST` propagate.
+ */
+async function createDatabaseFile(path: string): Promise<void> {
+  try {
+    const handle = await open(path, 'wx', 0o600)
+    await handle.close()
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+  }
+}
+
+/**
+ * Open, validate, and initialize persistent and connection-local schemas.
+ * @param path - dedicated derived-index path or `:memory:`; missing filesystem paths are created owner-only.
+ * @param journalMode - validated SQLite journal mode.
+ * @returns initialized database handle owned by the search service.
+ */
+export async function openSearchDatabase(path: string, journalMode: JournalMode): Promise<DatabaseSync> {
+  const actual = path === ':memory:' ? path : resolve(path)
+  if (actual !== ':memory:') {
+    await mkdir(dirname(actual), { recursive: true, mode: 0o700 })
+    await createDatabaseFile(actual)
+  }
+  const db = new DatabaseSync(actual)
+  try {
+    const { application_id: applicationId } = db.prepare('PRAGMA application_id').get() as { application_id: number }
+    const { user_version: version } = db.prepare('PRAGMA user_version').get() as { user_version: number }
+    const userTables = listUserTables(db)
+    if (applicationId !== 0 && applicationId !== SESSION_QUERY_SQLITE_APPLICATION_ID) {
+      throw new Error(`session-search database at "${actual}" belongs to another application`)
+    }
+    if (applicationId === 0 && userTables.length > 0) {
+      throw new Error(`session-search database at "${actual}" is not an empty or recognized derived index`)
+    }
+    if (applicationId === SESSION_QUERY_SQLITE_APPLICATION_ID) {
+      assertDerivedUserTables(actual, userTables)
+      if (version !== SESSION_QUERY_SQLITE_SCHEMA_VERSION) resetDerivedSchema(db, userTables)
+    }
+    // Apply mutating pragmas only after refusing foreign or canonical files.
+    // journalMode is a validated closed union, not caller-controlled SQL.
+    db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
+    ensurePersistentSchema(db)
+    ensureTemporarySchema(db)
+    return db
+  } catch (error: unknown) {
+    db.close()
+    throw error
+  }
+}
+
+function listUserTables(db: DatabaseSync): string[] {
+  const rows = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+  ).all() as Array<{ name: string }>
+  return rows.map(row => row.name)
+}
+
+function assertDerivedUserTables(path: string, userTables: readonly string[]): void {
+  const unknownTables = userTables.filter(name => !DERIVED_USER_TABLES.has(name))
+  if (unknownTables.length > 0) {
+    throw new Error(
+      `session-search database at "${path}" has unrecognized user tables: ${unknownTables.join(', ')}`,
+    )
+  }
+}
+
+function resetDerivedSchema(db: DatabaseSync, userTables: readonly string[]): void {
+  for (const name of userTables) {
+    db.exec(`DROP TABLE IF EXISTS ${quoteIdentifier(name)}`)
+  }
+  db.exec('PRAGMA user_version = 0')
+}
+
+function ensurePersistentSchema(db: DatabaseSync): void {
+  db.exec(`PRAGMA application_id = ${SESSION_QUERY_SQLITE_APPLICATION_ID}`)
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS search_state (
+      singleton         INTEGER PRIMARY KEY CHECK (singleton = 1),
+      global_generation INTEGER NOT NULL
+    ) STRICT
+  `)
+  db.exec('INSERT OR IGNORE INTO search_state (singleton, global_generation) VALUES (1, 0)')
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS persisted_sessions (
+      id             TEXT PRIMARY KEY,
+      version        INTEGER NOT NULL,
+      created_at     INTEGER NOT NULL,
+      cwd            TEXT,
+      parent_session TEXT,
+      seed_length    INTEGER,
+      delegation_depth INTEGER,
+      revision       TEXT NOT NULL,
+      generation     INTEGER NOT NULL
+    ) STRICT
+  `)
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS persisted_docs USING fts5(
+      text,
+      session_id UNINDEXED,
+      seq UNINDEXED,
+      type UNINDEXED,
+      time UNINDEXED,
+      surface UNINDEXED,
+      codepoint_length UNINDEXED,
+      tokenize = 'unicode61'
+    )
+  `)
+  db.exec(`PRAGMA user_version = ${SESSION_QUERY_SQLITE_SCHEMA_VERSION}`)
+}
+
+function ensureTemporarySchema(db: DatabaseSync): void {
+  db.exec(`
+    CREATE TEMP TABLE IF NOT EXISTS live_sessions (
+      id             TEXT PRIMARY KEY,
+      version        INTEGER NOT NULL,
+      created_at     INTEGER NOT NULL,
+      cwd            TEXT,
+      parent_session TEXT,
+      seed_length    INTEGER,
+      delegation_depth INTEGER,
+      fingerprint    TEXT NOT NULL,
+      persisted      INTEGER NOT NULL CHECK (persisted IN (0, 1)),
+      generation     INTEGER NOT NULL
+    ) STRICT
+  `)
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS temp.live_docs USING fts5(
+      text,
+      session_id UNINDEXED,
+      seq UNINDEXED,
+      type UNINDEXED,
+      time UNINDEXED,
+      surface UNINDEXED,
+      codepoint_length UNINDEXED,
+      tokenize = 'unicode61'
+    )
+  `)
+}
+
+function quoteIdentifier(value: string): string {
+  return `"${value.replaceAll('"', '""')}"`
+}

packages/session-query/session-query-sqlite/tests/load-path.e2e.ts

@@ -0,0 +1,62 @@
+/**
+ * Keyless real-Loader-path smoke for the combined SQLite session-query service.
+ *
+ * @module @deepseek-ai/dsh-session-query-sqlite/tests/load-path
+ */
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
+import SessionQuerySqlite, * as queryModule from '@deepseek-ai/dsh-session-query-sqlite'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    await rm(directory, { recursive: true, force: true })
+  }
+})
+
+async function temporaryPath(name: string): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-session-search-loader-'))
+  temporaryDirectories.push(directory)
+  return join(directory, name)
+}
+
+describe('dsh-session-query-sqlite real Loader path', () => {
+  it('unwraps, mounts, and searches the real persistence backend', async () => {
+    const persistencePath = await temporaryPath('canonical.db')
+    const searchPath = await temporaryPath('derived.db')
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const persistence = await ctx.plugin(SessionPersistenceSqlite, { path: persistencePath })
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(queryModule) as Parameters<Context['plugin']>[0]
+    expect(unwrapped).toBe(SessionQuerySqlite)
+    const query = await ctx.plugin(unwrapped, { path: searchPath })
+
+    const id = SessionId('loader-path')
+    await ctx.sessionPersistence.create({ version: SESSION_FORMAT_VERSION, id, createdAt: 10 })
+    await ctx.sessionPersistence.append(id, [{
+      type: 'user/message',
+      seq: 0,
+      time: 10,
+      data: { content: [{ type: 'text', text: 'real Loader needle' }], source: { kind: 'user' } },
+      surfaceOp: 'append',
+    }])
+
+    await expect(ctx.sessionQuery.searchSessions({ query: 'Loader needle' }))
+      .resolves.toMatchObject({ items: [{ header: { id }, persisted: true, live: false }] })
+    await expect(ctx.sessionQuery.listSessions())
+      .resolves.toMatchObject([{ header: { id }, persisted: true, live: false }])
+    await query.dispose()
+    await persistence.dispose()
+  })
+})

packages/session-query/session-query-sqlite/tests/query.spec.ts

@@ -0,0 +1,262 @@
+import { describe, expect, it } from 'vitest'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionSearchCursor, type SessionQueryErrorCode } from '@deepseek-ai/dsh-session-query'
+import {
+  buildEventWhere,
+  buildSessionWhere,
+  FTS_HIGHLIGHT_END,
+  FTS_HIGHLIGHT_START,
+  makeSnippet,
+  normalizeEventRequest,
+  normalizeSessionRequest,
+  quoteFtsData,
+  requestFingerprint,
+  SQLITE_FTS5_OUTER_PREDICATE_LIMIT,
+  SQLITE_MAX_PAGE_LIMIT,
+  type NormalizedEventRequest,
+  type NormalizedSessionRequest,
+} from '../src/query.ts'
+
+const limits = { defaultLimit: 2, maxLimit: 3 }
+
+function expectCode(code: SessionQueryErrorCode): Error {
+  return expect.objectContaining({ code }) as Error
+}
+
+describe('SQLite search request normalization', () => {
+  it('normalizes both scopes, defaults arrays and limits, and preserves cursors', () => {
+    expect(normalizeSessionRequest({ query: '  alpha\n beta  ' }, limits)).toEqual({
+      query: 'alpha beta',
+      sessionFilters: [],
+      eventFilters: [],
+      limit: 2,
+    })
+    expect(normalizeSessionRequest({
+      query: 'needle',
+      sessionFilters: [{ kind: 'availability', values: ['live'] }],
+      eventFilters: [{ kind: 'surface', values: ['current'] }],
+      limit: 3,
+      cursor: SessionSearchCursor('next'),
+    }, limits)).toEqual({
+      query: 'needle',
+      sessionFilters: [{ kind: 'availability', values: ['live'] }],
+      eventFilters: [{ kind: 'surface', values: ['current'] }],
+      limit: 3,
+      cursor: SessionSearchCursor('next'),
+    })
+    expect(normalizeEventRequest({ sessionId: SessionId('s'), query: 'needle' }, limits)).toEqual({
+      sessionId: SessionId('s'),
+      query: 'needle',
+      filters: [],
+      limit: 2,
+    })
+    expect(normalizeEventRequest({
+      sessionId: SessionId('s'),
+      query: 'needle',
+      filters: [{ kind: 'seq', from: 1 }],
+      cursor: SessionSearchCursor('next'),
+    }, limits)).toEqual({
+      sessionId: SessionId('s'),
+      query: 'needle',
+      filters: [{ kind: 'seq', from: 1 }],
+      limit: 2,
+      cursor: SessionSearchCursor('next'),
+    })
+  })
+
+  it('rejects non-text, blank, non-integer, non-positive, and oversized requests', () => {
+    expect(() => normalizeSessionRequest({ query: 1 as never }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_QUERY'))
+    expect(() => normalizeSessionRequest({ query: ' \n ' }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_QUERY'))
+    expect(() => normalizeSessionRequest({ query: 'bad\0query' }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_QUERY'))
+    expect(() => normalizeEventRequest({ sessionId: 1 as never, query: 'x' }, limits))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => normalizeEventRequest({
+      sessionId: SessionId('s'),
+      query: 'x',
+      cursor: 1 as never,
+    }, limits)).toThrow(expectCode('SESSION_QUERY_INVALID_CURSOR'))
+    expect(() => normalizeSessionRequest({
+      query: 'x',
+      eventFilters: [{ kind: 'text', text: 'x' } as never],
+    }, limits)).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => normalizeSessionRequest({
+      query: 'x',
+      eventFilters: [{} as never],
+    }, limits)).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    for (const limit of [1.5, 0, 4]) {
+      expect(() => normalizeEventRequest({ sessionId: SessionId('s'), query: 'x', limit }, limits))
+        .toThrow(expectCode('SESSION_QUERY_INVALID_LIMIT'))
+    }
+    expect(() => normalizeEventRequest({
+      sessionId: SessionId('s'),
+      query: 'x',
+      limit: SQLITE_MAX_PAGE_LIMIT + 1,
+    }, { defaultLimit: 1, maxLimit: SQLITE_MAX_PAGE_LIMIT + 1 }))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_LIMIT'))
+  })
+
+  it('materializes owned filter values during normalization', () => {
+    const values = ['live'] as Array<'live' | 'persisted'>
+    const filter = { kind: 'availability' as const, values }
+    const request = { query: 'needle', sessionFilters: [filter] }
+    const normalized = normalizeSessionRequest(request, limits)
+
+    values[0] = 'persisted'
+    request.sessionFilters.push({ kind: 'availability', values: ['persisted'] })
+    expect(normalized.sessionFilters).toEqual([{ kind: 'availability', values: ['live'] }])
+  })
+})
+
+describe('SQLite search predicate compilation', () => {
+  it('compiles all logical-session clauses including empty and nullable values', () => {
+    expect(buildSessionWhere([])).toEqual({ sql: '', params: [], predicateCount: 0 })
+    expect(buildSessionWhere([{ kind: 'id', values: [] }])).toEqual({
+      sql: '0',
+      params: [],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'id', values: [SessionId('a'), SessionId('b')] }])).toEqual({
+      sql: 'session_id IN (?, ?)',
+      params: [SessionId('a'), SessionId('b')],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'cwd', values: [] }])).toEqual({
+      sql: '0',
+      params: [],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'cwd', values: [null] }])).toEqual({
+      sql: '(cwd IS NULL)',
+      params: [],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'cwd', values: ['/a'] }])).toEqual({
+      sql: '(cwd IN (?))',
+      params: ['/a'],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([{ kind: 'parent', values: [SessionId('p'), null] }])).toEqual({
+      sql: '(parent_session IN (?) OR parent_session IS NULL)',
+      params: [SessionId('p')],
+      predicateCount: 1,
+    })
+    expect(buildSessionWhere([
+      { kind: 'created-at', from: 1, to: 2 },
+      { kind: 'availability', values: [] },
+      { kind: 'availability', values: ['live', 'live'] },
+      { kind: 'availability', values: ['live', 'persisted'] },
+    ])).toEqual({
+      sql: 'CAST(created_at AS INTEGER) >= ? AND CAST(created_at AS INTEGER) <= ? AND 0 AND live = 1',
+      params: [1, 2],
+      predicateCount: 4,
+    })
+    expect(buildSessionWhere([{ kind: 'created-at' }])).toEqual({
+      sql: '',
+      params: [],
+      predicateCount: 0,
+    })
+  })
+
+  it('compiles every event clause and empty lists', () => {
+    expect(buildEventWhere([
+      { kind: 'seq', from: 1 },
+      { kind: 'time', to: 9 },
+      { kind: 'type', values: ['user/message'] },
+      { kind: 'surface', values: ['current', 'log-only'] },
+    ])).toEqual({
+      sql: 'CAST(seq AS INTEGER) >= ? AND CAST(time AS INTEGER) <= ? AND type IN (?) AND surface IN (?, ?)',
+      params: [1, 9, 'user/message', 'current', 'log-only'],
+      predicateCount: 4,
+    })
+    expect(buildEventWhere([
+      { kind: 'type', values: [] },
+      { kind: 'surface', values: [] },
+    ])).toEqual({ sql: '0 AND 0', params: [], predicateCount: 2 })
+  })
+
+  it('rejects predicate builders above the supported FTS5 outer budget', () => {
+    const filters = Array.from(
+      { length: SQLITE_FTS5_OUTER_PREDICATE_LIMIT },
+      () => ({ kind: 'id' as const, values: [SessionId('safe')] }),
+    )
+
+    expect(buildSessionWhere(filters).predicateCount).toBe(SQLITE_FTS5_OUTER_PREDICATE_LIMIT)
+    expect(() => buildSessionWhere([
+      ...filters,
+      { kind: 'id', values: [SessionId('over')] },
+    ])).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('rejects runtime-unknown filter discriminants in both SQL builders', () => {
+    expect(() => buildSessionWhere([{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => buildEventWhere([{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => buildSessionWhere([{ kind: 'availability', values: ['future'] } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => buildSessionWhere([{} as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+})
+
+describe('SQLite query identity and presentation', () => {
+  it('quotes all caller MATCH syntax as data', () => {
+    expect(quoteFtsData('say "needle" OR *')).toBe('"say ""needle"" OR *"')
+  })
+
+  it('canonicalizes request and filter ordering in both scopes', () => {
+    const sessionA: NormalizedSessionRequest = {
+      query: 'needle',
+      limit: 2,
+      sessionFilters: [
+        { kind: 'cwd', values: ['/b', '/a'] },
+        { kind: 'parent', values: [null, SessionId('p')] },
+        { kind: 'id', values: [SessionId('same'), SessionId('same')] },
+        { kind: 'created-at', from: 1 },
+      ],
+      eventFilters: [{ kind: 'time', to: 9 }],
+    }
+    const sessionB: NormalizedSessionRequest = {
+      query: 'needle',
+      limit: 2,
+      sessionFilters: [
+        { kind: 'created-at', from: 1 },
+        { kind: 'id', values: [SessionId('same'), SessionId('same')] },
+        { kind: 'parent', values: [SessionId('p'), null] },
+        { kind: 'cwd', values: ['/a', '/b'] },
+      ],
+      eventFilters: [{ kind: 'time', to: 9 }],
+    }
+    expect(requestFingerprint(sessionA)).toBe(requestFingerprint(sessionB))
+
+    const eventA: NormalizedEventRequest = {
+      sessionId: SessionId('s'),
+      query: 'needle',
+      limit: 2,
+      filters: [{ kind: 'seq' }, { kind: 'surface', values: ['shadowed', 'current'] }],
+    }
+    const eventB: NormalizedEventRequest = {
+      sessionId: SessionId('s'),
+      query: 'needle',
+      limit: 2,
+      filters: [{ kind: 'surface', values: ['current', 'shadowed'] }, { kind: 'seq' }],
+    }
+    expect(requestFingerprint(eventA)).toBe(requestFingerprint(eventB))
+    expect(requestFingerprint(eventA)).not.toBe(requestFingerprint({ ...eventB, sessionId: SessionId('other') }))
+  })
+
+  it('normalizes, bounds, and positions snippets by Unicode code point', () => {
+    expect(makeSnippet('  short\ntext  ', 20)).toBe('short text')
+    expect(makeSnippet(`abcde${FTS_HIGHLIGHT_START}f${FTS_HIGHLIGHT_END}`, 1)).toBe('…')
+    expect(makeSnippet('abcdefghij', 5)).toBe('abcd…')
+    expect(makeSnippet(`ab${FTS_HIGHLIGHT_START}c${FTS_HIGHLIGHT_END}defghij`, 5)).toBe('…bcd…')
+    expect(makeSnippet(`ab${FTS_HIGHLIGHT_START}c${FTS_HIGHLIGHT_END}defghij`, 3)).toBe('…c…')
+    expect(makeSnippet(`abcde${FTS_HIGHLIGHT_START}f${FTS_HIGHLIGHT_END}`, 2)).toBe('…f')
+    expect(makeSnippet(`abcde${FTS_HIGHLIGHT_START}f${FTS_HIGHLIGHT_END}`, 5)).toBe('…cdef')
+    expect(makeSnippet(`  x—${FTS_HIGHLIGHT_START}café${FTS_HIGHLIGHT_END}\n y  `, 20))
+      .toBe('x—café y')
+  })
+})

packages/session-query/session-query-sqlite/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../session-query"
+    }
+  ]
+}

packages/session-query/session-query/README.md

@@ -1,10 +1,12 @@
 # @deepseek-ai/dsh-session-query
 
-Exact session-history retrieval and relationship tracing 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`.
+`SessionQueryService` is the combined abstract `ctx.sessionQuery` contract. It implements exact session-history retrieval, relationship tracing, and provider-independent filtering over live `ctx.sessions` plus optional dynamically mounted `ctx.sessionPersistence`; concrete backends implement its two full-text methods. 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.
+- `filterSessions(filters)` applies provider-independent session metadata and availability predicates to that same cloned logical corpus.
+- `filterEvents(sessionId, filters)` extracts first-party semantic documents and applies provider-independent metadata and literal-text predicates in ascending seq order.
 - `readTitle(sessionId)` loads one live-preferred or persisted log and folds its latest `session/title` event into a `SessionTitleSnapshot`; it returns `undefined` when the known session has no title.
 - `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.
 - `readSurface(sessionId)` returns one cloned header, raw-log capture boundary, and the complete folded current surface in model-history order. A live session wins over persistence; compaction is observed before or after its replacement append, never as a synthetic mixture.
@@ -14,9 +16,21 @@ Exact session-history retrieval and relationship tracing through `ctx.sessionQue
 
 Persistence is optional and may mount or unmount dynamically. Cross-corpus listing and lineage tracing fail with `SESSION_QUERY_PERSISTENCE_FAILED` while mounted persistence is unreadable. A title, event read, or trace targeting a known live session does not consult persistence, so durable backend health cannot make current in-memory state unreadable. Persisted title and event operations list before loading and reject a metadata mismatch rather than combining inconsistent observations. `listSessions()` remains lightweight and does not load logs or index titles.
 
-`listEvents()`, `readSurface()`, and `traceEvent()` run the same one-pass `dsh-session` surface fold. A loaded log is valid only when event seqs are zero-based and contiguous, surface markers obey event-type eligibility, provenance arrays are nonempty and duplicate-free, references name earlier events, and each positional replacement names and cites every surface node it removes; every violation fails with `SESSION_QUERY_INVALID_SURFACE`.
+## Filtering and extraction
 
-`SessionQueryError.code` is a closed union: `SESSION_QUERY_EVENT_NOT_FOUND`, `SESSION_QUERY_INVALID_CONFIG`, `SESSION_QUERY_INVALID_LINEAGE`, `SESSION_QUERY_INVALID_SURFACE`, `SESSION_QUERY_INVALID_WINDOW`, `SESSION_QUERY_PERSISTENCE_FAILED`, `SESSION_QUERY_SESSION_NOT_FOUND`, and `SESSION_QUERY_SOURCE_CONFLICT`.
+`SessionResultFilter` covers id, nullable cwd, created-at range, nullable parent, and source availability. `SessionEventResultFilter` covers seq/time ranges, event type, surface, and semantic text. Filter arrays are ANDed; values within one list clause are ORed. Empty list values match nothing, ranges are inclusive, and malformed ranges or closed-union values fail with `SESSION_QUERY_INVALID_FILTER`.
+
+The text clause is deliberately independent of FTS providers: caller text is escaped into a Unicode, case-insensitive regular expression, and each whitespace run matches one or more whitespace characters. It is a literal semantic-text scan, not a full-text query. `extractSessionEventText()` and `buildSessionEventSearchDocuments()` define the shared first-party document projection; structural boundaries, stream chunks, request headers, and unknown declaration-merged variants produce no document.
+
+## Full-text methods
+
+`SessionQueryService.searchSessions(request, exec?)` groups the logical corpus by strongest matching event; `searchEvents(request, exec?)` searches one logical session. These are the service's only abstract methods. Both return pages whose continuation is an owned branded `SessionSearchCursor`, accept optional cancellation, and expose snippets without provider-specific numeric scores. Search requests accept only metadata event filters, because literal-text filtering is the scan path described above.
+
+The package has no provider coordinator, fallback implementation, or standalone concrete plugin. A concrete service backend inherits the implemented reads, filters, and traces while owning full-text observation, reconciliation, ranking, cursor generations, and query execution; the first implementation is [`@deepseek-ai/dsh-session-query-sqlite`](../session-query-sqlite/README.md).
+
+`SessionQueryError.code` is a closed union covering request validation, missing targets, malformed surfaces, source conflicts, persistence/index failures, cancellation, and invalid or stale cursors; the exact literals are defined in [`src/config.ts`](src/config.ts).
+
+`listEvents()`, `readSurface()`, and `traceEvent()` run the same one-pass `dsh-session` surface fold. A loaded log is valid only when event seqs are zero-based and contiguous, surface markers obey event-type eligibility, provenance arrays are nonempty and duplicate-free, references name earlier events, and each positional replacement names and cites every surface node it removes; every violation fails with `SESSION_QUERY_INVALID_SURFACE`.
 
 ## Configuration
 
@@ -35,4 +49,4 @@ None; this package neither assembles nor sends a provider request.
 ## 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.
-- **No search or extraction** — filters, extraction registry, search-provider protocol, index synchronization, and a model-facing tool are absent. The [tracing decision](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) owns relationship semantics; content-bearing full-text-search results and their chainable filters belong beside their first implementation in the proposed [SQLite package](../../../.agents/notes/proposed/feature/2026-07-10-sqlite-session-query-provider.md).
+- **No registries or model-facing tool** — extractor and search-provider registries, recursive event-provenance traversal, and a model-facing tool are absent. The [tracing decision](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) owns relationship semantics; SQLite ownership and tokenizer decisions live in the [implemented search note](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md).

packages/session-query/session-query/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-session-query",
-  "description": "Live-preferred exact session-history retrieval and tracing service (ctx.sessionQuery)",
+  "description": "Combined session query service contract with concrete reads, traces, and filters",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -27,6 +27,7 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -39,10 +40,8 @@
       "optional": true
     }
   },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",

packages/session-query/session-query/src/config.ts

@@ -1,25 +1,32 @@
-/** Public configuration and typed failures for session-query. */
+/** Public configuration and typed failures for the combined session-query service. */
 
 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 and traces. */
+/** Backend-independent configuration inherited by every session-query implementation. */
 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 and traces. */
+/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
 export type SessionQueryErrorCode =
+  | 'SESSION_QUERY_ABORTED'
   | 'SESSION_QUERY_EVENT_NOT_FOUND'
+  | 'SESSION_QUERY_INDEX_FAILED'
   | 'SESSION_QUERY_INVALID_CONFIG'
+  | 'SESSION_QUERY_INVALID_CURSOR'
+  | 'SESSION_QUERY_INVALID_FILTER'
+  | 'SESSION_QUERY_INVALID_LIMIT'
+  | 'SESSION_QUERY_INVALID_QUERY'
   | 'SESSION_QUERY_INVALID_LINEAGE'
   | 'SESSION_QUERY_INVALID_SURFACE'
   | 'SESSION_QUERY_INVALID_WINDOW'
   | 'SESSION_QUERY_PERSISTENCE_FAILED'
   | 'SESSION_QUERY_SESSION_NOT_FOUND'
+  | 'SESSION_QUERY_STALE_CURSOR'
   | 'SESSION_QUERY_SOURCE_CONFLICT'
 
 /** Typed session-query failure whose `code` is one closed taxonomy member. */

packages/session-query/session-query/src/corpus.ts

@@ -1,10 +1,11 @@
 /** Live/persisted logical-corpus resolution for session-query. */
 
-import type { Context } from 'cordis'
+import type { Context, Fiber } 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'
+import { assertSessionHeadersCompatible } from './sources.ts'
 
 /** Detached source selected for one exact read. */
 export interface LogicalSession {
@@ -17,18 +18,19 @@ export interface LogicalSession {
 /** Resolves a live-preferred corpus against the persistence service mounted now. */
 export class SessionCorpus {
   private _persistence: SessionPersistence | undefined
+  private readonly _optionalPersistenceFiber: Fiber
 
   constructor(private readonly _ctx: Context) {
+    this._optionalPersistenceFiber = _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')
+    })
     _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()
+      return () => this._optionalPersistenceFiber.dispose()
     }, 'sessionQuery.optionalPersistence')
   }
 
@@ -45,7 +47,7 @@ export class SessionCorpus {
     }
     for (const session of this._ctx.sessions.list()) {
       const durable = records.get(session.id)
-      if (durable !== undefined) assertCompatibleHeaders(session.header, durable.header)
+      if (durable !== undefined) assertSessionHeadersCompatible(session.header, durable.header)
       records.set(session.id, {
         header: structuredClone(session.header),
         live: true,
@@ -70,17 +72,19 @@ export class SessionCorpus {
     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']>>
+    let loaded: Awaited<ReturnType<SessionPersistence['inspect']>>
     try {
-      loaded = await persistence.load(sessionId)
+      loaded = await persistence.inspect(sessionId)
     } catch (error: unknown) {
       throw new SessionQueryError(
-        `failed to load session "${sessionId}": ${errorMessage(error)}`,
+        `failed to inspect session "${sessionId}": ${errorMessage(error)}`,
         'SESSION_QUERY_PERSISTENCE_FAILED',
         { cause: error },
       )
     }
-    assertCompatibleHeaders(loaded.meta, listed)
+    const attached = this._ctx.sessions.get(sessionId)
+    if (attached !== undefined) return snapshotLive(attached)
+    assertSessionHeadersCompatible(loaded.meta, listed)
     return {
       header: structuredClone(loaded.meta),
       events: loaded.events.map(event => structuredClone(event)),
@@ -107,22 +111,6 @@ function snapshotLive(session: Session): LogicalSession {
   }
 }
 
-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)
 }

packages/session-query/session-query/src/cursor.ts

@@ -0,0 +1,15 @@
+/** Opaque cursor identity for session-search pagination. */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Provider-owned opaque continuation token returned by session search. */
+export type SessionSearchCursor = Branded<'SessionSearchCursor'>
+
+/**
+ * Brand an encoded provider cursor for the public search contract.
+ * @param value - opaque encoded cursor value.
+ * @returns the same runtime string with session-search cursor identity.
+ */
+export function SessionSearchCursor(value: string): SessionSearchCursor {
+  return value as SessionSearchCursor
+}

packages/session-query/session-query/src/documents.ts

@@ -0,0 +1,74 @@
+/** Shared event metadata and semantic-document projection. */
+
+import { foldSurface } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEventRecord, SessionEventSearchDocument, SessionEventSurface } from './types.ts'
+import { SessionQueryError } from './config.ts'
+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.
+ * @returns one record per event in ascending seq order.
+ */
+export function buildSessionEventRecords(
+  sessionId: SessionId,
+  events: readonly SessionEvent[],
+): SessionEventRecord[] {
+  const surfaceBySeq = classifySurface(events)
+  return events.map(event => ({
+    sessionId,
+    seq: event.seq,
+    type: event.type,
+    time: event.time,
+    surface: surfaceBySeq.get(event.seq) ?? 'log-only',
+  }))
+}
+
+/**
+ * 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.
+ * @returns searchable documents in ascending seq order; structural events are omitted.
+ */
+export function buildSessionEventSearchDocuments(
+  sessionId: SessionId,
+  events: readonly SessionEvent[],
+): SessionEventSearchDocument[] {
+  const surfaceBySeq = classifySurface(events)
+  const documents: SessionEventSearchDocument[] = []
+  for (const event of events) {
+    const text = extractSessionEventText(event)
+    if (text.length === 0) continue
+    documents.push({
+      sessionId,
+      seq: event.seq,
+      type: event.type,
+      time: event.time,
+      surface: surfaceBySeq.get(event.seq) ?? 'log-only',
+      text,
+    })
+  }
+  return documents
+}
+
+function classifySurface(events: readonly SessionEvent[]): Map<number, SessionEventSurface> {
+  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 result = new Map<number, SessionEventSurface>()
+  for (const seq of folded.nodes) result.set(seq, 'current')
+  for (const replacement of folded.replacements) {
+    for (const seq of replacement.shadowedSeqs) result.set(seq, 'shadowed')
+  }
+  return result
+}

packages/session-query/session-query/src/extraction.ts

@@ -0,0 +1,93 @@
+/** First-party semantic text extraction for session-query consumers. */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/**
+ * Extract searchable semantic text from one first-party session event.
+ *
+ * Structural boundaries, raw stream chunks, request envelopes, and unknown
+ * declaration-merged events contribute no text.
+ * @param event - event to inspect.
+ * @returns newline-joined semantic text, or an empty string when non-searchable.
+ */
+export function extractSessionEventText(event: SessionEvent): string {
+  switch (event.type) {
+    case 'user/message':
+    case 'assistant/message':
+    case 'steering/message':
+      return contentText(event.data.content)
+    case 'prompt/blocked':
+      return joinText([contentText(event.data.content), event.data.reason])
+    case 'tool/call':
+      return joinText([event.data.name, event.data.arguments])
+    case 'tool/result':
+      return joinText([
+        contentText(event.data.content),
+        event.data.error?.name ?? '',
+        event.data.error?.code ?? '',
+      ])
+    case 'todo/write':
+      return joinText(event.data.todos.flatMap(todo => [todo.status, todo.content]))
+    case 'turn/end':
+      return turnEndText(event.data.reason)
+    case 'turn/start':
+    case 'step/start':
+    case 'step/end':
+    case 'assistant/chunk':
+    case 'request/header':
+      return ''
+    // SessionEventMap is merge-extensible. Unknown events remain
+    // non-searchable until a concrete first-party consumer defines semantics.
+    default:
+      return ''
+  }
+}
+
+function turnEndText(reason: SessionEvent<'turn/end'>['data']['reason']): string {
+  switch (reason.kind) {
+    case 'error':
+      return 'failure' in reason
+        ? joinText(['error', reason.failure.message, reason.failure.code])
+        : joinText(['error', reason.message, reason.code ?? ''])
+    case 'aborted':
+      return 'aborted'
+    case 'rejected':
+      return joinText(['rejected', reason.reason])
+    case 'disposed':
+    case 'max-tokens':
+    case 'interrupted':
+      return reason.kind
+    case 'completed':
+      return ''
+    // TurnEndReasonMap is merge-extensible. Unknown outcomes stay out until
+    // their owner defines which detail is semantic rather than structural.
+    default:
+      return ''
+  }
+}
+
+type SessionContentBlock = SessionEvent<'user/message'>['data']['content'][number]
+
+function contentText(content: readonly SessionContentBlock[]): string {
+  return joinText(content.flatMap(blockText))
+}
+
+function blockText(block: SessionContentBlock): string[] {
+  switch (block.type) {
+    case 'text':
+    case 'reasoning':
+      return [block.text]
+    case 'tool-call':
+      return [block.name, block.arguments]
+    case 'tool-result':
+      return block.content.flatMap(blockText)
+    // ContentBlockMap is merge-extensible. Unknown blocks do not become
+    // searchable merely because their payload happens to contain strings.
+    default:
+      return []
+  }
+}
+
+function joinText(parts: readonly string[]): string {
+  return parts.map(part => part.trim()).filter(Boolean).join('\n')
+}

packages/session-query/session-query/src/filters.ts

@@ -0,0 +1,243 @@
+/** Pure provider-independent predicates for logical sessions and event text. */
+
+import type {
+  SessionEventResultFilter,
+  SessionEventSearchDocument,
+  SessionRecord,
+  SessionResultFilter,
+  SessionResultRange,
+} from './types.ts'
+import { SessionQueryError } from './config.ts'
+
+/**
+ * Apply ANDed logical-session filters while preserving input order.
+ * @param records - detached logical-session records to inspect.
+ * @param filters - clauses whose list values are ORed within each clause.
+ * @returns records accepted by every clause.
+ */
+export function filterSessionResults<T extends SessionRecord>(
+  records: readonly T[],
+  filters: readonly SessionResultFilter[] = [],
+): T[] {
+  const predicates = filters.map(sessionPredicate)
+  return records.filter(record => predicates.every(predicate => predicate(record)))
+}
+
+/**
+ * Apply ANDed event filters to extracted semantic documents.
+ * @param documents - semantic documents produced by {@link buildSessionEventSearchDocuments}.
+ * @param filters - metadata and literal-text predicates.
+ * @returns documents accepted by every clause, in input order.
+ */
+export function filterSessionEventDocuments<T extends SessionEventSearchDocument>(
+  documents: readonly T[],
+  filters: readonly SessionEventResultFilter[] = [],
+): T[] {
+  const predicates = filters.map(eventPredicate)
+  return documents.filter(document => predicates.every(predicate => predicate(document)))
+}
+
+/**
+ * Copy and validate logical-session filters before an asynchronous boundary.
+ * @param filters - caller-owned clauses to materialize.
+ * @returns detached validated clauses.
+ */
+export function materializeSessionResultFilters(
+  filters: readonly SessionResultFilter[],
+): SessionResultFilter[] {
+  assertArray(filters)
+  return filters.map((filter) => {
+    switch (filter.kind) {
+      case 'id':
+        return { kind: filter.kind, values: copyStrings(filter.kind, filter.values) }
+      case 'cwd':
+        return { kind: filter.kind, values: copyNullableStrings(filter.kind, filter.values) }
+      case 'created-at':
+        return copyRange(filter.kind, filter)
+      case 'parent':
+        return { kind: filter.kind, values: copyNullableStrings(filter.kind, filter.values) }
+      case 'availability': {
+        const values = copyStrings(filter.kind, filter.values)
+        assertAllowedValues(filter.kind, values, ['live', 'persisted'])
+        return { kind: filter.kind, values }
+      }
+      default:
+        return unknownFilter(filter)
+    }
+  })
+}
+
+/**
+ * Copy and validate event filters before an asynchronous boundary.
+ * @param filters - caller-owned clauses to materialize.
+ * @returns detached validated clauses.
+ */
+export function materializeSessionEventResultFilters(
+  filters: readonly SessionEventResultFilter[],
+): SessionEventResultFilter[] {
+  assertArray(filters)
+  return filters.map((filter) => {
+    switch (filter.kind) {
+      case 'seq':
+      case 'time':
+        return copyRange(filter.kind, filter)
+      case 'type':
+        return { kind: filter.kind, values: copyStrings(filter.kind, filter.values) }
+      case 'surface': {
+        const values = copyStrings(filter.kind, filter.values)
+        assertAllowedValues(filter.kind, values, ['current', 'shadowed', 'log-only'])
+        return { kind: filter.kind, values }
+      }
+      case 'text':
+        if (typeof filter.text !== 'string') throw invalidFilter('text filter text must be a string')
+        return { kind: filter.kind, text: filter.text }
+      default:
+        return unknownFilter(filter)
+    }
+  })
+}
+
+/**
+ * Compile a literal case-insensitive, whitespace-flexible semantic-text match.
+ * @param text - caller-provided literal text.
+ * @returns Unicode-aware regular expression safe from regex injection.
+ */
+export function compileSessionTextFilter(text: string): RegExp {
+  const trimmed = text.trim()
+  if (trimmed.length === 0) {
+    throw new SessionQueryError(
+      'session text filter must contain non-whitespace text',
+      'SESSION_QUERY_INVALID_FILTER',
+    )
+  }
+  const pattern = trimmed
+    .split(/\s+/u)
+    .map(part => part.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'))
+    .join('\\s+')
+  return new RegExp(pattern, 'iu')
+}
+
+function sessionPredicate(filter: SessionResultFilter): (record: SessionRecord) => boolean {
+  switch (filter.kind) {
+    case 'id':
+      return record => filter.values.includes(record.header.id)
+    case 'cwd':
+      return record => filter.values.includes(record.header.cwd ?? null)
+    case 'created-at': {
+      const range = validateRange(filter.kind, filter)
+      return record => matchesRange(record.header.createdAt, range)
+    }
+    case 'parent':
+      return record => filter.values.includes(record.header.parentSession ?? null)
+    case 'availability':
+      assertAllowedValues(filter.kind, filter.values, ['live', 'persisted'])
+      return record => filter.values.some(value => value === 'live' ? record.live : record.persisted)
+    default:
+      return unknownFilter(filter)
+  }
+}
+
+function eventPredicate(filter: SessionEventResultFilter): (document: SessionEventSearchDocument) => boolean {
+  switch (filter.kind) {
+    case 'seq': {
+      const range = validateRange(filter.kind, filter)
+      return document => matchesRange(document.seq, range)
+    }
+    case 'time': {
+      const range = validateRange(filter.kind, filter)
+      return document => matchesRange(document.time, range)
+    }
+    case 'type':
+      return document => filter.values.includes(document.type)
+    case 'surface':
+      assertAllowedValues(filter.kind, filter.values, ['current', 'shadowed', 'log-only'])
+      return document => filter.values.includes(document.surface)
+    case 'text': {
+      const pattern = compileSessionTextFilter(filter.text)
+      return document => pattern.test(document.text)
+    }
+    default:
+      return unknownFilter(filter)
+  }
+}
+
+function copyStrings<T extends string>(name: string, values: readonly T[]): T[] {
+  if (!isRuntimeArray(values) || values.some(value => typeof value !== 'string')) {
+    throw invalidFilter(`${name} filter values must be an array of strings`)
+  }
+  return [...values]
+}
+
+function assertArray(value: unknown): void {
+  if (!Array.isArray(value)) throw invalidFilter('filters must be an array')
+}
+
+function copyNullableStrings<T extends string>(name: string, values: readonly (T | null)[]): Array<T | null> {
+  if (!isRuntimeArray(values) || values.some(value => value !== null && typeof value !== 'string')) {
+    throw invalidFilter(`${name} filter values must be an array of strings or null`)
+  }
+  return [...values]
+}
+
+function copyRange<K extends 'created-at' | 'seq' | 'time'>(
+  kind: K,
+  range: SessionResultRange,
+): { kind: K } & SessionResultRange {
+  const copy = {
+    kind,
+    ...range.from === undefined ? {} : { from: range.from },
+    ...range.to === undefined ? {} : { to: range.to },
+  }
+  validateRange(kind, copy)
+  return copy
+}
+
+function unknownFilter(filter: never): never {
+  const kind = (filter as { kind?: unknown }).kind
+  throw invalidFilter(`unknown filter kind ${typeof kind === 'string' ? `"${kind}"` : '(missing)'}`)
+}
+
+function assertAllowedValues(
+  name: string,
+  values: readonly string[],
+  allowed: readonly string[],
+): void {
+  for (const value of values) {
+    if (!allowed.includes(value)) {
+      throw new SessionQueryError(
+        `session ${name} filter contains unknown value "${value}"`,
+        'SESSION_QUERY_INVALID_FILTER',
+      )
+    }
+  }
+}
+
+function validateRange(name: string, range: SessionResultRange): SessionResultRange {
+  if (range.from !== undefined && !Number.isFinite(range.from)) {
+    throw invalidRange(name, 'from must be finite')
+  }
+  if (range.to !== undefined && !Number.isFinite(range.to)) {
+    throw invalidRange(name, 'to must be finite')
+  }
+  if (range.from !== undefined && range.to !== undefined && range.from > range.to) {
+    throw invalidRange(name, 'from must be less than or equal to to')
+  }
+  return range
+}
+
+function matchesRange(value: number, range: SessionResultRange): boolean {
+  return (range.from === undefined || value >= range.from)
+    && (range.to === undefined || value <= range.to)
+}
+
+function invalidRange(name: string, detail: string): SessionQueryError {
+  return invalidFilter(`${name} filter ${detail}`)
+}
+
+function invalidFilter(detail: string): SessionQueryError {
+  return new SessionQueryError(`session ${detail}`, 'SESSION_QUERY_INVALID_FILTER')
+}
+
+function isRuntimeArray(value: unknown): boolean {
+  return Array.isArray(value)
+}

packages/session-query/session-query/src/index.ts

@@ -1,22 +1,30 @@
 /**
- * Exact session-history reads and traces over live and optionally persisted logs.
+ * Combined session-history reads, traces, filters, and full-text search seam.
  *
  * @module @deepseek-ai/dsh-session-query
  */
 
 import { Context, Service } from 'cordis'
-import z from 'schemastery'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
 import type { SessionTitleSnapshot } from '@deepseek-ai/dsh-session-title'
 import type {
+  SessionEventResultFilter,
   SessionEventReadRequest,
   SessionEventRecord,
+  SessionEventSearchHit,
+  SessionEventSearchDocument,
+  SessionEventSearchRequest,
   SessionEventTrace,
   SessionEventTraceRequest,
   SessionEventWindow,
   SessionLineageTrace,
   SessionRecord,
+  SessionResultFilter,
+  SessionSearchExecContext,
+  SessionSearchHit,
+  SessionSearchPage,
+  SessionSearchRequest,
   SessionSurfaceSnapshot,
 } from './types.ts'
 import {
@@ -25,11 +33,29 @@ import {
   type Config,
 } from './config.ts'
 import { SessionCorpus } from './corpus.ts'
+import { buildSessionEventSearchDocuments } from './documents.ts'
+import {
+  filterSessionEventDocuments,
+  filterSessionResults,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+} from './filters.ts'
 import * as tracing from './tracing.ts'
 
 export type * from './types.ts'
+export { SessionSearchCursor } from './cursor.ts'
 export type { Config, SessionQueryErrorCode } from './config.ts'
 export { SESSION_QUERY_READ_WINDOW_MAX, SessionQueryError } from './config.ts'
+export { extractSessionEventText } from './extraction.ts'
+export { buildSessionEventRecords, buildSessionEventSearchDocuments } from './documents.ts'
+export {
+  compileSessionTextFilter,
+  filterSessionEventDocuments,
+  filterSessionResults,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+} from './filters.ts'
+export { assertSessionHeadersCompatible } from './sources.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -37,12 +63,15 @@ declare module 'cordis' {
   }
 }
 
-/** Live-preferred logical-corpus exact-read and relationship-tracing service. */
-export class SessionQueryService extends Service {
+/**
+ * Unified live-preferred session query service.
+ *
+ * Exact reads, filters, and traces are backend-independent concrete behavior.
+ * A backend implements full-text observation, reconciliation, ranking, cursor
+ * generations, and query execution on the same `ctx.sessionQuery` service.
+ */
+export abstract 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
@@ -59,6 +88,28 @@ export class SessionQueryService extends Service {
     this._corpus = new SessionCorpus(ctx)
   }
 
+  /**
+   * Search the live-preferred logical corpus and group by session.
+   * @param request - query text, metadata filters, page size, and cursor.
+   * @param exec - optional cancellation control.
+   * @returns session hits ranked by their strongest matching event.
+   */
+  abstract searchSessions(
+    request: SessionSearchRequest,
+    exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionSearchHit>>
+
+  /**
+   * Search events within one live-preferred logical session.
+   * @param request - target session, query text, filters, page size, and cursor.
+   * @param exec - optional cancellation control.
+   * @returns matching event hits in deterministic relevance order.
+   */
+  abstract searchEvents(
+    request: SessionEventSearchRequest,
+    exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionEventSearchHit>>
+
   /**
    * List the complete logical corpus using live-preferred records.
    * @returns deterministic newest-first cloned session records.
@@ -67,6 +118,16 @@ export class SessionQueryService extends Service {
     return this._corpus.listSessions()
   }
 
+  /**
+   * Filter the complete logical corpus with provider-independent predicates.
+   * @param filters - ANDed session metadata and availability clauses.
+   * @returns matching cloned records in deterministic newest-first order.
+   */
+  async filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]> {
+    const ownedFilters = materializeSessionResultFilters(filters)
+    return this._filterSessions(ownedFilters)
+  }
+
   /**
    * Fold the latest log-backed title from one live-preferred logical session.
    * @param sessionId - live or persisted session id to read.
@@ -87,6 +148,33 @@ export class SessionQueryService extends Service {
     return tracing.eventRecords(sessionId, loaded.events)
   }
 
+  /**
+   * Scan first-party semantic event documents with provider-independent filters.
+   * @param sessionId - live-preferred session id to scan.
+   * @param filters - ANDed metadata and literal-text predicates.
+   * @returns matching semantic documents in ascending seq order.
+   */
+  async filterEvents(
+    sessionId: SessionId,
+    filters: readonly SessionEventResultFilter[],
+  ): Promise<SessionEventSearchDocument[]> {
+    const ownedFilters = materializeSessionEventResultFilters(filters)
+    return this._filterEvents(sessionId, ownedFilters)
+  }
+
+  private async _filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]> {
+    return filterSessionResults(await this._corpus.listSessions(), filters)
+  }
+
+  private async _filterEvents(
+    sessionId: SessionId,
+    filters: readonly SessionEventResultFilter[],
+  ): Promise<SessionEventSearchDocument[]> {
+    const loaded = await this._corpus.load(sessionId)
+    const documents = buildSessionEventSearchDocuments(sessionId, loaded.events)
+    return filterSessionEventDocuments(documents, filters)
+  }
+
   /**
    * Read one session's complete current model surface from one corpus observation.
    * @param sessionId - live-preferred session id to read.
@@ -132,16 +220,27 @@ export class SessionQueryService extends Service {
   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) {
+    const sessionId = request.sessionId
+    const seq = request.seq
+    return this._readEvent(sessionId, seq, before, after)
+  }
+
+  private async _readEvent(
+    sessionId: SessionId,
+    seq: number,
+    before: number,
+    after: number,
+  ): Promise<SessionEventWindow> {
+    const loaded = await this._corpus.load(sessionId)
+    const target = loaded.events[seq]
+    if (target === undefined || target.seq !== seq) {
       throw new SessionQueryError(
-        `session "${request.sessionId}" has no event at seq ${request.seq}`,
+        `session "${sessionId}" has no event at seq ${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)
+    const startSeq = Math.max(0, seq - before)
+    const endSeq = Math.min(loaded.events.length - 1, seq + after)
     return {
       session: loaded.header,
       target,

packages/session-query/session-query/src/sources.ts

@@ -0,0 +1,26 @@
+/** Shared immutable-header checks for logical session source observers. */
+
+import type { SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionQueryError } from './config.ts'
+
+/**
+ * Reject incompatible observations of one logical session source.
+ * @param a - first live, listed, or loaded header observation.
+ * @param b - second header observation expected to identify the same source.
+ */
+export function assertSessionHeadersCompatible(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
+    || (a.delegationDepth ?? 0) !== (b.delegationDepth ?? 0)
+  ) {
+    throw new SessionQueryError(
+      `session source headers conflict for session "${a.id}"`,
+      'SESSION_QUERY_SOURCE_CONFLICT',
+    )
+  }
+}

packages/session-query/session-query/src/types.ts

@@ -5,7 +5,16 @@
  * @module @deepseek-ai/dsh-session-query/types
  */
 
-import type { SessionEvent, SessionEventType, SessionHeader, SessionId, SurfaceEvent } from '@deepseek-ai/dsh-session'
+import type {
+  SessionEvent,
+  SessionEventType,
+  SessionHeader,
+  SessionId,
+  SurfaceEvent,
+} from '@deepseek-ai/dsh-session'
+import type { SessionSearchCursor } from './cursor.ts'
+
+export type { SessionSearchCursor } from './cursor.ts'
 
 /** Whether an event is current model context, replaced context, or raw-log-only. */
 export type SessionEventSurface = 'current' | 'shadowed' | 'log-only'
@@ -124,3 +133,99 @@ export interface SessionEventWindow {
   /** Last seq included in `events`. */
   endSeq: number
 }
+
+/** Inclusive numeric interval used by time and sequence filters. */
+export interface SessionResultRange {
+  /** Inclusive lower bound. */
+  from?: number
+  /** Inclusive upper bound. */
+  to?: number
+}
+
+/** Source availability predicates understood by logical-session filters. */
+export type SessionAvailability = 'live' | 'persisted'
+
+/**
+ * One logical-session predicate. A filter array is ANDed; `values` within a
+ * clause are ORed.
+ */
+export type SessionResultFilter =
+  | { kind: 'id'; values: readonly SessionId[] }
+  | { kind: 'cwd'; values: readonly (string | null)[] }
+  | ({ kind: 'created-at' } & SessionResultRange)
+  | { kind: 'parent'; values: readonly (SessionId | null)[] }
+  | { kind: 'availability'; values: readonly SessionAvailability[] }
+
+/**
+ * One event predicate. A filter array is ANDed; list-valued clauses are ORed.
+ * Text is a literal, case-insensitive, whitespace-flexible semantic-text scan.
+ */
+export type SessionEventResultFilter =
+  | ({ kind: 'seq' } & SessionResultRange)
+  | ({ kind: 'time' } & SessionResultRange)
+  | { kind: 'type'; values: readonly SessionEventType[] }
+  | { kind: 'surface'; values: readonly SessionEventSurface[] }
+  | { kind: 'text'; text: string }
+
+/** Event predicates a full-text provider can apply before relevance ranking. */
+export type SessionEventMetadataFilter = Exclude<SessionEventResultFilter, { kind: 'text' }>
+
+/** Searchable semantic document derived from one session event. */
+export interface SessionEventSearchDocument extends SessionEventRecord {
+  /** First-party semantic text used by scan filters and full-text indexes. */
+  text: string
+}
+
+/** One cursor-paginated result page. */
+export interface SessionSearchPage<T> {
+  /** Results for this page in contract-defined order. */
+  items: readonly T[]
+  /** Opaque continuation cursor, absent on the final page. */
+  nextCursor?: SessionSearchCursor
+}
+
+/** Controls shared by cross-session and within-session search calls. */
+export interface SessionSearchExecContext {
+  /** Abort caller waiting and interrupt provider work where supported. */
+  signal?: AbortSignal
+}
+
+/** Cross-session full-text search request. */
+export interface SessionSearchRequest {
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Logical-session predicates applied before event ranking. */
+  sessionFilters?: readonly SessionResultFilter[]
+  /** Event predicates applied before event ranking. */
+  eventFilters?: readonly SessionEventMetadataFilter[]
+  /** Maximum sessions in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+
+/** Within-session full-text search request. */
+export interface SessionEventSearchRequest {
+  /** Session whose live-preferred logical log is searched. */
+  sessionId: SessionId
+  /** Full-text query interpreted as data, never executable FTS syntax. */
+  query: string
+  /** Event predicates applied before ranking. */
+  filters?: readonly SessionEventMetadataFilter[]
+  /** Maximum events in this page. */
+  limit?: number
+  /** Opaque cursor returned for the identical normalized request. */
+  cursor?: SessionSearchCursor
+}
+
+/** One event full-text search hit with a bounded plain-text excerpt. */
+export interface SessionEventSearchHit extends SessionEventRecord {
+  /** Plain text excerpt selected around the match. */
+  snippet: string
+}
+
+/** One grouped cross-session hit, ranked by its strongest matching event. */
+export interface SessionSearchHit extends SessionRecord {
+  /** Strongest matching event for this session. */
+  bestMatch: SessionEventSearchHit
+}

packages/session-query/session-query/tests/search-helpers.spec.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+import {
+  buildSessionEventRecords,
+  buildSessionEventSearchDocuments,
+  compileSessionTextFilter,
+  extractSessionEventText,
+  filterSessionEventDocuments,
+  filterSessionResults,
+  materializeSessionEventResultFilters,
+  materializeSessionResultFilters,
+  type SessionQueryErrorCode,
+} from '@deepseek-ai/dsh-session-query'
+import { TestSessionQueryService } from './test-service.ts'
+
+const id = SessionId('session')
+
+function header(value: string, extra: Partial<SessionHeader> = {}): SessionHeader {
+  return { version: SESSION_FORMAT_VERSION, id: SessionId(value), createdAt: 10, ...extra }
+}
+
+function expectCode(code: SessionQueryErrorCode): Error {
+  return expect.objectContaining({ code }) as Error
+}
+
+describe('session-query semantic extraction', () => {
+  it('extracts first-party message, tool, todo, and failure detail', () => {
+    const callId = CallId('call')
+    const messageContent: SessionEvent<'user/message'>['data']['content'] = [
+      { type: 'text', text: ' visible ' },
+      { type: 'reasoning', text: 'thought' },
+      { type: 'tool-call', id: callId, name: 'read', arguments: '{"path":"a"}' },
+      {
+        type: 'tool-result',
+        toolCallId: callId,
+        content: [{ type: 'text', text: 'nested' }],
+        isError: false,
+      },
+      { type: 'future-content', payload: 'hidden' } as never,
+    ]
+    const events: SessionEvent[] = [
+      { type: 'user/message', seq: 0, time: 1, data: { content: messageContent, source: { kind: 'user' } }, surfaceOp: 'append' },
+      { type: 'assistant/message', seq: 1, time: 2, data: { turn: 1, step: 1, content: messageContent, provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: 'append' },
+      { type: 'user/message', seq: 2, time: 3, data: { content: messageContent, source: { kind: 'plugin', plugin: 'test' } }, surfaceOp: 'append' },
+      { type: 'steering/message', seq: 3, time: 4, data: { turn: 1, content: messageContent, source: { kind: 'user' } }, surfaceOp: 'append' },
+      { type: 'prompt/blocked', seq: 4, time: 5, data: { content: [{ type: 'text', text: 'unsafe' }], source: { kind: 'user' }, reason: 'policy' } },
+      { type: 'tool/call', seq: 5, time: 6, data: { turn: 1, step: 1, callId, name: 'bash', arguments: '{"cmd":"pwd"}' } },
+      { type: 'tool/result', seq: 6, time: 7, data: { turn: 1, step: 1, callId, content: [{ type: 'text', text: 'failed' }], isError: true, error: { name: 'Oops', code: 'E_OOPS' } }, surfaceOp: 'append' },
+      { type: 'tool/result', seq: 7, time: 8, data: { turn: 1, step: 1, callId, content: [], isError: false }, surfaceOp: 'append' },
+      { type: 'todo/write', seq: 8, time: 9, data: { todos: [{ status: 'in_progress', content: 'ship search' }] } },
+    ]
+
+    for (const event of events.slice(0, 4)) {
+      expect(extractSessionEventText(event)).toBe('visible\nthought\nread\n{"path":"a"}\nnested')
+    }
+    expect(extractSessionEventText(events[4]!)).toBe('unsafe\npolicy')
+    expect(extractSessionEventText(events[5]!)).toBe('bash\n{"cmd":"pwd"}')
+    expect(extractSessionEventText(events[6]!)).toBe('failed\nOops\nE_OOPS')
+    expect(extractSessionEventText(events[7]!)).toBe('')
+    expect(extractSessionEventText(events[8]!)).toBe('in_progress\nship search')
+  })
+
+  it('extracts meaningful turn outcomes and skips structural or unknown events', () => {
+    const reasons: Array<[SessionEvent<'turn/end'>['data']['reason'], string]> = [
+      [{ kind: 'error', step: 2, message: 'boom', code: 'E' }, 'error\nboom\nE'],
+      [{ kind: 'error', step: 2, message: 'boom' }, 'error\nboom'],
+      [{ kind: 'error', step: 2, failure: { message: 'provider boom', code: 'SERVER' } }, 'error\nprovider boom\nSERVER'],
+      [{ kind: 'aborted' }, 'aborted'],
+      [{ kind: 'rejected', reason: 'denied' }, 'rejected\ndenied'],
+      [{ kind: 'disposed' }, 'disposed'],
+      [{ kind: 'max-tokens' }, 'max-tokens'],
+      [{ kind: 'interrupted' }, 'interrupted'],
+      [{ kind: 'completed' }, ''],
+      [{ kind: 'future-status' } as never, ''],
+    ]
+    for (const [reason, text] of reasons) {
+      expect(extractSessionEventText({ type: 'turn/end', seq: 0, time: 1, data: { turn: 1, reason } })).toBe(text)
+    }
+    const structural: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'step/end', seq: 2, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'assistant/chunk', seq: 3, time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
+      { type: 'request/header', seq: 4, time: 1, data: { header: { config: { provider: 'test', model: 'test' } }, reason: 'initial' } },
+      { type: 'future/event', seq: 5, time: 1, data: { text: 'hidden' } } as never,
+    ]
+    expect(structural.map(extractSessionEventText)).toEqual(['', '', '', '', '', ''])
+  })
+})
+
+describe('session-query document and filter helpers', () => {
+  const events: SessionEvent[] = [
+    { type: 'user/message', seq: 0, time: 10, data: { content: [{ type: 'text', text: 'Hello\n(AI)+' }], source: { kind: 'user' } }, surfaceOp: 'append' },
+    { type: 'assistant/chunk', seq: 1, time: 11, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } },
+    { type: 'assistant/message', seq: 2, time: 12, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'replacement' }], provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] },
+    { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'interrupted' } } },
+  ]
+
+  it('classifies every event and omits non-semantic documents', () => {
+    expect(buildSessionEventRecords(id, events).map(record => record.surface))
+      .toEqual(['shadowed', 'log-only', 'current', 'log-only'])
+    const documents = buildSessionEventSearchDocuments(id, events)
+    expect(documents.map(document => [document.seq, document.text, document.surface])).toEqual([
+      [0, 'Hello\n(AI)+', 'shadowed'],
+      [2, 'replacement', 'current'],
+      [3, 'interrupted', 'log-only'],
+    ])
+  })
+
+  it('applies every session clause with OR values and validates closed values', () => {
+    const parent = SessionId('parent')
+    const records = [
+      { header: header('a', { cwd: '/a', parentSession: parent }), live: true, persisted: false, marker: 1 },
+      { header: header('b', { createdAt: 20 }), live: false, persisted: true, marker: 2 },
+    ]
+    expect(filterSessionResults(records, [
+      { kind: 'id', values: [SessionId('a'), SessionId('x')] },
+      { kind: 'cwd', values: ['/a', null] },
+      { kind: 'created-at', from: 5, to: 15 },
+      { kind: 'parent', values: [parent, null] },
+      { kind: 'availability', values: ['live'] },
+    ])).toEqual([records[0]])
+    expect(filterSessionResults(records, [{ kind: 'cwd', values: [null] }])).toEqual([records[1]])
+    expect(filterSessionResults(records, [{ kind: 'parent', values: [null] }])).toEqual([records[1]])
+    expect(filterSessionResults(records, [{ kind: 'availability', values: ['persisted'] }])).toEqual([records[1]])
+    expect(() => filterSessionResults(records, [{ kind: 'availability', values: ['remote' as never] }]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('applies event metadata and safe literal text clauses', () => {
+    const documents = buildSessionEventSearchDocuments(id, events).map((document, marker) => ({ ...document, marker }))
+    expect(filterSessionEventDocuments(documents, [
+      { kind: 'seq', from: 0, to: 1 },
+      { kind: 'time', from: 9, to: 11 },
+      { kind: 'type', values: ['user/message', 'tool/result'] },
+      { kind: 'surface', values: ['shadowed'] },
+      { kind: 'text', text: 'hello   (ai)+' },
+    ])).toEqual([documents[0]])
+    expect(compileSessionTextFilter('CAFÉ').test('café')).toBe(true)
+    expect(filterSessionEventDocuments(documents)).toEqual(documents)
+    expect(filterSessionEventDocuments(documents, [{ kind: 'surface', values: [] }])).toEqual([])
+    expect(() => filterSessionEventDocuments(documents, [{ kind: 'surface', values: ['future' as never] }]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => compileSessionTextFilter(' \n ')).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('rejects malformed range filters and malformed surfaces', () => {
+    const documents = buildSessionEventSearchDocuments(id, events)
+    for (const filter of [
+      { kind: 'seq', from: Number.NaN },
+      { kind: 'seq', to: Number.POSITIVE_INFINITY },
+      { kind: 'time', from: 2, to: 1 },
+    ] as const) {
+      expect(() => filterSessionEventDocuments(documents, [filter]))
+        .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    }
+    expect(() => filterSessionResults([], [{ kind: 'created-at', from: Number.NaN }]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => filterSessionResults([{ header: header('x'), live: true, persisted: false }], [
+      { kind: 'created-at', from: Number.NaN },
+    ])).toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    const malformed: SessionEvent[] = [{
+      type: 'assistant/message',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, step: 1, content: [{ type: 'text', text: 'bad' }], provenance: { provider: 'mock', model: 'mock' } },
+      surfaceOp: { op: 'replace', start: 9, end: 9 },
+    }]
+    expect(() => buildSessionEventRecords(id, malformed)).toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
+  })
+
+  it('owns filters and rejects malformed runtime filter shapes deterministically', () => {
+    expect(materializeSessionResultFilters([{ kind: 'created-at', to: 2 }]))
+      .toEqual([{ kind: 'created-at', to: 2 }])
+    expect(() => materializeSessionResultFilters('not-an-array' as never))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'id', values: 'bad' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'id', values: [1] } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'cwd', values: 'bad' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{ kind: 'parent', values: [1] } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionResultFilters([{} as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionEventResultFilters([{ kind: 'text', text: 1 } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => materializeSessionEventResultFilters([{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => filterSessionResults([], [{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    expect(() => filterSessionEventDocuments([], [{ kind: 'future' } as never]))
+      .toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
+  it('exposes the scan path on the combined query service', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(TestSessionQueryService)
+    const session = ctx.sessions.create(id)
+    session.append('user/message', { content: [{ type: 'text', text: 'Alpha\n beta' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    session.append('user/message', { content: [{ type: 'text', text: 'other' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    await expect(ctx.sessionQuery.filterEvents(id, [{ kind: 'text', text: 'alpha beta' }]))
+      .resolves.toMatchObject([{ seq: 0, text: 'Alpha\n beta' }])
+  })
+})
+
+it('registers exact and abstract search behavior under one ctx key', async () => {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  const fiber = await ctx.plugin(TestSessionQueryService)
+  await expect(ctx.sessionQuery.searchSessions({ query: 'AI' })).resolves.toEqual({ items: [] })
+  await expect(ctx.sessionQuery.searchEvents({ sessionId: id, query: 'AI' })).resolves.toEqual({ items: [] })
+  await fiber.dispose()
+  expect(ctx.sessionQuery).toBeUndefined()
+})

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

@@ -1,12 +1,14 @@
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context, type Fiber } 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 SessionPersistence, { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
 import SessionQueryService, {
+  type SessionEventSurface,
   type SessionQueryErrorCode,
 } from '@deepseek-ai/dsh-session-query'
 import { SessionTitleProviderId } from '@deepseek-ai/dsh-session-title'
+import { TestSessionQueryService } from './test-service.ts'
 
 function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
   return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
@@ -25,13 +27,15 @@ function eventLog(text = 'hello'): SessionEvent[] {
 class TestPersistence extends SessionPersistence {
   static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
   static listFailure: unknown
-  static loadFailure: unknown
+  static inspectFailure: unknown
+  static inspectEffect: (() => void) | undefined
   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.inspectFailure = undefined
+    this.inspectEffect = undefined
     this.afterList = undefined
   }
 
@@ -52,10 +56,17 @@ class TestPersistence extends SessionPersistence {
   }
 
   load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    if (TestPersistence.loadFailure !== undefined) return rejectUnknown(TestPersistence.loadFailure)
+    return this.inspect(id)
+  }
+
+  inspect(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    if (TestPersistence.inspectFailure !== undefined) return rejectUnknown(TestPersistence.inspectFailure)
     const entry = TestPersistence.entries.get(id)
     if (entry === undefined) return Promise.reject(new Error('missing test session'))
-    return Promise.resolve(structuredClone(entry))
+    const result = structuredClone(entry)
+    TestPersistence.inspectEffect?.()
+    TestPersistence.inspectEffect = undefined
+    return Promise.resolve(result)
   }
 
   list(): Promise<SessionHeader[]> {
@@ -64,12 +75,20 @@ class TestPersistence extends SessionPersistence {
     TestPersistence.afterList?.()
     return Promise.resolve(headers)
   }
+
+
+  async listSnapshots() {
+    return [...TestPersistence.entries.values()].map(entry => ({
+      header: structuredClone(entry.meta),
+      revision: SessionPersistenceRevision(`events:${entry.events.length}`),
+    }))
+  }
 }
 
-async function liveContext(config: ConstructorParameters<typeof SessionQueryService>[1] = {}): Promise<Context> {
+async function liveContext(config: ConstructorParameters<typeof TestSessionQueryService>[1] = {}): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SessionQueryService, config)
+  await ctx.plugin(TestSessionQueryService, config)
   return ctx
 }
 
@@ -86,6 +105,22 @@ function rejectUnknown<T>(reason: unknown): Promise<T> {
 }
 
 describe('session-query exact reads', () => {
+  it('prefers a live owner that attaches while its persisted prefix is inspected', async () => {
+    const shared = header('attach-during-inspect', 2)
+    TestPersistence.reset([{ meta: shared, events: eventLog('persisted') }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    TestPersistence.inspectEffect = () => {
+      ctx.sessions.create(shared.id, {
+        seed: eventLog('live'),
+        meta: { createdAt: shared.createdAt },
+      })
+    }
+
+    await expect(ctx.sessionQuery.filterEvents(shared.id, []))
+      .resolves.toMatchObject([{ sessionId: shared.id, text: 'live' }])
+  })
+
   it('reads the latest title from one live-preferred or persisted log without widening listSessions', async () => {
     const persistedHeader = header('persisted-title', 2)
     const sharedHeader = header('shared-title', 3)
@@ -151,6 +186,38 @@ describe('session-query exact reads', () => {
     expect(older.header.createdAt).toBe(1)
   })
 
+  it('filters sessions symmetrically and owns mutable filter values immediately', async () => {
+    const durable = header('durable-filter', 1)
+    TestPersistence.reset([{ meta: durable, events: eventLog('durable') }])
+    const ctx = await liveContext()
+    const live = ctx.sessions.create(SessionId('live-filter'), { meta: { createdAt: 2 } })
+    live.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'live' }], source: { kind: 'user' } },
+      { surfaceOp: 'append' },
+    )
+    const persistence = await ctx.plugin(TestPersistence)
+
+    const ids = [durable.id]
+    const filtered = ctx.sessionQuery.filterSessions([{ kind: 'id', values: ids }])
+    ids[0] = live.id
+    await expect(filtered).resolves.toEqual([{
+      header: durable,
+      live: false,
+      persisted: true,
+    }])
+
+    const surfaces: SessionEventSurface[] = ['current']
+    const events = ctx.sessionQuery.filterEvents(live.id, [{ kind: 'surface', values: surfaces }])
+    surfaces[0] = 'shadowed'
+    await expect(events).resolves.toMatchObject([{ sessionId: live.id, surface: 'current', text: 'live' }])
+    await expect(ctx.sessionQuery.filterSessions([{ kind: 'future' } as never]))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionQuery.filterEvents(live.id, [{ kind: 'future' } as never]))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await persistence.dispose()
+  })
+
   it('classifies current, shadowed, and raw-log-only events through foldSurface', async () => {
     const ctx = await liveContext()
     const session = ctx.sessions.create(SessionId('surface'))
@@ -301,6 +368,8 @@ describe('session-query exact reads', () => {
     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'))
+    sharedEntry.meta = { ...sharedEntry.meta, cwd: '/same', delegationDepth: 1 }
+    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 },
@@ -319,7 +388,7 @@ describe('session-query exact reads', () => {
     )
     await ctx.plugin(TestPersistence)
     TestPersistence.listFailure = new Error('list unavailable')
-    TestPersistence.loadFailure = new Error('load unavailable')
+    TestPersistence.inspectFailure = new Error('inspect unavailable')
 
     await expect(ctx.sessionQuery.listEvents(live.id)).resolves.toHaveLength(2)
     await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: 1 })).resolves.toMatchObject({ target: { seq: 1 } })
@@ -337,10 +406,10 @@ describe('session-query exact reads', () => {
     await expect(ctx.sessionQuery.listEvents(SessionId('absent')))
       .rejects.toThrow(expectCode('SESSION_QUERY_SESSION_NOT_FOUND'))
 
-    TestPersistence.loadFailure = 'raw failure'
+    TestPersistence.inspectFailure = 'raw failure'
     await expect(ctx.sessionQuery.listEvents(durable.id))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TestPersistence.loadFailure = undefined
+    TestPersistence.inspectFailure = undefined
     const durableEntry = TestPersistence.entries.get(durable.id)!
     durableEntry.meta = { ...durableEntry.meta, cwd: '/changed-after-list' }
     TestPersistence.afterList = () => {
@@ -370,19 +439,41 @@ describe('session-query exact reads', () => {
 
     const direct = new Context()
     await direct.plugin(SessionStore)
-    expect(new SessionQueryService(direct)).toBeInstanceOf(SessionQueryService)
+    expect(new TestSessionQueryService(direct)).toBeInstanceOf(SessionQueryService)
     const invalid = new Context()
     await invalid.plugin(SessionStore)
-    expect(() => new SessionQueryService(invalid, { readWindowMax: -1 }))
+    expect(() => new TestSessionQueryService(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)
+    const fiber = await ctx.plugin(TestSessionQueryService)
+    expect(ctx.sessionQuery).toBeInstanceOf(TestSessionQueryService)
     await fiber.dispose()
     expect(ctx.sessionQuery).toBeUndefined()
   })
+
+  it('awaits optional-persistence child-fiber quiescence on disposal', async () => {
+    TestPersistence.reset()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const query = await ctx.plugin(TestSessionQueryService)
+    const persistence = await ctx.plugin(TestPersistence)
+    const optional = (ctx.sessionQuery as unknown as {
+      _corpus: { _optionalPersistenceFiber: Fiber }
+    })._corpus._optionalPersistenceFiber
+    let release!: () => void
+    const cleanup = new Promise<void>((resolve) => { release = resolve })
+    optional.ctx.effect(() => () => cleanup)
+
+    let settled = false
+    const disposing = query.dispose().then(() => { settled = true })
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    release()
+    await disposing
+    await persistence.dispose()
+  })
 })

packages/session-query/session-query/tests/test-service.ts

@@ -0,0 +1,26 @@
+import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import type {
+  SessionEventSearchHit,
+  SessionEventSearchRequest,
+  SessionSearchExecContext,
+  SessionSearchHit,
+  SessionSearchPage,
+  SessionSearchRequest,
+} from '@deepseek-ai/dsh-session-query'
+
+/** Test-only concrete query service for backend-independent behavior. */
+export class TestSessionQueryService extends SessionQueryService {
+  override searchSessions(
+    _request: SessionSearchRequest,
+    _exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionSearchHit>> {
+    return Promise.resolve({ items: [] })
+  }
+
+  override searchEvents(
+    _request: SessionEventSearchRequest,
+    _exec?: SessionSearchExecContext,
+  ): Promise<SessionSearchPage<SessionEventSearchHit>> {
+    return Promise.resolve({ items: [] })
+  }
+}

packages/session-query/session-query/tests/tracing.spec.ts

@@ -3,7 +3,8 @@ import { Context } from 'cordis'
 import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import type { Session, 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'
+import { type SessionQueryErrorCode } from '@deepseek-ai/dsh-session-query'
+import { TestSessionQueryService } from './test-service.ts'
 
 type MutableSessionHeader = { -readonly [K in keyof SessionHeader]: SessionHeader[K] }
 
@@ -30,17 +31,17 @@ function appendEvent(seq: number, sources?: number[]): SessionEvent {
 class TracePersistence extends SessionPersistence {
   static entries = new Map<SessionIdType, { meta: SessionHeader; events: SessionEvent[] }>()
   static listCalls = 0
-  static loadCalls = 0
+  static inspectCalls = 0
   static listFailure: Error | undefined
-  static loadFailure: Error | undefined
+  static inspectFailure: Error | undefined
   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.listCalls = 0
-    this.loadCalls = 0
+    this.inspectCalls = 0
     this.listFailure = undefined
-    this.loadFailure = undefined
+    this.inspectFailure = undefined
     this.afterList = undefined
   }
 
@@ -61,8 +62,12 @@ class TracePersistence extends SessionPersistence {
   }
 
   load(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    TracePersistence.loadCalls += 1
-    if (TracePersistence.loadFailure !== undefined) return Promise.reject(TracePersistence.loadFailure)
+    return this.inspect(id)
+  }
+
+  inspect(id: SessionIdType): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    TracePersistence.inspectCalls += 1
+    if (TracePersistence.inspectFailure !== undefined) return Promise.reject(TracePersistence.inspectFailure)
     const entry = TracePersistence.entries.get(id)
     if (entry === undefined) return Promise.reject(new Error('missing test session'))
     return Promise.resolve(structuredClone(entry))
@@ -75,12 +80,16 @@ class TracePersistence extends SessionPersistence {
     TracePersistence.afterList?.()
     return Promise.resolve(result)
   }
+
+  listSnapshots(): Promise<never[]> {
+    return Promise.resolve([])
+  }
 }
 
 async function queryContext(): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SessionQueryService)
+  await ctx.plugin(TestSessionQueryService)
   return ctx
 }
 
@@ -204,7 +213,7 @@ describe('session lineage tracing', () => {
       complete: true,
     })
     expect(TracePersistence.listCalls).toBe(1)
-    expect(TracePersistence.loadCalls).toBe(0)
+    expect(TracePersistence.inspectCalls).toBe(0)
 
     TracePersistence.listFailure = new Error('unavailable')
     await expect(ctx.sessionQuery.traceSession(durable.id))
@@ -296,7 +305,7 @@ describe('session event tracing', () => {
     expect(repeated.derivedEventSeqs).toEqual([8])
   })
 
-  it('loads persisted logs once, prefers live logs, and preserves failures and conflicts', async () => {
+  it('inspects persisted logs once, prefers live logs, and preserves failures and conflicts', async () => {
     const durable = header('shared', 1, { cwd: '/same' })
     TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
     const ctx = await queryContext()
@@ -304,7 +313,7 @@ describe('session event tracing', () => {
 
     await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
       .resolves.toMatchObject({ target: { type: 'user/message', surface: 'current' } })
-    expect([TracePersistence.listCalls, TracePersistence.loadCalls]).toEqual([1, 1])
+    expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
 
     const live = ctx.sessions.create(durable.id, { meta: { createdAt: 1, cwd: '/same' } })
     live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
@@ -314,10 +323,10 @@ describe('session event tracing', () => {
       { surfaceOp: 'append' },
     )
     TracePersistence.listFailure = new Error('list unavailable')
-    TracePersistence.loadFailure = new Error('load unavailable')
+    TracePersistence.inspectFailure = new Error('inspect unavailable')
     await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 1 }))
       .resolves.toMatchObject({ target: { type: 'user/message' } })
-    expect([TracePersistence.listCalls, TracePersistence.loadCalls]).toEqual([1, 1])
+    expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1])
 
     TracePersistence.reset([{ meta: durable, events: [appendEvent(0)] }])
     const failedCtx = await queryContext()
@@ -326,10 +335,10 @@ describe('session event tracing', () => {
     await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
     TracePersistence.listFailure = undefined
-    TracePersistence.loadFailure = new Error('load unavailable')
+    TracePersistence.inspectFailure = new Error('inspect unavailable')
     await expect(failedCtx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
       .rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
-    TracePersistence.loadFailure = undefined
+    TracePersistence.inspectFailure = undefined
     TracePersistence.afterList = () => {
       mutableHeader(TracePersistence.entries.get(durable.id)!.meta).cwd = '/changed'
     }

packages/session-query/session-query/tsconfig.json

@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../../vendor/schemastery"
+      "path": "../../util/brand"
     },
     {
       "path": "../../llm/llm"