progmune-runtime 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [3.6.0] — 2026-08-23
+
+### 新增：SSG endState 检查（序列末尾资源未释放）
+
+- trust 桥接路径（`src/trust/ssg-bridge.ts`）补齐 endState 检测：函数序列末尾仍有未释放资源状态 → 违规（`endState: true`、`fixPath=[releaseFn]`、追加式修复文案、独立 rule_id `SSG_*_END_STATE_VIOLATION`）
+- 与 planner 语义对齐：共享判定 `findHeldResourceStates` + `RESOURCE_NAMESPACE_RE` 入 `ssg-validator.ts`（planner 重构换用，语义不变）
+- 边界：仅资源生命周期命名空间（auth/session 合法地以活跃会话结束不检查）；仅本序列新获取的状态（继承自初始态不算泄漏）
+- **Python 协议盲测 v1 复测：40/40 全检出（Recall/Precision 100%，0 FP）**，基线 `BASELINE_PROTOCOL_PYTHON_v1.md`
+
+### 新增：Python 协议盲测基准（v1）
+
+- `blind-benchmark/generate-projects-protocol-python.ts` + `scan-protocol-python.ts` + `expand-gold-protocol-python.ts`：6 违规类型 × 4 结构风格 = 24 项目，金标 `annotations-protocol-python-v1.json`
+- 测量生产 SSG 桥接校验器（确定性、无 LLM）；回归测试 `tests/python-protocol-benchmark.test.ts`
+
+### 文档
+
+- README 新增「社区与反馈」章节：讨论群二维码（`assets/wechat-group.png`，当前为占位图待替换真实群码）+ GitHub Issues 通道（中英双语）
+- README 删除双峰（Two-Hump）内容：科学基础章节的双峰类比段与 P0-P3 节的双峰报告链接
+- 覆盖矩阵（中英）刷新至 2026-08-23 并新增英文版 `coverage-matrix-en.md`；架构图规则数修正 140→148（与 protocols.json 实测一致）
+
 ## [3.5.0] — 2026-08-22
 
 ### 新增：多语言合并 IR（注册表式提取）

package/README.md

@@ -118,7 +118,7 @@ Progmune is honest about what it can and cannot verify.
 - **Framework internals** — well-known framework dispatch/cache machinery (e.g. django-unicorn internals) can produce a small number of boundary false positives; they are documented per-corpus in the benchmark gold files.
 - **Known failure boundaries are documented** rather than hidden: if Progmune cannot verify a language (e.g. Go), Confidence is lowered instead of pretending 100%.
 
-→ [Full Coverage Matrix](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/coverage-matrix.md)
+→ [Full Coverage Matrix](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/coverage-matrix-en.md)
 
 ---
 
