@zq-silk/yui 2.1.0 → 2.2.0

package/dist/nativeAgent/searchTools.js

@@ -0,0 +1,305 @@
+import { lstat, opendir } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { FileFault, bounded, workspaceRoot, validPath, checkPath, inspect, readSnapshot, digest, fits, cursor, readCursor, lines, isBinary } from './fileToolsSupport.js';
+import { glob, regex } from './filePatterns.js';
+const fail = (code, message) => ({ code, message, effect: 'none' });
+const limit = () => new FileFault('limit_exceeded', 'Scan incomplete: entry/depth/byte budget exceeded; narrow path or query');
+const defaults = { maxEntries: 10_000, maxResults: 200, maxOutputBytes: 64 * 1024,
+    maxFileBytes: 8 * 1024 * 1024, maxTotalBytes: 32 * 1024 * 1024, maxDepth: 32, maxPatternWork: 2_000_000 };
+/** Bounded rescans, no index/daemon, no OS sandbox. .git is always excluded. */
+export function createSearchTools(options) {
+    const root = workspaceRoot(options.root);
+    const limits = { ...defaults };
+    for (const key of Object.keys(defaults))
+        limits[key] = bounded(options[key], defaults[key], key);
+    const validate = (args, name) => {
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            return fail('invalid_arguments', 'Expected an argument object');
+        if (!validPath(args.path))
+            return fail(typeof args.path === 'string' && (path.isAbsolute(args.path)
+                || args.path.split(/[\\/]/).includes('..')) ? 'path_out_of_scope' : 'invalid_arguments', 'Expected a bounded relative path');
+        if (Object.keys(args).some(key => !['path', 'query', 'mode', 'cursor', 'ignore', 'generated', 'hidden', 'exclude'].includes(key))
+            || (name === 'list' && (args.query !== undefined || args.mode !== undefined))
+            || (name !== 'list' && (typeof args.query !== 'string' || !args.query || args.query.length > 4096 || /[\0\r\n]/.test(args.query)))
+            || (args.mode !== undefined && !['literal', 'glob', 'regex'].includes(args.mode))
+            || (args.mode === 'regex' && name !== 'search') || (args.mode === 'glob' && name !== 'find')
+            || ['ignore', 'generated', 'hidden'].some(key => args[key] !== undefined && typeof args[key] !== 'boolean')
+            || (args.cursor !== undefined && (typeof args.cursor !== 'string' || !args.cursor || args.cursor.length > 2048))
+            || (args.exclude !== undefined && (!Array.isArray(args.exclude) || args.exclude.length > 16
+                || args.exclude.some(item => typeof item !== 'string')))) {
+            return fail('invalid_arguments', 'Expected query mode, optional cursor and explicit discovery policy');
+        }
+        return null;
+    };
+    return ['list', 'find', 'search'].map(name => ({
+        definition: {
+            name,
+            description: name === 'list' ? 'List immediate entries with bounded pages and explicit discovery coverage'
+                : name === 'find' ? 'Find literal basename substrings (default) or root-relative glob patterns; bounded pages bind scan/policy. '
+                    + 'Glob (max 256 characters): *, ?, [] ranges/negation, backslash literal escapes outside []; ** only as a whole path segment. '
+                    + 'No braces or extglob (@(), +(), ?(), !(), *()). Example: mode="glob", query="**/*.ts".'
+                    : 'Search literal substrings (default) or bounded single-line regex; matching line snippets, real line numbers, explicit binary/policy coverage. '
+                        + 'Regex (max 256 characters): literals, ., [] ranges/^ negation, ^/$ anchors, *+?, \\d/\\w/\\s, escaped metacharacters. '
+                        + 'No groups, alternation, counted repeats, flags, lookaround, backreferences or escapes inside []. '
+                        + 'Example: mode="regex", query="^TODO\\\\s+.+$" (JSON-escaped).',
+            inputSchema: { type: 'object', properties: { path: { type: 'string' },
+                    ...(name !== 'list' ? { query: { type: 'string' }, mode: { type: 'string', enum: name === 'find'
+                                ? ['literal', 'glob'] : ['literal', 'regex'] } } : {}),
+                    cursor: { type: 'string' }, ignore: { type: 'boolean' }, generated: { type: 'boolean' },
+                    hidden: { type: 'boolean' }, exclude: { type: 'array', maxItems: 16, items: { type: 'string' } } },
+                required: name === 'list' ? ['path'] : ['path', 'query'], additionalProperties: false },
+        },
+        validate: args => validate(args, name),
+        async execute(args, scope, signal) {
+            const invalid = validate(args, name);
+            if (invalid)
+                return { ok: false, error: invalid };
+            const request = args;
+            try {
+                signal.throwIfAborted();
+                const start = await checkPath(root, request.path);
+                const startInfo = await inspect(start);
+                if (path.relative(root, start).split(path.sep).includes('.git')) {
+                    throw new FileFault('git_metadata_denied', 'Discovery does not enter .git metadata, including explicit paths');
+                }
+                const budget = { remaining: limits.maxPatternWork };
+                const match = request.mode === 'glob' ? glob(request.query) : request.mode === 'regex' ? regex(request.query) : undefined;
+                const excludes = (request.exclude ?? []).map(pattern => ({ pattern, match: glob(pattern) }));
+                const policy = { ignore: request.ignore ?? true, generated: request.generated ?? true,
+                    hidden: request.hidden ?? true, exclude: request.exclude ?? [], gitMetadata: false };
+                const binding = digest(JSON.stringify([name, request.path, request.query ?? null, request.mode ?? 'literal', policy, limits]));
+                // Decode request binding before the scan; fingerprint is checked after the bounded full rescan.
+                let offset = 0;
+                let previousFingerprint;
+                if (request.cursor) {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(Buffer.from(request.cursor, 'base64url').toString('utf8'));
+                    }
+                    catch {
+                        throw new FileFault('invalid_cursor', 'Cursor cannot be decoded');
+                    }
+                    if (!parsed || parsed.binding !== binding || typeof parsed.fingerprint !== 'string') {
+                        throw new FileFault('invalid_cursor', 'Cursor does not match request');
+                    }
+                    offset = readCursor(request.cursor, binding, parsed.fingerprint, Number.MAX_SAFE_INTEGER);
+                    previousFingerprint = parsed.fingerprint;
+                }
+                const fingerprint = createHash('sha256');
+                let scanned = 0;
+                let totalBytes = 0;
+                let ruleCount = 0;
+                let count = 0;
+                const skipped = { gitMetadata: 0, ignored: 0, generated: 0, hidden: 0, excluded: 0, binary: 0 };
+                const results = [];
+                const record = (target, info) => {
+                    fingerprint.update(JSON.stringify([path.relative(root, target), info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs]));
+                };
+                const append = (result) => {
+                    if (count >= offset && results.length <= limits.maxResults)
+                        results.push(result);
+                    count++;
+                };
+                const loadRules = async (directory, inherited) => {
+                    let rules = inherited;
+                    if (directory !== root) {
+                        try {
+                            const git = await lstat(path.join(directory, '.git'));
+                            if (git.isDirectory() || git.isFile())
+                                rules = []; // Nested repository starts a new ignore scope.
+                        }
+                        catch (error) {
+                            if (error.code !== 'ENOENT')
+                                throw error;
+                        }
+                    }
+                    if (!policy.ignore)
+                        return rules;
+                    const ignorePath = path.join(directory, '.gitignore');
+                    let content;
+                    try {
+                        await inspect(ignorePath);
+                        content = await readSnapshot(ignorePath, Math.min(64 * 1024, limits.maxFileBytes), signal);
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT')
+                            return rules;
+                        throw error;
+                    }
+                    totalBytes += content.bytes;
+                    if (totalBytes > limits.maxTotalBytes)
+                        throw limit();
+                    fingerprint.update(ignorePath + content.sha256 + content.identity);
+                    const base = path.relative(root, directory).split(path.sep).join('/');
+                    const added = [];
+                    for (let pattern of content.text.split(/\r?\n/)) {
+                        if (!pattern || pattern.startsWith('#'))
+                            continue;
+                        if (++ruleCount > 1024)
+                            throw new FileFault('pattern_limit', 'Too many ignore rules');
+                        const negate = pattern.startsWith('!');
+                        if (negate)
+                            pattern = pattern.slice(1);
+                        const directoryOnly = pattern.endsWith('/');
+                        if (directoryOnly)
+                            pattern = pattern.slice(0, -1);
+                        const anchored = pattern.startsWith('/');
+                        if (anchored)
+                            pattern = pattern.slice(1);
+                        added.push({ base, directory: directoryOnly, negate, basename: !anchored && !pattern.includes('/'), match: glob(pattern) });
+                    }
+                    return [...rules, ...added];
+                };
+                const omitted = (display, basename, directory, rules) => {
+                    if (basename === '.git') {
+                        skipped.gitMetadata++;
+                        return true;
+                    }
+                    if (!policy.hidden && basename.startsWith('.')) {
+                        skipped.hidden++;
+                        return true;
+                    }
+                    if (policy.generated && directory && ['node_modules', 'dist', 'build', 'coverage'].includes(basename)) {
+                        skipped.generated++;
+                        return true;
+                    }
+                    if (excludes.some(rule => rule.match(rule.pattern.includes('/') ? display : basename, budget))) {
+                        skipped.excluded++;
+                        return true;
+                    }
+                    let ignored = false;
+                    for (const rule of rules) {
+                        if (rule.directory && !directory)
+                            continue;
+                        if (rule.base && !display.startsWith(rule.base + '/'))
+                            continue;
+                        const local = rule.base ? display.slice(rule.base.length + 1) : display;
+                        if (rule.match(rule.basename ? basename : local, budget))
+                            ignored = !rule.negate;
+                    }
+                    if (ignored)
+                        skipped.ignored++;
+                    return ignored;
+                };
+                const fileResult = async (target, display) => {
+                    const info = await inspect(target);
+                    record(target, info);
+                    if (name === 'find') {
+                        if (match ? match(display, budget) : path.basename(target).includes(request.query))
+                            append({ path: display });
+                        return;
+                    }
+                    if (name === 'list') {
+                        append({ path: display, type: 'file' });
+                        return;
+                    }
+                    if (info.size > limits.maxFileBytes || info.size + totalBytes > limits.maxTotalBytes)
+                        throw limit();
+                    const snapshot = await readSnapshot(target, limits.maxFileBytes, signal);
+                    totalBytes += snapshot.bytes;
+                    if (totalBytes > limits.maxTotalBytes)
+                        throw limit();
+                    fingerprint.update(snapshot.sha256 + snapshot.identity);
+                    if (isBinary(snapshot.text)) {
+                        skipped.binary++;
+                        return;
+                    }
+                    let line = 0;
+                    let byteStart = 0;
+                    for (const raw of lines(snapshot.text)) {
+                        signal.throwIfAborted();
+                        line++;
+                        const text = raw.endsWith('\n') ? raw.slice(0, raw.endsWith('\r\n') ? -2 : -1) : raw;
+                        const matches = match ? match(text, budget) : text.includes(request.query);
+                        if (matches) {
+                            // Long matching lines are previews, not silently complete text.
+                            let end = Math.min(text.length, Math.max(1, Math.floor(limits.maxOutputBytes / 8)));
+                            if (/[\uDC00-\uDFFF]/.test(text[end] ?? ''))
+                                end--;
+                            const snippet = text.slice(0, end);
+                            append(end === text.length ? { path: display, line, text } : { path: display, line, text: snippet,
+                                textTruncated: true, lineBytes: Buffer.byteLength(text), byteStart, sha256: snapshot.sha256 });
+                        }
+                        byteStart += Buffer.byteLength(raw);
+                    }
+                };
+                const scan = async (directory, depth, inherited) => {
+                    signal.throwIfAborted();
+                    if (depth > limits.maxDepth)
+                        throw limit();
+                    const before = await inspect(directory);
+                    record(directory, before);
+                    const rules = await loadRules(directory, inherited);
+                    const names = [];
+                    const dir = await opendir(directory);
+                    for await (const entry of dir) {
+                        if (++scanned > limits.maxEntries)
+                            throw limit();
+                        names.push(entry.name);
+                    }
+                    names.sort();
+                    for (const basename of names) {
+                        signal.throwIfAborted();
+                        const target = path.join(directory, basename);
+                        const info = await lstat(target);
+                        const display = path.relative(root, target).split(path.sep).join('/');
+                        record(target, info);
+                        if (omitted(display, basename, info.isDirectory(), rules))
+                            continue;
+                        await inspect(target);
+                        if (info.isDirectory()) {
+                            if (name === 'list')
+                                append({ path: display, type: 'directory' });
+                            else
+                                await scan(target, depth + 1, rules);
+                        }
+                        else
+                            await fileResult(target, display);
+                    }
+                    const after = await inspect(directory);
+                    if (before.ino !== after.ino || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+                        throw new FileFault('edit_conflict', 'Directory changed during scan');
+                    }
+                };
+                let inherited = [];
+                const relativeParts = path.relative(root, start).split(path.sep).filter(Boolean);
+                let ancestor = root;
+                for (const part of startInfo.isDirectory() ? relativeParts : []) {
+                    inherited = await loadRules(ancestor, inherited);
+                    ancestor = path.join(ancestor, part);
+                }
+                if (startInfo.isDirectory())
+                    await scan(start, 0, inherited);
+                else
+                    await fileResult(start, path.relative(root, start).split(path.sep).join('/')); // Explicit files bypass discovery filters.
+                signal.throwIfAborted();
+                const stamp = fingerprint.digest('hex');
+                if (previousFingerprint !== undefined && previousFingerprint !== stamp)
+                    throw new FileFault('stale_cursor', 'Scan changed; restart query');
+                if (offset > count)
+                    throw new FileFault('invalid_cursor', 'Cursor exceeds results');
+                const page = results.slice(0, limits.maxResults);
+                const make = () => {
+                    const complete = offset + page.length === count;
+                    return { ok: true, content: JSON.stringify({ results: page, complete, scanComplete: true,
+                            nextCursor: complete ? null : cursor(binding, stamp, offset + page.length),
+                            coverage: { complete: Object.values(skipped).every(value => value === 0), policy },
+                            skipped, budgets: { entries: scanned, bytes: totalBytes, patternWork: limits.maxPatternWork - budget.remaining },
+                            truncationReason: complete ? null : page.length < limits.maxResults ? 'output_bytes' : 'result_limit' }) };
+                };
+                while (page.length && !fits(make(), limits.maxOutputBytes, name, scope.toolCallId))
+                    page.pop();
+                if ((offset < count && !page.length) || !fits(make(), limits.maxOutputBytes, name, scope.toolCallId)) {
+                    throw new FileFault('limit_exceeded', 'Output cannot hold one result plus coverage metadata; increase budget or narrow path');
+                }
+                return make();
+            }
+            catch (error) {
+                const code = error instanceof FileFault ? error.code === 'too_large' ? 'limit_exceeded' : error.code
+                    : signal.aborted ? 'cancelled' : error.code === 'ENOENT' ? 'not_found' : 'io_error';
+                return { ok: false, error: fail(code, error instanceof FileFault ? error.message : `Scan incomplete (${code})`) };
+            }
+        },
+    }));
+}

