tribunal-kit 9.2.6 → 9.2.8

package/src/execution/controlled_write_service.js

@@ -0,0 +1,301 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const TransactionManager = require('./transaction_manager');
+const { WritePolicyEngine } = require('./write_policy_engine');
+const { evaluateDecision } = require('../system1/decision_engine');
+const { ReviewExecutor } = require('./review_executor');
+const { VerdictAggregator } = require('./verdict_aggregator');
+
+function computeSha256(data) {
+  return crypto
+    .createHash('sha256')
+    .update(data || '', 'utf8')
+    .digest('hex');
+}
+
+const { AgentCorrectionEngine } = require('./agent_correction_engine');
+
+class ControlledWriteService {
+  constructor(options = {}) {
+    this.txManager =
+      options.txManager ||
+      new TransactionManager({ workspace: options.workspaceRoot || process.cwd() });
+    this.policyEngine = options.policyEngine || new WritePolicyEngine();
+    this.reviewExecutor =
+      options.reviewExecutor ||
+      new ReviewExecutor({ repoRoot: options.workspaceRoot || process.cwd() });
+    this.correctionEngine = options.correctionEngine || new AgentCorrectionEngine();
+    this.workspaceRoot = options.workspaceRoot || process.cwd();
+
+    // In-memory store for write requests and tokens
+    this.activeRequests = new Map();
+  }
+
+  _validateRequest(req) {
+    if (!req.workspaceId) throw new Error('Missing workspaceId');
+    if (!req.files || !Array.isArray(req.files) || req.files.length === 0)
+      throw new Error('Missing files array');
+
+    // Normalize and validate paths
+    for (const f of req.files) {
+      if (!['CREATE', 'MODIFY', 'DELETE'].includes(f.operation)) {
+        throw new Error(`Unknown operation: ${f.operation}`);
+      }
+      if (!f.path) throw new Error('File path missing');
+
+      const fullPath = path.resolve(this.workspaceRoot, f.path);
+      if (!fullPath.startsWith(this.workspaceRoot)) {
+        throw new Error(`Path outside workspace: ${f.path}`);
+      }
+      f.fullPath = fullPath;
+    }
+  }
+
+  _computeProposalHash(files) {
+    // Sort files by path for deterministic hash
+    const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+    const parts = sorted.map(f => `${f.path}:${f.operation}:${computeSha256(f.content || '')}`);
+    return computeSha256(parts.join('|'));
+  }
+
+  async requestWrite(req, options = {}) {
+    this._validateRequest(req);
+    const dryRun = options.dryRun || false;
+
+    const filePaths = req.files.map(f => f.path);
+    const lines = req.files.reduce(
+      (acc, f) => acc + (f.content ? f.content.split('\n').length : 0),
+      0,
+    );
+    const proposalHash = this._computeProposalHash(req.files);
+
+    // 1. Path Validation & Evidence Collection (via evaluateDecision)
+    // 2. Impact Classification & Reviewer Selection
+    const decision = evaluateDecision({
+      task: req.reason || 'Agent requested write',
+      files: filePaths,
+      lines,
+      repoRoot: this.workspaceRoot,
+    });
+
+    // 3. Write Policy Engine
+    const policyResult = this.policyEngine.evaluate(req, decision);
+
+    // 4. Execute Review if needed
+    let reviewResults = [];
+    let reviewRunId = null;
+    let verdict = null;
+
+    if (policyResult.action === 'REVIEW_REQUIRED' || policyResult.action === 'DENY') {
+      const reviewReq = {
+        decision,
+        code: req.files.map(f => `// ${f.path}\n${f.content || ''}`).join('\n\n'),
+        task: req.reason,
+      };
+
+      const res = await this.reviewExecutor.executeReview(reviewReq);
+      reviewResults = res.results;
+      reviewRunId = res.reviewRunId;
+
+      // 5. Deterministic Verdict
+      const aggregated = VerdictAggregator.aggregate({
+        results: reviewResults,
+        tier: decision.tier,
+        decision,
+        reviewRunId,
+      });
+      verdict = aggregated;
+    } else {
+      // Tier 0 ALLOW
+      verdict = {
+        verdict: 'APPROVED',
+        severity: 'INFO',
+        reason: 'Tier 0 Fast-Pass Policy ALLOW',
+      };
+    }
+
+    const isApproved = verdict.verdict === 'APPROVED' || verdict.verdict === 'WARNING';
+
+    let status = isApproved ? 'PENDING_COMMIT' : 'REJECTED';
+    let requiresHumanApproval = policyResult.requiresHumanApproval;
+
+    if (status === 'REJECTED') {
+      requiresHumanApproval = false; // Cannot approve a rejected AI review
+    } else if (requiresHumanApproval) {
+      status = 'HUMAN_APPROVAL_REQUIRED';
+    }
+
+    let correction = null;
+    if (status === 'REJECTED') {
+      correction = this.correctionEngine.generateCorrection(req, verdict, policyResult);
+    }
+
+    const token = `tok_${crypto.randomBytes(8).toString('hex')}`;
+    const txId = `tx_${crypto.randomBytes(8).toString('hex')}`;
+
+    const state = {
+      token,
+      transactionId: txId,
+      request: req,
+      decision,
+      policyResult,
+      verdict,
+      proposalHash,
+      status,
+      correction,
+      requiresHumanApproval,
+      humanApproval: null,
+      provenance: {
+        requestHash: computeSha256(JSON.stringify(req)),
+        proposalHash,
+        decisionHash: computeSha256(JSON.stringify(decision)),
+        reviewRunId,
+      },
+      timestamp: Date.now(),
+    };
+
+    if (!dryRun) {
+      this.activeRequests.set(token, state);
+    }
+
+    if (dryRun) {
+      return {
+        requestId: req.requestId,
+        status: 'NOT EXECUTED - DRY RUN',
+        verdict: verdict.verdict,
+        policy: policyResult.action,
+        impact: decision.tier_name,
+        files: filePaths,
+        correction,
+      };
+    }
+
+    // If APPROVED and no human approval needed, we can auto-commit if the API flow expects it,
+    // but the prompt implies we might want to return the token for commit.
+    // Let's just return the state so caller can commit.
+    return {
+      requestId: req.requestId,
+      transactionId: txId,
+      token,
+      status,
+      verdict: verdict.verdict,
+      files: filePaths,
+      correction,
+      provenance: state.provenance,
+    };
+  }
+
+  previewWrite(token) {
+    const state = this.activeRequests.get(token);
+    if (!state) throw new Error('Invalid or expired token');
+
+    return {
+      files: state.request.files.map(f => ({ path: f.path, operation: f.operation })),
+      impactTier: state.decision.tier_name,
+      policyDecision: state.policyResult.action,
+      approvalRequirements: state.requiresHumanApproval ? 'HUMAN_APPROVAL_REQUIRED' : 'NONE',
+      verdict: state.verdict.verdict,
+      findings: state.verdict.findings || [],
+    };
+  }
+
+  approveWrite(token, approverId, signature) {
+    const state = this.activeRequests.get(token);
+    if (!state) throw new Error('Invalid or expired token');
+
+    if (state.status !== 'HUMAN_APPROVAL_REQUIRED') {
+      throw new Error('Approval not required or already approved/rejected');
+    }
+
+    state.humanApproval = {
+      approverId,
+      signature,
+      timestamp: Date.now(),
+    };
+
+    state.status = 'PENDING_COMMIT';
+    return { status: state.status };
+  }
+
+  async commitWrite(token) {
+    const state = this.activeRequests.get(token);
+    if (!state) throw new Error('Invalid or expired token');
+
+    if (state.status === 'REJECTED') {
+      throw new Error('Cannot commit a REJECTED write');
+    }
+    if (state.status === 'HUMAN_APPROVAL_REQUIRED') {
+      throw new Error('Cannot commit: HUMAN_APPROVAL_REQUIRED');
+    }
+
+    // TOCTOU Protection
+    // 1. Verify hash binds
+    const currentProposalHash = this._computeProposalHash(state.request.files);
+    if (currentProposalHash !== state.proposalHash) {
+      state.status = 'STALE_REVIEW';
+      throw new Error('STALE_REVIEW: The requested files or content have changed since review.');
+    }
+
+    // 2. Lock and Validate File existence & Original hashes if any
+    try {
+      this.txManager.begin();
+
+      // Prepare
+      for (const f of state.request.files) {
+        if (f.operation === 'CREATE') {
+          if (fs.existsSync(f.fullPath)) {
+            throw new Error(`CONFLICT: File already exists: ${f.path}`);
+          }
+          this.txManager.prepareWrite(f.path, f.content);
+        } else if (f.operation === 'MODIFY') {
+          if (!fs.existsSync(f.fullPath)) {
+            throw new Error(`CONFLICT: File does not exist: ${f.path}`);
+          }
+          if (f.expectedHash) {
+            const actual = computeSha256(fs.readFileSync(f.fullPath, 'utf8'));
+            if (actual !== f.expectedHash) {
+              throw new Error(`CONFLICT: Hash mismatch for ${f.path}`);
+            }
+          }
+          this.txManager.prepareWrite(f.path, f.content);
+        } else if (f.operation === 'DELETE') {
+          if (!fs.existsSync(f.fullPath)) {
+            throw new Error(`CONFLICT: File does not exist: ${f.path}`);
+          }
+          this.txManager.prepareDelete(f.path);
+        }
+      }
+
+      // Validate & Commit
+      const txId = this.txManager.activeTxId;
+      this.txManager.validate();
+      this.txManager.commit();
+
+      state.status = 'COMMITTED';
+      this.activeRequests.delete(token); // cleanup
+
+      return {
+        requestId: state.request.requestId,
+        transactionId: txId,
+        status: 'COMMITTED',
+        verdict: state.verdict.verdict,
+        files: state.request.files.map(f => f.path),
+        provenance: state.provenance,
+      };
+    } catch (err) {
+      if (this.txManager.state !== 'IDLE' && this.txManager.state !== 'ROLLED_BACK') {
+        this.txManager.rollback();
+      }
+      state.status = 'ERROR';
+      throw err;
+    }
+  }
+}
+
+module.exports = {
+  ControlledWriteService,
+  computeSha256,
+};