@@ -162,7 +162,7 @@ C analysis is **research-only**: gold benchmark F1=16.5% across 4 repos (curl, l
 - Bootstrapping deadlock broken: all 21 protocol namespaces now have rule vocabulary
 - `excludePatterns` + `languages` architecture for FP management
 
-→ [Two-Hump Report](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/two-hump-report.md) · [P0-P3 Final Report](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/p0-p3-final-report.md)
+→ [P0-P3 Final Report](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/p0-p3-final-report.md)
 
 ---
 
@@ -179,7 +179,7 @@ SDK (src/sdk.ts)           verify() → APPROVED / NEEDS_REVIEW / BLOCKED
        │                     source-level markers: taint tracking, import resolution,
        │                     qualified call chains, cross-file template analysis
        ├─ Repair Executor   detect → plan → fix → validate → commit/rollback
-       └─ Knowledge Base    31 domains, 140 rules, evidence chains
+       └─ Knowledge Base    31 domains, 148 rules, evidence chains
 ```
 
 ### Interfaces
@@ -194,12 +194,20 @@ SDK (src/sdk.ts)           verify() → APPROVED / NEEDS_REVIEW / BLOCKED
 
 ---
 
+## Community & Feedback
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shenlian19831109/progmune-runtime/main/assets/wechat-group.png" width="240" alt="Progmune user discussion group QR code" />
+</p>
+
+Your feedback shapes Progmune. Scan the QR code to join the user discussion group (WeChat), or open a [GitHub Issue](https://github.com/shenlian19831109/progmune-runtime/issues) for bug reports, feature requests, and suggestions.
+
+---
+
 ## Scientific Foundation
 
 Progmune is built on the premise that **LLM outputs are statistical performances, not reasoning** — a view developed by Subbarao Kambhampati et al. in the position paper ["Stop Anthropomorphizing Intermediate Tokens as Reasoning/Thinking Traces!"](https://arxiv.org/abs/2505.22285) (arXiv:2505.22285, 2025) and elaborated in his ICML 2026 talk "On the Role of Verifiers and Thinking Traces in Reasoning Models". Rather than trusting what the model says about code, Progmune verifies what the program actually does — using protocol state machines, IR extraction, and evidence-backed decision chains.
 
-Coverage-gap analysis borrows the "two-hump problem" terminology **as a cross-domain analogy** from Sergei Gukov's work in mathematical physics (the Andrews-Curtis conjecture in group theory, 2026) — it describes a bimodal coverage distribution, not a collaboration. See [Two-Hump Report](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/two-hump-report.md) for the full methodology.
-
 → [Investor Whitepaper](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/Progmune_投资人白皮书_v2.0.html) · [Trust Decision Model](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/ai-trust-decision-model-v1.md)
 
 ---

package/README.zh-CN.md

@@ -162,7 +162,7 @@ C 分析**仅研究**：黄金基准 F1=16.5%，覆盖 4 个仓库（curl、libs
 - 打破引导死锁：全部 21 个协议命名空间已有规则词汇
 - `excludePatterns` + `languages` 架构管理误报
 
-→ [双峰报告](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/two-hump-report.md) · [P0-P3 终报](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/p0-p3-final-report.md)
+→ [P0-P3 终报](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/p0-p3-final-report.md)
 
 ---
 
@@ -178,7 +178,7 @@ SDK (src/sdk.ts)           verify() → APPROVED / NEEDS_REVIEW / BLOCKED
        │                     合并为每项目一份函数 IR；
        │                     源码级标记：污点追踪、import 解析、限定调用链、跨文件模板分析
        ├─ 修复执行器         detect → plan → fix → validate → commit/rollback
-       └─ 知识库             31 个域、140 条规则、证据链
+       └─ 知识库             31 个域、148 条规则、证据链
 ```
 
 ### 接口
@@ -193,12 +193,20 @@ SDK (src/sdk.ts)           verify() → APPROVED / NEEDS_REVIEW / BLOCKED
 
 ---
 
+## 社区与反馈
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shenlian19831109/progmune-runtime/main/assets/wechat-group.png" width="240" alt="Progmune 用户讨论群二维码" />
+</p>
+
+你的意见塑造 Progmune。扫码加入用户讨论群（微信），或通过 [GitHub Issue](https://github.com/shenlian19831109/progmune-runtime/issues) 提交缺陷报告、功能需求与建议。
+
+---
+
 ## 科学基础
 
 Progmune 建立在"**LLM 输出是统计表演而非推理**"这一前提上——该观点源自 Subbarao Kambhampati 等人的立场论文 ["Stop Anthropomorphizing Intermediate Tokens as Reasoning/Thinking Traces!"](https://arxiv.org/abs/2505.22285)（arXiv:2505.22285，2025），并在其 ICML 2026 演讲 "On the Role of Verifiers and Thinking Traces in Reasoning Models" 中展开。Progmune 不信任模型对代码的说法，而是用协议状态机、IR 提取与证据链验证程序实际行为。
 
-覆盖缺口分析借用"双峰问题"术语作为**跨域类比**，源自 Sergei Gukov 在数学物理领域的工作（群论中的 Andrews-Curtis 猜想，2026）——它描述的是双峰覆盖分布，而非合作关系。详见 [双峰报告](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/two-hump-report.md)。
-
 → [投资人白皮书](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/Progmune_投资人白皮书_v2.0.html) · [信任决策模型](https://github.com/shenlian19831109/progmune-runtime/blob/main/docs/ai-trust-decision-model-v1.md)
 
 ---

package/dist/planner.js

@@ -392,26 +392,10 @@ function validateProtocolWithTransitions(actions, protocols, namespaceInitialSta
         }
     }
     // End-of-sequence check: held resources must be released (resource leak).
-    // A state S is resource-holding when some rule REQUIRES S and INVALIDATES S
-    // (acquire/release semantics — e.g. FILE_OPEN set by open_file, released by
-    // close_file). Only RESOURCE-LIFECYCLE namespaces apply: session/auth flows
-    // legitimately END with an active session (SESSION_ACTIVE is not a leak).
-    const RESOURCE_NS = /^(file|db|database|connection|conn|socket|stream|resource|io)/i;
-    const heldStates = [];
-    for (const p of protocols) {
-        const ann = p.protocol;
-        if (!ann)
-            continue;
-        const ns = ann.namespace || "";
-        if (!RESOURCE_NS.test(ns))
-            continue;
-        const inv = ann.invalidate || [];
-        const pre = ann.pre_states || [];
-        for (const s of inv) {
-            if (pre.includes(s))
-                heldStates.push({ state: s, releaseFn: p.function, namespace: ns });
-        }
-    }
+    // 共享判定见 ssg-validator.findHeldResourceStates：资源生命周期命名空间 +
+    // pre/invalidate 交集（获取/释放语义）。会话/认证流合法地以活跃会话结束，
+    // 不在检查范围（SESSION_ACTIVE 不是泄漏）。
+    const heldStates = (0, ssg_validator_1.findHeldResourceStates)(rules);
     // 只检查"本序列中获取"的持有状态——继承自命名空间初始状态的
     // （如 db 初始即 DB_CONNECTED）不算泄漏。
     const acquiredStates = new Set();

package/dist/ssg-validator.js

@@ -33,7 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StateMachineValidator = exports.InvariantViolationError = void 0;
+exports.StateMachineValidator = exports.InvariantViolationError = exports.RESOURCE_NAMESPACE_RE = void 0;
+exports.findHeldResourceStates = findHeldResourceStates;
 exports.rebuildState = rebuildState;
 exports.applyTransitionDelta = applyTransitionDelta;
 exports.findFixPathStatic = findFixPathStatic;
@@ -51,6 +52,28 @@ exports.explainRejection = explainRejection;
 exports.rejectionToJSON = rejectionToJSON;
 exports.parseProtocolsFromJSON = parseProtocolsFromJSON;
 const crypto = __importStar(require("crypto"));
+/** 资源生命周期命名空间：会话/认证流合法地以活跃会话结束（SESSION_ACTIVE 不是泄漏），
+ *  只有资源类命名空间（文件/数据库/连接/流等）做序列末尾持有状态检查。 */
+exports.RESOURCE_NAMESPACE_RE = /^(file|db|database|connection|conn|socket|stream|resource|io)/i;
+/**
+ * 找出资源持有状态候选：某规则的 pre_states 与 invalidate 的交集
+ * （获取/释放语义——如 FILE_OPEN 由 open_file 设置、close_file 释放），
+ * 仅限资源生命周期命名空间。planner 与 trust 桥接共用（endState 检查）。
+ */
+function findHeldResourceStates(rules) {
+    const held = [];
+    for (const [fn, ann] of rules) {
+        const ns = ann.namespace || "";
+        if (!exports.RESOURCE_NAMESPACE_RE.test(ns))
+            continue;
+        for (const s of ann.invalidate || []) {
+            if ((ann.pre_states || []).includes(s)) {
+                held.push({ state: s, releaseFn: fn, namespace: ns });
+            }
+        }
+    }
+    return held;
+}
 const DEFAULT_NAMESPACE = "_global";
 class InvariantViolationError extends Error {
     constructor(message, detail) {

package/dist/trust/ssg-bridge.js

@@ -342,6 +342,18 @@ function validateSequenceWithSSG(steps, rules, namespaceInitialStates, file, ali
             return undefined;
         }
     })();
+    // 本序列中"新获取"的资源状态（endState 检查只针对本序列获取、未释放的状态——
+    // 继承自命名空间初始状态的不算泄漏，与 planner 语义一致）
+    const acquiredStates = new Set();
+    const trackAcquiredStates = (before, after) => {
+        for (const ns of Object.keys(after)) {
+            const prev = before?.[ns] || [];
+            for (const s of after[ns]) {
+                if (!prev.includes(s))
+                    acquiredStates.add(`${ns}::${s}`);
+            }
+        }
+    };
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
         const namespace = DOMAIN_TO_NAMESPACE[step.domain] || "stateless";
@@ -385,6 +397,7 @@ function validateSequenceWithSSG(steps, rules, namespaceInitialStates, file, ali
                 // Advance state
                 ctx.ledger.push(result.transition);
                 ctx.currentState = result.transition.statesAfter;
+                trackAcquiredStates(result.transition.statesBefore, result.transition.statesAfter);
             }
             else {
                 violatedCalls++;
@@ -414,6 +427,7 @@ function validateSequenceWithSSG(steps, rules, namespaceInitialStates, file, ali
                 // Still advance state on rejection (best-effort: apply transition anyway
                 // so subsequent calls can be validated)
                 ctx.ledger.push(result.transition);
+                trackAcquiredStates(result.transition.statesBefore, result.transition.statesAfter);
             }
         }
         catch {
@@ -440,6 +454,39 @@ function validateSequenceWithSSG(steps, rules, namespaceInitialStates, file, ali
             valid: true,
         });
     }
+    // ── End-of-sequence check: held resources must be released (resource leak).
+    // 共享判定见 ssg-validator.findHeldResourceStates：仅资源生命周期命名空间 +
+    // pre/invalidate 交集；只报本序列获取且最终仍持有的状态（对齐 planner）。
+    for (const hs of (0, ssg_validator_1.findHeldResourceStates)(rules)) {
+        const ctx = contexts.get(hs.namespace);
+        if (!ctx)
+            continue;
+        if (!acquiredStates.has(`${hs.namespace}::${hs.state}`))
+            continue;
+        const cur = ctx.currentState[hs.namespace] || [];
+        if (!cur.includes(hs.state))
+            continue;
+        violatedCalls++;
+        violations.push({
+            callName: "(end-of-sequence)",
+            namespace: hs.namespace,
+            currentState: cur,
+            requiredState: [],
+            fixPath: [hs.releaseFn],
+            matchedRule: hs.releaseFn,
+            endState: true,
+            explanation: `SSG end-state violation: resource state [${hs.state}] ` +
+                `acquired in this function is still held at end of sequence ` +
+                `(namespace ${hs.namespace}, current [${cur.join(", ")}]) — ` +
+                `missing release call: ${hs.releaseFn}.`,
+        });
+        trace.push({
+            call: "(end-of-sequence)",
+            namespace: hs.namespace,
+            matchedRule: hs.releaseFn,
+            valid: false,
+        });
+    }
     return {
         passed: violations.length === 0,
         trace,
@@ -459,19 +506,30 @@ function validateSequenceWithSSG(steps, rules, namespaceInitialStates, file, ali
 function ssgViolationsToTrustViolations(ssgResult, file, funcName) {
     return ssgResult.violations.map((v) => ({
         severity: "medium",
-        rule_id: `SSG_${v.namespace.toUpperCase()}_STATE_VIOLATION`,
+        rule_id: v.endState
+            ? `SSG_${v.namespace.toUpperCase()}_END_STATE_VIOLATION`
+            : `SSG_${v.namespace.toUpperCase()}_STATE_VIOLATION`,
         file,
         function: funcName,
         message: v.explanation,
-        evidence: `Call: ${v.callName} | Rule: ${v.matchedRule || "unknown"} | ` +
-            `Required: [${v.requiredState.join(", ")}] | ` +
-            `Current: [${v.currentState.join(", ")}]`,
-        why: `Protocol state machine violation in namespace "${v.namespace}": ` +
-            `function "${v.callName}" cannot be called in current state ` +
-            `[${v.currentState.join(", ")}]. Required pre-states: [${v.requiredState.join(", ")}].`,
-        fix: v.fixPath.length > 0
-            ? `Insert before the violating call: ${v.fixPath.join(" → ")}`
-            : `Review protocol documentation for namespace "${v.namespace}" to understand required state transitions.`,
+        evidence: v.endState
+            ? `End-of-sequence: held resource state [${v.currentState.join(", ")}] | ` +
+                `Release call: ${v.fixPath.join(" → ") || "unknown"}`
+            : `Call: ${v.callName} | Rule: ${v.matchedRule || "unknown"} | ` +
+                `Required: [${v.requiredState.join(", ")}] | ` +
+                `Current: [${v.currentState.join(", ")}]`,
+        why: v.endState
+            ? `Protocol state machine violation in namespace "${v.namespace}": ` +
+                `a resource acquired in this function ([${v.currentState.join(", ")}]) ` +
+                `is still held when the function ends — resource leak.`
+            : `Protocol state machine violation in namespace "${v.namespace}": ` +
+                `function "${v.callName}" cannot be called in current state ` +
+                `[${v.currentState.join(", ")}]. Required pre-states: [${v.requiredState.join(", ")}].`,
+        fix: v.endState
+            ? `Append the release call at the end of the function: ${v.fixPath.join(" → ")}`
+            : v.fixPath.length > 0
+                ? `Insert before the violating call: ${v.fixPath.join(" → ")}`
+                : `Review protocol documentation for namespace "${v.namespace}" to understand required state transitions.`,
         policy_ref: `protocol-safety.ssg.${v.namespace}`,
     }));
 }

package/dist/trust/ssg-bridge.test.js

@@ -167,17 +167,22 @@ function step(api, domain, description = "") {
             }
         });
         (0, vitest_1.it)("detects missing cleanup (file opened but not closed)", () => {
-            // open_file without close_file — state machine will show FILE_OPEN still active
+            // open_file without close_file — held FILE_OPEN at end of sequence
             const steps = [
                 step("fs.openSync", "conn_mgmt", "Open file"),
                 step("fs.readFileSync", "conn_mgmt", "Read file contents"),
                 // Missing: close_file
             ];
             const result = validate(steps);
-            // The SSG state machine tracks that file is still open.
-            // While it may not report this as a violation (since close_file
-            // isn't called), the state trace should show FILE_OPEN is active.
-            (0, vitest_1.expect)(result.trace.length).toBe(steps.length);
+            // endState 检查：序列末尾资源未释放 → 违规 + 追加式修复路径
+            const endState = result.violations.filter((v) => v.endState);
+            (0, vitest_1.expect)(endState).toHaveLength(1);
+            (0, vitest_1.expect)(endState[0].namespace).toBe("file");
+            (0, vitest_1.expect)(endState[0].currentState).toContain("FILE_OPEN");
+            (0, vitest_1.expect)(endState[0].fixPath).toEqual(["close_file"]);
+            (0, vitest_1.expect)(result.passed).toBe(false);
+            // trace 含步骤节点 + 末尾 endState 节点
+            (0, vitest_1.expect)(result.trace.length).toBe(steps.length + 1);
         });
     });
     (0, vitest_1.describe)("violation → TrustViolation conversion", () => {

package/package.json

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