dsh-plugin-sessiongraph-sessions 0.0.0-stage → 0.1.0

package/lib/parse.js

@@ -0,0 +1,445 @@
+/**
+ * Read one harness session log into the normalized shape the indexer writes.
+ *
+ * The log is a zstd-compressed JSONL file whose first line is a flat session header and whose later
+ * lines are events. It is NOT one zstd stream: the harness appends one complete zstd frame per write,
+ * so a real log is thousands of concatenated frames. `zstdDecompressSync` stops at the first frame's
+ * end, which is why {@link decompressSessionLog} walks the frames itself.
+ *
+ * What is indexed is the readable conversation, not the transcript feed: a human's messages, the
+ * model's visible text (never its reasoning), tool invocations (name and arguments, never results),
+ * and the session's final title. Injected context — runtime/skill/time blocks, team and agent
+ * messages, plugin notifications — arrives as `user/message` events too, so the `source.kind` check
+ * is what keeps them out of the index; on a real machine those injections outnumber real human
+ * messages by more than an order of magnitude.
+ *
+ * Parsing is tolerant per line: a truncated or corrupt line is skipped rather than failing the whole
+ * session, because an interrupted append must cost one event, not the conversation.
+ * @module dsh-plugin-sessiongraph-sessions/parse
+ */
+import { zstdDecompressSync } from 'node:zlib';
+/** zstd frame magic in numeric form, as read by `Buffer.readUInt32LE`. */
+const ZSTD_FRAME_MAGIC = 0xfd2fb528;
+/** The same magic as bytes, for the fallback scanner. */
+const ZSTD_MAGIC_BYTES = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+/** Mask and value identifying a zstd skippable frame (0x184D2A50 … 0x184D2A5F). */
+const ZSTD_SKIPPABLE_MASK = 0xfffffff0;
+const ZSTD_SKIPPABLE_MAGIC = 0x184d2a50;
+/** Frame-content-size field widths in bytes, indexed by the 2-bit flag minus one. */
+const CONTENT_SIZE_BYTES = [2, 4, 8];
+/** Dictionary-id field widths in bytes, indexed by the 2-bit flag. */
+const DICTIONARY_ID_BYTES = [0, 1, 2, 4];
+/** Byte widths of a zstd block header and of the checksum trailer. */
+const BLOCK_HEADER_BYTES = 3;
+const CHECKSUM_BYTES = 4;
+/**
+ * Decompress a session log, one zstd frame at a time.
+ *
+ * Node's `zstdDecompressSync` decodes the first frame of its input and stops, so a log written by
+ * repeated appends must be split into frames first. The frame structure is parsed exactly (RFC 8878
+ * header and block headers), which is why a magic-byte sequence inside a compressed block cannot
+ * split a frame incorrectly; the magic scan remains as a fallback for a frame layout this parser
+ * cannot describe.
+ * @param buffer - the raw log file contents.
+ * @returns the concatenated decompressed bytes of every frame.
+ */
+export function decompressSessionLog(buffer) {
+    if (buffer.length >= 4 && buffer.readUInt32LE(0) === ZSTD_FRAME_MAGIC) {
+        try {
+            return decompressByWalkingFrames(buffer);
+        }
+        catch {
+            // Fall through: the magic scan understands a few layouts the walker refuses, and a readable
+            // index is worth more than a stricter parser.
+        }
+    }
+    return decompressByMagic(buffer);
+}
+/**
+ * Walk every zstd frame in `buffer` and decompress each one.
+ * @param buffer - the raw log file contents, starting at a frame boundary.
+ * @returns the concatenated decompressed bytes.
+ */
+function decompressByWalkingFrames(buffer) {
+    const parts = [];
+    let at = 0;
+    while (at < buffer.length) {
+        const magic = buffer.readUInt32LE(at);
+        const end = frameEnd(buffer, at);
+        if (end <= at)
+            throw new Error(`zstd frame at byte ${at} does not advance`);
+        if ((magic & ZSTD_SKIPPABLE_MASK) !== ZSTD_SKIPPABLE_MAGIC)
+            parts.push(zstdDecompressSync(buffer.subarray(at, end)));
+        at = end;
+    }
+    return Buffer.concat(parts);
+}
+/**
+ * Decompress by scanning for frame magics and decoding each slice.
+ * @param buffer - the raw log file contents.
+ * @returns the concatenated decompressed bytes.
+ */
+function decompressByMagic(buffer) {
+    const offsets = [];
+    let at = buffer.indexOf(ZSTD_MAGIC_BYTES);
+    while (at !== -1) {
+        offsets.push(at);
+        at = buffer.indexOf(ZSTD_MAGIC_BYTES, at + ZSTD_MAGIC_BYTES.length);
+    }
+    if (offsets.length === 0)
+        throw new Error('session log is not a zstd stream');
+    const parts = [];
+    for (let index = 0; index < offsets.length; index += 1) {
+        const start = offsets[index];
+        const end = index + 1 < offsets.length ? offsets[index + 1] : buffer.length;
+        parts.push(zstdDecompressSync(buffer.subarray(start, end)));
+    }
+    return Buffer.concat(parts);
+}
+/**
+ * Compute where the zstd frame beginning at `start` ends, from its header and block headers alone.
+ * @param buffer - the raw log file contents.
+ * @param start - byte offset of the frame magic.
+ * @returns the exclusive end offset of the frame.
+ */
+function frameEnd(buffer, start) {
+    const magic = buffer.readUInt32LE(start);
+    if ((magic & ZSTD_SKIPPABLE_MASK) === ZSTD_SKIPPABLE_MAGIC) {
+        return start + 8 + buffer.readUInt32LE(start + 4);
+    }
+    if (magic !== ZSTD_FRAME_MAGIC)
+        throw new Error(`unexpected zstd magic at byte ${start}`);
+    let at = start + 4;
+    const descriptor = readUInt8(buffer, at);
+    at += 1;
+    const contentSizeFlag = descriptor >>> 6;
+    const singleSegment = ((descriptor >>> 5) & 1) === 1;
+    const checksum = ((descriptor >>> 2) & 1) === 1;
+    const dictionaryFlag = descriptor & 0x03;
+    if (!singleSegment)
+        at += 1;
+    at += DICTIONARY_ID_BYTES[dictionaryFlag];
+    at += contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : CONTENT_SIZE_BYTES[contentSizeFlag - 1];
+    for (;;) {
+        const header = readUIntLE(buffer, at, BLOCK_HEADER_BYTES);
+        at += BLOCK_HEADER_BYTES;
+        const lastBlock = (header & 0x01) === 1;
+        const blockType = (header >>> 1) & 0x03;
+        const blockSize = header >>> 3;
+        if (blockType === 0 || blockType === 2)
+            at += blockSize;
+        else if (blockType === 1)
+            at += 1;
+        else
+            throw new Error('reserved zstd block type');
+        if (lastBlock)
+            break;
+    }
+    if (checksum)
+        at += CHECKSUM_BYTES;
+    if (at > buffer.length)
+        throw new Error('truncated zstd frame');
+    return at;
+}
+/**
+ * Parse one session log.
+ * @param buffer - the raw log file contents.
+ * @param fallbackId - id to use when the header is missing or has none (the session directory name).
+ * @param limits - bounds applied to stored entry text.
+ * @returns the normalized session.
+ */
+export function parseSessionLog(buffer, fallbackId, limits) {
+    return parseSessionLines(decompressSessionLog(buffer).toString('utf8').split('\n'), fallbackId, limits);
+}
+/**
+ * Parse an already-split JSONL log, keeping the harness's first-line header convention.
+ * @param lines - the decompressed log split on newline characters.
+ * @param fallbackId - id to use when the header is missing or has none.
+ * @param limits - bounds applied to stored entry text.
+ * @returns the normalized session.
+ */
+export function parseSessionLines(lines, fallbackId, limits) {
+    const firstLine = firstNonEmptyLine(lines);
+    let header;
+    let start = 0;
+    if (firstLine !== undefined) {
+        const record = parseRecord(lines[firstLine]);
+        if (record?.type === 'session') {
+            header = record;
+            start = firstLine + 1;
+        }
+        else {
+            start = firstLine;
+        }
+    }
+    const records = [];
+    for (let index = start; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        records.push(line === '' ? undefined : parseRecord(line));
+    }
+    return normalizeSession(header, records, fallbackId, limits);
+}
+/**
+ * Parse a session the host already holds in memory.
+ *
+ * The live view carries the header and the raw events as two values, which is the same information a
+ * log's first line and remaining lines carry. Both paths normalize through {@link normalizeSession},
+ * so a live session and its later on-disk copy cannot disagree about what is searchable.
+ * @param header - the session header object, as the host reports it.
+ * @param events - raw event objects, shaped like the JSONL lines that follow the header.
+ * @param fallbackId - id to use when the header has none.
+ * @param limits - bounds applied to stored entry text.
+ * @returns the normalized session.
+ */
+export function parseSessionEvents(header, events, fallbackId, limits) {
+    return normalizeSession(asRecord(header), events.map(event => asRecord(event)), fallbackId, limits);
+}
+/**
+ * Normalize a session header and its event stream into the shape the index writes.
+ * @param header - the parsed session header, or undefined when the log carries none.
+ * @param records - parsed events, where `undefined` stands for a line that failed to parse and is
+ *   skipped without failing the session.
+ * @param fallbackId - id to use when the header has none.
+ * @param limits - bounds applied to stored entry text.
+ * @returns the normalized session.
+ */
+function normalizeSession(header, records, fallbackId, limits) {
+    const id = stringField(header, 'id') ?? fallbackId;
+    let createdAt = numberField(header, 'createdAt') ?? 0;
+    const parentSession = stringField(header, 'parentSession');
+    const origin = stringField(header, 'origin');
+    const agentPreset = stringField(header, 'agentPreset');
+    const headerCwd = stringField(header, 'cwd') ?? '';
+    const entries = [];
+    let title;
+    let titleSeq = 0;
+    let titleTime = 0;
+    let firstEventTime;
+    let lastAt = createdAt;
+    let turns = 0;
+    for (const record of records) {
+        if (record === undefined)
+            continue;
+        const seq = numberField(record, 'seq') ?? 0;
+        const time = numberField(record, 'time');
+        if (time !== undefined) {
+            firstEventTime ??= time;
+            if (time > lastAt)
+                lastAt = time;
+        }
+        const eventTime = time ?? lastAt;
+        const data = asRecord(record.data);
+        switch (record.type) {
+            case 'turn/start':
+                turns += 1;
+                break;
+            case 'session/title': {
+                const next = stringField(data, 'title');
+                if (next !== undefined && next.trim() !== '') {
+                    title = next;
+                    titleSeq = seq;
+                    titleTime = eventTime;
+                }
+                break;
+            }
+            case 'user/message': {
+                // Injected context travels as user messages too; only a human's own input is indexed.
+                if (stringField(asRecord(data?.source), 'kind') !== 'user')
+                    break;
+                const text = textBlocks(data?.content);
+                if (text !== '')
+                    pushEntry(entries, 'user', text, seq, eventTime, numberField(data, 'turn'), limits.maxEntryChars);
+                break;
+            }
+            case 'assistant/message': {
+                // One entry per visible text block: a reasoning block and a tool-call block are not prose.
+                const message = asRecord(data?.message);
+                const blocks = message?.content;
+                if (!Array.isArray(blocks))
+                    break;
+                for (const block of blocks) {
+                    const record = asRecord(block);
+                    if (stringField(record, 'type') !== 'text')
+                        continue;
+                    const text = stringField(record, 'text');
+                    if (text === undefined || text.trim() === '')
+                        continue;
+                    pushEntry(entries, 'assistant', text, seq, eventTime, numberField(data, 'turn'), limits.maxEntryChars);
+                }
+                break;
+            }
+            case 'tool/call': {
+                const name = stringField(data, 'name') ?? '';
+                const args = argumentText(data?.arguments);
+                const text = args === '' ? name : `${name} ${args}`;
+                if (text.trim() === '')
+                    break;
+                pushEntry(entries, 'tool', text, seq, eventTime, numberField(data, 'turn'), limits.toolCallChars);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    if (createdAt === 0 && firstEventTime !== undefined)
+        createdAt = firstEventTime;
+    if (lastAt < createdAt)
+        lastAt = createdAt;
+    if (title !== undefined) {
+        const clipped = clipText(title, limits.maxEntryChars);
+        entries.push({ seq: titleSeq, time: titleTime, turn: undefined, kind: 'title', text: clipped.text, clipped: clipped.clipped });
+    }
+    return {
+        id,
+        cwd: headerCwd,
+        createdAt,
+        lastAt,
+        title,
+        parentSession,
+        origin,
+        agentPreset,
+        turns,
+        entries,
+    };
+}
+/**
+ * Append one bounded entry, unless its text is blank.
+ * @param entries - destination list.
+ * @param kind - entry kind.
+ * @param text - raw entry text.
+ * @param seq - event sequence number.
+ * @param time - event timestamp.
+ * @param turn - turn number, when known.
+ * @param maxChars - longest text stored whole.
+ */
+function pushEntry(entries, kind, text, seq, time, turn, maxChars) {
+    if (text.trim() === '')
+        return;
+    const clipped = clipText(text, maxChars);
+    entries.push({ seq, time, turn, kind, text: clipped.text, clipped: clipped.clipped });
+}
+/**
+ * Bound one text to the configured character cap.
+ * @param text - raw text.
+ * @param maxChars - longest text kept whole.
+ * @returns the stored text and whether it was clipped.
+ */
+function clipText(text, maxChars) {
+    if (text.length <= maxChars)
+        return { text, clipped: false };
+    return { text: text.slice(0, maxChars), clipped: true };
+}
+/**
+ * Concatenate the text blocks of a message's content array.
+ * @param content - the event's `content` value.
+ * @returns the joined text, or an empty string when there is none.
+ */
+function textBlocks(content) {
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        const record = asRecord(block);
+        if (stringField(record, 'type') !== 'text')
+            continue;
+        const text = stringField(record, 'text');
+        if (text !== undefined && text !== '')
+            parts.push(text);
+    }
+    return parts.join('\n');
+}
+/**
+ * Render a tool call's arguments for indexing.
+ * @param value - the event's `arguments` value, normally a JSON string.
+ * @returns the arguments text, or an empty string when absent.
+ */
+function argumentText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined || value === null)
+        return '';
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Index of the first non-blank line.
+ * @param lines - split log lines.
+ * @returns the index, or undefined for an empty log.
+ */
+function firstNonEmptyLine(lines) {
+    for (let index = 0; index < lines.length; index += 1) {
+        if (lines[index].trim() !== '')
+            return index;
+    }
+    return undefined;
+}
+/**
+ * Parse one JSONL line into an object, tolerating a corrupt line.
+ * @param line - one trimmed, non-empty line.
+ * @returns the record, or undefined when the line is not a JSON object.
+ */
+function parseRecord(line) {
+    try {
+        const value = JSON.parse(line);
+        return asRecord(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Narrow a value to a plain object.
+ * @param value - candidate.
+ * @returns the object, or undefined.
+ */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * Read a string field from a record.
+ * @param record - the record, possibly absent.
+ * @param key - field name.
+ * @returns the string, or undefined when the field is absent or not a string.
+ */
+function stringField(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Read a finite number field from a record.
+ * @param record - the record, possibly absent.
+ * @param key - field name.
+ * @returns the number, or undefined when the field is absent or not a finite number.
+ */
+function numberField(record, key) {
+    const value = record?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Read one byte, failing with a readable message at a truncated frame.
+ * @param buffer - the raw log file contents.
+ * @param at - byte offset.
+ * @returns the byte value.
+ */
+function readUInt8(buffer, at) {
+    if (at + 1 > buffer.length)
+        throw new Error('truncated zstd frame header');
+    return buffer.readUInt8(at);
+}
+/**
+ * Read an unsigned little-endian integer of 1–6 bytes.
+ * @param buffer - the raw log file contents.
+ * @param at - byte offset.
+ * @param width - field width in bytes.
+ * @returns the value.
+ */
+function readUIntLE(buffer, at, width) {
+    if (at + width > buffer.length)
+        throw new Error('truncated zstd frame body');
+    return buffer.readUIntLE(at, width);
+}
+//# sourceMappingURL=parse.js.map

package/lib/scan.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Discover the harness session logs under `sessionsRoot`.
+ *
+ * The harness lays sessions out as `<sessionsRoot>/<escaped-cwd>/<session-dir>/session.v<N>.jsonl.zstd`,
+ * so the walk is exactly two directory levels deep followed by a filename match — it never recurses
+ * into unrelated files (a `.DS_Store` sits at the root of a real `~/.dsh/sessions`) and never reads
+ * anything it will not index.
+ *
+ * Both `v3` and `v4` logs are indexed: the harness has shipped both, they carry the same event shape,
+ * and a machine that upgraded keeps its older `v3` files. Within one session directory the highest
+ * version wins, so a half-finished v3 → v4 rewrite contributes one session rather than two.
+ * @module dsh-plugin-sessiongraph-sessions/scan
+ */
+/** A session log file the indexer can read. */
+export interface SessionFile {
+    /** Absolute path of the directory holding the log (the harness session directory). */
+    readonly sessionDir: string;
+    /** Absolute path of the log file itself. */
+    readonly filePath: string;
+    /** The workspace directory name as the harness escaped it; a fallback when the header has no `cwd`. */
+    readonly workspaceDir: string;
+    /** Modification time in epoch milliseconds, truncated to a whole millisecond for integer storage. */
+    readonly mtime: number;
+    /** File size in bytes, the other half of the incremental change key. */
+    readonly size: number;
+}
+/**
+ * List every session log under `sessionsRoot`, one entry per session directory.
+ * @param sessionsRoot - absolute path of the harness session store.
+ * @returns the logs found, ordered by workspace then session directory so runs are reproducible.
+ */
+export declare function scanSessions(sessionsRoot: string): Promise<SessionFile[]>;
+//# sourceMappingURL=scan.d.ts.map

package/lib/scan.js

@@ -0,0 +1,121 @@
+/**
+ * Discover the harness session logs under `sessionsRoot`.
+ *
+ * The harness lays sessions out as `<sessionsRoot>/<escaped-cwd>/<session-dir>/session.v<N>.jsonl.zstd`,
+ * so the walk is exactly two directory levels deep followed by a filename match — it never recurses
+ * into unrelated files (a `.DS_Store` sits at the root of a real `~/.dsh/sessions`) and never reads
+ * anything it will not index.
+ *
+ * Both `v3` and `v4` logs are indexed: the harness has shipped both, they carry the same event shape,
+ * and a machine that upgraded keeps its older `v3` files. Within one session directory the highest
+ * version wins, so a half-finished v3 → v4 rewrite contributes one session rather than two.
+ * @module dsh-plugin-sessiongraph-sessions/scan
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** `session.v4.jsonl.zstd`, `session.v3.jsonl.zstd`, … — the version is captured for the pick below. */
+const SESSION_LOG = /^session\.v(\d+)\.jsonl\.zstd$/;
+/**
+ * List every session log under `sessionsRoot`, one entry per session directory.
+ * @param sessionsRoot - absolute path of the harness session store.
+ * @returns the logs found, ordered by workspace then session directory so runs are reproducible.
+ */
+export async function scanSessions(sessionsRoot) {
+    const found = [];
+    let workspaces;
+    try {
+        workspaces = await readdir(sessionsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        // A machine that has never run a session has no store yet; that is an empty index, not a failure.
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+    for (const workspace of workspaces) {
+        if (!workspace.isDirectory())
+            continue;
+        const workspacePath = join(sessionsRoot, workspace.name);
+        const sessions = await listDirectories(workspacePath);
+        for (const session of sessions) {
+            const sessionDir = join(workspacePath, session);
+            const log = await pickLogFile(sessionDir);
+            if (log === undefined)
+                continue;
+            try {
+                const stats = await stat(log.path);
+                found.push({
+                    sessionDir,
+                    filePath: log.path,
+                    workspaceDir: workspace.name,
+                    mtime: Math.trunc(stats.mtimeMs),
+                    size: stats.size,
+                });
+            }
+            catch (error) {
+                // Vanished between the listing and the stat: the next run would drop it anyway.
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+    }
+    found.sort((left, right) => left.workspaceDir.localeCompare(right.workspaceDir) || left.sessionDir.localeCompare(right.sessionDir));
+    return found;
+}
+/**
+ * List the session directories inside one workspace directory.
+ * @param workspacePath - absolute path of one escaped workspace directory.
+ * @returns directory names, or none when the directory vanished mid-scan.
+ */
+async function listDirectories(workspacePath) {
+    try {
+        const entries = await readdir(workspacePath, { withFileTypes: true });
+        return entries.filter(entry => entry.isDirectory()).map(entry => entry.name);
+    }
+    catch (error) {
+        // Only a directory that vanished mid-scan is ignorable. Failing to read one for any other reason
+        // must abort the run: a silently short scan would look like "sources disappeared" and delete the
+        // rows of every session it could not list.
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+}
+/**
+ * Pick the newest-version log inside one session directory.
+ * @param sessionDir - absolute path of the session directory.
+ * @returns the chosen log path with its version, or undefined when the directory holds none.
+ */
+async function pickLogFile(sessionDir) {
+    let entries;
+    try {
+        entries = await readdir(sessionDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    let chosen;
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const match = SESSION_LOG.exec(entry.name);
+        if (match === null)
+            continue;
+        const version = Number.parseInt(match[1] ?? '0', 10);
+        if (chosen === undefined || version > chosen.version) {
+            chosen = { path: join(sessionDir, entry.name), version };
+        }
+    }
+    return chosen;
+}
+/**
+ * Whether an error is a missing path rather than a real I/O failure.
+ * @param error - the caught value.
+ * @returns true for ENOENT.
+ */
+function isMissing(error) {
+    return typeof error === 'object' && error !== null && error.code === 'ENOENT';
+}
+//# sourceMappingURL=scan.js.map

package/lib/write.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Write the session index with `node:sqlite`.
+ *
+ * Two modes, deliberately different on disk:
+ *
+ * - **Rebuild** (`force`) writes a complete index to `index.db.tmp` and renames it over `index.db`
+ *   only after the transaction commits, so a reader never observes a half-built index and a run that
+ *   dies leaves the previous one untouched. When the run is also scoped (a workspace or single
+ *   session was requested), the previous index is attached and copied in first, because a scoped
+ *   rebuild must not delete the sessions it was not asked about.
+ * - **Incremental** opens the live index and rewrites only the sessions whose source changed, inside
+ *   one transaction.
+ *
+ * `entry_fts.rowid` is aligned with `entry.id`: every written entry row is followed by exactly one
+ * FTS row carrying the tokenizer's output. Deletion therefore goes FTS-first — the entry rows are
+ * what names the rowids, so dropping them first would strand the FTS rows.
+ * @module dsh-plugin-sessiongraph-sessions/write
+ */
+import type { ParsedSession } from './parse.ts';
+/** One parsed session and the source it is recorded as coming from. */
+export interface IndexedSession {
+    readonly session: ParsedSession;
+    /**
+     * Absolute path of the log it came from, or the synthetic `live://<id>` marker for a session the
+     * host still holds in memory and that has no stable file version yet.
+     */
+    readonly sourcePath: string;
+    /** Source modification time, or 0 for a live session (there is no version to compare). */
+    readonly mtime: number;
+    /** Source size in bytes, or 0 for a live session. */
+    readonly size: number;
+}
+/**
+ * Sidecar summary an indexer leaves beside `index.db`.
+ *
+ * Prompt assembly must never open SQLite, so the same post-run totals the report carries are also
+ * persisted as a small JSON file the tool can read synchronously. It is a derived copy: the `meta`
+ * table stays authoritative for the store, and a missing sidecar only degrades the prompt line.
+ */
+export declare const STATUS_RELATIVE_PATH = "status.json";
+/** What a previous index already holds for one source file. */
+export interface ExistingSession {
+    readonly id: string;
+    readonly workspace: string;
+    /** Absolute path of the session log this row was built from. */
+    readonly sourcePath: string;
+    readonly mtime: number;
+    readonly size: number;
+}
+/** One index write, already scoped by the caller. */
+export interface IndexWritePlan {
+    /** Absolute path of `index.db`. */
+    readonly indexPath: string;
+    /** Rebuild from scratch in `index.db.tmp` and rename it into place. */
+    readonly force: boolean;
+    /** With `force`: seed the rebuild from the previous index so out-of-scope rows survive. */
+    readonly preserveExisting: boolean;
+    /** Sessions to (re)write. */
+    readonly sessions: readonly IndexedSession[];
+    /** Session ids whose source file disappeared. */
+    readonly removed: readonly string[];
+    /** Sessions the scan found, for `meta.discovered`. */
+    readonly discovered: number;
+    /** Sessions that failed to parse, for `meta.failed`. */
+    readonly failed: number;
+    /** Epoch milliseconds recorded as the run's completion time in `meta` and the sidecar. */
+    readonly indexedAt: number;
+}
+/** What one index write produced. */
+export interface IndexWriteResult {
+    /** Searchable entries in the index after the write. */
+    readonly entries: number;
+    /** Sessions in the index after the write. */
+    readonly sessions: number;
+    /** Distinct workspaces in the index after the write. */
+    readonly workspaces: number;
+    /** Bytes the index file occupies after the write. */
+    readonly bytes: number;
+}
+/**
+ * Read the state a previous index recorded, when it is usable.
+ *
+ * An index written by another schema version is refused rather than reused: silently mixing two
+ * shapes would hand the store rows it cannot interpret.
+ * @param indexPath - absolute path of `index.db`.
+ * @returns rows keyed by source path, or undefined when there is no usable index.
+ */
+export declare function readIndexState(indexPath: string): ReadonlyMap<string, ExistingSession> | undefined;
+/**
+ * Write one index update.
+ * @param plan - sessions to write, sessions to drop, and how to place the result.
+ * @returns what the index holds after the write.
+ */
+export declare function writeIndex(plan: IndexWritePlan): IndexWriteResult;
+//# sourceMappingURL=write.d.ts.map