@1agents/session-reader 0.1.1

package/dist/src/store/edges.js

@@ -0,0 +1,153 @@
+import { analyzableCommand } from '../writes.js';
+import { findSessionRow } from './read.js';
+import { EDGE_VERSION } from './schema.js';
+/** Subcommands that address another session, and what reading one means. */
+const VERB_RELATION = {
+    overview: 'references',
+    turns: 'references',
+    turn: 'references',
+    files: 'references',
+    commands: 'references',
+    errors: 'references',
+    jobs: 'references',
+    digest: 'references',
+    graph: 'references',
+    related: 'references',
+    handoff: 'handoff_from',
+};
+/**
+ * `1session <verb> <target>` in any of the shapes it actually gets typed:
+ * the bare alias, `node …/1session.js`, `tsx bin/1session.ts`. Flags between
+ * verb and target are skipped; the target must look like a session id.
+ */
+const INVOCATION = /(?:^|[\s;&|(])(?:[^\s;&|()]*\b1session(?:\.[jt]s)?)\s+([a-z-]+)((?:\s+--?[\w-]+(?:[= ][^\s;&|()]+)?)*)\s+([A-Za-z0-9][\w-]{5,})/g;
+/** Reads the session-reader invocations out of one tool call. */
+export function invocationsOf(event) {
+    // Here-doc payloads are stripped first: this module's own development
+    // sessions are full of `cat > x.ts <<'EOF'` blocks quoting example
+    // commands, and counting those would invent edges that never happened.
+    const command = analyzableCommand(event);
+    if (!command)
+        return [];
+    const found = [];
+    INVOCATION.lastIndex = 0;
+    for (const match of command.matchAll(INVOCATION)) {
+        const verb = match[1];
+        const relation = VERB_RELATION[verb];
+        if (!relation)
+            continue;
+        found.push({
+            relation,
+            target: match[3],
+            eventIndex: event.index,
+            operation: verb,
+            command: command.slice(match.index, match.index + 160).trim(),
+            ...(event.timestamp ? { timestamp: event.timestamp } : {}),
+        });
+    }
+    return found;
+}
+function upsertEdge(db, from, to, relation, candidate, provenance, extractor) {
+    db.prepare(`INSERT INTO session_edges (from_session, to_session, relation, first_seen_at, last_seen_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT (from_session, to_session, relation) DO UPDATE SET
+       first_seen_at = MIN(COALESCE(first_seen_at, excluded.first_seen_at), COALESCE(excluded.first_seen_at, first_seen_at)),
+       last_seen_at  = MAX(COALESCE(last_seen_at,  excluded.last_seen_at),  COALESCE(excluded.last_seen_at,  last_seen_at))`).run(from, to, relation, candidate.timestamp ?? null, candidate.timestamp ?? null);
+    const edge = db
+        .prepare('SELECT id FROM session_edges WHERE from_session = ? AND to_session = ? AND relation = ?')
+        .get(from, to, relation);
+    db.prepare(`INSERT OR IGNORE INTO edge_evidence
+       (edge_id, source_session, event_index, operation, command, ts, provenance, extractor)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(edge.id, from, candidate.eventIndex, candidate.operation, candidate.command, candidate.timestamp ?? null, provenance, extractor);
+    // Counted, never incremented: a re-index must not inflate the tally.
+    db.prepare('UPDATE session_edges SET evidence_count = (SELECT count(*) FROM edge_evidence WHERE edge_id = ?) WHERE id = ?').run(edge.id, edge.id);
+}
+/**
+ * Derives L3 for one session from its stored events. Targets that do not
+ * resolve to an indexed session are dropped — a dangling edge is worse than
+ * no edge.
+ */
+export function deriveEdges(db, id, session) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const stale = db
+            .prepare('SELECT edge_id FROM edge_evidence WHERE source_session = ?')
+            .all(id);
+        db.prepare('DELETE FROM edge_evidence WHERE source_session = ?').run(id);
+        let added = 0;
+        for (const event of session.turns) {
+            for (const candidate of invocationsOf(event)) {
+                const row = findSessionRow(db, candidate.target);
+                if (!row || row.id === id)
+                    continue;
+                upsertEdge(db, id, row.id, candidate.relation, candidate, 'derived', 'tool:Bash+1session');
+                added++;
+            }
+        }
+        // Edges whose last evidence just disappeared must go with it.
+        for (const { edge_id } of stale) {
+            db.prepare('DELETE FROM session_edges WHERE id = ? AND NOT EXISTS (SELECT 1 FROM edge_evidence WHERE edge_id = ?)').run(edge_id, edge_id);
+        }
+        db.prepare('UPDATE sessions SET edge_version = ? WHERE id = ?').run(EDGE_VERSION, id);
+        db.exec('COMMIT');
+        return added;
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}
+/**
+ * Records an edge at the moment it happens, when the caller session is known.
+ * Injected by a hook or the ACP context as `SESSION_READER_CALLER_SESSION`;
+ * absent everywhere else, in which case nothing is written.
+ */
+export function captureRuntimeEdge(db, verb, target) {
+    const caller = process.env.SESSION_READER_CALLER_SESSION?.trim();
+    const relation = VERB_RELATION[verb];
+    if (!caller || !relation)
+        return;
+    const from = findSessionRow(db, caller);
+    const to = findSessionRow(db, target);
+    if (!from || !to || from.id === to.id)
+        return;
+    const now = new Date().toISOString();
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        upsertEdge(db, from.id, to.id, relation, { relation, target, eventIndex: -1, operation: verb, command: `1session ${verb} ${target}`, timestamp: now }, 'observed', 'runtime:caller-env');
+        db.exec('COMMIT');
+    }
+    catch {
+        db.exec('ROLLBACK');
+    }
+}
+export function edgesOf(db, id) {
+    const rows = db
+        .prepare(`SELECT from_session, to_session, relation, evidence_count, first_seen_at, last_seen_at
+       FROM session_edges WHERE from_session = ? OR to_session = ?
+       ORDER BY evidence_count DESC`)
+        .all(id, id);
+    return rows.map((row) => ({
+        from: row.from_session,
+        to: row.to_session,
+        relation: row.relation,
+        evidenceCount: row.evidence_count,
+        ...(row.first_seen_at ? { firstSeenAt: row.first_seen_at } : {}),
+        ...(row.last_seen_at ? { lastSeenAt: row.last_seen_at } : {}),
+        direction: row.from_session === id ? 'out' : 'in',
+    }));
+}
+export function edgeEvidence(db, from, to, relation) {
+    const rows = db
+        .prepare(`SELECT e.event_index, e.operation, e.ts, e.extractor
+       FROM edge_evidence e JOIN session_edges s ON s.id = e.edge_id
+       WHERE s.from_session = ? AND s.to_session = ? AND s.relation = ?
+       ORDER BY e.event_index`)
+        .all(from, to, relation);
+    return rows.map((row) => ({
+        eventIndex: row.event_index,
+        operation: row.operation,
+        ...(row.ts ? { ts: row.ts } : {}),
+        extractor: row.extractor,
+    }));
+}

package/dist/src/store/facts.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { NormalizedSession } from '../types.js';
+/**
+ * Materializes L2. The rules themselves stay in `ledger.ts` — this only moves
+ * their output into rows, so a stored fact and a freshly computed one can
+ * never disagree.
+ */
+export declare function deriveFacts(db: DatabaseSync, id: string, session: NormalizedSession): void;

package/dist/src/store/facts.js

@@ -0,0 +1,39 @@
+import { commandLedger, fileLedger, jobLedger } from '../ledger.js';
+import { EXTRACTOR_VERSION } from './schema.js';
+/**
+ * Materializes L2. The rules themselves stay in `ledger.ts` — this only moves
+ * their output into rows, so a stored fact and a freshly computed one can
+ * never disagree.
+ */
+export function deriveFacts(db, id, session) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const table of ['file_ops', 'commands', 'jobs']) {
+            db.prepare(`DELETE FROM ${table} WHERE session_id = ?`).run(id);
+        }
+        const file = db.prepare(`INSERT INTO file_ops (session_id, path, host, operation, turn, event_index, ts,
+                             provenance, extractor, file_group)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const record of fileLedger(session)) {
+            file.run(id, record.path, record.host ?? null, record.operation, record.turn, record.eventIndex, record.timestamp ?? null, record.provenance, record.extractor, record.group);
+        }
+        const command = db.prepare(`INSERT INTO commands (session_id, event_index, turn, command, host, cwd, exit_code,
+                             duration_ms, pid, stderr, ts, provenance, extractor)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const record of commandLedger(session)) {
+            command.run(id, record.eventIndex, record.turn, record.command, record.host ?? null, record.cwd ?? null, record.exitCode ?? null, record.durationMs ?? null, record.pid ?? null, record.stderr ?? null, record.timestamp ?? null, record.provenance, record.extractor);
+        }
+        const job = db.prepare(`INSERT INTO jobs (session_id, job_id, command, pid, host, log, started_at,
+                         discovered_from, status, provenance, extractor, evidence_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const record of jobLedger(session)) {
+            job.run(id, record.id, record.command ?? null, record.pid ?? null, record.host ?? null, record.log ?? null, record.startedAt ?? null, record.discoveredFrom ?? null, record.status, record.provenance, record.extractor, JSON.stringify(record.evidence));
+        }
+        db.prepare('UPDATE sessions SET extractor_version = ? WHERE id = ?').run(EXTRACTOR_VERSION, id);
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}

package/dist/src/store/indexer.d.ts

@@ -0,0 +1,40 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ProviderAdapter, SessionCandidate } from '../parsers/provider.js';
+import type { NormalizedSession } from '../types.js';
+export type IndexAction = 'indexed' | 'reused' | 'facts-rederived' | 'edges-rederived';
+export interface IndexResult {
+    id: string;
+    action: IndexAction;
+    session: NormalizedSession;
+}
+export interface IndexHandle {
+    adapter: ProviderAdapter;
+    candidate: SessionCandidate;
+}
+export interface IndexOptions {
+    /** Re-read the source even when the fingerprint says nothing changed. */
+    force?: boolean;
+    /** Skip L3 — a bulk backfill derives edges once at the end instead. */
+    edges?: boolean;
+}
+export interface RefreshResult {
+    id: string;
+    action: IndexAction;
+    /** Present only when the work required materializing it anyway. */
+    session?: NormalizedSession;
+}
+/**
+ * Brings one session's index up to date and returns it.
+ *
+ * The three layers are invalidated independently: only a changed fingerprint
+ * or a new `PARSER_VERSION` costs a file read. A new `EXTRACTOR_VERSION` or
+ * `EDGE_VERSION` re-derives from the stored events alone.
+ */
+export declare function indexSession(db: DatabaseSync, handle: IndexHandle, options?: IndexOptions): Promise<IndexResult>;
+/**
+ * The same work without materializing the session.
+ *
+ * A caller that only needs the index to be current — search, for one — pays a
+ * stat and a 64KB read per session instead of rebuilding every event object.
+ */
+export declare function refreshSession(db: DatabaseSync, handle: IndexHandle, options?: IndexOptions): Promise<RefreshResult>;

package/dist/src/store/indexer.js

@@ -0,0 +1,62 @@
+import { summarizeTurns } from '../turns.js';
+import { deriveEdges } from './edges.js';
+import { deriveFacts } from './facts.js';
+import { readSession, sessionRow } from './read.js';
+import { EDGE_VERSION, EXTRACTOR_VERSION, PARSER_VERSION } from './schema.js';
+import { canonicalId, fingerprintOf, writeSession } from './write.js';
+/**
+ * Brings one session's index up to date and returns it.
+ *
+ * The three layers are invalidated independently: only a changed fingerprint
+ * or a new `PARSER_VERSION` costs a file read. A new `EXTRACTOR_VERSION` or
+ * `EDGE_VERSION` re-derives from the stored events alone.
+ */
+export async function indexSession(db, handle, options = {}) {
+    const result = await refreshSession(db, handle, options);
+    const session = result.session ?? readSession(db, sessionRow(db, result.id));
+    return { id: result.id, action: result.action, session };
+}
+/**
+ * The same work without materializing the session.
+ *
+ * A caller that only needs the index to be current — search, for one — pays a
+ * stat and a 64KB read per session instead of rebuilding every event object.
+ */
+export async function refreshSession(db, handle, options = {}) {
+    const { adapter, candidate } = handle;
+    const id = canonicalId(adapter.provider, candidate.id);
+    const aux = await adapter.auxFingerprint?.(candidate);
+    const fingerprint = fingerprintOf(candidate, aux);
+    const row = sessionRow(db, id);
+    const l1Valid = !!row &&
+        !options.force &&
+        row.parser_version === PARSER_VERSION &&
+        row.source_size === fingerprint.sourceSize &&
+        row.source_mtime_ms === fingerprint.sourceMtimeMs &&
+        row.head_hash === fingerprint.headHash &&
+        (row.aux_fingerprint ?? undefined) === fingerprint.auxFingerprint;
+    if (!l1Valid) {
+        const session = await adapter.parse(candidate);
+        writeSession(db, session, fingerprint, summarizeTurns(session).length);
+        deriveFacts(db, id, session);
+        if (options.edges !== false)
+            deriveEdges(db, id, session);
+        return { id, action: 'indexed', session };
+    }
+    // Nothing to redo: the caller gets an id and no object was ever built.
+    if (row.extractor_version === EXTRACTOR_VERSION &&
+        (options.edges === false || row.edge_version === EDGE_VERSION)) {
+        return { id, action: 'reused' };
+    }
+    const session = readSession(db, row);
+    let action = 'reused';
+    if (row.extractor_version !== EXTRACTOR_VERSION) {
+        deriveFacts(db, id, session);
+        action = 'facts-rederived';
+    }
+    if (options.edges !== false && row.edge_version !== EDGE_VERSION) {
+        deriveEdges(db, id, session);
+        action = action === 'reused' ? 'edges-rederived' : action;
+    }
+    return { id, action, session };
+}

package/dist/src/store/read.d.ts

@@ -0,0 +1,29 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type NormalizedSession, type SessionRef } from '../types.js';
+export interface SessionRow {
+    id: string;
+    provider: string;
+    native_id: string;
+    source_path: string;
+    workspace: string | null;
+    title: string | null;
+    started_at: string | null;
+    ended_at: string | null;
+    event_count: number;
+    turn_count: number;
+    source_size: number;
+    source_mtime_ms: number;
+    head_hash: string | null;
+    aux_fingerprint: string | null;
+    parser_version: number;
+    extractor_version: number;
+    edge_version: number;
+    indexed_at: string | null;
+    artifacts_json: string | null;
+    stats_json: string | null;
+}
+export declare function sessionRow(db: DatabaseSync, id: string): SessionRow | undefined;
+/** Resolves a full id, an id prefix, or a native id against the index. */
+export declare function findSessionRow(db: DatabaseSync, needle: string): SessionRow | undefined;
+export declare function refOf(row: SessionRow): SessionRef;
+export declare function readSession(db: DatabaseSync, row: SessionRow): NormalizedSession;

