progmune-runtime 3.7.6 → 3.7.7

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [3.7.7] — 2026-08-28
+
+### C 注解采纳体验（采纳生死线工具）
+
+- **注解建议引擎**（`src/annotation-suggest.ts`）：确定性启发式（无 LLM）——按函数名词汇（3.7.6 金标 5/5 真实注解反推的词表）× 已注解状态，生成原语注解候选（verify/establish/guard/open/close 角色 + 命名空间/状态转移/注释块模板/置信度/命中理由/掩蔽风险标记）；已注解、规则名、外部函数自动排除；两遍计算 maskRisk（体内调用规则原语或本批同被建议函数）
+- **CLI 扫描模式**（`scripts/c-annotate.js --scan <dir> [--write] [--all] [--include-resource]`）：dry-run 默认；--write 自动插入函数定义上方（写入后自动刷新 ir.json 防陈旧）；保守门控（全部实测依据）：establish/掩蔽风险跳过（不提供强制开关）、open/close 跳过（--include-resource 强制）
+- **引擎加性字段**：`evaluateTrust.annotationSuggestions`（仅 C 生成；TS/Python 无该字段——零漂移）
+- **验收（REALWORLD_C_V7.md）**：无注解 uftpd 副本金标恢复率 **4/4 角色正确**（check_user_pass=verify / handle_PASS=establish / do_RETR / do_STOR=guard）；自动应用 7 条后与手写金标**等价**（真实代码 0 SSG FP、植入违规 2/2 精确定位、NEEDS_REVIEW 72 同分）
+- **三个实测安全发现（自动写入的门控依据）**：①掩蔽风险——establish 注解把手握违规的流函数变「原语」（函数内顺序不检查）后植入违规被掩蔽（实测 2 处）；②资源生命周期注解自动应用触发跨函数窗口 FP 类（实测 28 条，open/close 分处不同函数窗口）；③new_session 词汇误判守卫（实测 4 FP，模式收紧为 channel 类）
+- 回归：15 个新单元测试；引擎相关套件 98/98；Python 盲测 v1.2 零漂移（64）；C 应用级金标 F1=95.7% 不变；演示重扫 SSG 结果不变
+
 ## [3.7.6] — 2026-08-28
 
 ### C 生产级路径收官：金标 5/5 + 采纳案例 + 正则层噪声治理

