devsmind-mcp 2.4.0 → 3.0.0

package/dist/db/schema.js

@@ -1,78 +1,130 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INIT_SCHEMA_SQL = void 0;
-exports.INIT_SCHEMA_SQL = `
-CREATE TABLE IF NOT EXISTS nodes (
-  id          TEXT PRIMARY KEY,
-  type        TEXT NOT NULL,
-  name        TEXT NOT NULL,
-  file_path   TEXT NOT NULL,
-  signature   TEXT,
-  deprecated  INTEGER DEFAULT 0,
-  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE IF NOT EXISTS node_connections (
-  source_node_id  TEXT,
-  target_node_id  TEXT,
-  PRIMARY KEY (source_node_id, target_node_id),
-  FOREIGN KEY (source_node_id) REFERENCES nodes (id) ON DELETE CASCADE,
-  FOREIGN KEY (target_node_id) REFERENCES nodes (id) ON DELETE CASCADE
-);
-
-CREATE TABLE IF NOT EXISTS history (
-  id             TEXT PRIMARY KEY,
-  node_id        TEXT NOT NULL,
-  session_id     TEXT NOT NULL,
-  created_at     DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at     DATETIME DEFAULT CURRENT_TIMESTAMP,
-  code_snapshot  TEXT NOT NULL,
-  reasoning      TEXT NOT NULL,
-  FOREIGN KEY (node_id) REFERENCES nodes (id) ON DELETE CASCADE
-);
-
-CREATE TABLE IF NOT EXISTS system_meta (
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL,
-  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE IF NOT EXISTS workflows (
-  id           TEXT PRIMARY KEY,
-  name         TEXT NOT NULL,
-  description  TEXT NOT NULL,
-  status       TEXT NOT NULL DEFAULT 'active',
-  created_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at   DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE IF NOT EXISTS workflow_steps (
-  id             TEXT PRIMARY KEY,
-  workflow_id    TEXT NOT NULL,
-  step_index     INTEGER NOT NULL,
-  summary        TEXT NOT NULL,
-  pending_tasks  TEXT,
-  history_ids    TEXT,
-  session_id     TEXT,
-  created_at     DATETIME DEFAULT CURRENT_TIMESTAMP,
-  FOREIGN KEY (workflow_id) REFERENCES workflows (id) ON DELETE CASCADE
-);
-
-CREATE TABLE IF NOT EXISTS workflow_artifacts (
-  id            TEXT PRIMARY KEY,
-  workflow_id   TEXT NOT NULL,
-  step_id       TEXT,
-  type          TEXT NOT NULL,
-  source_name   TEXT NOT NULL,
-  file_path     TEXT NOT NULL,
-  created_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
-  FOREIGN KEY (workflow_id) REFERENCES workflows (id) ON DELETE CASCADE
-);
-
--- Index for searching nodes by name and type
-CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes (name);
-CREATE INDEX IF NOT EXISTS idx_history_node_id ON history (node_id);
-CREATE INDEX IF NOT EXISTS idx_workflow_steps_workflow_id ON workflow_steps (workflow_id);
-CREATE INDEX IF NOT EXISTS idx_workflow_artifacts_workflow_id ON workflow_artifacts (workflow_id);
+exports.INIT_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS nodes (
+  id          TEXT PRIMARY KEY,
+  type        TEXT NOT NULL,
+  name        TEXT NOT NULL,
+  file_path   TEXT NOT NULL,
+  signature   TEXT,
+  description TEXT,
+  aliases     TEXT DEFAULT '[]',
+  deprecated  INTEGER DEFAULT 0,
+  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS node_connections (
+  source_node_id  TEXT,
+  target_node_id  TEXT,
+  PRIMARY KEY (source_node_id, target_node_id),
+  FOREIGN KEY (source_node_id) REFERENCES nodes (id) ON DELETE CASCADE,
+  FOREIGN KEY (target_node_id) REFERENCES nodes (id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS history (
+  id             TEXT PRIMARY KEY,
+  node_id        TEXT NOT NULL,
+  session_id     TEXT NOT NULL,
+  created_at     DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at     DATETIME DEFAULT CURRENT_TIMESTAMP,
+  code_snapshot  TEXT NOT NULL,
+  reasoning      TEXT NOT NULL,
+  FOREIGN KEY (node_id) REFERENCES nodes (id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS system_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Local, derived search index — never synced or committed, purely a cache rebuilt from
+-- nodes+history whenever search-index.ts's fingerprint check finds it stale. Same category as
+-- brain.db itself: safe to wipe and rebuild from the source of truth at any time.
+CREATE TABLE IF NOT EXISTS node_tokens (
+  node_id  TEXT NOT NULL,
+  token    TEXT NOT NULL,
+  field    TEXT NOT NULL,
+  tf       INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY (node_id, token, field)
+);
+CREATE INDEX IF NOT EXISTS idx_node_tokens_token ON node_tokens (token);
+
+-- Semantic (dense) vectors, one per node, from the vendored ONNX embedder (src/db/embedder.ts).
+-- Unlike node_tokens, these ARE synced via git (vectors/**/*.json, mirroring graph/**/*.json) —
+-- deliberately, per an explicit product decision to trade repo size for teammates skipping local
+-- inference. No foreign key to nodes(id): syncFromDisk() runs its destructive graph pass under
+-- foreign_keys=OFF, so a cascade here would silently never fire; orphans are swept explicitly
+-- instead (see syncFromDisk's vectors pass). model_id guards the git-sync hazard — vectors from
+-- a different embedding model are structurally valid but numerically meaningless, so any reader
+-- MUST check model_id before trusting a row, not just check for its presence.
+CREATE TABLE IF NOT EXISTS node_vectors (
+  node_id          TEXT PRIMARY KEY,
+  model_id         TEXT NOT NULL,
+  dim              INTEGER NOT NULL,
+  description_hash TEXT NOT NULL,
+  vector           BLOB NOT NULL
+);
+
+-- status is vestigial: still declared (NOT NULL DEFAULT makes an INSERT that omits it succeed)
+-- but no longer read or written. archived replaces it -- see DbWorkflow.
+CREATE TABLE IF NOT EXISTS workflows (
+  id           TEXT PRIMARY KEY,
+  name         TEXT NOT NULL,
+  description  TEXT NOT NULL,
+  status       TEXT NOT NULL DEFAULT 'active',
+  archived     INTEGER NOT NULL DEFAULT 0,
+  created_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- pending_tasks and history_ids are vestigial: never written or read by current code, and kept
+-- only so an older CLI opening the same brain.db does not hit "no such column". They are dropped
+-- from DbWorkflowStep, so nothing in TypeScript can reach them by accident.
+CREATE TABLE IF NOT EXISTS workflow_steps (
+  id             TEXT PRIMARY KEY,
+  workflow_id    TEXT NOT NULL,
+  step_index     INTEGER NOT NULL,
+  summary        TEXT NOT NULL,
+  reasoning      TEXT,
+  node_ids       TEXT,
+  doc_paths      TEXT,
+  pending_tasks  TEXT,
+  history_ids    TEXT,
+  session_id     TEXT,
+  created_at     DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (workflow_id) REFERENCES workflows (id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS workflow_artifacts (
+  id            TEXT PRIMARY KEY,
+  workflow_id   TEXT NOT NULL,
+  step_id       TEXT,
+  type          TEXT NOT NULL,
+  source_name   TEXT NOT NULL,
+  file_path     TEXT NOT NULL,
+  created_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (workflow_id) REFERENCES workflows (id) ON DELETE CASCADE
+);
+
+-- Index for searching nodes by name and type
+CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes (name);
+-- Matches getNodesByFilePath's own normalization (REPLACE(LOWER(file_path), '\', '/')) exactly —
+-- without this, that call is a full table scan, and get_node_code's file_outline now puts it on
+-- the hot path of the most-called read tool (once per call, to cross-reference outline entries
+-- against indexed nodes). Idempotent: existing brains pick this up on next open, no migration.
+CREATE INDEX IF NOT EXISTS idx_nodes_file_path ON nodes (REPLACE(LOWER(file_path), '\', '/'));
+-- node_connections' PRIMARY KEY is (source_node_id, target_node_id), so its autoindex serves
+-- "what does X use" but NOT the reverse. Every "who uses X" lookup — the inbound half of getGraph's
+-- BFS, getConnections' used_by, getConnectionCounts — was therefore a full table scan, and the BFS
+-- runs one PER NODE VISITED (up to 500 in a single call). The trailing source_node_id makes this
+-- covering, so the inbound query is answered from the index alone and comes back already ordered
+-- (which is what makes getGraph's ORDER BY free rather than a sort on top of a scan).
+-- Idempotent: existing brains pick this up on next open, no migration.
+CREATE INDEX IF NOT EXISTS idx_node_connections_target ON node_connections (target_node_id, source_node_id);
+CREATE INDEX IF NOT EXISTS idx_history_node_id ON history (node_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_steps_workflow_id ON workflow_steps (workflow_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_artifacts_workflow_id ON workflow_artifacts (workflow_id);
 `;
 //# sourceMappingURL=schema.js.map