package/dist/src/store/read.js

@@ -0,0 +1,70 @@
+import { emptyProviderStats, } from '../types.js';
+export function sessionRow(db, id) {
+    return db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
+}
+/** Resolves a full id, an id prefix, or a native id against the index. */
+export function findSessionRow(db, needle) {
+    const exact = db
+        .prepare('SELECT * FROM sessions WHERE id = ? OR native_id = ? LIMIT 1')
+        .get(needle, needle);
+    if (exact)
+        return exact;
+    if (needle.length < 6)
+        return undefined;
+    return db
+        .prepare('SELECT * FROM sessions WHERE native_id LIKE ? ORDER BY ended_at DESC LIMIT 1')
+        .get(`${needle}%`);
+}
+export function refOf(row) {
+    return {
+        id: row.native_id,
+        provider: row.provider,
+        path: row.source_path,
+        ...(row.title === null ? {} : { title: row.title }),
+        ...(row.workspace === null ? {} : { workspace: row.workspace }),
+        ...(row.started_at === null ? {} : { createdAt: row.started_at }),
+        ...(row.ended_at === null ? {} : { updatedAt: row.ended_at }),
+        sizeBytes: row.source_size,
+    };
+}
+/**
+ * Rebuilds events exactly as the parser emitted them — absent optionals stay
+ * absent, so the result deep-equals a fresh `parse()`.
+ */
+function eventsOf(db, id, nativeId) {
+    const rows = db
+        .prepare('SELECT * FROM events WHERE session_id = ? ORDER BY idx')
+        .all(id);
+    return rows.map((row) => ({
+        id: `${nativeId}#${row.idx}`,
+        index: row.idx,
+        kind: row.kind,
+        ...(row.text === null ? {} : { text: row.text }),
+        ...(row.tool_name === null ? {} : { toolName: row.tool_name }),
+        ...(row.tool_args_json === null
+            ? {}
+            : { toolArgs: JSON.parse(row.tool_args_json) }),
+        ...(row.tool_result === null ? {} : { toolResult: row.tool_result }),
+        ...(row.is_error === null ? {} : { isError: row.is_error === 1 }),
+        ...(row.ts === null ? {} : { timestamp: row.ts }),
+        ...(row.source_index === null ? {} : { sourceIndex: row.source_index }),
+        ...(row.provider_truncated === null ? {} : { truncated: row.provider_truncated === 1 }),
+        ...(row.pid === null ? {} : { processId: row.pid }),
+        ...(row.exit_code === null ? {} : { exitCode: row.exit_code }),
+        ...(row.duration_ms === null ? {} : { durationMs: row.duration_ms }),
+    }));
+}
+export function readSession(db, row) {
+    const artifacts = row.artifacts_json
+        ? JSON.parse(row.artifacts_json)
+        : [];
+    const stats = row.stats_json
+        ? JSON.parse(row.stats_json)
+        : emptyProviderStats();
+    return {
+        ref: refOf(row),
+        turns: eventsOf(db, row.id, row.native_id),
+        artifacts,
+        stats,
+    };
+}

