@namzu/sdk 43.0.0 → 44.1.0

package/src/store/session/memory.ts

@@ -17,12 +17,10 @@ import {
 	TenantIsolationError,
 } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
-import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
-import type { Message } from '../../types/message/index.js'
+import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, TopicId } from '../../types/session/ids.js'
-import type { SessionMessage } from '../../types/session/messages.js'
 import type {
 	CreateProjectParams,
 	CreateSessionParams,
@@ -36,7 +34,6 @@ import type { SessionSummaryRef } from '../../types/summary/ref.js'
 import {
 	asProjectId,
 	asTenantId,
-	generateMessageId,
 	generateProjectId,
 	generateSessionId,
 	generateSubSessionId,
@@ -81,7 +78,6 @@ export class InMemorySessionStore implements SessionStore {
 	private readonly projects = new Map<ProjectId, ProjectRecord>()
 	private readonly sessions = new Map<SessionId, SessionRecord>()
 	private readonly subSessions = new Map<SubSessionId, SubSessionRecord>()
-	private readonly messages = new Map<SessionId, SessionMessage[]>()
 	private readonly summaries = new Map<SessionId, SummaryRecord>()
 
 	/** Hydrate existing Project snapshots without minting replacement identities. */
@@ -368,7 +364,6 @@ export class InMemorySessionStore implements SessionStore {
 		}
 
 		this.sessions.delete(sessionId)
-		this.messages.delete(sessionId)
 		this.summaries.delete(sessionId)
 	}
 
@@ -431,78 +426,6 @@ export class InMemorySessionStore implements SessionStore {
 		this.subSessions.delete(subSessionId)
 	}
 
-	// Messages ----------------------------------------------------------------
-
-	async appendMessage(
-		sessionId: SessionId,
-		message: Message,
-		tenantId: TenantId,
-	): Promise<MessageId> {
-		const record = this.sessions.get(sessionId)
-		if (!record) {
-			throw new Error(`Session ${sessionId} not found`)
-		}
-		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
-
-		const id = generateMessageId()
-		const entry: SessionMessage = {
-			id,
-			sessionId,
-			tenantId,
-			message,
-			at: new Date(),
-		}
-		const existing = this.messages.get(sessionId)
-		if (existing) {
-			existing.push(entry)
-		} else {
-			this.messages.set(sessionId, [entry])
-		}
-		return id
-	}
-
-	async replaceMessages(
-		sessionId: SessionId,
-		messages: readonly Message[],
-		tenantId: TenantId,
-	): Promise<void> {
-		const record = this.sessions.get(sessionId)
-		if (!record) throw new Error(`Session ${sessionId} not found`)
-		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
-
-		const at = new Date()
-		this.messages.set(
-			sessionId,
-			messages.map((message) => ({
-				id: generateMessageId(),
-				sessionId,
-				tenantId,
-				message,
-				at,
-			})),
-		)
-	}
-
-	async loadMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly Message[]> {
-		const record = this.sessions.get(sessionId)
-		if (!record) return []
-		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
-		const entries = this.messages.get(sessionId) ?? []
-		return entries.map((e) => e.message)
-	}
-
-	async loadSessionMessages(
-		sessionId: SessionId,
-		tenantId: TenantId,
-	): Promise<readonly SessionMessage[]> {
-		const record = this.sessions.get(sessionId)
-		if (!record) return []
-		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
-		const entries = this.messages.get(sessionId) ?? []
-		// Return a shallow copy so callers cannot mutate the internal log.
-		return entries.map((e) => ({ ...e }))
-	}
-
 	// Linkage -----------------------------------------------------------------
 
 	async getChildren(sessionId: SessionId, tenantId: TenantId): Promise<readonly SubSession[]> {

package/src/store/session-claim.ts

@@ -0,0 +1,101 @@
+import { invariants } from '../invariants/index.js'
+import { type SessionLocatorOptions, locateSessionLog } from '../runtime/query/abandon-turn.js'
+import { NamzuError } from '../types/errors/index.js'
+import type { SessionId } from '../types/ids/index.js'
+import type { FencingToken, LeaseSummary } from '../types/session/durable.js'
+import type { ClaimSessionOptions, SessionLease, SessionLog } from './session-log/index.js'
+
+/**
+ * Take exclusive working possession of a session (its `lease.json`), or
+ * report that somebody else holds it. `null` is the ordinary outcome of a
+ * queue with more than one reader, not an error.
+ *
+ * A lease expires; claiming an expired one succeeds and mints a fence
+ * strictly greater than every fence issued before, so the stalled holder's
+ * next append is refused.
+ */
+export async function claimSession(
+	sessionId: SessionId,
+	options: ClaimSessionOptions & Omit<SessionLocatorOptions, 'lease'>,
+): Promise<SessionLease | null> {
+	const { log: given, index, home, ...claim } = options
+	const log = await locateSessionLog(sessionId, {
+		...(given ? { log: given } : {}),
+		...(index ? { index } : {}),
+		...(home ? { home } : {}),
+	})
+	return log.claim(claim)
+}
+
+/**
+ * Give a lease up early. Idempotent; presenting a superseded lease releases
+ * nothing.
+ */
+export async function releaseSession(
+	sessionId: SessionId,
+	lease: SessionLease,
+	options: Omit<SessionLocatorOptions, 'lease'> = {},
+): Promise<void> {
+	const log = await locateSessionLog(sessionId, options)
+	await log.release(lease)
+}
+
+/** A lease as a listing reports it, judged against one clock. */
+export function toClaimSummary(lease: SessionLease, now: number): LeaseSummary {
+	return {
+		holder: lease.holder,
+		fence: lease.fence,
+		expiresAt: lease.expiresAt,
+		expired: now >= lease.expiresAt,
+	}
+}
+
+/** The refusal for an append presented under a superseded lease. */
+export function fencedOut(
+	sessionId: SessionId,
+	presented: FencingToken,
+	current: FencingToken,
+): NamzuError {
+	return new NamzuError({
+		code: 'storage_error',
+		message: `Refusing an append to session ${sessionId} fenced at ${presented}: the session is now leased at ${current}. Another worker took it over, so this process no longer holds it. Stop rather than retrying: the lease is gone, not busy.`,
+		details: { sessionId, presentedFence: presented, currentFence: current },
+		retryable: false,
+	})
+}
+
+/** What `session-log:single-open-writer` is evaluated against: one session and the fence a writer presents. */
+export interface SingleOpenWriterContext {
+	readonly log: SessionLog
+	readonly presentedFence: FencingToken
+}
+
+/**
+ * One writer per session: a writer presenting a fence below the session's
+ * current lease is a stalled holder somebody took the session from.
+ * Evaluated per session; without one it reports `unknown`.
+ */
+invariants.register<SingleOpenWriterContext | undefined>(
+	'session-log',
+	'single-open-writer',
+	async (ctx) => {
+		if (!ctx) {
+			return {
+				state: 'unknown',
+				reason:
+					'no session log given — this invariant is evaluated per session, not for the process as a whole',
+			}
+		}
+		const current = await ctx.log.lease()
+		if (current && ctx.presentedFence < current.fence) {
+			const holderNote = current.holder ? ` (now held by "${current.holder}")` : ''
+			return {
+				state: 'violated',
+				detail:
+					`presented fence ${ctx.presentedFence} is behind this session's current fence ` +
+					`${current.fence}${holderNote} — another worker has taken this session over`,
+			}
+		}
+		return { state: 'holds' }
+	},
+)

package/src/store/session-index/fts.ts

@@ -0,0 +1,215 @@
+import type { SessionRecord } from '../../types/session/records.js'
+import { evidenceTokenMatcher, isEvidenceToken } from '../../utils/evidence-tokens.js'
+import { compactedToolMetadata } from '../evidence/compaction-provenance.js'
+
+/**
+ * Evidence search over the session logs: which text a record contributes,
+ * and what counts as a match.
+ *
+ * The text sources and the match rules are today's evidence search
+ * (`store/evidence`): a tool result, an assistant message's text, and the
+ * messages a compaction shed; literal substring or whole-token matching,
+ * case-sensitive by default, no regex operators, no ranking. `evidence_fts`
+ * (FTS5, trigram tokenizer) only narrows the candidates. Every candidate is
+ * checked here, so the SQLite index and the scan index return the same hits.
+ */
+
+/** One searchable text part of one record. */
+export interface EvidenceText {
+	/** The part's position among the record's text parts. */
+	readonly part: number
+	/** `tool_completed`, `message_completed`, or `compaction_shed:<role|summary>`. */
+	readonly source: string
+	readonly text: string
+	readonly toolName?: string
+	readonly isError?: boolean
+}
+
+function plainObject(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined
+}
+
+const ROLES = new Set(['system', 'user', 'assistant', 'tool'])
+
+interface ShedText {
+	source: string
+	text: string
+	toolName?: string
+	isError?: boolean
+}
+
+/**
+ * The texts of shed messages, in today's order: every plain-string message
+ * first, then the text blocks of tool messages. Binary blocks are never text.
+ * A tool message's texts carry its tool name and error flag, as today's
+ * compaction text does.
+ */
+function shedTexts(messages: unknown): ShedText[] {
+	if (!Array.isArray(messages)) return []
+	const strings: ShedText[] = []
+	const blocks: ShedText[] = []
+	const metadata = compactedToolMetadata(messages)
+	for (const [index, value] of messages.entries()) {
+		const message = plainObject(value)
+		if (!message || typeof message.role !== 'string' || !ROLES.has(message.role)) continue
+		const role = message.role
+		const tool = metadata[index]
+		if (typeof message.content === 'string') {
+			const summary =
+				role === 'system' && plainObject(message.source)?.type === 'compaction-summary'
+			strings.push({
+				source: `compaction_shed:${summary ? 'summary' : role}`,
+				text: message.content,
+				...tool,
+			})
+		} else if (role === 'tool' && Array.isArray(message.content)) {
+			for (const block of message.content) {
+				const part = plainObject(block)
+				if (part?.type === 'text' && typeof part.text === 'string') {
+					blocks.push({ source: 'compaction_shed:tool', text: part.text, ...tool })
+				}
+			}
+		}
+	}
+	return strings.concat(blocks)
+}
+
+/** The searchable text parts of one record; empty for a record that carries none. */
+export function evidenceTexts(record: SessionRecord): EvidenceText[] {
+	switch (record.type) {
+		case 'tool_completed':
+			return typeof record.result === 'string'
+				? [
+						{
+							part: 0,
+							source: 'tool_completed',
+							text: record.result,
+							toolName: record.toolName,
+							isError: record.isError,
+						},
+					]
+				: []
+		case 'message_completed':
+			return typeof record.content === 'string'
+				? [{ part: 0, source: 'message_completed', text: record.content }]
+				: []
+		case 'compaction_shed':
+			return shedTexts(record.messages).map((text, part) => ({ part, ...text }))
+		default:
+			return []
+	}
+}
+
+/** What to look for. Exactly today's evidence-search options. */
+export interface EvidenceQuery {
+	/** A literal string. An empty query (or none) matches every part. */
+	readonly query?: string
+	/** One to sixteen literal terms, matched as alternatives. Exclusive with `query`. */
+	readonly terms?: readonly string[]
+	/** `literal` (the default) matches substrings; `token` matches whole letter/number/underscore tokens. */
+	readonly matchMode?: 'literal' | 'token'
+	/** Defaults to true. */
+	readonly caseSensitive?: boolean
+}
+
+/** Where the first match in a text is, and the excerpt around it (UTF-16 positions). */
+export interface EvidenceMatch {
+	readonly hit: number
+	readonly start: number
+	readonly end: number
+}
+
+export class EvidenceQueryError extends Error {
+	override readonly name = 'EvidenceQueryError'
+}
+
+const LOW_SURROGATE = /[\uDC00-\uDFFF]/
+
+function queryTerms(query: EvidenceQuery): readonly string[] {
+	if (query.terms !== undefined && query.query !== undefined) {
+		throw new EvidenceQueryError('Supply either a literal query or literal terms, not both.')
+	}
+	if (query.terms !== undefined) {
+		if (query.terms.length === 0 || query.terms.length > 16) {
+			throw new EvidenceQueryError('Supply between one and sixteen terms.')
+		}
+		for (const term of query.terms) {
+			if (term.trim().length === 0 || term.length > 256) {
+				throw new EvidenceQueryError('Each term is nonblank and at most 256 characters.')
+			}
+		}
+		return [...new Set(query.terms)]
+	}
+	return [query.query ?? '']
+}
+
+/**
+ * The matcher for a query: the first hit in a text and the excerpt a result
+ * shows for it (up to 120 characters before the hit, 512 in all, never
+ * splitting a surrogate pair), or `undefined` when the text does not match.
+ */
+export function evidenceMatcher(query: EvidenceQuery): (text: string) => EvidenceMatch | undefined {
+	const terms = queryTerms(query)
+	const caseSensitive = query.caseSensitive ?? true
+	const single = query.terms === undefined
+	let find: (text: string) => number
+	if (query.matchMode === 'token') {
+		if (!terms.every(isEvidenceToken)) {
+			throw new EvidenceQueryError(
+				'Token search requires nonempty letter/number/underscore tokens.',
+			)
+		}
+		const match = evidenceTokenMatcher(terms, caseSensitive)
+		find = (text) => match(text, 0)?.index ?? -1
+	} else if (caseSensitive && single) {
+		const needle = terms[0] ?? ''
+		find = (text) => text.indexOf(needle)
+	} else {
+		const expression = new RegExp(
+			terms.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'),
+			caseSensitive ? 'g' : 'giu',
+		)
+		find = (text) => {
+			expression.lastIndex = 0
+			return expression.exec(text)?.index ?? -1
+		}
+	}
+	return (text) => {
+		const hit = find(text)
+		if (hit < 0) return undefined
+		let start = Math.max(0, hit - 120)
+		if (start > 0 && LOW_SURROGATE.test(text[start] ?? '')) start--
+		let end = Math.min(text.length, start + 512)
+		if (end < text.length && LOW_SURROGATE.test(text[end] ?? '')) end--
+		return { hit, start, end }
+	}
+}
+
+/**
+ * Characters that a case-insensitive JavaScript match folds onto an ASCII
+ * letter although SQLite's folding may not (U+212A KELVIN SIGN onto `k`,
+ * U+017F LONG S onto `s`). A case-insensitive term containing `k` or `s`
+ * therefore gets no FTS narrowing, so the narrowing can never drop a hit.
+ */
+const FOLDS_FROM_NON_ASCII = /[ks]/i
+const PRINTABLE_ASCII = /^[\x20-\x7e]+$/
+
+/**
+ * The FTS5 `MATCH` expression that narrows the candidates for a query, or
+ * `undefined` when narrowing could drop a hit and every part must be checked.
+ *
+ * The trigram tokenizer folds ASCII case and matches a quoted string as a
+ * substring, so for printable-ASCII terms of three or more characters its
+ * result is a superset of the literal and token matches.
+ */
+export function ftsMatchExpression(query: EvidenceQuery): string | undefined {
+	const terms = queryTerms(query)
+	const caseSensitive = query.caseSensitive ?? true
+	for (const term of terms) {
+		if (term.length < 3 || !PRINTABLE_ASCII.test(term)) return undefined
+		if (!caseSensitive && FOLDS_FROM_NON_ASCII.test(term)) return undefined
+	}
+	return terms.map((term) => `"${term.replace(/"/g, '""')}"`).join(' OR ')
+}

package/src/store/session-index/index.ts

@@ -0,0 +1,253 @@
+import { join } from 'node:path'
+import { resolveNamzuHome } from '../../session/home.js'
+import type { ProjectId, SessionId, TurnId } from '../../types/ids/index.js'
+import type { RecordPointer, SessionRecord } from '../../types/session/records.js'
+import type { TurnExecutionStatus } from '../../types/session/turn.js'
+import type { EvidenceQuery } from './fts.js'
+import type { ExternalRefKind, ExternalRefTarget } from './refs.js'
+import { ScanSessionIndex } from './scan.js'
+import { SqliteSessionIndex, sqliteAvailable } from './sqlite.js'
+
+/**
+ * The rebuildable index over every session log under `NAMZU_HOME`
+ * (`$NAMZU_HOME/index.sqlite`, spec §4.6).
+ *
+ * The logs are the source of truth; every row here is derived from their
+ * records and nothing is written directly, so deleting the index loses
+ * nothing. `SqliteSessionIndex` keeps it in SQLite where `node:sqlite` loads
+ * (Node 22.13+); elsewhere `ScanSessionIndex` derives the same answers in
+ * memory from the logs.
+ */
+
+/** One record as a log reader yields it: the record and where it sits in its file. */
+export interface IndexableRecord {
+	readonly record: SessionRecord
+	readonly pointer: RecordPointer
+}
+
+/** One session log to index, as records. */
+export interface SessionLogInput {
+	/** The project slug the log is filed under (`projects/<slug>/`). */
+	readonly slug: string
+	/** The log's path, recorded so a later check can compare the file with the index. */
+	readonly logPath: string
+	/**
+	 * The records, in order. Starting at seq 1 re-derives the session from
+	 * scratch; starting right after the indexed head continues it; anything
+	 * else is refused.
+	 */
+	readonly records: AsyncIterable<IndexableRecord> | Iterable<IndexableRecord>
+}
+
+/**
+ * `running`: a turn is open and not parked (the index cannot see leases, so
+ * an interrupted turn also reads `running`); `paused`: the open turn is
+ * parked; `idle`: no turn is open.
+ */
+export type IndexedSessionStatus = 'idle' | 'running' | 'paused'
+
+export interface IndexedSession {
+	readonly id: SessionId
+	readonly slug: string
+	readonly projectId: ProjectId
+	readonly parentId?: SessionId
+	readonly rootId: SessionId
+	/** 0 for a root session. */
+	readonly depth: number
+	readonly title?: string
+	readonly archived: boolean
+	readonly status: IndexedSessionStatus
+	readonly createdAt: string
+	readonly updatedAt: string
+	readonly logPath: string
+	/** Bytes of the log the index has read: the end of the head record. */
+	readonly logBytes: number
+	readonly headSeq: number
+	readonly headSha256: string
+}
+
+/** A turn's state as its records leave it. `paused` is parked, not terminal. */
+export type IndexedTurnStatus = 'running' | 'paused' | 'completed' | 'cancelled' | 'failed'
+
+export interface IndexedTurn {
+	readonly id: TurnId
+	readonly sessionId: SessionId
+	readonly status: IndexedTurnStatus
+	readonly stopReason?: string
+	readonly startedAt: string
+	readonly endedAt?: string
+	/** The settled total; 0 until the turn settles. */
+	readonly tokens: number
+	readonly costUsd: number
+	/** The first 200 characters of the prompt that opened the turn. */
+	readonly userPreview?: string
+	readonly originKind?: string
+}
+
+/** A decision a parked turn is waiting on. */
+export interface IndexedPendingDecision {
+	readonly decisionId: string
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	readonly checkpointId: string
+	readonly deadlineAt?: string
+}
+
+/** A child session as its parent's log describes it, with the child's own row once its log is indexed. */
+export interface ChildSessionSummary {
+	readonly sessionId: SessionId
+	readonly parentSessionId: SessionId
+	readonly parentTurnId: TurnId
+	readonly toolCallId: string
+	readonly kind: string
+	readonly description: string
+	/** The child's log, relative to the parent's session directory. */
+	readonly path: string
+	readonly batch?: { readonly batchId: string; readonly name: string; readonly phase?: string }
+	/** `running` until the parent records `child_session_ended`, then the child's settled status. */
+	readonly status: TurnExecutionStatus
+	readonly stopReason?: string
+	readonly tokens: number
+	readonly costUsd: number
+	readonly spawnedAt: string
+	readonly endedAt?: string
+	readonly session?: IndexedSession
+}
+
+/** A group of children spawned together, derived from `child_session_spawned.batch`. */
+export interface IndexedBatch {
+	readonly batchId: string
+	readonly sessionId: SessionId
+	readonly name: string
+	/** The phase the most recent spawn named. */
+	readonly phase?: string
+	readonly agentsDone: number
+	readonly agentsTotal: number
+	readonly tokensTotal: number
+}
+
+/** One searchable part that matched. */
+export interface EvidenceHit {
+	readonly sessionId: SessionId
+	readonly turnId?: TurnId
+	readonly seq: number
+	readonly part: number
+	readonly source: string
+	readonly toolName?: string
+	readonly isError?: boolean
+	/** UTF-16 position of the first match in the part's text. */
+	readonly hit: number
+	/** The text around the first match. */
+	readonly excerpt: string
+}
+
+export interface EvidenceSearchOptions extends EvidenceQuery {
+	readonly sessionId?: SessionId
+	/** Defaults to 100. */
+	readonly limit?: number
+}
+
+export interface ListSessionsOptions {
+	readonly slug?: string
+	/** Only sessions with no parent. */
+	readonly rootsOnly?: boolean
+	/** Defaults to true. */
+	readonly includeArchived?: boolean
+}
+
+/**
+ * How a log compares with its row: `fresh`, `grown` (appended since; the
+ * index continues from its head), `truncated` or `rewritten` (the head record
+ * no longer ends where it did or no longer hashes the same; the session is
+ * re-derived), `unindexed` (no row yet) or `missing` (no file).
+ */
+export type SessionStaleness =
+	| 'fresh'
+	| 'grown'
+	| 'truncated'
+	| 'rewritten'
+	| 'unindexed'
+	| 'missing'
+
+/** A log on disk, as the layout files it. */
+export interface SessionLogLocation {
+	readonly slug: string
+	readonly logPath: string
+	readonly sessionId: SessionId
+}
+
+export interface SessionIndex {
+	readonly backend: 'sqlite' | 'scan'
+	/** Derive (or continue deriving) one session from its records. */
+	indexSession(input: SessionLogInput): Promise<IndexedSession | undefined>
+	/** Compare one log with the index. */
+	staleness(location: SessionLogLocation): Promise<SessionStaleness>
+	/** Bring one session up to date with its log; returns what was found. */
+	refresh(location: SessionLogLocation): Promise<SessionStaleness>
+	/** Bring every session under `home` up to date and drop sessions whose log is gone. */
+	sync(home: string): Promise<void>
+	getSession(sessionId: SessionId): Promise<IndexedSession | undefined>
+	listSessions(options?: ListSessionsOptions): Promise<IndexedSession[]>
+	listTurns(sessionId: SessionId): Promise<IndexedTurn[]>
+	listChildren(sessionId: SessionId): Promise<ChildSessionSummary[]>
+	listPendingDecisions(options?: { sessionId?: SessionId }): Promise<IndexedPendingDecision[]>
+	/** What a caller-side name refers to. The earliest claim wins when two sessions claim one name. */
+	resolveExternal(
+		protocol: string,
+		kind: ExternalRefKind,
+		externalId: string,
+	): Promise<ExternalRefTarget | undefined>
+	/** Every name one session holds, including those another session claimed first. */
+	listExternalRefs(sessionId: SessionId): Promise<ExternalRefTarget[]>
+	batches(options?: { sessionId?: SessionId }): Promise<IndexedBatch[]>
+	searchEvidence(options: EvidenceSearchOptions): Promise<EvidenceHit[]>
+	close(): void
+}
+
+export interface OpenSessionIndexOptions {
+	/** Defaults to `resolveNamzuHome()`. */
+	readonly home?: string
+	/** Defaults to `<home>/index.sqlite`. */
+	readonly path?: string
+	/** `auto` (the default) uses SQLite when `node:sqlite` loads, the scan index otherwise. */
+	readonly backend?: 'auto' | 'sqlite' | 'scan'
+}
+
+/**
+ * Open the index for a home: a missing index, or one at another version, is
+ * rebuilt from the logs; an existing one is brought up to date with them.
+ */
+export async function openSessionIndex(
+	options: OpenSessionIndexOptions = {},
+): Promise<SessionIndex> {
+	const home = options.home ?? resolveNamzuHome()
+	const backend = options.backend ?? 'auto'
+	if (backend === 'scan' || (backend === 'auto' && !sqliteAvailable())) {
+		return ScanSessionIndex.load(home)
+	}
+	return SqliteSessionIndex.open({ home, path: options.path ?? join(home, 'index.sqlite') })
+}
+
+export { EvidenceQueryError, evidenceMatcher, evidenceTexts, ftsMatchExpression } from './fts.js'
+export type { EvidenceMatch, EvidenceQuery, EvidenceText } from './fts.js'
+export { externalRefChanges, sessionRefKind } from './refs.js'
+export type {
+	ExternalRefChange,
+	ExternalRefClaim,
+	ExternalRefKind,
+	ExternalRefTarget,
+} from './refs.js'
+export {
+	SessionIndexError,
+	discoverSessionLogs,
+	readIndexableRecords,
+} from './rebuild.js'
+export type { IndexedLogPosition } from './rebuild.js'
+export { ScanSessionIndex } from './scan.js'
+export {
+	SESSION_INDEX_VERSION,
+	SqliteSessionIndex,
+	rebuildSqliteSessionIndex,
+	sqliteAvailable,
+} from './sqlite.js'
+export type { RebuildSqliteSessionIndexOptions, SqliteSessionIndexOptions } from './sqlite.js'