flavor-code 1.2.11 → 1.2.14

package/README.md

@@ -35,7 +35,9 @@ Flavor Code connects to OpenAI, Anthropic, or compatible services and works with
 | 🧭 | **Controlled progress on complex tasks** | Task plans, sub-agents, steering, follow-ups, `/loop`, and `/goal` |
 | ⏪ | **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 |
 | 🎨 | **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 plugins that must pass sandbox verification and the test suite before hot-reload (`/evolve`) |
 | 🛡️ | **Clear permission boundaries** | Independent control over read, write, Shell, network, and destructive actions; Docker supported |
 
 ## Quick Start
@@ -152,41 +154,42 @@ Common commands:
 | `/memory`, `/remember`, `/forget`, `/forget-cold` | Manage long-term memory; `/forget-cold` purges cold entries and their files |
 | `/mcp` | View and manage MCP servers |
 | `/loop <goal>` | Run an autonomous loop with verification |
-| `/goal <objective>` | Run the plan, execute, adversarial-review workflow |
-| `/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.
-
-#### 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:
-
-```bash
-# terminal A, in project A
-flavor --pal-name A
-
-# terminal B, in project B
-flavor --pal-name B
-```
-
-Useful commands:
-
-```text
-/pals                              # aliases and per-process UUIDs
-/pals --verbose                    # also show project paths and timestamps
-/pals rename api                   # rename this active instance
-/chat B Update the API and tests   # deliver to B and start its agent safely
-/co-work B Upgrade B, then adapt A # negotiate one plan before parallel work
-/co-work status [co-work-uuid]
-/co-work cancel <co-work-uuid> [reason]
-```
-
-`/chat` is bidirectional and task-oriented. If B is idle, the attributed message starts a normal model turn; if B is already running, it becomes steering, or a follow-up when another local submission is pending. Remote text is converted to a safe non-slash prompt, so `/exit`-like text is not dispatched as a local command. B can answer with `/chat A ...`.
-
-`/co-work` first places both agents in planning and waits for both to accept the same hashed plan and declare READY. Early READY intents are retained, and only the broker's exactly-once START event opens parallel execution. Each agent works only in its own project, receives only its assigned tasks, and reports bounded completion evidence. The broker-selected integration owner verifies all assertions and emits END or FAIL through `CoWorkIntegrate`. Communication uses authenticated, bounded local IPC with no TCP listener; peer input cannot approve tools or access the other workspace. UUID/alias routing and the protocol already support a third active client; durable artifact exchange, broker-restart journaling/recovery, and large-group coordination are later hardening work. See the [CLI pals specification](./docs/specs/2026-08-14-cli-pals-cowork.md).
-
-### Electron Desktop
+| `/goal <objective>` | Run the plan, execute, adversarial-review workflow |
+| `/evolve <signals\|suggest\|improve ...>` | Self-improvement loop: review repeated tool failures, scaffold fix plugins, verify and hot-reload them |
+| `/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.
+
+#### 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:
+
+```bash
+# terminal A, in project A
+flavor --pal-name A
+
+# terminal B, in project B
+flavor --pal-name B
+```
+
+Useful commands:
+
+```text
+/pals                              # aliases and per-process UUIDs
+/pals --verbose                    # also show project paths and timestamps
+/pals rename api                   # rename this active instance
+/chat B Update the API and tests   # deliver to B and start its agent safely
+/co-work B Upgrade B, then adapt A # negotiate one plan before parallel work
+/co-work status [co-work-uuid]
+/co-work cancel <co-work-uuid> [reason]
+```
+
+`/chat` is bidirectional and task-oriented. If B is idle, the attributed message starts a normal model turn; if B is already running, it becomes steering, or a follow-up when another local submission is pending. Remote text is converted to a safe non-slash prompt, so `/exit`-like text is not dispatched as a local command. B can answer with `/chat A ...`.
+
+`/co-work` first places both agents in planning and waits for both to accept the same hashed plan and declare READY. Early READY intents are retained, and only the broker's exactly-once START event opens parallel execution. Each agent works only in its own project, receives only its assigned tasks, and reports bounded completion evidence. The broker-selected integration owner verifies all assertions and emits END or FAIL through `CoWorkIntegrate`. Communication uses authenticated, bounded local IPC with no TCP listener; peer input cannot approve tools or access the other workspace. UUID/alias routing and the protocol already support a third active client; durable artifact exchange, broker-restart journaling/recovery, and large-group coordination are later hardening work. See the [CLI pals specification](./docs/specs/2026-08-14-cli-pals-cowork.md).
+
+### Electron Desktop
 
 ```bash
 npm run desktop:dev      # dev mode
@@ -260,6 +263,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

@@ -35,7 +35,9 @@ Flavor Code 接入 OpenAI、Anthropic 或兼容服务，在受控工作区内使
 | 🧭 | **复杂任务可控推进** | 任务计划、子 Agent、steering、follow-up、`/loop` 和 `/goal` |
 | ⏪ | **结果可追溯、可恢复** | 完整时间线、checkpoint、rewind、trace、Diff 和失败审计 |
 | 🧠 | **本地长期上下文** | 记忆、Skill、插件和项目指南均保存在本机 |
+| 🔎 | **代码图导航** | 本地 AST 代码图索引（`.flavor/astgraph/`），通过 `ast_search`/`ast_callers`/`ast_impact` 等查询精确定位符号、追踪可达性 |
 | 🎨 | **E2E 需求到交付** | 从粗需求或设计稿到可交付产品：PRD、交互原型、视觉还原、接口联调、自主验收与评分交付（仅 Electron） |
+| 🔁 | **有界自进化** | 重复的工具失败被捕获、去重并形成建议；修复以插件形式落地，必须通过沙箱验证与测试套件后才能热重载（`/evolve`） |
 | 🛡️ | **明确的权限边界** | 分别控制读、写、Shell、网络和破坏性操作，也可使用 Docker |
 
 ## 快速开始
@@ -152,41 +154,42 @@ OAuth PKCE 的运行时行为与配置约定见 [PKCE 规范](./docs/specs/pkce-
 | `/memory`、`/remember`、`/forget`、`/forget-cold` | 管理长期记忆；`/forget-cold` 清空 cold 记忆及其文件 |
 | `/mcp` | 查看和管理 MCP 服务 |
 | `/loop <goal>` | 运行带验证的自治循环 |
-| `/goal <objective>` | 运行规划、执行、对抗审查流程 |
-| `/pals`、`/chat`、`/co-work` | 发现并协作其他本机 CLI 实例 |
-| `/audit` | 查看工具失败审计 |
-
-运行中可以提交 steering 或排队 follow-up；当前模型响应结束后，任务会在安全边界处接收新指令。
-
-#### CLI Pals 与跨项目协作
-
-同一 Windows 或 macOS 用户下的交互式 CLI 可以通过纯本地 IPC 协作（Windows named pipe 或 Unix socket，不回退到 TCP）。先给每个窗口一个容易识别的别名：
-
-```bash
-# 终端 A，位于项目 A
-flavor --pal-name A
-
-# 终端 B，位于项目 B
-flavor --pal-name B
-```
-
-常用命令：
-
-```text
-/pals                              # 查看别名和每进程 UUID
-/pals --verbose                    # 额外显示项目路径和时间
-/pals rename api                   # 重命名当前活动实例
-/chat B 更新 API 和测试             # 投递给 B，并安全启动其 Agent
-/co-work B 先升级 B，再兼容 A        # 先协商同一计划，再并行开工
-/co-work status [co-work-uuid]
-/co-work cancel <co-work-uuid> [reason]
-```
-
-`/chat` 支持双向任务通信。B 空闲时，带来源标识的消息会启动正常模型回合；B 正在运行时，消息会成为 steering；已有本地提交待运行时则成为 follow-up。远端文本会转换成安全的非斜杠 prompt，因此 `/exit` 一类文本不会被当成本地命令分派。B 可以用 `/chat A ...` 回复。
-
-`/co-work` 会先让双方进入规划，等待双方接受同一个哈希计划并声明 READY；较早的 READY 意图会被保留，只有 broker 恰好一次的 START 事件才会放行并行执行。每个 Agent 只在自己的项目内工作，只接收分配给自己的任务，并提交有界的完成证据。broker 指定的集成负责人会检查所有断言，再通过 `CoWorkIntegrate` 广播 END 或 FAIL。通信使用经过认证、有大小上限的本机 IPC，不开放 TCP 监听；peer 输入不能代替本机工具审批，也不能访问另一工作区。UUID/别名路由和协议已能支持第三个活动实例；持久化成果物交换、broker 重启日志与恢复、大规模多方协调属于后续强化。详见 [CLI Pals 规范](./docs/specs/2026-08-14-cli-pals-cowork.md)。
-
-### Electron 桌面端
+| `/goal <objective>` | 运行规划、执行、对抗审查流程 |
+| `/evolve <signals\|suggest\|improve ...>` | 自进化循环：查看重复工具失败、脚手架修复插件、验证并热重载 |
+| `/pals`、`/chat`、`/co-work` | 发现并协作其他本机 CLI 实例 |
+| `/audit` | 查看工具失败审计 |
+
+运行中可以提交 steering 或排队 follow-up；当前模型响应结束后，任务会在安全边界处接收新指令。
+
+#### CLI Pals 与跨项目协作
+
+同一 Windows 或 macOS 用户下的交互式 CLI 可以通过纯本地 IPC 协作（Windows named pipe 或 Unix socket，不回退到 TCP）。先给每个窗口一个容易识别的别名：
+
+```bash
+# 终端 A，位于项目 A
+flavor --pal-name A
+
+# 终端 B，位于项目 B
+flavor --pal-name B
+```
+
+常用命令：
+
+```text
+/pals                              # 查看别名和每进程 UUID
+/pals --verbose                    # 额外显示项目路径和时间
+/pals rename api                   # 重命名当前活动实例
+/chat B 更新 API 和测试             # 投递给 B，并安全启动其 Agent
+/co-work B 先升级 B，再兼容 A        # 先协商同一计划，再并行开工
+/co-work status [co-work-uuid]
+/co-work cancel <co-work-uuid> [reason]
+```
+
+`/chat` 支持双向任务通信。B 空闲时，带来源标识的消息会启动正常模型回合；B 正在运行时，消息会成为 steering；已有本地提交待运行时则成为 follow-up。远端文本会转换成安全的非斜杠 prompt，因此 `/exit` 一类文本不会被当成本地命令分派。B 可以用 `/chat A ...` 回复。
+
+`/co-work` 会先让双方进入规划，等待双方接受同一个哈希计划并声明 READY；较早的 READY 意图会被保留，只有 broker 恰好一次的 START 事件才会放行并行执行。每个 Agent 只在自己的项目内工作，只接收分配给自己的任务，并提交有界的完成证据。broker 指定的集成负责人会检查所有断言，再通过 `CoWorkIntegrate` 广播 END 或 FAIL。通信使用经过认证、有大小上限的本机 IPC，不开放 TCP 监听；peer 输入不能代替本机工具审批，也不能访问另一工作区。UUID/别名路由和协议已能支持第三个活动实例；持久化成果物交换、broker 重启日志与恢复、大规模多方协调属于后续强化。详见 [CLI Pals 规范](./docs/specs/2026-08-14-cli-pals-cowork.md)。
+
+### Electron 桌面端
 
 ```bash
 npm run desktop:dev      # 开发模式
