progmune-runtime 2.1.0 → 2.1.1

package/README.md

@@ -0,0 +1,172 @@
+# Progmune Runtime（免序）
+
+**程序免疫学：约束引导的程序合成运行时**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+[![Stage: Technical Preview](https://img.shields.io/badge/Stage-Technical_Preview-orange)]()
+
+Progmune（免序）不是一个 AI 编程助手，而是一个面向生成式程序的免疫系统。它将大语言模型（LLM）从开放世界的代码生成器，降级为在程序真相层（IR）严格约束下的启发式搜索器，确保生成的代码不仅在符号和类型上正确，更在行为协议上合法。
+
+---
+
+## 目录
+
+- [核心命题](#核心命题ai-生成的程序必须具备免疫系统)
+- [架构概览](#架构概览一个会学习会记忆会防御的运行时)
+- [语义有效性级别 (SVL)](#语义有效性级别-svl)
+- [v2.1.0 新特性：抗体与快照](#v210-新特性抗体与快照)
+- [Semantic Observatory](#semantic-observatory语义观测台)
+- [快速开始](#快速开始)
+- [CLI 命令](#cli-命令)
+- [MCP 工具](#mcp-工具)
+- [全球免疫网络](#全球免疫网络-global-immune-network)
+- [许可证](#许可证)
+
+---
+
+## 核心命题：AI 生成的程序必须具备免疫系统
+
+LLM 在生成代码时会产生“幻觉”——调用不存在的函数、违反类型约束、跳过关键的业务步骤。传统的提示工程和事后校验无法根除这些问题，因为它们将 LLM 置于系统的中心，缺乏第一性原理的约束。
+
+Progmune 提出**程序免疫学（Program Immunology）**范式，为生成式程序建立一套可识别、可记忆、可进化的防御体系：
+
+1.  **天然免疫**：快速识别并拒绝违反符号存在性、类型兼容性和数据流规则的代码。
+2.  **获得性免疫**：从过去的失败案例中学习，生成特异性的防御规则，主动预防未来同类错误。
+3.  **免疫记忆**：将成功和失败的模式沉淀为结构化的知识，使系统随着使用持续进化，越用越可靠。
+
+**详细理论框架请参阅《[Program Immunology 白皮书](./WHITEPAPER.md)》。**
+
+---
+
+## 架构概览：一个会学习、会记忆、会防御的运行时
+
+Progmune 的架构受生物免疫系统启发，分为核心防御层：
+
+| 生物免疫系统 | 程序免疫 (Progmune) | 核心职责 |
+|:-------------|:--------------------|:---------|
+| **天然免疫** | **约束引擎** (IR + SVL-1~SVL-3) | 快速、自动地拒绝调用不存在的函数、类型错误和数据流问题。 |
+| **获得性免疫** | **语义状态图 (SSG)** | 通过可编程的状态机，精确拦截非法业务逻辑跃迁（如“未认证即签发令牌”）。 |
+| **免疫记忆** | **三层记忆 + Failure Corpus** | 工作记忆、情景记忆和语义记忆协同；失败基因组记录每次语义异常、修复路径和适应轨迹。 |
+| **抗体生成** | **Antibody Registry** | **v2.1.0 新增**：从失败中自动挖掘修复模式，生成 ACL-1~4 置信度分级的免疫规则。 |
+| **免疫观测** | **Semantic Observatory** | 终端原生语义观测工具——时间线、认知回放、状态机追踪、基因组热力图。 |
+
+---
+
+## v2.1.0 新特性：抗体与快照
+
+在 v2.1.0 版本中，Progmune 实现了从“被动拦截”到“主动防御”的跨越：
+
+*   **抗体注册表 (Antibody Registry)**：系统自动从 `Failure Corpus` 中提取修复模式。高置信度（ACL-4）的抗体可触发“免疫快跑”，绕过 LLM 直接应用验证过的修复路径。
+*   **语义快照引擎 (Snapshot Engine)**：在规划时自动捕获 IR 状态。支持通过 `diff` 命令对比不同时间点的 IR 差异，解决因环境漂移导致的生成失败。
+*   **BFS 协议修复**：SSG 验证器现在使用广度优先搜索寻找多步修复路径，能够自动补全复杂的协议缺失（如 `INIT` -> `EMAIL_OK` -> `PWD_HASHED`）。
+
+---
+
+## 语义有效性级别 (SVL)
+
+Progmune 定义了 AI 生成代码正确性的分层标准：
+
+| 级别 | 名称 | 保证 |
+|:-----|:-----|:-----|
+| SVL-1 | 符号存在性 | 绝不调用项目中不存在的函数 |
+| SVL-2 | 类型有效性 | 参数数量和类型严格匹配 |
+| SVL-3 | 数据流正确性 | 变量先声明后使用，无循环引用 |
+| SVL-4 | 协议合法性 | 业务步骤顺序必须遵守状态迁移规则 |
+
+---
+
+## 快速开始
+
+### 前置条件
+
+*   [Node.js](https://nodejs.org/) >= 18
+*   一个有效的 LLM API 密钥（DeepSeek 或 OpenAI 兼容接口）
+
+### 1. 安装
+
+```bash
+npm install -g progmune-runtime
+```
+
+### 2. 配置
+
+```bash
+npx progmune-runtime setup "你的API密钥"
+```
+
+### 3. 验证
+
+```bash
+npx progmune-runtime test
+```
+
+---
+
+## 许可证
+
+MIT License。
+
+Progmune 正在重新定义 AI 辅助编程——不是“让模型更聪明”，而是“让程序真相主导生成”。
+
+---
+
+# Progmune Runtime
+
+**Program Immunology: Constraint-Guided Program Synthesis Runtime**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+[![Stage: Technical Preview](https://img.shields.io/badge/Stage-Technical_Preview-orange)]()
+
+Progmune is not an AI programming assistant, but an immune system for generative programs. It demotes LLMs from open-world code generators to heuristic searchers strictly constrained by the Program Truth Layer (IR).
+
+---
+
+## v2.1.0 New Features: Antibodies & Snapshots
+
+v2.1.0 marks a major leap from "passive interception" to "active defense":
+
+*   **Antibody Registry**: Automatically extracts repair patterns from the `Failure Corpus`. High-confidence (ACL-4) antibodies trigger "Immune Fast-Path," bypassing the LLM to apply validated fixes directly.
+*   **Semantic Snapshot Engine**: Captures the exact IR state during planning. Supports `diff` commands to track IR evolution and debug environment drift.
+*   **BFS Protocol Repair**: The SSG validator now uses Breadth-First Search to find multi-hop repair paths, automatically filling complex protocol gaps.
+
+---
+
+## Architecture Overview
+
+| Biological Immune System | Program Immunology (Progmune) | Core Responsibility |
+|:-------------------------|:------------------------------|:--------------------|
+| **Innate Immunity**      | **Constraint Engine** (IR + SVL-1~3) | Rejects non-existent functions, type errors, and dataflow issues. |
+| **Adaptive Immunity**    | **Semantic State Graph (SSG)** | Intercepts illegal business logic transitions (e.g., "issue token before auth"). |
+| **Immune Memory**        | **Three-Layer Memory**        | Working, episodic, and semantic memory collaborate to make the system smarter with use. |
+| **Antibody Generation**  | **Antibody Registry**         | **New in v2.1.0**: Mines repair patterns and generates ACL-1~4 graded immune rules. |
+
+---
+
+## Semantic Validity Levels (SVL)
+
+| Level | Name                 | Guarantee                                      |
+|:------|:---------------------|:-----------------------------------------------|
+| SVL-1 | Symbolic Existence   | Never calls functions that do not exist in the project |
+| SVL-2 | Type Validity        | Parameter count and types strictly match       |
+| SVL-3 | Dataflow Correctness | Variables are declared before use, no circular references |
+| SVL-4 | Protocol Legality    | Business step order must adhere to state transition rules |
+
+---
+
+## Quick Start
+
+```bash
+npm install -g progmune-runtime
+npx progmune-runtime setup "YOUR_API_KEY"
+npx progmune-runtime test
+```
+
+---
+
+## License
+
+MIT License.
+
+Progmune is redefining AI-assisted programming—not by "making models smarter," but by "letting program truth govern generation."

package/dist/action-runtime.js

@@ -51,6 +51,7 @@ class ActionBuilder {
     }
 }
 let currentVars = {};
+/** @requires ACTION_CODE @produces ACTION_RESULT */
 function executeActionCode(code) {
     const root = new ActionBuilder();
     currentVars = {};

package/dist/audit.js

@@ -46,6 +46,8 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 /** Scan a directory recursively for TypeScript files and check for @progmune-generated markers. */
 const DEFAULT_THRESHOLD = 0.8;
+/** Audit a directory for @progmune-generated markers and report coverage. */
+/** @requires DIRECTORY @produces AUDIT_RESULT */
 function auditDirectory(dir, threshold = DEFAULT_THRESHOLD) {
     const result = {
         directory: dir,
@@ -127,6 +129,8 @@ function scanDir(rootDir, currentDir, result) {
     }
 }
 /** Format audit result as human-readable text. */
+/** Format audit result as human-readable text with coverage statistics. */
+/** @requires AUDIT_RESULT @produces FORMATTED_REPORT */
 function formatAuditResult(result) {
     const pct = (result.coverage * 100).toFixed(1);
     const lines = [];

package/dist/branch-ledger.js

@@ -32,10 +32,13 @@ const runtime_invariants_1 = require("./runtime-invariants");
 const protocol_registry_1 = require("./protocol-registry");
 // ── Pure Functions ──
 /** Generate a unique branch ID. */
+/** @requires BRANCH_TREE @produces BRANCH_ID */
 function generateBranchId() {
     return `br_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
 }
 /** Create the root branch of a new execution tree. */
+/** Create the root branch of an execution tree. */
+/** @requires TRANSITIONS @produces ROOT_BRANCH */
 function createRootBranch(transitions = []) {
     const id = generateBranchId();
     return {
@@ -64,6 +67,8 @@ function createRootBranch(transitions = []) {
  * - The child has no shared history with the parent beyond the parent's
  *   final state
  */
+/** Create a child branch from a parent branch. */
+/** @requires PARENT_BRANCH @produces CHILD_BRANCH */
 function createBranch(parent, reason = "alternative", initialTransitions = []) {
     const id = generateBranchId();
     return {
@@ -103,6 +108,8 @@ function createBranch(parent, reason = "alternative", initialTransitions = []) {
  * Use createBranch when:
  * - Starting a completely fresh alternative from the parent's final state
  */
+/** Fork a branch at a split index creating a sibling repair branch. */
+/** @requires BRANCH @produces FORKED_BRANCHES */
 function forkBranch(branch, splitIndex, reason = "repair_attempt") {
     const sharedTransitions = branch.transitions.slice(0, splitIndex + 1);
     const remainingTransitions = branch.transitions.slice(splitIndex + 1);
@@ -133,6 +140,8 @@ function forkBranch(branch, splitIndex, reason = "repair_attempt") {
  *  Takes the successful path: concatenates transitions from each branch
  *  in the order they appear in the tree path.
  *  Returns null if no branches have transitions. */
+/** Merge multiple branches into one unified branch. */
+/** @requires BRANCH_LIST @produces MERGED_BRANCH */
 function mergeBranches(branches) {
     const validBranches = branches.filter(b => b.transitions.length > 0);
     if (validBranches.length === 0)
@@ -164,6 +173,8 @@ function mergeBranches(branches) {
 /** Flatten a branch and all its ancestors into a single linear transition sequence.
  *  This is the bridge between the tree model and existing linear-only consumers
  *  (checkLedgerConsistency, hashLedger, etc.). */
+/** Flatten a branch tree into a linear transition sequence. */
+/** @requires BRANCH_TREE @produces TRANSITIONS */
 function flattenBranch(branch, allBranches) {
     const path = getBranchPath(branch, allBranches);
     const allTransitions = [];
@@ -187,6 +198,8 @@ function flattenBranch(branch, allBranches) {
     return allTransitions.sort((a, b) => a.actionIndex - b.actionIndex);
 }
 /** Get the path from root to a given branch (inclusive). */
+/** Get the path from root to a target branch. */
+/** @requires BRANCH @produces BRANCH_PATH */
 function getBranchPath(branch, allBranches) {
     const path = [];
     let current = branch;
@@ -203,6 +216,8 @@ function getBranchPath(branch, allBranches) {
 }
 /** Replay a branch tree: rebuild state across all ancestor branches
  *  and verify every transition is valid. */
+/** Replay a branch tree verifying all transitions. */
+/** @requires BRANCH_TREE @produces REPLAY_RESULT */
 function replayBranch(branch, allBranches, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     const path = getBranchPath(branch, allBranches);
     const pathIds = path.map(b => b.id);
@@ -240,6 +255,8 @@ function replayBranch(branch, allBranches, namespaceInitialStates = (0, protocol
     };
 }
 /** Build a branch lookup map from an array of branches. */
+/** Build a lookup map from a branch array. */
+/** @requires BRANCH_LIST @produces BRANCH_MAP */
 function buildBranchMap(branches) {
     const map = new Map();
     for (const b of branches) {
@@ -248,10 +265,13 @@ function buildBranchMap(branches) {
     return map;
 }
 /** Find the root branch of a tree. */
+/** Find the root branch of a tree. */
+/** @requires BRANCH_LIST @produces ROOT_BRANCH */
 function findRootBranch(branches) {
     return branches.find(b => !b.parentId);
 }
 /** Find all child branches of a given parent. */
+/** @requires PARENT_BRANCH @produces CHILD_BRANCHES */
 function findChildBranches(parent, allBranches) {
     const children = [];
     for (const b of allBranches.values()) {
@@ -262,6 +282,8 @@ function findChildBranches(parent, allBranches) {
     return children;
 }
 /** Get the full branch tree as a human-readable structure. */
+/** Format a branch tree as human-readable text. */
+/** @requires BRANCH_TREE @produces DESCRIPTION */
 function describeBranchTree(root, allBranches, indent = 0) {
     const prefix = "  ".repeat(indent);
     let result = `${prefix}${root.id.slice(0, 12)} [${root.reason}] (${root.transitions.length} tx, outcome: ${root.outcome || "open"})\n`;
@@ -274,6 +296,8 @@ function describeBranchTree(root, allBranches, indent = 0) {
 /** Evaluate all branches in a tree, score them, and return the recommended winner.
  *  Scoring: replay +50, zero violations +30, success outcome +20.
  *  Highest score wins. Ties go to the smaller branch (fewer transitions). */
+/** Score all branches in a tree and return the recommended winner. */
+/** @requires BRANCH_TREE @produces BRANCH_SCORES */
 function evaluateBranches(branches, namespaceInitialStates = new Map([["_global", "UNAUTHENTICATED"]])) {
     if (branches.length === 0)
         return { scores: [], winner: null };
@@ -326,6 +350,8 @@ function evaluateBranches(branches, namespaceInitialStates = new Map([["_global"
     return { scores, winner };
 }
 /** Wrap a linear transition array as a single root branch (backward compat). */
+/** Wrap linear transitions as a single root branch. */
+/** @requires TRANSITIONS @produces ROOT_BRANCH */
 function wrapAsBranch(transitions) {
     const b = createRootBranch(transitions);
     b.outcome = transitions.length > 0
@@ -335,6 +361,8 @@ function wrapAsBranch(transitions) {
 }
 /** Unwrap a branch tree to the linear transition list.
  *  For backward compatibility: flattens the "winning" path (first successful leaf). */
+/** Unwrap a branch tree to a flat transition list. */
+/** @requires BRANCH_LIST @produces TRANSITIONS */
 function unwrapBranchTree(branches) {
     if (branches.length === 0)
         return [];

package/dist/deterministic-replay.js

@@ -53,6 +53,8 @@ const ssg_validator_1 = require("./ssg-validator");
 const branch_ledger_1 = require("./branch-ledger");
 // ── Core Replay ──
 /** Replay a session from disk, comparing against its stored fingerprint. */
+/** Deterministically replay a session ledger and verify against stored fingerprint. */
+/** @requires SESSION_DATA @produces REPLAY_RESULT */
 function replaySession(sessionId, currentRules, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     // Load session
     const sessionsDir = path.resolve(process.env.PROGMUNE_PROJECT_DIR || process.cwd(), ".progmune_corpus/sessions");
@@ -112,6 +114,8 @@ function replaySession(sessionId, currentRules, namespaceInitialStates = (0, pro
     return replayLedger(sessionId, transitions, sessionRuleHash, storedHash, currentRuleHash, currentRules, namespaceInitialStates);
 }
 /** Core replay logic: replay transitions against (optional) current rules. */
+/** Replay a ledger of transitions against current rules and verify consistency. */
+/** @requires LEDGER_DATA @produces REPLAY_RESULT */
 function replayLedger(sessionId, transitions, storedRuleHash, storedLedgerHash, currentRuleHash, currentRules, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     const replayedHash = transitions.length > 0 ? (0, ssg_validator_1.hashLedger)(transitions) : "";
     const ruleHashMatch = !currentRuleHash || !storedRuleHash
@@ -200,6 +204,8 @@ function replayLedger(sessionId, transitions, storedRuleHash, storedLedgerHash,
     };
 }
 /** Replay with per-transition detail — for debugging and UI. */
+/** Replay transitions with per-step detail for debugging. */
+/** @requires TRANSITIONS @produces DETAIL_RESULT */
 function replayWithDetail(transitions, currentRules, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     if (!currentRules || currentRules.size === 0) {
         return transitions.map(t => ({

package/dist/emitter.js

@@ -72,6 +72,8 @@ function getImportPath(file) {
  * 将动作序列编译为目标语言代码。
  * @protocol namespace=dev_pipeline pre_states=["SEQUENCE_VALIDATED"] post_states=["CODE_EMITTED"] invalidate=["SEQUENCE_VALIDATED"]
  */
+/** @requires ACTIONS @produces TYPESCRIPT_CODE */
+/** @requires ACTIONS @produces TYPESCRIPT_CODE */
 function emitCode(actions, meta) {
     const irRaw = JSON.parse(fs.readFileSync("ir.json", "utf-8"));
     // Support both old format (array) and new format ({typeMap, functions})
@@ -205,6 +207,22 @@ function emitCode(actions, meta) {
                         return "false";
                     return `""`;
                 }
+                // String enum defaults — match param type to sensible value
+                const STRING_ENUMS = {
+                    "SVL": '"SVL-4"', "RootCause": '"F01"', "BranchReason": '"repair_attempt"',
+                    "RepairStrategy": '"insert"', "ConstraintType": '"protocol"',
+                    "SVLString": '"SVL-4"', "BranchOutcome": '"success"',
+                };
+                if (STRING_ENUMS[paramType])
+                    return STRING_ENUMS[paramType];
+                // Array types: use empty array
+                if (paramType.endsWith("[]"))
+                    return "[]";
+                // Generic Map/Set types: use empty constructor
+                if (paramType.startsWith("Map<"))
+                    return `new Map()`;
+                if (paramType.startsWith("Set<"))
+                    return `new Set()`;
                 if (paramType === "UserPayload")
                     return `{ id: 1, role: "user" } as UserPayload`;
                 if (paramType === "PasswordHash")
@@ -253,6 +271,19 @@ function emitCode(actions, meta) {
     };
     for (const a of actions)
         code += convert(a) + "\n";
+    // Ensure last action is a return — inject one if LLM forgot
+    const lastAction = actions[actions.length - 1];
+    if (lastAction && lastAction.kind !== "return") {
+        const allCalls = actions.filter(a => a.kind === "call" && a.assignTo);
+        if (allCalls.length === 1) {
+            code += `  return ${allCalls[0].assignTo};\n`;
+        }
+        else if (allCalls.length > 1) {
+            // Multiple calls: return all results as an object
+            const vars = allCalls.map(c => c.assignTo).join(", ");
+            code += `  return { ${vars} };\n`;
+        }
+    }
     code += "}\n";
     // Call main with params if it has inputs, otherwise no-arg call
     if (inputs.length > 0) {

package/dist/execute.js

@@ -69,6 +69,7 @@ function saveMetrics(m) {
     fs.writeFileSync(METRICS_FILE, JSON.stringify(m, null, 2), "utf-8");
 }
 /** Record a generation event. Called automatically by execute(). */
+/** @requires GENERATION_EVENT @produces METRICS_DATA */
 function recordGeneration(record) {
     const m = loadMetrics();
     m.generated++;
@@ -82,6 +83,8 @@ function recordGeneration(record) {
     saveMetrics(m);
 }
 /** Get current execution metrics. */
+/** @requires METRICS_DATA @produces EXECUTION_METRICS */
+/** @requires METRICS_DATA @produces EXECUTION_METRICS */
 function getExecutionMetrics() {
     return loadMetrics();
 }
@@ -92,6 +95,8 @@ function getExecutionMetrics() {
  * @param projectPath - Absolute path to project root
  * @param filePath - Optional: write generated code to this file
  */
+/** @requires INTENT @produces CODE */
+/** @requires INTENT @produces CODE */
 async function execute(intent, projectPath, filePath) {
     // 1. IR extraction
     let ir;
@@ -208,6 +213,9 @@ async function execute(intent, projectPath, filePath) {
 }
 /** Verify a file compiles without errors. Returns {pass, errors[]}.
  *  Uses tsc directly — no grep tricks, no pipefail ambiguity. */
+/** @requires FILE_PATH @produces COMPILE_RESULT */
+/** @requires FILE_PATH @produces COMPILE_RESULT */
+/** @requires FILE_PATH @produces COMPILE_RESULT */
 function verifyCompiles(filePath) {
     try {
         const { execSync } = require("child_process");
@@ -228,6 +236,7 @@ function verifyCompiles(filePath) {
     }
 }
 /** Quick audit: check whether a file has the @progmune-generated marker. */
+/** @requires FILE_PATH @produces MARKER_STATUS */
 function verifyFileMarker(filePath) {
     try {
         const content = fs.readFileSync(filePath, "utf-8");

package/dist/extract-ir.js

@@ -39,19 +39,31 @@ const ts_morph_1 = require("ts-morph");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const ts = __importStar(require("typescript"));
-/** 从 JSDoc 注释中解析 capability 注解 (@purpose, @tags) */
+/** 从 JSDoc 注释中解析 capability 注解 (@purpose, @tags, @requires, @produces) */
 function parseCapabilityFromJSDoc(node) {
     const jsdocs = node.getJsDocs?.();
     if (!jsdocs || jsdocs.length === 0)
         return {};
     const result = {};
     for (const doc of jsdocs) {
-        // @purpose from the description text
-        const comment = doc.getComment?.() || "";
-        if (comment && !comment.startsWith("@")) {
-            result.purpose = comment.split("\n")[0].trim();
+        // @purpose: full description text (all lines before any @tag)
+        const fullText = doc.getFullText?.() || "";
+        // Extract description: everything between "/**" and the first "@tag"
+        const descMatch = fullText.match(/\/\*\*\s*\n?\s*\*?\s*([^@]*)/);
+        if (descMatch) {
+            const desc = descMatch[1].replace(/\n\s*\*\s*/g, " ").trim();
+            if (desc && !desc.startsWith("@")) {
+                result.purpose = desc;
+            }
+        }
+        // Fallback: use getComment()
+        if (!result.purpose) {
+            const comment = doc.getComment?.() || "";
+            if (comment && !comment.startsWith("@")) {
+                result.purpose = comment.split("\n")[0].trim();
+            }
         }
-        // @tags from ts-morph tag system (getTags returns @tag annotations)
+        // @tags from ts-morph tag system
         const tsTags = doc.getTags?.();
         if (tsTags) {
             for (const t of tsTags) {
@@ -60,11 +72,29 @@ function parseCapabilityFromJSDoc(node) {
                     const val = t.getCommentText?.() || "";
                     result.tags = val.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
                 }
+                if (tn === "requires") {
+                    const val = t.getCommentText?.() || "";
+                    if (!result.requires)
+                        result.requires = [];
+                    result.requires.push(...val.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean));
+                }
+                if (tn === "produces") {
+                    const val = t.getCommentText?.() || "";
+                    if (!result.produces)
+                        result.produces = [];
+                    result.produces.push(...val.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean));
+                }
             }
         }
     }
     return result;
 }
+/** Auto-derive tags from function's source file name */
+function deriveTagsFromFile(filePath) {
+    const name = filePath.replace(/\.ts$/, "").replace(/^src\//, "");
+    const tags = name.split(/[\/\-]/).filter(t => t.length > 2 && t !== "src");
+    return [...new Set(tags)];
+}
 /** 从 JSDoc 注释中解析 @protocol 注解 */
 function parseProtocolFromJSDoc(node) {
     const jsdocs = node.getJsDocs?.();
@@ -178,10 +208,14 @@ function extractDirectCalls(func) {
  * 从 TypeScript 项目提取 IR（函数签名、参数、返回值、协议注解）。
  * @protocol namespace=dev_pipeline pre_states=[] post_states=["IR_EXTRACTED"] invalidate=["IR_STALE"]
  */
+/** @requires PROJECT_PATH @produces IR_FUNCTIONS */
+/** @requires PROJECT_PATH @produces IR_FUNCTIONS */
 function extractIR(projectRoot) {
     return extractIRWithTypes(projectRoot).functions;
 }
 /** Extract both functions and type→file mapping. */
+/** @requires PROJECT_PATH @produces IR_WITH_TYPES */
+/** @requires PROJECT_PATH @produces IR_WITH_TYPES */
 function extractIRWithTypes(projectRoot) {
     const absRoot = path.resolve(projectRoot);
     const project = new ts_morph_1.Project({
@@ -605,6 +639,14 @@ function extractIRWithTypes(projectRoot) {
     }
     const totalExternal = dynamicCount + fallbackCount + externalCount;
     console.error(`📦 外部函数: ${totalExternal} (动态=${dynamicCount} 回退=${fallbackCount} 未签名=${externalCount}, from ${allCalls.size} total calls)`);
+    // Post-process: auto-derive tags from file names
+    for (const f of funcs) {
+        if (!f.tags || f.tags.length === 0) {
+            const derived = deriveTagsFromFile(f.file);
+            if (derived.length > 0)
+                f.tags = derived;
+        }
+    }
     // Build type→module map for emitter
     const _typeMap = {};
     for (const _sf of project.getSourceFiles()) {

package/dist/failure-collector.js

@@ -48,6 +48,9 @@ exports.formatFailureStats = formatFailureStats;
 const fs = __importStar(require("fs"));
 const CORPUS_DIR = "failure-corpus";
 /** Classify a compile error string into a root cause. */
+/** Classify a compile error into a root cause category. */
+/** @requires ERROR_STRING @produces ROOT_CAUSE */
+/** @requires ERROR_STRING @produces ROOT_CAUSE */
 function classifyError(error) {
     if (!error)
         return "F10";
@@ -68,6 +71,9 @@ function classifyError(error) {
     return "F10";
 }
 /** Classify a planning failure. */
+/** Classify a planning failure into a root cause category. */
+/** @requires ERROR_STRING @produces ROOT_CAUSE */
+/** @requires ERROR_STRING @produces ROOT_CAUSE */
 function classifyPlanError(error) {
     if (!error)
         return "F10";
@@ -78,6 +84,8 @@ function classifyPlanError(error) {
     return "F07"; // most plan failures are parsing issues
 }
 /** Record a failure and save to disk. */
+/** Record a generation failure to the failure corpus. */
+/** @requires FAILURE_EVENT @produces FAILURE_ID */
 function recordFailure(record) {
     const id = `F-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
     const entry = {
@@ -94,6 +102,10 @@ function recordFailure(record) {
     return id;
 }
 /** Load all recorded failures. */
+/** Load all recorded failures from the failure corpus. */
+/** @requires FAILURE_CORPUS @produces FAILURE_LIST */
+/** @requires FAILURE_CORPUS @produces FAILURE_LIST */
+/** @requires FAILURE_CORPUS @produces FAILURE_LIST */
 function loadFailures() {
     if (!fs.existsSync(CORPUS_DIR))
         return [];
@@ -109,6 +121,10 @@ function loadFailures() {
     return failures.sort((a, b) => b.timestamp - a.timestamp);
 }
 /** Get failure statistics grouped by root cause. */
+/** Get failure statistics grouped by root cause. */
+/** @requires FAILURE_LIST @produces FAILURE_STATS */
+/** @requires FAILURE_LIST @produces FAILURE_STATS */
+/** @requires FAILURE_LIST @produces FAILURE_STATS */
 function failureStats() {
     const failures = loadFailures();
     const byRootCause = {};
@@ -123,6 +139,10 @@ function failureStats() {
     };
 }
 /** Format failure stats as readable text. */
+/** Format failure statistics as a human-readable report. */
+/** @requires FAILURE_STATS @produces FORMATTED_REPORT */
+/** @requires FAILURE_STATS @produces FORMATTED_REPORT */
+/** @requires FAILURE_STATS @produces FORMATTED_REPORT */
 function formatFailureStats() {
     const stats = failureStats();
     if (stats.total === 0)