progmune-runtime 2.1.6 → 3.2.0

package/dist/knowledge-governance.test.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * P3.21-23: Knowledge Governance Tests
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const knowledge_governance_1 = require("./knowledge-governance");
+const GOV_DIR = path.resolve(__dirname, "..", "test-knowledge-gov");
+process.env.PROGMUNE_PROJECT_DIR = GOV_DIR;
+fs.mkdirSync(GOV_DIR, { recursive: true });
+fs.mkdirSync(path.join(GOV_DIR, ".progmune_corpus", "knowledge"), { recursive: true });
+function makeBaseRules() {
+    return new Map([
+        ["open_file", { pre_states: [], post_states: ["FILE_OPEN"] }],
+        ["write_file", { pre_states: ["FILE_OPEN"], post_states: ["FILE_DIRTY"] }],
+        ["close_file", { pre_states: ["FILE_OPEN", "FILE_DIRTY"], post_states: [], invalidate: ["FILE_OPEN", "FILE_DIRTY"] }],
+    ]);
+}
+(0, vitest_1.describe)("Inference Validator", () => {
+    (0, vitest_1.it)("classifies inferences as proposed/verified/rejected", () => {
+        const inferences = [
+            { from: "FILE_OPEN", to: "FILE_DIRTY", action: "open_file → flush_file", protocol: "FileProtocol", confidence: 1.0, evidenceCount: 1, examples: ["test"] },
+            { from: "FILE_OPEN", to: "FILE_DIRTY", action: "open_file → flush_file", protocol: "FileProtocol", confidence: 1.0, evidenceCount: 3, examples: ["a", "b", "c"] },
+        ];
+        const validated = (0, knowledge_governance_1.validateInferences)(inferences, 5); // 5 trajectory support
+        // First: only 1 benchmark → proposed
+        (0, vitest_1.expect)(validated[0].validation.status).toBe("proposed");
+        (0, vitest_1.expect)(validated[0].validation.benchmarkSupport).toBe(1);
+        (0, vitest_1.expect)(validated[0].validation.trajectorySupport).toBe(5);
+        // Second: 3 benchmarks + 5 trajectories → verified
+        (0, vitest_1.expect)(validated[1].validation.status).toBe("verified");
+    });
+});
+(0, vitest_1.describe)("Knowledge Patch Store", () => {
+    (0, vitest_1.it)("proposes, approves, rejects, and rolls back patches", () => {
+        const store = new knowledge_governance_1.KnowledgePatchStore(path.join(GOV_DIR, ".progmune_corpus", "knowledge", `test-${Date.now()}.json`));
+        const inference = {
+            from: "FILE_OPEN", to: "FILE_DIRTY", action: "open_file → flush_file",
+            protocol: "FileProtocol", confidence: 1.0, evidenceCount: 3, examples: ["a", "b", "c"],
+            validation: { benchmarkSupport: 3, trajectorySupport: 5, contradictionCount: 0, status: "verified" },
+        };
+        // Propose
+        const patch = store.propose(inference);
+        (0, vitest_1.expect)(patch.status).toBe("proposed");
+        (0, vitest_1.expect)(patch.id).toMatch(/^KP-/);
+        (0, vitest_1.expect)(store.proposed.length).toBe(1);
+        // Approve
+        const ok = store.approve(patch.id, { top1Before: 0.5, top1After: 0.55, top3Before: 0.7, top3After: 0.75 });
+        (0, vitest_1.expect)(ok).toBe(true);
+        (0, vitest_1.expect)(store.approved.length).toBe(1);
+        (0, vitest_1.expect)(store.approved[0].approvalMetrics?.top1After).toBe(0.55);
+        // Rollback
+        const rb = store.rollback(patch.id);
+        (0, vitest_1.expect)(rb).toBe(true);
+        (0, vitest_1.expect)(store.approved.length).toBe(0);
+        // Reject a new one
+        const p2 = store.propose(inference);
+        store.reject(p2.id);
+        (0, vitest_1.expect)(store.all.filter(p => p.status === "rejected").length).toBe(1);
+    });
+    (0, vitest_1.it)("builds augmented rules from approved patches", () => {
+        const store = new knowledge_governance_1.KnowledgePatchStore(path.join(GOV_DIR, ".progmune_corpus", "knowledge", `aug-${Date.now()}.json`));
+        const inference = {
+            from: "FILE_OPEN", to: "FILE_DIRTY", action: "open_file → flush_file",
+            protocol: "FileProtocol", confidence: 1.0, evidenceCount: 3, examples: ["a"],
+            validation: { benchmarkSupport: 3, trajectorySupport: 5, contradictionCount: 0, status: "verified" },
+        };
+        const patch = store.propose(inference);
+        store.approve(patch.id, { top1Before: 0.5, top1After: 0.6, top3Before: 0.7, top3After: 0.8 });
+        const baseRules = makeBaseRules();
+        const augmented = store.buildAugmentedRules(baseRules);
+        // Should have base rules + 1 patch bridge
+        (0, vitest_1.expect)(augmented.size).toBe(baseRules.size + 1);
+        const hasBridge = [...augmented.keys()].some(k => k.startsWith("_patch_"));
+        (0, vitest_1.expect)(hasBridge).toBe(true);
+    });
+});
+(0, vitest_1.describe)("Regression Test", () => {
+    (0, vitest_1.it)("auto-approves if Top-1/Top-3 improves", () => {
+        const store = new knowledge_governance_1.KnowledgePatchStore(path.join(GOV_DIR, ".progmune_corpus", "knowledge", `reg-${Date.now()}.json`));
+        const patch = store.propose({
+            from: "FILE_OPEN", to: "FILE_DIRTY", action: "open_file → flush_file",
+            protocol: "FileProtocol", confidence: 1.0, evidenceCount: 3, examples: ["a", "b", "c"],
+            validation: { benchmarkSupport: 3, trajectorySupport: 5, contradictionCount: 0, status: "verified" },
+        });
+        const baseRules = makeBaseRules();
+        // Test case: from FILE_OPEN to FILE_DIRTY — this path doesn't exist in base rules (open→write exists, but open→flush is missing)
+        const testCases = [
+            { currentState: ["FILE_OPEN"], targetState: ["FILE_DIRTY"] },
+        ];
+        const result = (0, knowledge_governance_1.autoApprovePatch)(patch, baseRules, testCases, store);
+        // With augmented rules, the patch adds open_file→flush_file bridge
+        // This should improve Top-1 (found paths increase)
+        (0, vitest_1.expect)(result.passed).toBe(true);
+        (0, vitest_1.expect)(result.top1After).toBeGreaterThanOrEqual(result.top1Before);
+    });
+});
+(0, vitest_1.describe)("Full Governance Pipeline", () => {
+    (0, vitest_1.it)("runs synthesize → validate → propose → regression → approve", () => {
+        // revoke_token produces UNAUTHENTICATED, create_session needs TOKEN_ISSUED
+        // These are NOT connected (UNAUTHENTICATED ≠ TOKEN_ISSUED) → genuine gap
+        // Both functions exist in AuthProtocol (protocols.json)
+        const failures = [
+            { goal: "revoke then create session", protocol: "AuthProtocol", expectedRepair: ["revoke_token", "create_session"] },
+            { goal: "revoke then create session v2", protocol: "AuthProtocol", expectedRepair: ["revoke_token", "create_session"] },
+        ];
+        const testCases = [
+            { currentState: ["FILE_OPEN"], targetState: ["FILE_DIRTY"] },
+        ];
+        const store = new knowledge_governance_1.KnowledgePatchStore(path.join(GOV_DIR, ".progmune_corpus", "knowledge", `full-${Date.now()}.json`));
+        const report = (0, knowledge_governance_1.runKnowledgeGovernance)(failures, testCases, store);
+        (0, vitest_1.expect)(report.proposed).toBeGreaterThanOrEqual(1);
+        (0, knowledge_governance_1.printGovernanceReport)(report);
+    });
+});

