flavor-code 1.2.13 → 1.2.15

package/README.md

@@ -32,11 +32,13 @@ Flavor Code connects to OpenAI, Anthropic, or compatible services and works with
 | | Capability | What you get |
 | --- | --- | --- |
 | 🖥️ | **One runtime, three entry points** | CLI, Electron, and VS Code share model configuration, sessions, and tooling |
-| 🧭 | **Controlled progress on complex tasks** | Task plans, sub-agents, steering, follow-ups, `/loop`, and `/goal` |
+| 🧭 | **Controlled progress on complex tasks** | Task plans, sub-agents, steering, follow-ups, `/loop`, `/goal`, and conflict-safe parallel execution (tasks owning overlapping files run serially) |
 | ⏪ | **Traceable, resumable results** | Full timeline, checkpoints, rewind, traces, diffs, and failure audits |
 | 🧠 | **Local long-term context** | Memory, Skills, plugins, and project guides stored on your machine |
 | 🔎 | **Code graph navigation** | A local AST code-graph index (`.flavor/astgraph/`) powers `ast_search`/`ast_callers`/`ast_impact` queries for precise symbol lookup and reachability tracing |
+| 🌿 | **Git-native workflows** | `/commit` drafts a Conventional-Commits message for staged changes and commits after confirmation; `/review` audits uncommitted changes; the read-only `GitHistory` tool explains when and why code changed |
 | 🎨 | **E2E requirement-to-delivery** | From a rough requirement or a design export to a delivered product: PRD, interactive prototype, visual implementation, API integration, autonomous acceptance, and scored delivery (Electron only) |
+| 🔁 | **Bounded self-improvement** | Repeated tool failures are captured, deduped, and proposed as suggestions; fixes ship as sandbox-verified plugins or as learned guardrail rules injected into future prompts, with run trends and rule management (`/evolve`) |
 | 🛡️ | **Clear permission boundaries** | Independent control over read, write, Shell, network, and destructive actions; Docker supported |
 
 ## Quick Start
@@ -154,11 +156,16 @@ Common commands:
 | `/mcp` | View and manage MCP servers |
 | `/loop <goal>` | Run an autonomous loop with verification |
 | `/goal <objective>` | Run the plan, execute, adversarial-review workflow |
+| `/commit [hint]` | Draft a Conventional-Commits message for staged changes and commit after confirmation |
+| `/review [focus]` | Review uncommitted changes for bugs and risks before committing |
+| `/evolve <signals\|suggest\|improve ...>` | Self-improvement loop: review repeated tool failures, scaffold fix plugins, manage run trends and learned guardrail rules, verify and hot-reload |
 | `/pals`, `/chat`, `/co-work` | Discover and collaborate with other local CLI instances |
 | `/audit` | View tool failure audits |
 
 You can submit steering or queue follow-ups while a run is in progress; once the current model response finishes, the task picks up new instructions at safe boundaries.
 
+`/commit` and `/review` use the cheap sub-agent model and degrade gracefully when it is unavailable. Session checkpoints are tagged with the current git state (`branch@sha`), so `/tree` shows what the workspace looked like at each node.
+
 #### CLI pals and cross-project work
 
 Interactive CLI instances on the same Windows or macOS user account can collaborate over local-only IPC (Windows named pipes or Unix sockets; no TCP fallback). Give each window a memorable alias:
@@ -261,6 +268,7 @@ Project runtime data lives under `.flavor/`:
 ├── memory/           # Long-term memory
 ├── traces/           # Optional execution traces
 ├── audit.jsonl       # Tool failure audits
