devsmind-mcp 2.4.0 → 3.0.0

package/dist/db/database.d.ts

@@ -1,5 +1,6 @@
 import { DbNode, DbHistory, DbConnection, DbWorkflow, DbWorkflowStep, DbWorkflowArtifact } from './schema';
 import { ProjectContext } from '../utils/config';
+import { RankedFile } from './grep';
 export interface ReasoningObject {
     what_changed: string;
     why: string;
@@ -23,24 +24,200 @@ export interface LiveCodeResult {
     updated_at?: string;
     message?: string;
 }
+/** `depth` is hops from the root IN THE TRAVERSAL THAT FOUND IT, not a call-stack distance — with
+ * `direction:"both"` a path can alternate caller→callee, so it is not a directional "N calls
+ * deep" number. Absent only for the synthetic case where a node id was never resolvable
+ * (see `getGraph`'s dangling-edge handling), which never reaches the returned `nodes` array. */
 export type GraphNode = DbNode & {
     code?: string;
     code_source?: CodeSource;
+    depth?: number;
 };
+/** One matching code-body line attached to a node found (or corroborated) by the grep layer. */
+export interface CodeMatchLine {
+    line_number: number;
+    line_content: string;
+}
+/** Which search layer(s) surfaced a node — the honest trust signal. A node found by several
+ * independent layers is far more likely right than one found by a single weak one. */
+export type SearchLayer = 'name' | 'keyword' | 'meaning' | 'code';
+/** How much to trust a result, in plain terms — NOT the raw RRF fusion float, which is a tiny,
+ * uninterpretable number (a #1-ranked hit tops out around 0.03) that made every good match look
+ * like a weak guess. `high` = an exact identifier, ≥2 layers agreeing, or a strong semantic match;
+ * `low` = a single weak signal near the floor. */
+export type Confidence = 'high' | 'medium' | 'low';
+/** Bumped when the shape written to `.devmind/workflows/<id>/workflow.json` changes. v2 replaced
+ * per-step `history_ids`/`pending_tasks` with `reasoning`/`node_ids`/`doc_paths`, and workflow
+ * `status`/`is_active` with `archived`. */
+export declare const WORKFLOW_SCHEMA_VERSION = 2;
+/** The half of a workflow a v1 client has no field for, and therefore cannot overwrite when it
+ * rewrites `workflow.json` from its own columns. See `writeWorkflowToDisk`. */
+export declare const WORKFLOW_SIDECAR_FILE = "v2.json";
+export declare const NO_STATIC_CALLERS_NOTE = "no static callers found \u2014 may be used via dynamic dispatch or a generated binding; verify before assuming unused";
+/** Drill-in hooks attached to every search result — the signal that tells the caller whether it's
+ * worth pulling in more graph/history in the same `get_node_code` call before this result is a
+ * dead end. */
+export interface DrillInHooks {
+    /** Outgoing connection count (what this node calls/uses). */
+    uses: number;
+    /** Incoming connection count (who calls/uses this node). A found-by-static-AST count only — see
+     * `used_by_note`. */
+    used_by: number;
+    /** Total history/revision entries for this node. */
+    history_count: number;
+    /** Most recent history update timestamp, if any. */
+    last_updated?: string;
+    /** Present ONLY when `used_by === 0` — a confident "0 callers" on dynamic-dispatch or
+     * generated-binding code (RTK hooks, DI containers) is a false negative, not a real answer. This
+     * turns a misleading zero into an honest "unverified" instead of silently asserting "unused". */
+    used_by_note?: string;
+}
+/** A node in the primary `nodes` bucket of {@link DevMindDatabase.searchNodes}. Either an exact
+ * identifier hit, or a ranked hit fused from the BM25 / vector / code layers. */
+export type RankedNode = (DbNode & DrillInHooks & {
+    matched_via: 'identifier';
+    found_by: SearchLayer[];
+    confidence: 'high';
+    relevance: number;
+}) | (DbNode & DrillInHooks & {
+    matched_via: 'fuzzy' | 'semantic' | 'code';
+    /** Every layer that matched this node — corroboration across layers is the real confidence. */
+    found_by: SearchLayer[];
+    /** Plain-language trust level; replaces the old opaque `score`/`low_confidence` pair. */
+    confidence: Confidence;
+    /** 0-100, relative to the top hit in THIS response — an intuitive ordering aid, not an
+     * absolute probability (that's what `confidence` is for). */
+    relevance: number;
+    matched_terms: string[];
+    /** Present when the node's code body matched — the lines that did, for eyeballing. */
+    code_matches?: CodeMatchLine[];
+});
+/**
+ * The two-bucket result of {@link DevMindDatabase.searchNodes}: `nodes` (the indexed graph,
+ * primary) and `files` (raw filesystem grep hits, last resort — the coverage for CSS/JSON/config
+ * and anything the graph doesn't model). `hint` is set only when BOTH buckets are empty;
+ * `truncated` when the grep walk hit its deadline and returned partial file results.
+ *
+ * `files`/`nodes` stay BARE ARRAYS (never wrapped in `{total, items}`) — an empty search must
+ * still return `files: []`, not `files: {items: [], total: 0}`. The true counts before either
+ * bucket's cap ship as SIBLING fields instead, so a capped result stays distinguishable from a
+ * complete one without changing the shape of the arrays themselves.
+ */
+export interface SearchNodesResult {
+    nodes: RankedNode[];
+    files: RankedFile[];
+    /** True total distinct files that matched, before the `files_offset`/page-size cap — lets the
+     * caller tell "that's everything" from "more exists, ask for the next page". */
+    files_total: number;
+    /** The offset this page of `files` started at (echoes back what was requested; default 0). */
+    files_offset: number;
+    /** True total ranked nodes found across all layers, before the top-20 fusion cap. */
+    nodes_total: number;
+    hint?: string;
+    truncated?: boolean;
+    /** Set only when an explicit `path` scope pointed AT a file excluded from search by default
+     * (a lockfile or build artifact). Distinct from `hint`, which means "nothing matched anywhere":
+     * this means "nothing was SCANNED", and no amount of re-querying will change that. */
+    scope_note?: string;
+}
+/** A `search_nodes` node after compaction — everything needed to decide "is this the one?" and
+ * nothing else. Field ORDER is deliberate and mirrors the full shape: trust signals first. */
+export interface CompactRankedNode {
+    id: string;
+    name: string;
+    type: string;
+    confidence: Confidence;
+    relevance: number;
+    found_by: SearchLayer[];
+    file_path: string;
+    signature: string | null;
+    description: string | null;
+    uses: number;
+    used_by: number;
+    history_count: number;
+    code_matches?: CodeMatchLine[];
+}
+/** A `search_nodes` file after compaction. `match_counts` is the big drop: a map keyed by every
+ * distinct lowercased substring that matched, which is bulk without being a decision input. */
+export interface CompactRankedFile {
+    file_path: string;
+    total_matches: number;
+    sample_lines?: {
+        line_number: number;
+        line_content: string;
+        symbol?: string;
+    }[];
+}
+/**
+ * The compacted form of {@link SearchNodesResult}. Every COUNT survives untouched — a trimmed
+ * result must never be mistakable for a complete one, the same contract the buckets already keep.
+ */
+export interface CompactSearchNodesResult {
+    nodes: CompactRankedNode[];
+    files: CompactRankedFile[];
+    files_total: number;
+    files_offset: number;
+    nodes_total: number;
+    hint?: string;
+    truncated?: boolean;
+    scope_note?: string;
+    /** Which tier was applied, and what it cost — always present when compaction ran, so the caller
+     * can never mistake a trimmed response for the full one. */
+    compacted?: string;
+}
+/**
+ * Shrink a search result to fit, in two tiers.
+ *
+ * Why two rather than an on/off switch: the sample lines and `code_matches` are genuinely the
+ * most useful part of a result — real agent feedback credits them with catching a live bug — so
+ * throwing all of them away at the first byte over a threshold overcorrects. Tier 1 drops what is
+ * bulk-without-signal (`match_counts`, `matched_terms`, `aliases`, `created_at`, `deprecated`, and
+ * the repeated `used_by_note` boilerplate) and thins the rest; only tier 2 gives up the evidence
+ * lines entirely and becomes a pure triage list.
+ *
+ * `confidence`/`relevance`/`found_by` and the `uses`/`used_by`/`history_count` drill-in hooks
+ * survive BOTH tiers on purpose. They are a handful of bytes each and they are precisely what a
+ * caller uses to decide which result to open next — dropping them would make a compact response
+ * smaller and useless at the same time.
+ *
+ * Pure: no DB access, no I/O. Kept here rather than in the MCP handler so it is unit-testable
+ * directly, and so it sits inside the coverage gate.
+ */
+export declare function toCompactSearchResult(result: SearchNodesResult, tier: 1 | 2): CompactSearchNodesResult;
 export interface GraphOptions {
     /** 'out' = callees only (call-flow trace), 'in' = callers only, 'both' = neighborhood. */
     direction?: 'out' | 'in' | 'both';
     includeCode?: boolean;
     codeCharBudget?: number;
+    /** Node-count safety valve for the BFS walk (default 500). Callers embedding a graph inside a
+     * cheaper response (get_node_code) pass a smaller cap than a dedicated graph call would. */
+    maxNodes?: number;
 }
 export interface GraphResult {
     nodes: GraphNode[];
     connections: DbConnection[];
     /** Total characters of code attached (only set when includeCode is true). */
     code_chars?: number;
-    /** Set when some nodes came back without code (budget exhausted, or no code available). */
+    /** Set when some nodes came back without code — for EITHER reason below. */
     code_truncated?: boolean;
+    /** Total nodes without code, both causes combined. Kept for callers that only need the count;
+     * the two fields below are what tell you which cause, and whether acting on it is possible. */
     nodes_without_code?: number;
+    /** Nodes whose code genuinely could not be found (symbol gone from disk, no cached snapshot).
+     * Raising `codeCharBudget` will NOT bring these back — that's the point of splitting them out. */
+    nodes_no_code_available?: number;
+    /** Nodes whose code EXISTS but was dropped to stay inside `codeCharBudget`, by id (capped).
+     * Reported as ids rather than a count so the caller can fetch exactly these — an id stays valid
+     * across calls, where a positional cursor into a re-derived BFS array does not. */
+    code_omitted_node_ids?: string[];
+    /** True when the walk hit `maxNodes` before the queue emptied — more of the graph exists than
+     * was returned. Previously this happened silently; a capped result was indistinguishable from
+     * a complete one. */
+    nodes_truncated?: boolean;
+    /** True when one or more discovered edges were dropped because an endpoint could not be
+     * resolved to a real node (a connections row surviving a deleted/renamed node) — never a
+     * dangling reference into `nodes` for an id that isn't actually there. */
+    connections_truncated?: boolean;
 }
 export declare function formatReasoning(r: string | ReasoningObject): string;
 /**
@@ -56,7 +233,21 @@ export declare class DevMindDatabase {
     private db;
     private dbPath;
     private context;
-    constructor(dbPath: string);
+    /**
+     * `onSyncProgress`: optional, fires during the constructor's initial `syncFromDisk()` pass —
+     * the one silent stretch every CLI command pays on `new DevMindDatabase(...)` before it can
+     * print anything else. Large `.devmind` folders (mainly `history/`, which grows one file per
+     * edit — much faster than node count) can make that pass take minutes; without this, a caller
+     * has no way to tell "still working" from "hung". Omit it for silent construction (the MCP
+     * server's normal path, where per-open console spam would be noise, not signal).
+     */
+    constructor(dbPath: string, opts?: {
+        onSyncProgress?: (phase: string, done: number, total: number) => void;
+    });
+    /** Throttles progress callbacks to ~100 updates across `total` items, regardless of scale —
+     * so a 500-file sync and a 500,000-file sync both report about as often, and the callback
+     * itself (a stdout write) never becomes the bottleneck it was being added to diagnose. */
+    private static shouldReport;
     private initSchema;
     getContext(): ProjectContext | null;
     getSystemMeta(key: string): string | null;
@@ -102,12 +293,65 @@ export declare class DevMindDatabase {
         name: string;
         file_path: string;
         signature?: string | null;
+        description?: string | null;
+        aliases?: string[];
     }): void;
