@nforma.ai/nforma 0.2.1

package/bin/debt-ledger.cjs

@@ -0,0 +1,61 @@
+/**
+ * Debt ledger I/O module
+ * Provides atomic read/write operations for debt ledger with fail-open behavior
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Read debt ledger from file
+ * Implements fail-open: returns empty ledger on missing or corrupt files
+ * @param {string} ledgerPath - Path to debt.json file
+ * @returns {object} Ledger object with schema_version, created_at, last_updated, debt_entries
+ */
+function readDebtLedger(ledgerPath) {
+  try {
+    const content = fs.readFileSync(ledgerPath, 'utf8');
+    const ledger = JSON.parse(content);
+    return ledger;
+  } catch (err) {
+    // Fail-open: log error but return empty ledger
+    console.error(`[debt-ledger] Failed to read ledger at ${ledgerPath}:`, err.message);
+
+    const now = new Date().toISOString();
+    return {
+      schema_version: '1',
+      created_at: now,
+      last_updated: now,
+      debt_entries: []
+    };
+  }
+}
+
+/**
+ * Write debt ledger to file atomically
+ * Uses temp file + rename pattern to prevent corruption on crash
+ * @param {string} ledgerPath - Path to debt.json file
+ * @param {object} ledger - Ledger object to write
+ */
+function writeDebtLedger(ledgerPath, ledger) {
+  // Ensure parent directory exists
+  const dir = path.dirname(ledgerPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Update last_updated timestamp
+  const now = new Date().toISOString();
+  const ledgerToWrite = {
+    ...ledger,
+    last_updated: now
+  };
+
+  // Atomic write: write to temp file, then rename
+  const tmpPath = ledgerPath + '.tmp';
+  fs.writeFileSync(tmpPath, JSON.stringify(ledgerToWrite, null, 2), 'utf8');
+  fs.renameSync(tmpPath, ledgerPath);
+}
+
+module.exports = {
+  readDebtLedger,
+  writeDebtLedger
+};

package/bin/debt-retention.cjs

@@ -0,0 +1,76 @@
+/**
+ * Debt retention policy module
+ * Handles archival of resolved entries older than max_age
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Apply retention policy to debt ledger
+ * Archives resolved entries older than max_age to separate array
+ * Non-resolved entries are NEVER archived regardless of age
+ * @param {object} ledger - Debt ledger object
+ * @param {number} maxAgeDays - Maximum age in days for resolved entries (default: 90)
+ * @returns {object} { active: [], archived: [] } - Split ledger entries
+ */
+function applyRetentionPolicy(ledger, maxAgeDays = 90) {
+  const active = [];
+  const archived = [];
+
+  // Calculate cutoff timestamp
+  const now = new Date();
+  const cutoffMs = now.getTime() - (maxAgeDays * 24 * 60 * 60 * 1000);
+  const cutoffDate = new Date(cutoffMs);
+
+  // Process each entry
+  for (const entry of ledger.debt_entries) {
+    // Only archive resolved entries
+    if (entry.status !== 'resolved') {
+      active.push(entry);
+      continue;
+    }
+
+    // Determine cutoff timestamp: prefer resolved_at, fall back to last_seen
+    const relevantTimestamp = entry.resolved_at || entry.last_seen;
+    if (!relevantTimestamp) {
+      // No timestamp available, keep active to avoid data loss
+      active.push(entry);
+      continue;
+    }
+
+    const entryDate = new Date(relevantTimestamp);
+    if (entryDate < cutoffDate) {
+      // Entry is older than max_age, archive it
+      archived.push(entry);
+    } else {
+      // Entry is newer than max_age, keep it active
+      active.push(entry);
+    }
+  }
+
+  return { active, archived };
+}
+
+/**
+ * Write archived entries to JSONL file
+ * Appends entries (does not overwrite)
+ * @param {array} archivedEntries - Array of debt entries to archive
+ * @param {string} archivePath - Path to .jsonl archive file
+ */
+function writeArchive(archivedEntries, archivePath) {
+  // Ensure parent directory exists
+  const dir = path.dirname(archivePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Write each entry as a separate JSON line
+  const lines = archivedEntries.map(entry => JSON.stringify(entry)).join('\n');
+  if (lines.length > 0) {
+    fs.appendFileSync(archivePath, lines + '\n', 'utf8');
+  }
+}
+
+module.exports = {
+  applyRetentionPolicy,
+  writeArchive
+};

package/bin/debt-state-machine.cjs

@@ -0,0 +1,80 @@
+/**
+ * Debt status state machine
+ * Enforces valid transitions: open -> acknowledged -> resolving -> resolved
+ */
+
+/**
+ * Allowed transitions map
+ * Each state maps to an array of valid target states
+ */
+const ALLOWED_TRANSITIONS = {
+  'open': ['acknowledged'],                    // open can only go to acknowledged
+  'acknowledged': ['resolving', 'open'],       // can move forward or revert to open
+  'resolving': ['resolved'],                   // can only go to resolved
+  'resolved': []                                // terminal state — no outbound transitions
+};
+
+/**
+ * Check if a transition is allowed
+ * @param {string} fromStatus - Current status
+ * @param {string} toStatus - Target status
+ * @returns {boolean} true if transition is allowed, false otherwise
+ */
+function canTransition(fromStatus, toStatus) {
+  // Reject transition to same status (no-op transitions not allowed)
+  if (fromStatus === toStatus) {
+    return false;
+  }
+
+  // Check if transition is in the allowed list
+  const allowed = ALLOWED_TRANSITIONS[fromStatus] || [];
+  return allowed.includes(toStatus);
+}
+
+/**
+ * Transition a debt entry to a new status
+ * @param {object} entry - Debt entry object
+ * @param {string} newStatus - Target status
+ * @returns {object} { success: boolean, entry?: object, error?: string }
+ */
+function transitionDebtEntry(entry, newStatus) {
+  const errors = [];
+
+  // Validate target status is one of the allowed values
+  const validStatuses = ['open', 'acknowledged', 'resolving', 'resolved'];
+  if (!validStatuses.includes(newStatus)) {
+    errors.push(`Invalid target status: ${newStatus}`);
+  }
+
+  // Check if transition is allowed
+  if (!canTransition(entry.status, newStatus)) {
+    errors.push(`Transition not allowed: ${entry.status} -> ${newStatus}`);
+  }
+
+  // Return error if any validation failed
+  if (errors.length > 0) {
+    return {
+      success: false,
+      error: errors.join('; ')
+    };
+  }
+
+  // Apply transition: create updated entry with new status
+  const updated = { ...entry, status: newStatus };
+
+  // Add resolved_at timestamp when transitioning to resolved state
+  if (newStatus === 'resolved') {
+    updated.resolved_at = new Date().toISOString();
+  }
+
+  return {
+    success: true,
+    entry: updated
+  };
+}
+
+module.exports = {
+  canTransition,
+  transitionDebtEntry,
+  ALLOWED_TRANSITIONS
+};

package/bin/detect-coverage-gaps.cjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+'use strict';
+// bin/detect-coverage-gaps.cjs
+// TLC state-space vs conformance trace coverage gap detector.
+// Requirements: SIG-01
+//
+// Usage:
+//   node bin/detect-coverage-gaps.cjs [--spec=QGSDQuorum] [--log=path]
+//
+// Output:
+//   .planning/formal/coverage-gaps.md — structured test backlog when gaps exist
+//
+// Computes: TLC-reachable states minus trace-observed states = coverage gaps.
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── State mapping definitions ────────────────────────────────────────────────
+// Maps each TLA+ spec to its state variable name and value-to-name mapping.
+// Source of truth: state comments in the TLA+ spec files.
+const STATE_MAPS = {
+  'QGSDQuorum': {
+    variable: 's',
+    values: { '0': 'COLLECTING_VOTES', '1': 'DECIDED', '2': 'DELIBERATING' },
+  },
+  'QGSDStopHook': {
+    variable: 'phase',
+    values: { '0': 'IDLE', '1': 'READING', '2': 'DECIDING', '3': 'BLOCKED' },
+  },
+  'QGSDCircuitBreaker': {
+    variable: 'state',
+    values: { '0': 'MONITORING', '1': 'TRIGGERED', '2': 'RECOVERING' },
+  },
+};
+
+// ── Action-to-state reverse mapping ──────────────────────────────────────────
+// Maps conformance event action names to state names for trace parsing.
+const ACTION_TO_STATE = {
+  'quorum_start':       'COLLECTING_VOTES',
+  'quorum_complete':    'DECIDED',
+  'quorum_block':       'DECIDED',
+  'deliberation_round': 'DELIBERATING',
+  'stop_hook_read':     'READING',
+  'stop_hook_decide':   'DECIDING',
+  'stop_hook_block':    'BLOCKED',
+  'stop_hook_idle':     'IDLE',
+  'breaker_trigger':    'TRIGGERED',
+  'breaker_recover':    'RECOVERING',
+  'breaker_monitor':    'MONITORING',
+};
+
+/**
+ * parseTlcStates(specName) — returns the full set of named states for a spec.
+ * @param {string} specName - TLA+ spec name (e.g. 'QGSDQuorum')
+ * @returns {{ specName: string, states: Set<string>, variable: string } | null}
+ */
+function parseTlcStates(specName) {
+  const map = STATE_MAPS[specName];
+  if (!map) return null;
+  return {
+    specName,
+    states: new Set(Object.values(map.values)),
+    variable: map.variable,
+  };
+}
+
+/**
+ * parseTraceStates(logPath) — extracts observed states from conformance JSONL.
+ * @param {string} logPath - path to conformance-events.jsonl
+ * @returns {Set<string> | null} - set of observed state names, or null if file missing
+ */
+function parseTraceStates(logPath) {
+  const pp = require('./planning-paths.cjs');
+  const p = logPath || pp.resolveWithFallback(process.cwd(), 'conformance-events');
+  try {
+    if (!fs.existsSync(p)) return null;
+    const raw = fs.readFileSync(p, 'utf8');
+    const lines = raw.split('\n').filter(l => l.trim().length > 0);
+    const observed = new Set();
+    for (const line of lines) {
+      try {
+        const event = JSON.parse(line);
+        // Try state field first
+        if (event.state && typeof event.state === 'string') {
+          observed.add(event.state);
+        }
+        // Map action to state
+        if (event.action && ACTION_TO_STATE[event.action]) {
+          observed.add(ACTION_TO_STATE[event.action]);
+        }
+      } catch (_) { /* skip malformed lines */ }
+    }
+    return observed;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * detectCoverageGaps(options) — computes TLC reachable minus trace observed.
+ * @param {{ specName?: string, logPath?: string, outputPath?: string }} options
+ * @returns {{ status: string, gaps?: string[], outputPath?: string, reason?: string }}
+ */
+function detectCoverageGaps(options = {}) {
+  const specName   = options.specName || 'QGSDQuorum';
+  const pp2 = require('./planning-paths.cjs');
+  const logPath    = options.logPath || pp2.resolveWithFallback(process.cwd(), 'conformance-events');
+  const outputPath = options.outputPath || path.join(process.cwd(), '.planning', 'formal', 'coverage-gaps.md');
+
+  const tlcResult = parseTlcStates(specName);
+  if (!tlcResult) {
+    return { status: 'unknown-spec', reason: 'Spec ' + specName + ' not found in STATE_MAPS' };
+  }
+
+  const traceStates = parseTraceStates(logPath);
+  if (traceStates === null) {
+    return { status: 'no-traces', reason: 'conformance log not found' };
+  }
+
+  // Compute gap = reachable - observed
+  const gaps = [];
+  for (const state of tlcResult.states) {
+    if (!traceStates.has(state)) {
+      gaps.push(state);
+    }
+  }
+
+  if (gaps.length === 0) {
+    return { status: 'full-coverage', gaps: [] };
+  }
+
+  // Write coverage-gaps.md
+  const reachable = tlcResult.states.size;
+  const observed  = reachable - gaps.length;
+  const pct       = ((observed / reachable) * 100).toFixed(0);
+  const timestamp = new Date().toISOString();
+
+  // Build variable value lookup
+  const specMap = STATE_MAPS[specName];
+  const stateToValue = {};
+  for (const [val, name] of Object.entries(specMap.values)) {
+    stateToValue[name] = specMap.variable + '=' + val;
+  }
+
+  const md = [
+    '# TLC Coverage Gaps',
+    '',
+    'Generated: ' + timestamp,
+    'Spec: ' + specName,
+    '',
+    '## Unreached States',
+    '',
+    '| State | Variable Value | Description |',
+    '|-------|---------------|-------------|',
+  ];
+
+  for (const gap of gaps.sort()) {
+    const varVal = stateToValue[gap] || 'unknown';
+    md.push('| ' + gap + ' | ' + varVal + ' | State reachable by TLC but never observed in conformance traces |');
+  }
+
+  md.push('');
+  md.push('## Coverage Summary');
+  md.push('');
+  md.push('- TLC reachable: ' + reachable + ' states');
+  md.push('- Trace observed: ' + observed + ' states');
+  md.push('- Gaps: ' + gaps.length + ' states (' + pct + '% coverage)');
+  md.push('');
+  md.push('## Action Items');
+  md.push('');
+  md.push('Each gap represents a state that formal verification proves is reachable but production has never exercised.');
+  md.push('Add test cases that drive the system into these states.');
+  md.push('');
+
+  // Ensure output directory exists
+  const outDir = path.dirname(outputPath);
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(outputPath, md.join('\n'));
+
+  return { status: 'gaps-found', gaps, outputPath };
+}
+
+// ── CLI entrypoint ───────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const specArg = args.find(a => a.startsWith('--spec='));
+  const logArg  = args.find(a => a.startsWith('--log='));
+
+  const specName = specArg ? specArg.split('=')[1] : 'QGSDQuorum';
+  const logPath  = logArg ? logArg.split('=')[1] : undefined;
+
+  const result = detectCoverageGaps({ specName, logPath });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+
+  if (result.status === 'gaps-found') {
+    process.stderr.write('[detect-coverage-gaps] ' + result.gaps.length + ' gap(s) found. See: ' + result.outputPath + '\n');
+  } else if (result.status === 'no-traces') {
+    process.stderr.write('[detect-coverage-gaps] No conformance log found — nothing to compare.\n');
+  } else if (result.status === 'full-coverage') {
+    process.stderr.write('[detect-coverage-gaps] Full coverage — all TLC-reachable states observed in traces.\n');
+  }
+}
+
+module.exports = { detectCoverageGaps, parseTlcStates, parseTraceStates };