+├── evolve/           # Self-improvement signals and run reflections
 ├── skills/           # Project skills
 └── plugins/          # Project plugins
 ```

package/README.zh-CN.md

@@ -32,11 +32,13 @@ Flavor Code 接入 OpenAI、Anthropic 或兼容服务，在受控工作区内使
 | | 能力 | 你得到什么 |
 | --- | --- | --- |
 | 🖥️ | **一个运行时，三个入口** | CLI、Electron 与 VS Code 共享模型配置、会话和工具能力 |
-| 🧭 | **复杂任务可控推进** | 任务计划、子 Agent、steering、follow-up、`/loop` 和 `/goal` |
+| 🧭 | **复杂任务可控推进** | 任务计划、子 Agent、steering、follow-up、`/loop`、`/goal`，并行任务自动避免写冲突（拥有重叠文件的任务串行执行） |
 | ⏪ | **结果可追溯、可恢复** | 完整时间线、checkpoint、rewind、trace、Diff 和失败审计 |
 | 🧠 | **本地长期上下文** | 记忆、Skill、插件和项目指南均保存在本机 |
 | 🔎 | **代码图导航** | 本地 AST 代码图索引（`.flavor/astgraph/`），通过 `ast_search`/`ast_callers`/`ast_impact` 等查询精确定位符号、追踪可达性 |
+| 🌿 | **Git 原生工作流** | `/commit` 为暂存改动生成 Conventional Commits 提交信息并确认提交；`/review` 审查未提交改动；只读 `GitHistory` 工具回答“这段代码为什么是这样” |
 | 🎨 | **E2E 需求到交付** | 从粗需求或设计稿到可交付产品：PRD、交互原型、视觉还原、接口联调、自主验收与评分交付（仅 Electron） |
+| 🔁 | **有界自进化** | 重复的工具失败被捕获、去重并形成建议；修复以沙箱验证过的插件形式落地，或沉淀为注入后续提示词的 guardrail 规则，并支持运行趋势与规则管理（`/evolve`） |
 | 🛡️ | **明确的权限边界** | 分别控制读、写、Shell、网络和破坏性操作，也可使用 Docker |
 
 ## 快速开始
@@ -154,11 +156,16 @@ OAuth PKCE 的运行时行为与配置约定见 [PKCE 规范](./docs/specs/pkce-
 | `/mcp` | 查看和管理 MCP 服务 |
 | `/loop <goal>` | 运行带验证的自治循环 |
 | `/goal <objective>` | 运行规划、执行、对抗审查流程 |
+| `/commit [hint]` | 为暂存改动生成 Conventional Commits 提交信息，确认后提交 |
+| `/review [focus]` | 提交前审查未提交改动的缺陷与风险 |
+| `/evolve <signals\|suggest\|improve ...>` | 自进化循环：查看重复工具失败、脚手架修复插件、管理运行趋势与 guardrail 规则、验证并热重载 |
 | `/pals`、`/chat`、`/co-work` | 发现并协作其他本机 CLI 实例 |
 | `/audit` | 查看工具失败审计 |
 
 运行中可以提交 steering 或排队 follow-up；当前模型响应结束后，任务会在安全边界处接收新指令。
 
+`/commit` 与 `/review` 使用廉价子 Agent 模型，模型不可用时优雅降级。会话 checkpoint 会标记当前 git 状态（`branch@sha`），`/tree` 可以看到每个节点对应的工作区现场。
+
 #### CLI Pals 与跨项目协作
 
 同一 Windows 或 macOS 用户下的交互式 CLI 可以通过纯本地 IPC 协作（Windows named pipe 或 Unix socket，不回退到 TCP）。先给每个窗口一个容易识别的别名：
@@ -261,6 +268,7 @@ Skill 是带有 YAML 头信息的 `SKILL.md`，放在 `.flavor/skills/<name>/`
 ├── memory/           # 长期记忆
 ├── traces/           # 可选执行 trace
 ├── audit.jsonl       # 工具失败审计
+├── evolve/           # 自进化信号与运行评估记录
 ├── skills/           # 项目 Skill
 └── plugins/          # 项目插件
 ```

package/dist/agent/planner.d.ts