+    /**
+     * Adds one alias to a node WITHOUT touching any it already has — the merge-safe counterpart to
+     * `upsertNode`'s replace-if-given aliases. This is what the batch graph-fix session's
+     * `record_alias` correction tool (Phase E) uses: it should never be able to accidentally drop an
+     * alias a deterministic detector pass already attached.
+     */
+    addAlias(nodeId: string, alias: string): void;
+    /**
+     * Stores a node's semantic vector and writes it to the committed `vectors/*.json` tree.
+     * `vector` must already be int8-quantized (`embedTextInt8`/`embedTextsInt8` in embedder.ts) and
+     * `descriptionHash` must be `hashDescription()` of the exact description it was computed from —
+     * this is the staleness key `getNodesNeedingEmbedding` checks against.
+     */
+    upsertNodeVector(nodeId: string, vector: Int8Array, descriptionHash: string): void;
+    getNodeVector(nodeId: string): {
+        modelId: string;
+        dim: number;
+        descriptionHash: string;
+        vector: Int8Array;
+    } | null;
+    /**
+     * Every non-deprecated, described node whose vector is missing, from a different model
+     * (`model_id` mismatch — e.g. a mismatched vector ignored during `syncFromDisk`), or stale
+     * (its description changed since the vector was computed). This is the work queue for both
+     * `devsmind embed` and the auto-embed hooks in `describe`/`add_description` — resumable and
+     * idempotent by construction, same shape as `describe.ts`'s own `WHERE description IS NULL`.
+     * `force: true` returns every described node regardless of vector state (model upgrades).
+     */
+    getNodesNeedingEmbedding(force?: boolean): DbNode[];
+    /**
+     * The `nodes.aliases` column is a JSON-array-in-TEXT blob — better-sqlite3 hands it back as a
+     * raw string, not a parsed array, on every `stmt.all()`/`stmt.get()`. A JSON string masquerading
+     * as `string[]` is a silent-wrong-answer hazard (both have `.length`, so a bug here would not
+     * throw, just quietly misbehave — e.g. counting characters instead of aliases). EVERY raw SQL
+     * read of the `nodes` table must route its rows through {@link parseNodeRow}/{@link
+     * parseNodeRows}, never cast `as DbNode`/`as DbNode[]` directly.
+     */
+    private static parseNodeAliases;
+    private static parseNodeRow;
+    private static parseNodeRows;
     getNode(id: string): DbNode | null;
     deleteNode(id: string): void;
     deprecateNode(id: string): void;
     /** `newFilePath`: pass when the rename is a file move (analyze's rename migration), leave undefined for a pure symbol-id rename where the file itself is unchanged. */
     renameNode(oldId: string, newId: string, newName?: string, newFilePath?: string): void;
