@veraxhq/verax 0.2.1 → 0.3.0

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

@@ -0,0 +1,438 @@
+/**
+ * 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);
+  }
+}
+
+/**
+ * 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,92 @@
+/**
+ * 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 {
+    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;
+  }
+}
+

package/src/verax/core/determinism/run-fingerprint.js

@@ -0,0 +1,118 @@
+/**
+ * PHASE 25 — Run Fingerprint
+ * 
+ * Computes stable run fingerprint from deterministic inputs.
+ * Used to verify that repeated runs have identical inputs.
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { getVeraxVersion } from '../run-id.js';
+
+/**
+ * Compute run fingerprint from deterministic inputs
+ * 
+ * @param {Object} params - Run parameters
+ * @param {string} params.url - Target URL
+ * @param {string} params.projectDir - Project directory
+ * @param {string} params.manifestPath - Manifest path (optional)
+ * @param {Object} params.policyHash - Policy hash (optional)
+ * @param {string} params.fixtureId - Fixture ID (optional)
+ * @returns {string} Run fingerprint (hex hash)
+ */
+export function computeRunFingerprint(params) {
+  const {
+    url,
+    projectDir,
+    manifestPath = null,
+    policyHash = null,
+    fixtureId = null
+  } = params;
+  
+  // Compute source hash (hash of all source files)
+  const srcHash = computeSourceHash(projectDir);
+  
+  // Compute policy hash if not provided
+  const computedPolicyHash = policyHash || computePolicyHash(projectDir);
+  
+  // Get VERAX version
+  const veraxVersion = getVeraxVersion();
+  
+  // Build fingerprint input
+  const fingerprintInput = {
+    url: normalizeUrl(url),
+    srcHash,
+    policyHash: computedPolicyHash,
+    veraxVersion,
+    fixtureId: fixtureId || null
+  };
+  
+  // Generate stable hash
+  const configString = JSON.stringify(fingerprintInput, Object.keys(fingerprintInput).sort());
+  const hash = createHash('sha256').update(configString).digest('hex');
+  
+  return hash.substring(0, 32); // 32 chars for readability
+}
+
+/**
+ * Compute source hash (hash of all source files in project)
+ */
+function computeSourceHash(projectDir) {
+  try {
+    // For now, use a simple approach: hash package.json + src directory structure
+    // In production, this should hash all source files
+    const packagePath = resolve(projectDir, 'package.json');
+    if (existsSync(packagePath)) {
+      const pkgContent = readFileSync(packagePath, 'utf-8');
+      return createHash('sha256').update(pkgContent).digest('hex').substring(0, 16);
+    }
+    return 'no-source';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Compute policy hash (hash of guardrails/confidence policies)
+ */
+function computePolicyHash(projectDir) {
+  try {
+    // Hash default policies (in production, should hash all policy files)
+    const policyPaths = [
+      resolve(projectDir, '.verax', 'guardrails.policy.json'),
+      resolve(projectDir, '.verax', 'confidence.policy.json')
+    ];
+    
+    const hashes = [];
+    for (const path of policyPaths) {
+      if (existsSync(path)) {
+        const content = readFileSync(path, 'utf-8');
+        hashes.push(createHash('sha256').update(content).digest('hex').substring(0, 8));
+      }
+    }
+    
+    if (hashes.length > 0) {
+      return createHash('sha256').update(hashes.join('|')).digest('hex').substring(0, 16);
+    }
+    
+    return 'default-policy';
+  } catch {
+    return 'unknown-policy';
+  }
+}
+
+/**
+ * Normalize URL for fingerprint
+ */
+function normalizeUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  try {
+    const urlObj = new URL(url);
+    // Normalize: remove trailing slash, lowercase host
+    return `${urlObj.protocol}//${urlObj.host.toLowerCase()}${urlObj.pathname.replace(/\/$/, '') || '/'}`;
+  } catch {
+    return url;
+  }
+}
+