@nforma.ai/nforma 0.2.1

package/bin/quorum-consensus-gate.cjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+'use strict';
+// bin/quorum-consensus-gate.cjs
+// PRISM consensus probability gate for quorum rounds.
+// Requirements: SIG-04
+//
+// Usage:
+//   node bin/quorum-consensus-gate.cjs [--min-quorum=2]
+//
+// Computes P(consensus_reached) from current scoreboard availability rates
+// using the Poisson binomial distribution (closed-form, no PRISM dependency).
+// Gates quorum rounds when probability is below threshold.
+//
+// Exit 0 = proceed, Exit 1 = defer.
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * poissonBinomialCDF(probabilities, k) — computes P(X >= k) for heterogeneous trials.
+ *
+ * Uses recursive DP approach for the Poisson binomial distribution:
+ *   dp[0] = 1 (base case: 0 successes with 0 trials)
+ *   For each probability p_i: dp[j] = dp[j] * (1-p_i) + dp[j-1] * p_i for j from n down to 1
+ *   Returns P(X >= k) = sum of dp[k..n]
+ *
+ * Equivalent to the PRISM mcp-availability.pm model but computed in O(n^2) without Java.
+ *
+ * @param {number[]} probabilities - per-slot availability rates
+ * @param {number} k - minimum number of successes needed
+ * @returns {number} P(X >= k)
+ */
+function poissonBinomialCDF(probabilities, k) {
+  const n = probabilities.length;
+  if (k > n) return 0;
+  if (k <= 0) return 1.0;
+
+  // dp[j] = probability of exactly j successes after processing i trials
+  const dp = new Array(n + 1).fill(0);
+  dp[0] = 1; // base: P(0 successes with 0 trials) = 1
+
+  for (let i = 0; i < n; i++) {
+    const p = probabilities[i];
+    // Process backwards to avoid overwriting dp[j-1] before it's used
+    for (let j = i + 1; j >= 1; j--) {
+      dp[j] = dp[j] * (1 - p) + dp[j - 1] * p;
+    }
+    dp[0] = dp[0] * (1 - p);
+  }
+
+  // P(X >= k) = sum of dp[k..n]
+  let result = 0;
+  for (let j = k; j <= n; j++) {
+    result += dp[j];
+  }
+
+  return result;
+}
+
+/**
+ * computeConsensusProbability(slotRates, minQuorum) — computes P(consensus_reached).
+ * @param {Object} slotRates - { slot_name: availability_rate }
+ * @param {number} minQuorum - minimum number of slots needed for consensus
+ * @returns {{ probability: number, slotCount: number, minQuorum: number, rates: Object }}
+ */
+function computeConsensusProbability(slotRates, minQuorum) {
+  const probabilities = Object.values(slotRates);
+  const probability = poissonBinomialCDF(probabilities, minQuorum);
+
+  return {
+    probability: Math.round(probability * 1e6) / 1e6,
+    slotCount: probabilities.length,
+    minQuorum,
+    rates: slotRates,
+  };
+}
+
+/**
+ * checkConsensusGate(options) — reads scoreboard, computes probability, returns gate decision.
+ * @param {{ scoreboardPath?: string, configPath?: string, minQuorum?: number }} options
+ * @returns {{ action: string, probability: number, threshold: number, message: string }}
+ */
+function checkConsensusGate(options = {}) {
+  const pp = require('./planning-paths.cjs');
+  const scoreboardPath = options.scoreboardPath || pp.resolveWithFallback(process.cwd(), 'quorum-scoreboard');
+  const configPath     = options.configPath || path.join(process.cwd(), '.planning', 'config.json');
+  const minQuorum      = options.minQuorum || 2;
+
+  // Read scoreboard availability rates
+  let slotRates = null;
+  try {
+    const { readMCPAvailabilityRates } = require('./run-prism.cjs');
+    slotRates = readMCPAvailabilityRates(scoreboardPath);
+  } catch (_) {
+    // run-prism.cjs not available — fall through to priors
+  }
+
+  // If no rates (empty/missing scoreboard): use conservative prior rates
+  if (!slotRates || Object.keys(slotRates).length === 0) {
+    slotRates = {
+      'slot-1': 0.85,
+      'slot-2': 0.85,
+      'slot-3': 0.85,
+      'slot-4': 0.85,
+    };
+  }
+
+  // Read threshold from config.json
+  let threshold = 0.70;
+  try {
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config.workflow && typeof config.workflow.consensus_probability_threshold === 'number') {
+        threshold = config.workflow.consensus_probability_threshold;
+      }
+    }
+  } catch (_) {
+    // Use default threshold
+  }
+
+  // Compute P(consensus_reached)
+  const result = computeConsensusProbability(slotRates, minQuorum);
+  const probability = result.probability;
+
+  if (probability >= threshold) {
+    return {
+      action: 'proceed',
+      probability,
+      threshold,
+      message: 'Consensus probability ' + probability.toFixed(4) + ' >= threshold ' + threshold.toFixed(2) + ' -- proceeding',
+    };
+  } else {
+    return {
+      action: 'defer',
+      probability,
+      threshold,
+      message: 'WARNING: Consensus probability ' + probability.toFixed(4) + ' < threshold ' + threshold.toFixed(2) + ' -- deferring quorum round. Slot availability too low for reliable consensus.',
+    };
+  }
+}
+
+/**
+ * readEarlyEscalationThreshold(configPaths) — reads workflow.early_escalation_threshold from config.
+ *
+ * Tries each config path in order. Returns 0.10 (default) if:
+ * - No paths provided or none exist
+ * - JSON parse fails (fail-open)
+ * - Value is missing, non-numeric, or outside [0, 1.0] range
+ *
+ * @param {string[]} configPaths - ordered list of config file paths to try
+ * @returns {number} threshold (0.0 to 1.0), or 0.10 default
+ */
+function readEarlyEscalationThreshold(configPaths) {
+  const DEFAULT = 0.10;
+  const paths = configPaths || [
+    path.join(process.cwd(), '.planning', 'config.json'),
+    path.join(process.cwd(), '.planning', 'qgsd.json'),
+  ];
+  for (const cfgPath of paths) {
+    try {
+      if (fs.existsSync(cfgPath)) {
+        const config = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+        const val = config.workflow?.early_escalation_threshold;
+        if (typeof val === 'number' && val > 0 && val <= 1.0) return val;
+      }
+    } catch (_) {
+      // Fail-open: JSON parse error, continue to next path
+    }
+  }
+  return DEFAULT;
+}
+
+/**
+ * computeEarlyEscalation(slotRates, minQuorum, remainingRounds, threshold)
+ *
+ * Computes P(consensus within remainingRounds) and checks early escalation:
+ * - P(at least minQuorum succeed in 1 round) using poissonBinomialCDF
+ * - P(consensus within k rounds) = 1 - (1 - pPerRound)^k
+ * - If P(consensus | remaining) < threshold, shouldEscalate = true
+ *
+ * @param {Object} slotRates - { slot_name: availability_rate }
+ * @param {number} minQuorum - minimum successful slots needed
+ * @param {number} remainingRounds - rounds left in deliberation loop
+ * @param {number} threshold - escalation threshold (optional, defaults to 0.10)
+ * @returns {{ shouldEscalate: boolean, probability: number, threshold: number, remainingRounds: number, pPerRound: number }}
+ */
+function computeEarlyEscalation(slotRates, minQuorum, remainingRounds, threshold) {
+  if (typeof threshold !== 'number') threshold = readEarlyEscalationThreshold();
+  if (remainingRounds <= 0) {
+    return { shouldEscalate: true, probability: 0, threshold, remainingRounds, pPerRound: 0 };
+  }
+  const rates = Object.values(slotRates);
+  const pPerRound = poissonBinomialCDF(rates, minQuorum);
+  const probability = 1 - Math.pow(1 - pPerRound, remainingRounds);
+  const rounded = Math.round(probability * 1e6) / 1e6;
+  return {
+    shouldEscalate: rounded < threshold,
+    probability: rounded,
+    threshold,
+    remainingRounds,
+    pPerRound: Math.round(pPerRound * 1e6) / 1e6,
+  };
+}
+
+// ── CLI entrypoint ───────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const minQuorumArg = args.find(a => a.startsWith('--min-quorum='));
+  const minQuorum = minQuorumArg ? parseInt(minQuorumArg.split('=')[1], 10) : undefined;
+
+  const remainingRoundsArg = args.find(a => a.startsWith('--remaining-rounds='));
+
+  if (remainingRoundsArg) {
+    // HEAL-01: Early escalation mode -- compute P(consensus | remaining rounds)
+    const remainingRounds = parseInt(remainingRoundsArg.split('=')[1], 10);
+    const pp2 = require('./planning-paths.cjs');
+    const scoreboardPath = pp2.resolveWithFallback(process.cwd(), 'quorum-scoreboard');
+    let slotRates = null;
+    try {
+      const { readMCPAvailabilityRates } = require('./run-prism.cjs');
+      slotRates = readMCPAvailabilityRates(scoreboardPath);
+    } catch (_) {}
+    if (!slotRates || Object.keys(slotRates).length === 0) {
+      slotRates = { 'slot-1': 0.85, 'slot-2': 0.85, 'slot-3': 0.85, 'slot-4': 0.85 };
+    }
+    const result = computeEarlyEscalation(slotRates, minQuorum || 2, remainingRounds);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    // Exit 1 = should escalate (stop deliberating), Exit 0 = continue deliberating
+    process.exit(result.shouldEscalate ? 1 : 0);
+  } else {
+    // Original behavior: unconditional consensus gate check
+    const result = checkConsensusGate({ minQuorum });
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    process.exit(result.action === 'proceed' ? 0 : 1);
+  }
+}
+
+module.exports = { checkConsensusGate, computeConsensusProbability, poissonBinomialCDF, computeEarlyEscalation, readEarlyEscalationThreshold };

