tribunal-kit 9.2.7 → 9.2.8

package/.agent/scripts/architecture_verifier.js

@@ -1,303 +1,303 @@
-#!/usr/bin/env node
-/**
- * architecture_verifier.js — Tribunal Zero-Trust Architecture Verifier
- * ═════════════════════════════════════════════════════════════════════════════
- * Evaluates architectural models against ground-truth source code bytes.
- *
- * Capabilities:
- *   - Verifies all source citations (file exists, line valid, no path escapes)
- *   - Detects Stale Evidence via SHA-256 drift verification
- *   - Verifies AST Symbol and Relationship Call Sites
- *   - Assigns Epistemic Confidence Levels (L1 to L5)
- *   - Surfaces Architectural Contradictions as first-class disputable records
- *   - Prevents unverified agent claims from masquerading as verified facts
- *
- * Emits: .agent/history/architecture-verification.json
- * Zero external dependencies.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { GREEN, YELLOW, CYAN, RED, DIM, RESET, BOX, banner, timer, formatMs } = require('./_colors');
-
-function computeSha256(str) {
-  return crypto
-    .createHash('sha256')
-    .update(str || '')
-    .digest('hex');
-}
-
-class ArchitectureVerifier {
-  constructor(repoRoot = process.cwd(), options = {}) {
-    this.repoRoot = path.resolve(repoRoot);
-    this.options = { strict: false, ...options };
-    this.results = {
-      verified: true,
-      timestamp: new Date().toISOString(),
-      stats: {
-        totalEntities: 0,
-        verifiedEntities: 0,
-        staleEntities: 0,
-        fabricatedEntities: 0,
-        totalRelations: 0,
-        verifiedRelations: 0,
-        contradictedRelations: 0,
-      },
-      confidenceDistribution: { L1: 0, L2: 0, L3: 0, L4: 0, L5: 0 },
-      contradictions: [],
-      diagnostics: [],
-    };
-  }
-
-  verifyModel(model) {
-    if (!model || !Array.isArray(model.entities)) {
-      throw new Error('Invalid model: expected an object with entities array.');
-    }
-
-    const { entities, relationships = [], contradictions = [] } = model;
-    this.results.stats.totalEntities = entities.length;
-    this.results.stats.totalRelations = relationships.length;
-
-    // Entity verification map for fast lookup
-    const entityIndex = new Map();
-
-    // 1. Verify Entity Sources & Ground Truth
-    for (const entity of entities) {
-      entityIndex.set(entity.id, entity);
-      const entityVerification = this.verifyEntity(entity);
-      if (entityVerification.status === 'verified') {
-        this.results.stats.verifiedEntities++;
-        this.results.confidenceDistribution[entity.confidence || 'L1']++;
-      } else if (entityVerification.status === 'stale') {
-        this.results.stats.staleEntities++;
-        this.results.confidenceDistribution['L3']++;
-        this.results.diagnostics.push({
-          severity: 'warning',
-          code: 'ARCH_EVIDENCE_STALE',
-          entityId: entity.id,
-          message: `Evidence has drifted for entity "${entity.name}" (${entity.id}). Content hash does not match.`,
-          details: entityVerification.details,
-        });
-      } else {
-        this.results.stats.fabricatedEntities++;
-        this.results.confidenceDistribution['L5']++;
-        this.results.verified = false;
-        this.results.diagnostics.push({
-          severity: 'error',
-          code: 'ARCH_EVIDENCE_FABRICATED',
-          entityId: entity.id,
-          message: `Evidence does not exist in repository for entity "${entity.name}" (${entity.id}).`,
-          details: entityVerification.details,
-        });
-      }
-    }
-
-    // 2. Verify Relationships & Call Sites
-    for (const rel of relationships) {
-      const relVerification = this.verifyRelationship(rel, entityIndex);
-      if (relVerification.status === 'verified') {
-        this.results.stats.verifiedRelations++;
-      } else if (relVerification.status === 'contradicted') {
-        this.results.stats.contradictedRelations++;
-        this.results.verified = false;
-        this.results.contradictions.push({
-          id: `conflict.${rel.id}`,
-          relationshipId: rel.id,
-          sourceId: rel.sourceId,
-          targetId: rel.targetId,
-          conflictType: relVerification.conflictType || 'unreachable_call_path',
-          claimedRelation: rel.relationType,
-          reason: relVerification.reason,
-          confidence: 'L5',
-        });
-        this.results.diagnostics.push({
-          severity: 'error',
-          code: 'ARCH_RELATION_CONTRADICTED',
-          relationId: rel.id,
-          message: `Contradiction detected in relationship ${rel.sourceId} -> ${rel.targetId}: ${relVerification.reason}`,
-        });
-      } else {
-        this.results.diagnostics.push({
-          severity: 'warning',
-          code: 'ARCH_RELATION_UNVERIFIED',
-          relationId: rel.id,
-          message: `Relationship ${rel.sourceId} -> ${rel.targetId} lacks direct call-site evidence.`,
-        });
-      }
-    }
-
-    // 3. Reconcile explicit contradictions passed in model
-    for (const c of contradictions) {
-      this.results.contradictions.push(c);
-    }
-
-    return this.results;
-  }
-
-  verifyEntity(entity) {
-    if (!entity.sources || !entity.sources.length) {
-      return { status: 'unverified', details: { reason: 'No sources declared' } };
-    }
-
-    let anyStale = false;
-    let anyMissing = false;
-
-    for (const src of entity.sources) {
-      const check = this.verifySourceFile(src.file, src.startLine, src.snippet, src.contentHash);
-      if (!check.exists) anyMissing = true;
-      if (check.stale) anyStale = true;
-    }
-
-    if (anyMissing)
-      return { status: 'fabricated', details: { reason: 'Cited file or line does not exist' } };
-    if (anyStale) return { status: 'stale', details: { reason: 'File content hash has drifted' } };
-    return { status: 'verified', details: {} };
-  }
-
-  verifyRelationship(rel, entityIndex) {
-    const source = entityIndex.get(rel.sourceId);
-    const target = entityIndex.get(rel.targetId);
-
-    if (!source) {
-      return {
-        status: 'contradicted',
-        conflictType: 'missing_source_entity',
-        reason: `Source entity ${rel.sourceId} not found.`,
-      };
-    }
-    if (!target) {
-      return {
-        status: 'contradicted',
-        conflictType: 'missing_target_entity',
-        reason: `Target entity ${rel.targetId} not found.`,
-      };
-    }
-
-    // Check evidence call site if present
-    if (rel.evidence && rel.evidence.length > 0) {
-      for (const ev of rel.evidence) {
-        const check = this.verifySourceFile(ev.file, ev.startLine, ev.snippet, ev.contentHash);
-        if (!check.exists) {
-          return {
-            status: 'contradicted',
-            conflictType: 'fabricated_call_site',
-            reason: `Evidence file ${ev.file} does not exist for relation.`,
-          };
-        }
-      }
-      return { status: 'verified' };
-    }
-
-    // If relation is an import or route, check if source imports target
-    return { status: 'unverified', reason: 'No call-site evidence' };
-  }
-
-  verifySourceFile(relPath, lineNum, expectedSnippet, expectedHash) {
-    const fullPath = path.resolve(this.repoRoot, relPath);
-
-    // Path escape boundary defense
-    const normalizedRepo = path.resolve(this.repoRoot);
-    if (!fullPath.startsWith(normalizedRepo)) {
-      return { exists: false, reason: 'Path traversal escape detected' };
-    }
-
-    if (!fs.existsSync(fullPath)) {
-      return { exists: false, reason: 'File does not exist' };
-    }
-
-    let content;
-    try {
-      content = fs.readFileSync(fullPath, 'utf8');
-    } catch (_e) {
-      return { exists: false, reason: 'File could not be read' };
-    }
-
-    const lines = content.split('\n');
-    if (lineNum !== undefined && lineNum !== null) {
-      if (lineNum < 1 || lineNum > lines.length) {
-        return {
-          exists: false,
-          reason: `Line ${lineNum} out of range (file has ${lines.length} lines)`,
-        };
-      }
-
-      if (expectedHash) {
-        const actualLine = lines[lineNum - 1] || '';
-        const actualHash = computeSha256(actualLine).substring(0, 16);
-        const actualFileHash = computeSha256(content).substring(0, 16);
-        if (actualHash !== expectedHash && actualFileHash !== expectedHash) {
-          return { exists: true, stale: true, reason: 'Content hash mismatch' };
-        }
-      }
-    }
-
-    return { exists: true, stale: false };
-  }
-
-  saveReport(outputPath) {
-    const defaultPath = path.join(
-      this.repoRoot,
-      '.agent',
-      'history',
-      'architecture-verification.json',
-    );
-    const dest = outputPath || defaultPath;
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.writeFileSync(dest, JSON.stringify(this.results, null, 2), 'utf8');
-    return dest;
-  }
-}
-
-// ── Standalone CLI ────────────────────────────────────────────────────────────
-if (require.main === module) {
-  const t = timer();
-  const repoRoot = process.argv[2] || process.cwd();
-  const modelFile = path.join(repoRoot, '.agent', 'history', 'architecture-model.json');
-
-  console.log(banner('Tribunal Architecture Zero-Trust Verifier'));
-
-  if (!fs.existsSync(modelFile)) {
-    console.error(
-      `  ${RED}✖ architecture-model.json not found.${RESET} Run architecture_extractor.js first.`,
-    );
-    process.exit(1);
-  }
-
-  const model = JSON.parse(fs.readFileSync(modelFile, 'utf8'));
-  const verifier = new ArchitectureVerifier(repoRoot);
-  const results = verifier.verifyModel(model);
-  const reportPath = verifier.saveReport();
-
-  const isOk =
-    results.verified && results.diagnostics.filter(d => d.severity === 'error').length === 0;
-  const statusColor = isOk ? GREEN : RED;
-  const statusIcon = isOk ? BOX.check : BOX.cross_mark;
-
-  console.log(
-    `  ${statusColor}${statusIcon} Verification ${isOk ? 'PASSED' : 'FLAGGED ISSUES'}${RESET} in ${formatMs(t())}`,
-  );
-  console.log(
-    `  ${DIM}Entities Verified:${RESET}      ${GREEN}${results.stats.verifiedEntities}${RESET} / ${results.stats.totalEntities}`,
-  );
-  console.log(
-    `  ${DIM}Stale Evidence:${RESET}         ${results.stats.staleEntities > 0 ? YELLOW : GREEN}${results.stats.staleEntities}${RESET}`,
-  );
-  console.log(
-    `  ${DIM}Contradictions Surfaced:${RESET} ${results.contradictions.length > 0 ? RED : GREEN}${results.contradictions.length}${RESET}`,
-  );
-  console.log(
-    `  ${DIM}Confidence (L1 Facts):${RESET}   ${CYAN}${results.confidenceDistribution.L1}${RESET}`,
-  );
-  console.log(`  ${DIM}Saved Report:${RESET}            ${CYAN}${reportPath}${RESET}\n`);
-
-  if (!isOk && process.argv.includes('--strict')) {
-    process.exit(1);
-  }
-}
-
-module.exports = {
-  ArchitectureVerifier,
-};
+#!/usr/bin/env node
+/**
+ * architecture_verifier.js — Tribunal Zero-Trust Architecture Verifier
+ * ═════════════════════════════════════════════════════════════════════════════
+ * Evaluates architectural models against ground-truth source code bytes.
+ *
+ * Capabilities:
+ *   - Verifies all source citations (file exists, line valid, no path escapes)
+ *   - Detects Stale Evidence via SHA-256 drift verification
+ *   - Verifies AST Symbol and Relationship Call Sites
+ *   - Assigns Epistemic Confidence Levels (L1 to L5)
+ *   - Surfaces Architectural Contradictions as first-class disputable records
+ *   - Prevents unverified agent claims from masquerading as verified facts
+ *
+ * Emits: .agent/history/architecture-verification.json
+ * Zero external dependencies.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { GREEN, YELLOW, CYAN, RED, DIM, RESET, BOX, banner, timer, formatMs } = require('./_colors');
+
+function computeSha256(str) {
+  return crypto
+    .createHash('sha256')
+    .update(str || '')
+    .digest('hex');
+}
+
+class ArchitectureVerifier {
+  constructor(repoRoot = process.cwd(), options = {}) {
+    this.repoRoot = path.resolve(repoRoot);
+    this.options = { strict: false, ...options };
+    this.results = {
+      verified: true,
+      timestamp: new Date().toISOString(),
+      stats: {
+        totalEntities: 0,
+        verifiedEntities: 0,
+        staleEntities: 0,
+        fabricatedEntities: 0,
+        totalRelations: 0,
+        verifiedRelations: 0,
+        contradictedRelations: 0,
+      },
+      confidenceDistribution: { L1: 0, L2: 0, L3: 0, L4: 0, L5: 0 },
+      contradictions: [],
+      diagnostics: [],
+    };
+  }
+
+  verifyModel(model) {
+    if (!model || !Array.isArray(model.entities)) {
+      throw new Error('Invalid model: expected an object with entities array.');
+    }
+
+    const { entities, relationships = [], contradictions = [] } = model;
+    this.results.stats.totalEntities = entities.length;
+    this.results.stats.totalRelations = relationships.length;
+
+    // Entity verification map for fast lookup
+    const entityIndex = new Map();
+
+    // 1. Verify Entity Sources & Ground Truth
+    for (const entity of entities) {
+      entityIndex.set(entity.id, entity);
+      const entityVerification = this.verifyEntity(entity);
+      if (entityVerification.status === 'verified') {
+        this.results.stats.verifiedEntities++;
+        this.results.confidenceDistribution[entity.confidence || 'L1']++;
+      } else if (entityVerification.status === 'stale') {
+        this.results.stats.staleEntities++;
+        this.results.confidenceDistribution['L3']++;
+        this.results.diagnostics.push({
+          severity: 'warning',
+          code: 'ARCH_EVIDENCE_STALE',
+          entityId: entity.id,
+          message: `Evidence has drifted for entity "${entity.name}" (${entity.id}). Content hash does not match.`,
+          details: entityVerification.details,
+        });
+      } else {
+        this.results.stats.fabricatedEntities++;
+        this.results.confidenceDistribution['L5']++;
+        this.results.verified = false;
+        this.results.diagnostics.push({
+          severity: 'error',
+          code: 'ARCH_EVIDENCE_FABRICATED',
+          entityId: entity.id,
+          message: `Evidence does not exist in repository for entity "${entity.name}" (${entity.id}).`,
+          details: entityVerification.details,
+        });
+      }
+    }
+
+    // 2. Verify Relationships & Call Sites
+    for (const rel of relationships) {
+      const relVerification = this.verifyRelationship(rel, entityIndex);
+      if (relVerification.status === 'verified') {
+        this.results.stats.verifiedRelations++;
+      } else if (relVerification.status === 'contradicted') {
+        this.results.stats.contradictedRelations++;
+        this.results.verified = false;
+        this.results.contradictions.push({
+          id: `conflict.${rel.id}`,
+          relationshipId: rel.id,
+          sourceId: rel.sourceId,
+          targetId: rel.targetId,
+          conflictType: relVerification.conflictType || 'unreachable_call_path',
+          claimedRelation: rel.relationType,
+          reason: relVerification.reason,
+          confidence: 'L5',
+        });
+        this.results.diagnostics.push({
+          severity: 'error',
+          code: 'ARCH_RELATION_CONTRADICTED',
+          relationId: rel.id,
+          message: `Contradiction detected in relationship ${rel.sourceId} -> ${rel.targetId}: ${relVerification.reason}`,
+        });
+      } else {
+        this.results.diagnostics.push({
+          severity: 'warning',
+          code: 'ARCH_RELATION_UNVERIFIED',
+          relationId: rel.id,
+          message: `Relationship ${rel.sourceId} -> ${rel.targetId} lacks direct call-site evidence.`,
+        });
+      }
+    }
+
+    // 3. Reconcile explicit contradictions passed in model
+    for (const c of contradictions) {
+      this.results.contradictions.push(c);
+    }
+
+    return this.results;
+  }
+
+  verifyEntity(entity) {
+    if (!entity.sources || !entity.sources.length) {
+      return { status: 'unverified', details: { reason: 'No sources declared' } };
+    }
+
+    let anyStale = false;
+    let anyMissing = false;
+
+    for (const src of entity.sources) {
+      const check = this.verifySourceFile(src.file, src.startLine, src.snippet, src.contentHash);
+      if (!check.exists) anyMissing = true;
+      if (check.stale) anyStale = true;
+    }
+
+    if (anyMissing)
+      return { status: 'fabricated', details: { reason: 'Cited file or line does not exist' } };
+    if (anyStale) return { status: 'stale', details: { reason: 'File content hash has drifted' } };
+    return { status: 'verified', details: {} };
+  }
+
+  verifyRelationship(rel, entityIndex) {
+    const source = entityIndex.get(rel.sourceId);
+    const target = entityIndex.get(rel.targetId);
+
+    if (!source) {
+      return {
+        status: 'contradicted',
+        conflictType: 'missing_source_entity',
+        reason: `Source entity ${rel.sourceId} not found.`,
+      };
+    }
+    if (!target) {
+      return {
+        status: 'contradicted',
+        conflictType: 'missing_target_entity',
+        reason: `Target entity ${rel.targetId} not found.`,
+      };
+    }
+
+    // Check evidence call site if present
+    if (rel.evidence && rel.evidence.length > 0) {
+      for (const ev of rel.evidence) {
+        const check = this.verifySourceFile(ev.file, ev.startLine, ev.snippet, ev.contentHash);
+        if (!check.exists) {
+          return {
+            status: 'contradicted',
+            conflictType: 'fabricated_call_site',
+            reason: `Evidence file ${ev.file} does not exist for relation.`,
+          };
+        }
+      }
+      return { status: 'verified' };
+    }
+
+    // If relation is an import or route, check if source imports target
+    return { status: 'unverified', reason: 'No call-site evidence' };
+  }
+
+  verifySourceFile(relPath, lineNum, expectedSnippet, expectedHash) {
+    const fullPath = path.resolve(this.repoRoot, relPath);
+
+    // Path escape boundary defense
+    const normalizedRepo = path.resolve(this.repoRoot);
+    if (!fullPath.startsWith(normalizedRepo)) {
+      return { exists: false, reason: 'Path traversal escape detected' };
+    }
+
+    if (!fs.existsSync(fullPath)) {
+      return { exists: false, reason: 'File does not exist' };
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch (_e) {
+      return { exists: false, reason: 'File could not be read' };
+    }
+
+    const lines = content.split('\n');
+    if (lineNum !== undefined && lineNum !== null) {
+      if (lineNum < 1 || lineNum > lines.length) {
+        return {
+          exists: false,
+          reason: `Line ${lineNum} out of range (file has ${lines.length} lines)`,
+        };
+      }
+
+      if (expectedHash) {
+        const actualLine = lines[lineNum - 1] || '';
+        const actualHash = computeSha256(actualLine).substring(0, 16);
+        const actualFileHash = computeSha256(content).substring(0, 16);
+        if (actualHash !== expectedHash && actualFileHash !== expectedHash) {
+          return { exists: true, stale: true, reason: 'Content hash mismatch' };
+        }
+      }
+    }
+
+    return { exists: true, stale: false };
+  }
+
+  saveReport(outputPath) {
+    const defaultPath = path.join(
+      this.repoRoot,
+      '.agent',
+      'history',
+      'architecture-verification.json',
+    );
+    const dest = outputPath || defaultPath;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, JSON.stringify(this.results, null, 2), 'utf8');
+    return dest;
+  }
+}
+
+// ── Standalone CLI ────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const t = timer();
+  const repoRoot = process.argv[2] || process.cwd();
+  const modelFile = path.join(repoRoot, '.agent', 'history', 'architecture-model.json');
+
+  console.log(banner('Tribunal Architecture Zero-Trust Verifier'));
+
+  if (!fs.existsSync(modelFile)) {
+    console.error(
+      `  ${RED}✖ architecture-model.json not found.${RESET} Run architecture_extractor.js first.`,
+    );
+    process.exit(1);
+  }
+
+  const model = JSON.parse(fs.readFileSync(modelFile, 'utf8'));
+  const verifier = new ArchitectureVerifier(repoRoot);
+  const results = verifier.verifyModel(model);
+  const reportPath = verifier.saveReport();
+
+  const isOk =
+    results.verified && results.diagnostics.filter(d => d.severity === 'error').length === 0;
+  const statusColor = isOk ? GREEN : RED;
+  const statusIcon = isOk ? BOX.check : BOX.cross_mark;
+
+  console.log(
+    `  ${statusColor}${statusIcon} Verification ${isOk ? 'PASSED' : 'FLAGGED ISSUES'}${RESET} in ${formatMs(t())}`,
+  );
+  console.log(
+    `  ${DIM}Entities Verified:${RESET}      ${GREEN}${results.stats.verifiedEntities}${RESET} / ${results.stats.totalEntities}`,
+  );
+  console.log(
+    `  ${DIM}Stale Evidence:${RESET}         ${results.stats.staleEntities > 0 ? YELLOW : GREEN}${results.stats.staleEntities}${RESET}`,
+  );
+  console.log(
+    `  ${DIM}Contradictions Surfaced:${RESET} ${results.contradictions.length > 0 ? RED : GREEN}${results.contradictions.length}${RESET}`,
+  );
+  console.log(
+    `  ${DIM}Confidence (L1 Facts):${RESET}   ${CYAN}${results.confidenceDistribution.L1}${RESET}`,
+  );
+  console.log(`  ${DIM}Saved Report:${RESET}            ${CYAN}${reportPath}${RESET}\n`);
+
+  if (!isOk && process.argv.includes('--strict')) {
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  ArchitectureVerifier,
+};