progmune-runtime 2.1.0 → 2.1.2

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)

package/dist/failure-corpus.js

@@ -66,6 +66,7 @@ function checkpointPath(intent) {
     const hash = Buffer.from(intent).toString("base64").replace(/[/+=]/g, "_").slice(0, 32);
     return path.join(CHECKPOINT_DIR, `ckpt_${hash}.json`);
 }
+/** Save planner checkpoint for crash recovery. */
 function saveCheckpoint(intent, data) {
     ensureDir(CHECKPOINT_DIR);
     const cp = {
@@ -75,6 +76,7 @@ function saveCheckpoint(intent, data) {
     };
     fs.writeFileSync(checkpointPath(intent), JSON.stringify(cp, null, 2));
 }
+/** Load a previously saved planner checkpoint. */
 function loadCheckpoint(intent) {
     try {
         const raw = fs.readFileSync(checkpointPath(intent), "utf-8");
@@ -84,12 +86,14 @@ function loadCheckpoint(intent) {
         return null;
     }
 }
+/** Clear a saved planner checkpoint. */
 function clearCheckpoint(intent) {
     try {
         fs.unlinkSync(checkpointPath(intent));
     }
     catch { }
 }
+/** Record a constraint violation to the failure corpus. */
 function recordFailure(record) {
     (0, file_lock_1.withLock)("failure-corpus", () => {
         ensureDir(CORPUS_DIR);
@@ -122,6 +126,8 @@ function recordFailure(record) {
  * 保存执行会话（含所有尝试、违规、状态转移）。
  * @protocol namespace=dev_pipeline pre_states=["CODE_EMITTED"] post_states=["SESSION_RECORDED"] invalidate=["CODE_EMITTED"]
  */
+/** @requires EXECUTION_DATA @produces SESSION_ID */
+/** @requires EXECUTION_DATA @produces SESSION_ID */
 function recordSession(session) {
     ensureDir(SESSIONS_DIR);
     const sessionId = session.sessionId || `sess_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
@@ -158,6 +164,7 @@ function recordSession(session) {
     fs.writeFileSync(path.join(SESSIONS_DIR, `${sessionId}.json`), JSON.stringify(fullSession, null, 2));
     return sessionId;
 }
+/** @requires FAILURE_CORPUS @produces FAILURE_LIST */
 function getAllFailures() {
     const records = [];
     if (!fs.existsSync(CORPUS_DIR))
@@ -178,9 +185,11 @@ function getAllFailures() {
     }
     return records;
 }
+/** @requires FAILURE_LIST @produces FILTERED_FAILURES */
 function getFailuresBySVL(level) {
     return getAllFailures().filter(r => r.violatedSVL === level);
 }
+/** @requires FAILURE_LIST @produces FAILURE_PATTERNS */
 function getTopFailurePatterns(limit = 5) {
     const groups = new Map();
     for (const r of getAllFailures()) {
@@ -200,6 +209,9 @@ function getTopFailurePatterns(limit = 5) {
 /** Get failure genome statistics: total failures, SVL distribution, constraint types, top patterns.
  * @tags failure, statistics, genome, audit
  */
+/** Get failure genome statistics: total failures by SVL, constraint type, and fix path. */
+/** @requires FAILURE_DATA @produces FAILURE_GENOME */
+/** @requires FAILURE_DATA @produces FAILURE_GENOME */
 function getFailureGenome() {
     const sessions = getAllSessions();
     const bySVL = { "SVL-1": 0, "SVL-2": 0, "SVL-3": 0, "SVL-4": 0 };
@@ -259,6 +271,10 @@ function getFailureGenome() {
 /** Load all execution sessions from the corpus directory.
  * @tags session, corpus, audit, history
  */
+/** @requires SESSION_DATA @produces SESSION_LIST */
+/** @requires SESSION_CORPUS @produces SESSION_LIST */
+/** @requires SESSION_CORPUS @produces SESSION_LIST */
+/** @requires SESSION_CORPUS @produces SESSION_LIST */
 function getAllSessions() {
     const sessions = [];
     if (!fs.existsSync(SESSIONS_DIR))
@@ -349,6 +365,8 @@ function computeACL(count, distinctIntents, resolvedRate) {
         return "ACL-2";
     return "ACL-1";
 }
+/** Get antibody patterns learned from failure history. */
+/** @requires FAILURE_HISTORY @produces LEARNED_PATTERNS */
 function getLearnedPatterns() {
     const sessions = getAllSessions();
     const agg = new Map();
@@ -407,6 +425,8 @@ function getLearnedPatterns() {
     return { failureToFix: patterns };
 }
 /** 查询匹配当前意图的高置信度抗体（ACL-3+），用于推理层免疫加速 */
+/** Query antibody registry for matching repair patterns. */
+/** @requires FAILURE_SIGNATURE @produces ANTIBODY_MATCH */
 function queryAntibodies(intent, minACL = "ACL-3") {
     const { failureToFix } = getLearnedPatterns();
     const aclRank = { "ACL-1": 1, "ACL-2": 2, "ACL-3": 3, "ACL-4": 4 };
@@ -431,6 +451,9 @@ function queryAntibodies(intent, minACL = "ACL-3") {
         .sort((a, b) => b._score - a._score);
 }
 /** 语义热力图：哪些协议/层最脆弱，约束如何聚类 */
+/** Get semantic heatmap showing fragile protocols and SVL hotspots. */
+/** @requires FAILURE_DATA @produces HEATMAP */
+/** @requires FAILURE_HEATMAP @produces HEATMAP_DATA */
 function getSemanticHeatmap() {
     const sessions = getAllSessions();
     // Count total violations from sessions
@@ -493,6 +516,8 @@ function getSemanticHeatmap() {
 /** Get antibody efficacy statistics: hits by level, tokens saved, top signatures.
  * @tags antibody, immune, statistics, efficiency
  */
+/** @requires ANTIBODY_DATA @produces ANTIBODY_STATS */
+/** @requires ANTIBODY_DATA @produces ANTIBODY_STATS */
 function getAntibodyStats() {
     const sessions = getAllSessions();
     let totalHits = 0;
@@ -537,6 +562,7 @@ function getAntibodyStats() {
         .slice(0, 10);
     return { totalHits, fastPathHits, injectedHintHits, totalLLMCallsSaved, totalTokensSaved, byLevel, topSignatures };
 }
+/** Generate candidate immune rules from failure patterns. */
 function generateCandidateRules() {
     const genome = getFailureGenome();
     const rules = [];

package/dist/feedback.js

@@ -41,11 +41,13 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const file_lock_1 = require("./file-lock");
 const FEEDBACK_PATH = path.resolve(__dirname, "../feedback.json");
+/** @requires CORPUS @produces FEEDBACK_DATA */
 function loadFeedback() {
     if (!fs.existsSync(FEEDBACK_PATH))
         return [];
     return JSON.parse(fs.readFileSync(FEEDBACK_PATH, "utf-8"));
 }
+/** @requires FEEDBACK_EVENT @produces FEEDBACK_ID */
 function saveFeedback(record) {
     (0, file_lock_1.withLock)("feedback.json", () => {
         const data = loadFeedback();
@@ -53,6 +55,7 @@ function saveFeedback(record) {
         fs.writeFileSync(FEEDBACK_PATH, JSON.stringify(data, null, 2));
     });
 }
+/** @requires FUNCTION_NAME @produces SUCCESS_RATE */
 function getFunctionSuccessRate(funcName) {
     const records = loadFeedback();
     const funcRecords = records.filter(r => r.functionName === funcName);
@@ -61,6 +64,7 @@ function getFunctionSuccessRate(funcName) {
     const successCount = funcRecords.filter(r => r.success).length;
     return successCount / funcRecords.length;
 }
+/** @requires EXECUTION_DATA @produces RUN_ID */
 function recordRun(intent, actions, success, error) {
     for (const action of actions) {
         if (action.kind === "call") {

package/dist/health-utils.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeHealthScore = computeHealthScore;
+exports.formatHealthLevel = formatHealthLevel;
+exports.countSessionLedgers = countSessionLedgers;
+/** Compute overall immune health score from failure and antibody data.
+ * @requires FAILURE_GENOME @produces HEALTH_SCORE
+ * @tags health, score, immune
+ */
+function computeHealthScore(failureGenome, antibodyStats) {
+    const totalFailures = failureGenome?.totalFailures || 0;
+    const totalHits = antibodyStats?.totalHits || 0;
+    const base = 100;
+    const failurePenalty = Math.min(totalFailures * 2, 40);
+    const antibodyBonus = Math.min(totalHits * 3, 20);
+    return Math.max(0, Math.min(100, base - failurePenalty + antibodyBonus));
+}
+/** Format a health score as a status level.
+ * @requires HEALTH_SCORE @produces HEALTH_STATUS
+ * @tags health, format
+ */
+function formatHealthLevel(score) {
+    if (score >= 90)
+        return "Excellent";
+    if (score >= 70)
+        return "Good";
+    if (score >= 50)
+        return "Fair";
+    return "Poor";
+}
+/** Validate a ledger and return pass/fail counts.
+ * @requires SESSION_LIST @produces VALIDATION_COUNTS
+ * @tags ledger, validation, audit
+ */
+function countSessionLedgers(sessions) {
+    const withLedger = sessions.filter((s) => {
+        return s.attempts?.some((a) => a.transitions?.length > 0);
+    }).length;
+    return { total: sessions.length, withLedger };
+}

package/dist/immune-reporter.js

@@ -97,6 +97,7 @@ function extractFingerprints(cursor) {
     }
     return fingerprints;
 }
+/** @requires CORPUS @produces FINGERPRINT_REPORT */
 async function reportFingerprints() {
     const cursor = getReportCursor();
     const fingerprints = extractFingerprints(cursor);

package/dist/ir-utils.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countExported = countExported;
+exports.mergeResults = mergeResults;
+/** Count exported functions in an IR function list.
+ * @requires IR_FUNCTIONS @produces EXPORT_COUNT
+ * @tags ir, count, export
+ */
+function countExported(ir) {
+    return ir.filter((f) => f.exported).length;
+}
+/** Merge two results into a combined object.
+ * @requires RESULT_A @produces MERGED_RESULT
+ * @tags merge, combine
+ */
+function mergeResults(a, b) {
+    return { first: a, second: b };
+}

package/dist/ledger-registry.js

@@ -62,6 +62,8 @@ function fingerprintPath(sessionId) {
 // ── Core API ──
 /** Register a ledger fingerprint (execution certificate).
  *  Called after a session is recorded — creates an immutable proof of the ledger state. */
+/** Register a ledger fingerprint as an execution certificate. */
+/** @requires LEDGER_DATA @produces FINGERPRINT */
 function registerFingerprint(sessionId, transitions, ruleHash) {
     const dir = fingerprintsDir();
     if (!fs.existsSync(dir)) {
@@ -78,6 +80,8 @@ function registerFingerprint(sessionId, transitions, ruleHash) {
     return fingerprint;
 }
 /** Get a single stored fingerprint by sessionId. Returns null if not registered. */
+/** Get a stored ledger fingerprint by session ID. */
+/** @requires SESSION_ID @produces FINGERPRINT */
 function getFingerprint(sessionId) {
     const fpPath = fingerprintPath(sessionId);
     if (!fs.existsSync(fpPath))
@@ -90,6 +94,7 @@ function getFingerprint(sessionId) {
     }
 }
 /** List all registered fingerprints, sorted by timestamp (oldest first). */
+/** List all registered ledger fingerprints. */
 function getFingerprintRegistry() {
     const dir = fingerprintsDir();
     if (!fs.existsSync(dir))
@@ -112,6 +117,7 @@ function getFingerprintRegistry() {
 }
 /** Verify a single session's fingerprint.
  *  Requires the session's transitions to re-hash and compare. */
+/** Verify a single ledger fingerprint against current data. */
 function verifyFingerprint(sessionId, transitions, currentRuleHash) {
     const stored = getFingerprint(sessionId);
     if (!stored) {
@@ -144,6 +150,9 @@ function verifyFingerprint(sessionId, transitions, currentRuleHash) {
 }
 /** Verify all registered fingerprints.
  *  Loads each session to re-hash and compare against the stored fingerprint. */
+/** Verify all registered ledger fingerprints and return tampered status. */
+/** @requires FINGERPRINT_DATA @produces VERIFICATION_RESULT */
+/** @requires FINGERPRINT_DATA @produces VERIFICATION_RESULT */
 function verifyAllFingerprints(currentRuleHash) {
     const fingerprints = getFingerprintRegistry();
     const results = [];
@@ -199,6 +208,8 @@ function verifyAllFingerprints(currentRuleHash) {
 }
 /** Register fingerprints for all sessions that don't yet have one.
  *  Called during `npm run check` to ensure all sessions are fingerprinted. */
+/** Register fingerprints for all sessions that lack them. */
+/** @requires SESSION_DATA @produces FINGERPRINT_DATA */
 function registerAllMissingFingerprints() {
     const sessionsDir = path.resolve(process.env.PROGMUNE_PROJECT_DIR || process.cwd(), ".progmune_corpus/sessions");
     if (!fs.existsSync(sessionsDir))

package/dist/ledger-utils.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countTotalTransitions = countTotalTransitions;
+exports.formatTransitionCount = formatTransitionCount;
+exports.hasViolations = hasViolations;
+exports.countSessionsWithViolations = countSessionsWithViolations;
+/** Count total transitions across all session ledgers.
+ * @requires SESSION_LIST @produces TRANSITION_COUNT
+ * @tags ledger, count, statistics
+ */
+function countTotalTransitions(sessions) {
+    let count = 0;
+    for (const s of sessions) {
+        for (const a of (s.attempts || [])) {
+            count += (a.transitions || []).length;
+        }
+    }
+    return count;
+}
+/** Format a transition count as a summary string.
+ * @requires TRANSITION_COUNT @produces FORMATTED_COUNT
+ * @tags ledger, format
+ */
+function formatTransitionCount(count) {
+    return `${count} total transitions across all sessions`;
+}
+/** Check if a session has any protocol violations in its attempts.
+ * @requires SESSION_DATA @produces VIOLATION_CHECK
+ * @tags ledger, validation
+ */
+function hasViolations(session) {
+    return (session.attempts || []).some((a) => (a.violations || []).length > 0);
+}
+/** Count sessions that have violations.
+ * @requires SESSION_LIST @produces VIOLATION_COUNT
+ * @tags ledger, validation, statistics
+ */
+function countSessionsWithViolations(sessions) {
+    return sessions.filter(s => hasViolations(s)).length;
+}

package/dist/llm.js

@@ -36,11 +36,13 @@ const client = new openai_1.default({ apiKey, baseURL });
 exports.callCount = 0;
 function resetCallCount() { exports.callCount = 0; }
 /** 粗略 token 估算：CJK 字符 ~1.5 token/字，其余 ~0.4 token/字符 */
+/** @requires TEXT @produces TOKEN_COUNT */
 function estimateTokens(text) {
     const cjk = (text.match(/[一-鿿㐀-䶿]/g) || []).length;
     const other = text.length - cjk;
     return Math.ceil(cjk * 1.5 + other * 0.4);
 }
+/** @requires PROMPT @produces LLM_RESPONSE */
 async function generate(prompt) {
     exports.callCount++;
     const resp = await client.chat.completions.create({
@@ -51,6 +53,7 @@ async function generate(prompt) {
     return resp.choices[0]?.message?.content || "";
 }
 /** 带 system prompt 的调用：静态规则放 system，动态内容放 user，语义分离便于未来对接各平台缓存策略 */
+/** @requires SYSTEM_PROMPT @produces LLM_RESPONSE */
 async function chat(systemPrompt, userPrompt) {
     exports.callCount++;
     const resp = await client.chat.completions.create({

package/dist/memory-layer.js

@@ -91,6 +91,7 @@ function saveEpisodes(episodes) {
         fs.writeFileSync(EPISODIC_FILE, JSON.stringify(fresh.slice(0, MAX_EPISODES), null, 2));
     });
 }
+/** @requires EXECUTION_DATA @produces MEMORY_ID */
 function recordEpisode(episode) {
     const episodes = loadEpisodes();
     const newEpisode = {
@@ -104,6 +105,7 @@ function recordEpisode(episode) {
     }
     saveEpisodes(episodes);
 }
+/** @requires LIMIT @produces EPISODE_LIST */
 function getRecentEpisodes(limit = 10) {
     return loadEpisodes().slice(0, limit);
 }
@@ -172,6 +174,7 @@ function consolidateSemantic(minOccurrences = 3) {
     saveSemantic(templates);
     console.error(`[语义记忆] 巩固完成，模板数量: ${templates.length}`);
 }
+/** @requires INTENT @produces TEMPLATE */
 function findSemanticTemplate(intent) {
     const templates = loadSemantic();
     if (templates.length === 0)

package/dist/planner.js

@@ -90,29 +90,72 @@ function determineConstraintType(svl) {
         case "SVL-4": return "protocol";
     }
 }
-/** 构建紧凑函数列表（约节省 50% token） */
-function buildCompactFuncList(funcs) {
+/** 构建紧凑函数列表 — 包含能力元数据帮助 LLM 理解函数语义 */
+function buildCompactFuncList(funcs, allFuncs) {
+    // Known string enums with example values
+    const ENUM_DEFAULTS = {
+        "SVL": '"SVL-4"', "RootCause": '"F01"', "BranchReason": '"repair_attempt"',
+        "RepairStrategy": '"insert"', "ConstraintType": '"protocol"',
+    };
     return funcs.map((f) => {
-        const params = (f.params || []).map((p) => `${p.name}:${p.type}`).join(",");
-        return `${f.name}(${params})->${f.returnType || "any"}`;
+        const params = (f.params || []).map((p) => {
+            const t = (p.type || "any").replace(/\[\]$/, "");
+            const def = ENUM_DEFAULTS[t];
+            return def ? `${p.name}: ${def}` : `${p.name}: ${p.type}`;
+        }).join(",");
+        let line = `${f.name}(${params})->${f.returnType || "any"}`;
+        // Add capability metadata
+        const meta = [];
+        if (f.purpose)
+            meta.push(f.purpose.slice(0, 60));
+        if (f.produces && f.produces.length > 0)
+            meta.push(`→${f.produces.join(",")}`);
+        if (meta.length > 0)
+            line += `  // ${meta.join(" | ")}`;
+        return line;
     }).join("\n");
 }
+/** Build capability chain hints from IR: producer→consumer relationships.
+ *  e.g. "failureStats → formatFailureStats (FAILURE_STATS)" */
+function buildChainHints(funcs) {
+    const chains = [];
+    for (const f of funcs) {
+        if (!f.produces)
+            continue;
+        for (const p of f.produces) {
+            const consumers = funcs.filter((x) => x.requires?.includes(p) && x.name !== f.name);
+            for (const c of consumers) {
+                chains.push(`${f.name}()→${c.name}()  // ${p}`);
+            }
+        }
+    }
+    if (chains.length === 0)
+        return "";
+    return "\n推荐调用链（先调生产者，用 $变量名 传给消费者）:\n" + chains.map(c => `  ${c}`).join("\n");
+}
 const SYSTEM_PROMPT = `你是程序合成助手。只输出 JSON 数组，不输出解释。
 
-格式（紧凑一行）：
-[{"f":"函数名","to":"变量名","a":[{"n":"参数名","t":"类型","v":值}]},{"r":"变量名"}]
+格式：[{"f":"函数名","to":"变量名","a":[{"n":"参数名","t":"类型","v":值}]},{"r":"变量名"}]
 
 规则：
-- "f": 函数名，"to": 接收返回值的变量名（void 函数省略）
-- "a": 参数数组，每个参数 n=名称 t=类型 v=值
-- 字符串值直接写: "v":"hello"，数字: "v":42
-- 引用之前返回的变量: "v":"$变量名"（$前缀表示这是变量引用）
-- {"r":"变量名"} 表示返回该变量
+- 函数名从可用列表中选择，优先选注释中 purpose 匹配需求的函数
+- 0参数函数直接用 "a":[]：{"f":"getAllSessions","to":"s","a":[]}
+- 参数值规则（重要！）：
+  - 字符串: "v":""（空串）或 "v":"SVL-4"（已知枚举值）
+  - 数字: "v":0 或 "v":1
+  - 布尔: "v":false
+  - 对象/数组: "v":{} as Type
+  - 上一个函数返回值: "v":"$变量名"（$前缀引用）
+- 返回值: {"r":"变量名"} — 必须返回，不能只调用不返回
+- 链式调用：看到推荐调用链时，用 $变量名 把生产者输出传给消费者
 
-示例 — 提取 IR 后校验：
-[{"f":"extractIR","to":"ir","a":[{"n":"root","t":"str","v":"."}]},{"f":"validateActionSequence","to":"ok","a":[{"n":"actions","t":"any","v":"$ir"}]},{"r":"ok"}]
-
-铁律：只输出 JSON 数组，双引号，不输出解释`;
+铁律：
+- 函数签名中带引号的参数（如 "SVL-4"）是字符串值，直接 v 中
+- 字符串枚举（SVL等）用带引号的值，禁止 {} as Type
+- 每个call的返回值用"to"命名变量，下一个call通过"$变量名"引用
+- 最后一个action必须是{"r":"变量名"}，不能以call结尾
+- 如果你调了函数，必须return它的结果
+- 只输出JSON`;
 const RETRY_HINT = `输出格式：紧凑 JSON 数组 [{"f":"函数名","to":"变量名","a":[...]}]`;
 /** 构建重试 prompt：精简但包含必要的 IR 语法提示 */
 /** 解析 LLM 输出的紧凑 JSON 为 Action[]。
@@ -479,6 +522,7 @@ function attemptSSGRepair(actions, rejection, ir, protocols, namespaceInitialSta
     }
     return null;
 }
+/** @requires INTENT @produces ACTION_PLAN */
 async function plan(userIntent) {
     (0, llm_1.resetCallCount)();
     const irRaw = JSON.parse(fs.readFileSync("ir.json", "utf-8"));
@@ -621,18 +665,65 @@ async function plan(userIntent) {
         console.error(`💉 ACL-3 抗体注入提示: ${top.fixPath.join(" → ")}`);
     }
     const keywords = (0, utils_1.extractKeywords)(userIntent);
+    const intentLower = userIntent.toLowerCase();
     const scored = ir.map((f) => {
         let score = 0;
+        // Name match (existing)
         for (const kw of keywords) {
             score += (0, utils_1.jaccardSimilarity)(f.name.toLowerCase(), kw);
             if (f.name.toLowerCase().includes(kw))
                 score += 0.5;
         }
+        // Capability Graph: purpose match
+        if (f.purpose) {
+            const purposeLower = f.purpose.toLowerCase();
+            for (const kw of keywords) {
+                if (purposeLower.includes(kw))
+                    score += 1.0; // strong signal
+            }
+            // Full intent overlap with purpose
+            const intentWords = intentLower.split(/[\s,，]+/);
+            for (const w of intentWords) {
+                if (w.length > 2 && purposeLower.includes(w))
+                    score += 0.3;
+            }
+        }
+        // Capability Graph: requires/produces capability matching
+        if (f.produces) {
+            for (const p of f.produces) {
+                if (intentLower.includes(p.toLowerCase().replace(/_/g, " ")))
+                    score += 1.5;
+            }
+        }
+        if (f.requires) {
+            for (const r of f.requires) {
+                if (intentLower.includes(r.toLowerCase().replace(/_/g, " ")))
+                    score += 0.5;
+            }
+        }
+        // Capability Graph: tag match
+        if (f.tags) {
+            for (const tag of f.tags) {
+                if (intentLower.includes(tag.toLowerCase()))
+                    score += 0.8;
+            }
+        }
         return { ...f, score };
     });
     scored.sort((a, b) => b.score - a.score);
     const topFuncs = scored.slice(0, 15);
-    const compactFuncList = buildCompactFuncList(topFuncs);
+    const compactFuncList = buildCompactFuncList(topFuncs, ir);
+    const chainHints = buildChainHints(topFuncs);
+    // Known string-enum types: tell LLM these are strings, not objects
+    const STRING_ENUMS = {
+        "SVL": '"SVL-1"|"SVL-2"|"SVL-3"|"SVL-4"',
+        "RootCause": '"F01"|"F02"|...|"F10"',
+        "BranchReason": '"root"|"repair_attempt"|"alternative"',
+        "RepairStrategy": '"insert"|"replace"|"reorder"',
+    };
+    const typeHints = Object.keys(STRING_ENUMS).length > 0
+        ? `\n类型速查：${Object.entries(STRING_ENUMS).map(([k, v]) => `${k}=${v}`).join("，")}。这些类型传字符串值。`
+        : "";
     const userIntentPart = userIntent.match(/(?:实现|implement|编写|创建)\s*(\w+)\s*(?:函数|function)?/i);
     const forbiddenFuncs = [];
     if (userIntentPart) {
@@ -643,7 +734,7 @@ async function plan(userIntent) {
     }
     const protocolChainHint = buildProtocolChainHint(protocols);
     const userPrompt = `可用函数：
-${compactFuncList}${protocolChainHint}
+${compactFuncList}${protocolChainHint}${chainHints}${typeHints}
 
 需求：${userIntent}${antibodyHint}
 
@@ -690,7 +781,7 @@ ${RETRY_HINT}
         });
         if (legalFuncs.length === topFuncs.length)
             return compactFuncList;
-        return buildCompactFuncList(legalFuncs);
+        return buildCompactFuncList(legalFuncs, ir);
     }
     const maxRetries = 3;
     for (let r = startRetry; r < maxRetries; r++) {

package/dist/protocol-registry.js

@@ -53,11 +53,14 @@ const ssg_validator_1 = require("./ssg-validator");
 // ── Singleton cache ──
 let cached = null;
 /** Invalidate the cache (call after protocols.json changes). */
+/** Invalidate cached protocol configuration for reload. */
 function invalidateProtocolCache() {
     cached = null;
 }
 /** Get the authoritative protocol configuration.
  *  Cached after first call; call invalidateProtocolCache() to force reload. */
+/** Get the authoritative protocol configuration from the single source of truth. */
+/** @requires PROJECT_CONFIG @produces PROTOCOL_CONFIG */
 function getProtocolConfig() {
     if (cached)
         return cached;
@@ -96,10 +99,14 @@ function getProtocolConfig() {
 }
 // ── Convenience re-exports ──
 /** Get namespace initial states only (most common need). */
+/** Get namespace initial states from protocol configuration. */
+/** @requires PROJECT_CONFIG @produces NAMESPACE_STATES */
 function getNsInit() {
     return new Map(getProtocolConfig().nsInit);
 }
 /** Get current rule hash without loading full config. */
+/** Get the current rule set hash. */
+/** @requires PROTOCOL_CONFIG @produces RULE_HASH */
 function getRuleHash() {
     return getProtocolConfig().ruleHash;
 }