package/dist/src/store/rows.d.ts

@@ -0,0 +1,35 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** One indexed event, reduced to the columns a text search needs. */
+export interface TextRow {
+    session_id: string;
+    idx: number;
+    kind: string;
+    tool_name: string | null;
+    ts: string | null;
+    text: string | null;
+    tool_result: string | null;
+    tool_args_json: string | null;
+}
+export interface RowQuery {
+    /** Sessions in scope, already refreshed against disk. */
+    ids: string[];
+    /** Canonical workspace root; matches the directory itself and everything under it. */
+    workspace?: string;
+    kinds?: string[];
+    /**
+     * A substring every match must contain. Pushing it into SQL is only sound
+     * when it is genuinely mandatory — see `mandatoryLiteral` in `search.ts`.
+     */
+    literal?: string;
+    /** Compare the literal case-insensitively (ASCII folding, as SQLite does). */
+    fold?: boolean;
+}
+/**
+ * Streams candidate rows. The filters are structural — session scope,
+ * workspace, kind — plus an optional literal prefilter; deciding whether a row
+ * really matches stays with the regex matcher, which remains the only
+ * authority on search semantics.
+ */
+export declare function searchRows(db: DatabaseSync, query: RowQuery): Generator<TextRow>;
+/** Session rows for the ids a search ended up with. */
+export declare function scopedSessions(db: DatabaseSync, ids: string[]): Record<string, import("node:sqlite").SQLOutputValue>[];