+    /**
+     * Merges `fromId` into `intoId` — the batch graph-fix session's `merge_nodes` correction, for
+     * when curation (or a human reviewing feedback) decides two node candidates were never really
+     * distinct entities. Unlike `renameNode` (which moves everything to a FRESH id), `intoId`
+     * already exists with its own rows here: `fromId`'s connections (both directions) and history
+     * are reassigned onto it, `fromId`'s aliases (plus its own name, so old references by that name
+     * still resolve) are folded into `intoId`'s alias set, and `fromId` is deprecated — not hard
+     * deleted, so its history stays reachable and the merge itself stays a reversible correction,
+     * not a destructive one.
+     */
+    mergeNodes(fromId: string, intoId: string): void;
     /**
      * Rewrites a history/[id].json file's identifying fields (node_id, node_metadata) in
      * place, leaving code_snapshot/reasoning/timestamps untouched. Used after a rename so
@@ -137,14 +381,65 @@ export declare class DevMindDatabase {
     private deleteHistoryFilesForNode;
     addConnection(sourceNodeId: string, targetNodeId: string): void;
     removeConnection(sourceNodeId: string, targetNodeId: string): void;
-    getConnections(nodeId: string): {
+    /**
+     * `opts.limit`/`opts.offset` page a hub node's caller/callee list deterministically —
+     * `ORDER BY file_path, name` so a repeated call with the same offset returns the same slice,
+     * and so the local/nearby callers a reader actually wants tend to sort ahead of a scattered
+     * cross-repo tail (same file_path groups together). Omitting `opts` returns every row, exactly
+     * as before — every pre-existing call site keeps working unchanged.
+     */
+    getConnections(nodeId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): {
         uses: DbNode[];
         usedBy: DbNode[];
     };