package/bin/quorum-formal-context.cjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+'use strict';
+// bin/quorum-formal-context.cjs
+// PLAN-03: Generates formal_spec_summary and verification_result fields for
+// injection into the quorum slot-worker prompt.
+//
+// Translates PLAN.md truths into plain-English descriptions with INVARIANT/PROPERTY
+// classifications, maps TLC results to PASS/FAIL/INCONCLUSIVE, and builds a
+// formatted evidence block for prompt injection.
+//
+// Usage:
+//   node bin/quorum-formal-context.cjs <path-to-PLAN.md> [--tlc-result=<json>]
+//
+// Output: Formatted evidence block to stdout
+
+const fs   = require('fs');
+const path = require('path');
+
+const { parsePlanFrontmatter, classifyTruth } = require('./generate-phase-spec.cjs');
+
+/**
+ * Sanitize a truth string for safe embedding in quorum prompts.
+ * - Replaces newlines with spaces
+ * - Replaces angle brackets with square brackets (prevents XML/tag injection)
+ * - Preserves backslashes (valid in TLA+ operators)
+ * - Wraps in backticks instead of double quotes (avoids nested quote confusion)
+ *
+ * @param {string} truth
+ * @returns {string}
+ */
+function sanitizeTruth(truth) {
+  return truth
+    .replace(/\n/g, ' ')
+    .replace(/\r/g, '')
+    .replace(/</g, '[')
+    .replace(/>/g, ']');
+}
+
+/**
+ * Generate a plain-English formal spec summary from a PLAN.md file.
+ *
+ * @param {string} planFilePath - Path to the PLAN.md file
+ * @returns {{ summary: string, truthCount: number } | null}
+ */
+function generateFormalSpecSummary(planFilePath) {
+  const content = fs.readFileSync(planFilePath, 'utf8');
+  const fm = parsePlanFrontmatter(content);
+  const truths = fm.truths || [];
+
+  if (truths.length === 0) {
+    return null;
+  }
+
+  let summary = "Proposed formal properties (from plan's must_haves: truths:):\n";
+
+  truths.forEach((truth, idx) => {
+    const kind = classifyTruth(truth);
+    const sanitized = sanitizeTruth(truth);
+    const kindLabel = kind === 'INVARIANT'
+      ? 'This is a safety property (must always hold)'
+      : 'This is a liveness property (must eventually hold)';
+    summary += (idx + 1) + '. [' + kind + '] `' + sanitized + '` -- ' + kindLabel + '\n';
+  });
+
+  return { summary, truthCount: truths.length };
+}
+
+/**
+ * Generate a verification result string from a TLC result object.
+ *
+ * @param {{ status?: string, truthCount?: number, runtimeMs?: number, violations?: string[], reason?: string } | null | undefined} tlcResult
+ * @returns {string}
+ */
+function generateVerificationResult(tlcResult) {
+  if (tlcResult === null || tlcResult === undefined) {
+    return 'INCONCLUSIVE: No verification was run';
+  }
+
+  if (tlcResult.status === 'skipped') {
+    return 'INCONCLUSIVE: No truths in plan to verify';
+  }
+
+  if (tlcResult.status === 'passed') {
+    const count = tlcResult.truthCount || 0;
+    const ms = tlcResult.runtimeMs || 0;
+    return 'PASS: All ' + count + ' properties verified by TLC in ' + ms + 'ms';
+  }
+
+  if (tlcResult.status === 'failed') {
+    const violations = tlcResult.violations || [];
+    // Check for Java not found
+    if (violations.some(v => v.includes('Java not found'))) {
+      return 'INCONCLUSIVE: Java/TLC not available for verification';
+    }
+    return 'FAIL: ' + violations.length + ' properties violated -- ' + violations.join(', ');
+  }
+
+  return 'INCONCLUSIVE: Unknown verification state';
+}
+
+/**
+ * Build a formatted formal evidence block for quorum prompt injection.
+ *
+ * @param {string | null} formalSpecSummary - Output of generateFormalSpecSummary().summary
+ * @param {string | null} verificationResult - Output of generateVerificationResult()
+ * @returns {string | null}
+ */
+function buildFormalEvidenceBlock(formalSpecSummary, verificationResult) {
+  if (!formalSpecSummary && !verificationResult) {
+    return null;
+  }
+
+  let block = '=== Formal Evidence ===\n';
+  if (formalSpecSummary) {
+    block += "Proposed TLA+ properties (from plan's must_haves: truths:):\n";
+    block += formalSpecSummary + '\n';
+  }
+  if (verificationResult) {
+    block += 'Verification result: ' + verificationResult + '\n';
+  }
+  block += '======================';
+
+  return block;
+}
+
+/**
+ * Convenience function: get full formal context for a plan file.
+ *
+ * @param {string} planFilePath - Path to the PLAN.md file
+ * @param {{ status?: string, truthCount?: number, runtimeMs?: number, violations?: string[] } | null} tlcResult
+ * @returns {{ formalSpecSummary: string | null, verificationResult: string | null, evidenceBlock: string | null }}
+ */
+function getFormalContext(planFilePath, tlcResult) {
+  const summaryResult = generateFormalSpecSummary(planFilePath);
+
+  if (!summaryResult) {
+    return { formalSpecSummary: null, verificationResult: null, evidenceBlock: null };
+  }
+
+  const formalSpecSummary = summaryResult.summary;
+  const verificationResult = generateVerificationResult(tlcResult);
+  const evidenceBlock = buildFormalEvidenceBlock(formalSpecSummary, verificationResult);
+
+  return { formalSpecSummary, verificationResult, evidenceBlock };
+}
+
+// ── CLI entrypoint ────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args = process.argv.slice(2).filter(a => !a.startsWith('--'));
+  const flags = process.argv.slice(2).filter(a => a.startsWith('--'));
+
+  if (args.length === 0) {
+    process.stderr.write('[quorum-formal-context] Usage: node bin/quorum-formal-context.cjs <path-to-PLAN.md> [--tlc-result=<json>]\n');
+    process.exit(1);
+  }
+
+  const planFilePath = path.resolve(args[0]);
+  if (!fs.existsSync(planFilePath)) {
+    process.stderr.write('[quorum-formal-context] Error: file not found: ' + planFilePath + '\n');
+    process.exit(1);
+  }
+
+  // Parse optional --tlc-result flag
+  let tlcResult = null;
+  const tlcFlag = flags.find(f => f.startsWith('--tlc-result='));
+  if (tlcFlag) {
+    try {
+      tlcResult = JSON.parse(tlcFlag.split('=').slice(1).join('='));
+    } catch (e) {
+      process.stderr.write('[quorum-formal-context] Warning: could not parse --tlc-result JSON: ' + e.message + '\n');
+    }
+  }
+
+  const ctx = getFormalContext(planFilePath, tlcResult);
+
+  if (ctx.evidenceBlock) {
+    process.stdout.write(ctx.evidenceBlock + '\n');
+  } else {
+    process.stderr.write('[quorum-formal-context] No formal evidence found in ' + planFilePath + '\n');
+  }
+}
+
+module.exports = { generateFormalSpecSummary, generateVerificationResult, buildFormalEvidenceBlock, getFormalContext };