package/dist/knowledge-graph.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Knowledge Network — Cross-protocol reference graph
+ *
+ * Transforms flat Knowledge Units into an interconnected graph.
+ * Protocols reference each other: TLS depends_on TCP, HTTP/2 extends HTTP, etc.
+ *
+ * Usage:
+ *   npx ts-node src/knowledge-graph.ts
+ *   npx ts-node src/knowledge-graph.ts --tree
+ *   npx ts-node src/knowledge-graph.ts --dependents TLS
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildKnowledgeGraph = buildKnowledgeGraph;
+exports.getDependents = getDependents;
+exports.getDependencies = getDependencies;
+const protocol_knowledge_1 = require("./protocol-knowledge");
+// Cross-protocol relations that go beyond existing unit.relations
+const CROSS_PROTOCOL_EDGES = [
+    // Transport layer
+    { from: "PROTO-TLS", to: "PROTO-CONN", type: "depends_on", description: "TLS handshake runs over a TCP connection" },
+    { from: "PROTO-QUIC", to: "PROTO-CONN", type: "depends_on", description: "QUIC runs over UDP connection" },
+    // HTTP stack
+    { from: "PROTO-H2", to: "PROTO-HTTP", type: "extends", description: "HTTP/2 extends HTTP/1.1 request semantics" },
+    { from: "PROTO-TLS-ALPN", to: "PROTO-TLS", type: "extends", description: "ALPN negotiation extends TLS handshake" },
+    { from: "PROTO-TLS-CERT", to: "PROTO-TLS", type: "extends", description: "Certificate validation extends TLS handshake" },
+    { from: "PROTO-TLS-SESS", to: "PROTO-TLS", type: "depends_on", description: "Session resumption requires completed handshake" },
+    // Auth
+    { from: "PROTO-SSH", to: "PROTO-AUTH", type: "depends_on", description: "SSH requires authentication" },
+    { from: "PROTO-HTTP", to: "PROTO-AUTH", type: "compatible_with", description: "HTTP can use authentication headers" },
+    // Cross-domain
+    { from: "PROTO-TLS", to: "PROTO-AUTH", type: "compatible_with", description: "TLS can carry client certificates for authentication" },
+    { from: "PROTO-SSH", to: "PROTO-CONN", type: "depends_on", description: "SSH runs over TCP connection" },
+];
+function buildKnowledgeGraph() {
+    const kb = (0, protocol_knowledge_1.buildKnowledgeBase)();
+    const nodes = kb.units.map(u => ({
+        id: u.id, name: u.name, domain: u.domain, maturity: u.maturity, confidence: u.confidence,
+    }));
+    // Collect all edges: both intra-unit relations and cross-protocol relations
+    const edges = [...CROSS_PROTOCOL_EDGES];
+    // Add intra-unit relations
+    for (const u of kb.units) {
+        for (const r of u.relations || []) {
+            edges.push({ from: u.id, to: r.targetId, type: r.type, description: r.description });
+        }
+    }
+    // Build adjacency
+    const adj = {};
+    const inDeg = {};
+    const outDeg = {};
+    for (const n of nodes) {
+        adj[n.id] = [];
+        inDeg[n.id] = 0;
+        outDeg[n.id] = 0;
+    }
+    for (const e of edges) {
+        if (!adj[e.from])
+            adj[e.from] = [];
+        if (!adj[e.to])
+            adj[e.to] = [];
+        adj[e.from].push(e.to);
+        outDeg[e.from] = (outDeg[e.from] || 0) + 1;
+        inDeg[e.to] = (inDeg[e.to] || 0) + 1;
+    }
+    return { nodes, edges, adjacency: adj, inDegree: inDeg, outDegree: outDeg };
+}
+// ═══════════════════════════════════════════════════════════════
+// Queries
+// ═══════════════════════════════════════════════════════════════
+function getDependents(graph, nodeId) {
+    const ids = graph.edges.filter(e => e.to === nodeId).map(e => e.from);
+    return graph.nodes.filter(n => ids.includes(n.id));
+}
+function getDependencies(graph, nodeId) {
+    const ids = graph.edges.filter(e => e.from === nodeId).map(e => e.to);
+    return graph.nodes.filter(n => ids.includes(n.id));
+}
+// ═══════════════════════════════════════════════════════════════
+// Formatters
+// ═══════════════════════════════════════════════════════════════
+function formatTree(graph) {
+    const C = { r: "\x1b[0m", b: "\x1b[1m", d: "\x1b[2m", g: "\x1b[32m", y: "\x1b[33m", r2: "\x1b[31m", c: "\x1b[36m", m: "\x1b[35m" };
+    const l = [];
+    l.push(`\n${C.b}${C.c}Protocol Knowledge Graph${C.r}\n`);
+    // Find root nodes (no incoming edges from other protocols)
+    const roots = graph.nodes.filter(n => graph.inDegree[n.id] === 0 || (graph.inDegree[n.id] <= 1 && graph.outDegree[n.id] >= 2));
+    const visited = new Set();
+    function renderNode(id, prefix, isLast) {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        const n = graph.nodes.find(x => x.id === id);
+        if (!n)
+            return;
+        const connector = isLast ? "└── " : "├── ";
+        const matIcon = n.maturity === "stable" ? C.g + "★" + C.r : n.maturity === "validated" ? C.y + "◉" + C.r : C.r2 + "●" + C.r;
+        l.push(`${prefix}${connector}${matIcon} ${C.b}${n.name}${C.r} ${C.d}(${n.domain}, ${n.confidence}%)${C.r}`);
+        const children = graph.edges.filter(e => e.from === id);
+        const childPrefix = prefix + (isLast ? "    " : "│   ");
+        children.forEach((e, i) => {
+            l.push(`${childPrefix}${i === children.length - 1 ? "└── " : "├── "}${C.d}${e.type}${C.r} → ${e.description.slice(0, 50)}`);
+        });
+        // Don't recurse into children to avoid cycles — just show direct edges
+    }
+    // Render starting from connection/transport layer (roots)
+    const transportRoots = graph.nodes.filter(n => n.domain === "Connection" || n.domain === "QUIC");
+    for (const r of transportRoots) {
+        renderNode(r.id, "", true);
+    }
+    // Then TLS, SSH, HTTP
+    const appRoots = graph.nodes.filter(n => ["TLS", "SSH", "HTTP"].includes(n.domain) && !transportRoots.includes(n));
+    for (const r of appRoots) {
+        if (!visited.has(r.id))
+            renderNode(r.id, "", true);
+    }
+    return l.join("\n") + "\n";
+}
+function formatMatrix(graph) {
+    const C = { r: "\x1b[0m", b: "\x1b[1m", d: "\x1b[2m", g: "\x1b[32m" };
+    const l = [];
+    l.push(`\n${C.b}Cross-Reference Matrix${C.r}\n`);
+    l.push(`${C.d}Rows point TO columns (row depends_on / extends column)${C.r}\n`);
+    const ids = graph.nodes.map(n => n.id);
+    const names = graph.nodes.map(n => n.name.slice(0, 8));
+    l.push(`         ${names.join("  ")}`);
+    l.push(`         ${names.map(() => "──").join("  ")}`);
+    for (const n of graph.nodes) {
+        const row = ids.map(targetId => {
+            const edge = graph.edges.find(e => e.from === n.id && e.to === targetId);
+            return edge ? (edge.type === "depends_on" ? "↓ " : edge.type === "extends" ? "↗ " : "· ") : "  ";
+        }).join("  ");
+        l.push(`${n.name.slice(0, 8).padEnd(8)} ${row}`);
+    }
+    return l.join("\n") + "\n";
+}
+// ═══════════════════════════════════════════════════════════════
+// CLI
+// ═══════════════════════════════════════════════════════════════
+if (require.main === module) {
+    const g = buildKnowledgeGraph();
+    const args = process.argv.slice(2);
+    const C = { r: "\x1b[0m", b: "\x1b[1m", d: "\x1b[2m", g: "\x1b[32m", c: "\x1b[36m" };
+    if (args.includes("--tree")) {
+        console.log(formatTree(g));
+    }
+    else if (args.includes("--matrix")) {
+        console.log(formatMatrix(g));
+    }
+    else if (args.includes("--dependents") && args[1]) {
+        const deps = getDependents(g, args[1]);
+        console.log(`\nNodes that depend on ${args[1]}:`);
+        deps.forEach(d => console.log(`  ${d.name} (${d.domain}, ${d.maturity})`));
+    }
+    else if (args.includes("--dependencies") && args[1]) {
+        const deps = getDependencies(g, args[1]);
+        console.log(`\nNodes that ${args[1]} depends on:`);
+        deps.forEach(d => console.log(`  ${d.name} (${d.domain}, ${d.maturity})`));
+    }
+    else {
+        // Default: summary
+        console.log(`\n${C.b}${C.c}Knowledge Network${C.r}`);
+        console.log(`${C.d}${g.nodes.length} nodes, ${g.edges.length} edges${C.r}`);
+        // Top nodes by connections
+        const ranked = g.nodes.map(n => ({
+            name: n.name, domain: n.domain, maturity: n.maturity,
+            total: (g.inDegree[n.id] || 0) + (g.outDegree[n.id] || 0),
+            in: g.inDegree[n.id] || 0, out: g.outDegree[n.id] || 0,
+        })).sort((a, b) => b.total - a.total);
+        console.log(`\n  Node                 Domain      In   Out  Total`);
+        for (const r of ranked.slice(0, 8)) {
+            console.log(`  ${r.name.padEnd(20)} ${r.domain.padEnd(10)} ${String(r.in).padStart(2)}  ${String(r.out).padStart(2)}  ${r.total}`);
+        }
+        // Cross-references
+        console.log(`\n  Cross-protocol edges:`);
+        for (const e of g.edges) {
+            console.log(`  ${e.from.padEnd(14)} ${e.type.padEnd(14)} → ${e.to.padEnd(14)} ${C.d}${e.description.slice(0, 50)}${C.r}`);
+        }
+        console.log("");
+    }
+}

