progmune-runtime 2.1.0 → 2.1.1

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/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/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;
 }

package/dist/repair-proposal.js

@@ -27,6 +27,8 @@ const protocol_registry_1 = require("./protocol-registry");
 const branch_ledger_1 = require("./branch-ledger");
 // ── Proposal Generation ──
 /** Generate repair proposals for all detected violations in a ledger. */
+/** Generate repair proposals for all detected violations. */
+/** @requires VIOLATIONS @produces REPAIR_PROPOSALS */
 function suggestRepairs(violations, ir, protocols) {
     const proposals = [];
     for (const v of violations) {
@@ -43,6 +45,7 @@ function suggestRepairs(violations, ir, protocols) {
     return proposals;
 }
 /** Protocol violation repair: use SSG fixPath to suggest insertions. */
+/** Generate repair proposals for SSG protocol violations. */
 function suggestProtocolRepair(rejection, ir) {
     const proposals = [];
     if (rejection.fixPath && rejection.fixPath.length > 0) {
@@ -94,6 +97,7 @@ function suggestProtocolRepair(rejection, ir) {
     return proposals;
 }
 /** Invariant violation repair: use rebuildState to compute correct transition data. */
+/** Generate repair proposals for invariant consistency violations. */
 function suggestInvariantRepair(violation, ledger, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     const proposals = [];
     if (violation.invariant === "before-consistency") {
@@ -223,6 +227,7 @@ function suggestGenericRepair(violation, ir) {
 /** Convert an accepted repair proposal into a new Branch.
  *  Creates a child branch with the proposed fix applied.
  *  The original ledger is never modified. */
+/** Convert an accepted repair proposal into a new branch. */
 function applyProposalAsBranch(proposal, parentBranch, currentLedger, ir) {
     const branch = (0, branch_ledger_1.createBranch)(parentBranch, "repair_attempt");
     switch (proposal.strategy) {
@@ -275,6 +280,7 @@ function applyProposalAsBranch(proposal, parentBranch, currentLedger, ir) {
 // ── Validation ──
 /** Validate a repair proposal: does applying it fix the violation?
  *  Returns true if a re-check passes after applying the proposal. */
+/** Validate whether a repair proposal fixes the violation. */
 function validateProposal(proposal, currentLedger, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     let proposedLedger;
     switch (proposal.strategy) {
@@ -298,6 +304,8 @@ function validateProposal(proposal, currentLedger, namespaceInitialStates = (0,
 }
 // ── Summary ──
 /** Generate a comprehensive repair summary from a ledger and IR context. */
+/** Generate a comprehensive repair summary with minimal fix set. */
+/** @requires LEDGER_DATA @produces REPAIR_SUMMARY */
 function generateRepairSummary(ledger, ir, protocols, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     const consistency = (0, ssg_validator_1.checkLedgerConsistency)(ledger, namespaceInitialStates);
     const allProposals = [];
@@ -319,6 +327,8 @@ function generateRepairSummary(ledger, ir, protocols, namespaceInitialStates = (
  * This is the authoritative "minimal fix set" — applying these proposals in order
  * should resolve all detected violations without redundant fixes.
  */
+/** Get the minimal set of repair proposals by deduplication. */
+/** @requires REPAIR_PROPOSALS @produces MINIMAL_FIX_SET */
 function getMinimalFixSet(proposals) {
     const seen = new Map();
     for (const p of proposals) {

package/dist/runtime-invariants.js

@@ -25,6 +25,8 @@ const isStrict = () => STRICT;
 // ── Assertions ──
 /** Assert full ledger passes Invariant-0 + Invariant-1.
  *  Throws InvariantViolationError with the first violation's details. */
+/** Assert a ledger passes all invariant checks. */
+/** @requires LEDGER_DATA @produces CONSISTENCY_CHECK */
 function assertLedgerConsistency(ledger, namespaceInitialStates = (0, protocol_registry_1.getNsInit)()) {
     if (ledger.length === 0)
         return;
@@ -51,6 +53,8 @@ function assertLedgerConsistency(ledger, namespaceInitialStates = (0, protocol_r
 }
 /** Assert a single transition's delta consistency.
  *  Checks that applying acquire/invalidate to statesBefore produces statesAfter. */
+/** Assert a single transition has consistent state deltas. */
+/** @requires TRANSITION @produces DELTA_CHECK */
 function assertDeltaConsistency(transition) {
     if (!transition.valid)
         return;
@@ -111,6 +115,8 @@ function assertDeltaConsistency(transition) {
     }
 }
 /** Assert rule hashes match — detects when validation rules changed under a ledger. */
+/** Assert rule hashes match to detect rule changes. */
+/** @requires EXPECTED_HASH @produces HASH_MATCH_RESULT */
 function assertRuleHashMatch(expected, actual, context) {
     if (expected === actual)
         return;
@@ -126,6 +132,7 @@ function assertRuleHashMatch(expected, actual, context) {
     });
 }
 /** Assert transition indices are strictly monotonic (no duplicates, non-decreasing). */
+/** Assert transition indices are strictly monotonic. */
 function assertTransitionOrder(ledger) {
     if (ledger.length <= 1)
         return;
@@ -144,6 +151,8 @@ function assertTransitionOrder(ledger) {
     }
 }
 /** Convenience: run all invariant checks on a ledger. Does not throw if all pass. */
+/** Run all invariant checks on a ledger. */
+/** @requires LEDGER_DATA @produces INVARIANT_RESULT */
 function assertLedgerInvariants(ledger, namespaceInitialStates = (0, protocol_registry_1.getNsInit)(), expectedRuleHash) {
     assertTransitionOrder(ledger);
     assertLedgerConsistency(ledger, namespaceInitialStates);

package/dist/runtime.js

@@ -37,6 +37,7 @@ exports.runAndCheck = runAndCheck;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/** @requires COMMAND @produces EXECUTION_RESULT */
 function runAndCheck(code) {
     // 把临时文件写入 test-login 目录，使用它的 tsconfig 编译
     const tmpDir = path.resolve("test-login");

package/dist/search-planner.js

@@ -127,6 +127,7 @@ async function batchScoreFuncs(funcs, goal) {
     }
     return result;
 }
+/** @requires INTENT @produces ACTION_PLAN */
 async function searchPlan(intent, beamWidth = 2, maxDepth = 6) {
     (0, llm_1.resetCallCount)();
     staticScoreCache.clear();

package/dist/semantic-snapshot.js

@@ -50,6 +50,7 @@ function ensureDir(dir) {
         fs.mkdirSync(dir, { recursive: true });
 }
 /** 从 IR 数据创建快照 */
+/** @requires IR_DATA @produces SNAPSHOT */
 function createSnapshot(ir, intent, sessionId) {
     const functions = ir.map((f) => ({
         name: f.name,
@@ -69,6 +70,7 @@ function createSnapshot(ir, intent, sessionId) {
     };
 }
 /** 持久化快照 */
+/** @requires SNAPSHOT @produces SNAPSHOT_ID */
 function saveSnapshot(snapshot) {
     ensureDir(SNAPSHOT_DIR);
     fs.writeFileSync(path.join(SNAPSHOT_DIR, `${snapshot.id}.json`), JSON.stringify(snapshot, null, 2));

package/dist/session-utils.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countResolved = countResolved;
+exports.formatSessionCounts = formatSessionCounts;
+/** Count resolved vs unresolved sessions in a session list.
+ * @requires SESSION_LIST @produces RESOLVED_COUNT
+ * @tags session, count, statistics
+ */
+function countResolved(sessions) {
+    const resolved = sessions.filter((s) => s.resolved).length;
+    return { resolved, unresolved: sessions.length - resolved, total: sessions.length };
+}
+/** Get a summary of session counts as a formatted string.
+ * @requires RESOLVED_COUNT @produces FORMATTED_COUNT
+ * @tags session, format, report
+ */
+function formatSessionCounts(counts) {
+    return `${counts.resolved}/${counts.total} resolved, ${counts.unresolved} unresolved`;
+}