progmune-runtime 2.1.5 → 3.2.0

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

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * SSG Bridge — Smoke Tests
+ *
+ * Validates that the SSG bridge correctly:
+ *   1. Maps semantic domains to SSG namespaces
+ *   2. Matches real API calls to protocol rules
+ *   3. Detects state machine violations
+ *   4. Passes valid sequences without false positives
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const ssg_bridge_1 = require("./ssg-bridge");
+// Load protocol rules once for all tests
+const protoData = (0, ssg_bridge_1.loadProtocolRules)();
+const rules = protoData?.rules;
+const nsInit = protoData?.namespaceInitialStates || {};
+const aliasIndex = protoData?.aliasIndex || new Map();
+const noAliases = new Map(); // empty alias map for fallback tests
+// Helper: run SSG validation with alias index
+function validate(steps, file = "test.ts") {
+    return (0, ssg_bridge_1.validateSequenceWithSSG)(steps, rules, nsInit, file, aliasIndex);
+}
+// Helper: build a minimal SemanticStep
+function step(api, domain, description = "") {
+    return {
+        api,
+        domain: domain,
+        description,
+        source: "lookup",
+    };
+}
+(0, vitest_1.describe)("SSG Bridge", () => {
+    (0, vitest_1.it)("loads protocol rules from protocols.json", () => {
+        (0, vitest_1.expect)(rules).toBeDefined();
+        (0, vitest_1.expect)(rules.size).toBeGreaterThan(100);
+        (0, vitest_1.expect)(nsInit).toBeDefined();
+        (0, vitest_1.expect)(nsInit["auth"]).toBeDefined();
+    });
+    (0, vitest_1.describe)("call → rule inference", () => {
+        (0, vitest_1.it)("matches bcrypt-like calls to auth rules", () => {
+            const steps = [
+                step("bcrypt.compare", "auth_hash", "Verify password against stored hash"),
+            ];
+            const result = validate(steps);
+            (0, vitest_1.expect)(result.stats.matchedCalls).toBeGreaterThanOrEqual(1);
+        });
+        (0, vitest_1.it)("matches JWT-like calls to auth rules", () => {
+            const steps = [
+                step("jwt.sign", "auth_mech", "Generate JWT token"),
+            ];
+            const result = validate(steps);
+            (0, vitest_1.expect)(result.stats.matchedCalls).toBeGreaterThanOrEqual(1);
+        });
+        (0, vitest_1.it)("matches TLS-related calls to tls rules", () => {
+            const steps = [
+                step("https.createServer", "http_ops", "Create HTTPS server"),
+            ];
+            const result = validate(steps);
+            // http_ops maps to "tls" namespace, and createServer → http_create_server rule
+            (0, vitest_1.expect)(result.stats.matchedCalls).toBeGreaterThanOrEqual(1);
+        });
+        (0, vitest_1.it)("matches file I/O calls to resource rules", () => {
+            const steps = [
+                step("fs.openSync", "conn_mgmt", "Open file for reading"),
+            ];
+            const result = validate(steps);
+            (0, vitest_1.expect)(result.stats.matchedCalls).toBeGreaterThanOrEqual(1);
+        });
+        (0, vitest_1.it)("does not match util/stateless calls", () => {
+            const steps = [
+                step("console.log", "util", "Log output"),
+                step("JSON.parse", "util", "Parse JSON"),
+            ];
+            const result = validate(steps);
+            (0, vitest_1.expect)(result.stats.matchedCalls).toBe(0);
+            (0, vitest_1.expect)(result.stats.unmatchedCalls).toBe(steps.length);
+        });
+    });
+    (0, vitest_1.describe)("alias-based matching (exact)", () => {
+        (0, vitest_1.it)("matches bcrypt.compare to verify_hash via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("bcrypt.compare")).toBe("verify_hash");
+        });
+        (0, vitest_1.it)("matches bcrypt.hash to hash_password via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("bcrypt.hash")).toBe("hash_password");
+        });
+        (0, vitest_1.it)("matches jsonwebtoken.sign to generate_jwt via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("jsonwebtoken.sign")).toBe("generate_jwt");
+        });
+        (0, vitest_1.it)("matches jsonwebtoken.verify to verify_token via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("jsonwebtoken.verify")).toBe("verify_token");
+        });
+        (0, vitest_1.it)("matches fs.openSync to open_file via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("fs.opensync")).toBe("open_file");
+        });
+        (0, vitest_1.it)("matches prisma.model.findMany to query_db via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("prisma.model.findmany")).toBe("query_db");
+        });
+        (0, vitest_1.it)("matches prisma.$disconnect to disconnect_db via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("prisma.$disconnect")).toBe("disconnect_db");
+        });
+        (0, vitest_1.it)("matches express.listen to http_create_server via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("express.listen")).toBe("http_create_server");
+        });
+        (0, vitest_1.it)("matches app.listen to http_create_server via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("app.listen")).toBe("http_create_server");
+        });
+        (0, vitest_1.it)("matches db.transaction to begin_tx via alias", () => {
+            (0, vitest_1.expect)(aliasIndex.get("db.transaction")).toBe("begin_tx");
+        });
+        (0, vitest_1.it)("alias index has expected number of entries", () => {
+            // 21 rules with aliases, each with 3-10+ aliases
+            (0, vitest_1.expect)(aliasIndex.size).toBeGreaterThanOrEqual(50);
+        });
+        (0, vitest_1.it)("no duplicate alias mappings", () => {
+            // Each alias should map to exactly one rule
+            const values = Array.from(aliasIndex.values());
+            const uniqueValues = new Set(values);
+            // All unique rules should be present
+            (0, vitest_1.expect)(uniqueValues.size).toBeGreaterThanOrEqual(15);
+        });
+    });
+    (0, vitest_1.describe)("state machine validation", () => {
+        (0, vitest_1.it)("accepts jwt.sign as entry point (OAuth / cold start)", () => {
+            // generate_jwt is now an entry point (empty pre_states) because
+            // JWT can be generated from OAuth flow or password flow.
+            // See: state machine split — auth vs registration namespaces.
+            const steps = [
+                step("jwt.sign", "auth_mech", "Generate JWT token (OAuth callback or login)"),
+            ];
+            const result = validate(steps);
+            // jwt.sign maps to generate_jwt which now has empty pre_states
+            // → should match and pass without violations
+            (0, vitest_1.expect)(result.stats.matchedCalls).toBeGreaterThanOrEqual(1);
+            (0, vitest_1.expect)(result.violations.length).toBe(0);
+        });
+        (0, vitest_1.it)("passes valid auth sequence (all entry points after split)", () => {
+            // After state machine split:
+            // - bcrypt.hash → hash_password (registration, entry point)
+            // - bcrypt.compare → verify_hash (auth/login, entry point)
+            // - jwt.sign → generate_jwt (auth, entry point for OAuth/login)
+            // All three are now valid entry points — no pre_state requirements.
+            const steps = [
+                step("bcrypt.hash", "auth_hash", "Hash password (registration flow)"),
+                step("bcrypt.compare", "auth_hash", "Verify password (login flow)"),
+                step("jwt.sign", "auth_mech", "Generate JWT token"),
+            ];
+            const result = validate(steps);
+            (0, vitest_1.expect)(result.stats.matchedCalls).toBeGreaterThanOrEqual(3);
+            (0, vitest_1.expect)(result.violations.length).toBe(0);
+        });
+        (0, vitest_1.it)("passes valid TLS sequence", () => {
+            const steps = [
+                step("fs.readFileSync", "tls_config", "Load TLS certificate"),
+                step("https.createServer", "http_ops", "Create HTTPS server with TLS"),
+            ];
+            const result = validate(steps);
+            // load_tls_config → TLS_CONFIGURED
+            // http_create_server requires TLS_CONFIGURED
+            // No state violations expected for correct sequence
+            const tlsViolations = result.violations.filter(v => v.namespace === "tls");
+            if (tlsViolations.length > 0) {
+                // If there are violations, they should include fix paths
+                for (const v of tlsViolations) {
+                    (0, vitest_1.expect)(v.explanation).toBeTruthy();
+                }
+            }
+        });
+        (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
+            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);
+        });
+    });
+    (0, vitest_1.describe)("violation → TrustViolation conversion", () => {
+        (0, vitest_1.it)("converts SSG violations to TrustViolation format", () => {
+            const mockResult = {
+                passed: false,
+                trace: [],
+                violations: [{
+                        callName: "jwt.sign",
+                        namespace: "auth",
+                        currentState: ["UNAUTHENTICATED"],
+                        requiredState: ["PASSWORD_VERIFIED"],
+                        fixPath: ["hash_password", "verify_hash"],
+                        matchedRule: "generate_jwt",
+                        explanation: "State violation: requires PASSWORD_VERIFIED but current is UNAUTHENTICATED",
+                    }],
+                stats: { totalCalls: 1, matchedCalls: 1, unmatchedCalls: 0, validatedCalls: 1, violatedCalls: 1 },
+            };
+            const tv = (0, ssg_bridge_1.ssgViolationsToTrustViolations)(mockResult, "auth.ts", "login");
+            (0, vitest_1.expect)(tv.length).toBe(1);
+            (0, vitest_1.expect)(tv[0].rule_id).toContain("SSG_AUTH");
+            (0, vitest_1.expect)(tv[0].severity).toBe("medium");
+            (0, vitest_1.expect)(tv[0].file).toBe("auth.ts");
+            (0, vitest_1.expect)(tv[0].function).toBe("login");
+            (0, vitest_1.expect)(tv[0].fix).toContain("hash_password");
+        });
+    });
+    (0, vitest_1.describe)("loadProjectAliases", () => {
+        (0, vitest_1.it)("returns null when no .progmune_aliases.json exists", () => {
+            const result = (0, ssg_bridge_1.loadProjectAliases)("/tmp/nonexistent", new Set(["rule_a"]));
+            (0, vitest_1.expect)(result).toBeNull();
+        });
+        (0, vitest_1.it)("validates that target rules exist", () => {
+            // We need a real temp dir with a .progmune_aliases.json
+            const fs = require("fs");
+            const path = require("path");
+            const tmpDir = fs.mkdtempSync("/tmp/progmune-test-");
+            const aliasPath = path.join(tmpDir, ".progmune_aliases.json");
+            fs.writeFileSync(aliasPath, JSON.stringify({
+                aliases: {
+                    "createSessionToken": "create_user_session",
+                    "unknownWrapper": "nonexistent_rule",
+                }
+            }));
+            const result = (0, ssg_bridge_1.loadProjectAliases)(tmpDir, new Set(["create_user_session"]));
+            (0, vitest_1.expect)(result).not.toBeNull();
+            (0, vitest_1.expect)(result.aliases["createsessiontoken"]).toBe("create_user_session");
+            // unknownWrapper should have been skipped with a warning
+            (0, vitest_1.expect)(result.aliases["unknownwrapper"]).toBeUndefined();
+            (0, vitest_1.expect)(result.warnings.length).toBeGreaterThanOrEqual(1);
+            (0, vitest_1.expect)(result.warnings[0]).toContain("nonexistent_rule");
+            // Cleanup
+            fs.unlinkSync(aliasPath);
+            fs.rmdirSync(tmpDir);
+        });
+        (0, vitest_1.it)("respects case-insensitive alias keys", () => {
+            const fs = require("fs");
+            const path = require("path");
+            const tmpDir = fs.mkdtempSync("/tmp/progmune-test-");
+            fs.writeFileSync(path.join(tmpDir, ".progmune_aliases.json"), JSON.stringify({
+                aliases: {
+                    "CreateSessionToken": "create_user_session",
+                }
+            }));
+            const result = (0, ssg_bridge_1.loadProjectAliases)(tmpDir, new Set(["create_user_session"]));
+            (0, vitest_1.expect)(result.aliases["createsessiontoken"]).toBe("create_user_session");
+            fs.unlinkSync(path.join(tmpDir, ".progmune_aliases.json"));
+            fs.rmdirSync(tmpDir);
+        });
+        (0, vitest_1.it)("merges project aliases without overriding global ones", () => {
+            // Load rules with project aliases — global aliasIndex should still have
+            // the global entries, and project entries should be additive
+            const data = (0, ssg_bridge_1.loadProtocolRules)("/Users/shenlian/printlab_mvp");
+            (0, vitest_1.expect)(data).not.toBeNull();
+            // Global aliases should still be present
+            (0, vitest_1.expect)(data.aliasIndex.get("bcrypt.compare")).toBe("verify_hash");
+            (0, vitest_1.expect)(data.aliasIndex.get("jsonwebtoken.sign")).toBe("generate_jwt");
+            // Project aliases should be present (from .progmune_aliases.json)
+            (0, vitest_1.expect)(data.aliasIndex.get("createsessiontoken")).toBe("create_user_session");
+            (0, vitest_1.expect)(data.aliasIndex.get("sendemail")).toBe("send_notification");
+            // Project aliases should be recorded separately
+            (0, vitest_1.expect)(data.projectAliases).toBeDefined();
+            (0, vitest_1.expect)(Object.keys(data.projectAliases).length).toBeGreaterThan(10);
+            // Should not have warnings for valid rules
+            const warnCount = (data.aliasWarnings || []).filter(w => w.includes("not found")).length;
+            (0, vitest_1.expect)(warnCount).toBe(0);
+        });
+    });
+});