package/dist/src/store/rows.js

@@ -0,0 +1,55 @@
+const TEXT_COLUMNS = ['text', 'tool_result', 'tool_args_json'];
+/**
+ * Streams candidate rows. The filters are structural — session scope,
+ * workspace, kind — plus an optional literal prefilter; deciding whether a row
+ * really matches stays with the regex matcher, which remains the only
+ * authority on search semantics.
+ */
+export function* searchRows(db, query) {
+    if (!query.ids.length)
+        return;
+    db.exec('DROP TABLE IF EXISTS temp.search_scope');
+    db.exec('CREATE TEMP TABLE search_scope (id TEXT PRIMARY KEY)');
+    const insert = db.prepare('INSERT OR IGNORE INTO temp.search_scope (id) VALUES (?)');
+    for (const id of query.ids)
+        insert.run(id);
+    const where = [];
+    const params = [];
+    if (query.workspace) {
+        // Plain prefix comparison, not LIKE: real paths contain `_`, which LIKE
+        // would treat as a wildcard.
+        where.push('(s.workspace = ? OR substr(s.workspace, 1, ?) = ?)');
+        params.push(query.workspace, query.workspace.length + 1, `${query.workspace}/`);
+    }
+    if (query.kinds?.length) {
+        where.push(`e.kind IN (${query.kinds.map(() => '?').join(', ')})`);
+        params.push(...query.kinds);
+    }
+    if (query.literal) {
+        const column = (name) => query.fold ? `lower(coalesce(e.${name}, ''))` : `coalesce(e.${name}, '')`;
+        // Per column, never across the joined haystack: a literal that straddles
+        // two fields would be missed, so callers reject literals containing a
+        // newline before they get here.
+        where.push(`(${TEXT_COLUMNS.map((name) => `instr(${column(name)}, ?) > 0`).join(' OR ')})`);
+        params.push(...TEXT_COLUMNS.map(() => query.literal));
+    }
+    const sql = `SELECT e.session_id, e.idx, e.kind, e.tool_name, e.ts, e.text, e.tool_result, e.tool_args_json
+     FROM events e
+     JOIN temp.search_scope sc ON sc.id = e.session_id
+     JOIN sessions s ON s.id = e.session_id` +
+        (where.length ? `\n     WHERE ${where.join(' AND ')}` : '') +
+        '\n     ORDER BY e.session_id, e.idx';
+    try {
+        yield* db.prepare(sql).iterate(...params);
+    }
+    finally {
+        db.exec('DROP TABLE IF EXISTS temp.search_scope');
+    }
+}
+/** Session rows for the ids a search ended up with. */
+export function scopedSessions(db, ids) {
+    if (!ids.length)
+        return [];
+    const placeholders = ids.map(() => '?').join(', ');
+    return db.prepare(`SELECT * FROM sessions WHERE id IN (${placeholders})`).all(...ids);
+}