package/dist/knowledge-guided-synth.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * P6: Knowledge-Guided Rule Synthesis
+ *
+ * The existing synthesizer generates too many rules (452 from 61 sequences)
+ * because it blindly clusters ALL observed patterns. This module adds
+ * knowledge-based filtering to produce fewer, higher-quality rules.
+ *
+ * Three filters:
+ *   1. DOMAIN_FILTER    — Only generate rules for protocol-relevant functions
+ *   2. SPECIFICITY_FILTER — Require minimum pre/post state specificity
+ *   3. FREQUENCY_FILTER — Require pattern observed in ≥N sequences
+ *
+ * Target: 452 rules → ~50 high-quality rules (89% reduction)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeWithKnowledge = synthesizeWithKnowledge;
+exports.formatKGSynthesisStats = formatKGSynthesisStats;
+const auto_protocol_synthesizer_1 = require("./auto-protocol-synthesizer");
+// ═══════════════════════════════════════════════════════════════
+// Knowledge Base — Protocol-Relevant Function Patterns
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Protocol domain patterns — functions matching these patterns
+ * are likely to be part of real protocols (TLS, SSH, HTTP, File, Auth).
+ *
+ * Functions NOT matching any pattern are likely utilities, helpers,
+ * or internal functions that should be excluded from rule generation.
+ */
+const PROTOCOL_DOMAINS = [
+    {
+        domain: "TLS/SSL",
+        patterns: [
+            /ssl/i, /tls/i, /handshake/i, /cipher/i, /cert/i, /verify/i,
+            /encrypt/i, /decrypt/i, /key/i, /x509/i, /pki/i,
+            /SSL_/i, /TLS_/i, /ossl_/i,
+        ],
+    },
+    {
+        domain: "SSH",
+        patterns: [
+            /ssh_/i, /sftp/i, /scp/i, /auth_/i, /kex/i, /hostkey/i,
+            /SSH_/i, /ssh_/i,
+        ],
+    },
+    {
+        domain: "HTTP",
+        patterns: [
+            /http/i, /request/i, /response/i, /header/i, /cookie/i,
+            /session/i, /url/i, /uri/i, /CURL/i, /curl_/i, /ngx_http/i,
+        ],
+    },
+    {
+        domain: "File I/O",
+        patterns: [
+            /open_/i, /close_/i, /read_/i, /write_/i, /file_/i,
+            /fopen/i, /fclose/i, /fread/i, /fwrite/i, /fd_/i,
+        ],
+    },
+    {
+        domain: "Auth",
+        patterns: [
+            /auth/i, /login/i, /logout/i, /password/i, /token/i,
+            /verify_/i, /credential/i, /oauth/i, /jwt/i,
+        ],
+    },
+    {
+        domain: "Connection",
+        patterns: [
+            /connect/i, /disconnect/i, /bind/i, /listen/i, /accept/i,
+            /socket/i, /resolve/i, /dns/i,
+        ],
+    },
+    {
+        domain: "Memory/Resource",
+        patterns: [
+            /alloc/i, /free/i, /init/i, /cleanup/i, /destroy/i,
+            /create_/i, /delete_/i, /new_/i, /release/i, /acquire/i,
+        ],
+    },
+];
+/**
+ * Generic utility functions that are NOT protocol-relevant.
+ * Rules generated from these functions are almost always false positives.
+ */
+const GENERIC_FUNCTIONS = new Set([
+    // Standard library
+    "memset", "memcpy", "memmove", "memcmp", "strlen", "strcmp", "strcasecmp",
+    "strdup", "strcpy", "strncpy", "strcat", "sprintf", "snprintf",
+    "malloc", "calloc", "realloc", "free",
+    "printf", "fprintf", "assert", "abort", "exit",
+    // Preprocessor / compiler
+    "defined", "UNUSED", "FALLTHROUGH", "GOOD_MULTI_HANDLE",
+    // Data structures
+    "STACK_OF", "ERR_clear_error", "curlx_dyn_init",
+    // Generic utility
+    "time", "delay", "sleep", "usleep",
+    "buffer", "files", "multi_now", "scheme",
+    "curl_socket", "curl_dynhds_init", "curl_global_trace",
+    "is_pkcs11_uri", "ossl_do_file_type",
+    // One-off internal helpers
+    "init_telnet", "rfc2228", "myssh_to_error",
+    "libssh2_sftp_stat_ex",
+]);
+const DEFAULT_KG_OPTIONS = {
+    minFrequency: 3, // Cluster must have ≥3 sequences
+    minSpecificity: 1,
+    filterGenerics: true,
+    requireDomain: false,
+};
+/**
+ * Check if a function name matches any known protocol domain.
+ */
+function matchesDomain(fnName) {
+    for (const domain of PROTOCOL_DOMAINS) {
+        if (domain.patterns.some(p => p.test(fnName))) {
+            return domain.domain;
+        }
+    }
+    return null;
+}
+function classifySemanticRole(fnName, preStates, postStates, invalidate) {
+    const fn = fnName.toLowerCase();
+    // Init: creates/acquires resources — empty pre_states, produces post_states
+    if (preStates.length === 0 && postStates.length > 0)
+        return "init";
+    // Cleanup: releases/invalidates resources
+    if (invalidate && invalidate.length > 0)
+        return "cleanup";
+    // Use: requires pre_states, may produce post_states, no invalidation
+    if (preStates.length > 0)
+        return "use";
+    return "unknown";
+}
+function synthesizeWithKnowledge(sequences, options = {}) {
+    const opts = { ...DEFAULT_KG_OPTIONS, ...options };
+    const stats = {
+        inputSequences: sequences.length,
+        filteredSequences: sequences.length, // Don't filter sequences — filter rules instead
+        rawProtocols: 0,
+        rawRules: 0,
+        filteredProtocols: 0,
+        filteredRules: 0,
+        byFilter: { domain: 0, generic: 0, frequency: 0, specificity: 0 },
+        domainBreakdown: {},
+    };
+    // Step 1: Run the existing synthesizer on ALL sequences (don't pre-filter)
+    const rawProtocols = (0, auto_protocol_synthesizer_1.synthesizeProtocols)(sequences);
+    stats.rawProtocols = rawProtocols.length;
+    let totalRawRules = 0;
+    for (const p of rawProtocols)
+        totalRawRules += p.rules.length;
+    stats.rawRules = totalRawRules;
+    // Step 2: Filter synthesized rules by quality
+    const rules = new Map();
+    const namespaces = new Set();
+    // Count function frequency across ALL sequences
+    const fnFrequency = new Map();
+    for (const seq of sequences) {
+        const seen = new Set();
+        for (const fn of seq) {
+            if (!seen.has(fn)) {
+                fnFrequency.set(fn, (fnFrequency.get(fn) || 0) + 1);
+                seen.add(fn);
+            }
+        }
+    }
+    for (const proto of rawProtocols) {
+        // Frequency/confidence filter: cluster must have sufficient confidence
+        // (closedLoopRate from clustering — higher = stronger pattern)
+        if (proto.confidence < 0.3 && proto.prototype.length < 5) {
+            stats.byFilter.frequency++;
+            continue;
+        }
+        let keptRules = 0;
+        for (const r of proto.rules) {
+            // Filter 1: Generic/utility functions — these match everywhere, always FP
+            if (opts.filterGenerics && GENERIC_FUNCTIONS.has(r.function)) {
+                stats.byFilter.generic++;
+                continue;
+            }
+            // Filter 2: Frequency — function must appear in ≥minFrequency sequences
+            const freq = fnFrequency.get(r.function) || 0;
+            if (freq < opts.minFrequency) {
+                stats.byFilter.frequency++;
+                continue;
+            }
+            // Filter 3: Semantic role
+            const role = classifySemanticRole(r.function, r.pre_states, r.post_states, r.invalidate);
+            if (role === "unknown") {
+                stats.byFilter.specificity++;
+                continue;
+            }
+            // Filter 4: Domain annotation
+            const domain = matchesDomain(r.function);
+            const ns = domain || proto.inferredPattern || "discovered";
+            namespaces.add(ns);
+            stats.domainBreakdown[domain || "unknown"] =
+                (stats.domainBreakdown[domain || "unknown"] || 0) + 1;
+            rules.set(r.function, {
+                pre_states: r.pre_states,
+                post_states: r.post_states,
+                invalidate: r.invalidate,
+                namespace: ns,
+            });
+            keptRules++;
+        }
+        if (keptRules > 0) {
+            stats.filteredProtocols++;
+        }
+    }
+    stats.filteredRules = rules.size;
+    // Build namespace initial states
+    const nsInit = new Map();
+    nsInit.set("_global", "INIT");
+    for (const ns of namespaces) {
+        nsInit.set(ns, "INIT");
+    }
+    return { rules, nsInit, stats };
+}
+function formatKGSynthesisStats(stats) {
+    const lines = [];
+    const reduction = stats.rawRules > 0
+        ? ((1 - stats.filteredRules / stats.rawRules) * 100).toFixed(0)
+        : "0";
+    lines.push("");
+    lines.push("── Knowledge-Guided Synthesis ──");
+    lines.push(`  Input sequences:   ${stats.inputSequences}`);
+    lines.push(`  After domain filter: ${stats.filteredSequences} (${stats.byFilter.domain} removed by domain, ${stats.byFilter.generic} generics)`);
+    lines.push(`  Raw protocols:     ${stats.rawProtocols}`);
+    lines.push(`  Raw rules:         ${stats.rawRules}`);
+    lines.push(`  Filtered rules:    ${stats.filteredRules} (${reduction}% reduction)`);
+    lines.push("");
+    lines.push("  ── Filter breakdown ──");
+    lines.push(`  Domain mismatch:   ${stats.byFilter.domain}`);
+    lines.push(`  Generic function:  ${stats.byFilter.generic}`);
+    lines.push(`  Low frequency:     ${stats.byFilter.frequency}`);
+    lines.push(`  Low specificity:   ${stats.byFilter.specificity}`);
+    lines.push("");
+    lines.push("  ── Domain distribution ──");
+    for (const [domain, count] of Object.entries(stats.domainBreakdown).sort((a, b) => b[1] - a[1])) {
+        lines.push(`  ${domain.padEnd(20)} ${count} rules`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/knowledge-loop.test.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Knowledge loop integration test.
+ *
+ * Verifies the full feedback loop end-to-end:
+ *   Failure → Record → Aggregate → Antibody → L1 Hint / L2 Fast Path / L3 Credit
+ *
+ * Tests run against real feedback.json and .progmune_corpus data on disk.
+ */
+const vitest_1 = require("vitest");
+const failure_corpus_1 = require("./failure-corpus");
+const feedback_1 = require("./feedback");
+const logger_1 = require("./logger");
+// ── L3: Credit scoring works with real data ──
+(0, vitest_1.describe)("L3: Credit scoring", () => {
+    (0, vitest_1.it)("getFailureAdjustedCredit returns Laplace-smoothed value for unknown function", () => {
+        const credit = (0, feedback_1.getFailureAdjustedCredit)("__nonexistent_xyz__");
+        (0, vitest_1.expect)(credit).toBe(0.5);
+    });
+    (0, vitest_1.it)("getFailureAdjustedCredit for known functions is between 0.3 and 1.0", () => {
+        // Test a few functions that may or may not have history
+        for (const fn of ["generateJWT", "validatePassword", "loadIR", "plan"]) {
+            const credit = (0, feedback_1.getFailureAdjustedCredit)(fn);
+            (0, vitest_1.expect)(credit).toBeGreaterThanOrEqual(0.3);
+            (0, vitest_1.expect)(credit).toBeLessThanOrEqual(1.0);
+        }
+    });
+    (0, vitest_1.it)("getFunctionSuccessRate returns 0.5 for cold start", () => {
+        (0, vitest_1.expect)((0, feedback_1.getFunctionSuccessRate)("__never_called__")).toBe(0.5);
+    });
+});
+// ── L1/L2: Antibody generation ──
+(0, vitest_1.describe)("L1/L2: Antibody pipeline", () => {
+    (0, vitest_1.it)("getLearnedPatterns returns a valid structure", () => {
+        const result = (0, failure_corpus_1.getLearnedPatterns)();
+        (0, vitest_1.expect)(result).toHaveProperty("failureToFix");
+        (0, vitest_1.expect)(Array.isArray(result.failureToFix)).toBe(true);
+    });
+    (0, vitest_1.it)("getFailureGenome returns summary statistics", () => {
+        const genome = (0, failure_corpus_1.getFailureGenome)();
+        (0, vitest_1.expect)(genome).toHaveProperty("totalFailures");
+        (0, vitest_1.expect)(genome).toHaveProperty("bySVL");
+        (0, vitest_1.expect)(genome).toHaveProperty("averageRetriesToSuccess");
+        (0, vitest_1.expect)(typeof genome.totalFailures).toBe("number");
+    });
+    (0, vitest_1.it)("getTopFailurePatterns returns sorted patterns", () => {
+        const patterns = (0, failure_corpus_1.getTopFailurePatterns)(5);
+        (0, vitest_1.expect)(Array.isArray(patterns)).toBe(true);
+        // Verify sorted by count descending
+        for (let i = 1; i < patterns.length; i++) {
+            (0, vitest_1.expect)(patterns[i].count).toBeLessThanOrEqual(patterns[i - 1].count);
+        }
+    });
+    (0, vitest_1.it)("queryAntibodies returns ACL-3+ matches", () => {
+        const antibodies = (0, failure_corpus_1.queryAntibodies)("test intent", "ACL-3");
+        (0, vitest_1.expect)(Array.isArray(antibodies)).toBe(true);
+        // All returned antibodies should be ACL-3 or ACL-4
+        for (const ab of antibodies) {
+            (0, vitest_1.expect)(["ACL-3", "ACL-4"]).toContain(ab.antibodyLevel);
+        }
+    });
+    (0, vitest_1.it)("queryAntibodies returns results sorted by relevance", () => {
+        const antibodies = (0, failure_corpus_1.queryAntibodies)("authenticate user password", "ACL-3");
+        for (let i = 1; i < antibodies.length; i++) {
+            (0, vitest_1.expect)(antibodies[i]._score).toBeLessThanOrEqual(antibodies[i - 1]._score);
+        }
+    });
+});
+// ── Logger integration ──
+(0, vitest_1.describe)("Structured logger", () => {
+    (0, vitest_1.it)("createLogger produces distinguishable module names", () => {
+        const plan = (0, logger_1.createLogger)("planner");
+        const val = (0, logger_1.createLogger)("validator");
+        (0, vitest_1.expect)(plan).not.toBe(val);
+    });
+});