package/dist/trust/types.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Phase 1: AI Trust Decision Model — Type Definitions
+ *
+ * Self-contained type system for the Trust Decision Engine.
+ * Does NOT modify or depend on existing types in src/policy/types.ts
+ * or src/audit/types.ts. The Trust Engine maps from those types into
+ * these types during evaluation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECISION_THRESHOLDS = exports.DEFAULT_GOVERNANCE_DEDUCTIONS = exports.DEFAULT_COVERAGE_MAX_SCORES = exports.DEFAULT_PROTOCOL_WEIGHTS = exports.DEFAULT_SEVERITY_DEDUCTIONS = exports.DEFAULT_DIMENSION_WEIGHTS = exports.TRUST_VIOLATION_REQUIRED_FIELDS = void 0;
+/** The 7 required fields for explainability completeness */
+exports.TRUST_VIOLATION_REQUIRED_FIELDS = [
+    "severity",
+    "rule_id",
+    "file",
+    "function",
+    "evidence",
+    "why",
+    "fix",
+    "policy_ref",
+];
+// ── Default Dimension Weights (from design doc) ──
+exports.DEFAULT_DIMENSION_WEIGHTS = {
+    policyCompliance: 0.35,
+    protocolSafety: 0.30,
+    verificationCoverage: 0.20,
+    governanceIntegrity: 0.15,
+    evolutionStability: 0.00, // N/A in v1
+};
+// ── Default Severity Deductions (from design doc) ──
+exports.DEFAULT_SEVERITY_DEDUCTIONS = {
+    critical: 40,
+    high: 20,
+    medium: 8,
+    low: 2,
+};
+// ── Default Protocol Weights ──
+exports.DEFAULT_PROTOCOL_WEIGHTS = {
+    authentication: 0.25,
+    authorization: 0.20,
+    payment: 0.20,
+    data_integrity: 0.20,
+    ledger: 0.15,
+};
+// ── Default Verification Coverage Max Scores ──
+exports.DEFAULT_COVERAGE_MAX_SCORES = {
+    typescriptTypeCheck: 25,
+    ssgRules: 30,
+    ledgerInvariant: 20,
+    coverage: 15,
+    failureGenome: 10,
+};
+// ── Default Governance Integrity Deductions ──
+exports.DEFAULT_GOVERNANCE_DEDUCTIONS = {
+    hashMismatch: 50,
+    ledgerMissing: 30,
+    chainBroken: 20,
+    auditIncomplete: 10,
+};
+// ── Decision Thresholds ──
+exports.DECISION_THRESHOLDS = {
+    approved: 80,
+    needsReview: 60,
+    // below 60 = BLOCKED
+    criticalLock: 59, // max score when critical violation exists
+};

