create-byan-agent 2.4.6 → 2.6.0

package/src/byan-v2/fact-check/fact-sheet.js

@@ -0,0 +1,96 @@
+/**
+ * FactSheet - Generates a Markdown fact sheet from session facts
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class FactSheet {
+  constructor(outputPath = '_byan-output/fact-sheets') {
+    this.outputPath = outputPath;
+  }
+
+  generate(sessionId, facts) {
+    if (!sessionId) throw new Error('sessionId is required');
+    if (!facts || typeof facts !== 'object') throw new Error('facts must be an object');
+
+    const { verified = [], claims = [], disputed = [], opinions = [] } = facts;
+    const total = verified.length + claims.length + disputed.length + opinions.length;
+    const sourced = verified.length + claims.length;
+    const trustScore = total > 0 ? Math.round((sourced / total) * 100) : 100;
+    const badge = FactSheet.trustBadge(trustScore);
+
+    const date = new Date().toISOString().slice(0, 10);
+    const lines = [
+      `# Fact Sheet — Session ${sessionId}`,
+      `**Date :** ${date}`,
+      `**Truth Score :** ${trustScore}% (${sourced}/${total} claims sourced)  ${badge}`,
+      ''
+    ];
+
+    if (verified.length > 0) {
+      lines.push('## Facts verifies par l\'utilisateur');
+      verified.forEach(f => lines.push(`- [FACT USER-VERIFIED] ${f.claim}`));
+      lines.push('');
+    }
+
+    if (claims.length > 0) {
+      lines.push('## Claims sources (LEVEL-1 a LEVEL-3)');
+      claims.forEach(f => {
+        const src = f.source ? ` — ${f.source.url || f.source}` : '';
+        const proof = f.proof ? ` — proof: ${f.proof.content || f.proof}` : '';
+        lines.push(`- [CLAIM L${f.level || '?'}] ${f.claim}${src}${proof}`);
+      });
+      lines.push('');
+    }
+
+    if (disputed.length > 0) {
+      lines.push('## Claims disputes (sources contradictoires)');
+      disputed.forEach(f => lines.push(`- [DISPUTED] ${f.claim}`));
+      lines.push('');
+    }
+
+    if (opinions.length > 0) {
+      lines.push('## Opinions et hypotheses declarees');
+      opinions.forEach(f => {
+        const prefix = f.status === 'HYPOTHESIS' ? '[HYPOTHESIS]' : '[OPINION]';
+        lines.push(`- ${prefix} ${f.claim}`);
+      });
+      lines.push('');
+    }
+
+    if (trustScore < 80) {
+      lines.push('## Avertissement');
+      lines.push(`Truth Score de ${trustScore}% — plus de ${100 - trustScore}% des assertions ne sont pas sourcees.`);
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Returns a text badge representing the trust level
+   * @param {number} score - 0 to 100
+   * @returns {string}
+   */
+  static trustBadge(score) {
+    if (score >= 90) return '[Trust: A — Excellent]';
+    if (score >= 75) return '[Trust: B — Bon]';
+    if (score >= 60) return '[Trust: C — Acceptable]';
+    if (score >= 40) return '[Trust: D — Faible]';
+    return '[Trust: F — Non-source]';
+  }
+
+  save(sessionId, facts) {
+    const content = this.generate(sessionId, facts);
+    const date = new Date().toISOString().slice(0, 10);
+    const filename = `session-${date}-${sessionId.slice(0, 8)}.md`;
+    const fullPath = path.join(this.outputPath, filename);
+
+    fs.mkdirSync(this.outputPath, { recursive: true });
+    fs.writeFileSync(fullPath, content, 'utf8');
+    return fullPath;
+  }
+}
+
+module.exports = FactSheet;

package/src/byan-v2/fact-check/index.js