package/dist/src/store/schema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Index store schema and the version constants that decide what is stale.
+ *
+ * The four versions are independent on purpose: a change to fact extraction
+ * must not force a re-read of 600MB of JSONL, it only invalidates the layer it
+ * actually touched. Bump the matching constant in the same commit that changes
+ * the behaviour — never derive them from a git hash, `dist` ships without git.
+ */
+/** DDL layout. A bump drops and rebuilds the whole database. */
+export declare const SCHEMA_VERSION = 1;
+/** L1 semantics — anything in `parsers/` that changes normalized events. */
+export declare const PARSER_VERSION = 1;
+/** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */
+export declare const EXTRACTOR_VERSION = 1;
+/** L3 rules — `store/edges.ts`. Re-derives edges from stored events. */
+export declare const EDGE_VERSION = 1;
+export declare const DDL = "\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS sessions (\n  id                TEXT PRIMARY KEY,          -- canonical \"provider:native_id\"\n  provider          TEXT NOT NULL,\n  native_id         TEXT NOT NULL,\n  source_path       TEXT NOT NULL,\n  workspace         TEXT,\n  title             TEXT,\n  started_at        TEXT,\n  ended_at          TEXT,\n  event_count       INTEGER NOT NULL DEFAULT 0,\n  turn_count        INTEGER NOT NULL DEFAULT 0,\n  source_size       INTEGER NOT NULL DEFAULT 0,\n  source_mtime_ms   INTEGER NOT NULL DEFAULT 0,\n  head_hash         TEXT,\n  aux_fingerprint   TEXT,\n  indexed_bytes     INTEGER NOT NULL DEFAULT 0, -- reserved for resumable parse\n  parser_version    INTEGER NOT NULL DEFAULT 0,\n  extractor_version INTEGER NOT NULL DEFAULT 0,\n  edge_version      INTEGER NOT NULL DEFAULT 0,\n  indexed_at        TEXT,\n  artifacts_json    TEXT,\n  stats_json        TEXT\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  session_id     TEXT NOT NULL,\n  idx            INTEGER NOT NULL,\n  kind           TEXT NOT NULL,\n  text           TEXT,\n  tool_name      TEXT,\n  tool_args_json TEXT,\n  tool_result    TEXT,\n  is_error       INTEGER,\n  ts             TEXT,\n  source_index   INTEGER,\n  exit_code      INTEGER,\n  pid            TEXT,\n  duration_ms    INTEGER,\n  provider_truncated INTEGER,                 -- the provider's own \"shortened copy\" flag\n  PRIMARY KEY (session_id, idx)\n) WITHOUT ROWID;\n\nCREATE TABLE IF NOT EXISTS file_ops (\n  session_id  TEXT NOT NULL,\n  path        TEXT NOT NULL,\n  host        TEXT,\n  operation   TEXT NOT NULL,\n  turn        INTEGER NOT NULL,\n  event_index INTEGER NOT NULL,\n  ts          TEXT,\n  provenance  TEXT NOT NULL,\n  extractor   TEXT NOT NULL,\n  file_group  TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS commands (\n  session_id  TEXT NOT NULL,\n  event_index INTEGER NOT NULL,\n  turn        INTEGER NOT NULL,\n  command     TEXT NOT NULL,\n  host        TEXT,\n  cwd         TEXT,\n  exit_code   INTEGER,\n  duration_ms INTEGER,\n  pid         TEXT,\n  stderr      TEXT,\n  ts          TEXT,\n  provenance  TEXT NOT NULL,\n  extractor   TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS jobs (\n  session_id     TEXT NOT NULL,\n  job_id         TEXT NOT NULL,\n  command        TEXT,\n  pid            TEXT,\n  host           TEXT,\n  log            TEXT,\n  started_at     TEXT,\n  discovered_from INTEGER,\n  status         TEXT NOT NULL,\n  provenance     TEXT NOT NULL,\n  extractor      TEXT NOT NULL,\n  evidence_json  TEXT\n);\n\nCREATE TABLE IF NOT EXISTS session_edges (\n  id             INTEGER PRIMARY KEY AUTOINCREMENT,\n  from_session   TEXT NOT NULL,\n  to_session     TEXT NOT NULL,\n  relation       TEXT NOT NULL,\n  first_seen_at  TEXT,\n  last_seen_at   TEXT,\n  evidence_count INTEGER NOT NULL DEFAULT 0,\n  UNIQUE (from_session, to_session, relation)\n);\n\nCREATE TABLE IF NOT EXISTS edge_evidence (\n  edge_id       INTEGER NOT NULL,\n  source_session TEXT NOT NULL,\n  event_index   INTEGER NOT NULL,\n  operation     TEXT NOT NULL,\n  command       TEXT,\n  ts            TEXT,\n  provenance    TEXT NOT NULL,\n  extractor     TEXT NOT NULL,\n  UNIQUE (edge_id, source_session, event_index)\n);\n\nCREATE INDEX IF NOT EXISTS idx_events_kind      ON events (session_id, kind);\nCREATE INDEX IF NOT EXISTS idx_fileops_path     ON file_ops (path);\nCREATE INDEX IF NOT EXISTS idx_fileops_session  ON file_ops (session_id);\nCREATE INDEX IF NOT EXISTS idx_commands_session ON commands (session_id, exit_code);\nCREATE INDEX IF NOT EXISTS idx_jobs_session     ON jobs (session_id);\nCREATE INDEX IF NOT EXISTS idx_sessions_ws      ON sessions (workspace, ended_at);\nCREATE INDEX IF NOT EXISTS idx_sessions_native  ON sessions (native_id);\nCREATE INDEX IF NOT EXISTS idx_edges_to         ON session_edges (to_session);\n";
+/** Tables holding derived rows — dropped wholesale when a layer is rebuilt. */
+export declare const L2_TABLES: readonly ["file_ops", "commands", "jobs"];