@@ -260,6 +263,7 @@ Skill 是带有 YAML 头信息的 `SKILL.md`，放在 `.flavor/skills/<name>/`
 ├── memory/           # 长期记忆
 ├── traces/           # 可选执行 trace
 ├── audit.jsonl       # 工具失败审计
+├── evolve/           # 自进化信号与运行评估记录
 ├── skills/           # 项目 Skill
 └── plugins/          # 项目插件
 ```

package/dist/{app-MXWPZBEU.js → app-UJAGMKD5.js}

@@ -15,8 +15,8 @@ import {
   packageVersion,
   redactErrorText,
   transcriptReducer
-} from "./chunk-OT5XIN6G.js";
-import "./chunk-XFCJXRJ2.js";
+} from "./chunk-4YXDGGIC.js";
+import "./chunk-IG4Z23CL.js";
 import {
   Box_default,
   ClockContext,
@@ -1249,8 +1249,10 @@ function buildSlashCandidates(commands, plugins, skills) {
   for (const command of commands) {
     candidates.set(command.name, { name: command.name, kind: "command", description: command.description });
   }
-  for (const name of plugins) {
-    if (!candidates.has(name)) candidates.set(name, { name, kind: "plugin" });
+  for (const plugin of plugins) {
+    if (!candidates.has(plugin.name)) {
+      candidates.set(plugin.name, plugin.description === void 0 ? { name: plugin.name, kind: "plugin" } : { name: plugin.name, kind: "plugin", description: plugin.description });
+    }
   }
   for (const skill of skills) {
     if (!candidates.has(skill.name)) {

package/dist/astgraph/db.mjs

@@ -0,0 +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;
+}