progmune-runtime 2.1.0 → 2.1.2

package/dist/repair-proposal.js

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

package/dist/runtime-invariants.js

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

package/dist/runtime.js

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

package/dist/search-planner.js

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

package/dist/semantic-snapshot.js

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

package/dist/session-utils.js

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

package/dist/ssg-validator.js

@@ -98,6 +98,7 @@ function deepEqualSnapshots(a, b) {
     return true;
 }
 // ── rebuildState: pure fold over ledger → per-namespace state snapshot ──
+/** @requires LEDGER_DATA @produces STATE_SNAPSHOT */
 function rebuildState(ledger, namespaceInitialStates = new Map([["_global", "INIT"]])) {
     const stateMap = fromSnapshot({});
     for (const [ns, initState] of namespaceInitialStates) {
@@ -131,6 +132,7 @@ function computeDelta(beforeSnap, afterSnap, namespace) {
     return { acquired, invalidated };
 }
 // ── findFixPathStatic: BFS state graph search (extracted from class) ──
+/** @requires CURRENT_STATES @produces FIX_PATH */
 function findFixPathStatic(rules, namespace, current, targetPreStates) {
     const nsFuncs = [];
     for (const [fn, rule] of rules) {
@@ -184,6 +186,7 @@ function findFixPathStatic(rules, namespace, current, targetPreStates) {
     return path;
 }
 // ── validateTransition: pure function, stateless ──
+/** @requires TRANSITION_CONTEXT @produces VALIDATION_RESULT */
 function validateTransition(ctx, candidateFunctionName, actionIndex, rules, namespaceInitialStates, ruleHash) {
     const currentState = ctx.currentState;
     const rule = rules.get(candidateFunctionName);
@@ -281,6 +284,7 @@ function validateTransition(ctx, candidateFunctionName, actionIndex, rules, name
     return { valid: true, transition };
 }
 // ── checkLedgerConsistency: Invariant-0 + Invariant-1 over full ledger ──
+/** @requires LEDGER_DATA @produces CONSISTENCY_RESULT */
 function checkLedgerConsistency(ledger, namespaceInitialStates = new Map([["_global", "INIT"]])) {
     const violations = [];
     const running = fromSnapshot({});
@@ -348,6 +352,7 @@ function checkLedgerConsistency(ledger, namespaceInitialStates = new Map([["_glo
     return { consistent: violations.length === 0, violations };
 }
 // ── hashRules: stable hash of rule set for constraint snapshot (P1) ──
+/** @requires RULES @produces RULE_HASH */
 function hashRules(rules) {
     const sorted = [...rules.entries()]
         .sort(([a], [b]) => a.localeCompare(b))
@@ -361,6 +366,7 @@ function hashRules(rules) {
     return crypto.createHash("sha256").update(JSON.stringify(sorted)).digest("hex").slice(0, 16);
 }
 /** Compute a deterministic SHA256 hash of an entire ledger (P1: Tamper-evident integrity). */
+/** @requires LEDGER_DATA @produces LEDGER_HASH */
 function hashLedger(ledger) {
     const canonical = ledger.map(t => ({
         actionIndex: t.actionIndex,
@@ -376,6 +382,7 @@ function hashLedger(ledger) {
     return crypto.createHash("sha256").update(JSON.stringify(canonical)).digest("hex").slice(0, 16);
 }
 /** Compare two ledgers and identify structural differences. */
+/** @requires TWO_LEDGERS @produces LEDGER_DIFF */
 function diffLedgers(ledgerA, ledgerB) {
     const hash = (t) => crypto.createHash("sha256").update(JSON.stringify({
         i: t.actionIndex, f: t.function, n: t.namespace,
@@ -617,6 +624,7 @@ exports.StateMachineValidator = StateMachineValidator;
 // Standalone presentation utilities (formerly static methods)
 // ═══════════════════════════════════════════════════════════════
 /** Format an SSG rejection as a human-readable multi-line string. */
+/** @requires SSG_REJECTION @produces EXPLANATION */
 function explainRejection(rejection) {
     const nsLabel = rejection.namespace && rejection.namespace !== DEFAULT_NAMESPACE
         ? ` [namespace: ${rejection.namespace}]` : '';

package/dist/stdlib.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Progmune Standard Library — general-purpose utilities for external tasks.
+ * Each function has @requires/@produces for Capability Graph integration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidEmail = isValidEmail;
+exports.truncate = truncate;
+exports.camelToSnake = camelToSnake;
+exports.capitalizeWords = capitalizeWords;
+exports.countSubstring = countSubstring;
+exports.removeWhitespace = removeWhitespace;
+exports.mostFrequent = mostFrequent;
+exports.unique = unique;
+exports.chunk = chunk;
+exports.arrayDiff = arrayDiff;
+exports.average = average;
+exports.median = median;
+exports.roundTo = roundTo;
+exports.isPrime = isPrime;
+exports.randomInt = randomInt;
+exports.deepClone = deepClone;
+exports.pick = pick;
+exports.deepMerge = deepMerge;
+exports.hasRequiredFields = hasRequiredFields;
+exports.isPlainObject = isPlainObject;
+exports.parseSemver = parseSemver;
+exports.formatDuration = formatDuration;
+exports.formatFileSize = formatFileSize;
+exports.toQueryString = toQueryString;
+exports.retry = retry;
+exports.debounce = debounce;
+// ── String ──
+/** @requires STRING @produces VALIDATION_RESULT @tags string, email, validation */
+function isValidEmail(str) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(str);
+}
+/** @requires STRING @produces TRUNCATED_STRING @tags string, format */
+function truncate(str, maxLen, ellipsis = "...") {
+    return str.length <= maxLen ? str : str.slice(0, maxLen - ellipsis.length) + ellipsis;
+}
+/** @requires STRING @produces FORMATTED_STRING @tags string, case, format */
+function camelToSnake(str) {
+    return str.replace(/[A-Z]/g, (c) => "_" + c.toLowerCase());
+}
+/** @requires STRING @produces FORMATTED_STRING @tags string, case, format */
+function capitalizeWords(str) {
+    return str.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/** @requires STRING @produces COUNT @tags string, count */
+function countSubstring(str, sub) {
+    if (!sub)
+        return 0;
+    let count = 0, pos = 0;
+    while ((pos = str.indexOf(sub, pos)) !== -1) {
+        count++;
+        pos += sub.length;
+    }
+    return count;
+}
+/** @requires STRING @produces CLEANED_STRING @tags string, format */
+function removeWhitespace(str) {
+    return str.replace(/\s+/g, "");
+}
+// ── Array ──
+/** @requires ARRAY @produces ELEMENT @tags array, statistics */
+function mostFrequent(arr) {
+    if (arr.length === 0)
+        return null;
+    const counts = new Map();
+    for (const item of arr)
+        counts.set(item, (counts.get(item) || 0) + 1);
+    return [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+}
+/** @requires ARRAY @produces ARRAY @tags array, dedupe */
+function unique(arr) { return [...new Set(arr)]; }
+/** @requires ARRAY @produces ARRAY @tags array, chunk */
+function chunk(arr, size) {
+    const result = [];
+    for (let i = 0; i < arr.length; i += size)
+        result.push(arr.slice(i, i + size));
+    return result;
+}
+/** @requires ARRAY @produces ARRAY @tags array, difference */
+function arrayDiff(a, b) {
+    const setB = new Set(b);
+    return a.filter(x => !setB.has(x));
+}
+// ── Math ──
+/** @requires NUMBERS @produces AVERAGE @tags math, statistics */
+function average(nums) {
+    return nums.length === 0 ? 0 : nums.reduce((a, b) => a + b, 0) / nums.length;
+}
+/** @requires NUMBERS @produces MEDIAN @tags math, statistics */
+function median(nums) {
+    if (nums.length === 0)
+        return 0;
+    const sorted = [...nums].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/** @requires NUMBER @produces ROUNDED_NUMBER @tags math, format */
+function roundTo(num, decimals) {
+    const factor = Math.pow(10, decimals);
+    return Math.round(num * factor) / factor;
+}
+/** @requires NUMBER @produces PRIME_CHECK @tags math, validation */
+function isPrime(n) {
+    if (n < 2)
+        return false;
+    for (let i = 2; i <= Math.sqrt(n); i++)
+        if (n % i === 0)
+            return false;
+    return true;
+}
+/** @requires NUMBERS @produces RANDOM_INT @tags math, random */
+function randomInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+// ── Object ──
+/** @requires OBJECT @produces CLONED_OBJECT @tags object, clone */
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+/** @requires OBJECT @produces PICKED_OBJECT @tags object, filter */
+function pick(obj, keys) {
+    const result = {};
+    for (const k of keys)
+        if (k in obj)
+            result[k] = obj[k];
+    return result;
+}
+/** @requires OBJECTS @produces MERGED_OBJECT @tags object, merge */
+function deepMerge(...objects) {
+    return objects.reduce((acc, obj) => {
+        for (const key of Object.keys(obj || {})) {
+            acc[key] = typeof obj[key] === "object" && !Array.isArray(obj[key])
+                ? deepMerge(acc[key] || {}, obj[key]) : obj[key];
+        }
+        return acc;
+    }, {});
+}
+// ── Validation ──
+/** @requires OBJECT @produces VALIDATION_RESULT @tags validation, schema */
+function hasRequiredFields(obj, fields) {
+    return fields.every(f => obj && obj[f] !== undefined && obj[f] !== null);
+}
+/** @requires ANY @produces VALIDATION_RESULT @tags validation, type */
+function isPlainObject(val) {
+    return val !== null && typeof val === "object" && !Array.isArray(val);
+}
+/** @requires STRING @produces PARSED_VERSION @tags validation, semver */
+function parseSemver(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return { major: +match[1], minor: +match[2], patch: +match[3] };
+}
+// ── Formatting ──
+/** @requires NUMBER @produces FORMATTED_STRING @tags format, duration */
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const mins = Math.floor(ms / 60000);
+    const secs = Math.round((ms % 60000) / 1000);
+    return `${mins}m ${secs}s`;
+}
+/** @requires NUMBER @produces FORMATTED_STRING @tags format, file */
+function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1048576)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / 1048576).toFixed(1)}MB`;
+}
+/** @requires OBJECT @produces QUERY_STRING @tags web, format */
+function toQueryString(obj) {
+    return Object.entries(obj)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join("&");
+}
+// ── Async ──
+/** @requires FUNCTION @produces RETRY_RESULT @tags async, retry */
+async function retry(fn, maxRetries = 3) {
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (i === maxRetries - 1)
+                throw e;
+        }
+    }
+    throw new Error("unreachable");
+}
+/** @requires FUNCTION @produces DEBOUNCED_FUNCTION @tags async, debounce */
+function debounce(fn, delay) {
+    let timer;
+    return ((...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), delay);
+    });
+}

package/dist/utils.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.jaccardSimilarity = jaccardSimilarity;
 exports.extractKeywords = extractKeywords;
 // 计算两个字符串的简单 Jaccard 相似度（基于字符二元组）
+/** @requires STRING_A @produces SIMILARITY_SCORE */
 function jaccardSimilarity(a, b) {
     const bigrams = (s) => {
         const bgs = new Set();
@@ -17,6 +18,7 @@ function jaccardSimilarity(a, b) {
     return intersection.size / (union.size || 1);
 }
 // 从意图中提取关键词
+/** @requires TEXT @produces KEYWORDS */
 function extractKeywords(intent) {
     return intent.split(/[\s，。！？,]+/).filter(w => w.length > 1).map(w => w.toLowerCase());
 }

package/dist/validator.js

@@ -150,6 +150,7 @@ function checkVariableFlow(actions) {
  * 校验单个动作的合法性（函数存在、类型匹配、参数数量）。
  * @protocol namespace=dev_pipeline pre_states=["IR_EXTRACTED"] post_states=["ACTION_VALIDATED"]
  */
+/** @requires ACTION @produces VALIDATION_RESULT */
 function validateAction(action, actionIndex) {
     const functions = loadIR();
     const errors = [];
@@ -229,6 +230,7 @@ function validateAction(action, actionIndex) {
  * 批量校验动作序列 + 变量流向分析。
  * @protocol namespace=dev_pipeline pre_states=["ACTION_VALIDATED"] post_states=["SEQUENCE_VALIDATED"] invalidate=["ACTION_VALIDATED"]
  */
+/** @requires ACTIONS @produces VALIDATION_RESULT */
 function validateActionSequence(actions) {
     const errors = [];
     const violations = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "progmune-runtime",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Progmune Runtime — Program Immunology: Constraint-Guided Program Synthesis Runtime",
   "main": "dist/mcp-server.mjs",
   "bin": {