@@ -6,6 +6,7 @@ export declare const TaskNodeSchema: z.ZodObject<{
     dependencies: z.ZodArray<z.ZodString>;
     expectedOutputs: z.ZodArray<z.ZodString>;
     verification: z.ZodArray<z.ZodString>;
+    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export declare const TaskGraphSchema: z.ZodObject<{
     nodes: z.ZodArray<z.ZodObject<{
@@ -14,6 +15,7 @@ export declare const TaskGraphSchema: z.ZodObject<{
         dependencies: z.ZodArray<z.ZodString>;
         expectedOutputs: z.ZodArray<z.ZodString>;
         verification: z.ZodArray<z.ZodString>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TaskNode = z.infer<typeof TaskNodeSchema>;

package/dist/{app-Z3YWFIBB.js → app-3KW2FTVJ.js}

@@ -15,8 +15,8 @@ import {
   packageVersion,
   redactErrorText,
   transcriptReducer
-} from "./chunk-Y5MZDG7I.js";
-import "./chunk-XFCJXRJ2.js";
+} from "./chunk-5TG3E2EJ.js";
+import "./chunk-IG4Z23CL.js";
 import {
   Box_default,
   ClockContext,

package/dist/astgraph/db.mjs

@@ -1,237 +1,237 @@
-// astgraph graph database — SQLite-backed node/edge graph (codegraph-inspired).
-// Uses node:sqlite with WAL mode so concurrent readers never block on a writer.
-
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { DatabaseSync } from "node:sqlite";
-
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS schema_versions (
-    version INTEGER PRIMARY KEY,
-    applied_at INTEGER NOT NULL,
-    description TEXT
-);
-
-CREATE TABLE IF NOT EXISTS files (
-    path TEXT PRIMARY KEY,
-    content_hash TEXT NOT NULL,
-    language TEXT NOT NULL,
-    size INTEGER NOT NULL,
-    modified_at INTEGER NOT NULL DEFAULT 0,
-    indexed_at INTEGER NOT NULL DEFAULT 0,
-    node_count INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS nodes (
-    id TEXT PRIMARY KEY,
-    kind TEXT NOT NULL,
-    name TEXT NOT NULL,
-    qualified_name TEXT NOT NULL,
-    file_path TEXT NOT NULL,
-    language TEXT NOT NULL,
-    start_line INTEGER NOT NULL,
-    end_line INTEGER NOT NULL,
-    signature TEXT,
-    docstring TEXT,
-    is_exported INTEGER NOT NULL DEFAULT 0,
-    is_async INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS edges (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    source TEXT NOT NULL,
-    target TEXT NOT NULL,
-    kind TEXT NOT NULL,
-    line INTEGER,
-    col INTEGER,
-    FOREIGN KEY (source) REFERENCES nodes(id) ON DELETE CASCADE,
-    FOREIGN KEY (target) REFERENCES nodes(id) ON DELETE CASCADE
-);
-
-CREATE TABLE IF NOT EXISTS unresolved_refs (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    from_node_id TEXT,
-    reference_name TEXT NOT NULL,
-    reference_kind TEXT NOT NULL,
-    line INTEGER NOT NULL,
-    col INTEGER NOT NULL,
-    file_path TEXT NOT NULL DEFAULT '',
-    module_specifier TEXT,
-    status TEXT NOT NULL DEFAULT 'pending',
-    FOREIGN KEY (from_node_id) REFERENCES nodes(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
-CREATE INDEX IF NOT EXISTS idx_nodes_lower_name ON nodes(lower(name));
-CREATE INDEX IF NOT EXISTS idx_nodes_file_path ON nodes(file_path);
-CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
-CREATE INDEX IF NOT EXISTS idx_edges_source_kind ON edges(source, kind);
-CREATE INDEX IF NOT EXISTS idx_edges_target_kind ON edges(target, kind);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_edges_identity
-  ON edges(source, target, kind, IFNULL(line, -1), IFNULL(col, -1));
-CREATE INDEX IF NOT EXISTS idx_unresolved_from ON unresolved_refs(from_node_id);
-CREATE INDEX IF NOT EXISTS idx_unresolved_name ON unresolved_refs(reference_name);
-
-CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
-    name,
-    qualified_name,
-    signature,
-    docstring,
-    content='nodes',
-    content_rowid='rowid'
-);
-
-CREATE TRIGGER IF NOT EXISTS nodes_ai AFTER INSERT ON nodes BEGIN
-    INSERT INTO nodes_fts(rowid, name, qualified_name, signature, docstring)
-    VALUES (NEW.rowid, NEW.name, NEW.qualified_name, NEW.signature, NEW.docstring);
-END;
-
-CREATE TRIGGER IF NOT EXISTS nodes_ad AFTER DELETE ON nodes BEGIN
-    INSERT INTO nodes_fts(nodes_fts, rowid, name, qualified_name, signature, docstring)
-    VALUES ('delete', OLD.rowid, OLD.name, OLD.qualified_name, OLD.signature, OLD.docstring);
-END;
-
-CREATE TRIGGER IF NOT EXISTS nodes_au AFTER UPDATE ON nodes BEGIN
-    INSERT INTO nodes_fts(nodes_fts, rowid, name, qualified_name, signature, docstring)
-    VALUES ('delete', OLD.rowid, OLD.name, OLD.qualified_name, OLD.signature, OLD.docstring);
-    INSERT INTO nodes_fts(rowid, name, qualified_name, signature, docstring)
-    VALUES (NEW.rowid, NEW.name, NEW.qualified_name, NEW.signature, NEW.docstring);
-END;
-
-CREATE TABLE IF NOT EXISTS project_metadata (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL,
-    updated_at INTEGER NOT NULL
-);
-`;
-
-/** Open (creating when absent) the graph database at `path`. Returns a DatabaseSync. */
-export function openDb(path) {
-  if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
-  const db = new DatabaseSync(path);
-  db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA foreign_keys = ON");
-  db.exec("PRAGMA synchronous = NORMAL");
-  db.exec(SCHEMA);
-  const version = db.prepare("SELECT COUNT(*) AS count FROM schema_versions").get();
-  if (version.count === 0) {
-    db.prepare("INSERT INTO schema_versions(version, applied_at, description) VALUES (?, ?, ?)")
-      .run(1, Date.now(), "Initial astgraph schema");
-  }
-  return db;
-}
-
-/** Insert or replace the tracking record for one source file. */
-export function upsertFileRecord(db, record) {
-  db.prepare(`
-    INSERT INTO files(path, content_hash, language, size, modified_at, indexed_at, node_count)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(path) DO UPDATE SET
-      content_hash = excluded.content_hash,
-      language = excluded.language,
-      size = excluded.size,
-      modified_at = excluded.modified_at,
-      indexed_at = excluded.indexed_at,
-      node_count = excluded.node_count
-  `).run(
-    record.path, record.contentHash, record.language, record.size,
-    record.modifiedAt ?? Date.now(), record.indexedAt ?? Date.now(), record.nodeCount ?? 0,
-  );
-}
-
-/** Read the tracking record for one source file, or undefined when absent. */
-export function getFileRecord(db, path) {
-  const row = db.prepare("SELECT * FROM files WHERE path = ?").get(path);
-  if (row === undefined) return undefined;
-  return {
-    path: row.path, contentHash: row.content_hash, language: row.language,
-    size: row.size, modifiedAt: row.modified_at, indexedAt: row.indexed_at,
-    nodeCount: row.node_count,
-  };
-}
-
-/** Delete a file record; nodes cascade (and with them edges + refs + FTS rows). */
-export function deleteFileRecord(db, path) {
-  db.prepare("DELETE FROM nodes WHERE file_path = ?").run(path);
-  db.prepare("DELETE FROM files WHERE path = ?").run(path);
-}
-
-/**
- * Replace every node belonging to a file. Runs inside one transaction; the FTS
- * triggers keep nodes_fts in sync.
- */
-export function replaceNodes(db, filePath, nodes) {
-  const insert = db.prepare(`
-    INSERT OR REPLACE INTO nodes(
-      id, kind, name, qualified_name, file_path, language,
-      start_line, end_line, signature, docstring, is_exported, is_async
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `);
-  const clear = db.prepare("DELETE FROM nodes WHERE file_path = ?");
-  db.exec("BEGIN");
-  try {
-    clear.run(filePath);
-    for (const node of nodes) {
-      insert.run(
-        node.id, node.kind, node.name, node.qualifiedName, node.filePath, node.language,
-        node.startLine, node.endLine, node.signature ?? null, node.docstring ?? null,
-        node.isExported ? 1 : 0, node.isAsync ? 1 : 0,
-      );
-    }
-    db.exec("COMMIT");
-  } catch (error) {
-    db.exec("ROLLBACK");
-    throw error;
-  }
-}
-
-/** Insert one edge; duplicate (source, target, kind, line, col) rows are ignored. */
-export function insertEdge(db, edge) {
-  db.prepare(`
-    INSERT OR IGNORE INTO edges(source, target, kind, line, col) VALUES (?, ?, ?, ?, ?)
-  `).run(edge.source, edge.target, edge.kind, edge.line ?? null, edge.col ?? null);
-}
-
-/** Delete every edge whose source OR target belongs to a file. */
-export function deleteEdgesForFile(db, filePath) {
-  db.prepare(`
-    DELETE FROM edges WHERE source IN (SELECT id FROM nodes WHERE file_path = ?)
-       OR target IN (SELECT id FROM nodes WHERE file_path = ?)
-  `).run(filePath, filePath);
-}
-
-/** Insert one unresolved cross-file reference (status 'pending'). */
-export function insertUnresolvedRef(db, ref) {
-  db.prepare(`
-    INSERT INTO unresolved_refs(from_node_id, reference_name, reference_kind, line, col, file_path, module_specifier, status)
-    VALUES (?, ?, ?, ?, ?, ?, ?, 'pending')
-  `).run(ref.fromNodeId, ref.referenceName, ref.referenceKind, ref.line, ref.col, ref.filePath, ref.moduleSpecifier ?? null);
-}
-
-/** Delete every unresolved reference originating from a file. */
-export function deleteUnresolvedRefsForFile(db, filePath) {
-  db.prepare("DELETE FROM unresolved_refs WHERE file_path = ?").run(filePath);
-}
-
-/** Summary counters used by /ast status. */
-export function stats(db) {
-  const files = db.prepare("SELECT COUNT(*) AS count FROM files").get().count;
-  const nodes = db.prepare("SELECT COUNT(*) AS count FROM nodes").get().count;
-  const edges = db.prepare("SELECT COUNT(*) AS count FROM edges").get().count;
-  const unresolved = db.prepare("SELECT COUNT(*) AS count FROM unresolved_refs WHERE status = 'pending'").get().count;
-  return { files, nodes, edges, unresolved };
-}
-
-/** Store a provenance metadata value. */
-export function setMetadata(db, key, value) {
-  db.prepare(`
-    INSERT INTO project_metadata(key, value, updated_at) VALUES (?, ?, ?)
-    ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
-  `).run(key, value, Date.now());
-}
-
-/** Read a provenance metadata value, or undefined when absent. */
-export function getMetadata(db, key) {
-  const row = db.prepare("SELECT value FROM project_metadata WHERE key = ?").get(key);
-  return row?.value;
-}
+// astgraph graph database — SQLite-backed node/edge graph (codegraph-inspired).
+// Uses node:sqlite with WAL mode so concurrent readers never block on a writer.
+
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS schema_versions (
+    version INTEGER PRIMARY KEY,
+    applied_at INTEGER NOT NULL,
+    description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS files (
+    path TEXT PRIMARY KEY,
+    content_hash TEXT NOT NULL,
+    language TEXT NOT NULL,
+    size INTEGER NOT NULL,
+    modified_at INTEGER NOT NULL DEFAULT 0,
+    indexed_at INTEGER NOT NULL DEFAULT 0,
+    node_count INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS nodes (
+    id TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    name TEXT NOT NULL,
+    qualified_name TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    language TEXT NOT NULL,
+    start_line INTEGER NOT NULL,
+    end_line INTEGER NOT NULL,
+    signature TEXT,
+    docstring TEXT,
+    is_exported INTEGER NOT NULL DEFAULT 0,
+    is_async INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source TEXT NOT NULL,
+    target TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    line INTEGER,
+    col INTEGER,
+    FOREIGN KEY (source) REFERENCES nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (target) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS unresolved_refs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_node_id TEXT,
+    reference_name TEXT NOT NULL,
+    reference_kind TEXT NOT NULL,
+    line INTEGER NOT NULL,
+    col INTEGER NOT NULL,
+    file_path TEXT NOT NULL DEFAULT '',
+    module_specifier TEXT,
+    status TEXT NOT NULL DEFAULT 'pending',
+    FOREIGN KEY (from_node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
+CREATE INDEX IF NOT EXISTS idx_nodes_lower_name ON nodes(lower(name));
+CREATE INDEX IF NOT EXISTS idx_nodes_file_path ON nodes(file_path);
+CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
+CREATE INDEX IF NOT EXISTS idx_edges_source_kind ON edges(source, kind);
+CREATE INDEX IF NOT EXISTS idx_edges_target_kind ON edges(target, kind);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_edges_identity
+  ON edges(source, target, kind, IFNULL(line, -1), IFNULL(col, -1));
+CREATE INDEX IF NOT EXISTS idx_unresolved_from ON unresolved_refs(from_node_id);
+CREATE INDEX IF NOT EXISTS idx_unresolved_name ON unresolved_refs(reference_name);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+    name,
+    qualified_name,
+    signature,
+    docstring,
+    content='nodes',
+    content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS nodes_ai AFTER INSERT ON nodes BEGIN
+    INSERT INTO nodes_fts(rowid, name, qualified_name, signature, docstring)
+    VALUES (NEW.rowid, NEW.name, NEW.qualified_name, NEW.signature, NEW.docstring);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_ad AFTER DELETE ON nodes BEGIN
+    INSERT INTO nodes_fts(nodes_fts, rowid, name, qualified_name, signature, docstring)
+    VALUES ('delete', OLD.rowid, OLD.name, OLD.qualified_name, OLD.signature, OLD.docstring);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_au AFTER UPDATE ON nodes BEGIN
+    INSERT INTO nodes_fts(nodes_fts, rowid, name, qualified_name, signature, docstring)
+    VALUES ('delete', OLD.rowid, OLD.name, OLD.qualified_name, OLD.signature, OLD.docstring);
+    INSERT INTO nodes_fts(rowid, name, qualified_name, signature, docstring)
+    VALUES (NEW.rowid, NEW.name, NEW.qualified_name, NEW.signature, NEW.docstring);
+END;
+
+CREATE TABLE IF NOT EXISTS project_metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+`;
+
+/** Open (creating when absent) the graph database at `path`. Returns a DatabaseSync. */
+export function openDb(path) {
+  if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA synchronous = NORMAL");
+  db.exec(SCHEMA);
+  const version = db.prepare("SELECT COUNT(*) AS count FROM schema_versions").get();
+  if (version.count === 0) {
+    db.prepare("INSERT INTO schema_versions(version, applied_at, description) VALUES (?, ?, ?)")
+      .run(1, Date.now(), "Initial astgraph schema");
+  }
+  return db;
+}
+
+/** Insert or replace the tracking record for one source file. */
+export function upsertFileRecord(db, record) {
+  db.prepare(`
+    INSERT INTO files(path, content_hash, language, size, modified_at, indexed_at, node_count)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(path) DO UPDATE SET
+      content_hash = excluded.content_hash,
+      language = excluded.language,
+      size = excluded.size,
+      modified_at = excluded.modified_at,
+      indexed_at = excluded.indexed_at,
+      node_count = excluded.node_count
+  `).run(
+    record.path, record.contentHash, record.language, record.size,
+    record.modifiedAt ?? Date.now(), record.indexedAt ?? Date.now(), record.nodeCount ?? 0,
+  );
+}
+
+/** Read the tracking record for one source file, or undefined when absent. */
+export function getFileRecord(db, path) {
+  const row = db.prepare("SELECT * FROM files WHERE path = ?").get(path);
+  if (row === undefined) return undefined;
+  return {
+    path: row.path, contentHash: row.content_hash, language: row.language,
+    size: row.size, modifiedAt: row.modified_at, indexedAt: row.indexed_at,
+    nodeCount: row.node_count,
+  };
+}
+
+/** Delete a file record; nodes cascade (and with them edges + refs + FTS rows). */
+export function deleteFileRecord(db, path) {
+  db.prepare("DELETE FROM nodes WHERE file_path = ?").run(path);
+  db.prepare("DELETE FROM files WHERE path = ?").run(path);
+}
+
+/**
+ * Replace every node belonging to a file. Runs inside one transaction; the FTS
+ * triggers keep nodes_fts in sync.
+ */
+export function replaceNodes(db, filePath, nodes) {
+  const insert = db.prepare(`
+    INSERT OR REPLACE INTO nodes(
+      id, kind, name, qualified_name, file_path, language,
+      start_line, end_line, signature, docstring, is_exported, is_async
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const clear = db.prepare("DELETE FROM nodes WHERE file_path = ?");
+  db.exec("BEGIN");
+  try {
+    clear.run(filePath);
+    for (const node of nodes) {
+      insert.run(
+        node.id, node.kind, node.name, node.qualifiedName, node.filePath, node.language,
+        node.startLine, node.endLine, node.signature ?? null, node.docstring ?? null,
+        node.isExported ? 1 : 0, node.isAsync ? 1 : 0,
+      );
+    }
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+/** Insert one edge; duplicate (source, target, kind, line, col) rows are ignored. */
+export function insertEdge(db, edge) {
+  db.prepare(`
+    INSERT OR IGNORE INTO edges(source, target, kind, line, col) VALUES (?, ?, ?, ?, ?)
+  `).run(edge.source, edge.target, edge.kind, edge.line ?? null, edge.col ?? null);
+}
+
+/** Delete every edge whose source OR target belongs to a file. */
+export function deleteEdgesForFile(db, filePath) {
+  db.prepare(`
+    DELETE FROM edges WHERE source IN (SELECT id FROM nodes WHERE file_path = ?)
+       OR target IN (SELECT id FROM nodes WHERE file_path = ?)
+  `).run(filePath, filePath);
+}
+
+/** Insert one unresolved cross-file reference (status 'pending'). */
+export function insertUnresolvedRef(db, ref) {
+  db.prepare(`
+    INSERT INTO unresolved_refs(from_node_id, reference_name, reference_kind, line, col, file_path, module_specifier, status)
+    VALUES (?, ?, ?, ?, ?, ?, ?, 'pending')
+  `).run(ref.fromNodeId, ref.referenceName, ref.referenceKind, ref.line, ref.col, ref.filePath, ref.moduleSpecifier ?? null);
+}
+
+/** Delete every unresolved reference originating from a file. */
+export function deleteUnresolvedRefsForFile(db, filePath) {
+  db.prepare("DELETE FROM unresolved_refs WHERE file_path = ?").run(filePath);
+}
+
+/** Summary counters used by /ast status. */
+export function stats(db) {
+  const files = db.prepare("SELECT COUNT(*) AS count FROM files").get().count;
+  const nodes = db.prepare("SELECT COUNT(*) AS count FROM nodes").get().count;
+  const edges = db.prepare("SELECT COUNT(*) AS count FROM edges").get().count;
+  const unresolved = db.prepare("SELECT COUNT(*) AS count FROM unresolved_refs WHERE status = 'pending'").get().count;
+  return { files, nodes, edges, unresolved };
+}
+
+/** Store a provenance metadata value. */
+export function setMetadata(db, key, value) {
+  db.prepare(`
+    INSERT INTO project_metadata(key, value, updated_at) VALUES (?, ?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+  `).run(key, value, Date.now());
+}
+
+/** Read a provenance metadata value, or undefined when absent. */
+export function getMetadata(db, key) {
+  const row = db.prepare("SELECT value FROM project_metadata WHERE key = ?").get(key);
+  return row?.value;
+}