package/dist/db/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/db/schema.ts"],"names":[],"mappings":";;;AAuDa,QAAA,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyE9B,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/db/schema.ts"],"names":[],"mappings":";;;AAqGa,QAAA,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6H9B,CAAC"}

package/dist/db/search-index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The searchable "surface" of a node, split into fields so each can carry its own relevance
+ * weight. `description` is the whole point of this module: without it, natural-language search
+ * has almost nothing to match against — an identifier and a file path are a handful of words.
+ */
+export type TokenField = 'identifier' | 'path' | 'description' | 'reasoning';
+export interface TokenRow {
+    token: string;
+    field: TokenField;
+    /** Term frequency — how many times this token appears in this field, for this node. */
+    tf: number;
+}
+/**
+ * Tokenizes one field's text into deduplicated (token, tf) pairs, ready to write into
+ * `node_tokens`. `identifier`/`path` fields use the identifier splitter (camelCase/snake/kebab
+ * boundaries) since that's what they actually are; `description`/`reasoning` use the plain
+ * natural-language tokenizer since they're already prose.
+ */
+export declare function tokenizeNodeField(text: string | null | undefined, field: TokenField): TokenRow[];
+export interface FieldWeights {
+    identifier: number;
+    path: number;
+    description: number;
+    reasoning: number;
+}
+/**
+ * `description` outweighs everything else — it's the field written specifically to be found
+ * by natural language, so a hit there is the strongest possible signal that this is the right
+ * node. `identifier` is still weighted highly since an exact-ish name match is usually right.
+ * `reasoning` is last: it explains WHY something changed, not WHAT it is, so it's a weaker
+ * signal for "find the code that does X" than the other three.
+ */
+export declare const DEFAULT_FIELD_WEIGHTS: FieldWeights;
+export interface FieldMatch {
+    field: TokenField;
+    /** This node's term frequency for the matched token, in this field. */
+    tf: number;
+    /** How many OTHER nodes also have this token in this field — rarer tokens carry more signal. */
+    docFreq: number;
+    /** Total nodes considered, for the IDF calculation. */
+    totalNodes: number;
+}
+/**
+ * A saturating-TF, IDF-weighted score for one candidate node across every (field, token) it
+ * matched. This is BM25-shaped (the same `tf*(k1+1)/(tf+k1)` saturation and log-IDF term BM25
+ * uses) but deliberately simplified: it scores a small, already-narrowed candidate set (nodes
+ * that matched at least one query token via a SQL lookup), not a full-corpus scan, so there's
+ * no need for BM25's document-length normalization term — every "document" here is one node's
+ * handful of fields, not a variable-length passage.
+ */
+export declare function scoreCandidate(matches: FieldMatch[], weights?: FieldWeights): number;
+export interface RankedId {
+    id: string;
+    score: number;
+}
+/**
+ * Reciprocal Rank Fusion — merges the BM25 ranking and the vector-cosine ranking into one list,
+ * using each id's POSITION within each ranking rather than the raw scores. Necessary because
+ * BM25 scores are unbounded and cosine similarity is bounded [-1,1]; there's no principled scale
+ * to sum them on directly, but "1st place" means the same thing in both rankings. An id missing
+ * from a ranking simply contributes 0 from it — appearing in both rankings compounds naturally.
+ * k=60 is the standard RRF constant (Cormack et al.): large enough that rank 1 vs rank 2 isn't a
+ * cliff, small enough that being ranked at all still matters more than being buried at rank 500.
+ */
+export declare function reciprocalRankFusion(rankings: string[][], k?: number): RankedId[];

