fix(session-query): guard FTS predicate planning (round 7)

docs/config-catalog.md

@@ -666,7 +666,7 @@ export interface Config {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 ```
 
-Source: [`packages/session-query/session-query-sqlite/src/index.ts:72`](../packages/session-query/session-query-sqlite/src/index.ts)
+Source: [`packages/session-query/session-query-sqlite/src/index.ts:73`](../packages/session-query/session-query-sqlite/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill`
 

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

@@ -4,7 +4,7 @@ SQLite FTS5 implementation of `ctx.sessionSearch`. The service searches the live
 
 ## 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. A request exceeding SQLite's portable limit of 32,766 total bindings, including fixed query and pagination values, fails with `SESSION_QUERY_INVALID_FILTER` before statement preparation.
+`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.
 

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

@@ -40,6 +40,7 @@ import {
   type NormalizedSessionRequest,
   FTS_HIGHLIGHT_END,
   FTS_HIGHLIGHT_START,
+  assertFts5OuterPredicateCount,
   assertPortableBindingCount,
   buildEventWhere,
   buildSessionWhere,
@@ -558,6 +559,7 @@ export class SessionSearchSqlite extends SessionSearchService {
     const selected = selectedDocumentsSql()
     const sessionWhere = buildSessionWhere(request.sessionFilters)
     const eventWhere = buildEventWhere(request.eventFilters)
+    assertFts5OuterPredicateCount(sessionWhere.predicateCount + eventWhere.predicateCount)
     const where = [sessionWhere.sql, eventWhere.sql].filter(Boolean).join(' AND ')
     const bindings = [
       ...selectedDocumentsParams(request.query, persistenceBinding.service !== undefined),
@@ -593,6 +595,7 @@ export class SessionSearchSqlite extends SessionSearchService {
   ): SearchRow[] {
     const selected = selectedDocumentsSql()
     const eventWhere = buildEventWhere(request.filters)
+    assertFts5OuterPredicateCount(1 + eventWhere.predicateCount)
     const where = ['session_id = ?', eventWhere.sql].filter(Boolean).join(' AND ')
     const bindings = [
       ...selectedDocumentsParams(request.query, persistenceBinding.service !== undefined),

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

@@ -26,6 +26,9 @@ 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.
@@ -39,6 +42,19 @@ export function assertPortableBindingCount(count: number): void {
   }
 }
 
+/**
+ * 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. */
@@ -71,6 +87,8 @@ export interface SqlWhere {
   sql: string
   /** Bindings in placeholder order. */
   params: Array<string | number>
+  /** Number of compiled predicates in `sql`. */
+  predicateCount: number
 }
 
 /**
@@ -163,7 +181,8 @@ export function buildSessionWhere(filters: readonly SessionResultFilter[]): SqlW
         unknownFilter(filter)
     }
   }
-  return { sql: clauses.join(' AND '), params }
+  assertFts5OuterPredicateCount(clauses.length)
+  return { sql: clauses.join(' AND '), params, predicateCount: clauses.length }
 }
 
 /**
@@ -192,7 +211,8 @@ export function buildEventWhere(filters: readonly SessionEventMetadataFilter[]):
         unknownFilter(filter)
     }
   }
-  return { sql: clauses.join(' AND '), params }
+  assertFts5OuterPredicateCount(clauses.length)
+  return { sql: clauses.join(' AND '), params, predicateCount: clauses.length }
 }
 
 /**

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

@@ -11,6 +11,7 @@ import {
   normalizeSessionRequest,
   quoteFtsData,
   requestFingerprint,
+  SQLITE_FTS5_OUTER_PREDICATE_LIMIT,
   SQLITE_MAX_PAGE_LIMIT,
   type NormalizedEventRequest,
   type NormalizedSessionRequest,
@@ -111,24 +112,36 @@ describe('SQLite search request normalization', () => {
 
 describe('SQLite search predicate compilation', () => {
   it('compiles all logical-session clauses including empty and nullable values', () => {
-    expect(buildSessionWhere([])).toEqual({ sql: '', params: [] })
-    expect(buildSessionWhere([{ kind: 'id', values: [] }])).toEqual({ sql: '0', params: [] })
+    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: [] }])).toEqual({ sql: '0', params: [] })
     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 },
@@ -138,8 +151,13 @@ describe('SQLite search predicate compilation', () => {
     ])).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,
     })
-    expect(buildSessionWhere([{ kind: 'created-at' }])).toEqual({ sql: '', params: [] })
   })
 
   it('compiles every event clause and empty lists', () => {
@@ -151,11 +169,25 @@ describe('SQLite search predicate compilation', () => {
     ])).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: [] })
+    ])).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', () => {

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

@@ -210,6 +210,61 @@ describe('SQLite session search', () => {
     })
   })
 
+  it('searches at the supported FTS5 outer-predicate boundary in both scopes', async () => {
+    const ctx = await liveContext()
+    const session = ctx.sessions.create(SessionId('predicate-boundary'), {
+      seed: messageEvents('needle'),
+      meta: { cwd: '/work' },
+    })
+    const sessionFilters = Array.from(
+      { length: 14 },
+      () => ({ kind: 'cwd' as const, values: ['/work', null] }),
+    )
+    const eventFilters = Array.from(
+      { length: 13 },
+      () => ({ kind: 'type' as const, values: ['user/message' as const] }),
+    )
+
+    await expect(ctx.sessionSearch.searchSessions({ query: 'needle', sessionFilters }))
+      .resolves.toMatchObject({ items: [{ header: { id: session.id } }] })
+    await expect(ctx.sessionSearch.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: eventFilters,
+    })).resolves.toMatchObject({ items: [{ sessionId: session.id, seq: 0 }] })
+  })
+
+  it('rejects unsupported FTS5 outer-predicate counts with typed errors', async () => {
+    const ctx = await liveContext()
+    const session = ctx.sessions.create(SessionId('predicate-limit'), { seed: messageEvents('needle') })
+    const sessionFilters = Array.from(
+      { length: 1_100 },
+      () => ({ kind: 'id' as const, values: [session.id] }),
+    )
+    const eventFilters = Array.from(
+      { length: 1_100 },
+      () => ({ kind: 'type' as const, values: ['user/message' as const] }),
+    )
+
+    await expect(ctx.sessionSearch.searchSessions({ query: 'needle', sessionFilters }))
+      .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionSearch.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: eventFilters,
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionSearch.searchSessions({
+      query: 'needle',
+      sessionFilters: sessionFilters.slice(0, 7),
+      eventFilters: eventFilters.slice(0, 8),
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+    await expect(ctx.sessionSearch.searchEvents({
+      sessionId: session.id,
+      query: 'needle',
+      filters: eventFilters.slice(0, 14),
+    })).rejects.toThrow(expectCode('SESSION_QUERY_INVALID_FILTER'))
+  })
+
   it('uses literal phrase tokens, stable ties, and bounded Unicode snippets', async () => {
     const ctx = await liveContext({ path: ':memory:', defaultLimit: 10, maxLimit: 10, snippetChars: 5 })
     ctx.sessions.create(SessionId('a'), { seed: messageEvents('😀😀 alpha beta BRAID 😀😀', 10), meta: { createdAt: 1 } })