@duckcodeailabs/dql-agent 1.6.31 → 1.6.33

package/dist/conversation/session-store.js

@@ -0,0 +1,387 @@
+/**
+ * Server-side conversation session store: threads + ordered turns, persisted in
+ * `.dql/cache/agent-conversations.sqlite` so multi-turn context survives page
+ * refreshes and process restarts.
+ *
+ * This is the SESSION layer — auto-captured, compactable, per-thread. It is
+ * strictly separate from the governed durable memory (`MemoryStore`): raw chat
+ * is never a correctness signal and never enters `agent_memory` except through
+ * an explicit promotion action. Modeled on `memory/sqlite-memory.ts`
+ * (better-sqlite3, WAL, FTS5 porter).
+ */
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { sanitizeFtsQuery } from '../memory/fts-query.js';
+const require = createRequire(import.meta.url);
+let databaseCtor = null;
+function loadDatabase() {
+    databaseCtor ??= require('better-sqlite3');
+    return databaseCtor;
+}
+/** Caps applied at write time so stored turns stay bounded (mirrors the in-request caps). */
+const MAX_SAMPLE_ROWS = 8;
+const MAX_COLUMNS = 24;
+const MAX_DIMENSION_KEYS = 8;
+const MAX_DIMENSION_VALUES = 24;
+const MAX_ANSWER_TEXT = 4000;
+const MAX_SUMMARY = 1200;
+const MAX_DQL_SOURCE = 3000;
+export function defaultConversationPath(projectRoot) {
+    return join(projectRoot, '.dql', 'cache', 'agent-conversations.sqlite');
+}
+export class ConversationStore {
+    db;
+    constructor(dbPath) {
+        mkdirSync(dirname(dbPath), { recursive: true });
+        const Database = loadDatabase();
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.initSchema();
+    }
+    initSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS conversation_threads (
+        id                 TEXT PRIMARY KEY,
+        surface            TEXT NOT NULL DEFAULT 'notebook',
+        title              TEXT,
+        notebook_path      TEXT,
+        working_state_json TEXT NOT NULL DEFAULT '{}',
+        rolling_summary    TEXT,
+        summary_turn_seq   INTEGER NOT NULL DEFAULT 0,
+        archived           INTEGER NOT NULL DEFAULT 0,
+        created_at         TEXT NOT NULL,
+        updated_at         TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_conversation_threads_updated
+        ON conversation_threads(archived, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS conversation_turns (
+        id                     TEXT PRIMARY KEY,
+        thread_id              TEXT NOT NULL,
+        seq                    INTEGER NOT NULL,
+        question               TEXT NOT NULL,
+        answer_summary         TEXT,
+        answer_text            TEXT,
+        route                  TEXT,
+        trust_label            TEXT,
+        certification          TEXT,
+        source_certified_block TEXT,
+        context_pack_id        TEXT,
+        sql                    TEXT,
+        dql_artifact_json      TEXT NOT NULL DEFAULT '{}',
+        cascade_json           TEXT NOT NULL DEFAULT '{}',
+        result_json            TEXT NOT NULL DEFAULT '{}',
+        contract_json          TEXT NOT NULL DEFAULT '{}',
+        created_at             TEXT NOT NULL,
+        UNIQUE (thread_id, seq)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_conversation_turns_thread
+        ON conversation_turns(thread_id, seq DESC);
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS conversation_turns_fts USING fts5(
+        id UNINDEXED,
+        thread_id UNINDEXED,
+        question,
+        answer_summary,
+        tags,
+        tokenize = 'porter unicode61'
+      );
+    `);
+        this.ensureColumn('conversation_turns', 'dql_artifact_json', "TEXT NOT NULL DEFAULT '{}'");
+        this.ensureColumn('conversation_turns', 'cascade_json', "TEXT NOT NULL DEFAULT '{}'");
+    }
+    ensureColumn(table, column, ddl) {
+        const columns = this.db.prepare(`PRAGMA table_info(${table})`).all();
+        if (columns.some((item) => item.name === column))
+            return;
+        this.db.prepare(`ALTER TABLE ${table} ADD COLUMN ${column} ${ddl}`).run();
+    }
+    createThread(input = {}) {
+        const now = new Date().toISOString();
+        const id = `thr_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        const thread = {
+            id,
+            surface: input.surface?.trim() || 'notebook',
+            title: input.title?.trim() || undefined,
+            notebookPath: input.notebookPath?.trim() || undefined,
+            workingState: {},
+            rollingSummary: undefined,
+            summaryTurnSeq: 0,
+            archived: false,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.db.prepare(`
+      INSERT INTO conversation_threads (
+        id, surface, title, notebook_path, working_state_json, rolling_summary,
+        summary_turn_seq, archived, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, '{}', NULL, 0, 0, ?, ?)
+    `).run(thread.id, thread.surface, thread.title ?? null, thread.notebookPath ?? null, now, now);
+        return thread;
+    }
+    getThread(id) {
+        const row = this.db.prepare('SELECT * FROM conversation_threads WHERE id = ?').get(id);
+        return row ? rowToThread(row) : null;
+    }
+    listThreads(options = {}) {
+        const rows = options.includeArchived
+            ? this.db.prepare('SELECT * FROM conversation_threads ORDER BY updated_at DESC LIMIT ?')
+                .all(options.limit ?? 50)
+            : this.db.prepare('SELECT * FROM conversation_threads WHERE archived = 0 ORDER BY updated_at DESC LIMIT ?')
+                .all(options.limit ?? 50);
+        return rows.map(rowToThread);
+    }
+    archiveThread(id) {
+        this.db.prepare('UPDATE conversation_threads SET archived = 1, updated_at = ? WHERE id = ?')
+            .run(new Date().toISOString(), id);
+    }
+    /**
+     * Append a turn to a thread (assigns the next seq, dual-writes the FTS index,
+     * bumps the thread, and sets the thread title from the first question).
+     */
+    appendTurn(threadId, input) {
+        const now = new Date().toISOString();
+        const id = `trn_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        const result = capTurnResult(input.result);
+        const dqlArtifact = capDqlArtifact(input.dqlArtifact);
+        const turn = {
+            ...input,
+            answerText: input.answerText?.slice(0, MAX_ANSWER_TEXT),
+            answerSummary: input.answerSummary?.slice(0, MAX_SUMMARY),
+            dqlArtifact,
+            result,
+            id,
+            threadId,
+            seq: 0,
+            createdAt: now,
+        };
+        const txn = this.db.transaction(() => {
+            const seqRow = this.db.prepare('SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM conversation_turns WHERE thread_id = ?').get(threadId);
+            turn.seq = seqRow.next;
+            this.db.prepare(`
+        INSERT INTO conversation_turns (
+          id, thread_id, seq, question, answer_summary, answer_text, route,
+          trust_label, certification, source_certified_block, context_pack_id,
+          sql, dql_artifact_json, cascade_json, result_json, contract_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(turn.id, threadId, turn.seq, turn.question, turn.answerSummary ?? null, turn.answerText ?? null, turn.route ?? null, turn.trustLabel ?? null, turn.certification ?? null, turn.sourceCertifiedBlock ?? null, turn.contextPackId ?? null, turn.sql ?? null, JSON.stringify(turn.dqlArtifact ?? {}), JSON.stringify(turn.cascade ?? {}), JSON.stringify(turn.result ?? {}), JSON.stringify(turn.contract ?? {}), now);
+            const tags = [
+                turn.sourceCertifiedBlock ?? '',
+                turn.route ?? '',
+                turn.cascade?.terminalLane ?? '',
+                turn.cascade?.routeTier ?? '',
+                turn.dqlArtifact?.name ?? '',
+                turn.dqlArtifact?.kind ?? '',
+                ...(turn.dqlArtifact?.metrics ?? []),
+                ...(turn.dqlArtifact?.dimensions ?? []),
+                ...(turn.result?.columns ?? []),
+                ...Object.keys(turn.result?.dimensionValues ?? {}),
+            ].filter(Boolean).join(' ');
+            this.db.prepare(`
+        INSERT INTO conversation_turns_fts (id, thread_id, question, answer_summary, tags)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(turn.id, threadId, turn.question, turn.answerSummary ?? '', tags);
+            this.db.prepare(`
+        UPDATE conversation_threads
+        SET updated_at = ?, title = COALESCE(title, ?)
+        WHERE id = ?
+      `).run(now, turn.question.slice(0, 120), threadId);
+        });
+        txn();
+        return turn;
+    }
+    recentTurns(threadId, limit = 4) {
+        const rows = this.db.prepare(`
+      SELECT * FROM conversation_turns WHERE thread_id = ? ORDER BY seq DESC LIMIT ?
+    `).all(threadId, limit);
+        return rows.map(rowToTurn).reverse();
+    }
+    /**
+     * Which cascade tiers have answered recently, across all threads. Powers a
+     * tier-distribution surface so you can see the governance ladder shift upward
+     * (more certified/semantic answers) as usage compounds.
+     */
+    tierDistribution(options = {}) {
+        const limit = options.limit ?? 500;
+        const rows = this.db.prepare(`
+      SELECT * FROM conversation_turns ORDER BY created_at DESC LIMIT ?
+    `).all(limit);
+        const byRouteTier = {};
+        const byTerminalLane = {};
+        let total = 0;
+        for (const turn of rows.map(rowToTurn)) {
+            const routeTier = turn.cascade?.routeTier;
+            const terminalLane = turn.cascade?.terminalLane;
+            if (routeTier) {
+                byRouteTier[routeTier] = (byRouteTier[routeTier] ?? 0) + 1;
+                total += 1;
+            }
+            if (terminalLane)
+                byTerminalLane[terminalLane] = (byTerminalLane[terminalLane] ?? 0) + 1;
+        }
+        return { total, byRouteTier, byTerminalLane };
+    }
+    /** Turns older than the compaction cursor and outside the recent window (for rolling summary). */
+    turnsForCompaction(threadId, afterSeq, beforeSeq) {
+        const rows = this.db.prepare(`
+      SELECT * FROM conversation_turns
+      WHERE thread_id = ? AND seq > ? AND seq < ?
+      ORDER BY seq ASC
+    `).all(threadId, afterSeq, beforeSeq);
+        return rows.map(rowToTurn);
+    }
+    updateThreadState(threadId, input) {
+        const sets = ['updated_at = ?'];
+        const params = [new Date().toISOString()];
+        if (input.workingState !== undefined) {
+            sets.push('working_state_json = ?');
+            params.push(JSON.stringify(input.workingState));
+        }
+        if (input.rollingSummary !== undefined) {
+            sets.push('rolling_summary = ?');
+            params.push(input.rollingSummary || null);
+        }
+        if (input.summaryTurnSeq !== undefined) {
+            sets.push('summary_turn_seq = ?');
+            params.push(input.summaryTurnSeq);
+        }
+        params.push(threadId);
+        this.db.prepare(`UPDATE conversation_threads SET ${sets.join(', ')} WHERE id = ?`).run(...params);
+    }
+    /** FTS keyword search over turns; hybrid embedding re-ranking layers on top (P5). */
+    searchTurns(options) {
+        const query = sanitizeFtsQuery(options.query);
+        if (!query)
+            return [];
+        const params = [query];
+        let threadFilter = '';
+        if (options.threadId) {
+            threadFilter = 'AND t.thread_id = ?';
+            params.push(options.threadId);
+        }
+        const rows = this.db.prepare(`
+      SELECT t.*, bm25(conversation_turns_fts) AS rank
+      FROM conversation_turns_fts AS f
+      JOIN conversation_turns AS t ON t.id = f.id
+      WHERE conversation_turns_fts MATCH ?
+        ${threadFilter}
+      ORDER BY rank
+      LIMIT ?
+    `).all(...params, options.limit ?? 6);
+        return rows.map(rowToTurn);
+    }
+    /** Housekeeping: hard-delete archived threads (and their turns) older than the cutoff. */
+    pruneThreads(olderThanDays) {
+        const cutoff = new Date(Date.now() - olderThanDays * 24 * 60 * 60 * 1000).toISOString();
+        let pruned = 0;
+        const txn = this.db.transaction(() => {
+            const stale = this.db.prepare('SELECT id FROM conversation_threads WHERE archived = 1 AND updated_at < ?').all(cutoff);
+            for (const { id } of stale) {
+                this.db.prepare('DELETE FROM conversation_turns_fts WHERE thread_id = ?').run(id);
+                this.db.prepare('DELETE FROM conversation_turns WHERE thread_id = ?').run(id);
+                this.db.prepare('DELETE FROM conversation_threads WHERE id = ?').run(id);
+                pruned += 1;
+            }
+        });
+        txn();
+        return pruned;
+    }
+    close() {
+        this.db.close();
+    }
+}
+function capTurnResult(result) {
+    if (!result)
+        return undefined;
+    const columns = result.columns?.slice(0, MAX_COLUMNS);
+    const rowsSample = result.rowsSample?.slice(0, MAX_SAMPLE_ROWS)
+        .map((row) => Array.isArray(row) ? row.slice(0, MAX_COLUMNS) : row);
+    const dimensionValues = result.dimensionValues
+        ? Object.fromEntries(Object.entries(result.dimensionValues)
+            .slice(0, MAX_DIMENSION_KEYS)
+            .map(([key, values]) => [key, values.slice(0, MAX_DIMENSION_VALUES)]))
+        : undefined;
+    return {
+        columns,
+        rowsSample,
+        dimensionValues,
+        measureColumns: result.measureColumns?.slice(0, MAX_COLUMNS),
+        rowCount: result.rowCount,
+    };
+}
+function capDqlArtifact(artifact) {
+    if (!artifact?.source?.trim())
+        return undefined;
+    return {
+        kind: artifact.kind,
+        source: artifact.source.slice(0, MAX_DQL_SOURCE),
+        name: artifact.name?.slice(0, 180),
+        sourcePath: artifact.sourcePath?.slice(0, 400),
+        metrics: artifact.metrics?.slice(0, MAX_COLUMNS),
+        dimensions: artifact.dimensions?.slice(0, MAX_COLUMNS),
+        filters: artifact.filters?.slice(0, MAX_DIMENSION_KEYS).map((filter) => ({
+            dimension: filter.dimension.slice(0, 180),
+            operator: filter.operator.slice(0, 80),
+            values: filter.values.slice(0, MAX_DIMENSION_VALUES).map((value) => value.slice(0, 240)),
+        })),
+        timeDimension: artifact.timeDimension
+            ? {
+                name: artifact.timeDimension.name.slice(0, 180),
+                granularity: artifact.timeDimension.granularity.slice(0, 80),
+            }
+            : undefined,
+    };
+}
+function rowToThread(row) {
+    return {
+        id: row.id,
+        surface: row.surface,
+        title: row.title ?? undefined,
+        notebookPath: row.notebook_path ?? undefined,
+        workingState: safeJSON(row.working_state_json, {}),
+        rollingSummary: row.rolling_summary ?? undefined,
+        summaryTurnSeq: row.summary_turn_seq,
+        archived: Boolean(row.archived),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function rowToTurn(row) {
+    const result = safeJSON(row.result_json, {});
+    const dqlArtifact = safeJSON(row.dql_artifact_json, {});
+    const cascade = safeJSON(row.cascade_json, {});
+    const contract = safeJSON(row.contract_json, {});
+    return {
+        id: row.id,
+        threadId: row.thread_id,
+        seq: row.seq,
+        question: row.question,
+        answerSummary: row.answer_summary ?? undefined,
+        answerText: row.answer_text ?? undefined,
+        route: row.route ?? undefined,
+        trustLabel: row.trust_label ?? undefined,
+        certification: row.certification ?? undefined,
+        sourceCertifiedBlock: row.source_certified_block ?? undefined,
+        contextPackId: row.context_pack_id ?? undefined,
+        sql: row.sql ?? undefined,
+        dqlArtifact: Object.keys(dqlArtifact).length > 0 ? capDqlArtifact(dqlArtifact) : undefined,
+        cascade: Object.keys(cascade).length > 0 ? cascade : undefined,
+        result: Object.keys(result).length > 0 ? result : undefined,
+        contract: Object.keys(contract).length > 0 ? contract : undefined,
+        createdAt: row.created_at,
+    };
+}
+function safeJSON(raw, fallback) {
+    if (!raw)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/conversation/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/conversation/session-store.ts"],"names":[],"mappings":"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"}

package/dist/conversation/snapshot.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Conversation snapshot: the bounded, structured view of a thread that every
+ * question carries into the answer loop — working state + rolling summary +
+ * a few verbatim recent turns + how the new question relates to the topic.
+ */
+import type { ConversationStore, ConversationTurn } from './session-store.js';
+import type { AgentDqlArtifactReference } from '../answer-loop.js';
+import type { CascadeAnswerResult } from '../cascade/cascade.js';
+import { type ConversationWorkingState, type TopicRelation } from './working-state.js';
+export interface ConversationSnapshotTurn {
+    id: string;
+    question: string;
+    answerSummary?: string;
+    route?: string;
+    sourceCertifiedBlock?: string;
+    contextPackId?: string;
+    resultColumns?: string[];
+    resultRowCount?: number;
+    resultDimensionValues?: Record<string, string[]>;
+    sourceSql?: string;
+    dqlArtifact?: AgentDqlArtifactReference;
+    cascade?: CascadeAnswerResult;
+}
+export interface ConversationSnapshot {
+    threadId: string;
+    rollingSummary?: string;
+    workingState?: ConversationWorkingState;
+    recentTurns: ConversationSnapshotTurn[];
+    /** Semantic-recall hits over older turns (P5). */
+    recalledTurns?: ConversationSnapshotTurn[];
+    /** How the NEW question relates to the ongoing topic (when a question is supplied). */
+    topicRelation?: TopicRelation;
+}
+/**
+ * Build the snapshot for a new question. When the question starts a genuinely
+ * new topic (shift), the carried filters are deterministically cleared in the
+ * snapshot — stale-context protection that doesn't rely on the model.
+ */
+export declare function buildConversationSnapshot(store: ConversationStore, threadId: string, options?: {
+    question?: string;
+    recent?: number;
+}): ConversationSnapshot | null;
+/**
+ * Post-run maintenance: fold the appended turn into the thread's working state
+ * and compact turns that just left the recent window into the rolling summary.
+ * Incremental and idempotent (cursor = summaryTurnSeq); never throws.
+ */
+export declare function advanceThreadState(store: ConversationStore, threadId: string, turn: ConversationTurn): void;
+/**
+ * Semantic recall over the thread's OLDER turns ("what did we discuss about X?").
+ * FTS candidates re-ranked with the deterministic hash-embedding blend
+ * (alpha 0.4 — FTS still dominates). Turns already in the recent verbatim
+ * window are excluded; returns at most `limit` hits. Never throws.
+ */
+export declare function recallRelevantTurns(store: ConversationStore, threadId: string, question: string, options?: {
+    limit?: number;
+    excludeTurnIds?: string[];
+}): Promise<ConversationSnapshotTurn[]>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/conversation/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/conversation/snapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAO5B,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,wBAAwB,CAAC;IACxC,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,kDAAkD;IAClD,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;IAC3C,uFAAuF;IACvF,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,oBAAoB,GAAG,IAAI,CAmB7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAuB3G;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC1D,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAoBrC"}

package/dist/conversation/snapshot.js

@@ -0,0 +1,153 @@
+/**
+ * Conversation snapshot: the bounded, structured view of a thread that every
+ * question carries into the answer loop — working state + rolling summary +
+ * a few verbatim recent turns + how the new question relates to the topic.
+ */
+import { parseWorkingState, reduceWorkingState, } from './working-state.js';
+import { updateRollingSummary } from './rolling-summary.js';
+import { buildAnalysisQuestionPlan } from '../metadata/analysis-planner.js';
+import { hybridRank } from '../embeddings/provider.js';
+const RECENT_TURNS = 4;
+/**
+ * Build the snapshot for a new question. When the question starts a genuinely
+ * new topic (shift), the carried filters are deterministically cleared in the
+ * snapshot — stale-context protection that doesn't rely on the model.
+ */
+export function buildConversationSnapshot(store, threadId, options = {}) {
+    const thread = store.getThread(threadId);
+    if (!thread)
+        return null;
+    const recent = store.recentTurns(threadId, options.recent ?? RECENT_TURNS);
+    let workingState = parseWorkingState(thread.workingState);
+    let topicRelation;
+    if (options.question && workingState.topicKey) {
+        topicRelation = classifyQuestionRelation(workingState, options.question);
+        if (topicRelation === 'shift') {
+            workingState = { ...workingState, filters: [] };
+        }
+    }
+    return {
+        threadId,
+        rollingSummary: thread.rollingSummary,
+        workingState: hasWorkingState(workingState) ? workingState : undefined,
+        recentTurns: recent.map(snapshotTurn),
+        topicRelation,
+    };
+}
+/**
+ * Post-run maintenance: fold the appended turn into the thread's working state
+ * and compact turns that just left the recent window into the rolling summary.
+ * Incremental and idempotent (cursor = summaryTurnSeq); never throws.
+ */
+export function advanceThreadState(store, threadId, turn) {
+    try {
+        const thread = store.getThread(threadId);
+        if (!thread)
+            return;
+        const { state } = reduceWorkingState(parseWorkingState(thread.workingState), turn);
+        // Compact everything older than the recent verbatim window.
+        const compactBefore = Math.max(turn.seq - RECENT_TURNS + 1, 1);
+        const compactable = thread.summaryTurnSeq < compactBefore - 1
+            ? store.turnsForCompaction(threadId, thread.summaryTurnSeq, compactBefore)
+            : [];
+        const rollingSummary = compactable.length > 0
+            ? updateRollingSummary({ previousSummary: thread.rollingSummary, compactedTurns: compactable })
+            : thread.rollingSummary;
+        store.updateThreadState(threadId, {
+            workingState: state,
+            rollingSummary,
+            summaryTurnSeq: compactable.length > 0
+                ? compactable[compactable.length - 1].seq
+                : thread.summaryTurnSeq,
+        });
+    }
+    catch {
+        // Advisory maintenance — never fail the run for it.
+    }
+}
+/**
+ * Semantic recall over the thread's OLDER turns ("what did we discuss about X?").
+ * FTS candidates re-ranked with the deterministic hash-embedding blend
+ * (alpha 0.4 — FTS still dominates). Turns already in the recent verbatim
+ * window are excluded; returns at most `limit` hits. Never throws.
+ */
+export async function recallRelevantTurns(store, threadId, question, options = {}) {
+    try {
+        const excluded = new Set(options.excludeTurnIds ?? []);
+        const candidates = store.searchTurns({ query: question, threadId, limit: 24 })
+            .filter((turn) => !excluded.has(turn.id));
+        if (candidates.length === 0)
+            return [];
+        const ranked = await hybridRank(question, candidates.map((turn, index) => ({
+            item: turn,
+            // FTS returns rank-ordered rows; convert position to a [0,1] score.
+            ftsScore: 1 - index / candidates.length,
+            text: `${turn.question} ${turn.answerSummary ?? ''}`,
+        })), { alpha: 0.4 });
+        return ranked.slice(0, options.limit ?? 3).map((entry) => snapshotTurn(entry.item));
+    }
+    catch {
+        return [];
+    }
+}
+/** Classify the NEW question against the current topic key (same Jaccard rule as the reducer). */
+function classifyQuestionRelation(state, question) {
+    const plan = buildAnalysisQuestionPlan(question);
+    const terms = new Set([
+        ...plan.entities.map((entity) => normalizeTerm(entity.text)),
+        ...plan.metricTerms.map(normalizeTerm),
+    ].filter(Boolean));
+    const topicTerms = new Set((state.topicKey ?? '').split('|').filter(Boolean));
+    if (terms.size === 0)
+        return 'continuation';
+    if (topicTerms.size === 0)
+        return 'continuation';
+    let shared = 0;
+    for (const term of terms)
+        if (topicTerms.has(term))
+            shared += 1;
+    const overlap = shared / (terms.size + topicTerms.size - shared);
+    if (overlap >= 0.5)
+        return 'continuation';
+    if (overlap > 0)
+        return 'refinement';
+    const returned = (state.priorTopics ?? []).some((frame) => {
+        const frameTerms = new Set(frame.topicKey.split('|').filter(Boolean));
+        let hit = 0;
+        for (const term of terms)
+            if (frameTerms.has(term))
+                hit += 1;
+        return frameTerms.size > 0 && hit / (terms.size + frameTerms.size - hit) >= 0.5;
+    });
+    if (returned)
+        return 'return';
+    const onlyRefinement = plan.dimensionTerms.length === 0 && plan.metricTerms.length === 0 && plan.entities.length === 0;
+    return onlyRefinement ? 'refinement' : 'shift';
+}
+function snapshotTurn(turn) {
+    return {
+        id: turn.id,
+        question: turn.question,
+        answerSummary: turn.answerSummary,
+        route: turn.route,
+        sourceCertifiedBlock: turn.sourceCertifiedBlock,
+        contextPackId: turn.contextPackId,
+        resultColumns: turn.result?.columns,
+        resultRowCount: turn.result?.rowCount,
+        resultDimensionValues: turn.result?.dimensionValues,
+        sourceSql: turn.sql,
+        dqlArtifact: turn.dqlArtifact,
+        cascade: turn.cascade,
+    };
+}
+function hasWorkingState(state) {
+    return state.entities.length > 0
+        || state.measures.length > 0
+        || state.dimensions.length > 0
+        || state.filters.length > 0
+        || Boolean(state.topicKey);
+}
+function normalizeTerm(value) {
+    return value.toLowerCase().replace(/[^a-z0-9_ ]+/g, '').replace(/s$/, '').trim();
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/conversation/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/conversation/snapshot.ts"],"names":[],"mappings":"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"}