package/dist/src/store/schema.js

@@ -0,0 +1,142 @@
+/**
+ * Index store schema and the version constants that decide what is stale.
+ *
+ * The four versions are independent on purpose: a change to fact extraction
+ * must not force a re-read of 600MB of JSONL, it only invalidates the layer it
+ * actually touched. Bump the matching constant in the same commit that changes
+ * the behaviour — never derive them from a git hash, `dist` ships without git.
+ */
+/** DDL layout. A bump drops and rebuilds the whole database. */
+export const SCHEMA_VERSION = 1;
+/** L1 semantics — anything in `parsers/` that changes normalized events. */
+export const PARSER_VERSION = 1;
+/** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */
+export const EXTRACTOR_VERSION = 1;
+/** L3 rules — `store/edges.ts`. Re-derives edges from stored events. */
+export const EDGE_VERSION = 1;
+export const DDL = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id                TEXT PRIMARY KEY,          -- canonical "provider:native_id"
+  provider          TEXT NOT NULL,
+  native_id         TEXT NOT NULL,
+  source_path       TEXT NOT NULL,
+  workspace         TEXT,
+  title             TEXT,
+  started_at        TEXT,
+  ended_at          TEXT,
+  event_count       INTEGER NOT NULL DEFAULT 0,
+  turn_count        INTEGER NOT NULL DEFAULT 0,
+  source_size       INTEGER NOT NULL DEFAULT 0,
+  source_mtime_ms   INTEGER NOT NULL DEFAULT 0,
+  head_hash         TEXT,
+  aux_fingerprint   TEXT,
+  indexed_bytes     INTEGER NOT NULL DEFAULT 0, -- reserved for resumable parse
+  parser_version    INTEGER NOT NULL DEFAULT 0,
+  extractor_version INTEGER NOT NULL DEFAULT 0,
+  edge_version      INTEGER NOT NULL DEFAULT 0,
+  indexed_at        TEXT,
+  artifacts_json    TEXT,
+  stats_json        TEXT
+);
+
+CREATE TABLE IF NOT EXISTS events (
+  session_id     TEXT NOT NULL,
+  idx            INTEGER NOT NULL,
+  kind           TEXT NOT NULL,
+  text           TEXT,
+  tool_name      TEXT,
+  tool_args_json TEXT,
+  tool_result    TEXT,
+  is_error       INTEGER,
+  ts             TEXT,
+  source_index   INTEGER,
+  exit_code      INTEGER,
+  pid            TEXT,
+  duration_ms    INTEGER,
+  provider_truncated INTEGER,                 -- the provider's own "shortened copy" flag
+  PRIMARY KEY (session_id, idx)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS file_ops (
+  session_id  TEXT NOT NULL,
+  path        TEXT NOT NULL,
+  host        TEXT,
+  operation   TEXT NOT NULL,
+  turn        INTEGER NOT NULL,
+  event_index INTEGER NOT NULL,
+  ts          TEXT,
+  provenance  TEXT NOT NULL,
+  extractor   TEXT NOT NULL,
+  file_group  TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS commands (
+  session_id  TEXT NOT NULL,
+  event_index INTEGER NOT NULL,
+  turn        INTEGER NOT NULL,
+  command     TEXT NOT NULL,
+  host        TEXT,
+  cwd         TEXT,
+  exit_code   INTEGER,
+  duration_ms INTEGER,
+  pid         TEXT,
+  stderr      TEXT,
+  ts          TEXT,
+  provenance  TEXT NOT NULL,
+  extractor   TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS jobs (
+  session_id     TEXT NOT NULL,
+  job_id         TEXT NOT NULL,
+  command        TEXT,
+  pid            TEXT,
+  host           TEXT,
+  log            TEXT,
+  started_at     TEXT,
+  discovered_from INTEGER,
+  status         TEXT NOT NULL,
+  provenance     TEXT NOT NULL,
+  extractor      TEXT NOT NULL,
+  evidence_json  TEXT
+);
+
+CREATE TABLE IF NOT EXISTS session_edges (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_session   TEXT NOT NULL,
+  to_session     TEXT NOT NULL,
+  relation       TEXT NOT NULL,
+  first_seen_at  TEXT,
+  last_seen_at   TEXT,
+  evidence_count INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (from_session, to_session, relation)
+);
+
+CREATE TABLE IF NOT EXISTS edge_evidence (
+  edge_id       INTEGER NOT NULL,
+  source_session TEXT NOT NULL,
+  event_index   INTEGER NOT NULL,
+  operation     TEXT NOT NULL,
+  command       TEXT,
+  ts            TEXT,
+  provenance    TEXT NOT NULL,
+  extractor     TEXT NOT NULL,
+  UNIQUE (edge_id, source_session, event_index)
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_kind      ON events (session_id, kind);
+CREATE INDEX IF NOT EXISTS idx_fileops_path     ON file_ops (path);
+CREATE INDEX IF NOT EXISTS idx_fileops_session  ON file_ops (session_id);
+CREATE INDEX IF NOT EXISTS idx_commands_session ON commands (session_id, exit_code);
+CREATE INDEX IF NOT EXISTS idx_jobs_session     ON jobs (session_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_ws      ON sessions (workspace, ended_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_native  ON sessions (native_id);
+CREATE INDEX IF NOT EXISTS idx_edges_to         ON session_edges (to_session);
+`;
+/** Tables holding derived rows — dropped wholesale when a layer is rebuilt. */
+export const L2_TABLES = ['file_ops', 'commands', 'jobs'];