+    /**
+     * Batched, COUNT-only connection degree for many nodes at once — the search-result drill-in
+     * hooks need this for ~20 nodes per call, and `getConnections` per-node would mean 20 pairs of
+     * full-row-fetching queries. One grouped COUNT each way instead (same shape as the degree
+     * subquery in {@link getGodEntities}). IDs not present in `node_connections` still get a
+     * `{uses:0, usedBy:0}` entry so callers never need an existence check.
+     */
+    getConnectionCounts(ids: string[]): Map<string, {
+        uses: number;
+        usedBy: number;
+    }>;
+    /** Batched history-entry count for many nodes at once — metadata only, no disk reads. */
+    getHistoryCounts(ids: string[]): Map<string, number>;
+    /**
+     * Batched most-recent history timestamp for many nodes at once. Deliberately SQL-only (`MAX`
+     * over the indexed `updated_at` column) — unlike {@link getLatestHistory}, this never touches
+     * `populateHistoryFromDisk`, so it costs nothing beyond the query itself.
+     */
+    getLastUpdatedMap(ids: string[]): Map<string, string>;
     getLatestHistory(nodeId: string): DbHistory | null;
-    listHistory(nodeId: string): Omit<DbHistory, 'code_snapshot' | 'reasoning'>[];
+    listHistory(nodeId: string): Omit<DbHistory, 'code_snapshot' | 'reasoning' | 'edits'>[];
     getHistoryEntry(id: string): DbHistory | null;
     getFullHistory(nodeId: string): DbHistory[];