package/dist/annotation-suggest.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * annotation-suggest.ts — C 注解建议引擎（确定性启发式，无 LLM）
+ *
+ * 注解驱动定位的「采纳生死线」：未注解 C 项目的 SSG 层静默（0 flags——
+ * 看不见问题，也看不见该在哪下注）。本模块按函数名词汇 + 已注解状态，
+ * 为项目生成「原语注解建议清单」——每条建议含角色（verify/establish/
+ * guard/open/close）、命名空间、状态转移与可直接粘贴的注释块模板。
+ *
+ * 设计原则：
+ *   - 纯名称启发式，诚实标注置信度（high=多证据/强动词，medium=单证据）；
+ *     不假装语义理解——建议是「填空起点」，人工确认后生效（与
+ *     c-alias-propose.js 的人工确认门同一哲学）。
+ *   - 词汇来自 3.7.6 金标 5/5 的真实注解反推（check_user_pass=verify、
+ *     handle_PASS=establish、do_RETR/do_STOR=守卫、auth_password=verify、
+ *     new_session_channel=会话守卫、open/close_data_connection=资源生命周期）。
+ *   - 已注解函数、规则名函数（按名即命中，无需注解）、外部函数不重复建议。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestAnnotations = suggestAnnotations;
+const ROLE_DEFS = [
+    {
+        // 凭证比对（密码/口令/凭证 × 比对动词）——verify_password 同款语义
+        role: "verify",
+        namespace: "auth",
+        pre: ["UNAUTHENTICATED"],
+        post: ["PASSWORD_VERIFIED"],
+        patterns: [
+            ["password", "check"],
+            ["password", "compare"],
+            ["password", "verify"],
+            ["password", "auth"],
+            ["passwd", "check"],
+            ["pass", "check"],
+            ["pass", "compare"],
+            ["credential", "check"],
+            ["credential", "compare"],
+            ["secret", "check"],
+            ["secret", "compare"],
+            ["kbdint", "get"],
+            ["otp", "check"],
+        ],
+    },
+    {
+        // 登录完成（认证循环/命令处理器的完成点）——establish 原语
+        role: "establish",
+        namespace: "auth",
+        pre: [],
+        post: ["AUTHENTICATED"],
+        patterns: [
+            ["authenticate"],
+            ["login"],
+            ["logon"],
+            ["sign_in"],
+            ["auth_success"],
+            ["auth_ok"],
+            ["handle", "pass"],
+            ["do", "login"],
+            ["do", "user"],
+        ],
+    },
+    {
+        // 权限/会话守卫（权限词 × 检查动词，或 FTP/传输类命令处理器、
+        // 通道开启回调）——check_resource_ownership 同款语义（auth 命名空间，
+        // 见 REALWORLD_C_V6.md 发现 G5：跨命名空间 pre 不可满足）
+        role: "guard",
+        namespace: "auth",
+        pre: ["AUTHENTICATED"],
+        post: ["AUTHORIZED"],
+        patterns: [
+            ["perm", "check"],
+            ["authoriz", "check"],
+            ["acl", "check"],
+            ["grant", "check"],
+            ["privilege", "check"],
+            ["do", "retr"],
+            ["do", "stor"],
+            ["handle", "retr"],
+            ["handle", "stor"],
+            ["do", "download"],
+            ["do", "upload"],
+            ["do", "transfer"],
+            ["start", "transfer"],
+            ["send", "transfer"],
+            ["open", "channel"],
+            ["accept", "channel"],
+            ["new", "channel"],
+            ["new", "session", "channel"],
+            // 注意：不带 ["new","session"]——new_session 是会话工厂（创建而非检查），
+            // 实测（V7）：守卫注解会误报其调用方（ftp_cb/tftp_cb/main 在登录前建会话）。
+        ],
+    },
+    {
+        // 资源获取（打开文件/连接/日志）——open_file 同款语义
+        role: "open",
+        namespace: "file",
+        pre: [],
+        post: ["FILE_OPEN"],
+        patterns: [
+            ["open", "file"],
+            ["open", "data"],
+            ["open", "connection"],
+            ["open", "conn"],
+            ["open", "log"],
+            ["open", "db"],
+            ["create", "connection"],
+        ],
+    },
+    {
+        // 资源释放（关闭/销毁文件/连接）——close_file 同款语义
+        role: "close",
+        namespace: "file",
+        pre: ["FILE_OPEN"],
+        post: [],
+        invalidate: ["FILE_OPEN"],
+        patterns: [
+            ["close", "file"],
+            ["close", "data"],
+            ["close", "connection"],
+            ["close", "conn"],
+            ["close", "log"],
+            ["close", "db"],
+            ["release", "connection"],
+            ["destroy", "connection"],
+        ],
+    },
+];
+/** 匹配命中数 ≥2 视为高置信（多个独立证据） */
+const HIGH_CONFIDENCE_HITS = 2;
+/**
+ * 为一组函数生成注解建议（确定性，同输入同输出）。
+ *
+ * @param functions — 项目函数列表（C IR）
+ * @param ruleNames — 已加载规则名集合（规则名函数按名即命中，无需注解建议）
+ * @param limit — 输出上限（默认 20，防大仓库刷屏；按置信度排序）
+ */
+function suggestAnnotations(functions, ruleNames, limit = 20) {
+    const suggestions = [];
+    const seen = new Set();
+    for (const fn of functions) {
+        if (!fn.name)
+            continue;
+        if (fn.protocol && (fn.protocol.pre_states?.length || fn.protocol.post_states?.length)) {
+            continue; // 已注解
+        }
+        if (ruleNames?.has(fn.name))
+            continue; // 规则名函数按名命中，无需注解
+        if (fn.external)
+            continue;
+        if (seen.has(fn.name))
+            continue;
+        seen.add(fn.name);
+        const lower = fn.name.toLowerCase();
+        for (const def of ROLE_DEFS) {
+            const hits = [];
+            for (const pattern of def.patterns) {
+                if (pattern.every((word) => lower.includes(word))) {
+                    hits.push(pattern.join("+"));
+                }
+            }
+            if (hits.length === 0)
+                continue;
+            const confidence = hits.length >= HIGH_CONFIDENCE_HITS ? "high" : "medium";
+            const invalidatePart = def.invalidate
+                ? `, invalidate=${fmtStates(def.invalidate)}`
+                : "";
+            suggestions.push({
+                function: fn.name,
+                file: fn.file || "",
+                role: def.role,
+                namespace: def.namespace,
+                pre: def.pre,
+                post: def.post,
+                invalidate: def.invalidate,
+                confidence,
+                reasons: hits,
+                template: `/* @progmune(namespace="${def.namespace}", pre=${fmtStates(def.pre)}, post=${fmtStates(def.post)}${invalidatePart}) */`,
+                maskRisk: false, // 两遍计算（见下）
+            });
+            break; // 一个函数只取最先命中的角色
+        }
+    }
+    // 第二遍：掩蔽风险——函数体调用了「已存在规则原语」或「本批同被建议的
+    // 函数」→ 注解后体内序列不再被验证，可能掩蔽其握有的违规（V7 实测：
+    // 植入流被 establish 注解变不透明后违规消失）。
+    const coSuggested = new Set(suggestions.map((s) => s.function));
+    for (const s of suggestions) {
+        const fnInfo = functions.find((f) => f.name === s.function);
+        s.maskRisk = (fnInfo?.calls || []).some((c) => (ruleNames?.has(c) ?? false) || coSuggested.has(c));
+    }
+    // 稳定性排序：置信度高优先，其次按 文件+名字（结果可复现）
+    const rank = { high: 0, medium: 1 };
+    suggestions.sort((a, b) => rank[a.confidence] - rank[b.confidence] ||
+        a.file.localeCompare(b.file) ||
+        a.function.localeCompare(b.function));
+    return suggestions.slice(0, limit);
+}
+function fmtStates(states) {
+    return `[${states.map((s) => `"${s}"`).join(", ")}]`;
+}

