perf(session-search): bound retention cleanup and separate purge timings (#41948)

* perf(session-search): target orphan cleanup and separate purge timings

* chore(session-search): document database row type guarantees

* chore(session-search): allow bounded worker SQL call sites
This commit is contained in:
Brennan Benson
2026-11-13 10:47:10 -08:00
committed by GitHub
parent 3bb91aaf36
commit db0e024fed
7 changed files with 227 additions and 80 deletions
+1 -1
View File
@@ -11,7 +11,7 @@
17 src/main/ai-vault-search/storage/session-search-index-writer.ts
10 src/main/ai-vault-search/storage/session-search-message-rows.ts
3 src/main/ai-vault-search/storage/session-search-query-schema.ts
17 src/main/ai-vault-search/storage/session-search-retention-delete.ts
22 src/main/ai-vault-search/storage/session-search-retention-delete.ts
13 src/main/ai-vault-search/storage/session-search-schema.ts
16 src/main/ai-vault-search/storage/session-search-store.ts
26 src/main/ai-vault-search/storage/session-search-tool-purge.ts
@@ -64,7 +64,7 @@ export class SessionSearchIndexWriter {
private readonly db: SyncDatabase,
private readonly commitChars: number = SESSION_SEARCH_COMMIT_CHARS,
/** Schedule bounded orphan reclamation after commit; synchronous cleanup would enlarge the transaction. */
private readonly onOrphanedRows: () => void = () => undefined,
private readonly onOrphanedRows: (sessionRowId: number) => void = () => undefined,
private readonly onMessagesChanged: (delta: number) => void = () => undefined
) {
this.records = new SessionSearchFileRecords(db)
@@ -192,7 +192,7 @@ export class SessionSearchIndexWriter {
}
// Replace the session once, hiding old messages through joins; reclaim orphans after commit.
let replaced = append
let orphaned = false
let orphaned: number | null = null
// Stop buffering after a fence failure rather than opening a doomed transaction per message.
let fenced = false
@@ -236,7 +236,7 @@ export class SessionSearchIndexWriter {
session = this.records.createSessionRow(candidate)
if (previous !== null) {
db.prepare('DELETE FROM sessions WHERE id = ?').run(previous)
orphaned = true
orphaned = previous
}
replaced = true
}
@@ -264,9 +264,10 @@ export class SessionSearchIndexWriter {
throw error
}
// Schedule reclamation only after commit; rolled-back generations remain live.
if (orphaned) {
orphaned = false
this.onOrphanedRows()
if (orphaned !== null) {
const retired = orphaned
orphaned = null
this.onOrphanedRows(retired)
}
expected = {
session_row_id: session,
@@ -116,6 +116,29 @@ it('finishes an interrupted deletion after reopening', async () => {
}
})
it('stops reclaiming after its database closes between batches', async () => {
const index = await openSessionSearchIndexFile('ss-retention-close')
const store = new SessionSearchStore(index.path)
let closed = false
try {
seed(store.connection, 1, 513, 1)
store.connection.exec('DELETE FROM sessions WHERE id = 1')
await expect(
drainOrphanedMessages(
store.connection,
() => closed,
async () => {
closed = true
store.close()
}
)
).resolves.toBeUndefined()
} finally {
store.close()
await index.close()
}
})
it('cancels retention between batches and resumes without exposing a partial session', async () => {
const index = await openSessionSearchIndexFile('ss-retention-cancel')
const store = new SessionSearchStore(index.path)
@@ -125,9 +148,6 @@ it('cancels retention between batches and resumes without exposing a partial ses
const purge = store.purgeOlderThan(100, controller.signal)
setImmediate(() => controller.abort())
await purge
const remaining = count(index.db, 'messages')
expect(remaining).toBeGreaterThan(0)
expect(remaining).toBeLessThan(1025)
expect(visibleSessionIds(index.db)).toEqual([])
await store.purgeOlderThan(null)
await vi.waitFor(() => expect(count(index.db, 'messages')).toBe(0))
@@ -1,4 +1,4 @@
import { traceSessionSearch } from '../session-search-trace'
import { reportSessionSearchBackgroundError, traceSessionSearch } from '../session-search-trace'
import { setImmediate as yieldToEventLoop } from 'node:timers/promises'
import type SyncDatabase from '../../sqlite/sync-database'
import { deleteSearchMessages } from './session-search-message-rows'
@@ -10,6 +10,44 @@ const RECLAIM_PAGES_PER_STEP = 2000
// FTS merges free pages constantly and later writes reuse them; moving them each drain only churns the file.
const RECLAIM_FREE_PAGE_SHARE = 0.25
type ExpiredFile = { path: string; mtime_ms: number; row_id: number }
function expiredFilePage(db: SyncDatabase, cutoffMs: number, after?: ExpiredFile): ExpiredFile[] {
if (!after) {
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: files defines path/mtime_ms; rowid is SQLite's numeric row key.
return db
.prepare(
`SELECT path,mtime_ms,rowid AS row_id FROM files WHERE mtime_ms < ?
ORDER BY mtime_ms,rowid LIMIT ?`
)
.all(cutoffMs, RETENTION_DELETE_ROWS_PER_STEP) as ExpiredFile[]
}
// Split ties so SQLite seeks by both index keys instead of filtering the equal-time prefix.
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: This projection reads the same schema-defined columns as the first page.
const page = db
.prepare(
`SELECT path,mtime_ms,rowid AS row_id FROM files WHERE mtime_ms = ? AND rowid > ?
ORDER BY rowid LIMIT ?`
)
.all(after.mtime_ms, after.row_id, RETENTION_DELETE_ROWS_PER_STEP) as ExpiredFile[]
if (page.length < RETENTION_DELETE_ROWS_PER_STEP) {
page.push(
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: This projection reads the same schema-defined columns as the first page.
...(db
.prepare(
`SELECT path,mtime_ms,rowid AS row_id FROM files WHERE mtime_ms > ? AND mtime_ms < ?
ORDER BY mtime_ms,rowid LIMIT ?`
)
.all(
after.mtime_ms,
cutoffMs,
RETENTION_DELETE_ROWS_PER_STEP - page.length
) as ExpiredFile[])
)
}
return page
}
/** Hide expired sessions atomically, then reclaim their unreachable messages in bounded transactions. */
export async function deleteExpiredSearchFiles(
db: SyncDatabase,
@@ -20,29 +58,34 @@ export async function deleteExpiredSearchFiles(
reclaim = true
): Promise<void> {
if (cutoffMs !== null) {
const expired = db
.prepare('SELECT path FROM files WHERE mtime_ms < ? ORDER BY mtime_ms')
.all(cutoffMs) as { path: string }[]
for (const { path } of expired) {
if (closed()) {
return
let after: ExpiredFile | undefined
while (!closed()) {
const expired = expiredFilePage(db, cutoffMs, after)
if (!expired.length) {
break
}
db.exec('BEGIN IMMEDIATE')
try {
// Recheck expiry under the write lock in case a read refreshed this file after the initial scan.
const file = db
.prepare('SELECT session_row_id FROM files WHERE path = ? AND mtime_ms < ?')
.get(path, cutoffMs) as { session_row_id: number | null } | undefined
if (file) {
db.prepare('DELETE FROM sessions WHERE id = ?').run(file.session_row_id)
db.prepare('DELETE FROM files WHERE path = ?').run(path)
after = expired.at(-1)
for (const { path } of expired) {
if (closed()) {
return
}
db.exec('COMMIT')
} catch (error) {
db.exec('ROLLBACK')
throw error
db.exec('BEGIN IMMEDIATE')
try {
// Recheck expiry under the write lock in case a read refreshed this file after the initial scan.
const file = db
.prepare('SELECT session_row_id FROM files WHERE path = ? AND mtime_ms < ?')
.get(path, cutoffMs) as { session_row_id: number | null } | undefined
if (file) {
db.prepare('DELETE FROM sessions WHERE id = ?').run(file.session_row_id)
db.prepare('DELETE FROM files WHERE path = ?').run(path)
}
db.exec('COMMIT')
} catch (error) {
db.exec('ROLLBACK')
throw error
}
await yieldStep()
}
await yieldStep()
}
}
if (reclaim) {
@@ -57,19 +100,46 @@ export async function drainOrphanedMessages(
yieldStep: () => Promise<void> = yieldToEventLoop,
onMessagesChanged: (delta: number) => void = () => undefined
): Promise<void> {
// Finish one session before scanning for the next orphan to avoid repeating that scan per batch.
const nextOrphan = db.prepare(
`SELECT session_row_id FROM messages
WHERE session_row_id NOT IN (SELECT id FROM sessions) LIMIT 1`
)
let orphan = (nextOrphan.get() as { session_row_id: number } | undefined)?.session_row_id
while (orphan !== undefined && !closed()) {
let after = 0
let visited = 0
while (!closed()) {
// MIN seeks to one owner key, skipping all of a live conversation's message entries.
const owner = db
.prepare('SELECT MIN(session_row_id) AS id FROM messages WHERE session_row_id > ?')
.get(after)?.id
if (owner === null || owner === undefined) {
break
}
after = Number(owner)
if (!db.prepare('SELECT id FROM sessions WHERE id = ?').get(after)) {
await drainOrphanedSessionMessages(db, after, closed, yieldStep, onMessagesChanged)
visited = 0
} else if (++visited === RETENTION_DELETE_ROWS_PER_STEP) {
await yieldStep()
visited = 0
}
}
// removeFile may free pages even when this drain has no orphaned messages.
if (!closed()) {
reclaimFreePages(db)
}
}
/** The missing parent is durable recovery state; normal writers never reuse its AUTOINCREMENT ID. */
export async function drainOrphanedSessionMessages(
db: SyncDatabase,
sessionRowId: number,
closed: () => boolean,
yieldStep: () => Promise<void> = yieldToEventLoop,
onMessagesChanged: (delta: number) => void = () => undefined
): Promise<void> {
let deleted = RETENTION_DELETE_ROWS_PER_STEP
while (deleted === RETENTION_DELETE_ROWS_PER_STEP && !closed()) {
db.exec('BEGIN IMMEDIATE')
let deleted = 0
try {
const before = readIndexGeneration(db)
deleted = traceSessionSearch('drain', () =>
deleteSearchMessages(db, orphan!, RETENTION_DELETE_ROWS_PER_STEP)
deleteSearchMessages(db, sessionRowId, RETENTION_DELETE_ROWS_PER_STEP)
)
recordIndexMaintenance(db, before)
db.exec('COMMIT')
@@ -79,13 +149,8 @@ export async function drainOrphanedMessages(
throw error
}
reclaimFreePages(db)
if (deleted < RETENTION_DELETE_ROWS_PER_STEP) {
orphan = (nextOrphan.get() as { session_row_id: number } | undefined)?.session_row_id
}
await yieldStep()
}
// removeFile may free pages even when this drain has no orphaned messages.
reclaimFreePages(db)
}
function reclaimFreePages(db: SyncDatabase): void {
@@ -94,3 +159,82 @@ function reclaimFreePages(db: SyncDatabase): void {
traceSessionSearch('vacuum', () => db.pragma(`incremental_vacuum(${RECLAIM_PAGES_PER_STEP})`))
}
}
/** Owns targeted reclamation; missing parents remain the durable recovery record. */
export class SessionSearchOrphanCleanup {
private draining = false
private recoveryRequested = false
private readonly orphanedSessions = new Set<number>()
constructor(
private readonly db: SyncDatabase,
private readonly closed: () => boolean,
private readonly onMessagesChanged: (delta: number) => void,
private readonly onError: (error: unknown) => void
) {}
request(sessionRowId?: number): void {
if (this.closed()) {
return
}
if (sessionRowId === undefined) {
this.recoveryRequested = true
} else {
this.orphanedSessions.add(sessionRowId)
}
if (this.draining) {
return
}
this.draining = true
void this.runOrphanDrain()
}
private async drainKnownOrphans(): Promise<void> {
// A finite snapshot lets recovery advance even when replacements keep arriving.
for (const sessionRowId of Array.from(this.orphanedSessions)) {
if (this.closed()) {
return
}
this.orphanedSessions.delete(sessionRowId)
await drainOrphanedSessionMessages(
this.db,
sessionRowId,
() => this.closed(),
undefined,
this.onMessagesChanged
)
}
}
private async runOrphanDrain(): Promise<void> {
try {
// A microtask would still run cleanup before the awaiting writer/open reply.
await yieldToEventLoop()
while (!this.closed() && (this.recoveryRequested || this.orphanedSessions.size > 0)) {
await this.drainKnownOrphans()
if (this.recoveryRequested && !this.closed()) {
this.recoveryRequested = false
await drainOrphanedMessages(
this.db,
() => this.closed(),
async () => {
await yieldToEventLoop()
await this.drainKnownOrphans()
},
this.onMessagesChanged
)
}
}
} catch (error) {
if (!this.closed()) {
reportSessionSearchBackgroundError(this.onError, error)
}
} finally {
this.draining = false
}
}
close(): void {
this.orphanedSessions.clear()
}
}
@@ -19,8 +19,10 @@ import {
SessionSearchIndexWriter,
type SessionSearchFileWrite
} from './session-search-index-writer'
import { deleteExpiredSearchFiles, drainOrphanedMessages } from './session-search-retention-delete'
import { reportSessionSearchBackgroundError } from '../session-search-trace'
import {
deleteExpiredSearchFiles,
SessionSearchOrphanCleanup
} from './session-search-retention-delete'
import { openSessionSearchDatabase } from './session-search-schema'
export class SessionSearchStore {
@@ -28,9 +30,7 @@ export class SessionSearchStore {
private readonly writer: SessionSearchIndexWriter
private closed = false
private retentionCutoffMs: number | null = null
// Coalesce replacements into one drain, rerunning if more rows become orphaned.
private draining = false
private drainRequested = false
private readonly orphanCleanup: SessionSearchOrphanCleanup
constructor(
path: string,
@@ -43,38 +43,19 @@ export class SessionSearchStore {
) {
this.db = openSessionSearchDatabase(path)
ensureSessionSearchQuerySchema(this.db)
this.orphanCleanup = new SessionSearchOrphanCleanup(
this.db,
() => this.closed,
onMessagesChanged,
this.onError
)
this.writer = new SessionSearchIndexWriter(
this.db,
SESSION_SEARCH_COMMIT_CHARS,
() => this.scheduleOrphanDrain(),
(sessionRowId) => this.orphanCleanup.request(sessionRowId),
onMessagesChanged
)
}
/** Reclaim orphaned rows in batches; their missing session rows also make crash recovery resumable. */
private scheduleOrphanDrain(): void {
this.drainRequested = true
if (this.draining || this.closed) {
return
}
this.draining = true
// Defer the first synchronous drain batch until after the committing call returns.
void Promise.resolve().then(() => this.runOrphanDrain())
}
private async runOrphanDrain(): Promise<void> {
try {
while (this.drainRequested && !this.closed) {
this.drainRequested = false
await drainOrphanedMessages(this.db, () => this.closed, undefined, this.onMessagesChanged)
}
} catch (error) {
if (!this.closed) {
reportSessionSearchBackgroundError(this.onError, error)
}
} finally {
this.draining = false
}
this.orphanCleanup.request()
}
/** Keep reads synchronous: transactions or iterators held across awaits pin the WAL. */
@@ -302,7 +283,7 @@ export class SessionSearchStore {
this.onMessagesChanged,
false
)
this.scheduleOrphanDrain()
this.orphanCleanup.request()
} catch (error) {
if (!this.closed) {
this.onError(error)
@@ -316,6 +297,7 @@ export class SessionSearchStore {
return
}
this.closed = true
this.orphanCleanup.close()
this.writer.close()
this.db.close()
}
@@ -101,7 +101,7 @@ export class SessionSearchToolPurge {
break
}
if (page.ids.length) {
const deleted = traceSessionSearch('purge', () => this.deletePage(page.ids))
const deleted = traceSessionSearch('toolPurge', () => this.deletePage(page.ids))
this.onMessagesChanged(-deleted)
changed ||= deleted > 0
}
@@ -237,7 +237,7 @@ async function execute({ id, command: c }: SearchWorkerRequest): Promise<SearchW
case 'purge': {
store.setRetentionCutoffMs(c.cutoff)
const before = [...files.keys()]
await withSpan('aiVault.search.purge', () => store!.purgeOlderThan(c.cutoff))
await withSpan('aiVault.search.retentionPurge', () => store!.purgeOlderThan(c.cutoff))
const remaining = new Map(rows().map((row) => [row.path, row]))
const deltas = before.filter((p) => !remaining.has(p)).map(delta)
return {