@@ -0,0 +1,263 @@
+/**
+ * FactChecker - Scientific fact-checking for BYAN
+ *
+ * Principles : demonstrable, quantifiable, reproducible
+ * Method     : 4 assertion types x 5 proof levels
+ * Rule       : Never generate a URL — only cite verified knowledge base
+ *
+ * @class FactChecker
+ */
+
+const fs = require('fs');
+const path = require('path');
+const LevelScorer = require('./level-scorer');
+const ClaimParser = require('./claim-parser');
+const FactSheet = require('./fact-sheet');
+const KnowledgeGraph = require('./knowledge-graph');
+
+const ASSERTION_TYPES = ['REASONING', 'HYPOTHESIS', 'CLAIM', 'FACT'];
+
+// Fact half-lives in days by domain (null = never expires)
+const DEFAULT_HALF_LIVES = {
+  security:    180,   // 6 months — CVEs and vulns change fast
+  performance: 365,   // 1 year — benchmarks depend on versions
+  compliance:  180,   // 6 months — regulations evolve
+  javascript:  365,   // 1 year — ecosystem moves fast
+  general:     730,   // 2 years — general tech claims
+  algorithms:  null   // never — Big O does not change
+};
+
+class FactChecker {
+  constructor(config = {}, sessionState = null) {
+    this.config = {
+      enabled: true,
+      mode: 'offline',
+      min_level: 3,
+      strict_domains: ['security', 'performance', 'compliance'],
+      output_fact_sheet: true,
+      fact_sheet_path: '_byan-output/fact-sheets',
+      knowledge_base: '_byan/knowledge/sources.md',
+      axioms: '_byan/knowledge/axioms.md',
+      half_lives: DEFAULT_HALF_LIVES,
+      ...config
+    };
+    this.sessionState = sessionState;
+    this.graph = new KnowledgeGraph(this.config.graph_path || '_byan/_memory/fact-graph.json');
+    this.scorer = new LevelScorer();
+    this.parser = new ClaimParser(config.auto_trigger_patterns || []);
+    this.sheet = new FactSheet(this.config.fact_sheet_path);
+    this._knowledgeBase = null;
+    this._axioms = null;
+  }
+
+  /**
+   * Check a claim against the knowledge base
+   * @param {string} claim
+   * @param {object} options - { level, source, proof, domain }
+   * @returns {{ status, level, score, assertionType, message }}
+   */
+  check(claim, options = {}) {
+    if (typeof claim !== 'string' || !claim) {
+      throw new Error('claim must be a non-empty string');
+    }
+
+    const { level = 5, source = null, proof = null, domain = null } = options;
+
+    if (level < 1 || level > 5) throw new Error('level must be between 1 and 5');
+
+    if (domain && this.scorer.isBlockedInDomain(level, domain)) {
+      return {
+        status: 'BLOCKED',
+        level,
+        score: this.scorer.score(level),
+        assertionType: 'OPINION',
+        message: `Domain "${domain}" requires LEVEL-${this.config.strict_domains.includes(domain) ? 2 : 1} minimum. Got LEVEL-${level}.`
+      };
+    }
+
+    if (level > this.config.min_level) {
+      return {
+        status: 'OPINION',
+        level,
+        score: this.scorer.score(level),
+        assertionType: 'HYPOTHESIS',
+        message: `LEVEL-${level} is below min_level (${this.config.min_level}). Marked as HYPOTHESIS.`
+      };
+    }
+
+    const fact = {
+      claim,
+      level,
+      source,
+      proof,
+      status: 'CLAIM',
+      confidence: this.scorer.score(level),
+      assertionType: 'CLAIM'
+    };
+
+    if (this.sessionState) this.sessionState.addFact(fact);
+    this.graph.add({ ...fact, domain: domain || 'general', expires_at: this.expiresAt(domain || 'general') });
+
+    return {
+      status: 'CLAIM',
+      level,
+      score: fact.confidence,
+      assertionType: 'CLAIM',
+      message: `[CLAIM L${level}] ${claim}${source ? ' — ' + (source.url || source) : ''}${proof ? ' — proof: ' + (proof.content || proof) : ''}`
+    };
+  }
+
+  /**
+   * Register a user-verified fact with proof artifact
+   * @param {string} claim
+   * @param {string|object} proof - command output, screenshot path, log excerpt
+   * @returns {{ status, message }}
+   */
+  verify(claim, proof) {
+    if (typeof claim !== 'string' || !claim) throw new Error('claim must be a non-empty string');
+    if (!proof) throw new Error('proof artifact is required for USER-VERIFIED facts');
+
+    const date = new Date().toISOString().slice(0, 10);
+    const fact = {
+      claim,
+      level: 1,
+      proof: typeof proof === 'string' ? { type: 'user-provided', content: proof } : proof,
+      status: 'VERIFIED',
+      confidence: 100,
+      assertionType: 'FACT',
+      verified_at: date
+    };
+
+    if (this.sessionState) this.sessionState.addFact(fact);
+    this.graph.add({ ...fact, domain: 'verified', expires_at: null });
+
+    return {
+      status: 'VERIFIED',
+      message: `[FACT USER-VERIFIED ${date}] ${claim}`
+    };
+  }
+
+  /**
+   * Detect implicit claims in a text using trigger patterns
+   * @param {string} text
+   * @returns {Array<{ matched, excerpt, position }>}
+   */
+  parse(text) {
+    return this.parser.parse(text);
+  }
+
+  /**
+   * Generate and optionally save the session Fact Sheet
+   * @param {string} sessionId
+   * @param {object} facts - { verified, claims, disputed, opinions }
+   * @param {boolean} save - write to disk
+   * @returns {{ content, filePath }}
+   */
+  generateFactSheet(sessionId, facts, save = true) {
+    const content = this.sheet.generate(sessionId, facts);
+    let filePath = null;
+    if (save && this.config.output_fact_sheet) {
+      filePath = this.sheet.save(sessionId, facts);
+    }
+    return { content, filePath };
+  }
+
+  /**
+   * Calculate expiry date for a fact based on its domain
+   * @param {string} domain
+   * @param {string} createdAt - ISO date string
+   * @returns {string|null} ISO expiry date or null if never expires
+   */
+  expiresAt(domain, createdAt = new Date().toISOString()) {
+    const halfLife = (this.config.half_lives || DEFAULT_HALF_LIVES)[domain];
+    if (halfLife === null || halfLife === undefined) return null;
+    const created = new Date(createdAt);
+    const expiry = new Date(Date.UTC(
+      created.getUTCFullYear(),
+      created.getUTCMonth(),
+      created.getUTCDate() + halfLife
+    ));
+    return expiry.toISOString().slice(0, 10);
+  }
+
+  /**
+   * Check if a stored fact has expired
+   * @param {object} fact - must have created_at and domain
+   * @returns {{ expired: boolean, daysLeft: number|null, warning: string|null }}
+   */
+  checkExpiration(fact) {
+    if (!fact || !fact.created_at) throw new Error('fact.created_at is required');
+    const domain = fact.domain || 'general';
+    const expiry = this.expiresAt(domain, fact.created_at);
+
+    if (!expiry) return { expired: false, daysLeft: null, warning: null };
+
+    const now = new Date();
+    const expiryDate = new Date(expiry);
+    const daysLeft = Math.ceil((expiryDate - now) / (1000 * 60 * 60 * 24));
+
+    if (daysLeft <= 0) {
+      return { expired: true, daysLeft: 0, warning: `[EXPIRED] This fact (domain: ${domain}) is ${Math.abs(daysLeft)} days past its expiry date. Re-verify before using.` };
+    }
+    if (daysLeft <= 30) {
+      return { expired: false, daysLeft, warning: `[EXPIRING SOON] This fact expires in ${daysLeft} days. Consider re-verifying.` };
+    }
+    return { expired: false, daysLeft, warning: null };
+  }
+
+  /**
+   * Calculate confidence propagation through a reasoning chain
+   * Confidence degrades multiplicatively: 80% x 80% x 80% = 51%
+   * @param {Array<number>} scores - confidence scores for each chain step (0-100)
+   * @returns {{ finalScore: number, warning: string|null, steps: number }}
+   */
+  chain(scores) {
+    if (!Array.isArray(scores) || scores.length === 0) {
+      throw new Error('scores must be a non-empty array of numbers');
+    }
+    for (const s of scores) {
+      if (typeof s !== 'number' || s < 0 || s > 100) {
+        throw new Error('Each score must be a number between 0 and 100');
+      }
+    }
+
+    const finalScore = Math.round(
+      scores.reduce((acc, s) => acc * (s / 100), 1) * 100
+    );
+
+    let warning = null;
+    if (scores.length > 3) {
+      warning = `Chain of ${scores.length} steps detected. Confidence degraded to ${finalScore}% (${scores.join('% x ')}%). Consider finding a direct source instead of a long deduction chain.`;
+    } else if (finalScore < 60) {
+      warning = `Chain confidence is ${finalScore}% — below 60% threshold. This conclusion should not be presented as a firm recommendation.`;
+    }
+
+    return { finalScore, steps: scores.length, warning };
+  }
+
+  _loadKnowledgeBase() {
+    if (this._knowledgeBase) return this._knowledgeBase;
+    try {
+      this._knowledgeBase = fs.readFileSync(
+        path.resolve(this.config.knowledge_base), 'utf8'
+      );
+    } catch {
+      this._knowledgeBase = '';
+    }
+    return this._knowledgeBase;
+  }
+
+  _loadAxioms() {
+    if (this._axioms) return this._axioms;
+    try {
+      this._axioms = fs.readFileSync(
+        path.resolve(this.config.axioms), 'utf8'
+      );
+    } catch {
+      this._axioms = '';
+    }
+    return this._axioms;
+  }
+}
+
+module.exports = FactChecker;