package/dist/annotation-suggest.test.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * annotation-suggest.test.ts — 注解建议引擎回归（纯函数，无文件系统 I/O）
+ *
+ * 词汇模式来自 3.7.6 金标 5/5 真实注解反推（REALWORLD_C_V6.md）：
+ * check_user_pass/auth_password=verify、handle_PASS=establish、
+ * do_RETR/do_STOR/new_session_channel=guard、open/close_data_connection=资源生命周期。
+ */
+const vitest_1 = require("vitest");
+const annotation_suggest_1 = require("./annotation-suggest");
+const fn = (name, extra = {}) => ({
+    name,
+    file: "src/demo.c",
+    ...extra,
+});
+(0, vitest_1.describe)("annotation-suggest", () => {
+    (0, vitest_1.it)("verify：凭证名词 × 比对动词（check_user_pass / auth_password）", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([fn("check_user_pass"), fn("auth_password")]);
+        (0, vitest_1.expect)(s).toHaveLength(2);
+        for (const x of s) {
+            (0, vitest_1.expect)(x.role).toBe("verify");
+            (0, vitest_1.expect)(x.namespace).toBe("auth");
+            (0, vitest_1.expect)(x.pre).toEqual(["UNAUTHENTICATED"]);
+            (0, vitest_1.expect)(x.post).toEqual(["PASSWORD_VERIFIED"]);
+        }
+    });
+    (0, vitest_1.it)("establish：登录完成原语（handle_PASS / authenticate）", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([fn("handle_PASS"), fn("authenticate")]);
+        (0, vitest_1.expect)(s.map((x) => [x.function, x.role])).toEqual(vitest_1.expect.arrayContaining([
+            ["handle_PASS", "establish"],
+            ["authenticate", "establish"],
+        ]));
+        (0, vitest_1.expect)(s[0].pre).toEqual([]);
+        (0, vitest_1.expect)(s[0].post).toEqual(["AUTHENTICATED"]);
+    });
+    (0, vitest_1.it)("guard：FTP 命令处理器与通道开启回调（do_RETR/do_STOR/new_session_channel）", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([
+            fn("do_RETR"),
+            fn("do_STOR"),
+            fn("new_session_channel"),
+        ]);
+        for (const x of s) {
+            (0, vitest_1.expect)(x.role).toBe("guard");
+            (0, vitest_1.expect)(x.pre).toEqual(["AUTHENTICATED"]);
+            (0, vitest_1.expect)(x.post).toEqual(["AUTHORIZED"]);
+        }
+    });
+    (0, vitest_1.it)("资源生命周期：open/close_data_connection", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([
+            fn("open_data_connection"),
+            fn("close_data_connection"),
+        ]);
+        const open = s.find((x) => x.function === "open_data_connection");
+        const close = s.find((x) => x.function === "close_data_connection");
+        (0, vitest_1.expect)(open?.role).toBe("open");
+        (0, vitest_1.expect)(open?.post).toEqual(["FILE_OPEN"]);
+        (0, vitest_1.expect)(close?.role).toBe("close");
+        (0, vitest_1.expect)(close?.pre).toEqual(["FILE_OPEN"]);
+        (0, vitest_1.expect)(close?.invalidate).toEqual(["FILE_OPEN"]);
+    });
+    (0, vitest_1.it)("已注解函数不再建议", () => {
+        const annotated = fn("check_user_pass", {
+            protocol: { pre_states: ["UNAUTHENTICATED"], post_states: ["PASSWORD_VERIFIED"], namespace: "auth" },
+        });
+        (0, vitest_1.expect)((0, annotation_suggest_1.suggestAnnotations)([annotated])).toHaveLength(0);
+    });
+    (0, vitest_1.it)("规则名函数（按名即命中）不再建议", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([fn("verify_password")], new Set(["verify_password"]));
+        (0, vitest_1.expect)(s).toHaveLength(0);
+    });
+    (0, vitest_1.it)("外部函数不再建议", () => {
+        (0, vitest_1.expect)((0, annotation_suggest_1.suggestAnnotations)([fn("check_password", { external: true })])).toHaveLength(0);
+    });
+    (0, vitest_1.it)("模板可直接粘贴：完整注释块文本", () => {
+        const [s] = (0, annotation_suggest_1.suggestAnnotations)([fn("check_user_pass")]);
+        (0, vitest_1.expect)(s.template).toBe('/* @progmune(namespace="auth", pre=["UNAUTHENTICATED"], post=["PASSWORD_VERIFIED"]) */');
+    });
+    (0, vitest_1.it)("确定性 + 上限：同输入同输出，超过 limit 截断（置信度优先）", () => {
+        const fns = Array.from({ length: 30 }, (_, i) => fn(`do_RETR_${i}`) // 全部 guard，单证据 medium
+        );
+        const a = (0, annotation_suggest_1.suggestAnnotations)(fns, undefined, 10);
+        const b = (0, annotation_suggest_1.suggestAnnotations)(fns, undefined, 10);
+        (0, vitest_1.expect)(a).toEqual(b);
+        (0, vitest_1.expect)(a).toHaveLength(10);
+        (0, vitest_1.expect)(a[0].function).toBe("do_RETR_0");
+    });
+    (0, vitest_1.it)("无命中词汇的函数不产生建议", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([fn("parse_int"), fn("strlcat"), fn("main")]);
+        (0, vitest_1.expect)(s).toHaveLength(0);
+    });
+    (0, vitest_1.it)("掩蔽风险：函数体调用已有规则原语 → maskRisk=true", () => {
+        const [s] = (0, annotation_suggest_1.suggestAnnotations)([fn("login_flow", { calls: ["verify_password"] })], new Set(["verify_password"]));
+        (0, vitest_1.expect)(s.maskRisk).toBe(true);
+    });
+    (0, vitest_1.it)("掩蔽风险：函数体调用本批同被建议的函数 → maskRisk=true（co-suggestion）", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([
+            fn("login_flow", { calls: ["start_file_transfer"] }),
+            fn("start_file_transfer"),
+        ]);
+        const flow = s.find((x) => x.function === "login_flow");
+        (0, vitest_1.expect)(flow?.maskRisk).toBe(true);
+    });
+    (0, vitest_1.it)("叶子函数（体内无规则原语调用）→ maskRisk=false", () => {
+        const [s] = (0, annotation_suggest_1.suggestAnnotations)([fn("check_user_pass", { calls: ["strcmp", "strlcpy"] })]);
+        (0, vitest_1.expect)(s.maskRisk).toBe(false);
+    });
+    (0, vitest_1.it)("会话工厂 new_session 不再误判为守卫", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([fn("new_session")]);
+        (0, vitest_1.expect)(s).toHaveLength(0);
+    });
+    (0, vitest_1.it)("通道守卫 new_session_channel 仍命中 guard", () => {
+        const s = (0, annotation_suggest_1.suggestAnnotations)([fn("new_session_channel")]);
+        (0, vitest_1.expect)(s).toHaveLength(1);
+        (0, vitest_1.expect)(s[0].role).toBe("guard");
+    });
+});