package/dist/nativeAgent/session/backends.js

@@ -0,0 +1,293 @@
+import Database from 'better-sqlite3';
+import { randomUUID } from 'node:crypto';
+import { isAbsolute, resolve } from 'node:path';
+import { existsSync, lstatSync } from 'node:fs';
+import { copyEvent, encode, identity, inspectDocument, revision, SessionError, sessionLimits } from './format.js';
+import { currentCursor, historyRecords, increment, metadataRevision, nextCursor, normalizeTitle, pageLimit, queryBounds, readCursor, } from './catalog.js';
+import { decode, digest, hash, initializeSessionDatabase } from './sqliteFormat.js';
+import { copyLocation, decodeLocation } from './location.js';
+export { digest } from './sqliteFormat.js';
+function transition(previous, next, expected) {
+    if (expected === null ? previous !== null : !previous || revision(previous) !== expected) {
+        throw new SessionError('revision_conflict', 'Session revision conflict; reload, do not replay uncertain effects');
+    }
+    if (expected === null ? next.events.length !== 0
+        : next.events.length !== expected + 1
+            || JSON.stringify(next.events.slice(0, -1)) !== JSON.stringify(previous.events)) {
+        throw new SessionError('invalid_append', 'Write must create an empty Session or append exactly one immutable fact');
+    }
+}
+function missing() { throw new SessionError('not_found', 'Session not found'); }
+function compareIds(a, b) { return Buffer.compare(Buffer.from(a), Buffer.from(b)); }
+function seek(ids, after) {
+    let lo = 0, hi = ids.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (compareIds(ids[mid], after) <= 0)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+export function createMemorySessionBackend() {
+    const source = Object.freeze({ id: `memory:${randomUUID()}`, durability: 'volatile' });
+    const storeId = randomUUID();
+    const documents = new Map();
+    const metadata = new Map();
+    const ids = [];
+    let catalogRevision = 0;
+    let closed = false;
+    const check = () => { if (closed)
+        throw new SessionError('closed', 'Session backend is closed'); };
+    const info = (sessionId) => {
+        check();
+        identity(sessionId);
+        const stored = documents.get(sessionId) ?? missing();
+        return { ...metadata.get(sessionId), revision: revision(stored.document), digest: stored.digest, source, storeId,
+            location: stored.location === null ? null : { ...stored.location } };
+    };
+    const query = (sessionId, after, limit) => {
+        queryBounds(after, limit);
+        const detail = info(sessionId);
+        if (after > detail.revision)
+            throw new SessionError('invalid_query', 'Cursor exceeds saved revision');
+        const records = historyRecords(after, detail.revision, limit, at => ({
+            revision: at, event: structuredClone(documents.get(sessionId).document.events[at - 1]),
+        }));
+        const end = records.at(-1)?.revision ?? after;
+        return { sessionId, revision: detail.revision, digest: detail.digest, source, records,
+            nextCursor: end < detail.revision ? end : null };
+    };
+    const write = (document, expectedRevision, location = null) => {
+        check();
+        const next = inspectDocument(document).document;
+        const previous = documents.get(next.sessionId);
+        transition(previous?.document ?? null, next, expectedRevision);
+        const nextDigest = digest(next);
+        if (expectedRevision === null) {
+            const nextRevision = increment(catalogRevision);
+            metadata.set(next.sessionId, { sessionId: next.sessionId, title: null, metadataRevision: 0 });
+            ids.splice(seek(ids, next.sessionId), 0, next.sessionId);
+            catalogRevision = nextRevision;
+        }
+        documents.set(next.sessionId, { document: next, digest: nextDigest, location: previous?.location ?? location });
+    };
+    return {
+        source,
+        catalog: {
+            async getSessionInfo(sessionId) { return info(sessionId); },
+            async listSessions(options = {}) {
+                check();
+                const limit = pageLimit(options);
+                const cursor = readCursor(options, storeId, 'sessions');
+                currentCursor(cursor, catalogRevision);
+                if (cursor && !metadata.has(cursor.after)) {
+                    throw new SessionError('invalid_cursor', 'Cursor does not identify a saved Session');
+                }
+                const start = cursor ? seek(ids, cursor.after) : 0;
+                const selected = ids.slice(start, start + limit);
+                return { storeId, catalogRevision, items: selected.map(id => ({ ...metadata.get(id) })),
+                    nextCursor: start + selected.length < ids.length
+                        ? nextCursor(storeId, 'sessions', limit, catalogRevision, selected.at(-1)) : null };
+            },
+            async renameSession(sessionId, title, expected) {
+                const detail = info(sessionId);
+                const nextTitle = normalizeTitle(title);
+                metadataRevision(expected);
+                if (detail.metadataRevision !== expected)
+                    throw new SessionError('revision_conflict', 'Metadata revision conflict; read current title');
+                if (detail.title !== nextTitle) {
+                    const nextRevision = increment(catalogRevision);
+                    metadata.set(sessionId, { sessionId, title: nextTitle, metadataRevision: increment(expected) });
+                    catalogRevision = nextRevision;
+                }
+                return info(sessionId);
+            },
+            async readHistory(sessionId, options = {}) {
+                check();
+                identity(sessionId);
+                const limit = pageLimit(options);
+                const cursor = readCursor(options, storeId, 'history', sessionId);
+                const detail = info(sessionId);
+                currentCursor(cursor, detail.revision);
+                const page = query(sessionId, cursor ? cursor.after : 0, limit);
+                return { ...page, storeId, nextCursor: page.nextCursor === null ? null
+                        : nextCursor(storeId, 'history', limit, detail.revision, page.nextCursor, sessionId) };
+            },
+        },
+        async query(sessionId, options) { check(); return query(sessionId, options.after, options.limit); },
+        async read(sessionId) {
+            check();
+            identity(sessionId);
+            return structuredClone(documents.get(sessionId)?.document ?? null);
+        },
+        async write(document, expectedRevision) {
+            write(document, expectedRevision);
+        },
+        async createWithLocation(document, location) { write(document, null, copyLocation(location)); },
+        async close() { closed = true; documents.clear(); metadata.clear(); ids.length = 0; },
+    };
+}
+/** Caller-selected local file; no Yui Home discovery, global connection or daemon. */
+export function createSqliteSessionBackend(filename) {
+    if (!isAbsolute(filename) || (existsSync(filename)
+        && (lstatSync(filename).isSymbolicLink() || !lstatSync(filename).isFile()))) {
+        throw new SessionError('invalid_path', 'An absolute controlled regular-file path is required');
+    }
+    const db = new Database(filename, { timeout: 1000 });
+    try {
+        db.pragma('synchronous = FULL');
+        const journal = db.pragma('journal_mode', { simple: true });
+        if (journal !== 'delete')
+            throw new SessionError('unsupported_format', 'Session database requires DELETE journal mode');
+        initializeSessionDatabase(db);
+    }
+    catch (cause) {
+        db.close();
+        throw cause;
+    }
+    let closed = false;
+    const check = () => { if (closed)
+        throw new SessionError('closed', 'Session backend is closed'); };
+    const source = Object.freeze({ id: `sqlite:${resolve(filename)}`, durability: 'persistent' });
+    const catalogRow = db.prepare('SELECT id, revision FROM session_catalog WHERE singleton = 1');
+    const catalogState = () => {
+        const state = catalogRow.get();
+        if (!state || !Number.isSafeInteger(state.revision) || state.revision < 0) {
+            throw new SessionError('corrupt_session', 'Invalid catalog state');
+        }
+        return state;
+    };
+    const storeId = catalogState().id;
+    const readInfo = db.prepare('SELECT id, revision, digest, title, metadata_revision, location FROM sessions INDEXED BY session_info WHERE id = ?');
+    const detail = (row) => {
+        if (!Number.isSafeInteger(row.revision) || row.revision < 0 || row.revision > sessionLimits.events
+            || !Number.isSafeInteger(row.metadata_revision) || row.metadata_revision < 0
+            || normalizeTitle(row.title) !== row.title || !/^[0-9a-f]{64}$/.test(row.digest)) {
+            throw new SessionError('corrupt_session', 'Malformed Session summary');
+        }
+        return { sessionId: row.id, revision: row.revision, digest: row.digest, title: row.title,
+            metadataRevision: row.metadata_revision, storeId, source, location: decodeLocation(row.location) };
+    };
+    const info = (id) => { identity(id); return detail(readInfo.get(id) ?? missing()); };
+    const readRow = db.prepare('SELECT id, revision, document, digest FROM sessions WHERE id = ?');
+    const readEvent = db.prepare('SELECT event, digest FROM session_events WHERE session_id = ? AND revision = ?');
+    const query = (sessionId, after, limit) => {
+        queryBounds(after, limit);
+        const saved = info(sessionId);
+        if (after > saved.revision)
+            throw new SessionError('invalid_query', 'Cursor exceeds the saved revision');
+        const records = historyRecords(after, saved.revision, limit, at => {
+            const row = readEvent.get(sessionId, at);
+            if (!row || Buffer.byteLength(row.event) > sessionLimits.eventBytes || hash(row.event) !== row.digest) {
+                throw new SessionError('corrupt_session', 'Missing or corrupt history projection; preserve the file');
+            }
+            const event = copyEvent(JSON.parse(row.event));
+            if (event.sessionId !== sessionId)
+                throw new SessionError('corrupt_session', 'History identity mismatch');
+            return { revision: at, event };
+        });
+        const end = records.at(-1)?.revision ?? after;
+        return { sessionId, revision: saved.revision, digest: saved.digest, source, records,
+            nextCursor: end < saved.revision ? end : null };
+    };
+    const listFirst = db.prepare('SELECT id, title, metadata_revision FROM sessions INDEXED BY session_info ORDER BY id COLLATE BINARY LIMIT ?');
+    const listNext = db.prepare('SELECT id, title, metadata_revision FROM sessions INDEXED BY session_info WHERE id > ? COLLATE BINARY ORDER BY id COLLATE BINARY LIMIT ?');
+    const bumpCatalog = () => db.prepare('UPDATE session_catalog SET revision = ? WHERE singleton = 1').run(increment(catalogState().revision));
+    const insert = db.prepare('INSERT INTO sessions VALUES (?, ?, ?, ?, NULL, 0, ?)');
+    const update = db.prepare('UPDATE sessions SET revision = ?, document = ?, digest = ? WHERE id = ?');
+    const insertEvent = db.prepare('INSERT INTO session_events VALUES (?, ?, ?, ?)');
+    const write = db.transaction((next, expected, location = null) => {
+        const row = readRow.get(next.sessionId);
+        transition(row ? decode(row) : null, next, expected);
+        if (row) {
+            update.run(revision(next), encode(next), digest(next), next.sessionId);
+            const text = JSON.stringify(next.events.at(-1));
+            insertEvent.run(next.sessionId, revision(next), text, hash(text));
+        }
+        else {
+            insert.run(next.sessionId, revision(next), encode(next), digest(next), location === null ? null : JSON.stringify(location));
+            bumpCatalog();
+        }
+    });
+    const catalog = {
+        async getSessionInfo(sessionId) { check(); return info(sessionId); },
+        async listSessions(options = {}) {
+            check();
+            return db.transaction(() => {
+                const limit = pageLimit(options);
+                const state = catalogState();
+                const cursor = readCursor(options, storeId, 'sessions');
+                currentCursor(cursor, state.revision);
+                if (cursor && !readInfo.get(cursor.after)) {
+                    throw new SessionError('invalid_cursor', 'Cursor does not identify a saved Session');
+                }
+                const rows = (cursor ? listNext.all(cursor.after, limit + 1) : listFirst.all(limit + 1));
+                const selected = rows.slice(0, limit);
+                const items = selected.map(row => {
+                    identity(row.id);
+                    metadataRevision(row.metadata_revision);
+                    if (normalizeTitle(row.title) !== row.title)
+                        throw new SessionError('corrupt_session', 'Invalid stored title');
+                    return { sessionId: row.id, title: row.title, metadataRevision: row.metadata_revision };
+                });
+                return { storeId, catalogRevision: state.revision, items,
+                    nextCursor: rows.length > limit ? nextCursor(storeId, 'sessions', limit, state.revision, items.at(-1).sessionId) : null };
+            })();
+        },
+        async renameSession(sessionId, title, expected) {
+            check();
+            identity(sessionId);
+            const nextTitle = normalizeTitle(title);
+            metadataRevision(expected);
+            return db.transaction(() => {
+                const current = info(sessionId);
+                if (current.metadataRevision !== expected)
+                    throw new SessionError('revision_conflict', 'Metadata revision conflict; read current title');
+                if (current.title !== nextTitle) {
+                    db.prepare('UPDATE sessions SET title = ?, metadata_revision = ? WHERE id = ?')
+                        .run(nextTitle, increment(expected), sessionId);
+                    bumpCatalog();
+                }
+                return info(sessionId);
+            }).immediate();
+        },
+        async readHistory(sessionId, options = {}) {
+            check();
+            identity(sessionId);
+            return db.transaction(() => {
+                const limit = pageLimit(options);
+                const cursor = readCursor(options, storeId, 'history', sessionId);
+                const saved = info(sessionId);
+                currentCursor(cursor, saved.revision);
+                const page = query(sessionId, cursor ? cursor.after : 0, limit);
+                return { ...page, storeId, nextCursor: page.nextCursor === null ? null
+                        : nextCursor(storeId, 'history', limit, saved.revision, page.nextCursor, sessionId) };
+            })();
+        },
+    };
+    return {
+        source, catalog,
+        async query(sessionId, options) { check(); return db.transaction(() => query(sessionId, options.after, options.limit))(); },
+        async read(sessionId) {
+            check();
+            identity(sessionId);
+            const row = readRow.get(sessionId);
+            return row ? decode(row) : null;
+        },
+        async write(document, expectedRevision) {
+            check();
+            write.immediate(inspectDocument(document).document, expectedRevision);
+        },
+        async createWithLocation(document, location) {
+            check();
+            const selected = copyLocation(location);
+            write.immediate(inspectDocument(document).document, null, selected);
+        },
+        async close() { if (!closed) {
+            db.close();
+            closed = true;
+        } },
+    };
+}