@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/determinism/finding-identity.js

@@ -0,0 +1,149 @@
+/**
+ * PHASE 18 — Stable Finding Identity
+ * 
+ * Computes stable identity keys for findings that are consistent across runs.
+ * Used for matching findings between runs for comparison.
+ */
+
+import { createHash } from 'crypto';
+
+/**
+ * PHASE 18: Compute stable finding identity
+ * 
+ * Uses type + promise signature + route/network target + interaction selector/context chain
+ * Includes evidence trigger source signature where available (AST snippet hash or location)
+ * Must NOT include runId/timestamps
+ * 
+ * @param {Object} finding - Finding object
+ * @returns {string} Stable identity key
+ */
+export function computeFindingIdentity(finding) {
+  const parts = [];
+  
+  // Part 1: Finding type
+  parts.push(`type:${finding.type || 'unknown'}`);
+  
+  // Part 2: Interaction signature
+  const interaction = finding.interaction || {};
+  if (interaction.type && interaction.selector) {
+    parts.push(`interaction:${interaction.type}:${normalizeSelector(interaction.selector)}`);
+  }
+  if (interaction.label) {
+    parts.push(`label:${interaction.label}`);
+  }
+  
+  // Part 3: Promise signature
+  const expectation = finding.expectation || {};
+  const promise = finding.promise || {};
+  
+  if (expectation.type) {
+    parts.push(`promiseType:${expectation.type}`);
+  }
+  if (expectation.targetPath) {
+    parts.push(`targetPath:${normalizePath(expectation.targetPath)}`);
+  }
+  if (expectation.urlPath) {
+    parts.push(`urlPath:${normalizePath(expectation.urlPath)}`);
+  }
+  if (promise.type) {
+    parts.push(`promise:${promise.type}`);
+  }
+  
+  // Part 4: Route/network target
+  if (finding.route) {
+    const route = finding.route;
+    if (route.path) {
+      parts.push(`route:${normalizePath(route.path)}`);
+    }
+    if (route.originalPattern) {
+      parts.push(`routePattern:${normalizePath(route.originalPattern)}`);
+    }
+  }
+  
+  if (finding.evidence?.networkRequest?.url) {
+    parts.push(`networkUrl:${normalizeUrl(finding.evidence.networkRequest.url)}`);
+  }
+  
+  // Part 5: Evidence trigger source signature
+  const source = finding.source || expectation.source || {};
+  if (source.file) {
+    parts.push(`sourceFile:${normalizePath(source.file)}`);
+  }
+  if (source.line) {
+    parts.push(`sourceLine:${source.line}`);
+  }
+  if (source.astSource) {
+    // Hash AST source for stability
+    const astHash = hashString(source.astSource);
+    parts.push(`astHash:${astHash}`);
+  }
+  
+  // Part 6: Evidence trigger from evidencePackage
+  if (finding.evidencePackage?.trigger?.astSource) {
+    const triggerHash = hashString(finding.evidencePackage.trigger.astSource);
+    parts.push(`triggerHash:${triggerHash}`);
+  }
+  if (finding.evidencePackage?.trigger?.source?.file) {
+    parts.push(`triggerFile:${normalizePath(finding.evidencePackage.trigger.source.file)}`);
+  }
+  if (finding.evidencePackage?.trigger?.source?.line) {
+    parts.push(`triggerLine:${finding.evidencePackage.trigger.source.line}`);
+  }
+  
+  // Part 7: Context chain (if available)
+  if (finding.contextChain && Array.isArray(finding.contextChain)) {
+    const contextSig = finding.contextChain.map(c => `${c.type}:${c.name || ''}`).join('>');
+    parts.push(`context:${contextSig}`);
+  }
+  
+  // Combine all parts into stable identity
+  const identity = parts.join('|');
+  
+  // Return hash for compactness and stability
+  return hashString(identity);
+}
+
+/**
+ * Normalize selector (remove volatile parts)
+ */
+function normalizeSelector(selector) {
+  if (!selector || typeof selector !== 'string') return '';
+  // Remove any dynamic IDs or classes that might change
+  return selector.replace(/\[data-[^\]]+\]/g, '').replace(/\.\w+-\d+/g, '');
+}
+
+/**
+ * Normalize path (remove absolute paths, normalize separators)
+ */
+function normalizePath(path) {
+  if (!path || typeof path !== 'string') return '';
+  // Normalize separators
+  let normalized = path.replace(/\\/g, '/');
+  // Remove absolute path prefixes (keep relative structure)
+  normalized = normalized.replace(/^[A-Z]:\/[^/]+/, '');
+  normalized = normalized.replace(/^\/[^/]+/, '');
+  return normalized;
+}
+
+/**
+ * Normalize URL (remove query params, hash, normalize domain)
+ */
+function normalizeUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  try {
+    const urlObj = new URL(url);
+    // Keep only pathname for comparison
+    return urlObj.pathname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Hash string for stable identity
+ */
+function hashString(str) {
+  // @ts-expect-error - digest returns string
+  return createHash('sha256').update(str).digest('hex').substring(0, 16);
+}
+

package/src/verax/core/determinism/normalize.js

@@ -0,0 +1,466 @@
+/**
+ * PHASE 18 — Determinism Normalization Layer
+ * 
+ * Normalizes artifacts for deterministic comparison by:
+ * - Stripping volatile fields (timestamps, runId, absolute paths, temp dirs)
+ * - Normalizing ordering (sort arrays by stable keys)
+ * - Normalizing evidence paths but preserving evidence presence/absence
+ * - Normalizing floating scores with fixed rounding
+ */
+
+/**
+ * PHASE 18: Normalize artifact for comparison
+ * 
+ * @param {string} artifactName - Name of artifact (findings, runStatus, etc.)
+ * @param {Object} json - Artifact JSON object
+ * @returns {Object} Normalized artifact
+ */
+export function normalizeArtifact(artifactName, json) {
+  if (!json || typeof json !== 'object') {
+    return json;
+  }
+  
+  // Deep clone to avoid mutating original
+  const normalized = JSON.parse(JSON.stringify(json));
+  
+  // Apply artifact-specific normalization
+  switch (artifactName) {
+    case 'findings':
+      return normalizeFindings(normalized);
+    case 'runStatus':
+      return normalizeRunStatus(normalized);
+    case 'summary':
+      return normalizeSummary(normalized);
+    case 'learn':
+      return normalizeLearn(normalized);
+    case 'evidenceIntent':
+      return normalizeEvidenceIntent(normalized);
+    case 'guardrailsReport':
+      return normalizeGuardrailsReport(normalized);
+    case 'confidenceReport':
+      return normalizeConfidenceReport(normalized);
+    case 'determinismContract':
+      return normalizeDeterminismContract(normalized);
+    case 'runMeta':
+      return normalizeRunMeta(normalized);
+    case 'observe':
+    case 'traces':
+      return normalizeTraces(normalized);
+    case 'performanceReport':
+      return normalizePerformanceReport(normalized);
+    case 'securityReport':
+      return normalizeSecurityReport(normalized);
+    case 'gaReport':
+      return normalizeGAReport(normalized);
+    case 'releaseReport':
+      return normalizeReleaseReport(normalized);
+    default:
+      return normalizeGeneric(normalized);
+  }
+}
+
+function normalizeDeterminismContract(artifact) {
+  return normalizeGeneric(artifact);
+}
+
+function normalizeRunMeta(artifact) {
+  return normalizeGeneric(artifact);
+}
+
+function normalizeTraces(artifact) {
+  return normalizeGeneric(artifact);
+}
+
+function normalizePerformanceReport(artifact) {
+  return normalizeGeneric(artifact);
+}
+
+function normalizeSecurityReport(artifact) {
+  return normalizeGeneric(artifact);
+}
+
+function normalizeGAReport(artifact) {
+  return normalizeGeneric(artifact);
+}
+
+function normalizeReleaseReport(artifact) {
+  return normalizeGeneric(artifact);
+}
+
+/**
+ * Normalize findings artifact
+ */
+function normalizeFindings(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove volatile top-level fields
+  delete normalized.detectedAt;
+  delete normalized.runId;
+  delete normalized.timestamp;
+  
+  // Normalize findings array
+  if (Array.isArray(normalized.findings)) {
+    normalized.findings = normalized.findings.map(f => normalizeFinding(f));
+    // Sort by stable identity (if we had it, but for now sort by type + interaction)
+    normalized.findings.sort((a, b) => {
+      const keyA = `${a.type || ''}|${a.interaction?.selector || ''}|${a.interaction?.type || ''}`;
+      const keyB = `${b.type || ''}|${b.interaction?.selector || ''}|${b.interaction?.type || ''}`;
+      return keyA.localeCompare(keyB);
+    });
+  }
+  
+  // Normalize enforcement metadata (keep structure, remove timestamps)
+  if (normalized.enforcement) {
+    const enforcement = { ...normalized.enforcement };
+    // Keep enforcement data but normalize any timestamps
+    normalized.enforcement = enforcement;
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize individual finding
+ */
+function normalizeFinding(finding) {
+  const normalized = { ...finding };
+  
+  // Remove volatile fields
+  delete normalized.id;
+  delete normalized.findingId;
+  delete normalized.timestamp;
+  delete normalized.detectedAt;
+  
+  // Normalize confidence (round to 3 decimals)
+  if (typeof normalized.confidence === 'number') {
+    normalized.confidence = Math.round(normalized.confidence * 1000) / 1000;
+  }
+  
+  // Normalize evidence paths (keep structure, normalize paths)
+  if (normalized.evidence) {
+    normalized.evidence = normalizeEvidence(normalized.evidence);
+  }
+  
+  // Normalize evidencePackage
+  if (normalized.evidencePackage) {
+    normalized.evidencePackage = normalizeEvidencePackage(normalized.evidencePackage);
+  }
+  
+  // Normalize guardrails (keep structure, normalize confidence deltas)
+  if (normalized.guardrails) {
+    const guardrails = { ...normalized.guardrails };
+    if (typeof guardrails.confidenceDelta === 'number') {
+      guardrails.confidenceDelta = Math.round(guardrails.confidenceDelta * 1000) / 1000;
+    }
+    normalized.guardrails = guardrails;
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize evidence
+ */
+function normalizeEvidence(evidence) {
+  const normalized = { ...evidence };
+  
+  // Normalize screenshot paths (keep presence, normalize path)
+  if (normalized.before) {
+    normalized.before = normalizePath(normalized.before);
+  }
+  if (normalized.after) {
+    normalized.after = normalizePath(normalized.after);
+  }
+  
+  // Normalize URLs (remove query params, hash)
+  if (normalized.beforeUrl) {
+    normalized.beforeUrl = normalizeUrl(normalized.beforeUrl);
+  }
+  if (normalized.afterUrl) {
+    normalized.afterUrl = normalizeUrl(normalized.afterUrl);
+  }
+  
+  // Normalize source paths
+  if (normalized.source && typeof normalized.source === 'string') {
+    normalized.source = normalizePath(normalized.source);
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize evidencePackage
+ */
+function normalizeEvidencePackage(evidencePackage) {
+  const normalized = { ...evidencePackage };
+  
+  // Normalize before/after paths
+  if (normalized.before) {
+    normalized.before = {
+      ...normalized.before,
+      screenshot: normalized.before.screenshot ? normalizePath(normalized.before.screenshot) : null,
+      url: normalized.before.url ? normalizeUrl(normalized.before.url) : null,
+    };
+  }
+  
+  if (normalized.after) {
+    normalized.after = {
+      ...normalized.after,
+      screenshot: normalized.after.screenshot ? normalizePath(normalized.after.screenshot) : null,
+      url: normalized.after.url ? normalizeUrl(normalized.after.url) : null,
+    };
+  }
+  
+  // Normalize trigger source paths
+  if (normalized.trigger?.source?.file) {
+    normalized.trigger.source.file = normalizePath(normalized.trigger.source.file);
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize runStatus artifact
+ */
+function normalizeRunStatus(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove volatile fields
+  delete normalized.startedAt;
+  delete normalized.completedAt;
+  delete normalized.timestamp;
+  delete normalized.runId;
+  
+  // Keep structure but remove timestamps from nested objects
+  if (normalized.verification) {
+    const verification = { ...normalized.verification };
+    delete verification.verifiedAt;
+    normalized.verification = verification;
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize summary artifact
+ */
+function normalizeSummary(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove volatile fields
+  delete normalized.timestamp;
+  delete normalized.runId;
+  
+  // Normalize metrics (round durations)
+  if (normalized.metrics) {
+    const metrics = { ...normalized.metrics };
+    for (const key in metrics) {
+      if (typeof metrics[key] === 'number' && key.includes('Ms')) {
+        metrics[key] = Math.round(metrics[key]);
+      }
+    }
+    normalized.metrics = metrics;
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize learn artifact
+ */
+function normalizeLearn(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove volatile fields
+  delete normalized.learnedAt;
+  delete normalized.timestamp;
+  delete normalized.runId;
+  
+  // Normalize routes array (sort by path)
+  if (Array.isArray(normalized.routes)) {
+    normalized.routes = [...normalized.routes].sort((a, b) => {
+      const pathA = a.path || '';
+      const pathB = b.path || '';
+      return pathA.localeCompare(pathB);
+    });
+  }
+  
+  // Normalize expectations array (sort by type + target)
+  if (Array.isArray(normalized.expectations)) {
+    normalized.expectations = [...normalized.expectations].sort((a, b) => {
+      const keyA = `${a.type || ''}|${a.targetPath || ''}`;
+      const keyB = `${b.type || ''}|${b.targetPath || ''}`;
+      return keyA.localeCompare(keyB);
+    });
+  }
+  
+  return normalized;
+}
+
+/**
+ * PHASE 22: Normalize evidence intent ledger
+ */
+function normalizeEvidenceIntent(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove volatile fields
+  delete normalized.generatedAt;
+  
+  // Normalize entries (already sorted by findingIdentity, but normalize timestamps)
+  if (Array.isArray(normalized.entries)) {
+    normalized.entries = normalized.entries.map(entry => {
+      const normalizedEntry = { ...entry };
+      delete normalizedEntry.timestamp;
+      
+      // Normalize capture outcomes (preserve pass/fail, normalize failure details)
+      if (normalizedEntry.captureOutcomes) {
+        const outcomes = {};
+        for (const [field, outcome] of Object.entries(normalizedEntry.captureOutcomes)) {
+          outcomes[field] = {
+            required: outcome.required,
+            captured: outcome.captured,
+            failure: outcome.failure ? {
+              stage: outcome.failure.stage,
+              reasonCode: outcome.failure.reasonCode,
+              reason: outcome.failure.reason
+              // Exclude stackSummary and timestamp from failure for determinism
+            } : null
+          };
+        }
+        normalizedEntry.captureOutcomes = outcomes;
+      }
+      
+      return normalizedEntry;
+    });
+  }
+  
+  return normalized;
+}
+
+/**
+ * PHASE 23: Normalize guardrails report
+ */
+function normalizeGuardrailsReport(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove volatile fields
+  delete normalized.generatedAt;
+  
+  // Normalize summary (preserve counts, normalize topRules ordering)
+  if (normalized.summary && normalized.summary.topRules) {
+    normalized.summary.topRules = normalized.summary.topRules.map(r => ({
+      code: r.code,
+      count: r.count
+    }));
+  }
+  
+  // Normalize perFinding (already sorted by findingIdentity, but normalize timestamps if any)
+  if (normalized.perFinding && typeof normalized.perFinding === 'object') {
+    const perFindingNormalized = {};
+    const sortedKeys = Object.keys(normalized.perFinding).sort();
+    for (const key of sortedKeys) {
+      const entry = normalized.perFinding[key];
+      perFindingNormalized[key] = {
+        ...entry,
+        // Remove any volatile fields from entry
+      };
+    }
+    normalized.perFinding = perFindingNormalized;
+  }
+  
+  return normalized;
+}
+
+/**
+ * PHASE 24: Normalize confidence report
+ */
+function normalizeConfidenceReport(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove volatile fields
+  delete normalized.generatedAt;
+  
+  // Normalize summary (preserve counts)
+  if (normalized.summary) {
+    // Summary counts are already deterministic, no normalization needed
+  }
+  
+  // Normalize perFinding (already sorted by findingIdentity, but normalize timestamps if any)
+  if (normalized.perFinding && typeof normalized.perFinding === 'object') {
+    const perFindingNormalized = {};
+    const sortedKeys = Object.keys(normalized.perFinding).sort();
+    for (const key of sortedKeys) {
+      const entry = normalized.perFinding[key];
+      perFindingNormalized[key] = {
+        ...entry,
+        // Remove any volatile fields from entry
+        // Round confidence values to 3 decimal places for determinism
+        confidenceBefore: Math.round(entry.confidenceBefore * 1000) / 1000,
+        confidenceAfter: Math.round(entry.confidenceAfter * 1000) / 1000
+      };
+    }
+    normalized.perFinding = perFindingNormalized;
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize generic artifact
+ */
+function normalizeGeneric(artifact) {
+  const normalized = { ...artifact };
+  
+  // Remove common volatile fields
+  delete normalized.timestamp;
+  delete normalized.runId;
+  delete normalized.detectedAt;
+  delete normalized.startedAt;
+  delete normalized.completedAt;
+  delete normalized.verifiedAt;
+  delete normalized.learnedAt;
+  
+  // Recursively normalize nested objects
+  for (const key in normalized) {
+    if (normalized[key] && typeof normalized[key] === 'object') {
+      if (Array.isArray(normalized[key])) {
+        // Sort arrays if they contain objects with stable keys
+        normalized[key] = [...normalized[key]];
+      } else {
+        normalized[key] = normalizeGeneric(normalized[key]);
+      }
+    }
+  }
+  
+  return normalized;
+}
+
+/**
+ * Normalize path (remove absolute paths, normalize separators)
+ */
+function normalizePath(path) {
+  if (!path || typeof path !== 'string') return path;
+  let normalized = path.replace(/\\/g, '/');
+  // Remove absolute path prefixes
+  normalized = normalized.replace(/^[A-Z]:\/[^/]+/, '');
+  normalized = normalized.replace(/^\/[^/]+/, '');
+  // Remove temp dirs
+  normalized = normalized.replace(/\/tmp\/[^/]+/g, '/tmp/...');
+  normalized = normalized.replace(/\/\.verax\/runs\/[^/]+/g, '/.verax/runs/...');
+  return normalized;
+}
+
+/**
+ * Normalize URL (remove query params, hash, normalize domain)
+ */
+function normalizeUrl(url) {
+  if (!url || typeof url !== 'string') return url;
+  try {
+    const urlObj = new URL(url);
+    // Keep only pathname for comparison
+    return urlObj.pathname;
+  } catch {
+    return url;
+  }
+}
+

package/src/verax/core/determinism/report-writer.js

@@ -0,0 +1,93 @@
+/**
+ * PHASE 21.2 — Determinism Report Writer
+ * 
+ * Writes determinism.report.json with HARD TRUTH about determinism.
+ * No marketing language. Only binary verdict: DETERMINISTIC or NON_DETERMINISTIC.
+ */
+
+import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { ARTIFACT_REGISTRY, getArtifactVersions } from '../artifacts/registry.js';
+import { computeDeterminismVerdict, DETERMINISM_VERDICT, DETERMINISM_REASON } from './contract.js';
+import { DecisionRecorder } from '../determinism-model.js';
+
+/**
+ * PHASE 21.2: Write determinism report from DecisionRecorder
+ * 
+ * @param {string} runDir - Run directory path
+ * @param {DecisionRecorder} decisionRecorder - Decision recorder instance
+ * @returns {string} Path to determinism report
+ */
+export function writeDeterminismReport(runDir, decisionRecorder) {
+  const reportPath = resolve(runDir, ARTIFACT_REGISTRY.determinismReport.filename);
+  
+  // PHASE 21.2: Compute HARD verdict from adaptive events
+  const verdict = computeDeterminismVerdict(decisionRecorder);
+  
+  const report = {
+    version: 1,
+    contractVersion: 1,
+    artifactVersions: getArtifactVersions(),
+    generatedAt: new Date().toISOString(),
+    // PHASE 21.2: HARD TRUTH - binary verdict only
+    verdict: verdict.verdict,
+    message: verdict.message,
+    reasons: verdict.reasons,
+    adaptiveEvents: verdict.adaptiveEvents,
+    // PHASE 21.2: Decision summary for transparency
+    decisionSummary: decisionRecorder ? decisionRecorder.getSummary() : null,
+    // PHASE 21.2: Contract definition
+    contract: {
+      deterministic: 'Same inputs + same environment + same config → identical normalized artifacts',
+      nonDeterministic: 'Any adaptive behavior (adaptive stabilization, retries, truncations) → NON_DETERMINISTIC',
+      tracking: 'Tracking adaptive decisions is NOT determinism. Only absence of adaptive events = DETERMINISTIC.'
+    }
+  };
+  
+  writeFileSync(reportPath, JSON.stringify(report, null, 2) + '\n');
+  
+  return reportPath;
+}
+
+/**
+ * PHASE 21.2: Write determinism report from decisions.json file
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {string|null} Path to determinism report, or null if decisions.json not found
+ */
+export function writeDeterminismReportFromFile(runDir) {
+  const decisionsPath = resolve(runDir, 'decisions.json');
+  
+  if (!existsSync(decisionsPath)) {
+    return null;
+  }
+  
+  try {
+  // @ts-expect-error - readFileSync with encoding returns string
+    const decisionsData = JSON.parse(readFileSync(decisionsPath, 'utf-8'));
+    const decisionRecorder = DecisionRecorder.fromExport(decisionsData);
+    return writeDeterminismReport(runDir, decisionRecorder);
+  } catch (error) {
+    // If we can't read decisions, we can't determine determinism
+    const reportPath = resolve(runDir, ARTIFACT_REGISTRY.determinismReport.filename);
+    const report = {
+      version: 1,
+      contractVersion: 1,
+      artifactVersions: getArtifactVersions(),
+      generatedAt: new Date().toISOString(),
+      verdict: DETERMINISM_VERDICT.NON_DETERMINISTIC,
+      message: `Cannot determine determinism: ${error.message}`,
+      reasons: [DETERMINISM_REASON.ENVIRONMENT_VARIANCE],
+      adaptiveEvents: [],
+      decisionSummary: null,
+      contract: {
+        deterministic: 'Same inputs + same environment + same config → identical normalized artifacts',
+        nonDeterministic: 'Any adaptive behavior (adaptive stabilization, retries, truncations) → NON_DETERMINISTIC',
+        tracking: 'Tracking adaptive decisions is NOT determinism. Only absence of adaptive events = DETERMINISTIC.'
+      }
+    };
+    writeFileSync(reportPath, JSON.stringify(report, null, 2) + '\n');
+    return reportPath;
+  }
+}
+