package/dist/db/search-index.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FIELD_WEIGHTS = void 0;
+exports.tokenizeNodeField = tokenizeNodeField;
+exports.scoreCandidate = scoreCandidate;
+exports.reciprocalRankFusion = reciprocalRankFusion;
+const tokenize_1 = require("../utils/tokenize");
+/**
+ * Tokenizes one field's text into deduplicated (token, tf) pairs, ready to write into
+ * `node_tokens`. `identifier`/`path` fields use the identifier splitter (camelCase/snake/kebab
+ * boundaries) since that's what they actually are; `description`/`reasoning` use the plain
+ * natural-language tokenizer since they're already prose.
+ */
+function tokenizeNodeField(text, field) {
+    if (!text)
+        return [];
+    const tokens = field === 'identifier' || field === 'path' ? (0, tokenize_1.tokenizeIdentifier)(text) : (0, tokenize_1.tokenizeText)(text);
+    const counts = new Map();
+    for (const t of tokens)
+        counts.set(t, (counts.get(t) || 0) + 1);
+    return Array.from(counts.entries()).map(([token, tf]) => ({ token, field, tf }));
+}
+/**
+ * `description` outweighs everything else — it's the field written specifically to be found
+ * by natural language, so a hit there is the strongest possible signal that this is the right
+ * node. `identifier` is still weighted highly since an exact-ish name match is usually right.
+ * `reasoning` is last: it explains WHY something changed, not WHAT it is, so it's a weaker
+ * signal for "find the code that does X" than the other three.
+ */
+exports.DEFAULT_FIELD_WEIGHTS = {
+    description: 4,
+    identifier: 3,
+    path: 2,
+    reasoning: 1.5
+};
+/**
+ * A saturating-TF, IDF-weighted score for one candidate node across every (field, token) it
+ * matched. This is BM25-shaped (the same `tf*(k1+1)/(tf+k1)` saturation and log-IDF term BM25
+ * uses) but deliberately simplified: it scores a small, already-narrowed candidate set (nodes
+ * that matched at least one query token via a SQL lookup), not a full-corpus scan, so there's
+ * no need for BM25's document-length normalization term — every "document" here is one node's
+ * handful of fields, not a variable-length passage.
+ */
+function scoreCandidate(matches, weights = exports.DEFAULT_FIELD_WEIGHTS) {
+    const K1 = 1.2;
+    let score = 0;
+    for (const m of matches) {
+        const idf = Math.log(1 + (m.totalNodes - m.docFreq + 0.5) / (m.docFreq + 0.5));
+        const tfNorm = (m.tf * (K1 + 1)) / (m.tf + K1);
+        score += weights[m.field] * Math.max(idf, 0.01) * tfNorm;
+    }
+    return score;
+}
+/**
+ * Reciprocal Rank Fusion — merges the BM25 ranking and the vector-cosine ranking into one list,
+ * using each id's POSITION within each ranking rather than the raw scores. Necessary because
+ * BM25 scores are unbounded and cosine similarity is bounded [-1,1]; there's no principled scale
+ * to sum them on directly, but "1st place" means the same thing in both rankings. An id missing
+ * from a ranking simply contributes 0 from it — appearing in both rankings compounds naturally.
+ * k=60 is the standard RRF constant (Cormack et al.): large enough that rank 1 vs rank 2 isn't a
+ * cliff, small enough that being ranked at all still matters more than being buried at rank 500.
+ */
+function reciprocalRankFusion(rankings, k = 60) {
+    const scores = new Map();
+    for (const ranking of rankings) {
+        ranking.forEach((id, index) => {
+            scores.set(id, (scores.get(id) || 0) + 1 / (k + index + 1));
+        });
+    }
+    return Array.from(scores.entries())
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=search-index.js.map

package/dist/db/search-index.js.map

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

package/dist/db/staging.d.ts

@@ -4,21 +4,99 @@ export interface StagedEntry {
     node_id: string;
     file_path: string;
     code_snapshot: string;
-    reasoning: string | ReasoningObject;
+    /**
+     * The entity's text before this edit. Only `edit_node` can supply it (it holds the pre-edit
+     * file); `stage_change` takes a snapshot with nothing to diff against and leaves it undefined.
+     * Absent means the entry gets no diff and no revert.
+     */
+    code_before?: string | null;
     name?: string;
     type?: string;
     signature?: string;
+    /**
+     * A 1-3 sentence natural-language description of what this entity does. `commit_changes`
+     * refuses to create a node that has never had one before (see `add_description`) — but an
+     * ordinary edit to an already-described node can leave this unset; `upsertNode`'s COALESCE
+     * means the existing description survives untouched.
+     */
+    description?: string;
     session_id?: string;
     /** Optional explicit edges to add on top of AST resolution (source defaults to this entry). */
     connections?: {
         source_node_id?: string;
         target_node_id: string;
     }[];
+    /**
+     * When this was staged — set automatically by `stageEntry`, not by the caller. A file can pick
+     * up both a traced node-level entry and an untraced whole-file entry (StagedFileEdit) across
+     * separate edit_node calls before one commit; the activity message's edits must interleave the
+     * two in true chronological order for that file's whole-file reconstruction to undo cleanly, so
+     * this is the sort key `commit_changes` uses.
+     */
+    staged_at?: string;
+}
+/**
+ * A whole-file edit that didn't trace to any graph node — a non-code file (CSS, XML, JSON, ...)
+ * or a code edit landing outside any function/class (an import line, a top-level constant). The
+ * graph has nothing to hold for these, but the local activity log still can: `commit_changes`
+ * folds these into the same message as any traced node edits, so every file `edit_node` touches
+ * shows up and is individually revertable there, not just the ones that became graph nodes.
+ */
+export interface StagedFileEdit {
+    file_path: string;
+    before: string;
+    after: string;
+    session_id?: string;
+    /** When this was staged — set automatically by `stageFileEdit`. See StagedEntry.staged_at. */
+    staged_at?: string;
 }
 export declare function readStaged(devmindPath: string): StagedEntry[];
-/** Appends one entry to the buffer and returns the new pending count. */
+export declare function readStagedFileEdits(devmindPath: string): StagedFileEdit[];
+export interface SessionStagingPartition {
+    entries: StagedEntry[];
+    fileEdits: StagedFileEdit[];
+    /** Count of staged entries/file edits left behind because another session owns them. */
+    otherSessionsPending: number;
+}
+/**
+ * Splits the shared buffer into "what this session may commit" vs. "left behind" — the fix for
+ * the multi-session bug where `commit_changes` used to flush the ENTIRE buffer regardless of who
+ * staged what, silently pulling unrelated in-flight work (sometimes from other repos entirely)
+ * into a commit and stamping it with the committing session's reasoning. A plain commit now only
+ * ever touches its own session's staged work; other sessions' entries stay staged untouched.
+ */
+export declare function partitionStagedForSession(devmindPath: string, sessionId: string): SessionStagingPartition;
+/**
+ * Removes only this session's staged entries/file edits, leaving any other session's pending
+ * work in place — the scoped counterpart to `clearStaged`, which used to wipe the whole buffer
+ * (including work another session had not committed yet) after every commit.
+ */
+export declare function clearStagedForSession(devmindPath: string, sessionId: string): void;
+/** Appends one entry to the buffer (stamping `staged_at`) and returns the new pending count. */
 export declare function stageEntry(devmindPath: string, entry: StagedEntry): number;
+/** Appends one whole-file edit to the buffer (stamping `staged_at`) and returns the new pending count. */
+export declare function stageFileEdit(devmindPath: string, edit: StagedFileEdit): number;
+/**
+ * Replaces the buffer's entries wholesale, keeping `file_edits` untouched — used by
+ * `add_description` to persist a description written onto an already-staged entry (e.g. after
+ * a `commit_changes` rejection), since `readStaged` returns a fresh array each call and
+ * mutating it in memory has no effect until it's written back.
+ */
+export declare function overwriteStaged(devmindPath: string, entries: StagedEntry[]): void;
 export declare function clearStaged(devmindPath: string): void;
+/**
+ * Drops the newest staged entry for one node and returns it, or null if the node has none.
+ *
+ * Newest rather than all: the buffer can hold several edits to the same entity, and reverting is
+ * an undo of the last one. An entry removed here was never committed, so nothing else has to be
+ * unwound — there is no history row yet for it to have written.
+ */
+export declare function removeLastStagedEntry(devmindPath: string, nodeId: string): StagedEntry | null;
+/** Resolves an entry's raw node_id to the canonical `{repo}/relpath#symbol` form. Exported so
+ * the commit_changes gate can check "does this node already exist" using the exact same
+ * canonicalization commitStagedChanges itself uses — a mismatch there would let a node the
+ * gate thinks is new slip through uncommitted, or block one that's actually already described. */
+export declare function resolveEntryId(db: DevMindDatabase, entry: StagedEntry): string;
 export interface CommitSummary {
     nodes: number;
     history_entries: number;
@@ -35,9 +113,16 @@ export interface CommitSummary {
  *            auto-creating any missing target nodes. Only the staged nodes' own outbound edges
  *            are recomputed; every other node's edges are left intact.
  *
+ * `reasoning` is ONE object covering the whole batch — every entry in one commit serves one
+ * request, so it is asked for once here rather than repeated on every staged entry. Kept as an
+ * object (not pre-formatted) all the way to `updateHistory`, since the configured-developer
+ * override only fires on the object form.
+ *
  * Idempotent: re-running the same batch yields the same graph (upsert + INSERT OR IGNORE +
  * clear-then-resolve). Callers should clear the buffer only after this returns successfully.
  */
-export declare function commitStagedChanges(db: DevMindDatabase, devmindPath: string, entries: StagedEntry[]): CommitSummary;
-/** Builds a short workflow-step summary from a batch of staged entries' `what_changed` reasoning. */
-export declare function summarizeEntriesForWorkflow(entries: StagedEntry[]): string;
+export declare function commitStagedChanges(db: DevMindDatabase, devmindPath: string, entries: StagedEntry[], reasoning: string | ReasoningObject): Promise<CommitSummary>;
+/** Builds a short workflow-step/activity summary for a commit. The commit's own `reasoning`
+ * (one object covering the whole batch) is authoritative when it has a `what_changed`; falls
+ * back to naming the staged entities for a bare-string reasoning. */
+export declare function summarizeEntriesForWorkflow(entries: StagedEntry[], reasoning: string | ReasoningObject): string;