package/dist/sdk.js

@@ -20,7 +20,7 @@ const risk_model_1 = require("./risk-model");
 const protocol_knowledge_1 = require("./protocol-knowledge");
 const evidence_repository_1 = require("./evidence-repository");
 /** Runtime version — stable public identifier. Internal layers evolve underneath. */
-exports.RUNTIME_VERSION = "3.7.6";
+exports.RUNTIME_VERSION = "3.7.7";
 function verify(filePath) {
     const cert = (0, certify_1.certify)(filePath);
     const kb = (0, protocol_knowledge_1.buildKnowledgeBase)();

package/dist/trust/engine.js

@@ -60,6 +60,7 @@ const confidence_calculator_1 = require("./confidence-calculator");
 const violation_trace_1 = require("./violation-trace");
 const api_semantic_mapper_1 = require("./api-semantic-mapper");
 const protocol_domain_validator_1 = require("./protocol-domain-validator");
+const annotation_suggest_1 = require("../annotation-suggest");
 const call_graph_propagator_1 = require("./call-graph-propagator");
 const ssg_bridge_1 = require("./ssg-bridge");
 const call_sequence_1 = require("../call-sequence");
@@ -87,7 +88,7 @@ async function evaluateTrust(ctx) {
     // ── Phase 5: Build call graph for cross-function propagation ──
     const callGraph = (0, call_graph_propagator_1.buildCallGraphFromIR)(path.join(ctx.projectPath, "ir.json"));
     const enterpriseViolations = collectEnterpriseViolations(ctx);
-    const { violations: protocolViolations, coverage: mappingCoverageData, ssgCoverage: ssgCov } = await collectProtocolViolations(ctx, callGraph);
+    const { violations: protocolViolations, coverage: mappingCoverageData, ssgCoverage: ssgCov, annotationSuggestions: cAnnotationSuggestions } = await collectProtocolViolations(ctx, callGraph);
     const expressResult = collectExpressViolations(ctx);
     const nestjsResult = collectNestJSViolations(ctx);
     const trpcResult = collectTRPCViolations(ctx);
@@ -174,6 +175,7 @@ async function evaluateTrust(ctx) {
         commit: ctx.commit,
         timestamp,
         engineVersion,
+        annotationSuggestions: cAnnotationSuggestions,
         overall: {
             score: effectiveScore,
             decision,
@@ -717,6 +719,8 @@ async function collectProtocolViolations(ctx, callGraph) {
     let ssgTotalCalls = 0;
     let ssgMatchedCalls = 0;
     let ssgViolationCount = 0;
+    // C 注解建议（函数级作用域——返回值在 try 外组装）
+    let annotationSuggestions;
     try {
         // ── P4.5 校准：TS/JS 项目在 ir.json 缺失时先提取 IR ──
         // 序列必须来自「函数体内真实调用」而非「文件内函数声明名单」——
@@ -801,6 +805,10 @@ async function collectProtocolViolations(ctx, callGraph) {
         // ── P4.6.1: 词段匹配门控的项目函数集合（best-effort，与注解合并共用 ir.json） ──
         // 词段匹配只对项目函数适用（改名协议原语）；外部库调用走 alias/关键词桥接。
         let projectFunctions;
+        // ── 注解建议（采纳生死线）：未注解 C 项目的原语注解候选（加性，仅 C） ──
+        // 未注解项目 SSG 层静默（0 flags）——建议清单是「看不见的问题」的入口：
+        // 按函数名词汇启发式给出现成注释块模板（角色/命名空间/状态转移预填），
+        // 人工确认后生效（与 c-alias-propose 的确认门同一哲学）。
         try {
             const fs = require("fs");
             const irPath = path.join(ctx.projectPath, "ir.json");
@@ -808,6 +816,9 @@ async function collectProtocolViolations(ctx, callGraph) {
                 const ir = JSON.parse(fs.readFileSync(irPath, "utf-8"));
                 const functions = Array.isArray(ir) ? ir : (ir.functions || []);
                 projectFunctions = (0, call_sequence_1.collectProjectFunctionNames)(functions);
+                if ((ctx.language || "typescript") === "c") {
+                    annotationSuggestions = (0, annotation_suggest_1.suggestAnnotations)(functions, protocolRulesData ? new Set(protocolRulesData.rules.keys()) : undefined);
+                }
             }
         }
         catch { /* best-effort */ }
@@ -962,6 +973,7 @@ async function collectProtocolViolations(ctx, callGraph) {
             aliasWarnings: protocolRulesData.aliasWarnings?.length
                 ? protocolRulesData.aliasWarnings : undefined,
         } : undefined,
+        annotationSuggestions,
     };
 }
 function extractCallSequencesFromProject(projectPath, language, keepNames) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "progmune-runtime",
-  "version": "3.7.6",
+  "version": "3.7.7",
   "description": "Progmune — AI Trust Decision Engine. Verify AI-generated code before it reaches production. Outputs APPROVED / NEEDS_REVIEW / BLOCKED with evidence.",
   "files": [
     "dist/",