+    /**
+     * The last `limit` history entries' reasoning + timestamps only — no `code_snapshot`/`edits`.
+     * Built for `get_node_code`'s default `history:"recent"` mode, which already returns the
+     * CURRENT code: repeating past snapshots inline would just duplicate what's already in the
+     * response. The full trail (snapshots + diffable edits) is `history:"full"`, served by
+     * {@link getHistoryPage}. This answers "why does this look the way it does" cheaply enough to
+     * attach to every get_node_code call by default, instead of leaving that as a round trip an AI
+     * has to remember to make (or skip, and re-break a decision it never saw).
+     */
+    getRecentHistorySummaries(nodeId: string, limit: number): Array<Pick<DbHistory, 'id' | 'session_id' | 'created_at' | 'updated_at' | 'reasoning'>>;
+    /**
+     * `history:"full"`'s backing query — the same full-fidelity payload as {@link getFullHistory}
+     * (code_snapshot + diffable edits per entry), but LIMIT/OFFSET applied IN SQL before any disk
+     * read happens, not by slicing an already-fully-loaded array. `getFullHistory` reads every
+     * revision's JSON off disk unconditionally; for a node with dozens of revisions that is dozens
+     * of synchronous file reads to serve a request for the newest 5. `total` is the true count
+     * before paging, same honesty contract as `nodes_total`/`files_total` elsewhere.
+     */
+    getHistoryPage(nodeId: string, limit: number, offset: number): {
+        entries: DbHistory[];
+        total: number;
+    };
     /** Distinct source node ids of edges pointing INTO this node (its "used-by" callers). */
     getInboundSources(nodeId: string): string[];
     getLatestCode(nodeId: string): {
@@ -169,69 +464,167 @@ export declare class DevMindDatabase {
     updateHistory(params: {
         node_id: string;
         code_snapshot: string;
+        /**
+         * The entity's text before this edit, when the caller knows it (`edit_node` does; it holds
+         * the pre-edit file). `null` means the entity did not exist yet — a pure addition. `undefined`
+         * means the caller has no before-state at all (`stage_change`), and no edit is recorded to
+         * the trail: an entry with nothing to compare against gets no diff and no revert.
+         */
+        code_before?: string | null;
         reasoning: string | ReasoningObject;
         session_id?: string;
     }): DbHistory;
     /**
-     * Search for nodes by name/id/reasoning first (cheap, SQL-only). If that finds
-     * nothing, transparently fall back to a code-content search (same engine as
-     * {@link searchCode}) so a query like "alipay" still succeeds even when no
-     * node's name/id/reasoning mentions it but the code itself does. Every result
-     * is tagged `matched_via` so the caller knows which path found it.
+     * Removes the newest recorded edit from a history entry, leaving no trace of it.
+     *
+     * There used to be a citation guard here: a history row cited by a workflow step was emptied
+     * rather than deleted, so the step was not left pointing at nothing. Workflow steps record
+     * `node_ids` now, not history ids, so nothing cites a history row any more and the guard had
+     * nothing left to check. Keeping it would have meant keeping the `history_ids` column alive
+     * purely to protect a reference nothing makes.
+     *
+     * Callers are expected to have restored the file already; this only unwinds what was written
+     * about it.
      */
-    searchNodes(query: string, opts?: {
-        is_regex?: boolean;
+    eraseLastEdit(historyId: string): {
+        erased: boolean;
+        entry_deleted: boolean;
+        reason?: string;
+    };
+    /**
+     * The one search tool, covering both worlds in a single call:
+     *  - a primary `nodes` bucket — the indexed graph, found by exact identifier, then by three
+     *    fused rankers (BM25 over metadata, vector over descriptions, and code-body match), and
+     *  - a last-resort `files` bucket — a real filesystem grep of the configured repos, so files
+     *    the graph never models (CSS, JSON, config, markup, un-indexed code) are finally covered
+     *    in the same call instead of sending the caller off to an external grep.
+     *
+     * Inputs play to each layer's strength: the natural-language `query` drives the semantic vector
+     * layer (and BM25); `opts.keywords` (literal, OR) drive grep and the code-body match, and also
+     * feed BM25. If no keywords are given they're derived from the query's significant tokens, so a
+     * natural-only call still gets code + file coverage.
+     *
+     * Speed is the point — the two slow layers (vector, grep) run concurrently, and the old ~9k
+     * per-node snapshot read (the tool's former ~10-30s cost) is gone: code-body matching now rides
+     * the single grep walk. See `grep.ts` and Phase 4 of the plan.
+     */
+    /**
+     * Attaches the drill-in hooks (`uses`/`used_by`/`history_count`/`last_updated`) to a batch of
+     * search results in place, via ONE grouped query per hook instead of per-node fetches — see
+     * {@link getConnectionCounts}/{@link getHistoryCounts}/{@link getLastUpdatedMap}. This is the
+     * signal that turns a search result from a dead end into something worth drilling into with
+     * `get_node_graph`/`get_node_history` — without it, nothing hints there's more to find.
+     */
+    private attachDrillInHooks;
+    searchNodes(query: string | undefined, opts?: {
+        pattern?: string;
+        path?: string;
         case_insensitive?: boolean;
-    }): Array<(DbNode & {
-        matched_via: 'identifier';
-    }) | (ReturnType<DevMindDatabase['searchCode']>[number] & {
-        matched_via: 'code';
-    }) | (DbNode & {
-        matched_via: 'fuzzy';
-        matched_terms: string[];
-        score: number;
-    })>;
-    /**
-     * Splits a query string into lowercase word tokens for the fuzzy fallback
-     * stage of {@link searchNodes}. This is request-scoped tokenization only —
-     * nothing is persisted or indexed; the result is discarded after the call.
-     */
-    private tokenizeQuery;
-    /**
-     * Word-split relevance-ranked fallback for {@link searchNodes}. Runs only
-     * when the exact identifier and code stages both return nothing. Scores
-     * every non-deprecated node by how many distinct query tokens appear as a
-     * substring of its file_path/name/id (highest signal), latest reasoning,
-     * or code content (lowest signal, one point per matching line). No new
-     * data is written or synced — this is a plain in-memory scan reusing the
-     * same node/history sources searchCode already reads.
-     */
-    private fuzzySearchNodes;
-    getRecentChanges(hours?: number, analyzeImpact?: boolean): {
-        node_id: string;
-        node_name: string;
-        file_path: string;
-        updated_at: string;
-        reasoning: string;
-        downstream_impact?: {
-            node_id: string;
-            node_name: string;
-            file_path: string;
-            status: 'stale_warning' | 'already_updated';
-        }[];
-    }[];
-    getDeveloperActivity(developer: string, limit?: number): {
-        node_id: string;
-        node_name: string;
-        updated_at: string;
-        reasoning: string;
-    }[];
-    getChangesByRequirement(requirementId: string): {
-        node_id: string;
-        node_name: string;
-        updated_at: string;
-        reasoning: string;
-    }[];
+        offset?: number;
+        limit?: number;
+        compact?: boolean;
+    }): Promise<SearchNodesResult>;
+    /**
+     * The token-ranked (BM25) half of {@link searchNodes}. Looks up every query/keyword token in
+     * the local `node_tokens` index (rebuilding it first if stale — see {@link ensureSearchIndexFresh}),
+     * scores each candidate with {@link scoreCandidate} (IDF-weighted, saturating TF, per-field
+     * weights favoring `description`), and applies the noise floor. Metadata only — identifier / id
+     * / path / description / reasoning. Code-body matching is NO LONGER folded in here: it used to
+     * read one history-JSON per node (~9k serial reads = the tool's ~10-30s cost), and is now
+     * served far faster by the real filesystem grep in `searchNodes` (see `mapGrepHitsToNodes`).
+     * Returns nodes tagged `matched_via:'fuzzy'`, ranked; `searchNodes` re-fuses them by RRF.
+     */
+    private tokenSearchNodes;
+    /** Absolute filesystem roots for every configured repo — the search space for `grepRepos`. */
+    private repoRoots;
+    /**
+     * Resolves and validates `search_nodes`' optional `path` scope — a single folder or file the
+     * grep walk restricts to, instead of always walking every configured repo. A path outside every
+     * repo root is REJECTED (thrown, not silently widened to "search everything") — a scope that
+     * can't be honored should fail loudly, since silently ignoring it would search far more than
+     * the caller asked for. `canonicalizePath` (already used throughout this file for path
+     * comparisons) lowercases the Windows drive letter so `C:\...` and `c:\...` compare equal.
+     */
+    private resolveSearchScopePath;
+    /**
+     * Maps raw grep hits back to graph nodes — this is "code search that returns nodes", rebuilt
+     * on top of the single filesystem walk instead of the old ~9k per-node snapshot reads. For each
+     * file that had hits AND contains indexed nodes: an AST-parseable file is resolved precisely
+     * (each hit line → the one node whose line-range contains it, via {@link locateNodeInFile}), so
+     * a keyword hitting one method in a 10-method file surfaces THAT node, not all ten. A non-AST
+     * indexed file (a staged `.py`/`.go` node) falls back to coarse file→node. Returns node ids in
+     * match-strength order (files with more hits first) plus the matching lines, for RRF + display.
+     *
+     * Only the top {@link CODE_MATCH_FILE_CAP} files by hit count are AST-resolved — measured on a
+     * real 8-repo, 15k-grep-hit query, this step alone was 8.2s of a 9.6s total before the cap, one
+     * `locateNodeInFile` AST walk per node per matched file with no bound on how many files that
+     * could be. It doesn't cost result quality: the fused ranking downstream keeps only the top ~20
+     * nodes anyway, and files with more hits are exactly the ones most likely to place there — files
+     * past the cap would almost never have survived to the final result even fully resolved.
+     */
+    private mapGrepHitsToNodes;
+    /**
+     * Resolves every indexed node's line span within one AST-parseable file — extracted out of
+     * `mapGrepHitsToNodes` so `annotateSampleLinesWithSymbol` can reuse the identical span logic
+     * instead of re-deriving it. Computed ONCE per file (not per line/hit): a file with several
+     * sample lines would otherwise repeat the same `locateNodeInFile` AST walk once per line.
+     * `nodes` is accepted rather than re-fetched so an existing `getNodesByFilePath` result (as
+     * `mapGrepHitsToNodes` already has) isn't queried twice.
+     */
+    private computeSymbolSpans;
+    /**
+     * Mutates each `RankedFile`'s `sample_lines` in place, tagging every line with the function/class
+     * that contains it — the insight a plain filesystem grep can never give: not just "line 87
+     * matched" but "line 87, inside `onLikeTap`". This is the annotation `search_nodes` offers that
+     * makes it worth more than grep for a hit that lands inside real source.
+     *
+     * Deliberately bounded to the ALREADY-CAPPED page (`files`, ≤`maxFiles` entries × ≤5 sample
+     * lines each — at most ~125 lookups) rather than every raw grep hit. `mapGrepHitsToNodes` is
+     * measured at 8.2s of a 9.6s query on a real 8-repo search (see its doc comment) precisely from
+     * unbounded per-hit AST resolution; annotating only what's actually returned keeps this at a
+     * small, constant added cost regardless of how broad the pattern was or how many total hits it
+     * produced. Silently no-ops for a file that isn't indexed or isn't AST-parseable — a `symbol` on
+     * a sample line is a bonus, never a requirement.
+     */
+    private annotateSampleLinesWithSymbol;
+    /**
+     * The semantic half of hybrid search: embeds the query with the same vendored ONNX model used
+     * to embed every node's description (see embedder.ts), then linear-scans `node_vectors` for
+     * cosine similarity. Linear is fine at this scale — ~9k nodes × 384 int8 dims is a few million
+     * integer multiplications, well under a millisecond, far below the model's own inference time
+     * for the query itself; revisit only past ~100k nodes. Returns each surviving node's raw cosine
+     * alongside its id — the ORDER drives RRF, but the cosine value is kept so `searchNodes` can turn
+     * it into a human-meaningful confidence (a 0.7 cosine is a strong match; a 0.36 is a weak one —
+     * the fused RRF float can't express that). Returns [] — never throws — if the embedder is
+     * unavailable, so `searchNodes` degrades to BM25+grep exactly as before.
+     */
+    private vectorSearchNodes;
+    /**
+     * Cheap, single-pass signal for "has the graph changed since node_tokens was last built":
+     * how many non-deprecated nodes exist, the total length of every description (catches a
+     * description being added OR edited — length almost never stays identical), and how many
+     * history rows exist (catches new reasoning). Deliberately NOT based on an `updated_at`
+     * column on `nodes` — there isn't one, and `syncFromDisk`'s destructive graph-rebuild pass
+     * writes nodes via raw SQL, not through a single method that could easily be hooked, so a
+     * write-path-by-write-path invalidation scheme would silently miss that path (and did, in an
+     * earlier draft of this). A fingerprint checked lazily at query time can't be missed the same
+     * way — it doesn't matter HOW the data changed, only THAT it did.
+     */
+    private searchIndexFingerprint;
+    /** Rebuilds `node_tokens` from scratch for every non-deprecated node's current
+     * identifier/id/path/description and EVERY revision's reasoning (not just the latest — a
+     * decision recorded three revisions ago must stay findable by `search_nodes`, since there is
+     * no separate decisions-only search tool anymore; `GROUP_CONCAT` folds every history row's
+     * reasoning into one field before tokenizing, so an older "Decision: …" is searchable exactly
+     * like the newest one). Cheap at realistic node counts (hundreds to low-thousands) — a single
+     * scan plus one batched transaction, not something that needs to be avoided; simplicity here
+     * is worth more than incremental upkeep that a bypassed write path could silently defeat. */
+    private rebuildSearchIndex;
+    /** Compares the current fingerprint against what `node_tokens` was last built from, stored in
+     * `system_meta`; rebuilds and updates the stored fingerprint only on a mismatch. A momentarily
+     * stale index (between a real change and the next search call) only costs ranking quality on
+     * that one call, never correctness — the next call rebuilds it. */
+    private ensureSearchIndexFresh;
     searchDecisions(query: string): {
         node_id: string;
         node_name: string;
@@ -256,10 +649,35 @@ export declare class DevMindDatabase {
     }[];
     getOrphanedNodes(): DbNode[];
     getAllNodes(): DbNode[];
+    /**
+     * The shared WHERE clause behind {@link listNodes} and {@link countNodes}. Extracted so the page
+     * and its total can never drift apart — a `total` computed from even slightly different criteria
+     * than the rows it describes is worse than no total at all, since it reads as authoritative.
+     */
+    private buildNodeFilterSql;
+    /**
+     * Total nodes matching a filter, independent of any page. Exists so `list_nodes` can tell
+     * "that's everything" from "there is more" — the same honesty contract `nodes_total` and
+     * `files_total` already keep for search.
+     */
+    countNodes(filter?: {
+        type?: string;
+        file_path?: string;
+        include_deprecated?: boolean;
+    }): number;
+    /**
+     * `limit`/`offset` are OPTIONAL and, when omitted, this returns every matching row exactly as
+     * before — the internal analysis callers (`analyze.ts`, `edges.ts`) legitimately need the whole
+     * graph, so paging is opt-in rather than a default that would silently truncate them. Ordering
+     * is applied only when paging, since an unordered LIMIT is a lottery: without it, "page 2" is
+     * not guaranteed to exclude what "page 1" already returned.
+     */
     listNodes(filter?: {
         type?: string;
         file_path?: string;
         include_deprecated?: boolean;
+        limit?: number;
+        offset?: number;
     }): DbNode[];
     getAllConnections(): DbConnection[];
     getAllHistory(): DbHistory[];
@@ -299,21 +717,86 @@ export declare class DevMindDatabase {
         updated_at: string;
     }[];
     private workflowsDir;
-    /** Serializes the workflow + its steps + artifact index to disk so teammates can sync it via git. */
+    /**
+     * One-time backfill of `node_ids`/`reasoning` for steps written before v2, resolving each old
+     * `history_ids` entry to the node it belongs to. Runs at open, right after the ALTERs, and is
+     * self-limiting: it only touches rows where `node_ids IS NULL AND history_ids IS NOT NULL`, so
+     * the second open finds nothing and the query costs one indexed scan.
+     *
+     * Best-effort by nature. Because of the 1-hour history merge, an old step's `history_ids` can
+     * include rows an ADJACENT commit created, so a backfilled node list can be broader than what
+     * that step actually touched. That is acceptable for pre-v2 rows — they were already imprecise,
+     * which is exactly why the format changed — but it is why nothing presents backfilled data as
+     * exact. A step whose history rows have since been pruned keeps its `summary` and gets an empty
+     * list rather than being skipped, so it still appears on the timeline.
+     */
+    private backfillWorkflowStepNodeIds;
+    /**
+     * Serializes the workflow + its steps + artifact index to disk so teammates can sync it via git.
+     *
+     * Written as TWO files, and the split is the whole point:
+     *
+     * - `workflow.json` keeps the shape a v1 client understands, so an older build reading it loses
+     *   nothing it ever had.
+     * - `v2.json` holds everything v1 has no field for (`archived`, and per-step `reasoning` /
+     *   `node_ids` / `doc_paths`).
+     *
+     * A single file could not be made safe. `devsmind sync` calls `syncToDisk`, which re-serializes
+     * every workflow.json from whatever columns the local build knows about — so a teammate who
+     * pulls on an older version and syncs would rewrite every workflow and silently strip the new
+     * fields, then commit that loss for everyone. An older build has no idea `v2.json` exists, so it
+     * cannot rewrite it; the data survives the round trip and is merged back on the next read.
+     */
     private writeWorkflowToDisk;
+    /**
+     * Creates a workflow. Note what it deliberately does NOT do any more: set a global "active"
+     * pointer. Which workflow you are working on is a property of YOUR session, held locally — a
+     * workflow is a shared record, and one shared pointer meant two sessions (or two teammates,
+     * since the pointer synced through git) silently stole it from each other mid-work.
+     */
     createWorkflow(name: string, description: string): DbWorkflow;
     getWorkflow(id: string): DbWorkflow | null;
-    getActiveWorkflow(): DbWorkflow | null;
-    listWorkflows(status?: 'active' | 'paused' | 'completed'): DbWorkflow[];
-    /** Pauses the currently active workflow (if any) and clears the active pointer. */
-    pauseWorkflow(): DbWorkflow | null;
-    /** Resumes `id`, auto-pausing whatever was previously active (only one workflow is active at a time). */
-    resumeWorkflow(id: string): DbWorkflow;
-    completeWorkflow(id: string): DbWorkflow;
+    /**
+     * Workflows newest-touched first — which is the ordering that replaces the old `status` field.
+     * Live work floats up and abandoned threads sink on their own, so nothing has to be marked
+     * "completed" by hand (nobody ever did, and a lifecycle field nobody maintains just lies).
+     *
+     * `query` matches name AND description, the search `searchWorkflows` never actually did: it
+     * scanned step summaries and artifact names only, so looking a workflow up by its own name
+     * returned nothing. Paging mirrors `listNodes` — `total` is the true count before the page.
+     */
+    listWorkflows(opts?: {
+        query?: string;
+        includeArchived?: boolean;
+        limit?: number;
+        offset?: number;
+    }): DbWorkflow[];
+    countWorkflows(opts?: {
+        query?: string;
+        includeArchived?: boolean;
+    }): number;
+    /** Shared WHERE builder, so a page and its `total` can never describe different criteria. */
+    private buildWorkflowFilterSql;
+    /**
+     * Hides a workflow from the default listing. Deliberately NOT called "complete": a feature is
+     * never finished, it just stops being worked on, and the old `completed` status promised a
+     * lifecycle nobody maintained. Archiving claims only what it delivers, and is reversible.
+     */
+    setWorkflowArchived(id: string, archived: boolean): DbWorkflow;
+    /**
+     * Appends one step. A step is either a COMMIT (summary + reasoning + the node ids it touched) or
+     * a RESEARCH finding (summary + reasoning + the docs behind it, no nodes) — the second is the
+     * only record of work that produced a decision but no code, which nothing else in DevsMind
+     * captures: git has the diff and history has the per-node reasoning, but neither can tell you
+     * what was evaluated and rejected.
+     *
+     * `reasoning` is stored, not joined from `history`, deliberately — see DbWorkflowStep.
+     */
     addWorkflowStep(workflowId: string, opts: {
         summary: string;
-        pendingTasks?: string;
-        historyIds?: string[];
+        reasoning?: string;
+        nodeIds?: string[];
+        docPaths?: string[];
         sessionId?: string;
     }): DbWorkflowStep;
     /** Writes `content` to `.devmind/workflows/<workflowId>/<artifactId>_<sourceName>` and records the DB row. */
@@ -323,14 +806,28 @@ export declare class DevMindDatabase {
         sourceName: string;
         content: string;
     }): DbWorkflowArtifact;
+    /**
+     * The workflow's story: its steps in order, plus the docs attached to it.
+     *
+     * Paged, because this is now the ONLY read (it absorbed the old `workflow_get_steps`) and steps
+     * carry their own reasoning, so an unbounded version of it would be the largest response the
+     * server can produce. `steps_total` is exact regardless of the page — a short page must never
+     * read as "that is the whole story".
+     *
+     * Artifact CONTENT is deliberately not returned. It used to be inlined whole, which on an
+     * imported architecture doc is trivially tens of KB; the file path is enough, since the file is
+     * on disk and the caller can read exactly the part it needs.
+     */
     getWorkflowContext(id: string, opts?: {
-        includeArtifactContent?: boolean;
+        limit?: number;
+        offset?: number;
+        last_n?: number;
     }): {
         workflow: DbWorkflow;
         steps: DbWorkflowStep[];
-        artifacts: (DbWorkflowArtifact & {
-            content?: string;
-        })[];
+        steps_total: number;
+        steps_offset: number;
+        artifacts: DbWorkflowArtifact[];
     };
     /**
      * Returns steps for a workflow with optional pagination.
@@ -342,29 +839,6 @@ export declare class DevMindDatabase {
         offset?: number;
         last_n?: number;
     }): DbWorkflowStep[];
-    /**
-     * Reads a single workflow artifact's file content from disk.
-     * Accepts either an artifact_id or a source_name (first match used).
-     */
-    readWorkflowArtifact(workflowId: string, artifactId: string): {
-        artifact: DbWorkflowArtifact;
-        content: string;
-    };
-    /**
-     * Full-text keyword search across all workflows' step summaries, pending_tasks,
-     * and artifact source names. Optionally also searches artifact file content.
-     * Returns a list of matches grouped by workflow.
-     */
-    searchWorkflows(query: string, opts?: {
-        include_artifact_content?: boolean;
-        status?: 'active' | 'paused' | 'completed';
-    }): Array<{
-        workflow: DbWorkflow;
-        matched_steps: DbWorkflowStep[];
-        matched_artifacts: (DbWorkflowArtifact & {
-            content_snippet?: string;
-        })[];
-    }>;
     /**
      * Imports an existing flow/architecture doc as a paused workflow (not active — importing
      * a doc isn't the same as declaring active work). Idempotent on `name`: re-importing the
@@ -398,6 +872,8 @@ export declare class DevMindDatabase {
     };
     private populateHistoryFromDisk;
     private writeHistoryToDisk;
+    /** The configured developer identity (`.devmind/.env`'s DEVELOPER_NAME), or null if unset. */
+    getDeveloperName(): string | null;
     toRepoRelativePath(absolutePath: string): string;
     /**
      * Rejects a resolved path that escapes its expected root (e.g. via a stored
@@ -423,10 +899,18 @@ export declare class DevMindDatabase {
      */
     isPathAllowed(absPath: string): boolean;
     toAbsolutePath(repoRelativePath: string): string;
-    syncFromDisk(): void;
+    syncFromDisk(onProgress?: (phase: string, done: number, total: number) => void): void;
     /** Escape LIKE metacharacters so a path is matched literally (use with ESCAPE '\\'). */
     private likeEscape;
     writeGraphToDisk(filePath: string): void;
+    /**
+     * Mirrors `writeGraphToDisk` exactly (same file-matching logic, same directory shape) but into
+     * a separate `vectors/` tree rather than inside `graph/*.json` — deliberately, so opaque base64
+     * blobs never pollute the human-readable, merge-friendly graph JSON. Deprecated nodes are
+     * skipped here (unlike the graph, which keeps them): `searchNodes` never queries a deprecated
+     * node's vector, so writing one is pure dead weight.
+     */
+    writeVectorsToDisk(filePath: string): void;
     /** Force-syncs all database nodes and workflows to disk JSON files. */
     syncToDisk(): void;
 }