package/src/byan-v2/fact-check/knowledge-graph.js

@@ -0,0 +1,152 @@
+/**
+ * KnowledgeGraph - Persistent fact store across BYAN sessions
+ *
+ * Storage: _byan/_memory/fact-graph.json
+ * Each entry: { id, claim, domain, status, confidence, created_at, expires_at, source, session_id }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+class KnowledgeGraph {
+  constructor(storagePath = '_byan/_memory/fact-graph.json') {
+    this.storagePath = storagePath;
+    this._data = null;
+  }
+
+  load() {
+    if (this._data) return this._data;
+    try {
+      const raw = fs.readFileSync(path.resolve(this.storagePath), 'utf8');
+      this._data = JSON.parse(raw);
+    } catch {
+      this._data = { version: 1, facts: [], updated_at: null };
+    }
+    return this._data;
+  }
+
+  save() {
+    const data = this.load();
+    data.updated_at = new Date().toISOString();
+    const dir = path.dirname(path.resolve(this.storagePath));
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.resolve(this.storagePath), JSON.stringify(data, null, 2), 'utf8');
+  }
+
+  /**
+   * Add a fact to the graph. Deduplicates by claim text (updates existing).
+   * @param {object} fact - { claim, domain, status, confidence, source, session_id, expires_at }
+   * @returns {string} fact id
+   */
+  add(fact) {
+    if (!fact || !fact.claim) throw new Error('fact.claim is required');
+    const data = this.load();
+    const existing = data.facts.find(f => f.claim === fact.claim && f.domain === fact.domain);
+
+    if (existing) {
+      Object.assign(existing, fact, { updated_at: new Date().toISOString() });
+      this.save();
+      return existing.id;
+    }
+
+    const id = crypto.createHash('md5').update(fact.claim + (fact.domain || '')).digest('hex').slice(0, 8);
+    const entry = {
+      id,
+      claim: fact.claim,
+      domain: fact.domain || 'general',
+      status: fact.status || 'CLAIM',
+      confidence: fact.confidence || 50,
+      source: fact.source || null,
+      session_id: fact.session_id || null,
+      expires_at: fact.expires_at || null,
+      created_at: fact.created_at || new Date().toISOString().slice(0, 10),
+      updated_at: new Date().toISOString()
+    };
+
+    data.facts.push(entry);
+    this.save();
+    return id;
+  }
+
+  /**
+   * Query facts with optional filters
+   * @param {object} filters - { domain, status, expiredOnly, sessionId }
+   * @returns {Array}
+   */
+  query({ domain, status, expiredOnly, sessionId } = {}) {
+    const { facts } = this.load();
+    return facts.filter(f => {
+      if (domain && f.domain !== domain) return false;
+      if (status && f.status !== status) return false;
+      if (sessionId && f.session_id !== sessionId) return false;
+      if (expiredOnly) {
+        if (!f.expires_at) return false;
+        return new Date(f.expires_at) < new Date();
+      }
+      return true;
+    });
+  }
+
+  /**
+   * Run expiration check on all facts using FactChecker.checkExpiration
+   * @param {object} checker - FactChecker instance
+   * @returns {{ expired: Array, expiringSoon: Array, healthy: Array }}
+   */
+  audit(checker) {
+    const { facts } = this.load();
+    const result = { expired: [], expiringSoon: [], healthy: [] };
+
+    for (const fact of facts) {
+      const check = checker.checkExpiration({
+        claim: fact.claim,
+        domain: fact.domain,
+        created_at: fact.created_at
+      });
+
+      if (check.expired) {
+        result.expired.push({ ...fact, _check: check });
+      } else if (check.warning) {
+        result.expiringSoon.push({ ...fact, _check: check });
+      } else {
+        result.healthy.push(fact);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Remove all expired facts from the graph
+   * @param {object} checker - FactChecker instance
+   * @returns {number} count of pruned facts
+   */
+  prune(checker) {
+    const { expired } = this.audit(checker);
+    const data = this.load();
+    const expiredIds = new Set(expired.map(f => f.id));
+    const before = data.facts.length;
+    data.facts = data.facts.filter(f => !expiredIds.has(f.id));
+    this.save();
+    return before - data.facts.length;
+  }
+
+  /**
+   * Statistics by domain and status
+   * @returns {object}
+   */
+  stats() {
+    const { facts } = this.load();
+    const byDomain = {};
+    const byStatus = {};
+
+    for (const f of facts) {
+      byDomain[f.domain] = (byDomain[f.domain] || 0) + 1;
+      byStatus[f.status] = (byStatus[f.status] || 0) + 1;
+    }
+
+    return { total: facts.length, byDomain, byStatus };
+  }
+}
+
+module.exports = KnowledgeGraph;

package/src/byan-v2/fact-check/level-scorer.js

@@ -0,0 +1,45 @@
+/**
+ * LevelScorer - Scores a fact's confidence based on its proof level
+ * 
+ * LEVEL-1 : Official spec / RFC / Primary documentation  → 95
+ * LEVEL-2 : Reproducible benchmark / Executable code     → 80
+ * LEVEL-3 : Peer-reviewed article / Independent source   → 65
+ * LEVEL-4 : Community consensus (> 1000 votes)           → 50
+ * LEVEL-5 : Opinion / Personal experience                → 20
+ */
+
+const LEVEL_SCORES = { 1: 95, 2: 80, 3: 65, 4: 50, 5: 20 };
+
+const STRICT_DOMAIN_MIN_LEVEL = {
+  security:    2,
+  performance: 2,
+  compliance:  1
+};
+
+class LevelScorer {
+  score(level) {
+    if (!Number.isInteger(level) || level < 1 || level > 5) {
+      throw new Error('Level must be an integer between 1 and 5');
+    }
+    return LEVEL_SCORES[level];
+  }
+
+  isBlockedInDomain(level, domain) {
+    const minLevel = STRICT_DOMAIN_MIN_LEVEL[domain];
+    if (!minLevel) return false;
+    return level > minLevel;
+  }
+
+  describeLevel(level) {
+    const descriptions = {
+      1: 'Official spec / RFC / Primary documentation',
+      2: 'Reproducible benchmark / Executable proof',
+      3: 'Peer-reviewed / Independent source',
+      4: 'Community consensus',
+      5: 'Opinion / Personal experience'
+    };
+    return descriptions[level] || 'Unknown level';
+  }
+}
+
+module.exports = LevelScorer;