package/dist/trust/violation-trace.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * Phase 3: ViolationTrace — Structured Reasoning Chain
+ *
+ * Replaces string-concatenated violation messages with first-class
+ * ViolationTrace objects. Each trace captures the step-by-step protocol
+ * state transition that led to the violation, making it possible for
+ * an engineer who hasn't read protocols.json to understand the causal
+ * chain in under 2 minutes.
+ *
+ * Design principle: trace length → understanding time should be LINEAR,
+ * not exponential. This solves the "reasoning step disaster" where hidden
+ * intermediate states cause comprehension difficulty to explode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildViolationTrace = buildViolationTrace;
+exports.renderTraceAsText = renderTraceAsText;
+exports.renderTraceSummary = renderTraceSummary;
+exports.buildViolationTraces = buildViolationTraces;
+// ── Trace Builder ──
+/**
+ * Build a violation trace from a trust violation and its protocol context.
+ *
+ * The trace is a chain of protocol state transitions showing:
+ *   1. The sequence of function calls leading up to the violation
+ *   2. The expected protocol state at each step
+ *   3. The actual state at each step
+ *   4. The exact point where expectation and reality diverged
+ *   5. The fix: what should have been called instead
+ *
+ * @param violation - The violation to trace
+ * @param protocolStates - Optional ordered list of protocol states observed
+ * @param functionCalls - Optional ordered list of function calls (from IR)
+ * @returns A structured ViolationTrace
+ */
+function buildViolationTrace(violation, protocolStates, functionCalls) {
+    const steps = [];
+    const references = [];
+    // Extract RFC/protocol reference
+    if (violation.policy_ref) {
+        references.push(violation.policy_ref);
+    }
+    // ── Build the reasoning chain ──
+    if (protocolStates && protocolStates.length > 0 && functionCalls && functionCalls.length > 0) {
+        // Full trace: we have the actual state machine walk
+        buildFullTrace(steps, protocolStates, functionCalls, violation);
+    }
+    else {
+        // Minimal trace: reconstruct from violation fields alone
+        buildMinimalTrace(steps, violation);
+    }
+    // Calculate violation point
+    const violationIdx = steps.findIndex(s => s.isViolationPoint);
+    const actualIdx = violationIdx >= 0 ? violationIdx : steps.length - 1;
+    // Build expected behavior description
+    const expectedBehavior = buildExpectedBehavior(steps, violation);
+    // Build fix path
+    const fixPath = violation.fix
+        ? violation.fix.split(/[;,]\s*/).filter(Boolean)
+        : ["Add missing protocol safeguard call"];
+    // Estimate reading time: ~15 seconds per step (empirical)
+    const estimatedReadingTimeMinutes = Math.max(1, Math.ceil(steps.length * 0.25));
+    return {
+        violation: {
+            rule_id: violation.rule_id,
+            file: violation.file,
+            function: violation.function,
+            message: violation.message,
+        },
+        steps,
+        violationStepIndex: actualIdx,
+        expectedBehavior,
+        fixPath,
+        references,
+        estimatedReadingTimeMinutes,
+    };
+}
+// ── Full Trace (when we have state machine data) ──
+function buildFullTrace(steps, states, calls, violation) {
+    for (let i = 0; i < Math.min(calls.length, states.length); i++) {
+        const call = calls[i];
+        const currentState = i > 0 ? states[i - 1] : "INITIAL";
+        const actualNextState = i < states.length ? states[i] : "UNKNOWN";
+        // Determine expected state transition
+        const expected = inferExpectedState(currentState, call);
+        // Violation: expected transition exists but actual state doesn't match
+        // OR: call requires specific pre-state but we're not in it
+        const isViolation = expected !== null && expected !== actualNextState &&
+            actualNextState !== "UNKNOWN" && actualNextState !== expected;
+        const stepExplanation = isViolation
+            ? `函数 ${call} 在状态 ${currentState} 下被调用。` +
+                `预期协议状态应转为 ${expected}，但实际为 ${actualNextState}。` +
+                `这违反了 ${violation.rule_id}。${violation.evidence || violation.why || ""}`
+            : expected
+                ? `函数 ${call} 将协议状态从 ${currentState} 正常转移到 ${expected}。`
+                : `函数 ${call} 执行（无协议状态变更要求）。`;
+        steps.push({
+            step: i + 1,
+            label: inferStepLabel(call, currentState),
+            action: call,
+            preState: currentState,
+            expectedPostState: expected,
+            actualPostState: isViolation ? actualNextState : (expected || actualNextState),
+            isViolationPoint: isViolation,
+            ruleRef: violation.rule_id,
+            explanation: stepExplanation,
+        });
+    }
+}
+// ── Minimal Trace (reconstructed from violation fields) ──
+function buildMinimalTrace(steps, violation) {
+    // Parse the violation to reconstruct the reasoning chain
+    const funcName = violation.function || "unknown_function";
+    const fileName = violation.file || "unknown_file";
+    // Step 1: The triggering action
+    steps.push({
+        step: 1,
+        label: "违规触发点",
+        action: funcName,
+        preState: "EXPECTED_PROTOCOL_STATE",
+        expectedPostState: "SAFE_STATE",
+        actualPostState: "VIOLATION_STATE",
+        isViolationPoint: true,
+        ruleRef: violation.rule_id,
+        explanation: `在 ${fileName} 中，函数 ${funcName} 的执行触发了违规检测。${violation.evidence || ""}`,
+    });
+    // Step 2: Why it's a violation
+    steps.push({
+        step: 2,
+        label: "违规原因",
+        action: "protocol_check",
+        preState: "VIOLATION_STATE",
+        expectedPostState: null,
+        actualPostState: null,
+        isViolationPoint: false,
+        ruleRef: violation.rule_id,
+        explanation: violation.why || violation.message || "协议规则匹配发现违规。",
+    });
+    // Step 3: The fix
+    if (violation.fix) {
+        steps.push({
+            step: 3,
+            label: "修复路径",
+            action: violation.fix,
+            preState: "VIOLATION_STATE",
+            expectedPostState: "SAFE_STATE",
+            actualPostState: null,
+            isViolationPoint: false,
+            ruleRef: violation.rule_id,
+            explanation: `建议修复: ${violation.fix}`,
+        });
+    }
+}
+// ── State Inference Helpers ──
+/** Infer expected protocol state transition from function name + current state */
+function inferExpectedState(currentState, functionCall) {
+    const call = functionCall.toLowerCase();
+    // Authentication chain
+    if (currentState === "UNAUTHENTICATED") {
+        if (/login|authenticate|signin|verify_password/.test(call))
+            return "AUTHENTICATED";
+        if (/register|signup/.test(call))
+            return "USER_REGISTERED";
+    }
+    if (currentState === "AUTHENTICATED") {
+        if (/authorize|check_owner|check_permission/.test(call))
+            return "AUTHORIZED";
+        if (/logout|revoke/.test(call))
+            return "UNAUTHENTICATED";
+    }
+    if (currentState === "PASSWORD_RECEIVED" && /hash|crypt|bcrypt|argon/.test(call))
+        return "PASSWORD_HASHED";
+    if (currentState === "PASSWORD_HASHED" && /verify|compare/.test(call))
+        return "PASSWORD_VERIFIED";
+    if (currentState === "TOKEN_ISSUED" && /revoke|invalidate/.test(call))
+        return "UNAUTHENTICATED";
+    // TLS chain
+    if (currentState === "TLS_CONFIGURED") {
+        if (/listen|bind|accept|start_server|create_server/.test(call))
+            return "SERVER_STARTED";
+        if (/set_cipher|use_cert|load_cert/.test(call))
+            return "TLS_CONFIGURED"; // still configuring
+    }
+    // File upload chain
+    if (currentState === "AUTHENTICATED" && /receive_upload|handle_upload/.test(call))
+        return "FILE_RECEIVED";
+    if (currentState === "FILE_RECEIVED" && /validate_file|check_file|stat\b/.test(call))
+        return "FILE_VALIDATED";
+    if (currentState === "FILE_VALIDATED" && /store_file|save_file|write_file/.test(call))
+        return "FILE_STORED";
+    // Payment chain
+    if (currentState === "ORDER_CREATED" && /initiate_payment/.test(call))
+        return "PAYMENT_INITIATED";
+    if (currentState === "PAYMENT_INITIATED" && /receive_callback/.test(call))
+        return "PAYMENT_CALLBACK_RECEIVED";
+    if (currentState === "PAYMENT_CALLBACK_RECEIVED") {
+        if (/confirm/.test(call))
+            return "PAYMENT_CONFIRMED";
+        if (/fail/.test(call))
+            return "PAYMENT_FAILED";
+    }
+    // Generic patterns (fallback)
+    if (/init|create|new|start|setup|open/.test(call))
+        return "INITIALIZED";
+    if (/connect|handshake/.test(call))
+        return "CONNECTED";
+    if (/send|write|transfer|xfer/.test(call))
+        return "DATA_TRANSFERRED";
+    if (/close|free|cleanup|shutdown|destroy|done/.test(call))
+        return "CLOSED";
+    if (/validate|verify|check/.test(call))
+        return "VALIDATED";
+    return null;
+}
+/** Generate a human-readable label for a trace step */
+function inferStepLabel(functionCall, currentState) {
+    const call = functionCall.toLowerCase();
+    // Auth
+    if (/login|authenticate|signin|verify_password/.test(call))
+        return "用户认证";
+    if (/register|signup/.test(call))
+        return "用户注册";
+    if (/logout|revoke|invalidate/.test(call))
+        return "会话终止";
+    if (/authorize|check_owner|check_permission/.test(call))
+        return "权限检查";
+    if (/hash|crypt|bcrypt|argon/.test(call))
+        return "密码哈希";
+    if (/verify_hash|compare_password/.test(call))
+        return "密码验证";
+    // TLS
+    if (/load_tls|ssl_init|tls_setup|configure_ssl|configure_tls/.test(call))
+        return "TLS 配置";
+    if (/listen|bind|accept|start_server|create_server/.test(call))
+        return "服务器启动";
+    if (/set_cipher|use_cert|load_cert/.test(call))
+        return "证书配置";
+    // Network
+    if (/connect|handshake/.test(call))
+        return "协议握手";
+    if (/send|write|transfer|xfer/.test(call))
+        return "数据传输";
+    if (/close|free|cleanup|shutdown|destroy|done/.test(call))
+        return "连接关闭";
+    // File
+    if (/receive_upload|handle_upload/.test(call))
+        return "文件接收";
+    if (/validate_file|check_file/.test(call))
+        return "文件校验";
+    if (/store_file|save_file|write_file/.test(call))
+        return "文件存储";
+    // General
+    if (/init|create|new|start|setup|open/.test(call))
+        return "资源初始化";
+    if (/validate|verify|check/.test(call))
+        return "安全校验";
+    if (/encrypt|cipher/.test(call))
+        return "数据加密";
+    if (/decrypt/.test(call))
+        return "数据解密";
+    if (/hash/.test(call))
+        return "哈希计算";
+    return `状态转换: ${currentState}`;
+}
+/** Build a human-readable expected behavior description */
+function buildExpectedBehavior(steps, violation) {
+    const violStep = steps.find(s => s.isViolationPoint);
+    if (!violStep) {
+        return `应遵循协议规则 ${violation.rule_id}。修复建议: ${violation.fix || "添加缺失的协议安全调用"}`;
+    }
+    return `函数 ${violStep.action} 在状态 ${violStep.preState} 下被调用时，` +
+        `应首先确保协议状态转换到 ${violStep.expectedPostState || "安全状态"}，` +
+        `而非停留在 ${violStep.actualPostState || "违规状态"}。` +
+        `这违反了 ${violation.rule_id}。`;
+}
+// ── Serialization ──
+/**
+ * Render a ViolationTrace as a human-readable text block.
+ *
+ * Format:
+ *   代码第 X 行调用了 send()
+ *   → 此时 TLS 状态是 HANDSHAKE_INCOMPLETE
+ *   → 根据 RFC 8446 §4.2.2，此状态下不允许发送应用数据
+ *   → 违规
+ */
+function renderTraceAsText(trace) {
+    const lines = [];
+    lines.push(`═══════ 违规推理链 ═══════`);
+    lines.push(`文件: ${trace.violation.file}`);
+    lines.push(`函数: ${trace.violation.function}`);
+    lines.push(`规则: ${trace.violation.rule_id}`);
+    lines.push("");
+    for (const step of trace.steps) {
+        const marker = step.isViolationPoint ? "❌" : "  ";
+        lines.push(`${marker} [步骤 ${step.step}] ${step.label}`);
+        lines.push(`   操作: ${step.action}`);
+        lines.push(`   状态: ${step.preState}`);
+        if (step.expectedPostState) {
+            lines.push(`   预期: → ${step.expectedPostState}`);
+        }
+        if (step.actualPostState && step.isViolationPoint) {
+            lines.push(`   实际: → ${step.actualPostState}  ← 违规发生`);
+        }
+        if (step.ruleRef) {
+            lines.push(`   依据: ${step.ruleRef}`);
+        }
+        lines.push(`   说明: ${step.explanation}`);
+        lines.push("");
+    }
+    lines.push(`预期行为: ${trace.expectedBehavior}`);
+    lines.push(`修复路径: ${trace.fixPath.join(" → ")}`);
+    if (trace.references.length > 0) {
+        lines.push(`参考: ${trace.references.join(", ")}`);
+    }
+    lines.push("");
+    lines.push(`估算阅读时间: ~${trace.estimatedReadingTimeMinutes} 分钟`);
+    return lines.join("\n");
+}
+/**
+ * Render a ViolationTrace as a compact single-line summary.
+ */
+function renderTraceSummary(trace) {
+    const violStep = trace.steps[trace.violationStepIndex];
+    if (!violStep)
+        return trace.violation.message;
+    return `${violStep.action} 在 ${violStep.preState} 状态下违反 ${trace.violation.rule_id}` +
+        (trace.fixPath.length > 0 ? ` → 修复: ${trace.fixPath.join(" → ")}` : "");
+}
+// ── Batch Tracing ──
+/**
+ * Build traces for multiple violations.
+ */
+function buildViolationTraces(violations) {
+    return violations.map(v => buildViolationTrace(v));
+}