package/src/execution/correction_run_engine.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const crypto = require('crypto');
+const { AgentCorrectionEngine } = require('./agent_correction_engine');
+const { ControlledWriteService } = require('./controlled_write_service');
+const { FindingDiffEngine } = require('./finding_diff_engine');
+const { CorrectionVerifier } = require('./correction_verifier');
+const { ResolutionPolicy } = require('./resolution_policy');
+const { ResolutionCertificate } = require('./resolution_certificate');
+
+function computeFingerprint(obj) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(obj || {}))
+    .digest('hex');
+}
+
+/**
+ * Phase 5B: Correction Run Engine
+ * Orchestrates the closed-loop verification and adaptive governance pipeline.
+ */
+class CorrectionRunEngine {
+  constructor(options = {}) {
+    this.controlledWriteService = options.controlledWriteService || new ControlledWriteService();
+    this.correctionEngine = options.correctionEngine || new AgentCorrectionEngine();
+    this.findingDiffEngine = options.findingDiffEngine || new FindingDiffEngine();
+    this.correctionVerifier = options.correctionVerifier || new CorrectionVerifier();
+
+    // Limits
+    this.maxIterations = options.maxIterations || 3;
+    this.activeRuns = new Map();
+  }
+
+  createRun(finding, initialRequest, originalVerdict) {
+    const runId = `CR-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    const runState = {
+      runId,
+      finding,
+      initialRequest,
+      originalVerdict,
+      state: 'INITIALIZED',
+      iteration: 0,
+      history: [],
+      // Loop control fingerprints
+      fingerprints: {
+        proposals: new Set(),
+      },
+      budget: {
+        maxIterations: this.maxIterations,
+      },
+    };
+    this.activeRuns.set(runId, runState);
+    return runId;
+  }
+
+  _transition(runState, nextState) {
+    const validTransitions = {
+      INITIALIZED: ['ANALYZING', 'ABORTED'],
+      ANALYZING: ['PLAN_READY', 'ESCALATED', 'ABORTED'],
+      PLAN_READY: ['GOVERNANCE_PENDING', 'ESCALATED', 'ABORTED'],
+      GOVERNANCE_PENDING: ['CORRECTION_APPLIED', 'ESCALATED', 'ABORTED'],
+      CORRECTION_APPLIED: ['VERIFYING', 'ABORTED'],
+      VERIFYING: ['RE_REVIEWING', 'ESCALATED', 'ABORTED'],
+      RE_REVIEWING: ['COMPARING', 'ABORTED'],
+      COMPARING: ['RESOLVED', 'PARTIALLY_RESOLVED', 'UNRESOLVED', 'ANALYZING', 'ESCALATED'],
+      RESOLVED: [],
+      PARTIALLY_RESOLVED: ['ANALYZING', 'ESCALATED'],
+      UNRESOLVED: ['ANALYZING', 'ESCALATED'],
+      ESCALATED: [],
+      ABORTED: [],
+    };
+
+    if (!validTransitions[runState.state].includes(nextState)) {
+      throw new Error(`Invalid state transition: ${runState.state} -> ${nextState}`);
+    }
+    runState.state = nextState;
+  }
+
+  /**
+   * Plans the correction for a specific finding. (Phase 5C & 5E)
+   */
+  async planCorrection(runId, proposalContext) {
+    const runState = this.activeRuns.get(runId);
+    if (!runState) throw new Error('Invalid runId');
+
+    this._transition(runState, 'ANALYZING');
+
+    if (runState.iteration >= runState.budget.maxIterations) {
+      runState.escalationReason = 'Correction budget exhausted.';
+      this._transition(runState, 'ESCALATED');
+      return { status: runState.state, reason: runState.escalationReason };
+    }
+
+    runState.iteration++;
+
+    // Call the AgentCorrectionEngine to build the enhanced plan
+    const plan = this.correctionEngine.generateEnhancedPlan(runState.finding, proposalContext);
+
+    const proposalFingerprint = computeFingerprint(plan);
+    if (runState.fingerprints.proposals.has(proposalFingerprint)) {
+      runState.escalationReason = 'LOOP_DETECTED: Identical correction proposal generated.';
+      this._transition(runState, 'ESCALATED');
+      return { status: runState.state, reason: runState.escalationReason };
+    }
+    runState.fingerprints.proposals.add(proposalFingerprint);
+
+    runState.currentPlan = plan;
+    this._transition(runState, 'PLAN_READY');
+    return { status: runState.state, plan };
+  }
+
+  /**
+   * Submits a planned correction via the ControlledWriteService (Phase 5B, 5T).
+   */
+  async executeCorrection(runId, proposedFiles) {
+    const runState = this.activeRuns.get(runId);
+    if (!runState) throw new Error('Invalid runId');
+    if (runState.state !== 'PLAN_READY')
+      throw new Error(`Cannot execute in state: ${runState.state}`);
+
+    this._transition(runState, 'GOVERNANCE_PENDING');
+
+    // Hash binding for STALE_CORRECTION check (Phase 5P, 5Q)
+    runState.proposalHash = computeFingerprint(proposedFiles);
+
+    const writeReq = {
+      workspaceId: runState.initialRequest.workspaceId || 'ws_1',
+      requestId: `REQ-${runId}-ITER-${runState.iteration}`,
+      files: proposedFiles,
+      reason: `Correction run ${runId} - ${runState.currentPlan.objective}`,
+    };
+
+    const writeResponse = await this.controlledWriteService.requestWrite(writeReq);
+
+    if (writeResponse.status === 'REJECTED') {
+      runState.escalationReason = 'Correction write request was REJECTED by governance.';
+      this._transition(runState, 'ESCALATED');
+      return {
+        status: runState.state,
+        reason: runState.escalationReason,
+        feedback: writeResponse.correction,
+      };
+    }
+
+    // Automatically commit if approved for the correction loop
+    if (writeResponse.status === 'PENDING_COMMIT') {
+      await this.controlledWriteService.commitWrite(writeResponse.token);
+      this._transition(runState, 'CORRECTION_APPLIED');
+      runState.transactionId = writeResponse.transactionId;
+      runState.reviewRunId = writeResponse.provenance?.reviewRunId;
+      return { status: runState.state, transactionId: writeResponse.transactionId };
+    }
+
+    runState.escalationReason = `Unexpected write status: ${writeResponse.status}`;
+    this._transition(runState, 'ESCALATED');
+    return { status: runState.state, reason: runState.escalationReason };
+  }
+
+  /**
+   * Verifies the correction (Phase 5F, 5G, 5I) and checks for regressions (Phase 5M).
+   */
+  async verifyCorrection(runId, newVerdictFindings = []) {
+    const runState = this.activeRuns.get(runId);
+    if (!runState) throw new Error('Invalid runId');
+    if (runState.state !== 'CORRECTION_APPLIED')
+      throw new Error(`Cannot verify in state: ${runState.state}`);
+
+    this._transition(runState, 'VERIFYING');
+
+    // 1. Run Verification Plan and targeted reviews (Phase 6F, 6G)
+    // Now returns an EvidenceAggregator instance
+    const aggregator = await this.correctionVerifier.verify(runState.finding, runState.currentPlan);
+
+    this._transition(runState, 'RE_REVIEWING');
+
+    this._transition(runState, 'COMPARING');
+
+    const diff = this.findingDiffEngine.compare([runState.finding], newVerdictFindings);
+    runState.diff = diff;
+
+    // Add regression evidence
+    if (diff.regressed.length > 0 || diff.new.some(f => f.severity === 'CRITICAL')) {
+      aggregator.addEvidence({
+        type: 'REGRESSION',
+        source: 'FindingDiffEngine',
+        status: 'FAILED',
+        details: { regressed: diff.regressed, newCritical: diff.new },
+      });
+    } else {
+      aggregator.addEvidence({
+        type: 'REGRESSION',
+        source: 'FindingDiffEngine',
+        status: 'PASSED',
+        details: { resolved: diff.resolved },
+      });
+    }
+
+    // 2. Evaluate Resolution Policy (Phase 6K, 6L)
+    const policyResult = ResolutionPolicy.evaluate(runState.finding.category, aggregator);
+
+    if (policyResult.status === 'RESOLVED') {
+      this._transition(runState, 'RESOLVED');
+    } else if (policyResult.status === 'UNRESOLVED' || policyResult.status === 'ESCALATED') {
+      runState.escalationReason = policyResult.reason;
+      this._transition(runState, 'ESCALATED');
+    }
+
+    // 3. Generate Resolution Certificate (Phase 6N, 6O)
+    const certificate = ResolutionCertificate.generate({
+      runId,
+      findingFingerprint: runState.finding.id,
+      originalRepositoryFingerprint: 'mock-repo-hash',
+      correctedRepositoryFingerprint: 'mock-repo-hash',
+      proposalHash: runState.proposalHash,
+      reviewHash: runState.reviewRunId || 'no-review-hash',
+      transactionHash: runState.transactionId || 'no-tx-hash',
+      aggregator,
+      diff,
+      finalVerdict: runState.state,
+    });
+
+    runState.certificate = certificate;
+
+    return {
+      status: runState.state,
+      diff,
+      evidence: aggregator.getAllEvidence(),
+      certificate,
+      reason: runState.escalationReason,
+    };
+  }
+}
+
+module.exports = { CorrectionRunEngine, computeFingerprint };

package/src/execution/correction_verifier.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { ValidationRunner } = require('./validation_runner');
+const { EvidenceAggregator } = require('./evidence_aggregator');
+
+/**
+ * Phase 6F, 6G, 6H: Correction Verifier
+ * Now acts as the Validation Selector and Executor.
+ */
+class CorrectionVerifier {
+  constructor(options = {}) {
+    this.workspace = options.workspace || process.cwd();
+    this.validationRunner =
+      options.validationRunner || new ValidationRunner({ workspaceRoot: this.workspace });
+    // In a real flow, this would connect to the ReviewExecutor singleton
+    this.reviewExecutor = options.reviewExecutor;
+  }
+
+  _buildValidationPlan(finding) {
+    const checks = [];
+    if (finding.category === 'Security' || finding.severity === 'CRITICAL') {
+      checks.push({ type: 'STATIC', targetId: 'lint' });
+      checks.push({ type: 'REPRODUCTION', targetId: 'unit_tests' }); // Mock logic
+    } else if (finding.category === 'Performance') {
+      checks.push({ type: 'EXECUTION', targetId: 'unit_tests' });
+    } else {
+      checks.push({ type: 'EXECUTION', targetId: 'unit_tests' });
+    }
+    return checks;
+  }
+
+  async verify(finding, plan) {
+    const checks = this._buildValidationPlan(finding);
+    const aggregator = new EvidenceAggregator();
+
+    // 1. Run deterministic checks (Phase 6F, 6H)
+    for (const check of checks) {
+      if (check.type === 'EXECUTION' || check.type === 'STATIC' || check.type === 'REPRODUCTION') {
+        const result = await this.validationRunner.run(check.targetId);
+
+        let evidenceStatus = 'FAILED';
+        if (result.status === 'PASSED') {
+          evidenceStatus = check.type === 'REPRODUCTION' ? 'NOT_REPRODUCED' : 'PASSED';
+        }
+
+        aggregator.addEvidence({
+          type: check.type,
+          source: check.targetId,
+          status: evidenceStatus,
+          details: result,
+          repositoryFingerprint: result.repositoryFingerprint,
+          findingFingerprint: finding.id || 'unknown',
+        });
+      }
+    }
+
+    // 2. Real Targeted Re-Review (Phase 6G)
+    if (this.reviewExecutor) {
+      const reviewResult = await this.reviewExecutor.executeTargetedReview(
+        finding,
+        plan.affectedFiles,
+      );
+      aggregator.addEvidence({
+        type: 'REVIEW',
+        source: 'ReviewExecutor',
+        status: reviewResult.status === 'APPROVED' ? 'PASSED' : 'REJECTED',
+        details: reviewResult,
+        findingFingerprint: finding.id || 'unknown',
+      });
+    } else {
+      // Mock for testing if unprovided
+      aggregator.addEvidence({
+        type: 'REVIEW',
+        source: 'MockReviewer',
+        status: 'PASSED',
+        details: {},
+        findingFingerprint: finding.id || 'unknown',
+      });
+    }
+
+    return aggregator;
+  }
+}
+
+module.exports = { CorrectionVerifier };

package/src/execution/evidence_aggregator.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Phase 6I, 6J: Evidence Aggregator
+ * Collects evidence from multiple sources and ensures independence.
+ */
+class EvidenceAggregator {
+  constructor() {
+    this.evidence = new Map();
+  }
+
+  addEvidence(evidenceItem) {
+    if (!evidenceItem.type || !evidenceItem.source || !evidenceItem.status) {
+      throw new Error('Invalid evidence schema');
+    }
+
+    const evidenceId = evidenceItem.evidenceId || crypto.randomUUID();
+
+    // Grouping to ensure independence (e.g. don't count two test runners as two separate signals if they are wrappers)
+    const independenceKey = `${evidenceItem.type}:${evidenceItem.source}`;
+
+    this.evidence.set(independenceKey, {
+      ...evidenceItem,
+      evidenceId,
+      timestamp: new Date().toISOString(),
+    });
+
+    return evidenceId;
+  }
+
+  getEvidenceByType(type) {
+    return Array.from(this.evidence.values()).filter(e => e.type === type);
+  }
+
+  getAllEvidence() {
+    return Array.from(this.evidence.values());
+  }
+
+  hasPassingEvidence(type) {
+    const items = this.getEvidenceByType(type);
+    return items.some(e => e.status === 'PASSED' || e.status === 'VERIFIED');
+  }
+
+  hasFailingEvidence(type) {
+    const items = this.getEvidenceByType(type);
+    return items.some(
+      e => e.status === 'FAILED' || e.status === 'REJECTED' || e.status === 'CRASHED',
+    );
+  }
+}
+
+module.exports = { EvidenceAggregator };